|
Project: stp | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface StpResource
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. |
|
|
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. |
|
|
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()
|
Field Detail |
---|
static final PropertyNameList.PropertyName<StpProperty.List<StpProperty<?>>> ALL_PROPERTIES
getProperty
or an
appropriate getter method.
static final PropertyNameList.PropertyName<String> AUTHENTICATION_REALM
static final PropertyNameList.PropertyName<String> CREATOR_GROUP_NAME
static final PropertyNameList.PropertyName<String> CREATOR_LOGIN_NAME
static final PropertyNameList.PropertyName<StpLocation> EFFICIENT_LOCATION
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.
USER_FRIENDLY_LOCATION
,
STABLE_LOCATION
static final PropertyNameList.PropertyName<StpProperty.List<StpProperty<?>>> INVALID_PROPERTIES
static final PropertyNameList.PropertyName<StpRepository> REPOSITORY
static final PropertyNameList.PropertyName<StpLocation> STABLE_LOCATION
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.
USER_FRIENDLY_LOCATION
,
EFFICIENT_LOCATION
static final PropertyNameList.PropertyName<StpLocation> USER_FRIENDLY_LOCATION
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.
STABLE_LOCATION
,
EFFICIENT_LOCATION
Method Detail |
---|
Resource doReadProperties(Resource context, Feedback feedback) throws WvcmException
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
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.
WvcmException
- if failures occurResource.doReadProperties(Feedback)
boolean equals(Object rhs)
This proxy equates to another proxy iff one of the following conditions is true...
equals
in class Object
rhs
- The Object against which to compare this proxy. If the Object
is not a Resource, equals returns false.
Object.equals(java.lang.Object)
StpProperty.List<StpProperty<?>> getAllProperties()
String getAuthenticationRealm() throws WvcmException
AUTHENTICATION_REALM
property as defined by this proxy.
WvcmException
- if this proxy does not define a value for the
AUTHENTICATION_REALM
property.String getCreatorGroupName() throws WvcmException
CREATOR_GROUP_NAME
property as defined
by this proxy.
WvcmException
- Thrown if the property was never requested, or is
otherwise unavailable (e.g. requested in a client-context
only).String getCreatorLoginName() throws WvcmException
CREATOR_LOGIN_NAME
property as defined
by this proxy.
WvcmException
- Thrown if the property was never requested, or
otherwise unavailable (e.g. requested in a client-context
only).StpProperty.List<StpProperty<?>> getCustomProperties()
StpLocation getEfficientLocation() throws WvcmException
EFFICIENT_LOCATION
property as defined by this proxy.
WvcmException
- if this proxy does not define a value for the
EFFICIENT_LOCATION
property.StpProperty.List<StpProperty<?>> getInvalidProperties() throws WvcmException
INVALID_PROPERTIES
property as defined by this proxy.
WvcmException
- if this proxy does not define a value for the
INVALID_PROPERTIES
property.<T> StpProperty<T> getMetaProperties(PropertyNameList.PropertyName<T> name) throws WvcmException
name
- A PropertyName identifying the property whose metadata is
desired
WvcmException
- if no metadata for the given property has been
requested from the server through this proxy.StpException getPropertyException(PropertyNameList.PropertyName<?> 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.
propertyName
- The property for which an exception is desired.
Cannot be null.
propertyName
; Will be
null if no exception would be thrown.StpRepository getRepository() throws WvcmException
REPOSITORY
property as defined by this
proxy.
WvcmException
- if this proxy does not define a value for the
REPOSITORY
property.StpException getResourceError()
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.
String getResourceIdentifier() throws WvcmException
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().
getResourceIdentifier
in interface Resource
Resource.RESOURCE_IDENTIFIER
property.
WvcmException
- if this Resource was not created with
Resource.RESOURCE_IDENTIFIER
as a wanted property.Resource.getResourceIdentifier()
,
Resource.RESOURCE_IDENTIFIER
StpLocation getStableLocation() throws WvcmException
STABLE_LOCATION
property as defined by this proxy.
WvcmException
- if this proxy does not define a value for the
STABLE_LOCATION
property.StpLocation getUserFriendlyLocation() throws WvcmException
USER_FRIENDLY_LOCATION
property as
defined by this proxy.
WvcmException
- if this proxy does not define a value for the
USER_FRIENDLY_LOCATION
property.int hashCode()
hashCode
in class Object
Object.hashCode()
boolean hasProperties(PropertyRequestItem wantedProp)
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.
wantedProp
- A PropertyRequestItem, possibly with multiple nested
properties, to check the value for. Cannot be
null
.
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.<T> void initMetaProperty(PropertyNameList.PropertyName<?> propertyName, StpProperty.MetaPropertyName<T> metaPropertyName, T value) throws WvcmException
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.
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.
WvcmException
- If the meta-property is already defined by this
proxy.StpProvider.buildProxy(StpLocation, String, String)
,
Resource.forgetProperty(javax.wvcm.PropertyNameList.PropertyName)
String proxyType()
StpLocation stpLocation()
StpProvider stpProvider()
|
Generated Fri 5-Nov-2010 03:50 AM | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |