Generating a SOAP Client from WSDL in Ballerina

Introduction

This article explains how to generate a SOAP client using the Ballerina WSDL tool to interact with a SOAP web service. This was written using Ballerina Swan Lake Update 11.0 (2201.11.0) but is expected to remain compatible with newer versions.

What is WSDL?

WSDL (Web Services Description Language) is an XML-based language that describes the functionalities of a web service. It defines operations, messages, and bindings in a standardized format.

Why Ballerina?

Ballerina is a programming language designed for integration, including working with SOAP and REST services. The Ballerina WSDL tool, introduced in version 2201.11.0, allows developers to generate Ballerina files from a WSDL specification, eliminating the need to manually create client code and types for SOAP services.

Use Case: Calculator SOAP Service

This tutorial demonstrates how to connect to a SOAP service that performs arithmetic operations such as addition, subtraction, multiplication, and division. The following steps will show you how to,

1. Generate a SOAP client/s and necessary types.
2. Create a Ballerina project and use the generated client/s to interact with a SOAP service

Before we begin, make sure you have,

• Installed Ballerina (download it here)
• If already installed, update to the latest version : bal dist update
• Import the latest WSDL tool : bal tool pull wsdl

Getting Started

1. Create a New Ballerina Project

First, create a new Ballerina project to organize your files.

bal new calculator_soap_client

This command creates a standard Ballerina project structure with a main.bal file for your application logic.

2. Generate the SOAP Client and Types

Use the bal wsdl command to generate a SOAP client and types based on the WSDL file. Replace **<WSDL_SOURCE_FILE>** with the path to the WSDL file for the service.

bal wsdl <WSDL_SOURCE_FILE>

This command generates the following files inside the Ballerina project.

• ***client.bal / <soap_port_name + client>.bal***: Client/s to interact with the SOAP service
• ***types.bal* : Types corresponding to the WSDL messages and operations

Example: Calculator Service

Let’s try this with a publicly available calculator SOAP service.

1. Save the WSDL content from this link to a file named calculator.wsdl in your Ballerina project. ***http://www.dneonline.com/calculator.asmx?WSDL***
2. Execute the following command to generate a client and types for the SOAP 1.2 endpoint.

bal wsdl calculator.wsdl --port CalculatorSoap12

This command will generate these files in your project directory.

• **client.bal* - SOAP client for the CalculatorSoap12* port (SOAP 1.2 protocol) as Client
• **types.bal** - Types related to the operations in the calculator SOAP service

But if you want to generate clients for all the endpoints mentioned in the WSDL spec, you can just use the following command

bal wsdl calculator.wsdl

The command will generate these files in your project directory.

• **calculator_soap_client.bal* - SOAP client for the CalculatorSoap* port (SOAP 1.1 protocol) as CalculatorSoapClient
• **calculator_soap12_client.bal* - SOAP client for the CalculatorSoap12* port (SOAP 1.2 protocol) as CalculatorSoapClient12
• **types.bal** - Types related to the operations in the calculator SOAP service

For most use cases, generating a single client is sufficient and simplifies your project structure.

Advanced Options

Generate Client for a Specific Port

The --port flag is particularly useful when,

• You want to work with only one SOAP protocol version
• The WSDL specification includes multiple service endpoints
• You want a cleaner project structure with just one client file

bal wsdl calculator.wsdl --port <port-name>

This will generate a single client as Client in the client.bal file containing only the operations specified for the SOAP port.

Generate Specific Operations

To generate the client for specific operations, use the following command.

bal wsdl calculator.wsdl --operations https://example.com/soapAction1

The specific operations should be defined by their SOAP action URIs.

Specify a Custom Module

Use the following command to place the generated files in a specific module within the project. The files will be placed inside the modules/custom directory within the project

bal wsdl calculator.wsdl --module custom

3. Add Application Logic

After generating the SOAP client and types, you need to implement your application logic. Replace the contents of the default main.bal file with the following code.

import ballerina/io;

public function main(int intA, int intB) returns error? {
    Client soap = check new ();
    MultiplySoapRequest request = {
        Body: {
            Multiply: {
                sequenceGroup4: {
                    intA,
                    intB
                }
            }
        }
    };
    MultiplySoapResponse response = check soap->multiply(request);
    MultiplyResponse? result = response.Body.MultiplyResponse;
    if result !is () {
        io:println("Result: ", result.sequenceGroup5.MultiplyResult);
    }
}

Here, you don’t need to explicitly set the URL for the SOAP service as it is set by default in the generated client. This initializes the SOAP client and demonstrates the Add and Subtract operations provided by the calculator service.

4. Run the Project

To execute the project, use the following command including values for intA and intB arguments.

bal run -- 5 10

Example Output:

You should see the result of the multiplication operation in your console.

Result: 50

Conclusion

The Ballerina WSDL tool significantly simplifies the integration process with SOAP services. By generating a client directly from a WSDL specification, developers can quickly focus on business logic without worrying about low-level SOAP handling.

This article demonstrated how to create a Ballerina project, generate a SOAP client, and use it to interact with a web service. The same approach can be applied to other SOAP endpoints by using their respective WSDL specifications.

The complete code for this tutorial is available in this repository, including the calculator WSDL file we used. If you encounter any issues, feel free to leave a comment.