Was this article helpful?

COPY

Last modified 00:16, 7 Oct 2008

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.

This method is idempotent, but not safe (see Section 9.1 of [RFC2616]). Responses to this method MUST NOT be cached.

COPY for Non-collection 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. 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.

COPY for Properties

After a successful COPY invocation, all dead properties on the source resource SHOULD be duplicated on the destination resource. Live properties described in this document SHOULD be duplicated as identically behaving live properties at the destination resource, but not necessarily with the same values. Servers SHOULD NOT convert live properties into dead properties on the destination resource, because clients may then draw incorrect conclusions about the state or functionality of a resource. Note that some live properties are defined such that the absence of the property has a specific meaning (e.g., a flag with one meaning if present, and the opposite if absent), and in these cases, a successful COPY might result in the property being reported as "Not Found" in subsequent requests.

When the destination is an unmapped URL, a COPY operation creates a new resource much like a PUT operation does. Live properties that are related to resource creation (such as DAV:creationdate) should have their values set accordingly.

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". Servers MUST support the "0" and "infinity" Depth header behaviors on WebDAV-compliant resources.

An infinite-depth COPY 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. Note that an infinite-depth COPY of /A/ into /A/B/ could lead to infinite recursion if not handled correctly.

A COPY of "Depth: 0" only instructs that the collection and its properties, but not resources identified by its internal member URLs, 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://example.com/ and the Destination is http://example.com/b/, then when http://example.com/a/c/d is processed, it must use a Destination of http://example.com/b/c/d.

When the COPY method has completed processing, it MUST have created a consistent URL 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 descendants 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), and the URL of the resource causing the failure MUST appear with the specific error.

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.

COPY and Overwriting Destination Resources

If a COPY request has an Overwrite header with a value of "F", and a resource exists at the Destination URL, the server MUST fail the request.

When a server executes a COPY request and overwrites a destination resource, the exact behavior MAY depend on many factors, including WebDAV extension capabilities (see particularly [RFC3253]). For example, when an ordinary resource is overwritten, the server could delete the target resource before doing the copy, or could do an in-place overwrite to preserve live properties.

When a collection is overwritten, the membership of the destination collection after the successful COPY request MUST be the same membership as the source collection immediately before the COPY. Thus, merging the membership of the source and destination collections together in the destination is not a compliant behavior.

In general, if clients require the state of the destination URL to be wiped out prior to a COPY (e.g., to force live properties to be reset), then the client could send a DELETE to the destination before the COPY request to ensure this reset.

Status Codes

In addition to the general status codes possible, the following status codes have specific applicability to COPY:

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 preexisting destination resource.

207 (Multi-Status) - Multiple resources were to be affected by the COPY, but errors on some of them prevented the operation from taking place. Specific error messages, together with the most appropriate of the source and destination URLs, appear in the body of the multi-status response. For example, if a destination resource was locked and could not be overwritten, then the destination resource URL appears with the 423 (Locked) status.

403 (Forbidden) - The operation is forbidden. A special case for COPY could be that the source and destination resources are the same resource.

409 (Conflict) - A resource cannot be created at the destination until one or more intermediate collections have been created. The server MUST NOT create those intermediate collections automatically.

412 (Precondition Failed) - A precondition header check failed, e.g., the Overwrite header is "F" and the destination URL is already mapped to a resource.

423 (Locked) - The destination resource, or resource within the destination collection, was locked. This response SHOULD contain the 'lock-token-submitted' precondition element.

502 (Bad Gateway) - This may occur when the destination is on another server, repository, or URL namespace. Either the source namespace does not support copying to the destination namespace, or the destination namespace refuses to accept the resource. The client may wish to try GET/PUT and PROPFIND/PROPPATCH instead.

507 (Insufficient Storage) - The destination resource does not have sufficient space to record the state of the resource after the execution of this method.

Example - COPY with Overwrite

This example shows resource http://www.example.com/~fielding/index.html being copied to the location http://www.example.com/users/f/fielding/index.html. The 204 (No Content) status code indicates that the existing resource at the destination was overwritten.

>>Request

  COPY /~fielding/index.html HTTP/1.1 
  Host: www.example.com 
  Destination: http://www.example.com/users/f/fielding/index.html 

>>Response

  HTTP/1.1 204 No Content 

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 URL is already mapped to a resource.

>>Request

  COPY /~fielding/index.html HTTP/1.1 
  Host: www.example.com 
  Destination: http://www.example.com/users/f/fielding/index.html 
  Overwrite: F 

>>Response

  HTTP/1.1 412 Precondition Failed 

Example - COPY of a Collection

>>Request

  COPY /container/ HTTP/1.1 
  Host: www.example.com 
  Destination: http://www.example.com/othercontainer/ 
  Depth: infinity 

>>Response

  HTTP/1.1 207 Multi-Status 
  Content-Type: application/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.example.com/othercontainer/R2/</d:href> 
      <d:status>HTTP/1.1 423 Locked</d:status> 
      <d:error><d:lock-token-submitted/></d:error>
    </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 because the destination R2 is locked. 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.

Was this article helpful?
Page statistics
2802 view(s) and 1 edit(s)
Social share
Share this page?

Tags

Comments

You must to post a comment.

Attachments