Introduction

In a given axis2.xml there are a number of top-level elements:

• Message Receiver
• Transport Senders
• Transport Receivers
• Message Builders
• Message Formatters
• Listeners (Observers)
• Deployers
• Module References
• Flow configuration
• Clustering-related configuration

In this article, all of above elements are discussed, with the exception of flow configuration and clustering configuration. Some useful links to understand flow configuration and clustering configuration can be found under the references section at the end of the article.

Message Receiver

The purpose of the message receiver elements in the axis2.xml is to designate global level message receivers, which can specify the MEP (Message Exchange Pattern) and the implementation class. When a service is deployed, it simply refers the MEP in the services.xml and uses the global level message receivers. This makes the service author’s job easier because, if the default message receiver is used, it is not necessary to mention the message receiver in the services.xml.

 <messageReceivers>
        <messageReceiver mep="https://www.w3.org/2004/08/wsdl/in-only"
                         class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
        <messageReceiver mep="https://www.w3.org/2004/08/wsdl/in-out"
                         class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
 </messageReceivers> 

As seen above, the MEP attribute tells the MEP that this class can be handled and that the class attribute represents the implementation class of the MEP.

Transports

As you may know already, Axis2 is transport independent.  This means that, at runtime, Axis2 disregards a message as it arrives into the system, enabling the addition of new transports into Axis2.  Adding a transport is simply a matter of implementing the required interfaces and then configuring that in axis2.xml.  (A discussion on how to write transports is beyond the scope this article, but available resources on this topic are provided in the references section.) The new transport may or may not contain two parts, the transport sender and the transport receiver.

Transport Sender

As the name implies, a transport sender is used when sending a request (at the client side) or sending the response (at the server side). The structure of the transport sender element would look like the following:

<transportSender name="http"
                     class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
        <parameter name="PROTOCOL">HTTP/1.1</parameter>
        <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

The example above shows the transport sender element that consists of two attributes, the name and the class.  Name is the protocol alias, which would be the transport name. For example, if you have two transport sender implementations for HTTP, then the name of those two could be “http” and “http2”. This makes it possible when sending the response to define which transport sender to use, using the transport nickname.

The class attribute should be the actual implementation class of the given transport. Here, it is important that the value be the fully-qualified class name.

A point to note here is that it is possible to have any number of parameters inside the transport sender element, which at the runtime will be visible to the transport sender implementation class.

Transport Receiver

A transport receiver is one that acts as a listener; it can be considered a socket listener. The structure of a transport receiver element would look like the following:

<transportReceiver name="http"
                       class="org.apache.axis2.transport.http.SimpleHTTPServer">
        <parameter name="port">8080</parameter>
       ....
</transportReceiver>

As the example shows, the transport receiver also has two attributes called name and class. The name attribute has exactly the same meaning as the transport sender, and the class attribute represents the implementation class of the transport receiver. In the same manner as the transport sender, a transport receiver can also have a number of parameters which will be visible to the receiver class at the runtime.

Message Builder

The purpose of a message builder is to convert a non-SOAP message into a SOAP message. As mentioned at the beginning of the article, the Axis2 core is based on SOAP, thus it can only handle SOAP. As a result, if a message like REST (POX) or JSON is sent, it first has to be converted into SOAP and then handed over to the Axis2 core. Depending on the content type, new message builders and registers could be written in axis2.xml. Then, at the runtime, when a message is received with the content type specified, message builder will be called. This requires the creation of a SOAP message (correct Axiom object structure) from the incoming message.

<messageBuilders>
        <messageBuilder contentType="application/x-www-form-urlencoded"
                         class="org.apache.axis2.builder.XFormURLEncodedBuilder"/>
</messageBuilders>

The example above shows the message builder element consists of two attributes called content type and class. The attribute “content type” represents the content type of the message that this message builder can process, and the “class” attribute represents the implementation class of the message builder.

Message Formatters

In the case of message builder, message de-serialization is outlined, which deals with the conversion of an incoming message to an object structure. In the case of message formatters, it is the opposite, with the serialization of an object structure into a particular format. Depending on the content type of the outgoing message, Axis2 will call the correct message formatter and ask to process the message. At this point, the message formatter knows how to write the message to the wire. For example, if the content type is “application/xml” then the outgoing message will be serialized as a POX message. The element structure of message formatter would look like this:

<messageFormatters>
        <messageFormatter contentType="application/xml"
                         class="org.apache.axis2.transport.http.ApplicationXMLFormatter"/>
</messageFormatters>

The content type attribute represents the content type that the message formatter can handle, and the class attribute represents the implementation class of the message formatter.

Listeners (Observers)

In Axis2, Axis Configuration is observable. This allows for the registering of observers in order for behavior to be observed.  It will automatically inform them whenever a change occurs in Axis Configuration. Typically, Axis2 will notify the observers for the following type of events:

• Deploying a service
• Removing a service
• Activate/deactivate service
• Module deployment
• Module removal

Registering a listener is simply a matter of implementing the Observer interface in Axis2 and adding the following tag:

<listener class="org.apache.axis2.ObserverIMPL">
    <parameter name="foo" >foo Value</parameter>
</listener>

The class attribute represents an implementation class of observer; the implementation class should implement Axis Observer interface, and the attribute should represent the full qualified class name.

If the observer needs any parameter, it should be added as shown above, and they will be visible to the observer at the runtime.

Deployer

The idea of a deployer is to add a deployment extension to Axis2. Details on deployers are beyond the scope of this article, but resources for this can be found in the references section. The format of the deployer element would look like the following:

<deployer extension=".class" directory="pojo" class="org.apache.axis2.deployment.POJODeployer"/>

The example shows there are three attributes in the deployer element.

• extension – the file extension in which the deployer is interested
• directory – the folder in which particular files are dropped
• class – the implementation class of the deployer

Module References

If it is required to enable or engage some modules globally for the whole system, this can be achieved by adding module reference tags in axis2.xml. Module references can be simply added by the following XML tag:

<module ref="addressing"/>

The element has only one attribute, which represents the referenced module. There can be any number of module references in a given axis2.xml.

Conclusion

Here we discussed almost all the top levels that can be seen in any given axis2.xml as well as the available attributes in those elements.  This two part article covers all the important aspects of axis2.xml, and provides you with the knowledge to change it to suit your requirements.

References

• Axis2 Execution Framework

• Axis2 deployment – Custom deployers

Author

[Deepal Jayasinghe, Tech lead, WSO2, deepal +AT+ wso2 +dot+ com]