Copyright © 2009 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.
This specification extends the WS-Transfer [WS-Transfer] specification to enable clients to
retrieve and manipulate subsets
parts or fragments of a WS-Transfer
enabled resource without needing to include the entire XML
representation in a message exchange.
1 Introduction
1.1 Requirements
2 Terminology and
Notation
2.1 Terminology
2.2 XML
Namespaces
2.3 Notational
Conventions
2.4 Considerations on the
Use of Extensibility Points
2.5 Compliance
3 Fragment WS-Transfer Dialect
3.1 Get
3.2 Put
3.3 Delete
3.4 Create
4 Examples
4.1 Examples
5 QName Expression Language
5.1 Get
5.2 Put 5.3 Delete
5.4 Create 6 XPath Level
1 Expression Language
7 XPath 1.0 Expression Language
8 Faults
8.1 UnsupportedLanguage
8.2 InvalidFragment
8.3 InvalidExpression
8.4 UnsupportedMode
9 WS-Fragment Policy
Assertion(s) Metadata
9.1 Fragment
Assertion
10 Acknowledgements
11 References
11.1 Normative
References
A XML
Schema
B WSDL C Change
Log
D Open Questions and Actions
This specification extends the WS-Transfer specification and defines a mechanism that allows clients to retrieve and manipulate subsets (parts or fragments) of a WS-Transfer enabled resource without needing to include the entire XML representation in a message exchange.
This specification defines a fragment transfer mechanism, an extension framework for defining expression languages, and a set of expression languages.
The fragment transfer mechanism is defined as an extension to
WS-Transfer. This involves defining a WS-Transfer Dialect and
corresponding XML elements that go into the SOAP Body of the
Get, Put, Delete Get and Create
Put WS-Transfer operations. This
fragment transfer mechanism is designed so that it can be used with
any number of expression languages to indentify a subset of the
resource the operation is to operate over. on.
While other specifications can define other expression languages, it is RECOMMENDED that those languages reuse the fragment transfer framework that this specification defines.
This specification intends to meet the following requirement:
Provide an extension mechanism to WS-Transfer that allows for
subsets (parts or fragments) of a
resource to be retrieved and
or modified.
Provide an extension framework for defining expression languages.
Provide a set of expression languages that implementations can leverage.
A Language specific set of tokens that are
used refer resolves to a location
in a resource that contains a subset of
the resource.
A subset of a resource.
The XML Namespace URI that MUST be used by implementations of this specification is:
http://www.w3.org/2009/02/ws-frahttp://www.w3.org/2009/09/ws-fra
Table 2-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.
Prefix | XML Namespace | Specification(s) |
---|---|---|
wsf | This specification | |
s | Either SOAP 1.1 or 1.2 | SOAP |
s11 | http://schemas.xmlsoap.org/soap/envelope/ | |
s12 | http://www.w3.org/2003/05/soap-envelope | |
wsa | http://www.w3.org/2005/08/addressing | [WS-Addressing] |
http://www.w3.org/2001/XMLSchema | XML Schema |
|
wst | [WS-Transfer] |
The working group intends to update the value of the Web Services Fragment namespace URI each time a new version of this document is published until such time that the document reaches Candidate Recommendation status. Once it has reached Candidate Recommendation status, the working group intends to maintain the value of the Web Services Fragment namespace URI that was assigned in the Candidate Recommendation unless significant changes are made that impact the implementation or break post-CR implementations of the specification. Also see http://www.w3.org/2001/tag/doc/namespaceState.html and http://www.w3.org/2005/07/13-nsuri .
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119] .
This specification uses the following syntax to define outlines for messages:
The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.
Characters are appended to elements and attributes to indicate cardinality:
"?" (0 or 1)
"*" (0 or more)
"+" (1 or more)
The character "|" is used to indicate a choice between alternatives.
The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.
The characters "[" and "]" are used to call out references and property names.
Ellipsis (i.e. "...") indicate points of extensibility.
XML namespace prefixes (see Table 2-1 ) are used to indicate the namespace of the element being defined.
In addition to Message Information Header properties [WS-Addressing] , this specification uses the following properties to define messages:
Unordered message headers.
The value to be used for the wsa:Action URI. IRI.
A message body.
These properties bind to a SOAP Envelope as follows:
<s:Envelope> <s:Header> [Headers] <wsa:Action>[Action]</wsa:Action> ... </s:Header> <s:Body>[Body]</s:Body> </s:Envelope>
This specification can be used in terms of XML Information Set
(Infoset) [XMLInfoset] [XML Infoset] , even
though the specification uses XML 1.0 terminology. Valid Infoset
for this specification are is the one serializable in XML 1.0, hence the use
of XML 1.0.
In the outlines, bold text is used to indicate those parts of the message that are defined as part of this specification and are extensions to the WS-Transfer messages.
The elements defined in this specification MAY be extended at the points indicated by their outlines and schema. Implementations MAY add child elements and/or attributes at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively. If a receiver does not recognize an extension, the receiver SHOULD ignore that extension. Senders MAY indicate the presence of an extension that has to be understood through the use of a corresponding SOAP Header with a soap:mustUnderstand attribute with the value "1".
In cases where it is either desirable or necessary for the receiver of a request that has been extended to indicate that it has recognized and accepted the semantics associated with that extension, it is RECOMMENDED that the receiver add a corresponding extension to the response message. The definition of an extension SHOULD clearly specify how the extension that appears in the response correlates with that in the corresponding request.
Extension elements and attributes MUST NOT use the Web Services Fragment namespace URI.
An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML namespace identifier for this specification (listed in 2.2 XML Namespaces ) within SOAP Envelopes unless it is compliant with this specification.
Normative text within this specification takes precedence over the XML Schema and WSDL descriptions, which in turn take precedence over outlines, which in turn take precedence over examples.
All messages defined by this specification MUST be sent to a Web service that is addressable by an EPR (see [WS-Addressing] ).
Unless otherwise noted, all URIs
IRIs are absolute URIs IRIs and
URI IRI
comparison MUST be performed according to [RFC
3986] 3987] section 6.2.1. 5.3.1.
For any message defined by this specification, any OPTIONAL elements or attributes in the message MAY be used by senders of the message, however receivers of those messages MUST understand those OPTIONAL elements and attributes, unless other behavior is explicitly defined by this specification.
This section defines the fragment transfer mechanism that the expression languages defined in subsequent sections will use. The following sections define the expected behavior when the WS-Fragment Dialect is used in each of the WS-Transfer operations.
Each Expression language that uses this
transfer fragment mechanism MUST fully define how it behaves for
each operation and for the language specific expression constructs
it supports. For example, an XPath language will need to explain
how a new XML element is inserted into an existing resource.
WS-Transfer defines what the expected behavior of a resource is
with respect to modifications of the resource that might result in
an invalid state or if the client does not have the authority to
perform such operations. This specification only extends but does
not modify the base WS-Transfer behavior.
To retrieve a subset of a resource a client MUST specify the
WS-Fragment URI Dialect IRI in the wst:Get request.
The Get request message MUST be of the following form:
[Action]http://www.w3.org/2009/02/ws-tra/Gethttp://www.w3.org/2009/09/ws-tra/Get [Body]<wst:Get Dialect="http://www.w3.org/2009/02/ws-frag" ...> <wsf:Expression Language="" ...> *<wst:Get Dialect="http://www.w3.org/2009/09/ws-fra" ...> <wsf:Expression Language="xs:anyURI" ...> xs:any * </wsf:Expression> xs:any * </wst:Get>
The following describes additional, normative constraints on the outline listed above:
This attribute MUST be set to http://www.w3.org/2009/02/ws-frag. http://www.w3.org/2009/09/ws-fra.
This element identifies which fragment in the resource this
operation applies to. The If the value of this element MUST does not conform
to the syntax of the language specified in the Language attribute, otherwise or is semantically
invalid, a wsf:InvalidExpression fault MUST be generated.
This URI IRI indicates which expression language will be
used to identify the subset of the resource this operation applies
to. A resource MUST generate a wsf:UnsupportedLanguage Fault if it
does not support the specified Language.
If the resource accepts a Get request, it MUST reply with a response of the following form:
[Action]http://www.w3.org/2009/02/ws-tra/GetResponsehttp://www.w3.org/2009/09/ws-tra/GetResponse [Body] <wst:GetResponse ...><wsf:Value> * </wsf:Value> *<wsf:Value ...> xs:any * </wsf:Value> xs:any * </wst:GetResponse>
The following describes additional, normative constraints on the outline listed above:
This element encompasses the fragment response corresponding to
the wsf:Expression in the request and MUST contain the subset of
the resource identified by the wsf:Expression element in the
corresponding Get request. If the Expression identifies non-existent data, or it corresponds
evaluates to a fragment with no value,
then this element MAY be empty.
Other components of the outline above are not further constrained by this specification.
To update a subset of a resource a client MUST specify the
WS-Fragment URI IRI in the wst:Put request.
The Put request message MUST be of the following form:
[Action]http://www.w3.org/2009/02/ws-tra/Puthttp://www.w3.org/2009/09/ws-tra/Put [Body]<wst:Put Dialect="http://www.w3.org/2009/02/ws-frag" ...> <wsf:Fragment ...> <wsf:Expression Language="" ...> *<wst:Put Dialect="http://www.w3.org/2009/09/ws-fra" ...> <wsf:Fragment ...> <wsf:Expression Language="xs:anyURI" Mode="xs:anyURI"? ...> xs:any * </wsf:Expression> <wsf:Value ...>* </wsf:Value>xs:any * </wsf:Value> ? </wsf:Fragment> xs:any * </wst:Put>
The following describes additional, normative constraints on the outline listed above:
This attribute MUST be set to http://www.w3.org/2009/02/ws-frag. http://www.w3.org/2009/09/ws-fra.
This element contains an expression that identifies the location of a fragment in the resource and a value for the fragment. If the contents of this element are invalid a wsf:InvalidFragment fault MUST be generated.
This element identifies which fragment in the resource this
operation applies to. The If the value of this element MUST does not conform
to the syntax of the language specified in the Language attribute, otherwise or is semantically
invalid, a wsf:InvalidExpression fault MUST be generated.
This element identifies the fragment in the resource as it appears after successfully processing the Put request.
This URI IRI indicates which expression language will be
used to identify the subset of the resource this operation applies
to. A resource MUST generate a wsf:UnsupportedLanguage Fault fault if it does
not support the specified Language.
This element contains the fragment
resource representation corresponding to OPTIONAL attribute indicates the subset type of
the resource identified by the wsf:Expression
element. This operation MUST update
to be performed by removing any data
that corresponds to the Expression element of the request and
inserting the specified Fragment data in its place. If the
Expression identifies non-existent data then this operation will
not have any impact on the resource. In
other words, to insert new information into a resource the
wst:Create operation this fragment. The
implied value for this attribute is to
be used. Note: do we really want this? Should the client really be
forced to know whether or not there's data there just to add
something? What if, instead, we just allowed it to replace the
existing data (if any)? If the "http://www.w3.org/2009/09/ws-fra/Modes/Replace".
A resource accepts a Put request,
it MUST reply with a response of the
following form: http://www.w3.org/2009/02/ws-tra/PutResponse
<wst:PutResponse ...> * </wst:PutResponse> There are no
additional constraints beyond what WS-Transfer defines. 3.3 Delete
To delete a subset of a resource generate a client MUST
specify the WS-Fragment URI in the wst:Delete request. The Delete
request message MUST be of the following form:
http://www.w3.org/2009/02/ws-tra/Delete <wst:Delete
Dialect="http://www.w3.org/2009/02/ws-frag" ...>
<wsf:Expression Language="" ...> * </wsf:Expression> *
</wst:Delete> The following describes additional, normative
constraints on wsf:UnsupportedMode
fault if the outline listed
above: specified Mode is not
supported.
This When the
Mode attribute MUST be
is set to http://www.w3.org/2009/02/ws-frag. [Body]
/wst:Delete/wsf:Expression This element identifies which fragment
in the resource this operation applies to. The a value of this
"http://www.w3.org/2009/09/ws-fra/Modes/Replace" the
resource representation specified within the Value element
MUST conform to replace the syntax
entire resource representation referenced by
the children of the language specified
in Language attribute, otherwise a wsf:InvalidExpression fault MUST
be generated. Expression element, if it
exists.
This URI indicates which expression
language will be used to identify When the subset
Mode attribute is set to a value of
"http://www.w3.org/2009/09/ws-fra/Modes/Insert"
the resource this operation applies to. A
resource MUST generate a wsf:UnsupportedLanguage Fault if it does
not support the representation
specified Language. This operation
within the Value element MUST be
performed by removing any data that
corresponds added to the
Expression element of the request.
resource representation. If the
Expression identifies non-existent data then
this operation will not have any impact on expression targets a repeated element (maxOccurs >
1), the resource and no fault is
generated. fragment MUST be added at
the end. If the resource accepts
expression targets a Delete request, it non-repeated element (maxOccurrs = 1) that already
exists, the resource MUST reply
with generate a response of wst:InvalidRepresentation fault. If the
following form:
http://www.w3.org/2009/02/ws-tra/DeleteResponse
<wst:DeleteResponse ...> * </wst:DeleteResponse> There
are no additional constraints beyond what WS-Transfer defines. 3.4
Create To insert data into expression
targets an existing resource
item of a client
MUST specify the WS-Fragment URI in repeated element, the wst:Delete request. The Create request message
fragment MUST be of the following form:
http://www.w3.org/2009/02/ws-tra/Create <wst:Create
Dialect="http://www.w3.org/2009/02/ws-frag" ...>
<wsf:Fragment ...> <wsf:Expression Language="" ...> *
</wsf:Expression> <wsf:Value ...> * </wsf:Value>
</wsf:Fragment> * </wst:Create> The following describes
additional, normative constraints on added before the outline
listed above: existing item.
This When the
Mode attribute MUST be
is set to http://www.w3.org/2009/02/ws-frag. [Body]
/wst:Create/wsf:Fragment/wsf:Expression This element identifies
which fragment in the resource this operation applies to. The
a value of this
element MUST conform to "http://www.w3.org/2009/09/ws-fra/Modes/Remove"
the syntax resource representation referenced by the children
of the language specified in Language
attribute, otherwise a wsf:InvalidExpression fault
Expression element MUST be generated. This element identifies the fragment in
deleted from the resource as it appears after successful processing of the current
fragment. representation.
This URI indicates which expression
language will be used to identify the subset of Note: the resource this
operation applies to. A resource Value
element MUST generate a
wsf:UnsupportedLanguage Fault NOT be
present if it does not support the
specified Language. this attribute has
a value of
"http://www.w3.org/2009/09/ws-fra/Modes/Remove".
This OPTIONAL element encompasses contains
the fragment resource representation
corresponding to the subset of the resource indentified identified
by the wsf:Expression element.
When Mode is "http://www.w3.org/2009/09/ws-fra/Modes/Insert" or "http://www.w3.org/2009/09/ws-fra/Modes/Replace", any optional values (element or attributes) within this subset that are not specified in the Value element will be set to a resource-specific default value.
This operation element MUST NOT be
performed by inserting new data within
present if the Fragment Mode attribute has
a value of "http://www.w3.org/2009/09/ws-fra/Modes/Remove".
This element into the resource as
specified by the Expression element. If data is already
MUST be present and would result in if
the resource being left in an invalid state
then Mode attribute has a
wst:InvalidRepresentation fault MUST
value of either
"http://www.w3.org/2009/09/ws-fra/Modes/Replace" or
"http://www.w3.org/2009/09/ws-fra/Modes/Insert". When present, this
element can either be generated.
empty or non-empty.
If the resource accepts a Create
Put request, it MUST reply with a
response of the following form:
[Action]http://www.w3.org/2009/02/ws-tra/CreateResponsehttp://www.w3.org/2009/09/ws-tra/PutResponse [Body]<wst:CreateResponse ...> <wst:ResourceCreated> </wst:ResourceCreated><wst:PutResponse ...> xs:any *</wst:CreateResponse></wst:PutResponse>
There are no additional constraints beyond what WS-Transfer defines.
In the following examples, and Expression Language definitions, the following representation of a resource is used for informational purposes:
<ab:AddressBook xmlns:ab="http://example.com/address"> <ab:owner>Me</owner> <ab:size>2</size> <ab:contact> <ab:name>Joe Brown</name> <ab:address>123 Main Street</address> <ab:city>AnyTown</city> <ab:state>CA</state> <ab:zip>90210</zip> <ab:email>joe@example.com</email> </ab:contact> <ab:contact> <ab:name>Mary Smith</name> <ab:address>345 South Pine</address> <ab:city>AnyTown</city> <ab:state>CA</state> <ab:zip>90210</zip> <ab:email>mary@example.com</email> </ab:contact> </ab:AddressBook>
The following shows a sample SOAP envelope containing a Get request:
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:ex="http://www.example.com/" > <s:Header> <wsa:To>http://www.example.org/resourceABC</wsa:To> <wsa:Action>http://www.w3.org/2009/02/ws-tra/Gethttp://www.w3.org/2009/09/ws-tra/Get </wsa:Action> <wsa:MessageID> uuid:00000000-0000-0000-C000-000000000046 </wsa:MessageID> </s:Header> <s:Body><wst:Get> <wsf:Expression Language=".../ws-frag/QName"><wst:Get Dialect="http://www.w3.org/2009/09/ws-fra"> <wsf:Expression Language="http://www.w3.org/2009/09/ws-fra/QName"> ab:contact </wsf:Expression> </wst:Get> </s:Body> </s:Envelope>
The following shows the corresponding response message:
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:ex="http://www.example.com/" > <s:Header> <wsa:Action>http://www.w3.org/2009/02/ws-tra/GetResponsehttp://www.w3.org/2009/09/ws-tra/GetResponse </wsa:Action> <wsa:MessageID> uuid:0000010e-0000-0000-C000-000000000047 </wsa:MessageID> <wsa:RelatesTo> uuid:00000000-0000-0000-C000-000000000046 </wsa:RelatesTo> </s:Header> <s:Body> <wst:GetResponse> <wsf:Value> <ab:contact> <ab:name>Joe Brown</name> <ab:address>123 Main Street</address> <ab:city>AnyTown</city> <ab:state>CA</state> <ab:zip>90210</zip> <ab:email>joe@example.com</email> </ab:contact> <ab:contact> <ab:name>Mary Smith</name> <ab:address>345 South Pine</address> <ab:city>AnyTown</city> <ab:state>CA</state> <ab:zip>90210</zip> <ab:email>mary@example.com</email> </ab:contact> </wsf:Value> </wst:GetResponse> </s:Body> </s:Envelope>
The QName expression language is a syntax for expressions that uses a single QName to reference the immediate children of the root element of the resource representation. The expression MUST evaluate to zero or more elements, each including the element name, any attributes and its entire content. This language can be implemented as a precise subset of the XPath 1.0 [XPath1.0] language.
The QName language MUST be indicated by using the URI: IRI:
http://www.w3.org/2009/02/ws-fra/QNamehttp://www.w3.org/2009/09/ws-fra/QName
The XPath Level 1 expression language uses an XPath to reference specific fragments of the resource representation. The XPath is logically applied to the XML representation of the resource and the resulting node-set is the resource fragment which is the subject of the message containing the expression. This language is useful for resources with limited XPath processing capability which do not need to support returning values computed from their resource representation.
XPath Level 1 is a subset of the abbreviated relative syntax of
XPath 1.0, 1.0 [XPath1.0] , and is used to identify or select
a node (element, attribute or value)
within a resource representation or fragment. It is identified by
the following URI: IRI:
http://www.w3.org/2009/02/ws-fra/XPath-Level-1http://www.w3.org/2009/09/ws-fra/XPath-Level-1
An XPath Level 1 expression is an expression whose context is:
Context Node: the root element of the XML representation of the resource
Context Position: 1
Context Size: 1
Variable Binding: None
Node Tests: NameTest and the text NodeType
Function Libraries: None
Namespace Declarations: Any namespace declarations in-scope where the XPath expression appears
An implementation that uses the XPath Level 1 language MUST
support the expressions whose syntax is described by the following
BNF. It MAY support additional expressions defined by XPath 1.0.
The following XPath Level 1 grammar is LL(1), and the nonterminal non-terminal productions are in angle brackets.
Terminal symbols are either literals, or in UPPERCASE:
(01) <xpath> ::= <context> <node_sequence>; (02) (03) <context> ::= '/' | <>; (04) (05) <node_sequence> ::= (06) <element> <optional_collection_operator> <more>; (07) (08) <optional_collection_operator> ::= '[' <array_location> ']'; (09) <optional_collection_operator> ::= <>; (10) (11) <more> ::= '/' <follower> | <>; (12) (13) <follower> ::= (14) <attribute> | <text_function> | <node_sequence>; (15) (16) <element> ::= <qualified_name>; (17) <attribute> ::= '@' <qualified_name>; (18) (19) <qualified_name> ::= <name> <qname_follower>; (20) <qname_follower> ::= ':' <name> | <>; (21) <text_function> ::= "text()" ; (22) <array_location> ::= NONZERO_DECIMAL_UNSIGNED_INTEGER; (23) <name> ::= XML_TOKEN;
The terminal tokens which require further lexical specification
are NONZERO_DECIMAL_UNSIGNED_INTEGER, whose values are in the
subrange sub-range (1...4294967295), and XML_TOKEN whose
values are equivalent to those for the XML Schema type
xs:token . This grammar is small enough that it can be
easily implemented in resource-constrained implementations.
The following comments on the grammar will clarify certain constructs within the BNF.
Most of the examples assume the following XML sample acting as a "resource" document:
(01) <a> (02) <b> (03) <c d="30"> 20 </c> (04) </b> (05) <e> (06) <f/> (07) <f/> (08) </e> (09) </a>
The context and document root node need clarification. XPath Level 1 assumes that the root is the root node of the resource document, not the SOAP envelope or any other wrapper element which might contain the resource.
Further, the default context is the root element and the context position is 1.
In view of this, the / operator selects the containing root, and the only valid operand which can follow it is the outermost element of the resource:
(01) /a
The following paths are equivalent:
(01) /a/b (02) b
Note that because the context node is the root element, a relative path selects a matching child element.
The <node_sequence> production provides the recursive behavior for the XPath:
(01) /a/b/c (02) b/c
It also provides for selecting specific repeated elements through the <optional_collection_operator> production:
(01) /a/e/f[2]
The collection operator only takes unsigned nonzero values, as defined above for NONZERO_DECIMAL_UNSIGNED_INTEGER. Thus, [1] is the first of a repeating series of elements.
The <qualified_name> production allows the XML naming tokens to be either namespace-qualified or unqualified:
(01) /ns1:a/ns2:b/c
The namespace bindings are evaluated against any namespace declarations that are in scope where the XPath appears within the SOAP message.
NOTE: If the element name is unqualified, i.e. appears without a namespace prefix, then the element name MUST be matched against a matching element name in the resource document, regardless of namespace bindings that are in effect, including default bindings. This allows implementations to simply match element names in the majority of cases. If namespace bindings are significant for all elements, then qualified names MUST be used.
The <follower> production allows for special-casing of the final tokens of the XPath allowing it to end in either an attribute or text.
The text() NodeTest MAY be applied as a final token to the selected element. This NodeTest selects any text nodes that are children of the selected element. If the element only contains text content, the return value will be a node-set containing a single text node.
(01) b/c/text()
The above expression would return a node-set containing a single text node with the value 20 as its result. This text node would then be serialized into the following XML representation:
(01) <wsf:TextNode>20</wsf:TextNode>
If accessed, attributes MUST be the final token in the path and they MAY be namespace-qualified or unqualified names, as required:
(01) /a/b/c/@d
The above expression would return a node-set containing a single attribute node with the value d="30" as its result. This attribute node would then be serialized into the following XML representation:
(01) <wsf:AttributeNode name="d">30</wsf:AttributeNode>
Selection of an element returns the element and its entire content. The path /a/b executed against the sample XML returns a node-set containing a single element node which serializes directly:
(01) <b> <c d="30"> 20 </c> </b>
In the event that there is more than one node which would match the XPath, the implementation SHOULD select or return the first node only. This allows simple implementations to avoid the overhead of checking the remainder of the resource document for a possible match.
Conformant implementations MAY supply additional functions and capabilities, but MUST adhere to the minimum behavior described above.
Expressions in this language MUST NOT evaluate to more than a single node. The XPath Level 1 language does not support computed values. Text and attribute nodes MUST be serialized using the same serialization as for the XPath 1.0 language.
The XPath 1.0 expression language uses an XPath to reference specific fragments of the resource representation. The XPath is logically applied to the XML representation of the resource and the result of the XPath is returned as the value for that expression. The XPath 1.0 language supports a wider set of XPath function libraries than the XPath Level 1 language. This language is useful for resources with full XPath processing capability or which need to support returning values computed from their resource representation.
An XPath 1.0 expression is an expression whose context is:
Context Node: the root element of the XML representation of the resource
Context Position: 1
Context Size: 1
Variable Binding: None
Function Libraries: Core function library
Namespace Declarations: Any namespace declarations in-scope where the XPath expression appears
The XPath 1.0 language can define references to any element, attribute or value in the resource representation and can also be used to compute values from the resource representation.
The XPath 1.0 language MUST be indicated by using the
URI: IRI:
http://www.w3.org/2009/02/ws-fra/XPathhttp://www.w3.org/2009/09/ws-fra/XPath
Implementations that support the full XPath 1.0 language MUST support the XPath Level 1 language.
Note that the expression MAY evaluate to one of four possible types: a node-set, a Boolean, a number or a string. The latter three types are the results of evaluating a computed expression. They are serialized by performing the following conversion and then wrapping the result in the wsf:Value element:
Boolean - converted to an xs:boolean
string - convert to an xs:string
number - convert to an xs:double
A node-set is zero or more elements, attributes or text values of elements. A node-set is serialized into XML by concatenating each node and enclosing it in the wsf:Value wrapper XML element for which schema validation is suppressed. Element nodes in a node-set are serialized directly into their XML representation. For attributes and text nodes in the node-set, a wrapper element is used to enclose these values to distinguish them from other such nodes in the serialized result.
Attribute nodes in XPath are represented in the following form:
name="value"
Serialization of an attribute node separates the name from the value using the following element:
(01) <wsf:AttributeNode name="attribute name"> (02) attribute value (03) </wsf:AttributeNode>
The following describes additional constraints on the outline listed above:
This element is used to serialize an attribute node in a node-set and MUST contain the value portion of the attribute node.
This attribute MUST be the name portion of the attribute node.
Text nodes are serialized in the following form:
(01) <wsf:TextNode> (02) text value (03) </wsf:TextNode>
The following describes additional constraints on the outline listed above:
This element is used to serialize a text node in a node-set and
MUST contain the text value. (01) <a
xmlns="example">
Given the following XML as an example document.
(01) <a xmlns="example"> (02) <b>1</b> (03) <c x="y">2</c> (04) </a>
The result of the XPath "/a/b | /a/b/text() | /a/c/@x" would be serialized as the following:
(01) <wsf:Value> (02) <b>1</b> (03) <wsf:TextNode>1</wsf:TextNode> (04) <wsf:AttributeNode name="x">y</wsf:AttributeNode> (05) </wsf:Value>
The nodes in the node-set MAY be serialized in any order.
The WS-Fragment global element definition wsf:NodeSet can also
be used as the wrapper element when serializing these node-sets
outside of a WS-RT WS-Fragment result.
An XPath 1.0 expression MAY evaluate to multiple nodes; because of this the XPath 1.0 language MUST NOT be used with a "Put" or "Create" operation.
All fault messages defined in this specification MUST be sent according to the rules and usage described in [WS-Addressing 1.0 SOAP Binding] Section 6 for encoding SOAP 1.1 and SOAP 1.2 faults. The [Action] property below MUST be used for faults defined in this specification:
http://www.w3.org/2009/02/ws-fra/faulthttp://www.w3.org/2009/09/ws-fra/fault
The definitions of faults in this section use the following properties:
[Code] The fault code.
[Subcode] The fault subcode.
[Reason] The English language reason element.
[Detail] The detail element. If absent, no detail element is
defined for the fault.
For SOAP 1.2, the [Code] property MUST be either "Sender" or "Receiver". These properties are serialized into text XML as follows:
SOAP Version | Sender | Receiver |
---|---|---|
SOAP 1.2 | s12:Sender | s12:Receiver |
The properties above bind to a SOAP 1.2 fault as follows:
<s12:Envelope><s12:Header> <wsa:Action> </wsa:Action> <!-- Headers elided for brevity. --> </s12:Header> <s12:Body> <s12:Fault> <s12:Code> <s12:Value></s12:Value> <s12:Subcode> <s12:Value></s12:Value> </s12:Subcode> </s12:Code> <s12:Reason> <s12:Text xml:lang="en"></s12:Text> </s12:Reason> <s12:Detail> ... </s12:Detail> </s12:Fault> </s12:Body><s12:Header> <wsa:Action> [Action] </wsa:Action> <!-- Headers elided for brevity. --> </s12:Header> <s12:Body> <s12:Fault> <s12:Code> <s12:Value>[Code]</s12:Value> <s12:Subcode> <s12:Value>[Subcode]</s12:Value> </s12:Subcode> </s12:Code> <s12:Reason> <s12:Text xml:lang="en">[Reason]</s12:Text> </s12:Reason> <s12:Detail> [Detail] ... </s12:Detail> </s12:Fault> </s12:Body> </s12:Envelope>
The properties bind to a SOAP 1.1 fault as follows:
<s11:Envelope> <s11:Body> <s11:Fault> <faultcode> [Subcode] </faultcode> <faultstring xml:lang="en"> [Reason] </faultstring> <detail> [Detail] ... </detail> </s11:Fault> </s11:Body> </s11:Envelope>
This fault is generated when a service detects an unknown
or unsupported Language URI IRI in a request
message.
[Code] | s:Sender |
---|---|
[Subcode] | |
[Reason] | The specified Language |
[Detail] | The |
This fault is generated when a service determines that the fragment (contents of the wsf:Fragment element) specified in a request is invalid.
[Code] | s:Sender |
---|---|
[Subcode] | wst:InvalidFragment |
[Reason] | The specific fragment is invalid. |
[Detail] | The invalid fragment. |
This fault is generated when a service determines that the Language expression specified in a request does not conform to the syntax of the language specified in the Language attribute or is semantically invalid.
[Code] | s:Sender |
---|---|
[Subcode] | wst:InvalidExpression |
[Reason] | The specified Language expression is invalid. |
[Detail] | The invalid language expression. |
An endpoint MAY indicate that it supports WS-Fragment, or its
features, by including the WS-Fragment Policy assertion(s) assertion
within its WSDL. By doing so the endpoint is indicating that the
corresponding WS-Fragment operations
features are supported by that
endpoint.
The mechanism for indicating that a
binding or endpoint even though
conforms to the WS-Fragment specification is
through the use of the Web Services Policy - Framework
[WS-Policy]
and Web Services Policy - Attachment
[WS-Policy
Attachment] specifications.
This specification defines a policy assertion (wsf:FragmentAssertion). The wsf:FragmentAssertion policy assertion applies to the endpoint policy subject.
For WSDL 1.1, these assertions MAY be
attached to wsdl11:port or wsdl11:binding. For WSDL 2.0, they
do not explicitly appear MAY be attached to wsdl20:endpoint or wsdl20:binding. A
policy expression containing the wsf:FragmentAssertion policy
assertion MUST NOT be attached to a wsdl:portType or
wsdl20:interface.
The wsf:FragmentAssertion policy assertion is a nested policy container assertion. The meaning of this assertion, when present in a policy alternative, is that WS-Fragment is required to communicate with the subject and that the subject is a WS-Transfer Resource.
In order to indicate that the subject
supports WS-Fragment but does not require its WSDL. use, an additional
policy alternative SHOULD be provided which does not contain this
assertion. The compact authoring style for an OPTIONAL policy
assertion (the wsp:Optional attribute) provided by WS-Policy MAY be
used to indicate two policy alternatives, one which contains the
policy assertion, and another which does not.
The normative outline of this assertion is:
<wsf:FragmentAssertion ...> <wsf:Language ...> xs:anyURI </wsf:Language> * ... </wsf:FragmentAssertion>
The following describes additional, normative constraints on the outline listed above:
A policy assertion that specifies that WS-Fragment protocol MUST be used when communicating with this endpoint. This assertion has Endpoint Policy Subject.
When present, this OPTIONAL parameter indicates support for the specified Language IRI.
This specification has been developed as a result of joint work
with many individuals and teams, including: Ashok Malhotra (Oracle
Corp.), Asir Vedamuthu (Microsoft Corp.), Bob Freund (Hitachi,
Ltd.), Doug Davis (IBM), Fred Maciel (Hitachi, Ltd.), Geoff Bullen
(Microsoft Corp.), Gilbert Pilz (Oracle Corp.), Greg Carpenter
(Microsoft Corp.), Jeff Mischkinsky (Oracle Corp.), Katy Warr
(IBM), Li Li (Avaya Communications), Mark Little (Red Hat), Prasad
Yendluri (Software AG), Ram Jeyaraman (Microsoft Corp.), Sreedhara
Narayanaswamy (CA), Sumeet Vij (Software AG), Vikas Varma (Software
AG), Wu Chou (Avaya Communications), Yves Lafon (W3C) (W3C).
A normative copy of the XML Schema [XML
Schema, [XMLSchema - Part 1] , [XML Schema, [XMLSchema - Part 2] description for this
specification can be retrieved from the following address:
http://www.w3.org/2009/02/ws-fra/fragment.xsdhttp://www.w3.org/2009/09/ws-fra/fragment.xsd
A non-normative copy of the XML schema is listed below for convenience.
<xs:schematargetNamespace="http://www.w3.org/2009/02/ws-fra" xmlns:tns="http://www.w3.org/2009/02/ws-fra"targetNamespace="http://www.w3.org/2009/09/ws-fra" xmlns:tns="http://www.w3.org/2009/09/ws-fra" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns:wsa="http://www.w3.org/2005/08/addressing"elementFormDefault="qualified" blockDefault="#all" > <xs:complexType name="ExpressionType"> <xs:sequence> <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attribute name="Language" type="xs:anyURI" use="required"/> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType> <xs:element name="Expression" type="tns:ExpressionType"/> <xs:complexType name="ValueType"> <xs:sequence> <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType> <xs:element name="Value" type="tns:ValueType"/> <xs:element name="Fragment"> <xs:complexType> <xs:sequence> <xs:element name="Expression" type="tns:ExpressionType"/> <xs:element name="Value" type="tns:ValueType" minOccurs="0"/> <xs:any namespace="##other" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType> </xs:element> <!-- Policy --> <xs:complexType name="URI"> <xs:simpleContent> <xs:extension base="xs:anyURI"> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:element name="FragmentAssertion"> <xs:complexType> <xs:sequence> <xs:element name="Language" type="tns:URI" minOccurs="0" maxOccurs="unbounded"/> <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax" /> </xs:complexType> </xs:element> </xs:schema>
Data | Author | Description |
---|---|---|
2009/08/01 | DD | Initial draft |
2009/08/18 | DD | Added resolution of |
2009/08/18 | DD | Added resolution of issue 7197 |
2009/08/18 | DD | Added resolution of issue 7270 |
2009/09/01 | DD | Added resolution of issue 6700 |
2009/09/02 | DD | Added resolution of issue 6694 |
2009/09/30 | DD | Added resolution of issue 7088 |
2009/10/02 | DD | Added resolution of issue 7770 |
2009/10/02 | DD | Added resolution of issue 7426 |
2009/10/05 | DD | Added resolution of issue 6407 ,6721 |
2009/10/20 | DD | Added resolution of issue |