⚡︎ BoxLang Module: SOAP Web Services

|:------------------------------------------------------:  |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------:  |

Copyright Since 2023 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

 

Overview

The bx-compat-soap module provides comprehensive SOAP (Simple Object Access Protocol) web services functionality for BoxLang applications. It provides Compatibility for Adobe Coldfusion and Lucee Axis web services functionality. This module enables you to create, consume, and manage SOAP-based web services with automatic WSDL generation, request/response handling, and full support for complex data types.

Features

• 🌐 Automatic WSDL Generation - Generate standards-compliant WSDL documents from BoxLang classes
• 🔄 SOAP Request/Response Handling - Parse and process SOAP envelopes with namespace support
• 📝 Remote Method Invocation - Expose BoxLang methods as SOAP operations via access="remote"
• 🔒 Access Control - Only methods marked as remote are accessible via SOAP
• 🎯 Type Coercion - Automatic type conversion between SOAP XML types and BoxLang types
• 📋 Metadata Extraction - Extract function metadata for WSDL operation definitions
• 🚀 Web Context Support - Full integration with BoxLang web request/response cycle
• ⚡ SOAPAction Routing - Automatic routing based on SOAPAction headers or URL parameters

Installation

Install the module using CommandBox:

box install bx-compat-soap

Usage

Creating a SOAP Web Service

To create a SOAP web service, simply create a BoxLang class with remote methods:

/**
 * Calculator Web Service
 */
class {
    
    /**
     * Add two numbers
     * @a First number
     * @b Second number
     * @return The sum
     */
    remote numeric function add( required numeric a, required numeric b ) {
        return arguments.a + arguments.b;
    }
    
    /**
     * Get user information
     * @userId The user ID to lookup
     * @return User struct
     */
    remote struct function getUser( required string userId ) {
        return {
            id: arguments.userId,
            name: "John Doe",
            email: "[email protected]"
        };
    }
    
    /**
     * Get list of users
     * @limit Maximum number of users to return
     * @return Array of user structs
     */
    remote array function getUsers( numeric limit = 10 ) {
        var users = [];
        for( var i = 1; i <= arguments.limit; i++ ) {
            users.append({
                id: i,
                name: "User #i#"
            });
        }
        return users;
    }
    
    /**
     * This method is NOT accessible via SOAP (not marked as remote)
     */
    public numeric function multiply( required numeric a, required numeric b ) {
        return arguments.a * arguments.b;
    }
}

Accessing the WSDL

The WSDL is automatically generated and accessible via the ?wsdl parameter:

http://yourserver/path/to/Calculator.bx?wsdl

SOAP Request Format

Send SOAP requests to your service endpoint using standard SOAP envelope format:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <ns1:add soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
            xmlns:ns1="http://DefaultNamespace">
            <a xsi:type="xsd:double">5.0</a>
            <b xsi:type="xsd:double">10.0</b>
        </ns1:add>
    </soapenv:Body>
</soapenv:Envelope>

SOAP Response Format

The service returns standard SOAP responses:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soap:Body>
        <addResponse xmlns="http://boxlang.ortussolutions.com/soap/">
            <return>15.0</return>
        </addResponse>
    </soap:Body>
</soap:Envelope>

Error Handling (SOAP Faults)

Errors are returned as standard SOAP faults:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <soap:Fault>
            <faultcode>Server</faultcode>
            <faultstring>Method not found or not accessible: multiply</faultstring>
            <detail>Only methods with access="remote" can be invoked via SOAP</detail>
        </soap:Fault>
    </soap:Body>
</soap:Envelope>

Consuming SOAP Web Services

Using createObject()

The easiest way to consume a SOAP web service is using BoxLang's createObject() function:

// Create a SOAP web service instance
ws = createObject( "webservice", "http://example.com/Calculator.bx?wsdl" );

// Call methods directly on the web service object
result = ws.add( 5, 10 );
writeOutput( "5 + 10 = #result#" );

// Call methods with named arguments
user = ws.getUser( userId = "123" );
writeOutput( "User: #user.name# (#user.email#)" );

// Get multiple results
users = ws.getUsers( limit = 5 );
for( user in users ) {
    writeOutput( "#user.id#: #user.name#<br>" );
}

Advanced SOAP Client Usage

For more control over the SOAP request, you can configure the web service instance:

// Create web service with custom configuration
ws = createObject( 
    "webservice", 
    "http://example.com/Calculator.bx?wsdl",
    {
        timeout: 30,
        username: "admin",
        password: "secret"
    }
);

// Call methods
result = ws.complexCalculation( 
    operation = "multiply",
    values = [1, 2, 3, 4, 5]
);

Handling SOAP Faults

SOAP faults are automatically converted to BoxLang exceptions:

try {
    ws = createObject( "webservice", "http://example.com/Calculator.bx?wsdl" );
    
    // Try to call a non-remote method (will throw exception)
    result = ws.multiply( 5, 10 );
    
} catch( any e ) {
    writeOutput( "SOAP Error: #e.message#" );
    writeOutput( "Detail: #e.detail#" );
}

Programmatic Usage

You can also use the SOAP components programmatically within your BoxLang code:

Generate WSDL

controller = new bxmodules.bxsoap.public.WSDLController();
wsdl = controller.getWSDL( class = "com.myapp.services.Calculator" );
writeOutput( wsdl );

Invoke a Service Method

controller = new bxmodules.bxsoap.public.WSDLController();
result = controller.invokeServiceMethod(
    class = "com.myapp.services.Calculator",
    targetMethod = "add",
    args = { a: 5, b: 10 }
);

Module Components

WSDLController

The main controller for WSDL generation and SOAP request handling.

Methods:

• getWSDL( required string class ) - Generate WSDL for a given class
• invokeServiceMethod( required string class, required string targetMethod, struct args = {} ) - Invoke a remote method

WSDLGenerator

Generates WSDL XML documents from BoxLang class metadata.

Features:

• Automatic type mapping (BoxLang types to XSD types)
• Complex type definitions for structs and arrays
• SOAP binding definitions
• Service endpoint configuration

SOAPParser

Parses incoming SOAP requests and extracts method name and parameters.

Features:

• Namespace-aware XML parsing
• Support for simple and complex types
• Automatic parameter extraction
• Type attribute handling (xsi:type)

SOAPResponseBuilder

Builds SOAP response envelopes and SOAP faults.

Features:

• Automatic response structure generation
• Complex type serialization (structs, arrays)
• SOAP fault formatting
• Namespace management

ServiceInvoker

Handles dynamic invocation of BoxLang methods with type coercion.

Features:

• Class loading and instantiation
• Method metadata extraction
• Parameter order resolution
• Access control validation (remote only)

ServiceMetadataExtractor

Extracts function metadata from BoxLang classes for WSDL generation.

Features:

• Remote method filtering
• Parameter type extraction
• Return type determination
• Documentation hint parsing

Supported Data Types

Simple Types

• string → xsd:string
• numeric → xsd:double
• boolean → xsd:boolean
• date → xsd:dateTime

Complex Types

• struct → Complex type with named elements
• array → Array type with sequential items
• any → xsd:anyType

Configuration

The module can be configured in your Application.bx:

component {
    this.name = "MySOAPApp";
    
    // Module settings
    this.modules = {
        "bx-compat-soap": {
            // Default namespace for WSDL generation
            defaultNamespace: "http://mycompany.com/soap/",
            
            // SOAP version (1.1 or 1.2)
            soapVersion: "1.1"
        }
    };
}

Requirements

• BoxLang 1.0.0+
• BoxLang Web Support module (for web request handling)

Development

Running Tests

Execute the test suite:

gradle test

Building the Module

Build the module JAR:

gradle build

Support

• Documentation: BoxLang Documentation
• Issues: GitHub Issues
• Community: BoxLang Slack

Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12