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 di...@apache.org on 2007/06/22 06:55:36 UTC
svn commit: r549708 - in
/webservices/axis2/trunk/java/xdocs/@axis2_version_dir@: dii.html
ejb-provider.html
Author: dims
Date: Thu Jun 21 21:55:36 2007
New Revision: 549708
URL: http://svn.apache.org/viewvc?view=rev&rev=549708
Log:
Fix for AXIS2-2666
Modified:
webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html
webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/ejb-provider.html
Modified: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/dii.html?view=diff&rev=549708&r1=549707&r2=549708
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html Thu Jun 21 21:55:36 2007
@@ -14,16 +14,16 @@
<p>This section presents a complex yet powerful <strong>XML based client
API</strong>, which is intended for advanced users. However, if you are a new
user, we recommend using code generation given in the <a
-href="adv-userguide.html">Advance User's Guide</a>.</p>
+href="adv-userguide.html">Advanced User's Guide</a>.</p>
<p>Web services can be used to provide a wide-range of functionality to the
user from simple, quick operations such as "getStockQuote" to time consuming
business services. When we utilize (invoke using client applications) these
-Web services, we cannot use simple generic invocation paradigms that suite
+Web services, we cannot always use simple generic invocation paradigms that suite
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 an IN-OUT operation that takes a long time to complete, then most often
-we may end up with "connection time outs". On the other hand, if there are
+we may end up with "connection time outs". Further, 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
@@ -34,21 +34,21 @@
client APIs.</p>
<ul>
<li><p style="margin-bottom: 0in"><b>Blocking API</b> - Once the service
- invocation is called, the client application hangs and only regains
- control when the operation completes, after which the client receives a
+ invocation is called, the client application hangs, regaining control
+ only when the operation completes, after which the client receives a
response or a fault. This is the simplest way of invoking Web services,
and it also suites many business situations.</p>
</li>
<li><p><b>Non-Blocking API </b>- This is a callback or polling based API.
- Hence once a service invocation is called, the client application
+ Here, once a service invocation is called, the client application
immediately regains control and the response is retrieved using the
- callback object provided. This approach provides flexibility to the
+ callback object provided. This approach allows the
client application to invoke several Web services simultaneously without
- blocking the operation already invoked.</p>
+ needing to wait for the response of previous operations.</p>
</li>
</ul>
-<p>Both mechanisms work at the API level. Let's name the asynchronous
+<p>Both these mechanisms work at the API level. Let's name the asynchronous
behavior that we can get using the Non-Blocking API as <b>API Level
Asynchrony.</b></p>
@@ -56,8 +56,8 @@
to receive the response. They severely lag the capability of using two
transport connections for the request and the response (either One-Way or
Two-Way). So both these mechanisms fail to address the problem of long
-running transactions (the transport connection may time-out before the
-operation completes). A possible solution would be to use two separate
+running transactions, as the transport connection may still time-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 this solution can be called <b>Transport Level
Asynchrony</b>.</p>
@@ -83,7 +83,7 @@
</td>
<td width="33%"><p>No</p>
</td>
- <td width="33%"><p>The simplest and more familiar invocation pattern</p>
+ <td width="33%"><p>The simplest and most familiar invocation pattern</p>
</td>
</tr>
<tr>
@@ -99,7 +99,7 @@
</td>
<td width="33%"><p>Yes</p>
</td>
- <td width="33%"><p>This is useful when the service operation is IN-OUT
+ <td width="33%"><p>This is useful when the service operation is Request-Response
in nature but the transport used is One-Way (e.g. SMTP)</p>
</td>
</tr>
@@ -119,7 +119,7 @@
<p>Axis2 provides the user with all these possibilities to invoke Web
services.</p>
-<p>The following section presents clients that use the different
+<p>The following section presents clients that use some of the different
possibilities presented above to invoke a Web Service using
<code>ServiceClient</code>s. All the samples mentioned in this guide are
located at the <b><font color="#000000">"samples\userguide\src"</font></b>
@@ -128,7 +128,7 @@
<p>This section presents four types of clients.</p>
<ol>
<li>Request-Response, Blocking Client</li>
- <li>One Way Client</li>
+ <li>One Way Client, Non-Blocking</li>
<li>Request-Response, Non-Blocking that uses one transport connection</li>
<li>Request-Response, Non-Blocking that uses two transport connections</li>
</ol>
@@ -136,34 +136,29 @@
<h4>Request-Response, Blocking Client</h4>
-<p>Axis2 provides the user with several invocation patterns for Web services,
-ranging from pure blocking single channel invocations to non-blocking dual
-channel invocations. First let us see how we can write a client to invoke the
-"echo" operation of "MyService" using the simplest blocking invocation. The
-client code you need to write is as follows.</p>
-<source><pre> try {
- OMElement payload = ClientUtil.getEchoOMElement();
- <span style="color: rgb(36, 193, 19);">
- Options options = new Options();
- options.setTo(targetEPR); // this sets the location of MyService service
+<p>The client code below will invoke the "echo" operation of
+"MyService" using a pure blocking single-channel invocation.</p>
+<source>
+<pre>
+ try {
+ <span style="color: rgb(36, 193, 19);">
+ OMElement payload = ClientUtil.getEchoOMElement();
+ Options options = new Options();
+ options.setTo(targetEPR); // this sets the location of MyService service
- ServiceClient serviceClient = new ServiceClient();
- serviceClient.setOptions(options);
+ ServiceClient serviceClient = new ServiceClient();
+ serviceClient.setOptions(options);
- OMElement result = serviceClient.sendReceive(payload);
- </span>
- System.out.println(result);
-
- } catch (AxisFault axisFault) {
- axisFault.printStackTrace();
- }
+ OMElement result = serviceClient.sendReceive(payload);
+ </span>
+ System.out.println(result);
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ }
}</pre>
</source>
-<p>1. The lines highlighted in green show the set of operations that you need
-to perform in order to invoke a Web service.</p>
-
-<p>2. The rest is used to create the OMElement that needs to be sent and
-display the response OMElement.</p>
+<p>The lines highlighted in green show the set of operations that you need
+to perform in order to invoke the Web service in this manner.</p>
<p>To test this client, use the provided Ant build file that can be found in
the "<strong>Axis2_HOME/samples/userguide</strong>" directory. Run the
@@ -171,40 +166,38 @@
in your command line, then you have successfully tested the client.</p>
<a name="PingClient"></a>
-<h4>One Way Client</h4>
+<h4>One Way Client, Non-Blocking</h4>
<p>In the Web service "MyService", we had an IN-ONLY operation with the name
"ping" (see <a href="adv-userguide.html#Web_Services_Using_Axis2">Creating a
New Web Service</a>). Let's write a client to invoke this operation. The
client code is as follows:</p>
-<pre> try {
- OMElement payload = ClientUtil.getPingOMElement();
- Options options = new Options();
- options.setTo(targetEPR);
- ServiceClient serviceClient = new ServiceClient();
- serviceClient.setOptions(options);
- serviceClient.fireAndForget(payload);
- /**
- * We have to block this thread untill we send the request , the problem
- * is if we go out of the main thread , then request wont send ,so
- * you have to wait some time :)
- */
- Thread.sleep(500);
- }
-catch (AxisFault axisFault) {
- axisFault.printStackTrace();
- }</pre>
+<pre>
+ try {
+ OMElement payload = ClientUtil.getPingOMElement();
+ Options options = new Options();
+ options.setTo(targetEPR);
+ ServiceClient serviceClient = new ServiceClient();
+ serviceClient.setOptions(options);
+ serviceClient.fireAndForget(payload);
+ /**
+ * We need to wait some time for the message to be sent. Otherwise,
+ * if we immediately exit this function using the main thread,
+ * the request won't be sent.
+ */
+ Thread.sleep(500);
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ }
+</pre>
-<p>Since we are accessing an IN-ONLY operation, we can directly use the
+<p>Since we are calling an IN-ONLY web service, we can directly use the
<code>fireAndForget()</code> in the ServiceClient to invoke this operation.
This will not block the invocation and will return the control immediately
back to the client. You can test this client by running the target
"run.client.ping" of the Ant build file at
"<strong>Axis2Home/samples/userguide</strong>".</p>
-<p>We have now invoked the two operations in our service. Are we done? No!
-There's a lot more to explore. Let's see some other ways to invoke the same
-operations.</p>
<a name="EchoNonBlockingClient"></a>
<h4>Request-Response, Non-Blocking that uses one transport connection</h4>
@@ -219,23 +212,22 @@
<p>A sample client for this can be found under
"<strong>Axis2_HOME/samples/userguide/src/userguide/clients</strong>" with
-the name "EchoNonBlockingClient". If we consider the changes that users may
+the name "EchoNonBlockingClient". If we consider the changes that the developer may
have to do with respect to the "EchoBlockingClient" that we have already
seen, it will be as follows:</p>
<pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre>
-<p>The invocation accepts a callback object as a parameter. Axis2 client API
+<p>The invocation accepts a Callback object as a parameter. Axis2 client API
provides an abstract Callback with the following methods:</p>
<pre>public abstract void onComplete(AsyncResult result);
public abstract void onError(Exception e);
public boolean isComplete() {}</pre>
-<p>The user is expected to implement the "onComplete " and "onError " methods
-of their extended call back class. The Axis2 engine calls the "onComplete"
+<p>The developer is expected to override the onComplete() and onError() methods
+of their Callback subclass. The Axis2 engine calls the onComplete()
method once the Web service response is received by the Axis2 Client API
-(ServiceClient). This will eliminate the blocking nature of the Web service
-invocation and provide users with the flexibility to use Non Blocking API for
-Web service Clients.</p>
+(ServiceClient). This eliminates the blocking nature of the web service
+request-response invocation.</p>
<p>To run the sample client ("EchoNonBlockingClient") you can simply use the
<code>run.client.nonblocking</code> target of the Ant file found in the
@@ -244,19 +236,19 @@
<h4>Request-Response, Non-Blocking that uses two transport connections</h4>
-<p>The solution provided by the Non-Blocking API has one limitation when it
+<p>The solution provided above by the Non-Blocking API has one limitation when it
comes to Web service invocations that take a long time to complete. The
limitation is due to the use of single transport connections to invoke the
-Web service and retrieve the response. In other words, client API provides a
-non-blocking invocation mechanism for users, but the request and the response
-come in a single transport (Two-Way transport) connection (like HTTP). Long
+Web service and retrieve the response. In other words, the client API provides a
+non-blocking invocation mechanism for developers, but the request and the response
+still come in a single transport (Two-Way transport) connection like HTTP. Long
running Web service invocations or Web service invocations using One-Way
-transports (like SMTP) cannot be utilized by simply using a non-blocking
-invocation.</p>
+transports such as SMTP cannot be utilized by simply using a non-blocking
+API invocation.</p>
-<p>The trivial solution is to use separate transport connections (either
+<p>The simplest 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 solved is the correlation (correlating the request and the response).
+to be solved, however, is subsequently correlating each request with its response.
<a href="http://www.w3.org/2002/ws/addr/" target="_blank">WS-Addressing</a>
provides a neat solution to this using <wsa:MessageID> and
<wsa:RelatesTo> headers. Axis2 provides support for an addressing based
@@ -265,7 +257,7 @@
WS-Addressing, but contains a set of parameters, like in addressing, that can
be populated by any method. WS-Addressing is one of the uses that may
populate them. Even the transports can populate them. Hence, Axis2 has the
-flexibility to use different versions of addressing)</p>
+flexibility to use different addressing standards.)</p>
<p>Users can select between Blocking and Non-Blocking APIs for the Web
service clients with two transport connections. By simply using a boolean
@@ -274,46 +266,50 @@
example. The 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> try {
- OMElement payload = ClientUtil.getEchoOMElement();
-
- Options options = new Options();
- options.setTo(targetEPR);
- options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
- options.setUseSeparateListener(true);
- options.setAction("urn:echo"); // this is the action mapping we put within the service.xml
-
- //Callback to handle the response
- Callback callback = new Callback() {
- public void onComplete(AsyncResult result) {
- System.out.println(result.getResponseEnvelope());
- }
-
- public void onError(Exception e) {
- e.printStackTrace();
- }
- };
- //Non-Blocking Invocation
- sender = new ServiceClient();
- sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
- sender.setOptions(options);
- sender.sendReceiveNonBlocking(payload, callback);
- //Wait till the callback receives the response.
- while (!callback.isComplete()) {
- Thread.sleep(1000);
- }
- //Need to close the Client Side Listener.
- } catch (AxisFault axisFault) {
- axisFault.printStackTrace();
- } catch (Exception ex) {
- ex.printStackTrace();
- } finally {
- try {
- sender.cleanup();
- } catch (AxisFault axisFault) {
- //have to ignore this
- }
- }</pre>
+<pre>
+ try {
+ OMElement payload = ClientUtil.getEchoOMElement();
+
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+ options.setUseSeparateListener(true);
+ options.setAction("urn:echo"); // this is the action mapping we put within the service.xml
+
+ //Callback to handle the response
+ Callback callback = new Callback() {
+ public void onComplete(AsyncResult result) {
+ System.out.println(result.getResponseEnvelope());
+ }
+
+ public void onError(Exception e) {
+ e.printStackTrace();
+ }
+ };
+
+ //Non-Blocking Invocation
+ sender = new ServiceClient();
+ sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+ sender.setOptions(options);
+ sender.sendReceiveNonBlocking(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();
+ } finally {
+ try {
+ //Close the Client Side Listener.
+ sender.cleanup();
+ } catch (AxisFault axisFault) {
+ //have to ignore this
+ }
+ }
+</pre>
<p>The boolean flag (value True) in the
<b><code>options.setUseSeparateListener(...)</code></b> method informs the
Modified: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/ejb-provider.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/ejb-provider.html?view=diff&rev=549708&r1=549707&r2=549708
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/ejb-provider.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/ejb-provider.html Thu Jun 21 21:55:36 2007
@@ -14,10 +14,10 @@
<p>The EJB message receiver allows one to access stateless session EJBs
(Enterprise JavaBeans) through Web services. The example used in this guide
-illustrates how to use EJB provider that ships with axis2 to access EJBs
-deployed on a J2EE server such as Geronimo or Jboss.</p>
+illustrates how to use the EJB provider that ships with Axis2 to access EJBs
+deployed on a J2EE server such as Geronimo or JBoss.</p>
-<p>This example explains how to use Geronimo 1.1 and Jboss 4.0.4.GA as
+<p>This example explains how to use Geronimo 1.1 and JBoss 4.0.4.GA as
application server. </p>
<p>The following steps will take you through the example through which we
@@ -25,7 +25,7 @@
<h2>1. Creating a Simple Stateless Session EJB</h2>
-<p>First, we need to create a stateless session EJB. Use the following files
+<p>First we need to create a stateless session EJB. Use the following files
to make an EJB for testing:</p>
<pre>Remote interface (Hello.java)
package my.ejb;
@@ -41,7 +41,7 @@
import java.rmi.RemoteException;
public interface HelloBusiness {
-public String sayHello(String name) throws RemoteException;
+ public String sayHello(String name) throws RemoteException;
}</pre>
<p>2, Remote home interface - HelloHome.java</p>
@@ -51,7 +51,7 @@
import java.rmi.RemoteException;
public interface HelloHome extends EJBHome {
-public Hello create() throws CreateException, RemoteException;
+ public Hello create() throws CreateException, RemoteException;
}</pre>
<p>3. Bean class - HelloBean.java</p>
@@ -62,17 +62,17 @@
import javax.ejb.CreateException;
public class HelloBean implements SessionBean {
-public void setSessionContext(SessionContext sessionContext) throws
-EJBException {}
+ public void setSessionContext(SessionContext sessionContext) throws
+ EJBException {}
-public void ejbRemove() throws EJBException {}
-public void ejbActivate() throws EJBException {}
-public void ejbPassivate() throws EJBException {}
-public void ejbCreate() throws CreateException {}
-public String sayHello(String name) {
-
- return "Hello " + name + ", Have a nice day!";
- }
+ public void ejbRemove() throws EJBException {}
+ public void ejbActivate() throws EJBException {}
+ public void ejbPassivate() throws EJBException {}
+ public void ejbCreate() throws CreateException {}
+
+ public String sayHello(String name) {
+ return "Hello " + name + ", Have a nice day!";
+ }
}</pre>
@@ -106,7 +106,7 @@
</ejb-jar></pre>
<p>Now we have to write application server specific deployment descriptor(s)
-for the Hello EJB. Following listing shows an example Geronimo/OpenEJB
+for the Hello EJB. The following listing shows an example Geronimo/OpenEJB
deployment descriptor (openejb-jar.xml)</p>
<pre><?xml version="1.0" encoding="UTF-8"?>
<openejb-jar
@@ -156,7 +156,7 @@
+--HelloHome.class
</pre>
-<p>Deploy HelloEJB.jar on appropriate J2EE application server.</p>
+<p>Next, deploy the HelloEJB.jar file onto the appropriate J2EE application server.</p>
<h2>Creating the Axis2 Service Archive</h2>
@@ -252,14 +252,14 @@
Options options = serviceClient.getOptions();
EndpointReference targetEPR = new
-EndpointReference("http://localhost:8080/axis2/services/HelloBeanService");
+ EndpointReference("http://localhost:8080/axis2/services/HelloBeanService");
options.setTo(targetEPR);
QName hello = new QName("http://ejb.my/xsd", "sayHello");
Object[] helloArgs = new Object[] {"John"};
System.out.println(serviceClient.invokeBlocking(hello,
-helloArgs).getFirstElement().getText());
+ helloArgs).getFirstElement().getText());
...</pre>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org