How the World's Fastest ESB was Made

A couple of years ago, at WSO2 we implemented a new HTTP transport for WSO2 ESB. Requirements for this new transport can be summarized as follows:

1. Ultra-fast, low latency mediation of HTTP requests.
2. Supporting a very large number of inbound (client-ESB) and outbound (ESB-server) connections concurrently (we were looking at several thousand concurrent connections).
3. Automatic throttling and graceful performance degradation in the presence of slow or faulty clients and servers.

The default non-blocking HTTP (NHTTP) transport from Apache Synapse, which we were also using in WSO2 ESB, supported the above requirements up to a certain extent but we wanted to do better. The default transport was very generic and it was designed to offer reasonable performance in all the integration scenarios the ESB could potentially participate in. However HTTP load balancing, HTTP URL routing (URL rewriting) and HTTP header-based routing are some of the most widely used integration patterns in the industry and to support these use cases well, we needed a specialized transport. 

The old NHTTP transport was based on a dual buffer model. Incoming message content was placed in a SharedInputBuffer and the outgoing message content was placed in a SharedOutputBuffer. Apache Axiom, Apache Axis2 and the Synapse mediation engine sit between the two buffers, reading from the input buffer and writing to the output buffer. This architecture is illustrated in the following diagram.

The key advantage of this architecture is that it enables the ESB (mediators) to intercept all the messages and manipulate them in any way necessary. The main downside is every message happens to go through the Axiom layer, which is not really necessary in cases like HTTP load balancing and HTTP header-based routing. Also the overhead of moving data from one buffer to another was not always justifiable in this model. So when we started working on the new HTTP transport we wanted to get rid of these limitations. We knew that this might result in a not-so-generic HTTP transport, but we were willing to pay that price at the time.

So after some very interesting brainstorming sessions, an exciting 1-week long hackathon followed by several months of testing, bug-fixing and refactoring we came up with what’s today known as the HTTP pass-through transport. This transport was based on a single buffer model and completely bypassed the Axiom layer. The resulting architecture is illustrated below.

The HTTP pass-through transport was first released in June 2011 along with WSO2 ESB 4.0. Back then it was disabled by default and the user had to enable it by uncommenting a few entries in the axis2.xml file. The performance numbers we were seeing with the new transport were simply remarkable. WSO2 also published some of these benchmarking results in a March 2012 article. However at this point the 2 main limitations in the new transport were starting to give us headaches.

1. Configuration overhead (Users had to explicitly enable the transport depending on their target use cases)
2. Cannot support any integration scenario that requires HTTP content manipulation (because Axiom was bypassed, any mediator attempting to access the message payload would not get anything useful to work with)

In addition to these technical issues there were other process related issues that we had to deal with. For instance maintaining two separate HTTP transports was twice as work for the developers and testers. We found that because the pass-through transport was not used as the default, it often lagged behind the default NHTTP transport in terms of features and stability. So after a few brainstorming sessions we decided to try and make the pass-through transport the default HTTP transport in Apache Synapse/WSO2 ESB. But this required making the content manipulation use cases (content aware use cases) work with the new transport. This implied bringing Axiom back into the picture, the very thing we wanted to avoid in our initial implementation. So in order to balance out our performance and heterogeneous integration requirements we came up with the idea of “on-demand message parsing in the mediation engine”.

In this new model, each mediator instance belongs to one of two classes.

1. Content-unaware mediators – Mediators that never access the message content in anyway (eg: drop mediator)
2. Content-aware mediators – Mediators that always access the message content (eg: xslt mediator)

We also identified a third class known as conditionally content-aware mediators. These mediators could be either content-aware or content-unaware depending on their exact instance configuration. For an example a simple log mediator instance, configured as <log/> is content-unaware. However a log mediator configured as <log level=”full”/> would be content-aware since it’s expected to log the message payload. Similarly a simple property mediator instance such as <property name=”foo” value=”bar”/> is content-unaware but <property name=”foo” expression=”/some/xpath”/> could be content-aware depending on what the XPath expression does. In order to capture this content-awareness characteristic of mediator instances at runtime, we introduced a new method (isContentAware) to the top level Mediator interface of Synapse. The default implementation in AbstractMediator class returns true by default so as to maintain backward compatibility. 

With this change in place we modified the mediation engine to check the content-awareness of property of each mediator at runtime before submitting a message to it. List mediators such as the SequenceMediator would run the check recursively on its child mediators to obtain the final value. Assuming that messages are always received through the pass-through HTTP transport, the mediation engine would invoke a special message parsing routine whenever a mediator is detected to be content-aware. It is in this special routine that we bring Axiom into the picture. Therefore if none of the mediators in a given flow or a service is content-aware, the pass-through transport works as it usually does without ever engaging Axiom. But whenever a content-aware mediator is involved, we bring Axiom in. This way we can reap the performance benefits of the pass-through transport while supporting all integration scenarios of the ESB. Since we engage Axiom on-demand we get the best possible outcome for all scenarios. For instance a simple pass through proxy would always work without any Axiom interactions. An XSLT proxy that transforms requests would engage Axiom only in the request flow. Response flow would operate without parsing the messages.

Another tricky problem we encountered was dealing with message parsing itself. For instance how do we parse a message and then send it out when there is only one buffer provided by the underlying pass-through transport? Ideally we need two buffers to read the incoming message from and write the outgoing message to. Also the fact that the Axis2 message builder framework can only handle streams posed a few problems. The buffer we maintained in the pass-through transport was a Java NIO ByteBuffer instance. So we needed to adapt the buffer into a stream implementation whenever the mediation engine engages Axiom. We solved the first problem by implementing our message builder routine to create a second output buffer whenever Axiom is dragged into the picture. The outgoing messages are serialized into this second buffer and the pass-through transport was modified to pick the outgoing content from the second buffer when it’s available. Writing an InputStream implementation that can wrap a ByteBuffer instance solved the second problem.

One last problem that needed to be solved was handling security. In Synapse/WSO2 ESB, security is handled by Apache Rampart, which runs as an Axis2 module that intercepts the messages before they hit the mediation engine. So on-demand parsing at the mediation engine doesn’t work in this scenario. We need to parse the messages before Rampart intercepts them. We solved this issue by introducing a new smart handler to the Axis2 handler chain, which intercepts every message and performs an early parse if security is engaged on the flow. The same solution can be extended to support other modules that require parsing message payload in the Axis2 handler chain.

The reason I decided to compile this blog is because WSO2 folks just released WSO2 ESB 4.6. And this release is based on the new model I’ve described here. Pass-through transport is what the users now get by default. The WSO2 team has also published some performance figures that clearly indicate what the new design is capable of. It turns out the latest release of WSO2 ESB outperforms all the major open source ESB vendors by a significant margin. This release also comes with a new XSLT mediator (Fast XSLT) that operates on the top of the pass-through model of the underlying transport and a new streaming XPath implementation based on Antlr.

The next step of this effort would be to get these improvements integrated into the Apache Synapse code base. This work is already underway and you can monitor its progress through SYNAPSE-913 and SYNAPSE-920.

Busting Synapse and WSO2 ESB Myths

Paul Fremantle, PMC chair of the Apache Synapse project and CTO of WSO2, has written a very interesting blog post addressing some of the myths concerning Apache Synapse and WSO2 ESB. As of now both projects are quite popular, mature and have a very large user base including some of the largest organizations in the world. Surprisingly there are still some people who believe that these projects do not fall under the category of ESB (Enterprise Service Bus) implementations. In his latest post, Paul gives a clear and complete answer to all these misbeliefs, and backs it up with a wide range of facts.

ESB is one of those things in the IT world which don't have a proper standard definition. The best definitions I've come across attempt to align the term along the following cues:

• An architectural construct that provides fundamental services to complex architectures
• An entity that acts as a hub connecting many diverse systems
• A central driver that facilitates Enterprise Application Integration (EAI)

Apache Synapse and WSO2 ESB pass with flying colors on all the above criteria. They provide an array of fundamental services to the systems and architectures that rely on them.  Some of these basic services are:

• Message passing, routing and filtering
• Message transformation
• Protocol conversion
• QoS enforcement (security, reliable delivery etc)
• Logging, auditing and monitoring

Because Synapse and WSO2 ESB do such a good job providing these fundamental services, they can be used to integrate a large number of heterogeneous systems in an enterprise setting. As Paul has also pointed out in his post, Synapse and WSO2 ESB are currently used in hundreds of production deployments all around the world to connect various applications, implemented using various technologies (both open source and proprietary) running on various platforms (Windows, Linux, .NET, J2EE, LAMP, cloud..you name it). In other words Synapse and WSO2 ESB are widely used as centralized drivers that facilitate EAI. The configuration model of Synapse and WSO2 ESB is so agile and powerful that practically any EAI pattern can be implemented on top of them. In fact there are tons of samples, articles and tutorials that explain how various well-known EAI patterns can be implemented using these 'ESB implementations'.

One thing that I've learnt from writing code to Synapse is that it has a very flexible enterprise messaging model. Support for any wire level protocol or any message format can be easily implemented on top of this model and can be deployed as a separate pluggable module. During the last few years, I myself have contributed to the implementation of following adapters/connectors on various occasions:

• FIX transport
• SAP transport (IDoc and BAPI support)
• MLLP transport and HL7 message formats
• CSV and various other office document formats
• Thrift connector
• Numerous other custom binary protocols based on TCP/IP

This is just a bunch of stuff that I've had the privilege of implementing for Synapse/WSO2 ESB. I know for a fact that other committers of Synapse and WSO2 ESB have been working on supporting dozens of other protocols, message formats and mediators. Thanks to all this hard work Synapse and WSO2 ESB are currently two of the most powerful and feature-complete ESB implementations anyone will ever come across. Also the existence of connectors for so many protocols and applications is a testament to the agility and flexibility that Synapse and WSO2 ESB can bring in as ESB products.

Another aspect of Synapse/WSO2 ESB that has been questioned many times is their ability to support RESTful integrations (Paul also addresses this issue in his post). This confusion stems from the fact that Synapse uses SOAP as its intermediary message format. Without going into too many technical details, I'd just like to point out that one of the largest online marketplace and auctioning providers in the world uses Synapse/WSO2 ESB to process several hundred millions of REST calls in a daily basis. The new API support we have implemented in Synapse makes it absolutely simple to design, implement and expose RESTful APIs on Synapse/WSO2 ESB. In fact I recently published an article which demonstrates through practical examples how powerful RESTful applications can be implemented using Synapse/WSO2 ESB while supporting advanced REST semantics such as HATEOAS. The recently released WSO2 API Manager product which supports exposing rich web APIs with support for API key management is also based on Synapse/WSO2 ESB.

I think I have made my point. Both Synapse and WSO2 ESB are two excellent ESB choices if you're looking to adopt SOA or enterprise integration within your organization. Their wide range of features is only second to the very high level of performance they offer in terms of high throughput and low resource utilization. Please also go through the post made by Paul, where he has explained some of the above issues with low level technical details. I particularly like his analogy concerning Heisenberg's principle of uncertainty :) 

How to GET a Cup of Coffee the WSO2 Way: An Article

Since we implemented REST API support for WSO2 ESB (and Apache Synapse), we have received many requests for new samples, articles and tutorials explaining this powerful feature. I started working on an end-to-end sample for API support somewhere around March but didn't have enough cycles to write it up. Finally, after a several months delay, I was able to submit the finalized sample and the article to WSO2 Oxygen Tank last month. Now it has been published and available for reading on-line at http://wso2.org/library/articles/2012/09/get-cup-coffee-wso2-way

This articles starts with a quick overview on the REST support provided by WSO2 platform. It describes the API mediation capability of the ESB in detail providing several examples. Then the article explains how a complete order management system can be constructed using the REST support available in WSO2 ESB. This sample application has been inspired by the popular article on RESTful application development titled "How to GET a Cup of Coffee" by Jim Webber. Webber's article describes a hypothetical application used in a Starbucks coffee shop which supports placing orders, making payments, and processing orders. The sample described in my article implements all the major interfaces and message flows outlined by Webber. I have also made all the source code and configurations available so that anybody can do the same on their own machines using WSO2 middleware. To make it even more interesting I also implemented a couple of user interfaces for Webber's Starbucks application. These UI tools are also described in my article and they can help you better understand how the applications communicate with each other using RESTful API calls and how their application states change according to typical HATEOAS principles.

Towards the latter part of the article I discuss some of the advanced features of RESTful application development and how such features can be implemented on top of WSO2 middleware. This includes some very important topics such as security, caching and content negotiation.

I hope you will find this article interesting and useful. As always feel free to send any feedback either directly to me or to dev@wso2.org.

High Volume Web API management with WSO2 ESB

During last year's WSO2Con, Paul Fremantle and I co-presented on the topic "High Volume Web API management with WSO2 ESB". There we discussed how WSO2 ESB is specifically designed to handle large volumes of traffic received over many concurrent connections. We explained the multithreading, streaming and non-blocking IO aspects of the ESB while looking at some of the high performance extensions we offer such as the message relay and the pass through HTTP transport. We also went through some ESB and JVM performance tuning basics taking the WSO2 ESB deployment at eBay as a case study.

WSO2 ESB Tips & Tricks 08: Message Stores and Processors

Ability to store a message in a temporary storage is a fundamental requirement in many enterprise integration scenarios. There are many occasions where a systems integrator would have to design a message flow which simply dumps all the messages into some kind of a storage facility for later retrieval. Here are several scenarios that I’ve encountered while working on real-life integration projects which required me to consider using an intermediate message store:

Matching Request Rates

Some services can only process requests at a given rate. But the service consumers, who are generally unaware of the service implementation details, may send requests at any rate they prefer. In this case we should not directly expose the service to consumers who might overwhelm the service by sending too many requests. Therefore consumers should be provided with a virtual service interface (a proxy service) which stores all incoming requests in a persistent store. A separate component would retrieve these messages from the temporary store and play them at the actual service at the preferred rate. This type of a messaging system is generally known as a store-and-forward messaging system.

Guaranteed Delivery

In certain integration scenarios it is of utmost importance that all requests are received and processed by the back-end services (i.e. no message loss). However this is a rather tricky requirement to implement as the back-end services could be unavailable at times due to various reasons like maintenance activities and hardware faults. Here also we can use a persistent message store to solve the problem. We can configure the messaging system or the middleware to detect communication errors that may occur while sending requests and then save the failed requests in a message store for later delivery. Depending on the availability of tools an automated retry mechanism or a manual retry mechanism can be implemented for the failed messages. In this case the persistent store is acting as a dead letter channel.

In-Order Delivery

Some scenarios require that systems consume messages in the exact order they were produced. In such situations respective middleware should be programmed to deliver the requests in the received order. If a request fails due to a temporary outage, the middleware should not send the rest of the messages because that would disrupt the order at which the messages are consumed. The middleware should retry and make sure the failed message is indeed received by the back-end system before the rest of the messages can be sent. A temporary message store is a natural fit for implementing a solution of this nature. However unlike in the previous cases, the message store should be capable of retaining the order in which messages are stored. In general it should be a message queue which provides basic FIFO semantics. The middleware would enqueue all the incoming requests in the store and a different component will pick them up, one at a time, for delivery. In order to preserve the order of messages under error conditions, the delivery component should not remove a message from the store until a satisfactory response has been received from the back-end system for each message sent. This type of systems also falls under the store-and-forward category.

Separation of Concerns

Sometimes it is necessary to run messages through expensive logging and audit routines. However such additional processing can put a lot of overhead on message flows thus contributing to huge delays and sluggish user experience. Using a message store, it is possible to decouple concerns like logging from the fundamental requirements like routing. For an example middleware can be configured to create a copy of each incoming message and dump that into a temporary store. The original message can be routed through the middleware to the desired endpoint without any additional processing. The logging and audit systems can asynchronously consume the messages in the store and perform all the necessary processing on them off-line. This is one of the simplest as well as most common uses of a message store. In fact the standard enterprise integration pattern named "Message Store pattern" describes this very specific use case of intermediate message stores.

As seen from the above examples, the concept of message stores can be used to solve countless enterprise integration problems. The asynchronous and persistent messaging patterns that result from message stores are at the crux of modern message-oriented middleware (MOM). It is an accepted norm that message stores are ideal for constructing complex distributed systems while keeping the overall architecture cohesive but loosely coupled.

Starting from version 4.0.0, WSO2 ESB has built-in support for creating and managing message stores. In fact we took a revolutionary step forward in the enterprise integration space by introducing the “message store – message processor” architecture to WSO2 ESB. At high level a message store is a logical entity in which messages can be stored for later retrieval. Additionally a message store may provide some QoS features such as persistence, message order retention and random access support. The exact runtime behavior and the features offered by a message store are determined by the message store implementation being used. WSO2 ESB currently ships with following two message store implementations.

In-Memory Message Store	Stores messages in an in-memory queue. Not persistent. Supports random access. Retains message order.
JMS Message Store	Stores message in a JMS queue (works with any JMS/JNDI compliant broker). Persistent. Does not support random access. Retains message order.

WSO2 ESB also provides an API using which a user can develop his/her own message store implementations. For an example one can come up with a file system based message store, a JDBC based message store or a NoSQL based message store and use them in WSO2 ESB. XML syntax for configuring a message store is as follows:

<messageStore name="string" class="classname" >
  <parameter name="string" > "string" </parameter>*
</messageStore>

The store mediator is used to enqueue messages in a given message store. This mediator can be used in any sequence or proxy service. Therefore any message flow in WSO2 ESB runtime can be linked up with a message store. By using the store mediator in a fault sequence a message store can be used as a dead letter channel.

<store messageStore="storename"/>

Message stores in WSO2 ESB can be managed via the ESB management console or JMX. One may list the available stores, browse the objects stored in them and perform various operations on the stored messages using the above techniques.

Message processors work hand-in-hand with message stores. They are used to consume messages stored in message stores. Every message processor must be associated with an existing message store. Similar to the case with message stores, there can be multiple message processor implementations. The exact behavior and functionality provided by a processor is determined by its type. Currently WSO2 ESB ships with following two message processor implementations:

Message Forwarding Processor	Retrieves the messages stored in a message store and reliably forwards them to a specified endpoint. This processor attempts to send one message at a time and it does not dequeue a message from the store until it receives a response from the target endpoint. Therefore this processor is ideal for implementing in-order delivery scenarios and guaranteed delivery scenarios.
Sampling Processor	Retrieves the messages stored in a message store and injects them to a given sequence at specified intervals. This processor utilizes the Quartz scheduler framework for periodically processing messages. This can be used to implement message rate throttling scenarios.

Message processors also come with an API using which any custom message processor can be implemented. A message processor is configured as follows in the WSO2 ESB configuration:

<messageProcessor name="string" class="classname" messageStore="storename">
  <parameter name="string" > "string" </parameter>*
</messageProcessor>

As you can see the message store-message processor architecture and the associated API form a very powerful framework on which a wide range of enterprise messaging scenarios can be implemented. Generally speaking, any integration scenario that involves asynchronous or persistent messaging can be easily realized using these components of WSO2 ESB. We have already received some very positive feedback on this architecture from our users and I believe in the long run this will become one of the most widely used features of our middleware stack.

If you are interested in leaning more about the "message store-message processor" architecture of WSO2 ESB following resources will provide some useful details:

• Official documentation: Message stores
• Official documentation: Message processors
• Article: Implementing store and forward messaging patterns with WSO2 ESB - part 1
• Article: Implementing store and forward messaging patterns with WSO2 ESB - part 2

WSO2 ESB 4.0.3 is Out with REST API Support

WSO2 ESB 4.0.3 is now available for download. This contains several bug fixes over WSO2 ESB 4.0.0 and 4.0.2 releases. In addition to that this release comes with the highly anticipated REST API management support. This is a very powerful feature which I believe will be a game changer. I'm planning to do a series of blog posts and articles in the near future describing various use cases and capabilities of this brand new feature. At WSO2 we have already done some public webinars, workshops and development work for actual customers using the REST API support in the new ESB release and the feedback we have received so far has been phenomenal.

REST support is nothing new for WSO2 ESB. Even though we are primarily based on Apache Axis2, which is a SOAP engine, we have always had support for exposing RESTful interfaces and mediating RESTful invocations. However REST support in WSO2 stack was always a bit of a black sheep in the family. More often than not REST was perceived as a second class citizen in the WSO2 stack. But the new REST API support we have implemented changes all that. Now REST fans can easily define REST APIs and associated resources on the ESB and combine them with the powerful mediation features provided by the underlying messaging framework. Instead of worrying about mapping REST concepts to SOAP (which was the old way of handling REST calls with proxy services), developers can now configure REST endpoints in the ESB by directly specifying HTTP verbs, URL patterns (servlet styled), URI templates, HTTP media types and other related headers. Most REST fans will find themselves at home when working with the new API support in WSO2 ESB.

That's only a beginning. We are also looking into combining some of our best products together (including ESB of course) to come up with a comprehensive API management solution. This will be a complete platform where developers will be able to develop and expose REST APIs and users can subscribe and consume them.

As shown in the above diagram, core API management features such as API key management, user management, security and SLA monitoring are all provided by the solution itself. We are also looking at how to leverage our multi-tenant support to make this solution work seamlessly in the cloud.

If you are interested in learning more about the new REST API support in WSO2 stack and our future plans in this area, we are conducting a series of workshops on this very topic in US later this month. I'm sure you will find these sessions both interesting and eye opening. Also stay tuned for my own blog posts and articles on the subject which will give a more in-depth technical insight on the matter.

ESB: The Swiss Army Knife of SOA

My talk at WSO2Con 2011 is now available on YouTube. There I discussed why an ESB is essential for SOA, what kind of problems it can solve and what it is not.

JMS Proxy Services with Fail-Over Support

Rajika has written a very comprehensive article about setting up WSO2 ESB with JMS in a fail-over scenario.

The concept of fail-over endpoints is integral to WSO2 ESB. The user can define a fail-over endpoint in the ESB which in turns consists of two or more child endpoints. ESB will select one of the child endpoints to be the primary endpoint and will keep forwarding all messages to this primary endpoint. If the ESB detects some error while communicating with the primary endpoint, it will automatically fail-over to one of the available backup endpoints. User can also configure the endpoint error codes upon which to trigger a fail-over, endpoint suspend durations and timeout durations. However this is not what Rajika is talking about in his article. His article is about setting up a JMS proxy service with fail-over support in the ESB .

For an example imagine a situation where you have setup a proxy service to receive messages from a JMS queue. The ESB proxy service polls messages out of the queue and forwards them to a backend application for further processing. Now what if the ESB instance which hosts the above mentioned proxy service happens to fail (say due to a hardware failure). Actually in this case there's both good news and bad news. Good news is that no messages will get lost due to the persistent behavior of JMS messaging. If some messages were in flight within the ESB when the failure occurred those messages might get lost. But even that can be avoided by using something like JTA. The bad news however is that the backend application will not receive further requests to be processed. So as far as your overall system is concerned, your applications and services will stay idle while messages keep piling up on the JMS queue.

Rajika discusses a possible architecture to avoid such system downtime by having a backup proxy service (ideally deployed in a separate ESB instance) which listens on the same JMS queue. The backup proxy will be disabled by default to prevent contention between the two proxy services. His architecture also utilizes a scheduled task deployed on the backup ESB which sends periodic heartbeats to the other ESB node. If the backup ESB detects that the primary ESB instance is not responding, it will activate the backup proxy service which will start polling for JMS messages and resume operations in the system.

This is actually fairly simple to implement in WSO2 ESB and can be even further customized to suit the exact enterprise requirements. All the source code and relevant configurations are provided in the article itself.

Rediscover SOA with WSO2 Carbon and WS-Discovery

WS-Discovery is a standard protocol for discovering services and endpoints in an SOA based environment. Using WS-Discovery, servers can publish service metadata to a centralized repository known as the discovery proxy. Clients and other interested parties can query the discovery proxy to find a required service or an endpoint.

WSO2 Carbon platform has exceptional support for WS-Discovery. Service hosting products like WSO2 Application Server can publish their services to a user defined discovery proxy. WSO2 Governance Registry can be used as this discovery proxy and products like WSO2 ESB can query a discovery proxy to locate backend service endpoints.

I recently wrote an article explaining how WS-Discovery is supported in the Carbon platform. The article starts by explaining the basics of WS-Discovery and then describes how to build a complete practical solution based on the discovery protocol. The sample solution described in the article, an inventory management system for Trader Paul's department store, uses 4 WSO2 products. Almost all the core business logic of the solution resides in WSO2 Application Server and WSO2 Data Services Server. The web application which provides the UI layer of the solution uses WS-Discovery to dynamically discover the business services and data services. WSO2 Governance Registry acts as the discovery proxy where all the service metadata are stored. The solution also uses WSO2 ESB to expose some of the core services to the public through a secured channel. The article describes how to use the discovery support in ESB to create these proxy services. Further it describes an advanced functionality of the ESB (discovery mediation extensions), using which 100% dynamic proxy services can be created. These dynamic proxy services use the WS-Discovery protocol to discover the backend service endpoints at runtime.

This article shows the real power of the Carbon framework and what we can achieve with it when the appropriate components/products are combined into a single distributed solution. I certainly enjoyed a lot putting up all the samples and writing content for this article. I hope you will get a similar feeling reading it. All the code and configurations used for the samples are also provided so you can run the Trader Paul's Inventory Management System on your own and try it out. I'm currently working on porting this sample to the StratosLive environment. So it will be soon available on the cloud as well. If you are just looking to learn about WS-Discovery, or just trying to understand how to build solutions with WSO2 products, this article would be a great starting point.

WSO2 ESB Documentation Revamped

No software application is complete without documentation. According to Ian Sommerville (author of the well known textbook on Software Engineering), software is not just the computer programs, but also all associated documentation and configuration data that is needed to make the programs operate correctly. According to this definition documentation is not only a key component of software, but it is one of the factors which differentiates software from computer programs. But unfortunately many open source projects are getting hammered for their poorly structured and less comprehensive documentation. WSO2 ESB documentation also used to suffer from a number of such strictures which made it look slightly obfuscated and disorganized to the reader. While the samples and other configuration related documentation was fairly well organized, the overall documentation offering had several gaps in terms of content, user friendliness and ability to search.

However I'm pleased to announce that those days are now behind us. WSO2 ESB now has a brand new documentation package with a whole lot of new content, an exquisite look and feel and a ton of new features. You will find that almost all the old content has been rewritten, reformatted and reshaped to make it more comprehensive and easier to follow. In contrast to the old documentation, the new offering contains many diagrams, sample configurations and much easier navigation capabilities between different sections. Samples are no longer a separate section in the documentation but they are baked into the relative explanatory sections in the documentation. This way the reader can seamlessly move between content and relevant samples.

Perhaps the most significant feature in the new documentation package is its ability to search for content. All the content items have been properly labeled and indexed so the reader can find out what he's looking for by doing a search on the documentation site. Try out following search links to see for yourself.

• http://docs.wso2.org/dosearchsite.action?queryString=ancestorIds:1179863+AND+new+in+version+4.0&where=ESB&type=&lastModified=&contributor=&contributorUsername=
• http://docs.wso2.org/dosearchsite.action?searchQuery.queryString=ancestorIds:1179863+AND+eventing&searchQuery.spaceKey=ESB

As of now you will find documentation related to WSO2 ESB 3.0.1 and WSO2 ESB 4.0.0 in the new documentation site. Please note that this is still very much an ongoing effort. We are continuously working on making our documentation even more comprehensive and easier to follow. Feel free to help us out by pointing out mistakes, limitations and better yet providing new content that we can include in our documentation offering.

SOA & ESB: Food for Thought

With the immense popularity of Web Services and SOA, the term "Enterprise Service Bus" has become a well known technical buzz word. Many people consider Enterprise Service Bus (ESB) to be a magic wand by which any problem in enterprise integration and SOA can be solved at a whim. But what is the real technical definition of ESB? What are the problems it's supposed to solve? What are the fundamental services and facilities provided by an ESB? What are its limitations and what are the problems it's not supposed to solve? Many people don't really know the answers to these important questions and end up using the wrong tool to solve the wrong problem.

Some people consider ESB as a shortcut to implementing SOA. And why not? Most ESB solutions out their (including our own WSO2 ESB) provide excellent support for SOAP, WSDL and a plethora of other WS-* standards. But does adding an ESB into a solution architecture really bring any SOA aspects into it? On the other hand is it possible to implement a SOA without using an ESB? Food for thought...

Now don't get me wrong. ESB is a fantastic piece of technology. The number of problems it can solve and the number of use cases it can support is mind boggling. Having worked with a number of customers in the past, I've learnt that regardless of the application of SOA principles, it's almost impossible to implement a useful integration solution without an ESB. However as developers and architects we must have a good understanding of what an ESB is and what it is capable of so we can put the ESB technology to use in a more effective manner. Knowing the answers to above questions will help us make better choices when planning out an integration project and selecting middleware for a solution implementation.

I'm going to make an attempt at answering some of the above mentioned questions in my WSO2Con talk scheduled for next Tuesday. It would be interesting to listen to the feedback other developers and architects in the audience have to offer regarding these all important issues. So if you're keen on learning the fundamentals of enterprise integration and ESB feel free to drop in to my talk titled "ESB: The Swiss Army Knife of SOA". If you're not interested in this particular topic, please do join us at WSO2Con anyway. We have 20+ other professionals lined up to deliver some amazing tech talks. I'm sure you will find it interesting and useful.

The Fantastic 4

As usual I'm late with this, but better later than never :)

After almost an year worth of planning, developing, bug fixing and testing, WSO2 ESB 4.0 is finally out. This is the first WSO2 ESB release for year 2011 and follows the 3.0.1 release which went out in September 2010. WSO2 ESB 4.0 comes with an array of new features targeting enterprise users:

• Message stores and processors (for implementing advanced QoS levels such as in-order delivery and exactly once delivery)
• Concept of functions for the ESB configuration language (define sequences and endpoints as parameterized reusable entities)
• Deployment synchronizer (easily synchronize clusters of ESB nodes via the registry)
• Built-in Qpid broker (can be used as a JMS provider or an event broker for pub-sub messaging)
• LDAP based user store powered by Apache DS
• HTTP relay transport (a new non-blocking HTTP transport that supports pure streaming)

In addition you will find the following new mediators in this release:

• URL rewrite mediator (rewrite and modify URL strings)
• Event mediator (fire events to predefined topics)
• Conditional router mediator (implement complex routing scenarios and rules easily)

Apart from these improvements, our UI gurus have given a complete make over to the ESB management console with collapsible menus, improved input validation, and new styling. You will also find that many of the recurring bugs in the 3.x series have been fixed in this latest release.

If you are looking for a high performance, user friendly solution for enterprise integration, then WSO2 ESB is for you. It's completely free and open source under the ASL 2.0. Download today and let us know how it goes. You can get in touch with us over mail, forums and issue tracker.

WSO2 ESB Tips & Tricks 07: Cron Legacy

SOA architects and system integrators often come across situations where they want to schedule a particular task to be executed periodically. It could be a task which polls a message queue or a database at regular intervals to see whether any new data has been received. It could be a task which invokes a web service to retrieve a live feed or to check the status of an external system. Or it could be a task which performs regular house keeping activities such as cleaning up log files, updating configuration files and obtaining data backups.

WSO2 ESB provides a simple but powerful framework based on Quartz for scheduling and managing periodic tasks. The user can program tasks using Java and deploy them to the ESB as jar files. Such custom developed tasks must implement the Task interface of Apache Synapse which consists of a single method named execute(). Within this method user can implement his/her business logic which will then get executed periodically by the ESB. The compiled jar files containing the task implementation classes should be placed in the repository/components/lib directory of the ESB. These jar files will get converted into OSGi bundles at server startup and get deployed into the ESB runtime.

When it comes to scheduling tasks, the user has two options. The user can configure a simple trigger by simply specifying the number of times the task should be executed along with the period between successive runs. The following example shows how the task named foo has been scheduled to be executed every 5 seconds for 1000 times. Here the task implementation class is named org.wso2.testing.tasks.FooTask (to keep the task running until the server is shutdown, just get rid of the count attribute).

<task class="org.wso2.testing.tasks.FooTask" name="foo">
 <trigger interval="5" count="1000"/>
</task>

Alternatively user can configure tasks using the well known ‘Cron’ syntax. This way it is possible to specify more complex timing requirements. The following example shows how the task foo has been scheduled to be executed every Friday at 5pm. (To learn more about Cron syntax refer this tutorial)

<task class="org.wso2.testing.tasks.FooTask" name="foo">
 <trigger cron="0 0 17 ? ? FRI"/>
</task>

WSO2 ESB ships with a sample task implementation class named MessageInjector. This can be used to inject a message into the service bus periodically. Injected messages will be handled by the ‘main’ sequence so they can be routed and mediated as if they were received from a remote client. The same technique can be extended to implement a scheduled task which periodically invokes a web service. Sample 300 of WSO2 ESB documentation shows how to put the MessageInjector task to use.

<task class="org.apache.synapse.startup.tasks.MessageInjector" name="CheckPrice">
 <property name="to" value="http://localhost:9000/services/SimpleStockQuoteService"/>
 <property name="soapAction" value="urn:getQuote"/>
 <property name="message">
               <m0:getQuote xmlns:m0="http://services.samples">
                   <m0:request>
                       <m0:symbol>IBM</m0:symbol>
                   </m0:request>
               </m0:getQuote>
       </property>
       <trigger interval="5"/>
</task>

Note how a set of properties are passed into the task implementation class from the XML configuration. This can be done with user developed custom tasks as well. Let’s assume the task implementation class has a private attribute named ‘studentName’. If you want to pass a value for this attribute from the task configuration you should implement a getter method and a setter method for the above attribute following the standard Java bean conventions (ie getStudentName and setStudentName). Then you can have the following property definition under the task configuration to initialize the studentName attribute.

<property name="studentName" value="Hiranya"/>

This technique can be used to initialize any primitive type attribute of the task implementation class.

WSO2 ESB scheduled tasks also support a concept called ‘pinned servers’. This comes in handy when deploying scheduled tasks in a cluster of ESB servers. In such an environment it might be required that the task get deployed only on some of the nodes and not all the nodes. But since nodes in a cluster usually share all the configuration files this becomes little tricky. The solution is to specify the pinned servers attribute in the task configuration. With that the task will get deployed only on the specified set of servers. Basically this feature allows you to pin a scheduled task to a subset of the nodes in a cluster.

<task class="org.wso2.testing.tasks.FooTask" name="foo" pinnedServers="host1.wso2.org, host2.wso2.org">
 <trigger cron="0 0 17 ? ? FRI"/>
</task>

In the above example the task will get deployed only if the server hostnames match the ones specified in the pinnedServers attribute.

WSO2 ESB management console can be used to create and manage scheduled tasks. The ESB artifact uploader UI (added in ESB 3.x) can be used to upload jar files containing tasks to the ESB without restarting the server. Unfortunately current releases of WSO2 ESB do not enable the user to temporarily suspend the execution of a task. To do that user must remove the task from the ESB configuration. This limitation will be addressed in a future release.

Apache Synapse 2.0 Released

The Apache Synapse team reached a very important milestone last week. After a long but very busy 2 and half years, we announced the general availability of Apache Synapse version 2.0. The previous release of Synapse was version 1.2 which was released way back in year 2008. The Apache Synapse project has grown a lot in terms of code, features and community over the past 2 years and therefore you will find a horde of new features, improvements, bug fixes and samples in the latest release. Some of the noteworthy new features in this release are:

• New, fine-grained configuration model
• Hot deployment and hot update support for configuration artifacts
• Priority based mediation support
• Comprehensive eventing capabilities with WS-Eventing support
• Secure vault for encrypting passwords in configuration files
• File locking support in the VFS transport for concurrent polling
• URLRewrite mediator for fast and simple URL rewriting
• Synapse configuration observer API
• Multiple identity support in the HTTPS transport
• Enhanced JMX monitoring support for the NHTTP transport
• Dead letter channel implementation (experimental)
• Synapse XAR Maven plug-in for generating configuration artifacts

Apache Synapse is a lightweight Enterprise Service Bus (ESB) released under the Apache Software License. It is based on the tried and tested Apache Axis2 SOAP engine. It has excellent support for SOAP, REST, POX, JSON and a variety of wire level transports (HTTP/S, JMS, File transport, FIX...). The non-blocking HTTP transport of Synapse enables it to handle very high volumes of HTTP traffic over thousands of concurrent connections.

Apache Synapse also supports many WS-* standards including WS-Security, WS-ReliableMessaging, and WS-Policy. It can be easily linked up with any SOA registry for metadata management and governance purposes. Synapse has a very flexible configuration model built into it, which makes it one of the easiest ESB applications to learn and adopt.

If you are involved in any SOA projects or system integration activities, Synapse may have something to offer. So please feel free to grab the binary distro and take it for a spin. Feed back welcome on Synapse user list.

WSO2 Excels at NBQSA

WSO2 bagged four awards at the 12th National Best Quality Software Awards (NBQSA) held last week. NBQSA is an annual competition organized by the Sri Lankan chapter of the BCS. Every year many corporate firms, government organizations, tertiary education institutes and individuals take part in this event. The competition is pretty intense and the winners are also given the opportunity to take part in international events such as APICTA.

This year WSO2 really made their presence felt at NBQSA by winning the following four awards:

• Bronze award for tools and infrastructure apps category - WSO2 Data Services Server
• Silver award for research and development category - WSO2 Gadget Server
• Gold award for tools and infrastructure apps category - WSO2 Enterprise Service Bus
• Glod award for overall victory - WSO2 Enterprise Service Bus

I feel truly proud to be a part of such a dynamic team as the WSO2. Three cheers to WSO2 and all the folks who worked with WSO2 (in past and present) and made these achievements possible.

WSO2 ESB 3.0.1 Up for Grabs

Last week we released WSO2 ESB 3.0.1. This release contains a number of important bug fixes and we highly recommend everyone using WSO2 ESB 3.0.0 to upgrade to the latest release as soon as possible. Please note that this is only a bug fix release and as such it doesn't contain any new features over 3.0.0. Therefore any configuration can be easily migrated to the 3.0.1 from 3.0.0.

Some of the significant fixes available in this release are:

• Fixes to the hot deployment/hot update implementation
• Fixes to the built-in patch model
• Transport fixes (particularly in the NHTTP and FIX transports)
• An Axis2 security fix

To make a long story short, there are more than one reason to migrate to WSO2 ESB 3.0.1. So download your copy today.

FIX Your SOA with WSO2 ESB

I believe WSO2 ESB is the ONLY complete enterprise service bus which supports the FIX (Financial Information eXchange) protocol. The FIX transport of WSO2 ESB enables the service bus to communicate with FIX acceptors and initiators. FIX messages received by the service bus can be routed, filtered or transformed using the existing set of mediators. If needed, FIX messages can be transformed and sent to external systems over different protocols such as HTTP and JMS.

I published an article titled "FIX Your SOA with WSO2 ESB" which explains how to setup the FIX transport in WSO2 ESB 3.0 and how to use it to implement a variety of integration scenarios. It gives a good overview on how to develop high performance finance data routing systems using WSO2 ESB. Hope you'll like it!

New Configuration Model of Synapse

If you are trying out a latest Apache Synapse build off the SVN trunk, you will notice that the Synapse configuration model has gone through some significant changes lately. In the past, Synapse was programmed to load the entire mediation configuration (sequences, endpoints, proxy services, tasks etc) from a single XML file, named synapse.xml. Synapse would parse this XML file at startup and construct an object model known as the SynapseConfiguration which contains the definitions of all active mediation components at runtime. While this approach was simple and clean, it had a number of limitations:

• Configuration management becomes a nightmare as the size of the synapse.xml grows. A typical heavy duty configuration would consist of dozens of proxy services, sequences and endpoints. When all these are packed into a single XML file, it becomes difficult to locate a single configuration item quickly.
• With all configuration artifacts stored in a single flat file, it is almost impossible to develop satisfactory tooling support for configuration development and maintenance.
• A team of developers cannot work on configuring a single Synapse instance at the same time.
• Hot deployment is a feature that Synapse has been lacking for years. Being able to hot deploy a proxy service or a sequence into Synapse without having to restart the service bus is a great convenience at development time. But a configuration model based on a single XML file is not at all capable of handling such requirements.

Considering these drawbacks, I implemented a new configuration model for Synapse, known as the multi XML configuration builder. The new model, which is now the default configuration model in Synapse, loads the configuration from a structured file hierarchy, instead of loading the mediation configuration from a single XML file. With this model in place, each endpoint, sequence and proxy service has to be defined in separate XML files. The directory structure for storing these individual configuration files is as follows:

synapse-config
   |
   +-- registry.xml
   +-- endpoints
   +-- event-sources
   +-- local-entries
   +-- proxy-services
   +-- sequences
   `-- tasks

As you can see there are separate dedicated directories for each type of artifacts. Each of these directories can house zero or more XML configuration files. Each file must have the .xml extension to be recognized by the Synapse configuration builder. If you take a look at the source code you will notice that I have enforced this restriction using a Java FileFilter:

    private static FileFilter filter = new FileFilter() {
       public boolean accept(File pathname) {
           return (pathname.isFile() && pathname.getName().endsWith(".xml"));
       }
   };

   private static void createProxyServices(SynapseConfiguration synapseConfig, String rootDirPath)
           throws XMLStreamException {

       File proxyServicesDir = new File(rootDirPath, PROXY_SERVICES_DIR);
       if (proxyServicesDir.exists()) {
           if (log.isDebugEnabled()) {
               log.debug("Loading proxy services from : " + proxyServicesDir.getPath());
           }
           File[] proxyDefinitions = proxyServicesDir.listFiles(filter);
           for (File file : proxyDefinitions) {
               try {
                   OMElement document = parseFile(file);
                   ProxyService proxy = SynapseXMLConfigurationFactory.defineProxy(
                           synapseConfig, document);
                   proxy.setFileName(file.getName());
                   SynapseArtifactDeploymentStore.getInstance().addArtifact(
                           file.getAbsolutePath(), proxy.getName());
               } catch (FileNotFoundException ignored) {}
           }
       }
   }

The mediation registry is defined in the registry.xml file which should be placed at the top level of the file hierarchy.

So does the multi XML configuration builder solve the problems in the old configuration model? Let’s consider the facts:

• With Synapse configuration broken down into smaller, manageable pieces the whole configuration becomes easier to manage and keep track of. As long as the XML files are named appropriately, it is extremely easy to quickly locate a particular configuration item. We recommend using the artifact names to name the corresponding XML files. For an example the file containing the definition of the FooProxy can be named FooProxy.xml.
• With the multi XML configuration builder, developing powerful and elegant tools for creating pieces of the service bus configuration becomes a trivial task. Also one can use conventional configuration management tools and version controlling systems such as Subversion to store and manage the configuration artifacts.
• A team of developers can now work on configuring Synapse. Each developer in the team can work on his own configuration file or set of files.
• Supporting hot deployment is now feasible. As a matter of fact, Ruwan implemented hot deployment and hot update support for Synapse based on the multi XML configuration builder a few weeks back. This feature is now available in the Synapse trunk and will be available for the next Synapse release.

So there you go. Target achieved. There is one little glitch in this approach though. That is how do we handle backward compatibility with older Synapse versions? For instance how can a Synapse 1.2 user, who has a single synapse.xml file, migrate to a new Synapse version? We have provided a solution for that as well. In the new Synapse configuration file hierarchy you can place a synapse.xml file at the top level (alongside with registry.xml). All the mediation components defined in this synapse.xml will be loaded to the service bus at startup along with any other components defined inside the individual directories. So a Synapse 1.2 user can simply copy the existing synapse.xml file to the synapse-config directory in a new Synapse distribution, and it will be picked up by the service bus. In addition to this convenience feature, we are planning on developing some migration tools that can help users to easily migrate an old Synapse configuration file onto a newer version of Synapse.

As far as Synapse is concerned each configuration builder should be associated with a corresponding configuration serializer implementation. Serializers are used to convert the SynapseConfiguration object model back to the textual/XML form. So for the multi XML configuration builder I developed a matching multi XML configuration serializer which can save a SynapseConfiguration object model to a file hierarchy. Similar to the configuration builder this implementation was also heavily dependent on Java file IO APIs. However, after a while we realized that the serializer is not working as expected on certain platforms; most notably on Windows. After running some debug sessions and doing some on-line reading I realized that the Java file IO operations are not consistent on every platform. As a result sometimes the serializer would encounter trouble creating a new file or moving an existing file on Windows.

At this point, my colleague, Rajika suggested using Apache Commons IO API for file manipulation. Commons IO API provides a nice layer of abstraction on top of the standard Java IO APIs. It handles all file IO operations in a consistent and platform independent manner. So I got rid of almost all the Java file IO code in the multi XML configuration serializer and replaced them with corresponding calls to the Commons IO API. Some sample code fragments are shown below:

    private void cleanUpDirectory()  throws Exception {
       // If the target directory already exists and contains any files simply rename it to
       // create a backup - This method does not delete the target directory
       if (rootDirectory.exists() && rootDirectory.isDirectory() &&
               rootDirectory.listFiles().length > 0) {

           if (log.isDebugEnabled()) {
               log.debug("The directory :" + rootDirectory.getPath() + " already exists. " +
                       "Creating a backup.");
           }

           backupDirectory = new File(rootDirectory.getParentFile(), "__tmp" +
                   new GregorianCalendar().getTimeInMillis());
           FileUtils.moveDirectory(rootDirectory, backupDirectory);
       }

       // Create a new target directory
       FileUtils.forceMkdir(rootDirectory);
   }

   private void writeToFile(OMElement content, File file) throws Exception {
       File tempFile = File.createTempFile("syn_mx_", ".xml");
       OutputStream out = new FileOutputStream(tempFile);
       XMLPrettyPrinter.prettify(content, out);
       out.flush();
       out.close();

       FileUtils.copyFile(tempFile, file);
       FileUtils.deleteQuietly(tempFile);
   }

FileUtils is the entry point for file IO operations in the Commons IO API. It provides you with a range of useful methods for managing and manipulating files.

Note that when writing to a file we first write the whole thing to a temporary file and once completed we copy the temp file to the final location. This was required to handle certain edge cases in the hot update implementation. Without that the hot updater will attempt to pickup and process half baked files (Again mostly on Windows – It seems Windows writes to files in chunks).

All in all, Apache Synapse is now equipped with a powerful new configuration model, a matching configuration serializer and hot deployment capabilities that leverage the new configuration model. Speaking of hot deployment, it is also based on the Axis2 hot deployment framework. Therefore it is configured in the axis2.xml file. We are yet to do a Synapse release with all these new exciting features but if you are itching to try them out feel free to grab a nightly build. Also be aware that WSO2 ESB 3.0, which is based on Synapse, has been released and that release contains all these new improvements.

WSO2 ESB Tips & Tricks 04: Troubleshooting JMS

WSO2 ESB works really well with JMS. The JMS transport adapter used by WSO2 ESB comes from the Apache Axis2 project and it makes use of JNDI to connect to various JMS brokers. Therefore WSO2 ESB can work with pretty much any JMS broker that offers JNDI support. The product ships with sample configurations for Apache ActiveMQ integration, but it can be easily modified for integration with a JMS broker like IBM MQ or SwiftMQ.

Enabling JMS in WSO2 ESB is a simple 2-step process.

1. Deploy the JMS client libraries to the repository/components/lib directory (these libraries will be used by the ESB to connect to the JMS broker)
2. Enable JMS transport receiver and the sender by modifying the axis2.xml file or using the management console

Having followed the above mentioned process you can start creating JMS endpoints to forward messages and JMS proxy services to receive messages. However while implementing certain JMS related scenarios you might run into some error conditions. The rest of this blog post focuses on a couple of such commonly encountered problems and how to get rid of them, once and for all.

CNF? NCDF?

If you ever run into any ClassNotFoundExceptions or NoClassDefFoundExceptions while using JMS support in WSO2 ESB, chances are you haven’t deployed all the required client libraries. Please inspect what you have copied into repository/components/lib directory and make sure the required class is available in one of the deployed jars.

Also note that WSO2 ESB ships with geronimo-jms library which contains the javax.jms packages. Therefore you do not have to deploy them again.

HTTP Header Conversion Problem

When forwarding HTTP traffic to a JMS queue using WSO2 ESB, you might at times run into an error similar to the one given below.

ERROR JMSSender Error creating a JMS message from the axis message context

javax.jms.MessageFormatException: MQJMS1058: Invalid message property name: Content-Type

This exception is thrown by the JMS client libraries used to connect with your JMS broker and the problem is specific to the JMS broker being used. I have encountered this issue mostly with IBM Websphere MQ, but I guess there might be other broker implementations that may display the same issue. So here’s what happens….

The incoming HTTP message contains a bunch of HTTP headers that contain the ‘-‘ character. Some notable examples are ‘Content-length’ header and the ‘Transfer-encoding’ header. When ESB attempts to forward the message over JMS it sets the headers of the incoming message to the outgoing JMS message as JMS properties. According to the JMS spec the ‘-‘ character is prohibited in JMS property names. Some JMS brokers like ActiveMQ do not strictly check for this and hence they won’t complain. But certain other brokers will throw exceptions similar to the one shown above.

Even though the problem sounds very complex and tricky the solution is almost trivial. We just need to get rid of the troublemaking HTTP headers from the message before it is delivered over JMS. You can make use of the property mediator as follows to achieve this:

<property action="remove" name="Content-Length" scope="transport">
<property action="remove" name="Accept-Encoding" scope="transport">
<property action="remove" name="User-Agent" scope="transport">
<property action="remove" name="Content-Type" scope="transport">

JMS Property Data Type Mismatch

Sometimes when the ESB attempts to forwards a message over JMS, the client libraries may complain, saying that the data type of a particular message property is invalid. You may often run into this problem if you are using the property mediator to manipulate property values set on the message. This is because certain implementations of JMS, have restrictions on data types of properties. The property mediator always sets property values as strings.

To overcome this problem you will have to revise your mediation sequences and avoid manipulating property values which should contain non-string values. If you must set a non-string property value you will have to write a simple custom mediator to get the job done. Starting from WSO2 ESB 3.0 (scheduled to go out this month), the property mediator is type aware. Therefore to get rid of this problem you can set properties with specific data types. For an example if you want to set a property named foo with the integer value 12345 use the property mediator as follows:

<property name="foo" value="12345" type="INTEGER" scope="transport/">

If you leave the type attribute out the property value will be set as a string.

Too Many Threads? Out of Memory?

With certain JMS brokers WSO2 ESB tends to spawn new worker threads indefinitely until it runs out of memory and crashes. I have observed this behavior with SwiftMQ. This problem is caused by a bug in the underlying Axis2 engine and there is a simple workaround to the problem. In your mediation sequence engage the property mediator as follows:

<property action="remove" name="transportNonBlocking" scope="axis2">

This will prevent the ESB from creating new worker threads unlimitedly and everything will be back to normal. Note that you can always use a JMX client like jconsole to monitor the active threads and memory consumption of the ESB.

WSO2 ESB Tips & Tricks 03: Transport Switching

Back to WSO2 ESB Tips and Tricks!

Today we are going to see how to implement a transport switching scenario with WSO2 ESB. WSO2 ESB supports receiving and sending messages over following transport and application layer protocols.

• HTTP/HTTPS
• Mail protocols (POP3, IMAP, SMTP)
• JMS / AMQP
• VFS (Virtual File System)
• FIX (Financial Information eXchange)
• TCP
• UDP

With WSO2 ESB having support for such a wide range of transports, it is easy to implement a scenario which involves receiving messages over one protocol and forwarding them over another. As an example I’m going to explain how to receive messages over HTTP and forward them over JMS, using Apache Active MQ as the JMS provider. Looking at how most system integrators use WSO2 ESB it seems this is one of the most common use cases for ESB products.

The first thing we have to do is enable the JMS transport sender in the ESB. By default only the HTTP and HTTPS transports are enabled in the ESB configuration. But configuring and enabling other transports is a trivial task. Transports can be enabled by uncommenting the corresponding entries in the axis2.xml file or by using the ESB management console.

First, shutdown the ESB if it is already running. Then we need to deploy the Active MQ JMS client libraries into the ESB runtime. Download and extract an Apache Active MQ binary distribution (I prefer v5.2). Copy the following jar files from the Active MQ lib directory to the ESB_HOME/repository/components/lib directory.

• geronimo-j2ee_management.jar
• activemq-core.jar

Also this would be a good time to start the Active MQ broker.

Now start the ESB. The underlying Carbon platform will detect the newly deployed jar files and automagically convert them into OSGi bundles on the fly. Once the server has started go to the ESB_HOME/repository/components/dropins directory and do a file listing. You will see a set of OSGi bundles created out of the jar files you deployed.

Now that the server is up and running login to the management console as an admin. Click on ‘Transports’ under ‘Manage’ on the left navigation bar. A list of available transport receivers and senders will be displayed.

Select the ‘Enable’ option for the JMS sender. Click on ‘Enable’ to start the JMS transport sender. Once started, you can further configure the transport by specifying various parameters. But for this demonstration we can go ahead with the default settings (ie no parameters).

If you prefer to enable the JMS sender the old school way open up the axis2.xml file in the conf directory and uncomment the following entry before starting the ESB.

<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/>

Having enabled the JMS sender, we should now create a proxy service which will accept messages over HTTP and send them to a JMS endpoint. Click on ‘Add’ under ‘Proxy Services’ to start the proxy service creation wizard. On the first step simply specify a suitable name for the service (eg: JMSBridge) and click on ‘Next’.

On the second step of the wizard, create an anonymous in-sequence consisting of a property mediator. Configure the property mediator to set the ‘OUT_ONLY’ property to the value ‘true’. Save the in-sequence and create an anonymous endpoint for the proxy service. Specify the following JMS EPR as the target address. This EPR points to a dynamic queue named ‘SimpleStockQuoteService’ in Apache Active MQ broker.

jms:/SimpleStockQuoteService?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&transport.jms.DestinationType=queue

In this scenario we will be doing a one-way invocation using the sample client application. In other words, the client sends a message to the ESB but does not expect a response in return. So the ESB should not expect a response from the backend JMS service either. We indicate this to the ESB by setting the OUT_ONLY property in the in-sequence of the proxy service. ESB will not register any call backs for messages containing the OUT_ONLY property thus no response would be expected.

Having specified the in-sequence and the target endpoint click on ‘Next’ to proceed to the third step of the wizard. Leave the out-sequence and the fault-sequence settings unchanged and simply click on ‘Finish’ to save and exit the wizard. A new proxy service will be deployed on the ESB at this point.

If you prefer to create the above proxy using the ESB configuration language you can use the XML snippet given below.

<syn:proxy name="JMSBridge" transports="https http" startOnLoad="true" trace="disable">
<syn:target>
   <syn:endpoint>
      <syn:address uri="jms:/SimpleStockQuoteService?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&transport.jms.DestinationType=queue"/>
   </syn:endpoint>
   <syn:inSequence>
      <syn:property name="OUT_ONLY" value="true" scope="default"/>
   </syn:inSequence>
</syn:target>
</syn:proxy>

On the management console, click on the ‘Synapse’ link under ‘Configure’ and add the above XML as a child of the top level ‘definitions’ element. Click ‘Update’ to apply the changes.

Now we are all set to run the scenario. Deploy the SimpleStockQuoteService into the sample Axis2 server. Open up the axis2.xml file for the sample Axis2 server and enable the JMS transport receiver in it. This file can be found at samples/axis2Server/repository/conf directory. To enable the JMS listener uncomment the following XML fragment.

<transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">
......
</transportReceiver>

Finally start the sample Axis2 server. Since we have enabled the JMS receiver for the sample server, the SimpleStockQuote service will be exposed over JMS and the server will start listening on a JMS queue named ‘SimpleStockQuoteService’. When you haven’t specified a queue name in the service configuration, the Axis2 JMS transport will by default listen on a queue with the same name as the service. To explicitly specify the queue name for a service one must set the transport.jms.Destination parameter as a service parameter (ie in the services.xml file).

Finally go to samples/axisClient and run the following command to send a one-way message to the ESB proxy service over HTTP. (Here we invoke the in-only placeOrder operation on the backend service)

ant stockquote –Daddurl=http://localhost:8280/services/JMSBridge –Dmode=placeorder

The ESB will take the message and forward it over JMS to the queue named ‘SimpleStockQuoteService’. The sample Axis2 server which is currently listening on this queue will pick up the message and process it. Note the following log entry in the Axis2 server log when it takes the message from the JMS queue.

Sun Dec 13 16:15:39 IST 2009 samples.services.SimpleStockQuoteService  :: Accepted order for : 5789 stocks of IBM at $ 89.61765128551305

So there you have it. The proxy service abstraction in WSO2 ESB makes it extremely simple to perform protocol conversions and route messages back and forth. I suggest you also have a look at the set of transport switching samples that come with WSO2 ESB distribution. We got samples covering all the major protocols and even some of the domain specific transports like FIX and AMQP.

In my next post, I will focus on common problems that most developers encounter while implementing transport switching scenarios involving JMS and possible solutions to such pitfalls.