JLupin Next Server provides its own model of message processing via the SOAP interface and the XML language.

The flow of the message with the conversion of the XML-JAVA-XML objects is shown in the following pattern:

Calling a service via web service – SOAP-XML is very easy. No programming works are needed to add many unnecessary interfaces and descriptors. For better understanding of web service model available via SOAP and XML language, let’s take a look at the below example. As usual, we create service interface:

public interface DigestService {
    String getMD5Digest(String name, String surname) throws Throwable;
}

Implementation:

package com.jlupin.sampleapp.paramsfunction.service.impl;

import com.jlupin.interfaces.service.access.annotation.JLupinServiceAccessMode;
import com.jlupin.interfaces.service.access.enums.JLupinServiceAccessModeEnum;
import com.jlupin.sampleapp.paramsfunction.service.DigestService;
import org.springframework.stereotype.Service;

import java.security.MessageDigest;

@JLupinServiceAccessMode(mode = JLupinServiceAccessModeEnum.PUBLIC)
@Service("digestService")
public class DigestServiceImpl implements DigestService {

    public DigestService2Impl() {
    }

    @Override
    public String getMD5Digest(String name, String surname) throws Throwable {
            String stringToDigest = name+surname;
            MessageDigest  messageDigest = MessageDigest.getInstance("MD5");
            byte [] buffer = stringToDigest.getBytes();
            messageDigest.update(buffer);
            byte [] digestBuffer  = messageDigest.digest();
            return byteToHex(digestBuffer);
    }

    private String byteToHex(byte in[]) {
        byte ch = 0x00;
        int i = 0;
        if (in == null || in.length <= 0) {
            return null;
        }
        StringBuilder out = new StringBuilder(in.length * 2);

        while (i < in.length) {
            ch = (byte) (in[i] & 0xF0);
            ch = (byte) (ch >>> 4);
            ch = (byte) (ch & 0x0F);
            out.append(pseudo[ (int) ch]);
            ch = (byte) (in[i] & 0x0F);
            out.append(pseudo[ (int) ch]);
            i++;
        }
        return out.toString();

    }

    private char pseudo[] = {'0', '1', '2', '3', '4', '5', '6', '7','8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
}

Our example will use configuration by annotations provided by Spring. Our class will be available under the name of "digestService" – Spring annotation:

@Service("digestService")

Adding annotation:

@JLupinServiceAccessMode(mode = JLupinServiceAccessModeEnum.PUBLIC)

Informs the server that this class must be available outside as a service. Class and interface is compiled and digestMicroservice.jar file is created. Ok then, if we have our code written, we need to configure it and place on the server. Create Spring configuratgion file: (spring-services.xml).

Content:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <import resource="spring-default-configuration.xml"/>

    <context:annotation-config/>
    <context:component-scan base-package=" com.jlupin.sampleapp.paramsfunction.service.impl"/>
</beans>

In the above file, we import a file with classes provided by default with the server and we also determine a package with our service class. Our configuring file must import the file with default classes provided by JLupin, and they are in spring-default-configuration.xml file.

We create an example to jar file – it will include class files and spring configuration file. We add our new microservice to the server configuration or we add another service within existing microservice, we send commands on appStart sampleMicroservice and try to call our service (in this example, microservice will be named "sampleMicroservice", the service will be available as "digestService").

URL: http://127.0.0.1:8082/jLupinNextServerWebService/JLupinWebservice

Input:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ent="http://entrypoint.impl.jlupin.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <ent:jLupinService>
         <jLupinInputParameter>
         <applicationName>sampleMicroservice</applicationName>
           <locale>pl</locale>
            <methodName>getMD5Digest</methodName>
              <privilegeList>
               <privilegeName>privilege</privilegeName>
            </privilegeList>
            <requestId>request1</requestId>
            <sequenceName>sampleParamArrayXmlInOutSequence</sequenceName>
             <serviceName>digestService</serviceName>
            <sessionId>session1</sessionId>
            <user>test_user</user>
             <busName>busName</busName>
             <paramArray><![CDATA[<string>jon</string>;<string>mcdowell</string>]]>
            </paramArray>
         </jLupinInputParameter>
     </ent:jLupinService>
   </soapenv:Body>
</soapenv:Envelope>

Output:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
    <env:Header/>
    <env:Body>
        <jlns:jLupinServiceResponse xmlns:jlns="http://entrypoint.impl.jlupin.org/">
            <jLupinOutputParameter>
                <executedServiceError>false</executedServiceError>
                <result>
                    <![CDATA[
                    <?xml version="1.0" encoding="UTF-8"?><java version="1.8.0_45" class="java.beans.XMLDecoder"><string>50382149719ab04e47a966ad959f4241</string>]]>
                </result>
            </jLupinOutputParameter>
        </jlns:jLupinServiceResponse>
    </env:Body>
</env:Envelope>

And that's all. JLupin Next Server automatically calls many access interfaces, including the mentioned web service interface – soap – xml.

Let’s note the most important issues:

Encoding input parameters to the service – in a tag .
Encoding corresponds to the format that is generated via XMLDecoder available in JAVA API.
As a result of "jon" string coding, we receive xml in a form of:

<string>jon</string>

As a result of "mcdowell" string coding, we receive xml in a form of:

<string>mcdowell</string>

Input parameters are separated with a semicolon:

<string>jon</string>;<string>mcdowell</string>

and then packed in a CDATA tag:

<![CDATA[<string>jon</string>;<string>mcdowell</string>]]>

Input parameter developed this way will be decoded by a sequencer sampleParamArrayXmlInOutSequence (this name is included in tag) – this sequencer is provided by JLupin
and input objects ("jon", "mcdowell" ) will be changed to JAVA objects (via XMLEncoder available in JAVA API) and submitted to
getMD5Digest function. sampleParamArrayXmlInOutSequence sequencer is again responsible for input parameter encoding from getMD5Digest function. It will use XMLDecoder for input parameter encoding and the whole process will be packed in CDATA tag. Therefore, output object in tag will take the form of:

<![CDATA[<?xml version="1.0" encoding="UTF-8"?><java version="1.8.0_45" class="java.beans.XMLDecoder"><string>50382149719ab04e47a966ad959f4241</string>]]>

Programmer receiving a message will be responsible for message transformation to an object specific for the language/platform. JAVA objects to XML encoding/decoding mechanisms via XStream and Jackson will be added in the next versions of the server.

Let’s then move on to discuss further details of Web Service SOAP XML Facade interface.

For the JLupin Next Server, a specific entry point is responsible for the data exchange protocol. In this case, it is JLupinWebserviceMultiProcessEntryPointImpl. JLupin Next Server offers implementation of the "Facade" design pattern. In conjunction with the Web Service it is exactly JLupin Web Service SOAP XML Facade.

What is the main purpose of the JLupin Web Service SOAP XML Facade model?

It is to ensure the possibility of a standardized calling of any services as Java POJO objects through the HTTP transport protocol, the SOAP service protocol and the XML language, i.e. Web Service. As we already know, to call the service we send the JLupinInputParameter object where we indicate a specific application, a specific service, a particular method, we give other call parameters such as arrays of parameters for the method and other variables. The output object is JLupinOutputParameter. To use the aforementioned input/output objects in the Web Service model, the mentioned objects should be presented in the XML language. The XML representation of JLupinInputParameter and JLupinOutputParameter objects is constant. Variable parameters are internal parameters of these objects.

The constant part of the input XML:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ent="http://entrypoint.impl.jlupin.org/">
   <soapenv:Header/>
   <soapenv:Body>
      <ent:jLupinService>
         <jLupinInputParameter>

          …    

         </jLupinInputParameter>
     </ent:jLupinService>
   </soapenv:Body>
</soapenv:Envelope>

The constant part of the output XML:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <env:Body>
      <jlns:jLupinServiceResponse xmlns:jlns="http://entrypoint.impl.jlupin.org/">
         <jLupinOutputParameter>
            …
         </jLupinOutputParameter>
      </jlns:jLupinServiceResponse>
   </env:Body>
</env:Envelope>

How to execute it? It is shown in the WSDL file which describes the Web Service Facade.

The file can be downloaded after launching the server at:

http://127.0.0.1:8082/?wsdl

The format of the WSDL file is shown below:

<definitions name="JLupinDefaultWebService" targetNamespace="http://entrypoint.impl.jlupin.org/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://entrypoint.impl.jlupin.org/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <types>
        <xs:schema targetNamespace="http://entrypoint.impl.jlupin.org/" version="1.0" xmlns:tns="http://entrypoint.impl.jlupin.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <xs:element name="jLupinService" type="tns:jLupinService"/>
            <xs:element name="jLupinServiceResponse" type="tns:jLupinServiceResponse"/>
            <xs:complexType name="jLupinService">
                <xs:sequence>
                    <xs:element minOccurs="0" name="jLupinInputParameter" type="tns:jLupinInputParameter"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="jLupinInputParameter">
                <xs:sequence>
                    <xs:element minOccurs="1" name="applicationName" type="xs:string"/>
                    <xs:element minOccurs="1" name="locale" type="xs:string"/>
                    <xs:element minOccurs="0" name="methodName" type="xs:string"/>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="privilegeList" nillable="true" type="tns:privilege"/>
                    <xs:element minOccurs="1" name="requestId" type="xs:string"/>
                    <xs:element minOccurs="1" name="jLupinServiceDto" type="tns:jLupinServiceDto"/>
                    <xs:element minOccurs="1" name="serviceName" type="xs:string"/>
                    <xs:element minOccurs="1" name="sessionId" type="xs:string"/>
                    <xs:element minOccurs="0" name="busName" type="xs:string"/>
                    <xs:element minOccurs="0" name="user" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="privilege">
                <xs:sequence>
                    <xs:element minOccurs="0" name="privilegeName" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="jLupinServiceDto">
                <xs:sequence>
                    <xs:element minOccurs="0" name="createdDtoTime" type="xs:string"/>
                    <xs:element minOccurs="1" name="paramMap" type="tns:paramMap" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="paramMap">
                <xs:sequence>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="param" type="tns:param"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="param">
                <xs:sequence>
                    <xs:element minOccurs="0" name="paramKey" type="xs:string"/>
                    <xs:element minOccurs="0" name="paramValue" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="jLupinServiceResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="jlupinOutputParameter" type="tns:jLupinOutputParameter"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="jLupinOutputParameter">
                <xs:sequence>
                    <xs:element minOccurs="0" name="jLupinExceptionModel" type="tns:jLupinExceptionModel"/>
                    <xs:element name="executedServiceError" type="xs:boolean"/>
                    <xs:element minOccurs="0" name="serviceDto" type="tns:jLupinServiceDto"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="jLupinExceptionModel">
                <xs:sequence>
                    <xs:element name="additionalErrorCodeMap">
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element maxOccurs="unbounded" minOccurs="0" name="entry">
                                    <xs:complexType>
                                        <xs:sequence>
                                            <xs:element minOccurs="0" name="key" type="xs:anyType"/>
                                            <xs:element minOccurs="0" name="value" type="xs:anyType"/>
                                        </xs:sequence>
                                    </xs:complexType>
                                </xs:element>
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                    <xs:element minOccurs="0" name="errorCode" type="xs:string"/>
                    <xs:element minOccurs="0" name="errorMessage" type="xs:string"/>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="errorReasons" nillable="true" type="xs:string"/>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="errorSolutions" nillable="true" type="xs:string"/>
                    <xs:element minOccurs="0" name="sourceStackTrace" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </types>
    <message name="JLupinWebservice_jLupinService">
        <part element="tns:jLupinService" name="jLupinService"/>
    </message>
    <message name="JLupinWebservice_jLupinServiceResponse">
        <part element="tns:jLupinServiceResponse" name="jLupinServiceResponse"/>
    </message>
    <portType name="JLupinWebservice">
        <operation name="jLupinService" parameterOrder="jLupinService">
            <input message="tns:JLupinWebservice_jLupinService"/>
            <output message="tns:JLupinWebservice_jLupinServiceResponse"/>
        </operation>
    </portType>
    <binding name="JLupinWebserviceBinding" type="tns:JLupinWebservice">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="jLupinService">
            <soap:operation soapAction=""/>
            <input>
                <soap:body use="literal"/>
            </input>
            <output>
                <soap:body use="literal"/>
            </output>
        </operation>
    </binding>
    <service name="JLupinDefaultWebService">
        <port binding="tns:JLupinWebserviceBinding" name="JLupinWebservicePort">
            <soap:address location="http://127.0.0.1:8080/jLupinNextServerWebService/JLupinWebservice"/>
        </port>
    </service>
</definitions>