SIMPLE J. Rosenberg Internet-Draft dynamicsoft Expires: January 10, 2005 July 12, 2004 An Extension to the XML Configuration Access Protocol (XCAP) for Manipulating Multiple Elements draft-rosenberg-simple-xcap-multiple-00 Status of this Memo By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 10, 2005. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract The Extensible Markup Language (XML) Configuration Access Protocol (XCAP) provides a mechanism for getting and putting XML documents, elements and attributes to a server. XCAP only allows each operation to operate on a single document, element or attribute at a time. This specification defines an extension to XCAP that allows for manipulation of multiple XML elements within a single operation. Rosenberg Expires January 10, 2005 [Page 1] Internet-Draft XCAP Multiple July 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Multi-Element Resource . . . . . . . . . . . . . . . . . . . . 3 3. Client Operations . . . . . . . . . . . . . . . . . . . . . . 5 3.1 Create or Replace a Multi Element Resource . . . . . . . . 5 3.2 Delete a Multi-Element Resource . . . . . . . . . . . . . 6 3.3 Fetch an Multi-Element Resource . . . . . . . . . . . . . 7 4. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 7 4.1 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 GET Handling . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 DELETE Handling . . . . . . . . . . . . . . . . . . . . . 9 4.4 Managing Etags . . . . . . . . . . . . . . . . . . . . . . 9 5. Conflict Report Extensions . . . . . . . . . . . . . . . . . . 9 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 9.1 Normative References . . . . . . . . . . . . . . . . . . . . 10 9.2 Informative References . . . . . . . . . . . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 10 Intellectual Property and Copyright Statements . . . . . . . . 11 Rosenberg Expires January 10, 2005 [Page 2] Internet-Draft XCAP Multiple July 2004 1. Introduction The Extensible Markup Language (XML) Configuration Access Protocol (XCAP) [3] provides a mechanism for getting and putting XML documents, elements and attributes to a server. XCAP only allows each operation to operate on a single document, element or attribute at a time. However, in some cases an XCAP client wishes to perform an operation that requires maniulating multiple elements in a document. One example is a presence list application [4]. If a user is using XCAP to manage a list of users on their presence list, they may decide that they wish to remove a number of users from the list. Currently, this would require a separate HTTP DELETE for each user. Similarly, the Conference Policy Control Protocol (CPCP) [5] uses XCAP to manipulate conference policy documents. In some cases, if a user is added to the conference, they also need to be added to the dial-out list. This requires two operations with XCAP. The usage of multiple XCAP operations to accomplish these tasks brings additional network bandwidth and increased latency. It also introduces many more failure cases. If the first few operations succeed, but a subsequent one fails, the client will have to manually roll back to the previous good state. Similarly, it is possible that two clients are making changes to the same document, and one of them modifies it in the middle of a sequence of operations being made by another. This case will be detected, but it will require the client to implement complex recovery logic to restore the document to a good state. To resolve these problems, this specification defines an extension to XCAP that allows for manipulation of multiple XML elements within a single operation. The extension is explicitly limited to the manipulation of multiple elements, and not multiple attributes or documents. The manipulation includes all valid HTTP operations on an XCAP resource, including GET, PUT and DELETE. 2. Multi-Element Resource The extension operates by defining a new type of XCAP resource, called a multi-element resource. A multi-element resource is a resource that references an ordered list of elements contained within an XCAP document. The URi for a multi-element resource includes sufficient information to identify the ordered list of elements. In particular, the URI contains a sequence of node selectors that identify each of the elements, separated by the union operator from XPath (|). Rosenberg Expires January 10, 2005 [Page 3] Internet-Draft XCAP Multiple July 2004 Specifically, this specification extends the grammar for node selector: node-selector = (element-selector ["/" attribute-selector]) / multi-el-selector multi-el-selector = element-selector 1*(VBAR element-selector) VBAR = "%7c" ; The | character The multi-element resource is equal to the sequence of elements obtained by taking each of the element-selectors within the multi-el-selector and evaluating it against the document identified by the document selector. The representation of the multi-element resource is done using the "application/xcap-el+xml" MIME type defined in [3]. Each of the elements represented by the multi-element resource is placed into the body in order. The result is a balanced fragment of an XML document. Note, however, that this document will not be compliant to any XML schema. As an example, consider the following XML document: 1 2 3 This document has a URI of http://xcap.example.com/root/foo/users/joe/test. The following URI, prior to escaping, is a multi-element URI representing the elements with "id" 1 and 3: http://xcap.example.com/root/foo/users/joe/test/~~/ testing/el[@id="1"]|testing/node/el[@id="3"] And, after escaping, the valid XCAP URI for this resource is: http://xcap.example.com/root/foo/users/joe/test/~~/ testing/el%5B%40id%3D%221%22%5D%7Ctesting/node/el%5B%40id%3D%223%22%5D Rosenberg Expires January 10, 2005 [Page 4] Internet-Draft XCAP Multiple July 2004 If a client performed a GET against the resource, the result would be: 1 3 There are some important constraints on the multi-element resources when those resources are PUT or DELETE to the server. In such a case, each element in the sequence MUST NOT be a child of any of the other elements in the sequence. Furthermore, the way in which each element in the sequence is identified MUST remain valid (that is, MUST still identify the same element), after the changes to the other elements in the sequence implied by the PUT or DELETE. As an example, if positional selectors are used, and two of the elements in the sequence are siblings, the multi-element URI would not be valid for DELETE, as the deletion of one of the siblings will affect the URI for the other. These constraints are required to retain the idempotency characteristics of PUT and DELETE. 3. Client Operations The following are the operations a client can perform against multi-element resources. 3.1 Create or Replace a Multi Element Resource To create or replace an sequence of XML elements within an existing document, the client constructs a URI whose document URI points to the document to be modified. This URI SHOULD meet the additional constraints defined above for URIs that are PUT or DELETE to the server. If the client chooses a URI that doesnt meet this constraint, the server will verify it and reject the request. The multi element selector MUST be present in the URI. The selector is constructed such that, if the elements were added to the document as desired by the client, the multi element selector would select a sequence of elements corresponding to the ones the client wishes to create or replace. The client then invokes the HTTP PUT method. The content in the request MUST be an sequence of XML elements. The MIME type in the request SHOULD be "application/xcap-el:xml", defined in [3]. The server will insert the elements (including their attributes and content) into the document such that the multi-element selector, if evaluated by the server, would return the content present in the request. If the multi element URI identifies a sequence of elements which do Rosenberg Expires January 10, 2005 [Page 5] Internet-Draft XCAP Multiple July 2004 not all exist in the document, the multi element resource is said to not exist. As such, a PUT against such a URI would cause the multi-element resource to be created. Note that the existence of the multi-element resource is different from that of its components. Even if all but one of the sequence of elements identified by the multi element resource does not exist, the multi-element resource is said to not exist. Thus, when the multi-element resource is created, this will necessarily result in the modification of some elements within the document, and the creation of others. To create the multi-element resource as a result of the PUT, the server inserts the component elements which don't exist in the document, and modifies the ones that do, such that if the multi-element selector, when evaluated against the current document, would return the content provided in the body of the PUT request. The client SHOULD be certain, before making the request, that the resulting modified document will also be conformant to the schema. If the result of the PUT is a 200 or 202 response, the operation was successful. If it was a 409, the user performed some action which resulted in an invalid document. The 409 response may contain an XML body, formatted according to the schema in Section 5, which provides further information on the nature of the error. The client MAY use this information to try and alter the request so that this time, it might succeed. The client SHOULD NOT simply retry the request without changing some aspect of it. 3.2 Delete a Multi-Element Resource To delete a sequence of elements from a document, the client constructs a URI whose document URI points to the document containing the elements to be deleted. This URI SHOULD meet the additional constraints defined above for URIs that are PUT or DELETE to the server. If the client chooses a URI that doesnt meet this constraint, the server will verify it and reject the request. The multi-element selector MUST be present, and identify the specific elements to be deleted. The client then invokes the HTTP DELETE method on the URI. If the resource exists in the document (meaning that all of the constituent elements exist), the server will remove the elements from the document (including all of their attributes and their content, such as any children). The client SHOULD be certain, before making the request, that the resulting modified document will also be conformant to the schema. If the result of the DELETE is a 200 response, the operation was Rosenberg Expires January 10, 2005 [Page 6] Internet-Draft XCAP Multiple July 2004 successful. If it was a 409, the user performed some action which resulted in an invalid document. The 409 response may contain an XML body, formatted according to the schema in Section 5, which provides further information on the nature of the error. The client MAY use this information to try and alter the request so that this time, it might succeed. The client SHOULD NOT simply retry the request without changing some aspect of it. 3.3 Fetch an Multi-Element Resource To fetch a sequence of elements from a document, the client constructs a URI whose document URI points to the document containing the elements to be fetched. The multi-element selector MUST be present, and must identify the sequence of elements to be fetched. The client then invokes the GET method. The response will contain those XML elements. Specifically, it contains a sequence of XML elements. Each of those elements is the content of the XML document, starting with the opening bracket for the begin tag for that element, and ending with the closing bracket for the end tag for that element. This will, as a result, include all attributes and child elements of that element. 4. Server Behavior The general server behavior in [3] is updated by this specification with new procedures for processing requests for multiple-element resources. 4.1 PUT Handling If the request URI represents a document (i.e., there is no node selector component), the content of the request MUST be a valid XML document, and MUST be compliant to the schema associated with the application usage in the URI. If it is not, the request MUST be rejected with a 409 response. If the request URI matches a document that exists on the server, that document is replaced by the content of the request. If the request URI does not match a document that exists on the server, the server adds the document to its repository, and associates it with the URI in the request URI. Note that this may require the creation of one or more "directories" on the server. If the Request URI represents an multi-element resource, the server MUST verify that the document defined by the document URI exists. If no such document exists on the server, the server MUST reject the request with a 404 response code. The content of the request MUST be a sequence of N XML elements and associated content (including children elements) when the URI has N node-selectors (and thus N-1 Rosenberg Expires January 10, 2005 [Page 7] Internet-Draft XCAP Multiple July 2004 vertical bars). If the number of elements in the body does not match the number of node-selectors in the URI, the server MUST return a 409 response code, and SHOULD indicate the in the conflict report in the body of that response. See below for definitions of the schema for this error element. The body type of the request MUST be "application/xcap-el+xml". If the request does not contain a valid XML fragment body, the request is rejected with a 409 response code. The server MUST NOT perform the PUT operation if the result is not idempotent. It can be difficult to detect whether or not the resulting PUT operation would be idempotent. Section 2 discusses some of the constraints that must be met. This specification makes no normative recommendations on how the server verifies idempotence. However, the implementation choice that is most likely to succeed is to perform the PUT operation as if it was a series of PUTs to each element in the sequence. Once the sequence of PUTs is done, the server performs a local GET, and compares the result of that GET with the content of the PUT. If they match, the result was idempotent. If not, the server can undo the sequence of PUTs it performed, and reject the request with a 409. If any of the PUTs in the sequence fails, the server undoes the sequence of successful ones and rejects the request with a 409. No matter how it is done, if the PUT operation was to a URI which would not retain idempotence, the server MUST reject the request. It SHOULD include the element in the conflict report in the body of the 409 response. If the PUT operation was successful, the server returns a 200 OK or 201 Created, as appropriate. This response MUST not contain any content. 4.2 GET Handling If the request URI contains a multi-element selector, the server checks to see if each node selector in the sequence exists in the document. If they all exist, the server places each element into the content of the 200 OK response, in the order the elements are selected in the Request URI. The MIME type of the response MUST be "application/xcap-el+xml". The content of the response is a sequence of elements, with each element being the portion of the XML document starting with the left bracket of the begin tag of the element, ending with the right bracket of the end tag of the element. If, however, the referenced multi-element resource does not exist (this is the case if any of its constituent elements does not exist), a 404 is returned. Rosenberg Expires January 10, 2005 [Page 8] Internet-Draft XCAP Multiple July 2004 4.3 DELETE Handling If the request URI specifies a multi-element selector, the server verifies that each of the specified elements exist in the document. If they all do not exist, the server returns a 404 (Not Found) response. If they do exist, but the deletions cannot be done as a sequence of DELETE operations on each of the constituent elements, the server MUST reject the request with a 409 (Conflict) response. The conflict report in the 409 response SHOULD contain the element indicating this case. If removal of the elements would result in a document which does not comply with the XML schema for the application usage, the server MUST NOT perform the deletion, and MUST reject the request with a 409 (Conflict). If none of these cases are true, the server performs the deletion, and returns a 200 OK response. 4.4 Managing Etags The multi-element resource, like any other resource, has an etag. As with other xcap resources within a document, the multi-element resources within a document all share the same etag value as the document itself. 5. Conflict Report Extensions This specification adds two new errors to the conflict report document defined in [3]. In particular, it adds the and elements. The latter indicates that there was a mismatch between the number of node-selectors in the URI and the number of elements in the body of the request or the document itself. The former indicates that the resource represented one in which an idempotent operation could not be performed, and so the request was rejected. Schema TBD. 6. Security Considerations This specification does not introduce any security considerations beyond those specified in XCAP. 7. IANA Considerations This specification defines a new XCAP extension tag, , according to the procedures of XCAP. This tag will be present in the extensions document maintained by the server in the global tree. Rosenberg Expires January 10, 2005 [Page 9] Internet-Draft XCAP Multiple July 2004 8. Acknowledgements The author would like to thank Jari Urpalainen and Joel Halpern for their input to this work as it evolved within the SIMPLE group. 9. References 9.1 Normative References [1] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C FirstEdition REC-xml-20001006, October 2000. [2] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", W3C REC REC-xpath-19991116, November 1999. [3] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)", draft-ietf-simple-xcap-02 (work in progress), February 2004. 9.2 Informative References [4] Rosenberg, J., "An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) Usage for Presence Lists", draft-ietf-simple-xcap-list-usage-02 (work in progress), February 2004. [5] Khartabil, H. and P. Koskelainen, "The Conference Policy Control Protocol (CPCP)", draft-ietf-xcon-cpcp-00 (work in progress), April 2004. Author's Address Jonathan Rosenberg dynamicsoft 600 Lanidex Plaza Parsippany, NJ 07054 US Phone: +1 973 952-5000 EMail: jdrosen@dynamicsoft.com URI: http://www.jdrosen.net Rosenberg Expires January 10, 2005 [Page 10] Internet-Draft XCAP Multiple July 2004 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Rosenberg Expires January 10, 2005 [Page 11]