draft-ietf-simple-xcap-07.txt

最新的xcap协议

   course, if such information is present in a document, and a user
   selects an XML element enclosing that data, that information would be
   included in a resulting GET, for example.

   As an example, consider the following XML document:


   <?xml version="1.0"?>
      <watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
                   version="0" state="full">
        <watcher-list resource="sip:[e-mail]"
         package="presence">
          <watcher status="active"
                   id="8ajksjda7s"
                   duration-subscribed="509"
                   event="approved" >sip:[e-mail]</watcher>
          <watcher status="pending"
                   id="hh8juja87s997-ass7"
                   display-name="Mr. Subscriber"
                   event="subscribe">sip:[e-mail]</watcher>
        </watcher-list>
      </watcherinfo>



Rosenberg               Expires December 13, 2005              [Page 20]

Internet-Draft                    XCAP                         June 2005


                      Figure 3: Example XML Document

   Assuming that the default namespace URI for this application usage is
   urn:ietf:params:xml:ns:watcherinfo, the node selector "watcherinfo/
   watcher-list/watcher[@id="8ajksjda7s"]" would select the following
   XML element:


   <watcher status="active"
       id="8ajksjda7s"
       duration-subscribed="509"
       event="approved" >sip:[e-mail]
   </watcher>


6.4  Namespace Bindings

   In order to expand the namespace prefixes used in the document
   selector, a set of bindings from those namespace prefixes to
   namespace URI must be used.  Those bindings are contained in the
   query component of the URI.  If no query component is present, it
   means that only the default namespace URI (as identified by the
   application usage) is defined.  The query component is formatted as a
   valid xpointer expression [5] after suitable URI encoding as defined
   in Section 4.1 of the Xpointer framework.  This xpointer expression
   SHOULD only contain expressions from the xmlns() scheme [4].  A
   server compliant to this specification MUST ignore any xpointer
   expressions not from the xmlns() scheme.  The xmlns() xpointer
   expressions define the set of namespace bindings in use for
   evaluating the URI.

   Note that xpointer expressions were originally designed for usage
   within fragment identifiers of URIs.  However, within XCAP, they are
   used within query components of URIs.

   The following example shows a more complex matching operation, this
   time including the usage of namespace bindings.  Consider the
   following document:


   <foo xmlns="urn:test:default-namespace">
     <ns1:bar xmlns:ns1="urn:test:namespace1-uri"
              xmlns="urn:test:namespace1-uri">
       <baz/>
       <ns2:baz xmlns:ns2="urn:test:namespace2-uri"/>
     </ns1:bar>
     <ns3:hi xmlns:hi="urn:test:namespace3-uri">
       <there/>



Rosenberg               Expires December 13, 2005              [Page 21]

Internet-Draft                    XCAP                         June 2005


     </ns3:hi>
   </foo>

   Assume that this document has a document URI of
   http://xcap.example.com/test/users/joe/index, where "test" is the
   application usage.  This application usage defines a default
   namespace URI of "urn:test:default-namespace".  The XCAP URI:


   http://xcap.example.com/test/users/joe/index/~~/foo/a:bar/b:baz?
   xmlns(a=%22urn:test:namespace1-uri%22)xml
   ns(b=%22urn:test:namespace1-uri%22)

   will select the first <baz> element in the document.  The XCAP URI:


   http://xcap.example.com/test/users/joe/index/~~/foo/a:bar/b:baz?
   xmlns(a=%22urn:test:namespace1-uri%22)xml
   ns(b=%22urn:test:namespace2-uri%22)

   will select the second <baz> element in the document.  The following
   XCAP URI will also select the second element in the document:


   http://xcap.example.com/test/users/joe/index/~~/d:foo/a:bar/b:baz?
   xmlns(a=%22urn:test:namespace1-uri%22)xml
   ns(b=%22urn:test:namespace2-uri%22)xmlns(d=%22urn:test:
   default-namespace%22)


7.  Client Operations

   An XCAP client is an HTTP/1.1 compliant client.  Specific data
   manipulation tasks are accomplished by invoking the right set of HTTP
   methods with the right set of headers on the server.  This section
   describes those in detail.

   In all cases where the client modifies a document, by deleting or
   inserting a document, element or attribute resource, the client
   SHOULD verify that, if the operation were to succeed, the resulting
   document would meet the data constraints defined by the application
   usage, including schema validation.  For example, if the client
   performs a PUT operation to
   http://xcap.example.com/rls-services/users/joe/mybuddies, rls-
   services is the application unique ID, and the constraints defined by
   it SHOULD be followed.

   The client will know what URI to use based on the naming conventions



Rosenberg               Expires December 13, 2005              [Page 22]

Internet-Draft                    XCAP                         June 2005


   described by the application usage.

   If the document, after modification, does not meet the data
   constraints, the server will reject it with a 409.  The 409 response
   may contain an XML body, formatted according to the schema in
   Section 10.2, 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.

   In some cases, the application usage will dictate a uniqueness
   constraint that the client cannot guarantee on its own.  One such
   example is that a URI has to be unique within a domain.  Typically,
   the client is not the owner of the domain, and so it cannot be sure
   that a URI is unique.  In such a case, the client can either generate
   a sufficiently random identifier, or it can pick a "vanity"
   identifier in the hopes that it is not taken.  In either case, if the
   identifier is not unique, the server will reject the request with a
   409 and suggest alternatives that the client can use to try again.
   If the server does not suggest alternatives, the client SHOULD
   attempt to use random identifiers with increasing amounts of
   randomness.

   HTTP also specifies that PUT and DELETE requests are idempotent.
   This means that, if the client performs a PUT on a document and it
   succeeds, it can perform the same PUT, and the resulting document
   will look the same.  Similarly, when a client performs a DELETE, if
   it succeeds, a subsequent DELETE to the same URI will generate a 404;
   the resource no longer exists on the server since it was deleted by
   the previous DELETE operation.  To maintain this property, the client
   SHOULD construct its URIs such that, after the modification has taken
   place, the URI in the request will point to the resource just
   inserted for PUT (i.e., the body of the request), and will point to
   nothing for DELETE.  If this property is maintained, it is the case
   that GET to the URI in the PUT will return the same content (i.e.,
   GET(PUT(X)) == x).  This property implies idempotency.  Although a
   request can still be idempotent if it does not possess this property,
   XCAP does not permit such requests.  If the client's request does not
   have this property, the server will reject the request with a 409 and
   indicate a cannot-insert error condition.

   If the result of the PUT is a 200 or 201 response, the operation was
   successful.  Other response codes to any request, such as a
   redirection, are processed as per RFC 2616 [7].

7.1  Create or Replace a Document

   To create or replace a document, the client constructs a URI that



Rosenberg               Expires December 13, 2005              [Page 23]

Internet-Draft                    XCAP                         June 2005


   references the location where the document is to be placed.  This URI
   MUST be a document URI, and therefore contain the XCAP root and
   document selector.  The client then invokes a PUT method on that URI.

   The MIME content type MUST be the type defined by the application
   usage.  For example, it would be "application/rls-services+xml" for
   an RLS services [22] document, and not "application/xml".

   If the Request-URI identifies a document that already exists in the
   server, the PUT operation replaces that document with the content of
   the request.  If the Request-URI does not identify an existing
   document, the document is created on the server at that specific URI.

7.2  Delete a Document

   To delete a document, the client constructs a URI that references the
   document to be deleted.  This URI MUST be a document URI.  The client
   then invokes a DELETE operation on the URI to delete the document.

7.3  Fetch a Document

   As one would expect, fetching a document is trivially accomplished by
   performing an HTTP GET request with the Request URI set to the
   document URI.

7.4  Create or Replace an Element

   To create or replace an XML element within an existing document, the
   client constructs a URI whose document selector points to the
   document to be modified.  The node selector MUST be present in the
   URI, separated from the document selector with the path separator.
   The query component MUST be present if the node selector makes use of
   namespace prefixes, in which case the xmlns() expressions in the
   query component MUST define those prefixes.  To create this this
   element within the document, the node selector is constructed such
   that it is a no-match against the current document, but if the
   element in the body of the request was added to the document as
   desired by the client, the node selector would select that element.
   To replace an element in the document, the node selector is
   constructed so that it is a match against the element in the current
   document to be replaced, as well as a match to the new element
   (present in the body of the PUT request) that is to replace it.

   Oftentimes, the client will wish to insert an element into a document
   in a certain position relative to other children of the same parent.
   This is called a positional insertion.  They often arise because the
   schema constrains where the element can occur, or because ordering of
   elements is significant within the schema.  To accomplish this, the



Rosenberg               Expires December 13, 2005              [Page 24]

Internet-Draft                    XCAP                         June 2005


   client can use a node selector of the following form:


     parent/*[position][unique-attribute-value]

   Here, "parent" is an expression for the parent of the element to be
   inserted. "position" is the position amongst the existing children of
   this parent where the new element is to be inserted. "unique-
   attribute-value" is an attribute name and value for the element to be
   inserted, which is different from the current element in "position".
   The second predicate is needed so that the overall expression is a
   no-match when evaluated against the current children.  Otherwise, the
   PUT would replace the existing element in that position.

   Consider the example document in Figure 3.  The client would like to