Axis2 provides extended support for modules. For details on modules in Axis2, refer to the Architecture Guide here: http://axis.apache.org/axis2/java/core/docs/Axis2ArchitectureGuide.html
The following steps show the actions that need to be performed to deploy a custom module for a given Web service:
- Create the Module Implementation
- Create the Handlers
- Create the
- Modify the
axis2.xml(if you need custom phases)
- Modify the
services.xml(to engage modules at the deployment time)
- Package in a MAR (Module Archive)
- Deploy the module in Axis2
There is an example of a simple logging module below. This module contains one handler that just logs the message that is passed through it. Axis2 uses MAR (Module Archive) to deploy modules in Axis2.
Create the Module Implementation
LoggingModule is the implementation class of the
Axis2 modules should implement the
org.apache.axis2.modules.Module interface with the following methods:
- 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.
With the input parameter
AxisConfiguration, the user is provided with the complete configuration hierarchy. This can be used to fine-tune the module behavior by the module writers.
For a simple logging service (as in the example), it is possible to keep these methods blank in the implementation class.
Create the Handlers
In the example below, a
LogHandler is created.
A module in "Axis2" can contain one or more handlers that perform various SOAP header processing at different phases. To write a handler one should implement
org.apache.axis2.engine.Handler. But for convenience
org.apache.axis2.handlers.AbstractHandler provides an abstract implementation of the Handler interface.
For the logging module a handler is written with the following methods:
- public void invoke(MessageContext ctx); - Is the method that is called by the "Axis2" engine when the control is passed to the handler.
- public void revoke(MessageContext ctx); - Is called when the handlers are revoked by the "Axis2" engine.
module.xml contains the deployment configurations for a particular module. It contains details such as the implementation class of the module (in this example it is the
LoggingModule class and various handlers that will run in different phases). The
module.xml for the logging module will be as follows:
There are four flows defined in the
- 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.
- name - Is the name given for the particular instance of this handler class.
- class - Is the actual implementation class for this handler. Since we are writing a logging handler, we can reuse the same handler in all these phases. However, this may not be the same for all the modules.
- phase - Describes the phase in which this handler runs.
To learn more about Phase rules, refer to the article Axis2 Execution Framework: http://www.developer.com/java/web/article.php/3529321
In this handler the
loggingPhase is defined by the module writer. It is not a predefined handler phase, hence the module writer should introduce it to the
axis2.xml (not the
services.xml) so that the Axis2 engine knows where to place the handler in different flows (
The following XML lines show the respective changes made to the
axis2.xml in order to deploy the logging module in the "Axis2" engine. This is an extract of the phase section of
The custom phase
loggingPhase is placed in all the flows, hence that phase will be called in all the message flows in the engine. Since the module is associated with this phase, the
LogHandler inside the module will now be executed in this phase.
Modify the services.xml
Up to this point, it was created the required classes and configuration descriptions for the logging module and the required phases.
Next step is to "engage" (use) this module in one of the services, for example
MyService. It is necessary to modify the
MyService in order to engage this module.
The code for the service can be found in the
In this example, the service name was changed. In addition the line
<module ref="logging"/> was added to
services.xml. This informs the "Axis2" engine that the module logging should be engaged for this service. The handler inside the module will be executed in their respective phases as described by the
Package in a MAR (Module Archive)
Before deploying the module, it is necessary to create the MAR file for this module. This can be done using the JAR command and then renaming the created JAR file. Else you can find the
logging.mar that has already been created in the
Deploy the module in Axis2
Deploying a module in Axis2 requires the user to create a directory with the name "modules" in the
webapps/axis2/WEB-INF directory of their servlet container, and then copying the MAR file to that directory.
For more information, refer to http://axis.apache.org/axis2/java/core/docs/modules.html