You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2287 lines
129 KiB
2287 lines
129 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Web Services Resource Transfer (WS-RT)</title><style type="text/css">
|
|
code { font-family: monospace; }
|
|
|
|
div.constraint,
|
|
div.issue,
|
|
div.note,
|
|
div.notice { margin-left: 2em; }
|
|
|
|
ol.enumar { list-style-type: decimal; }
|
|
ol.enumla { list-style-type: lower-alpha; }
|
|
ol.enumlr { list-style-type: lower-roman; }
|
|
ol.enumua { list-style-type: upper-alpha; }
|
|
ol.enumur { list-style-type: upper-roman; }
|
|
|
|
|
|
div.exampleInner pre { margin-left: 1em;
|
|
margin-top: 0em; margin-bottom: 0em}
|
|
div.exampleOuter {border: 4px double gray;
|
|
margin: 0em; padding: 0em}
|
|
div.exampleInner { background-color: #d5dee3;
|
|
border-top-width: 4px;
|
|
border-top-style: double;
|
|
border-top-color: #d3d3d3;
|
|
border-bottom-width: 4px;
|
|
border-bottom-style: double;
|
|
border-bottom-color: #d3d3d3;
|
|
padding: 4px; margin: 0em }
|
|
div.exampleWrapper { margin: 4px }
|
|
div.exampleHeader { font-weight: bold;
|
|
margin: 4px}
|
|
</style><link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-WG-NOTE.css" /></head><body><div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72" /></a></p>
|
|
<h1><a name="title" id="title"></a>Web Services Resource Transfer (WS-RT)</h1>
|
|
<h2><a name="w3c-doctype" id="w3c-doctype"></a>W3C Working Group Note 13 July 2010</h2><dl><dt>This version:</dt><dd>
|
|
<a href="http://www.w3.org/TR/2010/NOTE-ws-resource-transfer-20100713">http://www.w3.org/TR/2010/NOTE-ws-resource-transfer-20100713
|
|
</a>
|
|
</dd><dt>Latest version:</dt><dd>
|
|
<a href="http://www.w3.org/TR/ws-resource-transfer">http://www.w3.org/TR/ws-resource-transfer
|
|
</a>
|
|
</dd><dt>Previous version:</dt><dd>
|
|
<a href="http://www.w3.org/TR/2009/WD-ws-resource-transfer-20090924">http://www.w3.org/TR/2009/WD-ws-resource-transfer-20090924
|
|
</a>
|
|
</dd><dt>Editors:</dt><dd>Doug Davis, IBM</dd><dd>Ashok Malhotra, Oracle</dd><dd>Katy Warr, IBM</dd><dd>Wu Chou, Avaya</dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2010 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr /><div>
|
|
<h2><a name="abstract" id="abstract"></a>Abstract</h2><p>
|
|
This specification defines extensions to
|
|
<a href="http://www.w3.org/2009/09/ws-tra">WS-Transfer</a>
|
|
primarily to provide fragment-based access to resources. This document is in the state
|
|
</p></div><div>
|
|
<h2><a name="status" id="status"></a>Status of this Document</h2><p><em>
|
|
This section describes the status of this document at the time
|
|
of its publication. Other documents may supersede this document.
|
|
A list of current W3C publications and the latest revision of
|
|
this technical report can be found in the
|
|
<a href="http://www.w3.org/TR/">W3C technical reports index</a>
|
|
at http://www.w3.org/TR/.
|
|
</em></p><p><strong>This document has been discontinued as of September 24, 2009. This document
|
|
has been obsoleted and parts of this document have been replaced in the
|
|
<a href="http://www.w3.org/TR/ws-fragment">WS-Fragment</a> specification. The document represents the state of the
|
|
specification when the Working Group decided to move these parts to the
|
|
<a href="http://www.w3.org/TR/ws-fragment">WS-Fragment</a> specification and to stop further work on this document. </strong></p><p>
|
|
It has been produced by the
|
|
<a href="http://www.w3.org/2002/ws/ra/">Web
|
|
Services Resource Access Working Group</a> (WG), which is part of the
|
|
<a href="http://www.w3.org/2002/ws/Activity">W3C Web Services
|
|
Activity</a>.
|
|
</p><p>
|
|
Please report errors in this document to the public
|
|
<a href="mailto:public-ws-resource-access-comments@w3.org">
|
|
public-ws-resource-access-comments@w3.org</a>
|
|
mailing list (<a href="http://lists.w3.org/Archives/Public/public-ws-resource-access-comments/">
|
|
public archive</a>).
|
|
</p><p>
|
|
Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
|
|
</p><p>
|
|
This document was produced by a group operating under the
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
|
|
February 2004 W3C Patent Policy</a>. W3C maintains a
|
|
<a rel="disclosure" href="http://www.w3.org/2004/01/pp-impl/43088/status">public
|
|
list of any patent disclosures</a> made in connection with the
|
|
deliverables of the group; that page also includes instructions for
|
|
disclosing a patent. An individual who has actual knowledge of a
|
|
patent which the individual believes contains
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
|
|
Claim(s)</a> must disclose the information in accordance with
|
|
<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
|
|
6 of the W3C Patent Policy</a>.
|
|
</p></div><div class="toc">
|
|
<h2><a name="contents" id="contents"></a>Table of Contents</h2><p class="toc">1 <a href="#comp">Composable Architecture</a><br />
|
|
2 <a href="#intro">Introduction</a><br />
|
|
2.1 <a href="#reqs">Requirements</a><br />
|
|
2.2 <a href="#non_reqs">Non-Requirements</a><br />
|
|
2.3 <a href="#example">Example</a><br />
|
|
3 <a href="#termsNote">Terminology and Notation</a><br />
|
|
3.1 <a href="#terms">Terminology</a><br />
|
|
3.2 <a href="#namespaces">XML Namespaces</a><br />
|
|
3.3 <a href="#conven">Notational Conventions</a><br />
|
|
3.4 <a href="#extensions">Considerations on the Use of Extensibility Points</a><br />
|
|
3.5 <a href="#compliance">Compliance</a><br />
|
|
4 <a href="#Transferextensions">Extensions to WS-Transfer</a><br />
|
|
4.1 <a href="#fragments">Fragments</a><br />
|
|
4.2 <a href="#dialects">Expression Dialects</a><br />
|
|
4.2.1 <a href="#qname">QName Dialect</a><br />
|
|
4.2.2 <a href="#xpath1">XPath Level 1 Dialect</a><br />
|
|
4.2.3 <a href="#xpath10">XPath 1.0 Dialect</a><br />
|
|
4.3 <a href="#get">Get</a><br />
|
|
4.4 <a href="#put">Put</a><br />
|
|
4.5 <a href="#Create">Create</a><br />
|
|
5 <a href="#faults">Faults</a><br />
|
|
5.1 <a href="#unreachable">wsa:DestinationUnreachable</a><br />
|
|
5.2 <a href="#unavailable">wsa:EndpointUnavailable</a><br />
|
|
5.3 <a href="#concurrency">ConcurrencyFault</a><br />
|
|
5.4 <a href="#baddialect">UnsupportedDialectFault</a><br />
|
|
5.5 <a href="#badexpression">InvalidExpressionFault</a><br />
|
|
5.6 <a href="#getfault">GetFault</a><br />
|
|
5.7 <a href="#validity">ResourceValidityFault</a><br />
|
|
5.8 <a href="#dupfrag">FragmentAlreadyExistsFault</a><br />
|
|
5.9 <a href="#putfault">PutFault</a><br />
|
|
5.10 <a href="#badputmode">PutModeUnsupportedFault</a><br />
|
|
5.11 <a href="#createfault">CreateFault</a><br />
|
|
5.12 <a href="#exceedmulti">MultipartLimitExceededFault</a><br />
|
|
5.13 <a href="#putsyntaxfault">InvalidPutSyntaxFault</a><br />
|
|
6 <a href="#security">Security Considerations</a><br />
|
|
7 <a href="#policy">WS-ResourceTransfer Policy Assertion(s)</a><br />
|
|
8 <a href="#acks">Acknowledgements</a><br />
|
|
9 <a href="#refs">References</a><br />
|
|
9.1 <a href="#id35821443">Normative References</a><br />
|
|
9.2 <a href="#id35821815">Informative References</a><br />
|
|
</p>
|
|
<h3><a name="appendices" id="appendices"></a>Appendices</h3><p class="toc">A <a href="#a_xpath1">XPath Level 1</a><br />
|
|
B <a href="#rt_metadata">Resource Metadata Content</a><br />
|
|
B.1 <a href="#lifemeta">Lifecycle metadata</a><br />
|
|
B.2 <a href="#expmetadata">Expression Dialect metadata</a><br />
|
|
C <a href="#schema">XML Schema</a><br />
|
|
D <a href="#wsdl">WSDL</a><br />
|
|
E <a href="#changelog">Change Log</a><br />
|
|
</p></div><hr /><div class="body"><div class="div1">
|
|
<h2><a name="comp" id="comp"></a>1 Composable Architecture</h2><p>
|
|
The Web service specifications (WS-*) are designed to be
|
|
composed with each other to provide a rich set of tools for the Web
|
|
services environment. This specification relies on other Web service
|
|
specifications to provide secure, reliable, and/or transacted message
|
|
delivery and to express Web service metadata.
|
|
</p></div><div class="div1">
|
|
<h2><a name="intro" id="intro"></a>2 Introduction</h2><p>
|
|
This specification is intended to form an essential core component of a
|
|
unified resource access protocol for the Web services space.
|
|
</p><p>
|
|
The operations described in this specification constitute an extension to
|
|
the WS-Transfer specification, which defines standard messages for
|
|
controlling resources using the familiar paradigms of "get",
|
|
"put", "create", and "delete".
|
|
The extensions deal primarily with fragment-based access to resources.
|
|
</p><p>
|
|
This document constitutes WS-ResourceTransfer, hereafter referred to
|
|
as WS-RT.
|
|
</p><div class="div2">
|
|
<h3><a name="reqs" id="reqs"></a>2.1 Requirements</h3><p>
|
|
This specification intends to meet the following requirements:
|
|
</p><ul><li><p>
|
|
Define WSDL 1.1 portTypes, for the Web service methods described
|
|
in this specification, compliant with WS-I Basic Profile 1.1
|
|
<a href="#WS_I">[WS-I BP 1.1]</a>.
|
|
</p></li><li><p>
|
|
Define minimum requirements for compliance without constraining
|
|
richer implementations.
|
|
</p></li><li><p>
|
|
Compose with other Web service specifications for secure,
|
|
reliable, transacted message delivery.
|
|
</p></li><li><p>
|
|
Provide extensibility for more sophisticated and/or currently
|
|
unanticipated scenarios.
|
|
</p></li><li><p>
|
|
Support a variety of encoding formats including (but not limited
|
|
to) both SOAP 1.1 <a href="#SOAP11">[SOAP11]</a> and
|
|
SOAP 1.2 <a href="#SOAP121">[SOAP12]</a> Envelopes.
|
|
</p></li></ul></div><div class="div2">
|
|
<h3><a name="non_reqs" id="non_reqs"></a>2.2 Non-Requirements</h3><p>
|
|
This specification does not intend to meet the following requirements:
|
|
</p><ul><li><p>
|
|
Discovery of resources.
|
|
</p></li></ul></div><div class="div2">
|
|
<h3><a name="example" id="example"></a>2.3 Example</h3><p>
|
|
This section contains a complete example of a WS-RT "Get"
|
|
operation. This example is meant for illustration only and does
|
|
not represent normative behavior or content.
|
|
</p><p>
|
|
<a href="#exresource">Example 2-1</a> shows the XML representation of the example
|
|
resource which will be
|
|
accessed by the protocol operation. The example resource is a physical disk
|
|
which has a number of logical volumes.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="exresource" id="exresource"></a>Example 2-1: Sample Resource</div><div class="exampleInner"><pre>(01) <Disk xmlns="http://example.org/sample">
|
|
(02) <DiskCapacity>62500000000</DiskCapacity>
|
|
(03) <DiskFreeSpace>524182841</DiskFreeSpace>
|
|
(04) <SerialNumber>123-F2560</SerialNumber>
|
|
(05) <LastAuditDate>1998-05-25T13:30:15</LastAuditDate>
|
|
(06) <Volume>
|
|
(07) <Drive>C:</Drive>
|
|
(08) <Label>MyDrive-C</Label>
|
|
(09) <TotalCapacity>10000000000</TotalCapacity>
|
|
(10) <FreeSpace>6234794528</FreeSpace>
|
|
(11) </Volume>
|
|
(12) <Volume>
|
|
(13) <Drive>D:</Drive>
|
|
(14) <Label>MyDrive-D</Label>
|
|
(15) <TotalCapacity>30000000000</TotalCapacity>
|
|
(16) <FreeSpace>26462809800</FreeSpace>
|
|
(17) </Volume>
|
|
(18) <Volume>
|
|
(19) <Drive>E:</Drive>
|
|
(20) <Label>MyDrive-E</Label>
|
|
(21) <TotalCapacity>22500000000</TotalCapacity>
|
|
(22) <FreeSpace>16056784170</FreeSpace>
|
|
(23) </Volume>
|
|
(24) </Disk></pre></div></div><p>
|
|
The protocol message for retrieving parts of the above resource
|
|
representation is shown in <a href="#exresource_get">Example 2-2</a>.
|
|
The response message of
|
|
a WS-Transfer
|
|
"Get" request message would return the entire representation of the
|
|
resource, so this example illustrates a WS-RT "Get" request message
|
|
augmented for extracting specific fragments of the representation:
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="exresource_get" id="exresource_get"></a>Example 2-2: "Get" operation of resource content</div><div class="exampleInner"><pre>(01) <s:Envelope
|
|
(02) xmlns:s="http://www.w3.org/2003/05/soap-envelope"
|
|
(03) xmlns:wsa="http://www.w3.org/2005/08/addressing"
|
|
(04) xmlns:wsrt=
|
|
(05) "http://www.w3.org/2009/09/ws-rst">
|
|
(06) <s:Header>
|
|
(07) <wsa:To>http://www.example.org/disk</wsa:To>
|
|
(08) <wsa:Action s:mustUnderstand="true">
|
|
(09) http://www.w3.org/2009/09/ws-tra/Get
|
|
(10) </wsa:Action>
|
|
(11) <wsrt:ResourceTransfer s:mustUnderstand="true"/>
|
|
(12) ...
|
|
(13) </s:Header>
|
|
(14) <s:Body>
|
|
(15) <wsrt:Get
|
|
(16) Dialect="http://www.w3.org/2009/09/ws-rst/Dialects/XPath-Level-1"
|
|
(17) xmlns:d="http://example.org/sample">
|
|
(18) <wsrt:Expression>
|
|
(19) d:Volume[1]/d:Label
|
|
(20) </wsrt:Expression>
|
|
(21) <wsrt:Expression>
|
|
(22) d:DiskCapacity
|
|
(23) </wsrt:Expression>
|
|
(24) <wsrt:Expression>
|
|
(25) d:SerialNumber/text()
|
|
(26) </wsrt:Expression>
|
|
(27) </wsrt:Get>
|
|
(28) </s:Body>
|
|
(29) </s:Envelope></pre></div></div><p>
|
|
In this example, the operation is a WS-Transfer "Get" as
|
|
defined by the wsa:Action in line (09). The extended, fragment-aware Get
|
|
behavior is indicated by the wsrt:ResourceTransfer header at line (11). The
|
|
resource being accessed is referenced by the WS-Addressing endpoint
|
|
reference, implied by the wsa:To element on line (07). WS-RT extensions for
|
|
extracting fragments of the resource representation are in the wsrt:Get
|
|
block on lines (15) through (27). For each targeted fragment the value
|
|
to be selected is specified in the wsrt:Expression element.
|
|
</p><p>
|
|
The response to the "Get" message is illustrated in
|
|
<a href="#exresource_getresponse">Example 2-3</a>.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="exresource_getresponse" id="exresource_getresponse"></a>Example 2-3: Example "Get" response</div><div class="exampleInner"><pre>(01) <s:Envelope
|
|
(02) xmlns:s="http://www.w3.org/2003/05/soap-envelope"
|
|
(03) xmlns:wsa="http://www.w3.org/2005/08/addressing"
|
|
(04) xmlns:wsrt=
|
|
(05) "http://www.w3.org/2009/09/ws-rst">
|
|
(06) <s:Header>
|
|
(07) <wsa:To>
|
|
(08) http://www.w3.org/2005/08/addressing/anonymous
|
|
(09) </wsa:To>
|
|
(10) <wsa:Action s:mustUnderstand="true">
|
|
(11) http://www.w3.org/2009/09/ws-tra/GetResponse
|
|
(12) </wsa:Action>
|
|
(13) <wsrt:ResourceTransfer/>
|
|
(14) ...
|
|
(15) </s:Header>
|
|
(16) <s:Body>
|
|
(17) <wsrt:GetResponse xmlns:d="http://example.org/sample">
|
|
(18) <wsrt:Result>
|
|
(19) <d:Label>MyDrive-C</d:Label>
|
|
(20) </wsrt:Result>
|
|
(21) <wsrt:Result>
|
|
(22) <d:DiskCapacity>62500000000</d:DiskCapacity>
|
|
(23) </wsrt:Result>
|
|
(24) <wsrt:Result>
|
|
(25) <wsrt:TextNode>123-F2560</wsrt:TextNode>
|
|
(26) </wsrt:Result>
|
|
(27) </wsrt:GetResponse>
|
|
(28) </s:Body>
|
|
(29) </s:Envelope></pre></div></div><p>
|
|
Note that the value of each resource fragment requested via
|
|
a wsrt:Expression element is individually returned in a matching
|
|
wsrt:Result element.
|
|
This example uses the XPath Level 1 Dialect for the wsrt:Expression
|
|
elements, one of which shows the use of the XPath text() NodeTest. The
|
|
wsrt:Result for the third fragment contains only the serialized text
|
|
value of that element (line (25)), rather than the XML element wrapper
|
|
as in the other cases.
|
|
</p></div></div><div class="div1">
|
|
<h2><a name="termsNote" id="termsNote"></a>3 Terminology and Notation</h2><div class="div2">
|
|
<h3><a name="terms" id="terms"></a>3.1 Terminology</h3><p>
|
|
Some of the terminology defined in this specification is repeated
|
|
from the WS-Transfer specification for convenience and is not meant
|
|
to deviate from those definitions in any way.
|
|
</p><dl><dt class="label">Resource</dt><dd><p>
|
|
A Web service that is addressable by an endpoint reference
|
|
as defined in WS-Addressing and that can be represented by an XML
|
|
document. This representation can be accessed using the operations
|
|
defined in the WS-Transfer and WS-ResourceTransfer specifications.
|
|
</p></dd><dt class="label">Resource representation</dt><dd><p>
|
|
The XML representation of the resource that is accessed
|
|
using the operations defined in the WS-Transfer and WS-ResourceTransfer
|
|
specifications.
|
|
</p></dd><dt class="label">Resource factory</dt><dd><p>
|
|
A Web service that is capable of creating new resources using the
|
|
Create operation defined in WS-Transfer and the WS-ResourceTransfer
|
|
specifications.
|
|
</p></dd><dt class="label">Metadata resource</dt><dd><p>
|
|
A resource whose XML representation describes some aspect of the
|
|
metadata of another resource, such as its WSDL or lifecycle metadata.
|
|
Each resource MAY have zero or more metadata resources associated with
|
|
it.
|
|
</p></dd><dt class="label">Fragment</dt><dd><p>
|
|
The term "fragment" is used in this specification to mean a
|
|
part of the resource representation.
|
|
</p></dd><dt class="label">EPR</dt><dd><p>
|
|
The wsa:EndpointReference (EPR), as defined by
|
|
WS-Addressing, is a reference to the resource in its entirety.
|
|
Operations, which are otherwise unconstrained within this
|
|
specification, are assumed to affect the resource as a whole.
|
|
</p></dd></dl></div><div class="div2">
|
|
<h3><a name="namespaces" id="namespaces"></a>3.2 XML Namespaces</h3><p>
|
|
The XML Namespace URI that MUST be used by implementations of this
|
|
specification is:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/09/ws-rst">http://www.w3.org/2009/09/ws-rst</a></pre></div></div><p>
|
|
<a href="#xmlnamespaces">Table 3-1</a> lists XML namespaces that are
|
|
used in this specification. The
|
|
choice of any namespace prefix is arbitrary and not semantically
|
|
significant.
|
|
</p><a name="xmlnamespaces" id="xmlnamespaces"></a><table border="1"><caption>Table 3-1:
|
|
Prefixes and XML Namespaces used in this specification.
|
|
</caption><tbody><tr><th align="left"> Prefix </th><th align="left"> XML Namespace </th><th align="left"> Specification(s) </th></tr><tr><td> s </td><td> (Either SOAP 1.1 or 1.2) </td><td> (Either SOAP 1.1 or 1.2) </td></tr><tr><td> s11 </td><td> http://schemas.xmlsoap.org/soap/envelope/ </td><td> <a href="#SOAP11">[SOAP11]</a> </td></tr><tr><td> s12 </td><td> http://www.w3.org/2003/05/soap-envelope </td><td> <a href="#SOAP121">[SOAP12]</a> </td></tr><tr><td> wsa </td><td> http://www.w3.org/2005/08/addressing </td><td> <a href="#AddrCore">[WS-Addressing]</a> </td></tr><tr><td> wsmex </td><td> http://www.w3.org/2009/09/ws-mex </td><td> <a href="#MEX">[WS-MetadataExchange]</a> </td></tr><tr><td> wsdl </td><td> http://schemas.xmlsoap.org/wsdl/ </td><td> <a href="#WSDL11">[WSDL11]</a> </td></tr><tr><td> wsrt </td><td> http://www.w3.org/2009/09/ws-rst </td><td> This specification </td></tr><tr><td> wst </td><td> http://www.w3.org/2009/09/ws-tra </td><td> <a href="#WsTransfer">[WS-Transfer]</a> </td></tr><tr><td> xs </td><td> http://www.w3.org/2001/XMLSchema </td><td>
|
|
XML Schema <a href="#XMLSchema1">[XMLSchema - Part 1]</a>,
|
|
<a href="#XMLSchema2">[XMLSchema - Part 2]</a>
|
|
</td></tr></tbody></table><p>
|
|
The working group intends to update the value of the Web Services
|
|
Resource Transfer 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 Resource Transfer 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
|
|
<a href="http://www.w3.org/2001/tag/doc/namespaceState.html">
|
|
http://www.w3.org/2001/tag/doc/namespaceState.html
|
|
</a> and
|
|
<a href="http://www.w3.org/2005/07/13-nsuri">
|
|
http://www.w3.org/2005/07/13-nsuri
|
|
</a>.
|
|
</p></div><div class="div2">
|
|
<h3><a name="conven" id="conven"></a>3.3 Notational Conventions</h3><p>
|
|
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
|
|
<a href="#RFC2119">[RFC 2119]</a>.
|
|
</p><p>
|
|
This specification uses the following syntax to define outlines for
|
|
messages:
|
|
</p><ul><li><p>
|
|
The syntax appears as an XML instance, but values in italics
|
|
indicate data types instead of literal values.
|
|
</p></li><li><p>
|
|
Characters are appended to elements and attributes to indicate
|
|
cardinality:
|
|
</p><ul><li><p> "?" (0 or 1) </p></li><li><p> "*" (0 or more) </p></li><li><p> "+" (1 or more) </p></li></ul></li><li><p>
|
|
The character "|" is used to indicate a choice between
|
|
alternatives.
|
|
</p></li><li><p>
|
|
The characters "(" and ")" are used to
|
|
indicate that contained items are to be treated as a group with
|
|
respect to cardinality or choice.
|
|
</p></li><li><p>
|
|
The characters "[" and "]" are used to call
|
|
out references and property names.
|
|
</p></li><li><p>
|
|
Ellipses (i.e., "...") indicate points of extensibility.
|
|
</p></li><li><p>
|
|
XML namespace prefixes (see <a href="#xmlnamespaces">Table 3-1</a>) are used
|
|
to indicate the namespace of the element being defined.
|
|
</p></li></ul><p>
|
|
In addition to Message Information Header properties
|
|
<a href="#AddrCore">[WS-Addressing]</a>,
|
|
this specification uses the following properties to define messages:
|
|
</p><dl><dt class="label"> <b>[Headers]</b> </dt><dd><p> Unordered message headers. </p></dd><dt class="label"> <b>[Action]</b> </dt><dd><p> The value to be used for the wsa:Action URI. </p></dd><dt class="label"> <b>[Body]</b> </dt><dd><p> A message body. </p></dd></dl><p>
|
|
These properties bind to a SOAP Envelope as follows:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><s:Envelope>
|
|
<s:Header>
|
|
<b>[Headers]</b>
|
|
<wsa:Action><b>[Action]</b></wsa:Action>
|
|
...
|
|
</s:Header>
|
|
<s:Body><b>[Body]</b></s:Body>
|
|
</s:Envelope></pre></div></div><p>
|
|
This specification defines Fault properties for each defined
|
|
fault and defines SOAP bindings for each Fault property.
|
|
</p><p>
|
|
This specification can be used in terms of XML Information Set (Infoset)
|
|
<a href="#XMLInfoset">[XML Infoset]</a>, 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.
|
|
</p></div><div class="div2">
|
|
<h3><a name="extensions" id="extensions"></a>3.4 Considerations on the Use of Extensibility Points</h3><p>
|
|
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".
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
Extension elements and attributes MUST NOT use the Web Services
|
|
Resource Transfer namespace URI.
|
|
</p></div><div class="div2">
|
|
<h3><a name="compliance" id="compliance"></a>3.5 Compliance</h3><p>
|
|
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 <a href="#namespaces"><b>3.2 XML Namespaces</b></a>) within SOAP
|
|
Envelopes unless it is compliant with this specification.
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
All messages defined by this specification MUST be sent to a Web service
|
|
that is addressable by an EPR (see <a href="#AddrCore">[WS-Addressing]</a>).
|
|
</p><p>
|
|
Unless otherwise noted, all URIs are absolute URIs and URI comparison
|
|
MUST be performed according to <a href="#RFC3986">[RFC 3986]</a> section 6.2.1.
|
|
</p></div></div><div class="div1">
|
|
<h2><a name="Transferextensions" id="Transferextensions"></a>4 Extensions to WS-Transfer</h2><p>
|
|
WS-Transfer defines operations to Get, Put, Create and
|
|
Delete representations of resources. WS-ResourceTransfer extends these
|
|
operations to add the capability to operate on fragments of the resource
|
|
representations.
|
|
</p><div class="div2">
|
|
<h3><a name="fragments" id="fragments"></a>4.1 Fragments</h3><p>
|
|
Since an EPR refers to a resource as a whole, techniques
|
|
which are used to reference or access parts of the resource
|
|
representation are referred to as "fragment access" in that they access
|
|
fragments of the XML representing the resource.
|
|
</p><p>
|
|
This specification defines an extensible mechanism for
|
|
designating the expression syntax by which the fragment is identified or
|
|
computed, and defines several such standard expression syntaxes or
|
|
"dialects".
|
|
</p></div><div class="div2">
|
|
<h3><a name="dialects" id="dialects"></a>4.2 Expression Dialects</h3><p>
|
|
The dialects defined below are used to form an expression
|
|
that can be evaluated with respect to the XML document that represents the
|
|
resource. The de-referenced value of the expression is the part of the XML
|
|
that is of interest. The expression MAY form a logical "pointer" to
|
|
the fragment of XML that is of interest or, depending on the dialect, MAY
|
|
form a query that can be applied to the XML document to produce an
|
|
evaluated result. It is important to understand that these expression
|
|
dialects simply identify the appropriate fragment of the resource
|
|
representation and that the <b>[Action]</b>
|
|
itself defines what will happen to the referenced fragment.
|
|
</p><p>
|
|
The definition of each dialect MUST clearly specify how the
|
|
result of evaluating an expression against a resource representation is
|
|
serialized to XML and SHOULD specify any dialect-specific behavior for
|
|
operations that access the resource representation.
|
|
</p><p>
|
|
New dialect definitions MUST include sufficient information for
|
|
proper application. For example, it would need to include the
|
|
context (which data) over which the dialect operates.
|
|
</p><div class="div3">
|
|
<h4><a name="qname" id="qname"></a>4.2.1 QName Dialect</h4><p>
|
|
The QName expression dialect is a simple dialect for
|
|
expressions that uses a QName to reference the immediate children of
|
|
the root element of the resource representation. Consider the
|
|
resource described in <a href="#exresource">Example 2-1</a>.
|
|
</p><p>
|
|
In this example, the QName dialect can define references to
|
|
the elements <DiskCapacity>, <DiskFreeSpace>,
|
|
<SerialNumber>, <LastAuditDate> and all <Volume>
|
|
elements.
|
|
The QName dialect cannot define direct references to the elements
|
|
<Drive>, <Label>, <TotalCapacity>
|
|
and <FreeSpace> - since they are not direct children of the
|
|
Disk (root) element of the resource - or to specific
|
|
<Volume> elements. <a href="#get_qname">Example 4-1</a>, below,
|
|
shows an example usage of this
|
|
dialect. This dialect is useful for simple resources with no XPath
|
|
processing capability.
|
|
</p><p>
|
|
The QName dialect MUST be indicated by using the URI:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>http://www.w3.org/2009/09/ws-rst/Dialects/QName</pre></div></div><p>
|
|
Note that the expression MUST evaluate to zero or more entire
|
|
elements, each including the element name, any attributes and its entire
|
|
content. The QName dialect does not support computed values.
|
|
</p></div><div class="div3">
|
|
<h4><a name="xpath1" id="xpath1"></a>4.2.2 XPath Level 1 Dialect</h4><p>
|
|
The XPath Level 1 expression dialect 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.
|
|
<a href="#exresource_get">Example 2-2</a> shows an example usage of this dialect.
|
|
This dialect is useful for resources with limited XPath processing
|
|
capability which do not need to support returning values computed from
|
|
their resource representation.
|
|
</p><p>
|
|
The XPath Level 1 dialect is defined in Appendix I of this specification.
|
|
An implementation that uses the XPath Level 1 dialect MUST support the
|
|
expressions whose syntax is described by the BNF in Appendix I. It MAY
|
|
support additional expressions defined by XPath 1.0.
|
|
</p><p>
|
|
An XPath Level 1 expression is an expression whose context is:
|
|
</p><ul><li><p>
|
|
Context Node: the root element of the XML representation of the resource
|
|
</p></li><li><p>
|
|
Context Position: 1
|
|
</p></li><li><p>
|
|
Context Size: 1
|
|
</p></li><li><p>
|
|
Variable Binding: None
|
|
</p></li><li><p>
|
|
Node Tests: NameTest and the text NodeType
|
|
</p></li><li><p>
|
|
Function Libraries: None
|
|
</p></li><li><p>
|
|
Namespace Declarations: Any namespace declarations in-scope where the
|
|
XPath expression appears
|
|
</p></li></ul><p>
|
|
Consider the resource described in <a href="#exresource">Example 2-1</a>.
|
|
The XPath Level 1 dialect can
|
|
define references to any element, attribute or value in the resource
|
|
representation.
|
|
</p><p>
|
|
The XPath Level 1 dialect MUST be indicated by using the URI:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>http://www.w3.org/2009/09/ws-rst/Dialects/XPath-Level-1</pre></div></div><p>
|
|
Expressions in this dialect MUST NOT evaluate to more than a
|
|
single node. The XPath Level 1 dialect does not support computed values.
|
|
Text and attribute nodes MUST be serialized using the same serialization
|
|
as for the XPath 1.0 dialect.
|
|
</p></div><div class="div3">
|
|
<h4><a name="xpath10" id="xpath10"></a>4.2.3 XPath 1.0 Dialect</h4><p>
|
|
The XPath 1.0 expression dialect 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
|
|
dialect supports a
|
|
wider set of XPath function libraries than the XPath Level 1 dialect.
|
|
<a href="#get_xpath10">Example 4-3</a>, below, shows an example usage of this
|
|
dialect. This dialect is
|
|
useful for resources with full XPath processing capability or which
|
|
need to support returning values computed from their resource
|
|
representation.
|
|
</p><p>
|
|
An XPath 1.0 expression is an expression whose context is:
|
|
</p><ul><li><p>
|
|
Context Node: the root element of the XML representation of the resource
|
|
</p></li><li><p>Context Position: 1</p></li><li><p>Context Size: 1</p></li><li><p>Variable Binding: None</p></li><li><p>Function Libraries: Core function library</p></li><li><p>
|
|
Namespace Declarations: Any namespace declarations in-scope where
|
|
the XPath expression appears
|
|
</p></li></ul><p>
|
|
Consider the resource described in <a href="#exresource">Example 2-1</a>.
|
|
The XPath 1.0 dialect 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.
|
|
</p><p>The XPath 1.0 dialect MUST be indicated by using the URI:</p><div class="exampleOuter"><div class="exampleInner"><pre>http://www.w3.org/2009/09/ws-rst/Dialects/XPath10</pre></div></div><p>
|
|
Implementations that support the full XPath 1.0 dialect MUST
|
|
support the XPath Level 1 dialect.
|
|
</p><p>
|
|
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 wsrt:Result element:
|
|
</p><ul><li><p>Boolean - converted to an xs:boolean</p></li><li><p>string - convert to an xs:string</p></li><li><p>number - convert to an xs:double</p></li></ul><p>
|
|
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 wsrt:Result 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.
|
|
</p><p>
|
|
Attribute nodes in XPath are represented in the following form:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>name="value"</pre></div></div><p>
|
|
Serialization of an attribute node separates the name from
|
|
the value using the following element:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:AttributeNode name="<em>attribute name</em>">
|
|
(02) <em>attribute value</em>
|
|
(03) </wsrt:AttributeNode></pre></div></div><p>
|
|
The following describes additional constraints on the outline
|
|
listed above:
|
|
</p><dl><dt class="label"> wsrt:AttributeNode </dt><dd><p>
|
|
This element is used to serialize an attribute node in a
|
|
node-set and MUST contain the value portion of the attribute node.
|
|
</p></dd><dt class="label"> wsrt:AttributeNode/@name </dt><dd><p>
|
|
This attribute MUST be the name portion of the attribute node.
|
|
</p></dd></dl><p>
|
|
Text nodes are serialized in the following form:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:TextNode>
|
|
(02) <em>text value</em>
|
|
(03) </wsrt:TextNode></pre></div></div><p>The following describes additional constraints on the
|
|
outline listed above:</p><p>wsrt:TextNode</p><p>
|
|
This element is used to serialize a text node in a node-set
|
|
and MUST contain the text value.
|
|
</p><p>Given the following XML as an example document.</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <a xmlns="example">
|
|
(02) <b>1</b>
|
|
(03) <c x="y">2</c>
|
|
(04) </a></pre></div></div><p>
|
|
The result of the XPath "/a/b | /a/b/text() | /a/c/@x" would
|
|
be serialized as the following:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:Result>
|
|
(02) <b>1</b>
|
|
(03) <wsrt:TextNode>1</wsrt:TextNode>
|
|
(04) <wsrt:AttributeNode name="x">y</wsrt:AttributeNode>
|
|
(05) </wsrt:Result></pre></div></div><p>The nodes in the node-set MAY be serialized in any order.</p><p>
|
|
The WS-RT global element definition wsrt:NodeSet can also be
|
|
used as the wrapper element when serializing these node-sets outside of
|
|
a WS-RT result.
|
|
</p><p>
|
|
An XPath 1.0 expression MAY evaluate to multiple nodes;
|
|
because of this the XPath 1.0 dialect MUST NOT be used with a "Put" or
|
|
"Create" operation.
|
|
</p></div></div><div class="div2">
|
|
<h3><a name="get" id="get"></a>4.3 Get</h3><p>
|
|
The WS-Transfer Get operation is used to retrieve an
|
|
existing resource representation in its entirety. WS-ResourceTransfer
|
|
extends
|
|
the "Get" operation to retrieve fragments of an existing representation. A
|
|
resource that can return its full representation MUST also support
|
|
wst:Get to
|
|
return the entire resource representation without using WS-ResourceTransfer
|
|
extensions.
|
|
</p><p>
|
|
The <b>[Body]</b> of wsrt:Get contains an expression that
|
|
identifies the fragment of interest.
|
|
</p><p>The outline for wsrt:Get is:</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Headers]</b>
|
|
<wsrt:ResourceTransfer s:mustUnderstand="true"? />
|
|
|
|
<b>[Action]</b>
|
|
http://www.w3.org/2009/09/ws-tra/Get
|
|
|
|
<b>[Body]</b>
|
|
<wsrt:Get Dialect="<em>xs:anyURI</em>"?>
|
|
<wsrt:Expression ...><em>xs:any</em></wsrt:Expression> *
|
|
</wsrt:Get></pre></div></div><p>
|
|
The following describes additional constraints on the outline listed above:
|
|
</p><dl><dt class="label"> <b>[Header]</b>/wsrt:ResourceTransfer </dt><dd><p>
|
|
If present and understood, a resource MUST process the
|
|
<b>[Body]</b> in its entirety and comply with its content. If
|
|
not present
|
|
then a resource MUST treat this request as described in WS-Transfer
|
|
Get <a href="#WsTransfer">[WS-Transfer]</a>.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Get </dt><dd><p>
|
|
An element which controls the retrieval of the resource
|
|
fragment. This element MUST be present if the wsrt:ResourceTransfer
|
|
header is
|
|
present.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Get/@Dialect </dt><dd><p>
|
|
This URI indicates which dialect expression will be used to
|
|
identify and retrieve the fragment(s). This attribute MUST be present
|
|
when the
|
|
message contains a wsrt:Expression element. A resource MUST generate an
|
|
UnsupportedDialectFault if it does not support the specified Dialect.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Get/wsrt:Expression </dt><dd><p>
|
|
When present this optional element identifies a fragment in
|
|
the resource to be sent in the response. Absence of this element is
|
|
equivalent
|
|
to an Expression that identifies the entire resource representation.
|
|
The value
|
|
of this element MUST conform to the dialect specified in
|
|
<b>[Body]</b>/wsrt:Get/@Dialect
|
|
attribute. A resource MUST generate an InvalidExpressionFault if the
|
|
expression is invalid. If the expression syntax is not valid with
|
|
respect to
|
|
the dialect then a resource SHOULD specify a fault detail of
|
|
"InvalidExpressionSyntax".
|
|
If the expression value is not valid for the resource type then the
|
|
resource
|
|
SHOULD specify a fault detail of "InvalidExpressionValue".
|
|
</p><p>
|
|
If a resource cannot return a value for a requested fragment then
|
|
it MUST generate a GetFault.
|
|
</p><p>
|
|
If the request contains more Expression elements than the resource
|
|
supports the resource MUST return a fault which SHOULD be
|
|
wsrt:MultipartLimitExceededFault.
|
|
</p></dd></dl><p>
|
|
If the resource accepts a wsrt:Get request and processes it successfully it
|
|
MUST reply with a response of the following form:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Headers]</b>
|
|
<wsrt:ResourceTransfer/>
|
|
|
|
<b>[Action]</b>
|
|
http://www.w3.org/2009/09/ws-tra/GetResponse
|
|
|
|
<b>[Body]</b>
|
|
<wsrt:GetResponse>
|
|
<wsrt:Result...> <em>xs:any</em> </wsrt:Result> +
|
|
</wsrt:GetResponse></pre></div></div><p>
|
|
The following describes additional constraints on the outline listed above:
|
|
</p><dl><dt class="label"> <b>[Headers]</b>/wsrt:ResourceTransfer </dt><dd><p>
|
|
This header indicates that the response contains body
|
|
content defined in WS-ResourceTransfer.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:GetResponse </dt><dd><p>
|
|
An element which wraps the packaging of the fragments in
|
|
the response. This element MUST be present if the request Body
|
|
contained a wsrt:Get element.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:GetResponse/wsrt:Result </dt><dd><p>
|
|
This element encompasses a single fragment response corresponding to a
|
|
wsrt:Expression in the original request and MUST contain the
|
|
fragment of the resource representation identified by the
|
|
wsrt:Expression. If
|
|
the request contained no wsrt:Expression then this element MUST contain
|
|
the
|
|
entire resource representation. If the request contained one or more
|
|
wsrt:Expression elements then for each wsrt:Expression element in the
|
|
request
|
|
there MUST be one wsrt:Result element in the response even if the
|
|
wsrt:Result
|
|
has empty content. The wsrt:Result elements MUST appear in the same
|
|
order in
|
|
the response as the corresponding wsrt:Expression elements in the
|
|
request. A
|
|
wsrt:Result MUST have empty content in the case where a wsrt:Expression
|
|
resolves to nothing.
|
|
</p></dd></dl><p>
|
|
An example Get message using the XPath Level 1 dialect
|
|
and the expected GetResponse is shown in <a href="#exresource_get">Example 2-2</a>
|
|
and the expected GetResource is shown in
|
|
<a href="#exresource_getresponse">Example 2-3</a>, for the resource whose
|
|
XML representation is shown in <a href="#exresource">Example 2-1</a> above.
|
|
</p><p>
|
|
An example Get message that uses the QName dialect is shown in
|
|
<a href="#get_qname">Example 4-1</a> below.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="get_qname" id="get_qname"></a>Example 4-1: Get message using the "QName" dialect</div><div class="exampleInner"><pre>(01) <s:Envelope
|
|
(02) xmlns:s="http://www.w3.org/2003/05/soap-envelope"
|
|
(03) xmlns:wsa="http://www.w3.org/2005/08/addressing"
|
|
(04) xmlns:wsrt=
|
|
(05) "http://www.w3.org/2009/09/ws-rst">
|
|
(06) <s:Header>
|
|
(07) <wsa:To>http://www.example.org/disk</wsa:To>
|
|
(08) <wsa:Action s:mustUnderstand="true">
|
|
(09) http://www.w3.org/2009/09/ws-tra/Get
|
|
(10) </wsa:Action>
|
|
(11) <wsrt:ResourceTransfer s:mustUnderstand="true"/>
|
|
(12) ...
|
|
(13) </s:Header>
|
|
(14) <s:Body>
|
|
(15) <wsrt:Get Dialect="http://www.w3.org/2009/09/ws-rst/Dialects/QName"
|
|
(16) xmlns:d="http://example.org/sample">
|
|
(17) <wsrt:Expression>
|
|
(18) d:Volume
|
|
(19) </wsrt:Expression>
|
|
(20) <wsrt:Expression>
|
|
(21) d:DiskCapacity
|
|
(22) </wsrt:Expression>
|
|
(23) </wsrt:Get>
|
|
(24) </s:Body>
|
|
(25) </s:Envelope></pre></div></div><p>
|
|
The fragments of the resource representation are identified by
|
|
the wsrt:Expression contents on lines (18) and (21). Notice that the
|
|
<em>d:Volume</em> QName in the example resolves to three
|
|
elements in the
|
|
resource representation. The response to this "Get" message is
|
|
illustrated in <a href="#getresponse_qname">Example 4-2</a>.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="getresponse_qname" id="getresponse_qname"></a>Example 4-2: Example GetResponse using the "QName" dialect</div><div class="exampleInner"><pre>(01) <s:Envelope
|
|
(02) xmlns:s="http://www.w3.org/2003/05/soap-envelope"
|
|
(03) xmlns:wsa="http://www.w3.org/2005/08/addressing"
|
|
(04) xmlns:wsrt=
|
|
(05) "http://www.w3.org/2009/09/ws-rst">
|
|
(06) <s:Header>
|
|
(07) <wsa:To>
|
|
(08) http://www.w3.org/2005/08/addressing/anonymous
|
|
(09) </wsa:To>
|
|
(10) <wsa:Action s:mustUnderstand="true">
|
|
(11) http://www.w3.org/2009/09/ws-tra/GetResponse
|
|
(12) </wsa:Action>
|
|
(13) <wsrt:ResourceTransfer/>
|
|
(14) ...
|
|
(15) </s:Header>
|
|
(16) <s:Body>
|
|
(17) <wsrt:GetResponse xmlns:d="http://example.org/sample">
|
|
(18) <wsrt:Result>
|
|
(19) <d:Volume>
|
|
(20) <d:Drive>C:</d:Drive>
|
|
(21) <d:Label>MyDrive-C</d:Label>
|
|
(22) <d:TotalCapacity>10000000000</d:TotalCapacity>
|
|
(23) <d:FreeSpace>6234794528</d:FreeSpace>
|
|
(24) </d:Volume>
|
|
(25) <d:Volume>
|
|
(26) <d:Drive>D:</d:Drive>
|
|
(27) <d:Label>MyDrive-D</d:Label>
|
|
(28) <d:TotalCapacity>30000000000</d:TotalCapacity>
|
|
(29) <d:FreeSpace>26462809800</d:FreeSpace>
|
|
(30) </d:Volume>
|
|
(31) <d:Volume>
|
|
(32) <d:Drive>E:</d:Drive>
|
|
(33) <d:Label>MyDrive-E</d:Label>
|
|
(34) <d:TotalCapacity>22500000000</d:TotalCapacity>
|
|
(35) <d:FreeSpace>16056784170</d:FreeSpace>
|
|
(36) </d:Volume>
|
|
(37) </wsrt:Result>
|
|
(38) <wsrt:Result>
|
|
(39) <d:DiskCapacity>62500000000</d:DiskCapacity>
|
|
(40) </wsrt:Result>
|
|
(41) </wsrt:GetResponse>
|
|
(42) </s:Body>
|
|
(43) </s:Envelope></pre></div></div><p>
|
|
The value of each of the wsrt:Expression fragments in the
|
|
request message is returned in a unique wsrt:Result wrapper in the
|
|
response message. The order of the wsrt:Result elements in the
|
|
response matches the order of the corresponding wsrt:Expression elements
|
|
in the request. The result of getting the <d:Volume> fragment,
|
|
for example, is shown on lines (18) - (37).
|
|
</p><p>
|
|
One final example of the Get operation, using the full XPath
|
|
1.0 dialect, is shown below in <a href="#get_xpath10">Example 4-3</a>.
|
|
This illustrates the use of a
|
|
query expression to return the computed result of the quantity of
|
|
<em>d:Volume</em> elements that have a capacity greater
|
|
than 20000000000.
|
|
For the sake of brevity, only the message body is shown.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="get_xpath10" id="get_xpath10"></a>Example 4-3: Example Get message using an XPath 1.0 query expression</div><div class="exampleInner"><pre>(01) <s:Body>
|
|
(02) <wsrt:Get Dialect="http://www.w3.org/2009/09/ws-rst/Dialects/XPath10"
|
|
(03) xmlns:d="http://example.org/sample">
|
|
(04) <wsrt:Expression>
|
|
(05) count( d:Volume[d:TotalCapacity > 20000000000] )
|
|
(06) </wsrt:Expression>
|
|
(07) </wsrt:Get>
|
|
(08) </s:Body></pre></div></div><p>
|
|
The expression on line (05), when applied to the resource representation
|
|
in <a href="#example"><b>2.3 Example</b></a>, evaluates to a result of "2".
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="getresponse_xpath10" id="getresponse_xpath10"></a>Example 4-4: GetResponse of an XPath 1.0 query expression</div><div class="exampleInner"><pre>(01) <s:Body>
|
|
(02) <wsrt:GetResponse>
|
|
(03) <wsrt:Result>2</wsrt:Result>
|
|
(04) </wsrt:GetResponse>
|
|
(05) </s:Body></pre></div></div><p>
|
|
The result of the query expression is a number which is
|
|
converted to an xs:double and returned as the value of the wsrt:Result
|
|
element shown on line (03).
|
|
</p></div><div class="div2">
|
|
<h3><a name="put" id="put"></a>4.4 Put</h3><p>
|
|
The WS-Transfer "Put" operation is used to update an existing resource
|
|
representation by providing a
|
|
replacement XML representation. WS-ResourceTransfer
|
|
extends the "Put" operation to update an existing resource representation
|
|
by providing fragments of the XML representation. A resource that can
|
|
update its full representation MUST also support wst:Put to update the
|
|
entire resource representation without using WS-
|
|
ResourceTransfer extensions.
|
|
</p><p>The extended outline for the "Put" operation is:</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Headers]</b>
|
|
<wsrt:ResourceTransfer s:mustUnderstand="true"/>
|
|
|
|
<b>[Action]</b>
|
|
http://www.w3.org/2009/09/ws-tra/Put
|
|
|
|
<b>[Body]</b>
|
|
<wsrt:Put Dialect="<em>xs:anyURI</em>"?>
|
|
<wsrt:Fragment Mode="<em>xs:anyURI</em>">
|
|
<wsrt:Expression><em>xs:any</em></wsrt:Expression> ?
|
|
<wsrt:Value ...><em>xs:any</em></wsrt:Value> ?
|
|
</wsrt:Fragment> +
|
|
</wsrt:Put></pre></div></div><p>
|
|
The following describes additional constraints on the outline listed above:
|
|
</p><dl><dt class="label"> <b>[Header]</b>/wsrt:ResourceTransfer </dt><dd><p>
|
|
If present and understood, a resource MUST process the
|
|
<b>[Body]</b> in its entirety and comply with its content.
|
|
If not present
|
|
then a resource MUST treat this request as described in WS-Transfer
|
|
Put <a href="#WsTransfer">[WS-Transfer]</a>.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Put </dt><dd><p>
|
|
An element that specifies the fragments of the resource representation
|
|
to update. This element MUST be present if the wsrt:ResourceTransfer
|
|
header is present.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Put/@Dialect </dt><dd><p>
|
|
This URI indicates which expression dialect will be used to
|
|
identify the fragment(s) of the resource representation to be updated.
|
|
This attribute MUST be present when the message contains a
|
|
wsrt:Expression element.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Put/Fragment </dt><dd><p>
|
|
This element encompasses a single update to be performed on
|
|
the resource. Upon successful completion of a Put operation, the
|
|
resource representation MUST appear as though the fragment updates
|
|
occurred in the order specified in the Put operation. If there are
|
|
multiple Fragment elements then, for the first fragment, the
|
|
resource representation is the original resource representation
|
|
(before applying the Put changes). For subsequent fragments, the
|
|
resource representation is the intermediate representation resulting
|
|
from
|
|
applying the previous fragments.
|
|
</p><p>
|
|
If the request contains more Fragment elements than the resource
|
|
supports the resource MUST return a fault which SHOULD be
|
|
wsrt:MultipartLimitExceededFault.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Put/Fragment/@Mode </dt><dd><p>
|
|
This attribute indicates the type of update to be performed
|
|
on this fragment. A resource MUST generate a ResourceValidityFault if
|
|
the result of executing this operation would cause the resource
|
|
representation to become invalid. A resource MAY support only a subset
|
|
of the Modes defined within this specification. A resource that does
|
|
not support a specified Mode MUST
|
|
generate a PutModeUnsupportedFault.
|
|
</p><p>
|
|
A value of "http://www.w3.org/2009/09/ws-rst/Remove" indicates that
|
|
the fragment MUST be
|
|
deleted if it is present. The expression dialect indicated in this
|
|
operation MAY place additional constraints on the definition of this
|
|
Mode. Note that, in order to delete the resource itself, a WS-Transfer
|
|
"Delete" message is used.
|
|
</p><p>
|
|
A value of "http://www.w3.org/2009/09/ws-rst/Modify" means that the
|
|
fragment MUST be
|
|
replaced by removing any fragment that already exists and inserting the
|
|
specified value in its place. If the expression resolves to nothing then
|
|
this fragment element does not result in any change to the resource
|
|
representation. The expression dialect indicated in this operation MAY
|
|
place additional constraints on the definition of this Mode. A fragment
|
|
with no wsrt:Expression MUST specify this Mode.
|
|
</p><p>
|
|
A value of "http://www.w3.org/2009/09/ws-rst/Insert" indicates that
|
|
the fragment 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 FragmentAlreadyExistsFault. If the expression targets an existing
|
|
item of a repeated element, the fragment MUST be added before the
|
|
existing item.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Put/Fragment/Expression </dt><dd><p>
|
|
When present this optional element contains the expression that
|
|
identifies a fragment of the resource representation to be updated.
|
|
Absence of this element is equivalent to an Expression that identifies
|
|
the entire resource representation.
|
|
</p><p>
|
|
The value of this element MUST conform to the dialect
|
|
specified in the <b>[Body]</b>/wsrt:Put/@Dialect attribute. A
|
|
resource
|
|
MUST generate an InvalidExpressionFault if the expression is invalid.
|
|
If the expression syntax is not valid with respect to the dialect then
|
|
a resource SHOULD specify a fault detail of "InvalidExpressionSyntax".
|
|
If the expression value is not valid for the resource type then the
|
|
resource SHOULD specify a fault detail of "InvalidExpressionValue".
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Put/Fragment/Value </dt><dd><p>
|
|
This element contains the data to be written to the
|
|
resource representation. If the <b>[Body]</b>/wsrt:Put/Fragment/@Mode
|
|
attribute is "http://www.w3.org/2009/09/ws-rst/Insert" or
|
|
"http://www.w3.org/2009/09/ws-rst/Modify" then this element
|
|
MUST be present.
|
|
If the <b>[Body]</b>/wsrt:Put/Fragment/@Mode attribute is
|
|
"http://www.w3.org/2009/09/ws-rst/Remove" then
|
|
this element MUST NOT be present. A resource MUST generate an
|
|
InvalidPutSyntaxFault if it receives a message with a Value
|
|
cardinality that is not valid for the Mode attribute.
|
|
</p></dd></dl><p>
|
|
If a resource encounters a
|
|
failure while processing the fragments in a Put request, it MUST
|
|
generate a PutFault. The resource SHOULD ensure that its representation
|
|
is unchanged from prior to the request, although atomic behavior is not
|
|
required of resource implementations. The resource SHOULD include a
|
|
wsrt:SideAffects element in the fault detail to indicate whether any
|
|
changes occurred.
|
|
</p><p>
|
|
If the resource accepts a Put request and performs the
|
|
requested update, it MUST reply with a response of the following form:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Headers]</b>
|
|
<wsrt:ResourceTransfer/>
|
|
|
|
<b>[Action]</b>
|
|
http://www.w3.org/2009/09/ws-tra/PutResponse
|
|
|
|
<b>[Body]</b></pre></div></div><p>
|
|
The following describes additional constraints on the outline listed above:
|
|
</p><dl><dt class="label"> <b>[Headers]</b>/wsrt:ResourceTransfer </dt><dd><p>
|
|
This header indicates that the response contains body
|
|
content defined in WS-ResourceTransfer.
|
|
</p></dd><dt class="label"> <b>[Body]</b> </dt><dd><p>
|
|
If the request Body contained a wsrt:Put element then the new
|
|
representation MUST be omitted in the response. Otherwise the response
|
|
MUST be as described in WS-Transfer. The absence of the resource
|
|
representation in the response is in recognition of the potentially
|
|
large amount of data that can be returned, which could have been the
|
|
reason a fragment Put was used instead of
|
|
sending the entire resource representation.
|
|
</p></dd></dl><p>
|
|
An example Put message using the XPath Level 1 dialect is
|
|
shown in <a href="#put_xpath1">Example 4-5</a>. For brevity only the message
|
|
body is shown.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="put_xpath1" id="put_xpath1"></a>Example 4-5: Put message using the XPath Level 1 dialect</div><div class="exampleInner"><pre>(01) <s:Body>
|
|
(02) <wsrt:Put Dialect="http://www.w3.org/2009/09/ws-rst/Dialects/XPath-Level-1"
|
|
(03) xmlns:d="http://example.org/sample">
|
|
(04) <wsrt:Fragment Mode='http://www.w3.org/2009/09/ws-rst/Remove'>
|
|
(05) <wsrt:Expression>
|
|
(06) d:Volume[1]
|
|
(07) </wsrt:Expression>
|
|
(08) </wsrt:Fragment>
|
|
(09) <wsrt:Fragment Mode='http://www.w3.org/2009/09/ws-rst/Insert'>
|
|
(10) <wsrt:Expression>
|
|
(11) d:Volume[2]
|
|
(12) </wsrt:Expression>
|
|
(13) <wsrt:Value>
|
|
(14) <d:Volume>
|
|
(15) <d:Drive>X:</d:Drive>
|
|
(16) <d:Label>MyDrive-X</d:Label>
|
|
(17) <d:TotalCapacity>5000000000</d:TotalCapacity>
|
|
(18) </d:Volume>
|
|
(19) </wsrt:Value>
|
|
(20) </wsrt:Fragment>
|
|
(21) </wsrt:Put>
|
|
(22) </s:Body></pre></div></div><p>
|
|
Line (04) indicates that a fragment SHOULD be removed and is targeted
|
|
at the 1<sup>st</sup> Volume element, identified by the wsrt:Expression
|
|
contents on line (05). Line (09) indicates that a fragment SHOULD be
|
|
inserted into the representation that results from applying the first
|
|
fragment update.
|
|
The insertion location is identified by the wsrt:Expression contents on
|
|
line (11), i.e. immediately before the second Volume element.
|
|
Lines (13) - (18) show the content of the new Volume which is to be
|
|
inserted. The updated resource representation is illustrated in
|
|
<a href="#after_put">Example 4-6</a>.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="after_put" id="after_put"></a>Example 4-6: Updated resource representation</div><div class="exampleInner"><pre>(01) <Disk xmlns="http://example.org/sample">
|
|
(02) <DiskCapacity>62500000000</DiskCapacity>
|
|
(03) <DiskFreeSpace>524182841</DiskFreeSpace>
|
|
(04) <SerialNumber>123-F2560</SerialNumber>
|
|
(05) <LastAuditDate>1998-05-25T13:30:15</LastAuditDate>
|
|
(06) <Volume>
|
|
(07) <Drive>D:</Drive>
|
|
(08) <Label>MyDrive-D</Label>
|
|
(09) <TotalCapacity>30000000000</TotalCapacity>
|
|
(10) <FreeSpace>26462809800</FreeSpace>
|
|
(11) </Volume>
|
|
(12) <Volume>
|
|
(13) <Drive>X:</Drive>
|
|
(14) <Label>MyDrive-X</Label>
|
|
(15) <TotalCapacity>5000000000</TotalCapacity>
|
|
(16) <FreeSpace>5000000000</FreeSpace>
|
|
(17) </Volume>
|
|
(18) <Volume>
|
|
(19) <Drive>E:</Drive>
|
|
(20) <Label>MyDrive-E</Label>
|
|
(21) <TotalCapacity>22500000000</TotalCapacity>
|
|
(22) <FreeSpace>16056784170</FreeSpace>
|
|
(23) </Volume>
|
|
(24) </Disk></pre></div></div><p>
|
|
Lines (12) - (17) show the result of the Put@Insert operation. Drive C was
|
|
removed and X was inserted at position 2 in between drive D and E since
|
|
the expression targeted the 2<sup>nd</sup> Volume element after the
|
|
removal of C.
|
|
</p><p>
|
|
An example Put message using the QName dialect is shown in
|
|
<a href="#putresponse_qname">Example 4-7</a>.
|
|
For brevity only the message body is shown.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="putresponse_qname" id="putresponse_qname"></a>Example 4-7: Put message using the QName dialect</div><div class="exampleInner"><pre>(01) <s:Body>
|
|
(02) <wsrt:Put Dialect="http://www.w3.org/2009/09/ws-rst/Dialects/QName"
|
|
(03) xmlns:d="http://example.org/sample">
|
|
(04) <wsrt:Fragment Mode='http://www.w3.org/2009/09/ws-rst/Modify'>
|
|
(05) <wsrt:Expression>
|
|
(06) d:Volume
|
|
(07) </wsrt:Expression>
|
|
(08) <wsrt:Value>
|
|
(09) <d:Volume>
|
|
(10) <d:Drive>F:</d:Drive>
|
|
(11) <d:Label>MyDrive-F</d:Label>
|
|
(12) <d:TotalCapacity>5000000000</d:TotalCapacity>
|
|
(13) </d:Volume>
|
|
(14) <d:Volume>
|
|
(15) <d:Drive>D:</d:Drive>
|
|
(16) <d:Label>MyDrive-D</d:Label>
|
|
(17) <d:TotalCapacity>30000000000</d:TotalCapacity>
|
|
(18) </d:Volume>
|
|
(19) </wsrt:Value>
|
|
(20) </wsrt:Fragment>
|
|
(21) <wsrt:Fragment Mode='http://www.w3.org/2009/09/ws-rst/Insert'>
|
|
(22) <wsrt:Expression>
|
|
(23) d:Volume
|
|
(24) </wsrt:Expression>
|
|
(25) <wsrt:Value>
|
|
(26) <d:Volume>
|
|
(27) <d:Drive>X:</d:Drive>
|
|
(28) <d:Label>MyDrive-X</d:Label>
|
|
(29) <d:TotalCapacity>5000000000</d:TotalCapacity>
|
|
(30) </d:Volume>
|
|
(31) </wsrt:Value>
|
|
(32) </wsrt:Fragment>
|
|
(33) </wsrt:Put>
|
|
(34) </s:Body></pre></div></div><p>
|
|
Line (04) again indicates that the fragment needs to be updated (i.e
|
|
logically removed and then replaced). The target fragment of the resource
|
|
is the set of d:Volume elements, identified by the wsrt:Expression
|
|
contents on line (06). Lines (08) - (19) show the new value for this
|
|
set of elements to use to replace the old set.
|
|
</p><p>
|
|
Lines (21) - (32) indicates that a fragment SHOULD be inserted into the
|
|
representation that results from applying the first fragment update.
|
|
Lines (25) - (31) show the content of the new Volume which is added at
|
|
the end.
|
|
</p><p>
|
|
The updated resource representation is illustrated in
|
|
<a href="#after_put2">Example 4-8</a>.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="after_put2" id="after_put2"></a>Example 4-8: Updated resource representation</div><div class="exampleInner"><pre>(01) <Disk xmlns="http://example.org/sample">
|
|
(02) <DiskCapacity>62500000000</DiskCapacity>
|
|
(03) <DiskFreeSpace>524182841</DiskFreeSpace>
|
|
(04) <SerialNumber>123-F2560</SerialNumber>
|
|
(05) <LastAuditDate>1998-05-25T13:30:15</LastAuditDate>
|
|
(06) <Volume>
|
|
(07) <Drive>F:</Drive>
|
|
(08) <Label>MyDrive-F</Label>
|
|
(09) <TotalCapacity>5000000000</TotalCapacity>
|
|
(10) <FreeSpace>5000000000</FreeSpace>
|
|
(11) </Volume>
|
|
(12) <Volume>
|
|
(13) <Drive>D:</Drive>
|
|
(14) <Label>MyDrive-D</Label>
|
|
(15) <TotalCapacity>30000000000</TotalCapacity>
|
|
(16) <FreeSpace>30000000000</FreeSpace>
|
|
(17) </Volume>
|
|
(18) <Volume>
|
|
(19) <Drive>X:</Drive>
|
|
(20) <Label>MyDrive-X</Label>
|
|
(21) <TotalCapacity>5000000000</TotalCapacity>
|
|
(22) <FreeSpace>5000000000</FreeSpace>
|
|
(23) </Volume>
|
|
(24) </Disk></pre></div></div><p>
|
|
Lines (06) - (17) show the result of the Put@Modify operation. Drives C, D
|
|
and E are replaced by drives D and F. Effectively, drives C and E are
|
|
removed and drive F is inserted. Lines (18) - (23) show the result of the
|
|
Put@Insert operation. The Volume element for drive X is added at the end
|
|
of the array of Volumes.
|
|
</p></div><div class="div2">
|
|
<h3><a name="Create" id="Create"></a>4.5 Create</h3><p>
|
|
The WS-Transfer "Create" operation is used for creating a
|
|
resource via an initial representation. The resource factory that receives a
|
|
Create request will allocate a new resource that is initialized from the
|
|
presented representation. The new resource will be assigned a
|
|
factory-service-determined
|
|
endpoint reference that is returned in the response message. In many cases, the
|
|
information required to create a resource can markedly differ from the initial
|
|
representation (the value as realized by a subsequent "Get"
|
|
operation), and supplying the initial representation is not viable.
|
|
</p><p>
|
|
WS-ResourceTransfer extends the "Create" operation to create
|
|
a resource from zero or more specified fragments of the XML representation.
|
|
</p><p>The extended outline for the "Create" operation is:</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Headers]</b>
|
|
<wsrt:ResourceTransfer s:mustUnderstand="true"/>
|
|
|
|
<b>[Action]</b>
|
|
http://www.w3.org/2009/09/ws-tra/Create
|
|
|
|
<b>[Body]</b>
|
|
<wsrt:Create Dialect="<em>xs:anyURI</em>"?>
|
|
<wsrt:Fragment>
|
|
<wsrt:Expression><em>xs:any</em></wsrt:Expression> ?
|
|
<wsrt:Value ...><em>xs:any</em></wsrt:Value>
|
|
</wsrt:Fragment> *
|
|
</wsrt:Create></pre></div></div><p>
|
|
The following describes additional constraints on the outline listed above:
|
|
</p><dl><dt class="label"> <b>[Header]</b>/wsrt:ResourceTransfer </dt><dd><p>
|
|
If present and understood, a resource MUST process the
|
|
<b>[Body]</b> in its entirety and comply with its content.
|
|
If not present
|
|
then a resource MUST treat this request as described in WS-Transfer
|
|
Create <a href="#WsTransfer">[WS-Transfer]</a>.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Create </dt><dd><p>
|
|
An element that specifies the fragments of the resource
|
|
representation to be initialized during resource creation.
|
|
This element MUST be present if the
|
|
wsrt:ResourceTransfer header is present.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Create/@Dialect </dt><dd><p>
|
|
This URI indicates which expression dialect will be used to
|
|
identify the fragment(s) of the resource representation to be
|
|
initialized during resource creation. This attribute MUST be present
|
|
when the message contains a wsrt:Expression element.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Create/Fragment </dt><dd><p>
|
|
This element encompasses a single resource fragment to be
|
|
initialized during the resource creation. If there are multiple
|
|
Fragment elements then the resource MUST appear to have been
|
|
created as though each fragment were processed in the sequence
|
|
specified in the Create message.
|
|
</p><p>
|
|
If the request contains more Fragment elements than the resource
|
|
supports the resource MUST return a fault which SHOULD be
|
|
wsrt:MultipartLimitExceededFault.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Create/Fragment/Expression </dt><dd><p>
|
|
When present this optional element contains an expression
|
|
that identifies a resource fragment to be initialized during resource
|
|
creation. The expression identifies the fragment in the resource
|
|
representation as it
|
|
appears <em>after</em> successful processing of the current
|
|
fragment. Absence of
|
|
this element is equivalent to an Expression that identifies the entire
|
|
resource representation. The value of this element MUST conform to the
|
|
dialect specified
|
|
in the <b>[Body]</b>/wsrt:Create/@Dialect attribute. A resource
|
|
factory MUST
|
|
generate an InvalidExpressionFault if the expression is invalid.
|
|
If the expression syntax is not valid with respect to the dialect
|
|
then a resource factory SHOULD
|
|
specify a fault detail of "InvalidExpressionSyntax". If the
|
|
expression is not valid for the resource type then the resource
|
|
factory SHOULD specify a fault detail of "InvalidExpressionValue".
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wsrt:Create/Fragment/Value </dt><dd><p>
|
|
This element contains the data to be written to the
|
|
resource representation. If the resource factory is unable to write the
|
|
requested fragment then it MUST generate a CreateFault.
|
|
</p></dd></dl><p>
|
|
If the resource factory accepts a Create request, it MUST reply with a
|
|
response of the following form:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><b>[Headers]</b>
|
|
<wsrt:ResourceTransfer/>
|
|
|
|
<b>[Action]</b>
|
|
http://www.w3.org/2009/09/ws-tra/CreateResponse
|
|
|
|
<b>[Body]</b>
|
|
<wst:ResourceCreated>
|
|
<em>wsa:EndpointReferenceType</em>
|
|
</wst:ResourceCreated></pre></div></div><p>
|
|
The following describes additional constraints on the outline listed above:
|
|
</p><dl><dt class="label"> <b>[Headers]</b>/wsrt:ResourceTransfer </dt><dd><p>
|
|
This header indicates that the response contains body
|
|
content defined in WS-ResourceTransfer.
|
|
</p></dd><dt class="label"> <b>[Body]</b>/wst:ResourceCreated </dt><dd><p>
|
|
This element contains the endpoint reference for the
|
|
resource that was created. All subsequent access to the resource MUST
|
|
be done using this EPR.
|
|
</p></dd></dl><p>
|
|
If the request Body contained a wsrt:Create element then the
|
|
new representation MUST be omitted in the response. Otherwise the
|
|
response MUST be as described in WS-Transfer.
|
|
</p><p>
|
|
An example Create message using the QName dialect is shown
|
|
in <a href="#create_qname">Example 4-9</a>. For brevity only the message body
|
|
is shown.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="create_qname" id="create_qname"></a>Example 4-9: Create message using the QName dialect</div><div class="exampleInner"><pre>(01) <s:Body>
|
|
(02) <wsrt:Create Dialect="http://www.w3.org/2009/09/ws-rst/Dialects/QName"
|
|
(03) xmlns:d="http://example.org/sample">
|
|
(04) <wsrt:Fragment>
|
|
(05) <wsrt:Expression>
|
|
(06) d:Volume
|
|
(07) </wsrt:Expression>
|
|
(08) <wsrt:Value>
|
|
(09) <d:Volume>
|
|
(10) <d:Drive>C:</d:Drive>
|
|
(11) <d:Label>MyDrive-C</d:Label>
|
|
(12) <d:TotalCapacity>10000000000</d:TotalCapacity>
|
|
(13) </d:Volume>
|
|
(14) <d:Volume>
|
|
(15) <d:Drive>D:</d:Drive>
|
|
(16) <d:Label>MyDrive-D</d:Label>
|
|
(17) <d:TotalCapacity>30000000000</d:TotalCapacity>
|
|
(18) </d:Volume>
|
|
(19) </wsrt:Value>
|
|
(20) </wsrt:Fragment>
|
|
(21) </wsrt:Create>
|
|
(22) </s:Body></pre></div></div><p>
|
|
Line (06) indicates that
|
|
resource is created with a specific value or set of values for the
|
|
<d:Volume> property. Lines (08) - (19) specify the set of values of
|
|
the <d:Volume> property. The response to this "Create"
|
|
message is illustrated in <a href="#createresponse_qname">Example 4-10</a>.
|
|
</p><div class="exampleOuter">
|
|
<div class="exampleHeader"><a name="createresponse_qname" id="createresponse_qname"></a>Example 4-10: CreateResponse</div><div class="exampleInner"><pre>(01) <s:Body>
|
|
(02) <wst:ResourceCreated>
|
|
(03) <wsa:Address>http://www.example.org/diskport</wsa:Address>
|
|
(04) <wsa:ReferenceParameters>
|
|
(05) <xyz:ManagedResource>44355</xyz:ManagedResource>
|
|
(06) </wsa:ReferenceParameters>
|
|
(07) </wst:ResourceCreated>
|
|
(08) </s:Body></pre></div></div><p>
|
|
Lines (02) - (07) show the EPR to the disk resource that is returned in
|
|
the response message.
|
|
</p></div></div><div class="div1">
|
|
<h2><a name="faults" id="faults"></a>5 Faults</h2><p>
|
|
All fault messages defined in this specification MUST be sent
|
|
according to the rules and usage described in
|
|
<a href="#WSABinding">[WS-Addressing 1.0 SOAP Binding]</a>
|
|
Section 6 for encoding SOAP 1.1 and SOAP 1.2 faults.
|
|
The <b>[Action]</b> property below MUST be used for faults
|
|
defined in this specification:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>http://www.w3.org/2009/09/ws-rst/fault</pre></div></div><p>
|
|
The definitions of faults in this section use the following properties:
|
|
</p><p>
|
|
<b>[Code]</b> The fault code.<br />
|
|
<b>[Subcode]</b> The fault subcode.<br />
|
|
<b>[Reason]</b> The English language reason element.<br />
|
|
<b>[Detail]</b> The detail element. If absent, no detail element
|
|
is defined for the fault.<br />
|
|
</p><p>
|
|
For SOAP 1.2, the <b>[Code]</b> property MUST be either
|
|
"Sender" or "Receiver". These properties are serialized
|
|
into text XML as follows:
|
|
</p><a name="soapver" id="soapver"></a><table border="1"><tbody><tr><th> SOAP Version </th><th> Sender </th><th> Receiver </th></tr><tr><td> SOAP 1.2 </td><td> s12:Sender </td><td> s12:Receiver </td></tr></tbody></table><p>The properties above bind to a SOAP 1.2 fault as follows:</p><div class="exampleOuter"><div class="exampleInner"><pre><s12:Envelope>
|
|
<s12:Header>
|
|
<wsa:Action> <b>[Action]</b> </wsa:Action>
|
|
<!-- Headers elided for brevity. -->
|
|
</s12:Header>
|
|
<s12:Body>
|
|
<s12:Fault>
|
|
<s12:Code>
|
|
<s12:Value><b>[Code]</b></s12:Value>
|
|
<s12:Subcode>
|
|
<s12:Value><b>[Subcode]</b></s12:Value>
|
|
</s12:Subcode>
|
|
</s12:Code>
|
|
<s12:Reason>
|
|
<s12:Text xml:lang="en"><b>[Reason]</b></s12:Text>
|
|
</s12:Reason>
|
|
<s12:Detail>
|
|
<b>[Detail]</b>
|
|
...
|
|
</s12:Detail>
|
|
</s12:Fault>
|
|
</s12:Body>
|
|
</s12:Envelope></pre></div></div><p>The properties bind to a SOAP 1.1 fault as follows:</p><div class="exampleOuter"><div class="exampleInner"><pre><s11:Envelope>
|
|
<s11:Body>
|
|
<s11:Fault>
|
|
<faultcode><b>[Subcode]</b></faultcode>
|
|
<faultstring xml:lang="en"><b>[Reason]</b></faultstring>
|
|
<detail>
|
|
<b>[Detail]</b>
|
|
...
|
|
</detail>
|
|
</s11:Fault>
|
|
</s11:Body>
|
|
</s11:Envelope></pre></div></div><div class="div2">
|
|
<h3><a name="unreachable" id="unreachable"></a>5.1 wsa:DestinationUnreachable</h3><p>
|
|
This fault is generated in response to a message that is targeted at a
|
|
resource that cannot be found and is deemed not to exist. This can be
|
|
because the resource was never created or because the resource has
|
|
been destroyed - there is no distinction between these cases.
|
|
</p><p>
|
|
The SOAP bindings for this fault are defined in
|
|
<a href="#AddrCore">[WS-Addressing]</a>.
|
|
</p></div><div class="div2">
|
|
<h3><a name="unavailable" id="unavailable"></a>5.2 wsa:EndpointUnavailable</h3><p>
|
|
The resource is unable to process the message at this time due to
|
|
some transient issue. The endpoint MAY optionally include a wsa:RetryAfter
|
|
parameter in the detail. The source SHOULD not retransmit the message until
|
|
this duration has passed.
|
|
</p><p>
|
|
The SOAP bindings for this fault are defined in
|
|
<a href="#AddrCore">[WS-Addressing]</a>.
|
|
</p></div><div class="div2">
|
|
<h3><a name="concurrency" id="concurrency"></a>5.3 ConcurrencyFault</h3><p>
|
|
This fault is generated by a resource to indicate that it was
|
|
unable to process a message due to concurrent access. A requester
|
|
might choose to handle this condition by retrying the operation that
|
|
caused it.
|
|
</p><a name="soapprops" id="soapprops"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:ConcurrencyFault </td></tr><tr><td> <b>[Reason]</b> </td><td>
|
|
Could not access the resource due to concurrency and/or
|
|
locking conditions
|
|
</td></tr><tr><td> <b>[Detail]</b> </td><td> </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="baddialect" id="baddialect"></a>5.4 UnsupportedDialectFault</h3><p>
|
|
This fault is generated by a resource to indicate that the expression
|
|
dialect used to identify a resource fragment is not supported by the
|
|
resource for the current operation. The fault detail SHOULD contain the
|
|
Dialect values that the resource does support for the operation.
|
|
</p><a name="tab_baddialect" id="tab_baddialect"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:UnsupportedDialectFault </td></tr><tr><td> <b>[Reason]</b> </td><td> The requested dialect is not supported </td></tr><tr><td> <b>[Detail]</b> </td><td> <wsrt:Dialect><em>xs:anyURI</em></wsrt:Dialect> * </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="badexpression" id="badexpression"></a>5.5 InvalidExpressionFault</h3><p>
|
|
This fault is generated by a resource if a <wsrt:Expression>
|
|
element has an syntax that is invalid according to the definition of the
|
|
expression dialect. If the expression syntax is not valid with respect
|
|
to the dialect then a resource SHOULD specify a fault detail of
|
|
"InvalidExpressionSyntax", indicating which expression this detail
|
|
applies to. If the expression is not valid for the resource type then
|
|
the resource SHOULD specify a fault detail of "InvalidExpressionValue",
|
|
indicating which expression this detail applies to.
|
|
</p><a name="tab_badexpression" id="tab_badexpression"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:InvalidExpressionFault </td></tr><tr><td> <b>[Reason]</b> </td><td> The specified Expression is not valid </td></tr><tr><td> <b>[Detail]</b> </td><td>
|
|
<div class="exampleOuter"><div class="exampleInner"><pre><wsrt:InvalidExpressionSyntax>
|
|
<wsrt:Expression><em>xs:any</em></wsrt:Expression> +
|
|
</wsrt:InvalidExpressionSyntax>
|
|
|
|
|
<wsrt:InvalidExpressionValue>
|
|
<wsrt:Expression><em>xs:any</em></wsrt:Expression> +
|
|
</wsrt:InvalidExpressionValue></pre></div></div>
|
|
</td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="getfault" id="getfault"></a>5.6 GetFault</h3><p>
|
|
This fault is generated by a resource if it is unable to
|
|
process a valid Get message.
|
|
</p><a name="tab_getfault" id="tab_getfault"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Receiver </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:GetFault </td></tr><tr><td> <b>[Reason]</b> </td><td> Unable to process Get message </td></tr><tr><td> <b>[Detail]</b> </td><td> </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="validity" id="validity"></a>5.7 ResourceValidityFault</h3><p>
|
|
This fault is generated by a resource if the result of processing
|
|
a Put message would cause the resource representation to become invalid. The
|
|
fault detail MAY include the wsrt:Fragment element in the Put message
|
|
that caused this fault to be generated.
|
|
</p><a name="tab_validity" id="tab_validity"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:ResourceValidityFault </td></tr><tr><td> <b>[Reason]</b> </td><td> The requested resource modification is not valid. </td></tr><tr><td> <b>[Detail]</b> </td><td> <wsrt:Fragment><em>fragment</em></wsrt:Fragmant> ? </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="dupfrag" id="dupfrag"></a>5.8 FragmentAlreadyExistsFault</h3><p>
|
|
This fault is generated by a resource if a "Put" message
|
|
specifies the "http://www.w3.org/2009/09/ws-rst/Insert" mode and
|
|
identifies a non-repeated fragment
|
|
element (maxOccurrs = 1) that already exists. The fault detail MAY include
|
|
the wsrt:Fragment that failed to be processed.
|
|
</p><a name="tab_dupfrag" id="tab_dupfrag"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:FragmentAlreadyExistsFault </td></tr><tr><td> <b>[Reason]</b> </td><td> The fragment already exists </td></tr><tr><td> <b>[Detail]</b> </td><td> <wsrt:Fragment><em>fragment</em></wsrt:Fragment> ? </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="putfault" id="putfault"></a>5.9 PutFault</h3><p>
|
|
This fault is generated by a resource if it is unable to
|
|
process a valid Put message. The fault detail MAY include the wsrt:Fragment
|
|
that failed to be processed.
|
|
</p><p>
|
|
The fault detail SHOULD include a wsrt:SideAffects element
|
|
in the fault detail to indicate whether any changes occurred. A value of
|
|
"true" indicates some changes occurred; a value of "false" indicates no
|
|
changes occurred. Absence of the element indicates that changes might
|
|
have occurred.
|
|
</p><a name="tab_putfault" id="tab_putfault"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Receiver </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:PutFault </td></tr><tr><td> <b>[Reason]</b> </td><td> Unable to process Put message </td></tr><tr><td> <b>[Detail]</b> </td><td>
|
|
<div class="exampleOuter"><div class="exampleInner"><pre><wsrt:Fragment><em>fragment</em></wsrt:Fragment> ?
|
|
<wsrt:SideEffects><em>xs:boolean</em></wsrt:SideEffects> ?</pre></div></div>
|
|
</td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="badputmode" id="badputmode"></a>5.10 PutModeUnsupportedFault</h3><p>
|
|
This fault is generated by a resource if a "Put" message
|
|
specifies a mode that is not supported by the resource.
|
|
</p><a name="tab_badputmode" id="tab_badputmode"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:PutModeUnsupportedFault </td></tr><tr><td> <b>[Reason]</b> </td><td> The Put mode is not supported </td></tr><tr><td> <b>[Detail]</b> </td><td> <em>The unsupported Mode URI</em> </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="createfault" id="createfault"></a>5.11 CreateFault</h3><p>
|
|
This fault is generated by a resource if it is unable to
|
|
process a valid Create message. The fault detail MAY include the
|
|
wsrt:Fragment that failed to be processed.
|
|
</p><a name="tab_createfault" id="tab_createfault"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Receiver </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:CreateFault </td></tr><tr><td> <b>[Reason]</b> </td><td> Unable to process Create message </td></tr><tr><td> <b>[Detail]</b> </td><td> <wsrt:Fragment><em>fragment</em></wsrt:Fragment> ? </td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="exceedmulti" id="exceedmulti"></a>5.12 MultipartLimitExceededFault</h3><p>
|
|
This fault is generated by a resource if a request message exceeds
|
|
the limit of wsrt:Expression or wsrt:Fragment elements supported for the
|
|
dialect. The fault detail MUST contain the maximum number of
|
|
wsrt:Expression or wsrt:Fragment elements supported for the dialect.
|
|
</p><a name="tab_exceedmulti" id="tab_exceedmulti"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:MultipartLimitExceededFault </td></tr><tr><td> <b>[Reason]</b> </td><td> Access to multiple fragments exceeded the supported
|
|
number of fragments in a single message </td></tr><tr><td> <b>[Detail]</b> </td><td>
|
|
<wsrt:MultipartLimit><em>xs:positiveInteger</em></wsrt:MultipartLimit>
|
|
</td></tr></tbody></table></div><div class="div2">
|
|
<h3><a name="putsyntaxfault" id="putsyntaxfault"></a>5.13 InvalidPutSyntaxFault</h3><p>
|
|
This fault is generated by a resource if a Put request
|
|
specifying a Mode "http://www.w3.org/2009/09/ws-rst/Remove"
|
|
contains a wsrt:Value element or if a Put
|
|
request specifying a Mode "http://www.w3.org/2009/09/ws-rst/Insert"
|
|
or "http://www.w3.org/2009/09/ws-rst/Modify" does not contain a
|
|
wsrt:Value element.
|
|
</p><a name="tab_putsyntaxfault" id="tab_putsyntaxfault"></a><table border="1"><tbody><tr><th align="left"> <b>[Action]</b> </th><th align="left">
|
|
http://www.w3.org/2009/09/ws-rst/fault
|
|
</th></tr><tr><td> <b>[Code]</b> </td><td> s12:Sender </td></tr><tr><td> <b>[Subcode]</b> </td><td> wsrt:InvalidRemoveSyntaxFault </td></tr><tr><td> <b>[Reason]</b> </td><td> Invalid syntax used for Put request </td></tr><tr><td> <b>[Detail]</b> </td><td> </td></tr></tbody></table></div></div><div class="div1">
|
|
<h2><a name="security" id="security"></a>6 Security Considerations</h2><p>
|
|
It is strongly RECOMMENDED that the communication between services be
|
|
secured using the mechanisms described in <a href="#WSSecurity">[WS-Security]</a>.
|
|
</p><p>
|
|
In order to properly secure messages, the
|
|
body (even if empty) and all relevant headers need to be included in the
|
|
signature. Specifically, the WS-Addressing header blocks and WS-Security
|
|
timestamp need to be signed along with the body in order to "bind"
|
|
them together and prevent certain types of attacks.
|
|
</p><p>
|
|
If a requestor is issuing multiple messages
|
|
to a resource reference, then it is RECOMMENDED that a security context be
|
|
established using the mechanisms described in <a href="#WSTrust">[WS-Trust]</a> and
|
|
<a href="#WSSecureConversation">[WS-SecureConversation]</a>. It is further RECOMMENDED that if
|
|
shared secrets are used, message-specific derived keys also be used to
|
|
protect the secret from crypto attacks.
|
|
</p><p>
|
|
The access control semantics of resource
|
|
references are out-of-scope of this specification and are specific to each
|
|
resource reference. Similarly, any protection mechanisms on resource
|
|
references independent of transfer (e.g. embedded signatures and
|
|
encryption) are also out-of-scope.
|
|
</p></div><div class="div1">
|
|
<h2><a name="policy" id="policy"></a>7 WS-ResourceTransfer Policy Assertion(s)</h2><p>
|
|
An endpoint MAY indicate that it supports WS-ResourceTransfer, or its
|
|
features, by including the WS-ResourceTransfer Policy assertion(s) within
|
|
its WSDL. By doing so the endpoint is indicating that the corresponding
|
|
WS-ResourceTransfer operations are supported by that endpoint even
|
|
though they do not explicitly appear in its WSDL.
|
|
</p></div><div class="div1">
|
|
<h2><a name="acks" id="acks"></a>8 Acknowledgements</h2><p>
|
|
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).
|
|
</p></div><div class="div1">
|
|
<h2><a name="refs" id="refs"></a>9 References</h2><div class="div2">
|
|
<h3><a name="id35821443" id="id35821443"></a>9.1 Normative References</h3><dl><dt class="label"><a name="RFC2119" id="RFC2119"></a>RFC 2119</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>
|
|
Key words for use in RFCs to Indicate Requirement Levels
|
|
</cite></a>
|
|
, S. Bradner, Author.
|
|
Internet Engineering Task Force, March 1997.
|
|
Available at <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>.</dd><dt class="label"><a name="RFC3986" id="RFC3986"></a>RFC 3986</dt><dd>
|
|
<a href="http://www.ietf.org/rfc/rfc3986.txt"><cite>
|
|
Uniform Resource Identifier (URI): Generic Syntax
|
|
</cite></a>
|
|
, T. Berners-Lee, R. Fields and L. Masinter, Authors.
|
|
Network Working Group, January 2005.
|
|
Available at <a href="http://www.ietf.org/rfc/rfc3986.txt">http://www.ietf.org/rfc/rfc3986.txt</a>.</dd><dt class="label"><a name="SOAP11" id="SOAP11"></a>SOAP11</dt><dd>
|
|
<a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/"><cite>
|
|
W3C Note, "Simple Object Access Protocol (SOAP) 1.1"
|
|
</cite></a>
|
|
, D. Box, et al, Editors.
|
|
World Wide Web Consortium (W3C), 8 May 2000.
|
|
Available at <a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">http://www.w3.org/TR/2000/NOTE-SOAP-20000508/</a>.</dd><dt class="label"><a name="SOAP121" id="SOAP121"></a>SOAP12</dt><dd>
|
|
<a href="http://www.w3.org/TR/soap12-part1/"><cite>
|
|
W3C Recommendation, "SOAP Version 1.2 Part 1: Messaging Framework"
|
|
</cite></a>
|
|
, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielson,
|
|
Editors.
|
|
World Wide Web Consortium (W3C), 27 April 2007.
|
|
Available at <a href="http://www.w3.org/TR/soap12-part1/">http://www.w3.org/TR/soap12-part1/</a>.</dd><dt class="label"><a name="AddrCore" id="AddrCore"></a>WS-Addressing</dt><dd>
|
|
<a href="http://www.w3.org/TR/ws-addr-core"><cite>
|
|
W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)"
|
|
</cite></a>
|
|
, M. Gudgin, M. Hadley, T. Rogers, Editors.
|
|
World Wide Web Consortium (W3C), 9 May 2006.
|
|
Available at <a href="http://www.w3.org/TR/ws-addr-core">http://www.w3.org/TR/ws-addr-core</a>.</dd><dt class="label"><a name="WSABinding" id="WSABinding"></a>WS-Addressing 1.0 SOAP Binding</dt><dd>
|
|
<a href="http://www.w3.org/TR/ws-addr-soap"><cite>
|
|
W3C Recommendation, "Web Services Addressing 1.0 - SOAP Binding"
|
|
</cite></a>
|
|
, M. Gudgin, M. Hadley, T. Rogers, Editors.
|
|
World Wide Web Consortium (W3C), 9 May 2006.
|
|
Available at <a href="http://www.w3.org/TR/ws-addr-soap">http://www.w3.org/TR/ws-addr-soap</a>.</dd><dt class="label"><a name="WSDL11" id="WSDL11"></a>WSDL11</dt><dd>
|
|
<a href="http://www.w3.org/TR/2001/NOTE-wsdl-20010315"><cite>
|
|
W3C Note, "Web Services Description Language (WSDL) 1.1"
|
|
</cite></a>
|
|
, E. Christensen, et al., Editors.
|
|
World Wide Web Consortium (W3C), 15 March 2001
|
|
Available at <a href="http://www.w3.org/TR/2001/NOTE-wsdl-20010315">http://www.w3.org/TR/2001/NOTE-wsdl-20010315</a>.</dd><dt class="label"><a name="MEX" id="MEX"></a>WS-MetadataExchange</dt><dd>
|
|
<a href="http://www.w3.org/TR/ws-metadata-exchange"><cite>
|
|
W3C Working Group Draft, "Web Services Metadata Exchange
|
|
(WS-MetadataExchange) 1.1"
|
|
</cite></a>
|
|
, D. Davis, et al., Editors.
|
|
World Wide Web Consortium (W3C), 15 September 2009.
|
|
Available at <a href="http://www.w3.org/TR/ws-metadata-exchange">http://www.w3.org/TR/ws-metadata-exchange</a>.</dd><dt class="label"><a name="WsTransfer" id="WsTransfer"></a>WS-Transfer</dt><dd>
|
|
<a href="http://www.w3.org/TR/ws-transfer"><cite>
|
|
W3C Working Group Draft, "Web Services Transfer (WS-Transfer)1.1"
|
|
</cite></a>
|
|
, D. Davis, et al., Editors.
|
|
World Wide Web Consortium (W3C), 15 September 2009.
|
|
Available at <a href="http://www.w3.org/TR/ws-transfer">http://www.w3.org/TR/ws-transfer</a>.</dd><dt class="label"><a name="XMLInfoset" id="XMLInfoset"></a>XML Infoset</dt><dd>
|
|
<a href="http://www.w3.org/TR/xml-infoset"><cite>
|
|
W3C Recommendation, "XML Information Set (Second Edition)"
|
|
</cite></a>
|
|
, J. Cowan, R. Tobin, Editors.
|
|
World Wide Web Consortium (W3C), 4 February 2004.
|
|
Available at <a href="http://www.w3.org/TR/xml-infoset">http://www.w3.org/TR/xml-infoset</a>.</dd><dt class="label"><a name="XMLSchema1" id="XMLSchema1"></a>XMLSchema - Part 1</dt><dd>
|
|
<a href="http://www.w3.org/TR/xmlschema-1/"><cite>
|
|
W3C Recommendation, "XML Schema Part 1: Structures (Second Edition)"
|
|
</cite></a>
|
|
, H. Thompson, et al., Editors.
|
|
World Wide Web Consortium (W3C), 28 October 2004.
|
|
Available at <a href="http://www.w3.org/TR/xmlschema-1/">http://www.w3.org/TR/xmlschema-1/</a>.</dd><dt class="label"><a name="XMLSchema2" id="XMLSchema2"></a>XMLSchema - Part 2</dt><dd>
|
|
<a href="http://www.w3.org/TR/xmlschema-2/"><cite>
|
|
W3C Recommendation, "XML Schema Part 2: Datatypes (Second Edition)"
|
|
</cite></a>
|
|
, P. Biron, A. Malhotra, Editors.
|
|
World Wide Web Consortium (W3C), 28 October 2004.
|
|
Available at <a href="http://www.w3.org/TR/xmlschema-2/">http://www.w3.org/TR/xmlschema-2/</a>.</dd><dt class="label"><a name="XPath1" id="XPath1"></a>XPath1.0</dt><dd>
|
|
<a href="http://www.w3.org/TR/xpath"><cite>
|
|
W3C Recommendation, "XML Path Language (XPath) Version 1.0"
|
|
</cite></a>
|
|
, J. Clark, S. DeRose, Editors.
|
|
World Wide Web Consortium (W3C), 16 November 1999.
|
|
Available at <a href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a>.</dd></dl></div><div class="div2">
|
|
<h3><a name="id35821815" id="id35821815"></a>9.2 Informative References</h3><dl><dt class="label"><a name="WS_I" id="WS_I"></a>WS-I BP 1.1</dt><dd>
|
|
<a href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html"><cite>
|
|
Final Material, "WS-I Basic Profile Version 1.1"
|
|
</cite></a>
|
|
, K. Ballinger, et al., Editors.
|
|
Web Services Interoperability Organization, 10 April 2006.
|
|
This is also an ISO (International Organization for Standards) Standard
|
|
ISO/IEC 29361:2008
|
|
http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=45422.
|
|
Available at <a href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">http://www.ws-i.org/Profiles/BasicProfile-1.1.html</a>.</dd><dt class="label"><a name="WSSecureConversation" id="WSSecureConversation"></a>WS-SecureConversation</dt><dd>
|
|
<a href="http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc"><cite>
|
|
OASIS Standard, "Web Services Secure Conversation
|
|
(WS-SecureConversation) 1.4"
|
|
</cite></a>
|
|
, A. Nadalin, et al., Editors.
|
|
Organization for the Advancement of Structured Information Standards
|
|
(OASIS), 2 February 2009.
|
|
Available at <a href="http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc">http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc</a>.</dd><dt class="label"><a name="WSSecurity" id="WSSecurity"></a>WS-Security</dt><dd>
|
|
<a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf"><cite>
|
|
OASIS Standard, "Web Services Security: SOAP Message Security 1.1"
|
|
</cite></a>
|
|
, K. Lawrence, C. Kaler, Editors.
|
|
Organization for the Advancement of Structured Information Standards
|
|
(OASIS), 1 February 2006.
|
|
Available at <a href="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf">http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf</a>.</dd><dt class="label"><a name="WSTrust" id="WSTrust"></a>WS-Trust</dt><dd>
|
|
<a href="http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.doc"><cite>
|
|
OASIS Standard, "Web Services Trust (WS-Trust) 1.4"
|
|
</cite></a>
|
|
, K. Lawrence, C. Kaler, Editors.
|
|
Organization for the Advancement of Structured Information Standards
|
|
(OASIS), 2 February 2009.
|
|
Available at <a href="http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.doc">http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.doc</a>.</dd></dl></div></div></div><div class="back"><div class="div1">
|
|
<h2><a name="a_xpath1" id="a_xpath1"></a>A XPath Level 1</h2><p>
|
|
XPath Level 1 is a subset of the abbreviated relative syntax
|
|
of XPath 1.0, and is used to identify or select a node within a resource
|
|
representation or fragment. It is identified by the following URI:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>http://www.w3.org/2009/09/ws-rst/Dialects/XPath-Level-1</pre></div></div><p>
|
|
The following XPath Level 1 grammar is LL(1), and the
|
|
nonterminal productions are in angle brackets. Terminal symbols are
|
|
either literals, or in UPPERCASE:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(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;</pre></div></div><p>
|
|
The terminal tokens which require further lexical
|
|
specification are NONZERO_DECIMAL_UNSIGNED_INTEGER, whose values are in the
|
|
subrange (1...4294967295), and XML_TOKEN whose values are equivalent to
|
|
those for the XML Schema type <em>xs:token</em>. This grammar
|
|
is small enough
|
|
that it can be easily implemented in resource-constrained implementations.
|
|
</p><p>
|
|
The following comments on the grammar will clarify certain
|
|
constructs within the BNF.
|
|
</p><p>
|
|
Most of the examples assume the following XML sample acting
|
|
as a "resource" document:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <a>
|
|
(02) <b>
|
|
(03) <c d="30"> 20 </c>
|
|
(04) </b>
|
|
(05) <e>
|
|
(06) <f/>
|
|
(07) <f/>
|
|
(08) </e>
|
|
(09) </a></pre></div></div><p>
|
|
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.
|
|
</p><p>
|
|
Further, the default context is the root element and the
|
|
context position is 1.
|
|
</p><p>
|
|
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:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) /a</pre></div></div><p>The following paths are equivalent:</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) /a/b
|
|
(02) b</pre></div></div><p>
|
|
Note that because the context node is the root element, a
|
|
relative path selects a matching child element.
|
|
</p><p>
|
|
The <node_sequence> production provides the recursive
|
|
behavior for the XPath:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) /a/b/c
|
|
(02) b/c</pre></div></div><p>
|
|
It also provides for selecting specific repeated elements
|
|
through the <optional_collection_operator> production:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) /a/e/f[2]</pre></div></div><p>
|
|
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.
|
|
</p><p>
|
|
The <qualified_name> production allows the XML naming
|
|
tokens to be either namespace-qualified or unqualified:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) /ns1:a/ns2:b/c</pre></div></div><p>
|
|
The namespace bindings are evaluated against any namespace
|
|
declarations that are in scope where the XPath appears within the SOAP
|
|
message.
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
The <follower> production allows for special-casing of
|
|
the final tokens of the XPath allowing it to end in either an attribute
|
|
or text.
|
|
</p><p>
|
|
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.
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) b/c/text()</pre></div></div><p>
|
|
The above expression would return a node-set containing a
|
|
single text node with the value <em>20 </em>as its result. This text
|
|
node would then be serialized into the following XML representation:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:TextNode>20</wsrt:TextNode></pre></div></div><p>
|
|
If accessed, attributes MUST be the final token in the path
|
|
and they MAY be namespace-qualified or unqualified names, as required:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) /a/b/c/@d</pre></div></div><p>
|
|
The above expression would return a node-set containing a
|
|
single attribute node with the value <em>d="30"</em> as its result. This
|
|
attribute node would then be serialized into the following XML
|
|
representation:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:AttributeNode name="d">30</wsrt:AttributeNode></pre></div></div><p>
|
|
Selection of an element returns the element and its entire
|
|
content. The path <em>/a/b </em>executed against the sample XML
|
|
returns a
|
|
node-set containing a single element node which serializes directly:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <b> <c d="30"> 20 </c> </b></pre></div></div><p>
|
|
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.
|
|
</p><p>
|
|
Conformant implementations MAY supply additional functions
|
|
and capabilities, but MUST adhere to the minimum behavior described above.
|
|
</p></div><div class="div1">
|
|
<h2><a name="rt_metadata" id="rt_metadata"></a>B Resource Metadata Content</h2><p>
|
|
A resource can have associated metadata that MAY be
|
|
specified when the resource is created. A resource MAY provide access to
|
|
that metadata after it has been created and some aspects of a resource's
|
|
metadata MAY be mutable.
|
|
</p><p>The form of the resource metadata is shown below.</p><p><b>Resource metadata:</b></p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:Metadata>
|
|
(02) <wsrt:Lifetime><em>lifetime metadata</em></wsrt:Lifetime> ?
|
|
(03) <wsrt:SupportedDialect>
|
|
(04) <em>dialect metadata</em>
|
|
(05) </wsrt:SupportedDialect> *
|
|
(06) ...
|
|
(07) </wsrt:Metadata></pre></div></div><p>
|
|
Metadata can be associated with a resource as described in
|
|
WS-MetadataExchange.
|
|
The following wsmex:GetMetadata/wsmex:Dialect URI is defined to
|
|
indicate metadata as defined in this specification:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre>http://www.w3.org/2009/09/ws-rst</pre></div></div><p>
|
|
This is used in the wsmex:GetMetadata message to return
|
|
resource metadata. It is RECOMMENDED that a resource whose
|
|
metadata is mutable use the form of a wsmex:MetadataSection that contains an
|
|
EPR which is a reference to a "metadata resource".
|
|
</p><p>
|
|
The metadata defined by this specification includes
|
|
lifecycle metadata as well as capability information about supported
|
|
dialects as described in the following sub-sections.
|
|
</p><div class="div2">
|
|
<h3><a name="lifemeta" id="lifemeta"></a>B.1 Lifecycle metadata</h3><p>
|
|
Resources have a distinct lifecycle in that they can be
|
|
created and they can be destroyed. There is no distinction between
|
|
a resource that has been destroyed and a resource that has not been
|
|
created.
|
|
</p><p>
|
|
Resources MAY allow their lifecycle metadata to be queried
|
|
and changed and MAY support operations to operate on their
|
|
lifecycle metadata. The following are properties of a resource's
|
|
lifecycle metadata:
|
|
</p><dl><dt class="label"> <b>[termination time]</b> </dt><dd><p>
|
|
The time at which the resource will be destroyed. The
|
|
environment controlling the resource MUST NOT destroy the resource
|
|
before this time but MAY choose to delay its destruction after this
|
|
time. However, client applications MUST NOT assume that the
|
|
resource will be available beyond this date/time.
|
|
</p></dd><dt class="label"> <b>[current time]</b> </dt><dd><p>
|
|
The current time, as measured by the resource. This can be used to
|
|
estimate local clock variations between time measured by a resource and
|
|
time measured by an application that uses the resource.
|
|
</p></dd></dl><p>The form of resource lifecycle metadata is shown below. </p><p><b>Resource lifecycle metadata:</b></p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:Lifetime>
|
|
(02) ( <wsrt:TerminateAt>
|
|
(03) <wsrt:TerminationTime><em>xs:dateTime</em></wsrt:TerminationTime>
|
|
(04) <wsrt:CurrentTime><em>xs:dateTime</em></wsrt:CurrentTime>
|
|
(05) </wsrt:TerminateAt> |
|
|
(06) <wsrt:TerminateAfter><em>xs:duration</em></wsrt:TerminateAfter> |
|
|
(07) <wsrt:TerminateAfterIdle>
|
|
(08) <em>xs:duration</em>
|
|
(09) </wsrt:TerminateAfterIdle> )
|
|
(10) </wsrt:Lifetime></pre></div></div><dl><dt class="label"> wsrt:Lifetime/wsrt:TerminateAt </dt><dd><p>
|
|
This element contains elements that specify the
|
|
<b>[termination time]</b> and <b>[current time]</b> as
|
|
absolute times, as measured
|
|
by the resource.
|
|
</p></dd><dt class="label"> wsrt:Lifetime/wsrt:TerminateAt/wsrt:TerminationTime </dt><dd><p>
|
|
This element specifies the <b>[termination time]</b> as an
|
|
absolute time, as measured by the resource, after which the
|
|
resource will be destroyed.
|
|
</p></dd><dt class="label"> wsrt:Lifetime/wsrt:TerminateAt/wsrt:CurrentTime </dt><dd><p>
|
|
This element specifies the <b>[current time]</b> as an absolute
|
|
time, as measured by the resource. This can be used to estimate local
|
|
clock variations between time measured by a resource and time measured
|
|
by an application that uses the resource.
|
|
</p></dd><dt class="label"> wsrt:Lifetime/wsrt:TerminateAfter </dt><dd><p>
|
|
This element specifies the <b>[termination time]</b> as a duration
|
|
after the current time that the resource will be destroyed.
|
|
</p></dd><dt class="label"> wsrt:Lifetime/wsrt:TerminateAfterIdle </dt><dd><p>
|
|
This element specifies the <b>[termination time]</b> as an amount of time to
|
|
wait after a message to the resource before automatically destroying
|
|
it. Any message sent to the resource SHOULD reset this timer.
|
|
</p></dd></dl></div><div class="div2">
|
|
<h3><a name="expmetadata" id="expmetadata"></a>B.2 Expression Dialect metadata</h3><p>
|
|
Resources can support different expression dialects, as
|
|
described above in Expression Dialect. A resource MAY declare which
|
|
dialects it supports through its resource metadata.
|
|
</p><p>
|
|
The form of resource expression dialect metadata is shown below.
|
|
</p><p><b>Resource expression metadata:</b></p><div class="exampleOuter"><div class="exampleInner"><pre>(01) <wsrt:SupportedDialect DialectName="<em>xs:anyURI</em>">
|
|
(02) <wsrt:SupportedOperation OperationName="<em>xs:anyURI</em>">
|
|
(03) <wsrt:SupportedPutMode>
|
|
(04) <em>xs:anyURI</em>
|
|
(05) </wsrt:SupportedPutMode> *
|
|
(06) <wsrt:MultipartLimit>
|
|
(07) <em>xs:positiveInteger</em>
|
|
(08) </wsrt:MultipartLimit> ?
|
|
(09) </wsrt:SupportedOperation> *
|
|
(10) </wsrt:SupportedDialect></pre></div></div><dl><dt class="label"> wsrt:SupportedDialect </dt><dd><p>
|
|
This element encapsulates all the metadata about the
|
|
support of a specific expression dialect. The resource MUST support
|
|
each of the dialects in this list and MAY support others.
|
|
</p></dd><dt class="label"> wsrt:SupportedDialect/@DialectName </dt><dd><p>
|
|
The URI that uniquely identifies the dialect.
|
|
</p></dd><dt class="label"> wsrt:SupportedDialect/wsrt:SupportedOperation </dt><dd><p>
|
|
This element encapsulates all the metadata regarding the
|
|
behaviour of the subject expression dialect for a specific WS-Transfer
|
|
operation. If this element is absent, then all WS-Transfer operations
|
|
and all Put Modes are supported for the subject dialect.
|
|
</p></dd><dt class="label">
|
|
wsrt:SupportedDialect/wsrt:SupportedOperation/@OperationName
|
|
</dt><dd><p>
|
|
The Action URI that indicates the Get, Put or Create operation.
|
|
</p></dd><dt class="label">
|
|
wsrt:SupportedDialect/wsrt:SupportedOperation/wsrt:SupportedPutMode
|
|
</dt><dd><p>
|
|
This element contains a Mode URI that is supported for the
|
|
operation for the subject dialect. If this element is absent, then all
|
|
Mode URIs defined by this specification are supported for the
|
|
operation for the subject dialect. This
|
|
element is present only when the @OperationName indicates the "Put"
|
|
operation.
|
|
</p></dd><dt class="label">
|
|
wsrt:SupportedDialect/wsrt:SupportedOperation/wsrt:MultipartLimit
|
|
</dt><dd><p>
|
|
Indicates the maximum number of <wsrt:Expression> elements
|
|
supported for a Get operation or the maximum number of
|
|
<wsrt:Fragment> elements supported for a Put or Create operation
|
|
for the subject dialect. If
|
|
this element is absent then there is no limit for the operation for the
|
|
subject dialect. A resource that specifies this metadata MUST generate
|
|
a MultipartLimitExceededFault if it receives a message that exceeds the
|
|
limit of wsrt:Expression or wsrt:Fragment elements supported for the
|
|
operation for the subject dialect.
|
|
</p></dd></dl></div></div><div class="div1">
|
|
<h2><a name="schema" id="schema"></a>C XML Schema</h2><p>
|
|
A normative copy of the XML Schema <a href="#XMLSchema1">[XMLSchema - Part 1]</a>,
|
|
<a href="#XMLSchema2">[XMLSchema - Part 2]</a> description
|
|
for this specification can be retrieved from the following address:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/09/ws-rst/wsrt.xsd">http://www.w3.org/2009/09/ws-rst/wsrt.xsd</a></pre></div></div><p>
|
|
A non-normative copy of the XML Schema description is listed
|
|
below for convenience.
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><xs:schema
|
|
targetNamespace="http://www.w3.org/2009/09/ws-rst"
|
|
xmlns:wsrt="http://www.w3.org/2009/09/ws-rst"
|
|
xmlns:xs="http://www.w3.org/2001/XMLSchema"
|
|
xmlns:wsa="http://www.w3.org/2005/08/addressing"
|
|
xmlns:wsmex="http://www.w3.org/2009/09/ws-mex"
|
|
elementFormDefault="qualified" blockDefault="#all">
|
|
|
|
<xs:import
|
|
namespace="http://www.w3.org/2005/08/addressing"
|
|
schemaLocation="http://www.w3.org/2006/03/addressing/ws-addr.xsd"/>
|
|
<xs:import namespace="http://www.w3.org/2009/09/ws-mex"
|
|
schemaLocation=
|
|
"http://www.w3.org/2009/09/ws-mex/MetadataExchange.xsd"/>
|
|
|
|
<!-- ResourceMetadata section -->
|
|
|
|
<!-- A wsmex:MetadaSection with a wsmex:Dialect of
|
|
http://www.w3.org/2009/09/ws-rst
|
|
contains the following Metadata element
|
|
-->
|
|
|
|
<xs:element name="Metadata">
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref="wsrt:Lifetime" minOccurs="0"/>
|
|
<xs:element ref="wsrt:SupportedDialect"
|
|
minOccurs="0" maxOccurs="unbounded"/>
|
|
<xs:any minOccurs="0" maxOccurs="unbounded"
|
|
namespace="##other" processContents="lax"/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name="Lifetime">
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:choice>
|
|
<xs:element ref="wsrt:TerminateAt"/>
|
|
<xs:element name="TerminateAfter" type="xs:duration"/>
|
|
<xs:element name="TerminateAfterIdle" type="xs:duration"/>
|
|
</xs:choice>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name="TerminateAt">
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name="TerminationTime" type="xs:dateTime"/>
|
|
<xs:element name="CurrentTime" type="xs:dateTime"/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name="SupportedDialect">
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref="wsrt:SupportedOperation"
|
|
minOccurs="0" maxOccurs="unbounded"/>
|
|
</xs:sequence>
|
|
<xs:attribute name='DialectName' type='xs:anyURI' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name="SupportedOperation">
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name="SupportedPutMode" type="xs:anyURI"
|
|
minOccurs="0" maxOccurs="unbounded"/>
|
|
<xs:element name="MultipartLimit"
|
|
type="xs:positiveInteger" minOccurs="0"/>
|
|
</xs:sequence>
|
|
<xs:attribute name='OperationName' type='xs:anyURI' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<!-- Shared Types section -->
|
|
<xs:complexType name='MixedAnyType' final='restriction' mixed="true">
|
|
<xs:complexContent mixed="true">
|
|
<xs:restriction base="xs:anyType">
|
|
<xs:sequence>
|
|
<xs:any processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
|
|
</xs:sequence>
|
|
</xs:restriction>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='ResultType' final='restriction'>
|
|
<xs:complexContent>
|
|
<xs:extension base='wsrt:MixedAnyType'/>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name='ExpressionType' final='restriction'>
|
|
<xs:complexContent>
|
|
<xs:extension base='wsrt:MixedAnyType'/>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:element name='Expression' type='wsrt:ExpressionType'/>
|
|
|
|
<xs:complexType name='FragmentType'>
|
|
<xs:sequence>
|
|
<xs:element ref='wsrt:Expression'
|
|
minOccurs='0' maxOccurs='1'/>
|
|
<xs:element name='Value' type='wsrt:MixedAnyType'
|
|
minOccurs='0' maxOccurs='1'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
|
|
<xs:element name='Fragment' type='wsrt:FragmentType'/>
|
|
|
|
<xs:element name="ResourceTransfer">
|
|
<xs:complexType>
|
|
<xs:anyAttribute namespace="##other" processContents="lax"/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<!-- Create section -->
|
|
<xs:element name='Create'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='wsrt:Fragment' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='Dialect' type='xs:anyURI'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name="CreateResponse">
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref="wsrt:ResourceCreated"/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name="ResourceCreated" type="wsa:EndpointReferenceType"/>
|
|
|
|
<!-- Put section -->
|
|
|
|
<xs:element name='Put'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='Fragment' type='wsrt:PutFragmentType'
|
|
maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='Dialect' type='xs:anyURI'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:complexType name='PutFragmentType'>
|
|
<xs:complexContent>
|
|
<xs:extension base="wsrt:FragmentType">
|
|
<xs:attribute name='Mode' type='xs:anyURI' use='required'/>
|
|
</xs:extension>
|
|
</xs:complexContent>
|
|
</xs:complexType>
|
|
|
|
<xs:element name="PutResponse">
|
|
<xs:complexType/>
|
|
</xs:element>
|
|
|
|
<!-- Get section -->
|
|
|
|
<xs:element name='Get'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='wsrt:Expression' minOccurs='0'
|
|
maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='Dialect' type='xs:anyURI'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='GetResponse'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='Result' type='wsrt:ResultType'
|
|
maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<!-- Fault section -->
|
|
|
|
<xs:simpleType name="FaultCodeTypes">
|
|
<xs:restriction base="xs:QName">
|
|
<xs:enumeration value="wsrt:ConcurrencyFault"/>
|
|
<xs:enumeration value="wsrt:UnsupportedDialectFault"/>
|
|
<xs:enumeration value="wsrt:InvalidExpressionFault"/>
|
|
<xs:enumeration value="wsrt:GetFault"/>
|
|
<xs:enumeration value="wsrt:ResourceValidityFault"/>
|
|
<xs:enumeration value="wsrt:FragmentAlreadyExistsFault"/>
|
|
<xs:enumeration value="wsrt:PutFault"/>
|
|
<xs:enumeration value="wsrt:PutModeUnsupportedFault"/>
|
|
<xs:enumeration value="wsrt:CreateFault"/>
|
|
<xs:enumeration value="wsrt:MultipartLimitExceededFault"/>
|
|
<xs:enumeration value="wsrt:InvalidPutSyntaxFault"/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
<xs:element name='Dialect' type='xs:anyURI'/>
|
|
|
|
<xs:element name='InvalidExpressionSyntax'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='wsrt:Expression' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='InvalidExpressionValue'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element ref='wsrt:Expression' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='MultipartLimit' type='xs:positiveInteger'/>
|
|
|
|
<xs:element name='SideEffects' type='xs:boolean'/>
|
|
|
|
<!-- XPath section -->
|
|
|
|
<xs:element name='AttributeNode'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='xs:string'>
|
|
<xs:attribute name='name' type='xs:QName'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='TextNode' type='xs:string'/>
|
|
|
|
<xs:element name='NodeSet' type='wsrt:ResultType'/>
|
|
</xs:schema></pre></div></div></div><div class="div1">
|
|
<h2><a name="wsdl" id="wsdl"></a>D WSDL</h2><p>
|
|
A normative copy of the WSDL <a href="#WSDL11">[WSDL11]</a>
|
|
description for this specification can be retrieved from the following
|
|
address:
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><a href="http://www.w3.org/2009/09/ws-rst/wsrt.wsdl">http://www.w3.org/2009/09/ws-rst/wsrt.wsdl</a></pre></div></div><p>
|
|
A non-normative copy of the WSDL description is listed below
|
|
for convenience.
|
|
</p><div class="exampleOuter"><div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8"?>
|
|
<wsdl:definitions targetNamespace=
|
|
"http://www.w3.org/2009/09/ws-rst"
|
|
xmlns:wsrt="http://www.w3.org/2009/09/ws-rst"
|
|
xmlns:wsa="http://www.w3.org/2005/08/addressing"
|
|
xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
|
|
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
|
|
xmlns:wst="http://www.w3.org/2009/09/ws-tra"
|
|
xmlns:xs="http://www.w3.org/2001/XMLSchema">
|
|
|
|
<wsdl:types>
|
|
<xs:schema>
|
|
<xs:include schemaLocation=
|
|
"http://www.w3.org/2009/09/ws-rst/wsrt.xsd"/>
|
|
</xs:schema>
|
|
</wsdl:types>
|
|
|
|
<wsdl:message name="CreateRequestMessage">
|
|
<wsdl:part name="Body" element="wsrt:Create"/>
|
|
</wsdl:message>
|
|
|
|
<wsdl:message name="CreateResponseMessage">
|
|
<wsdl:part name="Body" element="wsrt:CreateResponse"/>
|
|
</wsdl:message>
|
|
|
|
<wsdl:message name="GetRequestMessage">
|
|
<wsdl:part name="Body" element="wsrt:Get"/>
|
|
</wsdl:message>
|
|
|
|
<wsdl:message name="GetResponseMessage">
|
|
<wsdl:part name="Body" element="wsrt:GetResponse"/>
|
|
</wsdl:message>
|
|
|
|
<wsdl:message name="PutRequestMessage">
|
|
<wsdl:part name="Body" element="wsrt:Put"/>
|
|
</wsdl:message>
|
|
|
|
<wsdl:message name="PutResponseMessage">
|
|
<wsdl:part name="Body" element="wsrt:PutResponse"/>
|
|
</wsdl:message>
|
|
|
|
<wsdl:portType name="ResourceInterface">
|
|
<wsdl:documentation>
|
|
This port type contains the Get and Put
|
|
operations defined in WS-ResourceTransfer.
|
|
</wsdl:documentation>
|
|
<wsdl:operation name="Get">
|
|
<wsdl:input message="wsrt:GetRequestMessage"
|
|
wsam:Action="http://www.w3.org/2009/09/ws-tra/Get"/>
|
|
<wsdl:output message="wsrt:GetResponseMessage"
|
|
wsam:Action=
|
|
"http://www.w3.org/2009/09/ws-tra/GetResponse"/>
|
|
</wsdl:operation>
|
|
<wsdl:operation name="Put">
|
|
<wsdl:input message="wsrt:PutRequestMessage"
|
|
wsam:Action="http://www.w3.org/2009/09/ws-tra/Put"/>
|
|
<wsdl:output message="wsrt:PutResponseMessage"
|
|
wsam:Action=
|
|
"http://www.w3.org/2009/09/ws-tra/PutResponse"/>
|
|
</wsdl:operation>
|
|
</wsdl:portType>
|
|
|
|
<wsdl:portType name="ResourceFactoryInterface">
|
|
<wsdl:documentation>
|
|
This port type contains the Create operation
|
|
defined in WS-ResourceTransfer.
|
|
</wsdl:documentation>
|
|
<wsdl:operation name="Create">
|
|
<wsdl:input message="wsrt:CreateRequestMessage"
|
|
wsam:Action="http://www.w3.org/2009/09/ws-tra/Create"/>
|
|
<wsdl:output message="wsrt:CreateResponseMessage"
|
|
wsam:Action=
|
|
"http://www.w3.org/2009/09/ws-tra/CreateResponse"/>
|
|
</wsdl:operation>
|
|
</wsdl:portType>
|
|
</wsdl:definitions></pre></div></div></div><div class="div1">
|
|
<h2><a name="changelog" id="changelog"></a>E Change Log</h2><table border="1"><tbody><tr><th> Data </th><th> Author </th><th> Description </th></tr><tr><td> 2009/03/04 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6412">6412</a>
|
|
</td></tr><tr><td> 2009/03/04 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6519">6519</a>
|
|
</td></tr><tr><td> 2009/03/11 </td><td> DD </td><td> Added change log </td></tr><tr><td> 2009/03/11 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6425">6425</a>
|
|
</td></tr><tr><td> 2009/03/12 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6548">6548</a>
|
|
</td></tr><tr><td> 2009/03/23 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6666">6666</a>
|
|
</td></tr><tr><td> 2009/03/24 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6648">6648</a>
|
|
</td></tr><tr><td> 2009/04/22 </td><td> KW </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6739">6739</a>
|
|
</td></tr><tr><td> 2009/04/27 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6906">6906</a>
|
|
</td></tr><tr><td> 2009/07/01 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6699">6699</a>
|
|
</td></tr><tr><td> 2009/08/05 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=7159">7159</a>
|
|
</td></tr><tr><td> 2009/08/18 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=7206">7206</a>
|
|
</td></tr><tr><td> 2009/08/18 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=7196">7196</a>
|
|
</td></tr><tr><td> 2009/08/25 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=7365">7365</a>
|
|
</td></tr><tr><td> 2009/08/25 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=7270">7270</a>
|
|
</td></tr><tr><td> 2009/09/01 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=7429">7429</a>
|
|
</td></tr><tr><td> 2009/09/01 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6703">6703</a>
|
|
</td></tr><tr><td> 2009/09/02 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6694">6694</a>
|
|
</td></tr><tr><td> 2009/09/28 </td><td> DD </td><td> Added resolution of issue
|
|
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=6571">6571</a>
|
|
</td></tr></tbody></table></div></div></body></html>
|