SOAP Binding to Advanced Message Queuing Protocol …



SOAP Binding to Advanced Message Queuing Protocol (AMQP) Transport Version 1.0

Working Draft 01

09 September 2013

Technical Committee:

OASIS Advanced Message Queuing Protocol (AMQP) Bindings and Mappings (AMQP-BINDMAP) TC

Chair:

Steve Huston (shuston@), Individual

Editor:

Steve Huston (shuston@), Individual

Paul Knight (paul.the.knight@), Individual

other?

Additional artifacts:

This prose specification is one component of a Work Product that also includes:

• XML schemas: (list file names or directory name)

• Other parts (list titles and/or file names)

Related work:

This specification is related to:

• OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 0: Overview. 29 October 2012. OASIS Standard. .

Declared XML namespaces:

• (is this needed?)

Abstract:

This document describes how SOAP binds to the Advanced Message Queuing Protocol (AMQP). It describes bindings for SOAP 1.2 using the SOAP 1.2 Protocol Binding Framework, and also describes how to use WSDL documents to indicate and control the use of this binding.

Status:

This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.

Initial URI pattern:



(Managed by OASIS TC Administration; please don’t modify.)

Copyright © OASIS Open 2013. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1 Introduction 5

1.1 Background 5

1.2 Out of scope 5

1.3 Context 5

1.4 Terminology 5

1.5 Normative references 6

1.6 Non-normative references 7

1.7 XML namespaces 7

1.8 Conformance-related clauses 8

2 The SOAP/AMQP Underlying Protocol Binding 9

2.1 Introduction 9

2.2 Properties Affecting Binding 9

2.2.1 Connection to a destination 9

2.2.2 AMQP Message Header properties 11

2.2.2.1 Setting AMQP Message Header properties 12

2.2.3 AMQP Message properties 12

2.2.3.1 Setting AMQP Message properties 14

2.2.4 Binding of Properties to URI 14

2.2.5 Other Properties 15

2.3 Authentication for SOAP/AMQP 15

2.4 The AMQP Message Body 16

2.5 Supported Message Exchange Patterns 16

2.5.1 Support for Topic destinations 16

2.6 Request-Response Message Exchange Pattern 16

2.6.1 Behavior of Requesting SOAP Node 17

2.6.1.1 Init 17

2.6.1.2 Requesting 18

2.6.1.3 Sending + Receiving 18

2.6.1.4 Success and Fail 19

2.6.2 Behavior of Responding SOAP Node 19

2.6.2.1 Init 19

2.6.2.2 Receiving 19

2.6.2.3 Receiving + Sending 19

2.6.2.4 Success and Fail 20

2.7 One-way Message Exchange Pattern 20

2.7.1 Behavior of Sending SOAP Node 21

2.7.2 Behavior of Receiving SOAP Node 22

2.8 Faults 22

3 WSDL Usage 24

3.1 Overview 24

3.2 WSDL 1.1 Extensions Overview 24

3.3 WSDL 1.1 Extensions Detail 24

3.3.1 Example 24

3.3.2 WSDL 1.1 Transport Identification 26

3.3.3 WSDL 1.1 SOAP Action 26

3.3.4 Specifying Properties In WSDL 1.1 26

3.3.5 Specifying Properties 27

3.4 Properties 27

4 Conformance 28

Appendix A. Acknowledgments 29

Appendix B. Revision History 31

1. Introduction

[All text is normative unless otherwise labeled]

1 Background

This specification describes the transport of SOAP messages over the Advanced Message Queuing Protocol (AMQP). The main purpose is to ensure interoperability between the implementations of different Web services vendors. This will also enable customers to implement their own Web services for part of their infrastructure, and to have this interoperate with vendor provided Web services. The main audience will be implementers of Web services stacks; in particular people who wish to extend a Web services stack with an implementation of SOAP/AMQP. This will enable them to write a SOAP/AMQP implementation that will interoperate with other SOAP/AMQP implementations, and that will not be dependent on any specific AMQP implementation.

An example user is an organization with separate departments that use Web services infrastructure from two different vendors, VendorA and VendorB. The organization has a need for reliable Web services interaction between the departments. Where both these vendors provide support for SOAP/AMQP according to this standard, it ought be possible for a client using VendorA to interoperate with a service using VendorB.

This specification will also be of interest to providers of Web services intermediary services such as routing gateways; or SOAP/HTTP to SOAP/AMQP gateways. It does not provide any details of how such gateways might be designed and configured, but adherence to the standard will help the gateway ensure proper interoperation with SOAP/AMQP clients and services.

2 Out of scope

It is important to stress what this specification does NOT provide.

• It does NOT provide any mechanism for interoperation between two different AMQP providers. In the example above, VendorA and VendorB are different providers of a Web services infrastructure, but the organization still needs to use a single implementation of AMQP at both client and service side.

• It does NOT define any (wire) format for SOAP/AMQP messages.

• It does NOT define how the Web services themselves will be presented to the application programmer. For example, it does not describe how the programmer will characterize a one-way message.

3 Context

This document specifies how SOAP binds to an AMQP messaging system. Binding is specified for SOAP 1.2 using the SOAP Protocol Binding Framework described in Section 4 of [SOAP12-Part1].

The approach taken for this specification is to model it on the binding specifications that have been created for SOAP 1.2. The first of these was for a SOAP HTTP Binding, described in Section 7, “SOAP HTTP Binding,” in [SOAP12-Part2]. This specification generally follows the basic structure of SOAP over Java Message Service 1.0 [SOAP-JMS], and we gratefully acknowledge the valuable example provided by the contributors and editors of that specification.

4 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

References to the citations in the Normative References or Non-Normative References sections appear within brackets. References to other Internet-based resources are identified with complete visible hyperlinks enclosed in parentheses.

Text in red indicates commentary on areas in this document which require additional work, and should all be removed before publication at the OASIS Committee Specification level.

5 Normative references

[AMQP] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0. 29 October 2012. OASIS Standard. .

[amqp-pt1-types] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 1: Types. 29 October 2012. OASIS Standard. .

[amqp-pt2-transport] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 2: Transport. 29 October 2012. OASIS Standard. .

[amqp-pt3-messaging] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 3: Messaging. 29 October 2012. OASIS Standard. .

[amqp-pt4-transactions] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 4: Transactions. 29 October 2012. OASIS Standard. .

[amqp-pt5-security] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 5: Security. 29 October 2012. OASIS Standard. .

[RFC2045] N. Freed, N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies”, RFC 2045, November 1996. .

[RFC2119] S. Bradner, “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. .

[SOAP12-Part0] SOAP Version 1.2 Part 0: Primer (Second Edition), Nilo Mitra, Yves Lafon, Editors. World Wide Web Consortium, 27 April 2007. This version is . The latest version is available at .

[SOAP12-Part1] SOAP Version 1.2 Part 1: Messaging Framework (Second Edition), Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors. World Wide Web Consortium, 27 April 2007. This version is . The latest version is available at .

[SOAP12-Part2] SOAP Version 1.2 Part 2: Adjuncts (Second Edition), Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors. World Wide Web Consortium, 27 April 2007. This version is . The latest version is available at .

[SOAP12-Part3] SOAP 1.2 Part 3: One-Way MEP, David Orchard, Author. World Wide Web Consortium, 2 July 2007. This version is . The latest version is available at .

[WSDL-11] Web Services Description Language (WSDL) 1.1, E. Christensen, et al, Authors. Ariba, International Business Machines Corporation, and Microsoft, 15 March 2001. This version is available at . The latest version is available at .

[WSDL-11-SOAP12] WSDL 1.1 Binding Extension for SOAP 1.2, D. Angelov, et al, Authors. International Business Machines Corporation, Microsoft Corporation, Inc., Oracle Corp. and SAP AG, 5 April 2006. This version is available at . The latest version is available at .

[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, and F. Yergeau, Editors. World Wide Web Consortium, 10 February 1998, revised 26 November 2008. This version of the XML 1.0 Recommendation is . The latest version is available at .

[XML-Namespace] Namespaces in XML 1.0, T. Bray, D. Hollander, A. Layman, and R. Tobin, Editors. World Wide Web Consortium, 14 January 1999, revised 16 August 2006. This version is . The latest version is available at .

[XML-Schema] XML Schema Part 1: Structures Second Edition, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version is . The latest version is available at .

[XML-Schema-Part2] XML Schema Part 2: Datatypes Second Edition, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 2 May 2001, revised 28 October 2004. This version is . The latest version is available at .

6 Non-normative references

[SOAP-JMS] SOAP over Java Message Service 1.0, Phil Adams, Peter Easton, Eric Johnson, Roland Merrick, Mark Phillips, Editors. World Wide Web Consortium, 16 February 2012. This version is . The latest version is available at .

7 XML namespaces

Will a new XML namespace be declared?

Will any/all of the namespaces listed here be used?

XML namespaces and prefixes used in this standard:

|Prefix |Namespace |

|soapamqp | |

|xsd | |

|wsdl11 | |

|wsdl20 | |

|wsoap | |

|wsdl11soap12 | |

The binding defined by this specification is identified by the XML namespace URI [XML-Namespace] .

8 Conformance-related clauses

Clauses in this specification which use the key words identified in the Terminology section (1.4) are accompanied by an identifier in brackets. The Conformance section (5) describes the applicability of each identifier for implementations intending to conform to one or more parts of this specification.

The SOAP/AMQP Underlying Protocol Binding

1 Introduction

This section covers the SOAP/AMQP binding, and implicitly the AMQP calls that need to be made. One might think of the AMQP calls as the SOAP/AMQP message format. This is almost correct, but not completely. AMQP defines a wire level protocol. Also, this document covers how the SOAP/AMQP implementation connects to the AMQP service and selects the appropriate destination.

This part covers details such as how AMQP connections and destinations are handled. It also covers the message content, including how properties and headers such as priority, soapAction and targetService are handled within the SOAP/AMQP implementation.

2 Properties Affecting Binding

There are a number of properties that affect how the binding behaves. The following properties are grouped into related sets.

Some of the properties are optional. Properties can be obtained from a number of sources. If a given property is specified in more than one of these, the following list specifies the precedence: the first MUST be used in preference to the second. [conf]

1. The environment (for example local program variables, system environment variables etc).

2. WSDL elements or attributes (including those specified in an endpoint URI within the WSDL). The precedence rules for properties specified in a WSDL document are defined in Section 3.3.4, Specifying Properties In WSDL 1.1.

1 Connection to a destination

The text below is unchanged from the W3C SOAP-JMS specification. Some of it may be useful.

Since the underlying JMS URI scheme defines an open-ended scheme for identifying and connecting to a destination, it is not possible to enumerate all the ways that connection information can be set. However, in the interest of specifying context information such as JNDI connection properties in such a way that they can apply to multiple services or endpoints, this specification enumerates specific properties.

[Definition: soapjms:lookupVariant ](xsd:string)

• Specifies the technique to use for looking up the given destination name.

• MUST be specified in the JMS URI, as the jms-variant portion of the syntax. †

• The jms-variant: jndi MUST be supported.† [Definition: A fault MUST be generated with subcode unsupportedLookupVariant if the JMS URI specifies a lookupVariant that is not supported by the implementation.†]

[Definition: soapjms:destinationName ] (xsd:string)

• Specifies the name of the destination, for lookup as per the lookupVariant. If the variant is "jndi", this is the Java Naming and Directory Interface (JNDI) name of the destination (queue or topic).

• MUST be specified in JMS URI, as the jms-dest portion of the syntax.†

[Definition: soapjms:jndiConnectionFactoryName ] (xsd:string)

• Specifies the JNDI name of the connection factory.

• optional in URI, optional in WSDL, optional in environment

[Definition: soapjms:jndiInitialContextFactory ] (xsd:string)

• Specifies the fully qualified Java class name of the InitialContextFactory to use. This is mapped to the java.naming.factory.initial property (defined by the constant javax.naming.Context.INITIAL_CONTEXT_FACTORY) to be set in the HashMap sent to an InitialContext constructor.

• optional in URI, optional in WSDL, optional in environment

[Definition: soapjms:jndiURL ] (xsd:anyURI)

• Specifies the JNDI provider URL, which is mapped to the java.naming.provider.url property (defined by the constant javax.naming.Context.PROVIDER_URL) to be set in the HashMap sent to an InitialContext constructor.

• optional in URI, optional in WSDL, optional in environment

[Definition: soapjms:jndiContextParameter ] (soapjms:jndiContextParameterType)

• Provides mechanism to set additional, arbitrary JNDI environment properties, other than jndiURL and jndiInitialContextFactory, in the java.util.Hashtable sent to the InitialContext constructor for the JNDI provider.

• A property that can be specified more than once. When determining precedence rules for multiple occurrences of the jndiContextParameter property, the property is not considered to occur more than once unless the name attribute is identical in multiple jndiContextParameter properties.

• Specifies a JNDI property name and value pair to be added to the java.util.Hashtable sent to the InitialContext.

• In XML form the JNDI property's name is defined by the name attribute of the jndiContextParameter element, and the JNDI property value is defined by the value attribute. When indicated in a URI, the name of the JNDI property is derived from dropping the 'jndi-' prefix from any parameter name starting that way, and the value comes from the parameter value. The value is added as a java.lang.String.

• optional in URI, optional in WSDL, optional in environment

Example: Including JNDI context properties in WSDL

Example: Including JNDI context properties in URI

jms:jndi:destinationName?jndi-com.acme.jndi.enable.tracing=true&jndi-java.naming.referral=ignore

2 AMQP Message Header properties

This set of properties provide information that will set the values of corresponding AMQP fields. This specification assumes that the AMQP provider validates the values set for the respective message header properties, rather than being explicitly constrained by this specification.

The text below is unchanged from the W3C SOAP-JMS specification. Some of it may be useful.

[Definition: soapjms:deliveryMode] (soapjms:deliveryModeType)

• indicates whether the request message is persistent or not. The valid values are "PERSISTENT" and "NON_PERSISTENT". The default value is "PERSISTENT" (defaulted by JMS)

• optional in URI, optional in WSDL, optional in environment

• if specified MUST appear in the JMS message in the header named JMSDeliveryMode. If the value of this property is "PERSISTENT" then the JMSDeliveryMode integer value MUST be set to DeliveryMode.PERSISTENT. If the value of this property is "NON_PERSISTENT" then the JMSDeliveryMode integer value MUST be set to DeliveryMode.NON_PERSISTENT. †

[Definition: soapjms:timeToLive] (xsd:long)

• the lifetime, in milliseconds, of the request message. A value of 0 indicates an infinite lifetime. The default value is 0 (defaulted by JMS).

• optional in URI, optional in WSDL, optional in environment.

• if specified, this MUST be used to generate the value of the JMS header JMSExpiration.†

[Definition: soapjms:priority] (soapjms:priorityType)

• the JMS priority associated with the request message. Valid values are integers between 0 (lowest priority) and 9 (highest priority). The default value is 4 (defaulted by JMS).

• optional in URI, optional in WSDL, optional in environment

• if specified, MUST appear in the JMS message in the header named JMSPriority.†

[Definition: soapjms:replyToName] (xsd:string)

• Specifies the name of the destination to which a response message will be sent. If the replyToName property has a value it is used to lookup a destination using the lookupVariant. If the variant is "jndi", this is the Java Naming and Directory Interface (JNDI) name of the destination (queue or topic). If the variant is "queue" or "topic", this refers to the name of a JMS queue.

• optional in URI, optional in WSDL, optional in environment

• if specified, this MUST be used to derive the value to be used in the JMS header JMSReplyTo.†

[Definition: soapjms:topicReplyToName] (xsd:string)

• Specifies the name of the topic destination to which a response message will be sent.

• as defined by [IETF RFC 6167], the topicReplyToName only makes sense if the URI variant is "queue" or "topic".

• if the replyToName is specified in the URI, WSDL, or environment, topicReplyToName is not relevant and MUST be ignored.

• optional in URI, optional in WSDL, optional in environment

• if specified and if relevant, this MUST be used to derive the value to be used in the JMS header JMSReplyTo.†

1 Setting AMQP Message Header properties

This section is non-normative and is intended to give an example of how an AMQP Message Header property can be set.

3 AMQP Message properties

The text below is unchanged from the W3C SOAP-JMS specification. Some of it may be useful.

[Definition: soapjms:targetService] (xsd:string)

• Used by the service implementation to dispatch the service request.

• optional in URI

• [Definition: if specified MUST appear in the JMS message in the JMS property named SOAPJMS_targetService. Use fault subcode missingTargetService if specified and SOAPJMS_targetService does not appear. † ]

[Definition: soapjms:bindingVersion] (xsd:string)

• Specifies the version of SOAP JMS binding that is being used.

• fixed value "1.0" in the implementation, MUST appear in a JMS property named SOAPJMS_bindingVersion.†

[Definition: A fault MUST be generated with subcode unrecognizedBindingVersion if the value of the soapjms:bindingVersion property does not match the fixed value. †]

[Definition: soapjms:contentType] (xsd:string)

Note that the contentType value also indicates the MIME type of the primary message payload. This message property, then, identifies whether the message payload uses SOAP 1.1, SOAP 1.2, SOAP Messages With Attachments [SOAP Messages with Attachments] or MTOM [SOAP 1.1 Binding for MTOM 1.0] [SOAP MTOM] as the primary payload.

• Describes the content of the SOAP message, this has the same values as the MIME Content-Type specified for a SOAP message over HTTP [IETF RFC 2045].

• If the value of the property is text/xml or application/soap+xml, a charset parameter might be present; if the value of the property is multipart/related, a type parameter might be present.

• [Definition: If the charset parameter is specified, it is checked to ensure that it matches the encoding value from the supplied XML. A fault MUST be generated with subcode contentTypeMismatch if the encoding values do not match.†]

• The charset parameter is optional and can take the values "utf-8" or "utf-16". If the charset parameter is omitted, the character set rules for freestanding [XML 1.0] apply to the body of the JMS message.

• [Definition: The contentType value MUST appear in the JMS message in the JMS property named SOAPJMS_contentType. A fault MUST be generated with subcode missingContentType if the SOAPJMS_contentType property is missing.†]

[Definition: soapjms:soapAction] (xsd:anyURI)

• As with SOAP/HTTP

• Optional in WSDL, optional in environment

• [Definition: If specified MUST appear in the JMS message in the JMS property named SOAPJMS_soapAction. Fault subcode missingSoapAction MAY be used if SOAPJMS_soapAction does not appear.† ]

• [Definition: If using SOAP 1.2, and the contentType property has an action parameter, that parameter value is compared with the SOAPJMS_soapAction value. A fault MUST be generated with fault subcode mismatchedSoapAction if the SOAP 1.2 action does not match the SOAPJMS_soapAction value.†]

[Definition: soapjms:isFault] (xsd:boolean)

• This property indicates whether a SOAP/JMS message corresponds to a SOAP fault.

• For senders, this property is set to true when responding with a SOAP fault. When this property is true, the sending software MUST set a boolean JMS Message property named SOAPJMS_isFault with a value of true, as in: Message.setBooleanProperty("SOAPJMS_isFault", true). †

• For receivers, this property is derived from the boolean JMS Message property named SOAPJMS_isFault — if present and containing a value of true, the value of soapjms:isFault is true. If omitted, or present with a value of false, the value of soapjms:isFault is false.

[Definition: soapjms:requestURI] (xsd:string)

• Specifies the JMS URI of the service. The client MUST create the requestURI by taking the supplied URI, leaving the destinationName as-is, and removing the targetService and replyToName query parameters if they are specified. The client SHOULD also remove deliveryMode, jndiConnectionFactoryName, jndiInitialContextFactory, jndiURL, jndiContextParameter, timeToLive, and priority properties. The client MAY remove other query parameters not explicitly mentioned above (for example client security related properties).†

• A required property

• [Definition: Appears in the JMS message in the JMS property named SOAPJMS_requestURI. A fault MUST be generated with fault subcode missingRequestURI if the SOAPJMS_requestURI property is missing from the message.†]

• [Definition: A fault MUST be generated with subcode malformedRequestURI when the SOAPJMS_requestURI violates the expected syntax.† ].

• [Definition: A fault MUST be generated with subcode targetServiceNotAllowedInRequestURI when targetService parameter is included in the SOAPJMS_requestURI). † ]

[Definition: soapjms:contentEncoding] (xsd:string)

• Identifies the transformation that has been applied to the message payload body. Contains one of the values defined by IANA for the Content-Coding values of [IANA HTTP PARAMS]. Defaults to "identity" if the property is not present.

• Corresponds to the JMS Message property named SOAPJMS_contentEncoding

• [Definition: If the content encoding is specified, it is checked to ensure that it matches the content encoding values supported. A fault MUST be generated with subcode contentEncodingNotSupported if the encoding values do not match.†]

• Restriction: the meaning of the property is not defined for composite messages (messages with a Content-Type of "multipart" or "message"), only for discrete messages (Content-Type "application" or "text", for this specification).

1 Setting AMQP Message properties

This section is non-normative and is intended to give an example of how an AMQP Message property can be set.

4 Binding of Properties to URI

The text below is unchanged from the W3C SOAP-JMS specification. Some of it may be useful. for AMQP, most of these properties will be set as described in Section 3.2.4 of [amqp-pt3-messaging].

Implementations of this specification need to allow for the setting of the above properties. Some properties, as mentioned above can be inferred from context, or provided by the application environment. Some might be put into WSDL. In many cases, it is desirable to represent those properties as part of a URL-like representation. In particular, this section describes how the properties above are used in the URI. Note that the URI scheme also defines query parameters, and where the query parameter names are the same, the same meaning is intended here.

For brevity, properties are shown without the SOAPJMS prefix. The "URI representation" column describes how the property is carried in the URI.

|Binding of Properties to URI |

|Specification Property |URI Representation |

|deliveryMode |as deliveryMode query parameter |

|destinationName |as jms-dest portion of URI syntax |

|jndiConnectionFactoryName |as jndiConnectionFactoryName query parameter |

|jndiInitialContextFactory |as jndiInitialContextFactory query parameter |

|jndiURL |as jndiURL query parameter |

|jndiContextParameter |as a query parameter combining the string "jndi-" with the jndiContextParameter's name attribute |

|replyToName |as replyToName query parameter |

|topicReplyToName |as topicReplyToName query parameter |

|priority |as priority query parameter |

|targetService |as targetService query parameter |

|timeToLive |as timeToLive query parameter |

5 Other Properties

This section describes setting other AMQP properties.

3 Authentication for SOAP/AMQP

Security, and in particular authentication, is a critical concern in most if not all environments where this binding will be utilized. There are at least two places where authentication might need to occur — 1) authenticating to an AMQP registry where AMQP destinations or targets are located, and 2) authenticating to the AMQP system itself. Credentials such as usernames and passwords might be required to access directories and to obtain AMQP connections from a provider. This specification does not mandate how an implementation might obtain these credentials.

Implementers of this binding are encouraged to consider the most appropriate way to expose authentication functionality to their users such that it meshes smoothly with the models exposed by their environments.

4 The AMQP Message Body

The contents of the AMQP Message data section MUST be the SOAP payload. [conf]

After being decoded according to the contentEncoding property, the binary data of the AMQP Message data section corresponds to the MIME format as indicated by the definition of the contentType property. In this way, the SOAP node determines the proper formatting of the SOAP payload, and specifies an appropriate value for the contentType property which describes it to the receiving SOAP node. Specifically, if the payload is formatted as a MIME multipart message, then the first byte or character encountered in the AMQP Message data section MUST be the start of the MIME boundary for the start of the first part — what MIME Part One [RFC2045] section 2.5 calls a "Body Part". [conf] If the message is formatted as "text/xml" or "application/soap+xml", then the first byte or character of the AMQP Message data section MUST be the start of a conforming XML document. [conf]

5 Supported Message Exchange Patterns

In the case of SOAP 1.1 there is no formal specification of Message Exchange Patterns. A conforming SOAP-JMS Binding instance MUST support both the generic "request/response" and "one-way" patterns as specified in this document.†

In the case of SOAP 1.2 a conforming SOAP-AMQP Binding instance MUST support the following message exchange patterns: [conf]

(defined in Section 6.2 of [SOAP12-Part2], “Request-Response Message Exchange Pattern”)

(defined in [SOAP12-Part3])

1 Support for Topic destinations

Topics can be used as destinations for SOAP messages over AMQP. However, due to the potential complexities around how topics might interact with message-exchange patterns, this specification provides no guidelines as to how that message exchange might work.

For these reasons, implementers and clients of this specification are advised to use caution when dealing with AMQP topics. We strongly encourage implementers to carefully document their choices around the use and support of topic destinations.

6 Request-Response Message Exchange Pattern

For binding instances using the Request-Response Message Exchange Pattern:

• A SOAP Node instantiated at the JMS interface can take on the role (i.e. the property ) of RequestingSOAPNode.

• A SOAP Node instantiated at the JMS interface can take on the role (i.e. the property ) of RespondingSOAPNode.

The remainder of this section consists of descriptions of the MEP state machine. In the state descriptions following, the states are defined as values for the property .

Failure reasons as specified in the tables represent values of the property - their values are qualified names. If an implementation enters the "Fail" state, the property will contain the value specified for the particular transition.

1 Behavior of Requesting SOAP Node

1 Init

The material below is unchanged from the SOAP-JMS specification. It is expected that the corresponding AMQP fields and/or properties will be identified as the “Field” instead of the JMS elements.

In the "Init" state, a JMS request is formulated and transmission of the request is initiated. The message is created as a JMS BytesMessage or TextMessage as defined in 2.4 The JMS Message Body.

A number of the message header properties are implicitly created by the use of the JMS API. The following table shows how the binding properties described earlier explicitly affect the message constructed.

|Init State Values |

|Field |Value Set by Conforming Client |

|JMS Message Header |

|JMSDeliveryMode |the value of the deliveryMode property or not set if not specified |

|JMSExpiration |calculated from the value of the timeToLive property or not set if not specified |

|JMSPriority |the value of the priority property or not set if not specified |

|JMSDestination |derived from the destinationName property |

|JMSReplyTo |if the replyToName property is specified, this is the JMS Destination object derived from that |

| |name. Otherwise the implementation has to determine the reply queue, and use the JMS Destination |

| |object which represents that queue; the queue can be a temporary queue generated as described in |

| |the JMS specification. |

|JMS Message properties |

|SOAPJMS_requestURI |this is derived from the requestURI property |

|SOAPJMS_bindingVersion |this is copied from the bindingVersion property |

|SOAPJMS_soapAction |the value of the soapAction property or not set if not specified |

|SOAPJMS_targetService |the value of the targetService property or not set if not specified |

|SOAPJMS_contentType |inferred from the SOAP Envelope and presence of attachments |

|JMS Message Body |

|body |A SOAP envelope is serialized according to the media type specified in the JMS Message property |

| |SOAPJMS_contentType |

2 Requesting

In the "Requesting" state, sending of the request continues while waiting for the start of the correlated response message. A correlated response message is defined as follows: If the JMSCorrelationID header field is set in the request message then a correlated response message is one where the value of the JMSCorrelationID header field is the same as the value of the JMSCorrelationID of the request message. If the JMSCorrelationID header field is not set in the request message then a correlated response message is one where the value of the JMSCorrelationID header field is the same as the value of the JMSMessageID header of the request message.

The JMSReplyTo header MUST be assigned a value. † The response message will be received on the JMS Destination specified in the JMSReplyTo header above, and that Destination is where implementations need to listen.

If a correlated response message is received then a transition to "Sending + Receiving" is made.

If, for whatever reason (for example a timeout), no correlated response message is received then a failure reason receptionFailure is set and a transition to "Fail" is made.

3 Sending + Receiving

Receive a correlated message body that is assumed to contain a SOAP envelope serialised according to the rules for carrying a SOAP message in the media type specified in the JMS Message property SOAPJMS_contentType.

If a well formed response message is received a transition to "Success" is made, and otherwise transition to "Fail".

4 Success and Fail

"Success" and "Fail" are the terminal states of the Request-Response MEP. Control over the message exchange context returns to the local SOAP node.

2 Behavior of Responding SOAP Node

1 Init

Receive and validate the inbound request message.

If a well formed request message is received a transition to the local SOAP node is made followed by a transition to the "Receiving" state.

If a malformed request message is received a transition to "Fail" is made.

2 Receiving

Waiting for Response Message to become available in Message Exchange Context (as defined in Section 5.1.2.1 of [SOAP12-Part2]) as a result of processing the Request Message (note Request Message fully received on exit from Init state).

3 Receiving + Sending

Completing Request Message reception and Response Message transmission. (Response Message sent on exit from Receiving State).

The material below is unchanged from the SOAP-JMS specification. It is expected that the corresponding AMQP fields and/or properties will be identified as the “Field” instead of the JMS elements.

The JMS response is formulated and transmission of the response is initiated. The Response Message MUST be created using the same type as the corresponding Request Message, i.e. as a JMS BytesMessage or TextMessage.† The message MUST be sent to the JMS Destination in the JMSReplyTo header of the Request Message.† If the JMSCorrelationID is set in the request message, then the JMSCorrelationID header field in the response message MUST be set to the same value as the JMSCorrelationID header field in the request message. If the JMSCorrelationID header field is not set in the request message, then the JMSCorrelationID header field in the response message MUST be set to the value of the JMSMessageID header in the request message.†

A number of the message header properties are implicitly created by the use of the JMS API. The following table shows how the binding properties described earlier explicitly affect the message constructed.

|Receiving + Sending State Values |

|Field |Value Set by Conforming Client |

|JMS Message Header |

|JMSDeliveryMode |this ought to be the same as that specified on the request |

|JMSExpiration |this is derived from the request. It is up to the responding node to decide whether to degrade for|

| |processing time. |

|JMSCorrelationID |this is copied from the request JMSCorrelationID if it is set, or the request JMSMessageID if the |

| |request JMSCorrelationID is not set |

|JMSDestination |this is copied from the JMSReplyTo property in the request |

|JMS Message properties |

|SOAPJMS_requestURI |this is copied from the requestURI property in the request message |

|SOAPJMS_bindingVersion |this is copied from the bindingVersion property |

|SOAPJMS_contentType |inferred from the SOAP Envelope and presence of attachments |

|SOAPJMS_isFault |set to true if the response is a SOAP fault, otherwise it can be absent |

|JMS Message Body |

|body |A SOAP envelope is serialized according to the media type specified in the JMS Message property |

| |SOAPJMS_contentType. |

If a response message is successfully sent a transition to the "Success" state is made.

If there is a failure to send a response message then failure reason transmissionFailure is set and a transition to "Fail" is made.

4 Success and Fail

"Success" and "Fail" are the terminal states for the Request-Response MEP. From the point-of-view of the local node this message exchange has completed.

7 One-way Message Exchange Pattern

The SOAP One-way MEP defines properties for the exchange of a SOAP/AMQP message which does not solicit a response. For AMQP messages sent to a Queue destination this MEP results in a SOAP message which will be received by zero or one receiver. For AMQP messages sent to a Topic destination this MEP results in SOAP message(s) which will be received by zero, one, or many receivers.

This message exchange pattern is identified by the URI .

For binding instances conforming to this specification:

• A SOAP Node instantiated at the sending AMQP interface takes on the role (i.e. the property , defined in Table 2 in [SOAP12-Part2], Property definitions supporting the description of MEPs), of SendingSOAPNode.

• A SOAP Node instantiated at the receiving JMS interface takes on the role (i.e. the property ) of ReceivingSOAPNode.

The remainder of this section consists of descriptions of the MEP. Failure reasons represent values of the property — their values are qualified names. If a MEP instance terminates with a fault, then the property will contain a value identifying the fault.

1 Behavior of Sending SOAP Node

The message is created as defined in Section 2.4, The AMQP Message Body.

The AMQP ReplyTo header MUST NOT be assigned a value. [conf]

If the Sender receives a message transmission failure, then the property is set to transmissionFailure and the message exchange is terminated with a fault.

A number of the message header properties are implicitly created by the use of the AMQP transport. The following table shows how the binding properties described earlier explicitly affect the message constructed.

The material below is unchanged from the SOAP-JMS specification. It is expected that the corresponding AMQP fields and/or properties will be identified as the “Field” instead of the JMS elements.

|Sending SOAP Node Values |

|Field |Value Set by Conforming Client |

|JMS Message Header |

|JMSDeliveryMode |the value of the deliveryMode property or not set if not specified |

|JMSExpiration |calculated from the value of the timeToLive property or not set if not specified |

|JMSPriority |the value of the priority property or not set if not specified |

|JMSDestination |derived from the destinationName property |

|JMS Message properties |

|SOAPJMS_requestURI |this is derived from the requestURI property |

|SOAPJMS_bindingVersion |this is copied from the bindingVersion property |

|SOAPJMS_soapAction |the value of the soapAction property or not set if not specified |

|SOAPJMS_targetService |the value of the targetService property or not set if not specified |

|SOAPJMS_contentType |inferred from the SOAP Envelope and presence of attachments. |

|JMS Message Body |

|body |A SOAP envelope is serialized according to the media type specified in the JMS Message property |

| |SOAPJMS_contentType. |

2 Behavior of Receiving SOAP Node

The receiving node follows the rules defined in [SOAP12-Part3].

8 Faults

The SOAP fault subcodes listed throughout this document, and consolidated here, include:

• contentTypeMismatch

• malformedRequestURI

• mismatchedSoapAction

• missingContentType

• missingRequestURI

• missingSoapAction

• missingTargetService

• targetServiceNotAllowedInRequestURI

• unrecognizedBindingVersion

• unsupportedJMSMessageFormat

• unsupportedLookupVariant

• contentEncodingNotSupported

The material below is unchanged from the SOAP-JMS specification.

The above subcodes are the local name in the soapjms namespace, appearing, for example, as soapjms:malformedRequestURI.

In SOAP 1.2, the subcodes above are used as-is in the env:Value element of the env:Subcode for a SOAP Fault. The following shows an example of a SOAP 1.2 Fault payload with the contentTypeMismatch subcode:

Example: SOAP 1.2 Fault payload with the contentTypeMismatch subcode

env:Sender

soapjms:contentTypeMismatch

The content type of the JMS payload does

not match the XML.

This specification does not mandate any particular text for the env:Text child element of the env:Reason element.

The SOAP 1.1 specification does not support subcodes directly. In that scenario, the faultcode element uses a QName that matches the subcode for SOAP 1.2. The faultstring element can contain textual fault information. The same error as above, shown in SOAP 1.1:

Example: SOAP 1.1 Fault payload with the contentTypeMismatch subcode

soapjms:contentTypeMismatch

The content type of the JMS payload does not match the XML.

WSDL Usage

What parts are useful?

The material below is unchanged from the SOAP-JMS specification.

1 Overview

These next sections describe how to indicate the use of SOAP over AMQP in WSDL. We begin with complete examples, and then describe the individual pieces and parts in the sections which follow.

Section 2 The SOAP/AMQP Underlying Protocol Binding above contains the actual rules by which SOAP messages are sent and received using AMQP. This section indicates how WSDL can be used to indicate the use and control the operation of that binding.

For general information on extending SOAP bindings in WSDL, please refer to section 3 “SOAP Binding” in [WSDL-11]. For information about accepted SOAP 1.2 bindings, see [WSDL-11-SOAP12].

2 WSDL 1.1 Extensions Overview

• The transport attribute of the wsdl11soap11:binding or wsdl11soap12:binding element gets a new URL reflecting an AMQP transport.

• Allows use of SOAPAction header, even though it is explicitly disallowed by WSDL specification.

• Defines how to set various properties to control the behavior (connection parameters, runtime setting) of the binding.

• Locates the service using AMQP.

3 WSDL 1.1 Extensions Detail

The material below is unchanged from the SOAP-JMS specification.

This section is normative.

This section describes the optional feature: soapjms:WSDL11 []. To focus on the salient details, all of the WSDL examples in this section show only a portion of a WSDL file in question.

1 Example

The material below is unchanged from the SOAP-JMS specification.

The WSDL 1.1 specification includes in section 1.2, WSDL Document Example, the example Example 1 SOAP 1.1 Request/Response via HTTP.

The following example illustrates a new service description which assumes the original service available over HTTP is also made available over JMS.

Lines 14-33 are a new binding for specifying that JMS is to be used, line 15 shows the transport URI in , and lines 17-22 show the extension properties in the .

Lines 40-42 are also additions to specify the location at which this new implementation exists. Line 41 shows the JMS URI Scheme jms: in the .

Example: WSDL 1.1 JMS Binding

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19 sample.jms.ConnectionFactory

20

21

22 PERSISTENT

23

24

25

26

27

28

29

30

31

32

33

34

35

36 My first service

37

38

39

40

41

42

43

The key points to notice are:

• The transport URI in (line 15)

• The jms: URI in the (line 41)

• The extension properties in the (lines 17-22)

2 WSDL 1.1 Transport Identification

The material below is unchanged from the SOAP-JMS specification.

For each of SOAP 1.1 and SOAP 1.2, the transport attribute of the wsdl11soap11:binding element, and the wsdl11soap12:binding element, respectively, indicate the transport value. To indicate that this SOAP/JMS binding is in use, the transport attribute MUST be set to the value .†

Example: SOAP 1.1 Binding for WSDL 1.1 Transport Identification

3 WSDL 1.1 SOAP Action

The material below is unchanged from the SOAP-JMS specification.

The wsdl11soap11:operation portion of the WSDL specification explicitly disallows use of the soapAction attribute in non-HTTP bindings. This specification supersedes that requirement, and allows the use of soapAction in the wsdl11soap11:operation element for SOAP/JMS bindings. This value corresponds to the property soapAction.

4 Specifying Properties In WSDL 1.1

The material below is unchanged from the SOAP-JMS specification.

Various JMS properties described in the SOAP/JMS binding specification can be set in four places in the WSDL — the binding, the service, the port, and the URI for the port. Values specified at the service will propagate to all ports. Values specified at the binding will propagate to all ports using that binding. For example, the jndiInitialContextFactory can be indicated for a wsdl11:service, and it is then implied for all of the contained wsdl11:port elements.

If a property is specified at multiple levels within the WSDL document, the most specific setting MUST take precedence (URI specified in the address element's location attribute first, then other properties set on the port, then service, then binding).†

In the following example, notice the timeToLive property — for the quickPort port, the value will be 10 (specified at the port level). For the slowPort port, the value will be 100 (specified at the service level). The setting in the binding is, in this example, always overridden.

Example: Specifying Properties in WSDL 1.1

...

200

com.example.jndi.InitialContextFactory

100

...

...

10

...

5 Specifying Properties

The material below is unchanged from the SOAP-JMS specification.

Some of the above information can be put in the JMS URI. When expressing properties from the SOAP/JMS binding in the URI, you do not need the namespace prefix — just use the property name, such as "priority".

This URI is found as the value of the location attribute on the or element when using SOAP 1.1 and SOAP 1.2, respectively. The value of the location attribute MUST be a URI corresponding to a JMS Destination, and SHOULD be a "jms" scheme URI.† The characters in the URI need to be encoded ("%20" for space, for example) as per normal URI escaping rules, and the resulting URI needs to be encoded as per normal XML rules ("&" for &) when serialized into an XML attribute.

Example: Specifying WSDL 1.1 Properties Via the JMS URI

4 Properties

The material below is unchanged from the SOAP-JMS specification.

The XML elements jndiConnectionFactoryName, jndiInitialContextFactory, jndiURL, deliveryMode, priority, timeToLive, and replyToName, in the soapjms namespace, MUST be supported when used in the context of the WSDL service, port, and binding elements. This specification does not define any use outside of those elements.

Conformance

Clauses in this specification which use the key words identified in the Terminology section (1.4) are accompanied by an identifier in brackets. This section describes the applicability of each identifier for implementations intending to conform to one or more parts of this specification.

TBD

A. Acknowledgments

The following individuals are members of the OASIS Advanced Message Queuing Protocol (AMQP) Bindings and Mappings (AMQP-BINDMAP) TC as the date of this publication.

Those who have participated in the creation of this specification are gratefully acknowledged.

TC Members:

|Sanjay Aiyagari | VMware, Inc. |

|Matthew Arrott | Individual |

|Allan Beck | JPMorgan Chase Bank, N.A. |

|Mark Blair | Credit Suisse |

|Andrew Braddock | US Department of Homeland Security |

|Laurie Bryson | JPMorgan Chase Bank, N.A. |

|Raphael Cohn | Individual |

|Andrew Doddington | Bank of America |

|Rob Dolin | Microsoft |

|Robert Gemmell | JPMorgan Chase Bank, N.A. |

|Rob Godfrey | JPMorgan Chase Bank, N.A. |

|Philip Harvey | JPMorgan Chase Bank, N.A. |

|William Henry | Red Hat |

|Steve Huston | Individual |

|David Ingham | Microsoft |

|Ram Jeyaraman | Microsoft |

|James Kirkland | Red Hat |

|Paul Knight | Individual |

|Alex Kritikos | Software AG, Inc. |

|Shawn McAllister | Solace Systems |

|Dale Moberg | Axway Software |

|Andreas Moravec | Deutsche Boerse AG |

|John O'Hara | Individual |

|Duane Pauls | Solace Systems |

|Darryl Pierce | Red Hat |

|Jonathan Poulter | Kaazing |

|Sandeep Puri | Cisco Systems |

|Oleksandr Rudyy | JPMorgan Chase Bank, N.A. |

|Rafael Schloming | Red Hat |

|Jakub Scholz | Deutsche Boerse AG |

|Wolf Tombe | US Department of Homeland Security |

B. Revision History

|Revision |Date |Editor |Changes Made |

|wd01 |09 September 2013 |Paul Knight |Initial Working Draft based on structure of [SOAP-JMS] |

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download