draft-ietf-simple-xcap-07.txt

最新的xcap协议

   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.



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


   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.

   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 of 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 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



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


   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
   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 11.

5.9  Documenting Application Usages

   Application usages are documented in specifications which 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 14.

   o  XML Schema

   o  Default 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,



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


   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 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 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 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 user to manipulate elements or attributes that are
   descendants of an element which can repeat, that element SHOULD
   include, in its schema, an attribute which 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 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.10), and undo its previous changes.  This is very
   difficult.



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


   As a result, the schemas SHOULD be defined so that common operations
   generally require a single request to perform.  Consider an example.
   Lets 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.
   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 path separator with a
   escape coded 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 path separator is a
   path segment with a value of double tilde ("~~").  It is piece of
   syntactic sugar that separates the document selector from the node
   selector.  The node selector is an expression that identifies an XML
   element within a document.

   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



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


   actually exists on the server.  Its purpose is to identify the root
   of the tree within the domain where all XCAP documents are stored.
   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).  As an example,
   http://xcap.example.com/services might be used as the XCAP root URI
   within the example.com domain.  Typically, the XCAP root URI is
   provisioned into client devices.  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