org.apache.webdav.lib.methods
Class LockMethod

java.lang.Object
  |
  +--org.apache.commons.httpclient.HttpMethodBase
        |
        +--org.apache.webdav.lib.methods.XMLResponseMethodBase
              |
              +--org.apache.webdav.lib.methods.LockMethod

All Implemented Interfaces:

DepthSupport, org.apache.commons.httpclient.HttpMethod

public class LockMethod

extends XMLResponseMethodBase

implements DepthSupport

Web resources can be locked to ensure that only one user is updating the resource at a time. Locking helps to prevent the "lost update" problem. There are two types of lock currently defined by the WebDAV specification: exclusive locks and shared locks.

Per the specification, a lock indicates that someone is updating the resource, (hence the lock is a "write lock"), although the specification notes that the the syntax is extensible, and permits the eventual creation of locking for other access types.

Shared and Exclusive Locks

The most basic form of lock is an exclusive lock. This is a lock where the access right in question is only granted to a single client. The need for this arbitration results from a desire to avoid having to merge results. However, there are times when the goal of a lock is not to exclude others from exercising an access right but rather to provide a mechanism for principals to indicate that they intend to exercise their access rights. Shared locks are provided for this case. A shared lock allows multiple clients to receive a lock. Hence any user with appropriate access can get the lock.

With shared locks there are two trust sets that affect a resource. The first trust set is created by access permissions. Principals who are trusted, for example, may have permission to write to the resource. Among those who have access permission to write to the resource, the set of principals who have taken out a shared lock also must trust each other, creating a (typically) smaller trust set within the access permission write set.

Lock Compatibility

The following table indicates what happens if a new lock request is sent to a resource that is already locked:

	Lock Request
Current Lock	Exclusive Lock	Shared Lock
None	Success	Sucess
Shared	Failure	Sucess
Exclusive	Failure	Failure

Author:

Remy Maucherat, B.C. Holmes

Inner classes inherited from class org.apache.webdav.lib.methods.XMLResponseMethodBase

XMLResponseMethodBase.Response, XMLResponseMethodBase.ResponseWithinMultistatus, XMLResponseMethodBase.SingleResponse

Field Summary

static short	SCOPE_EXCLUSIVE
static short	SCOPE_SHARED
static long	TIMEOUT_INFINITY
static short	TYPE_WRITE

Fields inherited from class org.apache.webdav.lib.methods.XMLResponseMethodBase

builder

Fields inherited from class org.apache.commons.httpclient.HttpMethodBase

debug, followRedirects, name, parameters, path, query, queryString, requestHeaders, responseHeaders, state, statusCode, statusText

Fields inherited from interface org.apache.webdav.lib.methods.DepthSupport

DEPTH_0, DEPTH_1, DEPTH_INFINITY

Fields inherited from interface org.apache.commons.httpclient.HttpMethod

PROTOCOL

Constructor Summary

LockMethod()
Method constructor.

LockMethod(java.lang.String path)
Method constructor.

LockMethod(java.lang.String path, java.lang.String refreshOpaqueToken, long timeout)
Method constructor.

LockMethod(java.lang.String path, java.lang.String owner, short scope, long timeout)
Method constructor.

Method Summary

void	generateHeaders(java.lang.String host, org.apache.commons.httpclient.State state) Generate additional headers needed by the request.
java.lang.String	generateQuery() Generate the query body.
int	getDepth() Depth getter.
java.lang.String	getLockToken()
short	getScope()
long	getTimeout()
boolean	isRefresh()
void	parseResponse(java.io.InputStream input) Parse response.
void	recycle() Reset the State of the class to its initial state, so that it can be used again.
void	setDepth(int depth) Depth setter.
void	setHeader(java.lang.String headerName, java.lang.String headerValue) Set header.
void	setOwner(java.lang.String owner) Sets the owner of the lock.
void	setScope(short scope)
void	setTimeout(long timeout)

Methods inherited from class org.apache.webdav.lib.methods.XMLResponseMethodBase

convertElementToProperty, getResponseDocument, getResponseHashtable, getResponses, getState, parseXMLResponse

Methods inherited from class org.apache.commons.httpclient.HttpMethodBase

checkNotUsed, checkUsed, followRedirects, generateHeaders, generateRequestLine, generateRequestLine, getHeader, getHeaders, getHeadersHashtable, getName, getPath, getStatusCode, getStatusText, hasBeenUsed, hasResponseBody, isStreamedQuery, needContentLength, needExpectation, processResponseHeaders, removeHeader, setDebug, setFollowRedirects, setParameter, setPath, setQuery, setQueryString, setState, setStatusCode, setStatusText, setUsed, streamQuery, validate

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCOPE_EXCLUSIVE

public static final short SCOPE_EXCLUSIVE

SCOPE_SHARED

public static final short SCOPE_SHARED

TYPE_WRITE

public static final short TYPE_WRITE

TIMEOUT_INFINITY

public static final long TIMEOUT_INFINITY

Constructor Detail

LockMethod

public LockMethod()

Method constructor.

LockMethod

public LockMethod(java.lang.String path)

Method constructor.

LockMethod

public LockMethod(java.lang.String path,
                  java.lang.String refreshOpaqueToken,
                  long timeout)

Method constructor.

LockMethod

public LockMethod(java.lang.String path,
                  java.lang.String owner,
                  short scope,
                  long timeout)

Method constructor.

Method Detail

setHeader

public void setHeader(java.lang.String headerName,
                      java.lang.String headerValue)

Set header. handle the special case of Depth and Time

Overrides:

setHeader in class org.apache.commons.httpclient.HttpMethodBase

Parameters:

headerName - Header name

headerValue - Header value

setDepth

public void setDepth(int depth)

Depth setter.

Specified by:

setDepth in interface DepthSupport

Parameters:

depth - New depth value

getDepth

public int getDepth()

Depth getter.

Specified by:

getDepth in interface DepthSupport

Returns:

int depth value

getLockToken

public java.lang.String getLockToken()

isRefresh

public boolean isRefresh()

getScope

public short getScope()

setOwner

public void setOwner(java.lang.String owner)

Sets the owner of the lock. This method provides only "basic" owner information. Thus, setOwner("Jezebel Lipshitz") will produce an owner element in the request document like this:

   <D:owner>Jezebel Lipshitz</D:owner>
 

Examples in the Webdav specification suggest that one can use e-mail addresses, home page URLs, or other information; this implementation doesn't handle any of that.

setScope

public void setScope(short scope)

getTimeout

public long getTimeout()

setTimeout

public void setTimeout(long timeout)

recycle

public void recycle()

Description copied from class: XMLResponseMethodBase

Reset the State of the class to its initial state, so that it can be used again.

Overrides:

recycle in class XMLResponseMethodBase

generateHeaders

public void generateHeaders(java.lang.String host,
                            org.apache.commons.httpclient.State state)

Generate additional headers needed by the request.

Overrides:

generateHeaders in class org.apache.commons.httpclient.HttpMethodBase

Parameters:

host - the host

state - State token

generateQuery

public java.lang.String generateQuery()

Generate the query body.

Overrides:

generateQuery in class org.apache.commons.httpclient.HttpMethodBase

Returns:

String query

parseResponse

public void parseResponse(java.io.InputStream input)
                   throws java.io.IOException,
                          org.apache.commons.httpclient.HttpException

Parse response.

Overrides:

parseResponse in class XMLResponseMethodBase

Parameters:

input - Input stream