Web Services Fragment (WS-Fragment)
Latest version:
http://www.w3.org/TR/ws-fragment
Previous version:
http://www.w3.org/TR/2009/WD-ws-fragment-20090317
Editors:
Doug Davis, IBM
Ashok Malhotra,
Oracle
Katy Warr,
IBM
Wu Chou, Avaya
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 parts or fragments of a WS-Transfer enabled resource
without needing to include the entire XML representation in a message exchange.
This document is an editors' copy that
has no official standing.
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
6 XPath Level 1 Expression
Language
7 XPath 1.0 Expression Language
8 Faults
8.1 UnsupportedLanguage
8.2 InvalidExpression
8.3 UnsupportedMode
9 WS-Fragment Metadata
9.1 Fragment Assertion
10 Acknowledgements
11 References
11.1 Normative References
A XML Schema
B Change Log
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 and 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 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 or
modified.
·
Provide an extension framework for defining
expression languages.
·
Provide a set of expression languages that
implementations can leverage.
Expression
A Language
specific set of tokens that resolves to a location in
a resource that contains a subset of the resource.
Fragment
A subset of a resource.
The XML Namespace URI that MUST be used by
implementations of this specification is:
Table 2-1 lists XML namespaces that are used in this
specification. The choice of any namespace prefix is arbitrary and not
semantically significant.
|
Table 2-1: Prefixes and XML Namespaces used in this
specification. |
||
|
Prefix |
XML Namespace |
Specification(s) |
|
wsf
|
This
specification |
|
|
s |
Either SOAP
1.1 or 1.2 |
SOAP |
|
s11 |
||
|
s12 |
||
|
wsa |
||
|
xs |
XML Schema [XMLSchema - Part 1], [XMLSchema - Part 2] |
|
|
wst |
||
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:
o
"?" (0 or 1)
o
"*" (0 or more)
o
"+" (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:
[Headers]
Unordered message headers.
[Action]
The value to be used for the wsa:Action IRI.
[Body]
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)
[XML Infoset], even though
the specification uses XML 1.0 terminology. Valid Infoset
for this specification is the one serializable in XML
1.0, hence the use of XML 1.0.
The
term "generate" is used in relation to the various faults defined by
this specification to imply that a fault is produced and no futher
processing SHOULD be performed. In these cases the fault SHOULD be transmitted.
However, there might be reasons when a compliant implementation can choose not
to transmit the fault - for example, security concerns - in these situations
the fault MAY NOT be transmitted.
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 IRIs are absolute IRIs and IRI comparison MUST be performed according to [RFC 3987] section 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 support 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.
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 Dialect IRI in the wst:Get request.
The Get request message MUST be of the
following form:
[Action]
http://www.w3.org/2002/ws/ra/edcopies/ws-tra/Get
[Body]
<wst:Get Dialect="http://www.w3.org/2002/ws/ra/edcopies/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:
[Body]/wst:Get@Dialect
This attribute MUST
be set to http://www.w3.org/2002/ws/ra/edcopies/ws-fra.
[Body]/wst:Get/wsf:Expression
This element
identifies which fragment in the resource this operation applies to. If the
value of this element does not conform to the syntax of the language specified
in the Language attribute, or is semantically invalid, a wsf:InvalidExpression fault MUST be generated.
[Body]/wst:Get/wsf:Expression@Language
This 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/2002/ws/ra/edcopies/ws-tra/GetResponse
[Body]
<wst:GetResponse ...>
<wsf:Value ...> xs:any
* </wsf:Value>
xs:any *
</wst:GetResponse>
The following describes additional, normative
constraints on the outline listed above:
[Body]/wst:GetResponse/wsf:Value
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 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 IRI in the wst:Put request.
The Put request message MUST be of the
following form:
[Action]
http://www.w3.org/2002/ws/ra/edcopies/ws-tra/Put
[Body]
<wst:Put Dialect="http://www.w3.org/2002/ws/ra/edcopies/ws-fra"
...>
<wsf:Fragment ...>
<wsf:Expression Language="xs:anyURI"
Mode="xs:anyURI"?
...>
xs:any *
</wsf:Expression>
<wsf:Value ...>
xs:any *
</wsf:Value> ?
</wsf:Fragment>
xs:any *
</wst:Put>
The following describes additional, normative
constraints on the outline listed above:
[Body]/wst:Put@Dialect
This attribute MUST
be set to http://www.w3.org/2002/ws/ra/edcopies/ws-fra.
[Body]/wst:Put/wsf:Fragment
This element
contains an expression that identifies the location of a fragment in the
resource and a value for the fragment.
[Body]/wst:Put/wsf:Fragment/wsf:Expression
This element
identifies which fragment in the resource this operation applies to. If the
value of this element does not conform to the syntax of the language specified
in the Language attribute, or is semantically invalid, a wsf:InvalidExpression fault MUST be generated.
[Body]/wst:Put/wsf:Fragment/wsf:Expression@Language
This 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.
[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode
This OPTIONAL
attribute indicates the type of update to be performed on this fragment. The
implied value for this attribute is
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Replace". A
resource MUST generate a wsf:UnsupportedMode
fault if the specified Mode is not supported.
[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Replace"
When the Mode
attribute is set to a value of "http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Replace"
the resource representation specified within the Value element MUST replace the
entire resource representation referenced by the children of the Expression
element, if it exists.
[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Insert"
When the Mode
attribute is set to a value of
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Insert" the
resource representation specified within the Value element MUST be added to the
resource representation. If the expression targets a repeated
element (maxOccurs > 1), the fragment MUST be
added at the end. If the expression targets a non-repeated element (maxOccurrs = 1) that already exists, the resource MUST
generate a wst:InvalidRepresentation
fault. If the expression targets an existing item of a repeated element, the
fragment MUST be added before the existing item.
[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Remove"
When the Mode
attribute is set to a value of
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Remove" the
resource representation referenced by the children of the Expression element
MUST be deleted from the resource representation.
Note: the Value
element MUST NOT be present if this attribute has a
value of "http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Remove".
[Body]/wst:Put/wsf:Fragment/wsf:Value
This OPTIONAL
element contains the fragment resource representation corresponding to the
subset of the resource identified by the wsf:Expression element. If the contents of this element
are invalid, a wst:InvalidRepresentation
fault MUST be generated.
When Mode is
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Insert" or
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Replace", any
optional values (element or attributes) within this subset that are not
specified in the Value element will MUST
be set to a resource-specific default value.
This element MUST
NOT be present if the Mode attribute has a value of
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Remove". This
element MUST be present if the Mode attribute has a value of either
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Replace" or
"http://www.w3.org/2002/ws/ra/edcopies/ws-fra/Modes/Insert". When
present, this element can MAYeither
be empty or non-empty.
If the resource accepts a Put request, it
MUST reply with a response of the following form:
[Action]
http://www.w3.org/2002/ws/ra/edcopies/ws-tra/PutResponse
[Body]
<wst:PutResponse ...>
<wst:Representation ...>
xs:any ?
</wst:Representation ...> ?
xs:any *
</wst:PutResponse>
There are no additional constraints beyond
what WS-Transfer defines.
This specification does not extend the Delete
operation defined in WS-Transfer.
This specification does not extend the Create
operation defined in WS-Transfer.
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>
<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/2002/ws/ra/edcopies/ws-tra/Get
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000046
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Get
Dialect="http://www.w3.org/2002/ws/ra/edcopies/ws-fra">
<wsf:Expression
Language="http://www.w3.org/2002/ws/ra/edcopies/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/2002/ws/ra/edcopies/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>
<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 IRI:
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 [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 IRI:
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 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 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
<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 needed:
(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 case of a Put operation, if the XPath expression
selects more than one node, the implementation MUST process only the first
selected node. 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.
The
XPath Level 1 language does not support computed
values. Text and attribute nodes MUST be serialized in the GetResponse
message using the same serialization as for the XPath
1.0 language. This serialization mechanism MUST NOT be
used in the PutRequest message.
The
namespace bindings are evaluated against any namespace declarations that are in
scope where the expression appears within the SOAP message. Note that the
evaluation of expressions that rely on such context dependent bindings is
fragile in the face of transformations that alter namespace prefixes. Such
transformations might occur during the transmission, processing, storage, or
retrieval of a request. Clients that wish to isolate expressions from the
effects of any changes to the namespace prefixes in the containing SOAP message
are advised to construct expressions in a manner that avoids the use of
namespace prefixes. For example, use an expression such as "/a[namespace-uri()='http://www.example.com']"
not "/ns1:a".
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 IRI:
Implementations
that support the full XPath 1.0 language MUST support
the XPath Level 1 language.
In
the case of a Put operation if the XPath expression
selects more than one node, the implementation MUST process only the first
selected node. This allows simple implementations to avoid the overhead of
checking the remainder of the resource document for a possible match.
The
remainder of this section defines an XML serialization mechanism that MUST be
used when constructing a GetResponse message. Since
the PutRequest message MUST NOT be
used to modify more than one target, these serialization rules MUST NOT be used
in a PutRequest message.
Expressions
MUST 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. When they appear in a GetResponse message
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="xs:QName">
(02) attribute value
(03) </wsf:AttributeNode>
The
following describes additional constraints on the outline listed above:
wsf:AttributeNode
This element is used to serialize an attribute node in a
node-set and MUST contain the value portion of the attribute node.
wsf:AttributeNode/@name
This attribute MUST be the qualified name 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:
wsf:TextNode
This element is used to serialize a text node in a
node-set and MUST contain the text value.
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
namespace bindings are evaluated against any namespace declarations that are in
scope where the expression appears within the SOAP message. Note that the
evaluation of expressions that rely on such context dependent bindings is
fragile in the face of transformations that alter namespace prefixes. Such
transformations might occur during the transmission, processing, storage, or retrieval
of a request. Clients that wish to isolate expressions from the effects of any
changes to the namespace prefixes in the containing SOAP message are advised to
construct expressions in a manner that avoids the use of namespace prefixes.
For example, use an expression such as "/a[namespace-uri()='http://www.example.com']" not
"/ns1:a".
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:
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:
|
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> [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 MUST be
generated when a service detects an unknown or unsupported Language IRI in a
request message.
|
s:Sender |
|
|
[Subcode] |
wst:UnsupportedLanguage |
|
[Reason] |
The specified Language IRI is not supported. |
|
[Detail] |
The unsupported Language IRI. |
This fault MUST be 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.
|
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
within its WSDL. By doing so the endpoint is indicating that the corresponding
WS-Fragment features are supported by that endpoint.
The mechanism for indicating that a
binding or endpoint 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 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 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:
/wsf:FragmentAssertion
A policy assertion that specifies that WS-Fragment
protocol MUST be used when communicating with this endpoint. This assertion has
Endpoint Policy Subject.
/wsf:FragmentAssertion/wsf:Language
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).
Key words for use in RFCs to Indicate Requirement
Levels ,
A non-normative
copy of the XML schema is listed below for convenience.
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'
elementFormDefault='qualified'
<xs:complexType name='ExpressionType'>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
<xs:attribute name='Language' type='xs:anyURI'
use='required'/>
<xs:anyAttribute namespace='##other' processContents='lax'/>
<xs:element name='Expression' type='tns:ExpressionType'/>
<xs:complexType name='ValueType'>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
<xs:anyAttribute namespace='##other' processContents='lax'/>
<xs:element name='Value' type='tns:ValueType'/>
<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:anyAttribute
namespace='##other' processContents='lax'/>
<xs:extension base='xs:anyURI'>
<xs:anyAttribute
namespace='##other' processContents='lax'/>
<xs:element name='FragmentAssertion'>
<xs:element name='Language' type='tns:URI' minOccurs='0'
<xs:any namespace='##other' processContents='lax' minOccurs='0'
<xs:anyAttribute
namespace='##other' processContents='lax' />