6.4 COPY

The COPY request format is very similar to MOVE, so we'll cover it quickly. Like the MOVE method, it:

• Requires a Destination header

• Interprets the Overwrite header the same way

• Can use the Depth header

• Accepts the propertybehavior element in the body of the request

A successful COPY request results in two resources (or two collections of resources) with identical content and dead properties. The original resource or collection exists untouched, and a copy exists at the destination URL (see Listing 6-8).

Listing 6-8 COPY request and response for a regular resource.

Request:

 COPY /hr/recruiting/opening-template.doc HTTP/1.1 Host: www.example.com Destination: http://www.example.com/hr/recruiting/positions/web- ui-designer.doc  

Response:

 HTTP/1.1 201 Created Date: Mon, 02 Sep 2002 03:20:57 GMT  

The resource created by the COPY operation should always have the same contents as the original. That is, if the original is a noncollection resource, the copy must have the same body. If the original is a collection, the copy must have all the same members as the original, and those members must have all the same contents as the original members. However, the copy may not have the same property values. To start with, the value of getcreationdate will almost certainly be different in the copy than in the original. Other property values may change or remain the same, depending on the definition of the property. Custom or "dead" properties must be copied intact.

6.4.1 MOVE = COPY + DELETE?

Now that we've defined COPY, do we really need MOVE? It seems reasonable to do a MOVE as a COPY of a resource to a new location, followed by deleting the old resource. The WebDAV specification compares a MOVE operation to a COPY followed by a DELETE of the source.

However, that text has been taken too literally to mean that the server must behave exactly as if it had done a COPY + DELETE. Although a MOVE operation is similar to a COPY + DELETE, it is not identical.

Clients are unable to reliably use COPY and DELETE to achieve the same thing as MOVE:

• The user may be granted privileges to rename resources but not create or delete resources.

• The user may be approaching a quota limit, preventing creation of new resources, but renaming or moving would not be prevented.

It's also problematic for the server to implement MOVE internally as a COPY and DELETE operation. A moved resource ought to be the same resource it was before the move; it merely has a new name and location. In contrast, a COPY operation creates a new resource. Thus, MOVE should not change the creation date or the name of the resource creator, but COPY may reset those values. In general, metadata that is initialized only on creation of a new resource should be initialized when a resource is created with COPY but not when a resource is moved or renamed with MOVE.

MOVE, COPY, and Versioning

The debate on whether MOVE must behave identically to COPY + DELETE peaked during the design of versioning features. The designers realized that a MOVE and a COPY behaved very differently when old versions of the source resource existed. A MOVE operation must preserve older versions, whereas a COPY only copies the content of the latest version. Thus, the versioning specification clarifies the behavior that most servers followed already.

6.4.2 Depth and COPY

If a COPY request does not have a Depth header, the depth is assumed to be infinity. An infinite-depth copy operation was described in Section 4.3: It copies every resource in the collection recursively, including the collection itself.

A Depth header may be explicitly on a COPY request, with a value of either infinity or 0. The only data that is copied in a depth 0 COPY request is the metadata directly attached to a collection (this was also illustrated in Section 4.3). Thus, a COPY with depth 0 is a way of copying only the properties of a collection. It might also include metadata that isn't exposed as a property for example, access control settings on a server that doesn't yet support the access control extensions to WebDAV.

A client may not send a COPY request to a collection with a Depth header of 1. This should result in 400 Bad Request.

6.4.3 Status Codes for COPY

Like MOVE, COPY results in a 201 Created status code if the destination resource did not previously exist, and 204 No Content if the destination resource already existed.

Some special failure status codes for COPY:

• 207 Multi-Status: See the body of the response for individual success and failure status and URLs.

• 403 Forbidden: The source and destination resource are the same, or the operation would overwrite a parent of the source (e.g., copy the collection /a/b/b to the collection /a would overwrite the parent of /a/b/b because it happens to have the same name).

• 409 Conflict: The parent collection does not exist.

• 412 Precondition Failed: Some precondition, such as the Overwrite header or the property behavior specification, could not be met.

• 502 Bad Gateway: The server cannot copy to the destination URL location, perhaps because it's on another server.