Axis2 Handlers

The Axis2 handler is an extension point in Apache Axis2. Axis2 Handlers can intercept the message flow and read/write from/to MessageContext.

Writing an Axis2 handler

Writing an Axis2 handler involves the following:

Implementing the org.apache.axis2.handlers.AbstractHandler interface

The most common and convenient way to write an Axis2 handler is by implementing the org.apache.axis2.handlers.AbstractHandler interface. The logic to handle the message goes into the invoke method. Following is a sample Axis2 handler that is used for counting the number of incoming messages.

package org.wso2.carbon.extensions.handler;

import org.apache.axis2.AxisFault;
import org.apache.axis2.context.MessageContext;
import org.apache.axis2.handlers.AbstractHandler;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class SampleHandler extends AbstractHandler {
  private static int messageCount = 0;
  private static Log log = LogFactory.getLog(SampleHandler.class);
  public InvocationResponse invoke(MessageContext messageContext) throws AxisFault {
      messageCount++;
      log.info("Message count: " + messageCount);
      return InvocationResponse.CONTINUE;
  }
}

Given below are the possible return values:

InvocationResponse.CONTINUE: The message is allowed to continue in the message flow.
InvocationResponse.ABORT: The message is dropped.
InvocationResponse.SUSPEND: The message is suspended in the message flow. This can be used in a situation where we want the message to be held until another message is received.

Making an Axis2 module from the handler (OSGi bundle)

To package the handler, users can create an Axis2 module ( a collection of Handlers) and engage the module in your Carbon product. To make a module, the module.xml file is added to the META-INF directory. Following is the sample module.xml with respect to the above sample:

<module name="messageCounter">
  <InFlow>
      <handler name="InFlowMessageCounterHandler" class="org.wso2.carbon.extensions.handler.SampleHandler">
          <order phase="Transport" />
      </handler>
  </InFlow>
</module>

In the above sample, the module name is defined as “messageCounter” and it is in the message in flow. The handler name and the implementation class is defined in the “handler” tag. The “order” tag is used to define the order and the phase in which the handler should be included. To get a deep understanding of Axis2 Flows, Phases, Handlers and Modules, go to this link.

Next, the users need to build a bundle out of the source. The following pom.xml was used for the sample. Please note the <Axis2Module> tag (in maven-bundle-plugin configuration), which is used by carbon to identify this bundle as an Axis2 Module.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.wso2.carbon.extensions</groupId>
  <artifactId>sample-handler</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>bundle</packaging>
  <dependencies>
      <dependency>
          <groupId>org.apache.axis2.wso2</groupId>
          <artifactId>axis2</artifactId>
          <version>1.6.1.wso2v15</version>
      </dependency>
      <dependency>
          <groupId>commons-logging</groupId>
          <artifactId>commons-logging</artifactId>
          <version>1.2</version>
      </dependency>
  </dependencies>

  <repositories>
      <repository>
          <id>wso2-nexus</id>
          <name>WSO2 internal Repository</name>
          <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
          <releases>
              <enabled>true</enabled>
              <updatePolicy>daily</updatePolicy>
              <checksumPolicy>ignore</checksumPolicy>
          </releases>
      </repository>
  </repositories>

  <build>
      <plugins>
          <plugin>
              <groupId>org.apache.felix</groupId>
              <artifactId>maven-bundle-plugin</artifactId>
              <version>2.3.5</version>
              <extensions>true</extensions>
              <configuration>
                  <instructions>
                      <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                      <Import-Package>
                          org.apache.axis2.*,
                          org.apache.commons.logging.*
                      </Import-Package>
                      <Axis2Module>${project.artifactId}-${project.version}</Axis2Module>
                  </instructions>
              </configuration>
          </plugin>
      </plugins>
  </build>
</project>

Once the OSGi bundle is built, place it in the <PRODUCT_HOME>/repository/components/dropins directory in the Carbon server.

Engaging the Axis2 module

To engage the module globally, add the following entry to the axis2.xml file found in the <PRODUCT_HOME>/repository/conf/axis2 directory. The module can be engaged on service basis as well.