|
Project: stp | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface CqContextResource
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.
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 com.ibm.rational.wvcm.stp.StpResource |
---|
doReadProperties, equals, getAllProperties, getAuthenticationRealm, getCustomProperties, getEfficientLocation, getInvalidProperties, getMetaProperties, getPropertyException, getRepository, getResourceError, getResourceIdentifier, getStableLocation, getUserFriendlyLocation, hashCode, hasProperties, initMetaProperty, proxyType, setPropertyClean, 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 |
---|
static final PropertyNameList.PropertyName<Boolean> IS_MODIFIED
Method Detail |
---|
CqContextResource doDeliver(Feedback feedback) throws WvcmException
feedback
- A request for the properties of this resource that are to
be included in the proxy returned by this operation.
WvcmException
- if this resource has no modifications to deliver to
the database or if any of the modifications are invalid.CqContextResource doRevert(Feedback feedback) throws WvcmException
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.
feedback
- A Feedback object requesting property values from the
resource after the resource has been reverted. May be null
if no properties are desired.
WvcmException
- if the resource was not writable or if there were
problems reverting it.void doUnbindAll(Feedback feedback) throws WvcmException
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.
doUnbindAll
in interface Resource
WvcmException
- If the resource does not exist or cannot be deleted
using the default DELETE action.Resource.doUnbindAll(Feedback)
void doUnbindAll(Feedback feedback, List<CqContextResource> deliveryOrder) throws WvcmException
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
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.
WvcmException
- If the resource does not exist or cannot be deleted
using the default DELETE action.Resource.doUnbindAll(Feedback)
Resource doWriteProperties(Feedback feedback) throws WvcmException
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.
doWriteProperties
in interface Resource
feedback
- Specifies optional feedback to the caller.
WvcmException
- If there are errors when attempting update
properties or deliver the resource back to the database.CqContextResource doWriteProperties(Feedback feedback, List<CqContextResource> deliveryOrder) throws WvcmException
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.
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.
WvcmException
- If there are errors when attempting to write
properties or deliver the resource.boolean getIsModified() throws WvcmException
IS_MODIFIED
property as
defined by this proxy.
WvcmException
- if this proxy does not define a value for the
IS_MODIFIED
property.
|
Generated Tue 7-Feb-2017 11:15 PM | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |