Introduction

Since Apache Axis2 has been developed keeping WSDL 2.0 concepts in mind, it has built-in support for all the eight Message Exchange Patterns (MEPs) defined in WSDL 2.0. An MEP describes how communication occurs between two entities, such as, how the client interacts with the server. Some of the pre-defined MEPs in WSDL 2.0 are listed below:

• In-Only
• Out-In
• In-Out
• Out-Only etc.

Note : A particular MEP is defined with respect to the server. For example, in the case of In-Out MEP, there is a message coming into the server, and then there is a message going out from the server. So In-Out MEP is exactly equal to the request-response scenario defined in WSDL 1.1. Similarly, Out-Only MEP is a message sent out from the server but does not have a corresponding incoming message or response.

What is an Out-Only MEP?

In most of the applications we work with, a client is responsible for starting the conversation to which the server responds. So most of the today's Web service applications support either In-Out or In-Only MEPs. However, in the case of Out-Only the server will start the conversation. In other words, server will send out the message to the client. What is the typical use case of having a service which implements Out-Only MEP? Out-Only MEPs are useful for the applications that need eventing / notification.

A good real time application to which Out-Only MEP is applicable is a 'stock quote application', where you can register to the system with set of rules. And when a rule is satisfied the application will notify the client. So client does not need to poll to get to know what is going on. The client application will automatically get an update and can then act on it.

Writing a Sample Service With Out-Only MEP

In this case you need to understand that there should be a running instance of “something” in order to have this MEP. In the case of In-Out and In-Only MEPs what happens is that a client sends the message to the server, at which point the service instance will get called. Then service can process the message and send the response if any. However, in Out-Only case the situation is quite the opposite, the service needs to send a message without having received a message first.

Services with In-Out and In-Only can be considered as “sleeping” service, since only when the server receives a message it wakes up the service and gets the service to process the message. But in the case of Out-Only service, service needs to be active all the time. Therefore, service which has Out-Only MEP can be called an "Active" service.

When implementing a service as an active service you need to remember to make the service active yourself. If you want to have an active service then you need to start a thread when you deploy the service, thus making it active.

There are two main ways of writing an active service in Axis2:

• Implementing service life cycle interface and starting the thread inside the startUp method
• Deploying service in application scope and writing the thread initialization code inside the init method of the service implementation class

This tutorial will explain writing an active service with ServiceLifeCycle class.

Note: Creating a thread is not the recommended route usually. A thread may kill the CPU performance (an infinite thread can take up to 100% of CPU usage), therefore, the best approach is to use something like "TimerTask". However, in this sample We have used a thread just to show the concepts and usage of this particular MEP.

As the first step let's take a very simple sample application. We assume that there is a service whose job is to notify the users with a random number for each specified time interval. And further assume that client needs to register with the server in order to receive those messages. Therefore, the service will have two operations, one is for users to register with the server and other is actually send the messages to the registered clients.

Writing the Service

For better understanding of concepts and their applications, let's try to write the service in few steps. Step1 and Step2 are all about general Web services. Service implementation class has assumed that at the service deployment time user list (an array list of user) will be populated using ServiceLifeCycle implementation class. So whenever some one registers into the system, then new user will be added to the same list. When server shutdowns, all the data will be saved into a file, and next time, user list will be populated using that file, so that user does not need to register twice.

Step 1 : User Registration Method

• First get the current message context
• Then get the corresponding AxisService and
• Add the entry into pre-populated arrayList

 

   public void register(String notifyEpr) {
         MessageContext msgCtx = MessageContext.getCurrentMessageContext();
         AxisService service = msgCtx.getAxisService();
        ((ArrayList) service.getParameterValue("USER_LIST")).add(notifyEpr);
    }

 

Complete source code is available in ActiveService.java found in the sample code1.

Step 2 : Writing ServiceLifeCycle Implementation Class.

The idea of ServiceLifeCycle class is to provide a way to mange the life cycle of the service. And one thing to note here is that service life cycle management is completely different from service session management. Here the idea is to obtain a way to update services when the system is starting up and shutting down. Therefore, once the services.xml has an entry for implementation class of ServiceLifeCycle interface, Axis2 will call that particular implementation class whenever server starts up and shuts down. You can use this mechanism to fire up threads, start database connection etc. So here I have used the same technique to fire up the Service Thread and to pre-populate the users list.

• At service start up time, threads will be started and arraylist will be populated.
• At the service shutdown, user list will be saved to a file.

Complete source can be found in ActiveServiceLifeCycle .java in the sample code1.

Step3 : Writing Service Thread

This is the most important part in the tutorial where we implement Out-Only MEP invocation logic. As stated above Out-Only MEP is sending messages out from the server or simply running client inside the service implementation logic. Service Thread is a thread where we have overridden its run method to run forever (while (true)), so now the thread will be an active one. The logic inside is to generate a random number first, and then create a payload (message SOAP body), create a ServiceClient and send the request. That basically sums up the Out-Only MEP.

If you looking into the code you will realize that what I have used is exactly the same code that you have used to invoke In-Only MEP.

The following list of items can be considered as the key points in the implementation logic of ServiceThread class.

• Inside the Service Thread constructor we have created a service client instance
• And then set the action as “urn:notify”, since we have assumed that the client service has a method called notify.
• Then inside the run method, first it reads the user list from axisService , next generate a random number , create payload using the generated number and send out the message to all the users in the users list.

The complete code is available in ServiceThread.java found in sample code1 of this tutorial.

Deploying the Service

You can easily deploy the ActiveService.aar (download sample source code1) file or you can create your own .aar file just compiling the source. You can deploy the service either into any application server or to SimpleAxisServer.

Deploying the Client Side Service

To demonstrate the full scenario, I have written a sample service (ClientService) for the client side as well. The service only contains one method called notify and it will print out the message it gets. You can deploy either ClientService.aar file or you can build your own service archive file by compiling the code. Then you can deploy that into the same application server or where ever you need it.

How to Register

Now you have both server side service and client side service up and running. Next step is to register the client with the server. You can do that in two ways provided you have deployed the ActiveService service in an application server such as Apache Tomcat

• Register using its REST API
• Invoking the register method using some other means.

In order to register, you first need to know the service EPR (End Point Reference) of the client service. Let's say the EPR of client service is http://localhost:7070/axis2/service/ClientService

Then you can register the client using REST API as follows (assuming server is running in 8080);

http://127.0.0.1:8080/axis2/rest/ActiveService/register?notifyEpr=http://localhost:7070/axis2/service/ClientService

Now watch the client side console and what you are getting in it. It will print a random value, something similar to what I received- 8766030962797217830 at every 2 or 3 seconds.

This means that ActiveService is notifying the client service and is acting as an Out-Only service.

Conclusion

The sample demonstrate how to implement Out-Only service with Apache Axis2. You can improve it to use any advanced applications. It's important you remember the concept which will help you to write your own active services.

Resources

• Sample Code1- Sample Client, ActiveService for server side
• Sample Code2- Sample Service, ClientService for the client side
• Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts

Author

Deepal Jayasinghe, Senior Software Engineer, WSO2. deepal AT wso2 DOT com