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 2006/05/15 07:51:47 UTC
svn commit: r406543 [1/6] - in /webservices/axis2/trunk/java/xdocs/latest:
./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/
resources/ resources/schemas/
Author: chatra
Date: Sun May 14 22:51:17 2006
New Revision: 406543
URL: http://svn.apache.org/viewcvs?rev=406543&view=rev
Log:
creating latest dir with post 1.0 documents
Added:
webservices/axis2/trunk/java/xdocs/latest/
webservices/axis2/trunk/java/xdocs/latest/Axis2ArchitectureGuide.html
webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html
webservices/axis2/trunk/java/xdocs/latest/WS_policy.html
webservices/axis2/trunk/java/xdocs/latest/adb/
webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html
webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html
webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html
webservices/axis2/trunk/java/xdocs/latest/adb/images/
webservices/axis2/trunk/java/xdocs/latest/adb/images/ADB.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/axis2config.html
webservices/axis2/trunk/java/xdocs/latest/http-transport.html
webservices/axis2/trunk/java/xdocs/latest/images/
webservices/axis2/trunk/java/xdocs/latest/images/Architecture.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/AxisService.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/Component.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM001.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM002.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM003.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM004.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM005.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM006.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM007.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM008.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/OM1.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/ServerSideFault.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/ServiceDesc.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/TotalArch.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/WomBuilder.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/activate.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/admin.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/adminlogin.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/adminmain.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/ant.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/CodegenArchitecture.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/all.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/big-picture.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/contexts.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/phases.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/soap-processing.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi-guide/soap.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi001.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi002.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi003.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi004.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi005.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi006.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi007.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi008.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi009.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi010.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi011.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi012.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi013.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi014.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi015.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi016.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi017.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi018.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi019.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi020.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi021.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi022.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi023.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi024.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi025.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/archi026.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/arrow_left.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/arrow_right.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/axis.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/ayncresult.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/call.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/callback.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/cases.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clientAPi.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clientside.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image002.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image004.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image006.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image008.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image010.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image012.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image014.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image016.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image018.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image020.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image022.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image024.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/clip_image026.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/codegen.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/correlator.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/deploymetncomponent.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/editserviecpara.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/engine1.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/faultmsg.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/faultservice.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/globalchain.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/happyaxis.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image001.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image002.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image003.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image004.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image005.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image005.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image006.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image007.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image008.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image009.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image010.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image011.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image012.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/image013.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/inactivate.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/maven.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/module.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/moduleengage.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/modules.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/new.gif (with props)
webservices/axis2/trunk/java/xdocs/latest/images/om2.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/om3.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/parameters.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/select_service_for_handler.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/send.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/sendAsync.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/sendRecievce.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/sendRecieveAsync.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/sendRecieveWithListnere.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/serverSide.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/service.png (with props)
webservices/axis2/trunk/java/xdocs/latest/images/serviceHandlers.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/servicegroups.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/
webservices/axis2/trunk/java/xdocs/latest/images/userguide/DirectoryStructure.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/ModuleView.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/MyServiceDeployed.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/ServiceDeployed.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/ServiceItems.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/TestClient.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/userguide/http-get-ws.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/viewphases.jpg (with props)
webservices/axis2/trunk/java/xdocs/latest/images/wom.png (with props)
webservices/axis2/trunk/java/xdocs/latest/index.html
webservices/axis2/trunk/java/xdocs/latest/installationguide.html
webservices/axis2/trunk/java/xdocs/latest/jibx/
webservices/axis2/trunk/java/xdocs/latest/jibx/jibx-codegen-integration.html
webservices/axis2/trunk/java/xdocs/latest/mail-configuration.html
webservices/axis2/trunk/java/xdocs/latest/mail-transport.html
webservices/axis2/trunk/java/xdocs/latest/migration.html
webservices/axis2/trunk/java/xdocs/latest/mtom-guide.html
webservices/axis2/trunk/java/xdocs/latest/resources/
webservices/axis2/trunk/java/xdocs/latest/resources/schemas/
webservices/axis2/trunk/java/xdocs/latest/resources/schemas/module.xsd
webservices/axis2/trunk/java/xdocs/latest/resources/schemas/services.xsd
webservices/axis2/trunk/java/xdocs/latest/rest-ws.html
webservices/axis2/trunk/java/xdocs/latest/soapmonitor-module.html
webservices/axis2/trunk/java/xdocs/latest/tcp-transport.html
webservices/axis2/trunk/java/xdocs/latest/transport_howto.html
webservices/axis2/trunk/java/xdocs/latest/userguide.html
webservices/axis2/trunk/java/xdocs/latest/userguide1.html
webservices/axis2/trunk/java/xdocs/latest/userguide2.html
webservices/axis2/trunk/java/xdocs/latest/userguide3.html
webservices/axis2/trunk/java/xdocs/latest/userguide4.html
webservices/axis2/trunk/java/xdocs/latest/userguide5.html
webservices/axis2/trunk/java/xdocs/latest/webadminguide.html
Added: webservices/axis2/trunk/java/xdocs/latest/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/Axis2ArchitectureGuide.html?rev=406543&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/Axis2ArchitectureGuide.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/Axis2ArchitectureGuide.html Sun May 14 22:51:17 2006
@@ -0,0 +1,732 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Architecture Guide</title>
+ <meta content="20050916;22455288">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1 align="center">Apache Axis2 Architecture Guide</h1>
+
+<p><i>-Axis2 Version 1.0</i></p>
+
+<p>This document will give an introduction to Axis2's modular architecture
+with explanations on every module.</p>
+
+<p><i>Send your feedback to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<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 Architecture</a>
+ <ul>
+ <li><p><a href="#bmcore">Core Modules</a></p>
+ </li>
+ <li><a href="#bmother">Other Modules</a></li>
+ <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 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>Ability to deploy a Web service (with or without WSDL)</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>Ability to configure Axis2 and it's components via deployment.</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 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/other modules are layered on top of this core
+modules/architecture.</p>
+<a name="bmother"></a>
+
+<h3>Core Modules:</h3>
+<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 sub-project itself, under Web
+ service project, allowing that sub-project (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>
+<a name="bmcore"></a>
+
+<h3>Other Modules:</h3>
+<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><b>In</b> Pipe</i> and <i><b>Out</b>
+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>
+
+<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 from 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><strong>Transport Phase</strong> - The handlers are in the phase meant
+ to process transport specific information such as validating incoming
+ message by looking at various transport headers, add data into message
+ context etc.</li>
+ <li><strong>Pre-Dispatch Phase</strong>- 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 of the
+ SOAP message happen in this phase.Addressing handlers extract information
+ and put them in to the message context.</li>
+ <li><strong>Dispatch Phase</strong> - The Dispatchers run in this phase and
+ tries to find the correct service and operation this particular message
+ is destined to.<br>
+ The post condition of the dispatch phase (any phase can contain a post
+ condition) checks whether a service and an operation was found by the
+ dispatchers. If not the execution will halt and throws out a "service not
+ found error".</li>
+ <li><strong>User Defined Phases</strong> - 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><strong>Message Processing Phase</strong> - 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 endpoint.</li>
+</ol>
+
+<h3><a name="extending">Extending SOAP Processing Model</a></h3>
+
+<p>Above we discussed the default processing model of Axis2. Now let us
+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. This enables modification on the default processing behavior.
+SOAP Processing Model can be extended with <a
+href="#extendingwithhandlers">handler</a> or <a
+href="#extendingwithmodules">modules</a>.</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 includes</p>
+<ul>
+ <li>a set of handlers and</li>
+ <li>an associated descriptor which includes the phase rules</li>
+</ul>
+. 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>Apart from the extension mechanism based on the handlers, the WS-*
+specifications may 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. 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 engaged them.</p>
+
+<p>Modules can not be added (no hot deployment) 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/<a
+href="resources/schemas/services.xsd">services.xml</a></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/<a
+href="resources/schemas/module.xsd">module.xml</a> 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 that the corresponding services and modules are
+added to the Axis Configuration. System will build contexts on top of the
+Axis Configurations. After this Axis2 is ready to send or receive the SOAP
+messages. Hot deployment is only allowed for services.</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 MEPs are One-Way and the In-Out (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> method
+of <code>ServiceClient</code>. For one way invocations one can use HTTP ,
+SMTP and TCP transports. In the case of the HTTP transport the return channel
+is not used and the HTTP 202 OK is returned in the return Channel.</p>
+<a name="requestresponse"></a>
+
+<h3>In-Out (Request Response) Messaging Support</h3>
+
+<p>The In-Out support is provided by the <code>sendReceive()</code> method in
+ServiceClient. This 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, namely; Transport Senders
+and Transport Receivers . These are accessed via the AxisConfiguration.</p>
+
+<p>The incoming transport is the transport via which the AxisEngine receives
+the message. The outgoing transport is decided based on the addressing
+information (wsa:ReplyTo and wsa:FaultTo). If addressing information is not
+available and if server is trying to respond, 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, 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>
+ <li>JMS</li>
+</ol>
+<a name="bmWSDL" id="bmWSDL"></a>
+
+<h2>Code Generation</h2>
+
+<p>Although the basic objective of the code generation tools 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. First, an AxisService is populated
+from a WSDL. Then the code generator extracts information from the
+AxisService and creates an XML which is language independent. This emitted
+XML is then parsed with the relevant XSL to generate code for the relevant
+language. No matter what the output 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>
+
+<h3>Integration with Code Generation Engine</h3>
+
+<p>Databinding for Axis2 is implemented in an interesting manner. Databinding
+has not been included in the core deliberately and hence the code geneation
+allows different data binding frameworks to be plugged in. This is done
+through an extension mechanism where the codegen engine calls extensions
+first and then executes the core emitter. The extensions populate a map of
+QNames vs. class names that is passed to the code generator on which the
+emitter operates on.</p>
+
+<p><strong>The following diagram shows the structure:</strong></p>
+
+<p><img src="images/codegen.gif" name="Graphic7" align="bottom" width="406"
+alt="" height="467" border="0"></p>
+
+<p><strong>The following databinding extensions are available:</strong></p>
+<ol>
+ <li><strong>ADB</strong> - ADB (Axis Data Binding ) is a simple framework
+ that allows simple schemas to be compiled. It is lightweight and simple,
+ works off StAX and fairly performant. However, it does not support the
+ complete set of schema constructs and is likely to complain for certain
+ schemas!</li>
+ <li><strong>XMLBeans</strong> - XMLbeans claims that it supports the
+ complete schema specification and it is the choice, if full schema
+ support is needed!</li>
+ <li><strong>JAX-Me</strong> - JaxMe support has been added in a similar
+ manner to XMLbeans and serves as another option for the user</li>
+ <li><strong>JibX</strong> - This is the most recent addition to the family
+ of databinding extensions and it is also another option the users have
+ for data binding.</li>
+</ol>
+
+<h3><a name="serial" id="serial">Serialization and De-Serialization of Data
+bound classes</a></h3>
+
+<p>AXIOM is based on a StAX API (Streaming API for XML). 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 utility methods generated
+inside the stub (or the message receiver) that can de-serialize 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
+the following methods will be generated inside the relevant classes.</p>
+
+<pre>public static
+org.apache.axiom.om.OMElementtoOM(org.soapinterop.xsd.EchoStringParamDocument
+param)// This method will handle the serialization.
+
+public static org.apache.xmlbeans.XmlObject
+fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This
+method will handle the de-serialization.</pre>
+
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html?rev=406543&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html Sun May 14 22:51:17 2006
@@ -0,0 +1,727 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>OM Tutorial</title>
+ <link href="css/axis-docs.css" type="text/css" rel="stylesheet">
+</head>
+
+<body>
+<!-- Header section
+<table width="100%">
+<tr>
+<td align="left"><h1>Apache Axis2</h1></td>
+<td align="right"><img alt="" src="images/axis2.jpg"/></td>
+</tr>
+</table>
+end of header section -->
+
+<h1>AXIOM Tutorial</h1>
+
+<p>This document will contain information on the Object Model of Axis2. The
+information include an introduction to AXIOM and it's functionalities, data
+on some advanced options and limitations of OM.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a>
+ <ul>
+ <li><a href="#OM">What is OM?</a></li>
+ <li><a href="#whom">For whom is this Tutorial?</a></li>
+ <li><a href="#pull">What is Pull Parsing?</a></li>
+ <li><a href="#history">A Bit of History</a></li>
+ <li><a href="#features">Features of OM</a></li>
+ <li><a href="#caching">A Bit About Caching</a></li>
+ <li><a href="#SOAP">Where Does SOAP Come into Play?</a></li>
+ </ul>
+ </li>
+ <li><a href="#working">Working with OM</a>
+ <ul>
+ <li><a href="#om_binary">Obtaining the OM binary</a></li>
+ <li><a href="#creation">Creation</a></li>
+ <li><a href="#nodes">Addition of Nodes</a></li>
+ <li><a href="#traversing">Traversing</a></li>
+ </ul>
+ </li>
+ <li><a href="#advanced">Advanced Operations with OM</a>
+ <ul>
+ <li><a href="#OMNavigator">Use of the OMNavigator for Traversal</a></li>
+ <li><a href="#access_pullparser">Accessing the Pull Parser</a></li>
+ <li><a href="#OMNavigator">Use of the OMNavigator for Traversal</a></li>
+ </ul>
+ </li>
+ <li><a href="#limitations">Known Limitations of OM</a>
+ <ul>
+ <li><a href="#namespace_serialization">Inefficient Namespace
+ serialization</a></li>
+ </ul>
+ </li>
+ <li><a href="#summary">Summary</a></li>
+ <li><a href="#appendix">Appendix</a>
+ <ul>
+ <li><a href="#program_listing">Program Listing for complete OM - build
+ and serialize</a></li>
+ </ul>
+ </li>
+ <li><a href="#links">Links</a></li>
+</ul>
+<a name="intro"></a>
+
+<h2>Introduction</h2>
+<a name="OM"></a>
+
+<h3>What is OM?</h3>
+
+<p>OM stands for Object Model (also known as AXIOM - AXis Object Model) and
+refers to the XML infoset model that is initially developed for Apache Axis2.
+XML infoset refers to the information included inside the XML and for
+programmatical manipulation it is convenient to have a representation of this
+XML infoset in a language specific manner. For an object oriented language
+the obvious choice is a model made up of objects. DOM and <a
+href="http://www.jdom.org/">JDOM</a> are two such XML models. OM is
+conceptually similar to such an XML model by its external behavior but deep
+down it is very much different. The objective of this tutorial is to
+introduce the basics of OM and explain the best practices to follow while
+using OM. However before entering the deep end of OM it is better to skim the
+surface and see what it is all about!</p>
+<a name="whom"></a>
+
+<h3>For Whom is this Tutorial?</h3>
+
+<p>This tutorial can be used by anybody who is interested in OM and need to
+go deeper in it. However it is assumed that the reader has a basic
+understanding of the concepts of XML (such as <a
+href="http://www.w3.org/TR/REC-xml-names/">Namespaces</a>) and a working
+knowledge of tools such as <a href="http://ant.apache.org/">Ant</a>.
+Knowledge in similar object models such as DOM will be quite helpful in
+understanding OM but such knowledge is not assumed. Several Links are listed
+in the appendix/ links section that will help understand the basics of
+XML.</p>
+<a name="pull"></a>
+
+<h3>What is Pull Parsing?</h3>
+Pull parsing is a recent trend in XML processing. The previously popular XML
+processing frameworks such as SAX and DOM were "push-based" which means the
+control of the parsing was with the parser itself. This approach is fine and
+easy to use but it was not efficient in handling large XML documents since a
+complete memory model will be generated in the memory. Pull parsing inverts
+the control and hence the parser only proceeds at the users command. The user
+can decide to store or discard events generated from the parser. OM is based
+on pull parsing. To learn more about XML pull parsing see the <a
+href="http://www.bearcave.com/software/java/xml/xmlpull.html">XML pull
+parsing introduction</a>. <a name="history"></a>
+
+<h3>A Bit of History</h3>
+
+<p>The original OM was proposed as a store for the pull parser events for
+later processing, at the Axis summit held in Colombo, Sri Lanka, in September
+2004. However this approach was soon improved and OM was pursued as a
+complete info set model due to its flexibility. Several implementation
+techniques were attempted during the initial phases. The two most promising
+techniques were the table based technique and the link list based technique.
+During the intermediate performance tests the link list based technique
+proved to be much more memory efficient for smaller and mid sized XML
+documents (the advantage of the table based OM was only visible for the large
+and very large XML documents) and hence the link list based technique was
+chosen as the most suitable. Initial efforts were focused on implementing the
+XML info set items which are relevant to the SOAP specification (DTD support,
+Processing Instruction support, etc were not considered). The advantage of
+having a tight integration was evident at this stage and this resulted in
+having SOAP specific interfaces as part of OM rather than a layer on top of
+it. OM was deliberately made API centric. It allows the implementations to
+take place independently and swapped without affecting the program later.</p>
+<a name="features"></a>
+
+<h3>Features of OM</h3>
+
+<p>OM is a lightweight, differed built XML info set representation based on
+StAX (<a href="http://www.jcp.org/en/jsr/detail?id=173">JSR 173</a>), which
+is the standard streaming pull parser API. The object model can be
+manipulated as flexibly as any other object model (Such as <a
+href="http://www.jdom.org/">JDOM</a>), but underneath the objects will be
+created only when they are absolutely required. This leads to much less
+memory intensive programming. Following is a short feature overview of OM.</p>
+<ul>
+ <li>Lightweight: OM is specifically targeted to be lightweight. This is
+ achieved by reducing the depth of the hierarchy, number of methods and
+ the attributes enclosed in the objects. This makes the objects less
+ memory intensive.</li>
+ <li>Differed building: By far this is the most important feature of OM. The
+ objects are not made unless a need arises for them. This passes the
+ control of building over to the object model itself rather than an
+ external builder.</li>
+ <li>Pull based: For a differed building mechanism a pull based parser is
+ required. OM is based on StAX, the standard pull parser API.</li>
+</ul>
+<!-- Special section -->
+
+<p class="special"></p>
+
+<table width="100%">
+ <tbody>
+ <tr>
+ <td><img src="images/OM005.gif" alt="Remember this" width="35"
+ height="57"></td>
+ <td class="special-td">OM is tightly bound to StAX API. To work with OM
+ a StAX compliant parser and the API <i>must</i> be present in the
+ classpath.</td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+<!-- End of special section -->
+
+<p>The Following image shows how OM API is viewed by the user</p>
+<!-- Image -->
+
+<p align="center" class="img"><img alt="" src="images/archi006.jpg"
+class="img" width="490" height="282"></p>
+
+<p align="center" class="img-title">Figure 1</p>
+<!-- End of Image -->
+
+<p>OM Builder wraps the raw xml character stream through the StAX reader API.
+Hence the complexities of the pull event stream is transparent to the
+user.</p>
+<a name="caching"></a>
+
+<h3>A Bit About Caching</h3>
+
+<p>Since OM is a differed built object model, It incorporates the concept of
+caching. Caching refers to the creation of the objects while parsing the pull
+stream. The reason why this is so important is because caching can be turned
+off in certain situations. If so the parser proceeds without building the
+object structure. User can extract the raw pull stream from OM and use that
+instead of the OM. In this case it is sometimes beneficial to switch off
+caching. The advanced operations section explains more on accessing the raw
+pull stream and switching the caching on and off.</p>
+<a name="SOAP"></a>
+
+<h3>Where Does SOAP Come into Play?</h3>
+
+<p>In a nutshell SOAP is an information exchange protocol based on XML. SOAP
+has a defined set of XML elements that should be used in messages. Since Axis
+is a "SOAP Engine" and OM is built for Axis, A set of SOAP specific objects
+were also defined along with OM. These SOAP Objects are extensions of the
+general OM objects. See <a
+href="http://www.w3schools.com/SOAP/soap_intro.asp"> here </a> to learn more
+about SOAP.</p>
+<!--<p>This abstraction provides</p>
+<ul>
+<li>differed building support</li>
+<li>Caching</li>
+</ul>
+<p>AXIOM has the flexibility to plug in any builder which implements the given builders interface. The upcoming sections of this tutorial deal with the creation and usage of OM for manipulating SOAP (and to some extent nonSOAP) based XML documents.</p>
+-->
+<a name="working"></a>
+
+<h2>Working with OM</h2>
+<a name="om_binary"></a>
+
+<h3>Obtaining the OM Binary</h3>
+
+<p>The easiest way to obtain the OM binary is to download the latest release
+from <a href="http://ws.apache.org/commons/axiom/download.cgi">here</a>
+However more adventurous users can build the OM from source, which is
+described in the next section.</p>
+
+<p>Detailed information on getting source from Axis2 SVN repository can be
+found <a href="../svn.html" target="_blank">here</a>.</p>
+
+<p>After the source download, OM-binary can be built. For both Windows and
+Linux move it to the project directory and execute the command "maven jar".
+All other necessary jars will be automatically downloaded. <em> </em><font
+color="red"><span style="color: #000000">When the build finishes
+successfully, the <span style="color: #000000">axiom-api-<version>.jar</span>
+and <span style="color: #000000">axiom-impl-<version>.jar</span> can be found
+in the newly created "targets" directory.</span></font></p>
+
+<p>Once the OM-binary is obtained by any of the above ways , it should be
+included in the classpath for any of the OM based programs to work.
+Subsequent sections of this tutorial assume that this build step is complete
+and the jar files, axiom-api-.jar and axiom-impl-.jar are present in the
+classpath along with the StAX API jar file and a StAX implementation.</p>
+<a name="creation"></a>
+
+<h3>Creation</h3>
+
+<p>Creation is the first and foremost action when using an Object
+representation. This part explains how OM can be built from an existing
+document or just programmatically. OM provides a notion of a factory and a
+builder to create objects. The factory helps to keep the code at the
+interface level and the implementations separately (Figure 2). Since OM is
+tightly bound to StAX, a StAX compliant reader should be created first with
+the desired input stream. Then one can select one of the different builders
+available. StAXOMBuilder will build pure XML infoset compliant object model
+whilst the SOAPModelBuilder returns SOAP specific objects (such as the
+SOAPEnvelope, which are sub classes of the OMElement) through its builder
+methods and . The following piece of code shows the correct method of
+creating an OM document from an input stream.</p>
+
+<div align="left">
+<p><b>Code Listing 1</b></p>
+</div>
+<source><pre>//create the parser<br>
+XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(file));
+<br>//create the builder<br>
+StAXOMBuilder builder = new StAXOMBuilder(parser);
+//get the root element (in this case the envelope)<br>
+OMElement documentElement = builder.getDocumentElement();</pre>
+</source>
+<p>As the example shows, creating an OM from an input stream is pretty
+straightforward. However elements and nodes can be created programmatically
+to modify the structure as well. The recommended way to create OM objects
+programmatically is to use the factory. OMAbstractFactory.getOMFactory() will
+return the proper factory and the creator methods for each type should be
+called. Currently OM has two builders, namely the OM builder (StAXOMBuilder)
+and the SOAP model builder (StAXSOAPModelBuilder). These builders provide the
+necessary information to the XML info set model to build itself.</p>
+<!-- Image -->
+
+<p class="img"><img src="images/archi007.jpg" alt="OM Structure 2"
+class="img" width="420" height="246"></p>
+
+<p class="img-title">Figure 2</p>
+<!-- End of Image -->
+
+<p>A simple example is shown below.</p>
+
+<div align="left">
+<p><b>Code Listing 2</b></p>
+</div>
+<pre class="code">//create a factory
+OMFactory factory = OMAbstractFactory.getOMFactory();
+//use the factory to create two namespace objects
+OMNamespace ns1 = factory.createOMNamespace("bar","x");
+OMNamespace ns2 = factory.createOMNamespace("bar1","y");
+//use the factory to create three elements
+OMElement root = factory.createOMElement("root",ns1);
+OMElement elt11 = factory.createOMElement("foo1",ns1);
+OMElement elt12 = factory.createOMElement("foo2",ns1);</pre>
+
+<p>The reason to have a set of factory.createXXX methods is to cater for
+different implementations but keep the programmers code intact. Its highly
+recommend to use the factory for creating OM objects as this will ease the
+switching of different OM implementations. Several differences exist between
+a programmatically created OMNode and a conventionally built OMNode. The most
+important difference is that the former will have no builder object enclosed,
+where as the latter always carries a reference to its builder. As stated
+earlier in this tutorial, since the object model is built as and when
+required, each and every OMNode should have a reference to its builder. If
+this information is not available, it is due to the object being created
+without a builder. This difference becomes evident when the user tries to get
+a non caching pull parser from the OMElement. This will be discussed in more
+detail in the advanced operations section.</p>
+
+<p>In order to understand the requirement of the builder reference in each
+and every OMNode, consider the following scenario. Assume that the parent
+element is built but the children elements are not. If the parent is asked to
+iterate through its children, this information is not readily available to
+the parent element and it should build its children first before attempting
+to iterate them. In order to provide a reference of the builder, each and
+every node of an OM structure should carry the reference to its builder. Each
+and every OMNode carries a flag that states its build status. Apart from this
+restriction there are no other constraints that keep the programmer away from
+mixing up programmatically made OMNode objects with OMNode objects built from
+builders.</p>
+
+<p>The SOAP object hierarchy is made in the most natural way for a
+programmer. An inspection of the API will show that it is quite close to the
+SAAJ API but with no bindings to DOM or any other model. The SOAP classes
+extend basic OM classes (such as the OMElement) hence one can access a SOAP
+document either with the abstraction of SOAP or drill down to the underlying
+XML Object model with a simple casting.</p>
+<!-- The following illustration of the actual class diagram will be helpful in understanding this.
+Need an image here -->
+<a name="nodes"></a>
+
+<h3>Addition of Nodes</h3>
+
+<p>Addition and removal methods are primarily defined in the OMElement
+interface. The following are the most important in adding nodes.</p>
+
+<div align="left">
+<p><b>Code Listing 3</b></p>
+</div>
+<pre class="code">public void addChild(OMNode omNode);
+public void addAttribute(OMAttribute attr);</pre>
+
+<p>This code segment shows how the addition takes place. Note that it is
+related to the code segment shown in the creation section.</p>
+
+<div align="left">
+<p><b>Code Listing 4</b></p>
+</div>
+<pre class="code">//set the children
+elt11.addChild(elt21);
+elt12.addChild(elt22);
+root.addChild(elt11);
+root.addChild(elt12);</pre>
+<ul>
+ <li>AddChild method will always add the child as the last child of the
+ parent.</li>
+ <li><p>A given node can be removed from the tree by calling the detach()
+ method. A node can also be removed from the tree by calling the remove
+ method of the returned iterator which will also call the detach method of
+ the particular node internally.</p>
+ </li>
+ <li>Namespaces are a tricky part of any XML object model and is the same in
+ OM. However the interface to the namespace have been made very simple.
+ OMNamespace is the class that represents a namespace with intentionally
+ removed setter methods. This makes the OMNamespace immutable and allows
+ the underlying implementation to share the objects without any
+ difficulty.</li>
+</ul>
+
+<p>Following are the important methods available in OMElement to handle
+namespaces.</p>
+
+<div align="left">
+<p><b>Code Listing 5</b></p>
+</div>
+<pre class="code">public OMNamespace declareNamespace(String uri, String prefix);
+public OMNamespace declareNamespace(OMNamespace namespace);
+public OMNamespace findNamespace(String uri, String prefix) throws OMException;</pre>
+
+<p>The declareNamespaceXX methods are fairly straightforward. They add a
+namespace to namespace declarations section. Note that a namespace
+declaration that has already being added will not be added twice.
+findNamespace is a very handy method to locate a namespace object higher up
+the object tree. It searches for a matching namespace in its own declarations
+section and jumps to the parent if it's not found. The search progresses up
+the tree until a matching namespace is found or the root has been reached.</p>
+
+<p>During the serialization a directly created namespace from the factory
+will only be added to the declarations when that prefix is encountered by the
+serializer. More of the serialization matters will be discussed in the
+serializer section.</p>
+
+<p>The following simple code segment shows how the namespaces are dealt with
+in OM</p>
+
+<div align="left">
+<p><b>Code Listing 6</b></p>
+</div>
+<pre class="code">OMFactory factory = OMAbstractFactory.getOMFactory();
+OMNamespace ns1 = factory.createOMNamespace("bar","x");
+OMElement root = factory.createOMElement("root",ns1);
+OMNamespace ns2 = root.declareNamespace("bar1","y");
+OMElement elt1 = factory.createOMElement("foo",ns1);
+OMElement elt2 = factory.createOMElement("yuck",ns2);
+OMText txt1 = factory.createOMText(elt2,"blah");
+elt2.addChild(txt1);
+elt1.addChild(elt2);
+root.addChild(elt1);</pre>
+
+<p>Serilization of the root element produces the following XML</p>
+<pre class="xml"><x:root xmlns:x="bar" xmlns:y="bar1"><x:foo><y:yuck>blah</y:yuck></x:foo></x:root></pre>
+<a name="traversing"></a>
+
+<h3>Traversing</h3>
+
+<p>Traversing the object structure can be done in the usual way by using the
+list of children. Note however that the child nodes are returned as an
+iterator. The Iterator supports the 'OM way' of accessing elements and is
+more convenient than a list for sequential access. The following code sample
+shows how the children can be accessed. The children are of the type OMNode
+that can either be OMText or OMElement.</p>
+
+<div align="left">
+<p><b>Code Listing 7</b></p>
+</div>
+<pre class="code">Iterator children = root.getChildren();
+while(children.hasNext()){
+ OMNode node = (OMNode)children.next();
+}</pre>
+
+<p>Apart from this, every OMNode has links to its siblings. If more thorough
+navigation is needed the nextSibling() and PreviousSibling() methods can be
+used. A more selective set can be chosen by using the
+getChildrenWithName(QName) methods. The getChildWithName(Qname) method
+returns the first child that matches the given QName and
+getChildrenWithName(QName) returns a collection containing all the matching
+children. The advantage of these iterators is that they won't build the whole
+object structure at once, until its required.</p>
+<!-- Special section -->
+
+<p class="special"></p>
+
+<table width="100%">
+ <tbody>
+ <tr>
+ <td><img src="images/OM005.gif" alt="Remember this" width="35"
+ height="57"></td>
+ <td class="special-td">All iterator implementations internally stay one
+ step ahead of their apparent location to provide the correct value
+ for the hasNext() method. This hidden advancement can build elements
+ that are not intended to be built at all. Hence these iterators are
+ recommended only when caching is not a concern.</td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+<!-- End of special section -->
+
+<p>OM can be serialized either as the pure object model or the pull event
+stream. The serialization uses a XMLStreamWriter object to write out the
+output and hence the same serialization mechanism can be used to write
+different types of outputs (such as text, binary, etc.,).</p>
+
+<p>A caching flag is provided by OM to control the building of the in-memory
+OM. The OMNode has two methods, serializeAndConsume and serialize. When
+serializeAndConsume is called the cache flag is reset and the serializer does
+not cache the stream. Hence the object model will not be built if the cache
+flag is not set.</p>
+
+<p>The serializer serializes namespaces in the following way.</p>
+<ol>
+ <li>When a namespace that is in the scope but not yet declared is
+ encountered, it will then be declared.</li>
+ <li>When a namespace that is in scope and already declared is encountered,
+ the existing declarations prefix is used.</li>
+ <li>When the namespaces are declared explicitly using the elements
+ declareNamespace() method, they will be serialized even if those
+ namespaces are not used in that scope.</li>
+</ol>
+
+<p>Because of this behavior, if a fragment of the XML is serialized, it will
+also be <i>namespace qualified</i> with the necessary namespace
+declarations.</p>
+
+<p>Here is an example that shows how to write the output to the console, with
+reference to the earlier code sample (Code listing 1 ) that created a SOAP
+envelope.</p>
+
+<div align="left">
+<p><b>Code Listing 8</b></p>
+</div>
+<pre class="code">XMLStreamWriter writer = XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
+//dump the output to console with caching
+envelope.serialize(writer);
+writer.flush();</pre>
+or simply
+<pre class="code"> System.out.println(root.toStringWithConsume()); </pre>
+
+<p>The above mentioned features of the serializer forces a correct
+serialization even if only a part of the OM tree is serialized. The following
+serializations show how the serialization mechanism takes the trouble to
+accurately figure out the namespaces. The example is from Code Listing 6
+which creates a small OM programmatically. Serialization of the root element
+produces the following,</p>
+<pre class="xml"><x:root xmlns:x="bar" xmlns:y="bar1"><x:foo><y:yuck>blah</y:yuck></x:foo></x:root></pre>
+
+<p>However serialization of only the foo element produces the following</p>
+<pre class="xml"><x:foo xmlns:x="bar"><y:yuck xmlns:y="bar1">blah</y:yuck></x:foo></pre>
+
+<p>Note how the serializer puts the relevant namespace declarations in
+place.</p>
+<b>Complete code for the OM based document building and serialization </b>
+
+<p>The following code segment shows how to use the OM for completely building
+a document and then serializing it into text pushing the output to the
+console. Only the important sections are shown here. The complete program
+listing can be found in the appendix.</p>
+
+<div align="left">
+<p><b>Code Listing 9</b></p>
+</div>
+<pre class="code">//create the parser
+XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(file));
+//create the builder
+StAXOMBuilder builder = new StAXOMBuilder(parser);
+
+//get the root element (in this case the envelope)
+OMElement documentElement = builder.getDocumentElement();
+
+//dump the out put to console with caching
+System.out.println(documentElement.toStringWithConsume()); </pre>
+<a name="advanced"></a>
+
+<h2>Advanced Operations with OM</h2>
+<a name="OMNavigator"></a>
+
+<h3>Use of the OMNavigator for Traversal</h3>
+
+<p>OM provides a utility class to navigate the OM structure. The navigator
+provides an in-order traversal of the OM tree up to the last-built node. The
+Navigator has two states called the navigable state and the completion state.
+Since the navigator provides the navigation starting from an OMElement, it is
+deemed to have completed the navigation when the starting node is reached
+again. This state is known as the completion state. Once the navigator has
+reached the complete status its navigation is done and it cannot proceed.</p>
+
+<p>It is possible that the OM tree does not get built completely when it is
+navigated. The navigable status shows whether the tree structure is
+navigable. When the navigator is complete it is not navigable anymore.
+However it is possible for a navigator to become non-navigable without being
+complete. The following code sample shows how the navigator should be used
+and handled using its states.</p>
+
+<div align="left">
+<p><b>Code Listing 10</b></p>
+</div>
+<pre class="code">//Create a navigator
+OMNavigator navigator = new OMNavigator(envelope);
+OMNode node = null;
+while (navigator.isNavigable()) {
+ node = navigator.next();
+}</pre>
+<a name="access_pullparser"></a>
+
+<h3>Accessing the Pull Parser</h3>
+
+<p>OM is tightly integrated with StAX and the
+getXMLStreamReader()/getXMLStreamReaderWithoutCaching() methods in the
+OMElement provides a XMLStreamReader object. This XMLStreamReader instance
+has a special capability of switching between the underlying stream and the
+OM object tree if the cache setting is off. However this functionality is
+completely transparent to the user. This is further explained in the
+following paragraphs.</p>
+
+<p>OM has the concept of caching, and OM is the actual cache of the events
+fired. However the requester can choose to get the pull events from the
+underlying stream rather than the OM tree. This can be achieved by getting
+the pull parser with the cache off. If the pull parser was obtained without
+switching off cache, the new events fired will be cached and the tree
+updated. This returned pull parser will switch between the object structure
+and the stream underneath and the users need not worry about the differences
+caused by the switching. The exact pull stream the original document would
+have provided would be produced even if the OM tree was fully/partially
+built. The getXMLStreamReaderWithoutCaching() method is very useful when the
+events need to be handled in a pull based manner without any intermediate
+models. This makes such operations faster and efficient.</p>
+<!-- Special section -->
+
+<p class="special"></p>
+
+<table width="100%">
+ <tbody>
+ <tr>
+ <td><img src="images/OM005.gif" alt="Remember this" width="35"
+ height="57"></td>
+ <td class="special-td">For consistency reasons once the cache is
+ switched off it cannot be switched on again.</td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+<!-- End of special section -->
+<a name="limitations"></a>
+
+<h2>Known Limitations of OM</h2>
+<a name="namespace_serialization"></a>
+
+<h3>Inefficient Namespace Serialization</h3>
+
+<p>Although the serializer acts correctly in every situation, the code that
+it produces may not be efficient all the time. Take the following case where
+a similar Code Listing to Code Listing 6 is used, but with two elements
+having the same namespace. Note that the newly added items are in bold.</p>
+
+<div align="left">
+<p><b>Code Listing 11</b></p>
+</div>
+<pre class="code">OMFactory factory = OMAbstractFactory.getOMFactory();
+OMNamespace ns1 = factory.createOMNamespace("bar","x");
+OMElement root = factory.createOMElement("root",ns1);
+OMNamespace ns2 = root.declareNamespace("bar1","y");
+OMElement elt1 = factory.createOMElement("foo",ns1);
+OMElement elt2 = factory.createOMElement("yuck",ns2);
+<b>OMElement elt3 = factory.createOMElement("yuck",ns2);</b>
+OMText txt1 = factory.createText(elt2,"blah");
+<b>OMText txt2 = factory.createText(elt3,"blahblah");
+elt3.addchild(txt2);</b>
+elt2.addChild(txt1);
+elt1.addChild(elt2);
+<b>elt1.addChild(elt3);</b>
+root.addChild(elt1);</pre>
+
+<p>Serialization of the root element provides the following XML</p>
+<pre class="xml"><x:root xmlns:x="bar" xmlns:y="bar1"><x:foo><y:yuck>blahblah</y:yuck><y:yuck>blah</y:yuck></x:foo></x:root></pre>
+
+<p>However if the serialization is carried on the foo element then the
+following XML is produced</p>
+<pre class="xml"><x:foo xmlns:x="bar" ><y:yuck " xmlns:y="bar1">blahblah</y:yuck><y:yuck " xmlns:y="bar1">blah</y:yuck></x:foo></pre>
+
+<p>Note that the same Namespace is serialized twice. This XML is semantically
+correct but the same semantics could have been achieved by placing the y
+namespace declaration on the parent element. This behavior is due to the
+nature of the serialization where it tries to be accurate but not optimal. It
+is deliberately kept unchanged since such optimizations slow down the common
+case.</p>
+<a name="summary"></a>
+
+<h2>Summary</h2>
+
+<p>This is meant to be a small yet comprehensive introduction to AXIOM. AXIOM
+however is a lot more than what is described in this tutorial. Readers are
+welcome to explore AXIOM, specially it's capabilities to handle binary
+content.</p>
+<a name="appendix"></a>
+
+<h2>Appendix</h2>
+<a name="program_listing"></a>
+
+<h3>Program Listing for Complete OM - Build and Serialize</h3>
+<pre class="code">import org.apache.axiom.om.SOAPEnvelope;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMXMLParserWrapper;
+import org.apache.axis2.impl.llom.factory.OMXMLBuilderFactory;
+
+import javax.xml.stream.*;
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+
+public class TestOMBuilder {
+
+ /**
+ * Pass the file name as an argument
+ * @param args
+ */
+ public static void main(String[] args) {
+ try {
+ //create the parser
+ XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(args[0]));
+ //get the root element (in this case the envelope)
+ OMElement documentElement = builder.getDocumentElement();
+
+ //dump the out put to console with caching
+ System.out.println(documentElement.toStringWithConsume());
+
+ } catch (XMLStreamException e) {
+ e.printStackTrace();
+ } catch (FileNotFoundException e) {
+ e.printStackTrace();
+ }
+ }
+
+
+}</pre>
+<a name="links"></a>
+
+<h2>Links</h2>
+<ul>
+<li><a href="http://ws.apache.org/commons/axiom/index.html">Apache AXIOM Home</a></li>
+<li>For basics in XML
+<ul>
+ <li><a
+ href="http://www-128.ibm.com/developerworks/xml/newto/index.html">Developerworks
+ Introduction to XML</a></li>
+ <li><a
+ href="http://www.bearcave.com/software/java/xml/xmlpull.html">Introduction
+ to Pull parsing</a></li>
+</li></ul>
+</ul>
+<!-- Start of footer -->
+<hr>
+
+<table width="100%">
+ <tbody>
+ <tr>
+ <td align="center">All rights reserved by Apache Software
+ Foundation</td>
+ </tr>
+ </tbody>
+</table>
+<!-- End of footer -->
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/latest/WS_policy.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/WS_policy.html?rev=406543&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/WS_policy.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/WS_policy.html Sun May 14 22:51:17 2006
@@ -0,0 +1,176 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+ <title>WS Policy Support in Axis2</title>
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en">
+<h1 align="center">Web Services Policy Support In Axis2</h1>
+
+<p><em>-Axis2 version 1.0</em></p>
+
+<p>This document will give you an introduction to the role of Web services
+policy in Axis2.</p>
+
+<p><i>E-mail comments/ suggestions to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#what">What is Web Services (WS) Policy?</a></li>
+ <li><a href="#client">Client Side WS-Policy Support</a></li>
+ <li><a href="#server">Server Side WS-Policy Support</a></li>
+ <li><a href="#resources">Resources</a></li>
+</ul>
+<a name="what"></a>
+
+<h2>What is Web Services (WS) Policy?</h2>
+
+<p>To consume non trivial web services one must fully understand its xml
+contract (WSDL) along with any other additional requirements, capabilities or
+preferences which translates to the configuration of the service, and
+essentially becomes the policies of the service.</p>
+
+<p>WS Policy framework provides a way to express the policies of a service in
+a machine-readable way. Web services infrastructure can be enhanced to
+understand and enforce policies at runtime. For instance, a service author
+might write a policy requiring digital signature and encryption, while
+service consumers could use the policy information to reason out whether they
+can adhere to this policy information to use the service or not.</p>
+
+<p>Further more, web service infrastructure could be enhanced to enforce
+those requirements without requiring the service author to write even single
+line of code.</p>
+<a name="client"></a>
+
+<h2>Client Side WS-Policy Support</h2>
+
+<p>This release <strong>fully supports WS Policy at client-side</strong>. It
+means that when you codegen a stub against a WSLD which contains policies,
+the stub will contain the capability to engage the required modules with the
+appropriate configurations. For instance, if there is a security policy
+attached to an operation in the WSDL, the generated stub will engage the
+security module for that operation with the appropriate security
+configurations.</p>
+
+<h3>How it works:</h3>
+
+<h4>Phase 1: At PolicyEvaluator</h4>
+
+<p>Codegen engine runs few of its registered extensions before it generates
+the stub. When PolicyEvalutor (which is a registered Codegen extension) is
+initialized, it populates a registry of namespaces of supported policies to
+PolicyExtensions.</p>
+
+<p>For instance, module foo might have a mapping of namespace
+http://test.com/foo which means any primitive assertion which has this
+namespace will be processed by this module. Foo module might implement the
+ModulePolicyExtension interface through which PolicyExtension object can be
+obtained.</p>
+
+<p>A <strong>PolicyExtension</strong> is the access point for a module to add
+any other methods to the stub. For instance Reliable Messaging module can add
+createSequence() and endSequence() methods to the stub, that the user must
+call to start and end an RM sequence.</p>
+
+<p>Then at the engagement of PolicyEvaluator, effective policy of each
+operation is calculated based on policy information declared in the WSDL
+document. Here we assume that effective policy of an operation contains a
+single alternative (<strong>Multiple policy alternatives are not
+supported</strong>). Then we split that policy as follows into few other
+policies such that, each policy will contain primitive assertions belonging
+to only one namespace.</p>
+<pre> <wsp:Policy> <wsp:Policy> <wsp:Policy> <wsp:Policy>
+ <a:Foo/> <a:Foo/> <b:Foo/> <c:Bar/>
+ <a:Bar/> => <a:Bar/> </wsp:Policy> </wsp:Policy>
+ <b:Foo/> </wsp:Policy>
+ <c:Bar/>
+ </wsp:Policy></pre>
+
+<p>Then each policy is given to the appropriate PolicyExtension with an
+org.w3c.Element type object to which the module can append any other
+elements/attributes it wishes. Those attributes/elements should resolve to
+meaningful stub functions via PolicyExtensionTemplate.xsl at latter point of
+time.</p>
+
+<p>For instance depending on the policy, Security module can append
+<username>, <passwd> elements to the given element as children,
+which are later resolved into setUsername(..), setPasswd(..), functions of
+the stub. This way a module can include additional methods to the stub which
+can be used to get specific parameters to the module. These methods store any
+user input in the ServiceClient properties
+(ServiceClient.getOptions().putProperty(...)) which can later be accessed by
+the module.</p>
+
+<h4>Phase 2: At MultiLanguageClientEmitter</h4>
+
+<p>Further, effective policies (based on the WSDL) at appropriate levels
+(service level, operation level) are stored as policy strings in the stub.
+Few more generic methods are also added to the stub which are used to
+evaluate/process policies at runtime.</p>
+
+<h4>Phase 3: Runtime</h4>
+
+<p>When a new stub object is created, the policy strings in the stub are
+converted into policy objects and merged together to get the effective
+policies of each operation. These effective policies are stored in
+appropriate AxisOperation objects which a module can access at later point of
+time.</p>
+
+<p>Then based on its policy each AxisOperation is engaged to a set of
+modules.</p>
+
+<p>When the stub method is invoked, those modules which are engaged to that
+AxisOperation, access the effective policy for that operation via
+AxisOperation object. It can get other information needed from the
+MessageContext which get stored by stub methods which the module has added to
+the stub earlier. The modules are required to loads their configurations
+according to the effective policy which is set in AxisOperation and
+properties they get via MessageContext.</p>
+<a name="server"></a>
+
+<h2>Server Side WS-Policy Support</h2>
+
+<p>In this current release Axis2 framework uses WS-Commons/Neethi framework
+to manipulate policy documents. All its description builders store any policy
+information included in description documents (services.xml, axis2.xml, ..
+etc) in the appropriate description classes. This information is available at
+both deployment and run time via these description classes.</p>
+
+<p>When generating WSDL dynamically for each service, policy information in
+the description classes is included. For instance, if you declare a policy in
+axis2.xml then that policy is reflected in service elements of WSDL of every
+service. If a policy is declared in a services.xml, it is shown in the
+service element of WSDL for that particular service.</p>
+
+<p>Next step is to use that information to engage and configure required
+modules and allow the module to make use of this policy information.</p>
+
+<p>It is evident that a great deal of work is required to make axis2 a fully
+fledged ws-policy supported web service infrastructure. But it is encouraging
+to note that we've taken the first steps towards this goal. We appreciate any
+suggestions, patches etc you send us in this regard. Keep on
+contributing...!</p>
+<a name="resources"></a>
+
+<h2>Resources</h2>
+<ul>
+ <li>Apache Neethi (WS Policy Implementation) official site- <a
+ href="http://ws.apache.org/commons/neethi/index.html"
+ target="_blank">Home Page</a></li>
+ <li>Sanka Samaranayake, March 2006. <a
+ href="http://www.wso2.net/2006/01/web_services_policy_why_what_how"
+ target="_blank">Web services Policy - Why, What & How</a></li>
+ <li><a
+ href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/"
+ target="_blank">WS-commons/policy SVN</a></li>
+ <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf"
+ target="_blank">Web Services Policy Framework (WS-Policy)</a></li>
+</ul>
+</body>
+</html>