WSO2 ESB Tips & Tricks 02: Content Based Routing

Content based routing (CBR) is one of the most fundamental and widely used features of an ESB. Most integration scenarios involve situations where we need to analyze the content of a message and route it to a predefined endpoint based on the results. Depending on the actual requirements the ESB will have to inspect the message headers, message body or both.

For an example take a situation where you have two servers, server-A and server-B, that host an order processing service. Assume that server-A takes an hour to process an order whereas server-B takes over two hours. You could use something like WSO2 ESB to do CBR and provide a better service to the clients who are placing order requests on the servers. You can configure the ESB to analyze the request content and somehow identify the high priority requests based on a certain criteria. Such requests can be forwarded to server-A and the other requests can be forwarded to server-B. This way you can assure a better service to the clients who are placing high priority orders.

So how exactly do we implement a CBR scenario with WSO2 ESB? WSO2 ESB provides mediators like the filter mediator and the switch mediator for this task. I will now explain how to employ the filter mediator and get a simple CBR scenario up and running with WSO2 ESB.

Start the server and login to the management console. Click on “Sequences” and select the “Edit” option for the “main” sequence. Start by deleting all the child mediators already present in the sequence. To delete a mediator simply click on it and select the delete option from the little popup thingy that appears.

Now add an “In” mediator and an “Out” mediator to the sequence. Then add a “Filter” mediator as the first child of the “In” mediator. “Filter” mediator will appear on the editor with two more child mediators – “Then” mediator and the “Else” mediator. Let’s leave them as they are for the moment and configure the “Filter” mediator as follows.

On the “Filter” mediator configuration form (just below the editor window) select the “Source and Regular Expression” option. If you cannot see this form on your browser just click on the “Filter” mediator icon on the editor and it will appear on the screen. Specify the following parameters for the source and regular expression fields.

• Source: //m0:getQuote/m0:request/m0:symbol
• Regex: IBM

Now click on the “Namespaces” link and define the following namespace.

• Prefix: m0
• URL: http://services.samples

Exit the namespace editor popup and click on the “Update” button to save the changes made to the “Filter” mediator configuration. Now click on “Then” mediator and select the “Add Child” option from the little popup menu. Add a “Send” mediator as the child of the “Then” mediator. Specify an anonymous endpoint for the send mediator. Provide the address http://localhost:9000/services/SimpleStockQuoteService for the anonymous endpoint.

Once you are done with that click on “Else” mediator. Again add a “Send” mediator as a child. Specify the address http://localhost:9001/services/SimpleStockQuoteService as an anonymous endpoint for the send mediator.

Finally add another “Send” mediator as a child of the “Out” mediator which we added earlier. Do not specify any endpoints for that.

Save and close the sequence editor. We are now ready to run the scenario.

If you prefer to work with the Synapse configuration language and want to implement this scenario by manually editing the configuration you can use the following XML sequence configuration. Simply click on the “Synapse” link under “Configure” in the management console and locate the configuration for the “main” sequence. Replace it with the following XML snippet.

<syn:sequence name="main">
<syn:in>
   <syn:filter xmlns:m0="http://services.samples" source="//m0:getQuote/m0:request/m0:symbol" regex="IBM">
       <syn:then>
           <syn:send>
               <syn:endpoint>
                   <syn:address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
               </syn:endpoint>
           </syn:send>
       </syn:then>
       <syn:else>
           <syn:send>
               <syn:endpoint>
                   <syn:address uri="http://localhost:9001/services/SimpleStockQuoteService"/>
               </syn:endpoint>
           </syn:send>
       </syn:else>
   </syn:filter>
</syn:in>
<syn:out>
   <syn:send/>
</syn:out>
</syn:sequence>

Before we run this scenario let’s try to figure out what it is supposed to do. The “In” mediator will take all the incoming requests and hand them over to the “Filter” mediator which evaluates an XPath expression on the content (Yes – this is the XPath we specified as the 'Source' parameter earlier. It simply extracts a text value from the SOAP payload). We extract a value from the message payload and perform a regular expression match on it (Out regex is “IBM”). If the regular expression matches, the message will be handed to the “Then” mediator or else it will be given to the “Else” mediator. Both these mediators invoke the “Send” mediator but on two different endpoints, so that the incoming requests are sent to one of two endpoints depending on the result of the XPath evaluation and the regular expression match. The “Out” mediator grabs all the responses coming back from the endpoints and invokes the “Send” mediator. Since we haven’t specified a target endpoint for this “Send” mediator, responses will be sent back to the clients based on the addressing information available on the message.

That sounds simple enough. Let’s run this scenario. First go to the directory ESB_HOME/samples/axis2Server/src/SimpleStockQuoteService and deploy the sample service by running the command “ant” (you need to have Apache ANT installed). Then go to ESB_HOME/samples/axis2Server and run the following two commands on two different shells/command prompts. (Run the commands applicable to your platform)

Unix/Linux:
./axis2server.sh –http 9000 –https 9005
./axis2server.sh –http 9001 –https 9006

Windows:
axis2server.bat –http 9000 –https 9005
axis2server.bat –http 9001 –https 9006

These two commands will start two Axis2 instances, one running on port 9000 and the other running on port 9001. To invoke the sample client go to ESB_HOME/samples/axis2Client and execute the following command.

ant stockquote –Daddurl=http://localhost:8280 –Dsymbol=IBM

This will send a message to the ESB with the string “IBM” in the payload. This will match the regular expression and hence will be forwarded to the server running on port 9000. Check out the console where you started that server instance for confirmation. You should see something like this.

Wed Nov 25 18:48:57 IST 2009 samples.services.SimpleStockQuoteService :: Generating quote for : IBM

Now again invoke the client as follows.

ant stockquote –Daddurl=http://localhost:8280 –Dsymbol=MSFT

This will send a message to the ESB with the string “MSFT” in the payload and voila! The regular expression match will fail causing the message to be forwarded to port 9001. Check the Axis2 log for confirmation.

Wed Nov 25 18:48:49 IST 2009 samples.services.SimpleStockQuoteService :: Generating quote for : MSFT

So there you go – CBR made easy by WSO2 ESB. The filter mediator brings if-else like semantics into the mediation logic. The ESB also has a switch mediator. Just guess what semantics that can bring into the mediation. And then of course we have the router mediator to implement complex CBR scenarios. If you are interested in learning more about CBR support available in WSO2 ESB then you can have a look at the following samples. These 2 samples are shipped with WSO2 ESB so you can try them out all by yourself.

• Simple CBR with WSO2 ESB
• Switch mediator

WSO2 ESB Tips & Tricks 01: Sequences and Proxy Services

As promised, here is the first article of the “WSO2 ESB Tips & Tricks” series. The main objective of this post is to introduce two very important functional components of the ESB, namely sequences and proxy services. These are perhaps the most commonly used functional components of WSO2 ESB. They can be used to implement even the most complex of messaging systems and enterprise integration patterns using the service bus. During the course of this article I will briefly explain some of the use cases of sequences and proxy services along with some useful information on how to use them in WSO2 ESB.

WSO2 ESB supports four modes of operation.

1. Service mediation
2. Message mediation
3. Task scheduling
4. Eventing

In the service mediation mode, WSO2 ESB acts as a proxy to a real Web Service hosted in a Web Services container like Apache Axis2 or WSO2 WSAS. The ESB exposes a virtual Web Service which can accept requests from clients. The requests are processed, mediated and forwarded to the actual service implementation by the ESB. Any responses coming from the service implementation are mediated and forwarded to the clients. Proxy services are used to get the ESB operating in this mode.

In the message mediation mode, WSO2 ESB functions as a message router. It can filter, transform, drop messages or forward them to remote endpoints for further processing when operating in this mode. Sequences are used to define the message mediation behavior of the ESB. A sequence is a series of mediators, where each mediator is an entity that can accept messages and carry out a predefined task on them. WSO2 ESB provides you with a wide range of mediators designed to carry out various processing tasks on the messages. You can mix and match these available mediators to develop sequences. For instance a sequence comprising of the log mediator and the send mediator will act as a simple log-and-forward message flow. You can have any number of mediators in a sequence and a sequence can also dispatch messages to other sequences if needed.

A proxy service is a combination of three sequences and a target endpoint. The target endpoint is for the actual service implementation to which the messages will be forwarded after mediation. The three sequences are as follows.

• In-sequence: All the incoming requests to the proxy service are dispatched to the in-sequence. This sequence defines how the requests should be processed before forwarding them to the target endpoint.
• Out-sequence: All the responses coming back from the backend service implementation are dispatched to this sequence. It defines how the responses should be handled before sending them back to the clients. The out sequence can also forward the responses to a given service endpoint, thus effectively linking up multiple services. This way a single request to the proxy service will trigger multiple service invocations. The response from the 1st service is fed to the 2nd service as the request.
• Fault sequence: If an error occurs during service mediation the faulty message is handed to the fault sequence for error handling work. Depending on our requirements the fault sequence can be used log the error, ignore it or send a SOAP fault back to the client indicating that something went wrong.

Now that you have a basic understanding of sequences and proxy services let’s take a look at some of the use cases where these components come in handy. Proxy services can be used to expose an existing service over a different schema (message format). In scenarios like this one, proxy services can transform the messages flowing back and forth. Also since proxy services can be exposed over multiple transports they can be used to expose an existing service over a different transport. For an example we can take a simple HTTP service and expose it over JMS by creating a proxy service for the HTTP service and exposing it over JMS. The ESB will take care of switching the communication protocols. In addition, proxy services are useful in adding QoS features (security, RM etc) to ordinary message flows. As an example, we can take an unsecured service, create a proxy service for it and engage security on the proxy service to add security to the backend service implementation.

Sequences can be used to audit, filter, control and transform messages flowing through a network. Certain advanced features like access control, load balancing and fail over are also possible with sequences. In WSO2 ESB all the incoming messages which are not destined to a proxy service are dispatched to the “main” sequence. The main sequence can further distribute them to other sequences and they in turns can call even more sequences. This is somewhat analogous to how a C program works. The application runtime invokes the main procedure and it in turns can call other procedures.

Enough with the theory! Let’s get practical and see how to create sequences and proxy services in WSO2 ESB. Here actually you have several options. You can either use the XML based Synapse configuration language to define sequences and proxy services, or use the set of graphical tools that come with WSO2 ESB. To create a sequence graphically, first start the ESB server and logon to the management console. (By default the web based console is accessible at https://localhost:9443/carbon) Sign in as an administrator (By default the username and the password are both “admin”). Click on the “Sequences” option in the left panel. This will show you a list of existing sequences. By default the “main” sequence and the global “fault” sequence is listed on this page.

To create a new sequence, click on “Add Sequence”. This will bring up the on-line sequence editor. Start by giving a name to the sequence. Then go ahead and start adding mediators.

To further customize the behavior of a mediator instance click on the mediator and a dialog box will appear just below the sequence editor panel. Once you are done creating the sequence click on “Save” to save and close the editor. The newly created sequence will now show up on the list of available sequences.

Ceating a proxy service is just as easy. Click on the Proxy Service link in the left panel to start the proxy service creation wizard.

Simply go through the 3-step wizard and specify an in-sequence, target endpoint, out-sequence and a fault sequence for the proxy service. When specifying these items you can either import an already existing sequence/endpoint or create one on the spot by selecting the “Anonymous” option.

Once you finish the wizard the new service will get created and deployed on the server. If you gave the name “FooProxy” to the service it will be exposed on the HTTP endpoint http://localhost:8280/services/FooProxy.

Now if you click on the “Synapse” link on the left navigation bar you can see that the overall ESB configuration has been updated with your changes.

The UI also allows you to enable statistics collection on sequences and proxy services, enable tracing on them and modifying their configuration. Play around with the various options available to you and get familiar with sequences, proxy services and the ESB management console. We will be using these a lot in the days to come.

New Kids in Town

The team at WSO2 just released the latest version of WSO2 Carbon (v2.0.2) along with a whole bunch of Carbon based products. Log on to the WSO2 Oxygen Tank to lay your hands on the following smoking hot releases, right from the WSO2 oven ;)

• WSO2 Enterprise Service Bus v2.1.2
• WSO2 Web Services Application Server v3.1.2
• WSO2 Business Process Server v1.1.0
• WSO2 Mashup Server v2.0.1
• WSO2 Identity Server v2.0.2

You will be particularly interested in our Business Process Server and Mashup Server releases since we haven't done any releases of them for a fairly long time. Needless to say that all new releases have many new features, bug fixes and enhancements over the previous versions. So download today and experience the power of SOA.

Introducing "WSO2 ESB Tips and Tricks"

WSO2 ESB has kept me quite busy for the last couple of months. The ESB 2.1 release in July was soon followed by a 2.1.1 release and work is now underway for the 2.1.2 release. That’s way too much activity in such a short period, for an open source project. Anyway, since I’m spending a lot of time working on WSO2 ESB, I thought I might as well blog about my work in a regular basis. So in the next few months, I will be publishing a series of blog posts regarding WSO2 ESB and how to use it to implement real life integration scenarios. This series of blogs, which I have named “WSO2 ESB Tips and Tricks”, will surely benefit many folks who are either just learning SOA concepts or looking to integrate a bunch of apps using an ESB.

You can consider this post to be the 0th article of the “WSO2 ESB Tips and Tricks” series. So before I move on to the 1st post of the series I think I should briefly describe what WSO2 ESB is and why you should consider it as an option for enterprise integration. So here goes:

WSO2 ESB is a fast and lightweight, enterprise service bus. It is based on Apache Synapse, the lightweight ESB from the ASF (speaking of which, “Happy Birthday ASF”). It supports many messaging standards including SOAP, WS-* standards and REST as well as a variety of application and transport layer protocols like HTTP/S, Mail, JMS, VFS, AMQP, TCP and FIX. WSO2 ESB comes with a rich collection of mediators and other functional components which can be used out of the box to implement even the most complex integration patterns. Message routing, transformation, protocol switching, load balancing, clustering and service chaining are some of the common features supported by WSO2 ESB. Controlling and managing WSO2 ESB is also a trivial task thanks to the Web based management. Many of the common system administration tasks such as user management, certificate management and statistics collection are all available as inbuilt features of the server and the management console. WSO2 ESB is shipped with an embedded WSO2 Governance Registry, which makes it easy to store and manage SOA metadata. In addition to that the ESB can be configured to work with an externally hosted WSO2 Governance Registry if needed.

WSO2 ESB is also based on WSO2 Carbon, the OSGi based components framework for SOA. WSO2 Carbon makes it possible to easily install and configure additional features into the ESB runtime. Custom code and third part libraries can also be deployed into the server without any hassle.

Perhaps the best thing about WSO2 ESB (apart from it being super fast) is that it is totally free and open source. Binary and source distributions are available for download through the WSO2 Oxygen Tank. All artifacts are released under the business friendly Apache Software License 2.0. WSO2 also offers training and commercial support for users that require them.

As I have already mentioned a couple of times, WSO2 ESB is well known as a fast ESB. It can easily handle over 2500 transactions per second while maintaining constant memory usage. This level of performance is neither a coincidence nor an accident, but by clever and careful design. Two of the most significant features of WSO2 ESB architecture can be listed as follows:

• Non-blocking HTTP transport : The HTTP server worker threads of the ESB do not get blocked over network I/O. The Apache HTTP Core-NIO based transport makes it possible to accept many concurrent connections and process more messages than any other Java HTTP transport implementation.
• Pull Parsing and Streaming Model: WSO2 ESB uses Apache AXIOM, the StAX based XML infoset model. Therefore it does not build the object model for incoming messages, unless it has to. Incoming bytes are streamed through the ESB without touching the payload. This reduces memory usage significantly and also saves many valuable CPU cycles.

These architectural elements combine with the Carbon framework to deliver the best performance imaginable along with seamless modularization.

Some of the latest features that we have added to WSO2 ESB like rule based mediation and EDA (Eventing) support make WSO2 ESB suitable for implementing even the most complicated SOA platforms.

I think this explanation pretty much justifies why you should give WSO2 ESB a try. It is fast, feature rich and user friendly by all means. And don’t forget, it’s free and open source too. So grab a copy of the latest binary distribution today and get started. If you need any help we got tons of free documentation and articles on the WSO2 Oxygen Tank. This is in addition to our mailing lists and user forums.

I hope you will enjoy the “WSO2 ESB Tips and Tricks”.