Java JAX-WS වලින් SOAP Web Services හඳුනාගනිමු - SC Guide

ආයුබෝවන්! Software ලෝකයේ API (Application Programming Interface) කියන්නේ අත්‍යවශ්‍ය දෙයක්. අද දවසේ REST APIs ගැන ගොඩක් කතා වුණාට, enterprise-level systems වල සහ තවමත් බොහෝ legacy systems වල SOAP (Simple Object Access Protocol) web services ඉතා වැදගත්.

SOAP web services කියන්නේ ටිකක් "පරණ" තාක්ෂණයක් විදියට හඳුන්වන්න පුළුවන්. හැබැයි, ඒවායේ තියෙන security features, transaction support, සහ formal contract-based communication නිසා බැංකු, රජයේ ආයතන, සහ විශාල සංවිධාන වලදී තවමත් මේවා බහුලව භාවිත වෙනවා. ඉතින්, මේ ලිපියෙන් අපි SOAP web services මොකක්ද, ඒවා කොහොමද වැඩ කරන්නේ, ඒ වගේම Java වල JAX-WS (Java API for XML Web Services) පාවිච්චි කරලා කොහොමද සරල SOAP web service එකක් හදන්නේ සහ ඒක use කරන client එකක් හදන්නේ කියලා පියවරෙන් පියවර බලමු.

මේ ලිපිය කියෙව්වට පස්සේ ඔබට SOAP web services වල මූලික සංකල්ප සහ Java වලින් ඒවගෙ වැඩ කරන්න පුළුවන් හොඳ අවබෝධයක් ලැබෙයි කියලා අපි හිතනවා. එහෙනම්, අපි පටන් ගමු!

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

SOAP කියන්නේ XML-based message protocol එකක්. සරලව කිව්වොත්, network එකක් හරහා application දෙකක් අතර තොරතුරු හුවමාරු කරගන්න පාවිච්චි කරන "නීති මාලාවක්" (set of rules) විදියට මේක හඳුන්වන්න පුළුවන්. REST වගේ නෙවෙයි, SOAP strict protocol එකක්. ඒ කියන්නේ messages හදන්න ඕනේ යම් නිශ්චිත format එකකට අනුව.

WSDL - Web Services Description Language

SOAP web service එකකදී අත්‍යවශ්‍යම දෙයක් තමයි WSDL. මේක XML format එකෙන් ලියපු contract එකක් වගේ. ඒ කියන්නේ, මේ web service එක මොනවද කරන්නේ, මොන parameters ද බාර ගන්නේ, මොන return type එකක්ද දෙන්නේ කියන හැම දෙයක්ම මේ WSDL file එකේ තියෙනවා. Client application එකකට මේ service එක use කරන්න නම්, WSDL එක ගැන දැනගෙන ඉන්න ඕනේ.

SOAP Message Structure

SOAP message එකක් කියන්නේ XML document එකක්. ඒකේ ප්‍රධාන කොටස් 4ක් තියෙනවා:

• Envelope: SOAP message එකේ root element එක. මේකෙන් define කරනවා message එකේ content එක මොකක්ද සහ ඒක process කරන්න ඕන කොහොමද කියලා.
• Header (Optional): Authentication, transaction IDs, routing information වගේ application-specific data මෙතන අඩංගු වෙනවා.
• Body: Request එකේ actual data එක (methods, parameters) නැත්නම් response එකේ actual data එක මෙතන තියෙනවා.
• Fault (Optional): Request එක process කරනකොට error එකක් ආවොත්, ඒ error එක ගැන තොරතුරු මේ section එකේ අඩංගු වෙනවා.

මෙන්න සරල SOAP message එකක structure එකක්:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header/>
   <soap:Body>
      <ns2:sayHello xmlns:ns2="http://service.hello.com/">
         <name>චමින්ද</name>
      </ns2:sayHello>
   </soap:Body>
</soap:Envelope>

REST APIs වලට වඩා SOAP තරමක් complex වුණාට, standard security protocols (WS-Security), reliable messaging (WS-ReliableMessaging), සහ transactions (WS-AtomicTransaction) වගේ දේවල් වලට support එකක් දෙනවා. ඒක නිසා enterprise level applications වලට මේක වඩාත් සුදුසුයි.

JAX-WS (Java API for XML Web Services) මොකක්ද?

Java වලින් SOAP web services develop කරනකොට JAX-WS කියන්නේ අපිට ලැබෙන ලොකු උදව්වක්. මේ API එක මගින් Java objects සහ XML messages අතර map කිරීම පහසු කරනවා. ඒ කියන්නේ, අපිට XML messages ගැන වැඩිය හිතන්නේ නැතුව සාමාන්‍ය Java code ලියන්න පුළුවන්. JAX-WS විසින්ම අවශ්‍ය XML serialization/deserialization, marshalling/unmarshalling වගේ දේවල් බලාගන්නවා.

JAX-WS මූලික වශයෙන් Java annotations (@WebService, @WebMethod, @SOAPBinding, etc.) පාවිච්චි කරලා web service එකක් define කරනවා. මේ annotations පාවිච්චි කරලා සාමාන්‍ය Java class එකක් හෝ interface එකක් web service එකක් විදියට expose කරන්න පුළුවන්.

සරල SOAP Web Service එකක් හදමු (Service Provider)

දැන් අපි බලමු කොහොමද "Hello World" වගේ සරල SOAP web service එකක් JAX-WS පාවිච්චි කරලා හදන්නේ කියලා. මේකට අපිට Java Development Kit (JDK) එක තිබ්බා නම් ඇති. වෙන special libraries අවශ්‍ය වෙන්නේ නැහැ, මොකද JAX-WS JDK එකේම කොටසක්.

Step 1: Service Endpoint Interface (SEI) එක හදමු

මුලින්ම, අපේ web service එක මොන methods ද expose කරන්නේ කියලා define කරන interface එකක් හදමු. මේක තමයි Service Endpoint Interface (SEI) එක.

// src/com/hello/service/HelloWorldService.java
package com.hello.service;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;

// Service Provider Interface (SPI)
// WebService annotation එකෙන් කියනවා මේක web service එකක් කියලා
// serviceName: WSDL එකේ service element එකට දෙන නම
// targetNamespace: XML Namespace එක, client එකට වැදගත්
@WebService(serviceName = "HelloWorld")
@SOAPBinding(style = Style.RPC) // මෙතන RPC or DOCUMENT තෝරන්න පුළුවන්
public interface HelloWorldService {

    // WebMethod annotation එකෙන් කියනවා මේ method එක web service එකක් විදියට expose කරන්න කියලා
    @WebMethod
    String sayHello(String name);

    @WebMethod
    String getGreeting(String city);
}

මෙහිදී @WebService annotation එකෙන් මේ interface එක web service එකක් විදියට define කරනවා. serviceName එක WSDL එකේ service element එකට යන නම. targetNamespace එක client එකට වැදගත් namespace එකක් define කරනවා.

@SOAPBinding(style = Style.RPC) කියන්නේ SOAP message එකේ Body එක define කරන විදිය. RPC (Remote Procedure Call) කියන්නේ method call එකක් වගේ data යවන ක්‍රමයක්. DOCUMENT කියන්නේ XML document එකක් වගේ data යවන ක්‍රමයක්. බොහෝ විට DOCUMENT style එක තමයි recommend කරන්නේ.

Step 2: Service Implementation Class එක හදමු

දැන් අපි කලින් හදපු HelloWorldService interface එක implement කරන class එකක් හදමු.

// src/com/hello/service/HelloWorldServiceImpl.java
package com.hello.service;

import javax.jws.WebService;

// HelloWorldService interface එක implement කරනවා
// endpointInterface: මේ implementation එක අයිති interface එක කියනවා
@WebService(endpointInterface = "com.hello.service.HelloWorldService")
public class HelloWorldServiceImpl implements HelloWorldService {

    @Override
    public String sayHello(String name) {
        System.out.println("sayHello method එක call වුණා: " + name);
        return "ආයුබෝවන් " + name + ", SOAP Web Service එකට ඔබව සාදරයෙන් පිලිගනිමු!";
    }

    @Override
    public String getGreeting(String city) {
        System.out.println("getGreeting method එක call වුණා: " + city);
        return "සුභ දවසක් " + city + " සිටින ඔබට!";
    }
}

මෙතනදී @WebService annotation එකේ endpointInterface attribute එකෙන් මේ class එක implement කරන interface එක මොකක්ද කියලා JAX-WS engine එකට කියනවා.

Step 3: Web Service එක Publish කරමු

අපිට තවම application server එකක් (like Tomcat or WildFly) අවශ්‍ය නැතුවම මේ web service එක publish කරන්න පුළුවන්. JAX-WS වලට මේකටම පුංචි utility class එකක් තියෙනවා Endpoint කියලා.

// src/com/hello/publisher/HelloWorldPublisher.java
package com.hello.publisher;

import com.hello.service.HelloWorldServiceImpl;
import javax.xml.ws.Endpoint;

public class HelloWorldPublisher {

    public static void main(String[] args) {
        // Web service එක publish කරන URL එක
        String url = "http://localhost:8080/HelloWorldService"; 
        
        System.out.println("Web Service එක Publish කරනවා: " + url + "?wsdl");
        
        // Endpoint.publish() method එක පාවිච්චි කරලා service එක publish කරනවා
        // පළවෙනි parameter එක URL එක, දෙවෙනි එක service implementation object එක
        Endpoint.publish(url, new HelloWorldServiceImpl());
        
        System.out.println("Web Service එක සාර්ථකව Publish කළා. Services අවසන් කිරීමට Enter ඔබන්න.");
        
        // Console එක Block කරලා තියන්න, නැත්නම් service එක shutdown වෙනවා
        try {
            System.in.read();
        } catch (Exception e) {
            e.printStackTrace();
        }
        
        // Service එක shutdown කරන්න
        Endpoint.publish(url, new HelloWorldServiceImpl()).stop();
        System.out.println("Web Service එක Shutdown කළා.");
    }
}

දැන් මේ HelloWorldPublisher class එක run කරන්න. Console එකේ "Web Service එක සාර්ථකව Publish කළා" කියලා message එකක් පෙනෙයි. ඊට පස්සේ ඔබේ browser එක open කරලා http://localhost:8080/HelloWorldService?wsdl කියන URL එකට යන්න. ඔබට XML document එකක් පෙනෙයි. ඒක තමයි අපේ web service එකේ WSDL file එක. මේක තමයි client එකට මේ service එක use කරන්න අවශ්‍ය තොරතුරු ටික දෙන්නේ.

Web Service එකක් Use කරන Client එකක් හදමු (Service Consumer)

දැන් අපි හදපු web service එක use කරන client application එකක් හදමු. මේකටත් අපිට JAX-WS tools පාවිච්චි කරන්න පුළුවන්.

Step 1: wsimport tool එක පාවිච්චි කරලා Client Stubs හදමු

JAX-WS JDK එකත් එක්කම එන wsimport කියන command line tool එක පාවිච්චි කරලා අපිට WSDL file එකකින් client stubs (proxy classes) generate කරගන්න පුළුවන්. මේ classes මගින් web service එක invoke කරන එක පහසු කරනවා.

ඔබේ Terminal එක (Command Prompt/PowerShell for Windows, Terminal for Mac/Linux) open කරලා පහත command එක run කරන්න. මේක run කරන්න කලින් HelloWorldPublisher application එක running තියෙන්න ඕනේ.

wsimport -keep -s src -p com.hello.client http://localhost:8080/HelloWorldService?wsdl

මේ command එකෙන් වෙන්නේ:

• -keep: generate කරන source files තියාගන්න.
• -s src: generate කරන source files save කරන්න ඕනේ src folder එක ඇතුළේ.
• -p com.hello.client: generate කරන classes වල package එක com.hello.client විදියට set කරන්න.
• http://localhost:8080/HelloWorldService?wsdl: WSDL file එකේ URL එක.

මේ command එක run කළාම, src/com/hello/client කියන folder එක ඇතුළේ HelloWorld.java, HelloWorldService.java (Client පැත්තට අදාල වෙන) වගේ classes කීපයක් generate වෙයි.

Step 2: Client Application එක හදමු

දැන් අපි generate කරගත්ත classes පාවිච්චි කරලා web service එක invoke කරමු.

// src/com/hello/client/HelloWorldClient.java
package com.hello.client;

import com.hello.client.HelloWorld; // wsimport මගින් generate වූ service class එක
import com.hello.client.HelloWorldService; // wsimport මගින් generate වූ endpoint interface එක

public class HelloWorldClient {

    public static void main(String[] args) {
        // WSDL URL එකෙන් service එකේ instance එකක් හදාගන්නවා
        // මේ class එක wsimport මගින් generate වුණා
        HelloWorldService helloService = new HelloWorldService();
        
        // Service Port එක අරගන්නවා
        // මේකෙන් තමයි actual service methods call කරන්න පුළුවන්
        HelloWorld helloPort = helloService.getHelloWorldPort();
        
        // Service method එක invoke කරනවා
        String response1 = helloPort.sayHello("නලින්");
        System.out.println("Service Response 1: " + response1);
        
        String response2 = helloPort.getGreeting("ගාල්ල");
        System.out.println("Service Response 2: " + response2);
    }
}

දැන් HelloWorldClient class එක run කරන්න. ඔබට අපේ web service එකෙන් ලැබෙන responses console එකේ පෙනෙයි.

wsimport tool එක JAX-WS client side development simplify කරනවා. ඒක WSDL එක කියවලා අවශ්‍ය Java classes generate කරන නිසා අපිට XML parsing ගැන හිතන්නේ නැතුව Java object oriented විදියට code කරන්න පුළුවන්.

නිගමනය

ඉතින්, මේ ලිපියෙන් අපි SOAP web services වල මූලික සංකල්ප, WSDL වල වැදගත්කම, SOAP message structure එක, සහ Java වල JAX-WS framework එක පාවිච්චි කරලා සරල web service එකක් හදන හැටි සහ ඒක consume කරන client එකක් හදන හැටි ඉගෙන ගත්තා.

SOAP web services enterprise applications වලට ඉතාම සුදුසුයි, විශේෂයෙන් security, reliability, සහ transaction management වගේ දේවල් අත්‍යවශ්‍ය තැන් වලදී. JAX-WS වගේ tools නිසා Java developer කෙනෙකුට SOAP services එක්ක වැඩ කරන එක පහසු වෙනවා. මතක තියාගන්න, සැබෑ ලෝකයේ applications වලදී මේ වගේ systems හදනකොට error handling, security (WS-Security), logging, සහ proper deployment strategies ගැනත් අවධානය යොමු කරන්න ඕනේ.

මේ tutorial එක ඔබට ප්‍රයෝජනවත් වෙන්න ඇති කියලා හිතනවා. ඔබේ අත්දැකීම්, ප්‍රශ්න, හෝ මේ ගැන අදහස් comment section එකේ බෙදාගන්න! අපි ඊළඟ ලිපියෙන් හම්බවෙමු.