rfc2518.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

Goland, et al.              Standards Track                    [Page 10]

RFC 2518                         WEBDAV                    February 1999


5  Collections of Web Resources

   This section provides a description of a new type of Web resource,
   the collection, and discusses its interactions with the HTTP URL
   namespace. The purpose of a collection resource is to model
   collection-like objects (e.g., file system directories) within a
   server's namespace.

   All DAV compliant resources MUST support the HTTP URL namespace model
   specified herein.

5.1 HTTP URL Namespace Model

   The HTTP URL namespace is a hierarchical namespace where the
   hierarchy is delimited with the "/" character.

   An HTTP URL namespace is said to be consistent if it meets the
   following conditions: for every URL in the HTTP hierarchy there
   exists a collection that contains that URL as an internal member.
   The root, or top-level collection of the namespace under
   consideration is exempt from the previous rule.

   Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL
   namespace be consistent.  However, certain WebDAV methods are
   prohibited from producing results that cause namespace
   inconsistencies.

   Although implicit in [RFC2068] and [RFC2396], any resource, including
   collection resources, MAY be identified by more than one URI. For
   example, a resource could be identified by multiple HTTP URLs.

5.2 Collection Resources

   A collection is a resource whose state consists of at least a list of
   internal member URIs and a set of properties, but which may have
   additional state such as entity bodies returned by GET.  An internal
   member URI MUST be immediately relative to a base URI of the
   collection.  That is, the internal member URI is equal to a
   containing collection's URI plus an additional segment for non-
   collection resources, or additional segment plus trailing slash "/"
   for collection resources, where segment is defined in section 3.3 of
   [RFC2396].

   Any given internal member URI MUST only belong to the collection
   once, i.e., it is illegal to have multiple instances of the same URI
   in a collection.  Properties defined on collections behave exactly as
   do properties on non-collection resources.




Goland, et al.              Standards Track                    [Page 11]

RFC 2518                         WEBDAV                    February 1999


   For all WebDAV compliant resources A and B, identified by URIs U and
   V, for which U is immediately relative to V, B MUST be a collection
   that has U as an internal member URI. So, if the resource with URL
   http://foo.com/bar/blah is WebDAV compliant and if the resource with
   URL http://foo.com/bar/ is WebDAV compliant then the resource with
   URL http://foo.com/bar/ must be a collection and must contain URL
   http://foo.com/bar/blah as an internal member.

   Collection resources MAY list the URLs of non-WebDAV compliant
   children in the HTTP URL namespace hierarchy as internal members but
   are not required to do so. For example, if the resource with URL
   http://foo.com/bar/blah is not WebDAV compliant and the URL
   http://foo.com/bar/ identifies a collection then URL
   http://foo.com/bar/blah may or may not be an internal member of the
   collection with URL http://foo.com/bar/.

   If a WebDAV compliant resource has no WebDAV compliant children in
   the HTTP URL namespace hierarchy then the WebDAV compliant resource
   is not required to be a collection.

   There is a standing convention that when a collection is referred to
   by its name without a trailing slash, the trailing slash is
   automatically appended.  Due to this, a resource may accept a URI
   without a trailing "/" to point to a collection. In this case it
   SHOULD return a content-location header in the response pointing to
   the URI ending with the "/".  For example, if a client invokes a
   method on http://foo.bar/blah (no trailing slash), the resource
   http://foo.bar/blah/ (trailing slash) may respond as if the operation
   were invoked on it, and should return a content-location header with
   http://foo.bar/blah/ in it.  In general clients SHOULD use the "/"
   form of collection names.

   A resource MAY be a collection but not be WebDAV compliant.  That is,
   the resource may comply with all the rules set out in this
   specification regarding how a collection is to behave without
   necessarily supporting all methods that a WebDAV compliant resource
   is required to support.  In such a case the resource may return the
   DAV:resourcetype property with the value DAV:collection but MUST NOT
   return a DAV header containing the value "1" on an OPTIONS response.

5.3 Creation and Retrieval of Collection Resources

   This document specifies the MKCOL method to create new collection
   resources, rather than using the existing HTTP/1.1 PUT or POST
   method, for the following reasons:






Goland, et al.              Standards Track                    [Page 12]

RFC 2518                         WEBDAV                    February 1999


   In HTTP/1.1, the PUT method is defined to store the request body at
   the location specified by the Request-URI.  While a description
   format for a collection can readily be constructed for use with PUT,
   the implications of sending such a description to the server are
   undesirable.  For example, if a description of a collection that
   omitted some existing resources were PUT to a server, this might be
   interpreted as a command to remove those members.  This would extend
   PUT to perform DELETE functionality, which is undesirable since it
   changes the semantics of PUT, and makes it difficult to control
   DELETE functionality with an access control scheme based on methods.

   While the POST method is sufficiently open-ended that a "create a
   collection" POST command could be constructed, this is undesirable
   because it would be difficult to separate access control for
   collection creation from other uses of POST.

   The exact definition of the behavior of GET and PUT on collections is
   defined later in this document.

5.4 Source Resources and Output Resources

   For many resources, the entity returned by a GET method exactly
   matches the persistent state of the resource, for example, a GIF file
   stored on a disk.  For this simple case, the URI at which a resource
   is accessed is identical to the URI at which the source (the
   persistent state) of the resource is accessed.  This is also the case
   for HTML source files that are not processed by the server prior to
   transmission.

   However, the server can sometimes process HTML resources before they
   are transmitted as a return entity body.  For example, a server-
   side-include directive within an HTML file might instruct a server to
   replace the directive with another value, such as the current date.
   In this case, what is returned by GET (HTML plus date) differs from
   the persistent state of the resource (HTML plus directive).
   Typically there is no way to access the HTML resource containing the
   unprocessed directive.

   Sometimes the entity returned by GET is the output of a data-
   producing process that is described by one or more source resources
   (that may not even have a location in the URI namespace).  A single
   data-producing process may dynamically generate the state of a
   potentially large number of output resources.  An example of this is
   a CGI script that describes a "finger" gateway process that maps part
   of the namespace of a server into finger requests, such as
   http://www.foo.bar.org/finger_gateway/user@host.





Goland, et al.              Standards Track                    [Page 13]

RFC 2518                         WEBDAV                    February 1999


   In the absence of distributed authoring capabilities, it is
   acceptable to have no mapping of source resource(s) to the URI
   namespace. In fact, preventing access to the source resource(s) has
   desirable security benefits.  However, if remote editing of the
   source resource(s) is desired, the source resource(s) should be given
   a location in the URI namespace.  This source location should not be
   one of the locations at which the generated output is retrievable,
   since in general it is impossible for the server to differentiate
   requests for source resources from requests for process output
   resources.  There is often a many-to-many relationship between source
   resources and output resources.

   On WebDAV compliant servers the URI of the source resource(s) may be
   stored in a link on the output resource with type DAV:source (see
   section 13.10 for a description of the source link property).
   Storing the source URIs in links on the output resources places the
   burden of discovering the source on the authoring client.  Note that
   the value of a source link is not guaranteed to point to the correct
   source.  Source links may break or incorrect values may be entered.
   Also note that not all servers will allow the client to set the
   source link value.  For example a server which generates source links
   on the fly for its CGI files will most likely not allow a client to
   set the source link value.

6  Locking

   The ability to lock a resource provides a mechanism for serializing
   access to that resource.  Using a lock, an authoring client can
   provide a reasonable guarantee that another principal will not modify
   a resource while it is being edited.  In this way, a client can
   prevent the "lost update" problem.

   This specification allows locks to vary over two client-specified
   parameters, the number of principals involved (exclusive vs. shared)
   and the type of access to be granted. This document defines locking
   for only one access type, write. However, the syntax is extensible,
   and permits the eventual specification of locking for other access
   types.

6.1 Exclusive Vs. Shared 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
   principal.  The need for this arbitration results from a desire to
   avoid having to merge results.






Goland, et al.              Standards Track                    [Page 14]

RFC 2518                         WEBDAV                    February 1999


   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 principals to receive a lock.  Hence any
   principal 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.

   Starting with every possible principal on the Internet, in most
   situations the vast majority of these principals will not have write
   access to a given resource.  Of the small number who do have write
   access, some principals may decide to guarantee their edits are free
   from overwrite conflicts by using exclusive write locks.  Others may
   decide they trust their collaborators will not overwrite their work
   (the potential set of collaborators being the set of principals who
   have write permission) and use a shared lock, which informs their
   collaborators that a principal may be working on the resource.

   The WebDAV extensions to HTTP do not need to provide all of the
   communications paths necessary for principals to coordinate their
   activities.  When using shared locks, principals may use any out of
   band communication channel to coordinate their work (e.g., face-to-
   face interaction, written notes, post-it notes on the screen,
   telephone conversation, Email, etc.)  The intent of a shared lock is
   to let collaborators know who else may be working on a resource.

   Shared locks are included because experience from web distributed
   authoring systems has indicated that exclusive locks are often too
   rigid.  An exclusive lock is used to enforce a particular editing
   process: take out an exclusive lock, read the resource, perform
   edits, write the resource, release the lock.  This editing process