Project: stp

com.ibm.rational.wvcm.stp.cq
Interface CqContextResource

All Superinterfaces:
CqResource, CqUserDbMember, Resource, StpResource
All Known Subinterfaces:
CqAttachment, CqDynamicChoiceList, CqQuery, CqQueryFolder, CqQueryFolderItem, CqRecord, CqReport, CqReportFormat

public interface CqContextResource
extends CqUserDbMember

A CqContextResource is a ClearQuest user database resource that may be temporarily held in a change context while it is being modified and before those modifications are committed to the database. The server maintains a separate and private change context for each database a client is logged into. The new and modified resources in the change context are visible only to the client and to the hooks the client fires and will not be visible to other clients of the database until the resources in the change context are delivered to the database.

The process of modifying context resources involves three steps:

This modification process allows the client to work with its user to make coordinated changes to multiple resources, with the option of altering or abandoning at any time changes to any of the resources involved. In its full generality, this modification process could involve three or more interactions with the server, but for simple cases, the API allows the steps to be combined such that most modifications can be completed in only one interaction with the server.

Once a modification has been initiated by a client for a user, changes made to the resources involved are not visible to other users or clients until the modifications are delivered to the user database. The changes (including creation and deletion) are confined to the change context used and visible only through proxies obtained from the provider that made the changes.

The precise locking semantics of this modification process depend on the type of resource being modified. The only guarantee is that if an initiate-modify-deliver sequence is successfully completed by a client, the resources modified did not change in the database while they were being modified by that client.

When the modification of a resource is initiated, a writable version of the resource is created in the change context associated with the proxy used. Unless the resource is being created, the properties of the original resource are subsequently copied to this new version. Subsequent operations targeting the original resource through a proxy from the same provider will be redirected to operate on the version cached by the change context.

The delivery of modified resources from a change context to the database is controlled by the delivery order list parameter of any "do" method designed to operate on change context resources. Such "do" methods are specified in this interface and its extensions. See also CqUserDb.doDeliver(Feedback, List).

The delivery order list parameter specifies which resources are to be delivered after successful completion of the operation. The resources are delivered in the order in which they appear in the delivery order list. Unique delivery order list values are defined by CqProvider} for specifying the delivery of the entire change context or just the resources modified by the current operation.

Modifications (creations or deletions) initiated in a change context can be abandoned before they are delivered by removing the modified resource from the change context. "do" methods are defined for clearing the entire change context (CqUserDb.doClearContext(Feedback), reverting any individual resource (doRevert(Feedback) or reverting a list of resources (CqUserDb.doRevert(Feedback, List).

The doWriteProperties(Feedback, List) and doUnbindAll(Feedback, List) methods in this interface overload methods defined by the WVCM standard. If the standard methods are applied to a context resource, they behave as if the CqProvider.AUTO delivery order list was used in the extended method. If the targeted context resource is not yet in the change context, CqProvider.AUTO behaves like the CqProvider.DELIVER, causing any changes made by the method to be immediately delivered from the change context. If the targeted resource is already in the change context, CqProvider.AUTO behaves like CqProvider.HOLD, leaving the modified resource still in the change context. Since the generic WVCM client would not be aware of the change context, it looks to the WVCM client as if doWriteProperties is simply writing properties directly to the resource on the server.

See Also:
CqUserDb.doClearContext(Feedback), CqUserDb.doDeliver(Feedback, List), CqUserDb.doRevert(Feedback, List), CqUserDb.getModifiedResourcesList(), CqUserDb.getMoribundResourcesList(), CqProvider.HOLD, CqProvider.DELIVER, CqProvider.DELIVER_ALL, CqProvider.AUTO

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.ibm.rational.wvcm.stp.StpResource
StpResource.UnsupportedProperty
 
Nested classes/interfaces inherited from interface javax.wvcm.Resource
Resource.CopyFlag
 
Field Summary
static PropertyNameList.PropertyName<Boolean> IS_MODIFIED
          True if a modified copy of this resource exists in this clients database change context.
 
Fields inherited from interface CqUserDbMember
DB_SET, USER_DB
 
Fields inherited from interface com.ibm.rational.wvcm.stp.StpResource
ALL_PROPERTIES, AUTHENTICATION_REALM, CREATOR_GROUP_NAME, CREATOR_LOGIN_NAME, EFFICIENT_LOCATION, INVALID_PROPERTIES, REPOSITORY, STABLE_LOCATION, USER_FRIENDLY_LOCATION
 
Fields inherited from interface javax.wvcm.Resource
ALL_CUSTOM_PROPERTIES, COMMENT, CONTENT_CHARACTER_SET, CONTENT_IDENTIFIER, CONTENT_LANGUAGE, CONTENT_LENGTH, CONTENT_TYPE, CREATION_DATE, CREATOR_DISPLAY_NAME, DISPLAY_NAME, IS_EXECUTABLE, LAST_MODIFIED, PARENT_LIST, PATHNAME_LOCATION, PROVIDER_LIST, RESOURCE_IDENTIFIER, WORKSPACE_FOLDER_LIST
 
Method Summary
 CqContextResource doDeliver(Feedback feedback)
          Attempts to deliver this resource to the database.
 CqContextResource doRevert(Feedback feedback)
          Removes the modified or moribund resource referenced by this proxy from the client's change context, thereby revealing at that location the resource, if any, in the database.
 void doUnbindAll(Feedback feedback)
          Initiates the deletion of this context resource from the database using implicitly CqProvider.AUTO as the delivery order list value.
 void doUnbindAll(Feedback feedback, List<CqContextResource> deliveryOrder)
          Initiates the deletion of this context resource from the database.
 Resource doWriteProperties(Feedback feedback)
          Writes dirty properties from this proxy to the targeted context resource using implicitly CqProvider.AUTO as the delivery order list value.
 CqContextResource doWriteProperties(Feedback feedback, List<CqContextResource> deliveryOrder)
          Writes dirty properties to the change context-copy of this resource and, optionally, requests that modified or moribund resources in the change context be delivered to or deleted from the database.
 boolean getIsModified()
          Returns the value of the IS_MODIFIED property as defined by this proxy.
 
Methods inherited from interface CqUserDbMember
getDbSet, getUserDb
 
Methods inherited from interface CqResource
cqProvider, getComment, getContentCharacterSet, getContentIdentifier, getContentLanguage, getContentLength, getContentType, getCreationDate, getCreatorDisplayName, getCreatorGroupName, getCreatorLoginName, getIsExecutable, getLastModified, getProviderList, getWorkspaceFolderList, setComment, setContentCharacterSet, setContentLanguage, setContentType, setCreatorDisplayName, setIsExecutable
 
Methods inherited from interface com.ibm.rational.wvcm.stp.StpResource
doReadProperties, equals, getAllProperties, getAuthenticationRealm, getCustomProperties, getEfficientLocation, getInvalidProperties, getMetaProperties, getPropertyException, getRepository, getResourceError, getResourceIdentifier, getStableLocation, getUserFriendlyLocation, hashCode, hasProperties, initMetaProperty, proxyType, stpLocation, stpProvider
 
Methods inherited from interface javax.wvcm.Resource
doCopy, doFind, doFindAll, doGetPropertyNameList, doGetPropertyNameList, doReadContent, doReadProperties, doWriteContent, forgetProperty, getDisplayName, getParentList, getPathnameLocation, getProperty, initProperty, location, lookupProperty, modifyLocation, propertyNameList, provider, removeProperty, setDisplayName, setProperty, setProperty, updatedPropertyNameList
 

Field Detail

IS_MODIFIED

static final PropertyNameList.PropertyName<Boolean> IS_MODIFIED
True if a modified copy of this resource exists in this clients database change context.

Method Detail

doDeliver

CqContextResource doDeliver(Feedback feedback)
                            throws WvcmException
Attempts to deliver this resource to the database.

Parameters:
feedback - A request for the properties of this resource that are to be included in the proxy returned by this operation.
Returns:
A proxy for the delivered resource populated with the requested properties.
Throws:
WvcmException - if this resource has no modifications to deliver to the database or if any of the modifications are invalid.

doRevert

CqContextResource doRevert(Feedback feedback)
                           throws WvcmException
Removes the modified or moribund resource referenced by this proxy from the client's change context, thereby revealing at that location the resource, if any, in the database. This is not an undo operation applied only to the most recent modification of the resource. If removes all modifications made to the resource since it was last delivered to the database.

Note: other resources in the change context, even though initiated by changes to this resource, are not removed from the change context by this operation.

Since the target of this operation is being removed it makes little sense to write dirty properties to that resource before it is removed. Consequently, any dirty properties in the proxy are ignored.

Parameters:
feedback - A Feedback object requesting property values from the resource after the resource has been reverted. May be null if no properties are desired.
Returns:
A proxy for the resource made visible after removing the modified or moribund resource from the change context. Will be null if no such resource exists.
Throws:
WvcmException - if the resource was not writable or if there were problems reverting it.

doUnbindAll

void doUnbindAll(Feedback feedback)
                 throws WvcmException
Initiates the deletion of this context resource from the database using implicitly CqProvider.AUTO as the delivery order list value. The deletion of the resource becomes permanent and visible to other proxies only after this deletion has been delivered. Prior to delivery, the deletion of the resource may be canceled by executing doRevert(Feedback) on the resource.

This method is intended primarily for the use of generic WVCM clients, who have no knowledge of change contexts and their semantics and would expect context resources to behave simply as non-versioned resources. The net impact of this operation on the change context is nil; it will neither add new resources to the change context nor remove existing resources from the change context.

Between the time a resource is deleted and that deletion becomes permanent, the resource is said to be moribund (near death). A moribund resource can be targeted only by a doDeliver(Feedback) or doRevert(Feedback) operation. Any other method targeted to a moribund resource will throw a RESOURCE_NOT_FOUND exception. Moribund resources may also appear in a delivery order list parameter.

If an action must be started to perform the deletion, another action must not already be active on this resource. If no action is specified by a CqRecord.ACTION property value in this proxy and a DELETE-type action is not uniquely defined for this type of resource an StpException.StpReasonCode.UNKNOWN_ACTION exception is thrown.

If the resource was not in the change context when this method was invoked, the deletion becomes permanent immediately--before the method returns. If it was already in the change context, however, then no delivery is attempted and delivery will have to be requested directly to complete the deletion.

Specified by:
doUnbindAll in interface Resource
Throws:
WvcmException - If the resource does not exist or cannot be deleted using the default DELETE action.
See Also:
Resource.doUnbindAll(Feedback)

doUnbindAll

void doUnbindAll(Feedback feedback,
                 List<CqContextResource> deliveryOrder)
                 throws WvcmException
Initiates the deletion of this context resource from the database. The deletion of the resource becomes permanent and visible to other proxies only after this deletion has been delivered. Prior to delivery, the deletion of the resource may be canceled by executing doRevert(Feedback) on the resource.

Between the time a resource is deleted and that deletion becomes permanent, the resource is said to be moribund (near death). A moribund resource can be accessed only by a doDeliver(Feedback) or doRevert(Feedback) operation. Any other method will throw a RESOURCE_NOT_FOUND exception.

If an action must be started to perform the deletion, another action must not already be active on this resource. If no action is specified by a CqRecord.ACTION property value in this proxy and a DELETE-type action is not uniquely defined for this type of resource an StpException.StpReasonCode.UNKNOWN_ACTION exception is thrown.

The disposition of the change context after the deletion succeeds is controlled by the deliveryOrder parameter

Parameters:
feedback - A Feedback object requesting the properties desired from resources modified during this operation. May be null if no properties are desired.
deliveryOrder - If CqProvider.HOLD the moribund resource is left in the change context and not actually deleted--it must be delivered before the deletion becomes visible to other providers. If not CqProvider.HOLD, the modified and moribund resources specified by this parameter will be delivered to or deleted from the database in the order indicated. To deliver all modified and moribund resources in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just this moribund resource, use CqProvider.DELIVER. Must not be null.
Throws:
WvcmException - If the resource does not exist or cannot be deleted using the default DELETE action.
See Also:
Resource.doUnbindAll(Feedback)

doWriteProperties

Resource doWriteProperties(Feedback feedback)
                           throws WvcmException
Writes dirty properties from this proxy to the targeted context resource using implicitly CqProvider.AUTO as the delivery order list value.

This method is intended primarily for the use of generic WVCM clients, who have no knowledge of change contexts and their semantics and would expect context resources to behave simply as non-versioned resources. The net impact of this operation on the change context is nil; it will neither add new resources to the change context nor remove existing resources from the change context.

If the resource to be modified is not in the change context prior to calling this method, then the modified resource is immediately written back to the database when the property update succeeds and is removed from the change context when the update fails.

If the resource is already modified in the change context, then the resource remains in the change context after the operation whether the property update succeeds or fails.

If this proxy contains no dirty properties, no action is started, and no delivery takes place. If, in addition, the PropertyRequest for the result proxy provided by the feedback argument is null, no interaction with the server is initiated and, hence, the proxy location is not verified. A non-null (but possibly empty) PropertyRequest for the result proxy will force a server interaction and verification of the proxy location.

Specified by:
doWriteProperties in interface Resource
Parameters:
feedback - Specifies optional feedback to the caller.
Returns:
A proxy for this resource (after delivery if a delivery happens) populated with the properties requested by the Feedback object for the result.
Throws:
WvcmException - If there are errors when attempting update properties or deliver the resource back to the database.

doWriteProperties

CqContextResource doWriteProperties(Feedback feedback,
                                    List<CqContextResource> deliveryOrder)
                                    throws WvcmException
Writes dirty properties to the change context-copy of this resource and, optionally, requests that modified or moribund resources in the change context be delivered to or deleted from the database.

If the change context does not already have a copy of this resource, one is created in the change context. If an action is required and one is not specified by a CqRecord.ACTION property value in this proxy, a MODIFY-type action is started if one is uniquely defined for the resource.

Updated properties are not written back to the database until delivery of those changes to the database is requested by the client through the use of a delivery order list parameter or invocation of a doDeliver method.

If this proxy contains no dirty properties, no action is started and the state of the resource in the change context is not modified. If, in addition, the PropertyRequest for the result proxy provided by the feedback argument is null and also not delivery is requested, no interaction with the server is initiated and, hence, the proxy location is not verified.

A non-null (but possibly empty) PropertyRequest for the result proxy will force a server interaction and verification of the proxy location, even if the proxy contains no dirty properties and no delivery is indicated.

Parameters:
feedback - An instance of Feedback requesting properties for this resource and for the resources delivered by this operation. May be null if no feedback is desired.
deliveryOrder - If CqProvider.HOLD the modified resource is left in a writable state in the change context--the modified resource in the change context must be delivered before the modifications become visible to other providers. If not CqProvider.HOLD, the modified and moribund resources specified by this parameter will be delivered to or deleted from the database in the order indicated. To deliver all modified and moribund resources in an arbitrary order, use CqProvider.DELIVER_ALL. To deliver just this modified resource, use CqProvider.DELIVER. Must not be null.
Returns:
A proxy for this resource populated with the properties requested by the Feedback object for the result. The properties reflect the state of the resource after delivery if delivery has been requested.
Throws:
WvcmException - If there are errors when attempting to write properties or deliver the resource.

getIsModified

boolean getIsModified()
                      throws WvcmException
Returns the value of the IS_MODIFIED property as defined by this proxy.

Returns:
true if this proxy refers to a resource whose properties were modified in this client's change context; otherwise false.
Throws:
WvcmException - if this proxy does not define a value for the IS_MODIFIED property.

Generated Wed 29-Feb-2012 11:58 AM

Copyright © IBM 2012. All rights reserved.