org.apache.webdav.lib.methods

Class LockMethod

Implemented Interfaces:
DepthSupport

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

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.webdav.lib.methods.XMLResponseMethodBase

XMLResponseMethodBase.OptionsResponse, XMLResponseMethodBase.Response, XMLResponseMethodBase.ResponseWithinMultistatus, XMLResponseMethodBase.SingleResponse

Field Summary

static short
SCOPE_EXCLUSIVE
static short
SCOPE_SHARED
static int
TIMEOUT_INFINITY
static short
TYPE_WRITE

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

builder, decodeResponseHrefs, responseURLs

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

DEPTH_0, DEPTH_1, DEPTH_INFINITY

Constructor Summary

LockMethod()
Method constructor.
LockMethod(String path)
Method constructor.
LockMethod(String path, String refreshOpaqueToken, int timeout)
Method constructor.
LockMethod(String path, String owner, int timeout, boolean isTransaction)
Creates a lock method that can start a transaction when server supports them in a MS like style.
LockMethod(String path, String refreshOpaqueToken, long timeout)
Deprecated. The timeout value MUST NOT be greater than 2^32-1.
LockMethod(String path, String owner, short scope, int timeout)
Method constructor.
LockMethod(String path, String owner, short scope, long timeout)
Deprecated. The timeout value MUST NOT be greater than 2^32-1.

Method Summary

void
addRequestHeaders(HttpState state, HttpConnection conn)
Generate additional headers needed by the request.
protected String
generateRequestBody()
DAV requests that contain a body must override this function to generate that body.
int
getDepth()
Depth getter.
String
getLockToken()
String
getName()
String
getOwner()
Return the owner of the lock as reported by the server.
short
getScope()
int
getTimeout()
get the timeout value.
boolean
isRefresh()
boolean
isTypeTransaction()
void
parseResponse(InputStream input, HttpState state, HttpConnection conn)
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
setOwner(String owner)
Sets the owner of the lock.
void
setRequestHeader(String headerName, String headerValue)
Set a header value, redirecting the special cases of Depth and Time headers to setDepth(int) and setTimeout as appropriate.
void
setScope(short scope)
void
setTimeout(int timeout)
Set the timeout value.
void
setTimeout(long timeout)
Deprecated. The timeout value MUST NOT be greater than 2^32-1.
void
setTypeTransaction(boolean typeTransaction)

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

convertElementToProperty, generateRequestBody, getDebug, getRequestContentLength, getResponseDocument, getResponseHashtable, getResponseURLs, getResponses, parseResponse, parseXMLResponse, readResponseBody, recycle, setDebug, setDecodeResponseHrefs, setDocument, setResponseHashtable, writeRequestBody

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

getRequestContentLength, isRequestContentAlreadySet, readContinueCode, recycle, setRequestBody, setRequestBody, setRequestBody, setRequestBody, setRequestBody, writeRequestBody

Field Details

SCOPE_EXCLUSIVE

public static final short SCOPE_EXCLUSIVE
Field Value:
0

SCOPE_SHARED

public static final short SCOPE_SHARED
Field Value:
1

TIMEOUT_INFINITY

public static final int TIMEOUT_INFINITY

TYPE_WRITE

public static final short TYPE_WRITE
Field Value:
0

Constructor Details

LockMethod

public LockMethod()
Method constructor.

LockMethod

public LockMethod(String path)
Method constructor.

LockMethod

public LockMethod(String path,
                  String refreshOpaqueToken,
                  int timeout)
Method constructor.

LockMethod

public LockMethod(String path,
                  String owner,
                  int timeout,
                  boolean isTransaction)
Creates a lock method that can start a transaction when server supports them in a MS like style. The transacion handle of the started transaction will be returned as the lock token. To let subsequent requests participate in the transaction add a Transaction header with the lock token as value. You will have to enclose it in '<' and '>' just like ordinary lock tokens.

To either commit or abort the transaction use UnlockMethod.
Parameters:
path - any path inside Slide's scope
owner - of this transaction
timeout - timeout of this transaction
isTransaction - true when this method is used to starte a transaction

LockMethod

public LockMethod(String path,
                  String refreshOpaqueToken,
                  long timeout)

Deprecated. The timeout value MUST NOT be greater than 2^32-1.

Method constructor.

LockMethod

public LockMethod(String path,
                  String owner,
                  short scope,
                  int timeout)
Method constructor.

LockMethod

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

Deprecated. The timeout value MUST NOT be greater than 2^32-1.

Method constructor.

Method Details

addRequestHeaders

public void addRequestHeaders(HttpState state,
                              HttpConnection conn)
            throws IOException,
                   HttpException
Generate additional headers needed by the request.
Parameters:
state - State token
conn - The connection being used for the request.

generateRequestBody

protected String generateRequestBody()
DAV requests that contain a body must override this function to generate that body.

The default behavior simply returns an empty body.

Overrides:
generateRequestBody in interface XMLResponseMethodBase

getDepth

public int getDepth()
Depth getter.
Specified by:
getDepth in interface DepthSupport
Returns:
int depth value

getLockToken

public String getLockToken()

getName

public String getName()

getOwner

public String getOwner()
Return the owner of the lock as reported by the server.

getScope

public short getScope()

getTimeout

public int getTimeout()
get the timeout value.
Returns:
timeout

isRefresh

public boolean isRefresh()

isTypeTransaction

public boolean isTypeTransaction()

parseResponse

public void parseResponse(InputStream input,
                          HttpState state,
                          HttpConnection conn)
            throws IOException,
                   HttpException
Parse response.
Overrides:
parseResponse in interface XMLResponseMethodBase
Parameters:
input - Input stream

recycle

public void recycle()
Reset the State of the class to its initial state, so that it can be used again.
Overrides:
recycle in interface XMLResponseMethodBase

setDepth

public void setDepth(int depth)
Depth setter.
Specified by:
setDepth in interface DepthSupport
Parameters:
depth - New depth value

setOwner

public void setOwner(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.


setRequestHeader

public void setRequestHeader(String headerName,
                             String headerValue)
Parameters:
headerName - Header name
headerValue - Header value

setScope

public void setScope(short scope)

setTimeout

public void setTimeout(int timeout)
Set the timeout value.

setTimeout

public void setTimeout(long timeout)

Deprecated. The timeout value MUST NOT be greater than 2^32-1.

Set the timeout value.

setTypeTransaction

public void setTypeTransaction(boolean typeTransaction)