|
|||||||||
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, used to retrieve information from the resource and to perform operations on the resource. A resource has both properties, which are named values whose semantics are specified by the API, as well as "attributes" whose names are arbitrary strings selected by the client. An attribute also has a namespace which allows different clients to use simple attribute names without conflicting with each other. An attribute is called a "dead property" in RFC 2518.
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.
Methods whose name begin with the prefix "do", as in "doCheckin",
are redirected by the proxy to the persistent resource
(all other methods operate just on the proxy itself).
The state of the proxy itself is not modified by a "do" method.
In particular, if the request resulted in a change to any of the
property values of the persistent resource of the proxy, those
changes are not reflected in the proxy, but must be obtained
in a new proxy by a subsequent doReadProperties(javax.wvcm.PropertyNameList)
request.
The "do" methods can be expected to send and receive
messages over the network to the remote server that maintains
the persistent resource.
Methods whose name begin with "get" return the value of properties
that were requested as a wanted property when the proxy was created.
If a caller attempts to get the value of a property from a proxy
that was not created with that property as a "wanted property",
then a WvcmException
is thrown with a reason code
of WvcmException.VALUE_UNAVAILABLE
.
If a wanted property could not be retrieved from the server,
then the "get" method will throw a WvcmException
with an appropriate response code and condition failure value.
Methods whose name begin with "set" (for example
r.setXxx(newValue)
), update the value of a
proxy property, mark that property as "updated", and subsequent
requests to "get" that property value from that proxy
(for example, r.getXxx()
) will return the new value.
These updates are accumulated by a proxy,
until a "doXxx" method is applied to the proxy, at which time
the property updates are sent along with the "doXxx" method
to be applied to the persistent resource. If the property
updates succeed on the server, the "update flags" are cleared
on the proxy.
For the "doCreateXxx" methods that create new persistent resources,
the property updates are applied after the persistent resource
is created.
For all other "doXxx" methods, the property updates are applied
before the "doXxx" method is applied, and the "doXxx" method
is only attempted if the property updates are successful.
An "attribute" is a user or client defined property. In order to prevent property name collisions between different clients, an attribute is identified by both a name and a namespace.
As an example of getting and setting a property value on a
persistent resource, the following example appends some text
to the comment
property of a resource:
Provider myProvider = createProvider("com.myprovider.wvcm", null); PropertyNameList wantComment = new PropertyNameList(new PropertyName[] { PropertyName.COMMENT }); Resource myResource = myProvider.location("/my/resource/loc").resource().doReadProperties(wantComment); String comment = myResource.getComment(); myResource.setComment(comment + "addition to comment"); myResource.doWriteProperties();
Nested Class Summary | |
---|---|
static class |
Resource.GenericResourceImpl
NOT YET STANDARD Implementation of a generic Resource. |
Method Summary | |
---|---|
void |
doBind(Location destination,
boolean overwrite)
Binds the resource identified by this Resource
to the location identified by the destination . |
void |
doCopy(java.lang.String destination,
boolean overwrite)
Create a copy of the resource identified by this Resource
at the location identified by the destination . |
void |
doLock(LockToken.Timeout timeout,
boolean deep)
NOT YET STANDARD Locks this resource. |
void |
doLock(LockToken.Timeout timeout,
boolean deep,
boolean exclusive,
java.lang.String owner)
NOT YET STANDARD Locks this resource. |
java.util.List |
doReadAccessControlList(boolean includeInherited)
NOT YET STANDARD Return the list of AccessControlElement instances (ACL) defined
on this resource. |
Resource |
doReadContent(PropertyNameList wantedPropertyList,
java.io.OutputStream content)
Return a resource containing the wanted properties. |
Resource |
doReadProperties(PropertyNameList wantedPropertyList)
Return a Resource containing the wanted properties. |
void |
doRebind(Location destination,
boolean overwrite)
Unbinds the resource identified by this Resource
from its current location and binds it
to the location identified by the destination . |
java.util.List |
doSearch(PropertyNameList wantedPropertyList,
SearchToken searchToken)
NOT YET STANDARD !!! |
void |
doUnbind()
Unbinds the resource identified by the locator of this Resource . |
void |
doUnlock()
NOT YET STANDARD Releases the active lock of this resource. |
void |
doUnlock(LockToken lockToken)
NOT YET STANDARD Releases the specified lock of this resource. |
void |
doWriteAccessControlList(java.util.List acl)
NOT YET STANDARD Modifies the access control list (ACL) of this resource. |
void |
doWriteContent(java.io.InputStream content,
java.lang.String contentIdentifier)
Persists content changes to a resource. |
void |
doWriteProperties()
Persists property changes to this Resource . |
java.lang.Object |
getAttribute(PropertyNameList.AttributeName name)
Return an attribute of this Resource . |
java.lang.String |
getComment()
Return a comment describing this Resource
that is suitable for display to a user. |
java.lang.String |
getContentCharacterSet()
Return a description of the character set of the resource content (see RFC2278). |
java.lang.String |
getContentIdentifier()
Return an implementation-defined String
that identifies the persistent state of the resource. |
java.util.Locale |
getContentLanguage()
Return a description of the natural language used in the resource content. |
long |
getContentLength()
Return the content length as an integer number of bytes. |
java.lang.String |
getContentType()
Return a description of the media-type of the resource content. |
java.util.Date |
getCreationDate()
Return the date that the resource was originally created. |
Principal |
getCreationUser()
NOT YET STANDARD Return the principal that originally created the resource. |
java.lang.String |
getCreatorDisplayName()
Return a description of the user that created the resource, in a format that is suitable for display to an end user. |
java.lang.String |
getDisplayName()
Return a short description of the resource, in a format that is suitable for display to an end user in a tree display. |
java.util.Date |
getLastModified()
Return the date the content of the resource was last modified. |
java.util.List |
getLockTokens()
NOT YET STANDARD Returns the list of lock tokens available at this resource. |
java.util.Date |
getModificationDate()
NOT YET STANDARD Return the date that the resource was modified. |
Principal |
getModificationUser()
NOT YET STANDARD Return the principal that modified the resource. |
Principal |
getOwner()
NOT YET STANDARD Get the owner of this resource |
java.util.List |
getParentBindingList()
Return the list of bindings to this resource. |
java.util.List |
getPrincipalFolderList()
NOT YET STANDARD Return a list of Folder objects that identify folders
that contain principals. |
java.util.List |
getPrivilegeFolderList()
NOT YET STANDARD Return a list of Folder objects that identify folders
that contain privileges. |
java.lang.Object |
getProperty(PropertyNameList.PropertyName name)
NOT YET STANDARD !!! |
PropertyNameList |
getPropertyNameList(boolean onlyAttributes)
Return the list of names of properties available on this Resource . |
java.util.List |
getProviderList()
Return a list of String objects that identify the names of providers for this resource, with the preferred providers specified earlier in the list. |
java.lang.String |
getResourceIdentifier()
Return a unique identifier for this Resource. |
java.util.List |
getSupportedPrivilegeList()
NOT YET STANDARD Return a list of AccessControlElement.Privilege objects defined for the resource. |
PropertyNameList |
getUpdatedPropertyList()
Return the names of properties that have been updated in the proxy, but the updates have not yet been successfully applied to the resource. |
java.util.List |
getWorkspaceFolderList()
Return a list of Folder objects that identify folders
that contain workspaces. |
Location |
location()
Return the location of the persistent resource for which this Resource is a proxy. |
void |
removeAttribute(PropertyNameList.AttributeName name)
Removes the specified attribute of this Resource . |
void |
setAttribute(PropertyNameList.AttributeName name,
java.lang.Object value)
Adds or replaces the value of the specified attribute of this Resource . |
void |
setComment(java.lang.String comment)
Adds or replaces the comment string of this Resource . |
void |
setContentCharacterSet(java.lang.String contentCharacterSet)
Sets the content character set of the resource. |
void |
setContentLanguage(java.util.Locale contentLanguage)
Sets the content language of the resource. |
void |
setContentType(java.lang.String contentType)
Sets the content type of the resource. |
void |
setCreatorDisplayName(java.lang.String val)
Adds or replaces the creator display name string of the resource. |
void |
setDisplayName(java.lang.String val)
Adds or replaces the display name string of the resource. |
void |
setProperty(PropertyNameList.PropertyName name,
java.lang.Object value)
NOT YET STANDARD !!! |
Method Detail |
---|
Location location()
Resource
is a proxy.
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.
PropertyNameList getPropertyNameList(boolean onlyAttributes) throws WvcmException
Resource
.
onlyAttributes
- Only return the names of attributes.
WvcmException
Resource doReadProperties(PropertyNameList wantedPropertyList) throws WvcmException
Resource
containing the wanted properties.
If the property state is being maintained on both the
client and the server, and if ControllableResource.getServerState()
returns a non-NULL value, the client value is returned.
A requested property named XXX can be retrieved from
the resource with the getXxx
method.
WvcmException
PropertyNameList getUpdatedPropertyList() throws WvcmException
WvcmException
void doWriteProperties() throws WvcmException
Resource
.
WvcmException
Resource doReadContent(PropertyNameList wantedPropertyList, java.io.OutputStream content) throws WvcmException
getXxx
method.
The resource content is written to content
and content
is closed.
If state is being maintained on both the
client and the server, the client state is retrieved.
WvcmException
void doWriteContent(java.io.InputStream content, java.lang.String contentIdentifier) throws WvcmException
If content for a resource is being maintained persistently on both the client and the server, only the client copy of the content is updated.
If contentIdentifier
matches the current
state identifier of the persistent resource,
the content of the resource is replaced with the
bytes read from content
, and content
is then closed.
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
will be thrown,
possibly leading to incomplete data being stored on the resource.
WvcmException
- if the resource identified by this Resource
does not exist.
WvcmException
- Preconditions:
void doCopy(java.lang.String destination, boolean overwrite) throws WvcmException
Resource
at the location identified by the 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.
destination
- The location of the new resource created by doCopy.overwrite
- If false
the existence of a resource
at the destination will cause the copy to fail; otherwise,
doCopy will replace the destination resource.
WvcmException
- Preconditions:
overwrite
MUST be true
.
WvcmException
- Postconditions:
void doUnbind() throws WvcmException
Resource
.
The deletion of a resource only guarantees that the resource
is no longer accessible at the specified location; it does
not affect its accessibility at other locations.
If a folder is unbound, no resource is accessible at any
location that has the location of the unbound folder as its prefix.
WvcmException
- Preconditions:
WvcmException
- Postconditions:
void doRebind(Location destination, boolean overwrite) throws WvcmException
Resource
from its current location and binds it
to the location identified by the destination
.
The content and properties of a resource are not modified
by doRebind, except for the properties that are location dependent.
destination
- The new location of the resource.overwrite
- If false
the existence of a resource
at the destination will cause doRebind to fail; otherwise,
doRebind will replace the destination resource.
WvcmException
- Preconditions:
overwrite
MUST be true
.
WvcmException
- Postconditions:
void doBind(Location destination, boolean overwrite) throws WvcmException
Resource
to the location identified by the destination
.
The content and properties of a resource are not modified
by doBind.
destination
- The location of the new binding to the resource.overwrite
- If false
the existence of a resource
at the destination will cause doBind to fail; otherwise,
doBind will first unbind the existing resource at the destination.
WvcmException
- Preconditions:
overwrite
MUST be true
.
WvcmException
- Postconditions:
java.lang.String getComment() throws WvcmException
Resource
that is suitable for display to a user.
WvcmException
- if this Resource
was not created with
COMMENT
as a wanted property.void setComment(java.lang.String comment)
Resource
.
comment
- The new comment to apply to this Resource
.java.lang.String getContentIdentifier() throws WvcmException
String
that identifies the persistent state of the resource.
The semantics of a ContentIdentifier is similar to that
of an HTTP ETag (see RFC-2616).
WvcmException
- if this Resource
was not created with
CONTENT_IDENTIFIER
as a wanted property.java.util.Locale getContentLanguage() throws WvcmException
WvcmException
- if this Resource
was not created with
CONTENT_LANGUAGE
as a wanted property.void setContentLanguage(java.util.Locale contentLanguage)
contentLanguage
- The content language for the resource.long getContentLength() throws WvcmException
WvcmException
- if this Resource
was not created with
CONTENT_LENGTH
as a wanted propertyjava.lang.String getContentType() throws WvcmException
WvcmException
- if this Resource
was not created with
CONTENT_TYPE
as a wanted property.void setContentType(java.lang.String contentType)
contentType
- The content type for the resource.java.lang.String getContentCharacterSet() throws WvcmException
WvcmException
- if this Resource
was not created with
CONTENT_CHARACTER_SET
as a wanted property.void setContentCharacterSet(java.lang.String contentCharacterSet)
contentCharacterSet
- The content character set for the resource.java.util.Date getCreationDate() throws WvcmException
WvcmException
- if this Resource
was not created with
CREATION_DATE as a wanted propertyjava.util.Date getModificationDate() throws WvcmException
WvcmException
- if this Resource
was not created with
MODIFICATION_DATE as a wanted propertyPrincipal getCreationUser() throws WvcmException
WvcmException
- if this Resource
was not created with
CREATION_USER as a wanted propertyPrincipal getModificationUser() throws WvcmException
WvcmException
- if this Resource
was not created with
MODIFICATION_USER as a wanted propertyjava.lang.String getCreatorDisplayName() throws WvcmException
WvcmException
- if this Resource
was not created with
CREATOR_DISPLAY_NAME
as a wanted property.void setCreatorDisplayName(java.lang.String val)
val
- The new creator display name to apply to the resource.java.lang.String getDisplayName() throws WvcmException
WvcmException
- if this Resource
was not created with
DISPLAY_NAME
as a wanted property.void setDisplayName(java.lang.String val)
val
- The new display name to apply to the resource.java.util.Date getLastModified() throws WvcmException
WvcmException
- if this Resource
was not created with
LAST_MODIFIED
as a wanted property.java.util.List getWorkspaceFolderList() throws WvcmException
Folder
objects that identify folders
that contain workspaces.
WvcmException
- if this Resource
was not created with
WORKSPACE_FOLDER_LIST
as a wanted property.java.lang.Object getAttribute(PropertyNameList.AttributeName name) throws WvcmException
Resource
.
name
- The name of the attribute.
WvcmException
- if this Resource
was not created with
the specified attribute as a wanted property.void setAttribute(PropertyNameList.AttributeName name, java.lang.Object value)
Resource
.
name
- The name of the attribute.value
- The new value of the specified attribute.void removeAttribute(PropertyNameList.AttributeName name)
Resource
.
name
- The name of the attribute.java.util.List getProviderList() throws WvcmException
WvcmException
- if this Resource
was not created with
PROVIDER_LIST
as a wanted property.java.lang.String getResourceIdentifier() throws WvcmException
WvcmException
- if this Resource
was not created with
RESOURCE_IDENTIFIER
as a wanted property.java.util.List getParentBindingList() throws WvcmException
Folder.Binding
instances.
WvcmException
- if this Resource
was not created with
PARENT_BINDING_LIST
as a wanted property.java.lang.Object getProperty(PropertyNameList.PropertyName name) throws WvcmException
Resource
.
WvcmException
void setProperty(PropertyNameList.PropertyName name, java.lang.Object value)
Resource
.
java.util.List doSearch(PropertyNameList wantedPropertyList, SearchToken searchToken) throws WvcmException
Resource
objects containing the wanted properties
according to the conditions of the specified searct token from the scope
defined by this Resource
.
A requested property named XXX can be retrieved from
the resource with the getXxx
method.
WvcmException
Principal getOwner() throws WvcmException
WvcmException
- if this Resource
was not created with
OWNER
as a wanted property.java.util.List getPrincipalFolderList() throws WvcmException
Folder
objects that identify folders
that contain principals.
WvcmException
- if this Resource
was not created with
PRINCIPAL_FOLDER_LIST
as a wanted property.java.util.List getPrivilegeFolderList() throws WvcmException
Folder
objects that identify folders
that contain privileges.
WvcmException
- if this Resource
was not created with
PRIVILEGE_FOLDER_LIST
as a wanted property.java.util.List getSupportedPrivilegeList() throws WvcmException
AccessControlElement.Privilege
objects defined for the resource.
WvcmException
- if this Resource
was not created with
SUPPORTED_PRIVILEGE_LIST
as a wanted property.java.util.List doReadAccessControlList(boolean includeInherited) throws WvcmException
AccessControlElement
instances (ACL) defined
on this resource.
The ACL specifies the list of access control elements (ACEs), which define what principals
are to get what privileges for this resource.
Each ACE specifies the set of privileges to be either granted or denied to a single principal.
If the ACL is empty, no principal is granted any privilege.
includeInherited
- if false, only ACEs defined for the resource are returned;
otherwise, the ACL includes all inherited ACEs
WvcmException
void doWriteAccessControlList(java.util.List acl) throws WvcmException
acl
- a list of AccessControlElement
instances
WvcmException
void doLock(LockToken.Timeout timeout, boolean deep) throws WvcmException
timeout
- a Timeoutdeep
- a boolean
WvcmException
void doLock(LockToken.Timeout timeout, boolean deep, boolean exclusive, java.lang.String owner) throws WvcmException
timeout
- a Timeoutdeep
- a booleanexclusive
- a booleanowner
- a String
WvcmException
void doUnlock() throws WvcmException
WvcmException
void doUnlock(LockToken lockToken) throws WvcmException
lockToken
- a LockToken
WvcmException
java.util.List getLockTokens() throws WvcmException
WvcmException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |