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 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.
<module ref="messageCounter"/>