By Thisara Priyamal in Java SOAP Web Services — 19 Jul 2025

Java වල SOAP Web Services පාවිච්චි කරමු: Client Stubs හදලා Calls ගන්න හැටි (Sinhala Guide)

ආයුබෝවන් හැමෝටම! 👋

ඔයාලා software engineering වල ඉන්න කෙනෙක් නම්, නැත්නම් ඒ පැත්තට එන්න බලාගෙන ඉන්න කෙනෙක් නම්, APIs ගැන අනිවාර්යෙන්ම අහලා ඇති. අද කාලේ, REST APIs ගැන තමයි ගොඩක් අය කතා කරන්නේ. ඒක ඇත්ත, REST API ගොඩක් පහසුයි, lightweight, ඒ වගේම web development වලට ගොඩක් හොඳ විසඳුමක්. ඒත්, සමහර වෙලාවට අපිට enterprise level systems එක්ක වැඩ කරන්න වෙනවා, ඒ වගේම banking, healthcare, government sectors වගේ තැන්වල, තවමත් SOAP Web Services කියන කාරණාව අනිවාර්යෙන්ම හම්බවෙනවා. මේවා පරණ තාක්ෂණයක් වුණත්, Security, Transactions, Reliability වගේ දේවල් වලට SOAP තාමත් ජනප්‍රියයි, ඒ වගේම ඒවා තාමත් ලොකු systems වල backbone එක විදිහට පාවිච්චි වෙනවා.

ඉතින්, මේ blog post එකෙන් අපි බලමු Java වලින් SOAP Web Service එකක් පාවිච්චි කරන්නේ කොහොමද කියලා. ඒකට අවශ්‍ය client stubs හදාගන්නේ කොහොමද, ඒ වගේම ඒ stubs පාවිච්චි කරලා services වලට calls කරන්නේ කොහොමද කියන එක පියවරෙන් පියවර පැහැදිලිව ඉගෙන ගමු. ගොඩක් අය මේක ටිකක් සංකීර්ණ දෙයක් කියලා හිතුවත්, මේ guide එක කියෙව්වට පස්සේ ඔයාලට ඒක ගොඩක් ලේසි වෙයි. එහෙනම්, අපි පටන් ගමු!

SOAP Web Services කියන්නේ මොනවද? 🤔

හරි, මුලින්ම බලමු මේ SOAP කියන්නේ මොනවද කියලා. SOAP කියන්නේ Simple Object Access Protocol කියන එකට. ඒක XML-based messaging protocol එකක්, application දෙකක් අතරේ structured information හුවමාරු කරගන්න පාවිච්චි කරන. ගොඩක් වෙලාවට HTTP/S උඩ තමයි මේ messages යවන්නේ. ඒත් SMTP, TCP වගේ වෙනත් protocols උඩත් යවන්න පුළුවන්. SOAP වල ප්‍රධානම දේ තමයි ඒක XML මත පදනම් වෙලා තියෙන එක. හැම request එකක්ම, හැම response එකක්ම XML format එකෙන් තමයි තියෙන්නේ.

REST API එකක් වගේ 'stateless' concept එකකට වඩා, SOAP ටිකක් 'stateful' context එකකට වැඩියෙන් හුරුයි. ඒ වගේම, REST API වලට සාමාන්‍යයෙන් formal contract එකක් නැති වුණත්, SOAP වලට WSDL (Web Services Description Language) කියන එක අනිවාර්යයෙන්ම තියෙන්න ඕනේ. WSDL කියන්නේ XML format එකෙන් ලියපු contract එකක් වගේ දෙයක්. ඒකෙන් කියනවා service එකේ මොනවගේ operations ද තියෙන්නේ (methods මොනවද), ඒ operations වලට මොනවගේ parameters ද ඕනේ, මොනවගේ return values ද ලැබෙන්නේ කියලා. ඒ වගේම, service එක හොයාගන්න පුළුවන් endpoint URL එකත් ඒකේ තියෙනවා. මේ WSDL එක තමයි අපිට client stubs හදාගන්න අත්‍යවශ්‍ය වෙන්නේ.

SOAP තවමත් enterprise systems වල ජනප්‍රිය වෙන්න හේතු කීපයක් තියෙනවා:

Strict Contract (WSDL): WSDL එකක් තියෙන නිසා, client හා server අතරේ communication එකට ඉතා පැහැදිලි contract එකක් තියෙනවා. මේක නිසා interoperability (විවිධ platforms වල වැඩ කිරීමේ හැකියාව) වැඩි වෙනවා.
Built-in Security (WS-Security): SOAP වලට WS-Security වගේ standard extensions තියෙනවා messages encrypt කරන්න, digital signatures add කරන්න, authentication implement කරන්න. මේවා enterprise applications වලට අත්‍යවශ්‍යයි.
Reliability (WS-ReliableMessaging): Message delivery reliability සහ ordering වගේ දේවල් handle කරන්න SOAP extensions තියෙනවා.
Transactions (WS-AtomicTransaction): Distributed transactions manage කරන්නත් SOAP වලට support තියෙනවා.

WSDL එකෙන් Client Stubs හදමු 🛠️

SOAP Web Service එකක් consume කරන්න නම්, අපිට ඒ service එකත් එක්ක කතා කරන්න පුළුවන් Java classes ටිකක් ඕනේ. මේවට තමයි "Client Stubs" කියන්නේ. මේ stubs මගින් service එකට යවන XML messages construct කරන එකයි, service එකෙන් එන XML response messages parse කරන එකයි සිදු කරනවා. වාසනාවකට වගේ, Java JDK එකේ wsimport කියන tool එක තියෙනවා. මේක පාවිච්චි කරලා අපිට WSDL එකක් දුන්නම, ඒකට අදාළ client stubs ටික automatically generate කරගන්න පුළුවන්. මේක Java Architecture for XML Web Services (JAX-WS) වල කොටසක්.

අපි මේ guide එකට, පහත public calculator service එක උදාහරණයට ගමු. මේකෙන් Add කියන operation එක පාවිච්චි කරලා numbers දෙකක් එකතු කරන්න පුළුවන්:

http://www.dneonline.com/calculator.asmx?wsdl

දැන් ඔයාලගේ command prompt (Windows) හෝ Terminal (macOS/Linux) එක open කරලා, පහත command එක run කරන්න:

wsimport -keep -verbose http://www.dneonline.com/calculator.asmx?wsdl

මේ command එක run කරාම මොකද වෙන්නේ කියලා බලමු:

-keep: Generate වෙන source files (.java) තියාගන්න කියලා කියනවා. නැත්නම් ඒවා compile කරලා .class files විතරක් ඉතිරි වෙනවා. source files තියාගන්න එක code එක examine කරන්න හොඳයි.
-verbose: Process එකේ හැම step එකක්ම console එකේ print කරනවා. මොනවද වෙන්නේ කියලා දැනගන්න මේක හොඳයි, විශේෂයෙන්ම errors ආවොත්.
http://www.dneonline.com/calculator.asmx?wsdl: මේක තමයි අපේ WSDL URL එක. wsimport tool එක මේ URL එකට ගිහින් WSDL document එක download කරගෙන, ඒක parse කරලා Java classes generate කරනවා.
අමතර Options:
- -d <output_directory>: Generate වන classes file save කරන්න ඕන folder එක specify කරන්න පුළුවන්. (උදා: -d src/main/java)
- -p <package_name>: Generate වන classes වලට වෙනම package එකක් දෙන්න පුළුවන්. (උදා: -p com.mycompany.calculatorservice)

මේ command එක සාර්ථකව run වුණාට පස්සේ, ඔයාලා command run කරපු directory එක ඇතුලේ com/dneonline/www වගේ package structure එකක් හැදිලා, ඒ ඇතුලේ Java files ගොඩක් generate වෙලා තියෙයි. මේවා තමයි අපේ client stubs. උදාහරණයක් විදිහට, මේ Calculator service එකට අදාළව පහත වගේ classes ටිකක් generate වෙලා තියෙයි:

Calculator.java: මේක තමයි service class එක. මේකෙන් service instance එක හදාගන්න පුළුවන්.
CalculatorSoap.java: මේක service එකේ operations define කරලා තියෙන interface එක. අපේ Add() method එක මේකේ තියෙනවා.
Add.java: Add operation එකට යවන request parameters (input values) අඩංගු class එක.
AddResponse.java: Add operation එකෙන් ලැබෙන response parameters (output values) අඩංගු class එක.
ඒ වගේම, service එකේ XML elements Java objects වලට map කරන්න අවශ්‍ය තව classes කීපයක් (ObjectFactory වැනි) generate වෙනවා.

Client Stubs පාවිච්චි කරලා SOAP Call එකක් කරමු 📞

හරි, දැන් අපිට client stubs ටික තියෙනවා. ඊළඟට කරන්න තියෙන්නේ මේවා පාවිච්චි කරලා SOAP Web Service එකට call එකක් දීලා, ඒකෙන් data retrieve කරගන්න එක. මේ සඳහා අපි standard Java code එකක් ලියනවා.

අපි කලින් generate කරගත්තු Calculator service එක පාවිච්චි කරලා, අංක දෙකක් එකතු කරලා බලමු.

මුලින්ම, generate වුණු Service class එකේ instance එකක් හදාගන්න ඕනේ. අපේ උදාහරණයේදී ඒක Calculator කියන class එක. ඊට පස්සේ, getPort() method එක පාවිච්චි කරලා service port එක retrieve කරගන්න ඕනේ. මේ service port එක තමයි ඇත්තටම service operations access කරන්න පුළුවන් interface එක. අපේ උදාහරණයේදී ඒක CalculatorSoap කියන interface එක.

මෙන්න මේක කරන විදිහ:

import com.dneonline.www.Calculator;
import com.dneonline.www.CalculatorSoap;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.soap.SOAPFaultException;
import java.util.Map;

public class CalculatorClient {

    public static void main(String[] args) {
        try {
            // 1. Create a service instance
            // මේකෙන් තමයි WSDL එකේ define කරපු service එකේ object එකක් හැදෙන්නේ.
            // WSDL location එක generate වෙන class එකේ embedded වෙලා තියෙන්න පුළුවන්.
            // අවශ්‍ය නම්, new Calculator(new URL("http://www.dneonline.com/calculator.asmx?wsdl"))
            // වගේ URL එකක් direct කරන්නත් පුළුවන්.
            Calculator service = new Calculator(); 
            
            // 2. Get the service port (the actual interface to call methods)
            // මේක තමයි service operations (Add, Subtract, Multiply, Divide) අඩංගු interface එක.
            // SOAP 1.1 සඳහා getCalculatorSoap() ද, SOAP 1.2 සඳහා getCalculatorSoap12() ද පාවිච්චි කරන්න පුළුවන්.
            CalculatorSoap port = service.getCalculatorSoap(); 
            
            // Optional: If you need to override the endpoint URL at runtime
            // සමහර වෙලාවට test environment එකේදී වගේ endpoint URL එක වෙනස් කරන්න අවශ්‍ය වෙනවා.
            Map<String, Object> requestContext = ((BindingProvider) port).getRequestContext();
            requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
                    "http://www.dneonline.com/calculator.asmx"); // service එකේ URL එක මෙතන දාන්න

            // Optional: Set connection and receive timeouts (in milliseconds)
            // Network issues හෝ service response delay වලදී application hang වෙන එක වළක්වාගන්න මේවා වැදගත්.
            requestContext.put("javax.xml.ws.client.connectionTimeout", 5000); // 5 seconds connection timeout
            requestContext.put("javax.xml.ws.client.receiveTimeout", 10000); // 10 seconds receive timeout

            // 3. Make the actual SOAP call
            // Add operation එකට අවශ්‍ය numbers දෙක දෙන්න.
            int num1 = 10;
            int num2 = 25;
            
            // generate වුණු stubs නිසා, මේ method call එක automaticallly SOAP message එකක් බවට convert වෙලා,
            // service එකට යවලා, service එකෙන් එන response එක parse කරලා අපිට return value එක Java object එකක් විදිහට දෙනවා.
            int result = port.add(num1, num2); 

            System.out.println("Result of " + num1 + " + " + num2 + " = " + result);

        } catch (SOAPFaultException e) {
            System.err.println("SOAP Fault received: " + e.getFault().getFaultString());
            // More details from the fault
            if (e.getFault().hasDetail()) {
                System.err.println("SOAP Fault Detail: " + e.getFault().getDetail().getTextContent());
            }
            e.printStackTrace();
        } catch (Exception e) {
            System.err.println("An unexpected error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

මේ code එක run කරාම, console එකේ "Result of 10 + 25 = 35" කියලා print වෙයි. ඒ කියන්නේ, අපි සාර්ථකව SOAP Web Service එකක් consume කරලා තියෙන්නේ. වැඩේ ගොඩ!

Code Explanation:

Calculator service = new Calculator();: මේකෙන් අපි wsimport එකෙන් generate කරපු Calculator කියන service class එකේ object එකක් හදාගන්නවා. මේ class එක WSDL එකේ තියෙන service definition එකට අදාළව තමයි හැදිලා තියෙන්නේ.
CalculatorSoap port = service.getCalculatorSoap();: මේක තමයි key step එක. getCalculatorSoap() method එකෙන් අපිට CalculatorSoap කියන interface එකේ instance එකක් ලැබෙනවා. මේ interface එකේ තමයි add(), subtract() වගේ service operations define කරලා තියෙන්නේ. මේකට Port Type Interface එක කියලත් කියනවා.
((BindingProvider) port).getRequestContext().put(...): මේකෙන් අපිට runtime එකේදී service endpoint URL එක override කරන්න, timeouts set කරන්න වගේ advanced configurations කරන්න පුළුවන්. BindingProvider කියන්නේ JAX-WS වලදී service endpoint properties configure කරන්න පාවිච්චි කරන interface එකක්.
int result = port.add(num1, num2);: දැන් අපිට සාමාන්‍ය Java method එකක් call කරනවා වගේ add() method එක call කරන්න පුළුවන්. wsimport එකෙන් generate කරපු stubs නිසා, මේ method call එක automatically SOAP message එකක් බවට convert වෙලා, network එක හරහා service එකට යවලා, service එකෙන් එන XML response එක parse කරලා අපිට return value එක Java object එකක් විදිහට දෙනවා.

SOAP එක්ක වැඩ කරනකොට පොඩි Tips & Tricks 💡

SOAP services එක්ක වැඩ කරනකොට තව පොඩි දේවල් දෙක තුනක් ගැන දැනගෙන ඉන්න එක ඔයාලගේ ජීවිතේ ලේසි කරගන්න උදව් වෙයි.

1. Error Handling (SOAPFault)

SOAP Web Service එකකින් error එකක් ආවොත්, ඒක සාමාන්‍යයෙන් SOAPFaultException එකක් විදිහට තමයි අපිට ලැබෙන්නේ. ඒක handle කරන්න try-catch block එකක් පාවිච්චි කරන්න පුළුවන්. SOAPFaultException එකෙන් අපිට error එක ගැන ගොඩක් විස්තර ලබාගන්න පුළුවන්:

try {
    // ... your SOAP call ...
} catch (SOAPFaultException e) {
    System.err.println("SOAP Fault received: " + e.getFault().getFaultString());
    System.err.println("Fault Code: " + e.getFault().getFaultCodeAsQName());
    if (e.getFault().hasDetail()) {
        System.err.println("Fault Detail: " + e.getFault().getDetail().getTextContent());
    }
    e.printStackTrace(); // For debugging
} catch (Exception e) {
    System.err.println("A general error occurred: " + e.getMessage());
    e.printStackTrace();
}

getFaultString(), getFaultCodeAsQName(), getDetail() වගේ methods පාවිච්චි කරලා error message, error code සහ අමතර detail ලබාගන්න පුළුවන්.

2. Connection/Request Timeouts

ගොඩක් වෙලාවට network delays නිසා හෝ service එක slow නිසා අපේ application එක හැංවෙන්න (hang) පුළුවන්. ඒක වළක්වන්න timeouts set කරන්න පුළුවන්. මේවා BindingProvider එකේ request context එකට එකතු කරන්න ඕනේ:

Map<String, Object> requestContext = ((BindingProvider) port).getRequestContext();

// Connection timeout in milliseconds (e.g., 5 seconds)
requestContext.put("javax.xml.ws.client.connectionTimeout", 5000);

// Receive timeout in milliseconds (e.g., 10 seconds). 
// This is the timeout for reading the response from the server.
requestContext.put("javax.xml.ws.client.receiveTimeout", 10000);

javax.xml.ws.client.connectionTimeout: service endpoint එකට connect වෙන්න ගන්න උපරිම කාලය. javax.xml.ws.client.receiveTimeout: service එකෙන් response එකක් ලැබෙන්න ගන්න උපරිම කාලය.

3. Proxy Settings

ඔයාලා proxy server එකක් හරහා network එකට connect වෙනවා නම්, Java application එකට proxy settings provide කරන්න වෙනවා. මේවා JVM arguments විදිහට දෙන්න පුළුවන්:

java -Dhttp.proxyHost=your.proxy.host -Dhttp.proxyPort=8080 -Dhttp.proxyUser=youruser -Dhttp.proxyPassword=yourpass CalculatorClient

HTTPS proxies සඳහා -Dhttps.proxyHost, -Dhttps.proxyPort වගේ දේවල් පාවිච්චි කරන්න පුළුවන්.

4. Security (WS-Security)

SOAP වලට WS-Security වගේ standard extensions තියෙනවා, messages encrypt කරන්න, digital signatures add කරන්න, authentication credentials (username/password) message එකේ body එක ඇතුළේ යවන්න වගේ දේවල් වලට. මේවා ටිකක් advanced topic එකක්. JAX-WS by default මේවාට support කරන්නේ නැහැ. හැබැයි මේ වගේ දේවල් අවශ්‍ය වුණොත් Apache CXF, Spring Web Services වගේ libraries සහ frameworks පාවිච්චි කරන්න පුළුවන්. ඒවායින් WS-Security implementations සපයනවා.

අවසන් වශයෙන්... ✨

ඉතින්, මේ blog post එකෙන් අපි Java වලින් SOAP Web Service එකක් consume කරන්නේ කොහොමද කියලා විස්තරාත්මකව ඉගෙන ගත්තා. wsimport tool එක පාවිච්චි කරලා client stubs generate කරන හැටි, ඒ වගේම ඒ stubs පාවිච්චි කරලා service එකට call කරන හැටිත් අපි step-by-step බැලුවා. මුලින් සංකීර්ණයි කියලා හිතුණට, wsimport වගේ tools නිසා මේක දැන් ගොඩක් ලේසි වැඩක් කියලා ඔයාලට තේරෙන්න ඇති.

SOAP Web Services තාමත් ගොඩක් enterprise applications වල, banking, healthcare, telecom වගේ critical sectors වල බහුලව පාවිච්චි වෙනවා. ඒ නිසා මේ knowledge එක ඔයාලගේ career එකට ගොඩක් වටිනාකමක් එකතු කරයි. Legacy systems එක්ක වුණත්, අලුත් services එක්ක වුණත් වැඩ කරන්න මේ දැනුම ඔයාට විශ්වාසයක් ලබා දෙනවා.

මේ guide එක ඔයාලට වැදගත් වුණා කියලා හිතනවා. ඔයාලට මේ ගැන ප්‍රශ්න තියෙනවා නම්, නැත්නම් ඔයාලා මේ වගේ SOAP services එක්ක වැඩ කරපු අත්දැකීම් තියෙනවා නම්, comment section එකේ අපිත් එක්ක share කරන්න. අපි හැමෝටම මේ subject එක ගැන තවදුරටත් ඉගෙන ගන්න ඒක ගොඩක් උදව් වෙයි. ඊළඟ ලිපියකින් හමුවෙමු! Happy Coding! 👋