Suggested Stomp transport for Apache Axis2

Apache Axis2 is a leading open source software that provides the basis for the web services stack and supports both SOAP ( Simple Object Access Protocol) and REST (Representational State Transfer). In addition to that, it acts as the foundation for building complete web services stack with Apache Rampart, Rahas,Sandesha2 and Kandula2 providing support for all key web services specification.

Axis2 has flexible and scalable architecture compared to its predecessor Axis and it provides lot of support for extending its core functionality. Axis2 consists of pluggable modules, systems, event listeners and pluggable transport framework with very useful extension points. One such a great feature of Axis2 is transport independence. It doesn’t depend on any specific transport and its up to the user to select best transport to meet his requirements.

In this article, I’m not going to explain about what is Axis2 and all its features, instead I’m going to show you my attempt to write a new transport for Axis2 based on the Stomp protocol. Before reading the rest of the article, I recommend you to get an idea about the Axis2 architecture.

Role of a Message Broker in SOAP message delivery

If you need to send a SOAP message to Axis2, there are many ways to transport the SOAP message into the Axis engine. The most standard and flexible way is SOAP over HTTP. But when it comes to the reliability of the transport, it fails. After submitting the SOAP message, HTTP has no guarantee about its delivery. When we consider mission critical systems with zero down times, HTTP may not be the proper transportation option.

Message Oriented Middleware(MOM) can be helpful in such situations. They are often called ‘Message Brokers’ and they provide asynchronous message delivery between heterogeneous systems. Message brokers decouple the senders of messages from the consumers of the messages. The senders and consumers of the messages are completely independent and know nothing about each other.

The key feature of a broker is reliable messaging. With reliable messaging, broker is responsible for delivering messages one and only once for its subscriber. Message level security, Transaction support, message persistence and scalability are other noteworthy features of a message broker.

JMS(Java Messaging Service) provides rich set of Java API to communicate with any JMS compliant message broker. So developers found that SOAP over JMS is a better alternative to SOAP over HTTP, when it comes to reliability and guaranteed delivery.

But the problem was JMS is only for Java. In order to communicate with message brokers, open standard protocols such as AMQP and Stomp were defined and they can be used with any language.

What is Stomp?

Stomp is a very simple protocol to communicate with any Stomp supported message broker. Currently Apache ActiveMQ has a very good support for Stomp including SSL, Non blocking IO (NIO) and message persistence.

Unlike JMS(Java Messaging Service), Stomp has a wire format so that it can be implemented by any language with very little effort. So Stomp already has clients with scripting languages such as Ruby, PHP and Python.

Anatomy of the Stomp transport for Axis2

Before reading this section, I assume you may have a good understanding about the Axis2 architecture.

As I mentioned earlier, Axis2 is independent of underlying transport mechanism. You can create any kind of transport as your wish and plug it into the Axis core. That is a one such a great flexibility in Axis2 architecture.

In order to give you 10,000 feet view of my Stomp transport, just look at the figure below.

As the figure depicts, two queues are used as message destinations. They can be two separate queues in the same broker or two separate queues in different brokers. Selection is up to you. This architecture resembles the JMS point-to-point messaging paradigm.

Execution Sequence

Let me show you how web service client invokes a web service hosted in Axis2 using SOAP over Stomp.

  1. User application needs to make a SOAP request and it delegates the responsibility to Axis Client API with necessary data.
  2. AxisEngine creates the MessageContext object and pass it to he StompSender.
  3. StompSender creates a Stomp message and populates it with Stomp specific information and data extracted from the MessageContext. Body of the message contains the SOAP Request.
  4. StompSender places that Stomp message in inbound queue.
  5. In the server side, StompListener is subscribed to the inbound queue and it will receive the Stomp message when it is placed on the queue.
  6. StompListener dispatches the stomp message and extracts the SOAP request and starts building the MessageContext.
  7. After building the MessageContext, StompListener passes it to the Axis Engine to be processed.
  8. AxisEngine sends the processed MessageContext into StompSender and it starts building a Stomp message using the data extracted from MessageContext.
  9. Server side StompSender places the Stomp message in reply queue.
  10. Client side StompListener is subscribed to the reply queue it will receive the Stomp message.
  11. [6] and [7] steps are repeated in the client side. Once the reply message is processed, it will be passed back to the user application.

Classes involved in the Stomp transport

Stomp transport consist of following classes.

  1. StompListener

    This is the listening interface for the incoming Stomp messages. This class implements the TransportListener interface and takes the responsibility of constructing StompConnection objects according to the axis2.xml file. Each constructed StompConnection object is assigned with an instance of new StompPacketListener. This happens only once when ListenerManager calls the init() method of the StompListener.

  2. StompConnectionThis class abstracts the connection information that are useful to establish a connection with a message broker. Examples are host,port, login credentials and destination names. Usually these information are obtained through ConfigurationContext object and StompListener takes the responsibility of extracting them from ConfigurationContext and populating new StompConnections.
  3. StompPacketListenerThis is the actual dispatcher of a Stomp message. After calling the init() method of the StompListener, several StompConnections may exist and each one is assigned with their own StompPacketListener. StompPacketListener objects subscribes to the Inbound queue or Reply queue, depending on the situation. (If client side, then reply queue. Else they subscribe to the inbound queue).

according to the above figure, same worker thread pool is shared between all StompPacketListener instances. Whenever Stomp packet is received, StompPacketListener pick up a worker thread from worker pool and delegates the dispatching process to that thread.

4. StompSender

This is the opponent to the StompListener. This class is responsible for extracting information from MessageContext and populating a new stomp message. Also it delivers the message to the inbound or reply queue, depending on the situation.

5.  StompMessage

This class merely contains the data that is received with a Stomp packet.

6.  StompUtils

This class consists of utility methods.

7. StompConstants

Constants that are related to this transport are defined here. This includes the transport name and several service parameters.

Third party libraries used

I used Gozirra Java client for Stomp to make communications with the message broker. But its too simple and lack of good design features. So I’ll be writing my own Stomp client to use with this transport in near future.


Up to this point, I’ve implemented all the classes I mentioned and code is now in testing phase and I appreciate your comments on this.

I’ll make another post about how to build this transport with Axis2 source and configurations for axis2.xml.

So stay tuned…


11 thoughts on “Suggested Stomp transport for Apache Axis2

  1. Great article!

    Have you considered using RabbitMQ for this? Although RabbitMQ supports STOMP, the reason I suggest this is because it supports AMQP. Although AMQP is richer (“more complex”) than STOMP, the more detailed semantics that it supports may be helpful if you are using this architecture for integration, or for ‘scale out’ cases.



  2. Thanks in advance for the feedback Alexis!
    Actually I couldn’t find the time to test this implementation with RabitMQ Stomp gateway. I totally agree with your point that AMQP is more richer and robust than Stomp. When it comes to the scalability, AMQP would be the better choice. At the moment I’m using this transport with Apache ActiveMQ and I expect to move into RabbitMQ later on.
    I think Apache Synapse team already developed a AMQP transport and that will be available on axis2 commons transport soon. That transport is backed by Apache Qpid which is an an open source AMQP broker from Apache Software Foundation.

    1. As a part of my Master thesis,I need to develop a prototype of Webservices with ActiveMQ using STOMP.It would be great help to me if you provide me a example how it works.

      Many Thanks

  3. Hi ritwikha,
    I think what you are gonna do is calling a web service hosted in Axis2 using this STOMP transport, aren’t you? If so, you can use ActiveMQ as a STOMP broker.
    I’ll explain the necessary configurations in my next blog post.


  4. Yes Dunith you are rightneed to develop prototype as you said.
    It would be great help if you provide the necessary configurations at the earliest possible !!!

    Thanks and Regards,

  5. Hi Dunithd,

    While I go through Axis2 transport JIRA issues to prepare next release I found you have submitted Stomp transport component sometimes ago. I was able to run your new transport and planning to commit it with few modifications. Meantime I came-cross with nice article written by you here I’m wondering is it OK to take some content and diagrams of this post to include in the Axis2 Transport official documentation. Please let me know your inputs on this ?

    Also one major issue that this patch not yet committed is org.apache.axis2.transport.stomp.util package contains code with LGPL license and Apache does not allow to have LGPL code with it’s projects. May be we have to find another client or have to rewrite these part of the code. If you haven’t done this yet I will try to do it if i find enough time.

    Thanks !

    1. Hi Sagara,

      Go ahead and feel free to extract any information from this blog.
      Regarding the STOMP client rewriting, please proceed with your own implementation.

      Also let me know if there any further contributions I can make for the Axis2 project.

      Dunith Dhanushka

  6. Hi Dunithd,

    Nice article. It helped me alot in understanding AXIS2 transpots. Can you please let us know when your going to provide prototype with stomp.

    Awaiting for your next post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s