Ready for a article about WSO2? We tell you how to do the installation and quick start of WSO2 ESB.
Installation of the WSO2 ESB environment
In this new chapter dedicated to ESB, we will install the tool and a few of the most useful utilities to execute the examples that are included with WSO2, which are the same that are included in the Synapse distribution with slight modifications.
-
Java
We will use an Ubuntu 16.04 LTS, 64-bit Intel® Core™ i7-2630QM CPU @ 2.00GHz × 8.
In order to run WSO2, you need to install a Java Runtime Environment, since WSO2 has been developed in this language. We will accomplish this by downloading the Java SE Development Kit (JDK).
In order to do that, you first need to verify whether the virtual machine is installed on your computer; for this, type the following in your terminal:
java -version
If it is not, you need to install it from the repository. First, add the repository to be able to download JDK:
sudo add-apt-repository ppa:sun-java-community-team/sun-java6
After this, you need to update the repository and install the machine:
sudo apt-get update
sudo apt-get install sun-java6-jdk
Another interesting tool that can be used to install different versions of the virtual machine on your computer is called SDKMAN. It is a software development kit manager, like jdk. Installing it is quite simple, just follow these steps.
For example, in my case, using Ubuntu, in order to list all the virtual machines that are managed and installed by this tool: sdk list java
A list containing the virtual machines is displayed and the tool indicates which one is currently in use in the console. If you want to use a different machine:
If it is were not installed on your system, you can make a new installation. Type: Y
If you want to confirm that is has been installed:
The SDK also creates and updates JAVA_HOME each time a different JDK is used:
It is much easier this way.
-Before continuing, you should exactly know what is exactly WSO2 ESB-
-
JMS Provider (Java Message Service)
Since when using ESB you can work with queues, you can use the WSO2 Message Broker or Apache ActiveMQ. I will give you the installation instructions further down, in the chapter that deals with Message Store and Message Processor.
-
Apache Ant
You need to install the Ant tool, which can be used to compile the ESB client examples and the backends.
-To install it:
sudo apt-get install ant
-And to verify the installation:
ant -version
-This is the best way to design RESTful APIs-
-
Maven
With Maven we will gather the ESB examples.
-Installation:
wget http://www.apache.org/dist//maven/binaries/apache-maven-3.0.3-bin.tar.gz
Now we will extract the file, for example, into the /opt directory:
cd /opt
sudo tar -zxvf apache-maven-3.0.3-bin.tar.gz
Add Maven’s home to the path at the end of the .bashrc file:
export M2_HOME=/opt/apache-maven-3.0.3
export PATH=${M2_HOME}/bin:${PATH}
–To verify the installation:
-
Browser
Lastly, in order to access WSO2 ESB’s console, you need a browser such as Firefox. https://www.mozilla.org/en-US/firefox/new/
WSO2 ESB Quickstart: Installation
In this section, we will study the Synapse messaging model through the use of message mediators and service mediators, because it is the most basic example.
We will first start with WSO2 ESB, in this case, version 4.9.0, but it is just as valid for all other versions. Throughout the course, a few examples will be presented using different ESB versions and on Linux and Mac machines. Now, let’s navigate to the ‘bin’ folder to execute the ESB:
sudo ./wso2server.sh
Use sude, because the script needs to access and modify a series of files. Some interesting environment variables that appear in the log are JAVA_HOME and CARBON_HOME., to save the Java JDK de Java and the path where WSO2 was installed.
Further down you can find the Java Key Store, where the certificates and encrypted passwords are stored with WSO2’s certificate.
In this second image of the initialization, you can see the ports for the HTTP and HTTPS services which are 8280 and 8243 respectively. WSO2’s console can be accessed through the URL shown in red.
The WSO2 ESB URL needs to be added as a security exception since the keystore certificate had not been included in the browser’s certificate repository. Once this issue has been solved, we will see the login screen.
In red, you can see the URL of the ESB that has been selected in the console’s log. The default user and password is: admin, admin.
In the following screen, on the left side the tool’s menus are shown, and in the centre you can see information about the host where WSO2 is being executed: OS information, JRE (Java Runtime Environment used by WSO2) information, and the default H2 database, where information of the metadata repository is stored. WSO2 recommends that you refrain from using this database in your production environment.
Now you need to deploy the sample backend that comes with WSO2. This backend is in charge of receiving the messages coming from the ESB. The ESB then relays them to the client that sent the request.
To deploy the backend in Axis2, you need to go to the following directory:
cd samples/axis2Server/src/SimpleStockQuoteService/
Execute the ant command.
After this, you need to execute the Axis2 server where the web service was deployed: SimpleStockQuoteService
To this end, you need to execute the following command: sudo ./axis2server.sh
As you can see in the blue box, the ports that the server is listening are shown. 9000 for the HTTP service and 9002 for HTTPs.
The web service deployed on the server has a WSDL contract file that can be seen in the browser:
In the red boxes, you can see the URL where the services are stored, and the service deployed with the available operations. The operation I will use in this example is: getQuote. If you click the link, you can see the service’s WSDL file.
In the WSDL file, the endpoints that will be used by the ESB or by the client to redirect the requests to this service are defined.
Message Mediators
You can find the default mediator for the ESB in the left menu, “Sequences” option. Now, you need to press “Edit” in the “main” sequence.
Select “switch to source view” to see the sequence’s source code:
-Main sequence: All messages go through here since it is the default sequence. There is a mediator for incoming messages, in, that obtains the messages from the console. Then there is a filter to send/route the messages containing the value http://localhost:9000 in their To header to the endpoint. *
Outgoing messages, out, are sent directly to the client, send.
<
?xml version="1.0" encoding="UTF-8"?>
<sequence name="main" xmlns="http://ws.apache.org/ns/synapse">
<in>
<!-- Log all messages passing through -->
<log level="full"/>
<!-- ensure that the default configuration only sends if it is one of samples -->
<!-- Otherwise Synapse would be an open proxy by default (BAD!) -->
<filter regex="http://localhost:9000.*"
source="get-property('To')" xmlns:ns="http://org.apache.synapse/xsd">
<then>
<!-- Send the messages where they have been sent (i.e. implicit "To" EPR) -->
<send/>
</then>
<else/>
</filter>
</in>
<out>
<send/>
</out>
<description>The main sequence for the message mediation</description>
</sequence>
Now I will send a message using the client Web Service. The message is sent to the backend through the ESB. In order to do this, you need to go to the following folder:
/wso2esb-4.9.0/samples/axis2Client
In the command line, type:
sudo ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dmode=quote -Dsymbol=IBM
-Daddurl: This is the endpoint where you want to send the message.
-Dtrpurl: This is ESB’s endpoint.
The new stock price sent from the backend is: $145.44733097959232
Since the message has gone through the ESB, and there is a mediator to obtain the messages:
<log level=”full“/>
its contents can be seen in the ESB’s console:
-Formatting the message:
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:To>http://localhost:9000/services/SimpleStockQuoteService</wsa:To> <wsa:MessageID>urn:uuid:a1995447-5102-45ad-8d36-541da41c0657</wsa:MessageID> <wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header> <soapenv:Body> <m0:getQuote xmlns:m0="http://services.samples"> <m0:request> <m0:symbol>IBM</m0:symbol> </m0:request> </m0:getQuote> </soapenv:Body> </soapenv:Envelope>
In the header of the message you can find the To property, that indicates where the message is sent to or the backend’s url. MessageID is the message identifier. Action is the method of the backend web service that will be called. Body is the payload of the message.
The service’s log messages at the backend, axis2 server, are:
Indicating that a message has been received requesting the latest IBM quote. The data received by the client was, as we already know, $145.44733097959232.
Service Mediators (Proxy Service)
In this other case, the client deals with a virtual service. From its point of view, this service is the only endpoint, even though the virtual service may use none or several endpoints in the backend.
This is the difference when compared to the previous example, since it is the client who sends the requests to the ESB, and the endpoint or backend address is specified within the message in Axis2Service. Furthermore, this virtual service can be published with a protocol, scheme, WSDL file or quality of service that differs from the endpoint to which the requests are addressed. It also uses, as in the previous example, sequences and mediators, which means that the input message, from the client, or output message, from the backend, may be processed or mediated.
The definition of the virtual service in the ESB is as follows:
<?xml version="1.0" encoding="UTF-8"?> <proxy xmlns="http://ws.apache.org/ns/synapse" name="StockQuoteProxy" transports="https,http" statistics="disable" trace="disable" startOnLoad="true"> <target> <outSequence> <log level="full"/> <send/> </outSequence> <endpoint> <address uri="http://localhost:9000/services/SimpleStockQuoteService"/> </endpoint> </target> <description/> </proxy>
The proxy service publishes its communications contract through the WSDL file, publishWSDL. The endpoint of the Virtual Service is the Web Service published in Axis2Service, SimpleStockQuoteService.
We will now proceed to publish this service in the ESB. In order to do that, you need to select Proxy Service.
Then, select Custom Proxy.
Next, press switch to source view.
Inside the red box, you can start typing the content or definition of the Proxy Service.
The end result can be seen on the following screen. Press Save.
The service is deployed in the ESB as follows:
As can be seen in the overview, the service that is defined as a Proxy has no security assigned, is accessible through two contracts – WSDL1.1 and WSDL2.0 –, it can be tested and has a design and a source code view.
If you click the name of the StockQuoteProxy service you can see more information about it, such as the endpoint it needs to use to access the Proxy service, in the red box.
You can see the service contract content in the WSDL2.0 link.
In the browser, you can see the URI to access the WSDL file:
http://trm-dell-system-xps-l702x:8280/services/StockQuoteProxy?wsdl2
Port 8280 is the one used for the HTTP protocol in the ESB. Within the WSDL file, you can see the name of the service and the endpoint, in order to access it:
http://trm-Dell-System-XPS-L702X:8280/services/StockQuoteProxy.StockQuoteProxyHttpEndpoint
To test the service you need to type the following in the command line:
sudo ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM
As you can see, the only endpoint that is specified is one of the Virtual Service. In turn, the latter redirects the request to the Backend. Below you can see the response of the service at the backend.
The log generated by the ESB is:
This outSequence log mediator outputs that message, which was generated in the backend and is directed toward the client that made the request. The formatted response message is:
To: http://www.w3.org/2005/08/addressing/anonymous,
WSAction: urn:getQuoteResponse,
SOAPAction: urn:getQuoteResponse,
ReplyTo: http://www.w3.org/2005/08/addressing/anonymous,
MessageID: urn:uuid:e7372891-a7ad-4a8e-870b-5f8487367736,
Direction: response,
Envelope:
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:Action>urn:getQuoteResponse</wsa:Action> <wsa:RelatesTo>urn:uuid:95dcd642-92ef-4797-9dcc-c9941422c273</wsa:RelatesTo> </soapenv:Header> <soapenv:Body> <ns:getQuoteResponse xmlns:ns="http://services.samples"> <ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse"> <ax21:change>4.498546820367199</ax21:change> <ax21:earnings>12.582807320308271</ax21:earnings> <ax21:high>-146.55980144781606</ax21:high> <ax21:last>147.91774407057486</ax21:last> <ax21:lastTradeTimestamp>Sun Mar 04 20:45:40 GMT 2018</ax21:lastTradeTimestamp> <ax21:low>152.4077138700047</ax21:low> <ax21:marketCap>-5137701.204639474</ax21:marketCap> <ax21:name>IBM Company</ax21:name> <ax21:open>154.6561907290828</ax21:open> <ax21:peRatio>23.638753365530036</ax21:peRatio> <ax21:percentageChange>2.6971428631778473</ax21:percentageChange> <ax21:prevClose>166.78934148363535</ax21:prevClose> <ax21:symbol>IBM</ax21:symbol> <ax21:volume>7055</ax21:volume> </ns:return> </ns:getQuoteResponse> </soapenv:Body> </soapenv:Envelope>
In the message’s address, Direction: response is a response; this message is therefore coming from the backend and is headed toward the client that issued the request. The text in yellow is the value that the client sees on the command screen.
TCPmon
The ESB installation includes a sniffer called tcpmon. This is a very interesting tool that lets you intercept messages that are addressed to a service and that come back as someone else’s response on the fly. It allows you to debug and better understand how several integrated components work with each other. It is installed in the following folder: wso2esb-4.9.0/bin (4.9.0 is the version of the ESB I am using in this blog). It is shown with the bat extension for windows or sh for Linux. To execute it: sudo ./tcpmon.sh For the example in this blog – I am referring to the Virtual Service one – it can be used between the Client service and the ESB, and between the ESB and the backend to intercept all incoming and outgoing messages.
1) Client/TCPmon/ESB
In this case, the Web Client needs to send the message to the port where the sniffer is listening. While the sniffer, in turn, forwards that message to port 8280 of the ESB, where the Proxy Service was deployed, while it displays the content of the message. The response message is also displayed.
The Client’s request command would then be:
sudo ant stockquote -Dtrpurl=http://localhost:8281/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM
As you can see, the port is no longer 8280, but 8281, which is where the sniffer is listening.
TCPmon’s configuration is as follows:
The red box shows the port where the sniffer is listening, 8281. The blue box shows the port where the message is resent, 8280, which is to say, the port where our Proxy is listening.
Once the request has been sent, the sniffer intercepts the request and response messages:
You can see the port that TCPmon is listening to, 8281, as well as the port where the message is headed, 8280. The request type is show, which is POST /Services/StockQuoteProxy.
The Client’s request message:
POST /services/StockQuoteProxy HTTP/1.1
Content-Type: text/xml; charset=UTF-8
SOAPAction: “urn:getQuote”
User-Agent: Axis2
Host: 127.0.0.1:8281
Transfer-Encoding: chunked
1d6
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:MessageID>urn:uuid:f7c0f72a-27dd-44ef-a9d9-b1f7aab08bc3</wsa:MessageID> <wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header> <soapenv:Body> <m0:getQuote xmlns:m0="http://services.samples"> <m0:request> <m0:symbol>IBM</m0:symbol> </m0:request> </m0:getQuote> </soapenv:Body> </soapenv:Envelope>
The backend’s response message is:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=UTF-8; charset=UTF-8
Date: Sun, 04 Mar 2018 22:47:36 GMT
Transfer-Encoding: chunked
44c
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing" /> <soapenv:Body> <ns:getQuoteResponse xmlns:ns="http://services.samples"> <ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse"> <ax21:change>-2.5841872904853656</ax21:change> <ax21:earnings>12.399799910092177</ax21:earnings> <ax21:high>77.22015514490265</ax21:high> <ax21:last>73.57205995197508</ax21:last> <ax21:lastTradeTimestamp>Sun Mar 04 22:47:36 GMT 2018</ax21:lastTradeTimestamp> <ax21:low>-72.04349708004447</ax21:low> <ax21:marketCap>-5962331.904617637</ax21:marketCap> <ax21:name>IBM Company</ax21:name> <ax21:open>-71.98873049366591</ax21:open> <ax21:peRatio>24.59327295219441</ax21:peRatio> <ax21:percentageChange>3.7860003496820887</ax21:percentageChange> <ax21:prevClose>-68.25639333874759</ax21:prevClose> <ax21:symbol>IBM</ax21:symbol> <ax21:volume>15110</ax21:volume> </ns:return> </ns:getQuoteResponse> </soapenv:Body> </soapenv:Envelope>
The value in bold, 73.57205995197508, is what the client sees in the command line.
2) ESB/TCPmon/Backend
In this case, the sniffer shows the request message that is output by the ESB, in addition to the response message that is output by the backend. In order to do this, you need to modify the ESB’s Proxy to forward traffic toward the sniffer, and for this one to forward it to the backend in turn. It is important to change the endpoint’s port. In this case, we are using 9001
… <endpoint> <address uri="http://localhost:9001/services/SimpleStockQuoteService"/> </endpoint> ...
Upon saving the Proxy, the ESB deploys it with the new configuration. Now you need to configure TCPmon:
The red box contains the port that the sniffer is listening from. This is the same port used by the Proxy to send the messages to the endpoint. In turn, TCPmon forwards the messages to the backend through port 9000, which is in the blue box.
Now, the request is sent once again from the Client:
sudo ant stockquote -Dtrpurl=http://localhost:8281/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM
And indeed, the sniffer has captured the messages on the fly:
The Client’s request message output by the ESB:
POST /services/SimpleStockQuoteService HTTP/1.1
Content-Type: text/xml; charset=UTF-8
SOAPAction: “urn:getQuote”
Transfer-Encoding: chunked
Host: 127.0.0.1:9001
Connection: Keep-Alive
User-Agent: Synapse-PT-HttpComponents-NIO
1d6
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:MessageID>urn:uuid:247acf74-7d08-4af9-bc33-cab657fc7003</wsa:MessageID> <wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header> <soapenv:Body> <m0:getQuote xmlns:m0="http://services.samples"> <m0:request> <m0:symbol>IBM</m0:symbol> </m0:request> </m0:getQuote> </soapenv:Body> </soapenv:Envelope>
The backend’s response message that is headed toward the ESB:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=UTF-8
Date: Mon, 05 Mar 2018 20:03:17 GMT
Transfer-Encoding: chunked
Connection: Keep-Alive
4d9
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:Action>urn:getQuoteResponse</wsa:Action> <wsa:RelatesTo>urn:uuid:247acf74-7d08-4af9-bc33-cab657fc7003</wsa:RelatesTo> </soapenv:Header> <soapenv:Body> <ns:getQuoteResponse xmlns:ns="http://services.samples"> <ns:return xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ax21:GetQuoteResponse"> <ax21:change>-2.7094263029413312</ax21:change> <ax21:earnings>-9.121962748944178</ax21:earnings> <ax21:high>189.6192278787645</ax21:high> <ax21:last>184.43627910988891</ax21:last> <ax21:lastTradeTimestamp>Mon Mar 05 20:03:17 GMT 2018</ax21:lastTradeTimestamp> <ax21:low>-181.01566760388548</ax21:low> <ax21:marketCap>5.490809216978071E7</ax21:marketCap> <ax21:name>IBM Company</ax21:name> <ax21:open>190.55371322846588</ax21:open> <ax21:peRatio>24.83163812408509</ax21:peRatio> <ax21:percentageChange>1.5047337464878308</ax21:percentageChange> <ax21:prevClose>-180.06018069743897</ax21:prevClose> <ax21:symbol>IBM</ax21:symbol> <ax21:volume>18494</ax21:volume> </ns:return> </ns:getQuoteResponse> </soapenv:Body> </soapenv:Envelope>
As you can see, the messages are exactly the same. However, the content of the payload in each response is different, because two different requests have been generated.
Conclusion
The use of Proxy Services solves many integration problems in corporate information systems. Not only because it can act as a mediator for many protocols, but also because it allows a new security layer to be added, messages to be processed (through filters or by enriching them with more information from other services) and abstracting the user from the rest of the backend services.
On the other hand, and in line with good ESB development practices, Enterprise Integrator does no longer allow editing sequences directly at the ESB’s editor; now, all of this is performed in the Eclipse development environment with the WSO2 plugins installed.
In the following chapters, we will delve deeper into the use of ESB with specific, categorized examples.
