001/* 002 * file CqQueryFolderItem.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem 008 * 009 * (C) Copyright IBM Corporation 2006, 2012. All Rights Reserved. 010 * Note to U.S. Government Users Restricted Rights: Use, duplication or 011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 012 */ 013 014package com.ibm.rational.wvcm.stp.cq; 015 016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE; 017 018import java.util.List; 019 020import javax.wvcm.Feedback; 021import javax.wvcm.ResourceList; 022import javax.wvcm.WvcmException; 023import javax.wvcm.PropertyNameList.PropertyName; 024import javax.wvcm.PropertyRequestItem.PropertyRequest; 025 026import com.ibm.rational.wvcm.stp.StpLocation; 027import com.ibm.rational.wvcm.stp.StpResource; 028 029/** 030 * A specification for an item in a query folder, which may be a query, chart, 031 * report, report format, or a nested query folder. 032 * <p> 033 * The user-friendly specification for the location of a query folder item has 034 * the form 035 * 036 * <pre> 037 * <b>cq.query:</b><i><parent-folder-path></i>/<i><item-name></i>@<i><db-set></i>/<i><user-db></i> 038 * </pre> 039 * 040 */ 041public interface CqQueryFolderItem extends CqContextResource 042{ 043 /** The query folder that contains this folder */ 044 PropertyName<CqQueryFolder> QUERY_FOLDER = 045 new PropertyName<CqQueryFolder>(PROPERTY_NAMESPACE, "query-folder"); 046 047 /** 048 * Returns the value of the {@link #QUERY_FOLDER QUERY_FOLDER} property as 049 * defined by this proxy. 050 * 051 * @return A CqQueryFolder proxy for the query folder that contains this 052 * folder. Will be <b>null</b> if there is no containing query 053 * folder. 054 * 055 * @throws WvcmException if this proxy does not define a value for the 056 * {@link #QUERY_FOLDER QUERY_FOLDER} property. 057 */ 058 public CqQueryFolder getQueryFolder() throws WvcmException; 059 060 /** 061 * The site-extended name for this folder item. 062 */ 063 PropertyName<StpLocation> SITE_EXTENDED_NAME = 064 new PropertyName<StpLocation>(PROPERTY_NAMESPACE, "site-extended-name"); 065 066 /** 067 * Returns the value of the {@link #SITE_EXTENDED_NAME SITE_EXTENDED_NAME} 068 * property as defined by this proxy. 069 * 070 * @return An StpLocation containing the site-extended name for this 071 * resource. 072 * 073 * @throws WvcmException if this proxy does not define a value for the 074 * {@link #SITE_EXTENDED_NAME SITE_EXTENDED_NAME} property. 075 */ 076 public StpLocation getSiteExtendedName() throws WvcmException; 077 078 /** 079 * An indication whether or not a site extended name is required to access 080 * this resource unambiguously. 081 */ 082 PropertyName<Boolean> IS_SITE_EXTENDED_NAME_REQUIRED = 083 new PropertyName<Boolean>(PROPERTY_NAMESPACE, 084 "is-site-extended-name-required"); 085 086 /** 087 * Returns the value of the 088 * {@link #IS_SITE_EXTENDED_NAME_REQUIRED IS_SITE_EXTENDED_NAME_REQUIRED} 089 * property as defined by this proxy. 090 * 091 * @return <b>true</b> if the name of this resource requires a site 092 * extension field to be unambiguous; <b>false</b> if no site 093 * extension field is needed 094 * 095 * @throws WvcmException if this proxy does not define a value for the 096 * {@link #IS_SITE_EXTENDED_NAME_REQUIRED IS_SITE_EXTENDED_NAME_REQUIRED} 097 * property. 098 */ 099 public boolean getIsSiteExtendedNameRequired() throws WvcmException; 100 101 /** 102 * A list of all the items in the query folder hierarchy whose name differs 103 * from the name of this resource only in its site extensions. 104 */ 105 PropertyName<ResourceList<CqQueryFolderItem>> SITE_EXTENDED_NAMES = 106 new PropertyName<ResourceList<CqQueryFolderItem>>(PROPERTY_NAMESPACE, 107 "site-extended-names"); 108 109 /** 110 * Returns the value of the {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} 111 * property as defined by this proxy. 112 * 113 * @return A ResourceList containing a proxy for each CqQueryFolderItem 114 * resource whose name differs from the name of this resource only in the 115 * site extensions used. 116 * 117 * @throws WvcmException if this proxy does not define a value for the 118 * {@link #SITE_EXTENDED_NAMES SITE_EXTENDED_NAMES} property. 119 */ 120 public ResourceList<CqQueryFolderItem> getSiteExtendedNames() 121 throws WvcmException; 122 123 /** 124 * The replica that masters this resource. A resource can be modified only 125 * in the replica that masters (has mastership of) it. 126 */ 127 PropertyName<CqReplica> CQ_MASTER_REPLICA = 128 new PropertyName<CqReplica>(PROPERTY_NAMESPACE, "cq-master-replica"); 129 130 /** 131 * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 132 * property as defined by this proxy. 133 * 134 * @return A CqReplica proxy for the replica that has mastership of this 135 * resource. 136 * 137 * @throws WvcmException if this proxy does not define a value for the 138 * {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property. 139 */ 140 CqReplica getCqMasterReplica() throws WvcmException; 141 142 /** 143 * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} 144 * property of this proxy. 145 * 146 * @param newMasterReplica A CqReplica proxy identifying the replica that 147 * should assume mastership of this resource. 148 */ 149 void setCqMasterReplica(CqReplica newMasterReplica); 150 151 /** 152 * Indicates whether or not this query folder item can be updated and/or 153 * deleted by the user. 154 */ 155 PropertyName<Boolean> CAN_UPDATE_OR_DELETE = 156 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "can-update-or-delete"); 157 158 /** 159 * Returns the value of the 160 * {@link #CAN_UPDATE_OR_DELETE CAN_UPDATE_OR_DELETE} property as defined by 161 * this proxy. 162 * 163 * @return <b>true</b> if this query folder item can be updated or deleted 164 * by the current user. 165 * 166 * @throws WvcmException if this proxy does not define a value for the 167 * {@link #CAN_UPDATE_OR_DELETE CAN_UPDATE_OF_DELETE} property. 168 */ 169 boolean getCanUpdateOrDelete() throws WvcmException; 170 171 /** 172 * Makes an editable copy of the query folder item named by this proxy at 173 * the location specified in the argument list. Any dirty properties in this 174 * proxy are written to the new copy after it is created, <i>not</i> to the 175 * resource referenced by this proxy. This item is not modified by this 176 * operation. 177 * 178 * @param destination The location where a new copy of this query folder 179 * item is to be created. The parent folder of this location must 180 * already exist in the query folder hierarchy of the database. 181 * @param overwrite Specifies how a query folder item already at the target 182 * location is to be handled. 183 * @param feedback A request for the properties to be defined by the proxy 184 * that is returned by this method. 185 * @param deliveryOrder If {@link CqProvider#HOLD}, the copied resource is 186 * left in a writable state in the change context--the copied 187 * resource in the change context must be delivered before it 188 * becomes visible to other providers. If not 189 * {@link CqProvider#HOLD}, the modified and moribund resources 190 * specified by this parameter will be delivered to or deleted 191 * from the database in the order indicated. To deliver all 192 * modified and moribund resources in an arbitrary order, use 193 * {@link CqProvider#DELIVER_ALL}. To deliver just this copied 194 * resource, use {@link CqProvider#DELIVER}. Must not be <b>null</b>. 195 * 196 * @return A CqQueryFolderItem proxy for the new copy of this item. Unless 197 * the deliver option was specified, the copied query item will be 198 * editable. 199 * 200 * @throws WvcmException if the server is unable to create the copy at the 201 * specified location. 202 */ 203 CqQueryFolderItem doCopy(StpLocation destination, 204 OverwriteMode overwrite, 205 Feedback feedback, 206 List<CqContextResource> deliveryOrder) 207 throws WvcmException; 208 209 /** 210 * Makes an editable copy of the query folder item named by this proxy at 211 * the location specified in the argument list. Any dirty properties are 212 * written to the new copy after it is created, <i>not</i> to the resource 213 * addressed by this proxy. 214 * <p> 215 * This variant of doCopy is provided because in the presence of stable or 216 * fast location formats the client cannot always guarantee that 217 * <code>parentFolder.child(childName)</code> will be a valid location 218 * specification. 219 * 220 * @param parentFolder The folder to which this query folder item is to be 221 * copied. The proxy must name an existing query folder of this 222 * user database. 223 * @param childName The name the copy of this resource is to have in the 224 * destination folder. 225 * @param overwrite Specifies how a query folder item already at the target 226 * location is to be handled. 227 * @param feedback The query properties to be defined by the proxy that is 228 * returned by this method. 229 * @param deliveryOrder Same as the version of 230 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy taking an StpLocation}. 231 * 232 * @return A CqQueryFolderItem proxy for the new copy of this query folder 233 * item. Unless the deliver option was specified, this query 234 * definition will be editable. 235 * 236 * @throws WvcmException if the server is unable to create the copy at the 237 * specified location. 238 */ 239 CqQueryFolderItem doCopy(CqQueryFolder parentFolder, 240 String childName, 241 OverwriteMode overwrite, 242 Feedback feedback, 243 List<CqContextResource> deliveryOrder) 244 throws WvcmException; 245 246 /** 247 * An enumeration of the values for specifying what doCopy and/or doMove 248 * should do when a resource already exists at the targeted destination. 249 */ 250 public enum OverwriteMode 251 { 252 /** 253 * If a resource exists at the target location, the operation will 254 * fail; the resource at the target location will not be overwritten. 255 */ 256 FORBID, 257 258 /** 259 * If a resource exists at the target location, that resource is to be 260 * deleted and replaced by the source resource. Specifically, if the 261 * target is a folder, that folder and all of its members are deleted 262 * and replaced by the source. 263 */ 264 REPLACE, 265 266 /** 267 * If the source resource is a folder and a folder exists at the target 268 * location, that folder is not deleted, but the contents of the source 269 * folder are merged with the contents of the target folder and this 270 * rule is applied recursively for each member of the source folder. If 271 * either the source resource or the target resource is not a folder, 272 * the target resource is deleted and replaced by the source--i.e., in 273 * this case, the operation behaves the same as in the REPLACE 274 * OverwriteMode. 275 */ 276 MERGE 277 } 278 279 /** 280 * Makes an editable copy of the query folder item named by this proxy at 281 * the location specified in the argument list and deletes the query folder 282 * item at the current proxy location. Any dirty properties are written to 283 * the new copy after it is created. 284 * 285 * @param destination The location to which this query folder item is to be 286 * moved. The location must be in the QUERY namespace of this 287 * user database. 288 * @param overwrite Specifies how a query folder item already at the target 289 * location is to be handled. 290 * @param feedback The properties to be defined by the proxy that is 291 * returned by this method. 292 * @param deliveryOrder Same as the deliveryOrder parameter of 293 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}. 294 * But note that use of {@link CqProvider#DELIVER} both delivers 295 * the copy and deletes the original query folder item. 296 * 297 * @return A proxy for the new copy of this resource. Unless the deliver 298 * option was specified, the resource at the proxy location will be 299 * editable. 300 * 301 * @throws WvcmException if the server is unable to create the copy at the 302 * specified location. 303 */ 304 CqQueryFolderItem doMove(StpLocation destination, 305 OverwriteMode overwrite, 306 Feedback feedback, 307 List<CqContextResource> deliveryOrder) 308 throws WvcmException; 309 310 /** 311 * Directly rename the query item without change any other property of it. 312 * <p> 313 * 314 * @param parentFolder The folder to which this query folder item is belonged 315 * 316 * @param newName The name this resource will be renamed to 317 * 318 * @param feedback The properties to be defined by the proxy that is 319 * returned by this method. 320 * @param deliveryOrder Same as the deliveryOrder parameter of 321 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}. 322 * 323 * @return A proxy for the newly renamed resource. Unless the deliver 324 * option was specified, this resource will be editable. 325 * 326 * @throws WvcmException if the server is unable to rename the resource with the 327 * new name. 328 */ 329 CqQueryFolderItem doRename(CqQueryFolder parentFolder, 330 String newName, 331 Feedback feedback, 332 List<CqContextResource> deliveryOrder) 333 throws WvcmException; 334 335 336 /** 337 * Makes an editable copy of the query folder item named by this proxy in 338 * the query folder specified in the argument list and deletes the query 339 * folder item at the current proxy location. Any dirty properties are 340 * written to the new copy after it is created. 341 * <p> 342 * This variant of doMove is provided because in the presence of stable or 343 * fast location formats the client cannot always guarantee that 344 * <code>parentFolder.child(childName)</code> is a valid location 345 * specification. 346 * 347 * @param parentFolder The folder to which this query folder item is to be 348 * moved. The location must name an existing query folder of this 349 * user database. 350 * @param childName The name this resource is to have in the destination 351 * folder. 352 * @param overwrite Specifies how a query folder item already at the target 353 * location is to be handled. 354 * @param feedback The properties to be defined by the proxy that is 355 * returned by this method. 356 * @param deliveryOrder Same as the deliveryOrder parameter of 357 * {@link #doCopy(StpLocation, com.ibm.rational.wvcm.stp.cq.CqQueryFolderItem.OverwriteMode, Feedback, List) doCopy}. 358 * But note that use of {@link CqProvider#DELIVER} both 359 * delivers the copy and deletes the original query folder item. 360 * 361 * @return A proxy for the new copy of this resource. Unless the deliver 362 * option was specified, this resource will be editable. 363 * 364 * @throws WvcmException if the server is unable to create the copy at the 365 * specified location. 366 */ 367 CqQueryFolderItem doMove(CqQueryFolder parentFolder, 368 String childName, 369 OverwriteMode overwrite, 370 Feedback feedback, 371 List<CqContextResource> deliveryOrder) 372 throws WvcmException; 373}