| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=windows-1252"> |
| <title>Axis2 Architecture Guide</title> |
| <meta name="CREATED" content="20050916;22455288"> |
| <meta name="CHANGEDBY" content="Chamikara Jayalath"> |
| <meta name="CHANGED" content="20050918;22493797"> |
| </head> |
| |
| <body lang="en-US" dir="ltr"> |
| <h1>Axis2 Architecture Guide</h1> |
| |
| <h2>Contents</h2> |
| <ul> |
| <li><p><a href="#bmBP">The Big Picture</a></p> |
| </li> |
| <li><p><a href="#bmInfoMod">Information Model</a></p> |
| </li> |
| <li><p><a href="#bmXML">XML Processing Model</a></p> |
| </li> |
| <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p> |
| </li> |
| <li><p><a href="#bmDeployment">Deployment</a></p> |
| </li> |
| <li><p><a href="#bmWSDL">WSDL and code generation</a></p> |
| </li> |
| <li><p><a href="#bmDB">Data Binding</a></p> |
| </li> |
| <li><p><a href="#bmClientAPI">Client API</a></p> |
| </li> |
| <li><p><a href="#bmTransports">Transports</a></p> |
| </li> |
| </ul> |
| |
| <p><br> |
| <br> |
| </p> |
| |
| <h2><a name="bmBP"></a>The Big Picture</h2> |
| |
| <p>Any architecture is a result of what that architecture should yield, the |
| success of an architecture should be evaluated bases on the requirements the |
| architecture should meet. Let us start our journey in to Axis2 looking at the |
| requirements that are expected from Axis2.</p> |
| |
| <h3>Requirement of Axis2</h3> |
| |
| <p>In the SOAP terminology, a participant who is taking part in a Web Service |
| interaction is known as a SOAP Node. Delivery of a single SOAP Message is |
| defined based on two participants, SOAP Sender and SOAP Receiver. Each SOAP |
| Message is sent by SOAP Sender and received by SOAP Receiver, and single SOAP |
| delivery is the most basic unit that builds the Web Service interactions.</p> |
| |
| <p>Each SOAP Node may be written in specific programming language, may it be |
| Java, C++, .NET or Perl, the Web Services allow them to inter operate. This |
| is possible because at the wire each Web Service interaction is done via |
| SOAP, which is common to every SOAP Node.</p> |
| |
| <p><img src="images/archi-guide/soap.gif" name="Graphic1" align="bottom" |
| width="691" height="319" border="0"></p> |
| |
| <p>Web Service middleware handles the complexity SOAP messaging and let the |
| users to work with the programming language they are accustomed to. Axis2 |
| allows the java users to invoke the Web Services using java representations |
| and handles the SOAP messaging behind the curtain.</p> |
| |
| <p>Axis2 handles SOAP processing, along with numerous other functionalities |
| that make the life of the Web Service developer convenient. Following are the |
| identified requirements:</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Provide a framework to process the SOAP |
| messages, the framework should be extensible and the users should be able |
| to extend the SOAP processing per service or operation basis. Furthermore |
| it should be able to model different Message Exchange Patterns using the |
| processing framework.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Ability to deploy the Web Services (with |
| or without WSDL)</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Provide a Client API that can be used to |
| invoke Web Services, the API should supports both the Synchronous and |
| Asynchronous programming models.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Ability to configure Axis2 and it's |
| components via the deployment</p> |
| </li> |
| <li><p>Ability to send and receive SOAP messages with different |
| transports</p> |
| </li> |
| </ol> |
| |
| <p>Apart from the above functionalities, performance, both in the terms of |
| memory and speed, is a major consideration for Axis2. Axis2 Core Architecture |
| is built on three specifications, WSDL, SOAP and WS-Addressing. Other |
| specifications like JAX-RPC and SAAJ are layered on top of the Core |
| Architecture. The WS-Policy might join the core specifications in the near |
| future.</p> |
| |
| <h3>Axis2, the Architecture</h3> |
| |
| <p>Now having look at the requirements of the Axis2 we can direct our |
| attention to the Architecture.</p> |
| |
| <p>Axis2 architecture lay out few Principals to preserve the uniformity of |
| the architecture, they are as follows.</p> |
| <ul> |
| <li><p style="margin-bottom: 0in">Axis2 Architecture separates the logic |
| and the states, the code that process the logic is usually stateless. |
| This allows the code to be executed freely by parallel threads.</p> |
| </li> |
| <li><p>All the information is kept in a one Information model, this allows |
| the system to be stored and resumed</p> |
| </li> |
| </ul> |
| |
| <p>Axis2 architecture is modular, the architecture broke the Axis2 in to |
| Seven modules.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Information Model</p> |
| </li> |
| <li><p style="margin-bottom: 0in">XML processing Model</p> |
| </li> |
| <li><p style="margin-bottom: 0in">SOAP Processing Model</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Deployment</p> |
| </li> |
| <li><p style="margin-bottom: 0in">WSDL and Code Generation</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Client API</p> |
| </li> |
| <li><p>Transports</p> |
| </li> |
| </ol> |
| |
| <p><img src="images/archi-guide/all.png" name="Graphic2" align="bottom" |
| width="426" height="189" border="0"></p> |
| |
| <p>Let us look in to the rationale for each Module, and what each does?</p> |
| |
| <p>Axis2 defines a model to handle the information and all the states are |
| kept in this model. The model has a hierarchy for the information and the |
| system manages the life cycle of the objects in this hierarchy.</p> |
| |
| <p>Handling the SOAP Message is the most important and the most complex task, |
| the efficiency of this is the single most important factor that decides the |
| performance. It make sense to delegate this task to a separate module, and |
| that module, AXIOM provide a simple API for SOAP and XML info-set and while |
| hiding the complexities of the efficient XML processing with in the |
| implementation.</p> |
| |
| <p>SOAP Processing Model controls the execution of the processing, the Model |
| defines different phases the execution would walk though, and the user can |
| extend the Processing Model at some specific places.</p> |
| |
| <p>Axis2 define a transport framework that enables user to use different |
| transports, the transports match in to the specific places in the SOAP |
| processing model. The implementation provide few common transports and user |
| may write new ones if he wishes.</p> |
| |
| <p>Axis2 deployment model allows the user to deploy services, configure the |
| transports, extend the SOAP Processing model per system basis, per service |
| basis, and per operation basis.</p> |
| |
| <p>Finally Axis2 provides a code generation tool that will generate server |
| side and client side code along a test case. The generated code would |
| simplify the service deployment and the service invocation. This would make |
| the Axis2 easier to use.</p> |
| |
| <h2><a name="bmInfoMod"></a>Information Model</h2> |
| |
| <p>Information Model has two main hierarchies, the Contexts and |
| Descriptions.</p> |
| |
| <p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom" |
| width="400" height="443" border="0"></p> |
| |
| <p>This uses UML notations ( A ----<> B means B has 1 or more objects |
| of A. A------>B means the given relationship holds between A and B.)</p> |
| |
| <p>The two hierarchies are connected as shown in the above figure. The |
| Description hierarchy represents data that exists throughout the lifetime of |
| Axis2. Examples for such data would be deployed Web Services, operations, |
| etc. On the other hand, the context hierarchy holds more dynamic information |
| about things that has more than one instances (e.g.Message Context).</p> |
| |
| <p>These two hierarchies created a model that provides the ability to search |
| for key value pairs, when the values are searched at a given level, they are |
| searched while moving up in the level until a match is found. In the |
| resulting model the lower levels overrides the values in the upper levels. |
| For and example when a value is looked up at the Message Context and it is |
| not found, it would be looked up at the Operation Context etc, up the |
| hierarchy. The Search is first done up the hierarchy, and if starting point |
| is a Context then it is search in the Description hierarchy as well.</p> |
| |
| <p>This allows user to declare and override values, and result in very |
| flexible configuration model. The flexibility could be the Achilles heel for |
| the system, as the search, specially for something that does not exist is |
| expensive, yet in the final analysis developers believe that the flexibility |
| would serve better in this instants and opt for the flexibility.</p> |
| |
| <table width="955" border="1" cellpadding="2" cellspacing="3"> |
| <col width="112"><col width="371"><col width="103"><col width="336"><tbody> |
| <tr> |
| <td width="112"><p>Configuration Context</p> |
| </td> |
| <td width="371"><p>Holds the current state of execution. A deep copy of |
| this would essentially make a copy of Axis2.</p> |
| </td> |
| <td width="103"><p>Axis Configuration</p> |
| </td> |
| <td width="336"><p>Holds all global configurations. Transports, global |
| modules, parameters and Services.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><p>Service Group Context</p> |
| </td> |
| <td width="371"><p>Holds information about a perticular usage of the |
| respective service group. The life of a Service Group Context start |
| when a user start to interact with a service that belong to this |
| service group. This can be used to share information between service |
| usages in a single interaction, for services that belong to the same |
| group.</p> |
| </td> |
| <td width="103"><p>ServiceGroup Description</p> |
| </td> |
| <td width="336"><p>Holds deployment time information about a perticular |
| service group.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><p>Service Context</p> |
| </td> |
| <td width="371"><p>This context is avaliable throughout a usage of the |
| respective service. This can be used to share information between |
| several MAPs that belong to the same service, within a single |
| interaction.</p> |
| </td> |
| <td width="103"><p>Service Description</p> |
| </td> |
| <td width="336"><p>Hold the Operations and the service level |
| configurations</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><p>Operation Context</p> |
| </td> |
| <td width="371"><p>Holds the information about the current MEP |
| instance, maintain the Messages in the current MEP etc.</p> |
| </td> |
| <td width="103"><p>Operation Description</p> |
| </td> |
| <td width="336"><p>Holds the operation level configurations</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><p><a name="messageContext"></a>Message Context</p> |
| </td> |
| <td width="371"><p>Holds all the information about the Message |
| currently being executed.</p> |
| </td> |
| <td width="103"><p>Message Description</p> |
| </td> |
| <td width="336"><p>Do not hold any information as yet, but can be used |
| as future extension point.</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p><br> |
| <br> |
| </p> |
| |
| <p>All context classes implement readObject, writeObject methods that allows |
| to serialize and de-serialize them correctly. Serializing the current |
| Configuration Context object would essentially serialize the whole context |
| hierarchy. To restore it, the user has to fist perform the de-serialization |
| of the ConfigurationContext object. He can restore the description hierarchy |
| by calling the init (axisConfiguration) method of the de-serialized |
| ConfigurationContext object.</p> |
| |
| <h2><a name="bmXML"></a>XML Processing Model</h2> |
| |
| <p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p> |
| |
| <h2><a name="bmSOAPPM"></a>SOAP Processing Model</h2> |
| |
| <p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" |
| align="bottom" width="755" height="348" border="0"></p> |
| |
| <p>The architecture identified two basic actions a SOAP processor should |
| perform, sending and receiving SOAP messages. The architecture provides two |
| Pipes (also named 'Flows'), to perform these two basic actions. Axis Engine |
| or the driver of Axis2 defines two methods send() and receive() to implement |
| these two Pipes. The two pipes are named <i>In Pipe</i> and <i>Out Pipe</i>, |
| the complex Message Exchange Patterns are constructed by combining these two |
| pipes.</p> |
| |
| <p>Extensibility of the SOAP processing model is provided through the |
| Handlers. When a SOAP message is being processed the Handlers that are |
| registered would be executed. The Handlers can be registered in global, |
| service, or operation scopes and the final handler chain is calculated |
| combining the Handlers from all the scopes.</p> |
| |
| <p>The Handlers act as interceptors and they process the parts of the SOAP |
| message and provide add on services. Usually Handlers work on the SOAP |
| Headers yet they may access or change the SOAP Body as well.</p> |
| |
| <p>When a SOAP message is send from the Client API, a <i>Out Pipe</i> would |
| begin, the <i>Out Pipe</i> 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 <i>In Pipe</i>. The In Pipe consists of Handlers |
| and ends with a <a href="#mr">Message Receiver</a>, which consumes the SOAP |
| message.</p> |
| |
| <p>Above explained processing happens for each and every SOAP message |
| exchanged. Processing that follows may decide to give birth for the other |
| SOAP messages, in which case the more complex patterns emerge. But Axis2 |
| always view the SOAP message in terms of processing of a single message where |
| as the combination of the messages are layered on top of that basic |
| framework.</p> |
| |
| <p>The two pipes does not differentiate between the Server and the Client, |
| the SOAP Processing Model handles the complexity and provides two abstract |
| pipes to the user. Each pipe is a set of Handlers, the different areas of the |
| pipes are given names, and according to the Axis2 slang those are named |
| 'Phases'. A Handler always runs inside a Phase, and the Phase provides a |
| mechanism to specify the ordering of Handlers. Both Pipes has built in |
| Phases, and both define the areas for 'User Phases' which can be defined by |
| the user.</p> |
| |
| <p>Following figure shows the two pipes with their pre-defined Phases, the |
| user defined Phases would be fit in to the User Phases.</p> |
| |
| <p><img src="images/archi-guide/phases.png" name="Graphic5" align="bottom" |
| width="525" height="226" border="0"></p> |
| |
| <h3>Axis2 Default Processing Model</h3> |
| |
| <p>Axis2 has the, some inbuilt Handlers that run in inbuilt Phases and they |
| create the default configuration for the Axis2, we will be looking more in to |
| how to extend the default processing Model in the next section.</p> |
| |
| <p>There are four special handlers defined in Axis2.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Dispatchers - Find the Service the SOAP |
| message is directed to, always run on the In-Pipe and inside the Dispatch |
| Phase. There is a inbuilt Dispatcher, that run in any case and user may |
| override it by placing the dispatchers before the inbuilt Dispatcher.</p> |
| </li> |
| <li><p style="margin-bottom: 0in"><a name="mr"></a>Message Receiver - |
| Consume the SOAP Message and run on the Message Processing Phase in the |
| inflow</p> |
| </li> |
| <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the |
| message is destined to. Always runs on the</p> |
| </li> |
| </ol> |
| |
| <h3>Processing an Incoming SOAP Message</h3> |
| |
| <p>Incoming SOAP Message is always received by a Transport Receiver waiting |
| for the SOAP Messages, once the SOAP Message is arrived the transport Headers |
| are parsed and a <a href="#messageContext">Message Context</a> is created for |
| the incoming SOAP Message. The the <i>In Pipe</i> is executed with the |
| Message Context. Let us see what would happen at the each Phase of the |
| execution, this process my happen in either in the server or the Client, |
| there is a special case of using the two way transport where the first four |
| phases in the In-Phase most likely to do nothing.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Transport Phase - The Handlers in the |
| transport Phase are taken from the transport configuration associated, |
| they are executed according to the Phase rules.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Pre-Dispatch Phase- The Handlers that |
| goes there must be engaged globally (for all services) as the Service |
| does not known at this point. The best example for them would be, |
| Addressing Handlers and may be security Handlers if the Addressing |
| Headers are encrypted.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Dispatch Phase - The Dispatchers are run |
| in this Phases and find the Service if the service is not found |
| already.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Post-Dispatch Phase - This phase check |
| weather the service is found, if the service has not found by this point |
| the execution will halt and send a "service not found error". Policy |
| Determination Phase - This Phase does nothing for the time being, this is |
| placed for the implementing the Policy</p> |
| </li> |
| <li><p style="margin-bottom: 0in">User Defined Phases - User defined Phases |
| are executed here.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Message Validation Phase - Once the user |
| level execution is taken place, this Phase will validates has the SOAP |
| Message Processing has taken place correctly. For an example the must |
| understand processing would happen here.</p> |
| </li> |
| <li><p>Message Processing Phase - The Business logic of the SOAP message, |
| executed here, the a <a href="#mr">Message Receiver</a> is registered |
| with a each Operation. The Message receiver associated with the each |
| operation would be executed as the last Handler of this Phase.</p> |
| </li> |
| </ol> |
| |
| <p>There may be other handlers in the any of the these Phases, users may |
| employ custom Handlers to override the mechanics in the each of these Phases. |
| If there is a response message, that would be initiated by the <a |
| href="#mr">Message Receiver</a>, yet the architecture is not aware of the |
| response message and merely invoke the <a href="#mr">Message Receiver</a>.</p> |
| |
| <h3>Processing of the Outgoing Message</h3> |
| |
| <p>Out pipe is simpler because the Service and the Operation to dispatch is |
| known by the time the pipe is executed. The Out pipe may be initiated by the |
| <a href="#mr">Message Receiver</a> or the Client API implementation.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Message Initialize Phase - Fist Phase of |
| the out pipe, this serves as the placeholder for the custom Handlers</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Policy Determination Phase - Just like in |
| the in-pipe this is not implemented and suppose to serve as a extension |
| point</p> |
| </li> |
| <li><p style="margin-bottom: 0in">User Phases - This executes Handlers in |
| user define Phases</p> |
| </li> |
| <li><p>Transports Phase - Execute any transport Handlers taken from the |
| associated transport configuration and the last handler would be a |
| transport Sender which would send the SOAP message to the target end |
| point</p> |
| </li> |
| </ol> |
| |
| <h3>Extending SOAP Processing Model</h3> |
| |
| <p>We discussed the default processing model of the Axis2, ability to extend |
| the model has been the whole point of spending the energy on the SOAP |
| processing model. We shall discuss the extension mechanism for the SOAP |
| processing model now.</p> |
| |
| <p>Idea behind making each step of the SOAP processing in terms of Handlers |
| (inbuilt ones we discuss earlier) and placing them in the Phases is to allow |
| Handlers to be placed between those Handlers and to override or affect the |
| default mechanics. There are two ways the to extend the SOAP Processing |
| Model.</p> |
| |
| <h4>Extending the SOAP Processing Model with Handlers</h4> |
| |
| <p>The Handlers can specify the Phase they need to be run, further more they |
| can specify the there location inside a phase via the following |
| information.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Handler should run as the first in the |
| phases</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Handler should run as the last in the |
| Phases</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Handler should run before a given |
| Handlers</p> |
| </li> |
| <li><p>Handler should run after a Given Handler</p> |
| </li> |
| </ol> |
| |
| <h4>Extending the SOAP Processing Model with Modules</h4> |
| |
| <p>SOAP processing Model defines a logical entity called a module that |
| encapsulates two entities, Handlers and Web Service Operations. The Handlers |
| will act in the same way as explained in the first method.</p> |
| |
| <p>Apart from the extension mechanism based on the Handlers, the WS-* |
| specifications suggest a requirement for add new Operations using modules. |
| For an example once a user add a Reliable Messaging capability to a Service, |
| the "Create Sequence" operation needs to be available to the service end |
| point. This can be implemented by letting the Modules define the operations |
| and once the module is engaged to a service the operations will be added to |
| that service.</p> |
| |
| <p>A service, operations or the system may engage a module, once the module |
| is engaged the handlers and the operations defined in the module are added to |
| the entity that engages them. Modules can not be added while the Axis2 is |
| running but later they will be available once the system is restarted.</p> |
| |
| <h2><a name="bmDeployment"></a>Deployment</h2> |
| |
| <p>There deployment Model provides a concrete mechanism to configure Axis2. |
| Deployment Model has four entities that provide the configuration.</p> |
| |
| <h3>The <em>axis2.xml</em> file</h3> |
| |
| <p>This file holds the global configuration for the client and server, and |
| provide following information.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">The global parameters</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Registered transports in and transport |
| outs</p> |
| </li> |
| <li><p style="margin-bottom: 0in">User defined Phase names</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Modules that are engaged globally</p> |
| </li> |
| <li><p>Globally defines <a href="#mr">Message Receiver</a>s</p> |
| </li> |
| </ol> |
| |
| <h3>Service Archive</h3> |
| |
| <p>Service archive must have a <em>META-INF/services.xml</em> file and may |
| contain the dependent classes. the <em>services.xml</em> file has following |
| information.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Service level parameters</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Modules that are engaged Service level</p> |
| </li> |
| <li><p>Operations inside the Service</p> |
| </li> |
| </ol> |
| |
| <h3>Module Archive</h3> |
| |
| <p>Module archive must have a <em>META-INF/module.xml</em> file and dependent |
| classes the <em>module.xml</em> file has Module parameters and the Operations |
| defined in the module.</p> |
| |
| <p>When the system started up the Axis2 ask the deployment model to create a |
| Axis Configuration, the Deployment Model first find a <em>axis2.xml</em> file |
| and build the global configuration. Then the Deployment check for the Module |
| archives and then for the service archives, the corresponding services and |
| Modules are added to the Axis Configuration. System will build Contexts on |
| top of the Axis Configurations and the Axis2 is ready to send or receive the |
| SOAP Message. The Hot deployment is allowed only for the Service and in that |
| case a thread will check the repository repeatedly, and add the Service |
| corresponds to the new found Service archives to the repository.</p> |
| |
| <h2><a name="bmWSDL"></a>WSDL and code generation</h2> |
| |
| <p>Although the basic objective of the code generation tool has not changed, |
| the Code generation module of Axis2 has taken a different approach to |
| generate code. Primarily the change is in the use of templates, namely XSL |
| templates which gives the code generator the flexibility to generate code in |
| multiple languages.</p> |
| |
| <p>The basic approach is to set the code generator to generate an XML and |
| parse it with a template to generate the code file. The following figure |
| shows how this shows up in the architecture of the tool.</p> |
| |
| <p><img src="images/archi-guide/CodegenArchitecture.jpg" name="Graphic6" |
| align="bottom" width="478" height="218" border="0"></p> |
| |
| <p>The fact here is that it is the same information that is extracted from |
| the WSDL no matter what code is generated. Code generator uses the WOM (WSDL |
| Object Model) internally to manipulate the WSDL and passes that information |
| to the emitter which emits an XML. the XML is then parsed with the relevant |
| XSL to generate the code. No matter what the language, the process is the |
| same except for the template that is being used</p> |
| |
| <h2><a name="bmDB"></a>Data Binding</h2> |
| |
| <h3>Integration with the code generation engine</h3> |
| |
| <p>Axis2 M2 was released with code generation support but without data |
| binding. The version 0.9 was shipped with data binding support with complete |
| schema support. Such claim is made possible because of the fact that the data |
| binding tool, xml-beans, has the full schema support. The original |
| architecture of the code generation framework did not undergo significant |
| changes because of the way that the code generation framework was originally |
| designed. Data binding was incorporated as a pluggable extension to the code |
| generation engine. Version 0.91 did not does not support SOAP encoding. It |
| only supports RPC literal or document literal massages.</p> |
| |
| <p><img src="images/codegen.gif" name="Graphic7" align="bottom" width="406" |
| height="467" border="0"></p> |
| |
| <h3>Serialization and De-Serialization</h3> |
| |
| <p>Xml-beans supports StAX API and AXIOM is based on a StAX API. Data binding |
| in Axis2 is achieved through interfacing the AXIOM with the Xml-beans using |
| the StAX API which is supported by both parties. At the time of the code |
| generation there will be supporter classes for each WSDL operation that will |
| have the utility methods that can de-serialize the from AXIOM to data bound |
| object and serialize from data bound object to AXIOM. For example if the WSDL |
| has an operation called "echoString", once the code is generated there will |
| be an echoStringDatabindingSupporter.java class generated that will have |
| methods that will look like the following.</p> |
| |
| <p>public static org.apache.axis2.om.OMElement |
| toOM(org.soapinterop.xsd.EchoStringParamDocument param) : This method will |
| handle the serialization.</p> |
| |
| <p>public static org.apache.xmlbeans.XmlObject |
| fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) : This |
| method will handle the de-serialization.</p> |
| |
| <p>public static org.apache.xmlbeans.XmlObject getTestObject(java.lang.Class |
| type) : This will be a utility method that can be used to create sample |
| objects of the given data bound object.</p> |
| |
| <h2><a name="bmClientAPI"></a>Client API</h2> |
| |
| <p>There are three parameters that decide the nature of the Web Service |
| interaction.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Message Exchange Pattern</p> |
| </li> |
| <li><p style="margin-bottom: 0in">The Behavior of the transport. Does it |
| act one-way or two way</p> |
| </li> |
| <li><p>Synchronous/ Asynchronous behavior of the Client API</p> |
| </li> |
| </ol> |
| |
| <p>Variations of the three parameters can result in indefinite number of |
| scenarios, even though Axis2 is built on a core that support any messaging |
| interaction, the developers were compelled to support only two most widely |
| used Message Exchange Patterns.</p> |
| |
| <p>Two supported transports are One-Way and the Request-Response scenarios in |
| the Client API, the implementation is based on a class called |
| <code>MEPClient</code> and there are extensions for each Message Exchange |
| Pattern that Axis2 Client API supports.</p> |
| |
| <h3>One Way Messaging Support</h3> |
| |
| <p>The One-Way support is provided by the <code>InOnlyMEPClient</code> and |
| Axis2 provides a class called <code>Call</code> that provides a much simpler |
| interface for the user. The Axis2 supports 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.</p> |
| |
| <h3>Request Response Messaging Support</h3> |
| |
| <p>The Request-Response support is provided by the |
| <code>InOutMEPClient</code> and Axis2 provides a class called |
| <code>MessageSender</code> that provides a much simpler interface for the |
| user. The Client API has four ways to configure a given Message Exchange</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Blocking or Non-Blocking nature - this |
| can be decided by using <code>invokeBlocking()</code> or |
| <code>invokeNonBlocking()</code> methods</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Sender transport - transport use to send |
| the SOAP Message</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Listener transport - transport the |
| Response is received</p> |
| </li> |
| <li><p>Use Separate Channel - does the response is send over a separate |
| transport connection or not, this can be false only when sender an |
| listener transport is same and is a two way transport.</p> |
| </li> |
| </ol> |
| |
| <p>Depend on the values for the above four parameter, Axis2 behave |
| differently</p> |
| |
| <h2><a name="bmTransports"></a>Transports</h2> |
| |
| <p>Axis2 has two basic constructs for transports, named as Transport In |
| Configuration and Transport Out Configuration. The <a |
| href="#messageContext">Message Context</a> has two fields to put the input |
| and the out put transport to be used. Axis behaves according to the transport |
| that is specified in each of the fields.</p> |
| |
| <p>SOAP Message is arrived at the Server side, the incoming transport is |
| decided by the Transport Listener that accepts the incoming SOAP Message. The |
| transports for the subsequent SOAP Messages that are related to the first |
| message, are decided based on the addressing parameters.</p> |
| |
| <p>At the Client Side the user is free to specify the transport to be used, |
| as in the Server side the transport for the subsequent SOAP Messages are |
| decided by the addressing.</p> |
| |
| <p>There Transport In Configuration and the Transport Out Configuration |
| contains following information.</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Transport Sender in Out Configuration, |
| Transport Listener in the TransportIn Configuration</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Parameters of the transport</p> |
| </li> |
| <li><p>Transport Handlers</p> |
| </li> |
| </ol> |
| |
| <p>Transport Sender send the SOAP Message over a given transport, each and |
| every transport Out Configuration should define a transport Sender that send |
| the transport.</p> |
| |
| <p>Transport Receiver waits for the SOAP Messages and for each SOAP Message |
| that arrives, uses the <i>In Pipe</i> to process the SOAP Message.</p> |
| |
| <p>Axis2 Presently support the following transports</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">HTTP - The HTTP transport, the transport |
| Listener is a Servlet or a Simple HTTP server provided by Axis2. The |
| transport Sender uses sockets to connect and send the SOAP Message. |
| Currently we have the commons-HTTP-client based HTTP Transport sender as |
| the default transport</p> |
| </li> |
| <li><p style="margin-bottom: 0in">TCP - This is the most simplest |
| transport, but needed the addressing support to be functional.</p> |
| </li> |
| <li><p>SMTP - This work off a single email account, Transport Receiver is a |
| tread that checks for emails in fixed time intervals.</p> |
| </li> |
| </ol> |
| </body> |
| </html> |