IMS General Web Services WSDL Binding Guidelines 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 WSDL Binding Guidelines
Revision: 19 December 2005

Executive Summary

The 'IMS General Web Services WSDL Binding Guideline' document outlines a process for creating web service bindings using the IMS General Web Services Base Profile, Abstract Framework and business domain knowledge intrinsic to the Information Model of a particular Specification. The 'General Web Services WSDL Binding Guideline' contains a description of how a project teams should use the Unified Modelling Language (UML) and Extensible Mark-up Language (XML) style-sheet language auto-generation tools to specify a Web Service protocol and binding as appropriate.

For the auto-generation approach to work the IMS specification must be represented with UML. IMS has created a Web Services description Profile that defines how UML is to be used to describe a web service-based specification. A specification becomes a collection of UML packages. UML packages are used to ensure that the different ways in which UML models are visually presented by different UML tools do not result in tool interoperability issues. Three types of package stereotypes are used:

• Service Group Model - any specification that is service-based must have one and only one 'ServiceGroupModel' package. This package is used to describe the overall set of services being defined;
• Service Model - the service definition package. Any specification that has a ServiceGroupModel' package must have at least one 'ServiceModel'. Each service should have its own 'ServiceModel' package but the set of services are expected to be related to each other;
• Data Model - the data model for the specification, i.e., the information that is to be represented as an XSD. There can be several 'DataModel' packages. In principle each 'DataModel' package will result in the creation of a separate XSD control document.

The IMS General Web Services Basic Profile introduced the approach of separate bindings for different communications models. Therefore, three sets of transformation rules are required, one for each of the communication models that are to be supported by the bindings, namely (at the current time only the Synchronous binding is described herein):

1. Synchronous - the initiator is blocked until the respondent replies;
2. Asynchronous - the initiator is not blocked and so there can be more than one outstanding request;
3. Polled - once the initiator has sent the request the respondent will not reply until it is polled by the initiator.

This Guideline contains a description of how the IMS Binding Auto-generation Tool-kit (I-BAT) is used to create the WSDL/XSD files from the XMI-based description of the specification. The I-BAT is used to create WSDL/XSD bindings that are categorized as:

1. Single file WSDL/XSD representation - the WSDL and XSD descriptions are contained in a single file;
2. Split file representation - the WSDL and XSD descriptions are contained in separate files, i.e., one file for the WSDL and a second file for the XSD;
3. Split service representation - the WSDL and XSD descriptions are contained in separate files, i.e., two files for the WSDL (one for the abstract description and the other for the service specific description) and a third file for the XSD;
4. Multiple file representation - the WSDL descriptions are contained in two files (one for the abstract description and the other for the service specific description) and the XSD is spread over several linked files.

The WSDL/XSD files created are designed to comply with the Web Service Interoperability (WS-I) Consortium Base Profile v1.1. A clear statement of the relationship between the WS-I Base Profile and the IMS General Web Service Basic Profile is described in the IMS GWS Base Profile V1.0 Specification. Furthermore information on how the equivalent WSDL/XSD bindings are created to support the IMS General Web Services extension profiles, e.g., Addressing, Security, Attachments, etc. are supplied in the corresponding profile specifications. This guideline also presents recommendations on how to extend the specification by changing the UML description and re-applying the auto-generation file, and the areas for further work.

Table of Contents

1. Introduction

1.1 Scope and Context

The objective of the General Web Services Web Services Description Language (WSDL) Binding Guidelines activity is to provide a framework for guiding project teams looking to use web services as part of IMS/GLC specification development. The General Web Services WSDL Binding Guidelines provide a methodology that meets the following criteria:

• Interoperability - artefacts produced under the General Web Services activity will seek to identify mechanisms and standards that promote interoperability between web service specification implementations across different software and operating system platform;
• Efficiency - artefacts produced under the General Web Services activity will be designed to help other IMS/GLC project teams efficiently and effectively evaluate web services protocols as they pertain to the functional requirements of the project group;
• Consistency - artefacts produced under the General Web Services activity will be designed to facilitate the implementation of a consistent approach to the implementation of web service protocols across IMS/GLC project groups and specifications;
• Flexibility - artefacts produced under the General Web Services activity will be flexible enough to adapt to the evolving web service protocols such as SOAP and SOAP message attachments, and to work with a variety of binding methods for web services such as WSDL;
• Practicality - artefacts produced under the General Web Services activity will seek to facilitate vendor's ability to implement IMS/GLC based Web Service solutions and interoperability across platforms and vendor implementations of web service protocols.

The General Web Services WSDL Binding Guidelines (GWSWBG) outlines a process for creating web service bindings using the IMS General Web Services Base Profile, IMS Abstract Framework and business knowledge intrinsic to the Information Model of a particular Specification. The GWSWBG includes guidelines that instruct project groups in how to use the recommended tools in gathering information, processing information, and specifying Web Services protocols and binding as appropriate. The methodology includes information and graphics describing the role and relationship of the General Web Services methodology to the IMS/GLC Specifications. The creation of the WSDL binding files is based upon representation of the specification in the UML. The XML Metadata Interchange (XMI) representation of UML is then used to enable the auto-generation. The automated conversion is supplied by applying one or more specially developed Extensible Stylesheet Language Transformations (XSLTs) to the XMI to create the corresponding set of WSDL and Extensible Schema Definition (XSD) files.

This document should be read in conjunction with the General Web Services Base Profile document [GWS, 05b] and the set if extension profiles [GWS, 05c], [GWS, 05d] and [GWS, 05d] and the IMS Binding Auto-generation Toolkit (I-BAT) Manual [GWS, 05e]. The terms of reference for the creation of both documents are defined in the original project charter [GWS, 03].

1.2 Structure of this Document

The structure of this document is:

1.3 Nomenclature

1.4 References

2. Web Services Description Language Files

2.1 WSDL Document Structure

The structure of a WSDLv1.11 document is shown in Figure 2.1.

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definition of endpoints and messages is separated from their concrete network deployment or data format bindings. This allows the reuse of abstract definitions: messages, which are abstract descriptions of the data being exchanged, and port types that are abstract collections of operations. The concrete protocol and data format specifications for a particular port type constitute a reusable binding. A port is defined by associating a network address with a reusable binding and a collection of ports defines a service. Hence, a WSDL document uses the following elements in the definition of network services:

• Types - a container for data type definitions using some type system (such as XSD);
• Message - an abstract, typed definition of the data being communicated. In general there are many message parts;
• Operation - an abstract description of an action supported by the service. In general there are many operations each associated with one or two messages;
• Port Type - an abstract set of operations supported by one or more endpoints. There may be more than one Port Type defined each can have any number of operations;
• Binding - a concrete protocol and data format specification for a particular port type. There is a separate binding for every concrete protocol that is available;
• Port - a single endpoint defined as a combination of a binding and a network address. More than one port may be defined for each service;
• Service - a collection of related endpoints. More than one service can be described in the WSDL file.

It should be noted that WSDLv1.1 supports the following simple message choreographies:

• Single message to the server - in WSDL this is termed 'one-way';
• Single message from the server - in WSDL this is termed 'notification' and is prohibited in the WS-I Basic Profile [WSI, 04a];
• Single message to the server and single response from the server - in WSDL this is termed 'request-response';
• Single message from the server and single response to the server - in WSDL this is termed 'solicit-response' and is prohibited in the WS-I Basic Profile [WSI, 04a].

More complex choreographies have to be constructed using multiple WSDL file-sets with the choreography between the file-sets imposed by an implementation.

2.2 WSDL Schema

2.2.1 Top-level Structure (<definitions>)

The top level XSD for the WSDL schema is shown in Figure 2.2.

There are three approaches to the creation of the WSDL description:

1. Single file - the creation of a single WSDL file that contains all of the WSDL and XSD definitions;
2. Split files - the creation of a single WSDL file and single XSD file. The XSD is linked to the WSDL file by the usage of an <xsd:import> statement in the <wsdl:type> element in the WSDL file;
3. Service split files - the creation of a service specific WSDL file, an abstract definitions WSDL file and a single XSD file. The WSDL files are linked using the <wsdl:import> statement in the service specific WSDL file. The XSD file is linked using the <xsd:import> statement in the <wsdl:type> element in the abstract definitions WSDL file;
4. Multiple files - the creation of a service specific WSDL file, an abstract definitions WSDL file and one or more XSD files. The WSDL files are linked using the <wsdl:import> statement in the service specific WSDL file. The root XSD file is linked using the <xsd:import> statement in the <wsdl:type> element in the abstract definitions WSDL file.

2.2.2 <import> Element Structure

The <import> schema structure is shown in Figure 2.3. The <import> is used to enable a WSDL description to be defined in several linked physical files. IMS will use the <import> element to link the abstract definition file to the specific service file, i.e., the specific service file imports the abstract definitions file.

2.2.3 <types> Element Structure

The <type> schema structure is shown in Figure 2.4. The <type> Element is used within the single WSDL or abstract definitions file to link to the associated XSD files. These XSD files will contain the XML definitions of the SOAP structures.

2.2.4 <message> Element Structure

The <message> schema structure is shown in Figure 2.5. This element is used within the single WSDL or the abstract definitions file to define the set of messages that are used to exchange the information for a particular operation. The <part> elements are used to define the message header and body parts.

2.2.5 <portType> Element Structure

The <portType> schema structure is shown in Figure 2.6. The <portType> element is used within the abstract definitions file to identify the messages used to represent an operation. In a single abstract definition structure an operation can have at most one input message (from the client to the server) and one output message (from the server to the client).

2.2.6 <binding> Element Structure

The <binding> schema structure is shown in Figure 2.7. The <binding> element is used within the single WSDL or the specific service file to bind the abstract message definitions to a particular transport mechanism. In the case of the IMS GWS the transport system is SOAPv1.1/HTTPv1.1; no other bindings are supported.

2.2.7 <service> Element Structure

The <service> element is used within the single WSDL or the specific service file to represent a collection of port elements, where each port represents the availability of binding at a particular endpoint. The 'binding' attribute of the port element ties it to the corresponding binding element (see sub-section 2.2.6).

2.3 Basic WSDL File Content

2.3.1 Single File Representation

This is a single file containing the WSDL and XSD information. The basic structure of an integrated WSDL document is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
0033
0034
0035
0036
0037
0038
0039
0040
0042
0043
0044
0045
0046
0047
0048
0049
0050
0051
0052
0053
0054
0055
0056
0057
0058

<?xml version = "1.0" encoding = "UTF-8"?>
<wsdl:definitions name = "??" targetNamespace = "??">
   <wsdl:types>
      <xsd:schema>
         ...
      </xsd:schema>            
   </wsdl:types>
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   ...
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   <wsdl:portType name = "??">
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
      ...
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
   </wsdl:portType>
   ...
   <wsdl:portType name = "??">
      ...
   </wsdl:portType>
   <wsdl:binding name = "??" type= "??">
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
   </wsdl:binding>
   ...
   <wsdl:binding name = "??" type= "??">
      ...
   </wsdl:binding>
   <wsdl:service name = "??">
      <wsdl:port name="??" binding= "??"/>
         ...
      <wsdl:port name="??" binding= "??"/>
   </wsdl:service>
   ...
   <wsdl:service name = "??">
      ...
   </wsdl:service>
</wsdl:definitions>

2.3.2 Split File Representation

This is the separation of the WSDL and XSD into two separate files. The basic structure of the WSDL document is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
0033
0034
0035
0036
0037
0038
0039
0040
0042
0043
0044
0045
0046
0047
0048
0049
0050
0051
0052
0053
0054
0055
0056
0057
0058
      

<?xml version = "1.0" encoding = "UTF-8"?>
<wsdl:definitions name = "??" targetNamespace = "??">
   <wsdl:types>
      <xsd:schema>
         <xsd:import namespace = "??" schemaLocation = "??"/>
      </xsd:schema>
   </wsdl:types>
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   ...
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   <wsdl:portType name = "??">
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
      ...
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
   </wsdl:portType>
   ...
   <wsdl:portType name = "??">
      ...
   </wsdl:portType>
   <wsdl:binding name = "??" type= "??">
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
   </wsdl:binding>
   ...
   <wsdl:binding name = "??" type= "??">
      ...
   </wsdl:binding>
   <wsdl:service name = "??">
      <wsdl:port name="??" binding= "??"/>
         ...
      <wsdl:port name="??" binding= "??"/>
   </wsdl:service>
   ...
   <wsdl:service name = "??">
      ...
   </wsdl:service>
</wsdl:definitions>
      

The associated XSD file structure that is linked using the <xsd:import> statement (line 5 - in the shaded region) in the WSDL file is:

0001
0002
0003
0004

<?xml version = "1.0" encoding = "UTF-8"?>
<xsd:schema>
   ...
</xsd:schema>

2.3.3 Service Split File Representation

This is the separation of the WSDL into two files (abstract definitions and service specific files) and the XSD as a single file. For the IMS GWS the recommended composition for the Abstract Definitions File is:

code

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
      

<?xml version = "1.0" encoding = "UTF-8"?>
<wsdl:definitions name = "??" targetNamespace = "??">
   <wsdl:types>
      <xsd:schema>
         <xsd:import namespace = "??" schemaLocation = "??"/>
      </xsd:schema>
   </wsdl:types>
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   ...
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   <wsdl:portType name = "??">
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
      ...
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
   </wsdl:portType>
   ...
   <wsdl:portType name = "??">
      ...
   </wsdl:portType>
</wsdl:definitions>
      

For the IMS GWS the recommended composition for the Specific Service File is (the link to the abstract definitions file is achieved using the '<wsdl:import> statement in line 3 - see the shaded region):

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
      

<?xml version = "1.0" encoding = "UTF-8"?>
<wsdl:definitions name = "??" targetNamespace = "??">
   <wsdl:import namespace = "??" location = "??"/>
   <wsdl:binding name = "??" type= "??">
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
   </wsdl:binding>
   ...
   <wsdl:binding name = "??" type= "??">
      ...
   </wsdl:binding>
   <wsdl:service name = "??">
      <wsdl:port name="??" binding= "??"/>
         ...
      <wsdl:port name="??" binding= "??"/>
   </wsdl:service>
   ...
   <wsdl:service name = "??">
      ...
   </wsdl:service>
</wsdl:definitions>
      

Each of the associated XSD file structures that are linked using the <xsd:import> statement (lines 5 to 7 - see the shaded region) in the abstract data definitions WSDL file have the structure:

0001
0002
0003
0004

<?xml version = "1.0" encoding = "UTF-8"?>
<xsd:schema>
   ...
</xsd:schema>

2.3.4 Multiple File Representation

This is the separation of the WSDL into two files (abstract definitions and service specific files) and one or more XSD files as required. For the IMS GWS the recommended composition for the Abstract Definitions File is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
0033
0034
      

<?xml version = "1.0" encoding = "UTF-8"?>
<wsdl:definitions name = "??" targetNamespace = "??">
   <wsdl:types>
      <xsd:schema>
         <xsd:import namespace = "??" schemaLocation = "??"/>
         ...
         <xsd:import namespace = "??" schemaLocation = "??"/>
      </xsd:schema>
   </wsdl:types>
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   ...
   <wsdl:message name = "??">
      <wsdl:part name = "??" element = "??"/>
   </wsdl:message>
   <wsdl:portType name = "??">
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
      ...
      <wsdl:operation name = "??">
         <wsdl:input message = "??"/>
         <wsdl:output message = "??"/>
         <wsdl:fault message = "??" name = "??"/>
      </wsdl:operation>
   </wsdl:portType>
   ...
   <wsdl:portType name = "??">
      ...
   </wsdl:portType>
</wsdl:definitions>
      

For the IMS GWS the recommended composition for the Specific Service File is (the link to the abstract definitions file is achieved using the <wsdl:import> statement in line 3 - see the shaded region):

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
      

<?xml version = "1.0" encoding = "UTF-8"?>
<wsdl:definitions name = "??" targetNamespace = "??">
   <wsdl:import namespace = "??" location = "??"/>
   <wsdl:binding name = "??" type= "??">
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
      <wsdl:operation name = "??">
         <wsdl:input/>
         <wsdl:output/>
         <wsdl:fault name = "??"/>
      </wsdl:operation>
   </wsdl:binding>
   ...
   <wsdl:binding name = "??" type= "??">
      ...
   </wsdl:binding>
   <wsdl:service name = "??">
      <wsdl:port name="??" binding= "??"/>
         ...
      <wsdl:port name="??" binding= "??"/>
   </wsdl:service>
   ...
   <wsdl:service name = "??">
      ...
   </wsdl:service>
</wsdl:definitions>
      

Each of the associated XSD file structures that are linked using the <xsd:import> statement (lines 5 to 7 - see the shaded region) in the abstract data definitions WSDL file have the structure:

0001
0002
0003
0004

<?xml version = "1.0" encoding = "UTF-8"?>
<xsd:schema>
   ...
</xsd:schema>

2.3.5 Structure Relationships and Naming Conventions

The Types, Message, Operation, Port Type, Binding, Port and Service elements in the set of WSDL files have strict relationships. To make these relationships we propose a naming convention. The default target namespace is allocated a prefix of 'tns:'. The naming conventions introduced here are further refined in Section 5.

2.3.5.1 Service Definitions

Several services can be defined. Each Service will be given a unique name and will have the string 'Service' at the end. An example of the WSDL is:

0001
0002
0003
0004
0005
0006

<wsdl:definitions>
   ...
   <wsdl:service name = "PackagingService">
      ...
   </wsdl:service>
</wsdl:definitions>

2.3.5.2 Port Definitions

Several ports can be defined for each service. The Port associates a binding with a network address. Ports that are bound to the same Port Type are treated as alternatives, i.e., two ports could be defined for the same Port Type but one port would use a SOAP binding and the other a HTTP-Post binding. Each Port will have a unique name and will have the string 'Port' at the end. The binding identified in the <wsdl:port> declaration must be defined elsewhere in the WSDL using the <wsdl:binding> element. An example of the WSDL is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014

<wsdl:definitions>
   ...   
   <wsdl:service name = "PackagingService">
      <wsdl:port name = "Packaging1SoapPort" binding = "tns:OpSet1SoapBinding">
         ...
      </wsdl:port>
      <wsdl:port name = "Packaging2SoapPort" binding = "tns:OpSet2SoapBinding">
         ...
      </wsdl:port>
      <wsdl:port name = "PackagingPostPort" binding = "tns:OpSet1PostBinding">
         ...
      </wsdl:port>
   </wsdl:service>
</wsdl:definitions>

2.3.5.3 Binding Definitions

Every Port Type must have at least one binding. The binding defines the concrete protocol and data format for a particular Port Type. Each binding must have a unique name and will have the string 'Binding' at the end. The Port Type identified in the <wsdl:binding> element must be defined elsewhere n the WSDL using the <wsdl:portType> element. An example of the WSDL is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013

<wsdl:definitions>
   ...   
   <wsdl:binding name = "OpSet1SoapBinding" type "tns:OpSet1PortType>
      ...
   </wsdl:binding>
   <wsdl:binding name = "OpSet2SoapBinding" type "tns:OpSet2PortType>
      ...
   </wsdl:binding>
   <wsdl:binding name = "OpSet1PostBinding" type "tns:OpSet1PortType>
      ...
   </wsdl:binding>
   ...
</wsdl:definitions>

Note that for every binding name there must be an associated port usage (note the shaded words in the 'Port Definitions' and 'Binding Definitions' examples.

2.3.5.4 Port Type Definitions

The Port Type is an abstract set of operations supported by one or more end points. Each Port Type must have a unique name and will have the string 'PortType' at the end. An example of the WSDL is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010

<wsdl:definitions>
   ...   
   <wsdl:portType name = "OpSet1PortType">
      ...
   </wsdl: portType >
   <wsdl:portType name = "OpSet2PortType">
      ...
   </wsdl:portType>
   ...
</wsdl:definitions>

Note that every Port Type must be used in a binding. The relationship between the 'Port Type Definitions' and the 'Binding Definitions' is shown by the underlined phrases in the corresponding examples.

2.3.5.5 Operation Definitions

An operation is an abstract description of an action supported by the service. Operations are associated with a Port Type. Each operation within a Port Type must have a unique name and this name should be representative of the functional nature of the operation. An example of the WSDL is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022

<wsdl:definitions>
   ...   
   <wsdl:portType name = "OpSet1PortType">
      <wsdl:operation name = "createObject">
         ...
      </wsdl:operation>
      ...
      <wsdl:operation name = "deleteObject">
         ...
      </wsdl:operation>
   </wsdl: portType >
   <wsdl:portType name = "OpSet2PortType">
      <wsdl:operation name = "compressObjects">
         ...
      </wsdl:operation>
      ...
      <wsdl:operation name = "expandObjects">
         ...
      </wsdl:operation>
   </wsdl:portType>
   ...
</wsdl:definitions>

2.3.5.6 Message Definitions

A message is the abstract construct of the information being communicated. Messages are used to communicate the activity of the corresponding operations. The number of messages per operation depends upon the choreography for the service is 'one-way', 'request-response', solicit-response' or 'notification'. For the 'request-response' choreography the naming convention for the two messages is to take the name of the operation and append the string 'Request' for the message to the endpoint and the string 'Response' for the message from the end point. The example WSDL is:

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027
0028
0029
0030
0031
0032
0033
0034
0035
0036
0037
0038
0039
0040
0041
0042
0043
0044
0045
0046
0047
0048
0049
0050
0051

<wsdl:definitions>
   ...
   <wsdl:message name = "createObjectRequest">
      ...
   </wsdl:message>
   <wsdl:message name = "createObjectResponse">
      ...
   </message>
   <wsdl:message name = "deleteObjectRequest">
      ...
   </wsdl:message>
   <wsdl:message name = "deleteObjectResponse">
      ...
   </wsdl:message>
   <wsdl:message name = "compressObjectRequest">
      ...
   </wsdl:message>
   <wsdl:message name = "compressObjectResponse">
      ...
   </wsdl:message>
   <wsdl:message name = "expandObjectRequest">
      ...
   </wsdl:message>
   <wsdl:message name = "expandObjectResponse">
      ...
   </wsdl:message>
   ...
   <wsdl:portType name = "OpSet1PortType">
      <wsdl:operation name = "createObject">
         <wsdl:input message = "tns:createObjectRequest">
         <wsdl:output message = "tns:createObjectResponse">
      </wsdl:operation>
      ...
      <wsdl:operation name = "deleteObject">
         <wsdl:input message = "tns:deleteObjectRequest">
         <wsdl:output message = "tns:deleteObjectResponse">
      </wsdl:operation>
   </wsdl: portType >
   <wsdl:portType name = "OpSet2PortType">
      <wsdl:operation name = "compressObjects">
         <wsdl:input message = "tns:compressObjectRequest">
         <wsdl:output message = "tns:compressObjectResponse">
      </wsdl:operation>
      ...
      <wsdl:operation name = "expandObjects">
         <wsdl:input message = "tns:expandObjectRequest">
         <wsdl:output message = "tns:expandObjectResponse">
      </operation>
   </wsdl:portType>
   ...
</wsdl:definitions>

Note that the message descriptions are linked to the operation descriptions and every message must be used in at least one operation. In the WSDL example above the naming convention is shown by the shaded and underlined phrases.

2.4 WS-I Basic Profile

The WS-I Basic Profile 1.1 [WSI, 04a] consists of a set of non-proprietary Web services specifications, plus clarifications, refinements, interpretations and amplifications of those specifications which promote interoperability. The Profile was developed according to a set of principles that, together, form the philosophy of the Profile, as it relates to bringing about interoperability. The principles are:

1. No guarantee of interoperability - it is impossible to completely guarantee the interoperability of a particular service. However, the Profile does address the most common problems that implementation experience has revealed to date;
2. Application semantics - although communication of application semantics can be facilitated by the technologies that comprise the Profile, assuring the common understanding of those semantics is not addressed by it;
3. Testability - when possible, the Profile makes statements that are testable. However, such testability is not required. Preferably, testing is achieved in a non-intrusive manner, e.g., examining artifacts "on the wire";
4. Strength of requirements - the Profile makes strong requirements, e.g., MUST, MUST NOT, wherever feasible; if there are legitimate cases where such a requirement cannot be met, conditional requirements, e.g., SHOULD, SHOULD NOT, are used. Optional and conditional requirements introduce ambiguity and mismatches between implementations;
5. Restriction vs. relaxation - when amplifying the requirements of referenced specifications, the Profile may restrict them, but does not relax them, e.g., change a MUST to a MAY;
6. Multiple mechanisms - if a referenced specification allows multiple mechanisms to be used interchangeably, the Profile selects those that are well understood, widely implemented and useful. Extraneous or underspecified mechanisms and extensions introduce complexity and therefore reduce interoperability;
7. Future compatibility - when possible, the Profile aligns its requirements with in-progress revisions to the specifications it references. This aids implementers by enabling a graceful transition, and assures that WS-I does not 'fork' from these efforts. When the Profile cannot address an issue in a specification it references, this information is communicated to the appropriate body to assure its consideration;
8. Compatibility with deployed services - backwards compatibility with deployed Web services is not a goal for the Profile, but due consideration is given to it. The Profile does not introduce a change to the requirements of a referenced specification unless doing so addresses specific interoperability issues;
9. Focus on interoperability - although there are potentially a number of inconsistencies and design flaws in the referenced specifications, the Profile only addresses those that affect interoperability;
10. Conformance targets - where possible, the Profile places requirements on artifacts, e.g., WSDL descriptions, SOAP messages, rather than the producing or consuming software's behaviors or roles. Artifacts are concrete, making them easier to verify and therefore making conformance easier to understand and less error-prone;
11. Lower-layer interoperability - the Profile speaks to interoperability at the application layer; it assumes that interoperability of lower-layer protocols, e.g., TCP/IP , Ethernet, is adequate and well understood. Similarly, statements about application-layer substrate protocols (e.g., SSL /TLS , HTTP) are only made when there is an issue affecting Web services, specifically, WS-I does not attempt to assure the interoperability of these protocols as a whole. This assures that WS-I's expertise in and focus on Web services standards is used effectively.

The IMS GWS Base Profile [GWS, 05a] is heavily based upon the WS-I Basic Profile v1.1 [WSI, 04a] and the WS-I simple SOAP binding Profile v1.0 [WSI, 04d]. There are some points where the IMS GWS Base Profile differs from the WS-I equivalent. These differences are identified in Section 3 of [GWS, 05a].

3. WSDL Files for the Set of Communications Models

Three sets of transformation rules are required, one for each of the communication models that are to be supported by the bindings. The three communication models are:

• Synchronous - the initiator is blocked until the respondent replies;
• Asynchronous - the initiator is not blocked and so there can be more than one outstanding request;
• Polled - once the initiator has sent the request the respondent will not reply until it is polled by the initiator.

3.1 Synchronous Communications Transformation Algorithms

3.1.1 Single File Representation

The transformation algorithm is used to create the single file WSDL/XSD representation shown in Figure 3.1.

The binding files described in Figure 3.1 contain:

• 'SyncSinglev1p0.wsdl' - the full WSDL and associated XSD definitions. The service will use SOAP/http;
• The two shaded files are the W3C WSDL and SOAP XSDs.

The name space prefixes used within this binding are listed in Table 3.1.

3.1.2 Split File Representation

The transformation algorithm is used to create the single WSDL and single XSD files representation shown in Figure 3.2.

The binding files described in Figure 3.2 contain:

• 'SyncWSDLv1p0.wsdl' - the service specific and abstract definitions WSDL binding file. For a particular Service this is based upon SOAP/http. This file imports the message and data XSD using the <xsd:import> construct;
• 'SyncXSDv1p0.wsdl' - the XSD definitions. This includes the synchronous message body and header definitions and the data schema. This file must be created for each synchronous service binding.
• The two shaded files are the W3C WSDL and SOAP XSDs.

The name space prefixes used within this binding are listed in Table 3.2.

3.1.3 Service Split File Representation

The transformation algorithm is used to create the service specific and abstract definition WSDL and single XSD files shown in Figure 3.3.

The binding files described in Figure 3.3 contain:

• 'ServiceSyncv1p0.wsdl' - the service specific WSDL binding file. For a particular Service this is based upon SOAP/http. This file imports the abstract definitions using the <wsdl:import> construct. This file must be created for each synchronous service binding;
• 'AbstractSyncv1p0.wsdl' - the abstract message definitions that represent the behavior of a particular Service and its operations. This file imports the message XSD using the <xsd:import> construct. This file must be created for each synchronous service binding;
• 'SyncXSDv1p0.wsdl' - the XSD definitions. This includes the synchronous message body and header definitions and the data schema. This file must be created for each synchronous service binding.
• The two shaded files are the W3C WSDL and SOAP XSDs.

The name space prefixes used within this binding are listed in Table 3.3.

3.1.4 Multiple File Representation

The transformation algorithm is used to create the multiple WSDL and XSD files shown in Figure 3.4. The binding files described in Figure 3.4 contain:

• 'ServiceSyncv1p0.wsdl' - the service specific WSDL binding file. For a particular Service this is based upon SOAP/http. This file imports the abstract definitions using the <wsdl:import> construct. This file must be created for each synchronous service binding;
• 'AbstractSyncv1p0.wsdl' - the abstract message definitions that represent the behavior of a particular Service and its operations. This file imports the message XSD using the <xsd:import> construct. This file must be created for each synchronous service binding;
• 'MessSchemav1p0.xsd' - the XSD definitions for the synchronous messages. This file imports the appropriate data model XSD using the <xsd:import> construct. This file must be created for each synchronous service binding;
• 'DataSchemav1p0.xsd' - the definition of the particular Service data model. This file must be created for each service binding. The same data model is used for the synchronous, polled and asynchronous bindings;
• 'MessBindSchemav1p0.xsd' - the XSD binding of the message header parts. This includes the message headers for synchronous, polled and asynchronous message models. This file is used for all of the binding transformation rules independent of the type of communications model being supported (see Appendix A for the structure and content of this file);
• 'CommonSchemav1p0.xsd' - the XSD binding of the IMS common data objects. This file is available to the Service data model XSDs as well as the IMS message binding XSD. The content of this file does not change between Service definitions;
• 'wsiwsdlv1p1.xsd' - this is the reference XSD for the WSDL definition. This file is the WS-I amended version of the original file from W3C;
• 'wsisoapv1p1.xsd' - this is the reference XSD for the SOAP extensions to WSDL. This file is from WS-I.

The separation of the 'Service Specific' and 'Abstract Definition' files means that a new Service Specific binding can be created without changing the Abstract Definition. The Abstract Definition describes the behaviors in the UML model whereas the Service Specific file is responsible for binding these to the required transport protocol (in this document this is SOAP/http).

The name space prefixes used within these bindings are listed in Table 3.4.

3.2 Asynchronous Communications Transformation Algorithms

At the current time IMS has not authorized the publication of the Asynchronous Communications transformation algorithms as Final Release. This is because there are no validated implementations of this technique and there is work underway in W3C that could result in that IMS approach becoming proprietary. This work remains published as Public Draft material [GWS, 05a].

3.3 Polled Communications Transformation Algorithms

At the current time IMS has not authorized the publication of the Polled Communications transformation algorithms as Final Release. This is because there are no validated implementations of this technique and there is work underway in W3C that could result in that IMS approach becoming proprietary. This work remains published as Public Draft material [GWS, 05a].

4. Creating a WSDL Binding

The process for creating a WSDL binding based upon the IMS GWS Base Profile is:

1. The Information Model must be defined using the IMS Service UML Profile [GWS, 05f]. This profile describes how UML must be used to create a description of the specification that can be used by the IMS auto-generation tools. Note that the specification is created without explicit identification of the type of communications model to be supported by the binding, i.e., the nature of the communication model supported is defined when the binding is created;
2. The UML description must be made available as an XMI file, i.e., this is an XML instance that conforms to the XMI specification. At the present time only XMI files that have been created by the Poseidon tool, v2.5 or later, are valid. The Poseidon tool creates a '.zuml' file that must be unzipped and the XMI file within used as input to the I-BAT;
3. The XMI file is now used as input to the I-BAT. The XSL file 'UMLtoWSDLTransform.xsl' is applied to the XMI file, using an appropriate XSLT tool (Oxygen is the tool recommended by IMS) to generate the WSDL files. The XSL files automatically create the full set of WSDL files using a predetermined naming convention for the corresponding directory structure, the name(s) of the services and the communications model. The generation process also creates a validation report text file that can be used to identify any problems that the I-BAT found while creating the binding files.

The following points should be noted when using the I-BAT:

• The I-BAT will attempt to generate the binding files irrespective of any problems described in the validation report;
• The I-BAT cannot be used to correct problems with the UML description. Any problems in the Information Model must be corrected using the appropriate UML authoring tool. The binding creation process must then be repeated using the new XMI file;
• Any hand edits of the WSDL/XSD files will be lost when new binding files are created.

5. Base Profile WSDL Auto-generation

5.1 WSDL Auto-generation for Synchronous Communications

5.1.1 Single File Representation

The auto-generation files used to create the single file WSDL/XSD representation are shown in Figure 5.1.

The transformation files are used to:

• 'UMLtoWSDLTransform.xsl' - to generate the single full WSDL/XSD file from the XMI representation of the UML-based description of the specification;
• 'WSDLtoHTML.xsl' - to generate a HTML file that contains the description of the WSDL services described in the single WSDL file.

Details of these XSL files are given in I-BAT [GWS, 05f].

The transformation files use the information supplied in the UML description as described in Table 5.1. In Table 5.1 each attribute has an example value and for each set of values there follows the corresponding WSDL file. All of the attribute values are used in the single WSDL/XSD file.

<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:xs = "http://www.w3.org/2001/XMLSchema" 
   xmlns:xsi = "http://www.w3.org/2000/10/XMLSchema-instance">

<wsdl11:service name = "EgServiceNameSyncService">
   <wsdl11:port name = "CoreOperationsNameSyncSoapPort" binding = "...">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl11:port>
</wsdl11:service>

<wsdl11:binding name="CoreOperationsNameSyncSoapBinding" 
          type="tns: CoreOperationsNameSyncPortType">
   <soap11:binding transport="http://schema.xmlsoap.org/soap/http" style="document"/>
   <wsdl11:operation name="createObject">
      <soap11:operation soapAction="http://www.example/soap/service/createObject" 
         style="document"/>
      ...
   </wsdl11:operation>
   <wsdl11:operation name="replaceObject">
      <soap11:operation soapAction="http://www.example/soap/service/replaceObject" 
         style="document"/>
      ...
   </wsdl11:operation>
</wsdl11:binding>
<wsdl11:service name = "EgServiceNameSyncService">
   <wsdl11:port name = "CoreOperationsNameSyncSoapPort" 
            binding = "tns:CoreOperationsNameSyncSoapBinding">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl11:port>
</wsdl11:service>

<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"
      version="IMS 1.0"
      elementFormDefault="qualified"
      attributeFormDefault="unqualified">
   </xs:schema>
</wsdl11:types>

5.1.2 Split File Representation

The auto-generation files used to create the split file WSDL/XSD representation are shown in Figure 5.2.

The transformation files are used to:

• 'UMLtoWSDLTransform.xsl' - to generate the single full WSDL and XSD files from the XMI representation of the UML-based description of the specification;
• 'WSDLtoHTML.xsl' - to generate a HTML file that contains the description of the WSDL services described in the single WSDL file.

Details of these XSL files are given in I-BAT [GWS, 05f].

The transformation files use the information supplied in the UML description as described in Tables 5.2 and 5.3. In Tables 5.2 and 5.3 each attribute has an example value and for each set of values there follows the corresponding WSDL file. All of the attribute values are used in the split WSDL and XSD files.

<wsdl: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:wsdl ="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xsd = "http://www.w3.org/2001/XMLSchema" 
   xmlns:xsi = "http://www.w3.org/2000/10/XMLSchema-instance">

<wsdl:service name = "EgServiceNameSyncService">
   <wsdl:port name = "CoreOperationsNameSyncSoapPort" binding = "...">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl:port>
</wsdl:service>

<wsdl:binding name="CoreOperationsNameSyncSoapBinding" 
          type="tns: CoreOperationsNameSyncPortType">
   <soap11:binding transport="http://schema.xmlsoap.org/soap/http" style="document"/>
   <wsdl:operation name="createObject">
      <soap11:operation soapAction="http://www.example/soap/service/createObject" 
         style="document"/>
      ...
   </wsdl:operation>
   <wsdl:operation name="replaceObject">
      <soap11:operation soapAction="http://www.example/soap/service/replaceObject" 
         style="document"/>
      ...
   </wsdl:operation>
</wsdl:binding>
<wsdl:service name = "EgServiceNameSyncService">
   <wsdl:port name = "CoreOperationsNameSyncSoapPort" 
            binding = "tns:CoreOperationsNameSyncSoapBinding">
      <soap11:address 
         location="http://www.example.soap/serviceuri/ EgServiceNameSyncServiceSoap/"/>
   </wsdl:port>
</wsdl:service>

<wsdl11:types>
   <xs:schema>
      <xs:import namespace="http://www.imsglobal.org/xsd/exampleXSD" 
         schemaLocation="http://www.imsglobal.org/xsd/exampleXSD.xsd"/>
      </xs:schema>
</wsdl11:types>