You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ja...@apache.org on 2005/02/21 05:59:28 UTC
svn commit: r154626 -
webservices/axis/trunk/archive/java/scratch/prototype2/xdocs/ClientAPI.html
Author: jaliya
Date: Sun Feb 20 20:59:26 2005
New Revision: 154626
URL: http://svn.apache.org/viewcvs?view=rev&rev=154626
Log:
Did some review and change a bit
Modified:
webservices/axis/trunk/archive/java/scratch/prototype2/xdocs/ClientAPI.html
Modified: webservices/axis/trunk/archive/java/scratch/prototype2/xdocs/ClientAPI.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/archive/java/scratch/prototype2/xdocs/ClientAPI.html?view=diff&r1=154625&r2=154626
==============================================================================
--- webservices/axis/trunk/archive/java/scratch/prototype2/xdocs/ClientAPI.html (original)
+++ webservices/axis/trunk/archive/java/scratch/prototype2/xdocs/ClientAPI.html Sun Feb 20 20:59:26 2005
@@ -3,32 +3,40 @@
</head>
<body>
<h2>Introduction</h2>
-<p>Invocation of web service will lead to an exchange of messages between two or more parties. If we consider the general scenario where client invokes a single service, the communication between them can be either one way or two-way. Depending on the way the client handles the invocation at the API level, whether the transport protocol used is unidirectional or bi-directional and the type of the service method, one can derive many interaction patterns between client and the service. Rest of the document will focus on identifying these possible break ups and how they are supported in Apache Axis 2.</p>
-<p>Note: Through out the tutorial the words Client and the Service are used to represent Web Service Client and the Web Service respectively.</p>
+<p>Invocation of web service will lead to an exchange of messages between two or more parties. If we consider the general scenario where
+a client invokes a single service, the communication between them can be either one way or two-way. Depending on the way the client handles the invocation at the API level, whether the transport protocol used is unidirectional or bi-directional and the type of the service method, one can derive many interaction patterns between client and the service. Rest of the document will focus on identifying these possible break ups and
+on how they are supported in Apache Axis 2.</p>
+<p>Note: Please note that through out the tutorial the words "Client" and the "Service" are used to represent
+"Web Service Client" and the "Web Service" respectively.</p>
<h2>Axis 2 Client API</h2>
<p>Followings will decide the interaction patterns between client and the service.</p>
<ul>
<li>Client API </li>
- <li>The transport protocol used</li>
+ <li>The Protocol used to send the SOAP Message</li>
<li>The type of the service method</li>
</ul>
<h2>Client API</h2>
<p>Clients can consume services which take almost no time to complete and the services take considerable amount of time to complete. So its important that the SOAP engine provides both blocking and non-blocking APIs for the client. This can be easily done in the API level. </p>
-<p>With a blocking API client will hang till the operation completes. In other words once invoked, the client will keep blocking till it gets the response (if any) from the service. This will be a huge drawback in the client side performance, if the operation takes considerable amount of time.</p>
+<p>With a blocking API client will hang till the operation completes. In other words once invoked, the client will keep blocking till it gets the response (if any) from the service.
+This is very useful method when invoking web services that do not take long time
+to complete and the hanging in the client side is negligible. This will be a huge drawback in the client side performance, if the operation takes considerable amount of time.</p>
<p>A non blocking API will provide the client to use a Callback mechanism (or polling mechanism) to get the responses (if any) for a service invocation. Client gets this response it two ways. Both ways client has to register a call back with the SOAP engine.</p>
<ul>
-<li>Client keep on polling the call back object it registers with the SOAP engine, with the isComplete(). If isComplete() returns true, client get the result, if any, through getResult() which returns an AsyncResult object.
+<li>Client keep on polling the call back object it registers with the SOAP engine,
+using the isComplete(). If isComplete() returns true, client get the result, if any, through getResult() which returns an AsyncResult object.
<li>Upon receipt of the response, if any, SOAPEngine calls the onComplete(AsyncResult) of the call back object. </li></ul>
<p>Note that client can adopt any one of the above two methods, independent of the way service has been implemented.</p>
-<h2>Transport Protocol Used</h2>
-<p>Transport protocols can be categorized mainly in to two types.</p>
+<h2>The Protocol Use to Send the SOAP Message</h2>
+<p>The protocol used to send the SOAP message can be categorized mainly in to two types.</p>
<ol>
<li>Unidirectional </li>
<li>Bi-Directional</li>
</ol>
<p>With a unidirectional protocol (e.g. SMTP), client can simply invoke a service which has no response(s) to be sent in the same connection. But if the service is request/response in nature, it is required to use two separate connections of unidirectional protocol. However if the client needs only to send information, unidirectional is useful for that.</p>
<p>With a bidirectional protocol the client can retrieve the service response (if any) using the same connection. In this context HTTP is the most common bidirectional transport protocol. However the main drawback is the possibility of the timeouts that can happen. If the service takes some time to complete then there is a possibility of time out in the connection.</p>
-<p>Bi-directional transport can be used to invoke one-way services as well. In this case the return path of the communication channel is not used. However since we are using a bi-directional protocol the return path can be used to carry the acceptance state or a fault (if any). With reference to HTTP the HTTP 202 header status will act as the acceptance state and it will also be used to send a fault (if any) to the client using the same connection.</p>
+<p>Bi-directional transport can be used to invoke one-way services as well. In this case the return path of the communication channel is not used. However since we are using a bi-directional protocol the return path can be used to carry the acceptance state or a fault (if any). With reference to HTTP the
+"HTTP 202 Ok" header status will act as the acceptance state. The faults (if
+any) is also sent using the response path of the HTTP connection.</p>
<h2>Type of the Service Method</h2>
<p>According to the WSDL definitions, there can be various Message Exchange Patterns defined for web services. These require the client to use possible invocation mechanism to handle the service invocations. For example if the client is invoking a service method which is defined as IN-ONLY operation, then the client should be able to use a method in the client API which is capable of handling this type of requests.</p>
<p>All these variations give rise to several Client API methods which will ultimately ease the service invocation for a web service client. For Axis 2, currently we are providing following methods in the Call API provided</p>
@@ -115,8 +123,7 @@
<p><strong>Message Path and Sequence Diagram</strong></p>
<pre>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj)</pre><pre>p -> correlator.addCorrelationInfor(msgID,allbackObjRef)</pre><pre>b- > engine.send (..)</pre><pre>c -> Send the SOAP message</pre><pre>d -> Receive the response over the synchronous transport</pre><pre>w -> ProviderX will be called as the last step in engine.receive(..) </pre><pre>q -> correlator.getCorrelationInfo(msgID)</pre><pre>g -> callbackObj.onComplet()</pre>
<div align="center">
- <pre>
-<img height=225 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image010.jpg" width=643 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image010.jpg"></pre>
+ <pre><img height=225 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image010.jpg" width=643 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image010.jpg"></pre>
</div>
<p align=center>Figure 5 Sequence diagram corresponds to sendRecieveAysn with two way transport</p>
<p><strong>Method 2: With a Client Side Listener</strong></p>
@@ -135,10 +142,15 @@
<p align=center><img height=234 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image013.jpg" width=648 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image013.jpg"></p>
<p align=center>Figure 6 Sequence diagram corresponds to sendRecieveAync with one way transport.</p>
<h2>What is supported in M1</h2>
-<p>From the above interaction patterns for M1, we only support following two
-types.</p>
+<p>From the above interaction patterns for Milestone1, we have only implemented
+the following two types. </p>
<ul>
<li>Blocking Invocation of type In-Out</li>
<li>Non Blocking Invocation of type In-Out --> Method 1: Without a Client Side Listener</li>
</ul>
-<h2> </h2></body></html>
\ No newline at end of file
+<p>However from the client's point of view the other interaction patterns are
+also implemented except the Non Blocking Invocation of type In-Out with a client
+side listener, but still we could not test them since we need complete server
+implementation to test them.</p>
+<h2><span style="font-weight: 400"><font size="3">It is our intention to support
+all the required interaction patterns and will be available in the next release.</font></span></h2></body></html>
\ No newline at end of file