Article

How to use a Java SOAP client library created from wsdl2java and Apache CXF on Eclipse

Author:
Jirapongse Phuriphanvichai
Developer Advocate Developer Advocate

Simple Object Access Protocol (SOAP) was initially developed by Microsoft in 1998. It is a lightweight XML-based protocol for exchanging structured information over various standard network protocols, such as Hypertext Transfer Protocol (HTTP).  It is typically used to implement web services. SOAP also provides Web Services Description Language (WSDL) which is an XML based definition language. The file is used for describing the functionality of a SOAP based web service. There are several tools that can parse WSDL files and then generate classes or libraries in different programing languages, such as C#, Python, and Java to access SOAP based web services. 

This article introduces the wsdl2java tool in Apache CXF which is an open-source tool that can be used to generate JAVA classes and libraries from WSDL files. It also demonstrates how to use the wsdl2java tool to generate a Java SOAP client library from a DACS Station web service and use that library on Eclipse IDE for Java Developers. To use Apache CXF on Maven, please refer to the How to use wsdl2java and Apache CXF to generate a Java SOAP client library on Maven article.  

Apache CXF

Apache CXF is an open source software project. It helps developers build and develop Web services frameworks that support a variety of protocols such as SOAP, XML/HTTP, RESTful HTTP, or CORBA. It also provides tools for generating code, generating WSDLs, adding endpoints and support files, and validating WSDLs. The following sections will demonstrate how to use the wsdl2java tool to generate a Java SOAP client library from a SOAP web service (DACS Station Web Service) and use that library on Eclipse.

Setup an environment

The versions of Software applications used in this article are:

  1. Java 17.0.9
  2. Eclipse IDE for Java Developers 2023-12 (4.30.0)
  3. Apache CXF 4.0.3

Download and install those Software applications on the machine. Then, set the following environment variables.

 

Variable Name Value Example
JAVA_HOME <Java installation path> C:\Program Files\Java\jdk-17
CXF_HOME <Apache CXF installation path> C:\tools\apache-cxf-4.0.3
PATH <Java installation path>/bin
<Apache CXF installation path>/bin

 C:\Program Files\Java\jdk-17; C:\tools\apache-cxf-4.0.3\bin

 

On Windows operating systems, the following commands can be used.

    	
            
SET JAVA_HOME=C:\Program Files\Java\jdk-17


SET CXF_HOME=C:\tools\apache-cxf-4.0.3


SET PATH=%JAVA_HOME%\bin;%CXF_HOME%/bin;%PATH%

On Linux operating systems, the following commands can be used.

    	
            
export JAVA_HOME=/usr/java/jdk1.7.0_05


export CXF_HOME=/opt/tools/apache-cxf-4.0.3


export PATH=$JAVA_HOME/bin:$CXF_HOME/bin:$PATH

Run the following commands to verify the environment variables are set correctly.

    	
            
C:\>java --version


java 17.0.9 2023-10-17 LTS


Java(TM) SE Runtime Environment (build 17.0.9+11-LTS-201)


Java HotSpot(TM) 64-Bit Server VM (build 17.0.9+11-LTS-201, mixed mode, sharing)


 


C:\>wsdl2java


Missing argument: wsdlurl


 


Usage : wsdl2java -fe|-frontend <front-end-name> -db|-databinding <data-binding-name> -wv <wsdl-version> -p <[wsdl-namespace =]package-name>* -sn <service-name> -b <binding-file-name>* -reserveClass <class-name>* -catalog <catalog-file-name> -d <output-directory> -compile -classdir <compile-classes-directory> -impl -server -client -clientjar <jar-file-name> -all -autoNameResolution -allowElementReferences|-aer<=true> -defaultValues<=class-name-for-DefaultValueProvider> -ant -nexclude <schema-namespace [= java-package-name]>* -exsh <(true, false)> -noTypes -dns <Default value is true> -dex <(true, false)> -validate<[=all|basic|none]> -keep -wsdlLocation <wsdlLocation> -xjc<xjc-arguments>* -asyncMethods<[=method1,method2,...]>* -bareMethods<[=method1,method2,...]>* -mimeMethods<[=method1,method2,...]>* -noAddressBinding -faultSerialVersionUID <fault-serialVersionUID> -encoding <encoding> -exceptionSuper <exceptionSuper> -seiSuper <seiSuper>* -mark-generated -suppress-generated-date -maxExtensionStackDepth <maxExtensionStackDepth> -h|-?|-help -version|-v -verbose|-V -quiet|-q|-Q -wsdlList <wsdlurl>

Use wsdl2java with Eclipse IDE for Java Developers

wsdl2java is a command-line tool that takes a WSDL document and generates fully annotated Java code or library from which to implement a service. In this section, I will demonstrate how to use this tool to generate a Java library for the DACS Station Web Service and then use this library on Eclipse IDE for Java Developers.

 

1. Run the wsdl2java command

Run the following command on the command prompt or console to generate the jar file which contains all generated Java SOAP client classes of the DACS Station Web Service. 

    	
            wsdl2java.bat -clientjar dacs_client.jar http://<DACS_IP_Address>:8080/DacsWS/DacsWebServiceService?wsdl

It uses the -clientjar option which generates the jar file which contains all client classes. http://<DACS_IP_Address>:8080/DacsWS/DacsWebServiceService?wsdl is the location of the WSDL file of the DACS Station Web Service. The name of the jar file is dacs_client.jar.

2. Create a Java project

To use that jar file, I created a new Java project on Eclipse IDE for Java Developers. 

The project uses Java 17 and I unchecked the “Create module-info.java file” option. 

3. Add the dacs_client.jar file

Then, add the dacs_client.jar file created from the wsdl2java tool to the Classpath of the Java project. Open the project’s properties page, and the select Java Build Path to add the dacs_client.jar file as an external jar.

4. Add Apache CXF jar files

To use the generated jar file (dacs_client.jar), the Apache CXF jar files are required. The Apache CXF jar files are in the <Apache CXF installation path>/lib folder. You can add the Apache CXF manifest jar file (cxf-manifest.jar) to the Classpath of the project. 

5. Add the DACS example source code

Add a new Java class with the main method to implement the sample DACS Web Service client application. The source code is available on GitHub. 

In the source code, change the <DACS IP Address> in the dacs_wsdl variable to the IP address of a DACS server and change the <DACS Admin> and <DACS Admin Password> in the dacs_username, and dacs_password variables respectively. 

The example connects to the DACS Station Web Service and then displays DACS version, DACS site names, and DACS users, and entitlement data. 

6. Build and run the code

Then, build and run the code. The output will look like this.

The example also creates the dacs_permission.csv file that contains entitlement data for all users in DACS.

Summary

Simple Object Access Protocol (SOAP) is an XML-based web service protocol. Each SOAP web service provides a WSDL file which describes the definition and functionality of the web service. Wsdl2java is a tool in the Apache CXF that can generate Java classes and libraries from WSDL files. Then, the generated Java classes or libraries can be added to a Java project in Eclipse to access the SOAP web services. 

References

  1. Apache CXF: An open-source services framework (no date) Apache CXF -- Index. Available at: https://cxf.apache.org/ (Accessed: 08 January 2024). 
  2. Gillis, A.S. (2022) What is soap?, App Architecture. Available at: https://www.techtarget.com/searchapparchitecture/definition/SOAP-Simple-Object-Access-Protocol (Accessed: 08 January 2024). 
  3. Soap (2023) Wikipedia. Available at: https://en.wikipedia.org/wiki/SOAP (Accessed: 08 January 2024).