WSO2

Message Mediation: Catalog of Synapse Examples, WSO2 ESB

Welcome to another chapter of the ESB section! In this post we are going to detail a catalog of examples of Synapse with WSO2 ESB.

1.Introduction

In this instalment, we will start by analyzing the examples that come from Synapse, which are the same that appear in WSO2’s online documentation. All examples are categorized:

  • Message Mediation.
  • Endpoints.
  • Addition and removal of Quality of Service with Message Mediation.
  • Proxy Services.
  • Addition and removal of Quality of Service with Proxy Services.
  • Transports.
  • Scheduled Tasks.
  • Advanced Mediators.
  • Events.
  • Synapse configuration model.
  • Priority-based mediation.
  • Message storing and message processors.
  • Templates.
  • Rest API
  • Synapse’s EIP library.

Within each category, there is a wide array of examples that we will closely analyze in this post.

2.Message Mediation

  • Introduction to Synapse (Example 0).

In this basic example, Synapse is configured to log messages that go through this middleware. The following diagram outlines what is performed: [Diagram-1]

message mediation

A message is sent from the Axis2 client that heads to the ESB, and from here to Axis2 Server, where it is processed and a response is forwarded. In the sequence there are two main mediators: one is the IN mediator, for processing requests, and the other one is the OUT mediator, to process responses that arrive from the backend. All of this takes place within the same thread so that the variables we add to the input mediator are available in the output mediator.

Another important mediator is SEND, which is used to send the message to its destination, which is the Backend or the Client. The LOG mediator displays the message in the console based on the log4java configuration that we have set up in the ESB.

The sequence may be written using the ESB editor, but as good practices dictate, it is always better to use the development WSO2 environment, or in other words, WSO2 Developer Studio.

-Did you miss the first post of the ESB section, “Apache Synapse Enterprise Service Bus (ESB) and WSO2?” Find it here-

WSO2 Developer Studio

In the following link you will be able to download the development environment:

https://wso2.com/products/developer-studio/

You will then be shown a screen that looks like this:

In our case, since we use Ubuntu, we will select LINUX 64BIT, as shown in the highlighted red square.

Next, you download a zip file:

developer-studio-eclipse-jee-luna-linux-gtk-x86_64-3.8.0.zip

Decompress it into a folder, and inside it, double-click on the file titled “eclipse”.

Load Eclipse:

After that, the Eclipse workspace needs to be selected, which is the location where our projects will be stored.

Press OK.

The Eclipse development environment then opens with the required plugins for developing on WSO2’s Carbon platform.

As you can see on the screen, the project types we will use are:

Maven Multi Module Project: This is a Maven project that contains all other projects as if they were modules of the main project.

ESB Config Project: This project is used for writing the ESB’s configuration.

Composite Application Project: This is the project that generates a CAR file, which will be used to deploy the sequences on the ESB server.

In order to do this, we first generate a Multi-Module project:

Where the Group Id, the Artifact Id and the Project’s Version is specified. Just like in every Maven project. Press Finish.

The Multi-Module project has been created with its associated POM file. Within this project, create the ESB project. Select the Multi-Module project, right click and create the ESB Config project.

Press Next. The project’s name is Sample0.

-Before you continue, discover this useful ebook:-

This ESB Config project is created inside the Multi-Module project.

wso2 chakray esb section

As you can see, in the blue square you can find the ESB configuration project. In the Multi-Module Project’s POM file you can find the new Sample0 module (red square).

The next project that we need to create within the Multi-Module project is the Composite Application Project, where the CAR file, along with all of the ESB’s configuration, will be generated.

This is the file that is imported in WSO2ESB to generate the sequence. Are you with us so far?

esb message mediation

Now, select ‘Next’. The name of the project is Sample0CAR. Press Next.

project confing

As with the ESB Config project, select the Multi Module Project as the “parent” project and press Finish.

esb wso2 chakray

Now, in the Multi-Module project, add the new Composite Application Project module. The resulting structure would be as follows:

esb wso2 chakray

To the left, you can find the hierarchical structure of the MultiModule project, and to the right the two modules that were added: the ESB module and the CAR project module. 

Now, select the Sample0 project, the ESB Configuration project by right-clicking and selecting: New→Sequence.

Press Next. The name of the sequence is main. Then, press Finish.

new sequence artifact esb wso2

The next step is copying the following sequence into the main.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<sequence name="main" xmlns="http://ws.apache.org/ns/synapse">
   <in>
       <!-- log all attributes of messages passing through -->
       <log level="full"/>
       <!-- Send the message to implicit destination -->
       <send/>
   </in>
   <out>
       <!-- log all attributes of messages passing through -->
       <log level="full"/>
       <!-- send the message back to the client -->
       <send/>
   </out>
</sequence>

The final result would be:

esb section catalog examples

-Achieve the digital transformation of your company with the experts of WSO2!-

Now, select the pom.xml file within the Sample0CAR project. Select the Sample0 artifact, which is the ESB sequence, and save.

esb section catalog examples

Now, in the command line, compile the Multi-Module project with Maven.

maven project

If everything has successfully compiled, the ‘BUILD SUCCESS’ message will be displayed, as shown in the following image.

message mediation esb chakray

The CAR file has now been generated in the target folder:sample car esb wso2

 

Import this file into WSO2ESB. In order to do this, execute the ESB: ./wso2server.sh Afterward, select Add in the Carbon Applications menu.

wso2 esb

Now, select the generated CAR file:

carbon wso2 esb

If the steps were properly followed, WSO2ESB will show us a message congratulating us for it, as follows:

message congratulation

Via the command console, we can also see the ESB’s output log. It shows the result of the deployment of the CAR file in the ESB.

deployment of the CAR WSO2 ESB

In the ESB, the sequence shows in the Carbon application list.

CARBON APPLICATION LIST

If you want to see the expanded sequence, go to: Service Bus→ Sequences → Edit and that’s it!

WSO2 ESB

If you click on the Switch to Source link, you will see the sequence:

SWITCH TO SOURCE ESB

Testing the sequence.

In order to test the sequence, send a request from Axis2 Client to Axis2 server via the ESB. To accomplish this, first you need to run the Axis2 or backend server:

/wso2esb-4.9.0/samples/axis2Server$ sudo ./axis2server.sh

testing sequence

As can be seen in the image, Axis2Server uses two ports to receive requests: HTTP 9000 and HTTPS 9002.

-A short break: Is your company ready for GDPR? –

Now use the client to send the request. You can find the client in the following directory:

/wso2esb-4.9.0/samples/axis2Client

The client

The client that we will use is stock quote

Create and send a stock quote request. It can be executed in the ‘smart client’, ‘proxy’ and ‘gateway’ modes by specifying the WSA, transport and endpoints / HTTP proxy URL.

Optionally, a (security) policy could be applied to the requests. The required stock symbol and operation can be specified in the following way:

Examples:

1) ant stock quote

2) ant stock quote [-Dsymbol=IBM|MSFT|SUN|..]

                     [-Dmode=quote | custom quote | full quote | place order | marketactivity]

                      [-Daddurl=http://localhost:9000/soap/SimpleStockQuoteService]

                      [-Dtrpurl=http://localhost:8280]

                      [-Dprxurl=http://localhost:8280]

                      [-Drest=true]

                      [-Dwsrm=true]

                      [-Dpolicy=../../repository/samples/resources/policy/policy_1.xml]

Modes:

quote               – send a quote request for a single stock

custom quote    – sends a quote request for in a custom format

full quote          – obtain quotation reports for a period (e.g., 365 days of the year)

placeholder       – places an order for stock via a one-way request

market activity – obtain a market activity report.

The service

The service we will use is SimpleStockQuoteService

This service has four operations: getQuote (in-out), getFullQuote (in-out), getMarketActivity (in-out) and placeOrder (in-only). The getQuote operation will generate a sample stock quotation for a given symbol. The getFullQuote operation will generate a stock quotation history for the symbol across several days, and the getMarketActivity operation returns stock quotations for a given list of symbols. The placeOrder operation will take a one-way message for a request.

Smart client mode request

sudo ant stock quote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/

addurl: This property indicates the endpoint that the request is sent to (WS-Addressing EPR).

Trpurl: Transport URL, in this case, it is the ESB, as a mediator of the request.

Eclipse’s TCP Monitor

Before sending the request, we will configure Eclipse’s TCP Monitor so as to display the messages between the Client and the ESB, and between the ESB and the Backend. To configure it, there is a tab in Eclipse titled TCP Monitor. Here we configure those two sniffers just like we did in the previous chapter.

Now we need to slightly modify the call to use the ports used by the Sniffer for listening.

sudo ant stock quote -Daddurl=http://localhost:9001/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8281/

The client’s log output shows that the request was successful since we get a response from the server.

eclipse tcp monitor

Stock price = $72.14561840612878

The SOA request received by the first Sniffer between the Client and the ESB is:

soa request

In the previous image, you can see the configuration of Eclipse’s TCP Monitor and the request and reply in XML. Next, the message picked up by the first Sniffer appears.

POST / 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

esb message mediation

The method or action being called is getQuote. This will generate a sample stock quote  for the IBM symbol. The message’s final destination address is under wsa:To.

Below you can see the logs generated by the mediator in the ESB:

As you can see, the message is identical. The difference lies in the new message headers added by Synapse.

To, indicates the message’s destination.

MessageID, as the message identifier.

Direction, indicates whether the message is a request or a response.

INFO – LogMediator

To: http://localhost:9001/services/SimpleStockQuoteService,

WSAction: urn:getQuote,

SOAPAction: urn:getQuote,

ReplyTo: http://www.w3.org/2005/08/addressing/anonymous,

MessageID: urn:uuid:f2af7259-59b2-4b40-b888-28b7ffefdf21,

Direction: request,

Envelope:

log mediator

This is the request message captured by the second sniffer. It is the message that is sent 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

Synapse-PT-HttpComponents

This message arrives at the SimpleStockQuoteService service and generates a log message in the console.

SimpleStockQuoteService

The response to the request by this service is picked up by the second Sniffer:

HTTP/1.1 200 OK

Content-Type: text/xml; charset=UTF-8

Date: Sun, 01 Apr 2018 17:44:35 GMT

Transfer-Encoding: chunked

Connection: Keep-Alive

catalog synapse

The symbol that is associated with the request is IBM, as can be seen in the red square. In the blue square, you can see the latest quotation shown by the Client.

Below is the ESB’s log:

As you can see in the headers, there is no message destination in the To property. On the other hand, there is no Action either, since it is a response message, as indicated in the Direction header.

Since this is a new message, a new MessageID is generated.

LogMediator

To: http://www.w3.org/2005/08/addressing/anonymous,

WSAction: ,

SOAPAction: ,

ReplyTo: http://www.w3.org/2005/08/addressing/anonymous,

MessageID: urn:uuid:b4b13707-2516-49e7-aeca-0b386dc3fa33,

Direction: response,

Envelope:

new message id

Lastly, the response shown by the first Sniffer is as follows (Response coming from the ESB):

HTTP/1.1 200 OK

Content-Type: text/xml; charset=UTF-8; charset=UTF-8

Date: Sun, 01 Apr 2018 17:44:35 GMT

Transfer-Encoding: chunked

catalog synapse wso2 chakray

The payload is identical to the response message for the rest of the mediators, the ESB and the second Sniffer. The value for the ax21: last field is the one shown by the client logs, as we have seen.

Proxy client mode request

To execute the request on the client in proxy mode:

ant stock quote -Daddurl=http://localhost:9001/services/SimpleStockQuoteService -Dprxurl=http://localhost:8281/

prxurl: In this mode, the client uses ‘prxurl’ as an HTTP proxy for sending the request. Therefore, by configuring ‘prxurl’ in Synapse, the client can ensure that the message arrives in Synapse for the mediation.

Once the request has been issued, the first Sniffer shows this request message:

POST http://localhost:9001/services/SimpleStockQuoteService HTTP/1.1

Content-Type: text/xml; charset=UTF-8

SOAPAction: “urn:getQuote”

User-Agent: Axis2

Proxy-Authorization: Basic Og==

Host: 127.0.0.1:8281

Proxy-Connection: Keep-Alive

Transfer-Encoding: chunked

samples wso2 chakray

The payload is always the same.

The Proxy-Authorization HTTP request header contains the credentials to authenticate a user agent on a proxy server. In this case, there are no credentials in use. They are coded in Base 64 (https://www.base64decode.org/). The coded value is the username: password, in this case, there is no value.

You can also see the content of the second Sniffer and the ESB’s log, as well as the response value obtained by the fist Sniffer. It is not necessary to show them since they are similar to the ones already shown.

Conclusion

This time around, we have used WSO2 Developer Studio to generate the ESB’s configuration and follow good practices, and the TCP Monitor as a Sniffer integrated into Eclipse.

All of these environment plugins facilitate the task of working with WSO2 integration tools. Not only with the ESB, but also with WSO2API Manager, for example.

The environment configuration details are always the same in all chapters. If you have doubts in future instalments, make sure you check out this article. Oh, and if you missed the second instalment of this section on ESB: WSO2 Quick Start & Installation Guide, find it here.

Discover the Best Practices for Designing RESTful APIs

A REST API will only be effective if it has a correct design. WSO2 teaches us in this ebook how to create secure and high performance REST APIs.

Written By

Tomás Rabazo

Senior Integration Consultant