Sign in Subscribe
By Thisara Priyamal in Spring Boot —

Spring Boot SOAP Integration Sinhala | Legacy Systems

Spring Boot SOAP Integration Sinhala | Legacy Systems

Integrating Spring Boot with SOAP Web Services | Sinhala Guide

Integrating Spring Boot with SOAP Web Services | Sinhala Guide

ඉතින් කොහොමද යාලුවනේ!

අද අපි කතා කරන්න යන්නේ ගොඩක් වැදගත්, හැබැයි සමහරවිට ටිකක් සංකීර්ණ වෙන්න පුළුවන් මාතෘකාවක් ගැන. ඒ තමයි Spring Boot වගේ නවීන Framework එකක් භාවිතා කරලා, දැනටමත් ක්‍රියාත්මක වන Legacy SOAP Web Service එකක් එක්ක සම්බන්ධ වෙන්නේ කොහොමද කියලා. ගොඩක් අය හිතනවා SOAP කියන්නේ පරණ දෙයක්, ඒත් තාමත් ලෝකේ පුරා තියෙන ගොඩක් Enterprise Systems (බැංකු, රජයේ ආයතන වගේ) තාමත් SOAP Web Services තමයි භාවිත කරන්නේ. ඉතින්, අපේ අලුත් Application එකක් හදනකොට මේ පරණ Systems එක්ක කතා කරන්න වෙන අවස්ථා ගොඩක් එනවා. මේ tutorial එකෙන් අපි බලමු පියවරෙන් පියවර, කොහොමද මේ challenge එක සාර්ථකව ජය ගන්නේ කියලා.

මේ tutorial එක අවසානයේදී ඔයාලට පුළුවන් වෙයි:

  • SOAP Web Services කියන්නේ මොනවද කියලා පැහැදිලිව තේරුම් ගන්න.
  • Spring Boot project එකක් ඇතුලේ SOAP Client එකක් හදාගන්න.
  • WSDL (Web Services Description Language) එකකින් Java classes automate කරගන්න.
  • පවතින SOAP Web Service එකක් එක්ක සාර්ථකව සන්නිවේදනය කරන්න.

එහෙනම්, අපි පටන් ගමු!

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

ඉස්සෙල්ලම අපි බලමු SOAP කියන්නේ මොනවද කියලා. SOAP (Simple Object Access Protocol) කියන්නේ XML මත පදනම් වූ protocol එකක්. මේක භාවිත කරන්නේ Applications දෙකක් අතරේ structured information හුවමාරු කරගන්න. REST APIs වගේ නෙවෙයි, SOAP වලට දැඩි standard එකක් තියෙනවා messages හදන්නේ කොහොමද, ඒව handle කරන්නේ කොහොමද කියලා. මේකෙන් ලැබෙන වාසිය තමයි platform හෝ language එක මොකක් වුණත්, විශ්වාසදායක විදියට සන්නිවේදනය කරන්න පුළුවන් වීම.

SOAP Web Service එකක් ගැන කතා කරනකොට WSDL (Web Services Description Language) කියන එක ගොඩක් වැදගත් වෙනවා. WSDL කියන්නේ XML format එකකින් ලියපු document එකක්. මේකේ තියෙනවා Service එකට call කරන්න පුළුවන් operations මොනවද, ඒවට යවන්න ඕන parameter මොනවද, සහ ඒවයින් ලැබෙන response එක මොන වගේද වගේ හැම විස්තරයක්ම. හරියට service එකක manual එකක් වගේ. අපේ client application එකට මේ WSDL එක කියවලා service එක එක්ක කතා කරන්නේ කොහොමද කියලා තේරුම් ගන්න පුළුවන්.

SOAP වල ප්‍රධාන ලක්ෂණ:

  • XML-based: සියලුම messages XML format එකෙන් තමයි හදන්නේ.
  • Standardized: දැඩි protocol standards අනුගමනය කරනවා.
  • Platform Independent: ඕනෑම programming language එකකින් හෝ platform එකකින් use කරන්න පුළුවන්.
  • WSDL: Service එකේ capabilities විස්තර කරන document එකක් තියෙනවා.
  • Security: WS-Security වගේ standards හරහා security පහසුකම් සපයනවා.

අපිට තියෙන ප්‍රධානම වාසිය තමයි WSDL එකෙන් අපිට පුළුවන් automaticlly Java classes generate කරගන්න. ඒ නිසා අපිට manualy XML request හදන්න වෙන්නේ නෑ. අපි බලමු ඒක කරන්නේ කොහොමද කියලා.

2. Spring Boot Project එකක් හදාගමු

හරි, දැන් අපි අපේ Spring Boot project එක හදාගමු. මේක සඳහා අපි Spring Initializr භාවිත කරනවා. පහත සඳහන් dependencies add කරගන්න:

  • Spring Web Services (spring-boot-starter-web-services): SOAP client එකක් හදන්න මේක තමයි ප්‍රධානම dependency එක.
  • Lombok (Optional): Boilerplate code අඩු කරගන්න මේක ගොඩක් ප්‍රයෝජනවත්. (උදා: getters, setters, constructors automate කරන්න).
  • JAXB Runtime (javax.xml.bind:jaxb-api, org.glassfish.jaxb:jaxb-runtime): WSDL එකෙන් generate කරන Java classes XML වලට map කරන්න මේක අවශ්‍යයි. Java 9 සහ ඊට වැඩි versions වලට මේක explicit ව add කරන්න ඕන.
  • Spring Web (spring-boot-starter-web): අපේ SOAP client එක test කරන්න REST endpoint එකක් හදන්න මේක අවශ්‍යයි.

pom.xml එකේ dependencies ටික මේ වගේ වෙන්න ඕන (ඔයාලගේ versions වෙනස් වෙන්න පුළුවන්):

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web-services</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!-- JAXB API and Runtime for Java 9+ -->
    <dependency>
        <groupId>javax.xml.bind</groupId>
        <artifactId>jaxb-api</artifactId>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
    </dependency>
</dependencies>

3. WSDL එකෙන් Java Classes හදමු (Generating Java Classes from WSDL)

මේක තමයි SOAP integration එකේ වැදගත්ම කොටසක්. අපිට SOAP Web Service එක එක්ක interact කරන්න අවශ්‍ය Java classes, WSDL එකෙන් automate කරගන්න පුළුවන්. මේක කරන්න අපිට විවිධ tools තියෙනවා (wsimport, Apache CXF, Axis2). අපි මේකෙදි Apache CXF Framework එකේ Maven plugin එකක් වන cxf-codegen-plugin භාවිත කරමු. මේකෙන් අපිට Maven build process එකේදී WSDL එකෙන් Java classes generate කරගන්න පුළුවන්.

අපි හිතමු අපිට තියෙනවා 'CountryService' කියලා SOAP Service එකක්. ඒකෙන් පුළුවන් රටක නමක් දීලා ඒ රටේ විස්තර (අගනුවර, ජනගහනය වගේ) ගන්න. මේ Service එකේ WSDL එක http://www.example.com/countries?wsdl වගේ URL එකක තියෙනවා කියලා හිතමු.

Maven pom.xml එකට cxf-codegen-plugin එක එකතු කිරීම:

<build> tag එක ඇතුළත <plugins> section එකට මේ code එක add කරන්න:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.cxf</groupId>
            <artifactId>cxf-codegen-plugin</artifactId>
            <version>3.4.5</version> <!-- Use a recent stable version -->
            <executions>
                <execution>
                    <id>generate-sources</id>
                    <phase>generate-sources</phase>
                    <configuration>
                        <sourceRoot>${project.build.directory}/generated-sources/cxf</sourceRoot>
                        <wsdlOptions>
                            <wsdlOption>
                                <wsdl>http://www.example.com/countries.wsdl</wsdl> <!-- Replace with actual WSDL URL -->
                                <extraargs>
                                    <extraarg>-p</extraarg>
                                    <extraarg>com.example.ws.countries</extraarg> <!-- Package name for generated classes -->
                                    <extraarg>-mark-generated</extraarg> <!-- Adds @Generated annotation -->
                                    <extraarg>-client</extraarg> <!-- Generates client-side artifacts -->
                                </extraargs>
                            </wsdlOption>
                        </wsdlOptions>
                    </configuration>
                    <goals>
                        <goal>wsdl2java</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <!-- Spring Boot Maven Plugin -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>

මේ pom.xml config එකෙන් කියන්නේ Maven project එක build කරනකොට (විශේෂයෙන් generate-sources phase එකේදී), cxf-codegen-plugin එක භාවිත කරලා දීලා තියෙන WSDL URL එකෙන් Java classes generate කරන්න කියලා. Generate කරන classes ටික ${project.build.directory}/generated-sources/cxf කියන path එකට යනවා (සාමාන්‍යයෙන් target/generated-sources/cxf). <extraarg>-p com.example.ws.countries</extraarg> කියන එකෙන් අපි කියනවා මේ classes com.example.ws.countries කියන package එකට දාන්න කියලා.

දැන් project එක build කරන්න. මේක කරන්න පුළුවන් command line එකෙන්, නැත්නම් ඔබේ IDE එකෙන් (IntelliJ IDEA, Eclipse වගේ). IDE එකක් නම්, Maven projects section එකට ගිහින් 'Generate Sources and Update Folders' වගේ option එකක් තියෙනවා. Command line එකෙන් නම්:

mvn clean install

මේක සාර්ථක වුණාම, target/generated-sources/cxf/com/example/ws/countries කියන path එකේ මේ වගේ classes ටිකක් generate වෙලා තියෙයි:

  • GetCountryRequest.java
  • GetCountryResponse.java
  • Country.java
  • CountryPortService.java (Service client interface)
  • CountryService.java (Service implementation)
  • ObjectFactory.java (XML elements Java objects වලට convert කරන්න)

මේ generated classes තමයි අපිට SOAP service එකත් එක්ක interact කරන්න උදව් වෙන්නේ. මේවාට අතින් වෙනස්කම් කරන්න යන්න එපා, මොකද ආයෙත් generate කරනකොට ඒ වෙනස්කම් නැති වෙන්න පුළුවන්.

4. SOAP Client එකක් ලියමු (Writing a SOAP Client)

දැන් අපිට අවශ්‍ය Java classes generate කරගෙන ඉවරයි. ඊළඟට අපි Spring Boot එක භාවිත කරලා SOAP Client එකක් හදමු. මේකට අපි Spring Web Services වලින් ලැබෙන WebServiceTemplate එක භාවිත කරනවා.

a. WebServiceTemplate Configuration

WebServiceTemplate එකට XML messages Java objects වලට convert කරන්න (marshal) සහ Java objects XML වලට convert කරන්න (unmarshal) Marshaler එකක් අවශ්‍ය වෙනවා. මේකට Jaxb2Marshaller එක ගොඩක් හොඳයි.

src/main/java/com/example/soapintegration/config/WebServiceConfig.java (ඔබේ package name එකට අනුව වෙනස් කරන්න):

package com.example.soapintegration.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
import org.springframework.ws.client.core.WebServiceTemplate;

@Configuration
public class WebServiceConfig {

    @Bean
    public Jaxb2Marshaller marshaller() {
        Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
        // The package name containing your generated classes
        marshaller.setContextPath("com.example.ws.countries"); 
        return marshaller;
    }

    @Bean
    public WebServiceTemplate countryServiceTemplate(Jaxb2Marshaller marshaller) {
        WebServiceTemplate webServiceTemplate = new WebServiceTemplate();
        webServiceTemplate.setMarshaller(marshaller);
        webServiceTemplate.setUnmarshaller(marshaller);
        // Set default URI if you want, but can also be set per-request
        // webServiceTemplate.setDefaultUri("http://www.example.com/countries");
        return webServiceTemplate;
    }
}

marshaller.setContextPath("com.example.ws.countries") කියන එක ගොඩක් වැදගත්. මේකෙන් අපි කියනවා, generate කරපු Java classes තියෙන්නේ මේ package එක ඇතුලේ කියලා. WebServiceTemplate එකට මේ Marshaller එක inject කරලා, අපිට request යවන්න සහ response ගන්න පුළුවන්.

b. SOAP Client Service එකක් හදමු

දැන් අපි අපේ actual SOAP client service එක හදමු. මේකෙන් තමයි අපි WebServiceTemplate එක භාවිත කරලා SOAP service එකට calls කරන්නේ.

src/main/java/com/example/soapintegration/client/CountrySOAPClient.java:

package com.example.soapintegration.client;

import com.example.ws.countries.GetCountryRequest;
import com.example.ws.countries.GetCountryResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
import org.springframework.ws.client.core.WebServiceTemplate;

@Service
public class CountrySOAPClient {

    private static final String SOAP_URI = "http://www.example.com/countries"; // Actual SOAP Service Endpoint

    @Autowired
    @Qualifier("countryServiceTemplate") // Autowire the specific WebServiceTemplate bean
    private WebServiceTemplate webServiceTemplate;

    public GetCountryResponse getCountryDetails(String countryName) {
        GetCountryRequest request = new GetCountryRequest();
        request.setName(countryName);

        System.out.println("Requesting country details for: " + countryName);

        // Send request and receive response
        GetCountryResponse response = (GetCountryResponse) webServiceTemplate.marshalSendAndReceive(
                SOAP_URI, request);

        return response;
    }
}

මේ CountrySOAPClient එකේ getCountryDetails method එකෙන් තමයි රටේ නම දීලා details ඉල්ලන්නේ. marshalSendAndReceive() method එක තමයි මැජික් එක කරන්නේ. මේකෙන්:

  1. GetCountryRequest Java object එක XML message එකක් බවට convert කරනවා (marshal).
  2. ඒ XML message එක SOAP_URI එකට යවනවා.
  3. Service එකෙන් එන XML response එක අරගෙන, ඒක GetCountryResponse Java object එකක් බවට convert කරනවා (unmarshal).

SOAP_URI එකට ඔබේ actual SOAP service endpoint එක දෙන්න මතක තියාගන්න. සමහර වෙලාවට මේ URI එක WSDL URL එකෙන් වෙනස් වෙන්න පුළුවන්.

5. Project එක රන් කරලා බලමු (Running and Testing the Project)

දැන් අපිට client එකක් තියෙනවා. අපි මේක test කරන්න පුළුවන් සරල REST Controller එකක් භාවිත කරලා. මේකෙන් අපිට browser එකෙන් හරි Postman වගේ tool එකකින් හරි අපේ SOAP client එකට call කරන්න පුළුවන්.

src/main/java/com/example/soapintegration/controller/CountryController.java:

package com.example.soapintegration.controller;

import com.example.soapintegration.client.CountrySOAPClient;
import com.example.ws.countries.Country;
import com.example.ws.countries.GetCountryResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/countries")
public class CountryController {

    @Autowired
    private CountrySOAPClient soapClient;

    @GetMapping("/{name}")
    public Country getCountry(@PathVariable String name) {
        GetCountryResponse response = soapClient.getCountryDetails(name);
        if (response != null && response.getCountry() != null) {
            return response.getCountry();
        } else {
            // Handle case where country is not found or response is empty
            return null; // Or throw an exception
        }
    }
}

දැන් ඔයාලගේ Spring Boot Application එක run කරන්න. IDE එකෙන් හෝ command line එකෙන්:

mvn spring-boot:run

Application එක start වුණාට පස්සේ, browser එකේ මේ URL එකට යන්න:

http://localhost:8080/api/countries/SriLanka

ඔබේ SOAP service එක නිවැරදිව ක්‍රියාත්මක වෙනවා නම්, ඔබට Sri Lanka ගැන තොරතුරු JSON format එකෙන් ලැබෙන්න ඕන. (මතක තියාගන්න, මෙතන අපි 'http://www.example.com/countries' කියන dummy URL එකක් තමයි භාවිත කළේ. ඒ නිසා මේකෙන් actual response එකක් එන්නේ නෑ. ඒ වෙනුවට ඔයාලගේ real SOAP service endpoint එක භාවිත කරන්න.)

අවසාන වශයෙන් (Conclusion)

ඉතින් යාලුවනේ, මේ tutorial එකෙන් අපි සාර්ථකව Spring Boot project එකක් ඇතුළත SOAP Web Service එකක් එක්ක integrate කරන්නේ කොහොමද කියලා බැලුවා. WSDL එකකින් Java classes generate කරගන්න හැටි, WebServiceTemplate එක භාවිත කරලා client එකක් හදන්නේ කොහොමද කියන එකත් අපි ඉගෙනගත්තා.

Legacy systems එක්ක වැඩ කරනකොට මේ දැනුම ඔයාලට ගොඩක් වැදගත් වෙයි. සමහර වෙලාවට මේ වගේ integration වලදී security, error handling වගේ තව දේවල් ගැන හිතන්න වෙනවා. ඒත් මේ tutorial එකෙන් ඔයාලට හොඳ foundation එකක් ලැබිලා ඇති කියලා මම විශ්වාස කරනවා.

මේක අතින්ම කරලා බලන්න. මොකද code කරලා තේරුම් ගන්න එක තමයි හොඳම ක්‍රමය. ගැටලුවක් ආවොත්, නැත්නම් යෝජනාවක් තියෙනවා නම්, අනිවාර්යයෙන්ම පහළ තියෙන comment section එකේ අහන්න. ඔයාලගේ අත්දැකීම් අපිත් එක්ක බෙදාගන්නත් අමතක කරන්න එපා!

ආයෙත් මේ වගේ තවත් වැදගත් ලිපියකින් හමුවෙමු. හැමෝටම ජය වේවා!

Previous

Spring Boot Custom Actuator Endpoints | Sinhala Guide | Custom Health Check

 Next

Spring Boot vs Quarkus Performance | Benchmarking Guide Sinhala

You might also like...