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 ja...@apache.org on 2005/06/07 04:50:48 UTC
svn commit: r188673 - /webservices/axis/trunk/java/xdocs/userguide.html
Author: jaliya
Date: Mon Jun 6 19:50:47 2005
New Revision: 188673
URL: http://svn.apache.org/viewcvs?rev=188673&view=rev
Log:
Added "how to use modules" to the userguide
Modified:
webservices/axis/trunk/java/xdocs/userguide.html
Modified: webservices/axis/trunk/java/xdocs/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/userguide.html?rev=188673&r1=188672&r2=188673&view=diff
==============================================================================
--- webservices/axis/trunk/java/xdocs/userguide.html (original)
+++ webservices/axis/trunk/java/xdocs/userguide.html Mon Jun 6 19:50:47 2005
@@ -52,7 +52,7 @@
<p>This release includes the following features:</p>
<ul>
<li>AXIOM, a SOAP specific streaming XML infoset model for SOAP 1.1/1.2 Messages</li>
- <li>Modules, mechnisum to extend the SOAP Processing Model</li>
+ <li>Modules, mechanism to extend the SOAP Processing Model</li>
<li>Support for WS-Addressing</li>
<li>Client API</li>
<li>Support for One-Way Messaging</li>
@@ -61,7 +61,7 @@
<LI>Synchronous, Using a two way transport</LI>
<LI>Asynchronous, Using a two way transport</LI>
<LI>Synchronous, Using a one way transport</LI>
- <LI>Aynchronous, Using a two way transport</LI>
+ <LI>Asynchronous, Using a two way transport</LI>
</ol>
</li>
<li>Hot deployment of Web Services and Module deployment based on the archived modules </li>
@@ -133,9 +133,9 @@
<p>To create "MyService.aar" user can first create a jar file containing all the files necessary for the service and then rename the "jar" to "aar" so that Axis2 understands it as a service archive.
This has already been created in the "Axis2Home/samples/userguide" directory,
and let's use it.. </p>
-<p>Since this is our first Web Service we need one more step before we
-deploy the service. That is to create a directory named "<b>services</b>" under "webapps/axis2/WEB-INF" of you servlet container. Deploying is just a matter of
-dropping the ".aar" in to this directory and hence please copy the "MyService.aar" into the
+<p>Deploying the service is just a matter of
+dropping the ".aar" in to "services" directory that can be found in
+the "\webapps\axis2\WEB-INF" of your servlet container and hence please copy the "MyService.aar" into the
"<b>services</b>" directory. Once these steps are completed, please start the servlet container (if you have not already started) and check the link "List Available services" in the page http://localhost:8080/axis2/index.jsp and see whether the MyService is deployed properly. If
everything is ok, you will see the following out put.. </p>
<p align="center"><img src="images/userguide/MyServiceDeployed.JPG" width="797" height="654"> </p>
@@ -143,6 +143,79 @@
Axis2 provides an easy way to deploy a Web Services using, index.jsp. (See the
installation guide for more information on this)</p>
<h2> Web Service Clients Using Axis2 </h2>
+<p> Web services can be used to provide wide range of functionality to the users
+ranging from simple less time consuming operations such as "getStockQuote"
+to time consuming business data processing. When we utilize (write client
+applications) these Web Service we cannot use some simple generic invocation
+paradigm that suites all the timing complexities involved in the service
+operations. For example, if we use a single transport channel (such as HTTP) to
+invoke a Web Service with and IN-OUT operation, that take long time to complete,
+then in most of the time we may end up with "connection time outs". On the other
+hand, if there are simultaneous service invocations that we need to
+perform from a single client application, then the use of a "blocking" client
+API will degrade the performance of the client application. Similarly there are
+various other consequences such as One-Way transports come in to play when we
+need to invoke Web Services. So let's try to analyze some common service
+invocation paradigms.</p>
+<p> Many web service engines provide the users with a Blocking and Non-Blocking
+client APIs. </p>
+<ul>
+ <li><b>Blocking API</b> -Once the service invocation is called, the client
+ application hangs and gets the control back only when the operation completes
+ and the client receives a response or a fault. This is the simplest way of
+ invoking Web Services and suites many business situations.</li>
+ <li><b>Non-Blocking API </b>- A callback or polling based API and hence once a
+ service invocation is called, the client application immediately gets the
+ control back and the response is retrieved using the callback object provided.
+ This approach provides the flexibility to the client application to invoke
+ several Web Services simultaneously with out blocking on the operation already
+ invoked.</li>
+</ul>
+<p> Both these mechanism works in the API level and let's name the
+asynchronous behavior that we can get using the Non-Blocking API as <b>API Level
+Asynchrony.</b></p>
+<p> Both these mechanisms use single transport connection to send the request
+and to receive the response. They severely lags the capability of using two
+transport connections for the request and the response (either One-Way of
+Two-Way). So both of these mechanisms fail to address the problem of long
+running transactions (the transport connection may times-out before the
+operation completes). A possible solution would be to use two separate transport
+connections for request and response. The asynchronous behavior that we gain
+using can be called, <b>Transport Level Asynchrony</b>.</p>
+<p> By combining the two we can obtain four differtn invocation patterns for web
+services as shown in the follwing table.</p>
+<table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%" height="99">
+ <tr>
+ <td width="33%" height="19">API (Blocking/Non-Blocking)</td>
+ <td width="33%" height="19"> Dual Transports (Yes/No)</td>
+ <td width="33%" height="19">Description</td>
+ </tr>
+ <tr>
+ <td width="33%" height="19">Blocking</td>
+ <td width="33%" height="19">No</td>
+ <td width="33%" height="19">Simplest and the familiar invocation pattern</td>
+ </tr>
+ <tr>
+ <td width="33%" height="19">Non-Blocking</td>
+ <td width="33%" height="19">No</td>
+ <td width="33%" height="19">Using callbacks or polling</td>
+ </tr>
+ <tr>
+ <td width="33%" height="19">Blocking</td>
+ <td width="33%" height="19">Yes</td>
+ <td width="33%" height="19">This is useful when the service operation is
+ IN-OUT in nature but the transport used is One-Way (e.g. SMTP)</td>
+ </tr>
+ <tr>
+ <td width="33%" height="19">Non-Blocking</td>
+ <td width="33%" height="19">Yes</td>
+ <td width="33%" height="19">This is can be used to gain the maximum
+ asynchronous behavior. No blocking in the API level and also in the
+ transport level</td>
+ </tr>
+</table>
+<p><b>Axis2 provides the user with all these possibilities to invoke Web
+Services and let's see how to use them Now!</b></p>
<h3>EchoBlockingClient</h3>
<p>Axis2 provides the user with several invocation patterns for Web Services, ranging from pure blocking single channel invocations to a non-blocking dual channel invocations. First let's see how we can write a client to invoke "echo" operation of "MyService" using the simplest good old blocking invocation. The client code that you need to write will be as follows.</p>
<pre class="style1 style2 style3"> try {
@@ -303,24 +376,29 @@
<p>Axis2 provides an extended support for modules (See
<a href="Axis2ArchitectureGuide.html">Architecture Guide</a> for more details
about modules in axis2). Let's see how we can create a custom module and deploy
-it to the MyService that we have created earlier. Creating and deploying a
-custom moduel for a service in Axis2 can be described using the following steps.</p>
+it to the MyService that we have created earlier. Following steps shows the
+actions that needs to be performed to deploy a custom module for a given Web
+Service.</p>
<ol>
<li>Create the Module Implementation</li>
<li>Create the Handlers</li>
<li>Create the moduel.xml</li>
+ <li>Modify the "server.xml" (if you need custom phases)</li>
+ <li>Modify the "service.xml" to engage modules at the deployment time.</li>
<li>Package in a ".mar" (Module Archive)</li>
- <li>Deploy in Axis2</li>
+ <li>Deploy the module in Axis2</li>
</ol>
<h3>MyService with a Logging Module
</h3>
-<p>First let's write the LoggingModule (We will write a simple logging module
-that will simply log the messages). The module has a similar file
-hierarchy as shown below.</p>
+<p>Let's write a simple logging module for our sample. This module contains one
+handler that just logs the message that is passed though it. Axis2 uses ."mar"
+(Module Archive) to deploy modules in Axis2. Following diagram shows the file
+structure inside that needs to be there in the ".mar" archive. Let's create all
+these and see how it works.</p>
<p>
<img border="0" src="images/userguide/ModuleView.JPG" width="185" height="120"></p>
<h4>
-Step1</h4>
+Step1 : LoggingModule Class</h4>
<p>LoggingModule is the implementation class of the Axis2 module. Axis2 modules
should implement the "org.apache.axis.modules.Module" interface with the
following methods.</p>
@@ -330,13 +408,15 @@
<p>These methods can be used to control the module initialization and the
termination. With the input parameter AxisConfiguration, the user is provided
with the complete configuration hierarchy and this can be used to fine tune the
-module behavior by the module writers. For the simple logging service that we
-are going to write we can keep these methods blank in our implementation class.</p>
-<h4>Step2</h4>
-<p>A module in axis2 can contain, one or more handlers that performs various
+module behavior by the module writers. For the simple logging service, we can keep these methods blank in our implementation class.</p>
+<h4>Step2 : LogHandler</h4>
+<p>A module in axis2 can contain, one or more handlers that perform various
SOAP header processing at different phases. (See<a href="Axis2ArchitectureGuide.html">
Architecture Guide</a> for more information about phases). For the logging
-module we will write a handle with the following methods.</p>
+module we will write a handle with the following methods. "public void
+invoke(MessageContext ctx);" is the method that is called by the Axis2 engine
+when the control is passed to the handler. "public void revoke(MessageContext
+ctx);" is called when the handlers are revoked by the Axis2 engine. </p>
<pre class="style1 style2 style3">public class LogHandler extends AbstractHandler implements Handler {
private Log log = LogFactory.getLog(getClass());
private QName name;
@@ -358,41 +438,192 @@
}
}
</pre>
-<h4>Step3</h4>
+<h4>Step3 : module.xml</h4>
<p>"module.xml" contains the deployment configurations for a particular module.
It contains details such as Implementation class of the module (in this example
-it is the "LoggingModuel" class and the various handlers that will run in
+it is the "LoggingModule" class and the various handlers that will run in
different phases. "module.xml" for the logging module will be as follows.</p>
<p>
<pre class="style1 style2 style3"><module name="logging" class="userguide.loggingmodule.LoggingModule ">
<inflow>
-<handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
-<order phase="loggingPhase" />
-</handler>
+ <handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase" />
+ </handler>
</inflow>
<outflow>
-<handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
-<order phase="loggingPhase"/>
-</handler>
+ <handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
</outflow>
<Outfaultflow>
-<handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
-<order phase="loggingPhase"/>
-</handler>
+ <handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
</Outfaultflow>
<INfaultflow>
-<handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler">
-<order phase="loggingPhase"/>
-</handler>
+ <handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
</INfaultflow>
</module></pre></p>
-<h3> </h3>
+<p>As it can be seen there are four phases defined in this "module.xml"</p>
+<ol>
+ <li>inflow
+ - Represents the handler chain that will run when a message is coming in.</li>
+ <li>outflow
+ - Represents the handler chain that will run when the message is going out.</li>
+ <li>Outfaultflow - Represents the handler chain
+ that will run when there is a fault and the the fault is going out</li>
+ <li>INfaultflow - Represents the handler
+ chain that will run when there is a fault and the the fault is coming in</li>
+</ol>
+
+<p>
+<p>Following set of tags describe the name of the handler, handler class and the
+phase in which this handler going to run."InFlowLogHandler" is the name given
+for the particular instance of this handler. The property, class is the actual
+implementation class for this handler. Since we are writing logging handler, we
+can reuse the same handler in all these phases, however this may not be the same
+for all the modules. "<order phase="loggingPhase" />" describes the phase in
+which this handler runs. </p>
+<pre class="style1 style2 style3"><handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+<order phase="loggingPhase" />
+</handler>
+</pre></p>
+
+<h4>Step 4: Modify the "server.xml"</h4>
+
+
+<p>In this handler the phase "loggingPhase" is defined by the module writer. It
+is not a pre-defined handler phase and hence the module writer should introduce
+it to the "server.xml" (NOT the service.xml) so that Axis2 engine knows where to
+place the handler in different "flows" (<br>
+InFlow, OutFlow, etc...). Following xml lines shows the respective changes to
+the "server.xml" in order for us to deploy this logging module in Axis2 engine.
+This is an extract of the phase section of the "server.xml".</p>
+
+
+<pre class="style1 style2 style3"><!-- ================================================= -->
+<!-- Phases -->
+<!-- ================================================= -->
+<phaseOrder type="inflow">
+<!-- System pre defined phases -->
+ <phase name="TransportIn"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch"/>
+ <phase name="PostDispatch"/>
+<!-- System pre defined phases -->
+</pre>
+
+
+<pre class="style1 style2 style3"><!-- After Postdispatch phase module author or or service author can add any phase he want -->
+<phase name="<font color="#33CC00">loggingPhase</font>"/>
+</phaseOrder></pre>
+
+
+<pre class="style1 style2 style3"><phaseOrder type="outflow">
+<!-- user can add his own phases to this area -->
+<phase name="<font color="#33CC00">loggingPhase</font>"/>
+</phaseOrder></pre>
+
+
+<pre class="style1 style2 style3"><phaseOrder type="INfaultflow">
+<!-- user can add his own phases to this area -->
+<phase name="<font color="#33CC00">loggingPhase</font>"/>
+</phaseOrder></pre>
+
+
+<pre class="style1 style2 style3"><phaseOrder type="Outfaultflow">
+<!-- user can add his own phases to this area -->
+<phase name="<font color="#33CC00">loggingPhase</font>"/>
+</phaseOrder>
+</pre>
-<h3> </h3>
+
+<p>Shown in green, the custom phase "loggingPhase" is placed in all the flows,
+and hence that phase will be called in all the message flows in the engine.
+Since our module is associated with this phase, the LogHandler is now have a
+phase for it to get executed.
+</p>
+
+
+<h4>Step5 : Modify the "service.xml"</h4>
+
+
+<p>Up to this point we have created the required classes and the configuration
+descriptions for the logging module and by changing the "server.xml" we have
+created the required phases for the logging module. Now the next step is to "<b>engage</b>"
+(use) this module in one of our services. For this, let's use the same Web
+Service that we have used throughout the user guide, the MyService. However,
+since we need to modify the "service.xml" of the MyService in order for us
+engage this module, we use a separate Web Service, but with the similar
+operations. The code for this service can be found in the "Axis2Home/samples/userguide/src/userguide/example2"
+directory. The simple changes that we have done to he "service.xml' are shown in
+the green color in the following lines of xml.</p>
+
+<p><pre class="style1 style2 style3"><service name="<font color="#33CC00">MyServiceWithModule</font>">
+<description>
+This is a sample Web Service with a logging module engaged.
+</description>
+<font color="#33CC00"><module ref="logging"/></font>
+<parameter name="ServiceClass" locked="xsd:false">userguide.example2.MyService</parameter>
+<operation name="echo">
+<messageReceiver class="org.apache.axis.receivers.RawXMLINOutMessageRecevier"/>
+</operation>
+<operation name="ping">
+<messageReceiver class="org.apache.axis.receivers.RawXMLINOutMessageRecevier"/>
+</operation>
+</service>
+</pre></p>
+
+
+<p>In this example we have changed the service name (the implementatoin class is
+very similar to what we have used ealier although it is in a different package).
+In addition we have added the line <b>"<module ref="logging"/>"</b> to the "service.xml".
+This informs the Axis2 engine that the module "logging" should be engaged for
+this service. The handler in side the module will be executed in their
+respective phases as described by the "module.xml".</p>
+
+
+<p><b>Step6 : Packaging</b></p>
+
+
+<p>Before deploying the module we need to create the ".mar" file for this
+module. This can be done, using the "jar" command and then renaming the created
+jar file, or you can find the "Logging.mar" that is already created for you in
+the "Axis2Home/samples/userguide" directory.</p>
+
+
+<h4>Step7 : Deploy the module in Axis2</h4>
+
+
+<p>Deploying a module in Axis2 require the user to create a directory with the
+name "modules" in the "webapps/axis2/WEB-INF" directory of their servlet
+container and then copying the ".mar" file to that directory. So let's first
+create the "modules" directory and drop the "LoggingModule.mar" in to this
+directory.</p>
+
+
+<p>Although the required changes to the "service.xml" is very little, we have
+created a separate service archive (MyServiceWithModule.aar) for users to just
+deploy and see. Please deploy this service using the same steps that you use to
+deploy "MyService" and copy the "LoggingModule.mar" file to the "modules"
+directory. Then by
+</p>
+
+
+<p>NO NEED TO CREATE SEVICES DIRECTORY NOW</p>
+
+
+<p>THIS IS A TEMPORARY SOLUTION IN THE SERVER.XML</p>
+
+
+<p><br>
+</p>
<h3>Other Samples //Links to Google Samples </h3>
<h2>Tools</h2>