Web services

Web services

From the WWW Consortium:
A Web service is a software system identified by a URI, whose public interfaces and bindings are defined and described using XML. Its definition can be discovered by other software systems. These systems may then interact with the Web service in a manner prescribed by its definition, using XML based messages conveyed by internet protocols
Web services allow applications and agents to browse the Web on behalf of users
Instead of a user navigating HTML screens, an agent can connect to services on the Web and interact with them directly without the distraction of presentation elements
SOAP/WSDL/UDDI are the technologies behind Web services

Web Service Structure

Web Service Components

WSDL (Web Services Description Language) is the metalanguage used to describe a Web service. It corresponds to the IDL (Interface Definition Language) of other RPC systems
SOAP (Simple Object Access Protocol) is the wire format for remote method calls and their replies. It corresponds to the XDR level of Sun's RPC
UDDI (Universal Description, Discovery and Integration) is the resource registration and lookup mechanism. It corresponds to the Naming Services of CORBA, RMI

Remote Procedure Call

Web Services Remote Procedure Call

Components of RPC

An RPC system consists of the following pieces

A set of data types that can be sent as parameters and received as results
A representation of these data types on the wire
A message format for sending procedure name and parameters and getting procedure reply
A means of representing the procedures and their signatures (parameters and result types) in a form independent of implementation - this will be used to generate two implementations, one on the client side, the other on the server. This acts as a specification of a remote procedure call
A mechanism for automatically generating a client stub
A mechanism for automatically generating a server stub
A way of linking the server-side implementation of the procedure to the server stub so that the stub can call it
Address of the service
Locating the service

Web Services and Standardisation

RPC requirement	SOAP
defined data types	defined by SOAP
wire format for data	defined by SOAP using XML
wire format for messages	defined by SOAP over HTTP
an IDL	defined by WSDL
generation of client stubs	vendor specific
generation of server stubs	vendor specific
linking implementation	vendor specific
Address of service	URL
Locating service	UDDI

Simple Service

A service to convert millimetres to inches and vice versa may be described informally as


      Converter service:
          float inchToMM(float)
          float mmToInch(float)

The description includes no semantics
It includes no environment

WSDL

The WSDL specification looks like


<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:tns="urn:Converter" targetNamespace="urn:Converter" name="ConverterService">
    <message name="inchToMMRequest">
        <part name="param1" type="xsd:float"/>
    </message>
    <message name="inchToMMResponse">
        <part name="return" type="xsd:float"/>
    </message>
    <message name="mmToInchRequest">
        <part name="param1" type="xsd:float"/>
    </message>
    <message name="mmToInchResponse">
        <part name="return" type="xsd:float"/>
    </message>
    <message name="java_rmi_RemoteException">
        <part type="xsd:string" name="java_rmi_RemoteException"/>
    </message>
    <message name="com_iona_xmlbus_webservices_ejbserver_ConversionException">
        <part type="xsd:string" name="com_iona_xmlbus_webservices_ejbserver_ConversionException"/>
    </message>
    <portType name="ConverterPortType">
        <operation name="inchToMM">
            <input message="tns:inchToMMRequest" name="inchToMM"/>
            <output message="tns:inchToMMResponse" name="inchToMMResponse"/>
            <fault message="tns:java_rmi_RemoteException" name="java_rmi_RemoteException"/>
        </operation>
        <operation name="mmToInch">
            <input message="tns:mmToInchRequest" name="mmToInch"/>
            <output message="tns:mmToInchResponse" name="mmToInchResponse"/>
            <fault message="tns:java_rmi_RemoteException" name="java_rmi_RemoteException"/>
            <fault
                message="tns:com_iona_xmlbus_webservices_ejbserver_ConversionException" name="com_iona_xmlbus_webservices_ejbserver_ConversionException"/>
        </operation>
    </portType>
    <binding name="ConverterBinding" type="tns:ConverterPortType">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http/" style="rpc"/>
        <operation name="inchToMM">
            <soap:operation soapAction="" style="rpc"/>
            <input name="inchToMM">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </input>
            <output name="inchToMMResponse">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </output>
            <fault name="java_rmi_RemoteException">
                <soap:fault name="java_rmi_RemoteException"
                    use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </fault>
        </operation>
        <operation name="mmToInch">
            <soap:operation soapAction="" style="rpc"/>
            <input name="mmToInch">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </input>
            <output name="mmToInchResponse">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </output>
            <fault name="java_rmi_RemoteException">
                <soap:fault name="java_rmi_RemoteException"
                    use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </fault>
            <fault name="com_iona_xmlbus_webservices_ejbserver_ConversionException">
                <soap:fault
                    name="com_iona_xmlbus_webservices_ejbserver_ConversionException"
                    use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </fault>
        </operation>
    </binding>
    <service name="Converter">
        <port name="ConverterPort" binding="tns:ConverterBinding">
            <soap:address location="http://www.xmlbus.com:9010/ionasoap/servlet/Converter"/>
        </port>
    </service>
</definitions>

Components of WSDL Specification

Data types

XML data types are okay
Add extra data types here

Messages

inchToMMRequest
inchToMMResponse
java_rmi_RemoteException
...

Ports

inchToMM(inchToMMRequest, inchToMMResponse, java_rmi_RemoteException)
...

Bindings


      ConverterBinding
      operation: inchToMM/rpc
                 "inchToMM"
                 "inchToMMResponse"
                 "java_rmi_RemoteException"

...

Service


      name: Converter
      

      address: http://...
      ...

WSDL Specification Revisited


<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:tns="urn:Converter" targetNamespace="urn:Converter" name="ConverterService">

    <message name="inchToMMRequest">
        <part name="param1" type="xsd:float"/>
    </message>
    <message name="inchToMMResponse">
        <part name="return" type="xsd:float"/>
    </message>
    <message name="mmToInchRequest">
        <part name="param1" type="xsd:float"/>
    </message>
    <message name="mmToInchResponse">
        <part name="return" type="xsd:float"/>
    </message>
    <message name="java_rmi_RemoteException">
        <part type="xsd:string" name="java_rmi_RemoteException"/>
    </message>
    <message name="com_iona_xmlbus_webservices_ejbserver_ConversionException">
        <part type="xsd:string" name="com_iona_xmlbus_webservices_ejbserver_ConversionException"/>
    </message>

    <portType name="ConverterPortType">
        <operation name="inchToMM">
            <input message="tns:inchToMMRequest" name="inchToMM"/>
            <output message="tns:inchToMMResponse" name="inchToMMResponse"/>
            <fault message="tns:java_rmi_RemoteException" name="java_rmi_RemoteException"/>
        </operation>
        <operation name="mmToInch">
            <input message="tns:mmToInchRequest" name="mmToInch"/>
            <output message="tns:mmToInchResponse" name="mmToInchResponse"/>
            <fault message="tns:java_rmi_RemoteException" name="java_rmi_RemoteException"/>
            <fault
                message="tns:com_iona_xmlbus_webservices_ejbserver_ConversionException" name="com_iona_xmlbus_webservices_ejbserver_ConversionException"/>
        </operation>
    </portType>

    <binding name="ConverterBinding" type="tns:ConverterPortType">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http/" style="rpc"/>
        <operation name="inchToMM">
            <soap:operation soapAction="" style="rpc"/>
            <input name="inchToMM">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </input>
            <output name="inchToMMResponse">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </output>
            <fault name="java_rmi_RemoteException">
                <soap:fault name="java_rmi_RemoteException"
                    use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </fault>
        </operation>
        <operation name="mmToInch">
            <soap:operation soapAction="" style="rpc"/>
            <input name="mmToInch">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </input>
            <output name="mmToInchResponse">
                <soap:body use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </output>
            <fault name="java_rmi_RemoteException">
                <soap:fault name="java_rmi_RemoteException"
                    use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </fault>
            <fault name="com_iona_xmlbus_webservices_ejbserver_ConversionException">
                <soap:fault
                    name="com_iona_xmlbus_webservices_ejbserver_ConversionException"
                    use="encoded" namespace="urn:Converter" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
            </fault>
        </operation>
    </binding>

    <service name="Converter">
        <port name="ConverterPort" binding="tns:ConverterBinding">
            <soap:address location="http://www.xmlbus.com:9010/ionasoap/servlet/Converter"/>
        </port>
    </service>

</definitions>

Role of WSDL in Web Services

Implement a service using your favourite programming language (Java, C#, VB, ...)
Reverse engineer this to a WSDL spec using a tool supplied by your Web Service vendor
Forward engineer this to your next favourite language
This may not work well for i18n web services

Apache Axis WSDL Tools

Axis is available from www.apache.org, and builds on the IBM Web Services Toolkit (WSTK)
If a web service is available from Axis, then you can download a WSDL description to a browser by calling the web service URL with "?WSDL" appended. It may not show up as anything readable: the browser will fail to interpret most of the tags, but it can be saved to a file
In the WSTK 3.2 you can either give a Java interface and generate a WSDL interface, or a Java class (earlier versions would not accept an interface)

e.g


      interface ConverterInterface {
          float inchToMM(float value);
	  float mmToInch(float value);
      };

Then run a WSDL generator


      AXIS_LIB=/usr/local/axis-1_1/lib # change this for your lib dir
      for i in $AXIS_LIB/*.jar
      do
          CP=$CP:$i
      done
      java -cp "$CP" org.apache.axis.wsdl.Java2WSDL \
          -o ConverterInterface.apache.wsdl \
          -l http://localhost/wstk/services/ConverterInterface \
           ConverterInterface

A Java interface can be created from a WSDL spec by


      java -cp $WSTK_CP org.apache.axis.wsdl.WSDL2Java \
           ConverterInterface.ibm.wsdl

Stub and tie generation will be dealt with later

There and Back Again

Java -> WSDL -> Java may give a different result to what you started from

Original


    interface ConverterInterface {
        float inchToMM(float value);
        float mmToInch(float value);
};

Round trip


    package DefaultNamespace;

    public interface Converter extends java.rmi.Remote {
        public float inchToMM(float in0) throws java.rmi.RemoteException;
        public float mmToInch(float in0) throws java.rmi.RemoteException;
    }

SOAP

What SOAP is

Basically, SOAP/WSDL/UDDI is the latest in RPC technologies
It is the first open standard RPC supported by Microsoft, and was originally developed by Microsoft, IBM and Artima
It is now part of the W3C standards track
Version 1.2 is under finalisation by W3C
SOAP consists of
- A description of allowable data types
- A message format
- A binding to HTTP transport, and (non-normative) examples of other bindings (e.g. email)

SOAP Messages

SOAP messages are either

a request for a service
a response from a service

SOAP Request

A SOAP request consists of

The envelope which defines the various namespaces used by the rest of the message
The header is optional, and can carry authentication, payments, etc
The body carries the payload of the message. For RPC it contains
- the method/procedure name
- the arguments

SOAP Response

A SOAP response is just like a request, except the body contains the result.

SOAP Message Structure

<?xml version="1.0" ?>
 <env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope">
   <env:Header>
     <p:oneBlock xmlns:p="http://example.com" env:actor="http://example.com/Log">
     ::::
     </p:oneBlock>
     <q:anotherBlock xmlns:q="http://example.com"
           env:actor="http://www.w3.org/2001/12/soap-envelope/actor/next">
     ::::
     </q:anotherBlock>
     <r:aThirdBlock xmlns:r="http://example.com">
     ::::
     </r:aThirdBlock>
   </env:Header>
   <env:Body >
     ::::
   </env:Body>
 </env:Envelope>

SOAP Header Blocks

SOAP headers are optional, and are designed to allow for expansion
A header can specify an actor which is a SOAP processing node along the message route e.g. next or a URL
When a site matches the header it takes corresponding action
Actions could be e.g.
- Log the entry
- Discard the message if crossing a firewall (?)
The "anonymous" role (no actor specified) is the target of the message

SOAP Body for RPC Request

When used for RPC, the body of a request contains a "struct" which is a method and its arguments


<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Body>
    <m:reserveAndCharge 
        env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
             xmlns:m="http://travelcompany.example.org/" >
      <n:name xmlns:n="http://mycompany.example.com/employees">
           John Q. Public
      </n:name>
      <o:creditCard xmlns:o="http://mycompany.example.com/financial">
           <o:number>123456789099999</o:number>
           <o:expiration>2005-02</o:expiration>
      </o:creditCard>
    </m:reserveAndCharge>
  </env:Body>
</env:Envelope>

SOAP Body for RPC Response

When used for RPC, the body of a response contains a "struct" which is the return
The struct label is <Request>Response


<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
  <env:Body>
       <m:reserveAndChargeResponse
             env:encodingStyle="http://www.w3.org/2001/12/soap-encoding"
             xmlns:m="http://travelcompany.example.org/" >
           <m:confirmation>
               <reference>FT35ZBQ</reference>
               <viewAt>
               http://travelcompany.example.org/reservations?code=FT35ZBQ
               </viewAt>
           </m:confirmation>
       </m:reserveAndChargeResponse>
   </env:Body>
</env:Envelope>

SOAP HTTP Binding

SOAP 1.2 only defines HTTP as transport protocol
Other protocols (email, Java Messaging, etc) are left unspecified
Notable points
- POST (not GET) is supported
- The document type is application/soap
- Errors are signalled using HTTP 500 "Internal Server Error"

SOAP HTTP Request


POST /Charging HTTP/1.1
Host: travelcompany.example.org
Content-Type: application/soap; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Body>
    <m:reserveAndCharge>
        ::::::
    </m:reserveAndCharge>
  </env:Body>
</env:Envelope>

SOAP HTTP Response


HTTP/1.1 200 OK
Content-Type: application/soap; charset="utf-8"
Content-Length: nnnn

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
 <env:Body>
    <m:reserveAndChargeResponse>
        ::::::
    </m:reserveAndCharge>
 </env:Body>
</env:Envelope>

Calling SOAP Methods

Apache Axis Server

Apache Axis 1.1 is the Apache SOAP server
It runs as a servlet within e.g. Jakarta Tomcat
The Axis servlet is responsible for dispatching calls to the Web service
Install Axis in a Tomcat servlet directory such as .../jakarta-tomcat/webapps/axis
Copy the Java implementation source code with jws extension to the toplevel of the Axis directory e.g. .../jakarta-tomcat/webapps/axis/Converter.jws
Access the service URL by e.g. http://localhost:8088/axis/Converter.jws
The Axis servlet is responsible for generating WSDL, ties, and linking the service implementation

Apache Axis Client - do it yourself

The basic classes to interact with a service are Service and Call
These assume you know
- the location of the service (the endpoint address)
- the operation (the method you are calling)
- the parameters to the call (an array handed to Call.invoke()


    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;
    import javax.xml.namespace.QName;
   
    public class TestClient {
      public static void main(String [] args) {
          try {
              String endpoint =
                       "http://nagoya.apache.org:5049/axis/services/echo";
  
             Service  service = new Service();
             Call     call    = (Call) service.createCall();
  
             call.setTargetEndpointAddress( new java.net.URL(endpoint) );
             call.setOperationName(new QName("http://soapinterop.org/", "echoString"));
             String ret = (String) call.invoke( new Object[] { "Hello!" } );
  
             System.out.println("Sent 'Hello!', got '" + ret + "'");
         } catch (Exception e) {
             System.err.println(e.toString());
         }
     }
   }

Simple converter service

Simple converter client

Apache Axis client using WSDL

WSDL2Java generates client-side stubs
For the ConverterInterface service, it generates
- ConverterInterface.java - the Java interface you use
- ConverterInterfaceServiceLocator.java - finds the service and returns a ConverterInterfaceService.java
- ConverterInterfaceService.java - has a method to get the client HOPP
- ConverterInterfaceSoapBindingStub.java - an implementation of the interface which is the client part of the HOPP


public class Tester
{
    public static void main(String [] args) throws Exception {
        // Make a service
        ConverterInterfaceService service = new ConverterInterfaceServiceLocator();
 
        // Now use the service to get a stub which implements the SDI.
        ConverterInterface port = service.getConverterInterface();
 
        // Make the actual call
        float mm = port.inchToMM(1.0);
    }
}

i18n

There is only one document talking about web services and i18n Web Services Internationalization Usage Scenarios
It makes a few recommendations such as "all text intended for users should have a language tag." In particular, all fault messages should have a language tag and maybe be offered in several versions

Date

gMonth

It also recommends using additional infor to make measures clearer e.g.
It doesn't actually go to that level of detail :-(

Lang information in header block

One way of passing locale information is to use the header block
This is not standardised, and is not represented in the WSDL, so it would have to be an "out-of-band" agreement
Here is a client passing info in the header
Here is a service getting it back

i18n Measures and Axis

Some of this works fine, some is messy, some is broken...
The measure service is okay This can be copied to AXIS/MeasureConverter.jws
The services uses non-standard data types. In order for Axis to handle these, it must know how to serialize and deserialize them
Serialization and deserialization can be done if the datatype is a Java Bean and a special entry is made in the WSDD file
Serialization and deserialization can be done if the datatype is a Java Bean and
- code to implement getSerializer and getDeserializer is included in the datatype
- a type descriptor is included in the file
This changes the class Measure to
It changes the class Inch to
The extra code can be found by generating the WSDL for the service and then back to the Java code
Inheritance breaks the return data type in Axis 1.2

The method inchToMM is okay to take Inch as a datatype that inherits from Measure
But: the method inchToMM returns Measure as a datatype rather than Mm
For this method to work, Mm must not inherit from Measure:
Similar comments apply to the method mmToInch

jar

AXIS/WEB-INF/lib/

A client that uses the WSDL generated files is
The ant file to build all these is
All files are here

References

Roger Costello's Xfront Schema tutorial http://www.xfront.com/xml-schema.html
Bob DuCharme "A general-purpose Java SOAP client" http://www-106.ibm.com/developerworks/xml/library/x-soapcl/
Graham Glass Hello world, Web service-style , http://www-106.ibm.com/developerworks/webservices/library/ws-peer2/
Graham Glass How SOAP works , http://www-106.ibm.com/developerworks/webservices/library/ws-peer3/
Graham Glass Web Services Description Language (WSDL) , http://www-106.ibm.com/developerworks/webservices/library/ws-peer4/
SOAP 1.2 Protocol, http://www.w3.org/TR/soap12
WSDL 1.0 Specification, http://http://www.ibm.com/developerworks/web/library/w-wsdl.html
UDDI home page http://www.uddi.org
Web Services Tooolkit http://alphaworks.ibm.com/tech/webservicestoolkit

Jan Newmarch (http://jan.newmarch.name)

jan@newmarch.name