1. Overview
Simply put, Web Services Description Language (WSDL) is an XML-based language that describes the functionality offered by a web service. WSDL stubs are proxy classes generated from a WSDL file, making it easier to interact with a web service without manually creating and managing SOAP messages.
In this tutorial, we’ll learn how to generate WSDL stubs with Gradle. Also, we’ll see an example WSDL file and generate stubs from it.
2. Example Setup
To generate begin, let’s create a new Gradle project that generates WSDL stubs from a WSDL file. Next, we’ll create the directory structure for the WSDL file:
$ mkdir -p src/main/resources/wsdl
We’ll use a public WSDL file that converts a number to its word equivalent. Let’s download the WSDL file and place it in the wsdl folder:
$ curl -o src/main/resources/wsdl/NumberConversion.wsdl https://www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL
The above command downloads the WSDL file from dataacess.com and places it in the specified folder.
In the next section, we’ll configure build.gradle to generate classes that we can interact with in our sample program.
3. Gradle Configuration
To generate Java classes from WSDL files, we need a plugin that uses the Apache CXF library. One such plugin is com.github.bjornvester.wsdl2java, which we’ll use in this tutorial. This plugin simplifies the process and allows us to configure gradle.build:
plugins {
id 'java'
id("com.github.bjornvester.wsdl2java") version "1.2"
}
The project requires two plugins. The Java plugins help us compile the code, run tests, and create JAR files. The WSDL plugin helps us generate Java classes from WSDL files. WSDL files, as we know, are XML documents that describe a web service.
We can configure the WSDL plugin using the wsdl2java extension:
wsdl2java {
// ...
}
Also, we can configure the CXF version:
wsdl2java {
cxfVersion.set("3.4.4")
}
By default, the plugin creates stubs for all WSDL files in the resources folder. We can also configure it to create a stub for a specific WSDL file by specifying its location:
wsdl2java {
// ...
includes = [
"src/main/resources/wsdl/NumberConversion.wsdl",
]
// ...
}
Additionally, the generated classes are saved in the build/generated/sources/wsdl2java folder, but we can override that by specifying our own folder:
wsdl2java {
// ...
generatedSourceDir.set(layout.projectDirectory.dir("src/generated/wsdl2java"))
// ...
}
In the code above, we specify where to store the generated classes instead of using the default folder.
After configuration, we need to run the Gradle wsdl2java command to generate the stubs:
$ ./gradlew wsdl2java
The command above generates the Java classes, and we can now interact with them in our program.
4. Generating WSDL Stubs From WSDL File
First, let’s examine the build.gradle file of our sample project:
plugins {
id 'java'
id("com.github.bjornvester.wsdl2java") version "1.2"
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.sun.xml.ws:jaxws-ri:4.0.1'
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
}
test {
useJUnitPlatform()
}
wsdl2java {
cxfVersion.set("3.4.4")
}
The sample code above shows how to configure the WSDL plugin to use CXF version 3.4.4. The plugin generates the stubs in the default location and looks for the WSDL file in src/main/resources/wsdl. This is where we placed our WSDL file earlier.
Also, we need the Java API for XML Web Services (JAX-WS) dependency to interact with the service and execute the unit test.
To generate Java classes from the WSDL file, we can execute the Gradle wsdl2java command:
$ ./gradlew wsdl2java
Here are the generated Java classes:
The generated classes are stored in the default location. Next, let’s interact with the classes by writing a unit test:
@Test
public void givenNumberConversionService_whenConvertingNumberToWords_thenReturnCorrectWords() {
NumberConversion service = new NumberConversion();
NumberConversionSoapType numberConversionSoapType = service.getNumberConversionSoap();
String numberInWords = numberConversionSoapType.numberToWords(BigInteger.valueOf(10000000));
assertEquals("ten million", numberInWords);
}
In the sample unit test above, we create a new instance of NumberConversion and invoke the getNumberConversionSoap() method on the service object to get a reference to the NumberConversionSoapType object.
Furthermore, we invoke the numberToWords() method on numberConversionSoapType and pass the value of 1000000 as an argument.
Finally, we assert that the expected value is equal to the output.
5. Conclusion
In this article, we learned how to generate WSDL stubs using Gradle. Additionally, we saw how to customize the plugin configuration, such as specifying the CXF version and the output directory for the generated classes. Also, we discussed how to interact with the generated classes by writing a unit test.
As always, the complete source code for the examples is available over on GitHub.
