Replication and the PUT Method
Topic Last Modified: 2006-06-12
The PUT method is used to either add a new non- collection resource to an existing collection or update an existing non- collection resource. The PUT method in the context of WebDAV replication is used to upload the content change for a particular non- collection resource. The server returns the updated resourcetag of the affected non- collection resource in the response headers.
Normal PUT method
If the client issues a PUT method request without any headers specific to replication, the request will have the default behavior as defined in HTTP/1.1 and WebDAV protocol, except that the server will return the resourcetag and repl-uid of the affected resource.
PUT method with version checking
Usually, the client would like to verify that the correct version of a resource is being updated and, at the same time that the server would like to do conflict detection. If the client has previously downloaded content or properties of a resource, the server returned the resourcetag of that particular resource. The client can include the resourcetag in the request If Header of a PUT method in the form of:
If: (<resourcetag>)
The client can include the repl-uid in the request header of a PUT method in the form of:
If: (<repl-uid>)
The If: (<resourcetag>) and If: (<repl-uid>) conditions allows client-initiated conflict detection.
PUT method with server-side modifications
Sometimes the PUT method can trigger an action on the server that results in a successful overwrite from the client perspective, but modifications or transformations on the server resulting in content and/or properties mismatch between the client and server. Because every PUT method returns the updated resourcetag, there is a mismatch between the content and/or properties on the client and the content and/or properties reflected by the resourcetag.
In this case, the status code 210 Content Different is returned. The response should also include information about what was affected during the execution of the PUT method on the server.
To solve this mismatch problem, the client may need to re-fetch the contents and/or properties of the affected resource using the GET method or PROPFIND Method.
PUT method to prevent inadvertent overwrite of an existing resource
The client may want to check if the resource already exists that it is intending to write to the store and, if so, might not want to overwrite the existing contents. In this case, the client should include the following request header in the PUT method request so as to avoid overwriting an existing resource:
If-None-Match: *
PUT method with client-initiated conflict detection
The client should include the If: (<resourcetag>) or If: (<repl-uid>) request header in the PUT method request. The resource on the server will only be updated if the version matches. If the condition fails, the server returns a 412 Precondition Failed error code.
PUT method and enforcing resource integrity
Consider the following scenario:
Client 1 downloads a resource item.eml from a particular collection called docs. Assume that the URL of the resource is http://example.org/public/docs/item.eml.
Client 1 goes offline and makes changes to its local copy of item.eml. In the meantime, Client 2 deletes and then re-creates the resource item.eml on the server. Now, Client 1 comes online and updates the resource item.eml.
This specific scenario may or may not be an error, depending on what the client intended in the first place. If the client intended to update the contents of the resource item.eml no matter what, then this is not an error. If the client's intention was to update the contents of the resource item.eml only if it is the same resource it previously downloaded, there is a problem.
One way to resolve this problem is to include the If: (<resourcetag >) or If: (<repl-uid>) condition in the request header to make sure that the client is updating the correct version of a resource. Including the If: (<resourcetag >) condition may only partially solve the problem because although the resourcetag value is universally unique, it is not enough to distinguish between an updated version of an existing resource and updated version of a new resource with exact same URL.
This specific problem can be only resolved using the repl-uid Field on the resource, which uniquely identifies a resource. Thus in this scenario, deleting resource item.eml and re-creating resource item.eml in the same collection will result in two different repl-uids. In effect, including both the conditions of resourcetag and repl-uid,
If: (<resourcetag>) (<repl-uid>)
can solve this problem without ambiguity.