Re: new proposed text for locking overview

Jason wrote on 07/08/2004 06:00:06 PM:

> Geoff wrote 
> > But I'm not wedded to the idea of calling a lock a resource, so maybe 
> > it would be simplest to just say: 
> > ---------------------------------------- 
> > 2.5 Status of a lock 
> >    A lock is identified by a URI (the lock token URI) but in general, 
it
> >    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. 
> > ----------------------------------------- 
> > 
> > Since I believe this is the only section that refers to the 
"resourceness" 
> > of a lock, we can avoid the contention while keeping all the good 
stuff in 
> > the later paragraphs. 
> 
> I guess we'd have to see it in context, but if that's the only mention 
of 
> resourceness, that should be a significant improvement.  (Don't forget 
> to include the word "is" between lines 0 and 1.  :-)) 

The context is just the rest of the paragraphs of Julian's proposed
text, but I'll include it again below.  By "significant improvement",
do you mean "I now like it", or are there remaining problems that you
see in the proposed text (quoted below, with the first two sentences
changed to avoid calling a lock a resource):

-----------------------

2.5 Status of a lock 
    A lock is identified by a URI (the lock token URI) but in general, it
    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.
-----------------------

Does anyone have any issues with this revised text?

Cheers,
Geoff