http://www.w3.org/TR/ws-transfer
Editors:
Doug Davis,
IBM
Ashok
Malhotra, Oracle
Katy Warr,
IBM
Wu Chou,
Avaya
Copyright
© 2009 W3C® (MIT,
ERCIM,
Keio), All Rights Reserved. W3C liability,
trademark
and document
use rules apply.
This specification
describes a general SOAP-based protocol for accessing XML representations of
Web service-based resources.
This
document is an editors' copy that has no official standing.
1 Introduction
1.1 Requirements
2 Terminology and Notation
2.1 Terminology
2.2 XML Namespaces
2.3 Notational Conventions
2.4 Compliance
3 Resource Operations
3.1 Get
3.2 Put
3.3 Delete
4 Resource Factory Operations
4.1 Create
5 Faults
5.1 InvalidRepresentation
6 Security Considerations
7 Acknowledgements
8 References
A XML
Schema
B WSDL
This specification
defines a mechanism for acquiring XML-based representations of entities using
the Web service infrastructure. It defines two types of entities:
·
Resources, which
are entities addressable by an endpoint reference that provide an XML
representation
·
Resource
factories, which are Web services that can create a new resource from an XML
representation
Specifically, it
defines two operations for sending and receiving the representation of a given
resource and two operations for creating and deleting a resource and its
corresponding representation. This specification also defines optional
extensions in order to deal with fragment-based access to resources.
It should be noted
that the state maintenance of a resource is at most subject to the "best
efforts" of the hosting server. When a client receives the server's
acceptance of a request to create or update a resource, it can reasonably
expect that the resource now exists at the confirmed location and with the
confirmed representation, but this is not a guarantee, even in the absence of
any third parties. The server may change the representation of a resource, may
remove a resource entirely, or may bring back a resource that was deleted.
For instance, the
server may store resource state information on a disk drive. If that drive
crashes and the server recovers state information from a backup tape, changes
that occurred after the backup was made will be lost.
A server may have
other operational processes that change resource state information. A server
may run a background process that examines resources for objectionable content
and deletes any such resources it finds. A server may purge resources that have
not been accessed for some period of time. A server may apply storage quotas
that cause it to occasionally purge resources.
In essence, the
confirmation by a service of having processed a request to create, modify, or
delete a resource implies a commitment only at the instant that the
confirmation was generated. While the usual case should be that resources are
long-lived and stable, there are no guarantees, and clients should code
defensively.
There is no requirement
for uniformity in resource representations between the messages defined in this
specification. For example, the representations required by Create or Put may
differ from the representation returned by Get, depending on the semantic
requirements of the service. Additionally, there is no requirement that the
resource content is fixed for any given endpoint reference. The resource
content may vary based on environmental factors, such as the security context,
time of day, configuration, or the dynamic state of the service.
As per the SOAP
processing model, other specifications may define SOAP headers which may be
optionally added to request messages to require the transfer of subsets or the
application of transformations of the resource associated with the endpoint
reference. When the Action URIs defined by this specification are used, such
extension specifications must also allow the basic processing models defined
herein.
This specification
intends to meet the following requirements:
·
Provide a
SOAP-based protocol for managing resources and their representations.
·
Minimize
additional mechanism beyond the current Web Services architecture.
·
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.
This specification does not
intend to meet the following requirements:
·
Discovery of
resources.
Resource
A Web service that is addressable by an endpoint
reference as defined in WS-Addressing and that can be represented by an XML
Infoset using the Get and Put operations defined in this specification.
Resource factory
A Web service that is capable of creating new resources
using the Create operation defined in this specification.
Resource
representation
The XML representation of the resource that is
accessed using the operations defined in the WS-Transfer and
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.
The XML Namespace
URI that MUST be used by implementations of this specification is:
Table 2-1 lists
XML namespaces that are used in this specification. The choice of any namespace
prefix is arbitrary and not semantically significant.
|
Table 2-1: Prefixes and XML Namespaces used in this
specification. |
||
|
Prefix |
XML Namespace |
Specification(s) |
|
wxf |
This specification |
|
|
s |
Either SOAP 1.1 or 1.2 |
SOAP |
|
s11 |
||
|
s12 |
||
|
wsa |
||
|
wsdl |
||
|
xs |
XML
Schema [XML Schema, Part 1], [XML
Schema, Part 2] |
|
|
wsmex |
WS-MetadataExchange |
|
The working group intends to update the value
of the Web Services Enumeration 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 Enumeration
namespace URI that was assigned in the Candidate Recommendation unless
significant changes are made that impact the implementation or break post-CR
implementations of the specification. Also see http://www.w3.org/2001/tag/doc/namespaceState.html
and http://www.w3.org/2005/07/13-nsuri
.
The keywords
"MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD
NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in RFC 2119 [RFC 2119].
This specification uses the following syntax
to define outlines for messages:
·
The syntax appears
as an XML instance, but values in italics indicate data types instead of
literal values.
·
Characters are
appended to elements and attributes to indicate cardinality:
o
"?" (0
or 1)
o
"*" (0
or more)
o
"+" (1
or more)
·
The character
"|" is used to indicate a choice between alternatives.
·
The characters
"(" and ")" are used to indicate that contained items are
to be treated as a group with respect to cardinality or choice.
·
The characters
"[" and "]" are used to call out references and property
names.
·
An ellipsis (i.e.
"...") indicates a point of extensibility that allows other child or
attribute content. Additional children and/or attributes MAY be added 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 it.
·
XML namespace
prefixes (see Table 2-1) are used to indicate the
namespace of the element being defined.
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 Table 2-1) within SOAP
envelopes unless it is compliant with this specification.
Specifically, a compliant SOAP Node that
implements a resource MUST provide the Get operation as defined in this
specification, and MAY provide the Put and Delete operations.
Normative text within this specification
takes precedence over normative outlines, which in turn takes precedence over
the XML Schema and WSDL descriptions.
In any given request-response message
exchange, the responses generated by the service server MUST use the same
WS-Addressing namespace binding that was used in the request.
Implementations of WS-Transfer may optionally
support fragment-based access to resources. This section describes the key aspects
of such support.
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".
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.
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 Example 2-1.
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. Example 4-1,
below, shows an example usage of this dialect. This dialect is useful for
simple resources with no XPath processing capability.
The QName dialect MUST be indicated by using the
URI:
http://www.w3.org/2009/02/ws-tra/ExpressionDialect/QName
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.
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. Example
2-2 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.
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.
An XPath Level 1 expression is an expression whose
context is:
·
Context Node: the root element
of the XML representation of the resource
·
Context Position: 1
·
Context Size: 1
·
Variable Binding: None
·
Node Tests: NameTest and the
text NodeType
·
Function Libraries: None
·
Namespace Declarations: Any
namespace declarations in-scope where the XPath expression appears
Consider the resource described in Example 2-1.
The XPath Level 1 dialect can define references to any element, attribute or
value in the resource representation.
The XPath Level 1 dialect MUST be indicated by
using the URI:
http://www.w3.org/2009/02/ws-tra/ExpressionDialect/XPath-Level-1
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.
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. Example 4-3,
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.
An XPath 1.0 expression is an expression whose
context is:
·
Context Node: the root element
of the XML representation of the resource
·
Context Position: 1
·
Context Size: 1
·
Variable Binding: None
·
Function Libraries: Core
function library
·
Namespace Declarations: Any
namespace declarations in-scope where the XPath expression appears
Consider the resource described in Example 2-1.
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.
The XPath 1.0 dialect MUST be indicated by using
the URI:
http://www.w3.org/TR/1999/REC-xpath-19991116
Implementations that support the full XPath 1.0
dialect MUST support the XPath Level 1 dialect.
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 wst:Result element:
·
Boolean - converted to an
xs:boolean
·
string - convert to an
xs:string
·
number - convert to an
xs:double
A node-set is zero or more elements, attributes or
text values of elements. A node-set is serialized into XML by concatenating
each node and enclosing it in the wst: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.
Attribute nodes in XPath are represented in the
following form:
name="value"
Serialization of an attribute node separates the
name from the value using the following element:
(01) <wst:AttributeNode name="attribute name">(02) attribute value(03) </wst:AttributeNode>
The following describes additional constraints on
the outline listed above:
wst:AttributeNode
This element is used to serialize an attribute node
in a node-set and MUST contain the value portion of the attribute node.
wst:AttributeNode/@name
This attribute MUST be the name portion of the
attribute node.
Text nodes are serialized in the following form:
(01) <wst:TextNode>(02) text value(03) </wst:TextNode>
The following describes additional constraints on
the outline listed above:
wst:TextNode
This element is used to serialize a text node in a
node-set and MUST contain the text value.
Given the following XML as an example document.
(01) <a xmlns="example">(02) <b>1</b>(03) <c x="y">2</c>(04) </a>
The result of the XPath "/a/b | /a/b/text() |
/a/c/@x" would be serialized as the following:
(01) <wst:Result>(02) <b>1</b>(03) <wst:TextNode>1</wst:TextNode>(04) <wst:AttributeNode name="x">y</wst:AttributeNode>(05) </wst:Result>
The nodes in the node-set MAY be serialized in any
order.
The WS-Transfer global
element definition wst:NodeSet can also be used as
the wrapper element when serializing these node-sets outside of a WS-T result.
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.
This specification defines one Web
service operation (Get) for fetching a one-time snapshot of the representation
of a resource.
The Get request message MUST be of the
following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Get
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:Get ExpressionDialect="xs:anyURI"?
...>
<wst:Expression ...> ... </wst:Expression> +
|
xs:any *
</wst:Get>
</s:Body>
</s:Envelope>
The following describes additional,
normative constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the
value http://www.w3.org/2009/02/ws-tra/Get. If a SOAP Action URI is also present
in the underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:Get@DialectExpressionDialect
This OPTIONAL attribute, when
present, indicates that fragment retrieval is being performed and also indicates
which expression dialect will be used to identify the fragment(s) of the
resource representation to retrieve. When this attribute is
present, the only children elements of the wst:Get element MUST be
wst:Expression elements, and there MUST be at least one. When this attribute is not present then
...<<we default back to current ws-transfer where the first child is the
actual XML of the resource and 2+ children are ignored>>. This
attribute MUST be present when the message contains a wst:Expression element. A
resource MUST generate an UnsupportedDialectFault if it does not support the
specified Dialect.
<< add text that a fault MUST be generated if it doesn't support
Fragments at all>>
/s:Envelope/s:Body/wst:Get/wst: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 /s:Envelope/s:Body/wst:Get@ExpressionDialect 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
wst:MultipartLimitExceededFault.
A Get request MUST be targeted at the
resource whose representation is desired as described in 2 Terminology and
Notation of this specification.
There are no body blocks defined by default for a
Get Request. As per the SOAP processing model, other specifications may
introduce various types of extensions to the semantics of this message which
are enabled through headers tagged with s:mustUnderstand="true". Such extensions may define how resource or
subsets of it are to be retrieved or transformed prior to retrieval.
Specifications which define such extensions MUST allow processing the basic Get
request message without those extensions. Since the response may not be sent to
the original sender, extension specifications should consider adding a
corresponding SOAP header value in the response to signal to the receiver that
the extension is being used.
Implementations may respond with a fault
message using the standard fault codes defined in WS-Addressing (e.g.,
wsa:ActionNotSupported). Other components of the outline above are not further
constrained by this specification.
If the resource accepts a Get request, it MUST reply with
a response of the following form:
<s:Envelope
...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/GetResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:GetResponse ...>
<wst:ResourceFragment> xs:any
</wst:ResourceFragment> +
|
xs:any+
</wst:GetResponse>
</s:Body>
</s:Envelope>
The following describes additional, normative constraints
on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value
http://www.w3.org/2009/02/ws-tra/GetResponse. If a SOAP Action URI is also
present in the underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:GetResponse/wst:ResourceFragment
This OPTIONAL element, when present, encompasses a
single fragment response corresponding to a wst:Expression in the original
request and MUST contain the fragment of the resource representation identified
by the wst:Expression. If the request contained a wst:Get@ExpressionDialect
attribute then the response MUST contain an equal number of wst:Result
elements.
/s:Envelope/s:Body/xs:anychild::*[position()=1]
If the request message did not include the Dialect
attribute, then tThe representation itself MUST be the
initial child element of the wst:GetResponseSOAP:Body element of the response
message. The presence of subsequent child elements is service-specific and MAY
be controlled by the presence or extension-specific SOAP headers in the
original request.
Other components of the outline above are not further constrained by this
specification.
The following shows a sample SOAP envelope containing a
Get request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/pullport
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/repository</wsa:To>
<xxx:CustomerID>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Get
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000046
</wsa:MessageID>
</s:Header>
<s:Body/>
</s:Envelope>
The following shows the corresponding response message:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/pullport</wsa:Address>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/GetResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000046
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000046
</wsa:RelatesTo>
</s:Header>
<s:Body>
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>123 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
</s:Body>
</s:Envelope>
In this example, the representation of the resource is
the following XML element:
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>123 Main
Street</xxx:address>
<xxx:city>Manhattan
Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
This specification defines one Web
service operation (Put) for updating a resource by providing a replacement
representation. A resource MAY accept updates that provide different XML
representations than that returned by the resource; in such a case, the
semantics of the update operation is defined by the resource.
The Put request message MUST be of the
following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Put
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body...>
<wst:Put ExpressionDialect="xs:anyURI"?
...>
<wst:Fragment @Mode="xs:anyURI">
<wst:Expression> xs:any
</wst:Expression>[I2]
<wst:Value ...> xs:any </wst:Value> ?
</wst:Fragment>
| xs:any +
</wst:Put>
</s:Body>
</s:Envelope>
The following describes additional,
normative constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the
value http://www.w3.org/2009/02/ws-tra/Put. If a SOAP Action URI is also
present in the underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:Put@ExpressionDialect
This OPTIONAL attribute, when
present, indicates that a fragment update is being performed
and also 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 /s:Envelope/s:Body/wst:Put/wst:Fragment
element. << add text to say that a fault
MUST be generated if it doesn't support fragments at all>>
/s:Envelope/s:Body/wst:Put/wst:Fragment
This optional 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 wst:MultipartLimitExceededFault.
If this element is present, other (non-Fragment) children following this
element SHOULD be ignored by the service.[I3]
/s:Envelope/s:Body/wst:Put/wst: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-tra/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-tra/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 wst:Expression MUST specify this
Mode.
A value of
"http://www.w3.org/2009/02/ws-tra/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.
/s:Envelope/s:Body/wst:Put/wst:Fragment/wst:Expression
This
element contains the expression that identifies a fragment of the resource
representation to be updated.
The
value of this element MUST conform to the dialect specified in the /s:Envelope/s:Body/wst:Put@ExpressionDialect
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".
/s:Envelope/s:Body/wst:Put/wst:Fragment/wst:Value
This element
contains the data to be written to the resource representation. If the /s:Envelope/s:Body/wst:Put/wst:Fragment@Modeattribute is
"http://www.w3.org/2009/02/ws-tra/Insert"
or "http://www.w3.org/2009/02/ws-tra/Modify"
then this element MUST be present. If the [Body]/wst:Put/Fragment/@Mode
attribute is "http://www.w3.org/2009/02/ws-tra/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.
/s:Envelope/s:Body/wst:Put/xs:anychild::*[position()=1]
This OPTIONAL element MUST
contain tThe representation to be used for the
update
MUST be the initial child element of the s:Body element of the request message.
All other children SHOULD be ignored by the service. This element
MUST NOT be present if a wst:Fragment element is present.
A Put request MUST be targeted at the
resource whose representation is desired to be replaced, as described in 2 Terminology and
Notation of this specification. As per the SOAP processing model, other
specifications MAY introduce various types of extensions to this message which
are enabled through headers tagged with s:mustUnderstand="true". Such extensions may require that a full or partial
update should be accomplished using symbolic, instruction-based, or other
methodologies.
Extension specifications MAY also define extensions
to the original Put request, enabled by OPTIONAL SOAP headers, which control
the nature of the response, as discussed in remarks on the PutResponse below.
Specifications which define any of these extensions
MUST allow processing the Put message without such extensions.
In addition to the standard fault codes
defined in WS-Addressing, implementations MAY use the fault code
wxf:InvalidRepresentation if the presented representation is invalid for the
target resource. See Section 5. Other components of the outline above are not
further constrained by this specification.
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.
A successful Put operation updates the current
representation associated with the targeted resource.
If the resource accepts a Put request and performs the
requested update, it MUST reply with a response of the following form:
<s:Envelope
...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/PutResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:PutResponse ...>
xs:any ?
</wst:PutResponse>
</s:Body>
</s:Envelope>
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value
http://www.w3.org/2009/02/ws-tra/PutResponse. If a SOAP Action URI is also
present in the underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:PutResponse/child::*[position()=1]xs:any
If the
request Body contained a /s:Envelope/s:Body/wst:Create/wst:Fragment element, then the new representation MUST
be omitted in the response. 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. [I4]
If the request Body did not contain a wst:Fragment
element, By default, a service MUST return the
current representation of the resource as the initial child of the s:Body
element if the updated representation differs from the representation sent in
the Put request message. The presence of additional child elements which
contain other information pertaining to the update is service-specific.
As an optimization and as a service to the requester, the
s:Body element of the response message SHOULD be empty if the updated
representation does not differ from the representation sent in the Put request
message; that is, if the service accepted the new representation verbatim.
Such a response (an empty s:Body) implies that the update
request was successful in its entirety (assuming no intervening mutating
operations are performed). A service MAY return the current representation of
the resource as the initial child of the s:Body element even in this case,
however.
Extension specifications MAY define extensions to
the original Put request, enabled by OPTIONAL header values, which specifically
control the presence, absence, or format of the updated representation or other
child elements in the PutResponse in order to optimize the response. In the
absence of such headers, the behavior MUST be as described above. Specifications
which define any of these extensions MUST allow processing the Put message
without such extensions. Since the response may not be sent to the original
sender, extension specifications should consider adding a corresponding SOAP
header value in the response to signal to the receiver that the extension is
being used.
Other components of the outline above are
not further constrained by this specification.
The following shows a sample SOAP envelope containing a
Put request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/pushport</wsa:To>
<xxx:CustomerID>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Put
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000047
</wsa:MessageID>
</s:Header>
<s:Body>
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>321 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
</s:Body>
</s:Envelope>
The following shows the corresponding response message
indicating success:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/PutResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000047
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000047
</wsa:RelatesTo>
</s:Header>
<s:Body/>
</s:Envelope>
This specification defines one Web
service operation (Delete) for deleting a resource in its entirety.
Extension specifications MAY define
extensions to the Delete request, enabled by OPTIONAL header values, which
specifically control preconditions for the Delete to succeed and which may
control the nature or format of the response. Since the response may not be
sent to the original sender, extension specifications should consider adding a
corresponding SOAP header value in the response to signal to the receiver that
the extension is being used.
The Delete request message MUST be of
the following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Delete
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:Delete ...>
xs:any *
</wst:Delete>
</s:Body>
</s:Envelope>
The following describes additional,
normative constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the
value http://www.w3.org/2009/02/ws-tra/Delete. If a SOAP Action URI is also present
in the underlying transport, its value MUST convey the same value.
A Delete request MUST be targeted at
the resource to be deleted as described in 2 Terminology and Notation
of this specification.
There are no body blocks defined for a Delete Request.
Implementations may respond with a fault message using
the standard fault codes defined in WS-Addressing (e.g., wsa:ActionNotSupported). Other components of the outline above are not further
constrained by this specification.
A successful Delete operation invalidates the current
representation associated with the targeted resource.
If the resource accepts a Delete request, it MUST reply
with a response of the following form:
<s:Envelope
...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/DeleteResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:DeleteResponse>
xs:any ?
</wst:DeleteResponse>
</s:Body>
</s:Envelope>
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/DeleteResponse. If a SOAP Action URI is also present in the underlying
transport, its value MUST convey the same value.
By default, there are no s:Body blocks defined for a
Delete response. Specifications which define extensions for use in the original
Delete request which control the format of the response MUST allow processing
the Delete message without such extensions.
Other components of the outline above are not further
constrained by this specification.
The following shows a sample SOAP envelope containing a
Delete request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/pushport</wsa:To>
<xxx:CustomerID>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Delete
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000049
</wsa:MessageID>
</s:Header>
<s:Body/>
</s:Envelope>
The following shows the corresponding response message
indicating success:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/DeleteResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000049
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000049
</wsa:RelatesTo>
</s:Header>
<s:Body/>
</s:Envelope>
This specification
defines one Web service operation (Create) for creating a resource and
providing its initial representation. In some cases, the initial representation
MAY constitute the representation of a logical constructor for the resource and
may thus differ structurally from the representation returned by Get or the one
required by Put. This is because the parameterization requirement for creating
a resource is often distinct from the steady-state representation of the
resource. Implementations should provide metadata which describes the use of
the representation and how it relates to the resource which is created, but
such mechanisms are beyond the scope of this specification. 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 service-determined endpoint reference that is returned in the
response message.
The Create request
message MUST be of the following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Create
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:Create ExpressionDialect="xs:anyURI"?
...>
<wst:Metadata> resource metadata </wst:Metadata> ?[I5]
<wst:Fragment>
<wst:Expression> xs:any </wst:Expression>[I6]
<wst:Value ...> xs:any </wst:Value>
</wst:Fragment> *
| xs:any *
</wst:Create>
</s:Body>
</s:Envelope>
The following
describes additional, normative constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required
element MUST contain the value http://www.w3.org/2009/02/ws-tra/Create. If a SOAP Action
URI is also present in the underlying transport, its value MUST convey the same
value.
/s:Envelope/s:Body/wst:Create@ExpressionDialect
This OPTIONAL
attribute, when present, indicates that a fragment creation is being
performed and also 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 /s:Envelope/s:Body/wst:Create/wst:Fragment element. << add
text to say that a fault MUST be generated if it doesn't support fragments at
all>>
/s:Envelope/s:Body/wst:Create/wst:Metadata
When present
this optional element MUST contain at least one wsmex:MetadataSection. This is
resource metadata to be created and initialized during the creation of the
resource.
A resource
factory MUST generate an InvalidMetadataFault if the Create request message
contains a wsmex:Dialect that is not supported or if the resource metadata
contains values that are not supported for the resource.
This element
MAY contain a wsmex:MetadataSection with a wsmex:Dialect of
http://www.w3.org/2009/02/ws-tra allowing the requestor to specify desired metadata
as defined in this specification (such as lifecycle metadata).
/s:Envelope/s:Body/wst:Create/wst:Fragment
This optional
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 wst:MultipartLimitExceededFault.
/s:Envelope/s:Body/wst:Create/wst:Fragment/wst:Expression
This 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. The value of this element MUST
conform to the dialect specified in the /s:Envelope/s:Body/wst:Create@ExpressionDialect
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".
/s:Envelope/s:Body/wst:Create/wst:Fragment/wst: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.
/s:Envelope/s:Body/wst:Create/xs:anychild::*[position()=1]
The first
child element of the s:Body element MUST NOT be omitted. The
contents of this element are service-specific, and MAY contain the literal
initial resource representation, a representation of the constructor for the
resource, or other instructions for creating the resource. All other children that do
not have the wst namespace SHOULD be ignored by the service. This element
MUST NOT appear if a wst:Fragment element is present.
Extensions
specifications MAY also define extensions to the original Create request,
enabled by OPTIONAL SOAP headers, which constrain the nature of the response,
as discussed in remarks on the CreateResponse below.Similarly, they may require
headers which control the interpretation of the s:Body as part of the resource
creation process.
Such
specifications MUST also allow processing the Create message without such
extensions.
A Create request MUST be targeted at a resource factory capable of creating
the desired new resource. This factory is distinct from the resource being
created (which by definition does not exist prior to the successful processing
of the Create request message).
In addition to the
standard fault codes defined in WS-Addressing, implementations MAY use the
fault code wfx:InvalidRepresentation if the presented representation is invalid
for the target resource. See Section 5.
Other components
of the outline above are not further constrained by this specification.
If the resource
factory accepts a Create request, it MUST reply with a response of the
following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/CreateResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:CreateResponse
...>
<wstxf:ResourceCreated>endpoint-reference</wstxf:ResourceCreated>
xs:any ?
</wst:CreateResponse>
</s:Body>
</s:Envelope>
/s:Envelope/s:Header/wsa:Action
This required
element MUST contain the value http://www.w3.org/2009/02/ws-tra/CreateResponse.
If a SOAP Action URI is also present in the underlying transport, its value
MUST convey the same value.
/s:Envelope/s:Body/wst:CreateResponse/wstxf:ResourceCreated
This required
element MUST contain a resource reference for the newly created resource. This
resource reference, represented as an endpoint reference as defined in
WS-Addressing, MUST identify the resource for future Get, Put, and Delete
operations.
/s:Envelope/s:Body/wst:CreateResponse/child::*[position()=2]
If the
request Body contained either a /s:Envelope/s:Body/wst:Create/wsmex:Metadata or
a /s:Envelope/s:Body/wst:Create/wst:Fragment element, then the new representation
MUST be omitted in the response. Otherwise, By default, a
service MUST return the current representation of the new resource as the
second child of the s:Body element if the created representation logically
differs from the representation sent in the Create request message. That is,
the initial representation is returned if one or more values present in Create
message was specifically overridden with a different value during resource
creation. If default values are used to complete a resource creation which were
not present in the Create message, then this does not constitute a logical
difference. The presence of additional child elements which contain other
information pertaining to the result of the Create operation is service-specific.
As an optimization
and as a service to the requestor, the s:Body element of the response message
SHOULD be empty, other than the ResourceCreated element, if the created
representation does not logically differ from the representation sent in the
Create request message; that is, if the service accepted the new representation
or creation instructions verbatim. Such a response indicates that the request
was completely successful (assuming no intervening mutating operations are
performed). A service MAY return the current representation of the resource as
the initial child of the s:Body element even in this case, however.
Extension
specifications MAY define extensions to the original Create request, enabled by
OPTIONAL header values, which specifically control the presence, absence, or
format of the initial representation or other child elements in the
CreateResponse. These headers MAY override the default behavior if they are
marked with s:mustUnderstand="true". In the
absence of such OPTIONAL headers, the behavior MUST be as described in the
previous paragraphs. Since the response may not be sent to the original sender,
extension specifications should consider adding a corresponding SOAP header
value in the response to signal to the receiver that the extension is being
used.
Other components of the outline above are not further constrained by this
specification.
The following
shows a sample SOAP envelope containing a Create request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/pushport/CustomerSpace</wsa:To>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Create
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000048
</wsa:MessageID>
</s:Header>
<s:Body>
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>123 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
</s:Body>
</s:Envelope>
The following
shows the corresponding response message indicating success:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wxf="http://www.w3.org/2009/02/ws-tra"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/CreateResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000048
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000048
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wxf:ResourceCreated>
<wsa:Address>http://www.example.org/pushport</wsa:Address>
<wsa:ReferenceParameters>
<xxx:CustomerID>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
</wsa:ReferenceParameters>
</wxf:ResourceCreated>
</s:Body>
</s:Envelope>
All fault messages defined in this
specification MUST be sent according to the rules and usage described in WS-Addressing 1.0
SOAP Binding Section 6 for encoding SOAP 1.1 and SOAP 1.2 faults. The [action]
property below SHOULD be used for faults defined in this specification:
This fault
is returned when an incorrect representation is sent in a wxf:Put or wxf:Create
message.
|
s:Sender |
|
|
[Subcode] |
wxf:InvalidRepresentation |
|
[Reason] |
The supplied representation is
invalid |
|
[Detail] |
none |
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.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:ConcurrencyFault |
|
[Reason] |
Could not access the resource due to concurrency
and/or locking conditions |
|
[Detail] |
|
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.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:UnsupportedDialectFault |
|
[Reason] |
The requested dialect is not supported |
|
[Detail] |
<wst:Dialect>xs:anyURI</wst:Dialect>
* |
This fault is sent by a resource if a
<wst: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.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:InvalidExpressionFault |
|
[Reason] |
The specified Expression is not valid |
|
[Detail] |
<wst:InvalidExpressionSyntax> <wst:Expression>xs:any</wst:Expression> +</wst:InvalidExpressionSyntax>|<wst:InvalidExpressionValue> <wst:Expression>xs:any</wst:Expression> +</wst:InvalidExpressionValue> |
This fault is generated by a resource if it is
unable to process a valid Get message.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Receiver |
|
[Subcode] |
wst:GetFault |
|
[Reason] |
Unable to process Get message |
|
[Detail] |
|
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 wst:Fragment
element in the Put message that caused this fault to be generated.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:ResourceValidityFault |
|
[Reason] |
The requested resource modification is not valid.
|
|
[Detail] |
<wst:Fragment>fragment</wst:Fragmant>
? |
This fault is generated by a resource if a
"Put" message specifies the "http://www.w3.org/2009/02/ws-tra/Insert"
mode and identifies a non-repeated fragment element (maxOccurrs = 1) that
already exists. The fault detail MAY include the wst:Fragment
that failed to be processed.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:FragmentAlreadyExistsFault |
|
[Reason] |
The fragment already exists |
|
[Detail] |
<wst:Fragment>fragment</wst:Fragment>
? |
This fault is generated by a resource if it is
unable to process a valid Put message. The fault detail MAY include the
wst:Fragment that failed to be processed.
The fault detail SHOULD include a wst: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.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Receiver |
|
[Subcode] |
wst:PutFault |
|
[Reason] |
Unable to process Put message |
|
[Detail] |
<wst:Fragment>fragment</wst:Fragment> ?<wst:SideEffects>xs:boolean</wst:SideEffects> ? |
This fault is generated by a resource if a
"Put" message specifies a mode that is not supported by the resource.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:PutModeUnsupportedFault |
|
[Reason] |
The Put mode is not supported |
|
[Detail] |
The unsupported Mode URI |
This fault is generated by a resource if it is
unable to process a valid Create message. The fault detail MAY include the wst:Fragment
that failed to be processed.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Receiver |
|
[Subcode] |
wstt:CreateFault
|
|
[Reason] |
Unable to process Create message |
|
[Detail] |
<wstt:Fragment>fragment</wst:Fragment> ? |
This fault is generated by a resource factory if a
"Create" message contains a wsmex:Dialect that is not supported or if
the resource metadata contains values that are not supported for the resource.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:InvalidMetadataFault |
|
[Reason] |
Resource metadata values not supported by
resource |
|
[Detail] |
|
This fault is generated by a resource if a request
message exceeds the limit of wst:Expression
or wst:Fragment elements supported
for the dialect. The fault detail MUST contain the maximum number of wst:Expression
or wst:Fragment elements supported
for the dialect.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:MultipartLimitExceededFault |
|
[Reason] |
Access to multiple fragments exceeded the
supported number of fragments in a single message |
|
[Detail] |
<wst:MultipartLimit>xs:positiveInteger</wst:MultipartLimit>
|
This fault is generated by a resource if a Put
request specifying a Mode "http://www.w3.org/2009/02/ws-tra/Remove"
contains a wst:Value element or if a Put
request specifying a Mode "http://www.w3.org/2009/02/ws-tra/Insert"
or "http://www.w3.org/2009/02/ws-tra/Modify"
does not contain a wst:Value element.
|
http://www.w3.org/2009/02/ws-tra/fault |
|
|
[Code] |
s12:Sender |
|
[Subcode] |
wst:InvalidRemoveSyntaxFault |
|
[Reason] |
Invalid syntax used for Put request |
|
[Detail] |
|
It is
strongly recommended that the communication between services be secured using
the mechanisms described in [WS-Security].
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, WS-Security timestamp, and any
header blocks resulting from a <wsa:ReferenceParameters> in references need to be signed along with the body in
order to "bind" them together and prevent certain types of attacks.
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 WS-Trust and WS-SecureConversation. It is further
recommended that if shared secrets are used, message-specific derived keys also
be used to protect the secret from crypto attacks.
The access control semantics of resource references is
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.
It is recommended that the security considerations of
WS-Security also be considered.
While a comprehensive listing of attacks is not feasible,
the following list summarizes common classes of attacks that apply to this
protocol and identifies the mechanism(s) to prevent/mitigate the attacks.
·
Replay - Messages, or portions of messages, can be replayed in
an attempt to gain access or disrupt services. Freshness checks such as
timestamps, digests, and sequences can be used to detect duplicate messages.
·
Invalid tokens - There are a number of token attacks including
certificate authorities, false signatures, and PKI attacks. Care should be
taken to ensure each token is valid (usage window, digest, signing authority,
revocation, ...), and that the appropriate delegation policies are in
compliance.
·
Man-in-the-middle - The message exchanges in this specification could be
subject to man-in-the-middle attacks so care should be taken to reduce
possibilities here such as establishing a secure channel and verifying that the
security tokens user represent identities authorized to speak for, or on behalf
of, the desired resource reference.
·
Message alteration - Alteration is prevented by including signatures of the
message information using WS-Security. Care should be taken to review message
part references to ensure they haven't been forged (e.g. ID duplication).
·
Message disclosure - Confidentiality is preserved by encrypting sensitive
data using WS-Security.
·
Key integrity - Key integrity is maintained by using the strongest
algorithms possible (by comparing secured policies - see [WS-Policy]
and [WS-SecurityPolicy] and by using derived keys ([WS-SecureConversation]).
·
Authentication - Authentication is established using the mechanisms
described in WS-Security and WS-Trust. Each message is authenticated using the
mechanisms described in WS-Security.
·
Accountability - Accountability is a function of the type of and string
of the key and algorithms being used. In many cases, a strong symmetric key
provides sufficient accountability. However, in some environments, strong PKI
signatures are required.
·
Availability - All reliable messaging services are subject to a
variety of availability attacks. Replay detection is a common attack and it is
recommended that this be addressed by the mechanisms described in WS-Security.
Other attacks, such as network-level denial of service attacks are harder to
avoid and are outside the scope of this specification. That said, care should
be taken to ensure that minimal state is saved prior to any authenticating
sequences.
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), Sreedhara Narayanaswamy (CA),
Sumeet Vij (Software AG), Vikas Varma (Software AG), Wu Chou (Avaya
Communications), Yves Lafon (W3C)
Key words for use in RFCs to Indicate Requirement
Levels , S. Bradner, Harvard University, March 1997. (See
http://www.ietf.org/rfc/rfc2119.txt.)
Simple Object Access Protocol (SOAP) 1.1 ,
D. Box, et al, May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.)
SOAP Version 1.2 Part 1: Messaging Framework ,
M. Gudgin, et al, June 2003. (See http://www.w3.org/TR/soap12-part1/.)
D Box et al, W3C Submission, "Web Services
Addressing (WS-Addressing)" , May 2006. (See
http://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/.)
W3C Recommendation, "Web Services Addressing 1.0
(WS-Addressing)" , May 2006. (See
http://www.w3.org/2005/08/addressing/.)
S. Bajaj, et al, "Web Services Policy Framework
(WS-Policy)," , September 2004. (See
http://schemas.xmlsoap.org/ws/2004/09/policy.)
href="http://schemas.xmlsoap.org/ws/2005/02/sc/">
Web Services Secure Conversation Language
(WS-SecureConversation) , S. Anderson, et al, February 2005.
Web Services Security: SOAP Message Security 1.0 ,
OASIS standard. (See
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.)
G. Della-Libera, et al, "Web Services Security
Policy Language (WS-SecurityPolicy), Version 1.1" , July
2005. (See http://schemas.xmlsoap.org/ws/2005/07/securitypolicy.)
Web Services Description Language (WSDL) 1.1 ,
E. Christensen, et al, March 2001. (See
http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)
J.
Cowan, et al, "XML Information Set" , February 2004. (See
http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.)
XML
Schema Part 1: Structures , H. Thompson, et al, October
2004. (See
http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.)
XML
Schema Part 2: Datatypes , James Clark, et al,
November 1999. (See
http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.)
WS_I BP
…