JAX-WS service versioning with Maven

1. Reference

-Attached fully working sample 'zuora-cross-bizws' for deploying in a JEE stack (tested in GlassFish)

-JAX-WS documentation and reference implementation (RI) > https://jax-ws.java.net/

-Maven software project management and comprehension tool > https://maven.apache.org/2

2. Introduction

This article will build, step by step, a full SOAP WS service, versioning it in a way that new versions can cohexist with previous ones:

+First, we'll create a maven project that, in a completely automatically way, will create all the necessary SOAP WSDL and related schemas for interacting with the WS.

+Then, we'll version the web service via URL for each of the implementations.

3. Implementation of the different versions of the web service

3a. The first version of the web service

ZuoraBiz001.java is the implementation of the first version of this sample Hello World web service.

With annotation @WebService let's fix the serviceName and the portName to be used across all new versions.

With annotation @WebParam, it's optionally possible to indicate the name of the parameter in the generated WSDL/schema, instead of the default 'arg0'.

@WebService(serviceName="ZuoraBizService", portName="ZuoraBizPort")

public class ZuoraBiz001{

    @WebMethod(operationName = "sayHello")

    public String sayHello(@WebParam(name = "name") @XmlElement(required=true) final String name){

        return String.format("(version 1) Hello, %s", name);

    }

}

3b. A new version of the web service

ZuoraBiz002.java is the implementation of a new version of the same web service.

Notice that the same serviceName and portName are being used.

@WebService(serviceName="ZuoraBizService", portName="ZuoraBizPort")

public class ZuoraBiz002{

    @WebMethod(operationName = "sayHello")

    public String sayHello(@WebParam(name = "name") @XmlElement(required=true) final String name){

        return String.format("(version 2) Hello, %s", name);

    }

}

4. Web service versioning

Let's now use the WSDL URL for versioning the web service. The goal is to make every version of the web service available via a different, versioned, URL.

E.g: If the application (war) is deployed in server "zuora-cross-bizws-int.wielkopolska.elasticbeanstalk.com", the previous web service versions will be available at:

http://zuora-cross-bizws-int.wielkopolska.elasticbeanstalk.com/zuora-cross-bizws/1.0?wsdl

http://zuora-cross-bizws-int.wielkopolska.elasticbeanstalk.com/zuora-cross-bizws/2.0?wsdl

Notice that the only difference is the version number at the end of the URL, either 1.0 or 2.0

To achieve this URL versioning behavior, let's map the URL to the web corresponding service implementation via configuration file "webapp/WEB-INF/web.xml":

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" version="3.1">

<servlet id="ZuoraBiz001">

    <servlet-name>ZuoraBiz001</servlet-name>

    <servlet-class>com.axaa.cross.zuora.bizws.ZuoraBiz001</servlet-class>

    <load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

    <servlet-name>ZuoraBiz001</servlet-name>

    <url-pattern>/zuora-cross-bizws/1.0</url-pattern>

</servlet-mapping>

<servlet id="ZuoraBiz002">

    <servlet-name>ZuoraBiz002</servlet-name>

    <servlet-class>com.axaa.cross.zuora.bizws.ZuoraBiz002</servlet-class>

    <load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

    <servlet-name>ZuoraBiz002</servlet-name>

    <url-pattern>/zuora-cross-bizws/2.0</url-pattern>

</servlet-mapping>

</web-app>

Note: For web.xml deployment description examples, see > http://www.mkyong.com/web-development/the-web-xml-deployment-descriptor-examples/