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/06 06:58:27 UTC
svn commit: r180220 - in /webservices/axis/trunk/java/xdocs:
images/userguide/ images/userguide/MyServiceDeployed.JPG
images/userguide/ServiceItems.JPG images/userguide/TestClient.JPG
userguide.html
Author: jaliya
Date: Sun Jun 5 21:58:26 2005
New Revision: 180220
URL: http://svn.apache.org/viewcvs?rev=180220&view=rev
Log:
Updated the userguide
Added:
webservices/axis/trunk/java/xdocs/images/userguide/
webservices/axis/trunk/java/xdocs/images/userguide/MyServiceDeployed.JPG (with props)
webservices/axis/trunk/java/xdocs/images/userguide/ServiceItems.JPG (with props)
webservices/axis/trunk/java/xdocs/images/userguide/TestClient.JPG (with props)
Modified:
webservices/axis/trunk/java/xdocs/userguide.html
Added: webservices/axis/trunk/java/xdocs/images/userguide/MyServiceDeployed.JPG
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/images/userguide/MyServiceDeployed.JPG?rev=180220&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis/trunk/java/xdocs/images/userguide/MyServiceDeployed.JPG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis/trunk/java/xdocs/images/userguide/ServiceItems.JPG
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/images/userguide/ServiceItems.JPG?rev=180220&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis/trunk/java/xdocs/images/userguide/ServiceItems.JPG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: webservices/axis/trunk/java/xdocs/images/userguide/TestClient.JPG
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/images/userguide/TestClient.JPG?rev=180220&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis/trunk/java/xdocs/images/userguide/TestClient.JPG
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: webservices/axis/trunk/java/xdocs/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/userguide.html?rev=180220&r1=180219&r2=180220&view=diff
==============================================================================
--- webservices/axis/trunk/java/xdocs/userguide.html (original)
+++ webservices/axis/trunk/java/xdocs/userguide.html Sun Jun 5 21:58:26 2005
@@ -15,6 +15,10 @@
font-size: 14px;
color: #990000;
}
+.style9 {color: #FF0066}
+.style10 {color: #33CC00}
+.style13 {color: #00CC00}
+.style15 {color: #0000FF}
-->
</style>
</head>
@@ -131,21 +135,138 @@
absolutely required and AXIS will not create it automatically in the case of the simple axis server.
</b></p> -->
<h2><a name="_Toc96697863"></a>Samples</h2>
-<p>In this section of the userguide we will look at how to write and deploy Web Services and how to write Web Service Clients using Axis2. All the userguide samples are located at the "modules/samples" directory. So let's explore the samples.</p>
+<p>In this section of the userguide we will look at how to write and deploy Web Services and how to write Web Service Clients using Axis2. All the userguide samples are located at the <span class="style9">"modules/samples"</span> directory. So let's explore the samples.</p>
+<p>Note: Please note that the rest of this userguide assumes that the user has downloaded the binary distribution of Axis2. If you have already downloaded the source tree of Axis2 then please create the binary distribution by simply using the maven command <strong>maven dist-bin </strong>This will create the "axis2-M2-bin.zip" and "axis2-M2-bin.tar" in the "target/dist" directory. Extract the zip or the tar ball to any diretory in your machine and for the explantions purposes we will name this as "Axis2Home". </p>
<h3> Web Services Using Axis2</h3>
+<p>Before starting, please check wither you have deployed the "axis2.war" in your servlet container and it is working properly.</p>
<p>MyService</p>
-<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 with the following description.</p>
-<pre class="style1 style2 style3">public void ping(OMElement element){} //sample IN-ONLY operatoin, just accept the OMElement and do some processing.
+<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){} //sample IN-ONLY operation, just accept the OMElement and do some processing.
public OMElement echo(OMElement element){}//sample IN-OUT operation, accept an OMElement and respond with another OMElement after processing</pre>
-<p>You can find our first example Web Service(MyService) in the "modules/samples" 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 desciptors for the service and depoly it.</p>
-<p>Axis2 uses "service.xml" to locate configurations for a Web Service. Each Web Service deployed under Axis2 needs a "service.xml" contining 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.RawXMLINOutMessageRecevier"/><br> </operation><br> </service></pre>
-<p>This is used to inform Axis2 engine (once deployed) what is the service class and the operations that it contains. In addition user should specify the meand other relavent parameters (here we don't have any other). </p>
-<p>MyService with a Logging Module </p>
-<h3>Utilize Web Services Using Axis2 </h3>
-<p>Blocking</p>
-<p>Non-Blocking</p>
-<p>With Two Transports</p>
+<p>You can find our first example Web Service(MyService) 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 under 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>
+<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 InOut operation. For one way operation, "ping" we have used <strong>RawXMLINOnlyMessageRecevier</strong> as the message receiver. </p>
+<p>Axis2 use ".aar" file as the deployemnt package for Web Services. So for the MyService we will use "MyService.aar" with the "service.xml" packaged under META-INF as shown in the following picture.</p>
+<p><img src="images/userguide/ServiceItems.JPG" width="176" height="91"></p>
+<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. For this explanation we can use the "MyService.aar" that is in the Axis2Home/samples/userguide directory. </p>
+<p>Since this is our firts service we need once more steps before we depoly the service. That is to create a directory named "services" under "webapps/axis2/WEB-INF" of you servlet container. Deploying is just a matter of droping the ".aar" in to this drectory and hence please copy the "MyService.aar" into the service 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 eveyting is ok, you will see the following out put.. </p>
+<p align="center"><img src="images/userguide/MyServiceDeployed.JPG" width="797" height="654"> </p>
+<p>If you can see the above out put then you have successfully deployed MyService on Axis2. Now let's see how we can write Web Service client to use this services.</p>
+<h3> Web Service Clients Using Axis2 </h3>
+<h4>EchoBlockingClient</h4>
+<p>Axis2 provides the user with various 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 {
+ OMElement payload = ClientUtil.getEchoOMElement();
+ <span class="style10">Call call = new Call();
+ call.setTo(targetEPR);
+ call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false);
+
+ OMElement result = (OMElement) call.invokeBlocking("echo", payload);
+</span>
+ StringWriter writer = new StringWriter();
+ result.serializeWithCache(XMLOutputFactory.newInstance().createXMLStreamWriter(writer));
+ writer.flush();
+
+ System.out.println(writer.toString());
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (XMLStreamException e) {
+ e.printStackTrace();
+ }
+}
+</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 clent 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 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>
+<p><img src="images/userguide/TestClient.JPG" width="951" height="132"></p>
+<h4>PingClient</h4>
+<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. As earlier the client code will be as follows.</p>
+<pre class="style1 style2 style3"> try {
+ OMElement payload = ClientUtil.getPingOMElement();
+
+
+ MessageSender msgSender = new MessageSender();
+ msgSender.setTo(targetEPR);
+ msgSender.setSenderTransport(Constants.TRANSPORT_HTTP);
+ msgSender.send("ping", payload);
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ }
+</pre>
+</p>
+<p>Since we are accessing a one way 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 invockation, hence it will return the control immediately back to the client. You can find the "TestPingClient.bat" in the "Axis2Home/samples/userguide/src/userguide/clients/bin" directory and give it a try.</p>
+<p>Ok, we have invoked the two operations in our service, Are we done? No!, there are lot more to explore, Let's see some other ways to invoke same operations.</p>
+<h4>EchoNonBlockingClient</h4>
+<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 desireable 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>
+<p>The invocaton accepts a callback object as a parameter. Axis2 client API provides an abastract Callback with the following methods.</p>
+<p><pre class="style1 style2 style3">public abstract void onComplete(AsyncResult result);
+public abstract void reportError(Exception e);
+public boolean isComplete() {}</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 respones is received by the Axis2 Client API (Call). This will elimenate the blocking nature of the Web Service invocations and provides the user with the flexibility to use Non Blocking API for Web Service Cleints.</p>
+<p>To run the sample client ( EchoNonBlockingClient) you can simply use the "TestEchoNonBlockingClient.bat" or "TestEchoNonBlockingClient.sh" files that can be found in the "Axis2Home/samples/userguide/src/userguide/clients/bin" directory. </p>
+<h4>EchoNonBlockingDualClient </h4>
+<p>The solution provided by the Non-Blocking API, for the Web Service invocations which takes long time to complete, has one limitation. That is limitation due to the use of single transport connection to invoke the Web Service and to retrieve the response. In otherwords, client API provides a non blocking invocation mechanism for the users, but the request and the response comes in a single transport connection (needs two way transport like HTTP). Long runnig Web Service invocations or Web Service invocations using One-Way transports (like SMTP) cannot be utilized by simply using a non blocking invocation. </p>
+<p>The trivial solution is to use separate transport connections (either One-Way or Two-Way) for the request and response. The next problem that needs to be sloved is the correlation (correlating the request and the response). WS-Addressing provides a neat solution to above using <wsa:MessageID> and <wsa:RelatesTo> headers. Axis2 provides support for addressing based correlation mechanism and a complying Client API to invoke Web Services with two transport connections. </p>
+<p>Users can select between Blocking or Non-Blocking APIs for the Web Service client. By simply using a boolean flag, this same API can be used to invoke web services(IN-OUT operations) using two separate transport connections. Let's see how we can do it using an example. Following code fragement shows how to invoket the same "echo" operation, using Non-Blocking API with two transport connections<strong>.The ultimate asynchronoy!!</strong></p>
+<pre class="style1 style2 style3">
+ try {
+ OMElement payload = ClientUtil.getEchoOMElement();
+
+ Call call = new Call();
+ call.setTo(targetEPR);
+
+ //The boolean flag informs the axis2 engine to use two separate transport connection
+ //to retrieve the response.
+ <span class="style13">call.engageModule(new QName("addressing"));</span>
+ call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, <span class="style13">true</span>);
+
+ //Callback to handle the response
+ Callback callback = new Callback() {
+ public void onComplete(AsyncResult result) {
+ try {
+ StringWriter writer = new StringWriter();
+ result.getResponseEnvelope().serializeWithCache(
+ XMLOutputFactory.newInstance().createXMLStreamWriter(writer));
+ writer.flush();
+
+ System.out.println(writer.toString());
+
+ } catch (XMLStreamException e) {
+ reportError(e);
+ }
+ }
+
+ public void reportError(Exception e) {
+ e.printStackTrace();
+ }
+ };
+
+ //Non-Blocking Invocation
+ call.invokeNonBlocking("echo", payload, callback);
+
+ //Wait till the callback receives the response.
+ while (!callback.isComplete()) {
+ Thread.sleep(1000);
+ }
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ }
+</pre>
+<p>The two changes that we need at the client side 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"> Inorder to do that ... </span></p>
+<p>Before we run the sample cleint we need one more step to perform. As mentioned earlier Axis2 uses addressing based correlation mechanim and hence we need to "engage" addressing moduel in the server side as well. According to the Axis2 architecture addressing module is deployed in the "<strong>pre-dispatch</strong>" pahse and hance "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/axis2WEB-INF" directory under servlet container.</p>
+<pre class="style1 style2 style3"> <module ref="addressing"/></pre>
+<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.</p>
+<p>Note: Please note th<span class="style15">at once you change the "server.xml" you need to restart the servelet container and make sure that marr </span></p>
+<p> </p>
+<p>MyService with a Logging Module
+</p>
+<h3> </h3>
<h3>Other Samples //Links to Google Samples </h3>
<h2> Modules</h2>
<h2>Tools</h2>
@@ -502,4 +623,4 @@
<p> </p>
<p> </p>
</body>
-</html>
\ No newline at end of file
+</html>