javax.wvcm
Interface Resource

All Known Subinterfaces:

Activity, Baseline, Configuration, ControllableFolder, ControllableResource, Folder, FolderVersion, Version, VersionHistory, Workspace

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();      
 

Method Summary

void	doBind(Location destination, boolean overwrite) Binds the resource identified by this Resource to the location identified by the destination.
void	doCopy(String destination, boolean overwrite) Create a copy of the resource identified by this Resource at the location identified by the destination.
Resource	doReadContent(PropertyNameList wantedPropertyList, 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.
void	doUnbind() Unbinds the resource identified by the locator of this Resource.
void	doWriteContent(InputStream content, String contentIdentifier) Persists content changes to a resource.
void	doWriteProperties() Persists property changes to this Resource.
Object	getAttribute(PropertyNameList.AttributeName name) Return an attribute of this Resource.
String	getComment() Return a comment describing this Resource that is suitable for display to a user.
String	getContentCharacterSet() Return a description of the character set of the resource content (see RFC2278).
String	getContentIdentifier() Return an implementation-defined String that identifies the persistent state of the resource.
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.
String	getContentType() Return a description of the media-type of the resource content.
Date	getCreationDate() Return the date that the resource was originally created.
String	getCreatorDisplayName() Return a description of the user that created the resource, in a format that is suitable for display to an end user.
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.
Date	getLastModified() Return the date the content of the resource was last modified.
List	getParentBindingList() Return the list of bindings to this resource.
PropertyNameList	getPropertyNameList(boolean onlyAttributes) Return the list of names of properties available on this Resource.
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.
String	getResourceIdentifier() Return a unique identifier for this 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.
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, Object value) Adds or replaces the value of the specified attribute of this Resource.
void	setComment(String comment) Adds or replaces the comment string of this Resource.
void	setContentCharacterSet(String contentCharacterSet) Sets the content character set of the resource.
void	setContentLanguage(Locale contentLanguage) Sets the content language of the resource.
void	setContentType(String contentType) Sets the content type of the resource.
void	setCreatorDisplayName(String val) Adds or replaces the creator display name string of the resource.
void	setDisplayName(String val) Adds or replaces the display name string of the resource.

Method Detail

location

public Location location()

Return the location of the persistent resource for which this 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.

getPropertyNameList

public PropertyNameList getPropertyNameList(boolean onlyAttributes)
                                     throws WvcmException

Return the list of names of properties available on this Resource.

Parameters:

onlyAttributes - Only return the names of attributes.

WvcmException

doReadProperties

public Resource doReadProperties(PropertyNameList wantedPropertyList)
                          throws WvcmException

Return a 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

getUpdatedPropertyList

public PropertyNameList getUpdatedPropertyList()
                                        throws WvcmException

Return the names of properties that have been updated in the proxy, but the updates have not yet been successfully applied to the resource.

WvcmException

doWriteProperties

public void doWriteProperties()
                       throws WvcmException

Persists property changes to this Resource.

WvcmException

doReadContent

public Resource doReadContent(PropertyNameList wantedPropertyList,
                              OutputStream content)
                       throws WvcmException

Return a resource containing the wanted properties. A requested property named XXX can be retrieved from the resource with the 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

doWriteContent

public void doWriteContent(InputStream content,
                           String contentIdentifier)
                    throws WvcmException

Persists content changes to a resource.

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.

Throws:

WvcmException - if the resource identified by this Resource does not exist.

WvcmException - Preconditions:
(cannot-modify-controlled-content): If this ControllableResource identifies a resource whose IsCheckedOut property is false, the request MUST fail.
(cannot-modify-version): If this proxy identifies a version, the request MUST fail.

doCopy

public void doCopy(String destination,
                   boolean overwrite)
            throws WvcmException

Create a copy of the resource identified by this 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.

Parameters:

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.

Throws:

WvcmException - Preconditions:
(can-overwrite): If there already is a resource at the destination, overwrite MUST be true.
(cannot-copy-folder-version): This proxy MUST NOT identify a folder version.
(cannot-copy-history): If this proxy identifies a version history, the request MUST fail. In order to create another version history whose versions have the same content, the appropriate sequence of doControl, doCheckout, doWriteContent, and doCheckin requests must be made.

WvcmException - Postconditions:
(must-not-copy-property): A property defined by this document MUST NOT have been copied to the new resource created by this request, but instead that property of the new resource MUST have the default initial value it would have had if the new resource had been created by doCreateResource.
(copy-creates-new-resource): If the source of a doCopy is a controlled resource, and if there is no resource at the destination of the doCopy, then the doCopy creates a new uncontrolled resource at the destination of the doCopy.
(copy-creates-new-resource): If this proxy identifies a version, and if there is no resource at the destination of the doCopy, then the doCopy creates a new uncontrolled resource at the destination of the doCopy.

doUnbind

public void doUnbind()
              throws WvcmException

Unbinds the resource identified by the locator of this 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.

Throws:

WvcmException - Preconditions:
(cannot-modify-checked-in-parent): If this Resource identifies a controlled resource, the doUnbind MUST fail when the folder containing the controlled resource is a checked-in controlled folder.
(no-version-unbind): A server MAY fail an attempt to apply doUnbind to a version.

WvcmException - Postconditions:
(resource-unbound): There is no resource at the location identified by this Resource.
(unbind-activity-reference): If an activity is unbound, any reference to that activity in an ActivityList, SubactivityList, or CurrentActivityList MUST be removed.
(update-predecessor-list): If a version was unbound, the server MUST have replaced any reference to that version in a PredecessorList by a copy of the PredecessorList of the unbound version.
(version-history-has-root): If the request unbound the root version of a version history, the request MUST have updated the RootVersion of the version history to refer to another version that is an ancestor of all other remaining versions in that version history. A result of this postcondition is that every version history will have at least one version, and the only way to delete all versions is to unbind the version history resource.
(delete-version-reference): If a version is unbound, any reference to that version in a MergeList or AutoMergeList property MUST be removed.
(delete-version-set): If the request unbound a version history, the request MUST have unbound all versions in the VersionList of that version history, and MUST have satisfied the postconditions for version deletion.

doRebind

public void doRebind(Location destination,
                     boolean overwrite)
              throws WvcmException

Unbinds the resource identified by this 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.

Parameters:

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.

Throws:

WvcmException - Preconditions:
(can-overwrite): If there already is a resource at the destination, overwrite MUST be true.
(cannot-modify-checked-in-parent): If this ControllableResource is a controlled resource, the request MUST fail when the folder containing this ControllableResource is a checked-in controlled folder.
(cannot-modify-destination-checked-in-parent): If this ControllableResource is a controlled resource, the request MUST fail when the folder containing the destination location is a checked-in controlled folder.
(cannot-rename-history): This proxy MUST NOT identify a version history.
(cannot-rename-version): If this proxy identifies a version, the request MUST fail.

WvcmException - Postconditions:
(preserve-properties): The property values of the resource identified by this Resource MUST NOT have been modified by the doRebind request unless this specification states otherwise.
(workspace-member-moved): If this Resource did not identify a workspace, the Workspace property MUST have been updated to have the same value as the Workspace of its parent folder at the destination location.
(workspace-moved): If this proxy identified a workspace, any reference to that workspace in a Workspace property MUST have been updated to refer to the new location of that workspace.
(update-checked-out-reference): If a checked-out resource is moved, any reference to that resource in a ActivityCheckoutList property MUST be updated to refer to the new location of that resource.
(update-workspace-reference): If this proxy identifies a workspace, any reference to that workspace in a CurrentWorkspaceList property MUST be updated to refer to the new location of that workspace.
(update-activity-reference): If this proxy identifies an activity, any reference to that activity in a ActivityList, SubactivityList, or CurrentActivityList MUST be updated to refer to the new location of that activity.

doBind

public void doBind(Location destination,
                   boolean overwrite)
            throws WvcmException

Binds the resource identified by this Resource to the location identified by the destination. The content and properties of a resource are not modified by doBind.

Parameters:

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.

Throws:

WvcmException - Preconditions:
(cannot-modify-destination-checked-in-parent): If this Resource is a controlled resource, the request MUST fail when the folder containing the destination location is a checked-in controlled folder.
(binding-allowed): This Resource supports multiple bindings to it.
(cross-server-binding): If this Resource is on another server from the folder that contains the destination, the destination server MUST support cross-server bindings.
(can-overwrite): If there already is a resource at the destination, overwrite MUST be true.
(cycle-allowed): If this Resource is a folder, and the folder that contains the destination is a member of this Resource, then the server MUST support cycles in the location namespace.

WvcmException - Postconditions:
(preserve-properties): The property values of the resource identified by this Resource MUST NOT have been modified by the doBind request unless this specification states otherwise.
(new-binding): The destination MUST identify the resource identified by this Resource.

getComment

public String getComment()
                            throws WvcmException

Return a comment describing this Resource that is suitable for display to a user.

Throws:

WvcmException - if this Resource was not created with COMMENT as a wanted property.

setComment

public void setComment(String comment)

Adds or replaces the comment string of this Resource.

Parameters:

comment - The new comment to apply to this Resource.

getContentIdentifier

public String getContentIdentifier()
                                      throws WvcmException

Return an implementation-defined 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).

Throws:

WvcmException - if this Resource was not created with CONTENT_IDENTIFIER as a wanted property.

getContentLanguage

public Locale getContentLanguage()
                                    throws WvcmException

Return a description of the natural language used in the resource content. The format of the description is an ISO 3316 language string followed by an optional underscore and ISO 639 country code (see RFC1766).

Throws:

WvcmException - if this Resource was not created with COMMENT as a wanted property.

setContentLanguage

public void setContentLanguage(Locale contentLanguage)

Sets the content language of the resource.

getContentLength

public long getContentLength()
                      throws WvcmException

Return the content length as an integer number of bytes.

Throws:

WvcmException - if this Resource was not created with CONTENT_LENGTH as a wanted property

getContentType

public String getContentType()
                                throws WvcmException

Return a description of the media-type of the resource content. The format is a MIME type string (see RFC1590).

Throws:

WvcmException - if this Resource was not created with CONTENT_TYPE as a wanted property.

setContentType

public void setContentType(String contentType)

Sets the content type of the resource.

Parameters:

contentType - The content type for the resource.

getContentCharacterSet

public String getContentCharacterSet()
                                        throws WvcmException

Return a description of the character set of the resource content (see RFC2278).

Throws:

WvcmException - if this Resource was not created with CONTENT_CHARACTER_SET as a wanted property.

setContentCharacterSet

public void setContentCharacterSet(String contentCharacterSet)

Sets the content character set of the resource.

Parameters:

contentCharacterSet - The content character set for the resource.

getCreationDate

public Date getCreationDate()
                               throws WvcmException

Return the date that the resource was originally created.

Throws:

WvcmException - if this Resource was not created with CREATION_DATE as a wanted property

getCreatorDisplayName

public String getCreatorDisplayName()
                                       throws WvcmException

Return a description of the user that created the resource, in a format that is suitable for display to an end user.

Throws:

WvcmException - if this Resource was not created with CREATOR_DISPLAY_NAME as a wanted property.

setCreatorDisplayName

public void setCreatorDisplayName(String val)

Adds or replaces the creator display name string of the resource.

getDisplayName

public String getDisplayName()
                                throws WvcmException

Return a short description of the resource, in a format that is suitable for display to an end user in a tree display.

Throws:

WvcmException - if this Resource was not created with DISPLAY_NAME as a wanted property.

setDisplayName

public void setDisplayName(String val)

Adds or replaces the display name string of the resource.

getLastModified

public Date getLastModified()
                               throws WvcmException

Return the date the content of the resource was last modified.

Throws:

WvcmException - if this Resource was not created with LAST_MODIFIED as a wanted property.

getWorkspaceFolderList

public List getWorkspaceFolderList()
                                      throws WvcmException

Return a list of Folder objects that identify folders that contain workspaces.

Throws:

WvcmException - if this Resource was not created with WORKSPACE_FOLDER_LIST as a wanted property.

getAttribute

public Object getAttribute(PropertyNameList.AttributeName name)
                              throws WvcmException

Return an attribute of this Resource.

Parameters:

name - The name of the attribute.

Throws:

WvcmException - if this Resource was not created with either ALL_ATTRIBUTES or the specified attribute as a wanted property.

setAttribute

public void setAttribute(PropertyNameList.AttributeName name,
                         Object value)

Adds or replaces the value of the specified attribute of this Resource.

Parameters:

name - The name of the attribute.

value - The new value of the specified attribute.

removeAttribute

public void removeAttribute(PropertyNameList.AttributeName name)

Removes the specified attribute of this Resource.

Parameters:

name - The name of the attribute.

getProviderList

public List getProviderList()
                               throws WvcmException

Return a list of String objects that identify the names of providers for this resource, with the preferred providers specified earlier in the list.

Throws:

WvcmException - if this Resource was not created with PROVIDER_LIST as a wanted property.

getResourceIdentifier

public String getResourceIdentifier()
                                       throws WvcmException

Return a unique identifier for this Resource. The resource identifier enables clients to determine whether two bindings are to the same resource. The value of this property is a URI, and may use any registered URI scheme that guarantees the uniqueness of the value across all resources for all time.

Throws:

WvcmException - if this Resource was not created with RESOURCE_IDENTIFIER as a wanted property.

getParentBindingList

public List getParentBindingList()
                                    throws WvcmException

Return the list of bindings to this resource. The ParentBindingList property enables clients to discover what folders contain a binding to this resource (i.e. what folders have this resource as a bound member). The returned list contains Folder.Binding instances.

Throws:

WvcmException - if this Resource was not created with PARENT_BINDING_LIST as a wanted property.