| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-05-19 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20180519" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Axis2 – </title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script> |
| <meta http-equiv="content-type" content="" /> </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2018-05-19<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.7.8<span class="divider">|</span></li> |
| <li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> |
| <li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li> |
| <li class="active "></li> |
| </ul> |
| </div> |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">Axis2/Java</li> |
| <li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li> |
| <li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li> |
| <li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a> |
| <ul class="nav nav-list"> |
| <li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li> |
| <li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li> |
| <li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li> |
| <li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li> |
| <li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li> |
| <li><a href="../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li> |
| <li><a href="../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li> |
| <li><a href="../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li> |
| <li><a href="../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li> |
| <li><a href="../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li> |
| <li><a href="../release-notes/1.7.6.html" title="1.7.6"><span class="none"></span>1.7.6</a> </li> |
| <li><a href="../release-notes/1.7.7.html" title="1.7.7"><span class="none"></span>1.7.7</a> </li> |
| <li><a href="../release-notes/1.7.8.html" title="1.7.8"><span class="none"></span>1.7.8</a> </li> |
| </ul> |
| </li> |
| <li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li> |
| <li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li> |
| <li class="nav-header">Documentation</li> |
| <li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li> |
| <li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li> |
| <li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li> |
| <li><a href="../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li> |
| <li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li> |
| <li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li> |
| <li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li> |
| <li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li> |
| <li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li> |
| <li class="nav-header">Resources</li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li> |
| <li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li> |
| <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li> |
| <li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li> |
| <li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li> |
| <li class="nav-header">Get Involved</li> |
| <li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li> |
| <li><a href="../svn.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li> |
| <li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li> |
| <li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li> |
| <li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li> |
| <li class="nav-header">Project Information</li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li> |
| <li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li> |
| <li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li> |
| <li class="nav-header">Apache</li> |
| <li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li> |
| <li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li> |
| </ul> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </div> |
| <div id="bodyColumn" class="span10" > |
| <html> |
| |
| <a name="Web_Service_Clients_Using_Axis2"></a> |
| |
| |
| <h1>Writing Web Service Clients Using Axis2's Primary APIs</h1> |
| |
| |
| <p>This section presents a complex yet powerful <b>XML based client |
| API</b>, 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">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 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". 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 |
| consequences such as One-Way transports that come into play when we need |
| them. Let's try to analyze some common service invocation paradigms.</p> |
| |
| |
| <p>Many Web service engines provide users with Blocking and Non-Blocking |
| client APIs.</p> |
| |
| <ul> |
| |
| <li> |
| <p style="margin-bottom: 0in"><b>Blocking API</b> - Once the service |
| 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. |
| 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 allows the |
| client application to invoke several Web services simultaneously without |
| needing to wait for the response of previous operations.</p> |
| </li> |
| </ul> |
| |
| |
| <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> |
| |
| |
| <p>Both mechanisms use single transport connections to send the request and |
| 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, 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> |
| |
| |
| <p>By <b>combining API Level Asynchrony and Transport Level |
| Asynchrony</b>, we can obtain four different invocation patterns for Web |
| services as shown in the following table.</p> |
| <a name="table1"></a> |
| |
| |
| <table border="0" class="table table-striped"> |
| <tbody> |
| |
| <tr class="a"> |
| |
| <td width="33%" height="19"> |
| <p><b>API |
| (Blocking/Non-Blocking)</b></p> |
| </td> |
| |
| <td width="33%"> |
| <p><b>Dual Transports (Yes/No)</b></p> |
| </td> |
| |
| <td width="33%"> |
| <p><b>Description</b></p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td width="33%" height="19"> |
| <p>Blocking</p> |
| </td> |
| |
| <td width="33%"> |
| <p>No</p> |
| </td> |
| |
| <td width="33%"> |
| <p>The simplest and most familiar invocation pattern</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td width="33%" height="19"> |
| <p>Non-Blocking</p> |
| </td> |
| |
| <td width="33%"> |
| <p>No</p> |
| </td> |
| |
| <td width="33%"> |
| <p>Using callbacks or polling</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td width="33%" height="19"> |
| <p>Blocking</p> |
| </td> |
| |
| <td width="33%"> |
| <p>Yes</p> |
| </td> |
| |
| <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> |
| |
| <tr class="a"> |
| |
| <td width="33%" height="19"> |
| <p>Non-Blocking</p> |
| </td> |
| |
| <td width="33%"> |
| <p>Yes</p> |
| </td> |
| |
| <td width="33%"> |
| <p>This is can be used to gain the maximum asynchronous |
| behavior. Non blocking at the API level and also at the transport |
| level.</p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| |
| |
| <p>Axis2 provides the user with all these possibilities to invoke Web |
| services.</p> |
| |
| |
| <p>The following section presents clients that use some of the different |
| possibilities presented above to invoke a Web Service using |
| <tt>ServiceClient</tt>s. All the samples mentioned in this guide are |
| located at the <b><font color="#000000">"samples\userguide\src"</font></b> |
| directory of the binary distribution.</p> |
| |
| |
| <p>This section presents four types of clients.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Request-Response, Blocking 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> |
| <a name="EchoBlockingClient"></a> |
| |
| |
| <div class="section"> |
| <div class="section"> |
| <h4><a name="Request-Response_Blocking_Client"></a>Request-Response, Blocking Client</h4> |
| |
| |
| <p>The client code below will invoke the "echo" operation of |
| "MyService" using a pure blocking single-channel invocation.</p> |
| |
| <div> |
| <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); |
| |
| OMElement result = serviceClient.sendReceive(payload); |
| </span> |
| System.out.println(result); |
| } catch (AxisFault axisFault) { |
| axisFault.printStackTrace(); |
| } |
| }</pre></div> |
| |
| <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 "<b>Axis2_HOME/samples/userguide</b>" directory. Run the |
| "run.client.blocking" target. If you can see the response OMElement printed |
| in your command line, then you have successfully tested the client.</p> |
| <a name="PingClient"></a> |
| |
| </div> |
| <div class="section"> |
| <h4><a name="One_Way_Client_Non-Blocking"></a>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> |
| |
| <div> |
| <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></div> |
| |
| |
| <p>Since we are calling an IN-ONLY web service, we can directly use the |
| <tt>fireAndForget()</tt> 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 |
| "<b>Axis2Home/samples/userguide</b>".</p> |
| |
| <a name="EchoNonBlockingClient"></a> |
| |
| </div> |
| <div class="section"> |
| <h4><a name="Request-Response_Non-Blocking_that_uses_one_transport_connection"></a>Request-Response, Non-Blocking that uses one transport connection</h4> |
| |
| |
| <p>In the "EchoBlockingClient" once the |
| <tt>serviceClient.sendReceive(payload);</tt> is called, the client is |
| blocked till the operation is complete. This behavior is not desirable when |
| there are many Web service invocations to be done in a single client |
| application or within a GUI. 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 |
| "<b>Axis2_HOME/samples/userguide/src/userguide/clients</b>" with |
| 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> |
| |
| <div> |
| <pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre></div> |
| |
| |
| <p>The invocation accepts a Callback object as a parameter. Axis2 client API |
| provides an abstract Callback with the following methods:</p> |
| |
| <div> |
| <pre>public abstract void onComplete(AsyncResult result); |
| public abstract void onError(Exception e); |
| public boolean isComplete() {}</pre></div> |
| |
| |
| <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 eliminates the blocking nature of the web service |
| request-response invocation.</p> |
| |
| |
| <p>To run the sample client ("EchoNonBlockingClient") you can simply use the |
| <tt>run.client.nonblocking</tt> target of the Ant file found in the |
| "<b>Axis2_HOME/samples/userguide</b>" directory.</p> |
| <a name="EchoNonBlockingDualClient"></a> |
| |
| </div> |
| <div class="section"> |
| <h4><a name="Request-Response_Non-Blocking_that_uses_two_transport_connections"></a>Request-Response, Non-Blocking that uses two transport connections</h4> |
| |
| |
| <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, 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 such as SMTP cannot be utilized by simply using a non-blocking |
| API invocation.</p> |
| |
| |
| <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, however, is subsequently correlating each request with its response. |
| <a class="externalLink" href="http://www.w3.org/2002/ws/addr/">WS-Addressing</a> |
| provides a neat solution to this using <wsa:MessageID> and |
| <wsa:RelatesTo> headers. Axis2 provides support for an addressing based |
| correlation mechanism and a complying Client API to invoke Web services with |
| two transport connections. (The core of Axis2 does not depend on |
| 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 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 |
| flag, the same API can be used to invoke Web services (IN-OUT operations) |
| using two separate transport connections. Let's see how it's done using an |
| example. The following code fragment shows how to invoke the same "echo" |
| operation using Non-Blocking API with two transport connections<b>. The |
| ultimate asynchrony!!</b></p> |
| |
| <div> |
| <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></div> |
| |
| |
| <p>The boolean flag (value True) in the |
| <b><tt>options.setUseSeparateListener(...)</tt></b> method informs the |
| Axis2 engine to use separate transport connections for the request and |
| response. Finally <b><tt>sender.cleanup()</tt></b> informs the Axis2 |
| engine to stop the client side listener, which started to retrieve the |
| response.</p> |
| |
| |
| <p>To run the sample client ("EchoNonBlockingDualClient") you can simply use |
| the "run.client.nonblockingdual" target of the Ant file found in the |
| "<b>Axis2_HOME/samples/userguide/</b>" directory.</p> |
| </div></div> |
| </html> |
| </div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>Copyright ©2004–2018 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |