http://www.ics.uci.edu/users/f/fielding/index.html If: http://www.ics.uci.edu/users/f/fielding/index.html (opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6) Response HTTP/1.1 204 No Content In th
http://www.ics.uci.edu/users/f/fielding/index.html
If: <
http://www.ics.uci.edu/users/f/fielding/index.html>
(<opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
>>Response
HTTP/1.1 204 No Content
In this example, even though both the source and destination are
locked, only one lock token must be submitted, for the lock on the
destination. This is because the source resource is not modified by
a COPY, and hence unaffected by the write lock. In this example, user
agent authentication has previously occurred via a mechanism outside
the scope of the HTTP protocol, in the underlying transport layer.
7.7 Write Locks and COPY/MOVE
A COPY method invocation MUST NOT duplicate any write locks active on
the source. However, as previously noted, if the COPY copies the
resource into a collection that is locked with "Depth: infinity",
then the resource will be added to the lock.
A successful MOVE request on a write locked resource MUST NOT move
the write lock with the resource. However, the resource is subject to
being added to an existing lock at the destination, as specified in
section 7.5. For example, if the MOVE makes the resource a child of a
collection that is locked with "Depth: infinity", then the resource
will be added to that collection's lock. Additionally, if a resource
locked with "Depth: infinity" is moved to a destination that is
within the scope of the same lock (e.g., within the namespace tree
covered by the lock), the moved resource will again be a added to the
lock. In both these examples, as specified in section 7.6, an If
header must be submitted containing a lock token for both the source
and destination.
7.8 Refreshing Write Locks
A client MUST NOT submit the same write lock request twice. Note
that a client is always aware it is resubmitting the same lock
request because it must include the lock token in the If header in
order to make the request for a resource that is already locked.
However, a client may submit a LOCK method with an If header but
without a body. This form of LOCK MUST only be used to "refresh" a
lock. Meaning, at minimum, that any timers associated with the lock
MUST be re-set.
A server may return a Timeout header with a lock refresh that is
different than the Timeout header returned when the lock was
originally requested. Additionally clients may submit Timeout
headers of arbitrary value with their lock refresh requests.
Servers, as always, may ignore Timeout headers submitted by the
client.
If an error is received in response to a refresh LOCK request the
client SHOULD assume that the lock was not refreshed.
8 HTTP Methods for Distributed Authoring
The following new HTTP methods use XML as a request and response
format. All DAV compliant clients and resources MUST use XML parsers
that are compliant with [REC-XML]. All XML used in either requests
or responses MUST be, at minimum, well formed. If a server receives
ill-formed XML in a request it MUST reject the entire request with a
400 (Bad Request). If a client receives ill-formed XML in a response
then it MUST NOT assume anything about the outcome of the executed
method and SHOULD treat the server as malfunctioning.
8.1 PROPFIND
The PROPFIND method retrieves properties defined on the resource
identified by the Request-URI, if the resource does not have any
internal members, or on the resource identified by the Request-URI
and potentially its member resources, if the resource is a collection
that has internal member URIs. All DAV compliant resources MUST
support the PROPFIND method and the propfind XML element (section
12.14) along with all XML elements defined for use with that element.
A client may submit a Depth header with a value of "0", "1", or
"infinity" with a PROPFIND on a collection resource with internal
member URIs. DAV compliant servers MUST support the "0", "1" and
"infinity" behaviors. By default, the PROPFIND method without a Depth
header MUST act as if a "Depth: infinity" header was included.
A client may submit a propfind XML element in the body of the request
method describing what information is being requested. It is
possible to request particular property values, all property values,
or a list of the names of the resource's properties. A client may
choose not to submit a request body. An empty PROPFIND request body
MUST be treated as a request for the names and values of all
properties.
All servers MUST support returning a response of content type
text/xml or application/xml that contains a multistatus XML element
that describes the results of the attempts to retrieve the various
properties.
If there is an error retrieving a property then a proper error result
MUST be included in the response. A request to retrieve the value of
a property which does not exist is an error and MUST be noted, if the
response uses a multistatus XML element, with a response XML element
which contains a 404 (Not Found) status value.
Consequently, the multistatus XML element for a collection resource
with member URIs MUST include a response XML element for each member
URI of the collection, to whatever depth was requested. Each response
XML element MUST contain an href XML element that gives the URI of
the resource on which the properties in the prop XML element are
defined. Results for a PROPFIND on a collection resource with
internal member URIs are returned as a flat list whose order of
entries is not significant.
In the case of allprop and propname, if a principal does not have the
right to know whether a particular property exists then the property
should be silently excluded from the response.
The results of this method SHOULD NOT be cached.
8.1.1 Example - Retrieving Named Properties
>>Request
PROPFIND /file HTTP/1.1
Host: www.foo.bar
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox/>
<R:author/>
<R:DingALing/>
<R:Random/>
</D:prop>
</D:propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.foo.bar/file</D:href>
<D:propstat>
<D:prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox>
<R:BoxType>Box type A</R:BoxType>
</R:bigbox>
<R:author>
<R:Name>J.J. Johnson</R:Name>
</R:author>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop><R:DingALing/><R:Random/></D:prop>
<D:status>HTTP/1.1 403 Forbidden</D:status>
<D:responsedescription> The user does not have access to
the DingALing property.
</D:responsedescription>
</D:propstat>
</D:response>
<D:responsedescription> There has been an access violation error.
</D:responsedescription>
</D:multistatus>
In this example, PROPFIND is executed on a non-collection resource
http://www.foo.bar/file. The propfind XML element specifies the name
of four properties whose values are being requested. In this case
only two properties were returned, since the principal issuing the
request did not have sufficient access rights to see the third and
fourth properties.
8.1.2 Example - Using allprop to Retrieve All Properties
>>Request
PROPFIND /container/ HTTP/1.1
Host: www.foo.bar
Depth: 1
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propfind xmlns:D="DAV:">
<D:allprop/>
</D:propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.foo.bar/container/</D:href>
<D:propstat>
<D:prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox>
<R:BoxType>Box type A</R:BoxType>
</R:bigbox>
<R:author>
<R:Name>Hadrian</R:Name>
</R:author>
<D:creationdate>
1997-12-01T17:42:21-08:00
</D:creationdate>
<D:displayname>
Example collection
</D:displayname>
<D:resourcetype><D:collection/></D:resourcetype>
<D:supportedlock>
<D:lockentry>
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
<D:lockentry>
<D:lockscope><D:shared/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
</D:supportedlock>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://www.foo.bar/container/front.html</D:href>
<D:propstat>
<D:prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox>
<R:BoxType>Box type B</R:BoxType>
</R:bigbox>
<D:creationdate>
1997-12-01T18:27:21-08:00
</D:creationdate>
<D:displayname>
Example HTML resource
</D:displayname>
<D:getcontentlength>
4525
</D:getcontentlength>
<D:getcontenttype>
text/html
</D:getcontenttype>
<D:getetag>
zzyzx
</D:getetag>
<D:getlastmodified>
Monday, 12-Jan-98 09:25:56 GMT
</D:getlastmodified>
<D:resourcetype/>
<D:supportedlock>
<D:lockentry>
<D:lockscope><D:exclusive/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
<D:lockentry>
<D:lockscope><D:shared/></D:lockscope>
<D:locktype><D:write/></D:locktype>
</D:lockentry>
</D:supportedlock>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
In this example, PROPFIND was invoked on the resource
http://www.foo.bar/container/ with a Depth header of 1, meaning the
request applies to the resource and its children, and a propfind XML
element containing the allprop XML element, meaning the request
should return the name and value of all properties defined on each
resource.
The resource http://www.foo.bar/container/ has six properties defined
on it:
http://www.foo.bar/boxschema/bigbox,
http://www.foo.bar/boxschema/author, DAV:creationdate,
DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
The last four properties are WebDAV-specific, defined in section 13.
Since GET is not supported on this resource, the get* properties
(e.g., getcontentlength) are not defined on this resource. The DAV-
specific properties assert that "container" was created on December
1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
(creationdate), has a name of "Example collection" (displayname), a
collection resource type (resourcetype), and supports exclusive write
and shared write locks (supportedlock).
The resource http://www.foo.bar/container/front.html has nine
properties defined on it:
http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox"
property type), DAV:creationdate, DAV:displayname,
DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
The DAV-specific properties assert that "front.html" was created on
December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
(creationdate), has a name of "Example HTML resource" (displayname),
a content length of 4525 bytes (getcontentlength), a MIME type of
"text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was
last modified on Monday, January 12, 1998, at 09:25:56 GMT
(getlastmodified), has an empty resource type, meaning that it is not
a collection (resourcetype), and supports both exclusive write and
shared write locks (supportedlock).
8.1.3 Example - Using propname to Retrieve all Property Names
>>Request
PROPFIND /container/ HTTP/1.1
Host: www.foo.bar
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<propfind xmlns="DAV:">
<propname/>
</propfind>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<multistatus xmlns="DAV:">
<response>
<href>http://www.foo.bar/container/</href>
<propstat>
<prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox/>
<R:author/>
<creationdate/>
<displayname/>
<resourcetype/>
<supportedlock/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>http://www.foo.bar/container/front.html</href>
<propstat>
<prop xmlns:R="http://www.foo.bar/boxschema/">
<R:bigbox/>
<creationdate/>
<displayname/>
<getcontentlength/>
<getcontenttype/>
<getetag/>
<getlastmodified/>
<resourcetype/>
<supportedlock/>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
In this example, PROPFIND is invoked on the collection resource
http://www.foo.bar/container/, with a propfind XML element containing
the propname XML element, meaning the name of all properties should
be returned. Since no Depth header is present, it assumes its
default value of "infinity", meaning the name of the properties on
the collection and all its progeny should be returned.
Consistent with the previous example, resource
http://www.foo.bar/container/ has six properties defined on it,
http://www.foo.bar/boxschema/bigbox,
http://www.foo.bar/boxschema/author, DAV:creationdate,
DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
The resource http://www.foo.bar/container/index.html, a member of the
"container" collection, has nine properties defined on it,
http://www.foo.bar/boxschema/bigbox, DAV:creationdate,
DAV:displayname, DAV:getcontentlength, DAV:getcontenttype,
DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and
DAV:supportedlock.
This example also demonstrates the use of XML namespace scoping, and
the default namespace. Since the "xmlns" attribute does not contain
an explicit "shorthand name" (prefix) letter, the namespace applies
by default to all enclosed elements. Hence, all elements which do
not explicitly state the namespace to which they belong are members
of the "DAV:" namespace schema.
8.2 PROPPATCH
The PROPPATCH method processes instructions specified in the request
body to set and/or remove properties defined on the resource
identified by the Request-URI.
All DAV compliant resources MUST support the PROPPATCH method and
MUST process instructions that are specified using the
propertyupdate, set, and remove XML elements of the DAV schema.
Execution of the directives in this method is, of course, subject to
access control constraints. DAV compliant resources SHOULD support
the setting of arbitrary dead properties.
The request message body of a PROPPATCH method MUST contain the
propertyupdate XML element. Instruction processing MUST occur in the
order instructions are received (i.e., from top to bottom).
Instructions MUST either all be executed or none executed. Thus if
any error occurs during processing all executed instructions MUST be
undone and a proper error result returned. Instruction processing
details can be found in the definition of the set and remove
instructions in section 12.13.
8.2.1 Status Codes for use with 207 (Multi-Status)
The following are examples of response codes one would expect to be
used in a 207 (Multi-Status) response for this method. Note,
however, that unless explicitly prohibited any 2/3/4/5xx series
response code may be used in a 207 (Multi-Status) response.
200 (OK) - The command succeeded. As there can be a mixture of sets
and removes in a body, a 201 (Created) seems inappropriate.
403 (Forbidden) - The client, for reasons the server chooses not to
specify, cannot alter one of the properties.
409 (Conflict) - The client has provided a value whose semantics are
not appropriate for the property. This includes trying to set read-
only properties.
423 (Locked) - The specified resource is locked and the client either
is not a lock owner or the lock type requires a lock token to be
submitted and the client did not submit it.
507 (Insufficient Storage) - The server did not have sufficient space
to record the property.
8.2.2 Example - PROPPATCH
>>Request
PROPPATCH /bar.html HTTP/1.1
Host: www.foo.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:propertyupdate xmlns:D="DAV:"
xmlns:Z="
http://www.w3.com/standards/z39.50/">
<D:set>
<D:prop>
<Z:authors>
<Z:Author>Jim Whitehead</Z:Author>
<Z:Author>Roy Fielding</Z:Author>
</Z:authors>
</D:prop>
</D:set>
<D:remove>
<D:prop><Z:Copyright-Owner/></D:prop>
</D:remove>
</D:propertyupdate>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
xmlns:Z="
http://www.w3.com/standards/z39.50">
<D:response>
<D:href>http://www.foo.com/bar.html</D:href>
<D:propstat>
<D:prop><Z:Authors/></D:prop>
<D:status>HTTP/1.1 424 Failed Dependency</D:status>
</D:propstat>
<D:propstat>
<D:prop><Z:Copyright-Owner/></D:prop>
<D:status>HTTP/1.1 409 Conflict</D:status>
</D:propstat>
<D:responsedescription> Copyright Owner can not be deleted or
altered.</D:responsedescription>
</D:response>
</D:multistatus>
In this example, the client requests the server to set the value of
the
http://www.w3.com/standards/z39.50/Authors property, and to
remove the property
http://www.w3.com/standards/z39.50/Copyright-
Owner. Since the Copyright-Owner property could not be removed, no
property modifications occur. The 424 (Failed Dependency) status
code for the Authors property indicates this action would have
succeeded if it were not for the conflict with removing the
Copyright-Owner property.
8.3 MKCOL Method
The MKCOL method is used to create a new collection. All DAV
compliant resources MUST support the MKCOL method.
8.3.1 Request
MKCOL creates a new collection resource at the location specified by
the Request-URI. If the resource identified by the Request-URI is
non-null then the MKCOL MUST fail. During MKCOL processing, a server
MUST make the Request-URI a member of its parent collection, unless
the Request-URI is "/". If no such ancestor exists, the method MUST
fail. When the MKCOL operation creates a new collection resource,
all ancestors MUST already exist, or the method MUST fail with a 409
(Conflict) status code. For example, if a request to create
collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists,
the request must fail.
When MKCOL is invoked without a request body, the newly created
collection SHOULD have no members.
A MKCOL request message may contain a message body. The behavior of
a MKCOL request when the body is present is limited to creating
collections, members of a collection, bodies of members and
properties on the collections or members. If the server receives a
MKCOL request entity type it does not support or understand it MUST
respond with a 415 (Unsupported Media Type) status code. The exact
behavior of MKCOL for various request media types is undefined in
this document, and will be specified in separate documents.
8.3.2 Status Codes
Responses from a MKCOL request MUST NOT be cached as MKCOL has non-
idempotent semantics.
201 (Created) - The collection or structured resource was created in
its entirety.
403 (Forbidden) - This indicates at least one of two conditions: 1)
the server does not allow the creation of collections at the given
location in its namespace, or 2) the parent collection of the
Request-URI exists but cannot accept members.
405 (Method Not Allowed) - MKCOL can only be executed on a
deleted/non-existent resource.
409 (Conflict) - A collection cannot be made at the Request-URI until
one or more intermediate collections have been created.
415 (Unsupported Media Type)- The server does not support the request
type of the body.
507 (Insufficient Storage) - The resource does not have sufficient
space to record the state of the resource after the execution of this
method.
8.3.3 Example - MKCOL
This example creates a collection called /webdisc/xfiles/ on the
server www.server.org.
>>Request
MKCOL /webdisc/xfiles/ HTTP/1.1
Host: www.server.org
>>Response
HTTP/1.1 201 Created
8.4 GET, HEAD for Collections
The semantics of GET are unchanged when applied to a collection,
since GET is defined as, "retrieve whatever information (in the form
of an entity) is identified by the Request-URI" [
RFC2068]. GET when
applied to a collection may return the contents of an "index.html"
resource, a human-readable view of the contents of the collection, or
something else altogether. Hence it is possible that the result of a
GET on a collection will bear no correlation to the membership of the
collection.
Similarly, since the definition of HEAD is a GET without a response
message body, the semantics of HEAD are unmodified when applied to
collection resources.
8.5 POST for Collections
Since by definition the actual function performed by POST is
determined by the server and often depends on the particular
resource, the behavior of POST when applied to collections cannot be
meaningfully modified because it is largely undefined. Thus the
semantics of POST are unmodified when applied to a collection.
8.6 DELETE
8.6.1 DELETE for Non-Collection Resources
If the DELETE method is issued to a non-collection resource whose
URIs are an internal member of one or more collections, then during
DELETE processing a server MUST remove any URI for the resource
identified by the Request-URI from collections which contain it as a
member.
8.6.2 DELETE for Collections
The DELETE method on a collection MUST act as if a "Depth: infinity"
header was used on it. A client MUST NOT submit a Depth header with
a DELETE on a collection with any value but infinity.
DELETE instructs that the collection specified in the Request-URI and
all resources identified by its internal member URIs are to be
deleted.
If any resource identified by a member URI cannot be deleted then all
of the member's ancestors MUST NOT be deleted, so as to maintain
namespace consistency.
Any headers included with DELETE MUST be applied in processing every
resource to be deleted.
When the DELETE method has completed processing it MUST result in a
consistent namespace.
If an error occurs with a resource other than the resource identified
in the Request-URI then the response MUST be a 207 (Multi-Status).
424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi-
Status). They can be safely left out because the client will know
that the ancestors of a resource could not be deleted when the client
receives an error for the ancestor's progeny. Additionally 204 (No
Content) errors SHOULD NOT be returned in the 207 (Multi-Status).
The reason for this prohibition is that 204 (No Content) is the
default success code.
8.6.2.1 Example - DELETE
>>Request
DELETE /container/ HTTP/1.1
Host: www.foo.bar
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:multistatus xmlns:d="DAV:">
<d:response>
<d:href>http://www.foo.bar/container/resource3</d:href>
<d:status>HTTP/1.1 423 Locked</d:status>
</d:response>
</d:multistatus>
In this example the attempt to delete
http://www.foo.bar/container/resource3 failed because it is locked,
and no lock token was submitted with the request. Consequently, the
attempt to delete http://www.foo.bar/container/ also failed. Thus the
client knows that the attempt to delete http://www.foo.bar/container/
must have also failed since the parent can not be deleted unless its
child has also been deleted. Even though a Depth header has not been
included, a depth of infinity is assumed because the method is on a
collection.
8.7 PUT
8.7.1 PUT for Non-Collection Resources
A PUT performed on an existing resource replaces the GET response
entity of the resource. Properties defined on the resource may be
recomputed during PUT processing but are not otherwise affected. For
example, if a server recognizes the content type of the request body,
it may be able to automatically extract information that could be
profitably exposed as properties.
A PUT that would result in the creation of a resource without an
appropriately scoped parent collection MUST fail with a 409
(Conflict).
8.7.2 PUT for Collections
As defined in the HTTP/1.1 specification [
RFC2068], the "PUT method
requests that the enclosed entity be stored under the supplied
Request-URI." Since submission of an entity representing a
collection would implicitly encode creation and deletion of
resources, this specification intentionally does not define a
transmission format for creating a collection using PUT. Instead,
the MKCOL method is defined to create collections.
When the PUT operation creates a new non-collection resource all
ancestors MUST already exist. If all ancestors do not exist, the
method MUST fail with a 409 (Conflict) status code. For example, if
resource /a/b/c/d.html is to be created and /a/b/c/ does not exist,
then the request must fail.
8.8 COPY Method
The COPY method creates a duplicate of the source resource,
identified by the Request-URI, in the destination resource,
identified by the URI in the Destination header. The Destination
header MUST be present. The exact behavior of the COPY method
depends on the type of the source resource.
All WebDAV compliant resources MUST support the COPY method.
However, support for the COPY method does not guarantee the ability
to copy a resource. For example, separate programs may control
resources on the same server. As a result, it may not be possible to
copy a resource to a location that appears to be on the same server.
8.8.1 COPY for HTTP/1.1 resources
When the source resource is not a collection the result of the COPY
method is the creation of a new resource at the destination whose
state and behavior match that of the source resource as closely as
possible. After a successful COPY invocation, all properties on the
source resource MUST be duplicated on the destination resource,
subject to modifying headers and XML elements, following the
definition for copying properties. Since the environment at the
destination may be different than at the source due to factors
outside the scope of control of the server, such as the absence of
resources required for correct operation, it may not be possible to
completely duplicate the behavior of the resource at the destination.
Subsequent alterations to the destination resource will not modify
the source resource. Subsequent alterations to the source resource
will not modify the destination resource.
8.8.2. COPY for Properties
The following section defines how properties on a resource are
handled during a COPY operation.
Live properties SHOULD be duplicated as identically behaving live
properties at the destination resource. If a property cannot be
copied live, then its value MUST be duplicated, octet-for-octet, in
an identically named, dead property on the destination resource
subject to the effects of the propertybehavior XML element.
The propertybehavior XML element can specify that properties are
copied on best effort, that all live properties must be successfully
copied or the method must fail, or that a specified list of live
properties must be successfully copied or the method must fail. The
propertybehavior XML element is defined in section 12.12.
8.8.3 COPY for Collections
The COPY method on a collection without a Depth header MUST act as if
a Depth header with value "infinity" was included. A client may
submit a Depth header on a COPY on a collection with a value of "0"
or "infinity". DAV compliant servers MUST support the "0" and
"infinity" Depth header behaviors.
A COPY of depth infinity instructs that the collection resource
identified by the Request-URI is to be copied to the location
identified by the URI in the Destination header, and all its internal
member resources are to be copied to a location relative to it,
recursively through all levels of the collection hierarchy.
A COPY of "Depth: 0" only instructs that the collection and its
properties but not resources identified by its internal member URIs,
are to be copied.
Any headers included with a COPY MUST be applied in processing every
resource to be copied with the exception of the Destination header.
The Destination header only specifies the destination URI for the
Request-URI. When applied to members of the collection identified by
the Request-URI the value of Destination is to be modified to reflect
the current location in the hierarchy. So, if the Request- URI is
/a/ with Host header value
http://fun.com/ and the Destination is
http://fun.com/b/ then when
http://fun.com/a/c/d is processed it must
use a Destination of
http://fun.com/b/c/d.
When the COPY method has completed processing it MUST have created a
consistent namespace at the destination (see section 5.1 for the
definition of namespace consistency). However, if an error occurs
while copying an internal collection, the server MUST NOT copy any
resources identified by members of this collection (i.e., the server
must skip this subtree), as this would create an inconsistent
namespace. After detecting an error, the COPY operation SHOULD try to
finish as much of the original copy operation as possible (i.e., the
server should still attempt to copy other subtrees and their members,
that are not descendents of an error-causing collection). So, for
example, if an infinite depth copy operation is performed on
collection /a/, which contains collections /a/b/ and /a/c/, and an
error occurs copying /a/b/, an attempt should still be made to copy
/a/c/. Similarly, after encountering an error copying a non-
collection resource as part of an infinite depth copy, the server
SHOULD try to finish as much of the original copy operation as
possible.
If an error in executing the COPY method occurs with a resource other
than the resource identified in the Request-URI then the response
MUST be a 207 (Multi-Status).
The 424 (Failed Dependency) status code SHOULD NOT be returned in the
207 (Multi-Status) response from a COPY method. These responses can
be safely omitted because the client will know that the progeny of a
resource could not be copied when the client receives an error for
the parent. Additionally 201 (Created)/204 (No Content) status codes
SHOULD NOT be returned as values in 207 (Multi-Status) responses from
COPY methods. They, too, can be safely omitted because they are the
default success codes.
8.8.4 COPY and the Overwrite Header
If a resource exists at the destination and the Overwrite header is
"T" then prior to performing the copy the server MUST perform a
DELETE with "Depth: infinity" on the destination resource. If the
Overwrite header is set to "F" then the operation will fail.
8.8.5 Status Codes
201 (Created) - The source resource was successfully copied. The
copy operation resulted in the creation of a new resource.
204 (No Content) - The source resource was successfully copied to a
pre-existing destination resource.
403 (Forbidden) _ The source and destination URIs are the same.
409 (Conflict) _ A resource cannot be created at the destination
until one or more intermediate collections have been created.
412 (Precondition Failed) - The server was unable to maintain the
liveness of the properties listed in the propertybehavior XML element
or the Overwrite header is "F" and the state of the destination
resource is non-null.
423 (Locked) - The destination resource was locked.
502 (Bad Gateway) - This may occur when the destination is on another
server and the destination server refuses to accept the resource.
507 (Insufficient Storage) - The destination resource does not have
sufficient space to record the state of the resource after the
execution of this method.
8.8.6 Example - COPY with Overwrite
This example shows resource
http://www.ics.uci.edu/~fielding/index.html being copied to the
location
http://www.ics.uci.edu/users/f/fielding/index.html. The 204
(No Content) status code indicates the existing resource at the
destination was overwritten.
>>Request
COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination:
http://www.ics.uci.edu/users/f/fielding/index.html
>>Response
HTTP/1.1 204 No Content
8.8.7 Example - COPY with No Overwrite
The following example shows the same copy operation being performed,
but with the Overwrite header set to "F." A response of 412
(Precondition Failed) is returned because the destination resource
has a non-null state.
>>Request
COPY /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination:
http://www.ics.uci.edu/users/f/fielding/index.html
Overwrite: F
>>Response
HTTP/1.1 412 Precondition Failed
8.8.8 Example - COPY of a Collection
>>Request
COPY /container/ HTTP/1.1
Host: www.foo.bar
Destination: http://www.foo.bar/othercontainer/
Depth: infinity
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:propertybehavior xmlns:d="DAV:">
<d:keepalive>*</d:keepalive>
</d:propertybehavior>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:multistatus xmlns:d="DAV:">
<d:response>
<d:href>http://www.foo.bar/othercontainer/R2/</d:href>
<d:status>HTTP/1.1 412 Precondition Failed</d:status>
</d:response>
</d:multistatus>
The Depth header is unnecessary as the default behavior of COPY on a
collection is to act as if a "Depth: infinity" header had been
submitted. In this example most of the resources, along with the
collection, were copied successfully. However the collection R2
failed, most likely due to a problem with maintaining the liveness of
properties (this is specified by the propertybehavior XML element).
Because there was an error copying R2, none of R2's members were
copied. However no errors were listed for those members due to the
error minimization rules given in section 8.8.3.
8.9 MOVE Method
The MOVE operation on a non-collection resource is the logical
equivalent of a copy (COPY), followed by consistency maintenance
processing, followed by a delete of the source, where all three
actions are performed atomically. The consistency maintenance step
allows the server to perform updates caused by the move, such as
updating all URIs other than the Request-URI which identify the
source resource, to point to the new destination resource.
Consequently, the Destination header MUST be present on all MOVE
methods and MUST follow all COPY requirements for the COPY part of
the MOVE method. All DAV compliant resources MUST support the MOVE
method. However, support for the MOVE method does not guarantee the
ability to move a resource to a particular destination.
For example, separate programs may actually control different sets of
resources on the same server. Therefore, it may not be possible to
move a resource within a namespace that appears to belong to the same
server.
If a resource exists at the destination, the destination resource
will be DELETEd as a side-effect of the MOVE operation, subject to
the restrictions of the Overwrite header.
8.9.1 MOVE for Properties
The behavior of properties on a MOVE, including the effects of the
propertybehavior XML element, MUST be the same as specified in
section 8.8.2.
8.9.2 MOVE for Collections
A MOVE with "Depth: infinity" instructs that the collection
identified by the Request-URI be moved to the URI specified in the
Destination header, and all resources identified by its internal
member URIs are to be moved to locations relative to it, recursively
through all levels of the collection hierarchy.
The MOVE method on a collection MUST act as if a "Depth: infinity"
header was used on it. A client MUST NOT submit a Depth header on a
MOVE on a collection with any value but "infinity".
Any headers included with MOVE MUST be applied in processing every
resource to be moved with the exception of the Destination header.
The behavior of the Destination header is the same as given for COPY
on collections.
When the MOVE method has completed processing it MUST have created a
consistent namespace at both the source and destination (see section
5.1 for the definition of namespace consistency). However, if an
error occurs while moving an internal collection, the server MUST NOT
move any resources identified by members of the failed collection
(i.e., the server must skip the error-causing subtree), as this would
create an inconsistent namespace. In this case, after detecting the
error, the move operation SHOULD try to finish as much of the
original move as possible (i.e., the server should still attempt to
move other subtrees and the resources identified by their members,
that are not descendents of an error-causing collection). So, for
example, if an infinite depth move is performed on collection /a/,
which contains collections /a/b/ and /a/c/, and an error occurs
moving /a/b/, an attempt should still be made to try moving /a/c/.
Similarly, after encountering an error moving a non-collection
resource as part of an infinite depth move, the server SHOULD try to
finish as much of the original move operation as possible.
If an error occurs with a resource other than the resource identified
in the Request-URI then the response MUST be a 207 (Multi-Status).
The 424 (Failed Dependency) status code SHOULD NOT be returned in the
207 (Multi-Status) response from a MOVE method. These errors can be
safely omitted because the client will know that the progeny of a
resource could not be moved when the client receives an error for the
parent. Additionally 201 (Created)/204 (No Content) responses SHOULD
NOT be returned as values in 207 (Multi-Status) responses from a
MOVE. These responses can be safely omitted because they are the
default success codes.
8.9.3 MOVE and the Overwrite Header
If a resource exists at the destination and the Overwrite header is
"T" then prior to performing the move the server MUST perform a
DELETE with "Depth: infinity" on the destination resource. If the
Overwrite header is set to "F" then the operation will fail.
8.9.4 Status Codes
201 (Created) - The source resource was successfully moved, and a new
resource was created at the destination.
204 (No Content) - The source resource was successfully moved to a
pre-existing destination resource.
403 (Forbidden) _ The source and destination URIs are the same.
409 (Conflict) _ A resource cannot be created at the destination
until one or more intermediate collections have been created.
412 (Precondition Failed) - The server was unable to maintain the
liveness of the properties listed in the propertybehavior XML element
or the Overwrite header is "F" and the state of the destination
resource is non-null.
423 (Locked) - The source or the destination resource was locked.
502 (Bad Gateway) - This may occur when the destination is on another
server and the destination server refuses to accept the resource.
8.9.5 Example - MOVE of a Non-Collection
This example shows resource
http://www.ics.uci.edu/~fielding/index.html being moved to the
location
http://www.ics.uci.edu/users/f/fielding/index.html. The
contents of the destination resource would have been overwritten if
the destination resource had been non-null. In this case, since
there was nothing at the destination resource, the response code is
201 (Created).
>>Request
MOVE /~fielding/index.html HTTP/1.1
Host: www.ics.uci.edu
Destination:
http://www.ics.uci.edu/users/f/fielding/index.html
>>Response
HTTP/1.1 201 Created
Location:
http://www.ics.uci.edu/users/f/fielding/index.html
8.9.6 Example - MOVE of a Collection
>>Request
MOVE /container/ HTTP/1.1
Host: www.foo.bar
Destination: http://www.foo.bar/othercontainer/
Overwrite: F
If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
(<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:propertybehavior xmlns:d='DAV:'>
<d:keepalive>*</d:keepalive>
</d:propertybehavior>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<d:multistatus xmlns:d='DAV:'>
<d:response>
<d:href>http://www.foo.bar/othercontainer/C2/</d:href>
<d:status>HTTP/1.1 423 Locked</d:status>
</d:response>
</d:multistatus>
In this example the client has submitted a number of lock tokens with
the request. A lock token will need to be submitted for every
resource, both source and destination, anywhere in the scope of the
method, that is locked. In this case the proper lock token was not
submitted for the destination http://www.foo.bar/othercontainer/C2/.
This means that the resource /container/C2/ could not be moved.
Because there was an error copying /container/C2/, none of
/container/C2's members were copied. However no errors were listed
for those members due to the error minimization rules given in
section 8.8.3. User agent authentication has previously occurred via
a mechanism outside the scope of the HTTP protocol, in an underlying
transport layer.
8.10 LOCK Method
The following sections describe the LOCK method, which is used to
take out a lock of any access type. 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 which supports the LOCK method MUST, at minimum, support
the XML request and response formats defined herein.
8.10.1 Operation
A LOCK method invocation creates the lock specified by the lockinfo
XML element on the Request-URI. Lock method requests SHOULD have a
XML request body which contains an owner XML element for this lock
request, unless this is a refresh request. The LOCK request may have
a Timeout header.
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. The response MUST contain
the value of the lockdiscovery property in a prop XML element.
In order to indicate the lock token associated with a newly created
lock, a Lock-Token response header MUST be included in the response
for every successful LOCK request for a new lock. Note that the
Lock-Token header would not be returned in the response for a
successful refresh LOCK request because a new lock was not created.
8.10.2 The Effect of Locks on Properties and Collections
The scope of a lock is the entire state of the resource, including
its body and associated properties. As a result, a lock on a
resource MUST also lock the resource's properties.
For collections, a lock also affects the ability to add or remove
members. The nature of the effect depends upon the type of access
control involved.
8.10.3 Locking Replicated Resources
A resource may be made available through more than one URI. However
locks apply to resources, not URIs. Therefore a LOCK request on a
resource MUST NOT succeed if can not be honored by all the URIs
through which the resource is addressable.
8.10.4 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 internal members, all the way down
the hierarchy, are to be locked. A successful result MUST return a
single lock token which represents all the resources that have been
locked. If an UNLOCK is successfully executed on this token, all
associated resources are unlocked. If the lock cannot be granted to
all resources, a 409 (Conflict) status code MUST be returned with a
response entity body containing a multistatus XML element describing
which resource(s) prevented the lock from being granted. Hence,
partial success is not an option. Either the entire hierarchy is
locked or no resources are locked.
If no Depth header is submitted on a LOCK request then the request
MUST act as if a "Depth:infinity" had been submitted.
8.10.5 Interaction with other Methods
The interaction of a LOCK with various methods is dependent upon the
lock type. However, independent of lock type, a successful DELETE of
a resource MUST cause all of its locks to be removed.
8.10.6 Lock Compatibility Table
The table below describes the behavior that occurs when a lock
request is made on a resource.
Current lock state/ | Shared Lock | Exclusive
Lock request | | Lock
=====================+=================+==============
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 the lock must not
be granted.
8.10.7 Status Codes
200 (OK) - The lock request succeeded and the value of the
lockdiscovery property is included in the body.
412 (Precondition Failed) - The included lock token was not
enforceable on this resource or the server could not satisfy the
request in the lockinfo XML element.
423 (Locked) - The resource is locked, so the method has been
rejected.
8.10.8 Example - Simple Lock Request
>>Request
LOCK /workspace/webdav/proposal.doc HTTP/1.1
Host: webdav.sb.aol.com
Timeout: Infinite, Second-4100000000
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Authorization: Digest username="ejw",
realm="