Preloader image

JAX-WS @WebService example

Creating Web Services with JAX-WS is quite easy. Little has to be done aside from annotating a class with @WebService. For the purposes of this example we will also annotate our component with @Stateless which takes some of the configuration out of the process and gives us some nice options such as transactions and security.

@WebService

The following is all that is required. No external xml files are needed. This class placed in a jar or war and deployed into a compliant Java EE server like TomEE is enough to have the Calculator class discovered and deployed and the webservice online.

import jakarta.ejb.Stateless;
import jakarta.jws.WebService;

@Stateless
@WebService(
        portName = "CalculatorPort",
        serviceName = "CalculatorService",
        targetNamespace = "http://superbiz.org/wsdl",
        endpointInterface = "org.superbiz.calculator.ws.CalculatorWs")
public class Calculator implements CalculatorWs {

    public int sum(int add1, int add2) {
        return add1 + add2;
    }

    public int multiply(int mul1, int mul2) {
        return mul1 * mul2;
    }
}

@WebService Endpoint Interface

Having an endpoint interface is not required, but it can make testing and using the web service from other Java clients far easier.

import jakarta.jws.WebService;

@WebService(targetNamespace = "http://superbiz.org/wsdl")
public interface CalculatorWs {

    public int sum(int add1, int add2);

    public int multiply(int mul1, int mul2);
}

Calculator WSDL

The wsdl for our service is automatically created for us. With the jar deployed in TomEE it is available at http://127.0.0.1:8080/simple-webservice/Calculator?wsdl, inside a war (like the one the test deploys) at http://127.0.0.1:8080/simple-webservice/webservices/Calculator?wsdl

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" name="CalculatorService"
                  targetNamespace="http://superbiz.org/wsdl"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://superbiz.org/wsdl" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <wsdl:types>
    <xsd:schema attributeFormDefault="unqualified" elementFormDefault="unqualified"
                targetNamespace="http://superbiz.org/wsdl" xmlns:tns="http://superbiz.org/wsdl"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <xsd:element name="multiply" type="tns:multiply"/>
      <xsd:complexType name="multiply">
        <xsd:sequence>
          <xsd:element name="arg0" type="xsd:int"/>
          <xsd:element name="arg1" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:element name="multiplyResponse" type="tns:multiplyResponse"/>
      <xsd:complexType name="multiplyResponse">
        <xsd:sequence>
          <xsd:element name="return" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:element name="sum" type="tns:sum"/>
      <xsd:complexType name="sum">
        <xsd:sequence>
          <xsd:element name="arg0" type="xsd:int"/>
          <xsd:element name="arg1" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:element name="sumResponse" type="tns:sumResponse"/>
      <xsd:complexType name="sumResponse">
        <xsd:sequence>
          <xsd:element name="return" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="multiplyResponse">
    <wsdl:part element="tns:multiplyResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="sumResponse">
    <wsdl:part element="tns:sumResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="sum">
    <wsdl:part element="tns:sum" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="multiply">
    <wsdl:part element="tns:multiply" name="parameters"/>
  </wsdl:message>
  <wsdl:portType name="CalculatorWs">
    <wsdl:operation name="multiply">
      <wsdl:input message="tns:multiply" name="multiply"/>
      <wsdl:output message="tns:multiplyResponse" name="multiplyResponse"/>
    </wsdl:operation>
    <wsdl:operation name="sum">
      <wsdl:input message="tns:sum" name="sum"/>
      <wsdl:output message="tns:sumResponse" name="sumResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="CalculatorServiceSoapBinding" type="tns:CalculatorWs">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="multiply">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input name="multiply">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="multiplyResponse">
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
    <wsdl:operation name="sum">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input name="sum">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="sumResponse">
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="CalculatorService">
    <wsdl:port binding="tns:CalculatorServiceSoapBinding" name="CalculatorPort">
      <soap:address location="http://127.0.0.1:8080/simple-webservice/webservices/Calculator"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Accessing the @WebService with jakarta.xml.ws.Service

In our testcase we see how to create a client for our Calculator service via the jakarta.xml.ws.Service class and leveraging our CalculatorWs endpoint interface.

With this we can get an implementation of the interfacce generated dynamically for us that can be used to send compliant SOAP messages to our service.

import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.arquillian.junit.Arquillian;
import org.jboss.arquillian.test.api.ArquillianResource;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.spec.WebArchive;
import org.junit.Test;
import org.junit.runner.RunWith;

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

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;

@RunWith(Arquillian.class)
public class CalculatorTest {

    @ArquillianResource
    private URL base;

    @Deployment(testable = false)
    public static WebArchive war() {
        return ShrinkWrap.create(WebArchive.class, "simple-webservice.war")
                .addClasses(Calculator.class, CalculatorWs.class);
    }

    @Test
    public void test() throws Exception {
        Service calculatorService = Service.create(
                new URL(base.toExternalForm() + "webservices/Calculator?wsdl"),
                new QName("http://superbiz.org/wsdl", "CalculatorService"));

        assertNotNull(calculatorService);

        CalculatorWs calculator = calculatorService.getPort(CalculatorWs.class);
        assertEquals(10, calculator.sum(4, 6));
        assertEquals(12, calculator.multiply(3, 4));
    }
}

For easy testing we use Arquillian with TomEE embedded. The test deploys a war with our service to TomEE, which brings the web service online so we can invoke it. @ArquillianResource injects the base URL of the deployed war, and src/test/resources/arquillian.xml starts TomEE on a random HTTP port:

<arquillian
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    >
  <container qualifier="tomee" default="true">
    <configuration>
      <property name="httpPort">-1</property>
      <property name="stopPort">-1</property>
      <property name="appWorkingDir">target/tomee-embedded</property>
    </configuration>
  </container>
</arquillian>

Running

Running the example can be done from maven with a simple `mvn clean install' command run from the `simple-webservice' directory.

When run you should see output similar to the following.

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.superbiz.calculator.ws.CalculatorTest
INFO: Starting Servlet engine: [Apache Tomcat/11.0.25]
INFO: Version: 10.3.0-SNAPSHOT
INFO: ------------------------- localhost -> /simple-webservice
INFO: Configuring enterprise application: /path/to/examples/simple-webservice/target/tomee-embedded/0/simple-webservice
INFO: Auto-deploying ejb Calculator: EjbDeployment(deployment-id=Calculator)
INFO: Created Ejb(deployment-id=Calculator, ejb-name=Calculator, container=Default Stateless Container)
INFO: Started Ejb(deployment-id=Calculator, ejb-name=Calculator, container=Default Stateless Container)
INFO: Webservice(wsdl=http://localhost:53468/simple-webservice/webservices/Calculator, qname={http://superbiz.org/wsdl}CalculatorService) --> Ejb(id=Calculator)
INFO: Deployed Application(path=/path/to/examples/simple-webservice/target/tomee-embedded/0/simple-webservice)
INFO: Creating Service {http://superbiz.org/wsdl}CalculatorService from WSDL: http://localhost:53468/simple-webservice/webservices/Calculator?wsdl
INFO: Undeploying app: /path/to/examples/simple-webservice/target/tomee-embedded/0/simple-webservice
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.255 s -- in org.superbiz.calculator.ws.CalculatorTest

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Inspecting the messages

The above test case will result in the following SOAP messages being sent between the clien and server.

sum(int, int)

Request SOAP message:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:sum xmlns:ns1="http://superbiz.org/wsdl">
      <arg0>4</arg0>
      <arg1>6</arg1>
    </ns1:sum>
  </soap:Body>
</soap:Envelope>

Response SOAP message:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:sumResponse xmlns:ns1="http://superbiz.org/wsdl">
      <return>10</return>
    </ns1:sumResponse>
  </soap:Body>
</soap:Envelope>

multiply(int, int)

Request SOAP message:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:multiply xmlns:ns1="http://superbiz.org/wsdl">
      <arg0>3</arg0>
      <arg1>4</arg1>
    </ns1:multiply>
  </soap:Body>
</soap:Envelope>

Response SOAP message:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:multiplyResponse xmlns:ns1="http://superbiz.org/wsdl">
      <return>12</return>
    </ns1:multiplyResponse>
  </soap:Body>
</soap:Envelope>

Inside the jar

With so much going on it can make things look more complex than they are. It can be hard to believe that so much can happen with such little code. That’s the benefit of having an app server.

If we look at the jar built by maven, we’ll see the application itself is quite small:

$ jar tvf target/simple-webservice-1.1.0-SNAPSHOT.jar
     0 Sat Feb 18 19:17:06 PST 2012 META-INF/
   127 Sat Feb 18 19:17:04 PST 2012 META-INF/MANIFEST.MF
     0 Sat Feb 18 19:17:02 PST 2012 org/
     0 Sat Feb 18 19:17:02 PST 2012 org/superbiz/
     0 Sat Feb 18 19:17:02 PST 2012 org/superbiz/calculator/
     0 Sat Feb 18 19:17:02 PST 2012 org/superbiz/calculator/ws/
   855 Sat Feb 18 19:17:02 PST 2012 org/superbiz/calculator/ws/Calculator.class
   288 Sat Feb 18 19:17:02 PST 2012 org/superbiz/calculator/ws/CalculatorWs.class

This single jar could be deployed any any compliant Java EE implementation. In TomEE you’d simply place it in the tomee.home/webapps/ directory. No war file necessary. If you did want to create a war, you’d simply place the jar in the WEB-INF/lib/ directory of the war.

The server already contains the right libraries to run the code, such as Apache CXF, so no need to include anything extra beyond your own application code.

APIs Used