Go to Global Chains and you will be able to see the

IncomingMessageCountHandler handler in the transport phase between RequestURIBasedDispatcher and SOAPActionBasedDispatcher. Now, this simply tells us that we have engaged the module successfully and we have added the handler into the correct phases to invoke the version server, enter the following into your browser:

http://localhost:8080/axis2/services/Version/getVersion Then, in the console, you will see the following:

This simply tells us that the request has gone though the incoming counter handler and the response has gone though the outgoing counter handler. Now, let's invoke the service one more time and see what we get in the console. We will see the following:

Now we know how to write a very simple module, deploy it, and engage it. As an exercise, we can change the module.xml and see what happens. Also, we can change the phase rules and see whether it puts the handlers into the correct locations. In the meantime, we can restart Tomcat, without engaging the module. Here, we should not see any output in the console. This will help us to understand that handlers are invoked only when we engage the module.

There are other ways of engaging a module, for example, to engage a module globally, a user can edit axis2.xml and add the <module ref="modulename"/> element. Moreover, if a user wants to engage it to particular services, he/she can do that by editing the services.xml and adding the same tag mentioned earlier.

Advanced module.xml

Here, we looked at a very simple module.xml, but when it comes to very complex applications, we need to have many more configurations in a module.xml file. We might need to have parameters, WS-Policy, and endpoints. Now let's look at them one at a time in brief.

Parameters

Adding a parameter here is the same as adding a parameter in services.xml or axis2.xml. We just need to add the following tag into module.xml and Axis2 will do the right thing for us:

<parameter name="foo">bar</parameter>

We can have any number of parameters in a module.xml, and when we want to access the parameter, we can do that by carrying out the following steps:

• First we need to get the AxisModule. We can do that either by using the init method (Axis2 passes the AxisModule ) or we need to get the corresponding AxisModule from the ConfigurationContext (inside the Module

implementation class) or from messageContext (inside a handler).

• After this, we can ask for the parameter from the AxisModule.

WS-Policy

Specifying a WS-Policy element in module.xml is one way of configuring a module.

We can add WS-Policy element inside a module.xml. If we consider the Sandesha2 (reliable message implementation) module, we can find the following policy element:

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"

xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/

oasis-200401-wss-wssecurity-utility-1.0.xsd"

xmlns:sandesha2="http://ws.apache.org/sandesha2/

policy" wsu:Id="RMPolicy">

<sandesha2:RMAssertion>

[REST OF THE FILE]

</sandesha2:RMAssertion>

</wsp:Policy>

Endpoints

In Axis2, an endpoint is an operation of a web service. So, adding an endpoint is the same as adding an operation. The key question is—why do we need to add an endpoint to a module? To understand this, let's assume that we have a module and this module has a set of control operations. The most suitable example is reliable messaging, as it has a number of control messages (for example, create sequence, last message, terminate sequence). Say, we need to invoke a service in a reliable manner. It first needs to set up a sequence with the service. For this, it will send the control message called createSequence to the service we need to access. But that service does not have that method, so if we try to send the createSequence message without adding the method, Axis2 will throw an exception saying Unable to dispatch. Therefore, adding an endpoint will solve that issue. Hence, when we engage Sandesha, it adds a method called createSequence to the service at the time we engage the module (or all the services, if we engage that to the whole system).

When a request comes, Axis2 will dispatch without having any problem. This operation or the endpoint has its own message receiver to do the right thing.

So, it is obvious that when a module needs control operations exchange, it is required to add endpoint to represent those operations. Adding an endpoint is very simple.

What we need to do is add an operation element(s) along with a message receiver and a set of action mapping. To get an idea about that, let's take the Sandesha module as a reference. Its module.xml has the following operation tag to add the control operations. Remember, when we have the operation tag in module.xml, Axis2 will do all the processing, including creating AxisOperation and adding that. As a module author, all we need to do is specify them in the module.xml file:

<operation name="Sandesha2OperationInOut" mep="http://www.

w3.org/2006/01/wsdl/in-out">

<messageReceiver class="org.apache.sandesha2.msgreceivers.

RMMessageReceiver"/>

<!-- namespaces for the 2005-02 spec -->

<actionMapping>http://schemas.xmlsoap.org/ws/2005/02/rm/

CreateSequence</actionMapping>

<actionMapping>http://schemas.xmlsoap.org/ws/2005/02/rm/

AckRequested</actionMapping>

...

</operation>

If we look at the Sandesha module.xml, we will be able to learn and find out more about writing a module.xml file.

Summary

In this chapter, you learned about the importance of the Axis2 module. We also learned that the Axis2 module provides a very flexible way to extend the Axis2 core functionality and provides quality service. Moreover, we discussed the module and related concepts by writing a sample module and demonstrating most of the commonly used configuration settings. In our sample application, we discussed how to write handlers, how to write module implementation classes, and finally, how to put everything together and deploy the module. At the end of the chapter, we learned how to engage a module to Axis2.

In this chapter, we discussed how to write and deploy services and how to write and deploy modules. In the next chapter, we are going to discuss how to invoke a remote service. There, we will discuss how to use Axis2 as a client and invoke services in a number of ways.