rfc4825-xcap.txt

关于XCAP协议的rfc文档

   application usage specifies that the list of service definitions is
   present within a specific document with a specific name within the
   global tree.  This allows the RLS to perform a single XCAP request to
   fetch the service definition for the service associated with the SIP
   URI in a SUBSCRIBE request.

   Naming conventions are used by XCAP clients to construct their URIs.
   The XCAP server does not make use of them.

5.6.  Resource Interdependencies

   When a user modifies an XCAP resource, the content of many other
   resources is affected.  For example, when a user deletes an XML
   element within a document, it does so by issuing a DELETE request
   against the URI for the element resource.  However, deleting this
   element also deletes all child elements and their attributes, each of
   which is also an XCAP resource.  As such, manipulation of one
   resource affects the state of other resources.

   For the most part, these interdependencies are fully specified by the
   XML schema used by the application usage.  However, in some
   application usages, there is a need for the server to relate
   resources together, and such a relationship cannot be specified
   through a schema.  This occurs when changes in one document will
   affect another document.  Typically, this is the case when an
   application usage is defining a document that acts as a collection of
   information defined in other documents.



Rosenberg                   Standards Track                    [Page 11]

RFC 4825                          XCAP                          May 2007


   As an example, when a user creates a new RLS service (that is, it
   creates a new <service> element within an RLS services document), the
   server adds that element to a read-only global list of services
   maintained by the server in the global tree.  This read-only global
   list is accessed by the RLS when processing a SIP SUBSCRIBE request.

   Resource interdependencies are used by both XCAP clients and servers.

5.7.  Authorization Policies

   By default, each user is able to access (read, modify, and delete)
   all the documents below their home directory, and any user is able to
   read documents within the global directory.  However, only trusted
   users, explicitly provisioned into the server, can modify global
   documents.

   The application usage can specify a different authorization policy
   that applies to all documents associated with that application usage.
   An application usage can also specify whether another application
   usage is used to define the authorization policies.  An application
   usage for setting authorization policies can also be defined
   subsequent to the definition of the main application usage.  In such
   a case, the main application usage needs only to specify that such a
   usage will be defined in the future.

   If an application usage does not wish to change the default
   authorization policy, it can merely state that the default policy is
   used.

   The authorization policies defined by the application usage are used
   by the XCAP server during its operation.

5.8.  Data Extensibility

   An XCAP server MUST understand an application usage in order to
   process an HTTP request made against a resource for that particular
   application usage.  However, it is not required for the server to
   understand all of the contents of a document used by an application
   usage.  A server is required to understand the baseline schema
   defined by the application usage.  However, those schemas can define
   points of extensibility where new content can be added from other
   namespaces and corresponding schemas.  Sometimes, the server will
   understand those namespaces and therefore have access to their
   schemas.  Sometimes, it will not.

   A server MUST allow for documents that contain elements from
   namespaces not known to the server.  In such a case, the server




Rosenberg                   Standards Track                    [Page 12]

RFC 4825                          XCAP                          May 2007


   cannot validate that such content is schema compliant; it will only
   verify that the XML is well-formed.

   If a client wants to verify that a server supports a particular
   namespace before operating on a resource, it can query the server for
   its capabilities using the XCAP Capabilities application usage,
   discussed in Section 12.

5.9.  Documenting Application Usages

   Application usages are documented in specifications that convey the
   information described above.  In particular, an application usage
   specification MUST provide the following information:

   o  Application Unique ID (AUID): If the application usage is meant
      for general use on the Internet, the application usage MUST
      register the AUID into the IETF tree using the IANA procedures
      defined in Section 15.

   o  XML Schema

   o  Default Document Namespace

   o  MIME Type

   o  Validation Constraints

   o  Data Semantics

   o  Naming Conventions

   o  Resource Interdependencies

   o  Authorization Policies

5.10.  Guidelines for Creating Application Usages

   The primary design task when creating a new application usage is to
   define the schema.  Although XCAP can be used with any XML document,
   intelligent schema design will improve the efficiency and utility of
   the document when it is manipulated with XCAP.

   XCAP provides three fundamental ways to select elements amongst a set
   of siblings: by the expanded name of the element, by its position, or
   by the value of a specific attribute.  Positional selection always
   allows a client to get exactly what it wants.  However, it requires a
   client to cache a copy of the document in order to construct the
   predicate.  Furthermore, if a client performs a PUT, it requires the



Rosenberg                   Standards Track                    [Page 13]

RFC 4825                          XCAP                          May 2007


   client to reconstruct the PUT processing that a server would follow
   in order to update its local cached copy.  Otherwise, the client will
   be forced to re-GET the document after every PUT, which is
   inefficient.  As such, it is a good idea to design schemas such that
   common operations can be performed without requiring the client to
   cache a copy of the document.

   Without positional selection, a client can pick the element at each
   step by its expanded name or the value of an attribute.  Many schemas
   include elements that can be repeated within a parent (often,
   minOccurs equals zero or one, and maxOccurs is unbounded).  As such,
   all of the elements have the same name.  This leaves the attribute
   value as the only way to select an element.  Because of this, if an
   application usage expects the user to manipulate elements or
   attributes that are descendants of an element that can repeat, that
   element SHOULD include, in its schema, an attribute that can be
   suitably used as a unique index.  Furthermore, the naming conventions
   defined by that application usage SHOULD specify this uniqueness
   constraint explicitly.

   URIs often make a good choice for such a unique index.  They have
   fundamental uniqueness properties, and are also usually of semantic
   significance in the application usage.  However, care must be taken
   when using a URI as an attribute value.  URI equality is usually
   complex.  However, attribute equality is performed by the server
   using XML rules, which are based on case sensitive string comparison.
   Thus, XCAP will match URIs based on lexical equality, not functional
   equality.  In such cases, an application usage SHOULD consider these
   implications carefully.

   XCAP provides the ability of a client to operate on a single element,
   attribute, or document at a time.  As a result, it may be possible
   that common operations the client might perform will require a
   sequence of multiple requests.  This is inefficient, and introduces
   the possibility of failure conditions when another client modifies
   the document in the middle of a sequence.  In such a case, the client
   will be forced to detect this case using entity tags (discussed below
   in Section 7.11), and undo its previous changes.  This is very
   difficult.

   As a result, the schemas SHOULD be defined so that common operations
   generally require a single request to perform.  Consider an example.
   Let's say an application usage is defining permissions for users to
   perform certain operations.  The schema can be designed in two ways.
   The top level of the tree can identify users, and within each user,
   there can be the permissions associated with the user.  In an
   alternative design, the top level of the tree identifies each
   permission, and within that permission, the set of users who have it.



Rosenberg                   Standards Track                    [Page 14]

RFC 4825                          XCAP                          May 2007


   If, in this application usage, it is common to change the permission
   for a user from one value to another, the former schema design is
   better for xcap; it will require a single PUT to make such a change.
   In the latter case, either the entire document needs to be replaced
   (which is a single operation), or two PUT operations need to occur --
   one to remove the user from the old permission, and one to add the
   user to the new permission.

   Naming conventions form another key part of the design of an
   application usage.  The application usage should be certain that XCAP
   clients know where to "start" to retrieve and modify documents of
   interest.  Generally, this will involve the specification of a well-
   known document at a well-known URI.  That document can contain
   references to other documents that the client needs to read or
   modify.

6.  URI Construction

   In order to manipulate an XCAP resource, the data must be represented
   by an HTTP URI.  XCAP defines a specific naming convention for
   constructing these URIs.  The URI is constructed by concatenating the
   XCAP root with the document selector with the node selector separator
   with a percent-encoded form of the node selector.  This is followed
   by an optional query component that defines namespace bindings used
   in evaluating the URI.  The XCAP root is the enclosing context in
   which all XCAP resources live.  The document selector is a path that
   identifies a document within the XCAP root.  The node selector
   separator is a path segment with a value of double tilde ("~~"), and
   SHOULD NOT be percent-encoded, as advised in Section 2.3 of RFC 3986
   [13].  URIs containing %7E%7E should be normalized to ~~ for
   comparison; they are equivalent.  The node selector separator is a
   piece of syntactic sugar that separates the document selector from
   the node selector.  The node selector is an expression that
   identifies a component of the document, such as an element or
   attribute.  It is possible that a "~~" appears as part of the node
   selector itself; in such a case, the first "~~" in the URI is the
   node selector separator.

   The sections below describe these components in more detail.

6.1.  XCAP Root

   The root of the XCAP hierarchy is called the XCAP root.  It defines
   the context in which all other resources exist.  The XCAP root is
   represented with an HTTP URI, called the XCAP Root URI.  This URI is
   a valid HTTP URI; however, it doesn't point to any resource that
   actually exists on the server.  Its purpose is to identify the root
   of the tree within the domain where all XCAP documents are stored.



Rosenberg                   Standards Track                    [Page 15]

RFC 4825                          XCAP                          May 2007


   It can be any valid HTTP URI, but MUST NOT contain a query component
   (a complete XCAP URI may have a query component, but it is not part
   of the XCAP root URI).  It is RECOMMENDED that it be equal to
   xcap.domain, where domain is the domain of the provider.  As an
   example, "http://xcap.example.com" might be used as the XCAP root URI
   within the example.com domain.  Typically, the XCAP root URI is
   provisioned into client devices.  If not explicitly provisioned,
   clients SHOULD assume the form xcap.domain, where domain is the
   domain of their service provider (for SIP, this would be the domain
   part of their Address-of-Record (AOR)).  A server or domain MAY
   support multiple XCAP root URIs.  In such a case, it is effectively
   operating as if it were serving separate domains.  There is never
   information carryover or interactions between resources in different
   XCAP root URIs.

   When a client generates an HTTP request to a URI identifying an XCAP
   resource, RFC 2616 procedures for the construction of the Request-URI
   apply.  In particular, the authority component of the URI may not be
   present in the Request-URI if the request is sent directly to the
   origin server.

   The XCAP root URI can also be a relative HTTP URI.  It is the
   responsibility of the application usage to specify the base URI for
   an HTTP URI representing an XCAP resource whenever such a URI appears
   within a document defined by that application usage.  Generally
   speaking, it is unsafe to use the retrieval URI as the base URI.
   This is because any URI that points to an ancestor for a particular
   element or attribute can contain content including that element or
   attribute.  If that element or attribute contained a relative URI
   reference, it would be resolved relative to whatever happened to be
   used to retrieve the content, and this will often not be the base URI
   defined by the application usage.

6.2.  Document Selector