draft-ietf-simple-xcap-07.txt

最新的xcap协议

   Each document within the XCAP root is identified by its document
   selector.  The document selector is a sequence of path segments,
   separated by a slash ("/").  These path segments define a
   hierarchical structure for organizing documents within any XCAP root.
   The first path segment MUST be the XCAP AUID.  So, continuing the
   example above, all of the documents used by the resource lists
   application would be under
   http://xcap.example.com/services/resource-lists.

   It is assumed that each application will have data that is set by
   users, and/or it will have global data that applies to all users.  As
   a result, beneath each AUID there are two sub-trees.  One, called
   "users", holds the documents that are applicable to specific users,
   and the other, called "global", holds documents applicable to all
   users.  The subtree beneath "global" is called the global tree.  The



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


   path segment after the AUID MUST either be "global" or "users".

   Within the "users" tree are zero or more sub-trees, each of which
   identifies documents that apply to a specific user.  Each user known
   to the server is associated with a username, called the XCAP User
   Identifier (XUI).  This XUI MUST be used as the path segment beneath
   the "users" segment.  The subtree beneath an XUI for a particular
   user is called their home directory.  "User" in this context should
   be interpreted loosely; a user might correspond to device, for
   example.

   XCAP does not itself define what it means for documents to "apply" to
   a user, beyond specification of a baseline authorization policy,
   described below in Section 8.  Each application usage can specify
   additional authorization policies which depend on data used by the
   application itself.

   The remainder of the document selector (the path following "global"
   or the XUI) is not constrained by this specification.  The
   application usage MAY introduce constraints, or may allow any
   structure to be used.

   The final path segment in the document selector identifies the actual
   document in the hierarchy.  This is equivalent to a filename, except
   that XCAP does not require that its document resources be stored as
   files in a file system.  However, the term "filename" is used to
   describe the final path segment in the document selector.  In
   traditional filesystems, the filename would have a filename
   extension, such as ".xml".  There is nothing in this specification
   that requires or prevents such extensions from being used in the
   filename.  In some cases, the application usage will specify a naming
   convention for documents, and those naming conventions may or may not
   specify a file extension.  For example, in the RLS services
   application usage [22], documents in the user's home directory with
   the filename "index" will be used by the server to compute the global
   index, which is also a document with the filename "index".

   When the naming conventions in an application usage do not constrain
   the filename conventions (or, more generally, the document selector),
   an application will know the filename (or more generally, the
   document selector) because it is included as a reference in a
   document which is at a well known location.  As another example,
   within the index document defined by RLS services, the <service>
   element has a child element called <resource-list> whose content is a
   URI pointing to a resource list within the users home directory.

   As a result, if the user creates a new document, and then references
   that document from a well-known document (such as the index document



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


   above), it doesn't matter whether the user includes an extension in
   the filename or not, as long as the user is consistent and maintains
   referential integrity.

   As an example, the HTTP URI
   http://xcap.example.com/resource-lists/users/joe/index represents a
   document selector where the AUID is "resource-lists", and the
   document is in the user tree with the XUI "joe" with filename
   "index".

6.3  Node Selector

   The node selector specifies specific nodes of the XML document which
   are to be accessed.  A node refers to either an XML element or an
   attribute of an element.  The node selector is an expression which
   identifies an element or attribute.  Its grammar is:


   node-selector          = element-selector ["/" attribute-selector]
   element-selector       = step *( "/" step)
   step                   = by-name / by-pos / by-attr / by-pos-attr
   by-name                = NameorAny
   by-pos                 = NameorAny "[" position "]"
   position               = 1*DIGIT
   by-attr                = NameorAny "[" "@" att-name "=" <">
                              att-value <"> "]"
   by-pos-attr            = NameorAny "[" position "]" "[" "@"
                              att-name "=" <"> att-value <"> "]"
   NameorAny              = QName / "*"   ; QName from XML Namespaces
   att-name               = QName
   att-value              = AttValue      ; from XML specification
   attribute-selector     = "@" att-name

   The QName grammar is defined in the XML namespaces [3] specification,
   and the AttValue grammar is defined in the XML specification XML 1.0
   [1].

   Note that the left bracket, right bracket, and double quote
   characters, which are meaningful to XCAP, cannot be directly
   represented in the HTTP URI.  As a result, they are escape coded when
   placed within the HTTP URI.  Furthermore, since XML allows for non-
   ASCII characters, the names of elements and attributes may not be
   directly representable in a URI.  Any such characters MUST be
   represented by converting them to an octet sequence corresponding to
   their representation in UTF-8, and then escape-coding that sequence
   of octets.

   Similarly, the XML specification defines the QName production for the



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


   grammar for element and attribute names, and the AttValue production
   for the attribute values.  Unfortunately, the characters permitted by
   these productions include some that are not allowed for pchar, which
   is the production for the allowed set of characters in path segments
   in the URI.  The AttValue production allows many such characters
   within the US-ASCII set, including the space.  Those characters MUST
   be escaped coded when placed in the URI.  Furthermore, QName and
   AttValue allow many Unicode characters, outside of US-ASCII.  When
   these characters need to be represented in the HTTP URI, they are
   escape coded.  To do this, the data should be encoded first as octets
   according to the UTF-8 character encoding [19] and then only those
   octets that do not correspond to characters in the unreserved set
   should be percent-encoded.  For example, the character A would be
   represented as "A", the character LATIN CAPITAL LETTER A WITH GRAVE
   would be represented as "%C3%80", and the character KATAKANA LETTER A
   would be represented as "%E3%82%A2".

   As a result, the grammar above represents the expressions processed
   by the XCAP server internally after it has un-escape-coded the URI.
   The on-the-wire format is dictated by RFC 3986 [14].  In the
   discussions and examples below, when the node selectors are not part
   of an HTTP URI, they are presented in their internal format prior to
   encoding.  If an example includes a node selector within an HTTP URI,
   it is presented in its escape coded form.

   The node selector is based on the concepts in XPath [11].  Indeed,
   the node selector expression, before it is escape coded for
   representation in the HTTP URI, happens to be a valid XPath
   expression.  However, XPath provides a set of functionality far
   richer than is needed here, and its breadth would introduce much
   unneeded complexity into XCAP.

   To determine the XML element or attribute selected by the node
   selector, processing begins at the root of the XML document.  The
   first step in the element selector is then taken.  Each step chooses
   a single XML element within the current document context.  The
   document context is the point within the XML document from which a
   specific step is evaluated.  The document context begins at the root
   of the document.  When a step determines an element within that
   context, that element becomes the new context for evaluation of the
   next step.  Each step can select an element by its name, by a
   combination of name and attribute value, by name and position, or by
   name, position and attribute.  In all cases, the name can be
   wildcarded, so that all elements get selected.

   The selection operation operates as follows.  Within the current
   document context, the children of that context are enumerated in
   document order.  If the context is the document, its child is the



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


   root element in the document.  If the context is an element, its
   children are all of the children of that element (naturally).  Next,
   those elements whose name is not a match for NameorAny are discarded.
   An element name is a match if NameorAny is the wildcard, or, if its
   not a wildcard, the element name matches NameorAny.  Matching is
   discussed below.  The result is an ordered list of elements.

   The elements in the list are further filtered by the predicates,
   which are the expressions in square brackets following NameorAny.
   Each predicate further prunes the elements from the current ordered
   list.  These predicates are evaluated in order.  If the content of
   the predicate is a position, the position-th element is selected
   (that is, treat "position" as a variable, and take the element whose
   position equals that variable), and all others are discarded.  If
   there are fewer elements in the list than the value of position, the
   result is a no-match.

   If the content of the predicate is an attribute name and value, all
   elements possessing that attribute with that value are selected, and
   all others are discarded.  Note that, although a document can have
   elements with namespace attributes, those elements cannot be selected
   using a namespace attribute as a predicate.  That is, a step like el-
   name[@xmlns="namespace"] will never match an element, even if there
   is an element in the list that specifies a default namespace of
   "namespace".  If there are no elements with attributes having the
   given name and value, the result is a no-match.

   After the predicates have been applied, the result will be a no-
   match, one element, or multiple elements.  If the result is multiple
   elements, the node selector is invalid.  Each step in a node selector
   MUST produce a single element to form the context for the next step.
   This is more restrictive than general XPath expressions, which allow
   a context to contain multiple elements.  If the result is a no-match,
   the node selector is invalid.  The node selector is only valid if a
   single element was selected.  This element becomes the context for
   the evaluation of the next step in the node selector expression.

   Once the last step is executed, if there is no attribute selector,
   the result of the node selection is the last selected element.  If
   there is an attribute selector, the server checks to see if there is
   an attribute with that name in the element in the current context.
   If there is not, the result is considered a no-match.  Otherwise,
   that attribute is selected.  Note that namespace attributes (such as
   xmlns) cannot be selected.

   As a result, once the entire node selector is evaluated against the
   document, the result will either be a no-match, invalid, or a single
   element or single attribute.



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


   Matching of element names is performed as follows.  The element being
   compared in the step has its name expanded as described in XML
   namespaces [3].  The element name in the step is also expanded.  This
   expansion requires that any namespace prefix is converted to its
   namespace URI.  Doing that requires a set of bindings from prefixes
   to namespace URIs.  This set of bindings is obtained from the query
   component of the URI (see Section 6.4).  If the element name in the
   step is not qualified, it is expanded using the default namespace
   defined by the application usage.  Comparisons are then performed as
   described in XML namespaces [3].  Note that the namespace prefix
   expansions described here are different than those specified in the
   XPath 1.0 specification, but are compatible with those currently
   defined by the XPath 2.0 specification [25].

   Matching of attribute names proceeds in a similar way.  The attribute
   in the document has its name expanded as described in XML namespaces
   [3].  Note that the default namespace for attributes is null.  If the
   attribute name in the attribute selector has a namespace prefix, its
   name expanded using the namespace bindings obtained from the query
   component of the URI.  If the attribute name in the attribute
   selector does not have a namespace prefix, the default namespace is
   null.

   Comments, text content, and processing declarations can be present in
   a document, but cannot be selected by the expressions defined here.
   This is consistent with the XPath treatment of these components.  Of