new proposed text for locking overview

Hi,

I noticed that RFC2518 historically says little about what a lock 
actually *is*, instead just describes it's behaviour (which of course 
needs to be done is well). The result is that essential information if 
spread across the document; instead of being in a single place. A good 
example for this is if you look at the various places in RFC2518 that 
say something about what a timeout is, what it means to refresh it, when 
the server needs to respect it and so on...

Here's what I wrote for 
<http://greenbytes.de/tech/webdav/draft-reschke-webdav-locking-latest.html#rfc.section.2> 
(which continues to progress nicely)...:

-- 

2.5  Status of a lock

    Having a URI (the lock token URI) on it's own, a lock is a resource
    in the sense defined by [RFC2396].  In general, this resource does
    not have a HTTP URL, and thus can not be directly manipulated using
    HTTP methods.  Instead, this specification defines the new methods
    LOCK (creating and refreshing locks, see Section 4) and UNLOCK
    (removing locks, see Section 5) that act indirectly on locks.

    A lock has state that can be indirectly observed by using the
    DAV:lockdiscovery property defined in Section 3.2.  At a minimum, the
    state of a lock consists of the items defined in the sections below.
    After lock creation, all parts of the state with the exception of the
    timeout value are immutable.

2.5.1  Lock Access Type

    At present, this specification only defines one lock access type, the
    "write" lock defined in Section xx.

2.5.2  Lock Scope

    A lock has either exclusive or shared scope (see Section 2.1).

2.5.3  Lock Root

    A lock is created as effect of a LOCK (creation) method request.  The
    lock root is the URL to which this request was adressed.

2.5.4  Lock Depth

    A "depth 0" lock only affects the resource to which the LOCK request
    was adressed to (the lock root).  This resource is said to be
    "directly locked" by the lock.

    On the other hand, a "depth infinity" lock on a collection
    additionally affects all members of that collection.  These resources
    are said to be "indirectly locked" by the lock.  A "depth infinity"
    lock on a non-collection resource behaves exactly the same way as a
    "depth 0" lock.

2.5.5  Lock Owner

    Clients can submit information about the lock owner when creating a
    lock.  This information should be sufficient for either directly
    contacting a principal (such as a telephone number or email URI), or
    for discovering the principal (such as the URL of a homepage).

    Owner information is kept with the lock so that it can be returned in
    the DAV:lockdiscovery property upon request.  Note that this
    information is entirely client-controlled, thus a server MUST store
    the information faithfully just like if it appeared in a WebDAV dead
    property (see [RFC2518], section 4).

2.5.6  Lock Timeout

    In general, a lock expires after a certain amount of time.  This time
    can be specified in the LOCK creation request (however servers are
    not required to honor this request).

    If the timeout expires then the lock may be lost.  Specifically, if
    the server wishes to harvest the lock upon time-out, the server
    SHOULD act as if an UNLOCK method was executed by the server on the
    resource using the lock token of the timed-out lock, performed with
    its override authority.  Thus logs should be updated with the
    disposition of the lock, notifications should be sent, etc., just as
    they would be for an UNLOCK request.

    The timers used for timeout expiry can be reset by the client by
    submitting a LOCK refresh request.

    Servers are advised to pay close attention to the values submitted by
    clients, as they will be indicative of the type of activity the
    client intends to perform.  For example, an applet running in a
    browser may need to lock a resource, but because of the instability
    of the environment within which the applet is running, the applet may
    be turned off without warning.  As a result, the applet is likely to
    ask for a relatively small timeout value so that if the applet dies,
    the lock can be quickly harvested.  However, a document management
    system is likely to ask for an extremely long timeout because its
    user may be planning on going off-line.

    A client MUST NOT assume that just because the time-out has expired
    the lock has been lost.  Clients MUST assume that locks may
    arbitrarily disappear at any time, regardless of the value given in
    the Timeout header.  The Timeout header only indicates the behavior
    of the server if "extraordinary" circumstances do not occur.  For
    example, an administrator may remove a lock at any time or the system
    may crash in such a way that it loses the record of the lock's
    existence.

-- 

Feedback appreciated,

Julian


-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760



-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

Received on Tuesday, 6 July 2004 14:26:57 UTC