Book Excerpt: Quickstart Apache Axis2
XML Processing Model
SOAP Processing Model
This chapter excerpt from
Quickstart Apache Axis2 by Deepal Jayasinghe, is printed with
permission from Packt Publishing,
Looking into Axis2
Flexibility and extensibility are two main design criteria that software
designers would like to have in their applications. When it comes to Axis2, its
architecture is extremely flexible and extensible. Axis2 has a modular
architecture. In this chapter, we will learn more about Axis2 architecture, its
core components, and its main features.
Axis2 is built upon a modular architecture that consists of core modules and
non-core modules. The core engine is said to be a pure SOAP processing engine
(there is not any JAX-PRC concept burnt into the core). Every message coming
into the system has to be transformed into a SOAP message before it is handed
over to the core engine. An incoming message can either be a SOAP message or a
non-SOAP message (REST JSON or JMX). But at the transport level, it will be
converted into a SOAP message.
When Axis2 was designed, the following key rules were incorporated into the
architecture. These rules were mainly applied to achieve a highly fl exible and
extensible SOAP processing engine:
Separation of logic and state to provide a stateless processing mechanism.
(This is because Web Services are stateless.)
A single information model in order to enable the system to suspend and resume.
Ability to extend support to newer Web Service specifi cations with minimal
changes made to the core architecture.
The fi gure below shows all the key components in Axis2 architecture (including
core components as well as non-core components).
XML Processing Model:
Managing or processing the SOAP message is the most diffi cult part of the
execution of a message. The effi ciency of message processing is the single
most important factor that decides the performance of the entire system. Axis1
uses DOM as its message representation mechanism. However, Axis2 introduced a
fresh XML InfoSet-based representation for SOAP messages. It is known as AXIOM
(AXIs Object Model). AXIOM encapsulates the complexities of effi cient XML
processing within the implementation.
SOAP Processing Model:
This model involves the processing of an incoming SOAP message. The model defi
nes the different stages (phases) that the execution will walk through. The
user can then extend the processing model in specifi c places.
This keeps both static and dynamic states and has the logic to process them.
The information model consists of two hierarchies to keep static and run-time
information separate. Service life cycle and service session management are two
objectives in the information model.
The deployment model allows the user to easily deploy the services, confi gure
the transports, and extend the SOAP Processing Model. It also introduces newer
deployment mechanisms in order to handle hot deployment, hot updates, and
This provides a convenient API for users to interact with Web Services using
Axis2. The API consists of two sub-APIs, for average and advanced users. Axis2
default implementation supports all the eight MEPs (Message Exchange Patterns)
defi ned in WSDL 2.0. The API also allows easy extension to support custom
Transports: Axis2 defi nes a transport framework that allows
the user to use and expose the same service in multiple transports. The
transports fi t into specifi c places in the SOAP processing model. The
implementation, by default, provides a few common transports (HTTP, SMTP, JMX,
TCP and so on). However, the user can write or plug-in custom transports, if
XML Processing Model
As mentioned in Chapter 1, Axis2 is built on a completely new architecture as
compared to Axis 1.x. One of the key reasons for introducing Axis2 was to have
a better, and an effi cient XML processing model. Axis 1.x used DOM as its XML
representation mechanism, which required the complete object hierarchy
(corresponding to incoming message) to be kept in memory. This will not be a
problem for a message of small size. But when it comes to a message of large
size, it becomes an issue. To overcome this problem, Axis2 has introduced a new
AXIOM (AXIs Object Model) forms the basis of the XML representation for every
SOAP-based message in Axis2. The advantage of AXIOM over other XML InfoSet
representations is that it is based on the PULL parser technique, whereas most
others are based on the PUSH parser technique. The main advantage of PULL over
PUSH is that in the PULL technique, the invoker has full control over the
parser and it can request the next event and act upon that, whereas in case of
PUSH, the parser has limited control and delegates most of the functionality to
handlers that respond to the events that are fi red during its processing of
Since AXIOM is based on the PULL parser technique, it has 'on-demand-building'
capability whereby it will build an object model only if it is asked to do so.
If required, one can directly access the underlying PULL parser from AXIOM, and
use that rather than build an OM (Object Model).
SOAP Processing Model
Sending and receiving SOAP messages can be considered two of the key jobs of the
SOAP-processing engine. The architecture in Axis2 provides two Pipes ('Flows'),
in order to perform two basic actions. The AxisEngine or driver of Axis2 defi
nes two methods, send() and receive() to implement these two Pipes. The two
pipes are named InFlow and OutFlow. The complex Message Exchange Patterns
(MEPs) are constructed by combining these two types of pipes. It should be
noted that in addition to these two pipes there are two other pipes as well,
and those two help in handling incoming Fault messages and sending a Fault
Extensibility of the SOAP processing model is provided through handlers. When a
SOAP message is being processed, the handlers that are registered will be
executed. The handlers can be registered in global, service, or in operation
scopes, and the fi nal handler chain is calculated by combining the handlers
from all the scopes.
The handlers act as interceptors, and they process parts of the SOAP message and
provide the quality of service features (a good example of quality of service
is security or reliability). Usually handlers work on the SOAP headers; but
they may access or change the SOAP body as well.
The concept of a fl ow is very simple and it constitutes a series of phases
wherein a phase refers to a collection of handlers. Depending on the MEP for a
given method invocation, the number of fl ows associated with it may vary. In
the case of an in-only MEP, the corresponding method invocation has only one
pipe, that is, the message will only go through the in pipe (infl ow). On the
other hand, in the case of in-out MEP, the message will go through two pipes,
that is the in pipe (infl ow) and the out pipe (outfl ow). When a SOAP message
is being sent, an OutFlow begins. The OutFlow invokes the handlers and ends
with a Transport Sender that sends the SOAP message to the target endpoint. The
SOAP message is received by a Transport Receiver at the target endpoint, which
reads the SOAP message and starts the InFlow. The InFlow consists of handlers
and ends with the Message Receiver, which handles the actual business logic
A phase is a logical collection of one or more handlers, and sometimes a phase
itself acts as a handler. Axis2 introduced the phase concept as an easy way of
extending core functionalities. In Axis 1.x, we need to change the global confi
guration fi les if we want to add a handler into a handler chain. But Axis2
makes it easier by using the concept of phases and phase rules. Phase rules
specify how a given set of handlers, inside a particular phase, are ordered.
The figure below illustrates a flow and its phases.
If the message has gone through the execution chain without having any problem,
then the engine will hand over the message to the message receiver in order to
do the business logic invocation, After this, it is up to the message receiver
to invoke the service and send the response, if necessary. The figure below
shows how the Message Receiver fits into the execution chain.
The two pipes do not differentiate between the server and the client. The SOAP
processing model handles the complexity and provides two abstract pipes to the
user. The different areas or the stages of the pipes are named 'phases' in
A handler always runs inside a phase, and the phase provides a mechanism to
specify the ordering of handlers. Both pipes have built-in phases, and both
defi ne the areas for 'User Phases', which can be defi ned by the user, as
As shown in the fi gure below, the information model consists of two
hierarchies: "Description hierarchy" and "Context hierarchy". The Description
hierarchy represents the static data that may come from different deployment
descriptors. If hot deployment is turned off, then the description hierarchy is
not likely to change. If hot deployment is turned on, then we can deploy the
service while the system is up and running. In this case, the description
hierarchy is updated with the corresponding data of the service. The context
hierarchy keeps run-time data. Unlike the description hierarchy, the context
hierarchy keeps on changing when the server starts receiving messages.
These two hierarchies create a model that provides the ability to search for
key value pairs. When the values are to be searched for at a given level, they
are searched while moving up the hierarchy until a match is found. In the
resulting model, the lower levels override the values present in the upper
levels. For example, when a value has been searched for in the Message Context
and is not found, then it would be searched in the Operation Context, and so
on. The search is first done up the hierarchy, and if the starting point is a
Context then it would search for in the Description hierarchy as well.
This allows the user to declare and override values, with the result being a
very flexible configuration model. The flexibility could be the Achilles' heel
of the system, as the search is expensive, especially for something that does
The previous versions of Axis failed to address the usability factor involved in
the deployment of a Web Service. This was due to the fact that Axis 1.x was
released mainly to prove the Web Service concepts. Therefore in Axis 1.x, the
user has to manually invoke the admin client and update the server classpath.
Then, you need to restart the server in order to apply the changes. This
burdensome deployment model was a defi nite barrier for beginners. Axis2 is
engineered to overcome this drawback, and provide a fl exible, user-friendly,
easily confi gurable deployment model.
Axis2 deployment introduced a J2EE-like deployment mechanism, wherein the
developer can bundle all the class fi les, library fi les, resources fi les,
and confi guration fi les together as an archive fi le, and drop it in a
specifi ed location in the fi le system.
The concept of hot deployment and hot update is not a new technical paradigm,
particularly for the Web Service platform. But in the case of Apache Axis, it
is a new feature. Therefore, when Axis2 was developed, "hot" deployment
features were added to the feature list.
This refers to the capability to deploy services while the system is up and
running. In a real time system or in a business environment, the availability
of the system is very important. If the processing of the system is slow, even
for a moment, then the loss might be substantial and it may affect the
viability of the business. In the meanwhile, it is required to add new service
to the system. If this can be done without needing to shut down the servers, it
will be a great achievement. Axis2 addresses this issue and provides a Web
Service hot deployment ability, wherein we need not shut down the system to
deploy a new Web Service. All that needs to be done is to drop the required Web
Service archive into the services directory in the repository. The deployment
model will automatically deploy the service and make it available.
Hot update: This refers to the ability to make changes to an
existing Web Service without even shutting down the system. This is an
essential feature, which is best suited to use in a testing environment. It is
not advisable to use hot updates in a real-time system, because a hot update
could lead a system into an unknown state. Additionally, there is the
possibility of loosening the existing service data of that service. To prevent
this, Axis2 comes with the hot update parameter set to FALSE by default.
Nowadays, asynchronous or non-blocking Web Service invocation is a key
requirement in Web Services. There are currently two approaches to invoking a
Web Service in a non-blocking manner. The fi rst is the client programming
model, where a client invokes the service in a non-blocking manner. The second
way is the transport level non-blocking invocation where invocation occurs in
two transports (it could either be two single-channel transports like SMTP, or
two double-channel transports like HTTP). Axis2 client API supports both the
non-blocking invocation scenarios.
Axis2 introduces a very convenient client API for invoking services that
consists of two classes called "ServiceClient" and "OperationClient". The
ServiceClient API is intended for regular usage when you just require to send
and receive XML. On the other hand, the operation client is meant for advanced
usage, when there is a need to work with SOAP headers and some other advanced
tasks. With ServiceClient, we can only access the SOAP body or the payload.
Although we can add SOAP headers, we do not have any way to retrieve the SOAP
header by using the ServiceClient. We need to use an OperationClient for such a
ServiceClient has the following API for invoking a service:
The whole idea of this is to just send an XML request to the Web Service and
not care about its response. However, if something goes wrong, we require to
know that too, so this API invokes a service, where it does not have a return
value but would throw an exception.
This API is for just sending an XML request and not caring about either the
response, or any exception. Hence, this is useful in invoking an in-only MEP.
This invokes a service that has a return value. This is one of the most
commonly used APIs. Hence, this is used for invoking an in-out MEP.
SendReceiveNonBlocking: This invokes a service in a
non-blocking manner. This method can be used when the service has a return
value. In order to use this method, we have to pass a callback object, which is
called once the invocation is complete.
As mentioned earlier, the OperationClient class is for advanced users, and
working with OperationClient requires us to know Axis2 in depth. In
ServiceClient, we do not have to know anything about SOAP envelope, message
context, and so on. But when it comes to OperationClient, the users have to
create these by themselves, before invoking a service. Creating and invoking a
service using OperationClient involves the following steps:
Create a ServiceClient.
Then create OperationClient with the use of the ServiceClient that we have
Create SOAP envelop.
Create Message context.
Add the SOAP envelope to message context.
Add the messagecontext to OperationClient.
Then invoke the OperationClient.
If there is a response, then get the response message context from the
In Axis2, each and every transport consists of two parts, namely "Transport
Senders" and "Transport Receivers". We can defi ne transports along with
senders and receivers in Axis2 global confi guration. The Transport Receiver is
the one via which, the AxisEngine receives the message whereas the transport
sender is the one that sends out the message. One of the important aspects of
Axis2 is that its core is completely independent of the transport sender and
Axis2 is built to support the following transport protocols:
In HTTP transport, the transport listener is a servlet or org.
apache.axis2.transport.http.SimpleHTTPServer provided by Axis2. The transport
sender uses a common HTTP client for connection and sends the SOAP message.
This is the simplest transport and it needs WS-Addressing support in order to
This requires a single email account. The transport receiver is a thread that
checks for emails at fi xed time intervals.
This provides a way to invoke a Web Service using the JMS way.
XMPP: This provides a standard way to communicate with Jabber
server, and to invoke Web Services using XMPP protocol.
Axis2 provides a code generation tool that generates server-side (skeleton) and
client-side (stub or proxy) code along with descriptors and a test case. The
generated code simplifi es the service deployment and the service invocation.
This increases the usability of Axis2.
Pluggable Data Binding: The basic client API of Axis2 lets the
user process SOAP at the XML infoset level, whereas data binding extends it to
make it more convenient for the users by encapsulating the infoset layer and
providing a programming language-specifi c interface.
Although the basic objective of the code generation tools has not changed, the
code generation module of Axis2 has adopted a different approach. Primarily,
the change is in the use of templates, namely XSL templates, which gives fl
exibility to the code generator so as to generate code in multiple languages.
Databinding for Axis2 is implemented in an interesting manner. Databinding has
deliberately not been included in the core, and hence the code generation
allows different data binding frameworks to be plugged in. This is done through
an extension mechanism where the codegen engine calls the extensions fi rst,
and then executes the core emitter. The extensions plot a map of QNames versus
class names that is passed to the code generator wherein the emitter operates.
Axis2 supports the following data binding frameworks including its own data
binding framework called ADB:
ADB (Axis2 Data Binding) is a simple and lightweight framework that works off
StAX and is fairly performant.
XMLBeans is preferred if we want to use full schema support as XMLBeans claims
that it supports complete schema specifi cation.
JaxMe support has been added to XMLBeans, and it serves as another option for
JibX: This is the most recent addition to the family of data
Extensible Nature of Axis2
In Axis2, there are many ways to extend the functionalities. In this book, we
will be discussing a few of them, which are listed below:
Service extension of the module
Service Extension of the Module
Both Axis1 and Axis2 have the concept of handlers but when compared to Axis 1.x,
there are few changes in the way Axis2 specifi es and deploys handlers. In Axis
1.x, if you want to add a handler, then you need to change the global confi
guration fi le and then restart the system. In the meantime, it does not have a
way to add or change handlers dynamically.
To overcome the above problem as well as to add new features, Axis2 introduced
the concept of Web Service extensions or a modules, wherein the main purpose of
a module is to extend the core functionality. It is similar to adding handler
chains in Axis1.x. The advantage of Axis2 modules over Axis 1.x handler chains
is that we can add new modules without changing any global confi guration fi
A module is a self-contained package that includes handlers, third-party
libraries, module-related resources, and a module confi guration fi le.
A module can be deployed as an archive fi le. Axis2 came up with a new fi le
extension for modules, called ".mar". The most important fi le in a module
archive fi le is the module confi guration fi le or module.xml. A module will
not be functional unless it has a module.xml fi le. A module confi guration fi
le mainly specifi es handlers and their phase rules. So once we engage a
module, depending on the phase rule, the handlers will be placed in different
fl ows (infl ow, outfl ow, and so on).
The idea of modules is very simple. To implement support for WS-Addressing or
WS-Security in our services, we need to download the corresponding modules and
drop them into the modules directory of the Axis2 repository. We can engage the
module at deployment time by adding
to axis2. xml (global confi guration fi le). In
addition to that, if we want to engage a module at run time, we can do that in
many ways such as by using Axis2 web admin, handlers, and so on.
We can deploy a service in many ways. We could deploy a service as an archive fi
le (Axis2 default), by creating a service using a database, or by creating a
Web Service using a text fi le. The idea of custom deployers is to open avenues
to support any kind of deployment mechanisms. Axis2 has in-built support for:
Archive-based deployment (.aar and .mar concept)
POJO deployment (.class or .jar)
But if someone wants to deploy a service, or a module, then he or she can
achieve that goal with the use of custom deployers.
As we have discussed, the Axis2 execution chain is a collection of phases
wherein each phase is a logical group of handlers. The Message Receiver, in
itself, is a handler. However, it is different from other handlers because
Axis2 treats the Message Receiever in a different manner. If the message has
gone through the infl ow with no issues, or in other words, no exceptions have
occurred in the middle of the chain, then the engine hands over the message to
the message receiver so as to invoke the associated business logic.
Message receivers interact directly with both the actual service implementation
class and the AxisEngine. However, there can be some instances wherein there
are no service implementation classes and all the logic is handed inside the
Message Receiver. The message receiver is the last component in the infl ow
process. Axis2 has got nothing to do with it once the message is handled over
to the message receiver.