Class LockMethod

  • All Implemented Interfaces:
    org.apache.commons.httpclient.HttpMethod, 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
    • Constructor Summary

      Constructors 
      Constructor Description
      LockMethod()
      Method constructor.
      LockMethod​(java.lang.String path)
      Method constructor.
      LockMethod​(java.lang.String path, java.lang.String refreshOpaqueToken, int timeout)
      Method constructor.
      LockMethod​(java.lang.String path, java.lang.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​(java.lang.String path, java.lang.String refreshOpaqueToken, long timeout)
      Deprecated.
      The timeout value MUST NOT be greater than 2^32-1.
      LockMethod​(java.lang.String path, java.lang.String owner, short scope, int timeout)
      Method constructor.
      LockMethod​(java.lang.String path, java.lang.String owner, short scope, long timeout)
      Deprecated.
      The timeout value MUST NOT be greater than 2^32-1.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void addRequestHeaders​(org.apache.commons.httpclient.HttpState state, org.apache.commons.httpclient.HttpConnection conn)
      Generate additional headers needed by the request.
      protected java.lang.String generateRequestBody()
      DAV requests that contain a body must override this function to generate that body.
      int getDepth()
      Depth getter.
      java.lang.String getLockToken()  
      java.lang.String getName()  
      java.lang.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​(java.io.InputStream input, org.apache.commons.httpclient.HttpState state, org.apache.commons.httpclient.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​(java.lang.String owner)
      Sets the owner of the lock.
      void setRequestHeader​(java.lang.String headerName, java.lang.String headerValue)
      Set a header value, redirecting the special cases of Depth and Time headers to setDepth(int) and setTimeout(int) 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.commons.httpclient.HttpMethodBase

        abort, addCookieRequestHeader, addHostRequestHeader, addProxyConnectionHeader, addRequestHeader, addRequestHeader, addResponseFooter, addUserAgentRequestHeader, checkNotUsed, checkUsed, execute, generateRequestLine, getAuthenticationRealm, getContentCharSet, getDoAuthentication, getEffectiveVersion, getFollowRedirects, getHostAuthState, getHostConfiguration, getMethodRetryHandler, getParams, getPath, getProxyAuthenticationRealm, getProxyAuthState, getQueryString, getRecoverableExceptionCount, getRequestCharSet, getRequestHeader, getRequestHeaderGroup, getRequestHeaders, getRequestHeaders, getResponseBody, getResponseBody, getResponseBodyAsStream, getResponseBodyAsString, getResponseBodyAsString, getResponseCharSet, getResponseContentLength, getResponseFooter, getResponseFooters, getResponseHeader, getResponseHeaderGroup, getResponseHeaders, getResponseHeaders, getResponseStream, getResponseTrailerHeaderGroup, getStatusCode, getStatusLine, getStatusText, getURI, hasBeenUsed, isAborted, isConnectionCloseForced, isHttp11, isRequestSent, isStrictMode, processCookieHeaders, processResponseBody, processResponseHeaders, processStatusLine, readResponse, readResponseHeaders, readStatusLine, releaseConnection, removeRequestHeader, removeRequestHeader, responseBodyConsumed, setConnectionCloseForced, setDoAuthentication, setFollowRedirects, setHostConfiguration, setHttp11, setMethodRetryHandler, setParams, setPath, setQueryString, setQueryString, setRequestHeader, setResponseStream, setStrictMode, setURI, shouldCloseConnection, validate, writeRequest, writeRequestHeaders, writeRequestLine
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • LockMethod

        public LockMethod​(java.lang.String path,
                          java.lang.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()
        Method constructor.
      • LockMethod

        public LockMethod​(java.lang.String path)
        Method constructor.
      • LockMethod

        public LockMethod​(java.lang.String path,
                          java.lang.String refreshOpaqueToken,
                          int timeout)
        Method constructor.
      • LockMethod

        public LockMethod​(java.lang.String path,
                          java.lang.String owner,
                          short scope,
                          int timeout)
        Method constructor.
      • LockMethod

        public LockMethod​(java.lang.String path,
                          java.lang.String refreshOpaqueToken,
                          long timeout)
        Deprecated.
        The timeout value MUST NOT be greater than 2^32-1.
        Method constructor.
      • LockMethod

        public LockMethod​(java.lang.String path,
                          java.lang.String owner,
                          short scope,
                          long timeout)
        Deprecated.
        The timeout value MUST NOT be greater than 2^32-1.
        Method constructor.
    • Method Detail

      • setRequestHeader

        public void setRequestHeader​(java.lang.String headerName,
                                     java.lang.String headerValue)
        Set a header value, redirecting the special cases of Depth and Time headers to setDepth(int) and setTimeout(int) as appropriate.
        Specified by:
        setRequestHeader in interface org.apache.commons.httpclient.HttpMethod
        Overrides:
        setRequestHeader in class org.apache.commons.httpclient.HttpMethodBase
        Parameters:
        headerName - Header name
        headerValue - Header value
      • isTypeTransaction

        public boolean isTypeTransaction()
      • setTypeTransaction

        public void setTypeTransaction​(boolean typeTransaction)
      • 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.

      • getOwner

        public java.lang.String getOwner()
        Return the owner of the lock as reported by the server.
      • setScope

        public void setScope​(short scope)
      • getTimeout

        public int getTimeout()
        get the timeout value.
        Returns:
        timeout
      • 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.
      • getName

        public java.lang.String getName()
        Specified by:
        getName in interface org.apache.commons.httpclient.HttpMethod
        Specified by:
        getName in class org.apache.commons.httpclient.HttpMethodBase
      • 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.
        Specified by:
        recycle in interface org.apache.commons.httpclient.HttpMethod
        Overrides:
        recycle in class XMLResponseMethodBase
      • addRequestHeaders

        public void addRequestHeaders​(org.apache.commons.httpclient.HttpState state,
                                      org.apache.commons.httpclient.HttpConnection conn)
                               throws java.io.IOException,
                                      org.apache.commons.httpclient.HttpException
        Generate additional headers needed by the request.
        Overrides:
        addRequestHeaders in class org.apache.commons.httpclient.HttpMethodBase
        Parameters:
        state - State token
        conn - The connection being used for the request.
        Throws:
        java.io.IOException
        org.apache.commons.httpclient.HttpException
      • generateRequestBody

        protected java.lang.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 class XMLResponseMethodBase
      • parseResponse

        public void parseResponse​(java.io.InputStream input,
                                  org.apache.commons.httpclient.HttpState state,
                                  org.apache.commons.httpclient.HttpConnection conn)
                           throws java.io.IOException,
                                  org.apache.commons.httpclient.HttpException
        Parse response.
        Overrides:
        parseResponse in class XMLResponseMethodBase
        Parameters:
        input - Input stream
        Throws:
        java.io.IOException
        org.apache.commons.httpclient.HttpException