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 * © 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 }