Invoking a SOAP Web Service in Java

1. Overview

In this tutorial, we'll learn how to build a SOAP client in Java with JAX-WS RI. First, we'll generate the client code using the wsimport utility, and then test it using a JUnit.

For those starting out, our introduction to JAX-WS provides great background on the subject.

2. The Web Service

Before we start building a client, we need a server. In this case, a server exposing a JAX-WS web service.

For the purpose of this tutorial, we'll use a web service which will fetch us a country's data, given its name.

2.1. Summary of Implementation

Since we're focusing on building the client, we won't get into the implementation details of our service.

Let's suffice to say that an interface CountryService is used to expose the web service to the external world. To keep things simple, we'll build and deploy the web service using the javax.xml.ws.Endpoint API in our class CountryServicePublisher.

We'll run CountryServicePublisher as a Java application to publish an endpoint that'll accept the incoming requests. In other words, this will be our server.

After starting the server, hitting the URL http://localhost:8888/ws/country?wsdl gives us the web service description file. The WSDL acts as a guide to understand the service's offerings and generate implementation code for the client.

2.2. The Web Services Description Language

Let's look at our web service's WSDL, country:

<?xml version="1.0" encoding="UTF-8"?>
<definitions <!-- namespace declarations -->
    targetNamespace="http://server.ws.soap.baeldung.com/" name="CountryServiceImplService">
    <types>
        <xsd:schema>
            <xsd:import namespace="http://server.ws.soap.baeldung.com/" 
              schemaLocation="http://localhost:8888/ws/country?xsd=1"></xsd:import>
        </xsd:schema>
    </types>
    <message name="findByName">
        <part name="arg0" type="xsd:string"></part>
    </message>
    <message name="findByNameResponse">
        <part name="return" type="tns:country"></part>
    </message>
    <portType name="CountryService">
        <operation name="findByName">
            <input wsam:Action="http://server.ws.soap.baeldung.com/CountryService/findByNameRequest" 
              message="tns:findByName"></input>
            <output wsam:Action="http://server.ws.soap.baeldung.com/CountryService/findByNameResponse" 
              message="tns:findByNameResponse"></output>
        </operation>
    </portType>
    <binding name="CountryServiceImplPortBinding" type="tns:CountryService">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"></soap:binding>
        <operation name="findByName">
            <soap:operation soapAction=""></soap:operation>
            <input>
                <soap:body use="literal" namespace="http://server.ws.soap.baeldung.com/"></soap:body>
            </input>
            <output>
                <soap:body use="literal" namespace="http://server.ws.soap.baeldung.com/"></soap:body>
            </output>
        </operation>
    </binding>
    <service name="CountryServiceImplService">
        <port name="CountryServiceImplPort" binding="tns:CountryServiceImplPortBinding">
            <soap:address location="http://localhost:8888/ws/country"></soap:address>
        </port>
    </service>
</definitions>

In a nutshell, this is the useful information it provides:

• we can invoke the method findByName with a string argument
• in response, the service will return us a custom type of country
• types are defined in an xsd schema generated at the location http://localhost:8888/ws/country?xsd=1:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema <!-- namespace declarations -->
    targetNamespace="http://server.ws.soap.baeldung.com/">
    <xs:complexType name="country">
        <xs:sequence>
            <xs:element name="capital" type="xs:string" minOccurs="0"></xs:element>
            <xs:element name="currency" type="tns:currency" minOccurs="0"></xs:element>
            <xs:element name="name" type="xs:string" minOccurs="0"></xs:element>
            <xs:element name="population" type="xs:int"></xs:element>
        </xs:sequence>
    </xs:complexType>
    <xs:simpleType name="currency">
        <xs:restriction base="xs:string">
            <xs:enumeration value="EUR"></xs:enumeration>
            <xs:enumeration value="INR"></xs:enumeration>
            <xs:enumeration value="USD"></xs:enumeration>
        </xs:restriction>
    </xs:simpleType>
</xs:schema>

That's all we need to implement a client.

Let's see how in the next section.

3. Using wsimport to Generate Client Code

3.1. Maven Plugin

First, let's add a plugin to our pom.xml to use this tool via Maven:

<plugin> 
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxws-maven-plugin</artifactId>
    <version>2.6</version>
    <executions> 
        <execution> 
            <id>wsimport-from-jdk</id>
            <goals>
                <goal>wsimport</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <wsdlUrls>
            <wsdlUrl>http://localhost:8888/ws/country?wsdl</wsdlUrl> 
        </wsdlUrls>
        <keep>true</keep> 
        <packageName>com.baeldung.soap.ws.client.generated</packageName> 
        <sourceDestDir>src/main/java</sourceDestDir>
    </configuration>
</plugin>

Second, let's execute this plugin:

mvn clean jaxws:wsimport

That's all! The above command will generate code in the specified package com.baeldung.soap.ws.client.generated inside the sourceDestDir we provided in the plugin configuration.

Another way to achieve the same would be to use the wsimport utility. It comes out of the box with the standard JDK 8 distribution and can be found under JAVA_HOME/bin directory.

To generate client code using wsimport, we can navigate to the project's root, and run this command:

JAVA_HOME/bin/wsimport -s src/main/java/ -keep -p com.baeldung.soap.ws.client.generated "http://localhost:8888/ws/country?wsdl"

It's important to bear in mind that the service endpoint should be available in order to successfully execute the plugin or command.

Next, let's look at the generated artifacts.

3.2. Generated POJOs

Based on the xsd we saw earlier, the tool will generate a file named Country.java:

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "country", propOrder = { "capital", "currency", "name", "population" })
public class Country {
    protected String capital;
    @XmlSchemaType(name = "string")
    protected Currency currency;
    protected String name;
    protected int population;
    // standard getters and setters
}

As we can see, the generated class is decorated with JAXB annotations for marshalling and unmarshalling the object to and from XML.

Also, it generates a Currency enum:

@XmlType(name = "currency")
@XmlEnum
public enum Currency {
    EUR, INR, USD;
    public String value() {
        return name();
    }
    public static Currency fromValue(String v) {
        return valueOf(v);
    }
}

3.3. CountryService

The second generated artifact is an interface that acts as a proxy to the actual web service.

The interface CountryService declares the same method as our server, findByName:

@WebService(name = "CountryService", targetNamespace = "http://server.ws.soap.baeldung.com/")
@SOAPBinding(style = SOAPBinding.Style.RPC)
@XmlSeeAlso({ ObjectFactory.class })
public interface CountryService {
    @WebMethod
    @WebResult(partName = "return")
    @Action(input = "http://server.ws.soap.baeldung.com/CountryService/findByNameRequest", 
      output = "http://server.ws.soap.baeldung.com/CountryService/findByNameResponse")
    public Country findByName(@WebParam(name = "arg0", partName = "arg0") String arg0);
}

Notably, the interface is marked as a javax.jws.WebService, with a SOAPBinding.Style as RPC as defined by the service's WSDL.

The method findByName is annotated to declare that it's a javax.jws.WebMethod, with its expected input and output parameter types.

3.4. CountryServiceImplService

Our next generated class, CountryServiceImplService, extends javax.xml.ws.Service. Its annotation WebServiceClient denotes that it is the client view of a service:

@WebServiceClient(name = "CountryServiceImplService", 
  targetNamespace = "http://server.ws.soap.baeldung.com/", 
  wsdlLocation = "http://localhost:8888/ws/country?wsdl")
public class CountryServiceImplService extends Service {

    private final static URL COUNTRYSERVICEIMPLSERVICE_WSDL_LOCATION;
    private final static WebServiceException COUNTRYSERVICEIMPLSERVICE_EXCEPTION;
    private final static QName COUNTRYSERVICEIMPLSERVICE_QNAME = 
      new QName("http://server.ws.soap.baeldung.com/", "CountryServiceImplService");

    static {
        URL url = null;
        WebServiceException e = null;
        try {
            url = new URL("http://localhost:8888/ws/country?wsdl");
        } catch (MalformedURLException ex) {
            e = new WebServiceException(ex);
        }
        COUNTRYSERVICEIMPLSERVICE_WSDL_LOCATION = url;
        COUNTRYSERVICEIMPLSERVICE_EXCEPTION = e;
    }

    public CountryServiceImplService() {
        super(__getWsdlLocation(), COUNTRYSERVICEIMPLSERVICE_QNAME);
    }

    // other constructors 

    @WebEndpoint(name = "CountryServiceImplPort")
    public CountryService getCountryServiceImplPort() {
        return super.getPort(new QName("http://server.ws.soap.baeldung.com/", "CountryServiceImplPort"), 
          CountryService.class);
    }

    private static URL __getWsdlLocation() {
        if (COUNTRYSERVICEIMPLSERVICE_EXCEPTION != null) {
            throw COUNTRYSERVICEIMPLSERVICE_EXCEPTION;
        }
        return COUNTRYSERVICEIMPLSERVICE_WSDL_LOCATION;
    }

}

The important method to note here is getCountryServiceImplPort. Given a qualified name of the service endpoint, or QName, and the dynamic proxy's service endpoint interface name, it returns a proxy instance.

To invoke the web service, we need to use this proxy, as we'll see shortly.

Using a proxy makes it seem as if we are calling a service locally, abstracting away the intricacies of remote invocation.

4. Testing the Client

Next, we'll write a JUnit test to connect to the web service using the generated client code.

Before we can do that, we need to get the service's proxy instance at the client end:

@BeforeClass
public static void setup() {
    CountryServiceImplService service = new CountryServiceImplService();
    CountryService countryService = service.getCountryServiceImplPort();
}

For more advanced scenarios such as enabling or disabling a WebServiceFeature, we can use other generated constructors for CountryServiceImplService.

Now let's look at some tests:

@Test
public void givenCountryService_whenCountryIndia_thenCapitalIsNewDelhi() {
    assertEquals("New Delhi", countryService.findByName("India").getCapital());
}

@Test
public void givenCountryService_whenCountryFrance_thenPopulationCorrect() {
    assertEquals(66710000, countryService.findByName("France").getPopulation());
}

@Test
public void givenCountryService_whenCountryUSA_thenCurrencyUSD() {
    assertEquals(Currency.USD, countryService.findByName("USA").getCurrency());
}

As we can see, invoking the remote service's methods became as simple as calling methods locally. The proxy's findByName method returned a Country instance matching the name we provided. Then, we used various getters of the POJO to assert expected values.

5. Conclusion

In this tutorial, we saw how to invoke a SOAP web service in Java using JAX-WS RI and the wsimport utility.

Alternatively, we can use other JAX-WS implementations such as Apache CXF, Apache Axis2, and Spring to do the same.

As always, source code is available over on GitHub.