Web Services Versioning using WSO2 WSAS and WSO2 ESB

Let us review what we know already. Axis 1.x based Web services are primarily of rpc/encoded style, as that was the default option. Axis2 used document/literal style as the default. So the SOAP requests that are sent by the two sets of clients are very different from each other. So the first issue is to figure out how to re-use the Axis 1.x classes and the wsdd descriptor (migration). The second issue is how we can support legacy (rpc/encoded) and modern (doc/lit) clients at the same time (versioning). Thankfully, WSO2 WSAS and WSO2 ESB make it easy both for migration and for versioning.

Sample Service and Deployment Descriptors

Let us take a quick look at the sample service and classes that we will work with in this article. MyService is the service that needs to be deployed:

package org.wso2.samples;

public class MyService {
        public Employee[] getEmployees(){
                return new Employee[]{
                        new Employee("Sanjiva","Weerawarana",1),
                        new Employee("Paul","Fremantle",2)
                };
        }
}

and here's the Employee class:

package org.wso2.samples;

public class Employee {
    public String firstName = null;
    public String lastName = null;
    public int id = 0;
    public Employee() {
    }
    public Employee(String firstName, String lastName, int id){
                this.firstName = firstName;
                this.lastName = lastName;
                this.id = id;
    }
        public String getFirstName() {
                return firstName;
        }
        public void setFirstName(String firstName) {
                this.firstName = firstName;
        }
        public String getLastName() {
                return lastName;
        }
        public void setLastName(String lastName) {
                this.lastName = lastName;
        }
        public int getID() {
                return id;
        }
        public void setID(int id) {
                this.id = id;
        }
}

We can deploy this service in Axis 1.x using the following snippet in the server-config.wsdd:

        <service name="MyOldService" provider="java:RPC" style="rpc" use="encoded">
                <parameter name="wsdlTargetNamespace" value="http://samples.wso2.org"/>
                <parameter name="wsdlServiceElement" value="MyServiceService"/>
                <parameter name="schemaUnqualified" value="http://samples.wso2.org"/>
                <parameter name="wsdlServicePort" value="MyService"/>
                <parameter name="className" value="org.wso2.samples.MyService"/>
                <parameter name="wsdlPortType" value="MyService"/>
                <parameter name="typeMappingVersion" value="1.2"/>
                <operation name="getEmployees" qname="operNS:getEmployees" xmlns:operNS="http://samples.wso2.org" 
                              returnQName="getEmployeesReturn" returnType="rtns:ArrayOfEmployee" 
                              xmlns:rtns="http://samples.wso2.org" returnItemType="tns2:Employee" 
                              xmlns:tns2="http://samples.wso2.org">
                </operation>
                <parameter name="allowedMethods" value="getEmployees"/>
                <typeMapping xmlns:ns="http://samples.wso2.org" qname="ns:Employee" type="java:org.wso2.samples.Employee" 
                        serializer="org.apache.axis.encoding.ser.BeanSerializerFactory" 
                        deserializer="org.apache.axis.encoding.ser.BeanDeserializerFactory" 
                        encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
                <arrayMapping xmlns:ns="http://samples.wso2.org" qname="ns:ArrayOfEmployee" 
                        type="java:org.wso2.samples.Employee[]" innerType="cmp-ns:Employee" 
                        xmlns:cmp-ns="http://samples.wso2.org" 
                        encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
        </service>

And the following services.xml in Axis2:

<service name="MyService">
        <description>
                My Service class deployed on Axis2
        </description>
        <parameter name="ServiceClass">org.wso2.samples.MyService</parameter>
        <operation name="getEmployees">
                <messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
        </operation>
</service>

Installing Services on WSO2 WSAS

Download WSO2 WSAS 2.0 from http://dist.wso2.org/products/wsas/java/2.0/ and unzip to say C:\wso2wsas-2.0
The WSO2 WSAS server by default uses ports 9762 and 9443. Unfortunately WSO2 ESB uses 8080, 8443 and 9443. So let's switch the WSAS ports to avoid clashing with ESB

Edit c:\wso2wsas-2.0\conf\server.xml and add the following snippet:

    <Ports>
        <HTTP>7070</HTTP>
        <HTTPS>7443</HTTPS>
    </Ports>

Edit c:\wso2wsas-2.0\conf\axis2.xml and replace the ports (9762 with 7070 and 9443 with 7443)

Make sure JDK1.5's java.exe is on the command line, cd to c:\wso2wsas-2.0\bin and run "wso2wsas run". You will see an output similar to the one below:

Starting WSO2 Web Services Application Server v2.0 (in JDK 1.5)
 Using WSO2WSAS_HOME:   C:\WSO2WS~1.0\bin\..
 Using JAVA_HOME:       C:\JDK15
 INFO [2007-09-05 23:23:27,552]  Using WSO2 WSAS Home = C:\WSO2WS~1.0\bin\..
 INFO [2007-09-05 23:23:27,585]  Using Server Info Class = org.wso2.wsas.serverinfo.EmbeddedTomcatServerInfo
 INFO [2007-09-05 23:23:33,321]  Deploying module: addressing-1.25
 INFO [2007-09-05 23:23:33,374]  Deploying module: rahas-1.25
 INFO [2007-09-05 23:23:33,641]  Deploying module: rampart-1.25
 INFO [2007-09-05 23:23:33,666]  Deploying module: wso2mex-2.0
 INFO [2007-09-05 23:23:34,068]  Deploying module: sandesha2-2.0
 INFO [2007-09-05 23:23:34,085]  Deploying module: wso2statistics-2.0
 INFO [2007-09-05 23:23:34,126]  Deploying module: wso2throttle-2.0
 INFO [2007-09-05 23:23:34,148]  Deploying module: wso2tracer-2.0
 INFO [2007-09-05 23:23:34,152]  Deploying module: wso2wsas-admin-2.0
 INFO [2007-09-05 23:23:34,174]  Deploying module: wso2xfer-2.0
 INFO [2007-09-05 23:23:34,527]  Deploying module: addressing-1.25
 INFO [2007-09-05 23:23:34,540]  Deploying module: wso2mex-2.0
 INFO [2007-09-05 23:23:43,484]  Deploying Web service: echo.aar
 INFO [2007-09-05 23:23:44,122]  Deploying Web service: version.aar
 INFO [2007-09-05 23:23:44,241]  Deploying Web service: wso2codegen.aar
 INFO [2007-09-05 23:23:44,580]  Deploying Web service: wso2wsas-administration.aar
 INFO [2007-09-05 23:23:44,865]  Deploying Web service: wso2wsas-sts.aar
 INFO [2007-09-05 23:23:45,128]  Deploying Web service: xkms.aar
 INFO [2007-09-05 23:23:46,719]  Command listener starting on port ----> 6666
 INFO [2007-09-05 23:23:46,719]  Using Repository C:\WSO2WS~1.0\bin\../repository/
 INFO [2007-09-05 23:23:46,720]
 INFO [2007-09-05 23:23:46,720]  Listening for HTTP on             ----> 7070
 INFO [2007-09-05 23:23:46,720]  Listening for HTTPS on            ----> 7443
 INFO [2007-09-05 23:23:46,720]
 INFO [2007-09-05 23:23:46,720]  WSO2 WSAS started in 22131 ms

Point your browser to https://localhost:7443/ Login using admin/admin as the user ID and password and click on the services link.
To upload the Axis2 service, click on "Upload Service Artifact (.aar,.jar,.zip,.dbs)" and upload myservice-axis2.aar (see Downloads below)
To upload the Axis1 service, click on "Upload Axis1 Service (.wsdd)" and upload myservice-axis1.jar and server-config.wsdd (see Downloads below)
After a few seconds, you will see both the Axis1 and Axis2 services show up on the console:

Install WSO2 ESB and Set up a Mediation for Versioning

Download WSO2 ESB 1.0 from http://dist.wso2.org/products/esb/java/1.0/ and unzip to say C:\wso2esb-1.0

Make sure JDK1.5's java.exe is on the command line, cd to c:\wso2esb-1.0\bin and run "wso2-esb run". You will see an output similar to the one below:

 Using Bouncy castle JAR for Java 1.5
"Starting WSO2 Enterprise Service Bus ..."
Using ESB_HOME:        E:\WSO2ES~1.0\bin\..
Using JAVA_HOME:       C:\JDK15
Using SYNAPSE_XML:     -Dsynapse.xml="E:\WSO2ES~1.0\bin\..\conf\synapse.xml"
 INFO [06 Sep 00:38:40]  ServiceBusConfiguration - Service Bus Configuration loaded from : conf/server.xml
 INFO [06 Sep 00:38:40]  ServiceBus - Using Repository E:\WSO2ES~1.0\.\repository
 INFO [06 Sep 00:38:41]  ServiceBusManager - Database server started on localhost over port 1528
 INFO [06 Sep 00:38:42]  ModuleDeployer - Deploying module: addressing
 INFO [06 Sep 00:38:42]  ModuleDeployer - Deploying module: authentication
 INFO [06 Sep 00:38:42]  ModuleDeployer - Deploying module: rampart
 INFO [06 Sep 00:38:42]  ModuleDeployer - Deploying module: sandesha2
 INFO [06 Sep 00:38:42]  ModuleDeployer - Deploying module: synapse-1.0
 INFO [06 Sep 00:38:42]  ModuleDeployer - Deploying module: wso2statistics
 INFO [06 Sep 00:38:42]  SynapseModule - Initializing the Synapse configuration ...
 INFO [06 Sep 00:38:42]  XMLConfigurationBuilder - Generating the Synapse configuration model by parsing the XML configuration
 INFO [06 Sep 00:38:42]  SynapseConfigurationBuilder - Loaded Synapse configuration from : E:\WSO2ES~1.0\bin\..\conf\synapse.xml
 INFO [06 Sep 00:38:42]  SynapseModule - Deploying the Synapse service..
 INFO [06 Sep 00:38:42]  SynapseModule - Initializing Sandesha 2...
 INFO [06 Sep 00:38:42]  SynapseModule - Deploying Proxy services...
 INFO [06 Sep 00:38:42]  SynapseModule - Synapse initialized successfully...!
 INFO [06 Sep 00:38:43]  HttpCoreNIOSender - HTTPS Sender starting
 INFO [06 Sep 00:38:43]  HttpCoreNIOSender - HTTP Sender starting
 INFO [06 Sep 00:38:53]  ServiceDeployer - Deploying Web service: ESBAdmin.aar
 INFO [06 Sep 00:38:54]  HttpCoreNIOListener - HTTPS Listener starting on port : 8443
 INFO [06 Sep 00:38:54]  HttpCoreNIOListener - HTTP Listener starting on port : 8080
 INFO [06 Sep 00:38:54]  JettyServer - Console listener started on port 9443 over HTTPS. Connect to https://192.168.2.105:9443/
 INFO [06 Sep 00:38:54]  ServiceBus - WSO2 ESB started in 15004 ms

Point your browser to https://localhost:9443/ Login using admin/admin as the user ID and password, and click on the Configuration link
Copy the contents of esb-configuration.xml into the edit box, click Update and then click Save.
Now if you click on Proxy Services, Endpoints or Sequences, you can grapically view the information that was picked up from the esb-configuration.xml
In particular, http://localhost:8080/soap/MyService is the new endpoint that redirects the SOAP requests to http://localhost:7070/services/MyService for newer doc/lit clients and to http://localhost:7070/services/MyOldService for old rpc/encoded style clients.

When you click on Sequences, and look at "inSequence", you will see that we use an xpath expression //*[local-name()='getEmployees'] to decide which endpoint needs to be invoked. Here's the corresponding configuration snippet:

        <syn:sequence name="inSequence">
                <syn:filter xpath="//*[local-name()='getEmployees']">
                        <syn:send>
                                <syn:endpoint key="Axis1Service"/>
                        </syn:send>
                        <syn:drop/>
                </syn:filter>
                <syn:send>
                        <syn:endpoint key="Axis2Service"/>
                </syn:send>
        </syn:sequence>

Basically inside the SOAP body, for rpc/encoded requests, there is an additional element named "getEmployees". So we look for that to identify that it is an rpc/encoded request.

If you browse through the esb-configuration.xml, you will see that we used an inline WSDL for the axis1 service and a URL for the axis2 service. This is because, when we deploy an Axis1 service, the WSDL picks up the https:// endpoint. So we had to copy the WSDL and make the change to refer to http:// endpoint.

Testing the New Endpoint

You can use a tool like SOAPUI or XMLSPY to test the actual Web services deployed on WSO2 WSAS first, the wsdl's for those are http://localhost:7070/services/MyOldService?wsdl and http://localhost:7070/services/MyService?wsdl

For example, when you send the following SOAP request to http://localhost:7070/services/MyOldService

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <SOAP-ENV:Body>
                <m:getEmployees xmlns:m="http://samples.wso2.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
        </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

you will get the following:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
	          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
                <ns1:getEmployeesResponse xmlns:ns1="http://samples.wso2.org" 
				soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                        <getEmployeesReturn xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
						soapenc:arrayType="ns1:Employee[2]" xsi:type="soapenc:Array">
                                <getEmployeesReturn href="#id0"/>
                                <getEmployeesReturn href="#id1"/>
                        </getEmployeesReturn>
                </ns1:getEmployeesResponse>
                <multiRef xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
				xmlns:ns2="http://samples.wso2.org" id="id0" soapenc:root="0" 
				soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
				xsi:type="ns2:Employee">
                        <ID xsi:type="xsd:int">1</ID>
                        <firstName xsi:type="xsd:string">Sanjiva</firstName>
                        <lastName xsi:type="xsd:string">Weerawarana</lastName>
                        <id xsi:type="xsd:int">1</id>
                </multiRef>
                <multiRef xmlns:ns3="http://samples.wso2.org" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
				id="id1" soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="ns3:Employee">
                        <ID xsi:type="xsd:int">2</ID>
                        <firstName xsi:type="xsd:string">Paul</firstName>
                        <lastName xsi:type="xsd:string">Fremantle</lastName>
                        <id xsi:type="xsd:int">2</id>
                </multiRef>
        </soapenv:Body>
</soapenv:Envelope>

For example, when you send the following SOAP request to http://localhost:7070/services/MyService

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <SOAP-ENV:Body/>
</SOAP-ENV:Envelope>

you will get the following:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
                <ns:getEmployeesResponse xmlns:ns="http://samples.wso2.org" xmlns:ax225="http://samples.wso2.org/xsd">
                        <ns:return type="org.wso2.samples.Employee">
                                <ax225:firstName>Sanjiva</ax225:firstName>
                                <ax225:lastName>Weerawarana</ax225:lastName>
                        </ns:return>
                        <ns:return type="org.wso2.samples.Employee">
                                <ax225:firstName>Paul</ax225:firstName>
                                <ax225:lastName>Fremantle</ax225:lastName>
                        </ns:return>
                </ns:getEmployeesResponse>
        </soapenv:Body>
</soapenv:Envelope>