CAA Web Services and WSDL Definitions

CAA Web Services Home		CAA Web Services and WSDL Definitions Overview of WSDL and XSD definitions used to describe CAA Web services
Technical Article

Abstract

WSDL documents are used to describe CAA Web services. This article introduces the WSDL 1.1 specification, and explains how its related concepts are used in the context of CAA Web services.

CAA Web Services and WSDL Definitions
WSDL Interface Documents
WSDL Implementation Documents
In Short
References

CAA Web Services and WSDL Definitions

Web services are software systems, which can be accessed through messages conveyed by standard Internet protocols. The functionalities that these systems deliver are described in a platform and language neutral-way using an XML language called WSDL (Web Services Description Language). Using this abstract WSDL definition, developers can use off-the-shelf tools to generate a client proxy for their platform and programming language. This client proxy will know how to craft the correct messages and send them to the target software system. This mechanism enables the integration of heterogeneous systems.

CAA Web services respect this standard and provide their descriptions in WSDL form. This section gives an overview of the WSDL 1.1 specification, and then provides more information on the format of the exchanged messages through the description of the WSDL 1.1 SOAP (Simple Object Access Protocol) binding extension. Finally, it describes the WS-I (Web Services Interoperability) Basic Profile 1.0, a set of additional rules to improve the interoperability provided by WSDL and SOAP.

[Top]

WSDL 1.1 Specification

A WSDL document defines the contract between a Web service provider and a Web service consumer. The XML language defined in the WSDL 1.1 specification [1] uses the following elements to describe a Web service:

<wsdl:type>: description of the data types exposed, most of the time using XSD (XML Schema Definition),
<wsdl:message> and <wsdl:part>: description of the messages that can be exchanged, including references to the types defined in the above section,
<wsdl:portType> and <wsdl:operation>: a portType contains an abstract set of supported operations, along with references to the messages involved within each operation,
<wsdl:binding>: message format and protocol specific information for the operations defined in a portType,
<wsdl:service> and <wsdl:port>: a service is defined by a set of ports. Each port provides a single endpoint for a given binding.

Even if all of these elements may be found in a single WSDL document, it is common to have them separated in two different locations:

A WSDL interface document: describes an "abstract" interface of a Web service,
A WSDL implementation document: describes a "concrete" (i.e. deployed) implementation of a Web service. It contains a reference to the WSDL interface document describing the implemented interface.

Fig.1: Relationship Between WSDL Interface and Implementation Documents

[Top]

WSDL 1.1 SOAP Binding Extension

The WSDL 1.1 specification includes an extension to describe Web services that can be consumed using the SOAP 1.1 protocol [2]. Such Web services can be remotely invoked by sending SOAP messages (XML content) embedded inside HTTP POST requests. In a WSDL document, the SOAP protocol specific information are based on the following elements:

<soap:binding>: specifies that a given binding is bound to the SOAP 1.1 protocol,
<soap:operation>, <soap:body> and <soap:fault>: describe the format of the SOAP messages,
<soap:address>: provides the value of the SOAP endpoint URI, where HTTP POST SOAP requests must be sent in order to consume the given Web service.

The <soap:binding> and <soap:operation> elements include a style attribute which is used to differentiate two styles of SOAP messages that can be exchanged on the wire:

RPC: the message format must conform to some specific rules outside of the WSDL definition alone (see section "3.5 soap:body" of the WSDL 1.1 specification for a precise description of these rules),
Document: there is no underlying specific formatting rule, the message format must simply conform to the schemas described in the WSDL definition (most of the time it uses XML schema definitions).

The <soap:body> element includes a use attribute which is used to specify the type of SOAP serialization:

Encoded: data types (such as objects, structures or arrays) must be encoded within the SOAP messages according to the rules defined in section "5. SOAP Encoding" of the SOAP 1.1 specification,
Literal: messages (including data types) are serialized according to the schema definitions available in the WSDL document.

In the end, there are four combinations available: rpc/encoded, rpc/literal, document/encoded, document/literal. The following describes where these elements are defined inside WSDL documents:

<wsdl:definitions .... >

             <wsdl:binding .... >

              <soap:binding style="rpc|document" ... />

              <wsdl:operation .... >

               <soap:operation style="rpc|document" ... />

               <wsdl:input>

                <soap:body use="literal|encoded" ... />

               </wsdl:input>

               <wsdl:output>

                <soap:body use="literal|encoded" ... />

               </wsdl:output>

               <wsdl:fault>

                <soap:fault use="literal|encoded" ... />

               </wsdl:fault>

              </wsdl:operation>

             </wsdl:binding>

            </wsdl:definitions>

[Top]

WS-I Compliance

CAA Web services are WS-I compliant and conform to the WS-I Basic Profile 1.0 [3]. A Basic Profile consists of a set of Web services related specifications grouped together, such as the ones published by the W3C (World Wide Web Consortium) and the UDDI.org (Universal Description, Discovery and Integration) organizations. The Basic Profile 1.0 refers to the following specification levels: SOAP 1.1, XML 1.0, HTTP/1.1, WSDL 1.1, XML Schema 1.0 and UDDI v2.0. It also contains clarifications and specific requirements that are intended to enhance these specifications. The aim is to maximize interoperability between implementers of the Basic Profile requirements. As the Basic Profile 1.0 states itself, there can be no 100% guarantee of interoperability. Despite this consideration, the WS-I compliance claim is still considered by the industry as a major step forward in order to ease the integration of Web services on heterogeneous systems.

Following the Basic Profile 1.0 recommendation, WSDL documents for CAA Web services conform to the WSDL 1.1 specification. They use the document/literal approach described above. As explained in the Basic Profile 1.0 (section "4.1.7 SOAP encodingStyle Attribute"), the literal use is preferred to the encoded one, because the latter introduces unnecessary complexity. The document style is on the other hand the most widespread approach.

[Top]

WSDL Interface Documents

WSDL interface documents contain abstract descriptions of CAA Web service interfaces. They are available from the product installation and can be found at the following location:

<Product-install>\<Operating-system>\resources\wsdl\<Framework>\<Module>\<Interface>.wsdl

<Product-install>: product installation root folder,
<Operating-system>: identifier of the operating system chosen for the product installation. The following list is not exhaustive:
- Windows: intel_a
- AIX: aix_a
- SOLARIS: solaris_a
- HP/UX: hpux_b
\resources\wsdl\<Framework>\<Module>\<Interface>.wsdl: relative path to the WSDL interface document:
- Example: \resources\wsdl\ENOPosWS\ENOPos_ws\IApplicationBinder.wsdl.

WSDL documents describing CAA Web services rely on external XSDs in order to describe the data types that are relevant for the exchanged SOAP messages. WSDL documents import these XSDs, which can be found at the following location:

<Product-install>\<Operating-system>\resources\xsd\*.xsd

See [4] for the complete list of CAA Web service interfaces available. This document also provides the list of relative path values required to access each WSDL interface document.

Access From a Remote Location

Even if WSDL interface documents can be accessed directly from the file system, it may also be useful to access them from a remote location. In order to do so, CAA Web services must have been previously deployed on a target application server. Please refer to the product installation guide for more details about this task (see [4] for the list of related products). You can then use the following URL scheme to access a given WSDL interface document:

http://<Server>:<Port>/<Context-root>/file/resources/wsdl/<Framework>/<Module>/<Interface>.wsdl

<Server>: server name, including domain,
<Port>: server port,
<Context-root>: context root of the Web application,
/resources/wsdl/<Framework>/<Module>/<Interface>.wsdl: relative path to the WSDL interface document as described in the previous section, with every backward slash character ('\') replaced by a forward slash character ('/'):
- Example: /resources/wsdl/ENOPosWS/ENOPos_ws/IApplicationBinder.wsdl.

Fig.2: Sample WSDL Interface Document

[Top]

WSDL Implementation Documents

WSDL implementation documents contain concrete descriptions of deployed CAA Web service implementations. The main information available is the SOAP endpoint URI. It specifies the target location for the HTTP POST SOAP requests that must be sent in order to consume a given CAA Web service. Its value is contained in the location attribute of the <soap:address> element, as detailed below:

<definitions.... >

             <port.... >

              <binding.... >

               <soap:address location="URI" />

              </binding>

             </port>

            </definitions>

The SOAP endpoint URI is bound to a specific application server. As a result, the complete content of a WSDL implementation document can only be resolved once the related CAA Web service has been deployed on a target application server. Therefore, unlike WSDL interface documents, WSDL implementation documents cannot be delivered in the file system. Instead, they can be obtained by querying a servlet hosted on the same application server than the requested CAA Web service implementation. This servlet can be accessed by using through the following URI scheme:

http://<Server>:<Port>/<Context-root>/wsdl?service=<Identifier>

<Server>: server name, including domain,
<Port>: server port,
<Context-root>: context root of the Web application,
<Identifier>: CAA Web service implementation identifier:
- Example: urn:com:dassault_systemes:ENOPosWS:ENOPosAppliBinder:ENOPosApplicationBinderImpl.

Fig.3: Sample WSDL implementation document

See [4] for the complete list of available CAA Web service implementations. This document also provides the list of identifier values required to access each WSDL implementation document.

[Top]

In Short

CAA Web services are WS-I compliant. In such context, they are described using WSDL definitions that conform to the WSDL 1.1 specification. There are two types of WSDL documents available to describe a CAA Web service, a WSDL interface document and a WSDL implementation document:

The former describes the "abstract" interface of the CAA Web service. It can be accessed from the file system (within the product installation) or from a remote location (using a dedicated URI scheme),
The latter describes a "concrete" implementation of a CAA Web service that has been deployed on a target application server. This implementation can be consumed by sending HTTP POST SOAP requests to a specific SOAP endpoint URI. WSDL implementation documents are dynamically generated using a servlet hosted on the same server than the requested CAA Web service implementation.

[Top]

References

[1]	Web Services Description Language (WSDL) 1.1
[2]	Simple Object Access Protocol (SOAP) 1.1
[3]	WS-I Basic Profile 1.0
[4]	CAA Web Services Reference
[Top]

History

Version: 1 [Apr 2005]	Document created
[Top]

CAA Web Services Home

CAA Web Services and WSDL Definitions

Abstract

CAA Web Services and WSDL Definitions

WSDL 1.1 Specification

WSDL 1.1 SOAP Binding Extension

WS-I Compliance

WSDL Interface Documents

Access From a Remote Location

WSDL Implementation Documents

In Short

References

History