You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ch...@apache.org on 2006/10/05 11:56:40 UTC
svn commit: r453167 [1/6] - in /webservices/axis2/trunk/java/xdocs: ./ adb/
adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ resources/
resources/schemas/
Author: chatra
Date: Thu Oct 5 02:56:34 2006
New Revision: 453167
URL: http://svn.apache.org/viewvc?view=rev&rev=453167
Log:
moving all files in 1_1 dir one level up in to the xdocs root
Added:
webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html
webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
webservices/axis2/trunk/java/xdocs/WS_policy.html
webservices/axis2/trunk/java/xdocs/adb/
webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html
webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html
webservices/axis2/trunk/java/xdocs/adb/adb-howto.html
webservices/axis2/trunk/java/xdocs/adb/adb-tweaking.html
webservices/axis2/trunk/java/xdocs/adb/images/
webservices/axis2/trunk/java/xdocs/adb/images/ADB.jpg (with props)
webservices/axis2/trunk/java/xdocs/axis2config.html
webservices/axis2/trunk/java/xdocs/http-transport.html
webservices/axis2/trunk/java/xdocs/images/Architecture.gif (with props)
webservices/axis2/trunk/java/xdocs/images/AxisService.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/Component.png (with props)
webservices/axis2/trunk/java/xdocs/images/OM001.gif (with props)
webservices/axis2/trunk/java/xdocs/images/OM002.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/OM003.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/OM004.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/OM005.gif (with props)
webservices/axis2/trunk/java/xdocs/images/OM006.gif (with props)
webservices/axis2/trunk/java/xdocs/images/OM007.gif (with props)
webservices/axis2/trunk/java/xdocs/images/OM008.gif (with props)
webservices/axis2/trunk/java/xdocs/images/OM1.png (with props)
webservices/axis2/trunk/java/xdocs/images/ServerSideFault.png (with props)
webservices/axis2/trunk/java/xdocs/images/ServiceDesc.gif (with props)
webservices/axis2/trunk/java/xdocs/images/TotalArch.png (with props)
webservices/axis2/trunk/java/xdocs/images/WomBuilder.png (with props)
webservices/axis2/trunk/java/xdocs/images/activate.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/admin.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/adminlogin.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/adminmain.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/ant.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/
webservices/axis2/trunk/java/xdocs/images/archi-guide/CodegenArchitecture-new.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/CodegenArchitecture.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/all.png (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/big-picture.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/contexts.png (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/phases.png (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/soap-processing.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi-guide/soap.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi001.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi002.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi003.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi004.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi005.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi006.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi007.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi008.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi009.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi010.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi011.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi012.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi013.gif (with props)
webservices/axis2/trunk/java/xdocs/images/archi014.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi015.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi016.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi017.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi018.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi019.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi020.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi021.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi022.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi023.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi024.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi025.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/archi026.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/arrow_left.gif (with props)
webservices/axis2/trunk/java/xdocs/images/arrow_right.gif (with props)
webservices/axis2/trunk/java/xdocs/images/axis.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/ayncresult.png (with props)
webservices/axis2/trunk/java/xdocs/images/call.png (with props)
webservices/axis2/trunk/java/xdocs/images/callback.png (with props)
webservices/axis2/trunk/java/xdocs/images/cases.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clientAPi.png (with props)
webservices/axis2/trunk/java/xdocs/images/clientside.png (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image002.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image004.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image006.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image008.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image010.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image012.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image014.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image016.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image018.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image020.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image022.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image024.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/clip_image026.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/codegen.gif (with props)
webservices/axis2/trunk/java/xdocs/images/correlator.png (with props)
webservices/axis2/trunk/java/xdocs/images/deploymetncomponent.png (with props)
webservices/axis2/trunk/java/xdocs/images/editserviecpara.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/engine1.png (with props)
webservices/axis2/trunk/java/xdocs/images/faultmsg.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/faultservice.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/globalchain.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/happyaxis.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image001.png (with props)
webservices/axis2/trunk/java/xdocs/images/image002.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image003.png (with props)
webservices/axis2/trunk/java/xdocs/images/image004.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image005.gif (with props)
webservices/axis2/trunk/java/xdocs/images/image005.png (with props)
webservices/axis2/trunk/java/xdocs/images/image006.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image007.png (with props)
webservices/axis2/trunk/java/xdocs/images/image008.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image009.png (with props)
webservices/axis2/trunk/java/xdocs/images/image010.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image011.png (with props)
webservices/axis2/trunk/java/xdocs/images/image012.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/image013.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/inactivate.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/maven.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/module.png (with props)
webservices/axis2/trunk/java/xdocs/images/moduleengage.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/modules.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/new.gif (with props)
webservices/axis2/trunk/java/xdocs/images/om2.png (with props)
webservices/axis2/trunk/java/xdocs/images/om3.png (with props)
webservices/axis2/trunk/java/xdocs/images/parameters.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/select_service_for_handler.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/send.png (with props)
webservices/axis2/trunk/java/xdocs/images/sendAsync.png (with props)
webservices/axis2/trunk/java/xdocs/images/sendRecievce.png (with props)
webservices/axis2/trunk/java/xdocs/images/sendRecieveAsync.png (with props)
webservices/axis2/trunk/java/xdocs/images/sendRecieveWithListnere.png (with props)
webservices/axis2/trunk/java/xdocs/images/serverSide.png (with props)
webservices/axis2/trunk/java/xdocs/images/service.png (with props)
webservices/axis2/trunk/java/xdocs/images/serviceHandlers.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/servicegroups.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/
webservices/axis2/trunk/java/xdocs/images/userguide/DirectoryStructure.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/ModuleView.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/MyServiceDeployed.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/ServiceDeployed.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/ServiceItems.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/TestClient.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/userguide/http-get-ws.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/viewphases.jpg (with props)
webservices/axis2/trunk/java/xdocs/images/wom.png (with props)
webservices/axis2/trunk/java/xdocs/index_docs.html
webservices/axis2/trunk/java/xdocs/installationguide.html
webservices/axis2/trunk/java/xdocs/jibx/
webservices/axis2/trunk/java/xdocs/jibx/jibx-codegen-integration.html
webservices/axis2/trunk/java/xdocs/jms-transport.html
webservices/axis2/trunk/java/xdocs/mail-configuration.html
webservices/axis2/trunk/java/xdocs/mail-transport.html
webservices/axis2/trunk/java/xdocs/migration.html
webservices/axis2/trunk/java/xdocs/mtom-guide.html
webservices/axis2/trunk/java/xdocs/resources/
webservices/axis2/trunk/java/xdocs/resources/schemas/
webservices/axis2/trunk/java/xdocs/resources/schemas/module.xsd
webservices/axis2/trunk/java/xdocs/resources/schemas/services.xsd
webservices/axis2/trunk/java/xdocs/rest-ws.html
webservices/axis2/trunk/java/xdocs/soapmonitor-module.html
webservices/axis2/trunk/java/xdocs/spring.html
webservices/axis2/trunk/java/xdocs/tcp-transport.html
webservices/axis2/trunk/java/xdocs/transport_howto.html
webservices/axis2/trunk/java/xdocs/userguide.html
webservices/axis2/trunk/java/xdocs/webadminguide.html
Added: webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html (added)
+++ webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,266 @@
+<?xml version="1.0" encoding=""?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="content-type" content="" />
+ <title>Axis2 RPC Support</title>
+</head>
+
+<body>
+<h1>Axis2 RPC Support</h1>
+
+<p>This documents talks about the Axis2's Remote Procedure Calls support in a
+set of easy to understand implementation steps.</p>
+
+<h2>Introduction</h2>
+
+<p>Axis2 Remote Procedure Calls (RPC) support may seem somewhat tricky and
+confusing at first glance. However, Axis2 RPC strategy is based on a well
+defined set of rules and once the details are in place, it becomes clear as
+day. This document aims to drill down to the details of this strategy and
+fills up most of the fairly unknown bits and pieces. Note that Axis2
+currently does not support the rpc/encoded style fully. It's 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> .....
+ < message name="requestMessage">
+ <part name="part1" type="xs:string"/>
+ <part name="part2" type="xs:int"/>
+ </message>
+ <message name="responseMessage">
+ <part name="part1" type="xs:string"/>
+ </message>
+ <portType name="echoPortType">
+ <operation name="echo">
+ <input message="y:requestMessage"/>
+ <output message="y:responseMessage"/>
+ </operation>
+ </portType>
+ <binding name="echoBinding" type="y:echoPortType">
+ <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
+ <operation name="echo">
+ <soap:operation soapAction="echo"/>
+ <input>
+ <soap:body use="literal"/>
+ </input>
+ <output>
+ <soap:body use="literal"/>
+ </output>
+ </operation>
+ </binding>
+.....</pre>
+
+<p>The binding says its got to be rpc/lit and in this case the message parts
+need wrapping in the following order.</p>
+<ol>
+ <li>The first element needs to have the operation name as the local name
+ and the operation namespace (which 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>
+
+<p>For example the input wire message for the echo operation mentioned in the
+above WSDL fragment would look like this:</p>
+<pre> <op:<strong>echo</strong> xmlns:op="porttype namespace">
+ <<strong>part1</strong>>Hello World</part1>
+ <<strong>part2</strong>>123</part2>
+ </op:echo></pre>
+
+<p>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 quite
+possible to generate a schema, representing this structure and then treat the
+whole service as pure doc/lit service. In this case, following is the piece
+of schema generated to make this rpc to doc conversion. Note that in this
+case the wire message stays unchanged. It is only a different WSDL authoring
+style</p>
+<pre> <xs:element name="echo">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="part1" type="xs:string" />
+ <xs:element name="part2" type="xs:int" />
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element></pre>
+
+<p>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!</p>
+
+<h2>Step 2 - Unwrapping the Schema</h2>
+
+<p>If the schema needs to be unwrapped then that brings up a few issues
+mainly because the only thing that the emitters rely on when generating code
+is a mapping table!</p>
+<ol>
+ <li>When the schema is unwrapped where would that unwrapping information
+ stay?
+ <p>Good question - It needs to be a store that keeps the information
+ seperated. Hmm.. What can we use here ? Why of course, the Axis *
+ hierarchy! It has nicely separated information holders and a parameter
+ store that can hold a information bean.</p>
+ </li>
+ <li>How do we maintain uniqueness among message part names?
+ <p>Another Good question - part names are only unique across a message
+ and not globally. But 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</p>
+ </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. What it does is to walk 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>< element >
+ < complexType >
+ < sequence >
+ < element />
+ < /sequence >
+ < /complexType >
+ < /element >
+ </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><input>
+ <param name="param4" type="com.example.www.ServiceNameStub.Echo" shorttype="Echo" value="null" location="body" opname="echo">
+ <param name="param5" type="java.lang.String" shorttype="String" value="null" location="body" opname="echo" partname="Part1"
+ primitive="yes"/>
+ <param name="param6" type="int" shorttype="int" value="0" location="body" opname="echo" partname="Part2" primitive="yes"/>
+ </param>
+</input></pre>
+
+<p>The next part is upto the template to handle. 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 a sort of 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 />
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html (added)
+++ webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,735 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Architecture Guide</title>
+ <meta content="20050916;22455288">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1 align="center">Apache Axis2 Architecture Guide</h1>
+
+<p>This document will give an introduction to Axis2's modular architecture
+with explanations on every module.</p>
+
+<p><i>Send your feedback to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<h2>Contents</h2>
+<ul>
+ <li><a href="#bmBP">The Big Picture</a></li>
+ <li><p><a href="#requirements">Requirement of Axis2</a></p>
+ </li>
+ <li><a href="#thearchi">Axis2 Architecture</a>
+ <ul>
+ <li><p><a href="#bmcore">Core Modules</a></p>
+ </li>
+ <li><a href="#bmother">Other Modules</a></li>
+ <li><p><a href="#bmInfoMod">Information Model</a></p>
+ </li>
+ <li><a href="#bmXML">XML Processing Model</a></li>
+ <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
+ <ul>
+ <li><a href="#default">Axis2 Default Processing Model</a></li>
+ <li><p><a href="#incomingsoap">Processing an Incoming SOAP
+ Message</a></p>
+ </li>
+ <li><a></a><a href="#outgoing">Processing of the Outgoing
+ Message</a></li>
+ <li><p><a href="#extending">Extending SOAP Processing Model</a></p>
+ <ul>
+ <li><a href="#extendingwithhandlers">Extending the SOAP
+ Processing Model with Handlers</a></li>
+ <li><p><a href="#extendingwithmodules">Extending the SOAP
+ Processing Model with Modules</a></p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#bmDeployment">Deployment</a>
+ <ul>
+ <li><a href="#xmlfile">The <em>axis2.xml</em> file</a></li>
+ <li><p><a href="#servicearchive">Service Archive</a></p>
+ </li>
+ <li><a href="#modulearchive">Module Archive</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#bmClientAPI">Client API</a></p>
+ <ul>
+ <li><a href="#oneway">One Way Messaging Support</a></li>
+ <li><p><a href="#requestresponse">Request Response Messaging
+ Support</a></p>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#bmTransports">Transports</a></li>
+ <li><p><a href="#bmWSDL">Code generation</a></p>
+ </li>
+ <li><a href="#bmDB">Data Binding</a>
+ <ul>
+ <li><a href="#integration">Integration with Code Generation
+ Engine</a></li>
+ <li><p><a href="#serial">Serialization and De-Serialization</a></p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul>
+
+<h2><a name="bmBP">The Big Picture</a></h2>
+
+<p>A new architecture for Axis was introduced during the August 2004 Summit
+in Colombo, Sri Lanka. This new architecture Axis2 is based on 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.</p>
+
+<p>Any architecture is a result of what that architecture should yield. The
+success of an architecture should be evaluated based on the requirements
+expected to be met by that architecture. Let us start our journey into Axis2
+by looking at the requirements.</p>
+<a name="requirements"></a>
+
+<h2>Requirement of Axis2</h2>
+
+<p>In the SOAP terminology, a participant who is taking part in a Web service
+interaction is known as a SOAP Node. Delivery of a single SOAP Message is
+defined based on two participants, SOAP Sender and SOAP Receiver. Each SOAP
+Message is sent by SOAP Sender and received by SOAP Receiver. A single SOAP
+delivery is the most basic unit that builds the Web service interaction.</p>
+
+<p>Each SOAP Node may be written in specific programming language, may it be
+Java, C++, .NET or Perl, the Web services allow them to inter operate. This
+is possible because on the wire each Web service interaction is done via
+SOAP, which is common to every SOAP Node.</p>
+
+<p><img alt="" src="images/archi-guide/soap.gif" name="Graphic1"
+align="bottom" width="691" height="319" border="0"></p>
+
+<p>Web service middleware handles the complexity in SOAP messaging and lets
+the users work with the programming language they are accustomed to. Axis2
+allows java users to invoke Web services using java representations, and
+handles the SOAP messaging behind the curtain.</p>
+
+<p>Axis2 handles SOAP processing along with numerous other tasks. This makes
+the life of the Web service developer a whole lot easier. Following are the
+identified requirements:</p>
+<ol>
+ <li>Provide a framework to process the SOAP messages. The framework should
+ be extensible and the users should be able to extend the SOAP processing
+ per service or per operation basis. Furthermore it should be able to
+ model different Message Exchange Patterns (MEPs) using the processing
+ framework.</li>
+ <li>Ability to deploy a Web service (with or without WSDL)</li>
+ <li>Provide a Client API that can be used to invoke Web services. This API
+ should support both the Synchronous and Asynchronous programming
+ models.</li>
+ <li>Ability to configure Axis2 and it's components via deployment.</li>
+ <li>Ability to send and receive SOAP messages with different
+ transports.</li>
+</ol>
+
+<p>Apart from the above functionalities, performance in terms of memory and
+speed is a major consideration for Axis2. Axis2 Core Architecture is built on
+three specifications- WSDL, SOAP and WS-Addressing. Other specifications like
+JAX-RP, SAAJ & WS-Policy are layered on top of the Core Architecture.</p>
+
+<h2><a name="thearchi">Axis2 Architecture</a></h2>
+Axis2 architecture lays out some principals to preserve the uniformity. They
+are as follows:
+<ul>
+ <li><p>Axis2 architecture separates the logic and the states. Code that
+ does the processing is stateless inside Axis2. This allows code to be
+ executed freely by parallel threads.</p>
+ </li>
+ <li>All the information is kept in one information model allowing system to
+ be suspended and resumed.</li>
+</ul>
+
+<p>Axis2 architecture is modular. Therefore Axis2 Framework is built up of
+core modules which collectively make up the core architecture of Axis2, and
+non-core/other modules are layered on top of this core
+modules/architecture.</p>
+<a name="bmother"></a>
+
+<h3>Core Modules:</h3>
+<ul>
+ <li><a href="#bmInfoMod">Information Model</a>- Axis2 defines a model to
+ handle information and all states are kept in this model. The model has a
+ hierarchy for the information. The system manages the life cycle of the
+ objects in this hierarchy.</li>
+ <li><p><a href="#bmXML">XML processing Model</a>- Handling the SOAP Message
+ is the most important and most complex task. The efficiency of this is
+ the single most important factor that decides the performance. It makes
+ sense to delegate this task to a separate sub-project itself, under Web
+ service project, allowing that sub-project (AXIOM) to provide a simple
+ API for SOAP and XML info-set while hiding the complexities of the
+ efficient XML processing within the implementation.</p>
+ </li>
+ <li><a href="#bmSOAPPM">SOAP Processing Model</a>- This controls the
+ execution of the processing. The model defines different phases the
+ execution would walk through, and the user can extend the Processing
+ Model at some specific places.</li>
+ <li><p><a href="#bmDeployment">Deployment Model</a>- Axis2 deployment model
+ allows the user to deploy services, configure the transports, extend the
+ SOAP Processing model per system, service or operation basis.</p>
+ </li>
+ <li><a href="#bmClientAPI">Client API</a>- This provides a convenient API
+ for users to communicate with Web services using Axis2. There are set of
+ classes to interact with IN-OUT and IN-Only style Message Exchange
+ Patterns (MEPs) where those can be used to construct any other MEP.</li>
+ <li><p><a href="#bmTransports">Transports</a>- Axis2 define a transport
+ framework that enables the user to use different transports. The
+ transports fit into specific places in the SOAP processing model. The
+ implementation provides a few common transports and the user may write
+ new ones if and when it is needed.</p>
+ </li>
+</ul>
+<a name="bmcore"></a>
+
+<h3>Other Modules:</h3>
+<ul>
+ <li><a href="#bmWSDL">Code Generation</a>- Axis2 provides a code generation
+ tool that will generate server side and client side code along with a
+ test case. The generated code would simplify the service deployment and
+ the service invocation. This would increase usability of Axis2.</li>
+ <li><p><a href="#bmDB">Data Binding</a>- The basic client API of Axis2 lets
+ the users process SOAP at the infoset level where as data binding extends
+ it to make it more convenient to the users by encapsulating the infoset
+ layer and providing a programming language specific interface.</p>
+ </li>
+</ul>
+<map name="Graphic2Map" id="g2m">
+ <area shape="rect" coords="123,31,222,97" href="#bmInfoMod" alt="">
+ <area shape="rect" coords="239,62,319,134" href="#bmXML" alt="">
+ <area shape="rect" coords="127,112,218,177" href="#bmSOAPPM" alt="">
+ <area shape="rect" coords="12,39,89,95" href="#bmDeployment" alt="">
+ <area shape="rect" coords="0,108,94,156" href="#bmWSDL" alt="">
+ <area shape="rect" coords="350,31,426,86" href="#bmClientAPI" alt="">
+ <area shape="rect" coords="350,114,421,164" href="#bmTransports" alt="">
+</map>
+
+<p><img src="images/archi-guide/all.png" name="Graphic2" width="426" alt=""
+height="189" border="0" align="bottom" usemap="#Graphic2Map"></p>
+
+<h2><a name="bmInfoMod">Information Model</a></h2>
+
+<p>Information Model has two main hierarchies-Contexts and Descriptions. This
+model is described in UML notations below.</p>
+
+<p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom"
+alt="" width="400" height="443" border="0"></p>
+
+<p>( A ----<> B says, B has 1 or more objects of A. A------>B says,
+the given relationship holds between A and B.)</p>
+
+<p>The two hierarchies are connected as shown in the above figure. The
+Description hierarchy represents the static data. This data may be loaded
+from a configuration file that exists throughout the lifetime of Axis2. For
+example, deployed Web services, operations, etc. On the other hand, the
+context hierarchy holds more dynamic information about the things that have
+more than one instances (e.g.Message Context).</p>
+
+<p>These two hierarchies creates a model that provides the ability to search
+for key value pairs. When the values are searched at a given level, they are
+searched while moving up the hierarchy until a match is found. In the
+resulting model the lower levels override the values in the upper levels. For
+example, when a value is looked up in the Message Context and is not found,
+it would be looked up in the Operation Context etc, up the hierarchy. The
+Search is first done up the hierarchy, and if starting point is a Context
+then it is search in the Description hierarchy as well.</p>
+
+<p>This allows the user to declare and override values. Result being a very
+flexible configuration model. The flexibility could be the <em>Achilles</em>
+heel for the system as the search is expensive, specially for something that
+does not exist. Yet in the final analysis developers believe that the
+flexibility would serve better in this instant.</p>
+
+<table width="955" border="1" cellpadding="2" cellspacing="3">
+ <col width="112"><col width="371"><col width="103"><col width="336"><tbody>
+ <tr>
+ <td><strong>Context</strong></td>
+ <td><strong>Description</strong></td>
+ <td><strong>Configuration</strong></td>
+ <td><strong>Description</strong></td>
+ </tr>
+ <tr>
+ <td width="112"><p>Configuration Context</p>
+ </td>
+ <td width="371"><p>Holds the run time status. A deep copy of this would
+ essentially make a copy of Axis2.</p>
+ </td>
+ <td width="103"><p>Axis Configuration</p>
+ </td>
+ <td width="336"><p>Holds all global configurations. Transports, global
+ modules, parameters and services etc.</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Service Group Context</p>
+ </td>
+ <td width="371"><p>Holds information about a particular usage of the
+ respective service group. The life of a Service Group Context starts
+ when a user starts interacting with a service that belong to this
+ service group. This can be used to share information between services
+ (within the same service group) in a single interaction.</p>
+ </td>
+ <td width="103"><p>AxisServiceGroup</p>
+ </td>
+ <td width="336"><p>Holds deployment time information about a particular
+ service group.</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Service Context</p>
+ </td>
+ <td width="371"><p>This context is available throughout the usage of
+ the respective service. This can be used to share information between
+ several MEPs of the same service, within a single interaction.</p>
+ </td>
+ <td width="103"><p>AxisService</p>
+ </td>
+ <td width="336"><p>Hold the Operations and the service level
+ configurations</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Operation Context</p>
+ </td>
+ <td width="371"><p>Holds the information about the current MEP
+ instance, maintain the Messages in the current MEP etc.</p>
+ </td>
+ <td width="103"><p>AxisOperation</p>
+ </td>
+ <td width="336"><p>Holds the operation level configurations</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><a name="messageContext"></a>
+
+ <p>Message Context</p>
+ </td>
+ <td width="371"><p>Holds all the information about the Message
+ currently being executed.</p>
+ </td>
+ <td width="103"><p>AxisMessage</p>
+ </td>
+ <td width="336"><p>Do not hold any information as yet, but can be used
+ as a future extension point.</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<a name="bmXML"></a>
+
+<h2>XML Processing Model</h2>
+
+<p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p>
+
+<h2><a name="bmSOAPPM">SOAP Processing Model</a></h2>
+
+<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" alt=""
+align="bottom" width="755" height="348" border="0"></p>
+
+<p>The architecture identified two basic actions a SOAP processor should
+perform, sending and receiving SOAP messages. The architecture provides two
+Pipes ('Flows'), to perform these two basic actions. Axis Engine or the
+driver of Axis2 defines two methods send() and receive() to implement these
+two Pipes. The two pipes are named <i><b>In</b> Pipe</i> and <i><b>Out</b>
+Pipe</i>, and the complex Message Exchange Patterns (MEPs) are constructed by
+combining these two pipes.</p>
+
+<p>Extensibility of the SOAP processing model is provided through handlers.
+When a SOAP message is being processed the handlers that are registered would
+be executed. The handlers can be registered in global, service, or operation
+scopes and the final handler chain is calculated combining the handlers from
+all the scopes.</p>
+
+<p>The handlers act as interceptors and they process parts of the SOAP
+message and provide add-on services. Usually handlers work on the SOAP
+headers, yet they may access or change the SOAP Body as well.</p>
+
+<p>When a SOAP message is being sent through the Client API, an <i>Out
+Pipe</i> would begin, the <i>Out Pipe</i> invokes the handlers and end with a
+Transport Sender that sends the SOAP message to the target endpoint. The SOAP
+message is received by a Transport Receiver at the target endpoint, which
+reads the SOAP message and starts the <i>In Pipe</i>. The <em>In Pipe</em>
+consists of handlers and ends with the <a href="#mr">Message Receiver</a>,
+which consumes the SOAP message.</p>
+
+<p>Above explained processing happens for each and every SOAP message
+exchanged. After processing one message Axis2 may decide to create other SOAP
+messages, in which case more complex message patterns emerge. However Axis2
+always view the SOAP message in terms of processing a single message. The
+combination of the messages are layered on top of that basic framework.</p>
+
+<p>The two pipes does not differentiate between the Server and the Client.
+The SOAP Processing Model handles the complexity and provides two abstract
+pipes to the user. The different areas or the stages of the pipes are given
+names, and according to the Axis2 slang those are named 'phases'. A Handler
+always runs inside a phase, and the phase provides a mechanism to specify the
+ordering of handlers. Both Pipes have built in phases, and both define the
+areas for 'User Phases' which can be defined by the user.</p>
+
+<h3><a name="default">Axis2 Default Processing Model</a></h3>
+
+<p>Axis2 has some inbuilt handlers that run in inbuilt phases and they create
+the default configuration for the Axis2. We will be looking more in to how to
+extend the default processing Model in the next section.</p>
+There are four special handlers defined in Axis2.
+<ol>
+ <li>Dispatchers - Finds the service and the operation the SOAP message is
+ directed to. Dispatchers always run on the <em>In-Pipe</em> and inside
+ the Dispatch phase. The in-built dispatchers dispatch to a particular
+ operation depending on various conditions like WS-Addressing information,
+ URI information, SOAP action information, etc.,</li>
+</ol>
+<ul>
+ <li><a name="mr">Message Receiver - Consume the SOAP Message and hands that
+ over to application , Message receiver is the last handler of the
+ in-pipe</a></li>
+ <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
+ message is destined to. Always runs as last handler in the out-pipe</p>
+ </li>
+</ul>
+
+<h3><a name="incomingsoap">Processing an Incoming SOAP Message</a></h3>
+
+<p>Incoming SOAP Message is always received by a Transport Receiver waiting
+for the SOAP Messages. Once the SOAP Message arrives the transport Headers
+are parsed and a</p>
+<a href="#messageContext">Message Context</a> is created from the incoming
+SOAP Message. Then the <i>In Pipe</i> is executed with the Message Context.
+
+<p>Let us see what happens at each phase of the execution. This process may
+happen either in the server or in the Client.</p>
+<ol>
+ <li><strong>Transport Phase</strong> - The handlers are in the phase meant
+ to process transport specific information such as validating incoming
+ message by looking at various transport headers, add data into message
+ context etc.</li>
+ <li><strong>Pre-Dispatch Phase</strong>- The main functionality of the
+ handlers in this phase is to populate message context in order to do the
+ dispatching. As an example, processing of addressing headers of the SOAP
+ message happen in this phase.Addressing handlers extract information and
+ put them in to the message context.</li>
+ <li><strong>Dispatch Phase</strong> - The Dispatchers run in this phase and
+ tries to find the correct service and operation this particular message
+ is destined to.<br>
+ The post condition of the dispatch phase (any phase can contain a post
+ condition) checks whether a service and an operation was found by the
+ dispatchers. If not the execution will halt and throws out a "service not
+ found error".</li>
+ <li><strong>User Defined Phases</strong> - Users are allowed to engage
+ their custom handlers here.</li>
+ <li>Message Validation Phase - Once the user level execution has taken
+ place this phase validates whether SOAP Message Processing has taken
+ place correctly.</li>
+ <li><strong>Message Processing Phase</strong> - The Business logic of the
+ SOAP message is executed here. A <a href="#mr">Message Receiver</a> is
+ registered with each Operation. This Message receiver (associated to the
+ particular operation) will executed as the last Handler of this
+ phase.</li>
+</ol>
+
+<p>There may be other handlers in any of these phases. Users may use custom
+handlers to override the mechanics in each of these phases.</p>
+
+<h3><a name="outgoing">Processing of the Outgoing Message</a></h3>
+
+<p><em>Out Pipe</em> is simpler because the service and operation to dispatch
+is known by the time the pipe is executed. The <em>Out Pipe</em> may be
+initiated by the</p>
+<a href="#mr">Message Receiver</a> or the Client API implementation.Phases of
+the <em>Out Pipe</em> are described below:
+<ol>
+ <li>Message Initialize Phase - First phase of the <em>Out Pipe</em>. Serves
+ as the placeholder for the custom handlers</li>
+ <li>User Phases - This executes handlers in user defined phases</li>
+ <li>Transports Phase - Execute any transport handlers taken from the
+ associated transport configuration. The last handler would be a transport
+ sender which would send the SOAP message to the target endpoint.</li>
+</ol>
+
+<h3><a name="extending">Extending SOAP Processing Model</a></h3>
+
+<p>Above we discussed the default processing model of Axis2. Now let us
+discuss the extension mechanism for the SOAP processing model. After all, the
+whole effort of making this SOAP engine/processing model was focused much on
+making it extendable.</p>
+
+<p>Idea behind introducing step wise processing of the SOAP message in terms
+of handlers & phases is to allow easier modification of the processing
+order. The notion of phases makes it easier to place handlers in between
+other handlers. This enables modification on the default processing behavior.
+SOAP Processing Model can be extended with <a
+href="#extendingwithhandlers">handler</a> or <a
+href="#extendingwithmodules">modules</a>.</p>
+<a name="extendingwithhandlers"></a>
+
+<h4>Extending the SOAP Processing Model with Handlers</h4>
+The handlers in a module can specify the phase they need to be placed in.
+Furthermore they can specify their location inside a phase by providing phase
+rules. Phase rules will place a handler
+<ol>
+ <li>as the first handler in a phase.</li>
+ <li>or as the last handler in a phase.</li>
+ <li>or before a given handler</li>
+ <li>or after a given handler</li>
+</ol>
+
+<h4><a name="extendingwithmodules">Extending the SOAP Processing Model with
+Modules</a></h4>
+
+<p>Axis2 defines an entity called a 'module' that can introduce handlers and
+Web service operations. A Module in terms of Axis2 usually acts as a
+convenient packaging that includes</p>
+<ul>
+ <li>a set of handlers and</li>
+ <li>an associated descriptor which includes the phase rules</li>
+</ul>
+. Modules have the concept of being 'available' and 'engaged'. 'Availability'
+means the module is present in the system, but has not been activated, i.e.,
+the handlers included inside the module have not been used in the processing
+mechanism. When a module is 'engaged' it becomes active and the handlers get
+placed in the proper phases. The handlers will act in the same way as
+explained in the previous section. Usually a module will be used to implement
+a WS-* functionality such as WS-Addressing.
+
+<p>Apart from the extension mechanism based on the handlers, the WS-*
+specifications may suggest a requirement for adding new operations. For
+example, once a user add a Reliable Messaging capability to a service, the
+"Create Sequence" operation needs to be available to the service end point.
+This can be implemented by letting the modules define the operations. Once
+the module is engaged to a service, the necessary operations will be added to
+that service.</p>
+
+<p>A service, operations or the system may engage a module. Once the module
+is engaged the handlers and the operations defined in the module are added to
+the entity that engaged them.</p>
+
+<p>Modules can not be added (no hot deployment) while the Axis2 engine is
+running, but they will be available once the system is restarted.</p>
+<a name="bmDeployment"></a>
+
+<h2>Deployment</h2>
+
+<p>The Deployment Model provides a concrete mechanism to configure Axis2.
+This model has three entities that provide the configuration.</p>
+<a name="xmlfile"></a>
+
+<h3>The axis2.xml file</h3>
+
+<p>This file holds the global configuration for the client and server, and
+provide following information:</p>
+<ol>
+ <li>The global parameters</li>
+ <li>Registered transports in and transport outs</li>
+ <li>User defined phase names</li>
+ <li>Modules that are engaged globally (to all services)</li>
+ <li>Globally defined <a href="#mr">Message Receivers</a></li>
+</ol>
+<a name="servicearchive"></a>
+
+<h3>Service Archive</h3>
+
+<p>Service archive must have a <em>META-INF/<a
+href="resources/schemas/services.xsd">services.xml</a></em> file and may
+contain the dependent classes. The <em>services.xml</em> file has following
+information.</p>
+<ol>
+ <li>Service level parameters</li>
+ <li>Modules that are engaged service level</li>
+ <li>Service Specific <a href="#mr">Message Receivers</a></li>
+ <li>Operations inside the service</li>
+</ol>
+
+<h3><a name="modulearchive">Module Archive</a></h3>
+
+<p>Module archive must have a META-INF/<a
+href="resources/schemas/module.xsd">module.xml</a> file and dependent
+classes. The <em>module.xml</em> file has Module parameters and the
+Operations defined in the module.</p>
+
+<p>When the system is starting up Axis2 ask the deployment model to create a
+Axis Configuration. Deployment Model first finds the axis2.xml file and build
+the global configuration. Then it checks for the module archives and then for
+the service archives. After that the corresponding services and modules are
+added to the Axis Configuration. System will build contexts on top of the
+Axis Configurations. After this Axis2 is ready to send or receive the SOAP
+messages. Hot deployment is only allowed for services.</p>
+<a name="bmClientAPI"></a>
+
+<h2>Client API</h2>
+
+<p>There are three parameters that decide the nature of the Web service
+interaction.</p>
+<ol>
+ <li>Message Exchange Pattern (MEP)</li>
+ <li>The Behavior of the transport, whether it's One-Way or Two-Way</li>
+ <li>Synchronous/ Asynchronous behavior of the Client API</li>
+</ol>
+
+<p>Variations of the three parameters can result in indefinite number of
+scenarios, even though Axis2 is built on a core that support any messaging
+interaction, the developers were compelled to support only two most widely
+used Message Exchange Patterns (MEPs).</p>
+
+<p>Two supported MEPs are One-Way and the In-Out (Request-Response) scenarios
+in the Client API. The implementation is based on a class called
+<code>ServiceClient</code> and there are extensions for each MEP that Axis2
+Client API supports.</p>
+
+<h3><a name="oneway">One Way Messaging Support</a></h3>
+
+<p>The One-Way support is provided by the <code>fireAndForget</code> method
+of <code>ServiceClient</code>. For one way invocations one can use HTTP ,
+SMTP and TCP transports. In the case of the HTTP transport the return channel
+is not used and the HTTP 202 OK is returned in the return Channel.</p>
+<a name="requestresponse"></a>
+
+<h3>In-Out (Request Response) Messaging Support</h3>
+
+<p>The In-Out support is provided by the <code>sendReceive()</code> method in
+ServiceClient. This provides a much simpler interface for the user. The
+Client API has four ways to configure a given Message Exchange</p>
+<ol>
+ <li>Blocking or Non-Blocking nature - this can be decided by using
+ <code>sendReceive()</code> or <code>sendReceiveNonBlocking()</code>
+ methods</li>
+ <li>Sender transport - transport used to send the SOAP Message</li>
+ <li>Listener transport - transport the Response is received</li>
+ <li>Use Separate Channel - determines whether the response is send over a
+ separate transport connection or not. This can be false only when sender
+ and listener transport is same and is a Two-Way transport.</li>
+</ol>
+
+<p>Depending on the values of the above four parameter, Axis2 behave
+differently.</p>
+<a name="bmTransports"></a>
+
+<h2>Transports</h2>
+
+<p>Axis2 has two basic constructs for transports, namely; Transport Senders
+and Transport Receivers . These are accessed via the AxisConfiguration.</p>
+
+<p>The incoming transport is the transport via which the AxisEngine receives
+the message. The outgoing transport is decided based on the addressing
+information (wsa:ReplyTo and wsa:FaultTo). If addressing information is not
+available and if server is trying to respond, then the out going transport
+will be the outputstream of the incoming transport (if it is two-way
+transport).</p>
+
+<p>At the client side the user is free to specify the transport to be
+used.</p>
+
+<p>Transport Senders and Transport Receivers contains following
+information.</p>
+<ol>
+ <li>Transport Sender for Out Configuration</li>
+ <li>Transport Listener for In Configuration</li>
+ <li>Parameters of the transport</li>
+</ol>
+
+<p>Each and every transport out configuration defines a transport sender.
+Transport sender sends the SOAP message, depending on its configuration.</p>
+
+<p>Transport receiver waits for the SOAP Messages and for each SOAP Message
+that arrives, it uses the <i>In Pipe</i> to process the SOAP Message.</p>
+
+<p>Axis2 Presently support the following transports:</p>
+<ol>
+ <li>HTTP - In HTTP transport the transport listener is a servlet or
+ org.apache.axis2.transport.http.SimpleHTTPServer provided by Axis2. The
+ transport sender uses commons-httpclient to connect and send the SOAP
+ Message.</li>
+ <li>TCP - This is the most simplest transport, but needs the WS -
+ Addressing support to be functional.</li>
+ <li>SMTP - This works off a single email account. Transport receiver is a
+ thread that checks for emails in fixed time intervals.</li>
+ <li>JMS</li>
+</ol>
+<a name="bmWSDL" id="bmWSDL"></a>
+
+<h2>Code Generation</h2>
+
+<p>Although the basic objective of the code generation tools has not changed,
+the code generation module of Axis2 has taken a different approach to
+generate code. Primarily the change is in the use of templates, namely XSL
+templates which gives the code generator the flexibility to generate code in
+multiple languages.</p>
+
+<p>The basic approach is to set the code generator to generate an XML and
+parse it with a template to generate the code file. The following figure
+describes how this shows up in the architecture of the tool.</p>
+
+<p><img src="images/archi-guide/CodegenArchitecture-new.gif" name="Graphic6"
+alt="" align="bottom" border="0"></p>
+
+<p>The fact here is that it is the same information that is extracted from
+the WSDL no matter what code is generated. First, an AxisService is populated
+from a WSDL. Then the code generator extracts information from the
+AxisService and creates an XML which is language independent. This emitted
+XML is then parsed with the relevant XSL to generate code for the relevant
+language. No matter what the output language, the process is the same except
+for the template that is being used.</p>
+
+<h2><a name="bmDB" id="bmDB">Data Binding</a></h2>
+
+<h3>Integration with Code Generation Engine</h3>
+
+<p>Databinding for Axis2 is implemented in an interesting manner. Databinding
+has not been included in the core deliberately and hence the code geneation
+allows different data binding frameworks to be plugged in. This is done
+through an extension mechanism where the codegen engine calls extensions
+first and then executes the core emitter. The extensions populate a map of
+QNames vs. class names that is passed to the code generator on which the
+emitter operates on.</p>
+
+<p><strong>The following diagram shows the structure:</strong></p>
+
+<p><img src="images/codegen.gif" name="Graphic7" align="bottom"
+border="0"></p>
+
+<p><strong>The following databinding extensions are available:</strong></p>
+<ol>
+ <li><strong>ADB</strong> - ADB (Axis Data Binding ) is a simple framework
+ that allows simple schemas to be compiled. It is lightweight and simple,
+ works off StAX and fairly performant. However, it does not support the
+ complete set of schema constructs and is likely to complain for certain
+ schemas!</li>
+ <li><strong>XMLBeans</strong> - XMLbeans claims that it supports the
+ complete schema specification and it is the choice, if full schema
+ support is needed!</li>
+ <li><strong>JAX-Me</strong> - JaxMe support has been added in a similar
+ manner to XMLbeans and serves as another option for the user</li>
+ <li><strong>JibX</strong> - This is the most recent addition to the family
+ of databinding extensions and it is also another option the users have
+ for data binding.</li>
+</ol>
+
+<h3><a name="serial" id="serial">Serialization and De-Serialization of Data
+bound classes</a></h3>
+
+<p>AXIOM is based on a StAX API (Streaming API for XML). Xml-beans supports
+StAX API. Data binding in Axis2 is achieved through interfacing the AXIOM
+with the Xml-beans using the StAX API which is supported by both parties. At
+the time of the code generation there will be utility methods generated
+inside the stub (or the message receiver) that can de-serialize from AXIOM to
+data bound object and serialize from data bound object to AXIOM. For example,
+if the WSDL has an operation called "echoString", once the code is generated
+the following methods will be generated inside the relevant classes.</p>
+<pre>public static
+org.apache.axiom.om.OMElementtoOM(org.soapinterop.xsd.EchoStringParamDocument
+param)// This method will handle the serialization.
+
+public static org.apache.xmlbeans.XmlObject
+fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This
+method will handle the de-serialization.</pre>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/WS_policy.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/WS_policy.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/WS_policy.html (added)
+++ webservices/axis2/trunk/java/xdocs/WS_policy.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,174 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+ <title>WS Policy Support in Axis2</title>
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en">
+<h1 align="center">Web Services Policy Support In Axis2</h1>
+
+<p>This document will give you an introduction to the role of Web services
+policy in Axis2.</p>
+
+<p><i>E-mail comments/ suggestions to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#what">What is Web Services (WS) Policy?</a></li>
+ <li><a href="#client">Client Side WS-Policy Support</a></li>
+ <li><a href="#server">Server Side WS-Policy Support</a></li>
+ <li><a href="#resources">Resources</a></li>
+</ul>
+<a name="what"></a>
+
+<h2>What is Web Services (WS) Policy?</h2>
+
+<p>To consume non trivial web services one must fully understand its xml
+contract (WSDL) along with any other additional requirements, capabilities or
+preferences which translates to the configuration of the service, and
+essentially becomes the policies of the service.</p>
+
+<p>WS Policy framework provides a way to express the policies of a service in
+a machine-readable way. Web services infrastructure can be enhanced to
+understand and enforce policies at runtime. For instance, a service author
+might write a policy requiring digital signature and encryption, while
+service consumers could use the policy information to reason out whether they
+can adhere to this policy information to use the service or not.</p>
+
+<p>Further more, web service infrastructure could be enhanced to enforce
+those requirements without requiring the service author to write even single
+line of code.</p>
+<a name="client"></a>
+
+<h2>Client Side WS-Policy Support</h2>
+
+<p>This release <strong>fully supports WS Policy at client-side</strong>. It
+means that when you codegen a stub against a WSLD which contains policies,
+the stub will contain the capability to engage the required modules with the
+appropriate configurations. For instance, if there is a security policy
+attached to an operation in the WSDL, the generated stub will engage the
+security module for that operation with the appropriate security
+configurations.</p>
+
+<h3>How it works:</h3>
+
+<h4>Phase 1: At PolicyEvaluator</h4>
+
+<p>Codegen engine runs few of its registered extensions before it generates
+the stub. When PolicyEvalutor (which is a registered Codegen extension) is
+initialized, it populates a registry of namespaces of supported policies to
+PolicyExtensions.</p>
+
+<p>For instance, module foo might have a mapping of namespace
+http://test.com/foo which means any primitive assertion which has this
+namespace will be processed by this module. Foo module might implement the
+ModulePolicyExtension interface through which PolicyExtension object can be
+obtained.</p>
+
+<p>A <strong>PolicyExtension</strong> is the access point for a module to add
+any other methods to the stub. For instance Reliable Messaging module can add
+createSequence() and endSequence() methods to the stub, that the user must
+call to start and end an RM sequence.</p>
+
+<p>Then at the engagement of PolicyEvaluator, effective policy of each
+operation is calculated based on policy information declared in the WSDL
+document. Here we assume that effective policy of an operation contains a
+single alternative (<strong>Multiple policy alternatives are not
+supported</strong>). Then we split that policy as follows into few other
+policies such that, each policy will contain primitive assertions belonging
+to only one namespace.</p>
+<pre> <wsp:Policy> <wsp:Policy> <wsp:Policy> <wsp:Policy>
+ <a:Foo/> <a:Foo/> <b:Foo/> <c:Bar/>
+ <a:Bar/> => <a:Bar/> </wsp:Policy> </wsp:Policy>
+ <b:Foo/> </wsp:Policy>
+ <c:Bar/>
+ </wsp:Policy></pre>
+
+<p>Then each policy is given to the appropriate PolicyExtension with an
+org.w3c.Element type object to which the module can append any other
+elements/attributes it wishes. Those attributes/elements should resolve to
+meaningful stub functions via PolicyExtensionTemplate.xsl at latter point of
+time.</p>
+
+<p>For instance depending on the policy, Security module can append
+<username>, <passwd> elements to the given element as children,
+which are later resolved into setUsername(..), setPasswd(..), functions of
+the stub. This way a module can include additional methods to the stub which
+can be used to get specific parameters to the module. These methods store any
+user input in the ServiceClient properties
+(ServiceClient.getOptions().putProperty(...)) which can later be accessed by
+the module.</p>
+
+<h4>Phase 2: At MultiLanguageClientEmitter</h4>
+
+<p>Further, effective policies (based on the WSDL) at appropriate levels
+(service level, operation level) are stored as policy strings in the stub.
+Few more generic methods are also added to the stub which are used to
+evaluate/process policies at runtime.</p>
+
+<h4>Phase 3: Runtime</h4>
+
+<p>When a new stub object is created, the policy strings in the stub are
+converted into policy objects and merged together to get the effective
+policies of each operation. These effective policies are stored in
+appropriate AxisOperation objects which a module can access at later point of
+time.</p>
+
+<p>Then based on its policy each AxisOperation is engaged to a set of
+modules.</p>
+
+<p>When the stub method is invoked, those modules which are engaged to that
+AxisOperation, access the effective policy for that operation via
+AxisOperation object. It can get other information needed from the
+MessageContext which get stored by stub methods which the module has added to
+the stub earlier. The modules are required to loads their configurations
+according to the effective policy which is set in AxisOperation and
+properties they get via MessageContext.</p>
+<a name="server"></a>
+
+<h2>Server Side WS-Policy Support</h2>
+
+<p>In this current release Axis2 framework uses WS-Commons/Neethi framework
+to manipulate policy documents. All its description builders store any policy
+information included in description documents (services.xml, axis2.xml, ..
+etc) in the appropriate description classes. This information is available at
+both deployment and run time via these description classes.</p>
+
+<p>When generating WSDL dynamically for each service, policy information in
+the description classes is included. For instance, if you declare a policy in
+axis2.xml then that policy is reflected in service elements of WSDL of every
+service. If a policy is declared in a services.xml, it is shown in the
+service element of WSDL for that particular service.</p>
+
+<p>Next step is to use that information to engage and configure required
+modules and allow the module to make use of this policy information.</p>
+
+<p>It is evident that a great deal of work is required to make axis2 a fully
+fledged ws-policy supported web service infrastructure. But it is encouraging
+to note that we've taken the first steps towards this goal. We appreciate any
+suggestions, patches etc you send us in this regard. Keep on
+contributing...!</p>
+<a name="resources"></a>
+
+<h2>Resources</h2>
+<ul>
+ <li>Apache Neethi (WS Policy Implementation) official site- <a
+ href="http://ws.apache.org/commons/neethi/index.html"
+ target="_blank">Home Page</a></li>
+ <li>Sanka Samaranayake, March 2006. <a
+ href="http://www.wso2.net/2006/01/web_services_policy_why_what_how"
+ target="_blank">Web services Policy - Why, What & How</a></li>
+ <li><a
+ href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/"
+ target="_blank">WS-commons/policy SVN</a></li>
+ <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf"
+ target="_blank">Web Services Policy Framework (WS-Policy)</a></li>
+</ul>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html (added)
+++ webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,112 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+ <title>Advanced Axis2 Databinding Framework Features</title>
+</head>
+
+<body lang="en">
+<h1>Advanced Axis2 Databinding Framework Features</h1>
+
+<p>The aim of this section is provide an insight into the newly added
+advanced features of ADB.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#typeSupport">xsi:type Support</a></li>
+ <li><a href="#helper">Helpergen Mode</a></li>
+ <li><a href="#more">More Stuff on ADB?</a></li>
+</ul>
+
+<h2><a name="typeSupport">xsi:type Support</a></h2>
+
+<p>This is implemented by adding a extension maping class. The code that
+calls the extension mapper is generated inside the deserialization method of
+the beans and gets active when the xsi:type attribute is present. The
+following code fragment shows how the generated type mapper looks like</p>
+<pre> public static java.lang.Object getTypeObject(
+java.lang.String namespaceURI, java.lang.String typeName,
+javax.xml.stream.XMLStreamReader reader) throws java.lang.Exception {
+if ("http://new.webservice.namespace/types".equals(namespaceURI) && "derivedType2".equals(typeName)) {
+ return namespace.webservice._new.types.DerivedType2Helper.parse(reader);
+}
+
+......
+
+ return namespace.webservice._new.types.BaseTypeHelper.parse(reader);
+} else if ("http://new.webservice.namespace/types".equals(namespaceURI) && "derivedType1".equals(typeName)) {
+ return namespace.webservice._new.types.DerivedType1Helper.parse(reader);
+}
+
+throw new java.lang.RuntimeException("Unsupported type " +
+ namespaceURI + " " + typeName);
+
+}</pre>
+
+<p>Inside every deserialize method, the extension mapper gets called when a
+xsi:type attribute is encountered <strong>and</strong> that type is not the
+type that is being parsed</p>
+
+<p>The following code fragment shows how the ADB deserialize method calls the
+mapper class</p>
+<pre>if (reader.getAttributeValue(
+ "http://www.w3.org/2001/XMLSchema-instance", "type") != null) {
+ java.lang.String fullTypeName = reader.getAttributeValue("http://www.w3.org/2001/XMLSchema-instance",
+ "type");
+ if (fullTypeName != null) {
+ java.lang.String nsPrefix = fullTypeName.substring(0,fullTypeName.indexOf(":"));
+ nsPrefix = (nsPrefix == null) ? "" : nsPrefix;
+ java.lang.String type = fullTypeName.substring(fullTypeName.indexOf(":") + 1);
+ if (!"derivedType2".equals(type)) {
+ //find namespace for the prefix
+ java.lang.String nsUri = reader.getNamespaceContext().getNamespaceURI(nsPrefix);
+ <strong>return (DerivedType2) namespace.webservice._new.types.ExtensionMapper.getTypeObject(nsUri,
+ type, reader);</strong>
+ }
+ }
+}</pre>
+
+<p>This should make the xsi:type based deserialization possible and should
+result in proper xsi:type based serializations at runtime</p>
+
+<p>This is automatically done but the package name for the mapper class can
+be controlled by using the <strong>mp</strong> flag (with a preceding -E)</p>
+<pre> WSDL2Code -uri .... -Emp org.example.web.map</pre>
+
+<p>When the mapping package is not specified it is derived from the
+targetnamespace of the first schema that is encountered</p>
+
+<h2><a name="helper">Helper mode</a></h2>
+
+<p>Helper mode is a fairly new feature. In the helper mode, the beans are
+plain Java beans and all the deserialization/serialization code is moved to a
+helper class. For example the simple schema mentioned in the ADB-howto
+document will yield four classes for the two that has been previously seen</p>
+<ol>
+ <li>MyElement.java</li>
+ <li>MyElementHelper.java</li>
+ <li>SOAPStruct.java</li>
+ <li>SOAPStructHelper.java</li>
+</ol>
+
+<p>The helpers basically contain all the code that went into the ADBBeans.
+Hence the beans in the helper mode are pretty much readable than the rest.
+Also note that the helper mode is available only if you are in the unpacked
+mode. The code generator by default does not expand the classes</p>
+
+<p>Helper mode can be switched on by the <strong>h</strong> flag (Passed with
+a -E infront to indicate that it is an extra switch undertood by ADB). Also
+the <strong>-u</strong> flag should be present to indicate the unpacking</p>
+<pre> WSDL2Code -uri .... -u -Eh</pre>
+
+<h2><a name="more">More Stuff on ADB?</a></h2>
+<ul>
+ <li><a href="adb-tweaking.html">Tweaking the ADB Code Generator</a>-
+ explains available mechanisms to extend ADB and possibly adopt it to
+ compile schemas to support other languages.</li>
+ <li><a href="adb-codegen-integration.html">ADB and Axis2 Integration</a> -
+ explains how the ADB schema compiler was attached to the Axis2
+ framework</li>
+</ul>
+<hr>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html (added)
+++ webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html Thu Oct 5 02:56:34 2006
@@ -0,0 +1,93 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>ADB Integration With Axis2</title>
+</head>
+<body>
+<h1>ADB Integration With Axis2</h1>
+<p>This document will assist you to write an extension using the
+integrator in order to integrate ADB with Axis2.</p>
+<h2>Content</h2>
+<ul>
+<li><a href="#intro">Introduction</a></li>
+<li><a href="#select_modes">Selection of Generation Modes for
+ADB</a></li>
+<li><a href="#remember">Things to Remember</a></li>
+</ul>
+<h2><a name="intro" id="intro">Introduction</a></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>
+<a name="select_modes" id="select_modes"></a>
+<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 <a href=
+"adb-howto.html" target="_blank">ADB-How to document</a> for the
+different generation modes and their descriptions.</p>
+<table border="1">
+<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>
+<tr>
+<td>-u (unwrap classes)</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 in the command line (prefixed with
+-E)</p>
+<table border="1">
+<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>Note that these parameters have no relevant long names and MUST
+be prefixed with a -E to be processed by the code generator. For
+example</p>
+<pre>
+WSDL2Java .... -Er true
+</pre>
+<a name="remember" id="remember"></a>
+<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
+). In the most recent release, the default has been set as ADB and
+hence if the -d option is missing then the databinding framework
+will be ADB.</li>
+</ol>
+<hr />
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org
Re: svn commit: r453167 [1/6] - in /webservices/axis2/trunk/java/xdocs: ./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ resources/ resources/schemas/
Posted by Thilina Gunarathne <cs...@gmail.com>.
Please use svn move... Deleting and adding kills the history..
~Thilina
On 10/5/06, chatra@apache.org <ch...@apache.org> wrote:
> Author: chatra
> Date: Thu Oct 5 02:56:34 2006
> New Revision: 453167
>
> URL: http://svn.apache.org/viewvc?view=rev&rev=453167
> Log:
> moving all files in 1_1 dir one level up in to the xdocs root
>
> Added:
> webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html
> webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
> webservices/axis2/trunk/java/xdocs/WS_policy.html
> webservices/axis2/trunk/java/xdocs/adb/
> webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html
> webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html
> webservices/axis2/trunk/java/xdocs/adb/adb-howto.html
> webservices/axis2/trunk/java/xdocs/adb/adb-tweaking.html
> webservices/axis2/trunk/java/xdocs/adb/images/
> webservices/axis2/trunk/java/xdocs/adb/images/ADB.jpg (with props)
> webservices/axis2/trunk/java/xdocs/axis2config.html
> webservices/axis2/trunk/java/xdocs/http-transport.html
> webservices/axis2/trunk/java/xdocs/images/Architecture.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/AxisService.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/Component.png (with props)
> webservices/axis2/trunk/java/xdocs/images/OM001.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM002.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/OM003.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/OM004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/OM005.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM006.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM007.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM008.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM1.png (with props)
> webservices/axis2/trunk/java/xdocs/images/ServerSideFault.png (with props)
> webservices/axis2/trunk/java/xdocs/images/ServiceDesc.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/TotalArch.png (with props)
> webservices/axis2/trunk/java/xdocs/images/WomBuilder.png (with props)
> webservices/axis2/trunk/java/xdocs/images/activate.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/admin.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/adminlogin.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/adminmain.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/ant.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/
> webservices/axis2/trunk/java/xdocs/images/archi-guide/CodegenArchitecture-new.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/CodegenArchitecture.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/all.png (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/big-picture.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/contexts.png (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/phases.png (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/soap-processing.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/soap.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi001.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi002.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi003.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi005.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi006.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi007.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi008.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi009.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi010.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi011.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi012.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi013.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi014.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi015.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi016.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi017.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi018.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi019.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi020.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi021.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi022.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi023.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi024.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi025.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi026.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/arrow_left.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/arrow_right.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/axis.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/ayncresult.png (with props)
> webservices/axis2/trunk/java/xdocs/images/call.png (with props)
> webservices/axis2/trunk/java/xdocs/images/callback.png (with props)
> webservices/axis2/trunk/java/xdocs/images/cases.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clientAPi.png (with props)
> webservices/axis2/trunk/java/xdocs/images/clientside.png (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image002.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image006.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image008.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image010.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image012.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image014.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image016.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image018.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image020.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image022.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image024.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image026.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/codegen.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/correlator.png (with props)
> webservices/axis2/trunk/java/xdocs/images/deploymetncomponent.png (with props)
> webservices/axis2/trunk/java/xdocs/images/editserviecpara.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/engine1.png (with props)
> webservices/axis2/trunk/java/xdocs/images/faultmsg.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/faultservice.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/globalchain.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/happyaxis.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image001.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image002.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image003.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image005.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/image005.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image006.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image007.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image008.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image009.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image010.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image011.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image012.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image013.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/inactivate.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/maven.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/module.png (with props)
> webservices/axis2/trunk/java/xdocs/images/moduleengage.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/modules.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/new.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/om2.png (with props)
> webservices/axis2/trunk/java/xdocs/images/om3.png (with props)
> webservices/axis2/trunk/java/xdocs/images/parameters.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/select_service_for_handler.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/send.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendAsync.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendRecievce.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendRecieveAsync.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendRecieveWithListnere.png (with props)
> webservices/axis2/trunk/java/xdocs/images/serverSide.png (with props)
> webservices/axis2/trunk/java/xdocs/images/service.png (with props)
> webservices/axis2/trunk/java/xdocs/images/serviceHandlers.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/servicegroups.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/
> webservices/axis2/trunk/java/xdocs/images/userguide/DirectoryStructure.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/ModuleView.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/MyServiceDeployed.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/ServiceDeployed.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/ServiceItems.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/TestClient.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/http-get-ws.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/viewphases.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/wom.png (with props)
> webservices/axis2/trunk/java/xdocs/index_docs.html
> webservices/axis2/trunk/java/xdocs/installationguide.html
> webservices/axis2/trunk/java/xdocs/jibx/
> webservices/axis2/trunk/java/xdocs/jibx/jibx-codegen-integration.html
> webservices/axis2/trunk/java/xdocs/jms-transport.html
> webservices/axis2/trunk/java/xdocs/mail-configuration.html
> webservices/axis2/trunk/java/xdocs/mail-transport.html
> webservices/axis2/trunk/java/xdocs/migration.html
> webservices/axis2/trunk/java/xdocs/mtom-guide.html
> webservices/axis2/trunk/java/xdocs/resources/
> webservices/axis2/trunk/java/xdocs/resources/schemas/
> webservices/axis2/trunk/java/xdocs/resources/schemas/module.xsd
> webservices/axis2/trunk/java/xdocs/resources/schemas/services.xsd
> webservices/axis2/trunk/java/xdocs/rest-ws.html
> webservices/axis2/trunk/java/xdocs/soapmonitor-module.html
> webservices/axis2/trunk/java/xdocs/spring.html
> webservices/axis2/trunk/java/xdocs/tcp-transport.html
> webservices/axis2/trunk/java/xdocs/transport_howto.html
> webservices/axis2/trunk/java/xdocs/userguide.html
> webservices/axis2/trunk/java/xdocs/webadminguide.html
>
> Added: webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html (added)
> +++ webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,266 @@
> +<?xml version="1.0" encoding=""?>
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
> + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
> +<html xmlns="http://www.w3.org/1999/xhtml">
> +<head>
> + <meta http-equiv="content-type" content="" />
> + <title>Axis2 RPC Support</title>
> +</head>
> +
> +<body>
> +<h1>Axis2 RPC Support</h1>
> +
> +<p>This documents talks about the Axis2's Remote Procedure Calls support in a
> +set of easy to understand implementation steps.</p>
> +
> +<h2>Introduction</h2>
> +
> +<p>Axis2 Remote Procedure Calls (RPC) support may seem somewhat tricky and
> +confusing at first glance. However, Axis2 RPC strategy is based on a well
> +defined set of rules and once the details are in place, it becomes clear as
> +day. This document aims to drill down to the details of this strategy and
> +fills up most of the fairly unknown bits and pieces. Note that Axis2
> +currently does not support the rpc/encoded style fully. It's 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> .....
> + < message name="requestMessage">
> + <part name="part1" type="xs:string"/>
> + <part name="part2" type="xs:int"/>
> + </message>
> + <message name="responseMessage">
> + <part name="part1" type="xs:string"/>
> + </message>
> + <portType name="echoPortType">
> + <operation name="echo">
> + <input message="y:requestMessage"/>
> + <output message="y:responseMessage"/>
> + </operation>
> + </portType>
> + <binding name="echoBinding" type="y:echoPortType">
> + <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
> + <operation name="echo">
> + <soap:operation soapAction="echo"/>
> + <input>
> + <soap:body use="literal"/>
> + </input>
> + <output>
> + <soap:body use="literal"/>
> + </output>
> + </operation>
> + </binding>
> +.....</pre>
> +
> +<p>The binding says its got to be rpc/lit and in this case the message parts
> +need wrapping in the following order.</p>
> +<ol>
> + <li>The first element needs to have the operation name as the local name
> + and the operation namespace (which 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>
> +
> +<p>For example the input wire message for the echo operation mentioned in the
> +above WSDL fragment would look like this:</p>
> +<pre> <op:<strong>echo</strong> xmlns:op="porttype namespace">
> + <<strong>part1</strong>>Hello World</part1>
> + <<strong>part2</strong>>123</part2>
> + </op:echo></pre>
> +
> +<p>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 quite
> +possible to generate a schema, representing this structure and then treat the
> +whole service as pure doc/lit service. In this case, following is the piece
> +of schema generated to make this rpc to doc conversion. Note that in this
> +case the wire message stays unchanged. It is only a different WSDL authoring
> +style</p>
> +<pre> <xs:element name="echo">
> + <xs:complexType>
> + <xs:sequence>
> + <xs:element name="part1" type="xs:string" />
> + <xs:element name="part2" type="xs:int" />
> + </xs:sequence>
> + </xs:complexType>
> + </xs:element></pre>
> +
> +<p>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!</p>
> +
> +<h2>Step 2 - Unwrapping the Schema</h2>
> +
> +<p>If the schema needs to be unwrapped then that brings up a few issues
> +mainly because the only thing that the emitters rely on when generating code
> +is a mapping table!</p>
> +<ol>
> + <li>When the schema is unwrapped where would that unwrapping information
> + stay?
> + <p>Good question - It needs to be a store that keeps the information
> + seperated. Hmm.. What can we use here ? Why of course, the Axis *
> + hierarchy! It has nicely separated information holders and a parameter
> + store that can hold a information bean.</p>
> + </li>
> + <li>How do we maintain uniqueness among message part names?
> + <p>Another Good question - part names are only unique across a message
> + and not globally. But 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</p>
> + </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. What it does is to walk 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>< element >
> + < complexType >
> + < sequence >
> + < element />
> + < /sequence >
> + < /complexType >
> + < /element >
> + </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><input>
> + <param name="param4" type="com.example.www.ServiceNameStub.Echo" shorttype="Echo" value="null" location="body" opname="echo">
> + <param name="param5" type="java.lang.String" shorttype="String" value="null" location="body" opname="echo" partname="Part1"
> + primitive="yes"/>
> + <param name="param6" type="int" shorttype="int" value="0" location="body" opname="echo" partname="Part2" primitive="yes"/>
> + </param>
> +</input></pre>
> +
> +<p>The next part is upto the template to handle. 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 a sort of 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 />
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html (added)
> +++ webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,735 @@
> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
> +<html>
> +<head>
> + <meta http-equiv="content-type" content="">
> + <title>Axis2 Architecture Guide</title>
> + <meta content="20050916;22455288">
> +</head>
> +
> +<body lang="en-US" dir="ltr">
> +<h1 align="center">Apache Axis2 Architecture Guide</h1>
> +
> +<p>This document will give an introduction to Axis2's modular architecture
> +with explanations on every module.</p>
> +
> +<p><i>Send your feedback to: <a
> +href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
> +subject with [Axis2]. To subscribe to mailing list see <a
> +href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
> +
> +<h2>Contents</h2>
> +<ul>
> + <li><a href="#bmBP">The Big Picture</a></li>
> + <li><p><a href="#requirements">Requirement of Axis2</a></p>
> + </li>
> + <li><a href="#thearchi">Axis2 Architecture</a>
> + <ul>
> + <li><p><a href="#bmcore">Core Modules</a></p>
> + </li>
> + <li><a href="#bmother">Other Modules</a></li>
> + <li><p><a href="#bmInfoMod">Information Model</a></p>
> + </li>
> + <li><a href="#bmXML">XML Processing Model</a></li>
> + <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
> + <ul>
> + <li><a href="#default">Axis2 Default Processing Model</a></li>
> + <li><p><a href="#incomingsoap">Processing an Incoming SOAP
> + Message</a></p>
> + </li>
> + <li><a></a><a href="#outgoing">Processing of the Outgoing
> + Message</a></li>
> + <li><p><a href="#extending">Extending SOAP Processing Model</a></p>
> + <ul>
> + <li><a href="#extendingwithhandlers">Extending the SOAP
> + Processing Model with Handlers</a></li>
> + <li><p><a href="#extendingwithmodules">Extending the SOAP
> + Processing Model with Modules</a></p>
> + </li>
> + </ul>
> + </li>
> + </ul>
> + </li>
> + <li><a href="#bmDeployment">Deployment</a>
> + <ul>
> + <li><a href="#xmlfile">The <em>axis2.xml</em> file</a></li>
> + <li><p><a href="#servicearchive">Service Archive</a></p>
> + </li>
> + <li><a href="#modulearchive">Module Archive</a></li>
> + </ul>
> + </li>
> + <li><p><a href="#bmClientAPI">Client API</a></p>
> + <ul>
> + <li><a href="#oneway">One Way Messaging Support</a></li>
> + <li><p><a href="#requestresponse">Request Response Messaging
> + Support</a></p>
> + </li>
> + </ul>
> + </li>
> + <li><a href="#bmTransports">Transports</a></li>
> + <li><p><a href="#bmWSDL">Code generation</a></p>
> + </li>
> + <li><a href="#bmDB">Data Binding</a>
> + <ul>
> + <li><a href="#integration">Integration with Code Generation
> + Engine</a></li>
> + <li><p><a href="#serial">Serialization and De-Serialization</a></p>
> + </li>
> + </ul>
> + </li>
> + </ul>
> + </li>
> +</ul>
> +
> +<h2><a name="bmBP">The Big Picture</a></h2>
> +
> +<p>A new architecture for Axis was introduced during the August 2004 Summit
> +in Colombo, Sri Lanka. This new architecture Axis2 is based on 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.</p>
> +
> +<p>Any architecture is a result of what that architecture should yield. The
> +success of an architecture should be evaluated based on the requirements
> +expected to be met by that architecture. Let us start our journey into Axis2
> +by looking at the requirements.</p>
> +<a name="requirements"></a>
> +
> +<h2>Requirement of Axis2</h2>
> +
> +<p>In the SOAP terminology, a participant who is taking part in a Web service
> +interaction is known as a SOAP Node. Delivery of a single SOAP Message is
> +defined based on two participants, SOAP Sender and SOAP Receiver. Each SOAP
> +Message is sent by SOAP Sender and received by SOAP Receiver. A single SOAP
> +delivery is the most basic unit that builds the Web service interaction.</p>
> +
> +<p>Each SOAP Node may be written in specific programming language, may it be
> +Java, C++, .NET or Perl, the Web services allow them to inter operate. This
> +is possible because on the wire each Web service interaction is done via
> +SOAP, which is common to every SOAP Node.</p>
> +
> +<p><img alt="" src="images/archi-guide/soap.gif" name="Graphic1"
> +align="bottom" width="691" height="319" border="0"></p>
> +
> +<p>Web service middleware handles the complexity in SOAP messaging and lets
> +the users work with the programming language they are accustomed to. Axis2
> +allows java users to invoke Web services using java representations, and
> +handles the SOAP messaging behind the curtain.</p>
> +
> +<p>Axis2 handles SOAP processing along with numerous other tasks. This makes
> +the life of the Web service developer a whole lot easier. Following are the
> +identified requirements:</p>
> +<ol>
> + <li>Provide a framework to process the SOAP messages. The framework should
> + be extensible and the users should be able to extend the SOAP processing
> + per service or per operation basis. Furthermore it should be able to
> + model different Message Exchange Patterns (MEPs) using the processing
> + framework.</li>
> + <li>Ability to deploy a Web service (with or without WSDL)</li>
> + <li>Provide a Client API that can be used to invoke Web services. This API
> + should support both the Synchronous and Asynchronous programming
> + models.</li>
> + <li>Ability to configure Axis2 and it's components via deployment.</li>
> + <li>Ability to send and receive SOAP messages with different
> + transports.</li>
> +</ol>
> +
> +<p>Apart from the above functionalities, performance in terms of memory and
> +speed is a major consideration for Axis2. Axis2 Core Architecture is built on
> +three specifications- WSDL, SOAP and WS-Addressing. Other specifications like
> +JAX-RP, SAAJ & WS-Policy are layered on top of the Core Architecture.</p>
> +
> +<h2><a name="thearchi">Axis2 Architecture</a></h2>
> +Axis2 architecture lays out some principals to preserve the uniformity. They
> +are as follows:
> +<ul>
> + <li><p>Axis2 architecture separates the logic and the states. Code that
> + does the processing is stateless inside Axis2. This allows code to be
> + executed freely by parallel threads.</p>
> + </li>
> + <li>All the information is kept in one information model allowing system to
> + be suspended and resumed.</li>
> +</ul>
> +
> +<p>Axis2 architecture is modular. Therefore Axis2 Framework is built up of
> +core modules which collectively make up the core architecture of Axis2, and
> +non-core/other modules are layered on top of this core
> +modules/architecture.</p>
> +<a name="bmother"></a>
> +
> +<h3>Core Modules:</h3>
> +<ul>
> + <li><a href="#bmInfoMod">Information Model</a>- Axis2 defines a model to
> + handle information and all states are kept in this model. The model has a
> + hierarchy for the information. The system manages the life cycle of the
> + objects in this hierarchy.</li>
> + <li><p><a href="#bmXML">XML processing Model</a>- Handling the SOAP Message
> + is the most important and most complex task. The efficiency of this is
> + the single most important factor that decides the performance. It makes
> + sense to delegate this task to a separate sub-project itself, under Web
> + service project, allowing that sub-project (AXIOM) to provide a simple
> + API for SOAP and XML info-set while hiding the complexities of the
> + efficient XML processing within the implementation.</p>
> + </li>
> + <li><a href="#bmSOAPPM">SOAP Processing Model</a>- This controls the
> + execution of the processing. The model defines different phases the
> + execution would walk through, and the user can extend the Processing
> + Model at some specific places.</li>
> + <li><p><a href="#bmDeployment">Deployment Model</a>- Axis2 deployment model
> + allows the user to deploy services, configure the transports, extend the
> + SOAP Processing model per system, service or operation basis.</p>
> + </li>
> + <li><a href="#bmClientAPI">Client API</a>- This provides a convenient API
> + for users to communicate with Web services using Axis2. There are set of
> + classes to interact with IN-OUT and IN-Only style Message Exchange
> + Patterns (MEPs) where those can be used to construct any other MEP.</li>
> + <li><p><a href="#bmTransports">Transports</a>- Axis2 define a transport
> + framework that enables the user to use different transports. The
> + transports fit into specific places in the SOAP processing model. The
> + implementation provides a few common transports and the user may write
> + new ones if and when it is needed.</p>
> + </li>
> +</ul>
> +<a name="bmcore"></a>
> +
> +<h3>Other Modules:</h3>
> +<ul>
> + <li><a href="#bmWSDL">Code Generation</a>- Axis2 provides a code generation
> + tool that will generate server side and client side code along with a
> + test case. The generated code would simplify the service deployment and
> + the service invocation. This would increase usability of Axis2.</li>
> + <li><p><a href="#bmDB">Data Binding</a>- The basic client API of Axis2 lets
> + the users process SOAP at the infoset level where as data binding extends
> + it to make it more convenient to the users by encapsulating the infoset
> + layer and providing a programming language specific interface.</p>
> + </li>
> +</ul>
> +<map name="Graphic2Map" id="g2m">
> + <area shape="rect" coords="123,31,222,97" href="#bmInfoMod" alt="">
> + <area shape="rect" coords="239,62,319,134" href="#bmXML" alt="">
> + <area shape="rect" coords="127,112,218,177" href="#bmSOAPPM" alt="">
> + <area shape="rect" coords="12,39,89,95" href="#bmDeployment" alt="">
> + <area shape="rect" coords="0,108,94,156" href="#bmWSDL" alt="">
> + <area shape="rect" coords="350,31,426,86" href="#bmClientAPI" alt="">
> + <area shape="rect" coords="350,114,421,164" href="#bmTransports" alt="">
> +</map>
> +
> +<p><img src="images/archi-guide/all.png" name="Graphic2" width="426" alt=""
> +height="189" border="0" align="bottom" usemap="#Graphic2Map"></p>
> +
> +<h2><a name="bmInfoMod">Information Model</a></h2>
> +
> +<p>Information Model has two main hierarchies-Contexts and Descriptions. This
> +model is described in UML notations below.</p>
> +
> +<p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom"
> +alt="" width="400" height="443" border="0"></p>
> +
> +<p>( A ----<> B says, B has 1 or more objects of A. A------>B says,
> +the given relationship holds between A and B.)</p>
> +
> +<p>The two hierarchies are connected as shown in the above figure. The
> +Description hierarchy represents the static data. This data may be loaded
> +from a configuration file that exists throughout the lifetime of Axis2. For
> +example, deployed Web services, operations, etc. On the other hand, the
> +context hierarchy holds more dynamic information about the things that have
> +more than one instances (e.g.Message Context).</p>
> +
> +<p>These two hierarchies creates a model that provides the ability to search
> +for key value pairs. When the values are searched at a given level, they are
> +searched while moving up the hierarchy until a match is found. In the
> +resulting model the lower levels override the values in the upper levels. For
> +example, when a value is looked up in the Message Context and is not found,
> +it would be looked up in the Operation Context etc, up the hierarchy. The
> +Search is first done up the hierarchy, and if starting point is a Context
> +then it is search in the Description hierarchy as well.</p>
> +
> +<p>This allows the user to declare and override values. Result being a very
> +flexible configuration model. The flexibility could be the <em>Achilles</em>
> +heel for the system as the search is expensive, specially for something that
> +does not exist. Yet in the final analysis developers believe that the
> +flexibility would serve better in this instant.</p>
> +
> +<table width="955" border="1" cellpadding="2" cellspacing="3">
> + <col width="112"><col width="371"><col width="103"><col width="336"><tbody>
> + <tr>
> + <td><strong>Context</strong></td>
> + <td><strong>Description</strong></td>
> + <td><strong>Configuration</strong></td>
> + <td><strong>Description</strong></td>
> + </tr>
> + <tr>
> + <td width="112"><p>Configuration Context</p>
> + </td>
> + <td width="371"><p>Holds the run time status. A deep copy of this would
> + essentially make a copy of Axis2.</p>
> + </td>
> + <td width="103"><p>Axis Configuration</p>
> + </td>
> + <td width="336"><p>Holds all global configurations. Transports, global
> + modules, parameters and services etc.</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><p>Service Group Context</p>
> + </td>
> + <td width="371"><p>Holds information about a particular usage of the
> + respective service group. The life of a Service Group Context starts
> + when a user starts interacting with a service that belong to this
> + service group. This can be used to share information between services
> + (within the same service group) in a single interaction.</p>
> + </td>
> + <td width="103"><p>AxisServiceGroup</p>
> + </td>
> + <td width="336"><p>Holds deployment time information about a particular
> + service group.</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><p>Service Context</p>
> + </td>
> + <td width="371"><p>This context is available throughout the usage of
> + the respective service. This can be used to share information between
> + several MEPs of the same service, within a single interaction.</p>
> + </td>
> + <td width="103"><p>AxisService</p>
> + </td>
> + <td width="336"><p>Hold the Operations and the service level
> + configurations</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><p>Operation Context</p>
> + </td>
> + <td width="371"><p>Holds the information about the current MEP
> + instance, maintain the Messages in the current MEP etc.</p>
> + </td>
> + <td width="103"><p>AxisOperation</p>
> + </td>
> + <td width="336"><p>Holds the operation level configurations</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><a name="messageContext"></a>
> +
> + <p>Message Context</p>
> + </td>
> + <td width="371"><p>Holds all the information about the Message
> + currently being executed.</p>
> + </td>
> + <td width="103"><p>AxisMessage</p>
> + </td>
> + <td width="336"><p>Do not hold any information as yet, but can be used
> + as a future extension point.</p>
> + </td>
> + </tr>
> + </tbody>
> +</table>
> +<a name="bmXML"></a>
> +
> +<h2>XML Processing Model</h2>
> +
> +<p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p>
> +
> +<h2><a name="bmSOAPPM">SOAP Processing Model</a></h2>
> +
> +<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" alt=""
> +align="bottom" width="755" height="348" border="0"></p>
> +
> +<p>The architecture identified two basic actions a SOAP processor should
> +perform, sending and receiving SOAP messages. The architecture provides two
> +Pipes ('Flows'), to perform these two basic actions. Axis Engine or the
> +driver of Axis2 defines two methods send() and receive() to implement these
> +two Pipes. The two pipes are named <i><b>In</b> Pipe</i> and <i><b>Out</b>
> +Pipe</i>, and the complex Message Exchange Patterns (MEPs) are constructed by
> +combining these two pipes.</p>
> +
> +<p>Extensibility of the SOAP processing model is provided through handlers.
> +When a SOAP message is being processed the handlers that are registered would
> +be executed. The handlers can be registered in global, service, or operation
> +scopes and the final handler chain is calculated combining the handlers from
> +all the scopes.</p>
> +
> +<p>The handlers act as interceptors and they process parts of the SOAP
> +message and provide add-on services. Usually handlers work on the SOAP
> +headers, yet they may access or change the SOAP Body as well.</p>
> +
> +<p>When a SOAP message is being sent through the Client API, an <i>Out
> +Pipe</i> would begin, the <i>Out Pipe</i> invokes the handlers and end with a
> +Transport Sender that sends the SOAP message to the target endpoint. The SOAP
> +message is received by a Transport Receiver at the target endpoint, which
> +reads the SOAP message and starts the <i>In Pipe</i>. The <em>In Pipe</em>
> +consists of handlers and ends with the <a href="#mr">Message Receiver</a>,
> +which consumes the SOAP message.</p>
> +
> +<p>Above explained processing happens for each and every SOAP message
> +exchanged. After processing one message Axis2 may decide to create other SOAP
> +messages, in which case more complex message patterns emerge. However Axis2
> +always view the SOAP message in terms of processing a single message. The
> +combination of the messages are layered on top of that basic framework.</p>
> +
> +<p>The two pipes does not differentiate between the Server and the Client.
> +The SOAP Processing Model handles the complexity and provides two abstract
> +pipes to the user. The different areas or the stages of the pipes are given
> +names, and according to the Axis2 slang those are named 'phases'. A Handler
> +always runs inside a phase, and the phase provides a mechanism to specify the
> +ordering of handlers. Both Pipes have built in phases, and both define the
> +areas for 'User Phases' which can be defined by the user.</p>
> +
> +<h3><a name="default">Axis2 Default Processing Model</a></h3>
> +
> +<p>Axis2 has some inbuilt handlers that run in inbuilt phases and they create
> +the default configuration for the Axis2. We will be looking more in to how to
> +extend the default processing Model in the next section.</p>
> +There are four special handlers defined in Axis2.
> +<ol>
> + <li>Dispatchers - Finds the service and the operation the SOAP message is
> + directed to. Dispatchers always run on the <em>In-Pipe</em> and inside
> + the Dispatch phase. The in-built dispatchers dispatch to a particular
> + operation depending on various conditions like WS-Addressing information,
> + URI information, SOAP action information, etc.,</li>
> +</ol>
> +<ul>
> + <li><a name="mr">Message Receiver - Consume the SOAP Message and hands that
> + over to application , Message receiver is the last handler of the
> + in-pipe</a></li>
> + <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
> + message is destined to. Always runs as last handler in the out-pipe</p>
> + </li>
> +</ul>
> +
> +<h3><a name="incomingsoap">Processing an Incoming SOAP Message</a></h3>
> +
> +<p>Incoming SOAP Message is always received by a Transport Receiver waiting
> +for the SOAP Messages. Once the SOAP Message arrives the transport Headers
> +are parsed and a</p>
> +<a href="#messageContext">Message Context</a> is created from the incoming
> +SOAP Message. Then the <i>In Pipe</i> is executed with the Message Context.
> +
> +<p>Let us see what happens at each phase of the execution. This process may
> +happen either in the server or in the Client.</p>
> +<ol>
> + <li><strong>Transport Phase</strong> - The handlers are in the phase meant
> + to process transport specific information such as validating incoming
> + message by looking at various transport headers, add data into message
> + context etc.</li>
> + <li><strong>Pre-Dispatch Phase</strong>- The main functionality of the
> + handlers in this phase is to populate message context in order to do the
> + dispatching. As an example, processing of addressing headers of the SOAP
> + message happen in this phase.Addressing handlers extract information and
> + put them in to the message context.</li>
> + <li><strong>Dispatch Phase</strong> - The Dispatchers run in this phase and
> + tries to find the correct service and operation this particular message
> + is destined to.<br>
> + The post condition of the dispatch phase (any phase can contain a post
> + condition) checks whether a service and an operation was found by the
> + dispatchers. If not the execution will halt and throws out a "service not
> + found error".</li>
> + <li><strong>User Defined Phases</strong> - Users are allowed to engage
> + their custom handlers here.</li>
> + <li>Message Validation Phase - Once the user level execution has taken
> + place this phase validates whether SOAP Message Processing has taken
> + place correctly.</li>
> + <li><strong>Message Processing Phase</strong> - The Business logic of the
> + SOAP message is executed here. A <a href="#mr">Message Receiver</a> is
> + registered with each Operation. This Message receiver (associated to the
> + particular operation) will executed as the last Handler of this
> + phase.</li>
> +</ol>
> +
> +<p>There may be other handlers in any of these phases. Users may use custom
> +handlers to override the mechanics in each of these phases.</p>
> +
> +<h3><a name="outgoing">Processing of the Outgoing Message</a></h3>
> +
> +<p><em>Out Pipe</em> is simpler because the service and operation to dispatch
> +is known by the time the pipe is executed. The <em>Out Pipe</em> may be
> +initiated by the</p>
> +<a href="#mr">Message Receiver</a> or the Client API implementation.Phases of
> +the <em>Out Pipe</em> are described below:
> +<ol>
> + <li>Message Initialize Phase - First phase of the <em>Out Pipe</em>. Serves
> + as the placeholder for the custom handlers</li>
> + <li>User Phases - This executes handlers in user defined phases</li>
> + <li>Transports Phase - Execute any transport handlers taken from the
> + associated transport configuration. The last handler would be a transport
> + sender which would send the SOAP message to the target endpoint.</li>
> +</ol>
> +
> +<h3><a name="extending">Extending SOAP Processing Model</a></h3>
> +
> +<p>Above we discussed the default processing model of Axis2. Now let us
> +discuss the extension mechanism for the SOAP processing model. After all, the
> +whole effort of making this SOAP engine/processing model was focused much on
> +making it extendable.</p>
> +
> +<p>Idea behind introducing step wise processing of the SOAP message in terms
> +of handlers & phases is to allow easier modification of the processing
> +order. The notion of phases makes it easier to place handlers in between
> +other handlers. This enables modification on the default processing behavior.
> +SOAP Processing Model can be extended with <a
> +href="#extendingwithhandlers">handler</a> or <a
> +href="#extendingwithmodules">modules</a>.</p>
> +<a name="extendingwithhandlers"></a>
> +
> +<h4>Extending the SOAP Processing Model with Handlers</h4>
> +The handlers in a module can specify the phase they need to be placed in.
> +Furthermore they can specify their location inside a phase by providing phase
> +rules. Phase rules will place a handler
> +<ol>
> + <li>as the first handler in a phase.</li>
> + <li>or as the last handler in a phase.</li>
> + <li>or before a given handler</li>
> + <li>or after a given handler</li>
> +</ol>
> +
> +<h4><a name="extendingwithmodules">Extending the SOAP Processing Model with
> +Modules</a></h4>
> +
> +<p>Axis2 defines an entity called a 'module' that can introduce handlers and
> +Web service operations. A Module in terms of Axis2 usually acts as a
> +convenient packaging that includes</p>
> +<ul>
> + <li>a set of handlers and</li>
> + <li>an associated descriptor which includes the phase rules</li>
> +</ul>
> +. Modules have the concept of being 'available' and 'engaged'. 'Availability'
> +means the module is present in the system, but has not been activated, i.e.,
> +the handlers included inside the module have not been used in the processing
> +mechanism. When a module is 'engaged' it becomes active and the handlers get
> +placed in the proper phases. The handlers will act in the same way as
> +explained in the previous section. Usually a module will be used to implement
> +a WS-* functionality such as WS-Addressing.
> +
> +<p>Apart from the extension mechanism based on the handlers, the WS-*
> +specifications may suggest a requirement for adding new operations. For
> +example, once a user add a Reliable Messaging capability to a service, the
> +"Create Sequence" operation needs to be available to the service end point.
> +This can be implemented by letting the modules define the operations. Once
> +the module is engaged to a service, the necessary operations will be added to
> +that service.</p>
> +
> +<p>A service, operations or the system may engage a module. Once the module
> +is engaged the handlers and the operations defined in the module are added to
> +the entity that engaged them.</p>
> +
> +<p>Modules can not be added (no hot deployment) while the Axis2 engine is
> +running, but they will be available once the system is restarted.</p>
> +<a name="bmDeployment"></a>
> +
> +<h2>Deployment</h2>
> +
> +<p>The Deployment Model provides a concrete mechanism to configure Axis2.
> +This model has three entities that provide the configuration.</p>
> +<a name="xmlfile"></a>
> +
> +<h3>The axis2.xml file</h3>
> +
> +<p>This file holds the global configuration for the client and server, and
> +provide following information:</p>
> +<ol>
> + <li>The global parameters</li>
> + <li>Registered transports in and transport outs</li>
> + <li>User defined phase names</li>
> + <li>Modules that are engaged globally (to all services)</li>
> + <li>Globally defined <a href="#mr">Message Receivers</a></li>
> +</ol>
> +<a name="servicearchive"></a>
> +
> +<h3>Service Archive</h3>
> +
> +<p>Service archive must have a <em>META-INF/<a
> +href="resources/schemas/services.xsd">services.xml</a></em> file and may
> +contain the dependent classes. The <em>services.xml</em> file has following
> +information.</p>
> +<ol>
> + <li>Service level parameters</li>
> + <li>Modules that are engaged service level</li>
> + <li>Service Specific <a href="#mr">Message Receivers</a></li>
> + <li>Operations inside the service</li>
> +</ol>
> +
> +<h3><a name="modulearchive">Module Archive</a></h3>
> +
> +<p>Module archive must have a META-INF/<a
> +href="resources/schemas/module.xsd">module.xml</a> file and dependent
> +classes. The <em>module.xml</em> file has Module parameters and the
> +Operations defined in the module.</p>
> +
> +<p>When the system is starting up Axis2 ask the deployment model to create a
> +Axis Configuration. Deployment Model first finds the axis2.xml file and build
> +the global configuration. Then it checks for the module archives and then for
> +the service archives. After that the corresponding services and modules are
> +added to the Axis Configuration. System will build contexts on top of the
> +Axis Configurations. After this Axis2 is ready to send or receive the SOAP
> +messages. Hot deployment is only allowed for services.</p>
> +<a name="bmClientAPI"></a>
> +
> +<h2>Client API</h2>
> +
> +<p>There are three parameters that decide the nature of the Web service
> +interaction.</p>
> +<ol>
> + <li>Message Exchange Pattern (MEP)</li>
> + <li>The Behavior of the transport, whether it's One-Way or Two-Way</li>
> + <li>Synchronous/ Asynchronous behavior of the Client API</li>
> +</ol>
> +
> +<p>Variations of the three parameters can result in indefinite number of
> +scenarios, even though Axis2 is built on a core that support any messaging
> +interaction, the developers were compelled to support only two most widely
> +used Message Exchange Patterns (MEPs).</p>
> +
> +<p>Two supported MEPs are One-Way and the In-Out (Request-Response) scenarios
> +in the Client API. The implementation is based on a class called
> +<code>ServiceClient</code> and there are extensions for each MEP that Axis2
> +Client API supports.</p>
> +
> +<h3><a name="oneway">One Way Messaging Support</a></h3>
> +
> +<p>The One-Way support is provided by the <code>fireAndForget</code> method
> +of <code>ServiceClient</code>. For one way invocations one can use HTTP ,
> +SMTP and TCP transports. In the case of the HTTP transport the return channel
> +is not used and the HTTP 202 OK is returned in the return Channel.</p>
> +<a name="requestresponse"></a>
> +
> +<h3>In-Out (Request Response) Messaging Support</h3>
> +
> +<p>The In-Out support is provided by the <code>sendReceive()</code> method in
> +ServiceClient. This provides a much simpler interface for the user. The
> +Client API has four ways to configure a given Message Exchange</p>
> +<ol>
> + <li>Blocking or Non-Blocking nature - this can be decided by using
> + <code>sendReceive()</code> or <code>sendReceiveNonBlocking()</code>
> + methods</li>
> + <li>Sender transport - transport used to send the SOAP Message</li>
> + <li>Listener transport - transport the Response is received</li>
> + <li>Use Separate Channel - determines whether the response is send over a
> + separate transport connection or not. This can be false only when sender
> + and listener transport is same and is a Two-Way transport.</li>
> +</ol>
> +
> +<p>Depending on the values of the above four parameter, Axis2 behave
> +differently.</p>
> +<a name="bmTransports"></a>
> +
> +<h2>Transports</h2>
> +
> +<p>Axis2 has two basic constructs for transports, namely; Transport Senders
> +and Transport Receivers . These are accessed via the AxisConfiguration.</p>
> +
> +<p>The incoming transport is the transport via which the AxisEngine receives
> +the message. The outgoing transport is decided based on the addressing
> +information (wsa:ReplyTo and wsa:FaultTo). If addressing information is not
> +available and if server is trying to respond, then the out going transport
> +will be the outputstream of the incoming transport (if it is two-way
> +transport).</p>
> +
> +<p>At the client side the user is free to specify the transport to be
> +used.</p>
> +
> +<p>Transport Senders and Transport Receivers contains following
> +information.</p>
> +<ol>
> + <li>Transport Sender for Out Configuration</li>
> + <li>Transport Listener for In Configuration</li>
> + <li>Parameters of the transport</li>
> +</ol>
> +
> +<p>Each and every transport out configuration defines a transport sender.
> +Transport sender sends the SOAP message, depending on its configuration.</p>
> +
> +<p>Transport receiver waits for the SOAP Messages and for each SOAP Message
> +that arrives, it uses the <i>In Pipe</i> to process the SOAP Message.</p>
> +
> +<p>Axis2 Presently support the following transports:</p>
> +<ol>
> + <li>HTTP - In HTTP transport the transport listener is a servlet or
> + org.apache.axis2.transport.http.SimpleHTTPServer provided by Axis2. The
> + transport sender uses commons-httpclient to connect and send the SOAP
> + Message.</li>
> + <li>TCP - This is the most simplest transport, but needs the WS -
> + Addressing support to be functional.</li>
> + <li>SMTP - This works off a single email account. Transport receiver is a
> + thread that checks for emails in fixed time intervals.</li>
> + <li>JMS</li>
> +</ol>
> +<a name="bmWSDL" id="bmWSDL"></a>
> +
> +<h2>Code Generation</h2>
> +
> +<p>Although the basic objective of the code generation tools has not changed,
> +the code generation module of Axis2 has taken a different approach to
> +generate code. Primarily the change is in the use of templates, namely XSL
> +templates which gives the code generator the flexibility to generate code in
> +multiple languages.</p>
> +
> +<p>The basic approach is to set the code generator to generate an XML and
> +parse it with a template to generate the code file. The following figure
> +describes how this shows up in the architecture of the tool.</p>
> +
> +<p><img src="images/archi-guide/CodegenArchitecture-new.gif" name="Graphic6"
> +alt="" align="bottom" border="0"></p>
> +
> +<p>The fact here is that it is the same information that is extracted from
> +the WSDL no matter what code is generated. First, an AxisService is populated
> +from a WSDL. Then the code generator extracts information from the
> +AxisService and creates an XML which is language independent. This emitted
> +XML is then parsed with the relevant XSL to generate code for the relevant
> +language. No matter what the output language, the process is the same except
> +for the template that is being used.</p>
> +
> +<h2><a name="bmDB" id="bmDB">Data Binding</a></h2>
> +
> +<h3>Integration with Code Generation Engine</h3>
> +
> +<p>Databinding for Axis2 is implemented in an interesting manner. Databinding
> +has not been included in the core deliberately and hence the code geneation
> +allows different data binding frameworks to be plugged in. This is done
> +through an extension mechanism where the codegen engine calls extensions
> +first and then executes the core emitter. The extensions populate a map of
> +QNames vs. class names that is passed to the code generator on which the
> +emitter operates on.</p>
> +
> +<p><strong>The following diagram shows the structure:</strong></p>
> +
> +<p><img src="images/codegen.gif" name="Graphic7" align="bottom"
> +border="0"></p>
> +
> +<p><strong>The following databinding extensions are available:</strong></p>
> +<ol>
> + <li><strong>ADB</strong> - ADB (Axis Data Binding ) is a simple framework
> + that allows simple schemas to be compiled. It is lightweight and simple,
> + works off StAX and fairly performant. However, it does not support the
> + complete set of schema constructs and is likely to complain for certain
> + schemas!</li>
> + <li><strong>XMLBeans</strong> - XMLbeans claims that it supports the
> + complete schema specification and it is the choice, if full schema
> + support is needed!</li>
> + <li><strong>JAX-Me</strong> - JaxMe support has been added in a similar
> + manner to XMLbeans and serves as another option for the user</li>
> + <li><strong>JibX</strong> - This is the most recent addition to the family
> + of databinding extensions and it is also another option the users have
> + for data binding.</li>
> +</ol>
> +
> +<h3><a name="serial" id="serial">Serialization and De-Serialization of Data
> +bound classes</a></h3>
> +
> +<p>AXIOM is based on a StAX API (Streaming API for XML). Xml-beans supports
> +StAX API. Data binding in Axis2 is achieved through interfacing the AXIOM
> +with the Xml-beans using the StAX API which is supported by both parties. At
> +the time of the code generation there will be utility methods generated
> +inside the stub (or the message receiver) that can de-serialize from AXIOM to
> +data bound object and serialize from data bound object to AXIOM. For example,
> +if the WSDL has an operation called "echoString", once the code is generated
> +the following methods will be generated inside the relevant classes.</p>
> +<pre>public static
> +org.apache.axiom.om.OMElementtoOM(org.soapinterop.xsd.EchoStringParamDocument
> +param)// This method will handle the serialization.
> +
> +public static org.apache.xmlbeans.XmlObject
> +fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This
> +method will handle the de-serialization.</pre>
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/WS_policy.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/WS_policy.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/WS_policy.html (added)
> +++ webservices/axis2/trunk/java/xdocs/WS_policy.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,174 @@
> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
> + "http://www.w3.org/TR/html4/loose.dtd">
> +<html>
> +<head>
> + <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
> + <title>WS Policy Support in Axis2</title>
> + <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
> +</head>
> +
> +<body lang="en">
> +<h1 align="center">Web Services Policy Support In Axis2</h1>
> +
> +<p>This document will give you an introduction to the role of Web services
> +policy in Axis2.</p>
> +
> +<p><i>E-mail comments/ suggestions to: <a
> +href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
> +subject with [Axis2]. To subscribe to mailing list see <a
> +href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
> +
> +<h2>Content</h2>
> +<ul>
> + <li><a href="#what">What is Web Services (WS) Policy?</a></li>
> + <li><a href="#client">Client Side WS-Policy Support</a></li>
> + <li><a href="#server">Server Side WS-Policy Support</a></li>
> + <li><a href="#resources">Resources</a></li>
> +</ul>
> +<a name="what"></a>
> +
> +<h2>What is Web Services (WS) Policy?</h2>
> +
> +<p>To consume non trivial web services one must fully understand its xml
> +contract (WSDL) along with any other additional requirements, capabilities or
> +preferences which translates to the configuration of the service, and
> +essentially becomes the policies of the service.</p>
> +
> +<p>WS Policy framework provides a way to express the policies of a service in
> +a machine-readable way. Web services infrastructure can be enhanced to
> +understand and enforce policies at runtime. For instance, a service author
> +might write a policy requiring digital signature and encryption, while
> +service consumers could use the policy information to reason out whether they
> +can adhere to this policy information to use the service or not.</p>
> +
> +<p>Further more, web service infrastructure could be enhanced to enforce
> +those requirements without requiring the service author to write even single
> +line of code.</p>
> +<a name="client"></a>
> +
> +<h2>Client Side WS-Policy Support</h2>
> +
> +<p>This release <strong>fully supports WS Policy at client-side</strong>. It
> +means that when you codegen a stub against a WSLD which contains policies,
> +the stub will contain the capability to engage the required modules with the
> +appropriate configurations. For instance, if there is a security policy
> +attached to an operation in the WSDL, the generated stub will engage the
> +security module for that operation with the appropriate security
> +configurations.</p>
> +
> +<h3>How it works:</h3>
> +
> +<h4>Phase 1: At PolicyEvaluator</h4>
> +
> +<p>Codegen engine runs few of its registered extensions before it generates
> +the stub. When PolicyEvalutor (which is a registered Codegen extension) is
> +initialized, it populates a registry of namespaces of supported policies to
> +PolicyExtensions.</p>
> +
> +<p>For instance, module foo might have a mapping of namespace
> +http://test.com/foo which means any primitive assertion which has this
> +namespace will be processed by this module. Foo module might implement the
> +ModulePolicyExtension interface through which PolicyExtension object can be
> +obtained.</p>
> +
> +<p>A <strong>PolicyExtension</strong> is the access point for a module to add
> +any other methods to the stub. For instance Reliable Messaging module can add
> +createSequence() and endSequence() methods to the stub, that the user must
> +call to start and end an RM sequence.</p>
> +
> +<p>Then at the engagement of PolicyEvaluator, effective policy of each
> +operation is calculated based on policy information declared in the WSDL
> +document. Here we assume that effective policy of an operation contains a
> +single alternative (<strong>Multiple policy alternatives are not
> +supported</strong>). Then we split that policy as follows into few other
> +policies such that, each policy will contain primitive assertions belonging
> +to only one namespace.</p>
> +<pre> <wsp:Policy> <wsp:Policy> <wsp:Policy> <wsp:Policy>
> + <a:Foo/> <a:Foo/> <b:Foo/> <c:Bar/>
> + <a:Bar/> => <a:Bar/> </wsp:Policy> </wsp:Policy>
> + <b:Foo/> </wsp:Policy>
> + <c:Bar/>
> + </wsp:Policy></pre>
> +
> +<p>Then each policy is given to the appropriate PolicyExtension with an
> +org.w3c.Element type object to which the module can append any other
> +elements/attributes it wishes. Those attributes/elements should resolve to
> +meaningful stub functions via PolicyExtensionTemplate.xsl at latter point of
> +time.</p>
> +
> +<p>For instance depending on the policy, Security module can append
> +<username>, <passwd> elements to the given element as children,
> +which are later resolved into setUsername(..), setPasswd(..), functions of
> +the stub. This way a module can include additional methods to the stub which
> +can be used to get specific parameters to the module. These methods store any
> +user input in the ServiceClient properties
> +(ServiceClient.getOptions().putProperty(...)) which can later be accessed by
> +the module.</p>
> +
> +<h4>Phase 2: At MultiLanguageClientEmitter</h4>
> +
> +<p>Further, effective policies (based on the WSDL) at appropriate levels
> +(service level, operation level) are stored as policy strings in the stub.
> +Few more generic methods are also added to the stub which are used to
> +evaluate/process policies at runtime.</p>
> +
> +<h4>Phase 3: Runtime</h4>
> +
> +<p>When a new stub object is created, the policy strings in the stub are
> +converted into policy objects and merged together to get the effective
> +policies of each operation. These effective policies are stored in
> +appropriate AxisOperation objects which a module can access at later point of
> +time.</p>
> +
> +<p>Then based on its policy each AxisOperation is engaged to a set of
> +modules.</p>
> +
> +<p>When the stub method is invoked, those modules which are engaged to that
> +AxisOperation, access the effective policy for that operation via
> +AxisOperation object. It can get other information needed from the
> +MessageContext which get stored by stub methods which the module has added to
> +the stub earlier. The modules are required to loads their configurations
> +according to the effective policy which is set in AxisOperation and
> +properties they get via MessageContext.</p>
> +<a name="server"></a>
> +
> +<h2>Server Side WS-Policy Support</h2>
> +
> +<p>In this current release Axis2 framework uses WS-Commons/Neethi framework
> +to manipulate policy documents. All its description builders store any policy
> +information included in description documents (services.xml, axis2.xml, ..
> +etc) in the appropriate description classes. This information is available at
> +both deployment and run time via these description classes.</p>
> +
> +<p>When generating WSDL dynamically for each service, policy information in
> +the description classes is included. For instance, if you declare a policy in
> +axis2.xml then that policy is reflected in service elements of WSDL of every
> +service. If a policy is declared in a services.xml, it is shown in the
> +service element of WSDL for that particular service.</p>
> +
> +<p>Next step is to use that information to engage and configure required
> +modules and allow the module to make use of this policy information.</p>
> +
> +<p>It is evident that a great deal of work is required to make axis2 a fully
> +fledged ws-policy supported web service infrastructure. But it is encouraging
> +to note that we've taken the first steps towards this goal. We appreciate any
> +suggestions, patches etc you send us in this regard. Keep on
> +contributing...!</p>
> +<a name="resources"></a>
> +
> +<h2>Resources</h2>
> +<ul>
> + <li>Apache Neethi (WS Policy Implementation) official site- <a
> + href="http://ws.apache.org/commons/neethi/index.html"
> + target="_blank">Home Page</a></li>
> + <li>Sanka Samaranayake, March 2006. <a
> + href="http://www.wso2.net/2006/01/web_services_policy_why_what_how"
> + target="_blank">Web services Policy - Why, What & How</a></li>
> + <li><a
> + href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/"
> + target="_blank">WS-commons/policy SVN</a></li>
> + <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf"
> + target="_blank">Web Services Policy Framework (WS-Policy)</a></li>
> +</ul>
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html (added)
> +++ webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,112 @@
> +<html>
> +<head>
> + <meta http-equiv="content-type" content="text/html; charset=UTF-8">
> + <title>Advanced Axis2 Databinding Framework Features</title>
> +</head>
> +
> +<body lang="en">
> +<h1>Advanced Axis2 Databinding Framework Features</h1>
> +
> +<p>The aim of this section is provide an insight into the newly added
> +advanced features of ADB.</p>
> +
> +<h2>Content</h2>
> +<ul>
> + <li><a href="#typeSupport">xsi:type Support</a></li>
> + <li><a href="#helper">Helpergen Mode</a></li>
> + <li><a href="#more">More Stuff on ADB?</a></li>
> +</ul>
> +
> +<h2><a name="typeSupport">xsi:type Support</a></h2>
> +
> +<p>This is implemented by adding a extension maping class. The code that
> +calls the extension mapper is generated inside the deserialization method of
> +the beans and gets active when the xsi:type attribute is present. The
> +following code fragment shows how the generated type mapper looks like</p>
> +<pre> public static java.lang.Object getTypeObject(
> +java.lang.String namespaceURI, java.lang.String typeName,
> +javax.xml.stream.XMLStreamReader reader) throws java.lang.Exception {
> +if ("http://new.webservice.namespace/types".equals(namespaceURI) && "derivedType2".equals(typeName)) {
> + return namespace.webservice._new.types.DerivedType2Helper.parse(reader);
> +}
> +
> +......
> +
> + return namespace.webservice._new.types.BaseTypeHelper.parse(reader);
> +} else if ("http://new.webservice.namespace/types".equals(namespaceURI) && "derivedType1".equals(typeName)) {
> + return namespace.webservice._new.types.DerivedType1Helper.parse(reader);
> +}
> +
> +throw new java.lang.RuntimeException("Unsupported type " +
> + namespaceURI + " " + typeName);
> +
> +}</pre>
> +
> +<p>Inside every deserialize method, the extension mapper gets called when a
> +xsi:type attribute is encountered <strong>and</strong> that type is not the
> +type that is being parsed</p>
> +
> +<p>The following code fragment shows how the ADB deserialize method calls the
> +mapper class</p>
> +<pre>if (reader.getAttributeValue(
> + "http://www.w3.org/2001/XMLSchema-instance", "type") != null) {
> + java.lang.String fullTypeName = reader.getAttributeValue("http://www.w3.org/2001/XMLSchema-instance",
> + "type");
> + if (fullTypeName != null) {
> + java.lang.String nsPrefix = fullTypeName.substring(0,fullTypeName.indexOf(":"));
> + nsPrefix = (nsPrefix == null) ? "" : nsPrefix;
> + java.lang.String type = fullTypeName.substring(fullTypeName.indexOf(":") + 1);
> + if (!"derivedType2".equals(type)) {
> + //find namespace for the prefix
> + java.lang.String nsUri = reader.getNamespaceContext().getNamespaceURI(nsPrefix);
> + <strong>return (DerivedType2) namespace.webservice._new.types.ExtensionMapper.getTypeObject(nsUri,
> + type, reader);</strong>
> + }
> + }
> +}</pre>
> +
> +<p>This should make the xsi:type based deserialization possible and should
> +result in proper xsi:type based serializations at runtime</p>
> +
> +<p>This is automatically done but the package name for the mapper class can
> +be controlled by using the <strong>mp</strong> flag (with a preceding -E)</p>
> +<pre> WSDL2Code -uri .... -Emp org.example.web.map</pre>
> +
> +<p>When the mapping package is not specified it is derived from the
> +targetnamespace of the first schema that is encountered</p>
> +
> +<h2><a name="helper">Helper mode</a></h2>
> +
> +<p>Helper mode is a fairly new feature. In the helper mode, the beans are
> +plain Java beans and all the deserialization/serialization code is moved to a
> +helper class. For example the simple schema mentioned in the ADB-howto
> +document will yield four classes for the two that has been previously seen</p>
> +<ol>
> + <li>MyElement.java</li>
> + <li>MyElementHelper.java</li>
> + <li>SOAPStruct.java</li>
> + <li>SOAPStructHelper.java</li>
> +</ol>
> +
> +<p>The helpers basically contain all the code that went into the ADBBeans.
> +Hence the beans in the helper mode are pretty much readable than the rest.
> +Also note that the helper mode is available only if you are in the unpacked
> +mode. The code generator by default does not expand the classes</p>
> +
> +<p>Helper mode can be switched on by the <strong>h</strong> flag (Passed with
> +a -E infront to indicate that it is an extra switch undertood by ADB). Also
> +the <strong>-u</strong> flag should be present to indicate the unpacking</p>
> +<pre> WSDL2Code -uri .... -u -Eh</pre>
> +
> +<h2><a name="more">More Stuff on ADB?</a></h2>
> +<ul>
> + <li><a href="adb-tweaking.html">Tweaking the ADB Code Generator</a>-
> + explains available mechanisms to extend ADB and possibly adopt it to
> + compile schemas to support other languages.</li>
> + <li><a href="adb-codegen-integration.html">ADB and Axis2 Integration</a> -
> + explains how the ADB schema compiler was attached to the Axis2
> + framework</li>
> +</ul>
> +<hr>
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html (added)
> +++ webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,93 @@
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
>
> + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
>
> +<html xmlns="http://www.w3.org/1999/xhtml">
>
> +<head>
>
> +<title>ADB Integration With Axis2</title>
>
> +</head>
>
> +<body>
>
> +<h1>ADB Integration With Axis2</h1>
>
> +<p>This document will assist you to write an extension using the
>
> +integrator in order to integrate ADB with Axis2.</p>
>
> +<h2>Content</h2>
>
> +<ul>
>
> +<li><a href="#intro">Introduction</a></li>
>
> +<li><a href="#select_modes">Selection of Generation Modes for
>
> +ADB</a></li>
>
> +<li><a href="#remember">Things to Remember</a></li>
>
> +</ul>
>
> +<h2><a name="intro" id="intro">Introduction</a></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>
>
> +<a name="select_modes" id="select_modes"></a>
>
> +<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 <a href=
>
> +"adb-howto.html" target="_blank">ADB-How to document</a> for the
>
> +different generation modes and their descriptions.</p>
>
> +<table border="1">
>
> +<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>
>
> +<tr>
>
> +<td>-u (unwrap classes)</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 in the command line (prefixed with
>
> +-E)</p>
>
> +<table border="1">
>
> +<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>Note that these parameters have no relevant long names and MUST
>
> +be prefixed with a -E to be processed by the code generator. For
>
> +example</p>
>
> +<pre>
>
> +WSDL2Java .... -Er true
>
> +</pre>
>
> +<a name="remember" id="remember"></a>
>
> +<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
>
> +). In the most recent release, the default has been set as ADB and
>
> +hence if the -d option is missing then the databinding framework
>
> +will be ADB.</li>
>
> +</ol>
>
> +<hr />
>
> +</body>
>
> +</html>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
> For additional commands, e-mail: axis-cvs-help@ws.apache.org
>
>
--
http://webservices.apache.org/~thilina/
http://thilinag.blogspot.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org
Re: svn commit: r453167 [1/6] - in /webservices/axis2/trunk/java/xdocs: ./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ resources/ resources/schemas/
Posted by Thilina Gunarathne <cs...@gmail.com>.
Please use svn move... Deleting and adding kills the history..
~Thilina
On 10/5/06, chatra@apache.org <ch...@apache.org> wrote:
> Author: chatra
> Date: Thu Oct 5 02:56:34 2006
> New Revision: 453167
>
> URL: http://svn.apache.org/viewvc?view=rev&rev=453167
> Log:
> moving all files in 1_1 dir one level up in to the xdocs root
>
> Added:
> webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html
> webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
> webservices/axis2/trunk/java/xdocs/WS_policy.html
> webservices/axis2/trunk/java/xdocs/adb/
> webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html
> webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html
> webservices/axis2/trunk/java/xdocs/adb/adb-howto.html
> webservices/axis2/trunk/java/xdocs/adb/adb-tweaking.html
> webservices/axis2/trunk/java/xdocs/adb/images/
> webservices/axis2/trunk/java/xdocs/adb/images/ADB.jpg (with props)
> webservices/axis2/trunk/java/xdocs/axis2config.html
> webservices/axis2/trunk/java/xdocs/http-transport.html
> webservices/axis2/trunk/java/xdocs/images/Architecture.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/AxisService.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/Component.png (with props)
> webservices/axis2/trunk/java/xdocs/images/OM001.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM002.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/OM003.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/OM004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/OM005.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM006.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM007.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM008.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/OM1.png (with props)
> webservices/axis2/trunk/java/xdocs/images/ServerSideFault.png (with props)
> webservices/axis2/trunk/java/xdocs/images/ServiceDesc.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/TotalArch.png (with props)
> webservices/axis2/trunk/java/xdocs/images/WomBuilder.png (with props)
> webservices/axis2/trunk/java/xdocs/images/activate.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/admin.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/adminlogin.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/adminmain.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/ant.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/
> webservices/axis2/trunk/java/xdocs/images/archi-guide/CodegenArchitecture-new.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/CodegenArchitecture.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/all.png (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/big-picture.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/contexts.png (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/phases.png (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/soap-processing.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi-guide/soap.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi001.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi002.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi003.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi005.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi006.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi007.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi008.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi009.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi010.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi011.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi012.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi013.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/archi014.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi015.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi016.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi017.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi018.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi019.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi020.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi021.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi022.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi023.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi024.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi025.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/archi026.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/arrow_left.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/arrow_right.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/axis.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/ayncresult.png (with props)
> webservices/axis2/trunk/java/xdocs/images/call.png (with props)
> webservices/axis2/trunk/java/xdocs/images/callback.png (with props)
> webservices/axis2/trunk/java/xdocs/images/cases.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clientAPi.png (with props)
> webservices/axis2/trunk/java/xdocs/images/clientside.png (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image002.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image006.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image008.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image010.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image012.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image014.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image016.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image018.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image020.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image022.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image024.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/clip_image026.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/codegen.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/correlator.png (with props)
> webservices/axis2/trunk/java/xdocs/images/deploymetncomponent.png (with props)
> webservices/axis2/trunk/java/xdocs/images/editserviecpara.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/engine1.png (with props)
> webservices/axis2/trunk/java/xdocs/images/faultmsg.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/faultservice.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/globalchain.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/happyaxis.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image001.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image002.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image003.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image004.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image005.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/image005.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image006.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image007.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image008.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image009.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image010.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image011.png (with props)
> webservices/axis2/trunk/java/xdocs/images/image012.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/image013.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/inactivate.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/maven.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/module.png (with props)
> webservices/axis2/trunk/java/xdocs/images/moduleengage.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/modules.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/new.gif (with props)
> webservices/axis2/trunk/java/xdocs/images/om2.png (with props)
> webservices/axis2/trunk/java/xdocs/images/om3.png (with props)
> webservices/axis2/trunk/java/xdocs/images/parameters.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/select_service_for_handler.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/send.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendAsync.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendRecievce.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendRecieveAsync.png (with props)
> webservices/axis2/trunk/java/xdocs/images/sendRecieveWithListnere.png (with props)
> webservices/axis2/trunk/java/xdocs/images/serverSide.png (with props)
> webservices/axis2/trunk/java/xdocs/images/service.png (with props)
> webservices/axis2/trunk/java/xdocs/images/serviceHandlers.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/servicegroups.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/
> webservices/axis2/trunk/java/xdocs/images/userguide/DirectoryStructure.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/ModuleView.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/MyServiceDeployed.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/ServiceDeployed.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/ServiceItems.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/TestClient.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/userguide/http-get-ws.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/viewphases.jpg (with props)
> webservices/axis2/trunk/java/xdocs/images/wom.png (with props)
> webservices/axis2/trunk/java/xdocs/index_docs.html
> webservices/axis2/trunk/java/xdocs/installationguide.html
> webservices/axis2/trunk/java/xdocs/jibx/
> webservices/axis2/trunk/java/xdocs/jibx/jibx-codegen-integration.html
> webservices/axis2/trunk/java/xdocs/jms-transport.html
> webservices/axis2/trunk/java/xdocs/mail-configuration.html
> webservices/axis2/trunk/java/xdocs/mail-transport.html
> webservices/axis2/trunk/java/xdocs/migration.html
> webservices/axis2/trunk/java/xdocs/mtom-guide.html
> webservices/axis2/trunk/java/xdocs/resources/
> webservices/axis2/trunk/java/xdocs/resources/schemas/
> webservices/axis2/trunk/java/xdocs/resources/schemas/module.xsd
> webservices/axis2/trunk/java/xdocs/resources/schemas/services.xsd
> webservices/axis2/trunk/java/xdocs/rest-ws.html
> webservices/axis2/trunk/java/xdocs/soapmonitor-module.html
> webservices/axis2/trunk/java/xdocs/spring.html
> webservices/axis2/trunk/java/xdocs/tcp-transport.html
> webservices/axis2/trunk/java/xdocs/transport_howto.html
> webservices/axis2/trunk/java/xdocs/userguide.html
> webservices/axis2/trunk/java/xdocs/webadminguide.html
>
> Added: webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html (added)
> +++ webservices/axis2/trunk/java/xdocs/Axis2-rpc-support.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,266 @@
> +<?xml version="1.0" encoding=""?>
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
> + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
> +<html xmlns="http://www.w3.org/1999/xhtml">
> +<head>
> + <meta http-equiv="content-type" content="" />
> + <title>Axis2 RPC Support</title>
> +</head>
> +
> +<body>
> +<h1>Axis2 RPC Support</h1>
> +
> +<p>This documents talks about the Axis2's Remote Procedure Calls support in a
> +set of easy to understand implementation steps.</p>
> +
> +<h2>Introduction</h2>
> +
> +<p>Axis2 Remote Procedure Calls (RPC) support may seem somewhat tricky and
> +confusing at first glance. However, Axis2 RPC strategy is based on a well
> +defined set of rules and once the details are in place, it becomes clear as
> +day. This document aims to drill down to the details of this strategy and
> +fills up most of the fairly unknown bits and pieces. Note that Axis2
> +currently does not support the rpc/encoded style fully. It's 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> .....
> + < message name="requestMessage">
> + <part name="part1" type="xs:string"/>
> + <part name="part2" type="xs:int"/>
> + </message>
> + <message name="responseMessage">
> + <part name="part1" type="xs:string"/>
> + </message>
> + <portType name="echoPortType">
> + <operation name="echo">
> + <input message="y:requestMessage"/>
> + <output message="y:responseMessage"/>
> + </operation>
> + </portType>
> + <binding name="echoBinding" type="y:echoPortType">
> + <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
> + <operation name="echo">
> + <soap:operation soapAction="echo"/>
> + <input>
> + <soap:body use="literal"/>
> + </input>
> + <output>
> + <soap:body use="literal"/>
> + </output>
> + </operation>
> + </binding>
> +.....</pre>
> +
> +<p>The binding says its got to be rpc/lit and in this case the message parts
> +need wrapping in the following order.</p>
> +<ol>
> + <li>The first element needs to have the operation name as the local name
> + and the operation namespace (which 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>
> +
> +<p>For example the input wire message for the echo operation mentioned in the
> +above WSDL fragment would look like this:</p>
> +<pre> <op:<strong>echo</strong> xmlns:op="porttype namespace">
> + <<strong>part1</strong>>Hello World</part1>
> + <<strong>part2</strong>>123</part2>
> + </op:echo></pre>
> +
> +<p>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 quite
> +possible to generate a schema, representing this structure and then treat the
> +whole service as pure doc/lit service. In this case, following is the piece
> +of schema generated to make this rpc to doc conversion. Note that in this
> +case the wire message stays unchanged. It is only a different WSDL authoring
> +style</p>
> +<pre> <xs:element name="echo">
> + <xs:complexType>
> + <xs:sequence>
> + <xs:element name="part1" type="xs:string" />
> + <xs:element name="part2" type="xs:int" />
> + </xs:sequence>
> + </xs:complexType>
> + </xs:element></pre>
> +
> +<p>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!</p>
> +
> +<h2>Step 2 - Unwrapping the Schema</h2>
> +
> +<p>If the schema needs to be unwrapped then that brings up a few issues
> +mainly because the only thing that the emitters rely on when generating code
> +is a mapping table!</p>
> +<ol>
> + <li>When the schema is unwrapped where would that unwrapping information
> + stay?
> + <p>Good question - It needs to be a store that keeps the information
> + seperated. Hmm.. What can we use here ? Why of course, the Axis *
> + hierarchy! It has nicely separated information holders and a parameter
> + store that can hold a information bean.</p>
> + </li>
> + <li>How do we maintain uniqueness among message part names?
> + <p>Another Good question - part names are only unique across a message
> + and not globally. But 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</p>
> + </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. What it does is to walk 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>< element >
> + < complexType >
> + < sequence >
> + < element />
> + < /sequence >
> + < /complexType >
> + < /element >
> + </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><input>
> + <param name="param4" type="com.example.www.ServiceNameStub.Echo" shorttype="Echo" value="null" location="body" opname="echo">
> + <param name="param5" type="java.lang.String" shorttype="String" value="null" location="body" opname="echo" partname="Part1"
> + primitive="yes"/>
> + <param name="param6" type="int" shorttype="int" value="0" location="body" opname="echo" partname="Part2" primitive="yes"/>
> + </param>
> +</input></pre>
> +
> +<p>The next part is upto the template to handle. 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 a sort of 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 />
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html (added)
> +++ webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,735 @@
> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
> +<html>
> +<head>
> + <meta http-equiv="content-type" content="">
> + <title>Axis2 Architecture Guide</title>
> + <meta content="20050916;22455288">
> +</head>
> +
> +<body lang="en-US" dir="ltr">
> +<h1 align="center">Apache Axis2 Architecture Guide</h1>
> +
> +<p>This document will give an introduction to Axis2's modular architecture
> +with explanations on every module.</p>
> +
> +<p><i>Send your feedback to: <a
> +href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
> +subject with [Axis2]. To subscribe to mailing list see <a
> +href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
> +
> +<h2>Contents</h2>
> +<ul>
> + <li><a href="#bmBP">The Big Picture</a></li>
> + <li><p><a href="#requirements">Requirement of Axis2</a></p>
> + </li>
> + <li><a href="#thearchi">Axis2 Architecture</a>
> + <ul>
> + <li><p><a href="#bmcore">Core Modules</a></p>
> + </li>
> + <li><a href="#bmother">Other Modules</a></li>
> + <li><p><a href="#bmInfoMod">Information Model</a></p>
> + </li>
> + <li><a href="#bmXML">XML Processing Model</a></li>
> + <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
> + <ul>
> + <li><a href="#default">Axis2 Default Processing Model</a></li>
> + <li><p><a href="#incomingsoap">Processing an Incoming SOAP
> + Message</a></p>
> + </li>
> + <li><a></a><a href="#outgoing">Processing of the Outgoing
> + Message</a></li>
> + <li><p><a href="#extending">Extending SOAP Processing Model</a></p>
> + <ul>
> + <li><a href="#extendingwithhandlers">Extending the SOAP
> + Processing Model with Handlers</a></li>
> + <li><p><a href="#extendingwithmodules">Extending the SOAP
> + Processing Model with Modules</a></p>
> + </li>
> + </ul>
> + </li>
> + </ul>
> + </li>
> + <li><a href="#bmDeployment">Deployment</a>
> + <ul>
> + <li><a href="#xmlfile">The <em>axis2.xml</em> file</a></li>
> + <li><p><a href="#servicearchive">Service Archive</a></p>
> + </li>
> + <li><a href="#modulearchive">Module Archive</a></li>
> + </ul>
> + </li>
> + <li><p><a href="#bmClientAPI">Client API</a></p>
> + <ul>
> + <li><a href="#oneway">One Way Messaging Support</a></li>
> + <li><p><a href="#requestresponse">Request Response Messaging
> + Support</a></p>
> + </li>
> + </ul>
> + </li>
> + <li><a href="#bmTransports">Transports</a></li>
> + <li><p><a href="#bmWSDL">Code generation</a></p>
> + </li>
> + <li><a href="#bmDB">Data Binding</a>
> + <ul>
> + <li><a href="#integration">Integration with Code Generation
> + Engine</a></li>
> + <li><p><a href="#serial">Serialization and De-Serialization</a></p>
> + </li>
> + </ul>
> + </li>
> + </ul>
> + </li>
> +</ul>
> +
> +<h2><a name="bmBP">The Big Picture</a></h2>
> +
> +<p>A new architecture for Axis was introduced during the August 2004 Summit
> +in Colombo, Sri Lanka. This new architecture Axis2 is based on 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.</p>
> +
> +<p>Any architecture is a result of what that architecture should yield. The
> +success of an architecture should be evaluated based on the requirements
> +expected to be met by that architecture. Let us start our journey into Axis2
> +by looking at the requirements.</p>
> +<a name="requirements"></a>
> +
> +<h2>Requirement of Axis2</h2>
> +
> +<p>In the SOAP terminology, a participant who is taking part in a Web service
> +interaction is known as a SOAP Node. Delivery of a single SOAP Message is
> +defined based on two participants, SOAP Sender and SOAP Receiver. Each SOAP
> +Message is sent by SOAP Sender and received by SOAP Receiver. A single SOAP
> +delivery is the most basic unit that builds the Web service interaction.</p>
> +
> +<p>Each SOAP Node may be written in specific programming language, may it be
> +Java, C++, .NET or Perl, the Web services allow them to inter operate. This
> +is possible because on the wire each Web service interaction is done via
> +SOAP, which is common to every SOAP Node.</p>
> +
> +<p><img alt="" src="images/archi-guide/soap.gif" name="Graphic1"
> +align="bottom" width="691" height="319" border="0"></p>
> +
> +<p>Web service middleware handles the complexity in SOAP messaging and lets
> +the users work with the programming language they are accustomed to. Axis2
> +allows java users to invoke Web services using java representations, and
> +handles the SOAP messaging behind the curtain.</p>
> +
> +<p>Axis2 handles SOAP processing along with numerous other tasks. This makes
> +the life of the Web service developer a whole lot easier. Following are the
> +identified requirements:</p>
> +<ol>
> + <li>Provide a framework to process the SOAP messages. The framework should
> + be extensible and the users should be able to extend the SOAP processing
> + per service or per operation basis. Furthermore it should be able to
> + model different Message Exchange Patterns (MEPs) using the processing
> + framework.</li>
> + <li>Ability to deploy a Web service (with or without WSDL)</li>
> + <li>Provide a Client API that can be used to invoke Web services. This API
> + should support both the Synchronous and Asynchronous programming
> + models.</li>
> + <li>Ability to configure Axis2 and it's components via deployment.</li>
> + <li>Ability to send and receive SOAP messages with different
> + transports.</li>
> +</ol>
> +
> +<p>Apart from the above functionalities, performance in terms of memory and
> +speed is a major consideration for Axis2. Axis2 Core Architecture is built on
> +three specifications- WSDL, SOAP and WS-Addressing. Other specifications like
> +JAX-RP, SAAJ & WS-Policy are layered on top of the Core Architecture.</p>
> +
> +<h2><a name="thearchi">Axis2 Architecture</a></h2>
> +Axis2 architecture lays out some principals to preserve the uniformity. They
> +are as follows:
> +<ul>
> + <li><p>Axis2 architecture separates the logic and the states. Code that
> + does the processing is stateless inside Axis2. This allows code to be
> + executed freely by parallel threads.</p>
> + </li>
> + <li>All the information is kept in one information model allowing system to
> + be suspended and resumed.</li>
> +</ul>
> +
> +<p>Axis2 architecture is modular. Therefore Axis2 Framework is built up of
> +core modules which collectively make up the core architecture of Axis2, and
> +non-core/other modules are layered on top of this core
> +modules/architecture.</p>
> +<a name="bmother"></a>
> +
> +<h3>Core Modules:</h3>
> +<ul>
> + <li><a href="#bmInfoMod">Information Model</a>- Axis2 defines a model to
> + handle information and all states are kept in this model. The model has a
> + hierarchy for the information. The system manages the life cycle of the
> + objects in this hierarchy.</li>
> + <li><p><a href="#bmXML">XML processing Model</a>- Handling the SOAP Message
> + is the most important and most complex task. The efficiency of this is
> + the single most important factor that decides the performance. It makes
> + sense to delegate this task to a separate sub-project itself, under Web
> + service project, allowing that sub-project (AXIOM) to provide a simple
> + API for SOAP and XML info-set while hiding the complexities of the
> + efficient XML processing within the implementation.</p>
> + </li>
> + <li><a href="#bmSOAPPM">SOAP Processing Model</a>- This controls the
> + execution of the processing. The model defines different phases the
> + execution would walk through, and the user can extend the Processing
> + Model at some specific places.</li>
> + <li><p><a href="#bmDeployment">Deployment Model</a>- Axis2 deployment model
> + allows the user to deploy services, configure the transports, extend the
> + SOAP Processing model per system, service or operation basis.</p>
> + </li>
> + <li><a href="#bmClientAPI">Client API</a>- This provides a convenient API
> + for users to communicate with Web services using Axis2. There are set of
> + classes to interact with IN-OUT and IN-Only style Message Exchange
> + Patterns (MEPs) where those can be used to construct any other MEP.</li>
> + <li><p><a href="#bmTransports">Transports</a>- Axis2 define a transport
> + framework that enables the user to use different transports. The
> + transports fit into specific places in the SOAP processing model. The
> + implementation provides a few common transports and the user may write
> + new ones if and when it is needed.</p>
> + </li>
> +</ul>
> +<a name="bmcore"></a>
> +
> +<h3>Other Modules:</h3>
> +<ul>
> + <li><a href="#bmWSDL">Code Generation</a>- Axis2 provides a code generation
> + tool that will generate server side and client side code along with a
> + test case. The generated code would simplify the service deployment and
> + the service invocation. This would increase usability of Axis2.</li>
> + <li><p><a href="#bmDB">Data Binding</a>- The basic client API of Axis2 lets
> + the users process SOAP at the infoset level where as data binding extends
> + it to make it more convenient to the users by encapsulating the infoset
> + layer and providing a programming language specific interface.</p>
> + </li>
> +</ul>
> +<map name="Graphic2Map" id="g2m">
> + <area shape="rect" coords="123,31,222,97" href="#bmInfoMod" alt="">
> + <area shape="rect" coords="239,62,319,134" href="#bmXML" alt="">
> + <area shape="rect" coords="127,112,218,177" href="#bmSOAPPM" alt="">
> + <area shape="rect" coords="12,39,89,95" href="#bmDeployment" alt="">
> + <area shape="rect" coords="0,108,94,156" href="#bmWSDL" alt="">
> + <area shape="rect" coords="350,31,426,86" href="#bmClientAPI" alt="">
> + <area shape="rect" coords="350,114,421,164" href="#bmTransports" alt="">
> +</map>
> +
> +<p><img src="images/archi-guide/all.png" name="Graphic2" width="426" alt=""
> +height="189" border="0" align="bottom" usemap="#Graphic2Map"></p>
> +
> +<h2><a name="bmInfoMod">Information Model</a></h2>
> +
> +<p>Information Model has two main hierarchies-Contexts and Descriptions. This
> +model is described in UML notations below.</p>
> +
> +<p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom"
> +alt="" width="400" height="443" border="0"></p>
> +
> +<p>( A ----<> B says, B has 1 or more objects of A. A------>B says,
> +the given relationship holds between A and B.)</p>
> +
> +<p>The two hierarchies are connected as shown in the above figure. The
> +Description hierarchy represents the static data. This data may be loaded
> +from a configuration file that exists throughout the lifetime of Axis2. For
> +example, deployed Web services, operations, etc. On the other hand, the
> +context hierarchy holds more dynamic information about the things that have
> +more than one instances (e.g.Message Context).</p>
> +
> +<p>These two hierarchies creates a model that provides the ability to search
> +for key value pairs. When the values are searched at a given level, they are
> +searched while moving up the hierarchy until a match is found. In the
> +resulting model the lower levels override the values in the upper levels. For
> +example, when a value is looked up in the Message Context and is not found,
> +it would be looked up in the Operation Context etc, up the hierarchy. The
> +Search is first done up the hierarchy, and if starting point is a Context
> +then it is search in the Description hierarchy as well.</p>
> +
> +<p>This allows the user to declare and override values. Result being a very
> +flexible configuration model. The flexibility could be the <em>Achilles</em>
> +heel for the system as the search is expensive, specially for something that
> +does not exist. Yet in the final analysis developers believe that the
> +flexibility would serve better in this instant.</p>
> +
> +<table width="955" border="1" cellpadding="2" cellspacing="3">
> + <col width="112"><col width="371"><col width="103"><col width="336"><tbody>
> + <tr>
> + <td><strong>Context</strong></td>
> + <td><strong>Description</strong></td>
> + <td><strong>Configuration</strong></td>
> + <td><strong>Description</strong></td>
> + </tr>
> + <tr>
> + <td width="112"><p>Configuration Context</p>
> + </td>
> + <td width="371"><p>Holds the run time status. A deep copy of this would
> + essentially make a copy of Axis2.</p>
> + </td>
> + <td width="103"><p>Axis Configuration</p>
> + </td>
> + <td width="336"><p>Holds all global configurations. Transports, global
> + modules, parameters and services etc.</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><p>Service Group Context</p>
> + </td>
> + <td width="371"><p>Holds information about a particular usage of the
> + respective service group. The life of a Service Group Context starts
> + when a user starts interacting with a service that belong to this
> + service group. This can be used to share information between services
> + (within the same service group) in a single interaction.</p>
> + </td>
> + <td width="103"><p>AxisServiceGroup</p>
> + </td>
> + <td width="336"><p>Holds deployment time information about a particular
> + service group.</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><p>Service Context</p>
> + </td>
> + <td width="371"><p>This context is available throughout the usage of
> + the respective service. This can be used to share information between
> + several MEPs of the same service, within a single interaction.</p>
> + </td>
> + <td width="103"><p>AxisService</p>
> + </td>
> + <td width="336"><p>Hold the Operations and the service level
> + configurations</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><p>Operation Context</p>
> + </td>
> + <td width="371"><p>Holds the information about the current MEP
> + instance, maintain the Messages in the current MEP etc.</p>
> + </td>
> + <td width="103"><p>AxisOperation</p>
> + </td>
> + <td width="336"><p>Holds the operation level configurations</p>
> + </td>
> + </tr>
> + <tr>
> + <td width="112"><a name="messageContext"></a>
> +
> + <p>Message Context</p>
> + </td>
> + <td width="371"><p>Holds all the information about the Message
> + currently being executed.</p>
> + </td>
> + <td width="103"><p>AxisMessage</p>
> + </td>
> + <td width="336"><p>Do not hold any information as yet, but can be used
> + as a future extension point.</p>
> + </td>
> + </tr>
> + </tbody>
> +</table>
> +<a name="bmXML"></a>
> +
> +<h2>XML Processing Model</h2>
> +
> +<p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p>
> +
> +<h2><a name="bmSOAPPM">SOAP Processing Model</a></h2>
> +
> +<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" alt=""
> +align="bottom" width="755" height="348" border="0"></p>
> +
> +<p>The architecture identified two basic actions a SOAP processor should
> +perform, sending and receiving SOAP messages. The architecture provides two
> +Pipes ('Flows'), to perform these two basic actions. Axis Engine or the
> +driver of Axis2 defines two methods send() and receive() to implement these
> +two Pipes. The two pipes are named <i><b>In</b> Pipe</i> and <i><b>Out</b>
> +Pipe</i>, and the complex Message Exchange Patterns (MEPs) are constructed by
> +combining these two pipes.</p>
> +
> +<p>Extensibility of the SOAP processing model is provided through handlers.
> +When a SOAP message is being processed the handlers that are registered would
> +be executed. The handlers can be registered in global, service, or operation
> +scopes and the final handler chain is calculated combining the handlers from
> +all the scopes.</p>
> +
> +<p>The handlers act as interceptors and they process parts of the SOAP
> +message and provide add-on services. Usually handlers work on the SOAP
> +headers, yet they may access or change the SOAP Body as well.</p>
> +
> +<p>When a SOAP message is being sent through the Client API, an <i>Out
> +Pipe</i> would begin, the <i>Out Pipe</i> invokes the handlers and end with a
> +Transport Sender that sends the SOAP message to the target endpoint. The SOAP
> +message is received by a Transport Receiver at the target endpoint, which
> +reads the SOAP message and starts the <i>In Pipe</i>. The <em>In Pipe</em>
> +consists of handlers and ends with the <a href="#mr">Message Receiver</a>,
> +which consumes the SOAP message.</p>
> +
> +<p>Above explained processing happens for each and every SOAP message
> +exchanged. After processing one message Axis2 may decide to create other SOAP
> +messages, in which case more complex message patterns emerge. However Axis2
> +always view the SOAP message in terms of processing a single message. The
> +combination of the messages are layered on top of that basic framework.</p>
> +
> +<p>The two pipes does not differentiate between the Server and the Client.
> +The SOAP Processing Model handles the complexity and provides two abstract
> +pipes to the user. The different areas or the stages of the pipes are given
> +names, and according to the Axis2 slang those are named 'phases'. A Handler
> +always runs inside a phase, and the phase provides a mechanism to specify the
> +ordering of handlers. Both Pipes have built in phases, and both define the
> +areas for 'User Phases' which can be defined by the user.</p>
> +
> +<h3><a name="default">Axis2 Default Processing Model</a></h3>
> +
> +<p>Axis2 has some inbuilt handlers that run in inbuilt phases and they create
> +the default configuration for the Axis2. We will be looking more in to how to
> +extend the default processing Model in the next section.</p>
> +There are four special handlers defined in Axis2.
> +<ol>
> + <li>Dispatchers - Finds the service and the operation the SOAP message is
> + directed to. Dispatchers always run on the <em>In-Pipe</em> and inside
> + the Dispatch phase. The in-built dispatchers dispatch to a particular
> + operation depending on various conditions like WS-Addressing information,
> + URI information, SOAP action information, etc.,</li>
> +</ol>
> +<ul>
> + <li><a name="mr">Message Receiver - Consume the SOAP Message and hands that
> + over to application , Message receiver is the last handler of the
> + in-pipe</a></li>
> + <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
> + message is destined to. Always runs as last handler in the out-pipe</p>
> + </li>
> +</ul>
> +
> +<h3><a name="incomingsoap">Processing an Incoming SOAP Message</a></h3>
> +
> +<p>Incoming SOAP Message is always received by a Transport Receiver waiting
> +for the SOAP Messages. Once the SOAP Message arrives the transport Headers
> +are parsed and a</p>
> +<a href="#messageContext">Message Context</a> is created from the incoming
> +SOAP Message. Then the <i>In Pipe</i> is executed with the Message Context.
> +
> +<p>Let us see what happens at each phase of the execution. This process may
> +happen either in the server or in the Client.</p>
> +<ol>
> + <li><strong>Transport Phase</strong> - The handlers are in the phase meant
> + to process transport specific information such as validating incoming
> + message by looking at various transport headers, add data into message
> + context etc.</li>
> + <li><strong>Pre-Dispatch Phase</strong>- The main functionality of the
> + handlers in this phase is to populate message context in order to do the
> + dispatching. As an example, processing of addressing headers of the SOAP
> + message happen in this phase.Addressing handlers extract information and
> + put them in to the message context.</li>
> + <li><strong>Dispatch Phase</strong> - The Dispatchers run in this phase and
> + tries to find the correct service and operation this particular message
> + is destined to.<br>
> + The post condition of the dispatch phase (any phase can contain a post
> + condition) checks whether a service and an operation was found by the
> + dispatchers. If not the execution will halt and throws out a "service not
> + found error".</li>
> + <li><strong>User Defined Phases</strong> - Users are allowed to engage
> + their custom handlers here.</li>
> + <li>Message Validation Phase - Once the user level execution has taken
> + place this phase validates whether SOAP Message Processing has taken
> + place correctly.</li>
> + <li><strong>Message Processing Phase</strong> - The Business logic of the
> + SOAP message is executed here. A <a href="#mr">Message Receiver</a> is
> + registered with each Operation. This Message receiver (associated to the
> + particular operation) will executed as the last Handler of this
> + phase.</li>
> +</ol>
> +
> +<p>There may be other handlers in any of these phases. Users may use custom
> +handlers to override the mechanics in each of these phases.</p>
> +
> +<h3><a name="outgoing">Processing of the Outgoing Message</a></h3>
> +
> +<p><em>Out Pipe</em> is simpler because the service and operation to dispatch
> +is known by the time the pipe is executed. The <em>Out Pipe</em> may be
> +initiated by the</p>
> +<a href="#mr">Message Receiver</a> or the Client API implementation.Phases of
> +the <em>Out Pipe</em> are described below:
> +<ol>
> + <li>Message Initialize Phase - First phase of the <em>Out Pipe</em>. Serves
> + as the placeholder for the custom handlers</li>
> + <li>User Phases - This executes handlers in user defined phases</li>
> + <li>Transports Phase - Execute any transport handlers taken from the
> + associated transport configuration. The last handler would be a transport
> + sender which would send the SOAP message to the target endpoint.</li>
> +</ol>
> +
> +<h3><a name="extending">Extending SOAP Processing Model</a></h3>
> +
> +<p>Above we discussed the default processing model of Axis2. Now let us
> +discuss the extension mechanism for the SOAP processing model. After all, the
> +whole effort of making this SOAP engine/processing model was focused much on
> +making it extendable.</p>
> +
> +<p>Idea behind introducing step wise processing of the SOAP message in terms
> +of handlers & phases is to allow easier modification of the processing
> +order. The notion of phases makes it easier to place handlers in between
> +other handlers. This enables modification on the default processing behavior.
> +SOAP Processing Model can be extended with <a
> +href="#extendingwithhandlers">handler</a> or <a
> +href="#extendingwithmodules">modules</a>.</p>
> +<a name="extendingwithhandlers"></a>
> +
> +<h4>Extending the SOAP Processing Model with Handlers</h4>
> +The handlers in a module can specify the phase they need to be placed in.
> +Furthermore they can specify their location inside a phase by providing phase
> +rules. Phase rules will place a handler
> +<ol>
> + <li>as the first handler in a phase.</li>
> + <li>or as the last handler in a phase.</li>
> + <li>or before a given handler</li>
> + <li>or after a given handler</li>
> +</ol>
> +
> +<h4><a name="extendingwithmodules">Extending the SOAP Processing Model with
> +Modules</a></h4>
> +
> +<p>Axis2 defines an entity called a 'module' that can introduce handlers and
> +Web service operations. A Module in terms of Axis2 usually acts as a
> +convenient packaging that includes</p>
> +<ul>
> + <li>a set of handlers and</li>
> + <li>an associated descriptor which includes the phase rules</li>
> +</ul>
> +. Modules have the concept of being 'available' and 'engaged'. 'Availability'
> +means the module is present in the system, but has not been activated, i.e.,
> +the handlers included inside the module have not been used in the processing
> +mechanism. When a module is 'engaged' it becomes active and the handlers get
> +placed in the proper phases. The handlers will act in the same way as
> +explained in the previous section. Usually a module will be used to implement
> +a WS-* functionality such as WS-Addressing.
> +
> +<p>Apart from the extension mechanism based on the handlers, the WS-*
> +specifications may suggest a requirement for adding new operations. For
> +example, once a user add a Reliable Messaging capability to a service, the
> +"Create Sequence" operation needs to be available to the service end point.
> +This can be implemented by letting the modules define the operations. Once
> +the module is engaged to a service, the necessary operations will be added to
> +that service.</p>
> +
> +<p>A service, operations or the system may engage a module. Once the module
> +is engaged the handlers and the operations defined in the module are added to
> +the entity that engaged them.</p>
> +
> +<p>Modules can not be added (no hot deployment) while the Axis2 engine is
> +running, but they will be available once the system is restarted.</p>
> +<a name="bmDeployment"></a>
> +
> +<h2>Deployment</h2>
> +
> +<p>The Deployment Model provides a concrete mechanism to configure Axis2.
> +This model has three entities that provide the configuration.</p>
> +<a name="xmlfile"></a>
> +
> +<h3>The axis2.xml file</h3>
> +
> +<p>This file holds the global configuration for the client and server, and
> +provide following information:</p>
> +<ol>
> + <li>The global parameters</li>
> + <li>Registered transports in and transport outs</li>
> + <li>User defined phase names</li>
> + <li>Modules that are engaged globally (to all services)</li>
> + <li>Globally defined <a href="#mr">Message Receivers</a></li>
> +</ol>
> +<a name="servicearchive"></a>
> +
> +<h3>Service Archive</h3>
> +
> +<p>Service archive must have a <em>META-INF/<a
> +href="resources/schemas/services.xsd">services.xml</a></em> file and may
> +contain the dependent classes. The <em>services.xml</em> file has following
> +information.</p>
> +<ol>
> + <li>Service level parameters</li>
> + <li>Modules that are engaged service level</li>
> + <li>Service Specific <a href="#mr">Message Receivers</a></li>
> + <li>Operations inside the service</li>
> +</ol>
> +
> +<h3><a name="modulearchive">Module Archive</a></h3>
> +
> +<p>Module archive must have a META-INF/<a
> +href="resources/schemas/module.xsd">module.xml</a> file and dependent
> +classes. The <em>module.xml</em> file has Module parameters and the
> +Operations defined in the module.</p>
> +
> +<p>When the system is starting up Axis2 ask the deployment model to create a
> +Axis Configuration. Deployment Model first finds the axis2.xml file and build
> +the global configuration. Then it checks for the module archives and then for
> +the service archives. After that the corresponding services and modules are
> +added to the Axis Configuration. System will build contexts on top of the
> +Axis Configurations. After this Axis2 is ready to send or receive the SOAP
> +messages. Hot deployment is only allowed for services.</p>
> +<a name="bmClientAPI"></a>
> +
> +<h2>Client API</h2>
> +
> +<p>There are three parameters that decide the nature of the Web service
> +interaction.</p>
> +<ol>
> + <li>Message Exchange Pattern (MEP)</li>
> + <li>The Behavior of the transport, whether it's One-Way or Two-Way</li>
> + <li>Synchronous/ Asynchronous behavior of the Client API</li>
> +</ol>
> +
> +<p>Variations of the three parameters can result in indefinite number of
> +scenarios, even though Axis2 is built on a core that support any messaging
> +interaction, the developers were compelled to support only two most widely
> +used Message Exchange Patterns (MEPs).</p>
> +
> +<p>Two supported MEPs are One-Way and the In-Out (Request-Response) scenarios
> +in the Client API. The implementation is based on a class called
> +<code>ServiceClient</code> and there are extensions for each MEP that Axis2
> +Client API supports.</p>
> +
> +<h3><a name="oneway">One Way Messaging Support</a></h3>
> +
> +<p>The One-Way support is provided by the <code>fireAndForget</code> method
> +of <code>ServiceClient</code>. For one way invocations one can use HTTP ,
> +SMTP and TCP transports. In the case of the HTTP transport the return channel
> +is not used and the HTTP 202 OK is returned in the return Channel.</p>
> +<a name="requestresponse"></a>
> +
> +<h3>In-Out (Request Response) Messaging Support</h3>
> +
> +<p>The In-Out support is provided by the <code>sendReceive()</code> method in
> +ServiceClient. This provides a much simpler interface for the user. The
> +Client API has four ways to configure a given Message Exchange</p>
> +<ol>
> + <li>Blocking or Non-Blocking nature - this can be decided by using
> + <code>sendReceive()</code> or <code>sendReceiveNonBlocking()</code>
> + methods</li>
> + <li>Sender transport - transport used to send the SOAP Message</li>
> + <li>Listener transport - transport the Response is received</li>
> + <li>Use Separate Channel - determines whether the response is send over a
> + separate transport connection or not. This can be false only when sender
> + and listener transport is same and is a Two-Way transport.</li>
> +</ol>
> +
> +<p>Depending on the values of the above four parameter, Axis2 behave
> +differently.</p>
> +<a name="bmTransports"></a>
> +
> +<h2>Transports</h2>
> +
> +<p>Axis2 has two basic constructs for transports, namely; Transport Senders
> +and Transport Receivers . These are accessed via the AxisConfiguration.</p>
> +
> +<p>The incoming transport is the transport via which the AxisEngine receives
> +the message. The outgoing transport is decided based on the addressing
> +information (wsa:ReplyTo and wsa:FaultTo). If addressing information is not
> +available and if server is trying to respond, then the out going transport
> +will be the outputstream of the incoming transport (if it is two-way
> +transport).</p>
> +
> +<p>At the client side the user is free to specify the transport to be
> +used.</p>
> +
> +<p>Transport Senders and Transport Receivers contains following
> +information.</p>
> +<ol>
> + <li>Transport Sender for Out Configuration</li>
> + <li>Transport Listener for In Configuration</li>
> + <li>Parameters of the transport</li>
> +</ol>
> +
> +<p>Each and every transport out configuration defines a transport sender.
> +Transport sender sends the SOAP message, depending on its configuration.</p>
> +
> +<p>Transport receiver waits for the SOAP Messages and for each SOAP Message
> +that arrives, it uses the <i>In Pipe</i> to process the SOAP Message.</p>
> +
> +<p>Axis2 Presently support the following transports:</p>
> +<ol>
> + <li>HTTP - In HTTP transport the transport listener is a servlet or
> + org.apache.axis2.transport.http.SimpleHTTPServer provided by Axis2. The
> + transport sender uses commons-httpclient to connect and send the SOAP
> + Message.</li>
> + <li>TCP - This is the most simplest transport, but needs the WS -
> + Addressing support to be functional.</li>
> + <li>SMTP - This works off a single email account. Transport receiver is a
> + thread that checks for emails in fixed time intervals.</li>
> + <li>JMS</li>
> +</ol>
> +<a name="bmWSDL" id="bmWSDL"></a>
> +
> +<h2>Code Generation</h2>
> +
> +<p>Although the basic objective of the code generation tools has not changed,
> +the code generation module of Axis2 has taken a different approach to
> +generate code. Primarily the change is in the use of templates, namely XSL
> +templates which gives the code generator the flexibility to generate code in
> +multiple languages.</p>
> +
> +<p>The basic approach is to set the code generator to generate an XML and
> +parse it with a template to generate the code file. The following figure
> +describes how this shows up in the architecture of the tool.</p>
> +
> +<p><img src="images/archi-guide/CodegenArchitecture-new.gif" name="Graphic6"
> +alt="" align="bottom" border="0"></p>
> +
> +<p>The fact here is that it is the same information that is extracted from
> +the WSDL no matter what code is generated. First, an AxisService is populated
> +from a WSDL. Then the code generator extracts information from the
> +AxisService and creates an XML which is language independent. This emitted
> +XML is then parsed with the relevant XSL to generate code for the relevant
> +language. No matter what the output language, the process is the same except
> +for the template that is being used.</p>
> +
> +<h2><a name="bmDB" id="bmDB">Data Binding</a></h2>
> +
> +<h3>Integration with Code Generation Engine</h3>
> +
> +<p>Databinding for Axis2 is implemented in an interesting manner. Databinding
> +has not been included in the core deliberately and hence the code geneation
> +allows different data binding frameworks to be plugged in. This is done
> +through an extension mechanism where the codegen engine calls extensions
> +first and then executes the core emitter. The extensions populate a map of
> +QNames vs. class names that is passed to the code generator on which the
> +emitter operates on.</p>
> +
> +<p><strong>The following diagram shows the structure:</strong></p>
> +
> +<p><img src="images/codegen.gif" name="Graphic7" align="bottom"
> +border="0"></p>
> +
> +<p><strong>The following databinding extensions are available:</strong></p>
> +<ol>
> + <li><strong>ADB</strong> - ADB (Axis Data Binding ) is a simple framework
> + that allows simple schemas to be compiled. It is lightweight and simple,
> + works off StAX and fairly performant. However, it does not support the
> + complete set of schema constructs and is likely to complain for certain
> + schemas!</li>
> + <li><strong>XMLBeans</strong> - XMLbeans claims that it supports the
> + complete schema specification and it is the choice, if full schema
> + support is needed!</li>
> + <li><strong>JAX-Me</strong> - JaxMe support has been added in a similar
> + manner to XMLbeans and serves as another option for the user</li>
> + <li><strong>JibX</strong> - This is the most recent addition to the family
> + of databinding extensions and it is also another option the users have
> + for data binding.</li>
> +</ol>
> +
> +<h3><a name="serial" id="serial">Serialization and De-Serialization of Data
> +bound classes</a></h3>
> +
> +<p>AXIOM is based on a StAX API (Streaming API for XML). Xml-beans supports
> +StAX API. Data binding in Axis2 is achieved through interfacing the AXIOM
> +with the Xml-beans using the StAX API which is supported by both parties. At
> +the time of the code generation there will be utility methods generated
> +inside the stub (or the message receiver) that can de-serialize from AXIOM to
> +data bound object and serialize from data bound object to AXIOM. For example,
> +if the WSDL has an operation called "echoString", once the code is generated
> +the following methods will be generated inside the relevant classes.</p>
> +<pre>public static
> +org.apache.axiom.om.OMElementtoOM(org.soapinterop.xsd.EchoStringParamDocument
> +param)// This method will handle the serialization.
> +
> +public static org.apache.xmlbeans.XmlObject
> +fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This
> +method will handle the de-serialization.</pre>
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/WS_policy.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/WS_policy.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/WS_policy.html (added)
> +++ webservices/axis2/trunk/java/xdocs/WS_policy.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,174 @@
> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
> + "http://www.w3.org/TR/html4/loose.dtd">
> +<html>
> +<head>
> + <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
> + <title>WS Policy Support in Axis2</title>
> + <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
> +</head>
> +
> +<body lang="en">
> +<h1 align="center">Web Services Policy Support In Axis2</h1>
> +
> +<p>This document will give you an introduction to the role of Web services
> +policy in Axis2.</p>
> +
> +<p><i>E-mail comments/ suggestions to: <a
> +href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
> +subject with [Axis2]. To subscribe to mailing list see <a
> +href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
> +
> +<h2>Content</h2>
> +<ul>
> + <li><a href="#what">What is Web Services (WS) Policy?</a></li>
> + <li><a href="#client">Client Side WS-Policy Support</a></li>
> + <li><a href="#server">Server Side WS-Policy Support</a></li>
> + <li><a href="#resources">Resources</a></li>
> +</ul>
> +<a name="what"></a>
> +
> +<h2>What is Web Services (WS) Policy?</h2>
> +
> +<p>To consume non trivial web services one must fully understand its xml
> +contract (WSDL) along with any other additional requirements, capabilities or
> +preferences which translates to the configuration of the service, and
> +essentially becomes the policies of the service.</p>
> +
> +<p>WS Policy framework provides a way to express the policies of a service in
> +a machine-readable way. Web services infrastructure can be enhanced to
> +understand and enforce policies at runtime. For instance, a service author
> +might write a policy requiring digital signature and encryption, while
> +service consumers could use the policy information to reason out whether they
> +can adhere to this policy information to use the service or not.</p>
> +
> +<p>Further more, web service infrastructure could be enhanced to enforce
> +those requirements without requiring the service author to write even single
> +line of code.</p>
> +<a name="client"></a>
> +
> +<h2>Client Side WS-Policy Support</h2>
> +
> +<p>This release <strong>fully supports WS Policy at client-side</strong>. It
> +means that when you codegen a stub against a WSLD which contains policies,
> +the stub will contain the capability to engage the required modules with the
> +appropriate configurations. For instance, if there is a security policy
> +attached to an operation in the WSDL, the generated stub will engage the
> +security module for that operation with the appropriate security
> +configurations.</p>
> +
> +<h3>How it works:</h3>
> +
> +<h4>Phase 1: At PolicyEvaluator</h4>
> +
> +<p>Codegen engine runs few of its registered extensions before it generates
> +the stub. When PolicyEvalutor (which is a registered Codegen extension) is
> +initialized, it populates a registry of namespaces of supported policies to
> +PolicyExtensions.</p>
> +
> +<p>For instance, module foo might have a mapping of namespace
> +http://test.com/foo which means any primitive assertion which has this
> +namespace will be processed by this module. Foo module might implement the
> +ModulePolicyExtension interface through which PolicyExtension object can be
> +obtained.</p>
> +
> +<p>A <strong>PolicyExtension</strong> is the access point for a module to add
> +any other methods to the stub. For instance Reliable Messaging module can add
> +createSequence() and endSequence() methods to the stub, that the user must
> +call to start and end an RM sequence.</p>
> +
> +<p>Then at the engagement of PolicyEvaluator, effective policy of each
> +operation is calculated based on policy information declared in the WSDL
> +document. Here we assume that effective policy of an operation contains a
> +single alternative (<strong>Multiple policy alternatives are not
> +supported</strong>). Then we split that policy as follows into few other
> +policies such that, each policy will contain primitive assertions belonging
> +to only one namespace.</p>
> +<pre> <wsp:Policy> <wsp:Policy> <wsp:Policy> <wsp:Policy>
> + <a:Foo/> <a:Foo/> <b:Foo/> <c:Bar/>
> + <a:Bar/> => <a:Bar/> </wsp:Policy> </wsp:Policy>
> + <b:Foo/> </wsp:Policy>
> + <c:Bar/>
> + </wsp:Policy></pre>
> +
> +<p>Then each policy is given to the appropriate PolicyExtension with an
> +org.w3c.Element type object to which the module can append any other
> +elements/attributes it wishes. Those attributes/elements should resolve to
> +meaningful stub functions via PolicyExtensionTemplate.xsl at latter point of
> +time.</p>
> +
> +<p>For instance depending on the policy, Security module can append
> +<username>, <passwd> elements to the given element as children,
> +which are later resolved into setUsername(..), setPasswd(..), functions of
> +the stub. This way a module can include additional methods to the stub which
> +can be used to get specific parameters to the module. These methods store any
> +user input in the ServiceClient properties
> +(ServiceClient.getOptions().putProperty(...)) which can later be accessed by
> +the module.</p>
> +
> +<h4>Phase 2: At MultiLanguageClientEmitter</h4>
> +
> +<p>Further, effective policies (based on the WSDL) at appropriate levels
> +(service level, operation level) are stored as policy strings in the stub.
> +Few more generic methods are also added to the stub which are used to
> +evaluate/process policies at runtime.</p>
> +
> +<h4>Phase 3: Runtime</h4>
> +
> +<p>When a new stub object is created, the policy strings in the stub are
> +converted into policy objects and merged together to get the effective
> +policies of each operation. These effective policies are stored in
> +appropriate AxisOperation objects which a module can access at later point of
> +time.</p>
> +
> +<p>Then based on its policy each AxisOperation is engaged to a set of
> +modules.</p>
> +
> +<p>When the stub method is invoked, those modules which are engaged to that
> +AxisOperation, access the effective policy for that operation via
> +AxisOperation object. It can get other information needed from the
> +MessageContext which get stored by stub methods which the module has added to
> +the stub earlier. The modules are required to loads their configurations
> +according to the effective policy which is set in AxisOperation and
> +properties they get via MessageContext.</p>
> +<a name="server"></a>
> +
> +<h2>Server Side WS-Policy Support</h2>
> +
> +<p>In this current release Axis2 framework uses WS-Commons/Neethi framework
> +to manipulate policy documents. All its description builders store any policy
> +information included in description documents (services.xml, axis2.xml, ..
> +etc) in the appropriate description classes. This information is available at
> +both deployment and run time via these description classes.</p>
> +
> +<p>When generating WSDL dynamically for each service, policy information in
> +the description classes is included. For instance, if you declare a policy in
> +axis2.xml then that policy is reflected in service elements of WSDL of every
> +service. If a policy is declared in a services.xml, it is shown in the
> +service element of WSDL for that particular service.</p>
> +
> +<p>Next step is to use that information to engage and configure required
> +modules and allow the module to make use of this policy information.</p>
> +
> +<p>It is evident that a great deal of work is required to make axis2 a fully
> +fledged ws-policy supported web service infrastructure. But it is encouraging
> +to note that we've taken the first steps towards this goal. We appreciate any
> +suggestions, patches etc you send us in this regard. Keep on
> +contributing...!</p>
> +<a name="resources"></a>
> +
> +<h2>Resources</h2>
> +<ul>
> + <li>Apache Neethi (WS Policy Implementation) official site- <a
> + href="http://ws.apache.org/commons/neethi/index.html"
> + target="_blank">Home Page</a></li>
> + <li>Sanka Samaranayake, March 2006. <a
> + href="http://www.wso2.net/2006/01/web_services_policy_why_what_how"
> + target="_blank">Web services Policy - Why, What & How</a></li>
> + <li><a
> + href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/"
> + target="_blank">WS-commons/policy SVN</a></li>
> + <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf"
> + target="_blank">Web Services Policy Framework (WS-Policy)</a></li>
> +</ul>
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html (added)
> +++ webservices/axis2/trunk/java/xdocs/adb/adb-advanced.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,112 @@
> +<html>
> +<head>
> + <meta http-equiv="content-type" content="text/html; charset=UTF-8">
> + <title>Advanced Axis2 Databinding Framework Features</title>
> +</head>
> +
> +<body lang="en">
> +<h1>Advanced Axis2 Databinding Framework Features</h1>
> +
> +<p>The aim of this section is provide an insight into the newly added
> +advanced features of ADB.</p>
> +
> +<h2>Content</h2>
> +<ul>
> + <li><a href="#typeSupport">xsi:type Support</a></li>
> + <li><a href="#helper">Helpergen Mode</a></li>
> + <li><a href="#more">More Stuff on ADB?</a></li>
> +</ul>
> +
> +<h2><a name="typeSupport">xsi:type Support</a></h2>
> +
> +<p>This is implemented by adding a extension maping class. The code that
> +calls the extension mapper is generated inside the deserialization method of
> +the beans and gets active when the xsi:type attribute is present. The
> +following code fragment shows how the generated type mapper looks like</p>
> +<pre> public static java.lang.Object getTypeObject(
> +java.lang.String namespaceURI, java.lang.String typeName,
> +javax.xml.stream.XMLStreamReader reader) throws java.lang.Exception {
> +if ("http://new.webservice.namespace/types".equals(namespaceURI) && "derivedType2".equals(typeName)) {
> + return namespace.webservice._new.types.DerivedType2Helper.parse(reader);
> +}
> +
> +......
> +
> + return namespace.webservice._new.types.BaseTypeHelper.parse(reader);
> +} else if ("http://new.webservice.namespace/types".equals(namespaceURI) && "derivedType1".equals(typeName)) {
> + return namespace.webservice._new.types.DerivedType1Helper.parse(reader);
> +}
> +
> +throw new java.lang.RuntimeException("Unsupported type " +
> + namespaceURI + " " + typeName);
> +
> +}</pre>
> +
> +<p>Inside every deserialize method, the extension mapper gets called when a
> +xsi:type attribute is encountered <strong>and</strong> that type is not the
> +type that is being parsed</p>
> +
> +<p>The following code fragment shows how the ADB deserialize method calls the
> +mapper class</p>
> +<pre>if (reader.getAttributeValue(
> + "http://www.w3.org/2001/XMLSchema-instance", "type") != null) {
> + java.lang.String fullTypeName = reader.getAttributeValue("http://www.w3.org/2001/XMLSchema-instance",
> + "type");
> + if (fullTypeName != null) {
> + java.lang.String nsPrefix = fullTypeName.substring(0,fullTypeName.indexOf(":"));
> + nsPrefix = (nsPrefix == null) ? "" : nsPrefix;
> + java.lang.String type = fullTypeName.substring(fullTypeName.indexOf(":") + 1);
> + if (!"derivedType2".equals(type)) {
> + //find namespace for the prefix
> + java.lang.String nsUri = reader.getNamespaceContext().getNamespaceURI(nsPrefix);
> + <strong>return (DerivedType2) namespace.webservice._new.types.ExtensionMapper.getTypeObject(nsUri,
> + type, reader);</strong>
> + }
> + }
> +}</pre>
> +
> +<p>This should make the xsi:type based deserialization possible and should
> +result in proper xsi:type based serializations at runtime</p>
> +
> +<p>This is automatically done but the package name for the mapper class can
> +be controlled by using the <strong>mp</strong> flag (with a preceding -E)</p>
> +<pre> WSDL2Code -uri .... -Emp org.example.web.map</pre>
> +
> +<p>When the mapping package is not specified it is derived from the
> +targetnamespace of the first schema that is encountered</p>
> +
> +<h2><a name="helper">Helper mode</a></h2>
> +
> +<p>Helper mode is a fairly new feature. In the helper mode, the beans are
> +plain Java beans and all the deserialization/serialization code is moved to a
> +helper class. For example the simple schema mentioned in the ADB-howto
> +document will yield four classes for the two that has been previously seen</p>
> +<ol>
> + <li>MyElement.java</li>
> + <li>MyElementHelper.java</li>
> + <li>SOAPStruct.java</li>
> + <li>SOAPStructHelper.java</li>
> +</ol>
> +
> +<p>The helpers basically contain all the code that went into the ADBBeans.
> +Hence the beans in the helper mode are pretty much readable than the rest.
> +Also note that the helper mode is available only if you are in the unpacked
> +mode. The code generator by default does not expand the classes</p>
> +
> +<p>Helper mode can be switched on by the <strong>h</strong> flag (Passed with
> +a -E infront to indicate that it is an extra switch undertood by ADB). Also
> +the <strong>-u</strong> flag should be present to indicate the unpacking</p>
> +<pre> WSDL2Code -uri .... -u -Eh</pre>
> +
> +<h2><a name="more">More Stuff on ADB?</a></h2>
> +<ul>
> + <li><a href="adb-tweaking.html">Tweaking the ADB Code Generator</a>-
> + explains available mechanisms to extend ADB and possibly adopt it to
> + compile schemas to support other languages.</li>
> + <li><a href="adb-codegen-integration.html">ADB and Axis2 Integration</a> -
> + explains how the ADB schema compiler was attached to the Axis2
> + framework</li>
> +</ul>
> +<hr>
> +</body>
> +</html>
>
> Added: webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html
> URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html?view=auto&rev=453167
> ==============================================================================
> --- webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html (added)
> +++ webservices/axis2/trunk/java/xdocs/adb/adb-codegen-integration.html Thu Oct 5 02:56:34 2006
> @@ -0,0 +1,93 @@
> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
>
> + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
>
> +<html xmlns="http://www.w3.org/1999/xhtml">
>
> +<head>
>
> +<title>ADB Integration With Axis2</title>
>
> +</head>
>
> +<body>
>
> +<h1>ADB Integration With Axis2</h1>
>
> +<p>This document will assist you to write an extension using the
>
> +integrator in order to integrate ADB with Axis2.</p>
>
> +<h2>Content</h2>
>
> +<ul>
>
> +<li><a href="#intro">Introduction</a></li>
>
> +<li><a href="#select_modes">Selection of Generation Modes for
>
> +ADB</a></li>
>
> +<li><a href="#remember">Things to Remember</a></li>
>
> +</ul>
>
> +<h2><a name="intro" id="intro">Introduction</a></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>
>
> +<a name="select_modes" id="select_modes"></a>
>
> +<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 <a href=
>
> +"adb-howto.html" target="_blank">ADB-How to document</a> for the
>
> +different generation modes and their descriptions.</p>
>
> +<table border="1">
>
> +<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>
>
> +<tr>
>
> +<td>-u (unwrap classes)</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 in the command line (prefixed with
>
> +-E)</p>
>
> +<table border="1">
>
> +<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>Note that these parameters have no relevant long names and MUST
>
> +be prefixed with a -E to be processed by the code generator. For
>
> +example</p>
>
> +<pre>
>
> +WSDL2Java .... -Er true
>
> +</pre>
>
> +<a name="remember" id="remember"></a>
>
> +<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
>
> +). In the most recent release, the default has been set as ADB and
>
> +hence if the -d option is missing then the databinding framework
>
> +will be ADB.</li>
>
> +</ol>
>
> +<hr />
>
> +</body>
>
> +</html>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
> For additional commands, e-mail: axis-cvs-help@ws.apache.org
>
>
--
http://webservices.apache.org/~thilina/
http://thilinag.blogspot.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org