|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.webdav.client.AbstractResourceHandle
public abstract class AbstractResourceHandle
The AbstractResourceHandle
class is the abstract
superclass for all types of resource references. A resource
handle is a client-side 'proxy' for the server resource. Instances
of handle classes understand the methods appropriate for the
corresponding server resource and provide a convenient high-level
API for sending WebDAV methods to the server to manipulate
the resource.
It is certainly posible to create a stale or invalid handle in numerous ways. For example, the existance of a handle does not imply the existance of a corresponding server resource (indeed resource can be created by sending create() to a handle, or deleted using delete() -- so the life cycles are not coupled. It is also possible to create, say, a collection handle on a regular resource and invoke invalid WebDAV methods. These will typically result in an exception.
The API on these classes are intended to convenience methods for
the most common operations on server resources. They make some
assumptions about the way you want to receive the results. To
get finer (but possibly less convenient) control over the WebDAV
methods use the Server
interface of DAVClient
directly.
Field Summary | |
---|---|
protected DAVClient |
davClient
|
protected ILocator |
locator
|
Fields inherited from interface org.eclipse.webdav.internal.kernel.WebDAVPropertyValues |
---|
DAV_ACTIVITY_RESOURCE_TYPE, DAV_BASELINE_RESOURCE_TYPE, DAV_COLLECTION_RESOURCE_TYPE, DAV_DISCOURAGED, DAV_FORBIDDEN, DAV_HISTORY_RESOURCE_TYPE, DAV_KEEP_CHECKED_OUT, DAV_LOCKED_UPDATE, DAV_NEW_VERSION, DAV_OK, DAV_OVERWRITE, DAV_UNLOCKED_UPDATE, DAV_VERSION_HISTORY_RESOURCE_TYPE, DAV_WORKSPACE_RESOURCE_TYPE |
Fields inherited from interface org.eclipse.webdav.internal.kernel.WebDAVConstants |
---|
DAV_URI |
Constructor Summary | |
---|---|
AbstractResourceHandle(DAVClient davClient,
ILocator locator)
Creates a new AbstractResourceHandle with the given
DAV client and Locator . |
Method Summary | |
---|---|
CollectionHandle |
asCollectionHandle()
Answer a new collection handle on the same underlying server resource. |
ResourceHandle |
asResourceHandle()
Answer a new resource handle on the same underlying server resource. |
boolean |
canTalkDAV()
Return a boolean value indicating whether or not the server for this resource is DAV compliant. |
ResourceHandle |
checkIn()
Check-in this resource. |
abstract AbstractResourceHandle |
checkOut()
Check out this resource. |
protected void |
closeResponse(IResponse response)
Helper method to close a response from the server. |
void |
copy(ILocator destination)
Make a copy of this resource and place it at the location defined by the given locator. |
void |
copy(ILocator destination,
String depth,
boolean overwrite,
Collection propertyNames)
Make a copy of this resource and place it at the location specified by the given destination locator. |
abstract void |
create()
Create this resource in the repository. |
void |
delete()
Delete this resource from the repository. |
void |
delete(boolean mustExist)
Delete this resource from the repository, optionally succeeding in the delete if the resource was not found on the server. |
boolean |
equals(Object obj)
Answers true iff the receiver and the argument are considered equal, otherwise answers false. |
protected void |
examineMultiStatusResponse(IResponse response)
If the given response contains a multistatus body, the bodies status' are checked for errors. |
protected void |
examineResponse(IResponse response)
Check the status code of the given response and throw a WebDAV exception if the code indicates failure. |
protected void |
examineStatusCode(int code,
String message)
Check the given status code and throw a WebDAV exception if the code indicates failure. |
boolean |
exists()
Return a boolean value indicating whether or not this resource exists on the server. |
protected URLTable |
extractPropStats(MultiStatus multiStatus)
Helper method to extract the property status response from a multi status reponse, and populate a URLTable with the results. |
ResponseInputStream |
getContent()
Return the content of this resource as an input stream. |
DAVClient |
getDAVClient()
Answer the DAVClient being used by this resource handle for accessing the resource. |
ILocator |
getLocator()
Return the locator for this resource. |
Enumeration |
getLocks()
Return an Enumeration over ActiveLocks which lists the locks currently held on this resource. |
CollectionHandle |
getParent()
Returns a collection handle for the parent of this resource. |
URLTable |
getProperties(Collection propertyNames,
String depth)
Fetches and returns the specified properties for this resource and its children to the given depth. |
URLTable |
getProperties(String depth)
Return a URLTable which contains all of this resources
properties to the given depth. |
PropertyStatus |
getProperty(QualifiedName propertyName)
Return the property status for the property with the given name. |
URLTable |
getPropertyNames(String depth)
Fetch and return the property names for the resource, and the children resources to the specified depth. |
URLTable |
getVersionTree()
Retrieve the version tree infomration for the receiver, assuming that the receiver is a version or a version-controlled resource. |
CollectionHandle[] |
getWorkspaceCollections()
|
int |
hashCode()
Answers the hashcode of the receiver as defined by Object#hashCode() . |
IContext |
head()
Return the header from a message send to the server. |
boolean |
isCheckedIn()
Check to see if the resource is checked in (i.e., is an immutable resource). |
boolean |
isCheckedOut()
Check to see if the resource is checked-out. |
boolean |
isCollection()
Return a boolean value indicating whether or not this resource is a collection. |
boolean |
isLocked()
Return a boolean value indicating whether or not this resource is currently locked. |
boolean |
isVersion()
Check to see if the resource is a version. |
boolean |
isVersionControlled()
Check to see if the resource is under version control. |
boolean |
isWorkingResource()
Check to see if the resource is a working resource. |
LockToken |
lock()
Lock this resource with default values. |
LockToken |
lock(boolean isShared,
String depth,
int timeout,
String owner)
Lock this resource using the specified parameters. |
void |
move(ILocator destination)
Move this resource to the destination specified by the given locator. |
void |
move(ILocator destination,
boolean overwrite,
Enumeration names)
Move this resource to the location specified by the given locator. |
protected IContext |
newContext()
Answer a new empty context for requests sent to the receivers server. |
protected Document |
newDocument()
Answer a new empty DOM Document suitable for creating requests to the receiver's server. |
protected boolean |
propertyHasChild(QualifiedName propertyName,
QualifiedName childName)
This is a helper method to check to see if the resource has a property with the given name that in turn has a child with a given name. |
protected ILocator |
protectedCheckIn()
Check in the receiver and answer a new Locator on the resulting version resource. |
protected ILocator |
protectedCheckOut()
Check out the receiver and answer a new Locator on the resulting checked out resource. |
void |
refreshLock(LockToken lockToken,
int timeout)
Refresh the lock on this resource with the given lock token. |
void |
removeProperties(Collection propertyNames)
Remove the properties with the given names, from this resource. |
void |
removeProperty(QualifiedName propertyName)
Remove the property with the given name from this resource. |
void |
setContent(InputStream input)
Set the content of this resource to be the untyped data stored in the given input stream. |
void |
setContent(String contentType,
InputStream input)
Set the content of this resource to be the data stored in the given input stream. |
void |
setProperties(Collection properties)
Set the given properties on this resource. |
void |
setProperty(Element property)
Set the given property on this resource. |
boolean |
supportsLiveProperty(QualifiedName propertyName)
Check to see if the resource supports the named live property. |
String |
toString()
Return a string representation of this resource. |
ResponseInputStream |
trace()
Send a message to the server. |
void |
unlock(LockToken token)
Unlock this resource with the given lock token. |
void |
update(ILocator version)
Perform an UPDATE on the receiver to set the version it is based upon. |
void |
versionControl()
Bring the receiver under version control. |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
protected DAVClient davClient
protected ILocator locator
Constructor Detail |
---|
public AbstractResourceHandle(DAVClient davClient, ILocator locator)
AbstractResourceHandle
with the given
DAV client and Locator
.
davClient
- the DAVClient
that contains the server
reference and proxy/authentication information.locator
- the Locator
identity of the resource.Method Detail |
---|
public CollectionHandle asCollectionHandle()
public ResourceHandle asResourceHandle()
public boolean canTalkDAV() throws DAVException
true
if the server can respond to DAV
requests, or false
otherwise.
DAVException
- if there was a problem checking for DAV compliancepublic ResourceHandle checkIn() throws DAVException
Note that versioned collections do not have internal members
so they are represented by ResourceHandle
handles.
If the receiver is a working resource it becomes invalid after the check in (because the server deletes the working resource), however, if the receiver is a version-controlled resource the receiver can be used as a checked-in resource.
DAVException
- if a problem occurs with the check in on
the WebDAV server.public abstract AbstractResourceHandle checkOut() throws DAVException
Note that a checked-out version-controlled collection has members that are themselves version-controlled resources, or unversioned resources; however, working collection members are always version history resources.
DAVException
- if a problem occurs checking out the resource.protected void closeResponse(IResponse response) throws SystemException
Note that the argument MAY be null
in which case
the call has no effect.
response
- the response from the server, or SystemException
- if a problem occurred closing the response.public void copy(ILocator destination) throws DAVException
Uses default values of depth: infinity and overwrite: false for the copy.
destination
- the Locator
to the destination of the copy.
DAVException
- if there was a problem copying this resource.IServer.copy(ILocator, ILocator, IContext, Document)
public void copy(ILocator destination, String depth, boolean overwrite, Collection propertyNames) throws DAVException
destination
- the location to put the copy.depth
- how deep to make the copy.overwrite
- how to react if a resource already exists at the destination.propertyNames
- Collection
of QualifiedName
s
of properties that MUST be copied as live properties. Specifying null
mean that all properties must be kept alive; specifying an empty collection allows for
no properties to be kept live. (ref http://andrew2.andrew.cmu.edu/rfc/rfc2518.html#sec-12.12.1)
DAVException
- if there was a problem copying this resource.IServer.copy(ILocator, ILocator, IContext, Document)
public abstract void create() throws DAVException
Subclasses should override this method with the correct behavior for their type.
DAVException
- if there was a problem creating
this resource.public void delete() throws DAVException
As a convenience, if the resource does not exist this method will do nothing (rather than throw an exception). If the caller needs to know if a resource was deleted they can use delete(boolean).
DAVException
- if there was a problem deleting this resource.delete(boolean)
,
IServer#delete(Locator, Context)
public boolean equals(Object obj)
Note that this is a handle equivalence test, and does not imply that the resources are the same resource on the server. Indeed, the method does not contact the server.
equals
in class Object
obj
- the target of the comparison.
public int hashCode()
Object#hashCode()
.
hashCode
in class Object
protected void examineMultiStatusResponse(IResponse response) throws DAVException
response
- the response from the server to examine.
DAVException
- if the given response contains a multistatus
body that contains a status code signalling an error.protected void examineResponse(IResponse response) throws WebDAVException
response
- the response to check
WebDAVException
- if the server returned an HTTP/WebDAV
error code (i.e., anything outside the 200-series codes).protected URLTable extractPropStats(MultiStatus multiStatus) throws IOException, MalformedElementException
multiStatus
- an editor on the response from the server.
URLTable
.
IOException
- if there is a problem parsing the resource URLs.
MalformedElementException
- if the XML is badly formed.public ResponseInputStream getContent() throws DAVException
DAVException
- if there was a problem getting the contentsIServer#get(Locator, Context)
public DAVClient getDAVClient()
DAVClient
.public ILocator getLocator()
public Enumeration getLocks() throws DAVException
DAVException
- if there was a problem getting the locksgetProperty(QualifiedName)
public CollectionHandle getParent() throws DAVException
Note that this method does NOT perform a method call to the server to ensure that the collection exists.
Returns null
if this resource is the root.
NOTE
The parent of a resource is, in general, ambiguous and may not
be immediately discernable from a resource locator. For example,
a locator with a 'label' qualifier will identify a version of a version-
controlled resource, and the parent will not be found by a simple URL
operation. Where a handle is created on a stable URL (i.e. a version URL)
there is no concept of a 'parent' resource.
Clients require further contextual information to determine
the 'parent' of a resource in these cases.
null
.
DAVException
public URLTable getProperties(String depth) throws DAVException
URLTable
which contains all of this resources
properties to the given depth. The returned URLTable
maps resource URL
s to Hashtable
s
which in turn maps property QualifiedName
s to
PropertyStatus
.
depth
- the depth of the request; for example,
Context.DEPTH_ZERO
.
URLTable
containing properties.
DAVException
- if there was a problem retrieving the properties.getProperties(Collection, String)
public URLTable getProperties(Collection propertyNames, String depth) throws DAVException
URL
s of
the resources. The nested table is a table where the keys are the names
(QualifiedName
) of the properties and the values are the
properties' values (PropertyStatus
).
propertyNames
- collection of property names to search for
(QualifiedName
), or null
to retrieve
all properties.depth
- the depth of the search (eg. Context.DEPTH_INFINITY
)
URLKey
then by property name.
DAVException
- if there was a problem fetching the properties.IServer#propfind(Locator, Context, Document)
public PropertyStatus getProperty(QualifiedName propertyName) throws DAVException
propertyName
- the name of the property
DAVException
- if there was a problem getting the propertygetProperties(Collection, String)
public URLTable getPropertyNames(String depth) throws DAVException
URLTable
mapping resource URLs to enumerations over the property names for that
resource.
depth
- eg. Context.DEPTH_ZERO
URLTable
of Enumerations
over
QualfiedNames
DAVException
- if there was a problem getting the property namesIServer#propfind(Locator, Context, Document)
public URLTable getVersionTree() throws DAVException
The version tree info comprises a URLTable
whose keys
are the URL
s of each version in the version history,
and whose values are Vector
s of the resource's immediate
predecessor URL
s. Note that the root version is
(uniquely) identified by an empty set of predecessors.
DAVException
public CollectionHandle[] getWorkspaceCollections() throws DAVException
DAVException
public IContext head() throws DAVException
DAVException
- if there was a problem sending the messageIServer#head(Locator, Context)
public boolean isCollection() throws DAVException
A resource is a collection (i.e., implements collection semantics) if it's resource type includes a <DAV:collection> element.
true
if the resource implements collection
semantics, and false
otherwise.
DAVException
public boolean isLocked() throws DAVException
DAVException
- if there was a problem getting the locksgetLocks()
public LockToken lock() throws DAVException
Note: default values of DEPTH_ZERO for depth and -1 for timeout are used.
DAVException
- if there was a problem locking this resourcelock(boolean, String, int, String)
public LockToken lock(boolean isShared, String depth, int timeout, String owner) throws DAVException
isShared
- true if the lock is shared, false if the lock is exclusivedepth
- eg. Context.DEPTH_ZERO
timeout
- the timeout value for the lockowner
- the owner of the lock
DAVException
- if there was a problem locking this resourceIServer#lock(Locator, Context, Document)
public void move(ILocator destination) throws DAVException
destination
- the location to move this resource to
DAVException
- if there was a problem moving this resource#move(Locator, boolean, Enumeration)
public void move(ILocator destination, boolean overwrite, Enumeration names) throws DAVException
destination
- the location to move tooverwrite
- how to react if a resource already exists at the
destinationnames
- Enumeration
over QualifiedNames
DAVException
- if there was a problem moving this resourceIServer#move(Locator, Locator, Context, Document)
protected IContext newContext()
Context
.protected Document newDocument()
Document
.protected ILocator protectedCheckIn() throws DAVException
Locator
to the receiver's version.
DAVException
- if a problem occurs with the check in request.protected ILocator protectedCheckOut() throws DAVException
Locator
to the receiver's version.
DAVException
- if a problem occurs with the check in request.public void refreshLock(LockToken lockToken, int timeout) throws DAVException
lockToken
- the lock token to refreshtimeout
- the new timeout value to use
DAVException
- if there was a problem refreshing the lockpublic void removeProperties(Collection propertyNames) throws DAVException
propertyNames
- Enumeration
over
QualifiedNames
DAVException
- if there was a problem removing the
propertiesIServer#proppatch(Locator, Context, Document)
public void removeProperty(QualifiedName propertyName) throws DAVException
propertyName
- the name of the property to remove
DAVException
- if there was a problem removing the propertyremoveProperties(Collection)
public void setContent(InputStream input) throws DAVException
input
- the inputstream containing the resource contents.
DAVException
- if there was a problem setting the contents.setContent(String, InputStream)
,
IServer#put(Locator, Context, InputStream)
public void setContent(String contentType, InputStream input) throws DAVException
contentType
- the media type for the data on the input stream.input
- the inputstream containing the resource contents.
DAVException
- if there was a problem setting the contents.IServer#put(Locator, Context, InputStream)
public void setProperties(Collection properties) throws DAVException
properties
- a Collection
of property Element
s.
DAVException
- if there was a problem setting the properties.IServer#proppatch(Locator, Context, Document)
public void setProperty(Element property) throws DAVException
property
- the property to set
DAVException
- if there was a problem setting the propertysetProperties(Collection)
public String toString()
toString
in class Object
public ResponseInputStream trace() throws DAVException
The input stream should be closed by the user.
DAVException
- if there was a problem sending the
request to the server.IServer#trace(Locator, Context)
public void unlock(LockToken token) throws DAVException
token
- the lock token to remove from this resource
DAVException
- if there was a problem unlocking this resourceIServer#unlock(Locator, Context)
public void update(ILocator version) throws DAVException
version
- the Locator
of the version that
is the target of the update request.
DAVException
- if a problem occurs executing the update
on the WebDAV server.public void versionControl() throws DAVException
DAVException
- if a problem occurs bringing the
resource under version control.public void delete(boolean mustExist) throws DAVException
mustExist
- if true
then the delete will
fail if the resource was not on the server at the time of the
delete request. If false
the delete will succeed if
there was no such resource to delete.
DAVException
- if there was a problem deleting
this resource.IServer#delete(Locator, Context)
protected void examineStatusCode(int code, String message) throws WebDAVException
code
- the status code to check.message
- the status message accompanying the code.
WebDAVException
- if the server returned an HTTP/WebDAV
error code (i.e., anything outside the 200-series codes).public boolean exists() throws DAVException
This implementation uses the HTTP HEAD method so the URL may or may not exist in the DAV namespace. The DAV RESOURCE_TYPE property is NOT checked.
true
if the resource exists on the server
or false
otherwise.
DAVException
- if there was a problem checking for
existence.public boolean isCheckedIn() throws DAVException
The resource is checked in if it has a <DAV:checked-in> property.
true
if the resource is checked in
and false
otherwise.
DAVException
- if a problem occurs determining the state
of the resource.public boolean isCheckedOut() throws DAVException
The resource is checked out if it has a <DAV:checked-out> property.
true
if the resource is checked out
and false
otherwise.
DAVException
- if a problem occurs determining the state
of the resource.public boolean isVersion() throws DAVException
The resource is a version if it has <DAV:version-name> in the <DAV:supported-live-properties-set>.
true
if the resource is a version
and false
otherwise.
DAVException
- if a problem occurs determining the state
of the resource.public boolean isVersionControlled() throws DAVException
The resource is version controlled if it has <DAV:auto-checkout> in the <DAV:supported-live-properties-set>.
true
if the resource is under version
control and false
otherwise.
DAVException
- if a problem occurs determining the state
of the resource.public boolean isWorkingResource() throws DAVException
The resource is a working resource if it has <DAV:checked-out> and does not have <DAV:auto-checkout> in the <DAV:supported-live-properties-set>.
true
if the resource is a working resource
and false
otherwise.
DAVException
- if a problem occurs determining the state
of the resource.protected boolean propertyHasChild(QualifiedName propertyName, QualifiedName childName) throws DAVException
true
if the resource does have such a
property with a named child and false
if it does
not have such a property or does not have such a child of the
property.
DAVException
- if a problem occurs determining result
from the server.public boolean supportsLiveProperty(QualifiedName propertyName) throws DAVException
true
if the resource does support the live
property and false
otherwise.
DAVException
- if a problem occurs determining result
from the server.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |