Author: ts
Date: Fri Feb 29 20:53:55 2008
New Revision: 7472
Log:
- Extracted RFC overview from 1.1 design.
Added:
trunk/Webdav/design/rfc2518_overview-1.1.txt (with props)
Modified:
trunk/Webdav/design/design-1.1.txt
Modified: trunk/Webdav/design/design-1.1.txt
==============================================================================
--- trunk/Webdav/design/design-1.1.txt [iso-8859-1] (original)
+++ trunk/Webdav/design/design-1.1.txt [iso-8859-1] Fri Feb 29 20:53:55 2008
@@ -32,103 +32,6 @@
This section introduces common concerns of the issues covered in this design
document and the features resulting from them. Especially the if-header and its
support in the Webdav component are described.
-
-============
-RFC Overview
-============
-
-In addition to the headers If-Match and If-None-Match, which are described in
-the HTTP/1.1 RFC, RFC 2518 (WebDAV) describes the If-Header. The If header is
-used to define conditional actions by the client, similar to the 2 headers
-named before. However, it is constructed in a much more complex and weird way.
-
-If header
-=========
-
-The If header is described with the following pseudo EBNF: ::
-
- If = "If" ":" ( 1*No-tag-list | 1*Tagged-list)
- No-tag-list = List
- Tagged-list = Resource 1*List
- Resource = Coded-URL
- List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
- State-token = Coded-URL
- Coded-URL = "<" absoluteURI ">"
-
-It may contain entity tags (see `Entity tag support`_), lock tokens (see `Lock
-tokens`_) and combination of both. In addition the header may contain
-additional resource URIs to affect not only the main request URI. Luckily, the
-If header either containes a tagged list (including affected resource URIs) or
-a no-tag list (without resource URIs). It cannot contain a combination of
-those.
-
-Both lists (tagged and no-tag) contain a not limmited number of lock tokens
-and/or entity tags and maybe prefixed by the keyword "Not". This indicates
that the
-affected method may only be executed if the condition defined in the list does
-not match. This works similar to the If-None-Match header, specified by the
-HTTP/1.1 RFC.
-
-To illustrate this complex definition some more, some examples are presented
-and explained in following.
-
-No-tag list
-------------
-
-::
-
- If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another
ETag"])
-
-This If header consists of 2 no-tag lists (it does not contain any resource
-URIs). The first list consists of a lock token and an entity tag, the second
-only contains an entity tag. The semantics of this example is, that the method
-containing this If header may only be executed if
-
-- either the first combination of lock token and entity tag is matched
-- or if the second entity tag is matched.
-
-Note that the first list item describes a logical AND operation, while the
-whole list concatenates its items by logical OR.
-
-Tagged list
------------
-
-::
-
- COPY /resource1 HTTP/1.1
- Host: www.foo.bar
- Destination: http://www.foo.bar/resource2
- If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token>
- [W/"A weak ETag"]) (["strong ETag"])
- <http://www.bar.bar/random>(["another strong ETag"])
-
-This example does not only show an If header with a tagged list, but also a
-context where this could make some sense: The COPY method affects several
-resources at once. It works at least on a source (the request URI) and a
-destination (see Destination header), Additionally it can affect whole
-sub-tress, using the Depth header.
-
-The If header in this case affects 2 resources, while one of the defined
-conditions will be checked and the other won't. The first list affects the
-request URI and contains 2 elements concatenated with logical OR. The first
-item consists of an AND-combination of a lock token and an entity tag. The
-second only contains an entity tag. This is similar to the example shown above
-for the no-tag list. Except that it contains the "tagging" URI. For the
-second tag only an entity tag is listed. Anyway, this condition would not be
-checked in the request but simply be ignored, since the resource in the tag is
-not affected by the resource.
-
-Not
----
-
-::
-
- If: (Not <locktoken:write1> <locktoken:write2>)
-
-This simple If header only shows the definition of a "Not" affected list. The
-keyword must occur at the very begining of the affected list item. This item
-contains 2 lock tokens combined with logical AND. In clear words the requested
-affected by this If header will be executed if non of the affected resources is
-locked by either of the specified lock tokens.
=========================
Plugin based design draft
@@ -371,180 +274,6 @@
the usage of the if-header with entity tags and the generation and sending of
the
ETag header.
-============
-RFC Overview
-============
-
-Entity tags are generally used in the HTTP/1.1 protocol to provide a mechanism
-of validating that a resource is in the same state. Whenever the state of a
-resource changes, its entity tag needs to change. In following, the definition
-of the HTTP/1.1 validation mechanisms in general, the definition of an entity
-tag and the definition of the ETag-header are described. In addition the usage
-of entity tags in the Webdav RFC is described.
-
-Entity Tags
-===========
-
-Section 3.11 of the HTTP/1.1 RFC describes entity tags. These strings identify
-(tag) the state of a resource, named "entities" in the RFC. The entity tag
-consists of a quoted string and an optional weakness modifier. The quoted
-string must be unique for each state. ::
-
- entity-tag = [ weak ] opaque-tag
- weak = "W/"
- opaque-tag = quoted-string
-
-A non-weak entity tag must identify a certain state uniquely. With the added W/
-prefix, one and the same tag may identify different states of a resource that
-are semantically equivalent.
-
-Entity tags are used in HTTP/1.1 in combination with the following headers:
-
-- Request
- - If-Match
- - If-None-Match
- - If-Range
-- Response
- - ETag
-
-Since the Webdav component will generate the entity tag, we should ensure to
-only generate strong entity tags.
-
-Headers
-=======
-
-The following section describes the headers that are affected by entity tags
-and how the server should respect them.
-
-If-Match
---------
-
-The If-Match header is generally used to make the method it is send with
-conditional. Only if the conditions defined by the header are met, the action
-associated with the method should be performed by the server.
-
-The header format is defined as follows (14.24): ::
-
- If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
-
-The If-Match header in general assumes that the affected resource exists, if it
-does not, the request must fail since no entity is there to compare the given
-criteria too (no entity exists). The header either specifies "*", to indicate
-that an entity must exist, whichever that is. Alternatively any number of
-entity tags can be given, divided by ",". If one of the given tags match the
-current state of the resource, the method is performed as if not If-Match
-header was given. Else the method must fail with 412 (Precondition failed).
-
-In case the request would have failed anyway (not result in a 2xx or 412
-status), the If-Match condition is not even checked, but the error response
-generated by the request is returned. The reaction of a server to a combination
-of multiple If-* headers is undefined.
-
-.. Note::
- We should just throw all If-* headers away if a combination of the occurs,
- so the back-end does not need to deal with it.
-
-Examples: ::
-
- If-Match: "xyzzy"
- If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-Match: *
-
-If-None-Match
--------------
-
-This header behaves similar to the If-Match header, except that the operation
-is only performed if none of the submitted entity tags matches. In case the
-operation is a GET or a HEAD operation and one of the tags matched, the server
-should return a 304 (Not Modified) code, in all other cases a 412 (Precondition
-Failed) must be returned.
-
-The header is defined like this: ::
-
- If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
-
-The '*' again means that any entity tag exists (as for If-Match). In case of
-the If-None-Match header, the operation will be executed only of no entity of
-the resource exists. In fact this means that the resource does not exist.
-
-Examples: ::
-
- If-None-Match: "xyzzy"
- If-None-Match: W/"xyzzy"
- If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
- If-None-Match: *
-
-If-Range
---------
-
-The If-Range header does only make sense to be respected, if the server
supports
-partial GET requests and resuming of such. Since the Webdav component does not
-support this, yet, the header will be ignored.
-
-.. Note::
- If we support partial GET sometimes, support for this header must be
- considered, too.
-
-ETag
-----
-
-The ETag header is send by a server to give the client an entity-tag for the
-current resource that he can use later with any of the headers described above.
-The ETag header is therefore a response header, while the headers described
-above are request headers.
-
-The ETag header is build up like this: ::
-
- ETag = "ETag" ":" entity-tag
-
-Examples::
-
- ETag: "xyzzy"
- ETag: W/"xyzzy"
- ETag: ""
-
-.. Attention::
- The following is an assumption that should be verified somehow. It seems
that
- the ETag header is only defined for a single resource, which indicates that
- responses that affect multiple resources should not contain it. For Webdav
- this includes several methods like COPY and MOVE, but also PROPFIND with a
- Depth header other than 0.
-
-Validation
-==========
-
-The purpose of entity tags is to ensure, that a certain operation is only
-performed, if a resource resides in a certain state. This state is defined by
-an entity tag. Most likely, this applies to the GET operation in combination
-with caching for pure HTTP/1.1. However, in combination with the WebDAV
-extension, validation of entity tags might also be necessary for operations
-like PUT and others.
-
-The HTTP/1.1 RFC defines 2 different validator schemes: Strong and weak
-validators. Entity tags are generally considered strong validators, since they
-should change as soon as the affected resource changes its state. However, the
-protocol provides a way to declare entity tags to be weak validators, as
-described in the ETag header above.
-
-.. Note::
- We should not make use of this way of "weaking" entity tags, but always
provide
- the strong method.
-
-Caches (like proxy servers and browser caches) use additional methods to
-validate their content. The most common way here is to use the Last-Modified
-header in addition, which indicates the last modification time of the resource.
-
-
--- Note::
- We need to decide if we should support this validator in addition. This
- would also involve more headers to react on, like If-Modified-Since. This is
- not mandatory.
-
-======
-Design
-======
-
The following design only refers to the support of entity tags as defined in
the HTTP/1.1 RFC. This includes the headers mentioned in the above RFC overview
and the generation and comparison of entity tags.
@@ -682,188 +411,8 @@
shared lock it is possible the multiple clients take part in one and the same
lock. More information on lock scopes are provided later.
-============
-RFC overview
-============
-
-This section tries to summarize the important facts about locking mentioned in
-RFC 2518 in various places, enhanced by first pre-considerations of design and
-implementation issues associated with them.
-
-Lock types
-==========
-
-The WebDAV RFC distinguishes between read and write locks, while only write
-locks are defined in detail. The RFC explains, that "the syntax is extensible,
-and permits the eventual specification of locking for other access types".
-
-A write lock determines that the locking principle may exclusively write to the
-affected resources. Reading is possibly for every other client, too. If a
-client that does not hold a specific lock tries to perform a writing operation
-to a resource which is locked by another client, this operation must fail.
-
-Lock scopes
-===========
-
-The WebDAV RFC specifies 2 different scopes for locking:
-
-- Exclusive
-- Shared
-
-For an exclusive lock exactly 1 client may hold a lock on a specific resource
-and only this client is allowed to perform the affected operations on the
-locked resource. For a shared lock it is possible that multiple clients take
-part in the lock (group editing). Every client that takes part in a shared lock
-may perform the affected operations on the locked resource.
-
-WebDAV does not provide any channel to allow communication between the clients
-involved into a shared lock. The communication of these clients must be handled
-externally.
-
-Lock tokens
-===========
-
-A lock token identifies a specific lock uniquely across all resources for all
-times. Whenever a successful LOCK request was processed, it returns the
-specific lock token for this lock. The lock token associates the locking client
-with the locked resource. Therefore multiple lock tokens might be assigned to a
-single resource, if the lock is a shared lock.
-
-A lock token must be unique throughout all resources for all times. The WebDAV
-RFC therefore defines a lock token scheme, which can optionally be used by the
-server. The so called "opaquelocktoekn" scheme makes use of UUID_, as defined
-in `ISO-11578`_. A `PECL package for UUIDs`_ is available.
-
-.. _`UUID`: http://en.wikipedia.org/wiki/UUID
-.. _`ISO-11578`: http://www.iso.ch/cate/d2229.html
-.. _`PECL package for UUIDs`: http://pecl.php.net/package/uuid
-
-Since the opaquelocktoken scheme is not mandatory, the code snippet ::
-
- $token = md5( uniqid( rand(), true ) );
-
-could be used as an alternative to provide the necessary amount of uniqueness.
-To create a lock token that, a this way generated ID could be appended to the
-URI of the affected resource to provide transparency of the source of a lock
-token. For example: http://webdav/foo/bar.txt#<id>.
-
-Every client that can access the WebDAV server has access to lock tokens
-through the LOCKDISCOVERY request method, so the lock must be bound to a
-different authentication mechanism. An owner string is submitted with the LOCK
-request, which might help here.
-
-Affected requests
-=================
-
-Locks affect several request, beside the explicitly lock related requests. The
-following 2 sections summarize the affected request methods and give a short
-overview about how these are affected.
-
-Dedicated methods
------------------
-
-LOCK
- The LOCK method is used to initially establish a lock and to refresh locks.
-
-UNLOCK
- The UNLOCK method is used to release a specific lock before it times out
- automatically.
-
-Affected base methods
----------------------
-
-The following methods may only be performed on a locked resource if the
-performing client owns the specific lock.
-
-- PUT
-- POST
-- PROPPATCH
-- MOVE
-- DELETE
-- MKCOL
-
-In addition the PROPFIND request is affected by lock support, since lock
-information is visible to every client through the LOCKDISCOVERY and
-SUPPORTEDLOCK properties.
-
-Locking resources
-=================
-
-Both types of resources (non-collection and collection resources) can be
-locked. This section describes differences for both types and other points
-directly related to locking resources.
-
-Non-collection resources
-------------------------
-
-A non collection resource can be affected directly or indirectly by a lock. In
-the first case a client has issued a LOCK request explicitly for this resource,
-only locking this single resource. The second case occurs, if a client locked a
-collection resource and the non-collection resource is a direct or in-direct
-descendant of it. For detailed information on this topic see the next section
-about locking if collection resources.
-
-Collections
------------
-
-The LOCK request allows the 'Depth' header to be set to specify the depth of
-the created lock. A depth value of ZERO means, that only the affected
-collection itself is locked. This might be sensible to add new resources to
-this collection. The depth value INFINITY means that the created lock
-recursively affects all descendants of the collection. This way it is possible
-to lock a complete sub-tree of the WebDAV repository.
-
-Any lock (no matter which depth) on a collection prevents the addition and
-removal of direct members of this collection by non-lock-owners. This affects
-the following methods:
-
-- PUT
-- POST
-- MKCOL
-- DELETE
-
-If a collection should be locked and any of its members is already locked, this
-conflicts with the lock to be set and must result in an 423 error (Locked).
-Members that are newly created inside a locked collection or copied/moved to
-it are automatically included to the lock. This affects infinity-depth locks as
-well as zero-depth ones for direct children of the locked collection.
-
-Lock null resources
--------------------
-
-A write lock might be acquired to a resource that does not (yet) exist. This
-is called a "lock null resource". A lock null resource only supports the
-methods:
-
-- PUT
-- MKCOL
-- OPTIONS
-- PROPFIND
-- LOCK
-- UNLOCK
-
-All other methods must return 404 (Not found) or 405 (Method not allowed).
-
-The properties of a null resource are mostly empty, except there must be
-LOCKDISCOVERY and SUPPORTEDLOCK properties. If PUT or MKCOL are issued, a null
-resource becomes a normal one. The RFC does not state if the lock stays on this
-newly created (real) resource or if it is removed.
-
-COPY/MOVE
----------
-
-Both methods destroy locks. If a resource is moved to a locked collection, it
-is automatically added to the lock (same client assumed). Both will not work,
-if the destination is locked but no lock is owned by the client.
-
-Refresh
-=======
-
-A LOCK request must not occur twice. To refresh a lock, clients send a LOCK
-request with empty body and an If header that specifies the lock tokens to
-refresh locks for. If this occurs, the timers of the lock must be reset. A
-Timeout header might be send by the client, but the server may safely ignore
-these and simply perform a refresh as it desires.
+Locking
+^^^^^^^
===================
Plugin design draft
Added: trunk/Webdav/design/rfc2518_overview-1.1.txt
==============================================================================
--- trunk/Webdav/design/rfc2518_overview-1.1.txt (added)
+++ trunk/Webdav/design/rfc2518_overview-1.1.txt [iso-8859-1] Fri Feb 29
20:53:55 2008
@@ -1,0 +1,449 @@
+Entity Tags
+^^^^^^^^^^^
+
+Entity tags are generally used in the HTTP/1.1 protocol to provide a mechanism
+of validating that a resource is in the same state. Whenever the state of a
+resource changes, its entity tag needs to change. In following, the definition
+of the HTTP/1.1 validation mechanisms in general, the definition of an entity
+tag and the definition of the ETag-header are described. In addition the usage
+of entity tags in the Webdav RFC is described.
+
+Section 3.11 of the HTTP/1.1 RFC describes entity tags. These strings identify
+(tag) the state of a resource, named "entities" in the RFC. The entity tag
+consists of a quoted string and an optional weakness modifier. The quoted
+string must be unique for each state. ::
+
+ entity-tag = [ weak ] opaque-tag
+ weak = "W/"
+ opaque-tag = quoted-string
+
+A non-weak entity tag must identify a certain state uniquely. With the added W/
+prefix, one and the same tag may identify different states of a resource that
+are semantically equivalent.
+
+Entity tags are used in HTTP/1.1 in combination with the following headers:
+
+- Request
+ - If-Match
+ - If-None-Match
+ - If-Range
+- Response
+ - ETag
+
+Since the Webdav component will generate the entity tag, we should ensure to
+only generate strong entity tags.
+
+Headers
+=======
+
+The following section describes the headers that are affected by entity tags
+and how the server should respect them.
+
+If-Match
+--------
+
+The If-Match header is generally used to make the method it is send with
+conditional. Only if the conditions defined by the header are met, the action
+associated with the method should be performed by the server.
+
+The header format is defined as follows (14.24): ::
+
+ If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
+
+The If-Match header in general assumes that the affected resource exists, if it
+does not, the request must fail since no entity is there to compare the given
+criteria too (no entity exists). The header either specifies "*", to indicate
+that an entity must exist, whichever that is. Alternatively any number of
+entity tags can be given, divided by ",". If one of the given tags match the
+current state of the resource, the method is performed as if not If-Match
+header was given. Else the method must fail with 412 (Precondition failed).
+
+In case the request would have failed anyway (not result in a 2xx or 412
+status), the If-Match condition is not even checked, but the error response
+generated by the request is returned. The reaction of a server to a combination
+of multiple If-* headers is undefined.
+
+.. Note::
+ We should just throw all If-* headers away if a combination of the occurs,
+ so the back-end does not need to deal with it.
+
+Examples: ::
+
+ If-Match: "xyzzy"
+ If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-Match: *
+
+If-None-Match
+-------------
+
+This header behaves similar to the If-Match header, except that the operation
+is only performed if none of the submitted entity tags matches. In case the
+operation is a GET or a HEAD operation and one of the tags matched, the server
+should return a 304 (Not Modified) code, in all other cases a 412 (Precondition
+Failed) must be returned.
+
+The header is defined like this: ::
+
+ If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
+
+The '*' again means that any entity tag exists (as for If-Match). In case of
+the If-None-Match header, the operation will be executed only of no entity of
+the resource exists. In fact this means that the resource does not exist.
+
+Examples: ::
+
+ If-None-Match: "xyzzy"
+ If-None-Match: W/"xyzzy"
+ If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
+ If-None-Match: *
+
+If-Range
+--------
+
+The If-Range header does only make sense to be respected, if the server
supports
+partial GET requests and resuming of such. Since the Webdav component does not
+support this, yet, the header will be ignored.
+
+.. Note::
+ If we support partial GET sometimes, support for this header must be
+ considered, too.
+
+ETag
+----
+
+The ETag header is send by a server to give the client an entity-tag for the
+current resource that he can use later with any of the headers described above.
+The ETag header is therefore a response header, while the headers described
+above are request headers.
+
+The ETag header is build up like this: ::
+
+ ETag = "ETag" ":" entity-tag
+
+Examples::
+
+ ETag: "xyzzy"
+ ETag: W/"xyzzy"
+ ETag: ""
+
+.. Attention::
+ The following is an assumption that should be verified somehow. It seems
that
+ the ETag header is only defined for a single resource, which indicates that
+ responses that affect multiple resources should not contain it. For Webdav
+ this includes several methods like COPY and MOVE, but also PROPFIND with a
+ Depth header other than 0.
+
+Validation
+==========
+
+The purpose of entity tags is to ensure, that a certain operation is only
+performed, if a resource resides in a certain state. This state is defined by
+an entity tag. Most likely, this applies to the GET operation in combination
+with caching for pure HTTP/1.1. However, in combination with the WebDAV
+extension, validation of entity tags might also be necessary for operations
+like PUT and others.
+
+The HTTP/1.1 RFC defines 2 different validator schemes: Strong and weak
+validators. Entity tags are generally considered strong validators, since they
+should change as soon as the affected resource changes its state. However, the
+protocol provides a way to declare entity tags to be weak validators, as
+described in the ETag header above.
+
+.. Note::
+ We should not make use of this way of "weaking" entity tags, but always
provide
+ the strong method.
+
+Caches (like proxy servers and browser caches) use additional methods to
+validate their content. The most common way here is to use the Last-Modified
+header in addition, which indicates the last modification time of the resource.
+
+
+-- Note::
+ We need to decide if we should support this validator in addition. This
+ would also involve more headers to react on, like If-Modified-Since. This is
+ not mandatory.
+
+
+Locking
+^^^^^^^
+
+This section tries to summarize the important facts about locking mentioned in
+RFC 2518 in various places, enhanced by first pre-considerations of design and
+implementation issues associated with them.
+
+Lock types
+==========
+
+The WebDAV RFC distinguishes between read and write locks, while only write
+locks are defined in detail. The RFC explains, that "the syntax is extensible,
+and permits the eventual specification of locking for other access types".
+
+A write lock determines that the locking principle may exclusively write to the
+affected resources. Reading is possibly for every other client, too. If a
+client that does not hold a specific lock tries to perform a writing operation
+to a resource which is locked by another client, this operation must fail.
+
+Lock scopes
+===========
+
+The WebDAV RFC specifies 2 different scopes for locking:
+
+- Exclusive
+- Shared
+
+For an exclusive lock exactly 1 client may hold a lock on a specific resource
+and only this client is allowed to perform the affected operations on the
+locked resource. For a shared lock it is possible that multiple clients take
+part in the lock (group editing). Every client that takes part in a shared lock
+may perform the affected operations on the locked resource.
+
+WebDAV does not provide any channel to allow communication between the clients
+involved into a shared lock. The communication of these clients must be handled
+externally.
+
+Lock tokens
+===========
+
+A lock token identifies a specific lock uniquely across all resources for all
+times. Whenever a successful LOCK request was processed, it returns the
+specific lock token for this lock. The lock token associates the locking client
+with the locked resource. Therefore multiple lock tokens might be assigned to a
+single resource, if the lock is a shared lock.
+
+A lock token must be unique throughout all resources for all times. The WebDAV
+RFC therefore defines a lock token scheme, which can optionally be used by the
+server. The so called "opaquelocktoekn" scheme makes use of UUID_, as defined
+in `ISO-11578`_. A `PECL package for UUIDs`_ is available.
+
+.. _`UUID`: http://en.wikipedia.org/wiki/UUID
+.. _`ISO-11578`: http://www.iso.ch/cate/d2229.html
+.. _`PECL package for UUIDs`: http://pecl.php.net/package/uuid
+
+Since the opaquelocktoken scheme is not mandatory, the code snippet ::
+
+ $token = md5( uniqid( rand(), true ) );
+
+could be used as an alternative to provide the necessary amount of uniqueness.
+To create a lock token that, a this way generated ID could be appended to the
+URI of the affected resource to provide transparency of the source of a lock
+token. For example: http://webdav/foo/bar.txt#<id>.
+
+Every client that can access the WebDAV server has access to lock tokens
+through the LOCKDISCOVERY request method, so the lock must be bound to a
+different authentication mechanism. An owner string is submitted with the LOCK
+request, which might help here.
+
+Affected requests
+=================
+
+Locks affect several request, beside the explicitly lock related requests. The
+following 2 sections summarize the affected request methods and give a short
+overview about how these are affected.
+
+Dedicated methods
+-----------------
+
+LOCK
+ The LOCK method is used to initially establish a lock and to refresh locks.
+
+UNLOCK
+ The UNLOCK method is used to release a specific lock before it times out
+ automatically.
+
+Affected base methods
+---------------------
+
+The following methods may only be performed on a locked resource if the
+performing client owns the specific lock.
+
+- PUT
+- POST
+- PROPPATCH
+- MOVE
+- DELETE
+- MKCOL
+
+In addition the PROPFIND request is affected by lock support, since lock
+information is visible to every client through the LOCKDISCOVERY and
+SUPPORTEDLOCK properties.
+
+Locking resources
+=================
+
+Both types of resources (non-collection and collection resources) can be
+locked. This section describes differences for both types and other points
+directly related to locking resources.
+
+Non-collection resources
+------------------------
+
+A non collection resource can be affected directly or indirectly by a lock. In
+the first case a client has issued a LOCK request explicitly for this resource,
+only locking this single resource. The second case occurs, if a client locked a
+collection resource and the non-collection resource is a direct or in-direct
+descendant of it. For detailed information on this topic see the next section
+about locking if collection resources.
+
+Collections
+-----------
+
+The LOCK request allows the 'Depth' header to be set to specify the depth of
+the created lock. A depth value of ZERO means, that only the affected
+collection itself is locked. This might be sensible to add new resources to
+this collection. The depth value INFINITY means that the created lock
+recursively affects all descendants of the collection. This way it is possible
+to lock a complete sub-tree of the WebDAV repository.
+
+Any lock (no matter which depth) on a collection prevents the addition and
+removal of direct members of this collection by non-lock-owners. This affects
+the following methods:
+
+- PUT
+- POST
+- MKCOL
+- DELETE
+
+If a collection should be locked and any of its members is already locked, this
+conflicts with the lock to be set and must result in an 423 error (Locked).
+Members that are newly created inside a locked collection or copied/moved to
+it are automatically included to the lock. This affects infinity-depth locks as
+well as zero-depth ones for direct children of the locked collection.
+
+Lock null resources
+-------------------
+
+A write lock might be acquired to a resource that does not (yet) exist. This
+is called a "lock null resource". A lock null resource only supports the
+methods:
+
+- PUT
+- MKCOL
+- OPTIONS
+- PROPFIND
+- LOCK
+- UNLOCK
+
+All other methods must return 404 (Not found) or 405 (Method not allowed).
+
+The properties of a null resource are mostly empty, except there must be
+LOCKDISCOVERY and SUPPORTEDLOCK properties. If PUT or MKCOL are issued, a null
+resource becomes a normal one. The RFC does not state if the lock stays on this
+newly created (real) resource or if it is removed.
+
+COPY/MOVE
+---------
+
+Both methods destroy locks. If a resource is moved to a locked collection, it
+is automatically added to the lock (same client assumed). Both will not work,
+if the destination is locked but no lock is owned by the client.
+
+Refresh
+=======
+
+A LOCK request must not occur twice. To refresh a lock, clients send a LOCK
+request with empty body and an If header that specifies the lock tokens to
+refresh locks for. If this occurs, the timers of the lock must be reset. A
+Timeout header might be send by the client, but the server may safely ignore
+these and simply perform a refresh as it desires.
+
+If header
+^^^^^^^^^
+
+In addition to the headers If-Match and If-None-Match, which are described in
+the HTTP/1.1 RFC, RFC 2518 (WebDAV) describes the If-Header. The If header is
+used to define conditional actions by the client, similar to the 2 headers
+named before. However, it is constructed in a much more complex and weird way.
+
+The If header is described with the following pseudo EBNF: ::
+
+ If = "If" ":" ( 1*No-tag-list | 1*Tagged-list)
+ No-tag-list = List
+ Tagged-list = Resource 1*List
+ Resource = Coded-URL
+ List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
+ State-token = Coded-URL
+ Coded-URL = "<" absoluteURI ">"
+
+It may contain entity tags (see `Entity tag support`_), lock tokens (see `Lock
+tokens`_) and combination of both. In addition the header may contain
+additional resource URIs to affect not only the main request URI. Luckily, the
+If header either containes a tagged list (including affected resource URIs) or
+a no-tag list (without resource URIs). It cannot contain a combination of
+those.
+
+Both lists (tagged and no-tag) contain a not limmited number of lock tokens
+and/or entity tags and maybe prefixed by the keyword "Not". This indicates
that the
+affected method may only be executed if the condition defined in the list does
+not match. This works similar to the If-None-Match header, specified by the
+HTTP/1.1 RFC.
+
+To illustrate this complex definition some more, some examples are presented
+and explained in following.
+
+No-tag list
+------------
+
+::
+
+ If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another
ETag"])
+
+This If header consists of 2 no-tag lists (it does not contain any resource
+URIs). The first list consists of a lock token and an entity tag, the second
+only contains an entity tag. The semantics of this example is, that the method
+containing this If header may only be executed if
+
+- either the first combination of lock token and entity tag is matched
+- or if the second entity tag is matched.
+
+Note that the first list item describes a logical AND operation, while the
+whole list concatenates its items by logical OR.
+
+Tagged list
+-----------
+
+::
+
+ COPY /resource1 HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/resource2
+ If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token>
+ [W/"A weak ETag"]) (["strong ETag"])
+ <http://www.bar.bar/random>(["another strong ETag"])
+
+This example does not only show an If header with a tagged list, but also a
+context where this could make some sense: The COPY method affects several
+resources at once. It works at least on a source (the request URI) and a
+destination (see Destination header), Additionally it can affect whole
+sub-tress, using the Depth header.
+
+The If header in this case affects 2 resources, while one of the defined
+conditions will be checked and the other won't. The first list affects the
+request URI and contains 2 elements concatenated with logical OR. The first
+item consists of an AND-combination of a lock token and an entity tag. The
+second only contains an entity tag. This is similar to the example shown above
+for the no-tag list. Except that it contains the "tagging" URI. For the
+second tag only an entity tag is listed. Anyway, this condition would not be
+checked in the request but simply be ignored, since the resource in the tag is
+not affected by the resource.
+
+Not
+---
+
+::
+
+ If: (Not <locktoken:write1> <locktoken:write2>)
+
+This simple If header only shows the definition of a "Not" affected list. The
+keyword must occur at the very begining of the affected list item. This item
+contains 2 lock tokens combined with logical AND. In clear words the requested
+affected by this If header will be executed if non of the affected resources is
+locked by either of the specified lock tokens.
+
+
+..
+ Local Variables:
+ mode: rst
+ fill-column: 79
+ End:
+ vim: et syn=rst tw=79
Propchange: trunk/Webdav/design/rfc2518_overview-1.1.txt
------------------------------------------------------------------------------
svn:eol-style = native
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
