Web Services Resource Transfer (WS-RT)

2.1 Requirements

This specification intends to meet the following requirements:

• Define WSDL 1.1 portTypes, for the Web service methods described in this specification, compliant with WS-I Basic Profile 1.1 [WS-I BP 1.1].

• Define minimum requirements for compliance without constraining richer implementations.

• Compose with other Web service specifications for secure, reliable, transacted message delivery.

• Provide extensibility for more sophisticated and/or currently unanticipated scenarios.

• Support a variety of encoding formats including (but not limited to) both SOAP 1.1 [SOAP 1.1] and SOAP 1.2 [SOAP 1.2] Envelopes.

2.2 Non-Requirements

This specification does not intend to meet the following requirements:

• Discovery of resources.

2.3 Example

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.

Example 2-1 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.

(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>

The protocol message for retrieving parts of the above resource representation is shown in Example 2-2. 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:

(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/02/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/02/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/02/ws-rst/Dialect/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>

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.

The response to the "Get" message is illustrated in Example 2-3.

(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/02/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/02/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>

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.

3.1 Terminology

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.

Resource

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.

Resource representation

The XML representation of the resource that is accessed using the operations defined in the WS-Transfer and WS-ResourceTransfer specifications.

Resource factory

A Web service that is capable of creating new resources using the Create operation defined in WS-Transfer and the WS-ResourceTransfer specifications.

Metadata resource

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.

Fragment

The term "fragment" is used in this specification to mean a part of the resource representation.

EPR

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.

3.2 XML Namespaces

The XML Namespace URI that MUST be used by implementations of this specification is:

http://www.w3.org/2009/02/ws-rst

Table 3-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

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 http://www.w3.org/2001/tag/doc/namespaceState.html and http://www.w3.org/2005/07/13-nsuri .

3.3 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses the following syntax to define outlines for messages:

• The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.

• Characters are appended to elements and attributes to indicate cardinality:

  • "?" (0 or 1)

  • "*" (0 or more)

  • "+" (1 or more)

• The character "|" is used to indicate a choice between alternatives.

• The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

• The characters "[" and "]" are used to call out references and property names.

• Ellipses (i.e., "...") indicate points of extensibility.

• XML namespace prefixes (see Table 3-1) are used to indicate the namespace of the element being defined.

In addition to Message Information Header properties [WS-Addressing], this specification uses the following properties to define messages:

[Headers]

Unordered message headers.

[Action]

The value to be used for the wsa:Action URI.

[Body]

A message body.

These properties bind to a SOAP Envelope as follows:

<s:Envelope>
  <s:Header>
    [Headers]
    <wsa:Action>[Action]</wsa:Action>
    ...
  </s:Header>
  <s:Body>[Body]</s:Body>
</s:Envelope>

This specification defines Fault properties for each defined fault and defines SOAP bindings for each Fault property.

3.4 Considerations on the Use of Extensibility Points

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".

Extension elements and attributes MUST NOT use the Web Services Resource Transfer namespace URI.

3.5 Compliance

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 3.2 XML Namespaces) within SOAP Envelopes unless it is compliant with this specification.

Normative text within this specification takes precedence over the XML Schema and WSDL descriptions, which in turn take precedence over outlines, which in turn take precedence over examples.

All messages defined by this specification MUST be sent to a Web service that is addressable by an EPR (see [WS-Addressing]).

4.1 Fragments

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.

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".

4.2 Expression Dialects

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 [Action] itself defines what will happen to the referenced fragment.

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.

http://www.w3.org/2009/02/ws-rst/Dialect/QName

http://www.w3.org/2009/02/ws-rst/Dialect/XPath-Level-1

http://www.w3.org/TR/1999/REC-xpath-19991116

name="value"

(01) <wsrt:AttributeNode name="attribute name">
(02)   attribute value
(03) </wsrt:AttributeNode>

(01) <wsrt:TextNode>
(02)   text value
(03) </wsrt:TextNode>

(01) <a xmlns="example">
(02)   <b>1</b>
(03)   <c x="y">2</c>
(04) </a>

(01) <wsrt:Result>
(02)   <b>1</b>
(03)   <wsrt:TextNode>1</wsrt:TextNode>
(04)   <wsrt:AttributeNode name="x">y</wsrt:AttributeNode>
(05) </wsrt:Result>

4.3 Get

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.

The [Body] of wsrt:Get contains an expression that identifies the fragment of interest.

The outline for wsrt:Get is:

[Headers]
  <wsrt:ResourceTransfer s:mustUnderstand="true"? />

[Action]
  http://www.w3.org/2009/02/ws-tra/Get

[Body]
  <wsrt:Get Dialect="xs:anyURI"?>
    <wsrt:Expression ...>xs:any</wsrt:Expression> *
  </wsrt:Get>

The following describes additional constraints on the outline listed above:

[Header]/wsrt:ResourceTransfer

If present and understood, a resource MUST process the [Body] in its entirety and comply with its content. If not present then a resource MUST treat this request as described in WS-Transfer Get [WS-Transfer].

[Body]/wsrt:Get

An element which controls the retrieval of the resource fragment. This element MUST be present if the wsrt:ResourceTransfer header is present.

[Body]/wsrt:Get/@Dialect

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.

[Body]/wsrt:Get/wsrt:Expression

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 [Body]/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".

If a resource cannot return a value for a requested fragment then it MUST generate a GetFault.

If the request contains more Expression elements than the resource supports the resource MUST return a fault which SHOULD be wsrt:MultipartLimitExceededFault.

If the resource accepts a wsrt:Get request and processes it successfully it MUST reply with a response of the following form:

[Headers]
<wsrt:ResourceTransfer/>

[Action]
  http://www.w3.org/2009/02/ws-tra/GetResponse

[Body]
  <wsrt:GetResponse>
    <wsrt:Result...> xs:any </wsrt:Result> +
  </wsrt:GetResponse>

The following describes additional constraints on the outline listed above:

[Headers]/wsrt:ResourceTransfer

This header indicates that the response contains body content defined in WS-ResourceTransfer.

[Body]/wsrt:GetResponse

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.

[Body]/wsrt:GetResponse/wsrt:Result

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.

An example Get message using the XPath Level 1 dialect and the expected GetResponse is shown in Example 2-2 and the expected GetResource is shown in Example 2-3, for the resource whose XML representation is shown in Example 2-1 above.

An example Get message that uses the QName dialect is shown in Example 4-1 below.

(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/02/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/02/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/02/ws-rst/Dialect/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>

The fragments of the resource representation are identified by the wsrt:Expression contents on lines (18) and (21). Notice that the d:Volume QName in the example resolves to three elements in the resource representation. The response to this "Get" message is illustrated in Example 4-2.

(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/02/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/02/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>

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).

One final example of the Get operation, using the full XPath 1.0 dialect, is shown below in Example 4-3. This illustrates the use of a query expression to return the computed result of the quantity of d:Volume elements that have a capacity greater than 20000000000. For the sake of brevity, only the message body is shown.

(01) <s:Body>
(02)   <wsrt:Get Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"
(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>

The expression on line (05), when applied to the resource representation in 2.3 Example, evaluates to a result of "2".

(01) <s:Body>
(02)    <wsrt:GetResponse>
(03)      <wsrt:Result>2</wsrt:Result>
(04)    </wsrt:GetResponse>
(05) </s:Body>

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).

4.4 Put

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.

The extended outline for the "Put" operation is:

[Headers]
  <wsrt:ResourceTransfer s:mustUnderstand="true"/>

[Action]
  http://www.w3.org/2009/02/ws-tra/Put

[Body]
  <wsrt:Put Dialect="xs:anyURI"?>
    <wsrt:Fragment Mode="xs:anyURI">
      <wsrt:Expression>xs:any</wsrt:Expression> ?
      <wsrt:Value ...>xs:any</wsrt:Value> ?
    </wsrt:Fragment> +
  </wsrt:Put>

The following describes additional constraints on the outline listed above:

[Header]/wsrt:ResourceTransfer

If present and understood, a resource MUST process the [Body] in its entirety and comply with its content. If not present then a resource MUST treat this request as described in WS-Transfer Put [WS-Transfer].

[Body]/wsrt:Put

An element that specifies the fragments of the resource representation to update. This element MUST be present if the wsrt:ResourceTransfer header is present.

[Body]/wsrt:Put/@Dialect

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.

[Body]/wsrt:Put/Fragment

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.

If the request contains more Fragment elements than the resource supports the resource MUST return a fault which SHOULD be wsrt:MultipartLimitExceededFault.

[Body]/wsrt:Put/Fragment/@Mode

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.

A value of "http://www.w3.org/2009/02/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.

A value of "http://www.w3.org/2009/02/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.

A value of "http://www.w3.org/2009/02/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.

[Body]/wsrt:Put/Fragment/Expression

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.

The value of this element MUST conform to the dialect specified in the [Body]/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".

[Body]/wsrt:Put/Fragment/Value

This element contains the data to be written to the resource representation. If the [Body]/wsrt:Put/Fragment/@Mode attribute is "http://www.w3.org/2009/02/ws-rst/Insert" or "http://www.w3.org/2009/02/ws-rst/Modify" then this element MUST be present. If the [Body]/wsrt:Put/Fragment/@Mode attribute is "http://www.w3.org/2009/02/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.

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.

If the resource accepts a Put request and performs the requested update, it MUST reply with a response of the following form:

[Headers]
  <wsrt:ResourceTransfer/>

[Action]
  http://www.w3.org/2009/02/ws-tra/PutResponse

[Body]

The following describes additional constraints on the outline listed above:

[Headers]/wsrt:ResourceTransfer

This header indicates that the response contains body content defined in WS-ResourceTransfer.

[Body]

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 may be returned, which may have been the reason a fragment Put was used instead of sending the entire resource representation.

An example Put message using the XPath Level 1 dialect is shown in Example 4-5. For brevity only the message body is shown.

(01) <s:Body>
(02)   <wsrt:Put Dialect="http://www.w3.org/2009/02/ws-rst/Dialect/XPath-Level-1"
(03)       xmlns:d="http://example.org/sample">
(04)     <wsrt:Fragment Mode='http://www.w3.org/2009/02/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/02/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>

Line (04) indicates that a fragment should be removed and is targeted at the 1^st 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 Example 4-6.

(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>

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^nd Volume element after the removal of C.

An example Put message using the QName dialect is shown in Example 4-7. For brevity only the message body is shown.

(01) <s:Body>
(02)   <wsrt:Put Dialect="http://www.w3.org/2009/02/ws-rst/Dialect/QName"
(03)       xmlns:d="http://example.org/sample">
(04)     <wsrt:Fragment Mode='http://www.w3.org/2009/02/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/02/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>

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.

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.

The updated resource representation is illustrated in Example 4-8.

(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>

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.

4.5 Create

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 may markedly differ from the initial representation (the value as realized by a subsequent "Get" operation), and supplying the initial representation is not viable.

WS-ResourceTransfer extends the "Create" operation to create a resource from zero or more specified fragments of the XML representation.

The extended outline for the "Create" operation is:

[Headers]
  <wsrt:ResourceTransfer s:mustUnderstand="true"/>

[Action]
  http://www.w3.org/2009/02/ws-tra/Create

[Body]
  <wsrt:Create Dialect="xs:anyURI"?>
    <wsrt:Fragment>
      <wsrt:Expression>xs:any</wsrt:Expression> ?
      <wsrt:Value ...>xs:any</wsrt:Value>
    </wsrt:Fragment> *
  </wsrt:Create>

The following describes additional constraints on the outline listed above:

[Header]/wsrt:ResourceTransfer

If present and understood, a resource MUST process the [Body] in its entirety and comply with its content. If not present then a resource MUST treat this request as described in WS-Transfer Create [WS-Transfer].

[Body]/wsrt:Create

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.

[Body]/wsrt:Create/@Dialect

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.

[Body]/wsrt:Create/Fragment

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.

If the request contains more Fragment elements than the resource supports the resource MUST return a fault which SHOULD be wsrt:MultipartLimitExceededFault.

[Body]/wsrt:Create/Fragment/Expression

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 after 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 [Body]/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".

[Body]/wsrt:Create/Fragment/Value

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.

If the resource factory accepts a Create request, it MUST reply with a response of the following form:

[Headers]
  <wsrt:ResourceTransfer/>

[Action]
  http://www.w3.org/2009/02/ws-tra/CreateResponse

[Body]
  <wst:ResourceCreated>
      wsa:EndpointReferenceType
  </wst:ResourceCreated>

The following describes additional constraints on the outline listed above:

[Headers]/wsrt:ResourceTransfer

This header indicates that the response contains body content defined in WS-ResourceTransfer.

[Body]/wst:ResourceCreated

This element contains the endpoint reference for the resource that was created. All subsequent access to the resource MUST be done using this EPR.

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.

An example Create message using the QName dialect is shown in Example 4-9. For brevity only the message body is shown.

(01) <s:Body>
(02)   <wsrt:Create Dialect="http://www.w3.org/2009/02/ws-rst/Dialect/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>

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 Example 4-10.

(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>

Lines (02) - (07) show the EPR to the disk resource that is returned in the response message.

5.1 wsa:DestinationUnreachable

This fault is sent in response to a message that is targeted at a resource that cannot be found and is deemed not to exist. This may be because the resource was never created or because the resource has been destroyed - there is no distinction between these cases.

The SOAP bindings for this fault are defined in [WS-Addressing].

5.2 wsa:EndpointUnavailable

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.

The SOAP bindings for this fault are defined in [WS-Addressing].

5.3 ConcurrencyFault

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.

5.4 UnsupportedDialectFault

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.

5.5 InvalidExpressionFault

This fault is sent 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.

<wsrt:InvalidExpressionSyntax>
  <wsrt:Expression>xs:any</wsrt:Expression> +
</wsrt:InvalidExpressionSyntax>
|
<wsrt:InvalidExpressionValue>
  <wsrt:Expression>xs:any</wsrt:Expression> +
</wsrt:InvalidExpressionValue>

5.6 GetFault

This fault is generated by a resource if it is unable to process a valid Get message.

5.7 ResourceValidityFault

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.

5.8 FragmentAlreadyExistsFault

This fault is generated by a resource if a "Put" message specifies the "http://www.w3.org/2009/02/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.

5.9 PutFault

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.

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 may have occurred.

<wsrt:Fragment>fragment</wsrt:Fragment> ?
<wsrt:SideEffects>xs:boolean</wsrt:SideEffects> ?

5.10 PutModeUnsupportedFault

This fault is generated by a resource if a "Put" message specifies a mode that is not supported by the resource.

5.11 CreateFault

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.

5.12 MultipartLimitExceededFault

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.

5.13 InvalidPutSyntaxFault

This fault is generated by a resource if a Put request specifying a Mode "http://www.w3.org/2009/02/ws-rst/Remove" contains a wsrt:Value element or if a Put request specifying a Mode "http://www.w3.org/2009/02/ws-rst/Insert" or "http://www.w3.org/2009/02/ws-rst/Modify" does not contain a wsrt:Value element.