![]() |
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
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 © 2005 IMS Global Learning Consortium. All Rights Reserved.
If you wish to copy or distribute this document, you must complete a valid Registered User license registration with IMS and receive an email from IMS granting the license to distribute the specification. 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 Registered Users who have 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 project 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/license.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.
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.
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.
The structure of the rest of this document is:
[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. |
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:
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.
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:
<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.
MAPs define the full set of addressing information that can be attached to a SOAP message. The MAP objects are:
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.
The key terms used in the description of the work-flow are defined in Table 2.1.
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).
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:
Table 3.1 summarizes the set of rules used for the Addressing Profile. Within Table 3.1 the following conventions are used:
Note that in the rules the namespace prefix "wsa" is used. Any consistent prefix may be used.
The usage of IMS GWS Addressing Profile requires the following information to supplied as part of the specification process:
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.
The corresponding IMS GWS SOAP request message produced is (the text shown in bold is specific to the usage of WS-Addressing):
<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-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> |
The relationship of the Addressing Profile to the other IMS GWS profiles is shown in Figure 5.1.
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.
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.
In IMS GWS v2.0 further work will focus on three areas:
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.
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].
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 |
To register any
comments or questions about this specification please
visit:
http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=20 |
The following individuals contributed to the development of this document:
Version No. | Release Date | Comments |
---|---|---|
Final v1.0 |
19 December 2005 |
This is the first
formal version of the Final Release. |
A
Abstract Framework
1,
2,
3
Asynchronous 1, 2
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