Working with Axis2 Service and Module Life Cycle Events

You might be interested in keeping up-to-date with the services and modules deployed within an Axis2 engine. For example, you might want to know when new services and modules are deployed within Axis2 or when they are removed. For this purpose Axis2 provides a notification mechanism for you to register yourself and be notified when changes are made to the services and modules deployed. This tutorial by Eran Chinthaka introduces the event notification mechanism within Axis2 engine that makes it all possible.

Introduction

Oftentimes, it is important to be tuned into the changes that occur iside the Axis2 engine. For example, an Axis2 user may be interested in finding out about new services and modules deployed within the system, or, want to publish when those modules and services are removed from the system. One way users are able to find out about these changes is by having a RSS feed published within the Axis2 engine. This tutorial provides you with insights to useing the in-built capabilities within Axis2 to find out what is happening within Axis2. This helps you write your own method of publishing this information to your server users, if required.

Applies To

Table of Content

1. Writing an Event Listener Service
   1. Step 1 : Registering an event listener
   2. Step 2 : Implement AxisObserver
2. Summary
3. Resources

Writing an Event Listener Service

We will be writing an Axis2 service which can be used to listen into the modifications to the modules and services. You can use this service to publish these events using any method you want. First let's see how we can register ourselves with the Axis2 internal event notification system.

Step 1 : Registering an event listener

The org.apache.axis2.engine.AxisConfiguration provides you with methods to register yourself with the event notification system. You will receive events when there are changes to a service, a service group or a module. To register with org.apache.axis2.engine.AxisConfiguration for events, we need to implement the org.apache.axis2.engine.AxisObserver interface.

public class MyObserver implements AxisObserver
{ 
public void init(AxisConfiguration axisConfig) {} 
public void serviceUpdate(AxisEvent event, AxisService service) {} 
public void serviceGroupUpdate(AxisEvent event, AxisServiceGroup serviceGroup) {} 
public void moduleUpdate(AxisEvent event, AxisModule module) {} // there will also be methods coming from org.apache.axis2.description.ParameterInclude interface // also. Let'd forget about them in this tutorial. // methods coming from org.apache.axis2.description.ParameterInclude will come here 
}

Code Listing 1 : Skeleton of the AxisObserver implementation

As you can see, there are three separate methods in this class to receive different notifications. Let's postpone implementing the body of these methods for the time being and concentrate on registering our observer with AxisConfiguration.

There are two ways you can register this observer with Axis2. The static way is to register our observer using axis2.xml. axis2.xml contains all system-level static configuration. You can add the following XML fragment, under the root element, inorder to register the observer.

<listener class="packagename.MyObserver"/>

Code Listing 2 : Static registration of AxisObserver implementation in axis2.xml

If you followed the static configuration method, you need to make sure your observer implementation can be found in the classpath of Axis2 to ensure that the deployment system can find it during classloading.

If you want to register your observer implementation during runtime, then we need to invoke the org.apache.axis2.engine.AxisConfiguration.addObservers(AxisObserver axisObserver) method. Before calling this method you need to get access to the AxisConfiguration method. If you do not already have access to it, the easiest way is to access AxisConfiguration through the MessageContext object.

// first get access to AxisConfiguration 

AxisConfiguration axisConfiguration = MessageContext.getCurrentMessageContext(). getConfigurationContext().getAxisConfiguration(); 

MyObserver myObserver = new MyObserver(); 

axisConfiguration.addObservers();

Code Listing 3 : Dynamic registration of AxisObserver implementation using AxisConfiguration

Now we have an event registered with Axis2. Let's see how we can handle events that come through the AxisObserver implementation.

Step 2 : Implement AxisObserver

The methods within the AxisObsever interface has the event type and the object that generated the events. For example, if there is a new service deployment, you will get the AxisEvent.SERVICE_DEPLOY event and a reference to the new AxisService object.

All the events that you will receive to your observer implementation are defined inside the org.apache.axis2.engine.AxisEvent class. Let's implement the serviceUpdate method using those events as an example:

public void serviceUpdate(AxisEvent event, AxisService service) 
{ 
switch (event.getEventType()) 
{ 
case AxisEvent.SERVICE_DEPLOY : // handle new service deployment 
System.out.println("New service deployed. Service name " + axisService.getName()); 
break; 
case AxisEvent.SERVICE_REMOVE : // handle service removal 
System.out.println("Service removed from the system. Service name " + axisService.getName());
break; 
case AxisEvent.SERVICE_START : // handle service start 
System.out.println("Service Started. Service name " + axisService.getName()); 
break; 
case AxisEvent.SERVICE_STOP : // handle service stop 
System.out.println("Service Stopped. Service name " + axisService.getName()); 
break; 
} 
}

Code Listing 4 : Implementing serviceUpdate methods to act upon changes to the service changes

As you can see in code listing 4, implementing these service update methods is pretty straightforward. You only need to know about the appropriate events and how to handle them the way you want. You could have written these changes to an RSS feed within those case statements so that your users will get to know about them.

There is a slight difference between service deployed and service started methods. If you have seen the Axis2 administration Web console, it allows you to start and stop services. As soon as you deploy a Web service, it is available for invocations by the clients. However for some reason, the Axis2 administrator can turn off some of the services using the de-activate options (you will receive AxisEvent.SERVICE_STOP events for your observer). When the service is re-activated you will get the AxisEvent.SERVICE_START event.

You can easily integrate this by observing the code inside a Web service, and make it available by using a Web services interface so that the user can query using that. Else, you can publish this information using an RSS feed easily.

Summary

In this tutorial, we spoke about using the service and module life cycle event generation mechanism. We talked about registering our own event handler and handling those events to publish them to any interested users.

Resources

Axis2 User Guide

Axis2 deployment model - This article contains a good introduction to Axis2 modules and service packaging

Author

Eran Chinthaka, Member - Apache Software Foundation, chinthaka(!) at apache(!).org(!)