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 07:57:02 UTC
svn commit: r188703 - /webservices/axis/trunk/java/xdocs/userguide.html
Author: jaliya
Date: Mon Jun 6 22:57:01 2005
New Revision: 188703
URL: http://svn.apache.org/viewcvs?rev=188703&view=rev
Log:
Modified
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=188703&r1=188702&r2=188703&view=diff
==============================================================================
--- webservices/axis/trunk/java/xdocs/userguide.html (original)
+++ webservices/axis/trunk/java/xdocs/userguide.html Mon Jun 6 22:57:01 2005
@@ -122,13 +122,13 @@
properly. (See <a href="installationguide.htm">Installation Guide</a>)</p>
<h3>MyService</h3>
<p>First let's see how we can write a simple Web Service (MyService) and deploy it. For this purpose we will create a Web Service with two operations as follows.</p>
-<pre class="style1 style2 style3">public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
-public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and responds with another OMElement after processing.</pre>
+<pre><code>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
+public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and responds with another OMElement after processing.</code></pre>
<p>Complete code for this example Web Service (MyService) can be found in the "Axis2Home/samples/userguide/src" directory under
"userguide/example1" package. As you can see, the two operations are very simple and need no explanations on what they are doing. So let's see how we can write the deployment descriptors for the service and deploy it.</p>
<p>Axis2 uses "service.xml" to keep configurations for a Web Service. Each Web Service deployed
in Axis2 needs a "service.xml" containing the configurations. "service.xml" for MyService will be as follows; we will see what each parameter means later.</p>
-<pre class="style1 style2 style3"><service name="MyService"><br> <description><br> This is a sample Web Service with two operations, echo and ping.<br> </description><br> <parameter name="ServiceClass" locked="xsd:false">userguide.example1.MyService</parameter><br> <operation name="echo"><br> <messageReceiver class="org.apache.axis.receivers.RawXMLINOutMessageRecevier"/><br> </operation><br> <operation name="ping"><br> <messageReceiver class="org.apache.axis.receivers.RawXMLINOnlyMessageRecevier"/><br> </operation><br> </service></pre>
+<pre><code><service name="MyService"><br> <description><br> This is a sample Web Service with two operations, echo and ping.<br> </description><br> <parameter name="ServiceClass" locked="xsd:false">userguide.example1.MyService</parameter><br> <operation name="echo"><br> <messageReceiver class="org.apache.axis.receivers.RawXMLINOutMessageRecevier"/><br> </operation><br> <operation name="ping"><br> <messageReceiver class="org.apache.axis.receivers.RawXMLINOnlyMessageRecevier"/><br> </operation><br> </service></code></pre>
<p>As it can be seen, first line of the "service.xml" gives the name of the Web Service. This is used in the URL to the service as the service name. Next comes the description and the service class. The next two xml tags describe the operations that are available in this service with respective message receivers. For the "echo" operation we have used a <strong>RawXMLINOutMessageRecevier</strong> since it is an
IN-OUT operation. For IN-ONLY operation, "ping" we have used <strong>RawXMLINOnlyMessageRecevier</strong> as the message receiver. </p>
<p>Axis2 use ".aar" (Axis Archive) file as the deployment package for Web Services. So,
@@ -223,7 +223,7 @@
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 {
+<pre><code> try {
OMElement payload = ClientUtil.getEchoOMElement();
<span class="style10">Call call = new Call();
call.setTo(targetEPR);
@@ -243,7 +243,7 @@
e.printStackTrace();
}
}
-</pre></p>
+</code></pre></p>
<p>The green lines shows the set of operations that you need to perform in-order to invoke a web service while the rest is used to create the OMElement that needs to be sent and to display the response OMElement. To test this
client you can use the "TestEchoBlockingClient.bat" that can be found in the "Axis2Home/samples/userguide/src/userguide/clients/bin" directory. The
.bat or .sh files show the required jars that needs to be there in the classpath for one to write Web Service clients using Axis2. So if you can see the response OMElement printed in your command line (as shown below) then you have successfully tested the client as well. </p>
@@ -251,7 +251,7 @@
<h3>PingClient</h3>
<p>In the Web Service "MyService" we had a IN-ONLY operation with the name "ping" (see Web Services Using Axis2). So let's write a client to invoke this operation as well.
The client code will be as follows.</p>
-<pre class="style1 style2 style3"> try {
+<pre><code> try {
OMElement payload = ClientUtil.getPingOMElement();
MessageSender msgSender = new MessageSender();
@@ -262,7 +262,7 @@
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
}
-</pre>
+</code></pre>
</p>
<p>Since we are accessing a IN-ONLY operation we can directly use the "MessageSender" to invoke this operation. As it can be seen in the above code , it is very straight forward to invoke this type of operation. MessageSender will not block the
invocation, hence it will return the control immediately back to the client. You can
@@ -273,12 +273,12 @@
<p>In the EchoBlockingClient once the "call.invokeBlocking("echo", payload);" is called, the client is blocked till the operation is completed. This behavior is not
desirable when there are many Web Service invocations to be done in a single client application. A solution, would be to use a Non-Blocking API to invoke web services. Axis2 provides a callback based non-blocking API for users. </p>
<p>A sample client for this can be found under "Axis2Home/samples/userguide/src/userguide/clients" with the name EchoNonBlockingClient. If we consider the changes that the user may have to do with respect to the "EchoBlockingClient" that we have already seen, it will be as follows.</p>
-<pre class="style1 style2 style3">call.invokeNonBlocking("echo", payload, callback);</pre>
+<pre><code>call.invokeNonBlocking("echo", payload, callback);</code></pre>
<p>The invocation accepts a callback object as a parameter. Axis2 client API provides an
abstract Callback with the following methods.</p>
-<p><pre class="style1 style2 style3">public abstract void onComplete(AsyncResult result);
+<p><pre><code>public abstract void onComplete(AsyncResult result);
public abstract void reportError(Exception e);
-public boolean isComplete() {}</pre></p>
+public boolean isComplete() {}</code></pre></p>
<p>The user is expected to implement the "onComplete " and "reportError " methods of their extended call back class. Axis2 engine calls the onComplete method once the Web Service
response is received by the Axis2 Client API (Call). This will eliminate the blocking nature of the Web Service invocations and provides the user with the flexibility to use Non Blocking API for Web Service
Clients.</p>
@@ -300,7 +300,7 @@
services (IN-OUT operations) using two separate transport connections. Let's see how we can do it using an example. Following code
fragment shows how to invoke the same "echo" operation, using Non-Blocking API with two transport
connections<strong>. The ultimate asynchrony!!</strong></p>
-<pre class="style1 style2 style3"> try {
+<pre><code> try {
OMElement payload = ClientUtil.getEchoOMElement();
Call call = new Call();
@@ -338,15 +338,15 @@
//Wait till the callback receives the response.
while (!callback.isComplete()) {
Thread.sleep(1000);
- }</pre>
-<pre class="style1 style2 style3"> <font color="#33CC00">call.close();</font>
+ }</code></pre>
+<pre><code> <font color="#33CC00">call.close();</font>
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
} catch (Exception ex) {
ex.printStackTrace();
}
-</pre>
+</code></pre>
<p>The three changes that we need do to the EchoNonBlockingClient are shown in the "green" color. Since our correlation mechanism is based on addressing we need
to first "<strong>engage</strong>" the addressing module.<span class="style15">
<font color="#000000"><b>"call.engageModule(new
@@ -361,7 +361,7 @@
phase (See <a href="Axis2ArchitectureGuide.html">Architecture Guide</a> for more
details about phases) and hence "engaging" means simply adding module reference in the "server.xml" (NOT the "service.xml"). Please add the following line to the "server.xml" that you can find in the "/webapps/axis2/WEB-INF"
directory in the servlet container. </p>
-<pre class="style1 style2 style3"> <module ref="addressing"/></pre>
+<pre><code> <module ref="addressing"/></code></pre>
<p>Note: Please note that<span class="style15"><font color="#000000"> once you change the "server.xml" you need to restart the servlet container.</font></span></p>
<p>This will enable the addressing in the server side and now you can test the "TestEchoNonBlockingDualClient" using the "TestEchoNonBlockingDualClient.bat" or "TestEchoNonBlockingDualClient.sh" provided under "Axis2Home/samples/userguide/src/userguide/clients/bin" directory.
If you can see the response OMElement printed in the client side, that means you
@@ -407,9 +407,9 @@
<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>
-<pre class="style1 style2 style3">public void init(AxisConfiguration axisSystem) throws AxisFault;//Initialize the module
+<pre><code>public void init(AxisConfiguration axisSystem) throws AxisFault;//Initialize the module
public void shutdown(AxisConfiguration axisSystem) throws AxisFault;//End of module processing
-</pre>
+</code></pre>
<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
@@ -422,7 +422,7 @@
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 {
+<pre><code>public class LogHandler extends AbstractHandler implements Handler {
private Log log = LogFactory.getLog(getClass());
private QName name;
@@ -442,14 +442,14 @@
this.name = name;
}
}
-</pre>
+</code></pre>
<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 "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 ">
+<pre><code><module name="logging" class="userguide.loggingmodule.LoggingModule ">
<inflow>
<handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
<order phase="loggingPhase" />
@@ -473,7 +473,7 @@
<order phase="loggingPhase"/>
</handler>
</INfaultflow>
-</module></pre></p>
+</module></code></pre></p>
<p>As it can be seen there are four phases defined in this "module.xml"</p>
<ol>
@@ -495,10 +495,10 @@
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">
+<pre><code><handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
<order phase="loggingPhase" />
</handler>
-</pre></p>
+</code></pre></p>
<h4>Step 4: Modify the "server.xml"</h4>
@@ -512,7 +512,8 @@
This is an extract of the phase section of the "server.xml".</p>
-<pre class="style1 style2 style3"><!-- ================================================= -->
+<pre><code>
+<!-- ================================================= -->
<!-- Phases -->
<!-- ================================================= -->
<phaseOrder type="inflow">
@@ -522,31 +523,26 @@
<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 -->
+<!-- After Postdispatch phase module author or or service author can add any phase he want -->
<phase name="<font color="#33CC00">loggingPhase</font>"/>
-</phaseOrder></pre>
-
+</phaseOrder>
-<pre class="style1 style2 style3"><phaseOrder type="outflow">
+<phaseOrder type="outflow">
<!-- user can add his own phases to this area -->
<phase name="<font color="#33CC00">loggingPhase</font>"/>
-</phaseOrder></pre>
-
+</phaseOrder>
-<pre class="style1 style2 style3"><phaseOrder type="INfaultflow">
+<phaseOrder type="INfaultflow">
<!-- user can add his own phases to this area -->
<phase name="<font color="#33CC00">loggingPhase</font>"/>
-</phaseOrder></pre>
-
+</phaseOrder>
-<pre class="style1 style2 style3"><phaseOrder type="Outfaultflow">
+<phaseOrder type="Outfaultflow">
<!-- user can add his own phases to this area -->
<phase name="<font color="#33CC00">loggingPhase</font>"/>
</phaseOrder>
-</pre>
+</code></pre>
<p>Shown in green, the custom phase "loggingPhase" is placed in all the flows,
@@ -555,10 +551,8 @@
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>"
@@ -570,7 +564,7 @@
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>">
+<p><pre><cod><service name="<font color="#33CC00">MyServiceWithModule</font>">
<description>
This is a sample Web Service with a logging module engaged.
</description>
@@ -583,7 +577,7 @@
<messageReceiver class="org.apache.axis.receivers.RawXMLINOutMessageRecevier"/>
</operation>
</service>
-</pre></p>
+</code></pre></p>
<p>In this example we have changed the service name (the implementatoin class is