axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cha...@apache.org
Subject svn commit: r388085 [2/6] - in /webservices/axis2/trunk/java/xdocs/latest: ./ adb/ adb/images/ images/ images/archi-guide/ images/tools/ images/tools/service/ images/tools/wsdl/ images/userguide/ resources/ resources/schemas/ sec-conf/
Date Thu, 23 Mar 2006 07:38:40 GMT
Added: webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html?rev=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/OMTutorial.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,693 @@
+<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>OM Tutorial</h1>
+
+<h2>Introduction</h2>
+
+<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 developed for Axis 2. 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 JDOM 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>
+
+<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 Namespaces) and a working
+knowledge of tools such as Ant. 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>
+
+<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>.
+
+<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>
+
+<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/aboutJava/communityprocess/first/jsr173/">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 covered</p>
+
+<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 and 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>
+
+<h3>Where Does SOAP Come into Play?</h3>
+
+<p>In a nutshell SOAP is a 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>
+-->
+
+<h2>Working with OM</h2>
+
+<h3>Obtaining the OM binary</h3>
+
+<p>OM is not a separate product but part of Axis2. But Axis2 provides a
+minimal jar which contains the run time of Axis2. This axis2-core-0.95.jar
+contains the compiled version of OM module.</p>
+
+<p>The easiest way to obtain the OM binary is to download the Axis2 minimal
+binary distribution.  <font color="red" style="color: #000000">The lib
+directory will contain the <span
+style="color: #000000">axis2-</span></font><font style="color: #000000"><span
+style="color: #000000">core</span></font><font color="red"
+style="color: #000000"><span
+style="color: #000000">-0.95.jar</span></font><span style="color: #000000">.
+However more adventurous users can build the OM from source, which is
+described in the next section. In this way one get only the "OM
+jar".</span></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">axis2-xml-0.95.jar</span> can
+be found in the newly created "targets" directory in the XML
+module.</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 <font color="red"><span style="color: #000000">axis2-core-0.95.jar
+or</span> <span style="color: #000000">axis2-xml-0.95.jar </span></font>is
+correct in the classpath along with the StAX API jar file and a StAX
+implementation.</p>
+
+<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 the reader should be fed into the
+OMXMLBuilderFactory to instantiate a suitable builder. The interface provided
+by the builder is identical, though the internal implementations vary.
+However, the types of the returned objects depend on the implementation of
+the builder. For example the SOAPModelBuilder returns SOAP specific objects
+(such as the SOAPEnvelope, which are sub classes of the OMElement) through
+its builder methods. The following piece of code shows the correct method of
+creating an OM document from an input stream. Note that the SOAP builder is
+used in this example.</p>
+
+<div align="left">
+<p><b>Code Listing 1</b></p>
+</div>
+<source><pre>//create the parser<br/>
+XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
+<br/>//create the builder<br/>
+OMXMLParserWrapper builder = OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getSOAP11Factory(), parser); 
+//get the root element (in this case the envelope)<br/>
+        SOAPEnvelope envelope = (SOAPEnvelope) 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 and the SOAP
+model builder. 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 element) 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 -->
+
+<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 first 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.createText(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">&lt;x:root xmlns:x="bar" xmlns:y="bar1"&gt;
+  &lt;x:foo&gt;
+        &lt;y:yuck&gt;blah&lt;/y:yuck&gt;
+  &lt;/x:foo&gt;
+&lt;/x:root&gt;</pre>
+
+<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, serializeWithCache and serialize When
+serialize 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.serializeWithCache(writer); 
+writer.flush();</pre>
+<pre class="code"></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">&lt;x:root xmlns:x="bar" xmlns:y="bar1"&gt;
+ &lt;x:foo&gt;
+   &lt;y:yuck&gt;blah&lt;/y:yuck&gt;
+ &lt;/x:foo&gt;
+&lt;/x:root&gt;</pre>
+
+<p>However serialization of only the foo element produces the following</p>
+<pre class="xml">&lt;x:foo xmlns:x="bar"&gt;
+&lt;y:yuck xmlns:y="bar1"&gt;blah&lt;/y:yuck&gt;
+&lt;/x:foo&gt;</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 FileReader(file));
+//create the builder
+OMXMLParserWrapper builder =   OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getOMFactory(),parser);
+//get the root element (in this case the envelope)
+SOAPEnvelope envelope = (SOAPEnvelope)builder.getDocumentElement();
+//get the writer
+XMLStreamWriter writer = XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
+//dump the out put to console with caching
+envelope.serialize(writer);
+writer.flush();</pre>
+
+<h2>Advanced Operations with OM</h2>
+
+<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>
+
+<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 -->
+
+<h3>Known Limitations of OM</h3>
+
+<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">&lt;x:root xmlns:x="bar" xmlns:y="bar1"&gt;
+&lt;x:foo&gt;
+ &lt;y:yuck&gt;blahblah&lt;/y:yuck&gt;
+ &lt;y:yuck&gt;blah&lt;/y:yuck&gt;
+&lt;/x:foo&gt;
+&lt;/x:root&gt;
+
+</pre>
+
+<p>However if the serialization is carried on the foo element then the
+following XML is produced</p>
+<pre class="xml">&lt;x:foo xmlns:x="bar" &gt;
+ &lt;y:yuck " xmlns:y="bar1"&gt;blahblah&lt;/y:yuck&gt;
+ &lt;y:yuck " xmlns:y="bar1"&gt;blah&lt;/y:yuck&gt;
+&lt;/x:foo&gt;
+
+</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>
+
+<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>
+
+<h2>Appendix</h2>
+
+<h3>Program Listing for complete OM - build and serialize</h3>
+<pre class="code">import org.apache.ws.commons.om.SOAPEnvelope;
+import org.apache.ws.commons.om.OMFactory;
+import org.apache.ws.commons.om.OMXMLParserWrapper;
+import org.apache.axis2.impl.llom.factory.OMXMLBuilderFactory;
+
+import javax.xml.stream.*;
+import java.io.FileReader;
+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 FileReader(args[0]));
+            //create the builder
+            OMXMLParserWrapper builder = OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getOMFactory(), parser);
+            //get the root element (in this case the envelope)
+            SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement();
+            //get the writer
+            XMLStreamWriter writer = XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
+            //dump the out put to console with caching
+            envelope.serialize(writer);
+writer.flush();
+
+        } catch (XMLStreamException e) {
+            e.printStackTrace();
+        } catch (FileNotFoundException e) {
+            e.printStackTrace();
+        }
+    }
+
+
+}</pre>
+
+<h3>Links</h3>
+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>
+</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/ServiceArchiveToolReference.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/ServiceArchiveToolReference.html?rev=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/ServiceArchiveToolReference.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/ServiceArchiveToolReference.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,152 @@
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title></title>
+</head>
+
+<body>
+<h1>Service Archive Wizard - Eclipse Plug-in</h1>
+
+<p><a href="http://ws.apache.org/axis2/download.cgi">[Download]</a></p>
+
+<p>Axis2 comes with a simple service archiver tool. This tool provides easy
+to use functionality to develop an Axis archive or an "aar" file or a "jar"
+file that can be deployed as a web service to the Axis2. This tool is in the
+form of an Eclipse plug-in and can be downloaded from the downloads section.
+This document describes how the tool can be used.</p>
+
+<h2>Installation</h2>
+
+<p>Download the binary version of the plug-in and extract the content of the
+zip file into the Eclipse installation folder. (The plug-in will actually go
+into the plugins directory in the Eclipse installation root). Restarting
+Eclipse will set the plug-in automatically.</p>
+
+<h2>Operation</h2>
+
+<p>If the plug-in is properly installed you should see a new wizard under the
+"New" section.(use the File -&gt; New -&gt; Other or Ctrl + N )</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/ServiceWizardSelection.jpg" width="500"
+height="500"></p>
+
+<p>Selecting the wizard and pressing the next button will start the service
+generator wizard. Following is the first wizard page.</p>
+
+<p align="center"><img alt="" border="0" src="images/tools/service/ServicePage1.jpg"
+width="500" height="500"></p>
+
+<p>Once the class file folder is given (which should be a folder in the file
+system) the next button will be enabled. </p>
+
+<p>Page 2 of the wizard requires you to locate the wsdl file. Note that the
+WSDL file cannot be skipped in this version of the tool.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page2.JPG" width="500" height="500"></p>
+
+<p align="center">Select the service.XML file in the next wizard page</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page3.JPG" width="500" height="500"></p>
+
+<p>Note that The service XML file can be generated if needed. To proceed to
+the service generation page, check the "generate automatically" checkbox.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page3_hl.JPG"></p>
+
+<p>If the automatic mode is not selected, then the wizard will directly jump
+to the library selection page. However if the automatic mode is selected the
+wizard will show the following page.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page4_plain.JPG" width="500"
+height="500"></p>
+
+<p>This is a somewhat complicated page. The service name textbox should
+include the name of the service that you wish to give the service. For the
+implementation class, type in the fully qualified class name and hit the load
+button to view the operations.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page4_load.JPG"></p>
+
+<p>The loaded operations should be displayed in a table. Once this is
+displayed you can filter the methods by selecting/deselecting the methods
+using the checkbox at each row.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page4_table.JPG" width="500"
+height="500"></p>
+
+<p>Further filtering can be achieved by using the "search declared methods"
+only checkbox.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page4_search_declared.JPG"></p>
+
+<p>Once the method selection is complete the wizard has enough information to
+generate a basic services.xml file. If further customization is required,
+there's no choice but to manually edit it!</p>
+
+<p>The next step is to add the libraries. The library addition page looks
+like this</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page5.JPG"></p>
+
+<p>The library name (with full path) can be either typed on the text box or
+browsed for using the browse button.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page5_browsed.JPG"></p>
+
+<p>Hit the Add button to add the library to the list. The added libraries
+should be displayed in the list box</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page5_hl.JPG"></p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page5_added.JPG"></p>
+
+<p>If any library needs to be removed, highlight it in the list and hit
+remove. Click next to proceed to the last page of the wizard</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page5_remove.JPG"></p>
+
+<p>The last page of the wizard asks for the output location and the output
+archive name.</p>
+
+<p></p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/service_page6.JPG"></p>
+
+<p>Once all the parameters are filled, hit the finish button to complete the
+wizard and generate the service archive.</p>
+
+<p align="center"><img alt="" border="0"
+src="images/tools/service/success_msg.JPG"></p>
+
+<p>If you see the above message, then you've successfully generated the
+service archive! This service archive can be hot deployed to Axis2</p>
+
+<p>The plugin also adds a help document to the Eclipse help system. You
+should see it if you go to Eclipse help content</p>
+
+<p align="center"><img alt="" border="0" src="images/tools/service/help.JPG"></p>
+<hr>
+
+<p></p>
+
+<p></p>
+
+<p></p>
+
+<p></p>
+</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=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/WS_policy.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/WS_policy.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,155 @@
+<!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>
+
+<h2 align="center"><em>-Experimental Feature</em></h2>
+
+<p><em>Axis2 version 0.95</em></p>
+<i>E-mail comments/ suggestions to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>
+
+<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>
+
+<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>  &lt;wsp:Policy&gt;         &lt;wsp:Policy&gt;       &lt;wsp:Policy&gt;           &lt;wsp:Policy&gt;
+    &lt;a:Foo/&gt;             &lt;a:Foo/&gt;           &lt;b:Foo/&gt;               &lt;c:Bar/&gt;
+    &lt;a:Bar/&gt;      =&gt;     &lt;a:Bar/&gt;         &lt;/wsp:Policy&gt;          &lt;/wsp:Policy&gt;
+    &lt;b:Foo/&gt;           &lt;/wsp:Policy&gt;
+    &lt;c:Bar/&gt;
+  &lt;/wsp:Policy&gt;</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
+&lt;username&gt;, &lt;passwd&gt; 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>
+
+<h2>Server Side WS-Policy Support</h2>
+
+<p>In this current release Axis2 framework uses ws-commons/policy as an
+object model 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>
+<h2>Resources</h2>
+<ul>
+<li>Apache WS-Commons Policy Implementaion official site- <a href="http://ws.apache.org/commons/policy/index.html" target="_blank">Home Page</a></li>
+<li>Sanka Samaranayake, March 2006. <a href="" target="_blank">Web services Policy - Why, What & How</a></li>
+<li><a href="http://svn.apache.org/viewcvs.cgi/webservices/commons/modules/policy/" 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>

Added: webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html?rev=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,83 @@
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title></title>
+</head>
+
+<body>
+<h1>ADB Integration With Axis2</h1>
+
+<h2>Introduction</h2>
+
+<p>ADB Integration with Axis2 is simple and straightforward. Given the
+extension mechanism of the Axis2 code generator, the obvious choice for the
+integrator is to write an extension. The extension that is added to support
+ADB is the SimpleDBExtension
+(<strong>org.apache.axis2.wsdl.codegen.extension.SimpleDBExtension</strong>)
+and can be found in the extensions list of the codegen-config.properties
+file.</p>
+
+<h2>Selection of Generation Modes for ADB</h2>
+
+<p>The extension sets the options for the code generator via the
+CompilerOptions, depending on the users settings. The following table
+summarizes the use of options. Please refer the ADB-How to document for the
+different generation modes and their descriptions.</p>
+
+<table border="1">
+  <caption></caption>
+  <tbody>
+    <tr>
+      <td><strong>User parameters</strong></td>
+      <td><strong>Selected code generation parameters</strong></td>
+    </tr>
+    <tr>
+      <td>None (no other parameter than the mandatory ones)</td>
+      <td>wrapClasses=false,writeClasses=false</td>
+    </tr>
+    <tr>
+      <td>-ss (server side)</td>
+      <td>wrapClasses=false,writeClasses=true</td>
+    </tr>
+  </tbody>
+</table>
+
+<p>If the users want to override these settings manually, they need to use
+the following parameters with the command line (prefixed with -E)</p>
+
+<table border="1">
+  <caption></caption>
+  <tbody>
+    <tr>
+      <td><strong>Parameter Name</strong></td>
+      <td><strong>Allowed values</strong></td>
+      <td><strong>Description</strong></td>
+    </tr>
+    <tr>
+      <td>r</td>
+      <td>true, false</td>
+      <td>Sets the write flag. If set to true the classes will be written by
+        ADB</td>
+    </tr>
+    <tr>
+      <td>w</td>
+      <td>true, false</td>
+      <td>Sets the packing flag. if true the classes will be packed.</td>
+    </tr>
+  </tbody>
+</table>
+
+<p></p>
+
+<p>Note that these parameters have no relevant long names and MUST be
+prefixed with a -E to be processed bt the code generator. For example</p>
+<pre>WSDL2Java .... -Er true</pre>
+
+<h2>Things to Remember</h2>
+<ol>
+  <li>SimpleDBExtension is made to process requests only when the databinding
+    framework is specified as ADB (using the switch -d adb )</li>
+</ol>
+<hr>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html?rev=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,318 @@
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <meta content="">
+  <meta content="">
+  <meta content="">
+  <meta content="">
+  <meta content="">
+  <meta content="">
+  <title>ADB  - Howto</title>
+</head>
+
+<body>
+<h1>Axis2 Databinding Framework</h1>
+
+<h2>Introduction</h2>
+
+<p>The objective of the Axis2Databinding framework is to provide a
+lightweight and simple schema compiler/ Java bean generator for Axis2. By no
+means it's to be a fully functional schema compiler like XMLBeans. This
+document aims to provide the architectural overview of the Axis2 Databinding
+Framework (referred to as ADB from here onwards) and be a guide to anyone who
+wants to use and modify ADB. Note that ADB is written in a fashion that
+allows it to be used as a standalone schema compiler and also to be extended
+to generate code for other languages.</p>
+
+<h2>Architectural Overview</h2>
+
+<p>ADB is built on a modular architecture that allows it to utilize a pre
+configured writer depending on the configuration.The 'big block diagram' for
+the code generator architecture is depicted below</p>
+
+<p><img src="images/ADB.jpg"></p>
+
+<p>ADB utilizes the WS-commons XmlSchema library for reading the Schema. The
+object model for the schema comes in the form of an XmlSchema object. The
+schema compiler keeps an instance of the writer (in the default case it's the
+JavaBeanWriter) which actually writes the classes. The writers may use
+whatever technique they prefer, in the case of the JavaBeanWriter, it uses an
+XSLT template. The SchemaCompiler also uses a typemapper object that tells it
+what classnames to be used for the QNames that it encounters. This type
+mapper is also part of the configuration and the users can override the
+default type mapper by overriding the property setting.</p>
+
+<h2>Code and Dependencies</h2>
+
+<p>As explained in the previous section, the schema compiler depends on the
+WS-Commons XmlSchema library. The XSLT transformations are dependent on the
+JVM's DOMimplementation (either crimson or xerces) which means that the
+underlying JVM should be 1.4 or higher. Apart from that ADB has no special
+dependencies on any other special jar files. The code for the schema compiler
+is completely in the <strong>org.apache.axis2.schema.*</strong> package. This
+package resides in the codegen module of the Axis2 source tree.</p>
+
+<p>Following are the important classes and files</p>
+<ol>
+  <li>SchemaCompiler - The work horse that really compiles the schema into
+    classes.</li>
+  <li>BeanWriter - BeanWriter represents the kind of interface the
+    SchemaCompiler accepts as a writer. The writer needs to handle the actual
+    writing of the clasess</li>
+  <li>JavaBeanWriter - The default implementation of the BeanWriter
+  interface.</li>
+  <li>TypeMap - represents the interface that the schema compiler looks
+    towards to find classes</li>
+  <li>JavaTypeMap - the default implementation of the TypeMap</li>
+  <li>BeanTemplate.xsl - the XSLtemplate the JavaBeanWriter uses.</li>
+  <li>Schema-compile.properties - The property file for the schema
+  compiler</li>
+</ol>
+
+<p>The easiest way to obtain the ADB binaries is to run the maven build for
+the codegen module. This will generate the codegen-{$version}.jar inside the
+target folder which is directly usable when the ADB schema compiler is
+required.</p>
+
+<h2>Invoking the ADB Code Generator</h2>
+
+<h3>As a standalone schema compiler</h3>
+
+<p>ADB comes with a mainclass XSD2Java that allows the schemas to be compiled
+just by giving the schema file reference.This main class is pretty much
+primitive and does not provide much control over the code generation process.
+This is bound to improve in the near future.</p>
+
+<p>Code generator accepts the following parameters</p>
+<ol>
+  <li>The Schema file name - This should be a complete file name pointing to
+    the local file system</li>
+  <li>The output folder name - This should be the name of a folder within the
+    local file system</li>
+</ol>
+
+<p>Since the main class has no validations built in, the compiler is likely
+to cough up an unexpected error message if these parameters are not supplied
+properly.</p>
+
+<h3>Through the API</h3>
+
+<p>This is the only way to harness the full potential of the schema compiler.
+The current Axis2 integration of ADB happens through this API. The most
+important classes and methods of the Schema compiler are as follows.</p>
+<ul>
+  <li>SchemaCompiler - Constructor
+    <p>The constructor of the schema compiler expects a CompilerOptions
+    object. This compilerOptions object is more of a holder for the
+    parameters that are passed to the SchemaCompiler. The only mandatory
+    parameter in the CompilerOptions is the output directory</p>
+  </li>
+  <li>SchemaCompiler - Compile(XMLSchema schema)
+    <p>The compile method to call for a single schema. The expected object is
+    a XMLSchema which is part of the XmlSchema library.</p>
+  </li>
+  <li>SchemaCompiler - Compile(List schemaList)
+    <p>Similar to the previous method but accepts a list of schemas instead
+    of one.</p>
+  </li>
+</ul>
+
+<p>For a comprehensive code sample in invoking the schema compiler through
+the API, the following classes would be helpful. One would also need an
+understanding of the generation modes of the ADB schema compiler when using it
+through the API.</p>
+<ul>
+  <li><strong>org.apache.axis2.schema.XSD2Java</strong></li>
+  <li><strong>org.apache.axis2.wsdl.codegen.extension.SimpleDBExtension</strong></li>
+</ul>
+
+<h2>Generation Modes</h2>
+
+<p>ADB extension provides several Generation modes for the data bound
+classes.</p>
+<ol>
+  <li><strong>Integrated mode</strong>
+    <p>In this mode the classes are generated as inner classes of the stub,
+    message receiver or the interface. The ADB framework refrains from
+    writing the classes but provides a map of DOM document objects that
+    contains the model for the databinding class. The implementers are free
+    to use the models for their needs. The Axis2 codegen engine parses these
+    documents with the an XSLT parser to create the necessary code.</p>
+    <p>Integrated mode is supposed to be used by the tool builders.</p>
+  </li>
+  <li><strong>Wrapped mode</strong>
+    <p>In the wrapped mode, the ADB databinder generates one class that
+    contains all the databound classes. This is convenient when the number of
+    classes need to be limited.</p>
+  </li>
+  <li><strong>Expanded mode</strong>
+    <p>This is the usual mode where the codegenerator generates a class for
+    each of the outer elements and the named complex types. The command line
+    tool (XSD2Java) always generates code in the expanded mode.</p>
+  </li>
+</ol>
+
+<p>The rules for generating code (described in the next section) applies
+regardless of the mode. Switching these modes can be done by passing the
+correct options via the CompilerOptions object. The following is table lists
+the options and the consequences of using them.</p>
+
+<table border="1">
+  <caption></caption>
+  <tbody>
+    <tr>
+      <td><strong>Field Name in Options</strong></td>
+      <td><strong>Description</strong></td>
+    </tr>
+    <tr>
+      <td>writeOutput</td>
+      <td>This determines whether to write the output or not. If the flag is
+        on then the classes will be written by ADB. The default is off.</td>
+    </tr>
+    <tr>
+      <td>wrapClasses</td>
+      <td>This determines whether to wrap the generated classes. If the flag
+        is on then a single class (with adb added to the end of the specified
+        package) will be generated. The default is off.</td>
+    </tr>
+  </tbody>
+</table>
+
+<h2>Deep into the Generated Code</h2>
+
+<p>When the schema compiler is invoked (oneway or another) it generates code
+depending on the following rules</p>
+<ol>
+  <li>All named complex types become bean classes. Any attribute or element
+    encapsulated in this complex type will become a field in the generated
+    class. Note that the support for constructs other than the sequence and
+    all is not yet implemented.</li>
+  <li>All top level elements become classes. This is a rather questioning
+    feature since unless classes are generated for the top level elements the
+    handling of elements become difficult and messy!</li>
+  <li>SimpleType restrictions are handled by replacing the relevant type with
+    the basetype</li>
+</ol>
+
+<p>Once the code is generated according to the rules it looks like the
+following. Consider the following piece of schema</p>
+<pre>&lt;schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+xmlns:tns="http://soapinterop.org/types" targetNamespace="http://soapinterop.org/types"&gt;
+&lt;import namespace="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
+ &lt;complexType name="SOAPStruct"&gt;
+  &lt;sequence&gt;
+   &lt;element name="varString" type="xsd:string"/&gt;
+   &lt;element name="varInt" type="xsd:int"/&gt;
+   &lt;element name="varFloat" type="xsd:float"/&gt;
+  &lt;/sequence&gt;
+ &lt;/complexType&gt;
+&lt;element name="myElement" type="tns:SOAPStruct"/&gt;
+&lt;/schema&gt;</pre>
+
+<p>For comprehension let us consider the expanded mode for the code
+generator. Unless specifically mentioned, the rest of this document assumes
+that the expanded mode of the code generation is used. This particular schema
+generates the following two classes in the designated package. This package
+is derived from the target namespace of the schema.</p>
+<ol>
+  <li>myElement.java</li>
+  <li>SOAPStruct.java</li>
+</ol>
+
+<p>As explained earlier, SOAPStruct refers to the complexType. MyElement is
+the class that refers to the element. Just as expected, the SOAPStruct bean
+has getters and Setters for varString, varInt and varFloat which are String,
+int and float respectively. myElement on the other hand has a single field
+representing the SOAPStruct object that it encapsulates.</p>
+
+<p>The most important aspect of the generated code is that it encapsulates
+two methods for creation and serializing the beans. Note that to make this
+work, the generated beans implement the
+<strong>org.apache.axis2.databinding.ADBBean</strong> interface</p>
+
+<p>The creator and reader methods look like the following</p>
+<ul>
+  <li><pre>public javax.xml.stream.XMLStreamReader
+    getPullParser(javax.xml.namespace.QName qName)</pre>
+    <p>This method returns a pull parser that throws the right events for
+    this particular object. However there is a subtle difference between
+    element based classes and complexType based classes</p>
+    <ol>
+      <li>An element based bean class (like myElement.java in the example)
+        will ignore the passed in QName. Instead of using the passed in QName
+        it'll utilize it's own QName which is embedded in the class under the
+        constant MY_QNAME, during the code generation.</li>
+      <li>A ComplexType based bean class(like SOAPStruct.java in the example)
+        will use the passed in QName to return an instance of the
+        ADBpullparser. This will effectively wrap the elements inside with an
+        element having the passed QName</li>
+    </ol>
+  </li>
+  <li><pre> public static [Object] 
+             parse(javax.xml.stream.XMLStreamReader reader) 
+             throws java.lang.Exception </pre>
+    <p>This method returns a populated instance of the class in question.
+    Note that</p>
+    <pre>[Object]</pre>
+    will be replaced by the actual class that contains this method. Say for
+    SOAPStruct the method looks like
+    <pre>public static SOAPStruct 
+                parse(javax.xml.stream.XMLStreamReader reader) 
+                throws java.lang.Exception </pre>
+  </li>
+</ul>
+
+<h3>An Example!</h3>
+
+<p>Consider the following XML fragment</p>
+<pre>&lt;myElement&gt;
+  &lt;varInt&gt;5&lt;/varInt&gt;
+  &lt;varString&gt;Hello&lt;/varString&gt;
+  &lt;varFloat&gt;3.3&lt;/varFloat&gt;
+&lt;/myElement&gt;</pre>
+
+<p>Enthusiastic readers might already have figured out that this piece of XML
+complies to the Schema mentioned above. The following piece of code shows how
+to build a populated instance of myElement with this fragment of XML</p>
+
+<p></p>
+<pre>XMLStreamReader reader = XMLInputFactory.newInstance().
+                                createXMLStreamReader(
+                                        new ByteArrayInputStream(xmlString.getBytes()));
+myElement elt = myElement.parse(reader);</pre>
+
+<p>Although this example takes on the tedious effort of creating a reader out
+of the String, inside the Axis2 environment an XMLStreamReader can be
+direclty asked from the OMElement! Hence the parse method becomes a huge
+advantage for hassle free object creation.</p>
+
+<p>Similarly the reader obtained from the object can also be utilized as
+needed. The following code fragment shows how to utilize the getPullParser
+method to create an OMElement</p>
+
+<p></p>
+<pre>XMLStreamReader reader = elt.getPullParser(null);
+OMElement omElt =  new StAXOMBuilder(reader).getDocumentElement();</pre>
+
+<p>That's all to it! If you are interested in learning more on ADB the
+following documents may also be helpful</p>
+
+<p></p>
+<ul>
+  <li><a href="adb-tweaking.html">Tweaking the ADB code generator</a></li>
+  <li><a href="adb-codegen-integration.html">ADB and Axis2
+  Integration</a></li>
+</ul>
+
+<h2>Known Limitations</h2>
+ADB is meant to be a 'Simple' databinding framework and was not meant to
+compile all types of schemas. The following limitations are the most
+highlighted.
+<ol>
+  <li>Complex Extensions and Restrictions are not supported.</li>
+  <li>Choice (Particle) is not supported</li>
+  <li>SimpleType Unions are not supported</li>
+</ol>
+<hr>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html?rev=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,100 @@
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title></title>
+</head>
+
+<body>
+<h1>ADB Tweaking Guide</h1>
+
+<h2>Introduction</h2>
+
+<p>ADB is written with future extensions in mind, with a clear and flexible
+way to extend or modify it's functionality. This document explains available
+mechanisms to extend ADB and possibly adopt it to compile schemas to support
+other languages.</p>
+
+<h2>Know the Configuration</h2>
+
+<p>The configuration for the ADB framework is in the
+<strong>schema-compile.properties</strong> file found in the
+<strong>org.apache.axis2.databinding.schema</strong> package. This properties
+file has the following important properties</p>
+<ul>
+  <li>schema.bean.writer.class
+    <p>This is the writer class. This is used by the schema compiler to write
+    the beans and should implement the
+    <strong>org.apache.axis2.schema.writer.BeanWriter</strong> inteface. The
+    schema compiler delegates the bean writing task to the specified instance
+    of the BeanWriter.</p>
+  </li>
+  <li>schema.bean.writer.template
+    <p>This specifies the template to be used in the BeanWriter. The
+    beanWriter author is free to use any mechanism to write the classes but
+    the default mechanism is to use a xsl template. This property may be left
+    blank if the BeanWriter implementation does not require a template.</p>
+  </li>
+  <li>schema.bean.typemap
+    <p>This is the type map to be used by the schema compiler. it should be
+    an implementation of the <strong>org.apache.axis2.schema.typemap</strong>
+    interface. The default typemap implementation encapsulates a hashmap with
+    type QName to Class name string mapping.</p>
+  </li>
+</ul>
+
+<h2>The First Tweak - Generate Plain Java Beans</h2>
+
+<p>The first, most simple tweak for the code generator could be to switch to
+plain bean generation. The default behavior of the ADB framework is to
+generate ADBBeans, but most users, if they want to use ADB as a standalone
+compiler, would love to have plain java beans. This can infact be done by
+simply changing the template used.</p>
+
+<p>The template for plain java beans is already available in the
+<strong>org.apache.axis2.schema.template </strong>package. To make this work
+replace the
+<strong>/org/apache/axis2/databinding/schema/template/ADBBeanTemplate.xsl
+</strong>with the
+<strong>/org/apache/axis2/databinding/schema/template/PlainBeanTemplate.xsl
+</strong>in the schema-compile.properties<strong>.</strong> </p>
+
+<p>Congratualtions! You just tweaked ADB to generate plain java beans.</p>
+
+<p>To generate custom formats, the templates need to be modified. The schema
+for the xml generated by the JavaBeanWriter is availble in the source tree
+under the Other directory in the codegen module. Advanced users with
+knowledge of XSLT can easily modify the templates to generate code in their
+own formats.</p>
+
+<h2>A More Advanced Tweak - Generate Code for Another Language</h2>
+
+<p>To generate code for another language, there are two main components are
+to be written.</p>
+<ul>
+  <li>The BeanWriter
+    <p>Implement the BeanWriter interface for this class. A nice example is
+    the <strong>org.apache.axis2.schema.writer.JavaBeanWriter</strong> which
+    has a lot of reusable code. Infact if the language is OOP based (such as
+    C# or even C++), one would even be able to extend the JavaBeanWriter
+    itself.</p>
+  </li>
+  <li>The TypeMap
+    <p>Implement the TypeMap interface for this class. The
+    <strong>org.apache.axis2.schema.typemap.JavaTypeMap</strong> class is a
+    simple implementation for the typemap where the QName to class name
+    strings are kept inside a hashmap instance. This technique is fairly
+    sufficient and only the type names would need to change to support
+    another language.</p>
+  </li>
+</ul>
+
+<p>Surprisngly this is enough to have other language support for ADB. Change
+the configuration and you are ready to generate code for other lanuages!</p>
+
+<p>This tweaking guide is supposed to be a simple guideline for anyone who
+wishes to dig deep into the mechanics of the ADB code generator. Users are
+free experiment with it and modify the schema compiler accordingly to their
+needs.</p>
+<hr>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/latest/adb/images/ADB.jpg
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/images/ADB.jpg?rev=388085&view=auto
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/trunk/java/xdocs/latest/adb/images/ADB.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/trunk/java/xdocs/latest/axis2config.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/axis2config.html?rev=388085&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/axis2config.html (added)
+++ webservices/axis2/trunk/java/xdocs/latest/axis2config.html Wed Mar 22 23:38:30 2006
@@ -0,0 +1,388 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title>Axis2 Configuration Documents</title>
+</head>
+
+<body>
+<p>In Axis2 there are three kinds of configuration files to configure the
+system. First one configuration file is to configure whole system, second one
+is to configure a service and the third one is to configure a module.</p>
+<ul>
+  <li><a href="#Global_Configuration">Global Configuration
+  (axis2.xml)</a></li>
+  <li><a href="#Service_Configuration">Service Configuration
+    (services.xml)</a></li>
+  <li><a href="#Module_Configuration">Module Configuration
+  (module.xml)</a></li>
+</ul>
+
+<h2><a name="Global_Configuration">Global Configuration</a></h2>
+<ul>
+  <li>Writing axis2.xml</li>
+</ul>
+
+<p>All the configuration that requires starting axis2 is obtained from
+axis2.xml. The way of specifying them is very simple and easy. The document
+is all about the proper way of specifying the configurations in axis2.xml.
+There are six top level elements that can be seen in the configuration file
+and those can be listed as follows;</p>
+<ul>
+  <li>Parameter</li>
+  <li>Transport Receiver</li>
+  <li>Transport Sender</li>
+  <li>Phase Order</li>
+  <li>Module References</li>
+  <li>Listeners (Observers)</li>
+</ul>
+
+<p><b>Parameter </b> <br>
+In axis2 a parameter is nothing but name value pair, each and every top level
+parameter available in the axis2.xml (direct sub elements of root element)
+will be transformed into properties in AxisConfiguration. Therefore the top
+level parameters in configuration document can be accessed via
+AxisConfiguration in the running system. The correct way of defining a
+parameter looks like what is shown below;</p>
+<source><pre> 
+  &lt;parameter name="name of the parameter" &gt;parameter value &lt;/parameter&gt;</pre>
+</source>
+<p><b>Transport Receiver</b><br>
+Depending on the underline transport that axis going to be run , need to have
+different transport receivers so the way of adding them to the system can be
+done as follows;</p>
+<pre> 
+&lt;transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer"&gt;
+        &lt;parameter name="port" &gt;6060&lt;/parameter&gt;
+ &lt;/transportReceiver&gt; 
+ </pre>
+</source>The above elements shows the way of defining transport receivers in
+axis2.xml , here name attribute of the 'transportReceiver' element is the
+name of transport it can be http, tcp , smtp , commonshttp stc , and when the
+system starts up or when setting transport at the client side one can use
+these transport names to load the appropriate transport. Class attribute is
+to specify actual java class which implements required interfaces for the
+transport. Any transport can have zero or more parameters, and if there are
+any, then those parameters can be accessed via the corresponding transport
+receiver.
+
+<p><b>Transport Senders</b><br>
+As same as transport receivers it is possible to register transport senders
+in the system, and latter at the run time those senders can be used to send
+the messages. As an example consider Axis2 running under tomcat, then axis
+can use TCP transport senders to send message rather than HTTP. The way of
+specifying transport senders is as follows:</p>
+
+<p><source></p>
+<pre> 
+&lt;transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;
+        &lt;parameter name="PROTOCOL" locked="xsd:false"&gt;HTTP/1.0&lt;/parameter&gt;
+ &lt;/transportSender&gt; 
+ </pre>
+</source>name: Name of the transport (it is possible to have http and http1
+as transport name) Class: Implementation class of the corresponding
+transport. As same as transport receivers, transport senders can have zero or
+more parameters, and if there is any then it can be accessed via
+corresponding transport sender.
+
+<p><b>Phase Order</b><br>
+The specifying order of phases in execution chain has to be done using phase
+order element and it will be look like below;</p>
+
+<p><source></p>
+<pre>&lt;phaseOrder type="inflow"&gt;
+         &lt;phase name="TransportIn"/&gt;
+         .
+         .
+&lt;/phaseOrder&gt;   </pre>
+</source>The most interesting thing is that you can add handlers here as well
+, if you want to add a handler which should go in to that phase you can
+directly do that by adding a handler element into it . In addition to that
+there is no any hard coding stuffs for handler  chain in anywhere in Axis2
+(at any Axis*) , so all those configuration are also done here in phase order
+element. The complete configuration will look like as follows; <source>
+<pre>&lt;phaseOrder type="inflow""&gt;
+        &lt;!--  System pre defined phases       --"&gt;
+        &lt;phase name="TransportIn"/"&gt;
+        &lt;phase name="PreDispatch"/"&gt;
+        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
+            &lt;handler name="AddressingBasedDispatcher"
+                     class="org.apache.axis2.engine.AddressingBasedDispatcher""&gt;
+                &lt;order phase="Dispatch"/"&gt;
+            &lt;/handler"&gt;
+             &lt;handler name="RequestURIBasedDispatcher"
+                     class="org.apache.axis2.engine.RequestURIBasedDispatcher""&gt;
+                &lt;order phase="Dispatch"/"&gt;
+            &lt;/handler"&gt;
+             &lt;handler name="SOAPActionBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher""&gt;
+                &lt;order phase="Dispatch"/"&gt;
+            &lt;/handler"&gt;
+             &lt;handler name="SOAPMessageBodyBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher""&gt;
+                &lt;order phase="Dispatch"/"&gt;
+            &lt;/handler"&gt;
+            &lt;handler name="InstanceDispatcher"
+                     class="org.apache.axis2.engine.InstanceDispatcher""&gt;
+                &lt;order phase="Dispatch"/"&gt;
+            &lt;/handler"&gt;
+        &lt;/phase"&gt;
+        &lt;!--  Sysem pre defined phases       --"&gt;
+        &lt;!--   After Postdispatch phase module author or or service author can add any phase he want      --"&gt;
+        &lt;phase name="OperationInPhase"/"&gt;
+    &lt;/phaseOrder"&gt;
+    &lt;phaseOrder type="outflow""&gt;
+        &lt;!--      user can add his own phases to this area  --"&gt;
+        &lt;phase name="OperationOutPhase"/"&gt;
+        &lt;!--system predefined phase--"&gt;
+        &lt;!--these phase will run irrespective of the service--"&gt;
+        &lt;phase name="PolicyDetermination"/"&gt;
+        &lt;phase name="MessageOut"/"&gt;
+    &lt;/phaseOrder"&gt;
+    &lt;phaseOrder type="INfaultflow""&gt;
+        &lt;!--      user can add his own phases to this area  --"&gt;
+        &lt;phase name="OperationInFaultPhase"/"&gt;
+    &lt;/phaseOrder"&gt;
+    &lt;phaseOrder type="Outfaultflow""&gt;
+        &lt;!--      user can add his own phases to this area  --"&gt;
+        &lt;phase name="OperationOutFaultPhase"/"&gt;
+        &lt;phase name="PolicyDetermination"/"&gt;
+        &lt;phase name="MessageOut"/"&gt;
+    &lt;/phaseOrder"&gt;</pre>
+</source>type: the attribute represent type of the flow and which can only be
+one of the following
+<ul>
+  <li>inflow</li>
+  <li>outflow</li>
+  <li>INfaultflow</li>
+  <li>Outfaultflow</li>
+</ul>
+
+<p>In addition to that only child element allowed inside pahseOrder is phase
+element, which represents available phases in the execution chain. The way of
+specifying phase inside phaseOrder has to be done as follows;</p>
+
+<p><source></p>
+<pre> &lt;phase name="TransportIn"/&gt;</pre>
+</source>name: Name of the phase. <br>
+There are number of things that one has to keep in mind when changing
+pahseOrder,
+<ul>
+</ul>
+<ol>
+  there are phases called system pre-defined phases in all four flows;</ol>
+<ol>
+  You are not allowed change those  , and you can add new phase after system
+  pre-defined phase</ol>
+<ol>
+  If you closely look at the default axis2.xml can clearly identify that.</ol>
+
+<p><b>Module References</b><br>
+If you want to engage a module system wide you can do it by adding top level
+module element in axis2.xml.  It should be look like following:</p>
+
+<p><source></p>
+<pre>&lt;module ref="addressing"/&gt;  </pre>
+</source>ref: the module name which is going to be engage, system wide.
+
+<p><strong>Listeners (Observers)</strong></p>
+
+<p>In Axis2 AxisConfiguration is observable so that one can register
+observers into that, and they will be automatically informed whenever a
+change occurs in AxisConfiuration. In the current implementation the
+observers are informed of the following events</p>
+<ul>
+  <li>Deploying a Service</li>
+  <li>Removing a service</li>
+  <li>Activate/Inactivate Service</li>
+  <li>Module deploy</li>
+  <li>Module remove</li>
+</ul>
+Registering Observers is very useful for additional features such as RSS feed
+generation which will provide service information to subscribers. The correct
+way of registering observers should be like below; <source>
+<pre>&lt;listener class="org.apache.axis2.ObserverIMPL"&gt;
+    &lt;parameter name="RSS_URL" &gt;http://127.0.0.1/rss&lt;/parameter&gt;
+  &lt;/listener&gt;</pre>
+</source>class: Represent an Implementation class of observer, and it should
+be note that the implementation class should implement AxisObserver
+interface, and the class has to be available in the classpath. <a
+name="Service_Configuration"></a>
+
+<h2><font>Service Configuration</font></h2>
+<ul>
+  <li><font>Writing services.xml</font></li>
+</ul>
+
+<p><font>The description of service is specified using services.xml, each
+service archive file need to have services.xml in order to be a valid
+service. And which has to be available in META-INF directory of the archive
+file. <br>
+A very simple services.xml is shown below:</font></p>
+<source><pre><font>&lt;service name="name of the service" scope="name of the scope" targetNamespace="target namespase for the service"&gt;
+    &lt;description&gt; The description of the service  &lt;/description&gt;  
+
+    &lt;transports&gt; 
+       &lt;transport&gt;HTTP&lt;/transport&gt;
+    &lt;/transports&gt;
+    
+    &lt;schema schemaNamespace="schema namespace"/&gt; 
+     
+    &lt;messageReceivers&gt;
+            &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
+                             class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/&gt;
+    &lt;/messageReceivers&gt;
+     
+     &lt;parameter name="ServiceClass"     locked="xsd:false"&gt;org.apache.axis2.sample.echo.EchoImpl&lt;/parameter&gt;
+    
+    &lt;operation name="echoString" mep="operation MEP"&gt; 
+        &lt;actionMapping&gt;Mapping to action&lt;/actionMapping&gt;
+        &lt;module ref=" a module name "/&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;
+  &lt;/service&gt;</font></pre>
+</source><font><em><strong>name</strong></em>: the service name will be the
+name of the archive file if the .aar file contains only one service else name
+of the service will be the name given by the name attribute</font>
+
+<p><em><strong>scope</strong></em> : Scope that the service need to be
+deployed and scope can be one of
+"Application","SOAPSession","TransportSession","Request";</p>
+
+<p><em><strong>targetNamespace</strong></em> : Targtet name space of the
+service , and this value will be used when generation wsdl</p>
+
+<p></p>
+
+<p><font><strong>description</strong>: This is an optional element if you
+want to display any description about the service via Axis2 web-admin module
+then the description can be specified here.</font></p>
+
+<p><strong>transports</strong> : The transports that the service is going to
+be exposed , this is an optional element . If the transports element is not
+present then the service will be exposed in every transports available in the
+system. The transport child element is to specify the transport prefix (the
+name of the transport specified in axis2.xml)</p>
+
+<p><b>Parameter:</b><br>
+services.xml can have any number of top level parameters and all the
+specified parameters will be transformed into service properties in
+corresponding AxisService. There is a compulsory parameter in a services.xml
+called ServiceClass which specify the java class which really does the job
+and the class will be loaded by MessageReceiver.</p>
+
+<p><b>Operations</b><br>
+If the service impl class is java then all the public methods in that service
+will be exposed and if user wnats to override then he has to add operation
+tag and override that . In the case of Non-Java case or if you does no thave
+service class then all the operations user wants to expose by the service has
+to be indicated in the services.xml and the correct way of specifying that
+should be as follows:</p>
+<pre>    &lt;operation name="echoString"&gt;
+        &lt;module ref=" a module name "/&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;</pre>
+</source>Only compulsory attribute here is name, which represent the
+operation name that is going to be exposed. Any operation can contains module
+references, any number of parameters. The most interesting is that one can
+register custom message receiver per operation, then the registered message
+receiver will be the message receiver for the corresponding operation. If one
+does not specify the message receiver then the default message receiver will
+do the job. <br>
+<a name="Module_Configuration"></a>
+
+<h2>Module Configuration</h2>
+<ul>
+  <li>Writing module.xml</li>
+</ul>
+
+<p>The description of module is specified using module.xml, each module
+archive file need to have module.xml in order to be a valid module. And which
+has to be available in META-INF directory of the archive file. <br>
+A very simple module.xml is shown below:</p>
+
+<p><source></p>
+<pre>&lt;module class="org.apache.module.Module1Impl"&gt;
+    &lt;inflow&gt;
+        .
+        .
+    &lt;/inflow&gt;
+    &lt;outflow&gt;
+        .
+        .
+    &lt;/outflow&gt;
+
+    &lt;Outfaultflow&gt;
+        .   
+        .
+    &lt;/Outfaultflow&gt;
+
+    &lt;INfaultflow&gt;
+        .         
+        .
+    &lt;/INfaultflow&gt;
+
+    &lt;operation name="creatSeq" mep="MEP_URI_IN_OUT"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+        &lt;parameter name="para1" locked="xsd:true"&gt;10&lt;/parameter&gt;
+    &lt;/operation&gt;
+&lt;/module&gt;
+</pre>
+</source>class: This is an optional attribute which indicate module
+implementation class, a module may or may not contain module implementation
+class since the module can also be a collection of handlers. If a module
+contains an implementation class which implements the
+org.apache.axis2.modules.Module inteface where at the deployment time its
+init(); method will be called.
+
+<p><b>parameter:</b> Module can contains any number of parameters and all the
+listed parameters in the module.xml will be transformed into corresponding
+AxisModule of the module.</p>
+
+<p><b>Flow :</b></p>
+
+<p>Defining of handlers in a module has to done inside Flows , and there are
+four types of flows as listed below.</p>
+
+<p> It is possible to add any number of handlers into a flow and those
+handlers will be available in corresponding chains at the runtime when they
+engaged .</p>
+<ul>
+  <li>Inflow</li>
+  <li>outflow</li>
+  <li>INfaultflow</li>
+  <li>Outfaultflow</li>
+</ul>
+
+<p><b>operations</b> If a module wants to add an operation when it is engaged
+into a service it can be done by adding operation tag in module.xml and the
+way of specifying the operation is same as operation in services.xml.</p>
+
+<p><b>Handler</b><br>
+Handler element consists of compulsory and optional attribute and the way of
+defining a handler will be look like follows;</p>
+
+<p><source></p>
+<pre>&lt;handler name="handler1" class="handlerClass "&gt;
+            &lt;order phase="userphase1" /&gt;
+ &lt;/handler&gt;</pre>
+</source>
+<p><b><i>Compulsory attributes</i></b> <br>
+name: name of the handler<br>
+nlass: handler implementation class<br>
+phase: name of the phase that the handler should stay in the execution chain
+<br>
+<br>
+<i><b>Optional attributes :</b></i><br>
+phaseLast: to indicate the handler is last handler of the phase<br>
+phaseFirst: to indicate the handler is first handler of the phase.<br>
+before : the handler should be invoked before the handler specified by before
+handler<br>
+after:  the handler should be invoked after the handler specified by after
+handler<br>
+</p>
+
+<p><br>
+</p>
+</body>
+</html>



Mime
View raw message