| <!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 content="20050916;22455288"> |
| <meta name="CHANGEDBY" content="Chamikara Jayalath"> |
| <meta name="CHANGED" content="20050918;22493797"> |
| </head> |
| |
| <body lang="en-US" dir="ltr"> |
| <h1 align="center">Axis2 Architecture Guide</h1> |
| |
| <p><i>Version 0.95</i></p> |
| <i>Feedback: <a |
| href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i> |
| |
| <h2>Contents</h2> |
| <ul> |
| <li><a href="#bmBP">The Big Picture</a></li> |
| <li><p><a href="#requirements">Requirement of Axis2</a></p> |
| </li> |
| <li><a href="#thearchi">Axis2, The Architecture</a> |
| <ul> |
| <li><p><a href="#bmInfoMod">Information Model</a></p> |
| </li> |
| <li><a href="#bmXML">XML Processing Model</a></li> |
| <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p> |
| <ul> |
| <li><a href="#default">Axis2 Default Processing Model</a></li> |
| <li><p><a href="#incomingsoap">Processing an Incoming SOAP |
| Message</a></p> |
| </li> |
| <li><a></a><a href="#outgoing">Processing of the Outgoing |
| Message</a></li> |
| <li><p><a href="#extending">Extending SOAP Processing Model</a></p> |
| <ul> |
| <li><a href="#extendingwithhandlers">Extending the SOAP |
| Processing Model with Handlers</a></li> |
| <li><p><a href="#extendingwithmodules">Extending the SOAP |
| Processing Model with Modules</a></p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#bmDeployment">Deployment</a> |
| <ul> |
| <li><a href="#xmlfile">The <em>axis2.xml</em> file</a></li> |
| <li><p><a href="#servicearchive">Service Archive</a></p> |
| </li> |
| <li><a href="#modulearchive">Module Archive</a></li> |
| </ul> |
| </li> |
| <li><p><a href="#bmClientAPI">Client API</a></p> |
| <ul> |
| <li><a href="#oneway">One Way Messaging Support</a></li> |
| <li><p><a href="#requestresponse">Request Response Messaging |
| Support</a></p> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#bmTransports">Transports</a></li> |
| <li><p><a href="#bmWSDL">Code generation</a></p> |
| </li> |
| <li><a href="#bmDB">Data Binding</a> |
| <ul> |
| <li><a href="#integration">Integration with the code generation |
| engine</a></li> |
| <li><p><a href="#serial">Serialization and De-Serialization</a></p> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <h2><a name="bmBP">The Big Picture</a></h2> |
| |
| <p>Any architecture is a result of what that architecture should yield. The |
| success of an architecture should be evaluated based on the requirements |
| expected to be met by that architecture. Let us start our journey into Axis2 |
| by looking at the requirements.</p> |
| <a name="requirements"></a> |
| |
| <h2>Requirement of Axis2</h2> |
| |
| <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. A single SOAP |
| delivery is the most basic unit that builds the Web Service interaction.</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 on the wire each Web Service interaction is done via |
| SOAP, which is common to every SOAP Node.</p> |
| |
| <p><img alt="" src="images/archi-guide/soap.gif" name="Graphic1" |
| align="bottom" width="691" height="319" border="0"></p> |
| |
| <p>Web Service middleware handles the complexity in SOAP messaging and lets |
| the users work with the programming language they are accustomed to. Axis2 |
| allows java users to invoke Web Services using java representations, and |
| handles the SOAP messaging behind the curtain.</p> |
| |
| <p>Axis2 handles SOAP processing along with numerous other tasks. This makes |
| the life of the Web Service developer a whole lot easier. Following are the |
| identified requirements:</p> |
| <ol> |
| <li>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 per operation basis. Furthermore it should be able to |
| model different Message Exchange Patterns (MEPs) using the processing |
| framework.</li> |
| <li><p>Ability to deploy a Web Services (with or without WSDL)</p> |
| </li> |
| <li>Provide a Client API that can be used to invoke Web Services. This API |
| should support both the Synchronous and Asynchronous programming |
| models.</li> |
| <li><p>Ability to configure Axis2 and it's components via deployment.</p> |
| </li> |
| <li>Ability to send and receive SOAP messages with different |
| transports.</li> |
| </ol> |
| |
| <p>Apart from the above functionalities, performance in 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-RP, SAAJ & WS-Policy are layered on top of the Core Architecture.</p> |
| |
| <h2><a name="thearchi">Axis2, The Architecture</a></h2> |
| Axis2 architecture lays out some principals to preserve the uniformity. They |
| are as follows: |
| <ul> |
| <li><p>Axis2 architecture separates the logic and the states. Code that |
| does the processing is stateless inside Axis2. This allows code to be |
| executed freely by parallel threads.</p> |
| </li> |
| <li>All the information is kept in one information model allowing system to |
| be suspended and resumed.</li> |
| </ul> |
| |
| <p>Axis2 architecture is modular. Therefore Axis2 Framework is built up of |
| core modules which collectively make up the core architecture of Axis2, and |
| non-core modules that are layered on top of this core |
| modules/architecture.</p> |
| |
| <p>Core Modules:</p> |
| <ul> |
| <li><a href="#bmInfoMod">Information Model</a>- Axis2 defines a model to |
| handle information and all states are kept in this model. The model has a |
| hierarchy for the information. The system manages the life cycle of the |
| objects in this hierarchy.</li> |
| <li><p><a href="#bmXML">XML processing Model</a>- Handling the SOAP Message |
| is the most important and most complex task. The efficiency of this is |
| the single most important factor that decides the performance. It makes |
| sense to delegate this task to a separate module allowing that |
| module(AXIOM) to provide a simple API for SOAP and XML info-set while |
| hiding the complexities of the efficient XML processing within the |
| implementation.</p> |
| </li> |
| <li><a href="#bmSOAPPM">SOAP Processing Model</a>- This controls the |
| execution of the processing. The model defines different phases the |
| execution would walk through, and the user can extend the Processing |
| Model at some specific places.</li> |
| <li><p><a href="#bmDeployment">Deployment Model</a>- Axis2 deployment model |
| allows the user to deploy services, configure the transports, extend the |
| SOAP Processing model per system, service or operation basis.</p> |
| </li> |
| <li><a href="#bmClientAPI">Client API</a>- This provides a convenient API |
| for users to communicate with web services using Axis2. There are set of |
| classes to interact with IN-OUT and IN-Only style Message Exchange |
| Patterns (MEPs) where those can be used to construct any other MEP.</li> |
| <li><p><a href="#bmTransports">Transports</a>- Axis2 define a transport |
| framework that enables the user to use different transports. The |
| transports fit into specific places in the SOAP processing model. The |
| implementation provides a few common transports and the user may write |
| new ones if and when it is needed.</p> |
| </li> |
| </ul> |
| Non-core Modules: |
| <ul> |
| <li><a href="#bmWSDL">Code Generation</a>- Axis2 provides a code generation |
| tool that will generate server side and client side code along with a |
| test case. The generated code would simplify the service deployment and |
| the service invocation. This would increase usability of Axis2.</li> |
| <li><p><a href="#bmDB">Data Binding</a>- The basic client API of Axis2 lets |
| the users process SOAP at the infoset level where as data binding extends |
| it to make it more convenient to the users by encapsulating the infoset |
| layer and providing a programming language specific interface.</p> |
| </li> |
| </ul> |
| <map name="Graphic2Map" id="g2m"> |
| <area shape="rect" coords="123,31,222,97" href="#bmInfoMod" alt=""> |
| <area shape="rect" coords="239,62,319,134" href="#bmXML" alt=""> |
| <area shape="rect" coords="127,112,218,177" href="#bmSOAPPM" alt=""> |
| <area shape="rect" coords="12,39,89,95" href="#bmDeployment" alt=""> |
| <area shape="rect" coords="0,108,94,156" href="#bmWSDL" alt=""> |
| <area shape="rect" coords="350,31,426,86" href="#bmClientAPI" alt=""> |
| <area shape="rect" coords="350,114,421,164" href="#bmTransports" alt=""> |
| </map> |
| |
| <p><img src="images/archi-guide/all.png" name="Graphic2" width="426" alt="" |
| height="189" border="0" align="bottom" usemap="#Graphic2Map"></p> |
| |
| <h2><a name="bmInfoMod">Information Model</a></h2> |
| |
| <p>Information Model has two main hierarchies-Contexts and Descriptions. This |
| model is described in UML notations below.</p> |
| |
| <p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom" |
| alt="" width="400" height="443" border="0"></p> |
| |
| <p>( A ----<> B says, B has 1 or more objects of A. A------>B says, |
| 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 the static data. This data may be loaded |
| from a configuration file that exists throughout the lifetime of Axis2. For |
| example, deployed Web Services, operations, etc. On the other hand, the |
| context hierarchy holds more dynamic information about the things that have |
| more than one instances (e.g.Message Context).</p> |
| |
| <p>These two hierarchies creates 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 the hierarchy until a match is found. In the |
| resulting model the lower levels override the values in the upper levels. For |
| example, when a value is looked up in the Message Context and is not found, |
| it would be looked up in 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 the user to declare and override values. Result being a very |
| flexible configuration model. The flexibility could be the <em>Achilles</em> |
| heel for the system as the search is expensive, specially for something that |
| does not exist. Yet in the final analysis developers believe that the |
| flexibility would serve better in this instant.</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><strong>Context</strong></td> |
| <td><strong>Description</strong></td> |
| <td><strong>Configuration</strong></td> |
| <td><strong>Description</strong></td> |
| </tr> |
| <tr> |
| <td width="112"><p>Configuration Context</p> |
| </td> |
| <td width="371"><p>Holds the run time status. 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 etc.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><p>Service Group Context</p> |
| </td> |
| <td width="371"><p>Holds information about a particular usage of the |
| respective service group. The life of a Service Group Context starts |
| when a user starts interacting with a service that belong to this |
| service group. This can be used to share information between services |
| (within the same service group) in a single interaction.</p> |
| </td> |
| <td width="103"><p>AxisServiceGroup</p> |
| </td> |
| <td width="336"><p>Holds deployment time information about a particular |
| service group.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><p>Service Context</p> |
| </td> |
| <td width="371"><p>This context is available throughout the usage of |
| the respective service. This can be used to share information between |
| several MEPs of the same service, within a single interaction.</p> |
| </td> |
| <td width="103"><p>AxisService</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>AxisOperation</p> |
| </td> |
| <td width="336"><p>Holds the operation level configurations</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="112"><a name="messageContext"></a> |
| |
| <p>Message Context</p> |
| </td> |
| <td width="371"><p>Holds all the information about the Message |
| currently being executed.</p> |
| </td> |
| <td width="103"><p>AxisMessage</p> |
| </td> |
| <td width="336"><p>Do not hold any information as yet, but can be used |
| as a future extension point.</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <a name="bmXML"></a> |
| |
| <h2>XML Processing Model</h2> |
| |
| <p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p> |
| |
| <h2><a name="bmSOAPPM">SOAP Processing Model</a></h2> |
| |
| <p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" alt="" |
| 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 ('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>, and |
| the complex Message Exchange Patterns (MEPs) are constructed by combining |
| these two pipes.</p> |
| |
| <p>Extensibility of the SOAP processing model is provided through 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 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 being sent through the Client API, an <i>Out |
| Pipe</i> would begin, the <i>Out Pipe</i> invokes the handlers and end 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 <em>In Pipe</em> |
| consists of handlers and ends with the <a href="#mr">Message Receiver</a>, |
| which consumes the SOAP message.</p> |
| |
| <p>Above explained processing happens for each and every SOAP message |
| exchanged. After processing one message Axis2 may decide to create other SOAP |
| messages, in which case more complex message patterns emerge. However Axis2 |
| always view the SOAP message in terms of processing a single message. 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. The different areas or the stages 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 have 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 & |
| user-defined phases. User-defined phases fit in to the User Phases.</p> |
| |
| <p><img src="images/archi-guide/phases.png" name="Graphic5" align="bottom" |
| alt="" width="525" height="226" border="0"></p> |
| |
| <h3><a name="default">Axis2 Default Processing Model</a></h3> |
| |
| <p>Axis2 has 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> |
| There are four special handlers defined in Axis2. |
| <ol> |
| <li>Dispatchers - Finds the service and the operation the SOAP message is |
| directed to. Dispatchers always run on the <em>In-Pipe</em> and inside |
| the Dispatch phase. The in-built dispatchers dispatch to a particular |
| operation depending on various conditions like WS-Addressing information, |
| URI information, SOAP action information, etc.,</li> |
| </ol> |
| <ul> |
| <li><a name="mr">Message Receiver - Consume the SOAP Message And hands that |
| over to application , Message receiver is the last handler of the |
| in-pipe</a></li> |
| <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the |
| message is destined to. Always runs as last handler in the out-pipe</p> |
| </li> |
| </ul> |
| |
| <h3><a name="incomingsoap">Processing an Incoming SOAP Message</a></h3> |
| |
| <p>Incoming SOAP Message is always received by a Transport Receiver waiting |
| for the SOAP Messages. Once the SOAP Message arrives the transport Headers |
| are parsed and a</p> |
| <a href="#messageContext">Message Context</a> is created for the incoming |
| SOAP Message. Then the <i>In Pipe</i> is executed with the Message Context. |
| |
| <p>Let us see what happens at each phase of the execution. This process may |
| happen either in the server or in the Client. </p> |
| <ol> |
| <li>Transport Phase - The handlers are in the phase ment to be process |
| transport specific information such as validate incoming message by |
| looking at various transport headers, add data into message context etc.. |
| </li> |
| <li>Pre-Dispatch Phase- The main functionality of the handlers are in this |
| phase is to populate message context in order to do the dispatching. As |
| an example processing of addressing headers happen in this phase , so by |
| looking at addressing headers it will find the name of the service and |
| operation.</li> |
| <li>Dispatch Phase - The Dispatchers run in this phase and find the Service |
| if the service is not found already. <br> |
| The post condition of the dispatch phase work as follows; That checks |
| whether the service and operation are found or not. If the service or |
| operation has not been found by this point the execution will halt and |
| send a "service not found error".</li> |
| <li>User Defined Phases - Users are allowed to engage their custom handlers |
| here.</li> |
| <li>Message Validation Phase - Once the user level execution has taken |
| place this phase validates whether SOAP Message Processing has taken |
| place correctly.</li> |
| <li>Message Processing Phase - The Business logic of the SOAP message is |
| executed here. A <a href="#mr">Message Receiver</a> is registered with |
| each Operation. This Message receiver (associated to the particular |
| operation) will executed as the last Handler of this phase.</li> |
| </ol> |
| |
| <p>There may be other handlers in any of these phases. Users may use custom |
| handlers to override the mechanics in each of these phases.</p> |
| |
| <h3><a name="outgoing">Processing of the Outgoing Message</a></h3> |
| |
| <p><em>Out Pipe</em> is simpler because the service and operation to dispatch |
| is known by the time the pipe is executed. The <em>Out Pipe</em> may be |
| initiated by the</p> |
| <a href="#mr">Message Receiver</a> or the Client API implementation.Phases of |
| the <em>Out Pipe</em> are described below: |
| <ol> |
| <li>Message Initialize Phase - Fist phase of the <em>Out Pipe</em>. Serves |
| as the placeholder for the custom handlers</li> |
| <li>User Phases - This executes handlers in user defined phases</li> |
| <li>Transports Phase - Execute any transport handlers taken from the |
| associated transport configuration. The last handler would be a transport |
| Sender which would send the SOAP message to the target end point.</li> |
| </ol> |
| |
| <h3><a name="extending">Extending SOAP Processing Model</a></h3> |
| |
| <p>Above we discussed the default processing model of Axis2. Now lets discuss |
| the extension mechanism for the SOAP processing model. After all, the whole |
| effort of making this SOAP engine/processing model was focused much on making |
| it extendable.</p> |
| |
| <p>Idea behind introducing step wise processing of the SOAP message in terms |
| of handlers & phases is to allow easier modification of the processing |
| order. The notion of phases makes it easier to place handlers in between |
| other handlers enabling this modification on the default processing behavior. |
| SOAP Processing Model can be extended with handler or Modules.</p> |
| <a name="extendingwithhandlers"></a> |
| |
| <h4>Extending the SOAP Processing Model with Handlers</h4> |
| The handlers in a module can specify the phase they need to be placed in. |
| Furthermore they can specify their location inside a phase by providing phase |
| rules. Phase rules will place a handler |
| <ol> |
| <li>as the first handler in a phase.</li> |
| <li>or as the last handler in a phase.</li> |
| <li>or before a given handler</li> |
| <li>or after a given handler</li> |
| </ol> |
| |
| <h4><a name="extendingwithmodules">Extending the SOAP Processing Model with |
| Modules</a></h4> |
| |
| <p>Axis2 defines an entity called a 'module' that can introduce handlers and |
| web service operations. A Module in terms of Axis2 usually acts as a |
| convenient packaging that include 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 has not been activated, i.e., the handlers included inside the |
| module have not been used in the processing mechanism. When a module is |
| 'engaged' it becomes active and the handlers get placed in the proper phases. |
| The handlers will act in the same way as explained in the previous section. |
| Usually a module will be used to implement a WS-* functionality such as |
| WS-Addressing.</p> |
| |
| <p>Apart from the extension mechanism based on the handlers the WS-* |
| specifications suggest a requirement for adding new operations. For 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 necessary 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 engage them.</p> |
| |
| <p>Modules can not be added while the Axis2 engine is running, but they will |
| be available once the system is restarted.</p> |
| <a name="bmDeployment"></a> |
| |
| <h2>Deployment</h2> |
| |
| <p>The Deployment Model provides a concrete mechanism to configure Axis2. |
| This model has three entities that provide the configuration.</p> |
| <a name="xmlfile"></a> |
| <h3>The axis2.xml file</h3> |
| |
| <p>This file holds the global configuration for the client and server, and |
| provide following information:</p> |
| <ol> |
| <li>The global parameters</li> |
| <li>Registered transports in and transport outs</li> |
| <li>User defined phase names</li> |
| <li>Modules that are engaged globally (to all services)</li> |
| <li>Globally defined <a href="#mr">Message Receivers</a></li> |
| </ol> |
| <a name="servicearchive"></a> |
| |
| <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>Service level parameters</li> |
| <li>Modules that are engaged Service level</li> |
| <li>Service Specific <a href="#mr">Message Receivers</a></li> |
| <li>Operations inside the Service</li> |
| </ol> |
| |
| <h3><a name="modulearchive">Module Archive</a></h3> |
| |
| <p>Module archive must have a META-INF/module.xml 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 is starting up Axis2 ask the deployment model to create a |
| Axis Configuration. Deployment Model first finds the axis2.xml file and build |
| the global configuration. Then it checks for the module archives and then for |
| the service archives. After which the corresponding services and modules are |
| added to the Axis Configuration. System will build Contexts on top of the |
| Axis Configurations and then Axis2 is ready to send or receive the SOAP |
| Message. Hot deployment is only allowed for the service, in which case a |
| thread will check the repository repeatedly, and then add the service |
| corresponding to the new found service archives to the repository.</p> |
| <a name="bmClientAPI"></a> |
| |
| <h2>Client API</h2> |
| |
| <p>There are three parameters that decide the nature of the Web Service |
| interaction.</p> |
| <ol> |
| <li>Message Exchange Pattern (MEP)</li> |
| <li>The Behavior of the transport, whether it's One-Way or Two-Way</li> |
| <li>Synchronous/ Asynchronous behavior of the Client API</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 (MEPs).</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>ServiceClient</code> and there are extensions for each MEP that Axis2 |
| Client API supports.</p> |
| |
| <h3><a name="oneway">One Way Messaging Support</a></h3> |
| |
| <p>The One-Way support is provided by the <code>fireAndForget</code> which |
| provide by <code>ServiceClient</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> |
| <a name="requestresponse"></a> |
| |
| <h3>Request Response Messaging Support</h3> |
| |
| <p>The Request-Response support is provided by the <code>sendReceive()</code> |
| method in ServiceClient ,that provides a much simpler interface for the user. |
| The Client API has four ways to configure a given Message Exchange</p> |
| <ol> |
| <li>Blocking or Non-Blocking nature - this can be decided by using |
| <code>sendReceive()</code> or <code>sendReceiveNonBlocking()</code> |
| methods</li> |
| <li>Sender transport - transport used to send the SOAP Message</li> |
| <li>Listener transport - transport the Response is received</li> |
| <li>Use Separate Channel - determines whether the response is send over a |
| separate transport connection or not. This can be false only when sender |
| and listener transport is same and is a Two-Way transport.</li> |
| </ol> |
| |
| <p>Depending on the values of the above four parameter, Axis2 behave |
| differently.</p> |
| <a name="bmTransports"></a> |
| |
| <h2>Transports</h2> |
| |
| <p>Axis2 has two basic constructs for transports, Transport Senders and |
| Transport Receivers . These are accessed via the AxisConfiguration.</p> |
| |
| <p>The incoming transport is the transport via which the server side receives |
| the message and the outgoing transport is decided based on the addressing |
| information (wsa:ReplyTo and wsa:FaultTo). If addressing information is not |
| available then the out going transport will be the outputstream of the |
| incoming transport (if it is two-way transport).</p> |
| |
| <p>At the client side the user is free to specify the transport to be |
| used.</p> |
| |
| <p>Transport Senders and Transport Receivers contains following |
| information.</p> |
| <ol> |
| <li>Transport Sender for Out Configuration</li> |
| <li>Transport Listener for In Configuration</li> |
| <li>Parameters of the transport</li> |
| </ol> |
| |
| <p>Each and every transport Out Configuration defines a transport sender. |
| Transport sender sends the SOAP Message over depending on its |
| configuration.</p> |
| |
| <p>Transport receiver waits for the SOAP Messages and for each SOAP Message |
| that arrives, it uses the <i>In Pipe</i> to process the SOAP Message.</p> |
| |
| <p>Axis2 Presently support the following transports:</p> |
| <ol> |
| <li>HTTP - In HTTP transport the transport listener is a servlet or |
| org.apache.axis2.transport.http.SimpleHTTPServer provided by Axis2. The |
| transport sender uses commons-httpclient to connect and send the SOAP |
| Message.</li> |
| <li>TCP - This is the most simplest transport, but needs the WS - |
| Addressing support to be functional.</li> |
| <li>SMTP - This works off a single email account. Transport receiver is a |
| thread that checks for emails in fixed time intervals.</li> |
| </ol> |
| <a name="bmWSDL" id="bmWSDL"></a> |
| |
| <h2>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 |
| describes how this shows up in the architecture of the tool.</p> |
| |
| <p><img src="images/archi-guide/CodegenArchitecture.jpg" name="Graphic6" |
| alt="" 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" id="bmDB">Data Binding</a></h2> |
| <a name="integration"></a> |
| |
| <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. Axis2 version 0.91 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" |
| alt="" height="467" border="0"></p> |
| |
| <h3><a name="serial">Serialization and De-Serialization</a></h3> |
| |
| <p>AXIOM is based on a StAX (Streaming API for XML) API. Xml-beans supports |
| 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><code>public static |
| org.apache.axiom.om.OMElementtoOM(org.soapinterop.xsd.EchoStringParamDocument |
| param)</code><code>// This method will handle the serialization.</code></p> |
| |
| <p><code>public static org.apache.xmlbeans.XmlObject |
| fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This |
| method will handle the de-serialization.</code></p> |
| |
| <p><code>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.*/</code></p> |
| |
| <p></p> |
| </body> |
| </html> |