LOCK

Last modified 07:10, 24 Apr 2017

The following sections describe the LOCK method, which is used to take out a lock of any access type and to refresh an existing lock. These sections on the LOCK method describe only those semantics that are specific to the LOCK method and are independent of the access type of the lock being requested.

Any resource that supports the LOCK method MUST, at minimum, support the XML request and response formats defined herein.

This method is neither idempotent nor safe (see Section 9.1 of [RFC2616]). Responses to this method MUST NOT be cached.

Creating a Lock on an Existing Resource

A LOCK request to an existing resource will create a lock on the resource identified by the Request-URI, provided the resource is not already locked with a conflicting lock. The resource identified in the Request-URI becomes the root of the lock. LOCK method requests to create a new lock MUST have an XML request body. The server MUST preserve the information provided by the client in the 'owner' element in the LOCK request. The LOCK request MAY have a Timeout header.

When a new lock is created, the LOCK response:

  • MUST contain a body with the value of the DAV:lockdiscovery property in a prop XML element. This MUST contain the full information about the lock just granted, while information about other (shared) locks is OPTIONAL.
  • MUST include the Lock-Token response header with the token associated with the new lock.

Refreshing Locks

A lock is refreshed by sending a LOCK request to the URL of a resource within the scope of the lock. This request MUST NOT have a body and it MUST specify which lock to refresh by using the 'If' header with a single lock token (only one lock may be refreshed at a time). The request MAY contain a Timeout header, which a server MAY accept to change the duration remaining on the lock to the new value. A server MUST ignore the Depth header on a LOCK refresh.

If the resource has other (shared) locks, those locks are unaffected by a lock refresh. Additionally, those locks do not prevent the named lock from being refreshed.

The Lock-Token header is not returned in the response for a successful refresh LOCK request, but the LOCK response body MUST contain the new value for the DAV:lockdiscovery property.

Depth and Locking

The Depth header may be used with the LOCK method. Values other than 0 or infinity MUST NOT be used with the Depth header on a LOCK method. All resources that support the LOCK method MUST support the Depth header.

A Depth header of value 0 means to just lock the resource specified by the Request-URI.

If the Depth header is set to infinity, then the resource specified in the Request-URI along with all its members, all the way down the hierarchy, are to be locked. A successful result MUST return a single lock token. Similarly, if an UNLOCK is successfully executed on this token, all associated resources are unlocked. Hence, partial success is not an option for LOCK or UNLOCK. Either the entire hierarchy is locked or no resources are locked.

If the lock cannot be granted to all resources, the server MUST return a Multi-Status response with a 'response' element for at least one resource that prevented the lock from being granted, along with a suitable status code for that failure (e.g., 403 (Forbidden) or 423 (Locked)). Additionally, if the resource causing the failure was not the resource requested, then the server SHOULD include a 'response' element for the Request-URI as well, with a 'status' element containing 424 Failed Dependency.

If no Depth header is submitted on a LOCK request, then the request MUST act as if a "Depth:infinity" had been submitted.

Locking Unmapped URLs

A successful LOCK method MUST result in the creation of an empty resource that is locked (and that is not a collection) when a resource did not previously exist at that URL. Later on, the lock may go away but the empty resource remains. Empty resources MUST then appear in PROPFIND responses including that URL in the response scope. A server MUST respond successfully to a GET request to an empty resource, either by using a 204 No Content response, or by using 200 OK with a Content-Length header indicating zero length

Lock Compatibility Table

The table below describes the behavior that occurs when a lock request is made on a resource.

Current State Shared Lock OK Exclusive Lock OK
None True True
Shared Lock True False
Exclusive Lock False False*

Legend: True = lock may be granted. False = lock MUST NOT be granted. *=It is illegal for a principal to request the same lock twice.

The current lock state of a resource is given in the leftmost column, and lock requests are listed in the first row. The intersection of a row and column gives the result of a lock request. For example, if a shared lock is held on a resource, and an exclusive lock is requested, the table entry is "false", indicating that the lock must not be granted.

LOCK Responses

In addition to the general status codes possible, the following status codes have specific applicability to LOCK:

200 (OK) - The LOCK request succeeded and the value of the DAV:lockdiscovery property is included in the response body.

201 (Created) - The LOCK request was to an unmapped URL, the request succeeded and resulted in the creation of a new resource, and the value of the DAV:lockdiscovery property is included in the response body.

409 (Conflict) - A resource cannot be created at the destination until one or more intermediate collections have been created. The server MUST NOT create those intermediate collections automatically.

423 (Locked), potentially with 'no-conflicting-lock' precondition code - There is already a lock on the resource that is not compatible with the requested lock (see lock compatibility table above).

412 (Precondition Failed), with 'lock-token-matches-request-uri' precondition code - The LOCK request was made with an If header, indicating that the client wishes to refresh the given lock. However, the Request-URI did not fall within the scope of the lock identified by the token. The lock may have a scope that does not include the Request-URI, or the lock could have disappeared, or the token may be invalid.

Example - Simple Lock Request

>>Request

  LOCK /workspace/webdav/proposal.doc HTTP/1.1 
  Host: example.com 
  Timeout: Infinite, Second-4100000000 
  Content-Type: application/xml; charset="utf-8" 
  Content-Length: xxxx 
  Authorization: Digest username="ejw", 
    realm="ejw@example.com", nonce="...", 
    uri="/workspace/webdav/proposal.doc", 
    response="...", opaque="..." 
    
  <?xml version="1.0" encoding="utf-8" ?> 
  <D:lockinfo xmlns:D='DAV:'> 
    <D:lockscope><D:exclusive/></D:lockscope> 
    <D:locktype><D:write/></D:locktype> 
    <D:owner> 
      <D:href>http://example.org/~ejw/contact.html</D:href> 
    </D:owner> 
  </D:lockinfo> 

>>Response

  HTTP/1.1 200 OK 
  Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4> 
  Content-Type: application/xml; charset="utf-8" 
  Content-Length: xxxx 
  
  <?xml version="1.0" encoding="utf-8" ?> 
  <D:prop xmlns:D="DAV:"> 
    <D:lockdiscovery> 
      <D:activelock> 
        <D:locktype><D:write/></D:locktype> 
        <D:lockscope><D:exclusive/></D:lockscope> 
        <D:depth>infinity</D:depth> 
        <D:owner> 
          <D:href>http://example.org/~ejw/contact.html</D:href> 
        </D:owner> 
        <D:timeout>Second-604800</D:timeout> 
        <D:locktoken> 
          <D:href
          >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
        </D:locktoken> 
        <D:lockroot> 
          <D:href
          >http://example.com/workspace/webdav/proposal.doc</D:href>
        </D:lockroot> 
      </D:activelock> 
    </D:lockdiscovery> 
  </D:prop> 

This example shows the successful creation of an exclusive write lock on resource http://example.com/workspace/webdav/proposal.doc. The resource http://example.org/~ejw/contact.html contains contact information for the creator of the lock. The server has an activity-based timeout policy in place on this resource, which causes the lock to automatically be removed after 1 week (604800 seconds). Note that the nonce, response, and opaque fields have not been calculated in the Authorization request header.

Example - Refreshing a Write Lock

>>Request

  LOCK /workspace/webdav/proposal.doc HTTP/1.1 
  Host: example.com 
  Timeout: Infinite, Second-4100000000 
  If: (<urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>) 
  Authorization: Digest username="ejw", 
    realm="ejw@example.com", nonce="...", 
    uri="/workspace/webdav/proposal.doc", 
    response="...", opaque="..." 

>>Response

  HTTP/1.1 200 OK 
  Content-Type: application/xml; charset="utf-8" 
  Content-Length: xxxx 
  
  <?xml version="1.0" encoding="utf-8" ?> 
  <D:prop xmlns:D="DAV:"> 
    <D:lockdiscovery> 
      <D:activelock> 
        <D:locktype><D:write/></D:locktype> 
        <D:lockscope><D:exclusive/></D:lockscope> 
        <D:depth>infinity</D:depth> 
        <D:owner> 
          <D:href>http://example.org/~ejw/contact.html</D:href> 
        </D:owner> 
        <D:timeout>Second-604800</D:timeout> 
        <D:locktoken> 
          <D:href
          >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href> 
        </D:locktoken> 
        <D:lockroot> 
          <D:href
          >http://example.com/workspace/webdav/proposal.doc</D:href> 
        </D:lockroot> 
      </D:activelock> 
    </D:lockdiscovery> 
  </D:prop> 

This request would refresh the lock, attempting to reset the timeout to the new value specified in the timeout header. Notice that the client asked for an infinite time out but the server choose to ignore the request. In this example, the nonce, response, and opaque fields have not been calculated in the Authorization request header.

Example - Multi-Resource Lock Request

>>Request

  LOCK /webdav/ HTTP/1.1 
  Host: example.com 
  Timeout: Infinite, Second-4100000000 
  Depth: infinity 
  Content-Type: application/xml; charset="utf-8" 
  Content-Length: xxxx 
  Authorization: Digest username="ejw", 
    realm="ejw@example.com", nonce="...", 
    uri="/workspace/webdav/proposal.doc", 
    response="...", opaque="..." 
      
  <?xml version="1.0" encoding="utf-8" ?> 
  <D:lockinfo xmlns:D="DAV:"> 
    <D:locktype><D:write/></D:locktype> 
    <D:lockscope><D:exclusive/></D:lockscope> 
    <D:owner> 
      <D:href>http://example.org/~ejw/contact.html</D:href> 
    </D:owner> 
  </D:lockinfo> 

>>Response

  HTTP/1.1 207 Multi-Status 
  Content-Type: application/xml; charset="utf-8" 
  Content-Length: xxxx 
  
  <?xml version="1.0" encoding="utf-8" ?> 
  <D:multistatus xmlns:D="DAV:"> 
    <D:response> 
      <D:href>http://example.com/webdav/secret</D:href> 
      <D:status>HTTP/1.1 403 Forbidden</D:status> 
    </D:response> 
    <D:response> 
      <D:href>http://example.com/webdav/</D:href> 
      <D:status>HTTP/1.1 424 Failed Dependency</D:status> 
    </D:response> 
  </D:multistatus>      

This example shows a request for an exclusive write lock on a collection and all its children. In this request, the client has specified that it desires an infinite-length lock, if available, otherwise a timeout of 4.1 billion seconds, if available. The request entity body contains the contact information for the principal taking out the lock -- in this case, a Web page URL.

The error is a 403 (Forbidden) response on the resource http://example.com/webdav/secret. Because this resource could not be locked, none of the resources were locked. Note also that the a 'response' element for the Request-URI itself has been included as required.

In this example, the nonce, response, and opaque fields have not been calculated in the Authorization request header.

Page statistics
5156 view(s) and 2 edit(s)
Social share
Share this page?

Tags

This page has no classifications.

Comments

You must to post a comment.

Attachments