You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2005/09/20 06:29:52 UTC
svn commit: r290351 [1/2] - in /webservices/axis2/trunk/java/xdocs:
Axis2ArchitectureGuide.html faq.html http-transport.html
installationguide.html maven-help.html migration.html rest-ws.html
tcp-transport.html webadminguide.html
Author: chinthaka
Date: Mon Sep 19 21:29:37 2005
New Revision: 290351
URL: http://svn.apache.org/viewcvs?rev=290351&view=rev
Log:
Correcting more typos
Modified:
webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
webservices/axis2/trunk/java/xdocs/faq.html
webservices/axis2/trunk/java/xdocs/http-transport.html
webservices/axis2/trunk/java/xdocs/installationguide.html
webservices/axis2/trunk/java/xdocs/maven-help.html
webservices/axis2/trunk/java/xdocs/migration.html
webservices/axis2/trunk/java/xdocs/rest-ws.html
webservices/axis2/trunk/java/xdocs/tcp-transport.html
webservices/axis2/trunk/java/xdocs/webadminguide.html
Modified: webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html?rev=290351&r1=290350&r2=290351&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html (original)
+++ webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html Mon Sep 19 21:29:37 2005
@@ -1,682 +1,715 @@
-<!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="GENERATOR" CONTENT="OpenOffice.org 1.1.4 (Win32)">
- <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><P><A HREF="#bmInfoMod">Information Model</A></P>
- <LI><P><A HREF="#bmXML">XML Processing Model</A></P>
- <LI><P><A HREF="#bmSOAPPM">SOAP Processing Model</A></P>
- <LI><P><A HREF="#bmDeployment">Deployment</A></P>
- <LI><P><A HREF="#bmWSDL">WSDL and code generation</A></P>
- <LI><P><A HREF="#bmDB">Data Binding</A></P>
- <LI><P><A HREF="#bmClientAPI">Client API</A></P>
- <LI><P><A HREF="#bmTransports">Transports</A></P>
-</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><P STYLE="margin-bottom: 0in">Ability to deploy the Web Services
- (with or without WSDL)
- </P>
- <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><P STYLE="margin-bottom: 0in">Ability to configure Axis2 and
- it's components via the deployment
- </P>
- <LI><P>Ability to send and receive SOAP messages with different
- transports</P>
-</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><P>All the information is kept in a one Information model, this
- allows the system to be stored and resumed
- </P>
-</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><P STYLE="margin-bottom: 0in">XML processing Model
- </P>
- <LI><P STYLE="margin-bottom: 0in">SOAP Processing Model
- </P>
- <LI><P STYLE="margin-bottom: 0in">Deployment
- </P>
- <LI><P STYLE="margin-bottom: 0in">WSDL and Code Generation
- </P>
- <LI><P STYLE="margin-bottom: 0in">Client API
- </P>
- <LI><P>Transports
- </P>
-</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>
- <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>
-</TABLE>
-<P><BR><BR>
-</P>
-<P>All context classes implement readObject, writeObject methods that
-allows to serialize and deserialize them correctly. Serializing the
-current Configuration Context object would assentially serialize the
-whole contex thierarchy. To restore it, the user has to fist perform
-the deserialization of the ConfigurationContext object. He can
-restore the description hierarchy by calling the init
-(axisConfiguration) method of the deserialized 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><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><P>Transport Sender - Send the SOAP message to the SOAP endpoint
- the message is destined to. Always runs on the
- </P>
-</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><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><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><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><P STYLE="margin-bottom: 0in">User Defined Phases - User defined
- Phases are executed here.
- </P>
- <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><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>
-</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><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><P STYLE="margin-bottom: 0in">User Phases - This executes
- Handlers in user define Phases
- </P>
- <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>
-</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><P STYLE="margin-bottom: 0in">Handler should run as the last in
- the Phases
- </P>
- <LI><P STYLE="margin-bottom: 0in">Handler should run before a given
- Handlers
- </P>
- <LI><P>Handler should run after a Given Handler
- </P>
-</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 rater it ll 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><P STYLE="margin-bottom: 0in">Registered transports in and
- transport outs
- </P>
- <LI><P STYLE="margin-bottom: 0in">User defined Phase names
- </P>
- <LI><P STYLE="margin-bottom: 0in">Modules that are engaged globally
- </P>
- <LI><P>Globally defines <A HREF="#mr">Message Receiver</A>s
- </P>
-</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><P STYLE="margin-bottom: 0in">Modules that are engaged Service
- level
- </P>
- <LI><P>Operations inside the Service</P>
-</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 Dezerialization</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
-deserialize 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 deserialization.</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><P STYLE="margin-bottom: 0in">The Behavior of the transport.
- Does it act one-way or two way
- </P>
- <LI><P>Synchronous/ Asynchronous behavior of the Client API
- </P>
-</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><P STYLE="margin-bottom: 0in">Sender transport - transport use
- to send the SOAP Message
- </P>
- <LI><P STYLE="margin-bottom: 0in">Listener transport - transport the
- Response is received
- </P>
- <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>
-</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><P STYLE="margin-bottom: 0in">Parameters of the transport
- </P>
- <LI><P>Transport Handlers
- </P>
-</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 Servelet 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><P STYLE="margin-bottom: 0in">TCP - This is the most simplest
- transport, but needed the addressing support to be functional.
- </P>
- <LI><P>SMTP - This work off a single email account, Transport
- Receiver is a tread that checks for emails in fixed time intervals.
- </P>
-</OL>
-</BODY>
-</HTML>
\ No newline at end of file
+<!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>
Modified: webservices/axis2/trunk/java/xdocs/faq.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/faq.html?rev=290351&r1=290350&r2=290351&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/faq.html (original)
+++ webservices/axis2/trunk/java/xdocs/faq.html Mon Sep 19 21:29:37 2005
@@ -4,11 +4,11 @@
<title>Axis2 FAQ</title>
</head>
-<body>
+<body lang="en">
<h1>General</h1>
<ol>
<li><strong>I see OMElements in all the signatures, in the stubs, Client
- API and in skeltons. Where is data binding?</strong><br>
+ API and in skeletons. Where is data binding?</strong><br>
<p>Axis2 supports databinding using XML-Beans from 0.9 release. For more
information please read the <a href="userguide.html">user guide</a></p>
@@ -17,9 +17,9 @@
represents?</strong></a><br>
<p>OMElement is Axis2 representation of XML, it provide a tree model like
- DOM. If you are familer with DOM or JDOM you can soon get familerize with
- OM quickly. For more information read<a href="OMTutorial.html"> Axiom
- Tutorial</a></p>
+ DOM. If you are familiar with DOM or JDOM you can soon get familiarize
+ with OM quickly. For more information read<a href="OMTutorial.html">
+ Axiom Tutorial</a></p>
</li>
</ol>
@@ -49,18 +49,18 @@
care by the Client API and the Addressing Headers are under the Control
of Axis2.</p>
</li>
- <li><strong>When I try to do a non blocking call with use Seperate Listener
+ <li><strong>When I try to do a non blocking call with use Separate Listener
true I get the error <i>to do two Transport Channels the Addressing
- Modules must be engeged</i>, Why is this?</strong><br>
+ Modules must be engaged</i>, Why is this?</strong><br>
<p>To do the two transport Channel invocation you need to engage the
- addressing module. You can enable it by uncommenting the entry in the
+ addressing module. You can enable it by un-commenting the entry in the
axis2.xml file or Call.engageModule(QName).</p>
</li>
<li><a name="b5"><strong>What is the Axis Repository?</strong></a><br>
<p>Repository store the configuration of Axis2, the users should specify
- the repository folder starting the Aixs Server (HTTP ot TCP). In the case
+ the repository folder starting the Axis Server (HTTP or TCP). In the case
of tomcat it is the webapps/axis2/WEB-INF folder. Following picture shows
a sample repository.</p>
<img src="images/faq/1.jpg">
@@ -152,7 +152,7 @@
<td>
<div align="left">
To run the online-mode tests for say the modules/integration
- Run "maven itest" from modules/intergration</div>
+ Run "maven itest" from modules/integration</div>
</td>
</tr>
<tr>
Modified: webservices/axis2/trunk/java/xdocs/http-transport.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/http-transport.html?rev=290351&r1=290350&r2=290351&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/http-transport.html (original)
+++ webservices/axis2/trunk/java/xdocs/http-transport.html Mon Sep 19 21:29:37 2005
@@ -1,43 +1,42 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
- <title>HTTP transports</title>
-</head>
-<body>
-<h1><a name="#configTransport">HTTP
-transports</a></h1>
-<h3>CommonsHTTPTransportSender</h3>
-<p>This is the default transport
-sender that is being used in Server API as well as Client
-API. HTTP
-funtionality of the Sender is based on commons-httpclient-3.0-rc3. In
-order to aquire the maxium flexibiliy, this sender has implemented POST
-interface and GET interface. This is mainly due to the fact that Axis2
-SOAP stack has the tendency to support REST based services as well. </p>
-<p>
-Chunking support and KeepAlive support also integrated via the
-facilities provided by commons. It has the tendency to support HTTP
-version 1.0 and 1.1. As Chunking support is only available in HTTP
-version 1.1, thus, this distiction in sperating the tranport version
-is important.
-</p>
-<p>
-Tranport Sender sets in the axis2.xml's
-<tranposrtSender/>
-element, and it's being declared as follows,
-</p>
-<pre><transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"><br> <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.1</parameter><br> <parameter name="Transfer-Encoding">chunked</parameter><br></transportSender><br></pre>
-<code></code>
-<p>Above code snippet shows the
-complete configuration of the transport sender.
-<parameter/> element introduces the additional paraments
-that should be complient with the sender. HTTP PROTOCOL version sets as
-HTTP/1.0 or HTTP/1.1. Default version is HTTP/1.1. It should be noted
-that Chunking support is available at HTTP/1.1. Thus, the user should
-be careful of setting the "chunked" property only with version 1.1.
-KeepAlive is default in version 1.1. </p>
-<p>These are the only paramenters
-that is available from deployment. Other parameters such as character
-encoding style etc, are provided via MessageContext. </p>
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>HTTP transports</title>
+</head>
+
+<body lang="en">
+<h1><a name="#configTransport">HTTP transports</a></h1>
+
+<h3>CommonsHTTPTransportSender</h3>
+
+<p>This is the default transport sender that is being used in Server API as
+well as Client API. HTTP functionality of the Sender is based on
+commons-httpclient-3.0-rc3. In order to acquire the maximum flexibility, this
+sender has implemented POST interface and GET interface. This is mainly due
+to the fact that Axis2 SOAP stack has the tendency to support REST based
+services as well. </p>
+
+<p>Chunking support and KeepAlive support also integrated via the facilities
+provided by commons. It has the tendency to support HTTP version 1.0 and 1.1.
+As chunking support is only available in HTTP version 1.1, thus, this
+distinction in seperating the transport version is important.</p>
+
+<p>Transport Sender sets in the axis2.xml's <transportSender/> element,
+and it's being declared as follows,</p>
+<pre><transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"><br> <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.1</parameter><br> <parameter name="Transfer-Encoding">chunked</parameter><br></transportSender><br></pre>
+<code></code>
+
+<p>Above code snippet shows the complete configuration of the transport
+sender. <parameter/> element introduces the additional parameters that
+should be compliant with the sender. HTTP PROTOCOL version sets as HTTP/1.0
+or HTTP/1.1. Default version is HTTP/1.1. It should be noted that chunking
+support is available at HTTP/1.1. Thus, the user should be careful of setting
+the "chunked" property only with version 1.1. KeepAlive is default in version
+1.1. </p>
+
+<p>These are the only parameters that is available from deployment. Other
+parameters such as character encoding style etc, are provided via
+MessageContext.</p>
+</body>
+</html>
Modified: webservices/axis2/trunk/java/xdocs/installationguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/installationguide.html?rev=290351&r1=290350&r2=290351&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/installationguide.html (original)
+++ webservices/axis2/trunk/java/xdocs/installationguide.html Mon Sep 19 21:29:37 2005
@@ -1,122 +1,156 @@
-<!-- saved from url=(0022)http://internet.e-mail -->
-<html>
-<head>
-<title>Axis2 Installation Guide</title>
-</head>
-<body>
-<h3><a name="_Toc96698081"></a>Introduction </h3>
-<p>Axis 2.0 can be downloaded as a <a href="releases.html">zipped binary </a>
-or the <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN">source </a>.
-This section describes how Axis2 can be installed either as a
-standalone server or as part of a J2EE compliant servlet container. </p>
-
-<h3><a name="_Toc96698082"></a>Prerequisites </h3>
-<p>Axis2 requires the Java Runtime Environment to be properly
-installed. Axis2 is developed to be run on JRE 1.4 and upwards but it
-has not been fully tested with the latest JRE 1.5. Hence it is safe to
-run Axis2 with Java 1.4. If the JRE is not already in place it must be
-installed to proceed further. For instructions on setting up the JRE in
-different operating systems, please visit <a href="http://java.sun.com/">http://java.sun.com </a>. </p>
-<p>All the required jars are shipped with the binary distribution and
-if the source distribution is used, running the maven build will
-automatically download the required jars for you. </p>
-<p>Following sections describe how each type of distribution needs to
-be installed. Since the process with the source distribution is similar
-to the binary distribution after building, the first section explains
-the process of building Axis2 from source. If you have the binary
-distribution you can skip the build sections and directly go to the
-binary installation section. </p>
-<h3><a name="_Toc96698083"></a>Building Axis2 from source </h3>
-<h4><a name="_Toc96698084"></a>Setting up the Environment and the tools </h4>
-<p>The Axis2 build is based on <a href="http://maven.apache.org/">Maven </a>.
-Hence the only prerequisite to build Axis2 from source distribution is to have Maven
-installed. Even though extensive instruction guides are available at
-the Maven site, this guide also contains the easiest path for quick
-environment setting. Advanced users who wish to know more about Maven
-can visit <a href="http://maven.apache.org/start/index.html">here </a>. </p>
-
-<p>For Windows users the easiest way is to download the windows
-installer package. Once the installer package is run, all the necessary
-environment variables will be properly set. Once Maven is installed,
-the success of the installation can be tested by typing maven
-version in the command prompt. </p>
-<p align="center">
-<img alt="clip_image002 (15K)" src="images/clip_image002.jpg" height="211" width="477"/>
-<p> </p>
-<p>
-For Unix/Linux users the tar ball or the zip archive is the best
-option. Once the archive is downloaded expand it to a directory of
-choice and set the environment variable MAVEN_HOME and add
-MAVEN_HOME/bin to the path as well. More instructions for installing
-Maven in Unix based operating systems can be found <a href="http://maven.apache.org/start/install.html">here </a>. </p>
-<p>Once maven is properly installed it's all that is needed to start building Axis2. </p>
-<h4><a name="_Toc96698085"></a>The Axis2 source distribution </h4>
-<p>The <a href="releases.html">source distribution </a> is available as
-a zipped archive. All the necessary build scripts are
-included with the source distribution. Once the source archive is
-expanded into a directory of choice, moving to the particular directory
-and running maven command will build the Axis2 jar file. </p>
-
-<p align="center"><img alt="clip_image004 (43K)" src="images/maven.jpg" height="338" width="669" /></p>
-<p>Once the command completes, the binaries (jar files in this case) can be found at a newly created "target" directory. </p>
-<p><strong>Note For the first Maven build (if the maven repository is
-not built first) it will take a while since required jars need to be
-downloaded. However this is a once only process and will not affect any
-successive builds. </strong></p>
-<p><strong> </strong>The default maven build will however build only
-the Axis2 jar file. To obtain a WAR (Web Archive), "maven war" command
-should be issued. This will create a complete WAR with the name
-axis2.war inside the target directory. </p>
-<p>Once this build step is complete, the binaries are ready to be deployed. </p>
-<h3><a name="_Toc96698086"></a>Installing Axis2 in a Servlet container </h3>
-<p>Installation of the WAR is quite simple. It's a matter of dropping
-the war in the webapps folders and most servlet containers will
-automatically install the war. However some servlet containers may
-require a restart in order to capture the new web application. Please
-refer your servlet container documentation for more information about
-this. </p>
-<p>Once the WAR is successfully installed it can be tested by pointing the web
-browser to the <strong>http:// <host :port>/ axis2. </strong>It should produce the following page.
-</p>
-<p align="center"><strong><img src="images/clip_image006.jpg"></strong></p>
-<p>
-To ensure that everything is fine and smooth, a probing of the system can be done
-through the validate link. If the validation fails then the war has failed to
-install properly or some essential jars are missing. At such a situation the
-documentation of the particular servlet container should be consulted to find
-the problem. The following page is a successful validation. Note the statement
-core Axis2 libraries are present.
-</p>
-<p align="center"><strong><img src="images/happyaxis.jpg"></strong></p>
-<p>
-The Axis2 web application also provides an interface to upload services.
-Once a service is created according to the service specification as described in
-userguide that jar file can be uploaded using the upload page.
-</p>
-<p align="center"><strong><img src="images/clip_image010.jpg"></strong></p>
-<p>The uploaded jar files will be stored in the default service
-directory. For Axis2 this will be the
-<webapps>/axis2/WEB-INF/services directory. Once a service is
-uploaded it will be instantly installed. </p>
-<p>Since Axis2 supports hot deployment one can drop the service jar
-directly through the file system to the above mentioned services
-directory and it will also cause the service to be automatically
-installed without the container being restarted. </p>
-
-<p>To check the successful installation of a service <strong><em>available services link </em></strong>
-is provided. The services and the operations of successfully installed
-services will be displayed in the available services page.</p>
-<p align="center"><strong><img src="images/clip_image012.jpg"></strong></p>
-<p>If the service has deployment time error it will listed out those services as faulty services.
-And If you click on the link it will show your the deployment fault</p>
-<p align="center"><strong><img src="images/faultservice.jpg"></strong></p>
-<p>Deployment time error message</P>
-<p align="center"><strong><img src="images/faultmsg.jpg"></strong></p>
-
-<p> </p>
-<p> </p>
-<p>Axis2 Administration is all about configuring Axis2 at the run time and
-the configuration will be transient , and more descriptions are avilable in
-<a href="webadminguide.html">Axis2 admin web guide</a></p>
-</body>
-</html>
+<!-- saved from url=(0022)http://internet.e-mail -->
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Installation Guide</title>
+</head>
+
+<body lang="en">
+<h3><a name="_Toc96698081"></a>Introduction</h3>
+
+<p>Axis 2.0 can be downloaded as a <a href="releases.html">zipped binary </a>
+or the <a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN">source
+</a>. This section describes how Axis2 can be installed either as a
+standalone server or as part of a J2EE compliant servlet container.</p>
+
+<h3><a name="_Toc96698082"></a>Prerequisites</h3>
+
+<p>Axis2 requires the Java Runtime Environment to be properly installed.
+Axis2 is developed to be run on JRE 1.4 and upwards but it has not been fully
+tested with the latest JRE 1.5. Hence it is safe to run Axis2 with Java 1.4.
+If the JRE is not already in place it must be installed to proceed further.
+For instructions on setting up the JRE in different operating systems, please
+visit <a href="http://java.sun.com/">http://java.sun.com </a>.</p>
+
+<p>All the required jars are shipped with the binary distribution and if the
+source distribution is used, running the maven build will automatically
+download the required jars for you.</p>
+
+<p>Following sections describe how each type of distribution needs to be
+installed. Since the process with the source distribution is similar to the
+binary distribution after building, the first section explains the process of
+building Axis2 from source. If you have the binary distribution you can skip
+the build sections and directly go to the binary installation section.</p>
+
+<h3><a name="_Toc96698083"></a>Building Axis2 from source</h3>
+
+<h4><a name="_Toc96698084"></a>Setting up the Environment and the tools</h4>
+
+<p>The Axis2 build is based on <a href="http://maven.apache.org/">Maven </a>.
+Hence the only prerequisite to build Axis2 from source distribution is to
+have Maven installed. Even though extensive instruction guides are available
+at the Maven site, this guide also contains the easiest path for quick
+environment setting. Advanced users who wish to know more about Maven can
+visit <a href="http://maven.apache.org/start/index.html">here </a>.</p>
+
+<p>For Windows users the easiest way is to download the windows installer
+package. Once the installer package is run, all the necessary environment
+variables will be properly set. Once Maven is installed, the success of the
+installation can be tested by typing maven version in the command prompt.</p>
+
+<p align="center"><img alt="clip_image002 (15K)"
+src="images/clip_image002.jpg" height="211" width="477"></p>
+
+<p> </p>
+
+<p>For Unix/Linux users the tar ball or the zip archive is the best option.
+Once the archive is downloaded expand it to a directory of choice and set the
+environment variable MAVEN_HOME and add MAVEN_HOME/bin to the path as well.
+More instructions for installing Maven in Unix based operating systems can be
+found <a href="http://maven.apache.org/start/install.html">here </a>.</p>
+
+<p>Once maven is properly installed it's all that is needed to start building
+Axis2.</p>
+
+<h4><a name="_Toc96698085"></a>The Axis2 source distribution</h4>
+
+<p>The <a href="releases.html">source distribution </a> is available as a
+zipped archive. All the necessary build scripts are included with the source
+distribution. Once the source archive is expanded into a directory of choice,
+moving to the particular directory and running maven command will build the
+Axis2 jar file.</p>
+
+<p align="center"><img alt="clip_image004 (43K)" src="images/maven.jpg"
+height="338" width="669"></p>
+
+<p>Once the command completes, the binaries (jar files in this case) can be
+found at a newly created "target" directory.</p>
+
+<p><strong>Note For the first Maven build (if the maven repository is not
+built first) it will take a while since required jars need to be downloaded.
+However this is a once only process and will not affect any successive
+builds.</strong></p>
+
+<p><strong></strong>The default maven build will however build only the Axis2
+jar file. To obtain a WAR (Web Archive), "maven war" command should be
+issued. This will create a complete WAR with the name axis2.war inside the
+target directory.</p>
+
+<p>Once this build step is complete, the binaries are ready to be
+deployed.</p>
+
+<h3><a name="_Toc96698086"></a>Installing Axis2 in a Servlet container</h3>
+
+<p>Installation of the WAR is quite simple. It's a matter of dropping the war
+in the webapps folders and most servlet containers will automatically install
+the war. However some servlet containers may require a restart in order to
+capture the new web application. Please refer your servlet container
+documentation for more information about this.</p>
+
+<p>Once the WAR is successfully installed it can be tested by pointing the
+web browser to the <strong>http:// <host :port>/ axis2. </strong>It
+should produce the following page.</p>
+
+<p align="center"><strong><img src="images/clip_image006.jpg"></strong></p>
+
+<p>To ensure that everything is fine and smooth, a probing of the system can
+be done through the validate link. If the validation fails then the war has
+failed to install properly or some essential jars are missing. At such a
+situation the documentation of the particular servlet container should be
+consulted to find the problem. The following page is a successful validation.
+Note the statement core Axis2 libraries are present.</p>
+
+<p align="center"><strong><img src="images/happyaxis.jpg"></strong></p>
+
+<p>The Axis2 web application also provides an interface to upload services.
+Once a service is created according to the service specification as described
+in userguide that jar file can be uploaded using the upload page.</p>
+
+<p align="center"><strong><img src="images/clip_image010.jpg"></strong></p>
+
+<p>The uploaded jar files will be stored in the default service directory.
+For Axis2 this will be the <webapps>/axis2/WEB-INF/services directory.
+Once a service is uploaded it will be instantly installed.</p>
+
+<p>Since Axis2 supports hot deployment one can drop the service jar directly
+through the file system to the above mentioned services directory and it will
+also cause the service to be automatically installed without the container
+being restarted.</p>
+
+<p>To check the successful installation of a service <strong><em>available
+services link </em></strong> is provided. The services and the operations of
+successfully installed services will be displayed in the available services
+page.</p>
+
+<p align="center"><strong><img src="images/clip_image012.jpg"></strong></p>
+
+<p>If the service has deployment time error it will listed out those services
+as faulty services. And If you click on the link it will show your the
+deployment fault</p>
+
+<p align="center"><strong><img src="images/faultservice.jpg"></strong></p>
+
+<p>Deployment time error message</p>
+
+<p align="center"><strong><img src="images/faultmsg.jpg"></strong></p>
+
+<p> </p>
+
+<p> </p>
+
+<p>Axis2 Administration is all about configuring Axis2 at the run time and
+the configuration will be transient , and more descriptions are available in
+<a href="webadminguide.html">Axis2 admin web guide</a></p>
+</body>
+</html>