SOAP Binding to Advanced Message Queuing Protocol ... - Oasis

flashypumpkincenterSoftware and s/w Development

Dec 14, 2013 (3 years and 9 months ago)

127 views

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
1

of
31

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

Working Draft
01

09 September

201
3

Technical Committee:

OASIS Advanced Message Queuing Protocol (AMQP) Bindings

and Mappings (AMQP
-
BINDMAP) TC

Chair:

Steve Huston (
shuston@riverace.com
),
Individual

Editor:

Steve Huston (
shuston
@riverace.com
),
Individual

Paul Knight (
paul.the.knight@gmail.com
), 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 title
s 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.
http://docs.oasis
-
open.org/amqp/core/v1.0/os/amqp
-
core
-
overview
-
v1.0
-
os.html
.

Declared XML namespaces:



http://docs.oasis
-
open.org/amqp
-
bindmap/ns/amqpsoap/2013/

(is this needed?)

Abstract:

This document describes how SOAP binds to the Advanced Message Queuing Protocol (AMQP).

It describes bindings for

S
OAP

1.2

usi
ng the SOAP
1.2 Protocol Binding Framework, and

also
describes how to use WSDL documents to indicate and c
ontrol the use of this binding.

Status:

T
his
Working Draft

(WD) h
as 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 Dra
ft). 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
-
ap
prove it any number of times as a Committee Draf
t
.

Initial URI pattern:

http://docs.oasis
-
open.org/amqp
-
bindmap
/amqp
-
soap
/v1.0/csd01/amqp
-
soap
-
v1.0
-
csd01.doc

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



Copyright © OASIS Open

201
3
. All Righ
ts 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 f
ound 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 whol
e 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
amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
2

of
31

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


amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
3

of
31

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 referen
ces

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

6

1.6 Non
-
normative references

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

7

1.7 XML namespaces

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

7

1.8 Co
nformance
-
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 pr
operties

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

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 Prop
erties

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

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 Excha
nge 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

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
4

of
31

3.3.3 WSDL 1.1 SOAP Action

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

26

3.3.4 Specifying Prope
rties 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


amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
5

of
31

1

Introduc
tion

[All text is norm
ative unless otherwise labeled]

1.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 di
fferent
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 stac
ks; 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 a
ny 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 th
e 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 interopera
tion with SOAP/AMQP clients and services.

1.2

Out of
s
cope

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 s
ervices themselves will be presented to the application
programmer. For example, it does not describe how the programmer will characterize a one
-
way
message.

1.3

Context

This document specifies how SOAP binds to an AMQP messaging system. Binding is specified f
or

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 o
f these was for a SOAP HTTP Binding, described in
S
ection 7, “SOAP
HTTP Binding,” in
[
SOAP12
-
P
art2
]
. This specification
generally
follows the basic structure of
SOAP over
Java Message Service 1.0

[
SOAP
-
JMS
], an
d we gratefully acknowledge the valuable example provided
by the contributors and editors of that specification.

1.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]
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
6

of
31

References to the citations in the Normative References or Non
-
Normative References sections appear
within brackets. References to other Internet
-
based resources are identi
fied 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.

1.5

Normative
r
efe
rences

[AMQP]

OASIS Advanced Message Queu
ing Protocol (AMQP) Version 1.0
. 2
9 October
2012. OASIS Standard.
http://docs.oasis
-
open.org/amqp/core/v1.0/os/amqp
-
core
-
com
plete
-
v1.0
-
os.pdf
.

[amqp
-
pt1
-
types]

OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 1: Types
.
29 October 2012. OASIS Standard.
http://docs.oasis
-
open.
org/amqp/core/v1.0/os/amqp
-
core
-
types
-
v1.0
-
os.html
.

[amqp
-
pt2
-
transport]

OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part
2: Transport
. 29 October 2012. OASIS Standard.
http://docs.oasis
-
open.org/amqp/core/v1.0/os/amqp
-
core
-
transport
-
v1.0
-
os.html
.

[
amqp
-
pt3
-
messaging]

OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part
3: Messaging
. 29 October 2012. OASIS Standard.
http://docs.oasis
-
open.org/amqp/core/v1.0/os/amqp
-
core
-
messaging
-
v1.0
-
os.html
.


[amqp
-
pt4
-
transactions]

OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part
4: Transactions
.

29 October 2012. OASIS Standard.
http://docs.oasis
-
open.org/amqp/core/v1.0/os/amqp
-
core
-
transactions
-
v1.0
-
os.html
.

[amqp
-
pt5
-
security]

OASIS Advanced Message
Queuing Protocol (AMQP) Version 1.0 Part
5: Security
. 29 October 2012. OASIS Standard.
http://docs.oasis
-
open.org/amqp/core/v1.0/os/amqp
-
core
-
security
-
v1.0
-
os.html
.

[RFC2045]

N. Freed, N. Borenstein,


Multipurpose Internet Mail Extensions (MIME) Part
One: Format of Internet Message Bodies
”,

RFC 2045,

November 1996.
http://www.ietf.org/rfc/rfc2045.txt
.

[RFC2119]

S.
Bradner,

“Key words for use in RFCs to Indicate Requirement Levels”
, BCP
14, RFC 2119, March 1997.
http://www.ietf.org/rfc/rfc2119.txt
.

[SOAP12
-
Part0]

SOAP Version 1.2 Part 0: Primer (Second Edition), Ni
lo Mitra, Yves Lafon,
Editors. World Wide Web Consortium, 27 April 2007. This version is
http://www.w3.org/TR/2007/REC
-
soap12
-
part0
-
20070427
. The latest version is
available at
http://www.w3.org/TR/soap12
-
part0/
.

[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 Karmar
kar, Yves Lafon, Editors. World Wide Web Consortium, 27
April 2007. This version is
http://www.w3.org/TR/2007/REC
-
soap12
-
part1
-
20070427
. The latest version is available at
http://www.w3.org/TR/soap12
-
part1/
.

[SOAP12
-
P
art2]

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
http://www.w3.org/TR/2007/REC
-
soap12
-
part2
-
20070427
. The
latest version is available at
http://www.w3.org/TR/soap12
-
part2/
.

[SOAP12
-
Part3]

SOAP 1.2 Part 3: One
-
Way MEP
,
David Orchard, Author. World Wide Web
Consortium, 2 July 2007. This version is
http://w
ww.w3.org/TR/2007/NOTE
-
soap12
-
part3
-
20070702/
. The latest version is available at
http://www.w3.org/TR/soap12
-
part3/
.

[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
http://www.w3.org/TR/2001/NOTE
-
wsdl
-
20010315
. The latest version is available at
http://www.w3.org/TR/wsdl
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
7

of
31

[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 A
pril 2006. This version is available at
http://www.w3.org/Submission/2006/SUBM
-
wsdl11soap12
-
20060405/
. The latest
version is available at
http://www.w3.org/Submission/wsdl11soap12/
.

[XML]

Extensible Markup Language (XML) 1.0 (F
if
th 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

200
8
. This version of the
XML 1.0 Recommendation is
http://www.w3.org/TR/2008/REC
-
xml
-
20081126/
.

The
latest version
is available a
t
http://www
.w3.org/TR/REC
-
xml
.

[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
http://www.w3.org/TR/2006/REC
-
xml
-
names
-
20060816/
.

The
latest version is available at
http://www.w3.org/TR/REC
-
xml
-
names
.

[XML
-
S
chema]

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
http://www.w3.org/TR/2004/REC
-
xmlschema
-
1
-
20041028/
. The latest version is available at
http://www.w3.org/TR/xmlschema
-
1/
.

[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
http://www.w3.org/TR/2004/REC
-
xmlschema
-
2
-
20041028/
.
The latest version is available
at
http://www.w3.org/TR/xmlschema
-
2
.


[
Reference
]

[Full reference citation]


1.6

Non
-
n
ormative
r
eferences

[SOAP
-
JMS]

SOAP over Java Message Service 1.0
,
Phil Ada
ms, Peter Easton, Eric Johnson,
Roland Merrick, Mark Phillips
,
Editors
. World Wide Web Consortium,
16
February 2012
. This version is
http://www.w3.org/TR/2012/REC
-
soapjms
-
20120216/
. The latest

version

is available at
http://www.w3.org/TR/soapjms/
.

[
Reference
]

[Full reference citation]


1.7

XML
n
amespaces

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

http://docs.oasis
-
open.org/amqp
-
bindmap/ns/amqpsoap/2013/

xsd

ht
tp://www.w3.org/2001/XMLSchema

wsdl11

http://schemas.xmlsoap.org/wsdl/

wsdl20

http://www.w3.org/ns/wsdl

wsoap

http://www.w3.org/ns/wsdl/soap

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
8

of
31

wsdl11soap1
2

http://schemas.xmlsoap.org/wsdl/soap12/

The binding defined by this specification is identified b
y the XML namespace URI [
XML
-
Namespace
]
http://docs.oasis
-
open.org/amqp
-
bindmap/ns/amqpsoap/2013/
.

1.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 (
4
) des
cribes the applicability of
each identifier for implementations intending to conform to one or more parts of this specification.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
9

of
31

2

The SOAP/
AMQP

Underlying Protocol Binding

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

define
s

a
wire level protocol
. Also, this document covers how the SOAP/
AMQP

implementation connects to the
AMQP

servi
ce 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 hand
led within the SOAP/
AMQP

implementation.

2.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 obta
ined 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
.


2.2.1

Connection to a destination

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

Since the underlying JMS URI scheme defines an open
-
ended scheme for identifying and
co
nnecting 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 serv
ices 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).

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
10

of
31



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 environmen
t

[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.INIT
IAL_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

] (soapjm
s: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 t
hat 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 jndiContextParam
eter 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 prope
rty 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

<!
--

Enable tracing for the ACME Corporation JNDI provider
--
>

<soapjms:jndiContextParameter name="com.acme.jndi.enable.trac
ing"
value="true" />


amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
11

of
31

<!
--

Include the standard JNDI property to ignore JNDI provider
referrals
--
>

<soapjms:jndiContextParameter name="java.naming.referral"
value="ignore" />



Example: Including JNDI context properties in URI

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




2.2.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 valid
ates 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.
S
ome 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 life
time, 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. Va
lid 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)

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
12

of
31



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, op
tional in environment



if specified, this
MUST

be used to derive the value to be used in the JMS header
JMSReplyTo
.


[Definition:
soapjms:t
opicReplyToName
] (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 v
ariant 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
.



2.2.2.1

Setting
AMQP

Message Header properties

This section is non
-
normative and i
s intended to give an example of how a
n AMQP

Message Header
property can be set.

2.2.3

AMQP

Message properties

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

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



Used by th
e 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_targetServi
ce

does not appear.


]

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



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



f
ixed value "1.0" in the implementation,
MUST

appear in a JMS property named
SOAPJMS_bindingVersion
.


[Definition: A fault
MUST

be generate
d with subcode
unrecognizedBindingVersion

if the value of the
soapjms:bindingVersion

property does not match the fixed value.

]

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
13

of
31

[Definiti
on:
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
] [
SO
AP 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 t
he 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 t
he 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 boolea
n JMS
Message property named
SOAPJMS_isFault

with a value of
true
, as in:
Message.setBooleanProperty("SOAPJMS_isFault", true)
.





For rece
ivers, this property is derived from the boolean JMS Message property
named
SOAPJMS_isFault



if present and containing a value of
true
, the value
amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
14

of
31

of
soapjms:isFault

is
true
. I
f 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 cl
ient
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,
jnd
iInitialContextFactory, 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 t
he
SOAPJMS_requestURI

violates the expected syntax.


].



[Definition: A fault
MUST

be generated with subcode
targetServiceNotAllowedInReque
stURI

when
targetService

parameter is
included in the
SOAPJMS_requestURI
).


]

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



Identi
fies 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 "iden
tity" 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 ge
nerated with
subcode
contentEncodingNotSupported

if the encoding values do not match.

]



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


2.2.3.1

Setting
AMQP

Message properties

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

2.2.4

Binding of Properties to URI

The text below is unchanged from the W3C SOAP
-
JMS specification.
S
ome 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]
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
15

of
31

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
env
ironment. 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 defi
nes 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.

Bindi
ng 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

jndiInitialContextF
actory

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

topi
cReplyToName

as
topicReplyToName

query parameter

priority

as
priority

query parameter

targetService

as
targetService

query parameter

timeToLive

as
timeToLive

query parameter


2.2.5

Other Properties

This section describes setting other AMQP properties.

2.3

Authen
tication 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 A
MQP

registry where
AMQP

d
estinations
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 specifica
tion does
not mandate how an implementation might obtain these credentials.


amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
16

of
31

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.

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

correspond
s

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
recei
ving 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 f
irst 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.
[c
onf]


2.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]

http://www.w3.org/2003/05/soap/mep/request
-
response/

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

http://www.w3.org/2006/08/soap/mep/one
-
way/

(defined in [
SOAP12
-
Part3
])

2.5.1

Support for Topic destinations

Topics can be used as destinations for SOAP messages over AMQP. However, d
ue 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.

2.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
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeConte
xt/Role
) of
RequestingSOAPNode
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
17

of
31



A SOAP Node instantiated at the JMS interface can take on the role (i.e. the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
) of
RespondingSOAPNode
.

The remainder of this section consists of des
criptions of the MEP state machine. In the state
descriptions following, the states are defined as values for the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State
.

Failure reasons as specified in the tables represent values of

the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason

-

their values are qualified names. If an implementation enters the "Fail" state, the
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason

property will contain the value specified for the particular transition.

2.6.1

Behavio
r of Requesting SOAP Node


2.6.1.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 ide
ntified 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 sp
ecified

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

JMSReplyT
o

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, an
d use the JMS
Destination object which represents that queue; the queue can be a
temporary queue generated as described in the JMS specification.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
18

of
31

Init State Values

Field

Value Set by Conforming Client

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 JM
S Message property
SOAPJMS_contentType


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

hea
der 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 n
eed 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.


2.6.1.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_co
ntentType
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
19

of
31

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


2.6.1.4

Success and Fail

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

2.6.2

Behavio
r of Responding SOAP Node


2.6.2.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 "Receiv
ing" state.


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

2.6.2.2

Receiving

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

2.6.2.3

Receiving + Sending

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

The mat
erial 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 s
et 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, the
n 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.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
20

of
31

Receiving + Sending State Values

Field

Value Set b
y 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.

JMSCorre
lationID

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_reque
stURI

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 me
ssage then failure reason
transmissionFailure

is set
and a transition to "Fail" is made.


2.6.2.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 complet
ed.

2.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
http://www.w3.org/2006/08/soap/mep/one
-
way/
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
21

of
31

For binding instances conforming to this specification:



A SOAP Node instantiated at the sending AMQP interface takes on the role (i.e. the property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
,
defined in Table 2 in [
SOAP12
-
P
art2
], 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
http://www.w3.org/2003/05/soap/bindingFramework/Excha
ngeContext/Role
) of
ReceivingSOAPNode
.

The remainder of this section consists of descriptions of the MEP. Failure reasons represent values of the
property
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason



their values are qual
ified names. If a MEP instance terminates with a fault, then the
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason

property will contain a value identifying the fault.

2.7.1

Behavio
r of Sending SOAP Node

The message is created as defi
ned 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
http://www.w3.org
/2003/05/soap/bindingFramework/ExchangeContext/FailureReason

property is set to t
ransmissionFailure

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 ident
ified 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

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
22

of
31

Sending SOAP Node Values

Field

Value Set by Conforming Client

SOAPJMS_soapAction

the value of the
soapAction

prop
erty 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 S
OAP 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.7.2

Behavio
r of Receiving SOAP Node

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

2.8

Faults

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



contentTypeMism
atch




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

nam
espace, 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:Envelope


xmlns:env="http://www.w3.org/2003/05/soap
-
envelope"


xmlns
:soapjms="http://www.w3.org/2010/soapjms/"


xmlns:xml="http://www.w3.org/XML/1998/namespace">


<env:Body>

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
23

of
31


<env:Fault>


<env:Code>


<env:Value>env:Sender</env:Value>


<env:Subcode>


<env:Value>soapjms:contentTypeMismatch</env:Value>


</env:Subcode>


</env:Code>


<env:Reason>


<env:Text xml:lang="en">The content type of the JMS payload does


not match the XML.</env:Text>


</env:Reason>


</env:Fault>


</env:Body>

</env:Envelope>

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
fa
ultstring

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

<env:Envelope


xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">


<env:Body
>


<env:Fault xmlns:soapjms="http://www.w3.org/2010/soapjms/">


<faultcode>soapjms:contentTypeMismatch</faultcode>


<faultstring>The content type of the JMS payload does not match
the XML.</faultstring>


</env:Fault>


</en
v:Body>

</env:Envelope>


amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
24

of
31

3

WSDL Usage

What parts are useful?

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

3.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 u
sing 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
].

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



Al
lows 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.3

WSDL 1.1 Ex
tensions Detail

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

This section is normative.

This section describes the optional feature: soapjms:WSDL11
[
http://www.w3.org/2010/soapjms/WSDL11
]. To focus on the salient details, all of the WS
DL
examples in this section show only a portion of a WSDL file in question.

3.3.1

Example

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

The WSDL 1.1 specification includes in section 1.2,
WS
DL 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 a
lso 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
<wsdl11soap11:binding>
, and lines 17
-
22 show the extension properties in the
<wsdl11soap11:binding>
.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
25

of
31

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
<wsdl11soap11::address>
.

Example: WSDL 1.1 JMS Binding

1 <wsdl11:binding name="StockQuoteSoapBinding"
type="tns:StockQuotePortType">

2 <wsdl11soap11:binding style="document"


transport="http://schemas.xmlsoap.org/soap/http"/>

3 <wsdl11:operation name="GetLastTradePrice">

4 <wsdl11soap11:operation
soapAction="http://example.com/GetLastTradePrice
"/>

5 <wsdl11:input>

6 <wsdl11soap11:body use="literal"/>

7 </wsdl11:input>

8 <wsdl11:output>

9 <wsdl11soap11:body use="literal"/>

10 </wsdl11:output>

11 </wsdl11:operation>

12 <
/wsdl11:binding>

13

14 <wsdl11:binding name="StockQuoteSoapJMSBinding"
type="tns:StockQuotePortType"


xmlns:soapjms="http://www.w3.org/2010/soapjms/">

15 <wsdl11soap11:binding style="document"


transport="http://www.w3.o
rg/2010/soapjms/"/>

16

17 <!
--

We want this binding to use a particular CF class
--
>

18 <soapjms:jndiConnectionFactoryName>

19 sample.jms.ConnectionFactory

20 </soapjms:jndiConnectionFactoryName>

21 <!
--

Specify PERSISTENT d
elivery mode
--
>

22 <soapjms:deliveryMode>PERSISTENT</soapjms:deliveryMode>

23

24 <wsdl11:operation name="GetLastTradePrice">

25 <wsdl11soap11:operation
soapAction="http://example.com/GetLastTradePrice"/>

26 <wsdl11:input>

27

<wsdl11soap11:body use="literal"/>

28 </wsdl11:input>

29 <wsdl11:output>

30 <wsdl11soap11:body use="literal"/>

31 </wsdl11:output>

32 </wsdl11:operation>

33 </wsdl11:binding>

34

35 <wsdl11:service na
me="StockQuoteService">

36 <wsdl11:documentation>My first service</wsdl11:documentation>

37 <wsdl11:port name="StockQuotePort"
binding="tns:StockQuoteSoapBinding">

38 <wsdl11soap11:address location="http://example.com/stockquote"/>

39

</wsdl11:port>

40 <wsdl11:port name="StockQuotePort_jms"
binding="tns:StockQuoteSoapJMSBinding">

41 <wsdl11soap11:address
location="jms:jndi:myQueue?targetService=stockquote


&amp;priority=8&amp;repl
yToName=interested&amp;userprop=mystuff"/>

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
26

of
31

42 </wsdl11:port>

43 </wsdl11:service>

The key points to notice are:



The transport URI in
<wsdl11soap11:binding>

(line 15)



The jms: URI in the
<wsdl11soap11:address>

(line 41)



The extension properties in t
he
<wsdl11soap11:binding>

(lines 17
-
22)

3.3.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 se
t to the value
http://www.w3.org/2010/soapjms/
.



Example: SOAP 1.1 Binding for WSDL 1.1 Transport Identification

<wsdl11soap11:binding
style="document"


transport="http://www.w3.org/2010/soapjms/"/>

3.3.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. Thi
s value
corresponds to the property
soapAction
.

3.3.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 propaga
te
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 s
et 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

<wsdl11:binding name="exampleBinding">


...

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
27

of
31


<soapjms:timeToLive>200</soapjms:timeToLive>

</wsdl11:binding>


<wsdl11:service name="exampleService">


<soapjms:jndiInitialContextFactory>


com.example.jndi.InitialContextFactory


</soapjms:jndiInitialContextFactory>


<soapjms:timeTolive>100</soapjms:timeToLive>


...


<wsdl11:port name="quickPort" binding="tns:exampleBinding">


...


<soapjms:timeToLive>10</soapjms:timeToLive>


</wsd
l11:port>


<wsdl11:port name="slowPort" binding="tns:exampleBinding">


...


</wsdl11:port>

</wsdl11:service>

3.3.5

Specifying Properties

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

Some of the above information can be put in the JMS U
RI. 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
<wsdl11soap11:address>

or
<wsdl11soap12:address>

element when using SOAP 1.1 and SOAP 1.2, respectively. The
value of the
location

attribute
MUST

be a URI corresponding t
o 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 p
er normal URI escaping rules, and the resulting URI needs to be encoded
as per normal XML rules ("&amp;" for &) when serialized into an XML attribute.

Example: Specifying WSDL 1.1 Properties Via the JMS URI

<wsdl11:port .... >


<wsdl11soap11:address

location="jms:jndi:destinationName?targetService=service%20Test&amp;priority=
5"/>



</wsdl11:port>

3.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 u
sed in the
context of the WSDL service, port, and binding elements. This specification does not define any use
outside of those elements.

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
28

of
31

4

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

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
29

of
31

Appendix A.

Acknowl
e
dg
me
nts

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 acknow
ledged.

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


Individua
l

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


Indiv
idual

Duane Pauls


Solace Systems

Darryl Pierce


Red Hat

Jonathan Poulter


Kaazing

Sandeep Puri


Cisco Systems

amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
30

of
31

Oleksandr Rudyy


JPMorgan Chase Bank, N.A.

Rafael Schloming


Red Hat

Jakub Scholz


Deutsche Boerse AG

Wolf Tombe


US Department of Homela
nd Security


amqp
-
soap
-
v1.0
-
wd01

Working Draft 01

09

September

2013

Standards Track
Draft

Copyright
©

O
ASIS Open 201
3
. All Rights Reserved.

Page
31

of
31

Appendix B.

Revision History


Revision

Date

Editor

Changes Made

wd01

09 September
2013

Paul Knight

Initial Working Draft based on structure of
[
SOAP
-
JMS
]