|
IMS General Web Services
Addressing Profile
Version 1.0 Final
Specification
|
Copyright © 2005 IMS Global
Learning Consortium, Inc. All Rights Reserved.
The IMS Logo is a registered trademark of IMS/GLC
Document Name: IMS General Web Services Addressing Profile
Revision: 19 December 2005
Date Issued:
|
19 December 2005
|
Latest version:
|
http://www.imsglobal.org/gws/gwsv1p0/imsgws_addressProfv1p0.html
|
Register comments or implementations:
|
http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=20
|
|
IPR and Distribution Notices
Recipients of this document are requested to submit,
with
their comments, notification of any relevant patent claims or other
intellectual property rights of which they may be aware that might be
infringed by any implementation
of the specification set forth in this document, and to provide
supporting documentation.
IMS takes no position regarding the validity or scope of
any
intellectual property or other rights that might be claimed to pertain
to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or
might not be available; neither does it represent that it has made any
effort to identify any such rights. Information on IMS's procedures
with respect to rights in IMS specifications can be found at the IMS
Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
Copyright © IMS Global Learning Consortium
2006. All
Rights Reserved.
If you wish to distribute this document or use this
document
to implement a product or service, you must complete a valid license
registration with IMS and receive an email from IMS granting the
license. To register, follow the instructions on the IMS website: http://www.imsglobal.org/specificationdownload.cfm.
This document may be copied and furnished to others by
Licensee organizations registered on the IMS website provided that the
above copyright notice and this paragraph are included on all such
copies. However, this document itself may not be modified in any way,
such as by removing the copyright notice or references to IMS, except
as needed for the purpose of developing IMS specifications, under the
auspices of a chartered IMS work group.
Use of this specification to develop products or
services is
governed by the license with IMS found on the IMS website: http://www.imsglobal.org/gws/gwsv1p0/gwsv1p0speclicense.html.
The limited permissions granted above are perpetual and
will
not be revoked by IMS or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY
WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS
EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE
ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR
ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER
TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE
WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS
SPECIFICATION.
|
Executive
Summary
The
IMS General Web Service (GWS) Base Profile provides a basic structure
for the definition of Web Services used to realize IMS service-oriented
specifications. It consists of a set of non-proprietary Web Services
specifications, along with clarifications and amendments to those
specifications that promote interoperability. The IMS GWS Base Profile
addresses the most common problems experienced when implementing web
service specifications. The IMS GWS Base Profile defines the selection
of mechanisms within referenced specifications that are well
understood, widely implemented and useful.
The
IMS GWS Base Profile promotes interoperability across web
specifications implementations on different software and vendor
platforms. The IMS GWS Base Profile focuses on a core set of web
service specifications and the most common problems experienced
implementing the identified web service specifications. It is not a
goal of the IMS GWS Base Profile to create a plug-and-play architecture
for web services or to guarantee complete interoperability. The IMS GWS
Base Profile addresses interoperability in the application layer, in
particular, the description of behaviors exposed via Web Services.
The
IMS GWS Addressing Profile extends the IMS GWS Base Profile to enable
transport-independent end system addressing. IMS GWS Addressing is
based upon the WS-Addressing recommendations from the World Wide Web
Consortium. WS-Addressing describes two techniques for
transport-independent addressing, namely, Endpoint References (EPR) and
Message Addressing Properties (MAP). Both techniques are compatible
with Web Services Description Language (WSDL). The MAP approach has
been selected for the IMS GWS Addressing Profile as this is based upon
extending the WSDL v1.1 files as opposed to EPR that defines another
external object structure.
Table
of Contents
Executive Summary
1. Introduction
1.1 Scope and
Context
1.2 Structure of
the Primer
1.3 Nomenclature
1.4 References
2. Addressing
Framework
2.1 WS-Addressing
2.1.1
Endpoint References (EPRs)
2.1.2
Message Addressing Properties (MAPs)
2.2 Addressing
Processing Workflow
3. Addressing
Profile Rules
4. WSDL Binding
Implications
5. Relationship
to the Other GWS Profiles
6. Extending the
Addressing Profile
6.1 Proprietary
Extensions
6.2 Further Work
in V2.0
7. Conformance to
the Addressing Profile
Appendix A -
Glossary of Terms
About This
Document
List of
Contributors
Revision History
Index
1.
Introduction
1.1
Scope and Context
The
IMS General Web Services (GWS) Base Profile [GWS, 05a] provides a basic
structure for the definition of Web Services. It consists of a set of
non-proprietary Web Services specifications, along with clarifications
and amendments to those specifications that promote interoperability.
The IMS GWS Base Profile addresses the most common problems experienced
implementing web service specifications. The IMS GWS Base Profile
defines the selection of mechanisms within referenced specifications
that are well understood, widely implemented and useful.
The
IMS GWS Addressing Profile extends the IMS GWS Base Profile to enable
transport-independent end system addressing. IMS GWS Addressing is
based upon the WS-Addressing recommendations from the World Wide Web
Consortium (W3C) [WSA, 05a], [WSA, 05b], [WSA, 05c]. WS-Addressing
describes two techniques for transport-independent addressing, namely,
Endpoint References (EPR) and Message Addressing Properties (MAP). Both
techniques are compatible with the Web Services Description Language
(WSDL) v1.1 [WSDL, 01]. The MAP approach has been selected for the IMS
GWS Addressing Profile as this is based upon extending the WSDL v1.1
files as opposed to EPR that defines another external object structure.
1.2
Structure of the Primer
The
structure of the rest of this document is:
|
2.
Addressing Framework
|
Establishes
the framework for the operation of IMS web services that use
WS-Addressing to support transport-independent end-user addressing;
|
|
3.
Addressing Profile Rules
|
The
statement of the profile rules that must be followed to enable the IMS
Base Profile to be extended to enable transport-independent end-user
addressing;
|
|
4.
WSDL Binding Implications
|
An
explanation of the implications of the Addressing Profile rules on the
IMS specification development methodology (using the IMS Binding
Auto-generation Toolkit) and the WSDL binding that are created;
|
|
5.
Relationship to the Other IMS GWS Profiles
|
Describes
the relationships and dependencies between this profile and the other
IMS GWS profiles;
|
|
6.
Extending the Addressing Profile
|
A
brief discussion of the ways in which the Addressing Profile can be
extended to support proprietary requirements and an indication of
future development for this profile;
|
|
7.
Conformance to the Addressing Profile
|
An
explanation of how conformance for systems that use the Addressing
Profile can be demonstrated;
|
|
Appendix
A Glossary of Terms
|
Definition
of the concepts, terms and technologies used within this document. This
material complements the Abstract Framework Glossary.
|
1.3
Nomenclature
EPR
|
Endpoint Reference
|
HTTP
|
Hypertext Transport Protocol
|
IAF
|
IMS Abstract Framework
|
I-BAT
|
IMS Binding Auto-generation Toolkit
|
MAP
|
Message Addressing Properties
|
MEP
|
Message Exchange Pattern
|
SOAP
|
Simple Object Access Protocol
|
UML
|
Unified Modelling Language
|
URI
|
Universal Resource Identifier
|
URL
|
Universal Resource Locator
|
W3C
|
World Wide Web Consortium
|
WSDL
|
Web Services Description Language
|
WS-I
|
Web Services Interoperability
Organization
|
XML
|
Extensible Mark-up Language
|
XSD
|
XML Schema Definition
|
XSLT
|
Extensible Stylesheet Language
Transformations
|
1.4
References
[AbsGloss, 03]
|
IMS Abstract Framework:
Glossary v1.0, Ed. C.Smythe, IMS/GLC,
July 2003.
|
[GWS, 05a]
|
IMS General Web Services
Base Profile Final Release, C.Schroeder, J.Simon and
C.Smythe, V1.0 IMS/GLC, December 2005.
|
[GWS, 05b]
|
IMS General Web Services
WSDL Binding Guidelines Final Release, C.Schroeder,
J.Simon and C.Smythe, V1.0 IMS/GLC, December
2005.
|
[GWS, 05c]
|
IMS Binding
Auto-generation Toolkit Manual, C.Smythe, V1.0 IMS/GLC,
December 2005.
|
[RFC2119, 97]
|
RFC 2119: Key words for
use in RFC to Indicate Requirement Levels, S.Bradner, IETF,
March 1997.
|
[WSA, 05a]
|
Web Services Addressing
1.0 - Core, M.Gudgin and M.Hadley, W3C
Candidate Recommendation, http://www.w3.org/TR/2005/CR-ws-addr-core-20050817,
August 2005.
|
[WSA, 05b]
|
Web Services Addressing
1.0 - SOAP Binding, M.Gudgin and M.Hadley, W3C
Candidate Recommendation, http://www.w3.org/TR/2005/CR-ws-addr-soap-20050817,
August 2005.
|
[WSA, 05c]
|
Web Services Addressing
1.0 - WSDL Binding, M.Gudgin and M.Hadley, W3C
Working Draft, http://www.w3.org/TR/2005/WD-ws-addr-wsdl-20050413,
April 2005.
|
[WSDL, 01]
|
Web Services Description
Language, http://www.w3.org/TR/2001/NOTE-wsdl-20010315,
Version 1.1, W3C, W3C Note, March 2001.
|
2.
Addressing Framework
2.1
WS-Addressing
The
W3C WS-Addressing recommendation defines a standard for incorporating
message addressing information into Web Services messages.
WS-Addressing provides a uniform addressing method for SOAP messages
traveling over synchronous and/or asynchronous transports.
Additionally, it provides addressing features to help web service
developers build applications around a variety of messaging patterns
beyond the typical exchange of requests and responses. WS-Addressing is
independent of the other WS-* specifications but can be used in
conjunction with them. WS-Addressing extends and incorporates some
concepts from WSDL [WSDL, 01], but there is no explicit dependency
between the two. Web services developers can use either or both,
depending on their needs. WS-Addressing is currently published as three
separate specifications:
- WS-Addressing
Core [WSA, 05a] - defines the abstract properties;
- WS-Addressing
SOAP binding [WSA, 05b] - defines the SOAP binding for WS-Addressing;
- WS-Addressing
WSDL binding [WSA, 05c] - defines the WSDL binding for WS-Addressing;
SOAP
does not provide a standard way to specify where a message is going,
how to return a response, or where to report an error. Those details
have, historically, been left to the transport layer. Addressing at the
transport level is sufficient for many existing services, but it is a
limiting factor in the development of others. WS-Addressing defines
standard ways to route a message over multiple transports or direct a
response to a third party. WS-Addressing is achieved by extending the
SOAP header i.e.
<soap11:Envelope xmlns:soap11="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/03/addressing">
<soap11:Header>
<wsa:MessageID>AVSGEHUWEJIOLIUOMNGG1245</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>http://www.imsglobal.org/myaddress</wsa:Address>
</wsa:ReplyTo>
<wsa:FaultTo>
<wsa:Address>http://www.imsglobal.org/faultaddress</wsa:Address>
</wsa:FaultTo>
<wsa:To>http://www.imsglobal.org/serveraddress</wsa:To>
<wsa:Action>http://www.imsglobal.org/serviceoperationrequest</wsa:Action>
</soap11:Header>
<soap11:Body>
...
<!-- The message body of the SOAP request appears here -->
...
</soap11:Body>
</soap11:Envelope>
WS-Addressing
introduces two new Web Services constructs: Endpoint References (EPRs)
and Message Addressing Properties (MAPs). "Endpoint" is an established
term for a destination at which a Web Service can be accessed. EPRs are
a new model for describing these destinations. MAPs, which may include
one or more endpoint references, provide a context for that destination
information.
2.1.1
Endpoint References (EPRs)
The
WS-Addressing specification introduces a new description element type,
the EPR, with the intent of supporting a set of dynamic usage patterns
not currently appropriately covered by WSDL 1.1. EPRs are defined as a
complex type in the WS-Addressing schema that contains an address (a
URI), reference properties, reference parameters, a port type, a
service name, and policy elements (defined by the WS-Policy
specification). The only required element of an endpoint reference is
the address, so the simplest EPR is:
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">
<wsa:Address>http://www.imsglobal.org/services/myservice</wsa:Address>
</wsa:EndpointReference>
The
other elements of an EPR are optional. The port type and service name
elements are very similar to their WSDL counterparts [GWS, 05a]. WSDL
defines a port type as an identifying name attached to an abstract set
of operations. The port type and service name in a WS-Addressing EPR
provide compatibility with WSDL.
A
significant aspect of an EPR is the ability to attach data from other
XML namespaces using reference properties or reference parameters. Both
of these elements are collections of properties and values that can be
used to incorporate elements from any XML namespace into the EPR. A
reference property is used to identify the endpoint at which a service
is deployed. Two EPRs that share a URI but specify different reference
property values represent two different services. Reference properties
are used to dispatch a request to the appropriate service. For example,
one might deploy two different versions of a service and have requests
specify a target version in their reference parameters. When a service
receives a request and fulfills it, its behavior should not vary in
response to the reference properties. Reference parameters are meant to
identify resources managed by a particular service. Reference
parameters tell a service which resources to handle. They do not
identify the service. Two EPRs with different reference parameters do
refer to the same service.
EPRs
complement and do not replace the WSDL 1.1 <wsdl:service>
element. The EPR is linked to the associated WSDL 1.1 description using
one of two methods:
- External
meta-data reference
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">
<wsa:Address>http://www.imsglobal.org/services/myservice</wsa:Address>
<wsa:Metadata xmlns:wsdli="http://www.w3/org/2005/08/wsdl-instance"
wsdli:wsdlLocation="http://www.imsglobal.org/services/myservice.wsdl">
</wsa:Metadata>
</wsa:EndpointReference>
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">
<wsa:Address>http://www.imsglobal.org/services/myservice</wsa:Address>
<wsa:Metadata>
<wsdl11:definitions targetNamespace=""
...
xmlns:wsdl11="http://schemas.xmlsopa.org/wsdl/">
...
...
<wsdl11:service name="myservicename">
...
...
</wsdl11:service>
</wsdl11:definitions>
</wsa:Metadata>
</wsa:EndpointReference>
Each
EPR must be individually defined and linked to the associated service
and port/interface. At the current time IMS/GLC will not supply the
EPRs as part of the service specification development.
2.1.2
Message Addressing Properties (MAPs)
MAPs
define the full set of addressing information that can be attached to a
SOAP message. The MAP objects are:
- [destination]
: URI (mandatory) - the address of the intended receiver of this
message;
- [recipient]
: EPR (optional) - the intended receiver of this message;
- [source
endpoint] : EPR (optional) - from where the message
originated;
- [reply
endpoint] : EPR (optional) - this identifies the intended
receiver for replies to this message. When formulating a reply message,
the sender SHOULD use the contents of the [reply endpoint] of the
message being replied to formulate the reply message. If the [reply
endpoint] is absent, the sender MAY use the contents of the [source
endpoint] to formulate the reply message. This property may be absent
if the message has no meaningful reply, e.g., is a one-way application
message, or when the reply endpoint has already been communicated to
the target by other means. If the [reply endpoint] contains embedded
policy, that policy must be the complete policy for that endpoint;
- [fault
endpoint] : EPR (optional) - identifies the intended
receiver for faults related to this message. When formulating a fault
message, the sender SHOULD use the contents of the [fault endpoint] of
the message being replied to formulate the fault message. If the [fault
endpoint] is absent, the sender MAY use the contents of the [reply
endpoint] to formulate the fault message. If both the [fault endpoint]
and [reply endpoint] is absent, the sender MAY use the contents of the
[source endpoint] to formulate the fault message. This property may be
absent if the sender cannot receive fault messages (e.g., is a one-way
application message). If the [fault endpoint] contains embedded policy,
that policy must be the complete policy for that endpoint.
- [action]
: URI (mandatory) - an identifier that uniquely (and opaquely)
identifies the semantics implied by this message. It is RECOMMENDED
that the value of the [action] property is a URI corresponding to an
abstract WSDL construct, e.g., message, operation, port type available
at the destination endpoint. In this case, the "relates to" property
determines if the action is a request or response (the "direction" of
the message). It is expected that at least one interoperable URI
encoding scheme for computing an action element from WSDL will be
defined. An action may be associated with the WSDL definition of an
operation using a Policy element. The algorithm used for computing the
action element URI from the WSDL definition of the endpoint may also be
identified using an attached Policy element. Finally, it is possible to
explicitly associate an arbitrary URI with an operation, superceding
all declared encoding algorithms. This provides support to bottom-up
development models;
- [message
id] : URI (optional) - a URI that uniquely identifies this
message in time and space. No two messages may share a [message id]
property. The value of this property is an opaque URI whose
interpretation beyond equivalence is not defined in this specification;
- [relationship]
: (Qname, URI) (0..unbounded) - a pair of values that indicate how this
message relates to another message. The type of the relationship is
identified by a Qname. The related message is identified by a URI that
corresponds to the related message's [message id] property.
- [reference
parameters] : xs:any (0..unbounded) - corresponds to the
value of the reference parameters property of the EPR to which the
message is addressed.
These
properties are inserted into the SOAP header. Different combinations of
properties are used depending on the message exchange pattern. The IMS
GWS Message Exchange patterns (MEPs) are Synchronous, Asynchronous and
Polled. The Synchronous MEP is equivalent to the Request/Response MEP
in the WS-Addressing WSDL Binding [WSA, 05c].
The
MAP approach has been selected for the IMS GWS Addressing Profile as
this is based upon extending the WSDL v1.1 files.
2.2
Addressing Processing Workflow
The
key terms used in the description of the work-flow are defined in Table
2.1.
Table
2.1 Key terms for the workflow description.
| Term
|
Definition
|
INITIATOR
|
An application that consumes a Web
Service by sending SOAP messages and attachments to a RESPONDENT.
|
RESPONDENT
|
An application that exposes a Web
Service and performs processing upon receiving SOAP messages and
attachments from an INITIATOR.
|
MESSAGE
|
An IMS message encapsulated within a
SOAP envelope as referenced in the [GWS, 05b]
|
SOURCE
|
The ENDPOINT that transmits the
MESSAGE to the RESPONDENT
|
DESTINATION
|
The ENDPOINT that receives messages
from the INITIATOR.
|
Note
that INITIATOR and RESPONDENT as used in the rest of the document, are
at a different level of abstraction compared to SOURCE and DESTINATION,
the former belong to the application layer, while the latter belong to
the messaging infrastructure layer and provide services to INITIATORS
and RESPONDENTS (see Figure 2.1).
Figure
2.1 Schematic representation of the web service support for an
application.
The
following is a step-by-step breakdown of a typical workflow for
exchanging IMS MESSAGES that use the GWS Addressing Profile. This
workflow represents a common sequence of tasks. As a result, this
workflow is intended to outline the pertinent tasks and is not
prescriptive as to the sequence of fine-grained steps:
- INITIATOR
constructs an IMS MESSAGE according to the relevant IMS specification
and the WSDL binding guidelines [GWS, 05b];
- The
Web Services Messaging Adapter within the INITIATOR:-
- Constructs
the SOAP message request header according to the service WSDL. The
action value specified in the WSDL is used to construct the
<wsa:Action> header. The <wsa:To> and
<wsa:ReplyTo> endpoint addresses are taken from the
'soap:address/@location' attribute values for the service. The
<wsa:MessageID> value is allocated as per the local
algorithm
- Encapsulates
the IMS MESSAGE in the body of the SOAP message
- Passes
the IMS MESSAGE and any ATTACHMENT to SOURCE;
- SOURCE
transmits the IMS MESSAGE through the transport;
- IMS
MESSAGE is transferred to the DESTINATION;
- DESTINATION
gets the IMS MESSAGE from the transport;
- The
Web Services Messaging Adapter within the RESPONDENT:-
- Decodes
and detaches all ATTACHMENTs attached to the message
- Constructs
the SOAP message response header according to the service WSDL. The
action value specified in the WSDL is used to construct the
<wsa:Action> header. The <wsa:To> and
<wsa:ReplyTo> endpoint addresses are taken from the
'soap:address/@location' attribute values for the service. The
<wsa:MessageID> value is allocated as per the local
algorithm
- Passes
the receipt/response message to the INITIATOR
- RESPONDENT
extracts, validates and processes the IMS MESSAGE and any ATTACHMENT.
3.
Addressing Profile Rules
Table
3.1 summarizes the set of rules used for the Addressing Profile. Within
Table 3.1 the following conventions are used:
- The
keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC2119 [RFC2119, 97];
- Normative
statements in the Profile are presented in the following manner:
RADPnnnnStatement text here, where "nnnn" is
replaced by the statement number. Each statement contains exactly one
requirement level keyword, e.g., "MUST", and one conformance target
keyword, e.g., "MESSAGE".
Note
that in the rules the namespace prefix "wsa" is used. Any consistent
prefix may be used.
Table
3.1 Summary of the IMS GWS Addressing Profile rules.
| Identifier
|
Description
|
Basic
Addressing
|
RADP0001
|
All
messages based upon the IMS GWS Addressing Profile MUST use the
WS-Addressing framework for SOAP-based messages.
The
requirement to use this Profile.
|
RADP0002
|
All
messages based upon the IMS GWS Addressing Profile MUST have a
corresponding WSDL file based upon WSDL v1.1 that contains the relevant
information for the Message Addressing Properties.
This
states that it is the MAP approach within WS-Addressing that must be
supported.
|
RADP0003
|
An
IMS service using the IMS GWS Addressing Profile MAY have Endpoint
Reference definitions which MAY have the associated WSDL file embedded
within the <wsa:Metadata> element.
EPR
may also be used with the MAP approach in WS-Addressing. Embedded WSDL
file approaches are permitted.
|
RADP0004
|
An
IMS service using the IMS GWS Addressing Profile MAY have Endpoint
Reference definitions which MAY have the associated WSDL file
externally referenced by the <wsa:Metadata> element.
EPR
may also be used with the MAP approach in WS-Addressing. Externally
referenced WSDL file approaches are permitted.
|
Synchronous
Message Exchange Pattern - SOAP v1.1 Request Message
|
RADP2001
|
All
Request SOAP messages MUST contain the <wsa:To> header
element.
This
is the EPR for the Destination. The value for this element is the same
as the value of the 'soap:address/@location' attribute in the WSDL file
for the service.
|
RADP2002
|
All
Request SOAP messages MUST contain the <wsa:Action>
header element.
This
element is used by the Destination to identify the semantics of the
input message.
|
RADP2003
|
The
value of the <wsa:Action> header element must be set to
the value of the 'soapAction' attribute as defined in the XPath
'/definitions/binding/operation/soap:operation' element.
This
value is used to identify the input message within the WSDL portType
for the service.
|
RADP2004
|
All
Request SOAP messages MUST contain the <wsa:ReplyTo>
header element.
This
is the EPR for the Source. The value for this element is the same as
the value of the 'soap:address/@location' attribute in the WSDL file
for the service. This is the address to which the Response message will
be sent.
|
RADP2005
|
All
Request SOAP messages MUST contain the <wsa:MessageID>
header element.
This
is unique identifier for the message. The value of this element is the
same as that assigned to the <imsx_messageIdentifier>
element within the IMS GWS SOAP header. This identifier must be unique
for the duration of the communications session. The generation of this
value is left to the implementation but should take the form of
<xs:anyURI>.
|
RADP2006
|
Request
SOAP messages MAY contain other valid WS-Addressing MAP elements.
The
other MAP elements may be used to provide service-specific information.
These service-specific elements will be defined in the associated IMS
service specification.
|
RADP2007
|
Request
SOAP messages MUST NOT use other valid WS-Addressing MAP elements to
redefine the information mandated by this Addressing Profile.
A
service must not redefine the SOAP Request message rules defined in
this Profile by using other MAP elements.
|
RADP2008
|
Duplicate
Response messages MUST NOT result in duplicate information processing
by the Initiator application.
It
is the responsibility of the Source to ensure that duplicate Response
messages do not result in duplication information processing by the
local application(s).
|
Synchronous
Message Exchange Pattern - SOAP v1.1 Response Message
|
RADP4001
|
All
Response SOAP messages MUST contain the <wsa:To> header
element.
This
is the EPR for the Source. The value for this element is the same as
the value of the 'soap:address/@location' attribute in the WSDL file
for the service.
|
RADP4002
|
All
Response SOAP messages MUST contain the <wsa:Action>
header element.
This
element is used by the Source to identify the semantics of the output
message.
|
RADP4003
|
The
value of the <wsa:Action> header element must be set to
the value of the 'soapAction' attribute as defined in the XPath
'definitions/binding/operation/soap:operation' element.
This
value is used to identify the output message within the WSDL portType
for the service.
|
RADP4004
|
All
Response SOAP messages MUST contain the <wsa:MessageID>
header element.
This
is unique identifier for the message. The value of this element is the
same as that assigned to the <imsx_messageIdentifier>
element within the IMS GWS SOAP header. This identifier must be unique
for the duration of the communications session. The generation of this
value is left to the implementation but should take the form of
<xs:anyURI>.
|
RADP4005
|
All
Response SOAP messages MUST contain the <wsa:RelatesTo>
header element.
This
element is used by the Destination to denote that this message is a
response to a previous request message from the Source.
|
RADP4006
|
The
value of the <wsa:RelatesTo> element must be set to the
value of the <wsa:MessageID> element of the Source's
Request message which causes the generation of this Response message.
This
information is used by the Source to correlate the Response message
with the originating Request message.
|
RADP4007
|
The
value of the attribute 'RelationshipType' for the
<wsa:RelatesTo> element MUST be set to
"http://www.w3c.org/2005/08/addressing/reply".
This
identifies the message as a response to a previous request message.
Note that the Source may not be blocked and so it MUST keep a record of
all requests that have not yet had a response.
|
RADP4008
|
Response
SOAP messages MAY contain other valid WS-Addressing MAP elements.
The
other MAP elements may be used to provide service-specific information.
These service-specific elements will be defined in the associated IMS
service specification.
|
RADP4009
|
Response
SOAP messages MUST NOT use other valid WS-Addressing MAP elements to
redefine the information mandated by this Addressing Profile.
A
service must not redefine the SOAP Response message rules defined in
this Profile by using other MAP elements.
|
RADP4010
|
Duplicate
Request messages MUST NOT result in duplicate information processing by
the Respondent application.
It
is the responsibility of the Destination to ensure that duplicate
Request messages do not result in duplication information processing by
the local application(s).
|
WSDL
v1.1 Encodings
|
RADP6001
|
The
IMS GWS Address Profile MAP values MUST be defined using WSDL v1.1.
All
of the WSDL files that conform to WSDL v1.1 must be produced for the
service.
|
RADP6002
|
The
WS-Addressing namespace of "http://www.w3.org/2005/03/addressing' MUST
be used.
The
WS-Addressing namespace used within the WSDL files and the SOAP
messages is defined as http://www.w3c.w3.org/2005/03/addressing.
|
RADP6003
|
The
empty <wsa:UsingAddressing> element with the attribute
'wsdl:required=true' MUST be used in the <wsdl:binding>
element.
This
is used to indicate that WS-Addressing is to be used for this service
binding.
|
RADP6004
|
The
attribute 'wsa:Action' on the XPath
'/definitions/portType/operation/input' element MUST be defined.
This
element is used to supply the value of MAP <wsa:Action>
element for the Request message in the WS-Addressing SOAP header
extension.
|
RADP6005
|
The
value of the attribute 'wsa:Action' for the input structure SHOULD be
defined as:
[AddressLocationRoot][delimiter][portType_name][delimiter][input_message_name].
The
values of this default structure are:
[delimiter]
= '/'
[AddressLocationRoot]
= XPath value of
'definition/service/port/soap:address/soap:address/@location' minus the
last leaf string value (this root value is supplied as part of the IMS
UML Profile and supported by the I-BAT).
[portType_name]
= XPath value of '/definition/portType/@name'
[input_message_name]
= concatenation of XPath value of '/definition/binding/operation/@name'
with the string "Request".
|
RADP6006
|
The
attribute 'wsa:Action' on the XPath
'/definitions/portType/operation/output' element MUST be defined.
This
element is used to supply the value of MAP <wsa:Action>
element for the Response message in the WS-Addressing SOAP header
extension.
|
RADP6007
|
The
value of the attribute 'wsa:Action' for the output structure SHOULD be
defined as:
[AddressLocationRoot][delimiter][portType_name][delimiter][output_message_name].
The
values of this default structure are:
[delimiter]
= '/'
[AddressLocationRoot]
= XPath value of
'definition/service/port/soap:address/soap:address/@location' minus the
last leaf string value (this root value is supplied as part of the IMS
UML Profile and supported by the I-BAT).
[portType_name]
= XPath value of '/definition/portType/@name'
[output_message_name]
= concatenation of XPath value of '/definition/binding/operation/@name'
with the string "Response".
|
4.
WSDL Binding Implications
The
usage of IMS GWS Addressing Profile requires the following information
to supplied as part of the specification process:
- Identification
that the Addressing Profile is to be used.
From
the perspective of the WSDL 1.1 the attachment information is presented
in the WSDL definition part of the file. The transformation files in
the IMS Binding Auto-generation Toolkit (I-BAT) [I-BAT, 05] use the
information supplied in the UML description as described in Table 4.1.
In Table 4.1 each attribute has an example value and for each set of
values there follows the corresponding WSDL file.
Table
4.1 Synchronous single file auto-generation including the Addressing
Profile.
| Attribute
|
Original Value
|
ServiceGroupModel
Attributes
|
Service Group Package Name
|
ExampleGroup
|
WSDLv1.1:NameSpaceRoot
|
http://www.example/services/
|
WSDLv1.1:TargetNameSpaceLeaf
|
wsdlfilev1p0
|
WSDLv1.1:TargetNameSpacePrefix
|
tns
|
WSDLv1.1:AbstractFileNameSpaceLeaf
|
Unused
|
WSDLv1.1:AbstractFileNameSpacePrefix
|
Unused
|
WSDLv1.1:XSDLinkNameSpaceLeaf
|
Unused
|
WSDLv1.1:XSDLinkNameSpacePrefix
|
Unused
|
WSDLv1.1:MessageHdrNameSpaceLeaf
|
Unused
|
WSDLv1.1:MessageHdrNameSpacePrefix
|
Unused
|
WSDLv1.1:WS-Addressing
|
Yes
|
<wsdl11:definitions name = "ExampleGroupSyncServices" targetNamespace = "http://www.example/services/wsdl/sync/wsdlfilev1p0" xmlns:tns = "http://ww.example/services/wsdl/sync/wsdlfilev1p0" xmlns:soap11 = "http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl11 = "http://schemas.xmlsoap.org/wsdl/" xmlns:wsa = "http://www.w3.org/2005/03/addressing" xmlns:xs = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2000/10/XMLSchema-instance">
|
ServiceModel
Attributes
|
Service Package Name
|
EgServiceName
|
SOAPv1.1:AddressLocationRoot
|
http://www.example.soap/serviceuri/
|
SOAPv1.1:OperationActionRoot
|
http://www.example/soap/service/
|
<wsdl11:service name = "EgServiceNameSyncService"> <wsdl11:port name = "CoreOperationsNameSyncSoapPort" binding = "..."> <soap11:address location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/> </wsdl11:port> </wsdl11:service>
|
Interface
Attributes
|
Interface Name
|
CoreOpsName
|
<wsdl11:portType name = "coreOpsNamePortType"> <wsdl11:operation name = "createObject"> <wsdl11:input message = "tns:createObjectRequest" wsa:Action = "http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectRequest"/> <wsdl11:input message = "tns:createObjectResponse" wsa:Action = "http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectResponse"/> </wsdl11:operation> </wsdl11:portType <wsdl11:binding name = "CoreOpsNameSyncSoapBinding" type="tns:CoreOpsNameSyncPortType"> <soap11:binding transport="http://schema.xmlsoap.org/soap/http" style="document"/> <wsa:UsingAddressing wsdl:required = "true"/> <wsdl11:operation name="createObject"> <soap11:operation soapAction="http://www.example/soap/service/createObject" style="document"/> ... </wsdl11:operation> </wsdl11:binding> <wsdl11:service name = "EgServiceNameSyncService"> <wsdl11:port name = "CoreOpsNameSyncSoapPort" binding = "tns:CoreOpsNameSyncSoapBinding"> <soap11:address location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/> </wsdl11:port> </wsdl11:service>
|
DataModel
Attributes
|
NameSpaceRoot
|
Unused
|
NameSpaceLeaf
|
Unused
|
NameSpacePrefix
|
Unused
|
SchemaVersion
|
IMS 1.0
|
QualifiedElements
|
Yes
|
QualifiedAttributes
|
No
|
<wsdl11:types> <xs:schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example/services/wsdl/sync/wsdlfilev1p0" xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2000/10/XMLSchema-instance xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime" version="IMS 1.0" elementFormDefault="qualified" attributeFormDefault="unqualified">
...
</xs:schema> </wsdl11:types>
|
The
corresponding IMS GWS SOAP request message produced is (the text shown
in bold is specific to the usage of WS-Addressing):
SOAP request message
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/03/addressing"> <SOAP-ENV:Header> <wsa:To>http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap</wsa:To> <wsa:Action>http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectRequest </wsa:Action> <wsa:ReplyTo> <wsa:Address>http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap </wsa:Address> </wsa:ReplyTo> <wsa:MessageID>MessageIDSTRINGinitiator</wsa:MessageID> <imsx_syncRequestHeaderInfo xmlns="http://www.imsglobal.org/services/ti/wsdl/sync/sync/wsdlfilev1p0"> <imsx_version>1.0</imsx_version> <imsx_messageIdentifier>MessageIDSTRINGinitiator</imsx_messageIdentifier> </imsx_syncRequestHeaderInfo> </SOAP-ENV:Header> <SOAP-ENV:Body> <createObjectRequest xmlns="http://www.example/services/wsdl/sync/wsdlfilev1p0"> ... </ceateObjectRequest> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
|
The
corresponding IMS GWS SOAP response message produced is (the text shown
in bold is specific to the usage of WS-Addressing):
SOAP response message
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/03/addressing"> <SOAP-ENV:Header> <wsa:To>http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap</wsa:To> <wsa:Action>http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectResponse </wsa:Action> <wsa:MessageID>MessageIDSTRINGrespondent</wsa:MessageID> <wsa:RelatesTo wsa:RelationshipType = "http://www.w3.org/2005/08/adddressing/reply">
MessageIDSTRINGinitiator </wsa:RelatesTo> <imsx_syncResponseHeaderInfo xmlns="http://www.imsglobal.org/services/ti/wsdl/sync/sync/wsdlfilev1p0"> <imsx_version>1.0</imsx_version> <imsx_messageIdentifier>MessageIDSTRINGrespondent</imsx_messageIdentifier> <imsx_statusInfo> ... <imsx_statusInfo> </imsx_syncResponseHeaderInfo> </SOAP-ENV:Header> <SOAP-ENV:Body> <createObjectResponse xmlns="http://www.example/services/wsdl/sync/wsdlfilev1p0"> ... </ceateObjectResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
|
5.
Relationship to the Other GWS Profiles
The
relationship of the Addressing Profile to the other IMS GWS profiles is
shown in Figure 5.1.
Figure
5.1 Relationship between the Addressing Profile and the other IMS GWS
Profiles.
The
Addressing Profile assumes that the Base Profile is already being used
[GWS, 05a]. WS-Security assumes the usage of WS-Addressing and so the
IMS GWS Addressing Profile must be used with the IMS GWS Base Profile
is WS-Security is to be adopted as part of the IMS GWS Security
Profile.
6.
Extending the Addressing Profile
6.1
Proprietary Extensions
Extensions
to the Addressing Profile are restricted to using the reference
parameters element within the MAP. The
<wsa:ReferenceParameters> element should be used to pass
service-specific extension data between the communications web service
entities. The <wsa:ReferenceParameters> element is a SOAP
header extension which can occur any number of times and which can
contain any name-spaced element or attribute.
Any
extensions must be agreed using external mechanisms and services that
do not recognize the extension features should ignore them.
6.2
Further Work in V2.0
In
IMS GWS v2.0 further work will focus on three areas:
- The
usage of the Addressing Profile with SOAP v1.2 and WSDL v2.0;
- Definition
of what to do when SOAP faults occur. The current Addressing Profile
does not provide specific instructions for handling SOAP fault
messages;
- Investigation
of the provision of separate EPR files. This would be an alternative
method to using the current WSDL files to contain all of the
WS-Addressing information. In this approach the WSDL files are either
embedded or referenced using the EPR meta-data element.
7.
Conformance to the Addressing Profile
Any
claim of conformance for an implementation against the Addressing
Profile must show that the implementation complies with the set of
profile rules listed in Section 3.
Apart
from the WS-I Conformance Claims mechanism, the W3C is investigating
the usage of WS-Policy. Therefore, no definitive recommendation is made
on the usage of the WS-I approach. More information on the WS-I
Conformance Claim mechanism is given in the IMS GWS WSDL Binding
Guidelines document [GWS, 05b]. However, if some form of conformance
statement is required then the WS-I approach may be used but no firm
commitment is made to supporting this technique in later releases of
the IMS GWS specification.
Appendix
A - Glossary of Terms
Throughout
the General Web Services documents a variety of key terms, concepts and
descriptions have been introduced. These terms, concepts and
descriptions and defined below but where appropriate the normative
definition from the IAF Glossary is referenced [AbsGloss, 03].
Destination
|
The Endpoint
that receives messages from the Initiator.
|
Endpoint
|
An entity, processor, or resource
that can be referenced and where Web Service messages are originated or
targeted.
|
Endpoint Reference (EPR)
|
An Endpoint Reference is a construct
defined in WS-Addressing that enables the dynamic generation and
customization of service endpoint
descriptions, referencing and description of specific service instances
that are created as the result of state-full interactions, and flexible
and dynamic exchange of endpoint information in tightly coupled
environments where communicating parties share a set of common
assumptions about specific polices or protocols that are used during
the interaction.
|
Initiator
|
An application that consumes a Web
Service by sending SOAP messages and attachments to a Respondent.
|
Message Addressing
Properties (MAP)
|
Message Addressing Properties provide
references for the endpoints involved in an
interaction. The use of these properties to support specific
interactions is in general defined by both the semantics of the
properties themselves and the implicit or explicit contract that
governs the message exchange. If explicitly available, this contract
can take different forms including but not being limited to WSDL MEPs
and interfaces; business processes and e-commerce specifications, among
others, can also be used to define explicit contracts between the
parties.
|
Message Exchange
Pattern (MEP)
|
Message Exchange Patterns describe
the sequence of messages that are exchanged between a Source
and Destination. IMS GWS has three MEPS:
Synchronous, Asynchronous and Polled. The Synchronous MEP is in
effective the request-response message choreography.
|
Respondent
|
An application that exposes a Web
Service and performs processing upon receiving SOAP messages and
attachments from an Initiator.
|
Source
|
The Endpoint
that transmits the messages to the Respondent.
|
WS-Addressing
|
WS-Addressing provides a
transport-neutral mechanisms to address Web services and messages.
Specifically, this specification defines XML elements to identify Web
service endpoints and to secure end-to-end endpoint identification in
messages. This specification enables messaging systems to support
message transmission through networks that include processing nodes
such as endpoint managers, firewalls, and gateways in a
transport-neutral manner.
|
About
This Document
Title
|
IMS General Web Services Addressing
Profile
|
Editor
|
Colin Smythe (IMS)
|
Team Co-Leads
|
Cathy Schroeder (Microsoft Corp.),
James Simon (SUN Microsystems Corp.)
|
Version
|
1.0
|
Version Date
|
19 December 2005
|
Status
|
Final Specification
|
Summary
|
This document contains the
description of the profiling of the WS-Addressing specification from
the World Wide Web Consortium to enhance the IMS General Web Services
Base Profile. WS-Addressing defines an end-point addressing mechanism
that is transport independent.
|
Revision Information
|
19 December 2005
|
Purpose
|
This document is circulated for
public adoption. This document is to be adopted by IMS and all other
organizations that wish to enhance the IMS General Web Services Base
Profile to support WS-Addressing.
|
Document Location
|
http://www.imsglobal.org/gws/gwsv1p0/imsgws_addressProfv1p0.html
|
List
of Contributors
The
following individuals contributed to the development of this document:
| Name
|
Organization
|
Fred Beshears
|
UC Berkeley
|
John Evdemon
|
Microsoft Corp.
|
Ron Kleinman
|
SUN Micrsosystems Corp.
|
Sherman Mohler
|
Cisco Learning Institute, Inc.
|
Cathy Schroeder
|
Microsoft Corp.
|
James Simon
|
SUN Microsystems Corp.
|
Colin Smythe
|
Dunelm Services Ltd.
|
Scott Thorne
|
MIT
|
Revision
History
| Version
No. |
Release
Date |
Comments
|
Final v1.0
|
19 December 2005
|
This is the first formal version of
the Final Release.
|
Index
A
Abstract
Framework 1,
2,
3
Asynchronous
1,
2
B
Base
Profile 1,
2,
3
C
Conformance
1,
2
Context 1
E
Endpoint
Reference 1,
2,
3,
4,
5,
6,
7,
8,
9
I
IMS
Auto-generation Binding Tool 1, 2, 3, 4
IMS
General Web Services 1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15
Addressing
Profile 1,
2,
3,
4,
5,
6,
7,
8
Base
Profile 1,
2,
3,
4,
5,
6
Security
Profile 1
M
Message
Addressing Properties 1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11
Messaging
Asynchronous
1,
2
Polled 1, 2
Synchronous
1,
2,
3,
4,
5
P
Protocols
HTTP 1
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
S
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Synchronous
1,
2,
3,
4,
5
U
Unified
Modelling Language 1,
2,
3,
4
UML 1, 2, 3, 4
W
W3C 1, 2, 3, 4
Web
Services 1,
2,
3,
4,
5,
6
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
WS-Addressing
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15
WSDL 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
WS-Security
1
Web
Services Interoperability Organization 1, 2
WSA 1, 2, 3, 4
WS-Addressing
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15
Endpoint
Reference 1,
2,
3,
4,
5
EPR 1, 2, 3, 4, 5, 6, 7, 8, 9
MAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Message
Addressing Properties 1,
2,
3,
4,
5,
6
WSDL 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
WSDL
Versions
1.1 1, 2, 3
WS-Security
1
X
XML 1, 2, 3
XML Schema
1
XML Schema
Definition 1
XSD 1
XSLT 1
IMS Global Learning
Consortium, Inc. ("IMS/GLC") is publishing the information contained in
this IMS General Web Services Addressing Profile ("Specification")
for purposes of scientific, experimental, and scholarly collaboration
only.
IMS/GLC makes no warranty or representation regarding the accuracy or
completeness of the Specification.
This material is provided on an "As Is" and "As Available" basis.
The Specification is at all times subject to change and revision
without notice.
It is your sole responsibility to evaluate the usefulness, accuracy,
and completeness of the Specification as it relates to you.
IMS/GLC would appreciate receiving your comments and suggestions.
Please contact IMS/GLC through our website at http://www.imsglobal.org
Please refer to Document Name: IMS General Web Services
Addressing Profile Revision: 19 December 2005