Using Axis Web Services with JBoss: Migration to modern JAX-WS with WildFly 41

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <deployment>
     <exclude-subsystems>
        <subsystem name="webservices"/>
     </exclude-subsystems>
  </deployment>
</jboss-deployment-structure>

package com.mastertheboss.jaxws;

import jakarta.jws.WebMethod;
import jakarta.jws.WebService;
import jakarta.jws.WebParam;

@WebService(targetNamespace = "http://mastertheboss.com/jaxws")
public class HelloWorld {

    @WebMethod
    public String hello(@WebParam(name = "message") String message) {
        return "Invoked with " + message;
    }
}

<dependencies>
    <dependency>
        <groupId>jakarta.platform</groupId>
        <artifactId>jakarta.jakartaee-web-api</artifactId>
        <version>11.0.0-M1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

import jakarta.xml.ws.BindingProvider;
import jakarta.xml.ws.Service;
import java.net.URL;
import javax.xml.namespace.QName;

// Instantiate the service client
URL wsdlURL = new URL("https://localhost:8443/your-context/HelloWorld?wsdl");
QName qname = new QName("http://mastertheboss.com/jaxws", "HelloWorldService");
Service service = Service.create(wsdlURL, qname);
HelloWorld port = service.getPort(HelloWorld.class);

// Configure connection and read timeouts
BindingProvider bp = (BindingProvider) port;
bp.getRequestContext().put("jakarta.xml.ws.client.connectionTimeout", 5000); // 5 seconds
bp.getRequestContext().put("jakarta.xml.ws.client.receiveTimeout", 15000);   // 15 seconds

/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined)
/subsystem=webservices:write-attribute(name=wsdl-secure-port, value=443)
/subsystem=webservices:write-attribute(name=wsdl-uri-scheme, value=https)

curl -X POST -H "Content-Type: text/xml; charset=utf-8" \
  -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:jax="http://mastertheboss.com/jaxws">
        <soapenv:Header/>
        <soapenv:Body>
           <jax:hello>
              <message>World</message>
           </jax:hello>
        </soapenv:Body>
     </soapenv:Envelope>' \
  https://localhost:8443/your-context/HelloWorld

Legacy Archive: Using Apache Axis with JBoss 5

Warning: The content below is preserved for historical purposes and applies strictly to old, non-supported configurations on JBoss 5. For any modern production workloads, use JAX-WS and Apache CXF shown above.

Still not ready for JBoss WS? If you don’t have a JDK 1.5 compliant environment then consider using Axis as your Web Service Engine. It’s robust, stable and easy to setup.

Axis is essentially a SOAP engine, that is a framework for constructing SOAP processors such as clients, servers, gateways, etc. The first thing to do is installing Axis engine on JBoss.

Installing Axis on JBoss

At first download Axis from the Apache project: http://ws.apache.org/axis/java/index.html
Explode the zip folder. Now you need to deploy the Axis engine to JBoss Web Engine (Tomcat).
Here’s how to do it: rename the folder axis under AXIS_HOME/webapps to axis.war and copy the folder under “deploy” of your JBoss

Publishing Web Services with Axis

Let’s say we have a simple class like the following:

package test;

public class HelloWorld {

  public String hello(String message) {

    return "Invoked with " + message;

  }

}

How do we go about making this class available via SOAP? There are a couple of answers to that question, but we’ll start with an easy solution.

At first compile the class:

javac -d . HelloWorld.java

Now copy the class under WEB-INF/classes of your axis.war

Ok, now the last step is registering your Web Service so that Axis is aware of it. A Web Service can be registered with a Deployment Descriptor (WSDD) file. A deployment descriptor contains a bunch of things you want to “deploy” into Axis – i.e. make available to the Axis engine.

Here’s a simple wsdd file for our WebService:

<deployment
xmlns="http://xml.apache.org/axis/wsdd/"
xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

  <service name="HelloWorld" provider="java:RPC">
    <parameter name="className" value="test.HelloWorld"/>
    <parameter name="allowedMethods" value="*"/>
  </service>
</deployment>

Pretty simple, really – the outermost element tells the engine that this is a WSDD deployment, and defines the “java” namespace. Then the service element actually defines the service for us. A service is a targeted chain which means it may have any of: a request flow, a provider, and a response flow.

In this case, our provider is “java:RPC”, which is built into Axis, and indicates a Java RPC service. We need to tell the RPCProvider that it should instantiate and call the correct class (e.g. test.HelloWorld), and another to tell the engine that any public method on that class may be called via SOAP (that’s what the “*” means)

Now save your wsdd file as deploy.wsdd and run the AdminClient which is an Utility to deploy the WebService:

java -classpath %AXIS_HOME%/lib/axis.jar;%AXIS_HOME%/lib/commons-discovery-0.2.jar;%AXIS_HOME%/lib/commons-logging-1.0.4.jar;%AXIS_HOME%/lib/saaj.jar;%AXIS_HOME%/lib/jaxrpc.jar org.apache.axis.client.AdminClient deploy.wsdd

If everything was Ok now you should see the WebService deployed on Axis: check the “List” option from the URL http://localhost:8080/axis/

The client

Let’s take a look at an example Web Service client that will call the hello method of the HelloWorld Web Service:

package test;

import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import javax.xml.namespace.QName;
import java.net.URL;

public class Client {

  public static void main (String args[]) {

    try {

      String url;

      url="http://localhost:8080/axis/services/HelloWorld";

      Service service = new Service();

      Call call = (Call)service.createCall();

      call.setTargetEndpointAddress(new URL(url));

      call.setOperationName(new QName("HelloWorld", "hello"));

      Object[] params = new Object[1];

      params[0] = "Hello Message";

      Object result = call.invoke(params);

      System.out.println("result is " + result);

    }

    catch(Exception e) {

      e.printStackTrace();

    }

 }

}

In order to invoke our Web Service we use the Service and Call objects. These are the standard JAX-RPC objects that are used to store metadata about the service to invoke. With this we set up our endpoint URL – this is the destination for our SOAP message.

call.setTargetEndpointAddress(new URL(url));

With this we define the operation (method) name of the Web Service.

call.setOperationName(new QName("HelloWorld", "hello"));

Then we actually invoke the desired service, passing in an array of parameters – in this case just one String.

Object result = call.invoke(params);

Obtaining WSDL for deployed services

When you make a service available using Axis, there is typically a unique URL associated with that service. For our service it’s http://localhost:8080/axis/services/HelloWorld?wsdl

When you point your browser to that location, Axis will automatically generate a service description for the deployed service, and return it as XML in your browser:

<?xml version="1.0" encoding="UTF-8" ?>
<wsdl:definitions
 targetNamespace="http://localhost:8080/axis/services/HelloWorld"
 xmlns:apachesoap="http://xml.apache.org/xml-soap"
 xmlns:impl="http://localhost:8080/axis/services/HelloWorld"
 xmlns:intf="http://localhost:8080/axis/services/HelloWorld"
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <wsdl:message name="helloRequest">
  <wsdl:part name="in0" type="xsd:string" />
 </wsdl:message>
 <wsdl:message name="helloResponse">
  <wsdl:part name="helloReturn" type="xsd:string" />
 </wsdl:message>
 <wsdl:portType name="HelloWorld">
  <wsdl:operation name="hello" parameterOrder="in0">
   <wsdl:input message="impl:helloRequest" name="helloRequest" />
   <wsdl:output message="impl:helloResponse"
    name="helloResponse" />
  </wsdl:operation>
 </wsdl:portType>
 <wsdl:binding name="HelloWorldSoapBinding" type="impl:HelloWorld">
  <wsdlsoap:binding style="rpc"
   transport="http://schemas.xmlsoap.org/soap/http" />
  <wsdl:operation name="hello">
   <wsdlsoap:operation soapAction="" />
   <wsdl:input name="helloRequest">
    <wsdlsoap:body
     encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
     namespace="http://test" use="encoded" />
   </wsdl:input>
   <wsdl:output name="helloResponse">
    <wsdlsoap:body
     encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
     namespace="http://localhost:8080/axis/services/HelloWorld"
     use="encoded" />
   </wsdl:output>
  </wsdl:operation>
 </wsdl:binding>
 <wsdl:service name="HelloWorldService">
  <wsdl:port binding="impl:HelloWorldSoapBinding"
   name="HelloWorld">
   <wsdlsoap:address
    location="http://localhost:8080/axis/services/HelloWorld" />
  </wsdl:port>
 </wsdl:service>
</wsdl:definitions>

Generating Java Classes from WSDL

Another approach is to generate Java Classes starting from WSDL contract. You can use the AdminClient to follow this approach:

java -classpath %AXIS_HOME%/lib/wsdl4j-1.5.1.jar;%AXIS_HOME%/lib/axis.jar;%AXIS_HOME%/lib/commons-discovery-0.2.jar;%AXIS_HOME%/lib/commons-logging-1.0.4.jar;%AXIS_HOME%/lib/saaj.jar;%AXIS_HOME%/lib/jaxrpc.jar org.apache.axis.wsdl.WSDL2Java http://localhost:8080/axis/services/HelloWorld?wsdl

This will generate the following classes under the service namespace which is localhost\axis\services\HelloWorld:

HelloWorld.java
HelloWorldService.java
HelloWorldServiceLocator.java
HelloWorldSoapBindingStub.java

Generating Java Classes from the WSDL is defined as “top-down” approach, while generating WSDL from Java classes is called “bottom-up” style.

Although bottom-up Web service development may be faster and easier, especially if you are new to Web services, the top-down approach is the recommended way of creating a Web service. By creating the WSDL file first you will ultimately have more control over the Web service, and can eliminate interoperability issues that may arise when creating a Web service using the bottom-up method.