📄 draft-ietf-simple-xcap-12-latest.txt
字号:
the node selector. The node selector is an expression that
identifies a component of the document, such as an element or
attribute.
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.
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
Rosenberg Expires April 16, 2007 [Page 15]
Internet-Draft XCAP October 2006
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
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/resource-lists".
Implementors making use of HTTP servlets should be aware that XCAP
may require them to get authorization from the server
administrator to place resources within this specific subset of
the URI namespace.
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
path segment after the AUID MUST either be "global" or "users".
Within the "users" tree are zero or more sub-trees, each of which
Rosenberg Expires April 16, 2007 [Page 16]
Internet-Draft XCAP October 2006
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). Typically, an endpoint is provisioned with the
value of the XUI. For systems that support SIP applications, it is
RECOMMENDED that the XUI be equal to the Address-of-Record (AOR) for
the user (i.e., sip:joe@example.com). Since SIP endpoints generally
know their AOR, they will also know their XUI. As a consequence, if
no XUI is explicitly provisioned, a SIP UA SHOULD assume it is equal
to their AOR. This XUI MUST be used as the path segment beneath the
"users" segment. Since the SIP URI allows for characters which are
not permitted in HTTP URI path segments (such as the '?' and '/'
characters, which are permitted in the user part of the SIP URI), any
such characters MUST be percent encoded. 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) points to specific documents for that application usage.
Subdirectories are permitted, but are NOT RECOMMENDED. XCAP provides
no way to create sub-directories or to list their contents, thus
limiting their utility. If subdirectories are used, there MUST not
be a document in a directory with the same name as a sub-directory.
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". Barring
specific guidelines in the application usage, if a user has a single
document for a particular application usage, this SHOULD be called
"index".
Rosenberg Expires April 16, 2007 [Page 17]
Internet-Draft XCAP October 2006
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
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 path segment
"/resource-lists/users/sip:joe@example.com/index" is a document
selector. Concatenating the XCAP root URI with the document selector
produces the HTTP URI "http://xcap.example.com/resource-lists/users/
sip:joe@example.com/index". In this URI, the AUID is "resource-
lists", and the document is in the user tree with the XUI
"sip:joe@example.com" 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 an XML element, an attribute of
an element, or a set of namespace bindings. The node selector is an
expression which identifies an element, attribute or set of namespace
bindings. Its grammar is:
node-selector = element-selector ["/" terminal-selector]
terminal-selector = attribute-selector / namespace-selector /
extension-selector
element-selector = step *( "/" step)
step = by-name / by-pos / by-attr / by-pos-attr /
extension-selector
by-name = NameorAny
by-pos = NameorAny "[" position "]"
position = 1*DIGIT
attr-test = "@" att-name "=" att-value
by-attr = NameorAny "[" attr-test "]"
by-pos-attr = NameorAny "[" position "]" "[" attr-test "]"
NameorAny = QName / "*" ; QName from XML Namespaces
att-name = QName
att-value = AttValue ; from XML specification
attribute-selector = "@" att-name
Rosenberg Expires April 16, 2007 [Page 18]
Internet-Draft XCAP October 2006
namespace-selector = "namespace::*"
extension-selector = 1*( %x00-2e / %x30-ff ) ; anything but "/"
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].
The extension-selector is included for purposes of extensibility. It
can be composed of any character except the slash, which is the
delimeter amongst steps. Any characters in an extension that cannot
be represented in a URI MUST be percent-encoded before placement into
a URI.
Note that the double quote, left square bracket and right square
bracket characters, which are meaningful to XCAP, cannot be directly
represented in the HTTP URI. As a result, they are percent-encoded
when placed within the HTTP URI. In addition to these characters, an
apostrophe (') character can be used as a delimiter within XPath
expressions. 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 percent-encoding that sequence of
octets.
Similarly, the XML specification defines the QName production for the
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 percent- encoded 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
percent- encoded. To do this, the data should be encoded first as
octets according to the UTF-8 character encoding [18] and then only
those octets that do not correspond to characters in the pchar 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 decoded the URI. The on-
the-wire format is dictated by RFC 3986 [13]. 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
Rosenberg Expires April 16, 2007 [Page 19]
Internet-Draft XCAP October 2006
example includes a node selector within an HTTP URI, it is presented
in its percent-encoded form.
The node selector is based on the concepts in XPath [10]. Indeed,
the node selector expression, before it is percent-encoded 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, attribute or namespace bindings
selected by the node selector, processing begins at the root node 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
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -