Creating a Java client from a SOAP webservice

Imagine that you receive a request to integrate with a third-party service and the web service protocol that the third-party is using is SOAP and not REST. In this post, we are going to see how to integrate with a SOAP web service using a Java client.

WSDL is the contract in SOAP

In SOAP web services the WSDL is the contract between the client and the server and it’s where all the input/output requests are defined, the operations that the service has, and even the exceptions. One important point when we are dealing with SOAP web services is that

The third-party should not change the specification of the web service without informing all the clients

otherwise, the clients will break if there’s an operation that changes the signature of the method or changes the return type, or changes any of the attributes of a particular class.

The good practice is to create a new version of the WSDL for the clients that are integrated and give time to them to migrate to the new version without breaking their integrations.

If your are interested on learning more about maintining backward compatibility you can read this post that I wrote some time ago.

Third-party party provides a client to integrate

First of all, we have to check if the third-party provides us a client to integrate with his service. Some companies can provide a client for the programming language in which we are developing but maybe they have a php client or a python client and not Java. Keep reading if you are in this situation.

No client provided - Why creating a client?

Your code should not be coupled to a third-party library.

When you create a client you are defining a specific version of the SOAP web service that your applications are going to use.

The client that you create will be a jar file with a version in the jar name, so your application will depend on a specific version of the client generated by you that uses a specific version of the WSDL.

A client helps reusing code because the classes that you generate from the WSDL will be reused by all the applications that use that client and if the client has builders or any other kind of functionality (interceptors, guice modules…) for the clients it can be reused also.

Generating Java files from WSDL with Maven

To be able to use wsimport automatically in your client you can use the jaxws-maven-plugin to automate the WSDL parsing and the placement of the Java files autogenerated in the folder that you define in the source destination.

In the following example, we are parsing the AdParamService WSDL of Google Adwords API.

<build>
   <plugins>
       <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>jaxws-maven-plugin</artifactId>
            <version>2.6</version>
            <executions>
                <execution>
                <id>import_1</id>
                <goals>
                    <goal>wsimport</goal>
                </goals>
                <configuration>
                    <sourceDestDir>${project.basedir}/target/generated-sources/</sourceDestDir>
                    <wsdlUrls>
                        <wsdlUrl>https://adwords.google.com/api/adwords/cm/v201809/AdParamService?wsdl</wsdlUrl>
                    </wsdlUrls>
                <xadditionalHeaders>true</xadditionalHeaders>
                <!-- The name of your generated source package -->
                <packageName>com.google.api.adwords.aps</packageName>
            </configuration>
            </execution>
            </executions>
        </plugin>

Skipping from static code analysis maven plugins

In case that you are using Maven plugins to ensure that you are following certain rules to ensure the code quality of your code, in this case, we need to exclude the files autogenerated from checkstyle plugin and from pmd because we don’t have control over this autogenerated classes and we don’t want to change them as they are autogenerated.

<profiles>
   <profile>
       <!-- Activate this profile to run unit tests and continuous integration checks. -->
       <id>run-code-checks</id>
       <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-checkstyle-plugin</artifactId>
                        <configuration>
                        <sourceDirectory>${project.basedir}/target/**</sourceDirectory>
                        </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-pmd-plugin</artifactId>
                <inherited>true</inherited>
                <configuration>
                <excludes>
                    <exclude>generated-sources/com/google/**</exclude>
                </excludes>
                </configuration>
            </plugin>

Conclusion

In this post, we have seen why we should have our own Java client if it’s not provided by the third-party that we have to integrate with. We have seen how to generate files from WSDL using a maven plugin and we have seen how to skip the validation of some maven plugins.