|
Project: stp | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Resource
A proxy for a persistent resource. A proxy for a persistent resource is used to retrieve information from the resource and to perform operations on the resource. A resource has both standard properties, which are named values whose semantics are specified by the API, as well as custom properties whose names are arbitrary strings selected by the client. A custom property has a namespace which allows different clients to use simple property names without conflicting with each other.
A proxy for a persistent resource contains the location of that persistent resource on the server that maintains that resource. A proxy can be created as the return value of a request to the server, in which case the proxy is initialized with a set of properties reflecting the state of the persistent resource at the time of the request (the list of wanted properties is specified as an argument to the request). Alternatively, a proxy can be created locally by a client (using the Provider interface), in which case it is initialized with an empty set of properties.
Two proxies are equal if they are known to identify the same resource,
where the identity of a proxy is determined by its RESOURCE_IDENTIFIER
property if it has one loaded, and if not, by its location()
.
Nested Class Summary | |
---|---|
static class |
Resource.CopyFlag
Boolean flags for the doCopy method |
Field Summary | |
---|---|
static PropertyNameList.PropertyName<Object> |
ALL_CUSTOM_PROPERTIES
A generic PropertyName that selects all custom properties (i.e., properties with a non-null namespace) that are defined on the resource. |
static PropertyNameList.PropertyName<String> |
COMMENT
A brief comment about a resource that is suitable for presentation to a user. |
static PropertyNameList.PropertyName<String> |
CONTENT_CHARACTER_SET
The name of the character set of the resource content. |
static PropertyNameList.PropertyName<String> |
CONTENT_IDENTIFIER
An implementation-defined String identifying the value of the content of a resource. |
static PropertyNameList.PropertyName<Locale> |
CONTENT_LANGUAGE
The name of the natural language used in a resource content, represented by a Locale object,
with country, language, and variant if appropriate. |
static PropertyNameList.PropertyName<Long> |
CONTENT_LENGTH
The size in bytes of the content of a resource. |
static PropertyNameList.PropertyName<String> |
CONTENT_TYPE
A MIME type string (see RFC 1590) indicating the media type of the resource content. |
static PropertyNameList.PropertyName<Date> |
CREATION_DATE
The date and time the resource was created. |
static PropertyNameList.PropertyName<String> |
CREATOR_DISPLAY_NAME
This property contains a description of the creator of the resource that is suitable for presentation to a user. |
static PropertyNameList.PropertyName<String> |
DISPLAY_NAME
Contains a description of the resource that is suitable for presentation to a user in a tree display. |
static PropertyNameList.PropertyName<Boolean> |
IS_EXECUTABLE
Whether the content is executable (i.e, can be run as a program). |
static PropertyNameList.PropertyName<Date> |
LAST_MODIFIED
The date and time the content of the resource was last modified. |
static PropertyNameList.PropertyName<ResourceList<Folder>> |
PARENT_LIST
The PARENT_LIST property enables clients to discover what folders contain a binding to this resource (that is, which folders have this resource as a bound member). |
static PropertyNameList.PropertyName<Location> |
PATHNAME_LOCATION
A location for this resource to which Location.parent() can be applied
zero or more times to produce a location for a folder in either
the WORKSPACE_FOLDER_LIST of this resource, or for a folder in
the Workspace.ACTIVITY_FOLDER_LIST or Workspace.VERSION_HISTORY_FOLDER_LIST
of some workspace that is a member of a folder in WORKSPACE_FOLDER_LIST . |
static PropertyNameList.PropertyName<List<String>> |
PROVIDER_LIST
A list of names of alternative providers for the persistent resource identified by this resource. |
static PropertyNameList.PropertyName<String> |
RESOURCE_IDENTIFIER
A resource identifier is an optional unique and immutable identifier for a resource. |
static PropertyNameList.PropertyName<ResourceList<Folder>> |
WORKSPACE_FOLDER_LIST
A list of folders that contain workspaces that are being managed by the same server that is managing this resource. |
Method Summary | ||
---|---|---|
Resource |
doCopy(Location destination,
Resource.CopyFlag[] flags,
Feedback feedback)
Create a copy of the resource identified by this Resource at the location identified by the destination . |
|
Resource |
doFind(Feedback feedback)
Find a persistent resource that "matches" this proxy. |
|
|
doFindAll(Feedback feedback)
Find all persistent resources that "match" this proxy. |
|
PropertyNameList |
doGetPropertyNameList(Feedback feedback)
Get the names of standard properties available on the server resource identified by this Resource. |
|
PropertyNameList |
doGetPropertyNameList(String namespace,
Feedback feedback)
Get the names of properties in a given namespace available on the server resource identified by this Resource. |
|
Resource |
doReadContent(OutputStream content,
Feedback feedback)
Get both the content and selected properties of this resource. |
|
Resource |
doReadProperties(Feedback feedback)
Get a set of properties of this Resource from the server. |
|
void |
doUnbindAll(Feedback feedback)
Unbinds the resource identified by this Resource from all folders in its PARENT_LIST . |
|
Resource |
doWriteContent(InputStream content,
String contentIdentifier,
Feedback feedback)
Persists content changes to a resource. |
|
Resource |
doWriteProperties(Feedback feedback)
Persists property changes to this Resource. |
|
void |
forgetProperty(PropertyNameList.PropertyName<?> name)
Removes the specified property of this Resource. |
|
String |
getComment()
Get the COMMENT property. |
|
String |
getContentCharacterSet()
Get the CONTENT_CHARACTER_SET property. |
|
String |
getContentIdentifier()
Get the CONTENT_IDENTIFIER property. |
|
Locale |
getContentLanguage()
Get the CONTENT_LANGUAGE property. |
|
long |
getContentLength()
Get the CONTENT_LENGTH property. |
|
String |
getContentType()
Get the CONTENT_TYPE property. |
|
Date |
getCreationDate()
Get the CREATION_DATE property. |
|
String |
getCreatorDisplayName()
Get the CREATOR_DISPLAY_NAME property. |
|
String |
getDisplayName()
Get the DISPLAY_NAME property. |
|
Boolean |
getIsExecutable()
Get the IS_EXECUTABLE property. |
|
Date |
getLastModified()
Get the LAST_MODIFIED property. |
|
ResourceList<Folder> |
getParentList()
Get the PARENT_LIST property. |
|
Location |
getPathnameLocation()
Get the PATHNAME_LOCATION property. |
|
|
getProperty(PropertyNameList.PropertyName<T> name)
Get the value of the specified property of this Resource. |
|
List<String> |
getProviderList()
Get the PROVIDER_LIST property. |
|
String |
getResourceIdentifier()
Get the RESOURCE_IDENTIFIER property. |
|
ResourceList<Folder> |
getWorkspaceFolderList()
Get the WORKSPACE_FOLDER_LIST property. |
|
|
initProperty(PropertyNameList.PropertyName<T> name,
T value)
Initializes the value of the specified property of this Resource. |
|
Location |
location()
Get the location of this resource. |
|
Object |
lookupProperty(PropertyNameList.PropertyName<?> name)
Lookup the value of the specified property of this Resource. |
|
void |
modifyLocation(Location location)
Modify the location of this resource. |
|
PropertyNameList |
propertyNameList()
Get the names of properties available on this client proxy. |
|
Provider |
provider()
Get the provider of this resource. |
|
void |
removeProperty(PropertyNameList.PropertyName<?> name)
Removes the specified property of this Resource. |
|
void |
setComment(String comment)
Set the COMMENT property. |
|
void |
setContentCharacterSet(String contentCharacterSet)
Set the CONTENT_CHARACTER_SET property. |
|
void |
setContentLanguage(Locale contentLanguage)
Set the CONTENT_LANGUAGE property. |
|
void |
setContentType(String contentType)
Set the CONTENT_TYPE property. |
|
void |
setCreatorDisplayName(String val)
Set the CREATOR_DISPLAY_NAME property. |
|
void |
setDisplayName(String val)
Set the DISPLAY_NAME property. |
|
void |
setIsExecutable(Boolean isExecutable)
Set the IS_EXECUTABLE property. |
|
|
setProperty(PropertyNameList.PropertyName<T> name,
T value)
Adds or replaces the value of the specified property of this Resource. |
|
|
setProperty(PropertyNameList.PropertyName<U> name,
U additions,
U removals)
Adds and removes the specified values from the current value of the specified list-valued property. |
|
PropertyNameList |
updatedPropertyNameList()
Get a list of modified properties that have been updated in the proxy by setXyz operations, but not been successfully written to the corresponding persistent resource by a doXyz operation. |
Field Detail |
---|
static final PropertyNameList.PropertyName<Object> ALL_CUSTOM_PROPERTIES
static final PropertyNameList.PropertyName<String> COMMENT
static final PropertyNameList.PropertyName<String> CONTENT_CHARACTER_SET
static final PropertyNameList.PropertyName<String> CONTENT_IDENTIFIER
static final PropertyNameList.PropertyName<Locale> CONTENT_LANGUAGE
Locale
object,
with country, language, and variant if appropriate.
static final PropertyNameList.PropertyName<Long> CONTENT_LENGTH
static final PropertyNameList.PropertyName<String> CONTENT_TYPE
static final PropertyNameList.PropertyName<Date> CREATION_DATE
static final PropertyNameList.PropertyName<String> CREATOR_DISPLAY_NAME
CREATOR_DISPLAY_NAME
of a version can be used to indicate who created that version.
A server may automatically set the CREATOR_DISPLAY_NAME
property
and not allow it to be changed by a client.
static final PropertyNameList.PropertyName<String> DISPLAY_NAME
Note that the DISPLAY_NAME
of a resource is in general
not the binding name of that resource in its parent folder,
because at a given time, a resource can be bound into
multiple parent folders, and have a different binding name in
each parent folder.
static final PropertyNameList.PropertyName<Boolean> IS_EXECUTABLE
static final PropertyNameList.PropertyName<Date> LAST_MODIFIED
static final PropertyNameList.PropertyName<ResourceList<Folder>> PARENT_LIST
Folder
objects.
static final PropertyNameList.PropertyName<Location> PATHNAME_LOCATION
Location.parent()
can be applied
zero or more times to produce a location for a folder in either
the WORKSPACE_FOLDER_LIST
of this resource, or for a folder in
the Workspace.ACTIVITY_FOLDER_LIST
or Workspace.VERSION_HISTORY_FOLDER_LIST
of some workspace that is a member of a folder in WORKSPACE_FOLDER_LIST
.
static final PropertyNameList.PropertyName<List<String>> PROVIDER_LIST
Provider
objects
can be generated from provider names using ProviderFactory.createProvider(String,ProviderFactory.Callback)
.
The preferred providers are specified earlier in the list.
static final PropertyNameList.PropertyName<String> RESOURCE_IDENTIFIER
Folder.doRebindChild(java.lang.String, javax.wvcm.Folder, java.lang.String, javax.wvcm.Folder.RebindFlag[], javax.wvcm.Feedback)
or by the addition/removal of additional locations for the
resource by Folder.doBindChild(java.lang.String, javax.wvcm.Resource, javax.wvcm.Folder.BindFlag[], javax.wvcm.Feedback)
and Folder.doUnbindChild(java.lang.String, javax.wvcm.Feedback)
.
If Provider.location(java.lang.String)
can be applied to the resource identifier of a resource
to produces a valid location, then that location MUST identify that resource.
static final PropertyNameList.PropertyName<ResourceList<Folder>> WORKSPACE_FOLDER_LIST
Method Detail |
---|
Resource doCopy(Location destination, Resource.CopyFlag[] flags, Feedback feedback) throws WvcmException
destination
.
The content of the copy is the same as the content of the
resource identified by this Resource, but the properties of the
copy are the default properties for a new resource.
Postconditions:
destination
- the location of the new resource created by doCopy.flags
- Array of boolean flags (may be null):
Resource.CopyFlag.OVERWRITE
:
Indicates whether an existing destination resource
will be overwritten rather than the request failing.feedback
- Specifies optional feedback to the caller.
WvcmException
- ReasonCode:
WvcmException.ReasonCode.CANNOT_OVERWRITE
:
If there already is a resource at the destination,
and the overwrite
is false
, the request MUST fail.
WvcmException.ReasonCode.METHOD_NOT_SUPPORTED
:
This proxy MUST NOT identify a folder version or a version history.
In order to create another version history whose versions have the same content,
the appropriate sequence of doVersionControl, doCheckout, doWriteContent, and doCheckin requests must be made.Resource doFind(Feedback feedback) throws WvcmException
Activity activityExample = WorkspaceProvider.activity(WorkspaceProvider.location("/my-act-repo")): activityExample.setCreatorDisplayName("Geoff Clemm"); Activity activity = (Activity)activityExample.doFind(null);would return an activity in "/my-act-repo" created by "Geoff Clemm". Unlike most doXyz methods, this method does not save changes to the proxy before executing the query. In particular, it is valid to execute this method on a proxy that could not be saved by
doWriteProperties(javax.wvcm.Feedback)
.
The precise rules for matching are as follows:
doReadProperties(javax.wvcm.Feedback)
)
or by explicitly setting property values (e.g., setComment(java.lang.String)
or more generally, setProperty(javax.wvcm.PropertyNameList.PropertyName, T)
).
WorkspaceProvider.workspace(javax.wvcm.Location)
, to match that proxy a resource
must implement the Workspace
interface.
doFind(javax.wvcm.Feedback)
method.
Object.equals(java.lang.Object)
R.P.value.
feedback
- the properties to be available in the returned resources.
null
is returned.
WvcmException
- if problems encountered communicating with server
or if the request could not be executed.<T extends Resource> ResourceList.ResponseIterator<T> doFindAll(Feedback feedback) throws WvcmException
Activity activityExample = WorkspaceProvider.activity(WorkspaceProvider.location("/my-act-repo")): activityExample.setCreatorDisplayName("Geoff Clemm"); ResponseIterator myActivities = activityExample.doFindAll(null);would return all activities in "/my-act-repo" created by "Geoff Clemm". See
doFind(javax.wvcm.Feedback)
.
feedback
- the properties to be available in the returned resources.
WvcmException
- if problems encountered communicating with server
or if the request could not be executed.PropertyNameList doGetPropertyNameList(Feedback feedback) throws WvcmException
feedback
- Provides optional feedback to the caller for long-running requests.
WvcmException
- if problems encountered communicating with serverPropertyNameList doGetPropertyNameList(String namespace, Feedback feedback) throws WvcmException
namespace
- the namespace for the requested property names.feedback
- Provides optional feedback to the caller for long-running requests.
WvcmException
- if problems encountered communicating with serverResource doReadContent(OutputStream content, Feedback feedback) throws WvcmException
content
- the resource content is written to this
byte stream. The stream is then closed.feedback
- Specifies optional feedback to the caller.
WvcmException
- ReasonCode:
WvcmException.ReasonCode.METHOD_NOT_SUPPORTED
:
This resource has no content.Resource doReadProperties(Feedback feedback) throws WvcmException
doWriteProperties(javax.wvcm.Feedback)
.
feedback
- the properties to be available in the returned proxy,
and any other feedback desired, such as progress indications.
getXyz
method, when a
getXyz
method is defined in the interface.
WvcmException
- if problems encountered communicating with server or
if modified properties cannot be written (see doWriteProperties(javax.wvcm.Feedback)
.void doUnbindAll(Feedback feedback) throws WvcmException
PARENT_LIST
.
See Folder.doUnbindChild(java.lang.String, javax.wvcm.Feedback)
.
WvcmException
Resource doWriteContent(InputStream content, String contentIdentifier, Feedback feedback) throws WvcmException
Postconditions:
content
- if contentIdentifier
matches the current
content identifier of the persistent resource,
the content of the resource is replaced with the
bytes read from content
, and content
is then closed.contentIdentifier
- if this content identifier
does not match
the content identifier of the persistent resource, the persistent
resource is left unaltered, and a WvcmException is thrown.
If reading from the stream throws a java.io.IOException
,
then no further data will be read from the stream,
and after attempting to close the stream, a WvcmException
wrapping the IOException
is thrown,
possibly leading to incomplete data being stored on the resource.
feedback
- Specifies optional feedback to the caller.
WvcmException
- ReasonCode:
WvcmException.ReasonCode.CANNOT_MODIFY_VERSION
:
If this proxy identifies a version, the request MUST fail.
ControllableResource.doCheckin(javax.wvcm.ControllableResource.CheckinFlag[], javax.wvcm.Feedback)
for additional reason codes.Resource doWriteProperties(Feedback feedback) throws WvcmException
updatedPropertyNameList()
on this Resource.
Note that since doWriteProperties returns a new proxy whose properties are
specified in the feedback argument, doWriteProperties is semantically identical
to doReadProperties(javax.wvcm.Feedback)
.
Postconditions:
feedback
- Specifies optional feedback to the caller.
WvcmException
- ReasonCode:
WvcmException.ReasonCode.PROPERTY_OVERWRITE_FORBIDDEN
:
This property has been updated by another client after this proxy was created.
WvcmException.ReasonCode.CANNOT_MODIFY_PROTECTED_PROPERTY
:
Some properties cannot be directly updated.
WvcmException.ReasonCode.CANNOT_MODIFY_VERSION
:
If this proxy identifies a version, the request MUST fail
unless the property is explicitly defined to be modifiable on a
version.
ControllableResource.doCheckin(javax.wvcm.ControllableResource.CheckinFlag[], javax.wvcm.Feedback)
for additional reason codes.void forgetProperty(PropertyNameList.PropertyName<?> name)
doWriteProperties(javax.wvcm.Feedback)
to fail.
name
- the name of the property.String getComment() throws WvcmException
COMMENT
property.
COMMENT
property.
WvcmException
- if this property was not set and
this Resource was not created with
COMMENT
as a wanted property.setComment(java.lang.String)
String getContentCharacterSet() throws WvcmException
CONTENT_CHARACTER_SET
property.
CONTENT_CHARACTER_SET
property.
WvcmException
- if this property was not set and
this Resource was not created with
CONTENT_CHARACTER_SET
as a wanted property.setContentCharacterSet(java.lang.String)
String getContentIdentifier() throws WvcmException
CONTENT_IDENTIFIER
property.
CONTENT_IDENTIFIER
property.
WvcmException
- if this Resource was not created with
CONTENT_IDENTIFIER
as a wanted property.Locale getContentLanguage() throws WvcmException
CONTENT_LANGUAGE
property.
CONTENT_LANGUAGE
property.
WvcmException
- if this property was not set and
this Resource was not created with
CONTENT_LANGUAGE
as a wanted property.setContentLanguage(java.util.Locale)
long getContentLength() throws WvcmException
CONTENT_LENGTH
property.
CONTENT_LENGTH
property.
WvcmException
- if this Resource was not created with
CONTENT_LENGTH
as a wanted property.String getContentType() throws WvcmException
CONTENT_TYPE
property.
A server may refuse to allow the CONTENT_TYPE
of a resource to be changed
after the resource has been created.
CONTENT_TYPE
property.
WvcmException
- if this property was not set and
this Resource was not created with
CONTENT_TYPE
as a wanted property.setContentType(java.lang.String)
Date getCreationDate() throws WvcmException
CREATION_DATE
property.
CREATION_DATE
property.
WvcmException
- if this Resource was not created with
CREATION_DATE
as a wanted propertyString getCreatorDisplayName() throws WvcmException
CREATOR_DISPLAY_NAME
property.
CREATOR_DISPLAY_NAME
property.
WvcmException
- if this property was not set and
this Resource was not created with
CREATOR_DISPLAY_NAME
as a wanted property.setCreatorDisplayName(java.lang.String)
String getDisplayName() throws WvcmException
DISPLAY_NAME
property.
DISPLAY_NAME
property.
WvcmException
- if this property was not set and
this Resource was not created with
DISPLAY_NAME
as a wanted property.setDisplayName(java.lang.String)
Boolean getIsExecutable() throws WvcmException
IS_EXECUTABLE
property.
IS_EXECUTABLE
property.
WvcmException
- if this property was not set and
this Resource was not created with
IS_EXECUTABLE
as a wanted property.setIsExecutable(java.lang.Boolean)
Date getLastModified() throws WvcmException
LAST_MODIFIED
property.
LAST_MODIFIED
property.
WvcmException
- if this Resource was not created with
LAST_MODIFIED
as a wanted property.ResourceList<Folder> getParentList() throws WvcmException
PARENT_LIST
property.
PARENT_LIST
property.
WvcmException
- if this Resource was not created with
PARENT_LIST
as a wanted property.Location getPathnameLocation() throws WvcmException
PATHNAME_LOCATION
property.
PATHNAME_LOCATION
property.
WvcmException
- if this Resource was not created with
PATHNAME_LOCATION
as a wanted property.<T> T getProperty(PropertyNameList.PropertyName<T> name) throws WvcmException
name
- the name of the property.
WvcmException
- if this property was not set and
this Resource was not created with
the specified property as a wanted property.setProperty(javax.wvcm.PropertyNameList.PropertyName, T)
List<String> getProviderList() throws WvcmException
PROVIDER_LIST
property.
PROVIDER_LIST
property.
WvcmException
- if this Resource was not created with
PROVIDER_LIST
as a wanted property.String getResourceIdentifier() throws WvcmException
RESOURCE_IDENTIFIER
property.
RESOURCE_IDENTIFIER
property.
WvcmException
- if this Resource was not created with
RESOURCE_IDENTIFIER
as a wanted property.ResourceList<Folder> getWorkspaceFolderList() throws WvcmException
WORKSPACE_FOLDER_LIST
property.
WORKSPACE_FOLDER_LIST
property.
WvcmException
- if this Resource was not created with
WORKSPACE_FOLDER_LIST
as a wanted property.<T> void initProperty(PropertyNameList.PropertyName<T> name, T value)
doWriteProperties(javax.wvcm.Feedback)
request),
WvcmException
with WvcmException.ReasonCode.CANNOT_OVERWRITE
is thrown and the property of the Resource is not changed.
name
- the name of the property.value
- the value of the specified property.getProperty(javax.wvcm.PropertyNameList.PropertyName)
Location location()
The format of the location string is specific to the repository that stores the persistent resource. A URL, a UNC filename, and an NFS filename are examples of possible formats for a location string.
Object lookupProperty(PropertyNameList.PropertyName<?> name)
name
- the name of the property.
getProperty(javax.wvcm.PropertyNameList.PropertyName)
void modifyLocation(Location location)
PropertyNameList propertyNameList()
ALL_CUSTOM_PROPERTIES
would appear in wantedPropertyRequestList,
but the actual property names would appear in propertyNameList.
In addition, failing to retrieve a property would cause a property
to not appear in propertyNameList,
setting a property would add that property to propertyNameList,
and forgetting or removing a property would remove that property
from propertyNameList.
Provider provider()
Provider
for this Resource.void removeProperty(PropertyNameList.PropertyName<?> name)
name
- the name of the property.void setComment(String comment)
COMMENT
property.
comment
- the new comment to apply to this Resource.getComment()
void setContentCharacterSet(String contentCharacterSet)
CONTENT_CHARACTER_SET
property.
contentCharacterSet
- the content character set for the resource.getContentCharacterSet()
void setContentLanguage(Locale contentLanguage)
CONTENT_LANGUAGE
property.
contentLanguage
- the content language for the resource.getContentLanguage()
void setContentType(String contentType)
CONTENT_TYPE
property.
contentType
- the content type for the resource.getContentType()
void setCreatorDisplayName(String val)
CREATOR_DISPLAY_NAME
property.
val
- the new creator display name to apply to the resource.getCreatorDisplayName()
void setDisplayName(String val)
DISPLAY_NAME
property.
val
- the new display name to apply to the resource.getDisplayName()
void setIsExecutable(Boolean isExecutable)
IS_EXECUTABLE
property.
isExecutable
- whether the resource is executable.getIsExecutable()
<T> void setProperty(PropertyNameList.PropertyName<T> name, T value)
name
- the name of the property.value
- the new value of the specified property.getProperty(javax.wvcm.PropertyNameList.PropertyName)
<V,U extends Collection<V>> void setProperty(PropertyNameList.PropertyName<U> name, U additions, U removals)
name
- the name of the property.additions
- the values to be added to the value of the specified property value.removals
- the values to be removed from the value of the specified property.setProperty(javax.wvcm.PropertyNameList.PropertyName, T)
PropertyNameList updatedPropertyNameList()
|
Generated Wed 19-Nov-2014 10:09 AM | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |