Let’s Write Custom Axis2 Modules

In this blog I will be talking about Apache Axis2 engine and how to write a custom Axis2 module and deploy it in WSO2 MI.
Axis2 provides the capability to add Web services interfaces to Web application.

In the Axis2 architecture there are main 4 parts

1. Flow
2. Phase
3. Handlers
4. Module

Flow :

The Axis2 engine has two flows.

• In Flow : This flow is invoked the Axis2 engine receives a message
• Out Flow : This flow is invoked the Axis2 engine sends a message

Below is a diagram of Axis2 engine

Phase :

As you can see in the above diagram the Axis2 engine has set of pre-defined phases. These phases are configured in the axis2.xml configuration file.
If we take the Inflow, it has

• Transport pre-defined Phase
• Pre-Dispatch pre-defined Phase
• Dispatch pre-defined Phase
• Post Dispatch pre-defined Phase
• User Defined Phase (Which we create, not pre-defined)

The Out flow has

• User Defined Phase (Which we create, not pre-defined)
• Message out pre-defined Phase

These phases are place according to flow order inside the phaseOrder element in axis2.xml file. The type attribute of the phaseOrder element tell us the which the phase order is defined.

<phaseOrder type="inflow">
        <phase name="Transport"/>
        <phase name="PreDispatch"/>
        <phase name="Dispatch"/>
        <phase name="PostDispatch"/>
        <phase name="UserDefined1"/>
    </phaseOrder>
    <phaseOrder type="outflow">
        <phase name="UserDefined2"/>
        <phase name="MessageOut"/>
</phaseOrder>

Important point when adding a User defined Phases to Inflow :

• User defined phases can be added only after the PostDispatch pre-defined phase

Important Point when adding a User defined Phases to Outflow :

• You can add the user defined phases to any place inside the outflow but If any of the user defined phases has the same name as that of a pre-defined phase, the engine will throw errors

Handler :

When a phase is invoked, all the handlers with in the that invoked phase will be invoked according to the place order. The handlers will act as a unit of processing for a module.

Module :

Module is a configuration concept which has collection of handlers along with its configuration. A module can have one or more handlers. In addition, a module also has a configuration file that defines how the handlers of the module are to be placed into the phases.

Below is a sample of module.xml file

As you can see there are four flows defined in the module.xml:

• InFlow — Represents the handler chain that will run when a message is coming in.
• OutFlow — Represents the handler chain that will run when the message is going out.
• OutFaultFlow — Represents the handler chain that will run when there is a fault, and the fault is going out.
• InFaultFlow — Represents the handler chain that will run when there is a fault, and the fault is coming in.

The following set of tags describes the name of the handler, handler class, and the phase in which this handler is going to run.

Get Isuru Liyanage’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

handler

• name : Is the name given for the particular instance of this handler class.
• class: Is the actual implementation class for this handler.

order

• phase : Describes the phase in which this handler runs.

Now enough of theory!! , Lets start writing a Custom Axis2 module.

Ill be creating a custom module contains one handler that just logs the message that is passed through it.

Step 1: Create a Module Implementation

First we have to create a implementation class for the Axis2 module. In this example i’ll be using AuditLogModule.java class as my implementation class of Axis2 module. Axis2 modules should implement the org.apache.axis2.modules.Module interface with the following methods:

public void init(ConfigurationContext configContext, AxisModule module) throws AxisFault;//Initialize the module
public void shutdown(ConfigurationContext configurationContext) throws AxisFault;//End of module processing
public void engageNotify(AxisDescription axisDescription) throws AxisFault;
public void applyPolicy(Policy policy, AxisDescription axisDescription) throws AxisFault ;
public boolean canSupportAssertion(Assertion assertion) ;

• init(), shutdown(), engageNotify() : The methods that can be used to control the module initialization and the termination
• applyPolicy(), canSupportAssertion() :The methods that are used to perform policy related operations.

For this example i’ll be putting a logging method inside the init method so that we can see the init method get invoked.

Step 2: Create a Handler

We can use org.apache.axis2.handlers.AbstractHandler which provides an abstract implementation of the Handler interface. In here we can define the processing logic. I have put a simple logging method that will log the incoming message payload.

• The public void invoke(MessageContext ctx) is the method that is called by the “Axis2” engine when the control is passed to the handler.
• The public void revoke(MessageContext ctx) is called when the handlers are revoked by the “Axis2” engine.

Step 3: Create module.xml

Now we have to put the deployment configuration of the handler to the module.xml. From this the Axis2 engine will know how to deploy this handler and when to invoke the handler in the run time.
In this example i have put my handler in the InFlow under the user-defined phase called “loggingPhase”.

Also below is my pom.xml file of the project and you can find the GitHub project from here [4].

Now you have to run below command to create a .mar file.

mvn clean install

So finally we are done creating a custom Axis2 module. Next we have to deploy this module in the WSO2 MI [1].

Deploying in WSO2 MI

First we have to add our user defined phase to the Axis2 engine in the WSO2 MI. We can do that by editing the file axis2.xml which is in the [MI_Home]/conf/axis2 directory.
We have to add <phase name=”loggingPhase”/> under the InFlow after the Dispatch phase.

Then we have to put our .mar file inside [MI_Home]/repository/deployment/server/axis2modules directory.

Now we have to call the module we created. In WSO2 MI we can engage the module in two different ways.

• To engage in Global level

In the <MI_HOME>/conf/axis2/axis2.xml file, under the Global Engaged Modules section, add a <module ref=”modulename”/> entry for every module that you want to engage on a global level. After that restart the server.
When you invoke any service, the module we created will get invoked.

• To engage in Service Level

In here we are going to invoke the module in a particular service not for all the services. So we have to add the parameter as below including module name to the selected service.

<parameter name="engagedModules">auditLogger</parameter>

As an example,below is the full proxy service configuration after adding the parameter. Only when “testmodule” proxy is invoke the custom Axis2 module will get triggered.

Hope you got an idea on how Axis2 modules works and how to create a custom Axis2 module and deploy it in WSO2 MI.

Reference link :

[1].https://wso2.com/integration/micro-integrator/

[2]. https://wso2.com/library/777/

[3].https://docs.wso2.com/display/EI650/Writing+an+Axis2+Module

[4]. https://github.com/isurul28/Axis2-custom-module