Project: stp

com.ibm.rational.wvcm.stp
Interface StpResource

All Superinterfaces:
Resource
All Known Subinterfaces:
CcActivity, CcAttributeType, CcBaseline, CcBranch, CcBranchType, CcComponent, CcDirectory, CcDirectoryElement, CcDirectoryVersion, CcElement, CcElementType, CcFile, CcHyperlink, CcHyperlinkType, CcLabelType, CcProject, CcProjectFolder, CcRegistryRegion, CcReplica, CcResource, CcStream, CcSymlink, CcTriggerType, CcTypeBase, CcVersion, CcView, CcViewTag, CcVob, CcVobResource, CcVobTag, CqAction, CqAttachment, CqAttachmentFolder, CqContextResource, CqDb, CqDbSet, CqDynamicChoiceList, CqFieldDefinition, CqGroup, CqHook, CqQuery, CqQueryFolder, CqQueryFolderItem, CqRecord, CqRecordType, CqReplica, CqReport, CqReportFormat, CqResource, CqUser, CqUserDb, CqUserDbMember, StpAccessControlledResource, StpActivity, StpPrincipal, StpRepository

public interface StpResource
extends Resource

A proxy for a resource persisted in a repository or in a file area.


Nested Class Summary
static interface StpResource.UnsupportedProperty
          An annotation used on property getters or setters of a proxy interface to indicate that a property defined in a super interface is not supported by that proxy.
 
Nested classes/interfaces inherited from interface javax.wvcm.Resource
Resource.CopyFlag
 
Field Summary
static PropertyNameList.PropertyName<StpProperty.List<StpProperty<?>>> ALL_PROPERTIES
          A list of all the properties that are defined on this resource.
static PropertyNameList.PropertyName<String> AUTHENTICATION_REALM
          The authentication realm in which this resource resides.
static PropertyNameList.PropertyName<String> CREATOR_GROUP_NAME
          The group name of the user that created an object.
static PropertyNameList.PropertyName<String> CREATOR_LOGIN_NAME
          The login name of the user that created this object.
static PropertyNameList.PropertyName<StpLocation> EFFICIENT_LOCATION
          The most efficient location available for this resource.
static PropertyNameList.PropertyName<StpProperty.List<StpProperty<?>>> INVALID_PROPERTIES
          A list of the properties that are currently invalid for this resource
static PropertyNameList.PropertyName<StpRepository> REPOSITORY
          The StpRepository that contains this resource.
static PropertyNameList.PropertyName<StpLocation> STABLE_LOCATION
          The most stable (over space and time) location available for this resource.
static PropertyNameList.PropertyName<StpLocation> USER_FRIENDLY_LOCATION
          The most human-readable location for a resource.
 
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
 Resource doReadProperties(Resource context, Feedback feedback)
          Request the properties specified in feedback from the server resource represented by this proxy.
 boolean equals(Object rhs)
          Returns true iff it can be determined that this proxy references the same resource as the given proxy.
 StpProperty.List<StpProperty<?>> getAllProperties()
          Returns the properties defined in this proxy.
 String getAuthenticationRealm()
          Returns the value of the AUTHENTICATION_REALM property as defined by this proxy.
 String getCreatorGroupName()
          Returns the value of the CREATOR_GROUP_NAME property as defined by this proxy.
 String getCreatorLoginName()
          Returns the value of the CREATOR_LOGIN_NAME property as defined by this proxy.
 StpProperty.List<StpProperty<?>> getCustomProperties()
          Returns the custom properties recorded in this proxy.
 StpLocation getEfficientLocation()
          Returns the value of the EFFICIENT_LOCATION property as defined by this proxy.
 StpProperty.List<StpProperty<?>> getInvalidProperties()
          Returns the value of the INVALID_PROPERTIES property as defined by this proxy.
<T> StpProperty<T>
getMetaProperties(PropertyNameList.PropertyName<T> name)
          Returns the collection of metadata components defined in this proxy for a given PropertyName.
 StpException getPropertyException(PropertyNameList.PropertyName<?> propertyName)
          Returns the StpPropertyException that would be thrown by getProperty if it were called with the given PropertyName.
 StpRepository getRepository()
          Returns the value of the REPOSITORY property as defined by this proxy.
 StpException getResourceError()
          Returns the value of the resource error attribute associated with this proxy.
 String getResourceIdentifier()
          Note: the Resource.RESOURCE_IDENTIFIER property is defined only for server resources (it's undefined for uncontrolled controllable resources) and it's value is not available locally via ControllableResource.readProperties().
 StpLocation getStableLocation()
          Returns the value of the STABLE_LOCATION property as defined by this proxy.
 StpLocation getUserFriendlyLocation()
          Returns the value of the USER_FRIENDLY_LOCATION property as defined by this proxy.
 int hashCode()
          Returns the hashCode() for the value of this proxy's RESOURCE_IDENTIFIER property if the proxy has a value for it; otherwise returns the hashCode() for the proxy's Location object.
 boolean hasProperties(PropertyRequestItem wantedProp)
          Returns whether or not from this proxy uncorrupted property values can be obtained for all the properties and meta-properties specified by a given PropertyRequestItem, which may specify multiple and nested properties.
<T> void
initMetaProperty(PropertyNameList.PropertyName<?> propertyName, StpProperty.MetaPropertyName<T> metaPropertyName, T value)
          Sets the value of a meta-property of a property into this proxy without causing that property to be written to the resource on the next repository interaction.
 String proxyType()
          Returns an identifier that may be passed to StpProvider.buildProxy() to construct a proxy that supports the same interfaces as this proxy.
 StpLocation stpLocation()
          Returns the Location of this proxy's Location cast as an StpLocation.
 StpProvider stpProvider()
           
 
Methods inherited from interface javax.wvcm.Resource
doCopy, doFind, doFindAll, doGetPropertyNameList, doGetPropertyNameList, doReadContent, doReadProperties, doUnbindAll, doWriteContent, doWriteProperties, forgetProperty, getComment, getContentCharacterSet, getContentIdentifier, getContentLanguage, getContentLength, getContentType, getCreationDate, getCreatorDisplayName, getDisplayName, getIsExecutable, getLastModified, getParentList, getPathnameLocation, getProperty, getProviderList, getWorkspaceFolderList, initProperty, location, lookupProperty, modifyLocation, propertyNameList, provider, removeProperty, setComment, setContentCharacterSet, setContentLanguage, setContentType, setCreatorDisplayName, setDisplayName, setIsExecutable, setProperty, setProperty, updatedPropertyNameList
 

Field Detail

ALL_PROPERTIES

static final PropertyNameList.PropertyName<StpProperty.List<StpProperty<?>>> ALL_PROPERTIES
A list of all the properties that are defined on this resource. The returned properties can be retrieved as a list using getAllProperties() or individually, using getProperty or an appropriate getter method.


AUTHENTICATION_REALM

static final PropertyNameList.PropertyName<String> AUTHENTICATION_REALM
The authentication realm in which this resource resides. When credentials are needed to access this resource this is string that should be presented to the user to identify what the user is to provide credentials for.


CREATOR_GROUP_NAME

static final PropertyNameList.PropertyName<String> CREATOR_GROUP_NAME
The group name of the user that created an object. This value can only be satisfied by a request to the server; it is not available locally.


CREATOR_LOGIN_NAME

static final PropertyNameList.PropertyName<String> CREATOR_LOGIN_NAME
The login name of the user that created this object. A request for this value can only be satisfied by a request to a server; it is not available locally.


EFFICIENT_LOCATION

static final PropertyNameList.PropertyName<StpLocation> EFFICIENT_LOCATION
The most efficient location available for this resource. Clients should use this form of location when it is not necessary to either show this location to users, nor to archive resource references for use between sessions.

The efficient location is usually expressed by a repo-selector scheme location, but other location schemes may also be used depending on the type of resource.

The value of this property is always defined for every resource, but, in fact, it may not be more efficient than the other forms. But, if the resource has an efficient location, that location will be returned by this property.

The value returned always represents the identifier associated with the server state of the resource, even if the Resource on which it is requested has client-side state.

This is the location format usually used in the proxies returned from the server.

See Also:
USER_FRIENDLY_LOCATION, STABLE_LOCATION

INVALID_PROPERTIES

static final PropertyNameList.PropertyName<StpProperty.List<StpProperty<?>>> INVALID_PROPERTIES
A list of the properties that are currently invalid for this resource


REPOSITORY

static final PropertyNameList.PropertyName<StpRepository> REPOSITORY
The StpRepository that contains this resource.


STABLE_LOCATION

static final PropertyNameList.PropertyName<StpLocation> STABLE_LOCATION
The most stable (over space and time) location available for this resource. Clients should use this form of location when archiving resource references for use between sessions.

The stable location is usually expressed by a repo-selector scheme location, but other location schemes may also be used depending on the type of resource.

The value of this property is always defined for every resource, but, in fact, it may not be stable. But, if the resource has a stable location, that location will be returned by this property.

The value returned always represents the identifier associated with the server state of the resource, even if the Resource on which it is requested has client-side state.

Note that the location used by a proxy returned by the server is formatted to provide the most efficient access to the resource in subsequent interactions with the server in the current session. That location is not necessarily the same as the resource's USER_FRIENDLY_LOCATION or its STABLE_LOCATION.

See Also:
USER_FRIENDLY_LOCATION, EFFICIENT_LOCATION

USER_FRIENDLY_LOCATION

static final PropertyNameList.PropertyName<StpLocation> USER_FRIENDLY_LOCATION
The most human-readable location for a resource. This is the form of location that clients should show to users when a precise location must be displayed--e.g. one which the user must remember and re-enter in a subsequent session. When such precision is not needed, the Resource.DISPLAY_NAME property would be a better choice for the presentation.

The USER_FRIENDLY_LOCATION is usually expressed by a user-friendly-selector scheme location, but other location schemes may also be used depending on the type of resource.

The value of this property is not always defined for every resource. If a resource does not have a USER_FRIENDLY_LOCATION, that is a strong indication that that resource should not be part of the normal object model presented to the user. If not defined, the value will be an empty string.

Note that the location used by a proxy returned by the server is formatted to provide the most efficient access to the resource in subsequent interactions with the server in the current session. That location is not necessarily the same as the resource's USER_FRIENDLY_LOCATION or its STABLE_LOCATION.

See Also:
STABLE_LOCATION, EFFICIENT_LOCATION
Method Detail

doReadProperties

Resource doReadProperties(Resource context,
                          Feedback feedback)
                          throws WvcmException
Request the properties specified in feedback from the server resource represented by this proxy. A new proxy will be constructed whose property map contains just the requested properties.

Properties are computed relative to the given context. For example, the VIEW_RELATIVE_PATH property of a CcVersion or CcElement resource can only be provided in the context of a CcView. Hence, you would use this form of doReadProperties to specify the CcView context that should be used.

The properties requiring a CcView context are

Parameters:
context - An optional proxy (often CcView) providing context for the generation of certain properties (typically VIEW_RELATIVE_PATH) in the returned report. May be null.
feedback - Provides optional feedback to the caller for long-running requests and/or a list of properties desired from the server. If the parameter is null or empty, a request is still made, and the returned proxy will have only the properties always requested from the server.
Returns:
A proxy containing the properties retrieved from the server (and error messages for those that could not be retrieved). The class of the returned proxy is the one most suited to the type of resource addressed.
Throws:
WvcmException - if failures occur
See Also:
Resource.doReadProperties(Feedback)

equals

boolean equals(Object rhs)
Returns true iff it can be determined that this proxy references the same resource as the given proxy. Proxy equality is based either on the value of the proxy's Location or on the value of the proxy's RESOURCE_IDENTIFIER property.

This proxy equates to another proxy iff one of the following conditions is true...

Overrides:
equals in class Object
Parameters:
rhs - The Object against which to compare this proxy. If the Object is not a Resource, equals returns false.
Returns:
true if the proxies compare equal as defined above; false otherwise.
See Also:
Object.equals(java.lang.Object)

getAllProperties

StpProperty.List<StpProperty<?>> getAllProperties()
Returns the properties defined in this proxy. Note, this "getter" will work even if ALL_PROPERTIES was not explicitly requested when building the proxy.

Returns:
An StpProperty.List containing a Property object for each property defined by this proxy. If there were errors in retrieving any meta-properties (including the VALUE meta-property), these errors can be discovered through the StpProperty interface.

getAuthenticationRealm

String getAuthenticationRealm()
                              throws WvcmException
Returns the value of the AUTHENTICATION_REALM property as defined by this proxy.

Returns:
A String containing the realm identifier passed to the authentication callback when accessing this resource.
Throws:
WvcmException - if this proxy does not define a value for the AUTHENTICATION_REALM property.

getCreatorGroupName

String getCreatorGroupName()
                           throws WvcmException
Returns the value of the CREATOR_GROUP_NAME property as defined by this proxy.

Throws:
WvcmException - Thrown if the property was never requested, or is otherwise unavailable (e.g. requested in a client-context only).

getCreatorLoginName

String getCreatorLoginName()
                           throws WvcmException
Returns the value of the CREATOR_LOGIN_NAME property as defined by this proxy.

Throws:
WvcmException - Thrown if the property was never requested, or otherwise unavailable (e.g. requested in a client-context only).

getCustomProperties

StpProperty.List<StpProperty<?>> getCustomProperties()
Returns the custom properties recorded in this proxy. Note, this "getter" will work even if ALL_CUSTOM_PROPERTIES was not explicitly requested when building the proxy.

Returns:
A Property.List containing a Property object for each custom (i.e. not defined by WVCM) property defined by this proxy. If there were errors in retrieving any meta-properties (including the VALUE meta-property), these errors can be discovered through the Property interface.

getEfficientLocation

StpLocation getEfficientLocation()
                                 throws WvcmException
Returns the value of the EFFICIENT_LOCATION property as defined by this proxy.

Returns:
The StpLocation value for the resources most efficient location. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the EFFICIENT_LOCATION property.

getInvalidProperties

StpProperty.List<StpProperty<?>> getInvalidProperties()
                                                      throws WvcmException
Returns the value of the INVALID_PROPERTIES property as defined by this proxy.

Returns:
A Property.List of Property objects, each identifying one invalid property of this Resource
Throws:
WvcmException - if this proxy does not define a value for the INVALID_PROPERTIES property.

getMetaProperties

<T> StpProperty<T> getMetaProperties(PropertyNameList.PropertyName<T> name)
                                 throws WvcmException
Returns the collection of metadata components defined in this proxy for a given PropertyName.

Parameters:
name - A PropertyName identifying the property whose metadata is desired
Returns:
An StpProperty instance that contains the metadata for the given property requested from the server through this proxy.
Throws:
WvcmException - if no metadata for the given property has been requested from the server through this proxy.

getPropertyException

StpException getPropertyException(PropertyNameList.PropertyName<?> propertyName)
Returns the StpPropertyException that would be thrown by getProperty if it were called with the given PropertyName.

If there was an error retrieving the property when requested, or the property was never defined in the proxy, an StpPropertyException is returned; otherwise null is returned.

Parameters:
propertyName - The property for which an exception is desired. Cannot be null.
Returns:
The exception that would be thrown by getProperty() if it were used to access the given propertyName; Will be null if no exception would be thrown.

getRepository

StpRepository getRepository()
                            throws WvcmException
Returns the value of the REPOSITORY property as defined by this proxy.

Returns:
The StpRepository that this resource is in. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the REPOSITORY property.

getResourceError

StpException getResourceError()
Returns the value of the resource error attribute associated with this proxy.

If this attribute is not null it indicates that an error occurred when trying to access the resource addressed by this proxy (even though that address was actually generated by the server). In this case, none of the properties requested for this proxy will be defined. The value of the resource error attribute is an StpException that records the nature of the problem encountered by the server.

This attribute is set only when this proxy is returned as an indirect result of a server interaction. If this defective address was used by a client as the target of a server contact method or if it was the expected direct result of some server contact method, that contact method would have thrown an exception rather than setting this attribute.

Whenever the server returns a list of resources (either as a direct response to a request or as the value of a property) it is possible that the server can enumerate all of the members of the list but cannot actually access one or more of the enumerated members to access its properties. When this happens, the operation is not aborted and does not itself throw an exception. Instead, a proxy is generated and marked with this resource error attribute so that the problem is record and then the rest of the list is processed.

Returns:
null if no error is associated with the resource, otherwise a StpException describing the error.

getResourceIdentifier

String getResourceIdentifier()
                             throws WvcmException
Note: the Resource.RESOURCE_IDENTIFIER property is defined only for server resources (it's undefined for uncontrolled controllable resources) and it's value is not available locally via ControllableResource.readProperties().

Specified by:
getResourceIdentifier in interface Resource
Returns:
the Resource.RESOURCE_IDENTIFIER property.
Throws:
WvcmException - if this Resource was not created with Resource.RESOURCE_IDENTIFIER as a wanted property.
See Also:
Resource.getResourceIdentifier(), Resource.RESOURCE_IDENTIFIER

getStableLocation

StpLocation getStableLocation()
                              throws WvcmException
Returns the value of the STABLE_LOCATION property as defined by this proxy.

Returns:
The StpLocation value. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the STABLE_LOCATION property.

getUserFriendlyLocation

StpLocation getUserFriendlyLocation()
                                    throws WvcmException
Returns the value of the USER_FRIENDLY_LOCATION property as defined by this proxy.

Returns:
The StpLocation value. Will never be null.
Throws:
WvcmException - if this proxy does not define a value for the USER_FRIENDLY_LOCATION property.

hashCode

int hashCode()
Returns the hashCode() for the value of this proxy's RESOURCE_IDENTIFIER property if the proxy has a value for it; otherwise returns the hashCode() for the proxy's Location object.

Overrides:
hashCode in class Object
See Also:
Object.hashCode()

hasProperties

boolean hasProperties(PropertyRequestItem wantedProp)
Returns whether or not from this proxy uncorrupted property values can be obtained for all the properties and meta-properties specified by a given PropertyRequestItem, which may specify multiple and nested properties.

If wantedProp is a nested property request then the test is applied recursively to the non-null value(s) of the property named by wantedProp.getRoot() testing in each value for valid instances of the properties named by wantedProp.getNested(). If any of the values identified by the property name are invalid, then this method returns false. Note that if the value for the root property of a PropertyName is null, the test for that PropertyName is deemed valid even if the PropertyName had nested properties.

Parameters:
wantedProp - A PropertyRequestItem, possibly with multiple nested properties, to check the value for. Cannot be null.
Returns:
true if there is an entry in this proxy for all properties named at the top level of the PropertyRequestItem, and those entries contain a valid value (not in error) and for those property values that are resources any nested property request is also similarly satisfied; false otherwise.

initMetaProperty

<T> void initMetaProperty(PropertyNameList.PropertyName<?> propertyName,
                          StpProperty.MetaPropertyName<T> metaPropertyName,
                          T value)
                      throws WvcmException
Sets the value of a meta-property of a property into this proxy without causing that property to be written to the resource on the next repository interaction. Like the setProperty() method, this method does not verify that the given object is a value suitable for the specified meta-property. This method also does not verify that the given PropertyName is appropriate for the type of resource represented by this proxy nor that the given MetaPropertyName is appropriate for the given PropertyName.

This method may be used in conjunction with StpProvider.buildProxy() to reconstruct proxies previously saved to persistent storage. Use buildProxy() to construct a proxy object of the appropriate type and then use this method to copy each saved meta-property value into that proxy object.

This method may also be used in conjunction with forgetProperty to merge meta-property values from one proxy into another and thereby facilitate the use of a proxy object as a long-lived cache for resource data. This approach is not recommended unless the client fully understands the pitfalls inherent in maintaining a cache of shared server data in a client for any length of time.

Note 1: Since the primary intent of this method is to provide the client with a means to restore a proxy from archive, this method will throw an exception if an attempt is made to define a meta-property value already being defined by this proxy.

If a client wants to use this method to update an existing meta-property entry within a proxy, that existing meta-property value must first be removed. Since the meta-properties of a property are usually tightly coupled, they cannot be removed independently. They can only be removed as a group using the javax.wvcm.forgetProperty() method. If the client wants to retain some of the existing meta-property values while updating others, it must first fetch all the existing meta-property values from the proxy (using getMetaProperties()), then remove their definitions from the proxy using forgetProperty(), and then redefine the individual meta-property entries via multiple invocations of this method, reusing the old values or computing new values in a manner appropriate to the client's needs.

Note 2: Because of its role in the definition of Resource.equals() and Resource.hashCode(), the Resource.RESOURCE_IDENTIFIER property may only be initialized at the time of proxy construction; e.g., via Provider.buildProxy().

Note 3: A property value set by any of the setXXX methods defined by this interface (or any of its extensions) will activate the writing of that value to the repository by the next doXYZ method. Use of initProperty to set any of the meta-properties of such a property will fail until the property is successfully written to the repository.

Note 4: If the entry in this proxy for the given PropertyName indicates that an error occurred on the last attempt to read the property from the repository, initMetaProperty will fail as if the meta-property being set were already defined; i.e. it will throw an exception. In this case, the client must execute forgetProperty() on the invalid entry before attempting to initialize any of its meta-properties.

Parameters:
propertyName - The PropertyName for the property whose meta-property is to be defined by the proxy. Must not be null, must not be equal to Resource.RESOURCE_IDENTIFIER, and must not be a PropertyName currently on the Resource.updatedPropertyNameList().
metaPropertyName - The MetaPropertyName for the meta-property whose value is to be defined by the proxy. Must not be null and must not name a meta-property whose value is already defined by this proxy.
value - The initial value for the meta-property identified by the other two arguments of this method. May be null.
Throws:
WvcmException - If the meta-property is already defined by this proxy.
See Also:
StpProvider.buildProxy(StpLocation, String, String), Resource.forgetProperty(javax.wvcm.PropertyNameList.PropertyName)

proxyType

String proxyType()
Returns an identifier that may be passed to StpProvider.buildProxy() to construct a proxy that supports the same interfaces as this proxy.

Returns:
A String object containing the proxy class information; will never be null.

stpLocation

StpLocation stpLocation()
Returns the Location of this proxy's Location cast as an StpLocation.

Returns:
The StpLocation for this Resource proxy. Will never be null.

stpProvider

StpProvider stpProvider()
Returns:
Returns the StpProvider from which this proxy was obtained.

Generated Fri 5-Nov-2010 03:50 AM

Copyright © IBM 2010. All rights reserved.