WS-Addressing SOAP Adjunctions: Robust Request MEP and SOAP One-way plus optional additional connection Binding

Editor:
David Orchard, BEA Systems

Abstract

SOAP Version 1.2 provides a request-response MEP and a request-response bindings. This provides a one way + optional Fault MEP and a binding to HTTP request/response that supports SOAP request-response and the Robust-request way MEP over a single http connection or 2 http connections. This specification depends on SOAP Version 1.2 Part 2: Adjuntcts [SOAP-PART2].

Status of this Document

This document is an editors' copy that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

Table of Contents

1 Introduction
1.1 Notational Conventions
2 SOAP Robust Request Message Exchange Pattern
2.1 SOAP Feature Name
2.2 Description
2.3 State Machine Description
3 One-way + optional additional connection SOAP HTTP binding
3.1 Introduction
3.1.1 Description
3.1.2 Optionality
3.1.3 Use of HTTP
3.1.4 Interoperability with non-SOAP HTTP Implementations
3.1.5 HTTP Media-Type
3.2 Binding Name
3.3 Supported Message Exchange Patterns
3.4 Supported Features
3.5 Supported Properties
3.6 MEP Operation
3.6.1 Behavior of Requesting SOAP Node
3.6.1.1 Init
3.6.1.2 Requesting
3.6.1.3 Sending+Receiving
3.6.1.4 Success and Fail
3.6.2 Behavior of Responding SOAP Node
3.6.2.1 Init
3.6.2.2 Receiving
3.6.2.3 Receiving+Sending
3.6.2.4 Success and Fail
3.7 Security Considerations
4 References
4.1 Normative References
4.2 Informative References

Appendix

A Change Log (Non-Normative)


1 Introduction

SOAP Version 1.2 (SOAP) provides a request-response MEP and a request-response Bindins. This specification provides a 1 way + fault MEP and a 1 or 2 connection binding.

1.1 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 a number of namespace prefixes throughout; they are listed in ???. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).

Prefixes and Namespaces used in this specification
PrefixNamespaceNotes
env"http://www.w3.org/2003/05/soap-envelope"Defined by SOAP 1.2 Part 1 [SOAP Part 1].
xs"http://www.w3.org/2001/XMLSchema"Defined in the W3C XML Schema specification [XML Schema Part 1], [XML Schema Part 2].

Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs (see RFC 2396 [RFC 2396]).

This specification uses the Extended Backus-Naur Form (EBNF) as described in XML 1.0 [XML 1.0].

With the exception of examples and sections explicitly marked as "Non-Normative", all parts of this specification are normative.

2 SOAP Robust Request Message Exchange Pattern

This section defines the message exchange pattern (MEP) called "Robust Request". The description is an abstract presentation of the operation of this MEP. It is not intended to describe a real implementation or to suggest how a real implementation should be structured.

3 One-way + optional additional connection SOAP HTTP binding

3.1 Introduction

The One-way + Optional Additional Connection SOAP HTTP binding provides a binding of SOAP to HTTP. The binding conforms to the SOAP Protocol Binding Framework (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP Protocol Binding Framework) and supports the message exchange patterns and features described in ???.

3.1.1 Description

This binding is intended for one-way with optional fault message exchanges, request response exchanges using two different HTTP Connections (async two-way HTTP), as the request binding in request response exchange using HTTP for the request and a different protocol for the response, and as the response binding in a request response exchange using a non HTTP protocol for the request and HTTP for the response.

The algorithm is:

If (MEP==Robust in-only) then
   Message is transmitted using HTTP
   Optional Fault is transmitted
If (MEP==Request-Response) then
    Request Message is transmitted using HTTP
    If No response address specified then
       Set Fault to no response address, exit
    MEP is set to Robust in-only
    If response binding is empty then
       set response binding to HTTP One-way + Optional Additional Connection binding
    Response Message is transmitted by specified binding
There are a few design points worth noting. Firstly, the state machine for the receiving node when responding remains as sending+receiving. The receiving node could commence the use of the second binding at any time after it has started receiving the request message. This parallelism is difficult to model in single threaded state machines. It is approximated by the use of the second binding for the response, with no constraints placed upon timing of the start or finish of the 2nd binding. Secondly, this binding uses a second binding with Robust in-only mep for the response part of the request-response mep. The SOAP binding framework does not specify any scoping rules for such a nesting of bindings, and particularly for the properties or features used. However, it is not precluded so this binding assumes that nesting is possible. Thirdly, this binding adds properties that are not specified in the binding framework or in any of the used meps. The binding framework does not appear to preclude extending the binding framework in this way.

3.1.3 Use of HTTP

The WS-Addressing One-way + Optional Additional Connection SOAP HTTP binding defines a base URI according to the rules in HTTP/1.1 [RFC 2616]. I.e. the base URI is the HTTP Request-URI or the value of the HTTP Content-Location header field.

This binding of SOAP to HTTP is intended to make appropriate use of HTTP as an application protocol. For example, successful responses are sent with status code 200, and failures are indicated as 4XX or 5XX. This binding is not intended to fully exploit the features of HTTP, but rather to use HTTP specifically for the purpose of communicating with other SOAP nodes implementing the same binding. Therefore, this HTTP binding for SOAP does not specify the use and/or meaning of all possible HTTP methods, header fields and status responses. It specifies only those which are pertinent to the ??? or the ???, or which are likely to be introduced by HTTP mechanisms (such as proxies) acting between the SOAP nodes.

Certain optional features provided by this binding depend on capabilities provided by HTTP/1.1, for example content negotiation. Implementations SHOULD thus use HTTP/1.1 [RFC 2616] (or later compatible versions that share the same major version number). Implementations MAY also be deployed using HTTP/1.0, although in this case certain optional binding features may not be provided.

Note:

WS-Addressing One-way + Optional Additional Connection SOAP HTTP binding implementations need to account for the fact that HTTP/1.0 intermediaries (which may or may not also be SOAP intermediaries) may alter the representation of SOAP messages, even in situations where both the initial SOAP sender and ultimate SOAP receiver use HTTP/1.1.

3.1.4 Interoperability with non-SOAP HTTP Implementations

Particularly when used with the ???, the HTTP messages produced by this binding are likely to be indistinguishable from those produced by non-SOAP implementations performing similar operations. Accordingly, some degree of interoperation can be made possible between SOAP nodes and other HTTP implementations when using this binding. For example, a conventional Web server (i.e. one not written specifically to conform to this specification) might be used to respond to SOAP-initiated HTTP GET's with representations of Content-Type"application/soap+xml". Such interoperation is not a normative feature of this specification.

Even though HTTP often is used on the well-known TCP port 80, the use of HTTP is not limited to that port. As a result, it is possible to have a dedicated HTTP server for handling SOAP processing on a distinct TCP port. Alternatively, it is possible to use a separate virtual host for dealing with SOAP processing. Such configuration, however, is a matter of convenience and is not a requirement of this specification (see SOAP 1.2 Part 1 [SOAP Part 1]Binding to Application-Specific Protocols).

3.1.5 HTTP Media-Type

Conforming implementations of this binding:

  1. MUST be capable of sending and receiving messages serialized using media type "application/soap+xml" whose proper use and parameters are described in ???.

  2. MAY send requests and responses using other media types providing that such media types provide for at least the transfer of SOAP XML Infoset.

  3. MAY, when sending requests, provide an HTTP Accept header field. This header field:

    • SHOULD indicate an ability to accept at minimum "application/soap+xml".

    • MAY additionally indicate willingness to accept other media types that satisfy 2 above.

3.2 Binding Name

This binding is identified by the URI (see SOAP 1.2 Part 1 [SOAP Part 1]SOAP Protocol Binding Framework):

  • "http://www.w3.org/2005/6/ws-addr/bindings/onewayHTTPandoptionaladditionalconnection/"

3.6 MEP Operation

For binding instances conforming to this specification:

The remainder of this section describes the MEP state machine and its relation to the HTTP protocol. In the state tables below, the states are defined as values of the property http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State (see ??? and ???), and are of type xs:anyURI. For brevity, relative URIs are used, the base URI being the value of http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role.

The message exchange pattern in use is not indicated in this binding. This information SHOULD be conveyed by a mechanism outside of this binding.

3.6.1 Behavior of Requesting SOAP Node

The overall flow of the behavior of a requesting SOAP node follows a state machine description consistent with either ??? or ??? (differences are indicated as necessary.) This binding supports streaming and, as a result, requesting SOAP nodes MUST avoid deadlock by accepting and if necessary processing binding-specific response information while the SOAP request is being transmitted (see 2.3 State Machine Description). The following subsections describe each state in detail.

3.6.1.1 Init

In the "Init" state, a HTTP request is formulated according to ??? and transmission of the request is initiated.

HTTP Request Fields
FieldValue
HTTP MethodAccording to the http://www.w3.org/2003/05/soap/features/web-method/Method property. POST is the only value supported by this binding.
Request URIThe value of the URI carried in the http://www.w3.org/2003/05/soap/mep/ImmediateDestination property of the message exchange context.

Content-Type header field

The media type of the request entity body (if present) otherwise, omitted (see ??? for a description of permissible media types). If the SOAP envelope infoset in the http://www.w3.org/2003/05/soap/mep/OutboundMessage property is null, then the Content-Type header field MAY be omitted.

action parameter

According to the value of the http://www.w3.org/2003/05/soap/features/action/Action property.

Accept header field (optional)

List of media types that are acceptable in response to the request message.

Additional header fields

Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange. For example, a Content-Encoding header field (see HTTP [RFC 2616], section 14.11) may be used to express an optional compression feature.

HTTP entity body

SOAP message serialized according to the rules for carrying SOAP messages in the media type given by the Content-Type header field. Rules for carrying SOAP messages in media type "application/soap+xml" are given in ???. If the SOAP envelope infoset in the http://www.w3.org/2003/05/soap/mep/OutboundMessage property is null, the entity body is omitted

3.6.1.2 Requesting

In the "Requesting" state, sending of the request continues while waiting for the start of the optional fault response message. ??? details the transitions that take place when a requesting SOAP node receives an HTTP status line and response header fields. For some status codes there is a choice of possible next state. In cases where "Fail" is one of the choices, the next state is "Fail".

HTTP status code dependent transitions
Status CodeReason phraseSignificance/ActionNextState
2xxSuccessful
200OK "Sending+Receiving" or "Success"
3xxRedirection

The requested resource has moved and the HTTP request SHOULD be retried using the URI carried in the associated Location header field as the new value for the http://www.w3.org/2003/05/soap/mep/ImmediateDestination property.

"Init"
4xxClient Error
400Bad Request

Indicates a problem with the received HTTP request message.

"Sending+Receiving" or "Fail"

401Unauthorized

Indicates that the HTTP request requires authorization.

If the simple authentication feature is unavailable or the operation of simple authentication ultimately fails, then the message exchange is regarded as having completed unsuccessfully.

"Requesting" or "Fail"
405Method not allowed

Indicates that the peer HTTP server does not support the requested HTTP method at the given request URI. The message exchange is regarded as having completed unsuccessfully.

"Fail"
415Unsupported Media Type

Indicates that the peer HTTP server does not support the Content-type used to encode the request message. The message exchange is regarded as having completed unsuccessfully.

"Fail"
5xxServer Error
500Internal Server Error

Indicates a server problem or a problem with the received request

"Sending+Receiving" or "Fail"

??? refers to some but not all of the existing HTTP/1.1 [RFC 2616] status codes. In addition to these status codes, HTTP provides an open-ended mechanism for supporting status codes defined by HTTP extensions (see RFC 2817 [RFC 2817] for a registration mechanism for new status codes). HTTP status codes are divided into status code classes as described in HTTP [RFC 2616], section 6.1.1. The WS-Addressing One-way + Optional Additional Connection SOAP HTTP binding follows the rules of any HTTP application which means that an implementation of the WS-Addressing One-way + Optional Additional Connection SOAP HTTP binding must understand the class of any status code, as indicated by the first digit, and treat any unrecognized response as being equivalent to the x00 status code of that class, with the exception that an unrecognized response must not be cached.

Note:

There may be elements in the HTTP infrastructure configured to modify HTTP response entity bodies for 4xx and 5xx status code responses. For example, some HTTP origin servers have such a feature as a configuration option. This behavior may interfere with the use of 4xx and 5xx status code responses carrying SOAP fault messages in HTTP and it is recommended that such behavior is disabled for resources accepting SOAP/HTTP requests. If the rewriting behavior cannot be disabled, SOAP/HTTP cannot be used in such configurations.

3.6.1.3 Sending+Receiving

In the "Sending+Receiving" state (??? only), the transmission of the request message and receiving of the optional fault message is completed. This response message is assumed to contain an empty body or a fault. This response message may contain a SOAP envelope serialized according to the rules for carrying SOAP messages in the media type given in the Content-Type header field. Such usage is considered non-normative, and accordingly is not modelled in the state machine.

The response MAY be of content type other than "application/soap+xml". Such usage is considered non-normative, and accordingly is not modeled in the state machine. Interpretation of such responses is at the discretion of the receiver.

3.6.2 Behavior of Responding SOAP Node

The overall flow of the behavior of a responding SOAP node follows a state machine description consistent with either ??? or ??? (differences are indicated as necessary). The following subsections describe each state in detail.

3.6.2.1 Init

In the "Init" state, the binding waits for the start of an inbound request message. ??? describes the errors that a responding SOAP node might generate while in the "Init" state. In this state no SOAP message has been received, therefore the SOAP node cannot generate a SOAP fault.

Errors generated in the Init state
Problem with MessageHTTP Status CodeHTTP Reason Phrase (informative)
Malformed Request Message400Bad request
HTTP Method is not POST405Method Not Allowed
Unsupported message encapsulation method415Unsupported Media
3.6.2.2 Receiving

In the "Receiving" state, the binding receives the request and any associated message and waits for the start of a response message to be available. ??? describes the HTTP response header fields generated by the responding SOAP node. ??? describes the HTTP status codes that can be generated by the responding SOAP node.

HTTP Response Headers Fields
FieldValue
Status line

200, or set according to ??? if a SOAP fault was generated.

Content-Type header field

The media type of the response body, see ??? for a description of permissible media types.

Additional header fields

Generated in accordance with the rules for the binding specific expression of any optional features in use for this message exchange. For example, a Content-Encoding header field (see HTTP [RFC 2616], section 14.11) may be used to express an optional compression feature.

HTTP Entity Body

It MAY contain a SOAP Fault message serialized according to the rules for carrying SOAP messages in the media type given by the Content-Type header field. Rules for carrying SOAP messages in "application/soap+xml" are given in ???.

SOAP Fault to HTTP Status Mapping
SOAP FaultHTTP Status CodeHTTP Reason Phrase (informative)
env:VersionMismatch500Internal server error
env:MustUnderstand500Internal server error
env:Sender400Bad request
env:Receiver500Internal server error
env:DataEncodingUnknown500Internal server error
3.6.2.3 Receiving+Sending

In the "Receiving+Sending" state the binding completes receiving of the request message, transmission of the optional Fault response message and transmission of any response message. If the mep selected is request-response ??? then the response message is sent. The response binding is specified by http://www.w3.org/2005/6/ws-addr/binding/responsebinding property. If the property is empty or contains no value, then this binding is selected. The response location is specified by the http://www.w3.org/2005/6/ws-addr/binding/responseURI property. In using the response binding, the one-way MEP is specified for sending the response. It is an error for the request-response MEP to be selected and the http://www.w3.org/2005/6/ws-addr/binding/responseURI to be unset, but there is no constraint specified for when the property must be set in the state machine. It is possible that the property will be set after the responding node has finished sending the HTTP response.

3.7 Security Considerations

The One-way + Optional Additional Connection SOAP HTTP Binding (see ???) can be considered as an extension of the HTTP application protocol. As such, all of the security considerations identified and described in section 15 of the HTTP specification [RFC 2616] apply to the WS-Addressing One-way + Optional Additional Connection SOAP HTTP binding in addition to those described in SOAP 1.2 Part 1 [SOAP Part 1]Security Considerations. Implementors of the WS-Addressing One-way + Optional Additional Connection SOAP HTTP binding should carefully review this material.

4 References

4.1 Normative References

SOAP Part 1
W3C Proposed Recommendation "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, (See .)
RFC 2616
IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. (See http://www.ietf.org/rfc/rfc2616.txt.)
RFC 2119
IETF "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
XML Schema Part 1
W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)
XML Schema Part 2
W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)
RFC 2396
IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. (See http://www.ietf.org/rfc/rfc2396.txt.)
Namespaces in XML
W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)
XML 1.0
W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006.)
XML InfoSet
W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/2001/REC-xml-infoset-20011024/.)
RFC 3023
IETF "RFC 3023: XML Media Types", M. Murata, S. St. Laurent, D. Kohn, July 1998. (See http://www.ietf.org/rfc/rfc3023.txt.)
SOAP MediaType
IETF Internet Draft "The 'application/soap+xml' media type", M. Baker, M. Nottingham, "draft-baker-soap-media-reg-02.txt" April 14, 2003. (Work in progress). (See http://www.ietf.org/internet-drafts/draft-baker-soap-media-reg-02.txt.)

A Change Log (Non-Normative)

Changes since candidate recommendation.
WhoWhenWhat
DBO20041208Initial Revision
--------------------------------------------------------------------------------

Join CEO Alfred Chuang and CTO Mark Carges on June 15 for a unique online 
event, giving you the first look at a new category of enterprise software 
built specifically for Service-Oriented Architecture (SOA).

Register Now.  It's Free!

http://www.bea.com/events/june15