IMS Logo

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.


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:

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:

<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:

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

Schematic representation of the web service support for an application
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:

  1. INITIATOR constructs an IMS MESSAGE according to the relevant IMS specification and the WSDL binding guidelines [GWS, 05b];
  2. 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;
  3. SOURCE transmits the IMS MESSAGE through the transport;
  4. IMS MESSAGE is transferred to the DESTINATION;
  5. DESTINATION gets the IMS MESSAGE from the transport;
  6. 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:

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:

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.

Relationship between the Addressing Profile and the other IMS GWS Profiles
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:

  1. The usage of the Addressing Profile with SOAP v1.2 and WSDL v2.0;
  2. Definition of what to do when SOAP faults occur. The current Addressing Profile does not provide specific instructions for handling SOAP fault messages;
  3. 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

To register any comments or questions about this specification please visit: http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=20

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