You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by gl...@apache.org on 2002/01/22 16:35:12 UTC
cvs commit: xml-axis/java/docs ClientMessagePath.jpg architecture-guide.html chainclasses.jpg clientinteraction.jpg clientobjects.jpg engineclasses.jpg messagecontext.jpg pivots2.jpg stcengine.jpg subsystems.jpg targetedchainclasses.jpg wsddclasses.jpg ServerMessagePath.jpg index.html integration-guide.html
glyn 02/01/22 07:35:12
Modified: java/docs ServerMessagePath.jpg index.html
integration-guide.html
Added: java/docs ClientMessagePath.jpg architecture-guide.html
chainclasses.jpg clientinteraction.jpg
clientobjects.jpg engineclasses.jpg
messagecontext.jpg pivots2.jpg stcengine.jpg
subsystems.jpg targetedchainclasses.jpg
wsddclasses.jpg
Log:
Dump draft architecture guide to cvs.
Revision Changes Path
1.2 +216 -173 xml-axis/java/docs/ServerMessagePath.jpg
<<Binary file>>
1.5 +3 -0 xml-axis/java/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/index.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- index.html 21 Nov 2001 19:47:48 -0000 1.4
+++ index.html 22 Jan 2002 15:35:11 -0000 1.5
@@ -44,6 +44,9 @@
<a href="integration-guide.html">Integration Guide</a> - Description of
APIs and development direction to allow integration into an existing web
application server.</li>
+
+<li>
+<a href="architecture-guide.html">Architecture Guide</a> - Axis design concepts and rationale.</li>
</ul>
</ul>
1.3 +6 -83 xml-axis/java/docs/integration-guide.html
Index: integration-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/integration-guide.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- integration-guide.html 13 Dec 2001 05:10:57 -0000 1.2
+++ integration-guide.html 22 Jan 2002 15:35:11 -0000 1.3
@@ -28,7 +28,6 @@
<h3>
Table of Contents</h3>
<a href="#Introduction">Introduction</a>
-<br><a href="#Architectural Overview">Architectural Overview</a>
<br><a href="#Pluggable APIs">Pluggable APIs</a>
<br> <a href="#System Management Plug">System Management</a>
<br> <a href="#Logging/Tracing Plug">Logging/Tracing</a>
@@ -39,90 +38,14 @@
<br> <a href="#Encoding Plug">Encoding</a>
<h2>
<a NAME="Introduction"></a>Introduction</h2>
-This guide presents a brief architectural overview of AXIS, but its primary
-purpose is to present how AXIS can be integrated into an existing web application
+The primary purpose of this guide is
+to present how AXIS can be integrated into an existing web application
server, such as Tomcat or WebSphere, for example. AXIS has a number
of Pluggable APIs that are necessary for such an integration.
-<h2>
-<a NAME="Architectural Overview"></a>Architectural Overview</h2>
-
-<p>Axis consists of several subsystems working together. In this section we'll
- give you an overview of how the package works, but for more details please see
- the Axis Architecture Guide, a separate document.</p>
-<h3>Handlers and the Message Path in Axis</h3>
-<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
- oder 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. We'll go into a little more detail on this
- in a bit.</p>
-<p>There are two basic ways which Axis is invoked:</p>
-<ol>
- <li>As a <b>server</b>, a <b>Transport Listener</b> will create a MessageContext
- and invoke the Axis processing framework.</li>
- <li>As a <b>client</b>, application code (aided in most cases by the client
- programming model of Axis) will generate a MessageContext and invoke the Axis
- processing framework.</li>
-</ol>
-<p>In either case, the Axis framework's job is simply to pass the resulting MessageContext
- through a configurable set of Handlers, each of which has an opportunity to
- do whatever it is designed to do with the MessageContext. The message path (for
- the server side) looks like this:</p>
-<p><img src="ServerMessagePath.jpg" width="720" height="540"></p>
-<p>(In the diagram above, each of the small cylinders represents a Handler.)</p>
-<p>A message arrives (in some protocol-specific manner) at a Transport Listener.
- Let's posit that in this case it's an 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 case, an example
- would be setting the property "http.SOAPAction" to the value of the
- SOAPAction HTTP header. The Transport Listener also sets the <b>transportName</b>
- String on the MessageContext - in this case we set it to "http". Once
- the MessageContext is ready to go, the Listener hands it into the AxisEngine.</p>
-<p>The AxisEngine's first job is to look up the transport by name. This will result
- in an object which contains a <b>request</b> flow, a <b>response</b> flow, or
- perhaps both. If a transport request flow exists, it will be invoked, passing
- the MessageContext into the invoke() method. This will result in calling all
- the Handlers specified in the request flow configuration.</p>
-<p>After the transport request handler, the engine locates a global request flow,
- if configured (in the <requestFlow> element of the WSDD <globalConfiguration>,
- as explained in the WSDD deployment section later in this document), and then
- invokes any Handlers specified therein.</p>
-<p>At some point during the processing up until now, some Handler has hopefully
- set the <b>serviceHandler</b> field of the MessageContext (this is usually done
- in the HTTP transport by the "URLMapper" Handler, which maps a URL
- like "http://localhost/axis/services/AdminService" to the "AdminService"
- service). This field determines the Handler we'll invoke to execute service-specific
- functionality, such as making an RPC call on a back-end object. Services in
- Axis are typically instances of the "SOAPService" class (org.apache.axis.handlers.soap.SOAPService),
- which may contain <b>request</b> and <b>response</b> flows (similar to what
- we saw at the transport and global levels), and must contain a <b>provider</b>,
- which is simply a Handler responsible for implementing the actual back end logic
- of the service.</p>
-<p>In typical RPC examples, 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>
-<h3>The Message Path on the Client</h3>
-<p>The Message Path on the client side is similar, except the order of scoping
- is reversed. In other words:</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 flows. The service
- request and response flows serve to do any service-specific processing of the
- message on its way out of the system, and also for the response message on its
- way back to the caller.</p>
-<p>After the service request flow, the global requestFlow, 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 back up through the response
- flows - first the transport, then the global, and finally the service.</p>
+<p>
+The reader may find useful background information in the
+<a href="architecture-guide.html">Architecture Guide</a>.
+
<h2>
<a NAME="Pluggable APIs"></a>Pluggable APIs</h2>
The following are the points that are pluggable in order to integrate AXIS
1.1 xml-axis/java/docs/ClientMessagePath.jpg
<<Binary file>>
1.1 xml-axis/java/docs/architecture-guide.html
Index: architecture-guide.html
===================================================================
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.75 [en] (WinNT; U) [Netscape]">
<title>Axis Architecture Guide</title>
<!-- saved from url=(0022)http://internet.e-mail -->
<style type="text/css">
<!--
.example { background:#ccccff }
.xml { background:#eeeeee }
body { font-family: Verdana, Arial, Helvetica, sans-serif; margin-left: 40px}
h2 { text-decoration: underline; background-color: #DCE1FF; background-position: left; margin-left: -30px}
h3 { margin-left: -10px}
h1 { margin-left: -30px}
-->
</style>
</head>
<body text="#000000" bgcolor="#FFFFFF">
<center>
<h1>
<img SRC="axis.jpg" height=96 width=176></h1></center>
<h1>
Axis Architecture Guide</h1>
<font face="Lucida Sans"><font color="#CC0000"><font size=+3>Under construction
....</font></font></font>
<br><i>Post-Alpha 3 Version</i>
<br><i>Feedback: <a href="mailto:axis-dev@xml.apache.org">axis-dev@xml.apache.org</a></i>
<h3>
Contents</h3>
<a href="#Introduction">Introduction</a>
<br><a href="#Overview">Architecture Overview</a>
<br><a href="#Subsystems">Subsystems</a>
<br><a href="#Message Flow">Message Flow Subsystem</a>
<br> <a href="#Handlers">Handlers and Chains</a>
<br> <a href="#Message Contexts">Message Contexts</a>
<br> <a href="#Engine">Engine</a>
<br><a href="#Administration Subsystem">Administration Subsystem</a>
<br><a href="#Sequence Diagrams">Interaction Diagrams</a>
<br> <a href="#Client Interaction">Client Side Processing</a>
<br><a href="#Open Issues">Open Issues</a>
<h2>
<a NAME="Introduction"></a>Introduction</h2>
This guide records some of the rationale of the architecture and design
of Axis.
<h2>
<a NAME="Overview"></a>Architectural Overview</h2>
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.
<h3>
Handlers and the Message Path in Axis</h3>
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 oder 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>There are two basic ways in which Axis is invoked:
<ol>
<li>
As a <b>server</b>, a <b>Transport Listener</b> will create a MessageContext
and invoke the Axis processing framework.</li>
<li>
As a <b>client</b>, application code (usually aided by the client programming
model of Axis) will generate a MessageContext and invoke the Axis processing
framework.</li>
</ol>
In either case, the Axis framework's job is simply to pass the resulting
MessageContext through a configurable set of Handlers, each of which has
an opportunity to do whatever it is designed to do with the MessageContext.
<h3>
Message Path on the Server</h3>
The server side message path is shown in the following diagram. The small
cylinders represent Handlers and the larger, enclosing cylinders represent
Chains.
<br><img SRC="ServerMessagePath.jpg" VSPACE=30 height=282 width=602>
<br>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>The AxisEngine's first job is to look up the transport by name. The
transport is an object which contains a <b>request</b> Chain, a <b>response</b>
Chain, or perhaps both. A <b>Chain</b> is a Handler consisting of a sequence
of Handlers which are invoked in turn -- more on Chains later. If a transport
request Chain exists, it will be invoked, passing the MessageContext into
the invoke() method. This will result in calling all the Handlers specified
in the request Chain configuration.
<p>After the transport request Handler, the engine locates a global request
Chain, if configured (in the <requestFlow> element of the WSDD <globalConfiguration>,
as explained in the WSDD deployment section later in this document), and
then invokes any Handlers specified therein.
<p>At some point during the processing up until now, some Handler has hopefully
set the <b>serviceHandler</b> field of the MessageContext (this is usually
done in the HTTP transport by the "URLMapper" Handler, which maps a URL
like "http://localhost/axis/services/AdminService" to the "AdminService"
service). This field determines the Handler we'll invoke to execute service-specific
functionality, such as making an RPC call on a back-end object. Services
in Axis are typically instances of the "SOAPService" class (org.apache.axis.handlers.soap.SOAPService),
which may contain <b>request</b> and <b>response</b> Chains (similar to
what we saw at the transport and global levels), and must contain a <b>provider</b>,
which is simply a Handler responsible for implementing the actual back
end logic of the service.
<p>In typical RPC examples, 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.
<h3>
The Message Path on the Client</h3>
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.
<br><img SRC="ClientMessagePath.jpg" VSPACE=30 height=281 width=592>
<br>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 serve to do 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>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.
<h2>
<a NAME="Subsystems"></a>Subsystems</h2>
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>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 and SMTP transports are independent of each other but
may be used together.
<p><img SRC="subsystems.jpg" height=217 width=652>
<h2>
<a NAME="Message Flow"></a>Message Flow Subsystem</h2>
<h3>
<a NAME="Handlers"></a>Handlers and Chains</h3>
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.
<br><img SRC="pivots.jpg" height=240 width=403>
<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>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
diagram:
<br><img SRC="chainclasses.jpg" height=297 width=267>
<p>Back to message processing -- a message is processed by passing through
the appropriate Chains. A message context is used to pass the message and
associated environment through the sequence of Handlers. The model is that
Axis Chains are constructed offline by having Handlers added to them one
at a time. Then they are made online and message contexts start to flow
through the Chains. Multiple message contexts may flow through a single
Chain concurrently. Handlers are never added to a Chain once it goes online.
If a Handler needs to be added or removed, the Chain must be 'cloned',
the modifications made to the clone, and then the clone made online and
the old Chain retired when it is no longer in use. Message contexts that
were using the old Chain continue to use it until they are finished. This
means that Chains do not need to cope with the addition and removal of
Handlers while the Chains are processing message contexts -- an important
simplification.
<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.
<h4>
Targeted Chains</h4>
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><img SRC="targetedchainclasses.jpg" height=288 width=253>
<p>A service is a special kind of Targeted Chain in which the pivot Handler
is known as a "provider".
<h4>
Fault Processing</h4>
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><i>Need to explain how "FaultableHandlers" and "WSDD Fault Flows" fit
in.</i>
<h3>
<a NAME="Message Contexts"></a>Message Contexts</h3>
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.
<br><img SRC="messagecontext.jpg" height=140 width=597>
<br>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.
But if we were to factor out a more abstract Message Context interface,
we would then be then faced with a problem. Some Handlers, most likely
in the global layer, would need to accept a Message Context with a particular
concete type (e.g. for a HTTP transport) and produce a Message Context
of a different concrete type (e.g. for a SOAP service) and so Handler.invoke
would need a more complex signature.
<h3>
<a NAME="Engine"></a>Engine</h3>
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:
<br><img SRC="engineclasses.jpg" height=242 width=169>
<h2>
<a NAME="Administration Subsystem"></a>Administration Subsystem</h2>
The administration subsystem provides a set of factories for runtime artefacts
such as Chains and SOAPServices.
<h3>
WSDD-Based Administration</h3>
WSDD is an XML grammer for statically configuring an administration subsystem.
Its structure 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").
<br><img SRC="wsddclasses.jpg" height=381 width=655>
<h2>
<a NAME="Sequence Diagrams"></a>Interaction Diagrams</h2>
<h3>
<a NAME="Client Interaction"></a>Client Side Processing</h3>
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><img SRC="clientobjects.jpg" height=120 width=349>
<br>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.
<br><img SRC="clientinteraction.jpg" height=503 width=731>
<h2>
<a NAME="Open Issues"></a>Open Issues</h2>
<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, WSDD has leaked into the basic engine
architecture. Also, there is some SOAP and HTTP bias in the basic MessageContext
type and associated classes.</li>
<li>
What classes are included in the "encoding" and "message model" subsystems?
Are these 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 thee 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.</li>
<br><img SRC="stcengine.jpg" height=312 width=667>
<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.</li>
<br>
<p>
<br>
<br>
<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.
<br><img SRC="pivots2.jpg" height=413 width=658>
<li>
The administration subsystem is currently hardcoded to use WSDD. A generic
set of factory interfaces needs factoring out to enable non WSDD based
administration subsystems to be used with Axis.</li>
</ol>
</body>
</html>
1.1 xml-axis/java/docs/chainclasses.jpg
<<Binary file>>
1.1 xml-axis/java/docs/clientinteraction.jpg
<<Binary file>>
1.1 xml-axis/java/docs/clientobjects.jpg
<<Binary file>>
1.1 xml-axis/java/docs/engineclasses.jpg
<<Binary file>>
1.1 xml-axis/java/docs/messagecontext.jpg
<<Binary file>>
1.1 xml-axis/java/docs/pivots2.jpg
<<Binary file>>
1.1 xml-axis/java/docs/stcengine.jpg
<<Binary file>>
1.1 xml-axis/java/docs/subsystems.jpg
<<Binary file>>
1.1 xml-axis/java/docs/targetedchainclasses.jpg
<<Binary file>>
1.1 xml-axis/java/docs/wsddclasses.jpg
<<Binary file>>