You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ve...@apache.org on 2012/01/09 09:31:12 UTC
svn commit: r1229060 - in /axis/axis1/java/trunk: docs/ docs/images/
src/site/resources/ src/site/resources/images/ src/site/xdoc/
Author: veithen
Date: Mon Jan 9 08:31:10 2012
New Revision: 1229060
URL: http://svn.apache.org/viewvc?rev=1229060&view=rev
Log:
Migrated the Architecture guide to XDoc by starting from the Forrest site sources.
Added:
axis/axis1/java/trunk/src/site/resources/
axis/axis1/java/trunk/src/site/resources/images/
axis/axis1/java/trunk/src/site/resources/images/ClientMessagePath.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/ClientMessagePath.jpg
axis/axis1/java/trunk/src/site/resources/images/SAXHandlerClasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/SAXHandlerClasses.jpg
axis/axis1/java/trunk/src/site/resources/images/SAXhandlers.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/SAXhandlers.jpg
axis/axis1/java/trunk/src/site/resources/images/ServerMessagePath.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/ServerMessagePath.jpg
axis/axis1/java/trunk/src/site/resources/images/chainclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/chainclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/clientinteraction.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/clientinteraction.jpg
axis/axis1/java/trunk/src/site/resources/images/clientobjects.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/clientobjects.jpg
axis/axis1/java/trunk/src/site/resources/images/engineclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/engineclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/engineconfig.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/engineconfig.jpg
axis/axis1/java/trunk/src/site/resources/images/messagecontext.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/messagecontext.jpg
axis/axis1/java/trunk/src/site/resources/images/messagemodelclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/messagemodelclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/messagetree.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/messagetree.jpg
axis/axis1/java/trunk/src/site/resources/images/pivots.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/pivots.jpg
axis/axis1/java/trunk/src/site/resources/images/pivots2.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/pivots2.jpg
axis/axis1/java/trunk/src/site/resources/images/serclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/serclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/serfactoryclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/serfactoryclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/soapmessagemodel.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/soapmessagemodel.jpg
axis/axis1/java/trunk/src/site/resources/images/stcengine.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/stcengine.jpg
axis/axis1/java/trunk/src/site/resources/images/subsystems.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/subsystems.jpg
axis/axis1/java/trunk/src/site/resources/images/targetedchainclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/targetedchainclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/typemappingclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/typemappingclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/typemappingregistryclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/typemappingregistryclasses.jpg
axis/axis1/java/trunk/src/site/resources/images/wsddclasses.jpg
- copied unchanged from r1228993, axis/axis1/java/trunk/docs/images/wsddclasses.jpg
axis/axis1/java/trunk/src/site/xdoc/architecture-guide.xml
- copied, changed from r1228993, webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/architecture-guide.xml
Removed:
axis/axis1/java/trunk/docs/architecture-guide.html
axis/axis1/java/trunk/docs/images/ClientMessagePath.jpg
axis/axis1/java/trunk/docs/images/SAXHandlerClasses.jpg
axis/axis1/java/trunk/docs/images/SAXhandlers.jpg
axis/axis1/java/trunk/docs/images/ServerMessagePath.jpg
axis/axis1/java/trunk/docs/images/chainclasses.jpg
axis/axis1/java/trunk/docs/images/clientinteraction.jpg
axis/axis1/java/trunk/docs/images/clientobjects.jpg
axis/axis1/java/trunk/docs/images/engineclasses.jpg
axis/axis1/java/trunk/docs/images/engineconfig.jpg
axis/axis1/java/trunk/docs/images/messagecontext.jpg
axis/axis1/java/trunk/docs/images/messagemodelclasses.jpg
axis/axis1/java/trunk/docs/images/messagetree.jpg
axis/axis1/java/trunk/docs/images/pivots.jpg
axis/axis1/java/trunk/docs/images/pivots2.jpg
axis/axis1/java/trunk/docs/images/serclasses.jpg
axis/axis1/java/trunk/docs/images/serfactoryclasses.jpg
axis/axis1/java/trunk/docs/images/soapmessagemodel.jpg
axis/axis1/java/trunk/docs/images/stcengine.jpg
axis/axis1/java/trunk/docs/images/subsystems.jpg
axis/axis1/java/trunk/docs/images/targetedchainclasses.jpg
axis/axis1/java/trunk/docs/images/typemappingclasses.jpg
axis/axis1/java/trunk/docs/images/typemappingregistryclasses.jpg
axis/axis1/java/trunk/docs/images/wsddclasses.jpg
Copied: axis/axis1/java/trunk/src/site/xdoc/architecture-guide.xml (from r1228993, webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/architecture-guide.xml)
URL: http://svn.apache.org/viewvc/axis/axis1/java/trunk/src/site/xdoc/architecture-guide.xml?p2=axis/axis1/java/trunk/src/site/xdoc/architecture-guide.xml&p1=webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/architecture-guide.xml&r1=1228993&r2=1229060&rev=1229060&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/architecture-guide.xml (original)
+++ axis/axis1/java/trunk/src/site/xdoc/architecture-guide.xml Mon Jan 9 08:31:10 2012
@@ -1,80 +1,47 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "./dtd/document-v12.dtd">
-<document>
- <header>
- <title>WebServices - Axis</title>
- </header>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+ <properties>
+ <title>Architecture Guide</title>
+ </properties>
<body>
-<a name="AxisArchitectureGuide"/>
-<section>
-<title>Axis Architecture Guide</title>
-
-<p><i>1.2 Version</i><br/>
- <i>Feedback: <a href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i></p>
-
-<a name="TableOfContents"/>
-<section>
-<title>Table of Contents</title>
+<section name="Table of Contents">
-<ul>
- <li><a href="#Introduction">Introduction</a></li>
- <li><a href="#ArchitecturalOverview">Architectural Overview</a></li>
- <ul>
- <li><a href="#HandlersAndTheMessagePathInAxis">Handlers and the Message Path in Axis</a></li>
- <li><a href="#MessagePathOnTheServer">Message Path on the Server</a></li>
- <li><a href="#MessagePathOnTheClient">Message Path on the Client</a></li>
- </ul>
- <li><a href="#Subsystems">Subsystems</a></li>
- <li><a href="#MessageFlowSubsystem">Message Flow Subsystem</a></li>
- <ul>
- <li><a href="#HandlersAndChains">Handlers and Chains</a></li>
- <li><a href="#MessageContexts">Message Contexts</a></li>
- <li><a href="#Engine">Engine</a></li>
- </ul>
- <li><a href="#AdministrationSubsystem">Administration Subsystem</a></li>
- <ul>
- <li><a href="#WSDD-BasedAdministration">WSDD-Based Administration</a></li>
- </ul>
- <li><a href="#MessageModelSubsystem">Message Model Subsystem</a></li>
- <ul>
- <li><a href="#SOAPMessageModel">SOAP Message Model</a></li>
- <li><a href="#MessageElements">Message Elements</a></li>
- <li><a href="#Deserialization">Deserialization</a></li>
- </ul>
- <li><a href="#EncodingSubsystem">Encoding Subsystem</a></li>
- <li><a href="#WSDLToolsSubsystem">WSDL Tools Subsystem</a></li>
- <ul>
- <li><a href="#WSDL2Java">WSDL2Java</a></li>
- <li><a href="#Java2WSDL">Java2WSDL</a></li>
- </ul>
- <li><a href="#InteractionDiagrams">Interaction Diagrams</a></li>
- <ul>
- <li><a href="#ClientSideProcessing">Client Side Processing</a></li>
- </ul>
- <li><a href="#Pluggable-ComponentDiscovery">Pluggable-Component Discovery</a></li>
- <li><a href="#OpenIssues">Open Issues</a></li>
-</ul>
+<macro name="toc"/>
</section>
-<a name="Introduction"/>
-<section>
-<title>Introduction</title>
+<section name="Introduction">
<p>This guide records some of the rationale of the architecture and design of Axis.</p>
</section>
-<a name="ArchitecturalOverview"/>
-<section>
-<title>Architectural Overview</title>
+<section name="Architectural Overview">
<p>Axis consists of several subsystems working together, as we shall see later. In this section we'll give you an overview of how the core of Axis works.</p>
-<a name="HandlersAndTheMessagePathInAxis"/>
-<section>
-<title>Handlers and the Message Path in Axis</title>
+<subsection name="Handlers and the Message Path in Axis">
<p>Put simply, Axis is all about processing Messages. When the central Axis processing logic runs, a series of <b>Handlers</b> are each invoked in order. The particular order is determined by two factors - deployment configuration and whether the engine is a client or a server. The object which is passed to each Handler invocation is a <b>MessageContext</b>. A MessageContext is a structure which contains several important parts: 1) a "request" message, 2) a "response" message, and 3) a bag of properties. More on this in a bit.</p>
@@ -87,15 +54,13 @@
<p>In either case, the Axis framework's job is simply to pass the resulting MessageContext through the configured set of Handlers, each of which has an opportunity to do whatever it is designed to do with the MessageContext.</p>
-</section>
+</subsection>
-<a name="MessagePathOnTheServer"/>
-<section>
-<title>Message Path on the Server</title>
+<subsection name="Message Path on the Server">
<p>The server side message path is shown in the following diagram. The small cylinders represent Handlers and the larger, enclosing cylinders represent <b>Chains</b> (ordered collections of Handlers which will be described shortly).</p>
-<p><img src="images/ServerMessagePath.jpg" vspace="30" height="282" width="602"/></p>
+<p><img src="images/ServerMessagePath.jpg" vspace="30" height="282" width="602" alt="ServerMessagePath"/></p>
<p>A message arrives (in some protocol-specific manner) at a Transport Listener. In this case, let's assume the Listener is a HTTP servlet. It's the Listener's job to package the protocol-specific data into a <b>Message</b> object (org.apache.axis.Message), and put the Message into a <b>MessageContext</b>. The MessageContext is also loaded with various <b>properties</b> by the Listener - in this example the property "http.SOAPAction" would be set to the value of the SOAPAction HTTP header. The Transport Listener also sets the <b>transportName</b> String on the MessageContext , in this case to "http". Once the MessageContext is ready to go, the Listener hands it to the AxisEngine.</p>
@@ -107,56 +72,47 @@
<p>For RPC-style requests, the provider is the org.apache.axis.providers.java.RPCProvider class. This is just another Handler that, when invoked, attempts to call a backend Java object whose class is determined by the "className" parameter specified at deployment time. It uses the SOAP RPC convention for determining the method to call, and makes sure the types of the incoming XML-encoded arguments match the types of the required parameters of the resulting method.</p>
-</section>
+</subsection>
-<a name="MessagePathOnTheClient"/>
-<section>
-<title>Message Path on the Client</title>
+<subsection name="Message Path on the Client">
<p>The Message Path on the client side is similar to that on the server side, except the order of scoping is reversed, as shown below.</p>
-<p><img src="images/ClientMessagePath.jpg" vspace="30" height="281" width="592"/></p>
+<p><img src="images/ClientMessagePath.jpg" vspace="30" height="281" width="592" alt="ClientMessagePath"/></p>
<p>The <b>service</b> Handler, if any, is called first - on the client side, there is no "provider" since the service is being provided by a remote node, but there is still the possibility of request and response Chains. The service request and response Chains perform any service-specific processing of the request message on its way out of the system, and also of the response message on its way back to the caller.</p>
<p>After the service request Chain, the global request Chain, if any, is invoked, followed by the transport. The <b>Transport Sender</b>, a special Handler whose job it is to actually perform whatever protocol-specific operations are necessary to get the message to and from the target SOAP server, is invoked to send the message. The response (if any) is placed into the responseMessage field of the MessageContext, and the MessageContext then propagates through the response Chains - first the transport, then the global, and finally the service.</p>
-</section>
+</subsection>
</section>
-<a name="Subsystems"/>
-
-<section>
-<title>Subsystems</title>
+<section name="Subsystems">
<p>Axis comprises several subsystems working together with the aim of separating responsibilities cleanly and making Axis modular. Subsystems which are properly layered enable parts of a system to be used without having to use the whole of it (or hack the code).</p>
<p>The following diagram shows the layering of subsystems. The lower layers are independent of the higher layers. The 'stacked' boxes represent mutually independent, although not necessary mutually exclusive, alternatives. For example, the HTTP, SMTP, and JMS transports are independent of each other but may be used together.</p>
-<p><img src="images/subsystems.jpg"/></p>
+<p><img src="images/subsystems.jpg" alt="subsystems"/></p>
<p>In fact, the Axis source code is not as cleanly separated into subsystems as the above diagram might imply. Some subsystems are spread over several packages and some packages overlap more than one subsystem. Proposals to improve the code structure and make it conform more accurately to the notional Axis subsystems will be considered when we get a chance.</p>
</section>
-<a name="MessageFlowSubsystem"/>
-<section>
-<title>Message Flow Subsystem</title>
-
-<a name="HandlersAndChains"/>
-<section>
-<title>Handlers and Chains</title>
+<section name="Message Flow Subsystem">
+
+<subsection name="Handlers and Chains">
<p>Handlers are invoked in sequence to process messages. At some point in the sequence a Handler may send a request and receive a response or else process a request and produce a response. Such a Handler is known as the <i>pivot point</i> of the sequence. As described above, Handlers are either transport-specific, service-specific, or global. The Handlers of each of these three different kinds are combined together into Chains. So the overall sequence of Handlers comprises three Chains: transport, global, and service. The following diagram shows two sequences of handlers: the client-side sequence on the left and the server-side sequence on the right.</p>
-<p><img src="images/pivots.jpg" height="240" width="403"/></p>
+<p><img src="images/pivots.jpg" height="240" width="403" alt="pivots"/></p>
<p>A web service does not necessarily send a response message to each request message, although many do. However, response Handlers are still useful in the message path even when there isn't a response message, e.g. to stop timers, clean up resources, etc.</p>
<p>A Chain is a composite Handler, i.e. it aggregates a collection of Handlers as well as implementing the Handler interface as shown in the following UML diagram:</p>
-<p><img src="images/chainclasses.jpg"/></p>
+<p><img src="images/chainclasses.jpg" alt="chainclasses"/></p>
<p>A Chain also has similarities to the Chain of Responsibility design pattern in which a request flows along a sequence of Handlers until it is processed. Although an Axis Chain may process a request in stages over a succession of Handlers, it has the same advantages as Chain of Responsibility: flexibility and the ease with which new function can be added.</p>
@@ -164,92 +120,71 @@
<p>The deployment registry has factories for Handlers and Chains. Handlers and Chains can be defined to have 'per-access', 'per-request', or 'singleton' scope although the registry currently only distinguishes between these by constructing non-singleton scope objects when requested and constructing singleton scope objects once and holding on to them for use on subsequent creation requests.</p>
-<section>
-<title>Targeted Chains</title>
+<h4>Targeted Chains</h4>
<p>A <b>Targeted Chain</b> is a special kind of chain which may have any or all of: a request Handler, a pivot Handler, and a response Handler. The following class diagram shows how Targeted Chains relate to Chains. Note that a Targeted Chain is an aggregation of Handlers by virtue of extending the Chain interface which is an aggregation of Handlers.</p>
-<p><img src="images/targetedchainclasses.jpg"/></p>
+<p><img src="images/targetedchainclasses.jpg" alt="targetedchainclasses"/></p>
<p>A service is a special kind of Targeted Chain in which the pivot Handler is known as a "provider".</p>
-</section>
-
-<section>
-<title>Fault Processing</title>
+<h4>Fault Processing</h4>
<p>Now let's consider what happens when a fault occurs. The Handlers prior to the Handler that raised the fault are driven, in reverse order, for onFault (previously misnamed 'undo'). The scope of this backwards scan is interesting: all Handlers previously invoked for the current Message Context are driven.</p>
<p><i>Need to explain how "FaultableHandlers" and "WSDD Fault Flows" fit in.</i></p>
-</section>
-
-</section>
+</subsection>
-<a name="MessageContexts"/>
-<section>
-<title>Message Contexts</title>
+<subsection name="Message Contexts">
<p>The current structure of a MessageContext is shown below. Each message context may be associated with a request Message and/or a response Message. Each Message has a SOAPPart and an Attachments object, both of which implement the Part interface.</p>
-<p><img src="images/messagecontext.jpg"/></p>
+<p><img src="images/messagecontext.jpg" alt="messagecontext"/></p>
<p>The typing of Message Contexts needs to be carefully considered in relation to the Axis architecture. Since a Message Context appears on the Handler interface, it should not be tied to or biassed in favour of SOAP. The current implementation is marginally biassed towards SOAP in that the setServiceHandler method narrows the specified Handler to a SOAPService.</p>
-</section>
+</subsection>
-<a name="Engine"/>
-<section>
-<title>Engine</title>
+<subsection name="Engine">
<p>Axis has an abstract AxisEngine class with two concrete subclasses: AxisClient drives the client side handler chains and AxisServer drives the server side handler chains. The relationships between these classes is fairly simple:</p>
-<p><img src="images/engineclasses.jpg"/></p>
+<p><img src="images/engineclasses.jpg" alt="engineclasses"/></p>
-<section>
-<title>Engine Configuration</title>
+<h4>Engine Configuration</h4>
<p>The EngineConfiguration interface is the means of configuring the Handler factories and global options of an engine instance. An instance of a concrete implementation of EngineConfiguration must be passed to the engine when it is created and the engine must be notified if the EngineConfiguration contents are modified. The engine keeps a reference to the EngineConfiguration and then uses it to obtain Handler factories and global options.</p>
<p>The EngineConfiguration interface belongs to the Message Flow subsystem which means that the Message Flow subsystem does not depend on the Administration subsystem.</p>
-</section>
-
-</section>
+</subsection>
</section>
-<a name="AdministrationSubsystem"/>
-<section>
-<title>Administration Subsystem</title>
+<section name="Administration Subsystem">
<p>The Administration subsystem provides a way of configuring Axis engines. The configuration information an engine needs is a collection of factories for runtime artefacts such as Chains and SOAPServices and a set of global configuration options for the engine.</p>
<p>The Message Flow subsystem's EngineConfiguration interface is implemented by the Administration subsystem. FileProvider enables an engine to be configured statically from a file containing a deployment descriptor which is understood by the WSDDDeployment class. SimpleProvider, on the other hand, enables an engine to be configured dynamically.</p>
-<p><img src="images/engineconfig.jpg"/></p>
+<p><img src="images/engineconfig.jpg" alt="engineconfig"/></p>
-<a name="WSDD-BasedAdministration"/>
-<section>
-<title>WSDD-Based Administration</title>
+<subsection name="WSDD-Based Administration">
<p>WSDD is an XML grammer for deployment descriptors which are used to statically configure Axis engines. Each Handler needs configuration in terms of the concrete class name of a factory for the Handler, a set of options for the handler, and a lifecycle scope value which determines the scope of sharing of instances of the Handler.</p>
<p>The structure of the WSDD grammar is mirrored by a class hierarchy of factories for runtime artefacts. The following diagram shows the classes and the types of runtime artefacts they produce (a dotted arrow means "instantiates").</p>
-<p><img src="images/wsddclasses.jpg"/></p>
+<p><img src="images/wsddclasses.jpg" alt="wsddclasses"/></p>
-</section>
+</subsection>
</section>
-<a name="MessageModelSubsystem"/>
-<section>
-<title>Message Model Subsystem</title>
+<section name="Message Model Subsystem">
-<a name="SOAPMessageModel"/>
-<section>
-<title>SOAP Message Model</title>
+<subsection name="SOAP Message Model">
<p>The XML syntax of a SOAP message is fairly simple. A SOAP message consists of an <i>envelope</i> containing:</p>
@@ -272,27 +207,23 @@
<p>So the SOAP message model looks like this:</p>
-<p><img src="images/soapmessagemodel.jpg"/></p>
+<p><img src="images/soapmessagemodel.jpg" alt="soapmessagemodel"/></p>
-</section>
+</subsection>
-<a name="MessageElements"/>
-<section>
-<title>Message Elements</title>
+<subsection name="Message Elements">
<p>The classes which represent SOAP messages form a class hierarchy based on the MessageElement class which takes care of namespaces and encodings. The SOAPHeaderElement class looks after the actor and mustUnderstand attributes.</p>
-<p><img src="images/messagemodelclasses.jpg"/></p>
+<p><img src="images/messagemodelclasses.jpg" alt="messagemodelclasses"/></p>
<p>During deserialization, a parse tree is constructed consisting of instances of the above classes in parent-child relationships as shown below.</p>
-<p><img src="images/messagetree.jpg"/></p>
+<p><img src="images/messagetree.jpg" alt="messagetree"/></p>
-</section>
+</subsection>
-<a name="Deserialization"/>
-<section>
-<title>Deserialization</title>
+<subsection name="Deserialization">
<p>The class mainly responsible for XML parsing, i.e. deserialization, is DeserializationContext ('DC'). DC manages the construction of the parse tree and maintains a stack of SAX handlers, a reference to the MessageElement that is currently being deserialized, a stack of namespace mappings, a mapping from IDs to elements, a set of type mappings for deserialization (see <a href="#EncodingSubsystem">Encoding Subsystem</a>) and a SAX event recorder. </p>
@@ -302,11 +233,11 @@
<p>The SAX handlers form a class hierarchy:</p>
-<p><img src="images/SAXHandlerClasses.jpg"/></p>
+<p><img src="images/SAXHandlerClasses.jpg" alt="SAXHandlerClasses"/></p>
<p>and stack up as shown in the following diagram:</p>
-<p><img src="images/SAXhandlers.jpg"/></p>
+<p><img src="images/SAXhandlers.jpg" alt="SAXhandlers"/></p>
<p>Initially, the SAX handler stack just contains an instance of EnvelopeHandler which represents the fact that parsing of the SOAP envelope has not yet started. The EnvelopeHandler is constructed with a reference to an EnvelopeBuilder, which is the SAX handler responsible for parsing the SOAP envelope.</p>
@@ -318,29 +249,27 @@
<p>Elements which are not defined by SOAP are treated using a SOAPHandler as a SAX event handler and a MessageElement as a node in the parse tree.</p>
-</section>
+</subsection>
</section>
-<a name="EncodingSubsystem"/>
-<section>
-<title>Encoding Subsystem</title>
+<section name="Encoding Subsystem">
<p>Encoding is most easily understood from the bottom up. The basic requirement is to transform between values of programming language datatypes and their XML representations. In Axis, this means encoding (or 'serializing') Java objects and primitives into XML and decoding (or 'deserializing') XML into Java objects and primitives. The basic classes that implement these steps are <i>serializers</i> and <i>deserializers</i>.</p>
-<p><img src="images/serclasses.jpg"/></p>
+<p><img src="images/serclasses.jpg" alt="serclasses"/></p>
<p>Particular serializers and deserializers are written to support a specific XML processing mechanism such as DOM or SAX. So <i>serializer factories</i> and <i>deserializer factories</i> are introduced to construct serializers and deserializers for a XML processing mechanism which is specified as a parameter.</p>
-<p><img src="images/serfactoryclasses.jpg"/></p>
+<p><img src="images/serfactoryclasses.jpg" alt="serfactoryclasses"/></p>
<p>As is apparent from the above class diagrams, each pair of Java type and XML data type which needs encoding and decoding requires specific serializers and deserializers (actually one of each per XML processing mechanism). So we need to maintain a mapping from a pair of Java type and XML data type, identified by a QName, to a serializer factory and a deserializer factory. Such a mapping is known as a <i>type mapping</i>. The type mapping class hierarchy is shown below. Notice how the default type mapping instantiates the various serializer and deserialiser factories.</p>
-<p><img src="images/typemappingclasses.jpg"/></p>
+<p><img src="images/typemappingclasses.jpg" alt="typemappingclasses"/></p>
<p>There is one final level of indirection. How do we know which type mapping to use for a particular message? This is determined by the encoding which is specified in the message. A <i>type mapping registry</i> maintains a map from encoding name (URI) to type mapping. Note that the XML data type QNames are defined by the encoding.</p>
-<p><img src="images/typemappingclasses.jpg"/></p>
+<p><img src="images/typemappingclasses.jpg" alt="typemappingclasses"/></p>
<p>So, in summary, to encode a Java object or primitive data value to a XML datatype or to decode the latter to the former, we need to know:</p>
@@ -353,15 +282,11 @@
</section>
-<a name="WSDLToolsSubsystem"/>
-<section>
-<title>WSDL Tools Subsystem</title>
+<section name="WSDL Tools Subsystem">
<p>The WSDL Tools subsystem contains WSDL2Java and Java2WSDL. The Axis runtime does not depend on these tools -- they are just there to make life easier for the user. </p>
-<a name="WSDL2Java"/>
-<section>
-<title>WSDL2Java</title>
+<subsection name="WSDL2Java">
<p>This tool takes a description of a web service written in WSDL and emits Java artefacts used to access the web service.</p>
@@ -373,41 +298,33 @@
<li>The actual WSDL2Java emitters, one for each file generated: JavaInterfaceWriter, JavaStubWriter, etc.</li>
</ul>
-</section>
+</subsection>
-<a name="Java2WSDL"/>
-<section>
-<title>Java2WSDL</title>
+<subsection name="Java2WSDL">
<p>tbd.</p>
-</section>
+</subsection>
</section>
-<a name="InteractionDiagrams"/>
-<section>
-<title>Interaction Diagrams</title>
-
-<a name="ClientSideProcessing"/>
-<section>
-<title>Client Side Processing</title>
+<section name="Interaction Diagrams">
+
+<subsection name="Client Side Processing">
<p>The client side Axis processing constructs a Call object with associated Service, MessageContext, and request Message as shown below before invoking the AxisClient engine.</p>
-<p><img src="images/clientobjects.jpg" height="120" width="349"/></p>
+<p><img src="images/clientobjects.jpg" height="120" width="349" alt="clientobjects"/></p>
<p>An instance of Service and its related AxisClient instance are created before the Call object. The Call object is then created by invoking the Service.createCall <i>factory method</i>. Call.setOperation creates a Transport instance, if a suitable one is not already associated with the Call instance. Then Call.invoke creates a MessageContext and associated request Message, drives AxisClient.invoke, and processes the resultant MessageContext. This significant method calls in this sequence are shown in the following interaction diagram.</p>
-<p><img src="images/clientinteraction.jpg" height="503" width="731"/></p>
+<p><img src="images/clientinteraction.jpg" height="503" width="731" alt="clientinteraction"/></p>
-</section>
+</subsection>
</section>
-<a name="Pluggable-ComponentDiscovery"/>
-<section>
-<title>Pluggable-Component Discovery</title>
+<section name="Pluggable-Component Discovery">
<p>While most pluggable components infrastructures (jaxp/xerces, commons-logging, etc) provide discovery features, it is foreseen that there are situations where these may evolve over time. For example, as leading-edge technologies are reworked and adopted as standards, discovery mechanisms are likely to change.</p>
@@ -415,28 +332,24 @@
</section>
-<a name="OpenIssues"/>
-<section>
-<title>Open Issues</title>
+<section name="Open Issues">
<ol>
<li>The relationship between the Axis subsystems needs to be documented and somewhat cleaned up as there is leakage of responsibilities between some of the subsystems. For example, there is some SOAP and HTTP bias in the basic MessageContext type and associated classes.</li>
<li>What classes are included in the "encoding" subsystem? Are the encoding and message model subsystems independent of the other subsystems which depend on "message flow"?</li>
<li>(Possibly related to the previous issue) How should we distribute the classes in the above diagram between the Axis subsystems taking into account SOAP-specific and HTTP-specific features?</li>
<li>The Axis Engine currently knows about three layers of handlers: transport, global, and service. However, architecturally, this is rather odd. What "law" of web services ensures that there will always and only ever be <i>three</i> layers? It would be more natural to use Targeted Chains with their more primitive notion of request, pivot, and response Handlers. We would then implemented the Axis Engine as a Targeted Chain whose pivot Handler is itself a Targeted Chain with global request and response Handlers and a service pivot Handler (which is itself a Targeted Chain as we have just described). Such an Axis Engine architecture is shown in the diagram below.
- <p><img src="images/stcengine.jpg" height="312" width="667"/></p>
+ <p><img src="images/stcengine.jpg" height="312" width="667" alt="stcengine"/></p>
</li>
<li>WSDDService.faultFlows is initialised to an empty Vector and there is no way of adding a fault flow to it. Is this dead code or is something else missing?</li>
<li>If a fault occurs after the pivot Handler, should the backwards scan notify Handlers which were invoked prior to the pivot Handler? The current implementation does notify such Handlers. However, this is not consistent with the processing of faults raised in a downstream system and stored in the message context by the pivot Handler. These faults are passed through any response Handlers, but do not cause onFault to be driven in the local engine.
<p>We need to consider what's going on here. If you take a sequence of Handlers and then introduce a distribution boundary into the sequence, what effect should that have on the semantics of the sequence in terms of its effects on message contexts? The following diagram shows a client-side
Handler sequence invoking a server-side Handler sequence. We need to consider how the semantics of this combined sequence compares with the sequence formed by omitting the transport-related Handlers.</p>
- <p><img src="images/pivots2.jpg" height="413" width="658"/></p>
+ <p><img src="images/pivots2.jpg" height="413" width="658" alt="pivots2"/></p>
</li>
</ol>
</section>
-</section>
-
</body>
</document>
\ No newline at end of file