Apache Axis2 Architecture Guide

Apache Axis2 Architecture Guide

This document gives an introduction to Axis2's modulararchitecture with explanations on every module.

Contents

• The Big Picture

• Requirement of Axis2

• Axis2 Architecture

  • Core Modules

  • Other Modules

  • Information Model

  • XML Processing Model

  • SOAP Processing Model

    • Axis2 Default Processing Model

    • Processing an Incoming SOAPMessage

    • Processing of the Outgoing Message

    • Extending the SOAP Processing Model

      • Extending the SOAP ProcessingModel with Handlers

      • Extending the SOAP ProcessingModel with Modules

  • Deployment
    • The axis2.xml file

    • Service Archive

    • Module Archive

  • Client API

    • One Way Messaging Support

    • Request Response MessagingSupport

  • Transports

  • Code Generation

  • Data Binding
    • Integration with Code GenerationEngine

    • Serialization and De-Serialization

The Big Picture

A new architecture for Axis was introduced during the August2004 Summit in Colombo, Sri Lanka. This new architecture on whichAxis2 is based is more flexible, efficient, and configurable incomparison to Axis1.xarchitecture. Some well established concepts from Axis 1.x,like handlers etc., have been preserved in this newarchitecture.

Any architecture is a result of what that architecture shouldyield. The success of an architecture should be evaluated based onthe requirements expected to be met by that architecture. Let usstart our journey into Axis2 by looking at the requirements.

Requirement of Axis2

In SOAP terminology, a participant who is taking part in a Webservice interaction is known as a SOAP Node. Delivery of a singleSOAP Message is defined based on two participants, SOAP Sender andSOAP Receiver. Each SOAP message is sent by a SOAP Sender andreceived by a SOAP Receiver. A single SOAP delivery is the mostbasic unit that builds the Web service interaction.

Each SOAP Node may be written in specific programming language,may it be Java, C++, .NET or Perl, but the Web services allow themto interoperate. This is possible because on the wire each Webservice interaction is done via SOAP, which is common to every SOAPNode.

Web service middleware handles the complexity in SOAP messagingand lets the users work with the programming language they areaccustomed to. Axis2 allows Java users to invoke Web services usingJava representations, and handles the SOAP messaging behind thecurtain.

Axis2 handles SOAP processing along with numerous other tasks.This makes life of a Web service developer a whole lot easier.Following are the identified requirements:

1. Provide a framework to process the SOAP messages. The frameworkshould be extensible and the users should be able to extend theSOAP processing per service or per operation basis. Furthermore, itshould be able to model different Message Exchange Patterns (MEPs)using the processing framework.
2. Ability to deploy a Web service (with or without WSDL)
3. Provide a Client API that can be used to invoke Web services.This API should support both the Synchronous and Asynchronousprogramming models.
4. Ability to configure Axis2 and its components throughdeployment.
5. Ability to send and receive SOAP messages with differenttransports.

Apart from the above functionalities, performance in terms ofmemory and speed is a major consideration for Axis2. Axis2 CoreArchitecture is built on three specifications- WSDL, SOAP and WS-Addressing.Other specifications like JAX-RPC, SAAJ andWS-Policy arelayered on top of the Core Architecture.

Axis2 Architecture

Axis2 architecture lays out some principals to preserve theuniformity. They are as follows:

• Axis2 architecture separates the logic and the states. Code thatdoes the processing does not have a state inside Axis2. This allowscode to be executed freely by parallel threads.

• All the information is kept in one information model, allowingthe system to be suspended and resumed.

Axis2 architecture is modular. Therefore, Axis2 Framework isbuilt up of core modules that collectively make up the corearchitecture of Axis2. Non-core/other modules are layered on top ofthese core modules.

Core Modules:

• Information Model - Axis2 defines amodel to handle information and all states are kept in this model.The model consists of a hierarchy of information. The systemmanages the life cycle of the objects in this hierarchy.

• XML processing Model - Handling the SOAPMessage is the most important and most complex task. The efficiencyof this is the single most important factor that decides theperformance. It makes sense to delegate this task to a separatesub-project under the Web services project, allowing thatsub-project (AXIOM or AXisObject Model) to provide a simple API for SOAP and XML info-set. Ithides the complexities of efficient XML processing within itsimplementation.

• SOAP Processing Model - This controlsthe execution of the processing. The model defines different phasesthe execution would walk through, and the user can extend theProcessing Model at specific places.

• Deployment Model - The Axis2deployment model allows the user to deploy services, configure thetransports, and extend the SOAP Processing model per system,service, or operation basis.

• Client API - This provides aconvenient API for users to communicate with Web services usingAxis2. There are a set of classes to interact with IN-OUT andIN-Only style Message ExchangePatterns (MEPs), where they can be used to construct any otherMEP. (Please note that even if the client API has in-built supportfor the above named MEPs, it does not by any means limit Axis2'sflexibility to support custom MEPs.)

• Transports - Axis2 defines atransport framework that enables the user to use multiple differenttransports. The transports fit into specific places in the SOAPprocessing model. The implementation provides a few commontransports and the user can write or plug-in new ones if and whenit is needed.

Other Modules:

• Code Generation - Axis2 provides a codegeneration tool that generates server side and client side codealong with descriptors and a test case. The generated codesimplifies the service deployment and the service invocation,increasing the usability of Axis2.

• Data Binding - The basic client API of Axis2lets the users process SOAP at the infoset level, whereas databinding extends it to make it more convenient to users byencapsulating the infoset layer and providing a programminglanguage specific interface.

Information Model

The Information Model has two main hierarchies--Contexts andDescriptions. This model is described in UML notations below.

( A ----<> B says, B has 1 or more objects of A.A------>B says, the given relationship holds between A andB.)

The two hierarchies are connected as shown in the above figure.The Description hierarchy represents the static data. This data maybe loaded from a configuration file that exists throughout thelifetime of Axis2. For example, deployed Web services, operations,etc. On the other hand, the context hierarchy holds more dynamicinformation about objects that can have more than one instance(e.g., Message Contexts).

These two hierarchies create a model that provides the abilityto search for key-value pairs. When the values are searched at agiven level, they are searched while moving up the hierarchy untila match is found. In the resulting model, the lower levels overridethe values in the upper levels. For example, when a value is lookedup in the Message Context and is not found, it would be looked upin the Operation Context, etc, up the hierarchy. The Search isfirst done up the hierarchy, and if the starting point is a Contextthen it searches in the Description hierarchy as well.

This allows the user to declare and override values, with theresult being a very flexible configuration model. This flexibilitycould be the Achilles heel for the system, however, assearches are expensive, especially for parameters that turn out notto exist. Yet in the final analysis, the Axis Team believes thatthis flexibility serves developers better overall.

Context	Description	Configuration	Description
Configuration Context	Holds the Axis2's run time status. A deep copy of this wouldessentially make a copy of Axis2.	Axis Configuration	Holds all global configurations: transports, global modules,parameters, services, etc.
Service Group Context	Holds information about a particular usage of the respectiveservice group. The life of a Service Group Context starts when auser starts interacting with a service that belongs to this servicegroup. This can be used to share information between services(within the same service group) in a single interaction.	AxisServiceGroup	Holds deployment time information about a particular servicegroup.
Service Context	This context is available throughout the usage of the respectiveservice. This can be used to share information between several MEPsof the same service, within a single interaction. The life cycledepends on the scope of the service.	AxisService	Holds the Operations and the service level configurations
Operation Context	Holds the information about the current MEP instance, maintainsthe messages in the current MEP etc.	AxisOperation	Holds the operation level configurations
Message Context	Holds all the information about the message currently beingexecuted.	AxisMessage	Holds message level static information like the schema of theparticular message.

XML Processing Model

As mentioned above, the XML processing model of Axis2 has becomea separate sub-project, called Apache Axiom,in the Apache Web services project. Please refer to the OM Tutorial for more information.

SOAP Processing Model

The architecture identified two basic actions a SOAP processorshould perform, sending and receiving SOAP messages. Thearchitecture provides two pipes (or flows) to perform these twobasic actions. The Axis Engine or the driver of Axis2 defines twomethods, send() and receive(), to implement these two pipes. Thetwo pipes are named In Pipe and OutPipe, and complex Message Exchange Patterns (MEPs) areconstructed by combining these two pipes.

Extensibility of the SOAP processing model is provided throughhandlers. When a SOAP message is being processed, the handlers thatare registered will be executed. The handlers can be registered inglobal, service, or operation scope and the final handler chain iscalculated combining the handlers from all the scopes.

The handlers act as interceptors and they process parts of theSOAP message and provide add-on services. Usually handlers work onthe SOAP headers, yet they may access or change the SOAP body aswell.

When a SOAP message is being sent through the Client API, anOut Pipe activates. The Out Pipe will invoke thehandlers and end with a Transport Sender that sends the SOAPmessage to the target endpoint. The SOAP message is received by aTransport Receiver at the target endpoint, which reads the SOAPmessage and starts the In Pipe. The In Pipeconsists of handlers and ends with the MessageReceiver, which consumes the SOAP message.

The processing explained above happens for each and every SOAPmessage that is exchanged. After processing one message, Axis2 maydecide to create other SOAP messages, in which case more complexmessage patterns emerge. However, Axis2 always views the SOAPmessage in terms of processing a single message. The combination ofthe messages are layered on top of that basic framework.

The two pipes do not differentiate between the Server and theClient. The SOAP Processing Model handles the complexity andprovides two abstract pipes to the user. The different areas or thestages of the pipes are called 'phases' within Axis2. A Handleralways runs inside a specific phase, and the phase provides amechanism to specify the ordering of handlers. Both Pipes havebuilt-in phases, and both define the areas for 'User Phases' whichcan be defined by the user.

Axis2 Default Processing Model

Axis2 has some inbuilt handlers that run in inbuilt phases andthey create the default configuration for Axis2. We will be lookingmore in to how to extend the default processing Model in the nextsection.

There are three special handlers defined in Axis2.

1. Dispatchers - Finds the service and the operation the SOAPmessage is directed to. Dispatchers always run on theIn-Pipe and inside the Dispatch phase. The in-builtdispatchers dispatch to a particular operation depending on variousconditions like WS-Addressing information, URI information, SOAPaction information, etc. ( See more information on Dispatching)

• Message Receiver - Consumes the SOAPmessage and hands it over to the application. The message receiveris the last handler of the in-pipe

• Transport Sender - Sends the SOAP message to the SOAP endpointthe message is destined to. Always runs as the last handler in theout-pipe

Processing an Incoming SOAP Message

An incoming SOAP message is always received by a TransportReceiver waiting for the SOAP messages. Once the SOAP messagearrives, the transport Headers are parsed and a Message Context is created from the incomingSOAP message. This message context encapsulates all theinformation, including the SOAP message itself, transport headers,etc., inside it. Then the In Pipe is executed with theMessage Context.

Let us see what happens at each phase of the execution. Thisprocess can happen in the server or in the client.

1. Transport Phase - The handlers are in thephase that processes transport specific information such asvalidating incoming messages by looking at various transportheaders, adding data into message contexts, etc.
2. Pre-Dispatch Phase- The main functionality ofthe handlers in this phase is to populate message context to do thedispatching. For example, processing of addressing headers of theSOAP message, if any, happens in this phase. Addressing handlersextract information and put them in to the message context.
3. Dispatch Phase - The Dispatchers run in thisphase and try to find the correct service and operation thisparticular message is destined for.
   The post condition of the dispatch phase (any phase can contain apost condition) checks whether a service and an operation werefound by the dispatchers. If not, the execution will halt andreturn a "service not found' error.
4. User Defined Phases - Users can engage theircustom handlers here.
5. Message Validation Phase - Once the user levelexecution has taken place, this phase validates whether SOAPMessage Processing has taken place correctly.
6. Message Processing Phase - The Business logicof the SOAP message is executed here. A MessageReceiver is registered with each Operation. This messagereceiver (associated to the particular operation) will be executedas the last handler of this phase.

There may be other handlers in any of these phases. Users mayuse custom handlers to override the processing logic in each ofthese phases.

Processing of the Outgoing Message

The Out Pipe is simpler because the service and theoperation to dispatch are known by the time the pipe is executed.The Out Pipe may be initiated by the

Message Receiver or the Client APIimplementation. Phases of the Out Pipe are describedbelow:

1. Message Initialize Phase - First phase of theOut Pipe. Serves as the placeholder for the customhandlers.
2. User Phases - Executes handlers inuser-defined phases.
3. Transports Phase - Executes any transporthandlers taken from the associated transport configuration. Thelast handler would be a transport sender which will send the SOAPmessage to the target endpoint.

Extending the SOAP Processing Model

Above, we discussed the default processing model of Axis2. Nowlet us discuss the extension mechanism for the SOAP processingmodel. After all, the whole effort of making this SOAPengine/processing model was focused on making it extendable.

The idea behind introducing step-wise processing of the SOAPmessage in terms of handlers and phases is to allow easiermodification of the processing order. The notion of phases makes iteasier to place handlers in between other handlers. This enablesmodification of the default processing behavior. The SOAPProcessing Model can be extended with handlers or modules.

Extending the SOAP Processing Model with Handlers

The handlers in a module can specify the phase they need to beplaced in. Furthermore, they can specify their location inside aphase by providing phase rules. Phase rules will place ahandler,

1. as the first handler in a phase,
2. as the last handler in a phase,
3. before a given handler,
4. or after a given handler.

Extending the SOAP Processing Model with Modules

Axis2 defines an entity called a 'module' that can introducehandlers and Web service operations. A Module in terms of Axis2usually acts as a convenient packaging that includes:

• A set of handlers and
• An associated descriptor which includes the phase rules

Modules have the concept of being 'available' and 'engaged'.'Availability' means the module is present in the system, but hasnot been activated, i.e., the handlers included inside the modulehave not been used in the processing mechanism. When a module is'engaged' it becomes active and the handlers get placed in theproper phases. The handlers will act in the same way as explainedin the previous section. Usually a module will be used to implementa WS-* functionality such as WS-Addressing.

Apart from the extension mechanism based on the handlers, theWS-* specifications may suggest a requirement for adding newoperations. For example, once a user adds Reliable Messagingcapability to a service, the "Create Sequence" operation needs tobe available to the service endpoint. This can be implemented byletting the modules define the operations. Once the module isengaged to a service, the necessary operations will be added tothat service.

A service, operation, or the system may engage a module. Oncethe module is engaged, the handlers and the operations defined inthe module are added to the entity that engaged them.

Modules cannot be added (no hot deployment) while the Axis2engine is running, but they will be available once the system isrestarted.

Deployment

The Deployment Model provides a concrete mechanism to configureAxis2. This model has three entities that provide theconfiguration.

The axis2.xml file

This file holds the global configuration for the client andserver, and provides the following information:

1. The global parameters
2. Registered transport-in and transport-outs
3. User-defined phase names
4. Modules that are engaged globally (to all services)
5. Globally defined Message Receivers

Service Archive

The Service archive must have a META-INF/services.xml file and maycontain the dependent classes. Please see modules/kernel/resources/services.xsd in the source distribution for the schema for services.xml. The services.xml file hasthe following information.

1. Service level parameters
2. Modules that are engaged at service level
3. Service Specific Message Receivers
4. Operations inside the service

Module Archive

Module archive must have a META-INF/module.xml file and dependentclasses. The module.xml file has Module parameters and theOperations defined in the module.

When the system starts up, Axis2 prompts the deployment model tocreate an Axis Configuration. The deployment model first finds theaxis2.xml file and builds the global configuration. Then it checksfor the module archives and then for the service archives. Afterthat, the corresponding services and modules are added to the AxisConfiguration. The system will build contexts on top of the AxisConfiguration. After this, Axis2 is ready to send or receive SOAPmessages. Hot deployment is only allowed for services.

Client API

There are three parameters that decide the nature of the Webservice interaction.

1. Message Exchange Pattern (MEP)
2. The behavior of the transport, whether it's One-Way orTwo-Way
3. Synchronous/Asynchronous behavior of the Client API

Variations of the three parameters can result in an indefinitenumber of scenarios. Even though Axis2 is built on a core thatsupports any messaging interaction, the developers were compelledto provide built-in support for only the two most widely usedMessage Exchange Patterns (MEPs).

The two supported MEPs are One-Way and the In-Out(Request-Response) scenarios in the Client API. The implementationis based on a class called ServiceClient and there areextensions for each MEP that Axis2 Client API supports.

One Way Messaging Support

The One-Way support is provided by thefireAndForget method of ServiceClient.For one way invocations, one can use HTTP, SMTP and TCP transports.In the case of the HTTP transport, the return channel is not used,and the HTTP 202 OK is returned in the return channel.

In-Out (Request Response) Messaging Support

The In-Out support is provided by the sendReceive()method in ServiceClient. This provides a simpler interface for theuser. The Client API has four ways to configure a given messageexchange

1. Blocking or Non-Blocking nature - this can be decided by usingsendReceive() or sendReceiveNonBlocking()methods
2. Sender transport - transport that sends the SOAP message
3. Listener transport - transport that receives the response
4. Use Separate Channel - determines whether the response is sentover a separate transport connection or not. This can be false onlywhen the sender and listener transport is same and is a Two-Waytransport.

Depending on the values of the above four parameters, Axis2behaves differently.

Transports

Axis2 has two basic constructs for transports, namely: TransportSenders and Transport Receivers. These are accessed via theAxisConfiguration.

The incoming transport is the transport via which the AxisEnginereceives the message. The outgoing transport is decided based onthe addressing information (wsa:ReplyTo and wsa:FaultTo). Ifaddressing information is not available and if the server is tryingto respond, then the out going transport will be the output streamof the incoming transport (if it is two-way transport).

At the client side, the user is free to specify the transport tobe used.

Transport Senders and Transport Receivers contain the followinginformation.

1. Transport Sender for Out Configuration
2. Transport Listener for In Configuration
3. Parameters of the transport

Each and every transport out configuration defines a transportsender. The transport sender sends the SOAP message depending onits configuration.

The transport receiver waits for the SOAP messages, and for eachSOAP message that arrives, it uses the In Pipe to processthe SOAP message.

Axis2 presently supports the following transports:

1. HTTP - In HTTP transport, the transport listener is a servletor org.apache.axis2.transport.http.SimpleHTTPServer provided byAxis2. The transport sender uses commons-httpclient to connect andsend the SOAP message.
2. Local - This transport can be used for in-VM communication.
3. Transports for TCP, SMTP, JMS and other protocols are availablefrom the WS-Commons Transportproject.

Code Generation

Although the basic objective of the code generation tools hasnot changed, the code generation module of Axis2 has taken adifferent approach to generate code. Primarily, the change is inthe use of templates, namely XSL templates, which gives the codegenerator the flexibility to generate code in multiplelanguages.

The basic approach is to set the code generator to generate anXML, and parse it with a template to generate the code file. Thefollowing figure describes how this shows up in the architecture ofthe tool.

The fact here is that it is the same information that isextracted from the WSDL no matter what output code is generated.First, an AxisService is populated from a WSDL. Then the codegenerator extracts information from the AxisService and creates anXML, which is language independent. This emitted XML is then parsedwith the relevant XSL to generate code in the desired outputlanguage. No matter what the output language is, the process is thesame except for the XSL template that is used.

Data Binding

Integration with the Code Generation Engine

Databinding for Axis2 is implemented in an interesting manner.Databinding has not been included in the core deliberately, andhence the code generation allows different data binding frameworksto be plugged in. This is done through an extension mechanism wherethe codegen engine first calls the extensions and then executes thecore emitter. The extensions populate a map of QNames vs. classnames that is passed to the code generator on which the emitteroperates on.

The following diagram shows the structure:

The following databinding extensions areavailable:

1. ADB - ADB (Axis Data Binding ) is a simpleframework that allows simple schemas to be compiled. It islightweight and simple, works off StAX and fairly performant.However, it does not support the complete set of schema constructsand is likely to complain for certain schemas!
2. XMLBeans - XMLbeans claims that it supportsthe complete schema specification, and it is preferred if fullschema support is needed!
3. JAXB-RI - JAXB2 support has been added in asimilar manner to XMLbeans and serves as another option for theuser
4. JibX - This is the most recent addition to thefamily of databinding extensions, and it is also another optionusers have for data binding.

Serialization and De-Serialization of Data bound classes

AXIOM is based on the StAX API (Streaming API for XML).Xml-beans also supports this API. Data binding in Axis2 is achievedthrough interfacing the AXIOM with the Xml-beans using the StAXAPI. At the time of code generation, there will be utility methodsgenerated inside the stub (or the message receiver) that cande-serialize from AXIOM to a data bound object and serialize from adata bound object to AXIOM. For example, if the WSDL has anoperation called "echoString", once the code is generated, thefollowing methods will be generated inside the relevantclasses.

public static
org.apache.axiom.om.OMElement toOM(org.soapinterop.xsd.EchoStringParamDocument
param)// This method will handle the serialization.

public static org.apache.xmlbeans.XmlObject
fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This
method will handle the de-serialization.