axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dee...@apache.org
Subject svn commit: r565295 [1/14] - in /webservices/axis2/site/1_3: ./ adb/ jibx/ src/
Date Mon, 13 Aug 2007 10:13:23 GMT
Author: deepal
Date: Mon Aug 13 03:13:18 2007
New Revision: 565295

URL: http://svn.apache.org/viewvc?view=rev&rev=565295
Log:
site updated for 1.3 release

Added:
    webservices/axis2/site/1_3/
    webservices/axis2/site/1_3/Axis2-rpc-support.html
    webservices/axis2/site/1_3/Axis2ArchitectureGuide.html
    webservices/axis2/site/1_3/WS_policy.html
    webservices/axis2/site/1_3/adb/
    webservices/axis2/site/1_3/adb/adb-advanced.html
    webservices/axis2/site/1_3/adb/adb-codegen-integration.html
    webservices/axis2/site/1_3/adb/adb-howto.html
    webservices/axis2/site/1_3/adb/adb-tweaking.html
    webservices/axis2/site/1_3/adv-userguide.html
    webservices/axis2/site/1_3/app_server.html
    webservices/axis2/site/1_3/axis2config.html
    webservices/axis2/site/1_3/clustering-guide.html
    webservices/axis2/site/1_3/contents.html
    webservices/axis2/site/1_3/dii.html
    webservices/axis2/site/1_3/ejb-provider.html
    webservices/axis2/site/1_3/http-transport.html
    webservices/axis2/site/1_3/index.html
    webservices/axis2/site/1_3/installationguide.html
    webservices/axis2/site/1_3/jibx/
    webservices/axis2/site/1_3/jibx/jibx-codegen-integration.html
    webservices/axis2/site/1_3/jibx/jibx-doclit-example.html
    webservices/axis2/site/1_3/jibx/jibx-unwrapped-example.html
    webservices/axis2/site/1_3/jms-transport.html
    webservices/axis2/site/1_3/json_support.html
    webservices/axis2/site/1_3/mail-configuration.html
    webservices/axis2/site/1_3/mail-transport.html
    webservices/axis2/site/1_3/migration.html
    webservices/axis2/site/1_3/modules.html
    webservices/axis2/site/1_3/mtom-guide.html
    webservices/axis2/site/1_3/pojoguide.html
    webservices/axis2/site/1_3/quickstartguide.html
    webservices/axis2/site/1_3/reference.html
    webservices/axis2/site/1_3/rest-ws.html
    webservices/axis2/site/1_3/soapmonitor-module.html
    webservices/axis2/site/1_3/spring.html
    webservices/axis2/site/1_3/src/
    webservices/axis2/site/1_3/src/Axis2SampleDocLitServiceCode.html
    webservices/axis2/site/1_3/tcp-transport.html
    webservices/axis2/site/1_3/toc.html
    webservices/axis2/site/1_3/transport_howto.html
    webservices/axis2/site/1_3/userguide-buildingservices.html
    webservices/axis2/site/1_3/userguide-codelisting5.html
    webservices/axis2/site/1_3/userguide-codelisting7.html
    webservices/axis2/site/1_3/userguide-creatingclients-jibx.html
    webservices/axis2/site/1_3/userguide-creatingclients-xmlbeans.html
    webservices/axis2/site/1_3/userguide-creatingclients.html
    webservices/axis2/site/1_3/userguide-forfurtherstudy.html
    webservices/axis2/site/1_3/userguide-installingtesting.html
    webservices/axis2/site/1_3/userguide-introtoservices.html
    webservices/axis2/site/1_3/userguide-samples.html
    webservices/axis2/site/1_3/userguide.html
    webservices/axis2/site/1_3/webadminguide.html
    webservices/axis2/site/1_3/xmlbased-server.html

Added: webservices/axis2/site/1_3/Axis2-rpc-support.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/Axis2-rpc-support.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/Axis2-rpc-support.html (added)
+++ webservices/axis2/site/1_3/Axis2-rpc-support.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,560 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                    <img src="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+            <div class="xleft">
+        Last Published: 08/13/2007
+                      </div>
+            <div class="xright">      <a href="../index.html">Axis2/Java</a>
+          |
+          <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+          |
+          <a href="../../../">Apache WS</a>
+          |
+          <a href="http://www.apache.org">Apache</a>
+          
+  
+
+  
+    
+  
+  
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+                   <h5>Axis2/Java</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../index.html">Home</a>
+        </li>
+          </ul>
+          <h5>Downloads</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../download.cgi">Releases</a>
+        </li>
+              
+    <li class="none">
+              <a href="../modules/index.html">Modules</a>
+        </li>
+              
+    <li class="none">
+              <a href="../tools/index.html">Tools</a>
+        </li>
+          </ul>
+          <h5>Documentation</h5>
+        <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+              <a href="../1_3/contents.html">Version 1.3</a>
+                <ul>
+                  
+    <li class="none">
+              <a href="../1_3/toc.html">Table of Contents</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/installationguide.html">Installation Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/userguide.html">User Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/pojoguide.html">POJO Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/spring.html">Spring Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+        </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+              <a href="../1_2/contents.html">Version 1.2</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_1_1/contents.html">Version 1.1.1</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_1/contents.html">Version 1.1</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_0/index.html">Version 1.0</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_95/index.html">Version 0.95</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_94/index.html">Version 0.94</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_93/index.html">Version 0.93</a>
+        </li>
+          </ul>
+          <h5>Resources</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../faq.html">FAQ</a>
+        </li>
+              
+    <li class="none">
+              <a href="../articles.html">Articles</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://wiki.apache.org/ws/FrontPage/Axis2/">Wiki</a>
+        </li>
+              
+    <li class="none">
+              <a href="../refLib.html">Reference Library</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://ws.apache.org/axis2/1_3/api/index.html">Online Java Docs</a>
+        </li>
+          </ul>
+          <h5>Get Involved</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../overview.html">Overview</a>
+        </li>
+              
+    <li class="none">
+              <a href="../svn.html">Checkout the Source</a>
+        </li>
+              
+    <li class="none">
+              <a href="../mail-lists.html">Mailing Lists</a>
+        </li>
+              
+    <li class="none">
+              <a href="../release-process.html">Release Process</a>
+        </li>
+              
+    <li class="none">
+              <a href="../guidelines.html">Developer Guidelines</a>
+        </li>
+              
+    <li class="none">
+              <a href="../siteHowTo.html">Build the Site</a>
+        </li>
+          </ul>
+          <h5>Project Information</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../team-list.html">Project Team</a>
+        </li>
+              
+    <li class="none">
+              <a href="../issue-tracking.html">Issue Tracking</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN">Source Code</a>
+        </li>
+              
+    <li class="none">
+              <a href="../thanks.html">Acknowledgements</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a>
+        </li>
+          </ul>
+                                       <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"></meta>
+<meta http-equiv="content-type" content=""></meta>
+Axis2 RPC Support
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+<h1>Axis2 RPC Support</h1>
+<p>This document describes Axis2's Remote Procedure Call support in
+a set of easy to understand implementation steps.</p>
+<h2>Introduction</h2>
+<p>Axis2 Remote Procedure Call (RPC) support may seem somewhat
+tricky and confusing at first glance. However, Axis2 RPC strategy
+is based on a set of well defined rules. This document aims to
+drill down to the details of the strategy and resolve most of the
+unknown bits and pieces. Note that Axis2 currently does not support
+the rpc/encoded style fully. Its main support is for the rpc/lit
+style.</p>
+<p>We will discuss the Axis2 RPC strategy in the following
+steps</p>
+<h2>Step 1 - Converting RPC Style WSDL's into Doc/Lit Style
+WSDL</h2>
+<p>This is probably the most confusing part of the RPC strategy.
+Since the Axis2 code generator is based on pure doc/lit style, the
+first step of the code generation process is to generate a wrapper
+schema. This wrapper generation can be easily explained by using an
+example.</p>
+<p>Take the following piece of WSDL</p>
+<pre>
+ .....
+    &lt;message name=&quot;requestMessage&quot;&gt;
+                &lt;part name=&quot;part1&quot; type=&quot;xs:string&quot;/&gt;
+                &lt;part name=&quot;part2&quot; type=&quot;xs:int&quot;/&gt;
+        &lt;/message&gt;
+        &lt;message name=&quot;responseMessage&quot;&gt;
+                &lt;part name=&quot;part1&quot; type=&quot;xs:string&quot;/&gt;
+        &lt;/message&gt;
+        &lt;portType name=&quot;echoPortType&quot;&gt;
+                &lt;operation name=&quot;echo&quot;&gt;
+                        &lt;input message=&quot;y:requestMessage&quot;/&gt;
+                        &lt;output message=&quot;y:responseMessage&quot;/&gt;
+                &lt;/operation&gt;
+        &lt;/portType&gt;
+        &lt;binding name=&quot;echoBinding&quot; type=&quot;y:echoPortType&quot;&gt;
+                &lt;soap:binding style=&quot;rpc&quot; transport=&quot;http://schemas.xmlsoap.org/soap/http&quot;/&gt;
+                &lt;operation name=&quot;echo&quot;&gt;
+                        &lt;soap:operation soapAction=&quot;echo&quot;/&gt;
+                        &lt;input&gt;
+                                &lt;soap:body use=&quot;literal&quot;/&gt;
+                        &lt;/input&gt;
+                        &lt;output&gt;
+                                &lt;soap:body use=&quot;literal&quot;/&gt;
+                        &lt;/output&gt;
+                &lt;/operation&gt;
+        &lt;/binding&gt;
+.....
+</pre>
+<p>The binding says rpc/lit is required and in this case the
+message parts will need wrapping in the following order:</p>
+<ol type="1">
+<li>The first element needs to have the operation name as the local
+name and the operation namespace. (This happens to be the namespace
+of the porttype - in this case the targetnamespace of the
+WSDL.)</li>
+<li>The children of this element are non namespace qualified
+elements with the part names as local names (referred to as
+<strong>part element</strong>)</li>
+<li>In case the part refers to a standard type like the example
+WSDL, the content of the part element would be of that type. If the
+part refers to a complex type defined in the schema, the content of
+the part element becomes of that type. Having an element reference
+in the part when the binding is rpc is invalid.</li>
+</ol>
+For example, the input wire message for the echo operation
+mentioned in the above WSDL fragment would look like this:
+<pre>
+ &lt;op:<strong>echo</strong> xmlns:op=&quot;porttype namespace&quot;&gt;
+  &lt;<strong>part1</strong>&gt;Hello World&lt;/part1&gt;
+  &lt;<strong>part2</strong>&gt;123&lt;/part2&gt;
+ &lt;/op:echo&gt;
+</pre>
+Note that the element name is in bold. The first one is the
+operation name, the second and third are part names. It can be seen
+that it is possible to generate a schema representing this
+structure, and then treat the whole service as a pure doc/lit
+service. In this case, the following piece of schema is generated
+to make the rpc to doc conversion. Note that in this case the wire
+message stays unchanged. It is only a different WSDL authoring
+style
+<pre>
+ &lt;xs:element name=&quot;echo&quot;&gt;
+    &lt;xs:complexType&gt;
+      &lt;xs:sequence&gt;
+                &lt;xs:element name=&quot;part1&quot; type=&quot;xs:string&quot; /&gt; 
+                &lt;xs:element name=&quot;part2&quot; type=&quot;xs:int&quot; /&gt; 
+           &lt;/xs:sequence&gt;    
+    &lt;/xs:complexType&gt;
+ &lt;/xs:element&gt;
+</pre>
+What the Axis2 code generator does is exactly this. By looking
+at the binding style, it generates a wrapper schema in places
+required before handing over the Axis* hierarchy to the code
+generator engine. In every case (even when the schema needs to be
+unwrapped) this wrapping part will take place!
+<h2>Step 2 - Unwrapping the Schema</h2>
+<p>If the schema needs to be unwrapped, it brings up a few issues.
+This is mainly because the only thing that the emitters rely on
+when generating code is a mapping table.</p>
+<ol type="1">
+<li>When the schema is unwrapped, where will the unwrapping
+information remain?
+There has to be a store to keep the information seperated. The
+Axis * hierarchy can be used for this. It has nicely separated
+information holders and a parameter store that can hold an
+information bean.
+</li>
+<li>How do we maintain uniqueness among message part names?
+Part names are only unique across a message and not globally.
+However, due to the fact that we have a global mapping table, we
+need a way to differentiate between parts of different messages.
+The technique used here is to generate a QName that has the
+operation name as a namespace and a suffix (like _input) appended
+to the local name.
+</li>
+</ol>
+<p>Given these solutions, the first step in unwrapping is to walk
+the schema and figure out the unwrappable items. The key player of
+the unwrapping process is the unwrapping extension. It walks a
+given schema and figure out the unwrappable parts if there are
+any.</p>
+<p>The current unwrapper looks for the following patterns and fails
+if it is not found!</p>
+<pre>
+&lt; element &gt;
+      &lt; complexType &gt;
+           &lt; sequence &gt;
+               &lt; element /&gt;
+           &lt; /sequence &gt;
+       &lt; /complexType &gt;
+  &lt; /element &gt;
+ 
+</pre>
+<p>Once this pattern is detected, the unwrapper details will be
+added to the relevant AxisMessage component.</p>
+<h2>Step 3 - Populate Type Information</h2>
+<p>The next step is to populate the Type information for the parts.
+This has to be explicitly done by the data binding extensions, and
+currently the ADB and XMLbeans extensions populate the relevant
+AxisMessage by looking up their generated type systems. This type
+information goes into the AxisMessage inside a
+MessagePartInformationHolder instance.</p>
+<p>The following code fragment from the ADB extension shows how the
+AxisMessages get populated with the relevant type information. The
+code is almost the same for the XMLBeans extension. Note the items
+in bold.</p>
+<pre>
+ if (message.getParameter(Constants.UNWRAPPED_KEY) != null) {
+            XmlSchemaType schemaType = message.getSchemaElement().getSchemaType();
+            if (schemaType instanceof XmlSchemaComplexType) {
+                XmlSchemaComplexType cmplxType = (XmlSchemaComplexType) schemaType;
+                XmlSchemaParticle particle = cmplxType.getParticle();
+                if (particle instanceof XmlSchemaSequence) {
+                    XmlSchemaObjectCollection items =
+                            ((XmlSchemaSequence) particle).getItems();
+                    for (Iterator i = items.getIterator(); i.hasNext();) {
+                        Object item = i.next();
+                        if (item instanceof XmlSchemaElement) {
+                           XmlSchemaElement xmlSchemaElement = (XmlSchemaElement) item;
+                            XmlSchemaType eltSchemaType = xmlSchemaElement.getSchemaType();
+                            if (eltSchemaType != null) {
+                                <strong>populateClassName(eltSchemaType,mapper,opName,xmlSchemaElement.getName());</strong>
+                            } else if (xmlSchemaElement.getSchemaTypeName() != null) {
+                              eltSchemaType = findSchemaType(schemaMap,
+                                       xmlSchemaElement.getSchemaTypeName());
+                              if (eltSchemaType!=null){
+                                 populateClassName(eltSchemaType,mapper,opName,xmlSchemaElement.getName());
+                            }
+                          }
+                      }
+                  }
+              }
+         }
+   }
+</pre>
+<p>The populateClassName looks like this</p>
+<pre>
+ private static void populateClassName(XmlSchemaType eltSchemaType,
+                                          TypeMapper typeMap,
+                                          String opName,
+                                          String partName) {
+        Map metaInfoMap = eltSchemaType.getMetaInfoMap();
+        if (metaInfoMap != null) {
+            <strong>String className = (String) metaInfoMap.
+                    get(SchemaConstants.SchemaCompilerInfoHolder.CLASSNAME_KEY);
+            QName partQName = WSDLUtil.getPartQName(opName,
+                    WSDLConstants.INPUT_PART_QNAME_SUFFIX,
+                    partName);
+            typeMap.addTypeMappingName(partQName,className);</strong>
+            if (Boolean.TRUE.equals(
+                    metaInfoMap.get(SchemaConstants.
+                            SchemaCompilerInfoHolder.CLASSNAME_PRIMITVE_KEY))){
+                //this type is primitive - add that to the type mapper status
+                //for now lets add a boolean
+                typeMap.addTypeMappingStatus(partQName,Boolean.TRUE);
+            }
+
+        }
+    }
+</pre>
+<h2>Step 4 - Generate Code with Unwrapped Parameters</h2>
+<p>The next step is generating the actual code. The
+AxisServiceBasedMultiLanguageEmitter has a method that generates
+the XML model for the input parameters, and that method includes
+the relevant part parameters inside the relavant top level input
+parameter element.</p>
+<p>The relevant part of the XML model looks like this. Note that
+this intermediate XML model is the one that is parsed against the
+Stylesheets to generate the code.</p>
+<pre>
+&lt;input&gt;
+ &lt;param name=&quot;param4&quot; type=&quot;com.example.www.ServiceNameStub.Echo&quot; shorttype=&quot;Echo&quot; value=&quot;null&quot; location=&quot;body&quot; opname=&quot;echo&quot;&gt;
+        &lt;param name=&quot;param5&quot; type=&quot;java.lang.String&quot; shorttype=&quot;String&quot; value=&quot;null&quot; location=&quot;body&quot; opname=&quot;echo&quot; partname=&quot;Part1&quot; 
+                                                                                                primitive=&quot;yes&quot;/&gt;
+        &lt;param name=&quot;param6&quot; type=&quot;int&quot; shorttype=&quot;int&quot; value=&quot;0&quot; location=&quot;body&quot; opname=&quot;echo&quot; partname=&quot;Part2&quot; primitive=&quot;yes&quot;/&gt;
+  &lt;/param&gt;
+&lt;/input&gt;
+</pre>
+<p>The next part is handled by the template. Basically, the
+template looks after the generation of multiple parameters into the
+method signatures, and then the generating of the relevant
+serialization and deserialization code for the parameters.</p>
+<h2>Bringing the Parameters Together and Exploding Them</h2>
+<p>This is a somewhat controversial area. The current Axis2 code
+generator does the wrapping and unwrapping at the object level and
+not the XML level. In short, the exploded parameters are only a
+convenience and the explosion does not run down to the XML level.
+The following example of generated source code makes this
+clear:</p>
+<pre>
+ private org.apache.axiom.soap.SOAPEnvelope toEnvelope(
+        org.apache.axiom.soap.SOAPFactory factory, java.lang.String param1,
+        int param2, boolean optimizeContent) {
+        <strong>com.example.www.ServiceNameStub.Echo wrappedType = new com.example.www.ServiceNameStub.Echo();
+        wrappedType.setPart1(param1);
+        wrappedType.setPart2(param2);</strong>
+        rg.apache.axiom.soap.SOAPEnvelope emptyEnvelope = factory.getDefaultEnvelope();
+        emptyEnvelope.getBody().addChild(wrappedType.getOMElement(
+                        com.example.www.ServiceNameStub.Echo.MY_QNAME, factory));
+        
+        return emptyEnvelope;
+}
+</pre>
+<p>Note the lines in bold. The wrapped class will anyway be
+instantiated and used at the end, but what the user sees is
+different. Exploding the parameters happens in a similar way!</p>
+<h2>Conclusion</h2>
+<p>Axis2 RPC support is sort of a misty area, but it is based on a
+well defined set of rules which makes it not <em>that</em> misty
+after all!</p>
+<hr></hr>
+
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2007
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: webservices/axis2/site/1_3/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/Axis2ArchitectureGuide.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/Axis2ArchitectureGuide.html (added)
+++ webservices/axis2/site/1_3/Axis2ArchitectureGuide.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,1039 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                    <img src="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+            <div class="xleft">
+        Last Published: 08/13/2007
+                      </div>
+            <div class="xright">      <a href="../index.html">Axis2/Java</a>
+          |
+          <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+          |
+          <a href="../../../">Apache WS</a>
+          |
+          <a href="http://www.apache.org">Apache</a>
+          
+  
+
+  
+    
+  
+  
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+                   <h5>Axis2/Java</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../index.html">Home</a>
+        </li>
+          </ul>
+          <h5>Downloads</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../download.cgi">Releases</a>
+        </li>
+              
+    <li class="none">
+              <a href="../modules/index.html">Modules</a>
+        </li>
+              
+    <li class="none">
+              <a href="../tools/index.html">Tools</a>
+        </li>
+          </ul>
+          <h5>Documentation</h5>
+        <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+              <a href="../1_3/contents.html">Version 1.3</a>
+                <ul>
+                  
+    <li class="none">
+              <a href="../1_3/toc.html">Table of Contents</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/installationguide.html">Installation Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/userguide.html">User Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/pojoguide.html">POJO Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/spring.html">Spring Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+        </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+              <a href="../1_2/contents.html">Version 1.2</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_1_1/contents.html">Version 1.1.1</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_1/contents.html">Version 1.1</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_0/index.html">Version 1.0</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_95/index.html">Version 0.95</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_94/index.html">Version 0.94</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_93/index.html">Version 0.93</a>
+        </li>
+          </ul>
+          <h5>Resources</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../faq.html">FAQ</a>
+        </li>
+              
+    <li class="none">
+              <a href="../articles.html">Articles</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://wiki.apache.org/ws/FrontPage/Axis2/">Wiki</a>
+        </li>
+              
+    <li class="none">
+              <a href="../refLib.html">Reference Library</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://ws.apache.org/axis2/1_3/api/index.html">Online Java Docs</a>
+        </li>
+          </ul>
+          <h5>Get Involved</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../overview.html">Overview</a>
+        </li>
+              
+    <li class="none">
+              <a href="../svn.html">Checkout the Source</a>
+        </li>
+              
+    <li class="none">
+              <a href="../mail-lists.html">Mailing Lists</a>
+        </li>
+              
+    <li class="none">
+              <a href="../release-process.html">Release Process</a>
+        </li>
+              
+    <li class="none">
+              <a href="../guidelines.html">Developer Guidelines</a>
+        </li>
+              
+    <li class="none">
+              <a href="../siteHowTo.html">Build the Site</a>
+        </li>
+          </ul>
+          <h5>Project Information</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../team-list.html">Project Team</a>
+        </li>
+              
+    <li class="none">
+              <a href="../issue-tracking.html">Issue Tracking</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN">Source Code</a>
+        </li>
+              
+    <li class="none">
+              <a href="../thanks.html">Acknowledgements</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a>
+        </li>
+          </ul>
+                                       <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"></meta>
+<meta http-equiv="content-type" content=""></meta>
+Axis2 Architecture Guide
+<meta content="20050916;22455288"></meta>
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+<h1 align="center">Apache Axis2 Architecture Guide</h1>
+<p>This document gives an introduction to Axis2's modular
+architecture with explanations on every module.</p>
+<h2>Contents</h2>
+<ul>
+<li><a href="#bmBP">The Big Picture</a></li>
+<li>
+<a href="#requirements">Requirement of Axis2</a>
+</li>
+<li><a href="#thearchi">Axis2 Architecture</a>
+<ul>
+<li>
+<a href="#bmcore">Core Modules</a>
+</li>
+<li><a href="#bmother">Other Modules</a></li>
+<li>
+<a href="#bmInfoMod">Information Model</a>
+</li>
+<li><a href="#bmXML">XML Processing Model</a></li>
+<li>
+<a href="#bmSOAPPM">SOAP Processing Model</a>
+<ul>
+<li><a href="#default">Axis2 Default Processing Model</a></li>
+<li>
+<a href="#incomingsoap">Processing an Incoming SOAP
+Message</a>
+</li>
+<li><a href="#outgoing">Processing of the Outgoing Message</a></li>
+<li>
+<a href="#extending">Extending the SOAP Processing Model</a>
+<ul>
+<li><a href="#extendingwithhandlers">Extending the SOAP Processing
+Model with Handlers</a></li>
+<li>
+<a href="#extendingwithmodules">Extending the SOAP Processing
+Model with Modules</a>
+</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>
+<a href="#servicearchive">Service Archive</a>
+</li>
+<li><a href="#modulearchive">Module Archive</a></li>
+</ul>
+</li>
+<li>
+<a href="#bmClientAPI">Client API</a>
+<ul>
+<li><a href="#oneway">One Way Messaging Support</a></li>
+<li>
+<a href="#requestresponse">Request Response Messaging
+Support</a>
+</li>
+</ul>
+</li>
+<li><a href="#bmTransports">Transports</a></li>
+<li>
+<a href="#bmWSDL">Code Generation</a>
+</li>
+<li><a href="#bmDB">Data Binding</a>
+<ul>
+<li><a href="#integration">Integration with Code Generation
+Engine</a></li>
+<li>
+<a href="#serial">Serialization and De-Serialization</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+<a name="bmBP"></a>
+<h2>The Big Picture</h2>
+A new architecture for Axis was introduced during the August
+2004 Summit in Colombo, Sri Lanka. This new architecture on which
+Axis2 is based is more flexible, efficient, and configurable in
+comparison to <a href="http://ws.apache.org/axis/java/architecture-guide.html">Axis1.x
+architecture</a>. Some well established concepts from Axis 1.x,
+like handlers etc., have been preserved in this new
+architecture.
+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.
+<a name="requirements"></a>
+<h2>Requirement of Axis2</h2>
+In 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 a SOAP Sender and
+received by a SOAP Receiver. A single SOAP delivery is the most
+basic unit that builds the Web service interaction.
+Each SOAP Node may be written in specific programming language,
+may it be Java, C++, .NET or Perl, but the Web services allow them
+to interoperate. This is possible because on the wire each Web
+service interaction is done via SOAP, which is common to every SOAP
+Node.
+<img alt="" src="images/archi-guide/soap.gif" name="Graphic1" align="bottom" width="691" height="319" border="0" id="Graphic1"></img>
+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.
+Axis2 handles SOAP processing along with numerous other tasks.
+This makes life of a Web service developer a whole lot easier.
+Following are the identified requirements:
+<ol type="1">
+<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 its components through
+deployment.</li>
+<li>Ability to send and receive SOAP messages with different
+transports.</li>
+</ol>
+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- <a href="http://www.w3.org/TR/wsdl">WSDL</a>, <a href="http://www.w3.org/TR/soap/">SOAP</a> and <a href="http://www.w3.org/Submission/ws-addressing/">WS-Addressing</a>.
+Other specifications like JAX-RPC, <a href="http://java.sun.com/webservices/saaj/index.jsp">SAAJ</a> and
+<a href="http://www.w3.org/Submission/WS-Policy/">WS-Policy</a> are
+layered on top of the Core Architecture.
+<a name="thearchi"></a>
+<h2>Axis2 Architecture</h2>
+Axis2 architecture lays out some principals to preserve the
+uniformity. They are as follows:
+<ul>
+<li>
+Axis2 architecture separates the logic and the states. Code that
+does the processing does not have a state inside Axis2. This allows
+code to be executed freely by parallel threads.
+</li>
+<li>All the information is kept in one information model, allowing
+the system to be suspended and resumed.</li>
+</ul>
+Axis2 architecture is modular. Therefore, Axis2 Framework is
+built up of core modules that collectively make up the core
+architecture of Axis2. Non-core/other modules are layered on top of
+these core modules.
+<a name="bmcore"></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 consists of a hierarchy of information. The system
+manages the life cycle of the objects in this hierarchy.</li>
+<li>
+<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 under the Web services project, allowing that
+sub-project (<a href="http://ws.apache.org/commons/axiom/index.html">AXIOM</a> or AXis
+Object Model) to provide a simple API for SOAP and XML info-set. It
+hides the complexities of efficient XML processing within its
+implementation.
+</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 specific places.</li>
+<li>
+<a href="#bmDeployment">Deployment Model</a> - The Axis2
+deployment model allows the user to deploy services, configure the
+transports, and extend the SOAP Processing model per system,
+service, or operation basis.
+</li>
+<li><a href="#bmClientAPI">Client API</a> - This provides a
+convenient API for users to communicate with Web services using
+Axis2. There are a set of classes to interact with IN-OUT and
+IN-Only style <a href="http://www.w3.org/2002/ws/cg/2/07/meps.html">Message Exchange
+Patterns (MEPs)</a>, where they can be used to construct any other
+MEP. (Please note that even if the client API has in-built support
+for the above named MEPs, it does not by any means limit Axis2's
+flexibility to support custom MEPs.)</li>
+<li>
+<a href="#bmTransports">Transports</a> - Axis2 defines a
+transport framework that enables the user to use multiple different
+transports. The transports fit into specific places in the SOAP
+processing model. The implementation provides a few common
+transports and the user can write or plug-in new ones if and when
+it is needed.
+</li>
+</ul>
+<a name="bmother"></a>
+<h3>Other Modules:</h3>
+<ul>
+<li><a href="#bmWSDL">Code Generation</a> - Axis2 provides a code
+generation tool that generates server side and client side code
+along with descriptors and a test case. The generated code
+simplifies the service deployment and the service invocation,
+increasing the usability of Axis2.</li>
+<li>
+<a href="#bmDB">Data Binding</a> - The basic client API of Axis2
+lets the users process SOAP at the infoset level, whereas data
+binding extends it to make it more convenient to users by
+encapsulating the infoset layer and providing a programming
+language specific interface.
+</li>
+</ul>
+<map name="Graphic2Map" id="g2m">
+<area shape="rect" coords="123,31,222,97" href="#bmInfoMod" alt=""></area>
+<area shape="rect" coords="239,62,319,134" href="#bmXML" alt=""></area>
+<area shape="rect" coords="127,112,218,177" href="#bmSOAPPM" alt=""></area>
+<area shape="rect" coords="12,39,89,95" href="#bmDeployment" alt=""></area>
+<area shape="rect" coords="0,108,94,156" href="#bmWSDL" alt=""></area>
+<area shape="rect" coords="350,31,426,86" href="#bmClientAPI" alt=""></area>
+<area shape="rect" coords="350,114,421,164" href="#bmTransports" alt=""></area></map>
+<img src="images/archi-guide/all.png" name="Graphic2" width="426" alt="" height="189" border="0" align="bottom" usemap="#Graphic2Map" id="Graphic2"></img>
+<a name="bmInfoMod"></a>
+<h2>Information Model</h2>
+The Information Model has two main hierarchies--Contexts and
+Descriptions. This model is described in UML notations below.
+<img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom" alt="" width="400" height="443" border="0" id="Graphic3"></img>
+( A ----&lt;&gt; B says, B has 1 or more objects of A.
+A------&gt;B says, the given relationship holds between A and
+B.)
+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 objects that can have more than one instance
+(e.g., Message Contexts).
+These two hierarchies create 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 the starting point is a Context
+then it searches in the Description hierarchy as well.
+This allows the user to declare and override values, with the
+result being a very flexible configuration model. This flexibility
+could be the <em>Achilles heel</em> for the system, however, as
+searches are expensive, especially for parameters that turn out not
+to exist. Yet in the final analysis, the Axis Team believes that
+this flexibility serves developers better overall.
+<table class="bodyTable">
+<col width="112"></col>
+<col width="371"></col>
+<col width="103"></col>
+<col width="336"></col>
+<tbody>
+<tr class="a">
+<td><strong>Context</strong></td>
+<td><strong>Description</strong></td>
+<td><strong>Configuration</strong></td>
+<td><strong>Description</strong></td>
+</tr>
+<tr class="b">
+<td>
+Configuration Context
+</td>
+<td>
+Holds the Axis2's run time status. A deep copy of this would
+essentially make a copy of Axis2.
+</td>
+<td>
+Axis Configuration
+</td>
+<td>
+Holds all global configurations: transports, global modules,
+parameters, services, etc.
+</td>
+</tr>
+<tr class="a">
+<td>
+Service Group Context
+</td>
+<td>
+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 belongs to this service
+group. This can be used to share information between services
+(within the same service group) in a single interaction.
+</td>
+<td>
+AxisServiceGroup
+</td>
+<td>
+Holds deployment time information about a particular service
+group.
+</td>
+</tr>
+<tr class="b">
+<td>
+<p>Service Context</p>
+</td>
+<td>
+<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. The life cycle
+depends on the scope of the service.</p>
+</td>
+<td>
+<p>AxisService</p>
+</td>
+<td>
+<p>Holds the Operations and the service level configurations</p>
+</td>
+</tr>
+<tr class="a">
+<td>
+<p>Operation Context</p>
+</td>
+<td>
+<p>Holds the information about the current MEP instance, maintains
+the messages in the current MEP etc.</p>
+</td>
+<td>
+<p>AxisOperation</p>
+</td>
+<td>
+<p>Holds the operation level configurations</p>
+</td>
+</tr>
+<tr class="b">
+<td><a name="messageContext"></a>
+<p>Message Context</p>
+</td>
+<td>
+<p>Holds all the information about the message currently being
+executed.</p>
+</td>
+<td>
+<p>AxisMessage</p>
+</td>
+<td>
+<p>Holds message level static information like the schema of the
+particular message.</p>
+</td>
+</tr>
+</tbody>
+</table>
+<a name="bmXML"></a>
+<h2>XML Processing Model</h2>
+<p>As mentioned above, the XML processing model of Axis2 has become
+a separate sub-project, called <a href="http://ws.apache.org/commons/axiom/index.html">Apache Axiom</a>,
+in the Apache Web services project. Please refer to the <a href="OMTutorial.html">OM Tutorial</a> for more information.</p>
+<a name="bmSOAPPM"></a>
+<h2>SOAP Processing Model</h2>
+<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" alt="" align="bottom" width="755" height="348" border="0" id="Graphic4"></img></p>
+<p>The architecture identified two basic actions a SOAP processor
+should perform, sending and receiving SOAP messages. The
+architecture provides two pipes (or flows) to perform these two
+basic actions. The 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 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 will be executed. The handlers can be registered in
+global, service, or operation scope 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> activates. The <i>Out Pipe</i> will invoke 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>The processing explained above happens for each and every SOAP
+message that is exchanged. After processing one message, Axis2 may
+decide to create other SOAP messages, in which case more complex
+message patterns emerge. However, Axis2 always views 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 do 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 called 'phases' within Axis2. A Handler
+always runs inside a specific 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>
+<a name="default"></a>
+<h3>Axis2 Default Processing Model</h3>
+<p>Axis2 has some inbuilt handlers that run in inbuilt phases and
+they create the default configuration for Axis2. We will be looking
+more in to how to extend the default processing Model in the next
+section.</p>
+There are three special handlers defined in Axis2.
+<ol type="1">
+<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. ( See more information on <a href="http://www.wso2.net/tutorials/axis2/java/2006/06/18/operation-service-message-is-destined-to">
+Dispatching</a>)</li>
+</ol>
+<ul>
+<li><a name="mr"></a>Message Receiver - Consumes the SOAP
+message and hands it over to the application. The message receiver
+is the last handler of the in-pipe</li>
+<li>
+Transport Sender - Sends the SOAP message to the SOAP endpoint
+the message is destined to. Always runs as the last handler in the
+out-pipe
+</li>
+</ul>
+<a name="incomingsoap"></a>
+<h3>Processing an Incoming SOAP Message</h3>
+An 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 <a href="#messageContext">Message Context</a> is created from the incoming
+SOAP message. This message context encapsulates all the
+information, including the SOAP message itself, transport headers,
+etc., inside it. Then the <i>In Pipe</i> is executed with the
+Message Context.
+Let us see what happens at each phase of the execution. This
+process can happen in the server or in the client.
+<ol type="1">
+<li><strong>Transport Phase</strong> - The handlers are in the
+phase that processes transport specific information such as
+validating incoming messages by looking at various transport
+headers, adding data into message contexts, etc.</li>
+<li><strong>Pre-Dispatch Phase</strong>- The main functionality of
+the handlers in this phase is to populate message context to do the
+dispatching. For example, processing of addressing headers of the
+SOAP message, if any, happens 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 try to find the correct service and operation this
+particular message is destined for.<br></br>
+The post condition of the dispatch phase (any phase can contain a
+post condition) checks whether a service and an operation were
+found by the dispatchers. If not, the execution will halt and
+return a &quot;service not found' error.</li>
+<li><strong>User Defined Phases</strong> - Users can engage their
+custom handlers here.</li>
+<li><strong>Message Validation Phase</strong> - 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 be executed
+as the last handler of this phase.</li>
+</ol>
+There may be other handlers in any of these phases. Users may
+use custom handlers to override the processing logic in each of
+these phases.
+<a name="outgoing"></a>
+<h3>Processing of the Outgoing Message</h3>
+The <em>Out Pipe</em> is simpler because the service and the
+operation to dispatch are known by the time the pipe is executed.
+The <em>Out Pipe</em> may be initiated by the
+<a href="#mr">Message Receiver</a> or the Client API
+implementation. Phases of the <em>Out Pipe</em> are described
+below:
+<ol type="1">
+<li><strong>Message Initialize Phase</strong> - First phase of the
+<em>Out Pipe</em>. Serves as the placeholder for the custom
+handlers.</li>
+<li><strong>User Phases</strong> - Executes handlers in
+user-defined phases.</li>
+<li><strong>Transports Phase</strong> - Executes any transport
+handlers taken from the associated transport configuration. The
+last handler would be a transport sender which will send the SOAP
+message to the target endpoint.</li>
+</ol>
+<a name="extending"></a>
+<h3>Extending the SOAP Processing Model</h3>
+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 on making it extendable.
+The idea behind introducing step-wise processing of the SOAP
+message in terms of handlers and 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 of the default processing behavior. The SOAP
+Processing Model can be extended with <a href="#extendingwithhandlers">handlers</a> or <a href="#extendingwithmodules">modules</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 type="1">
+<li>as the first handler in a phase,</li>
+<li>as the last handler in a phase,</li>
+<li>before a given handler,</li>
+<li>or after a given handler.</li>
+</ol>
+<a name="extendingwithmodules"></a>
+<h4>Extending the SOAP Processing Model with Modules</h4>
+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:
+<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.
+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 adds Reliable Messaging
+capability to a service, the &quot;Create Sequence&quot; operation needs to
+be available to the service endpoint. 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.
+A service, operation, 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.
+Modules cannot be added (no hot deployment) while the Axis2
+engine is running, but they will be available once the system is
+restarted.
+<a name="bmDeployment"></a>
+<h2>Deployment</h2>
+The Deployment Model provides a concrete mechanism to configure
+Axis2. This model has three entities that provide the
+configuration.
+<a name="xmlfile"></a>
+<h3>The axis2.xml file</h3>
+This file holds the global configuration for the client and
+server, and provides the following information:
+<ol type="1">
+<li>The global parameters</li>
+<li>Registered transport-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>
+The 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
+the following information.
+<ol type="1">
+<li>Service level parameters</li>
+<li>Modules that are engaged at service level</li>
+<li>Service Specific <a href="#mr">Message Receivers</a></li>
+<li>Operations inside the service</li>
+</ol>
+<a name="modulearchive"></a>
+<h3>Module Archive</h3>
+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.
+When the system starts up, Axis2 prompts the deployment model to
+create an Axis Configuration. The deployment model first finds the
+axis2.xml file and builds 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. The system will build contexts on top of the Axis
+Configuration. After this, Axis2 is ready to send or receive SOAP
+messages. Hot deployment is only allowed for services.
+<a name="bmClientAPI"></a>
+<h2>Client API</h2>
+There are three parameters that decide the nature of the Web
+service interaction.
+<ol type="1">
+<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>
+Variations of the three parameters can result in an indefinite
+number of scenarios. Even though Axis2 is built on a core that
+supports any messaging interaction, the developers were compelled
+to provide built-in support for only the two most widely used
+Message Exchange Patterns (MEPs).
+The 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.
+<a name="oneway"></a>
+<h3>One Way Messaging Support</h3>
+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.
+<a name="requestresponse"></a>
+<h3>In-Out (Request Response) Messaging Support</h3>
+The In-Out support is provided by the <code>sendReceive()</code>
+method in ServiceClient. This provides a simpler interface for the
+user. The Client API has four ways to configure a given message
+exchange
+<ol type="1">
+<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 that sends the SOAP message</li>
+<li>Listener transport - transport that receives the response</li>
+<li>Use Separate Channel - determines whether the response is sent
+over a separate transport connection or not. This can be false only
+when the sender and listener transport is same and is a Two-Way
+transport.</li>
+</ol>
+Depending on the values of the above four parameters, Axis2
+behaves differently.
+<a name="bmTransports"></a>
+<h2>Transports</h2>
+Axis2 has two basic constructs for transports, namely: Transport
+Senders and Transport Receivers. These are accessed via the
+AxisConfiguration.
+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 the server is trying
+to respond, then the out going transport will be the output stream
+of the incoming transport (if it is two-way transport).
+At the client side, the user is free to specify the transport to
+be used.
+Transport Senders and Transport Receivers contain the following
+information.
+<ol type="1">
+<li>Transport Sender for Out Configuration</li>
+<li>Transport Listener for In Configuration</li>
+<li>Parameters of the transport</li>
+</ol>
+Each and every transport out configuration defines a transport
+sender. The transport sender sends the SOAP message depending on
+its configuration.
+The 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.
+Axis2 presently supports the following transports:
+<ol type="1">
+<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 simplest transport, but needs 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 at fixed time
+intervals.</li>
+<li>JMS</li>
+</ol>
+<a name="bmWSDL"></a>
+<h2>Code Generation</h2>
+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.
+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.
+<img src="images/archi-guide/CodegenArchitecture-new.gif" name="Graphic6" alt="" align="bottom" border="0" id="Graphic6"></img>
+The fact here is that it is the same information that is
+extracted from the WSDL no matter what output 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 in the desired output
+language. No matter what the output language is, the process is the
+same except for the XSL template that is used.
+<a name="bmDB"></a>
+<h2>Data Binding</h2>
+<h3>Integration with the Code Generation Engine</h3>
+Databinding for Axis2 is implemented in an interesting manner.
+Databinding has not been included in the core deliberately, and
+hence the code generation allows different data binding frameworks
+to be plugged in. This is done through an extension mechanism where
+the codegen engine first calls the extensions 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.
+<strong>The following diagram shows the structure:</strong>
+<img src="images/codegen.gif" name="Graphic7" align="bottom" border="0" id="Graphic7"></img>
+<strong>The following databinding extensions are
+available:</strong>
+<ol type="1">
+<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 preferred 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
+users have for data binding.</li>
+</ol>
+<a name="serial"></a>
+<h3>Serialization and De-Serialization of Data bound classes</h3>
+AXIOM is based on the StAX API (Streaming API for XML).
+Xml-beans also supports this API. Data binding in Axis2 is achieved
+through interfacing the AXIOM with the Xml-beans using the StAX
+API. At the time of code generation, there will be utility methods
+generated inside the stub (or the message receiver) that can
+de-serialize from AXIOM to a data bound object and serialize from a
+data bound object to AXIOM. For example, if the WSDL has an
+operation called &quot;echoString&quot;, once the code is generated, the
+following methods will be generated inside the relevant
+classes.
+<pre>
+public static
+org.apache.axiom.om.OMElement toOM(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>
+
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2007
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: webservices/axis2/site/1_3/WS_policy.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_3/WS_policy.html?view=auto&rev=565295
==============================================================================
--- webservices/axis2/site/1_3/WS_policy.html (added)
+++ webservices/axis2/site/1_3/WS_policy.html Mon Aug 13 03:13:18 2007
@@ -0,0 +1,457 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+<html>
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                    <img src="http://ws.apache.org/axis2/images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+            <div class="xleft">
+        Last Published: 08/13/2007
+                      </div>
+            <div class="xright">      <a href="../index.html">Axis2/Java</a>
+          |
+          <a href="http://ws.apache.org/axis2/c">Axis2/C</a>
+          |
+          <a href="../../../">Apache WS</a>
+          |
+          <a href="http://www.apache.org">Apache</a>
+          
+  
+
+  
+    
+  
+  
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+                   <h5>Axis2/Java</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../index.html">Home</a>
+        </li>
+          </ul>
+          <h5>Downloads</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../download.cgi">Releases</a>
+        </li>
+              
+    <li class="none">
+              <a href="../modules/index.html">Modules</a>
+        </li>
+              
+    <li class="none">
+              <a href="../tools/index.html">Tools</a>
+        </li>
+          </ul>
+          <h5>Documentation</h5>
+        <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+              <a href="../1_3/contents.html">Version 1.3</a>
+                <ul>
+                  
+    <li class="none">
+              <a href="../1_3/toc.html">Table of Contents</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/installationguide.html">Installation Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/quickstartguide.html">QuickStart Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/userguide.html">User Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/pojoguide.html">POJO Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/spring.html">Spring Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/webadminguide.html">Web Administrator's Guide</a>
+        </li>
+                  
+    <li class="none">
+              <a href="../1_3/migration.html">Migration Guide (from Axis1)</a>
+        </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+              <a href="../1_2/contents.html">Version 1.2</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_1_1/contents.html">Version 1.1.1</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_1/contents.html">Version 1.1</a>
+        </li>
+              
+    <li class="none">
+              <a href="../1_0/index.html">Version 1.0</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_95/index.html">Version 0.95</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_94/index.html">Version 0.94</a>
+        </li>
+              
+    <li class="none">
+              <a href="../0_93/index.html">Version 0.93</a>
+        </li>
+          </ul>
+          <h5>Resources</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../faq.html">FAQ</a>
+        </li>
+              
+    <li class="none">
+              <a href="../articles.html">Articles</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://wiki.apache.org/ws/FrontPage/Axis2/">Wiki</a>
+        </li>
+              
+    <li class="none">
+              <a href="../refLib.html">Reference Library</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://ws.apache.org/axis2/1_3/api/index.html">Online Java Docs</a>
+        </li>
+          </ul>
+          <h5>Get Involved</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../overview.html">Overview</a>
+        </li>
+              
+    <li class="none">
+              <a href="../svn.html">Checkout the Source</a>
+        </li>
+              
+    <li class="none">
+              <a href="../mail-lists.html">Mailing Lists</a>
+        </li>
+              
+    <li class="none">
+              <a href="../release-process.html">Release Process</a>
+        </li>
+              
+    <li class="none">
+              <a href="../guidelines.html">Developer Guidelines</a>
+        </li>
+              
+    <li class="none">
+              <a href="../siteHowTo.html">Build the Site</a>
+        </li>
+          </ul>
+          <h5>Project Information</h5>
+        <ul>
+              
+    <li class="none">
+              <a href="../team-list.html">Project Team</a>
+        </li>
+              
+    <li class="none">
+              <a href="../issue-tracking.html">Issue Tracking</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN">Source Code</a>
+        </li>
+              
+    <li class="none">
+              <a href="../thanks.html">Acknowledgements</a>
+        </li>
+              
+    <li class="none">
+              <a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a>
+        </li>
+          </ul>
+                                       <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"></meta>
+<meta http-equiv="content-type" content="text/html; charset=us-ascii"></meta>
+WS Policy Support in Axis2
+<meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"></meta>
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></link>
+</head>
+
+<h1 align="center">Web Services Policy Support In Apache Axis2</h1>
+<p>This document gives you an introduction to the role of Web
+services policy in Apache Axis2.</p>
+<p>Send your feedback to: <a href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>.
+(Subscription details are available on the <a href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.)
+Kindly prefix every email subject with [Axis2].</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>
+To consume non trivial web services you must fully understand
+its XML contract (WSDL) along with any other additional
+requirements, capabilities, or preferences that translate to the
+configuration of the service and essentially becomes the policies
+of the service.
+WS Policy framework provides a way to express the policies of a
+service in a machine-readable way. A Web services infrastructure
+can be enhanced to understand and enforce policies at runtime. For
+instance, a service author might write a policy requiring a digital
+signature and encryption, while service consumers can use the
+policy information to reason out whether they can adhere to this
+policy information to use the service.
+Furthermore, Web service infrastructure can be enhanced to
+enforce those requirements without requiring the service author to
+write even a single line of code.
+<a name="client"></a>
+<h2>Client Side WS-Policy Support</h2>
+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, plus it will generate additional methods in the
+stub where the user can set certain properties. For instance, if
+there is a security policy attached to a binding, the generated
+stub will engage the security module for that service with the
+appropriate security configurations with some addtional methods
+that the user can use to set properties in the generated stub.
+<h3>How it works:</h3>
+<h4>Phase 1: At PolicyEvaluator</h4>
+<p>The Codegen engine runs a few of its registered extensions
+before it generates the stub. When the PolicyEvalutor (which is a
+registered Codegen extension) is initialized, it populates a
+registry of QNames of supported policy assertions to
+PolicyExtensions.</p>
+<p>For instance, module Foo might have a mapping of assertion
+{http://test.com/foo, foo} which means any assertion that has this
+name will be processed by this module. The Foo module might
+implement the ModulePolicyExtension interface through which the
+PolicyExtension object can be obtained.</p>
+<p>A <strong>PolicyExtension</strong> is the access point for a
+module to add any additional methods to the stub. For instance a
+Reliable Messaging module can add startSequence() 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 the PolicyEvaluator, the effective
+policy of each message of every operation is calculated based on
+policy information declared in the WSDL document. Here we assume
+that the 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 assertions that
+can be processed by a single module.</p>
+<pre>
+  &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;b:Bar/&gt;      =&gt;                               &lt;/wsp:Policy&gt;       
+                                   &lt;/wsp:Policy&gt;
+  &lt;/wsp:Policy&gt;
+</pre>
+<p>Then each policy is given 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 through the Custom
+PolicyExtensionTemplate.xsl at a latter point of time.</p>
+<p>For instance, depending on the policy, the 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 that can be used to get specific
+propreties from the user. 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 AxisServiceBasedMultiLanguageClientEmitter</h4>
+<p>Further, policies (based on the WSDL) at appropriate levels
+(service level, operation level) are stored as policy strings in
+the stub. If there are a few policies at a given level, they are
+merged together and represented as a single policy in the stub. Few
+more generic methods are also added to the stub which are used to
+evaluate and process the 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 are set in the
+AxisDescription hierarchy that is used in the stub. In other words,
+any policy information available in the WSDL will be preserved in
+the AxisService object that is used in the stub.</p>
+<p>Then based on its policy, each AxisDescription is engaged to a
+set of modules. Modules can do a prior calculation of
+configurations if needed at the engagement.</p>
+<p>When the stub method is invoked, those modules which are engaged
+to that AxisDescription, access the policy for that operation via
+the AxisDescription object. It can get the other required
+information from the MessageContext, which is stored by stub
+methods that the module has added to the stub earlier, through the
+ModulePolicyExtension implementation. The modules are required to
+load their configurations according to the effective policy, which
+is set at AxisDescription, and the properties they get via
+MessageContext.</p>
+<a name="server"></a>
+<h2>Server Side WS-Policy Support</h2>
+<p>In this current release, the Apache Axis2 framework uses the
+WS-Commons/Neethi framework to manipulate policy documents. All its
+description builders store the 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 the service elements of the 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>Further, when a service is deployed, an arbitary policy
+alternative is selected and set for each AxisOperation and
+AxisMessages of the AxisService. If the selected Policy alternative
+cannot be supported by any modules that are capable of processing
+the selective alternative, then the service is considered as a
+faulty service. Else, the set of modules is engaged at appropriate
+levels to support the requirments and capabilities that are defined
+in the Policies associated with the AxisDescription.</p>
+<p>It is evident that there is some work left to make Apache Axis2
+a fully fledged ws-policy supported Web service infrastructure.
+However, 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">Home Page</a></li>
+<li>Sanka Samaranayake, March 2006. <a href="http://www.wso2.net/articles/neethi/java/2006/01/24/ws-policy">Web services Policy - Why, What &amp; How</a></li>
+<li><a href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/">WS-commons/policy SVN</a></li>
+<li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf">Web Services Policy Framework (WS-Policy)</a></li>
+</ul>
+
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2007
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org


Mime
View raw message