001 /* 002 * file CqContextResource.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cq.CqContextResource 008 * 009 * (C) Copyright IBM Corporation 2004, 2008. 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 package com.ibm.rational.wvcm.stp.cq; 014 015 import java.util.List; 016 017 import javax.wvcm.Feedback; 018 import javax.wvcm.Resource; 019 import javax.wvcm.WvcmException; 020 import javax.wvcm.PropertyNameList.PropertyName; 021 022 import com.ibm.rational.wvcm.stp.cq.CqProvider; 023 import com.ibm.rational.wvcm.stpex.StpExBase; 024 import com.ibm.rational.wvcm.stp.StpException; 025 import com.ibm.rational.wvcm.stp.StpResource; 026 027 028 /** 029 * A CqContextResource is a ClearQuest user database resource that may be 030 * temporarily held in a change context while it is being modified and before 031 * those modifications are committed to the database. The server maintains a 032 * separate and private change context for each database a client is logged 033 * into. The new and modified resources in the change context are visible only 034 * to the client and to the hooks the client fires and will not be visible to 035 * other clients of the database until the resources in the change context are 036 * delivered to the database. 037 * 038 * <p> 039 * The process of modifying context resources involves three steps: 040 * </p> 041 * 042 * <ul> 043 * <li><b>Initiate:</b> A new context resource is created, one or more 044 * properties of an existing context resource are updated, or an existing 045 * context resource is deleted. For records and attachments, this initial step 046 * requires the specification of an action to be used, thus declaring the 047 * business rules to be followed in making the modifications.</li> 048 * <li><b>Modify:</b> Modifications are made to the copy of the resource in 049 * the change context. As changes are written to the server they are verified on 050 * the server according to the business rules of the schema. Note that moribund 051 * resources (resources in the change context that have been deleted) cannot be 052 * modified.</li> 053 * <li><b>Deliver:</b> When all resource modifications have been completed, 054 * the modified resources are delivered to the user database to make changes 055 * permanent.</li> 056 * </ul> 057 * 058 * <p> 059 * This modification process allows the client to work with its user to make 060 * coordinated changes to multiple resources, with the option of altering or 061 * abandoning at any time changes to any of the resources involved. In its full 062 * generality, this modification process could involve three or more 063 * interactions with the server, but for simple cases, the API allows the steps 064 * to be combined such that most modifications can be completed in only one 065 * interaction with the server. 066 * </p> 067 * 068 * <p> 069 * Once a modification has been initiated by a client for a user, changes made 070 * to the resources involved are not visible to other users or clients until the 071 * modifications are delivered to the user database. The changes (including 072 * creation and deletion) are confined to the change context used and visible 073 * only through proxies obtained from the provider that made the changes. 074 * </p> 075 * 076 * <p> 077 * The precise locking semantics of this modification process depend on the type 078 * of resource being modified. The only guarantee is that if an 079 * initiate-modify-deliver sequence is successfully completed by a client, the 080 * resources modified did not change in the database while they were being 081 * modified by that client. 082 * </p> 083 * 084 * <p> 085 * When the modification of a resource is initiated, a writable version of the 086 * resource is created in the change context associated with the proxy used. 087 * Unless the resource is being created, the properties of the original resource 088 * are subsequently copied to this new version. Subsequent operations targeting 089 * the original resource through a proxy from the same provider will be 090 * redirected to operate on the version cached by the change context. 091 * </p> 092 * 093 * <p> 094 * The delivery of modified resources from a change context to the database is 095 * controlled by the delivery order list parameter of any "do" method designed 096 * to operate on change context resources. Such "do" methods are specified in 097 * this interface and its extensions. See also 098 * {@link CqUserDb#doDeliver(Feedback, List)}. 099 * <p> 100 * The delivery order list parameter specifies which resources are to be 101 * delivered after successful completion of the operation. The resources are 102 * delivered in the order in which they appear in the delivery order list. 103 * Unique delivery order list values are defined by {@link CqProvider}} for 104 * specifying the delivery of the entire change context or just the resources 105 * modified by the current operation. 106 * </p> 107 * <p> 108 * Modifications (creations or deletions) initiated in a change context can be 109 * abandoned before they are delivered by removing the modified resource from 110 * the change context. "do" methods are defined for clearing the entire change 111 * context ({@link CqUserDb#doClearContext(Feedback)}, reverting any 112 * individual resource ({@link #doRevert(Feedback)} or reverting a list of 113 * resources ({@link CqUserDb#doRevert(Feedback, List)}. 114 * </p> 115 * <p> 116 * The {@link #doWriteProperties(Feedback, List)} and 117 * {@link #doUnbindAll(Feedback, List)} methods in this interface overload 118 * methods defined by the WVCM standard. If the standard methods are applied to 119 * a context resource, they behave as if the {@link CqProvider#AUTO} delivery 120 * order list was used in the extended method. If the targeted context resource 121 * is not yet in the change context, {@link CqProvider#AUTO} behaves like the 122 * {@link CqProvider#DELIVER}, causing any changes made by the method to be 123 * immediately delivered from the change context. If the targeted resource is 124 * already in the change context, {@link CqProvider#AUTO} behaves like 125 * {@link CqProvider#HOLD}, leaving the modified resource still in the change 126 * context. Since the generic WVCM client would not be aware of the change 127 * context, it looks to the WVCM client as if doWriteProperties is simply 128 * writing properties directly to the resource on the server. 129 * </p> 130 * 131 * @see CqUserDb#doClearContext(Feedback) 132 * @see CqUserDb#doDeliver(Feedback, List) 133 * @see CqUserDb#doRevert(Feedback, List) 134 * @see CqUserDb#getModifiedResourcesList() 135 * @see CqUserDb#getMoribundResourcesList() 136 * @see CqProvider#HOLD 137 * @see CqProvider#DELIVER 138 * @see CqProvider#DELIVER_ALL 139 * @see CqProvider#AUTO 140 * 141 */ 142 public interface CqContextResource extends CqUserDbMember 143 { 144 /** 145 * Attempts to deliver this resource to the database. 146 * 147 * @param feedback A request for the properties of this resource that are to 148 * be included in the proxy returned by this operation. 149 * @return A proxy for the delivered resource populated with the requested 150 * properties. 151 * @throws WvcmException if this resource has no modifications to deliver to 152 * the database or if any of the modifications are invalid. 153 */ 154 CqContextResource doDeliver(Feedback feedback) throws WvcmException; 155 156 /** 157 * Removes the modified or moribund resource referenced by this proxy from 158 * the client's change context, thereby revealing at that location the 159 * resource, if any, in the database. This is <i>not</i> an undo operation 160 * applied only to the most recent modification of the resource. If removes 161 * <i>all</i> modifications made to the resource since it was last 162 * delivered to the database. 163 * <p> 164 * Note: other resources in the change context, even though initiated by 165 * changes to this resource, are not removed from the change context by this 166 * operation. 167 * <P> 168 * Since the target of this operation is being removed it makes little sense 169 * to write dirty properties to that resource before it is removed. 170 * Consequently, any dirty properties in the proxy are ignored. 171 * 172 * @param feedback A Feedback object requesting property values from the 173 * resource after the resource has been reverted. May be <b>null</b> 174 * if no properties are desired. 175 * @return A proxy for the resource made visible after removing the modified 176 * or moribund resource from the change context. Will be <b>null</b> 177 * if no such resource exists. 178 * 179 * @throws WvcmException if the resource was not writable or if there were 180 * problems reverting it. 181 */ 182 CqContextResource doRevert(Feedback feedback) 183 throws WvcmException; 184 185 /** 186 * Writes dirty properties from this proxy to the targeted context resource 187 * using implicitly {@link CqProvider#AUTO} as the delivery order list value. 188 * <p> 189 * This method is intended primarily for the use of generic WVCM clients, 190 * who have no knowledge of change contexts and their semantics and would 191 * expect context resources to behave simply as non-versioned resources. The 192 * net impact of this operation on the change context is nil; it will 193 * neither add new resources to the change context nor remove existing 194 * resources from the change context. 195 * <p> 196 * If the resource to be modified is not in the change context prior to 197 * calling this method, then the modified resource is immediately written 198 * back to the database when the property update succeeds and is removed 199 * from the change context when the update fails. 200 * <p> 201 * If the resource is already modified in the change context, then the 202 * resource remains in the change context after the operation whether the 203 * property update succeeds or fails. 204 * <p> 205 * If this proxy contains no dirty properties, no action is started, and no 206 * delivery takes place. If, in addition, the PropertyRequest for the result 207 * proxy provided by the feedback argument is null, no interaction with the 208 * server is initiated and, hence, the proxy location is not verified. A 209 * non-null (but possibly empty) PropertyRequest for the result proxy will 210 * force a server interaction and verification of the proxy location. 211 * 212 * @return A proxy for this resource (after delivery if a delivery happens) 213 * populated with the properties requested by the Feedback object 214 * for the result. 215 * 216 * @throws WvcmException If there are errors when attempting update 217 * properties or deliver the resource back to the database. 218 */ 219 Resource doWriteProperties(Feedback feedback) 220 throws WvcmException; 221 222 /** 223 * Writes dirty properties to the change context-copy of this resource and, 224 * optionally, requests that modified or moribund resources in the change 225 * context be delivered to or deleted from the database. 226 * <p> 227 * If the change context does not already have a copy of this resource, one 228 * is created in the change context. If an action is required and one is not 229 * specified by a {@link CqRecord#ACTION} property value in this proxy, a 230 * MODIFY-type action is started if one is uniquely defined for the 231 * resource. 232 * <p> 233 * Updated properties are not written back to the database until delivery of 234 * those changes to the database is requested by the client through the use 235 * of a delivery order list parameter or invocation of a doDeliver method. 236 * <p> 237 * If this proxy contains no dirty properties, no action is started and the 238 * state of the resource in the change context is not modified. If, in 239 * addition, the PropertyRequest for the result proxy provided by the 240 * feedback argument is <b>null</b> and also not delivery is requested, no 241 * interaction with the server is initiated and, hence, the proxy location 242 * is not verified. 243 * <p> 244 * A non-null (but possibly empty) PropertyRequest for the result proxy will 245 * force a server interaction and verification of the proxy location, even 246 * if the proxy contains no dirty properties and no delivery is indicated. 247 * 248 * @param feedback An instance of Feedback requesting properties for this 249 * resource and for the resources delivered by this operation. 250 * May be <b>null</b> if no feedback is desired. 251 * 252 * @param deliveryOrder If {@link CqProvider#HOLD} the modified resource is 253 * left in a writable state in the change context--the modified 254 * resource in the change context must be delivered before the 255 * modifications become visible to other providers. If not 256 * {@link CqProvider#HOLD}, the modified and moribund resources 257 * specified by this parameter will be delivered to or deleted 258 * from the database in the order indicated. To deliver all 259 * modified and moribund resources in an arbitrary order, use 260 * {@link CqProvider#DELIVER_ALL}. To deliver just this modified 261 * resource, use {@link CqProvider#DELIVER}. Must not be <b>null</b>. 262 * @return A proxy for this resource populated with the properties requested 263 * by the Feedback object for the result. The properties reflect the 264 * state of the resource after delivery if delivery has been 265 * requested. 266 * 267 * @throws WvcmException If there are errors when attempting to write 268 * properties or deliver the resource. 269 */ 270 CqContextResource doWriteProperties(Feedback feedback, 271 List<CqContextResource> deliveryOrder) 272 throws WvcmException; 273 274 /** 275 * Initiates the deletion of this context resource from the database using 276 * implicitly {@link CqProvider#AUTO} as the delivery order list value. 277 * The deletion of the resource becomes permanent and visible to other 278 * proxies only after this deletion has been delivered. Prior to delivery, 279 * the deletion of the resource may be canceled by executing 280 * {@link #doRevert(Feedback)} on the resource. 281 * <p> 282 * This method is intended primarily for the use of generic WVCM clients, 283 * who have no knowledge of change contexts and their semantics and would 284 * expect context resources to behave simply as non-versioned resources. The 285 * net impact of this operation on the change context is nil; it will 286 * neither add new resources to the change context nor remove existing 287 * resources from the change context. 288 * <p> 289 * Between the time a resource is deleted and that deletion becomes 290 * permanent, the resource is said to be <i>moribund</i> (near death). A 291 * moribund resource can be targeted only by a {@link #doDeliver(Feedback)} 292 * or {@link #doRevert(Feedback)} operation. Any other method targeted to a 293 * moribund resource will throw a RESOURCE_NOT_FOUND exception. Moribund 294 * resources may also appear in a delivery order list parameter. 295 * <p> 296 * If an action must be started to perform the deletion, another action must 297 * not already be active on this resource. If no action is specified by a 298 * {@link CqRecord#ACTION} property value in this proxy and a DELETE-type 299 * action is not uniquely defined for this type of resource an 300 * {@link com.ibm.rational.wvcm.stp.StpException.StpReasonCode#UNKNOWN_ACTION} exception is thrown. 301 * <p> 302 * If the resource was not in the change context when this method was 303 * invoked, the deletion becomes permanent immediately--before the method 304 * returns. If it was already in the change context, however, then no 305 * delivery is attempted and delivery will have to be requested directly to 306 * complete the deletion. 307 * 308 * @throws WvcmException If the resource does not exist or cannot be deleted 309 * using the default DELETE action. 310 * 311 * @see StpResource#doUnbindAll(Feedback) 312 */ 313 void doUnbindAll(Feedback feedback) 314 throws WvcmException; 315 316 /** 317 * Initiates the deletion of this context resource from the database. The 318 * deletion of the resource becomes permanent and visible to other proxies 319 * only after this deletion has been delivered. Prior to delivery, the 320 * deletion of the resource may be canceled by executing 321 * {@link #doRevert(Feedback)} on the resource. 322 * <p> 323 * Between the time a resource is deleted and that deletion becomes 324 * permanent, the resource is said to be <i>moribund</i> (near death). A 325 * moribund resource can be accessed only by a {@link #doDeliver(Feedback)} 326 * or {@link #doRevert(Feedback)} operation. Any other method will throw a 327 * RESOURCE_NOT_FOUND exception. 328 * <p> 329 * If an action must be started to perform the deletion, another action must 330 * not already be active on this resource. If no action is specified by a 331 * {@link CqRecord#ACTION} property value in this proxy and a DELETE-type 332 * action is not uniquely defined for this type of resource an 333 * {@link com.ibm.rational.wvcm.stp.StpException.StpReasonCode#UNKNOWN_ACTION} exception is thrown. 334 * <p> 335 * The disposition of the change context after the deletion succeeds is 336 * controlled by the deliveryOrder parameter 337 * </p> 338 * 339 * @param feedback A Feedback object requesting the properties desired from 340 * resources modified during this operation. May be null if no 341 * properties are desired. 342 * @param deliveryOrder If {@link CqProvider#HOLD} the moribund resource is 343 * left in the change context and not actually deleted--it must 344 * be delivered before the deletion becomes visible to other 345 * providers. If not {@link CqProvider#HOLD}, the modified and 346 * moribund resources specified by this parameter will be 347 * delivered to or deleted from the database in the order 348 * indicated. To deliver all modified and moribund resources in 349 * an arbitrary order, use {@link CqProvider#DELIVER_ALL}. To 350 * deliver just this moribund resource, use 351 * {@link CqProvider#DELIVER}. Must not be <b>null</b>. 352 * 353 * @throws WvcmException If the resource does not exist or cannot be deleted 354 * using the default DELETE action. 355 * 356 * @see StpResource#doUnbindAll(Feedback) 357 */ 358 void doUnbindAll(Feedback feedback, 359 List<CqContextResource> deliveryOrder) 360 throws WvcmException; 361 362 /** 363 * True if a modified copy of this resource exists in this clients database 364 * change context. 365 */ 366 PropertyName<Boolean> IS_MODIFIED = 367 new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-modified" /*NOI18N*/); 368 369 /** 370 * Returns the value of the {@link #IS_MODIFIED IS_MODIFIED} property as 371 * defined by this proxy. 372 * 373 * @return <b>true</b> if this proxy refers to a resource whose properties 374 * were modified in this client's change context; otherwise <b>false</b>. 375 * 376 * @throws WvcmException if this proxy does not define a value for the 377 * {@link #IS_MODIFIED IS_MODIFIED} property. 378 */ 379 boolean getIsModified() 380 throws WvcmException; 381 }