[OASIS Issue Tracker] Commented: (CMIS-656) Clarify how ETags andcmis:changeToken interact

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

    [ http://tools.oasis-open.org/issues/browse/CMIS-656?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=19217#action_19217 ] 

Florian Mueller commented on CMIS-656:
--------------------------------------

ETags and change tokens are different things and should not be mapped.

Here are simple examples why:

Relationships are not considered part of an object in many repositories. Adding or removing a relationship does not modify the object and therefore does not change the change token. The ETag, other hand, should change in such a case because an entry GET request could return different XML content. 
If the change token and the ETag would be equivalent then a server would have to reply to a  client request with a If-None-Match header and a matching ETag with a 304 (Not Modified) status. But that would be wrong because the Atom entry is different to the Atom entry before the relationships have been changed.
The same works for policies and renditions.

A similar problem exists with versioning. There are several properties on versionable documents that could be computed by the repository. Let's take cmis:isLatestVersion as an example. Creating a new version will toggle this boolean from true to false at the previous latest version. Some repositories might not see this as a change of the object and therefore don't change the change token of this object. The Atom entry, however, will be different. In this particular example the Atom entry would also gain a new current-version link relation.

Another reason why we should avoid this is that it makes the implementation of a binding agnostic client even harder. Since the change token and the ETag might not be the same string, the client has to remember both. That is, this binding specific detail has be carried around in the client objects.


> Clarify how ETags and cmis:changeToken interact
> -----------------------------------------------
>
>                 Key: CMIS-656
>                 URL: http://tools.oasis-open.org/issues/browse/CMIS-656
>             Project: OASIS Content Management Interoperability Services (CMIS) TC
>          Issue Type: Bug
>          Components: REST/AtomPub Binding
>    Affects Versions: Committee Draft 06
>            Reporter: Al Brown
>            Assignee: Al Brown
>
> RFC5023 uses If-Match in the example in 9.5.1.  As such, the server MUST return 412 if the ETag does not match.  RFC5023 does not have normative language around status code 412 and is only used in the example.
> As I read the relevant RFCs, I get the following:
>  
> 1. Map the cmis:changeToken property to the HTTP header ETag on retrieval from the server.  The changeToken is available in both locations (may be the same or different representations of current state/version)
> 2. On updates, perform the following checks (HTTP & CMIS levels)
> 2.1 If If-Match header is sent by client, ETag value is pulled from HTTP header If-Match per RFC2616.  The supplied ETag is compared against the ETag on the server.  If the match fails, then status code 412 is used.
> 2.2 If cmis:changeToken property is supplied by the client, compare the supplied and the cmis:changeToken on the server.  If the comparison fails, then return status code 409 per CMIS.
> 2.3 If ETag and cmis:changeToken are both specified, the HTTP If-Match check should be performed first.
> This provides normal HTTP behavior if ETag/If-Match headers are used (code 412).  If cmis:changeToken is used, the follow the advice in the HTTP spec and use 409 Conflict.
> The difference in status codes comes down to HTTP modelling the optimistic versioning as a client constraint.  E.g., client states don't perform the PUT if the resource is different from ETag XXXX.  Technically if the If-Match header was not specified by the client, the PUT would go through if the cmis:changeToken check was not there.  The CMIS model is a server constraint and thus the 409 status code.
> Backup material:
> HTTP RFC 2616 states:
> 409 Conflict
> The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough 
> information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required. 
> Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by an earlier (third-party) request, the server might use the 409 response to indicate that it can't complete the request. In this case, the response entity would likely contain a list of the differences between the two versions in a format defined by the response Content-Type. 
> 412 Precondition Failed
> The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. This response code allows the client to place preconditions on the current resource metainformation (header field data) and thus prevent the requested method from being applied to a resource other than the one intended. 
> 14.24 If-Match
> The If-Match request-header field is used with a method to make it conditional. A client that has one or more entities previously obtained from the resource can verify that one of those entities is current by including a list of their associated entity tags in the If-Match header field. Entity tags are defined in section 3.11. The purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead. It is also used, on updating requests, to prevent inadvertent modification of the wrong version of a resource. As a special case, the value "*" matches any current entity of the resource. 
>        If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
> If any of the entity tags match the entity tag of the entity that would have been returned in the response to a similar GET request (without the If-Match header) on that resource, or if "*" is given 
> and any current entity exists for that resource, then the server MAY perform the requested method as if the If-Match header field did not exist. 
> A server MUST use the strong comparison function (see section 13.3.3) to compare the entity tags in If-Match. 
> If none of the entity tags match, or if "*" is given and no current entity exists, the server MUST NOT perform the requested method, and MUST return a 412 (Precondition Failed) response. This behavior is most useful when the client wants to prevent an updating method, such as PUT, from modifying a resource that has changed since the client last retrieved it. 
> If the request would, without the If-Match header field, result in anything other than a 2xx or 412 status, then the If-Match header MUST be ignored. 
> The meaning of "If-Match: *" is that the method SHOULD be performed if the representation selected by the origin server (or by a cache, possibly using the Vary mechanism, see section 14.44) exists, and MUST NOT be performed if the representation does not exist. 
> A request intended to update a resource (e.g., a PUT) MAY include an If-Match header field to signal that the request method MUST NOT be applied if the entity corresponding to the If-Match value (a single entity tag) is no longer a representation of that resource. This allows the user to indicate that they do not wish the request to be successful if the resource has been changed without their knowledge. Examples: 
>        If-Match: "xyzzy"
>        If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
>        If-Match: *
> The result of a request having both an If-Match header field and either an If-None-Match or an If-Modified-Since header fields is undefined by this specification. 

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira