cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1030343 - in /websites/production/cxf/content: cache/docs.pageCache docs/developing-a-consumer.html
Date Thu, 24 May 2018 15:57:52 GMT
Author: buildbot
Date: Thu May 24 15:57:52 2018
New Revision: 1030343

Log:
Production update by buildbot for cxf

Modified:
    websites/production/cxf/content/cache/docs.pageCache
    websites/production/cxf/content/docs/developing-a-consumer.html

Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/cxf/content/docs/developing-a-consumer.html
==============================================================================
--- websites/production/cxf/content/docs/developing-a-consumer.html (original)
+++ websites/production/cxf/content/docs/developing-a-consumer.html Thu May 24 15:57:52 2018
@@ -118,7 +118,7 @@ Apache CXF -- Developing a Consumer
            <!-- Content -->
            <div class="wiki-content">
 <div id="ConfluenceContent"><h1 id="DevelopingaConsumer-DevelopingaConsumerwithCXF">Developing
a Consumer with CXF</h1><h2 id="DevelopingaConsumer-GeneratingtheStubCode">Generating
the Stub Code</h2><p>The starting point for developing a service consumer (or
client) in CXF is a WSDL contract, complete with port type, binding, and service definitions.
You can then use the <a shape="rect" href="wsdl-to-java.html">wsdl2java</a> utility
to generate the Java stub code from the WSDL contract. The stub code provides the supporting
code that is required to invoke operations on the remote service.<br clear="none"> For
CXF clients, the wsdl2java utility can generate the following kinds of code:</p><ul><li>Stub
code - supporting files for implementing a CXF client.</li><li>Client starting
point code - sample client code that connects to the remote service and invokes every operation
on the remote service.</li><li>Ant build file - a <code>build.xml</code>
file intended for use with the ant buil
 d utility. It has targets for building and for running the sample client application.</li></ul><h4
id="DevelopingaConsumer-BasicHelloWorldWSDLcontract">Basic HelloWorld WSDL contract</h4><p>The
below shows the HelloWorld WSDL contract. This contract defines a single port type, <code>Greeter</code>,
with a SOAP binding, <code>Greeter_SOAPBinding</code>, and a service, <code>SOAPService</code>,
which has a single port, <code>SoapPort</code>.</p><p><span class="confluence-anchor-link"
id="DevelopingaConsumer-Example1"></span></p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>HelloWorld WSDL Contract</b></div><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;wsdl:definitions
name="HelloWorld" targetNamespace="http://apache.org/hello_world_soap_http" 
+<pre class="brush: java; gutter: false; theme: Default">&lt;wsdl:definitions name="HelloWorld"
targetNamespace="http://apache.org/hello_world_soap_http" 
     xmlns="http://schemas.xmlsoap.org/wsdl/" 
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
     xmlns:tns="http://apache.org/hello_world_soap_http"
@@ -286,11 +286,11 @@ Apache CXF -- Developing a Consumer
 </div></div><p>The <code>Greeter</code> port type defines the
following WSDL operations:</p><ul><li><code>sayHi</code> - has
a single output parameter, of <code>xsd:string</code>.</li><li><code>greetMe</code>
- has an input parameter, of <code>xsd:string</code>, and an output parameter,
of <code>xsd:string</code>.</li><li><code>greetMeOneWay</code>
- has a single input parameter, of <code>xsd:string</code>. Because this operation
has no output parameters, CXF can optimize this call to be a oneway invocation (that is, the
client does not wait for a response from the server).</li><li><code>pingMe</code>
- has no input parameters and no output parameters, but it can raise a fault exception.</li></ul><p>This
WSDL also defines a binding, <code>Greeter_SOAPBinding</code>, for the SOAP protocol.
In practice, the binding is normally generated automatically - for example, by running either
of the CXF wsdl2soap or wsdl2xml utilities. Likewise, the <code>SOAPService</code>
service can be gener
 ated automatically by running the CXF wsdl2service utility.</p><h4 id="DevelopingaConsumer-Generatingthestubcode">Generating
the stub code</h4><p>After defining the WSDL contract, you can generate client
code using the CXF wsdl2java utility. Enter the following command at a command-line prompt:</p><div
class="panel" style="border-width: 1px;"><div class="panelContent">
 <p><code>wsdl2java -ant -client -d <em>ClientDir</em> hello_world.wsdl</code></p>
 </div></div><p>Where <em>ClientDir</em> is the location of
a directory where you would like to put the generated files and<code> hello_world.wsdl</code>
is a file containing the contract shown in the WSDL above. The <code>-ant</code>
option generates an ant <code>build.xml</code> file, for use with the ant build
utility. The <code>-client</code> option generates starting point code for a client
<code>main()</code> method.</p><p>The preceding wsdl2java command
generates the following Java packages:</p><ul><li><code>org.apache.hello_world_soap_http</code>
<br clear="none"> This package name is generated from the <code>
-      <a shape="rect" class="external-link" href="http://apache.org/hello_world_soap_http">http://apache.org/hello_world_soap_http</a>
+      <span class="nolink">http://apache.org/hello_world_soap_http</span>
     </code> target namespace. All of the WSDL entities defined in this target namespace
(for example, the Greeter port type and the SOAPService service) map to Java classes in the
corresponding Java package.</li><li><code>org.apache.hello_world_soap_http.types</code>
<br clear="none"> This package name is generated from the <code>
-      <a shape="rect" class="external-link" href="http://apache.org/hello_world_soap_http/types">http://apache.org/hello_world_soap_http/types</a>
+      <span class="nolink">http://apache.org/hello_world_soap_http/types</span>
     </code> target namespace. All of the XML types defined in this target namespace
(that is, everything defined in the <code>wsdl:types</code> element of the HelloWorld
contract) map to Java classes in the corresponding Java package.</li></ul><p>The
stub files generated by the wsdl2java command fall into the following categories:</p><ul><li>Classes
representing WSDL entities (in the <code>org.apache.hello_world_soap_http</code>
package) - the following classes are generated to represent WSDL entities:<ul><li><code>Greeter</code>
is a Java interface that represents the Greeter WSDL port type. In JAX-WS terminology, this
Java interface is a service endpoint interface.</li><li><code>SOAPService</code>
is a Java class that represents the SOAPService WSDL <code>service</code> element.</li><li><code>PingMeFault</code>
is a Java exception class (extending <code>java.lang.Exception</code>) that represents
the pingMeFault WSDL <code>fault</code> element.</li></ul></li><li>Classes
representi
 ng XML types (in the <code>org.apache.hello_world_soap_http.types</code> package)
- in the HelloWorld example, the only generated types are the various wrappers for the request
and reply messages. Some of these data types are useful for the asynchronous invocation model.</li></ul><h2
id="DevelopingaConsumer-ImplementingaCXFClient">Implementing a CXF Client</h2><p>This
section describes how to write the code for a simple Java client, based on the WSDL contract
<a shape="rect" href="developing-a-consumer.html">above</a>. To implement the
client, you need to use the following stub classes:</p><ul><li>Service class
(that is, <code>SOAPService</code>).</li><li>Service endpoint interface
(that is, <code>Greeter</code>).</li></ul><h4 id="DevelopingaConsumer-Generatedserviceclass">Generated
service class</h4><p>The below shows the typical outline for a generated service
class, <code>ServiceName</code>, which extends the <code>javax.xml.ws.Service</code>
base class.</p><p><span class="conflu
 ence-anchor-link" id="DevelopingaConsumer-Example2"></span></p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Outline of a Generated Service Class</b></div><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public
class ServiceName extends javax.xml.ws.Service {
+<pre class="brush: java; gutter: false; theme: Default">public class ServiceName extends
javax.xml.ws.Service {
   ...
   public ServiceName(URL wsdlLocation, QName serviceName) { }
   
@@ -305,7 +305,7 @@ Apache CXF -- Developing a Consumer
 </div></div><p>The <code>ServiceName</code> class defines the
following methods:</p><ul><li>Constructor methods - the following forms
of constructor are defined:<ul><li><code>
           <em>ServiceName</em>(URL <em>wsdlLocation</em>, QName <em>serviceName</em>)</code>
constructs a service object based on the data in the <em>serviceName</em> service
in the WSDL contract that is obtainable from <em>wsdlLocation</em>.</li><li><code>
           <em>ServiceName</em>()</code> is the default constructor, which
constructs a service object based on the service name and WSDL contract that were provided
at the time the stub code was generated (for example, when running the CXF wsdl2java command).
Using this constructor presupposes that the WSDL contract remains available at its original
location.</li></ul></li><li><code>get_PortName_()</code>
methods - for every <em>PortName</em> port defined on the <em>ServiceName</em>
service, CXF generates a corresponding <code>get_PortName_()</code> method in
Java. Therefore, a <code>wsdl:service</code> element that defines multiple ports
will generate a service class with multiple <code>get_PortName_()</code> methods.</li></ul><h4
id="DevelopingaConsumer-Serviceendpointinterface">Service endpoint interface</h4><p>For
every port type defined in the original WSDL contract, you can generate a corresponding service
endpoint interface in Java. A service endpoint interface is the Java ma
 pping of a WSDL port type. Each operation defined in the original WSDL port type maps to
a corresponding method in the service endpoint interface. The operation's parameters are mapped
as follows:</p><ol><li>The input parameters are mapped to method arguments.</li><li>The
first output parameter is mapped to a return value.</li><li>If there is more than
one output parameter, the second and subsequent output parameters map to method arguments
(moreover, the values of these arguments must be passed using Holder types).</li></ol><p>For
example, the below shows the Greeter service endpoint interface, which is generated from the
Greeter port type defined in <a shape="rect" href="developing-a-consumer.html">#Example1</a>.
For simplicity, <a shape="rect" href="developing-a-consumer.html">#Example3</a>
omits the standard JAXB and JAX-WS annotations.</p><p><span class="confluence-anchor-link"
id="DevelopingaConsumer-Example3"></span></p><div class="code panel pdl"
style="border-width: 1px;"><
 div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>The
Greeter Service Endpoint Interface</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">/*
Generated by WSDLToJava Compiler. */
+<pre class="brush: java; gutter: false; theme: Default">/* Generated by WSDLToJava
Compiler. */
 
 package org.objectweb.hello_world_soap_http;
   ...
@@ -320,7 +320,7 @@ public interface Greeter {
 }
 </pre>
 </div></div><h4 id="DevelopingaConsumer-Clientmainfunction">Client main
function</h4><p>Here is Java code that implements the HelloWorld client. In summary,
the client connects to the <code>SoapPort</code> port on the <code>SOAPService</code>
service and then proceeds to invoke each of the operations supported by the <code>Greeter</code>
port type.</p><p><span class="confluence-anchor-link" id="DevelopingaConsumer-Example4"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Client Implementation Code</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package
demo.hw.client;
+<pre class="brush: java; gutter: false; theme: Default">package demo.hw.client;
 
 import java.io.File;
 import java.net.URL;
@@ -383,10 +383,10 @@ public final class Client {
 }
 </pre>
 </div></div><p>The <code>Client.main()</code> function proceeds
as follows:</p><ol><li>The CXF runtime is implicitly initialized - that
is, provided the CXF runtime classes are loaded. Hence, there is no need to call a special
function in order to initialize CXF.</li><li>The client expects a single string
argument that gives the location of the WSDL contract for HelloWorld. The WSDL location is
stored in <code>wsdlURL</code>.</li><li><p>A new port object
(which enables you to access the remote server endpoint) is created in two steps, as shown
in the following code fragment:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">SOAPService
ss = new SOAPService(wsdlURL, SERVICE_NAME);
+<pre class="brush: java; gutter: false; theme: Default">SOAPService ss = new SOAPService(wsdlURL,
SERVICE_NAME);
 Greeter port = ss.getSoapPort();</pre>
 </div></div><p>To create a new port object, you first create a service
object (passing in the WSDL location and service name) and then call the appropriate <code>get
<em>PortName</em> ()</code> method to obtain an instance of the particular
port you need. In this case, the <code>SOAPService</code> service supports only
the <code>SoapPort</code> port, which is of <code>Greeter</code> type.</p></li><li>The
client proceeds to call each of the methods supported by the <code>Greeter</code>
service endpoint interface.</li><li>In the case of the <code>pingMe()</code>
operation, the example code shows how to catch the <code>PingMeFault</code> fault
exception.</li></ol><h2 id="DevelopingaConsumer-SettingConnectionPropertieswithContexts">Setting
Connection Properties with Contexts</h2><p>You can use JAX-WS contexts to customize
the properties of a client proxy. In particular, contexts can be used to modify connection
properties and to send data in protocol headers. For example, you could use 
 contexts to add a SOAP header, either to a request message or to a response message. The
following types of context are supported on the client side:</p><ul><li><strong>Request
context</strong> - on the client side, the request context enables you to set properties
that affect outbound messages. Request context properties are applied to a specific port instance
and, once set, the properties affect every subsequent operation invocation made on the port,
until such time as a property is explicitly cleared. For example, you might use a request
context property to set a connection timeout or to initialize data for sending in a header.</li><li><strong>Response
context</strong> - on the client side, you can access the response context to read the
property values set by the inbound message from the last operation invocation. Response context
properties are reset after every operation invocation. For example, you might access a response
context property to read header information received f
 rom the last inbound message.</li></ul><h4 id="DevelopingaConsumer-Settingarequestcontext">Setting
a request context</h4><p>To set a particular request context property, <em>ContextPropertyName</em>,
to the value, <em>PropertyValue</em>, use the code shown here:</p><p><span
class="confluence-anchor-link" id="DevelopingaConsumer-Example4"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Setting a Request Context Property on the
Client Side</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">//
Set request context property.
+<pre class="brush: java; gutter: false; theme: Default">// Set request context property.
 java.util.Map&lt;String, Object&gt; requestContext =
   ((javax.xml.ws.BindingProvider)port).getRequestContext();
 requestContext.put(ContextPropertyName, PropertyValue);
@@ -395,7 +395,7 @@ requestContext.put(ContextPropertyName,
 port.SomeOperation();
 </pre>
 </div></div><p>You have to cast the port object to <code>javax.xml.ws.BindingProvider</code>
in order to access the request context. The request context itself is of type, <code>java.util.Map&lt;String,
Object&gt;</code>, which is a hash map that has keys of <code>String</code>
and values of arbitrary type. Use <code>java.util.Map.put()</code> to create a
new entry in the hash map.</p><h4 id="DevelopingaConsumer-Readingaresponsecontext">Reading
a response context</h4><p>To retrieve a particular response context property,
<em>ContextPropertyName</em>, use the code shown here:</p><p><span
class="confluence-anchor-link" id="DevelopingaConsumer-Example5"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Reading a Response Context Property on
the Client Side</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">//
Invoke an operation.
+<pre class="brush: java; gutter: false; theme: Default">// Invoke an operation.
 port.SomeOperation();
 
 // Read response context property.
@@ -404,7 +404,7 @@ java.util.Map&lt;String, Object&gt; resp
 PropertyType propValue = (PropertyType) responseContext.get(ContextPropertyName);
 </pre>
 </div></div><p>The response context is of type, <code>java.util.Map&lt;String,
Object&gt;</code>, which is a hash map that has keys of type <code>String</code>
and values of an arbitrary type. Use <code>java.util.Map.get()</code> to access
an entry in the hash map of response context properties.</p><h4 id="DevelopingaConsumer-Supportedcontexts">Supported
contexts</h4><p>CXF supports the following context properties:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Context Property Name</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Context Property Type</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.cxf.ws.addressing.JAXWSAConstants.CLIENT_ADDRESSING_PROPERTIES</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>org.apache.cxf.ws.addressing.AddressingProperties</code></p></td></tr></tbody></table></div><h2
id="DevelopingaConsumer-Asynchrono
 usInvocationModel">Asynchronous Invocation Model</h2><p>In addition to the
usual synchronous mode of invocation, CXF also supports two forms of asynchronous invocation,
as follows:</p><ul><li><strong>Polling approach</strong> - in
this case, to invoke the remote operation, you call a special method that has no output parameters,
but returns a <code>javax.xml.ws.Response</code> instance. The <code>Response</code>
object (which inherits from the <code>javax.util.concurrency.Future</code> interface)
can be polled to check whether or not a response message has arrived.</li><li><strong>Callback
approach</strong> - in this case, to invoke the remote operation, you call another special
method that takes a reference to a callback object (of <code>javax.xml.ws.AsyncHandler</code>
type) as one of its parameters. Whenever the response message arrives at the client, the CXF
runtime calls back on the <code>AsyncHandler</code> object to give it the contents
of the response message.</li></ul><p>Bo
 th of these asynchronous invocation approaches are described here and illustrated by code
examples.</p><h4 id="DevelopingaConsumer-Contractforasynchronousexample">Contract
for asynchronous example</h4><p>The following example shows the WSDL contract
that is used for the asynchronous example. The contract defines a single port type, <code>GreeterAsync</code>,
which contains a single operation, <code>greetMeSometime</code>.</p><p><span
class="confluence-anchor-link" id="DevelopingaConsumer-Example6"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>HelloWorld WSDL Contract for Asynchronous
Example</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;wsdl:definitions
xmlns="http://schemas.xmlsoap.org/wsdl/"
+<pre class="brush: java; gutter: false; theme: Default">&lt;wsdl:definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
            xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
            xmlns:tns="http://apache.org/hello_world_async_soap_http"
            xmlns:x1="http://apache.org/hello_world_async_soap_http/types"
@@ -468,9 +468,9 @@ PropertyType propValue = (PropertyType)
 &lt;/wsdl:definitions&gt;
 </pre>
 </div></div><h4 id="DevelopingaConsumer-Generatingtheasynchronousstubcode">Generating
the asynchronous stub code</h4><p>The asynchronous style of invocation requires
extra stub code (for example, dedicated asychronous methods defined on the service endpoint
interface). This special stub code is not generated by default, however. To switch on the
asynchronous feature and generate the requisite stub code, you must use the mapping customization
feature from the WSDL 2.0 specification.</p><p>Customization enables you to modify
the way the wsdl2java utility generates stub code. In particular, it enables you to modify
the WSDL-to-Java mapping and to switch on certain features. Here, customization is used to
switch on the asynchronous invocation feature. Customizations are specified using a binding
declaration, which you define using a <code>jaxws:bindings</code> tag (where the
jaxws prefix is tied to the <code>
-    <a shape="rect" class="external-link" href="http://java.sun.com/xml/ns/jaxws" rel="nofollow">http://java.sun.com/xml/ns/jaxws</a>
+    <span class="nolink">http://java.sun.com/xml/ns/jaxws</span>
   </code> namespace). There are two alternative ways of specifying a binding declaration:</p><ul><li><strong>External
binding declaration</strong> - the <code>jaxws:bindings</code> element is
defined in a file separately from the WSDL contract. You specify the location of the binding
declaration file to the wsdl2java utility when you generate the stub code.</li><li><strong>Embedded
binding declaration</strong> - you can also embed the <code>jaxws:bindings</code>
element directly in a WSDL contract, treating it as a WSDL extension. In this case, the settings
in <code>jaxws:bindings</code> apply only to the immediate parent element.</li></ul><p>This
section considers only the first approach, the external binding declaration. The template
for a binding declaration file that switches on asynchronous invocations is shown next:</p><p><span
class="confluence-anchor-link" id="DevelopingaConsumer-Example7"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHead
 er panelHeader pdl" style="border-bottom-width: 1px;"><b>Template for an Asynchronous
Binding Declaration</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;bindings
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+<pre class="brush: java; gutter: false; theme: Default">&lt;bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
           wsdlLocation="&lt;at:var at:name="WSDL_LOCATION" /&gt;/hello_world_async.wsdl"
           xmlns="http://java.sun.com/xml/ns/jaxws"&gt;
@@ -482,7 +482,7 @@ PropertyType propValue = (PropertyType)
 </div></div><p>Where <em>AffectedWSDLContract</em> specifies
the URL of the WSDL contract that is affected by this binding declaration. The <em>AffectedNode</em>
is an XPath value that specifies which node (or nodes) from the WSDL contract are affected
by this binding declaration. You can set <em>AffectedNode</em> to <code>wsdl:definitions</code>,
if you want the entire WSDL contract to be affected. The {jaxws:enableAsyncMapping}} element
is set to <code>true</code> to enable the asynchronous invocation feature.</p><p>For
example, if you want to generate asynchronous methods only for the <code>GreeterAsync</code>
port type, you could specify <code>&lt;bindings node="wsdl:definitions/wsdl:portType<u><a
shape="rect" class="unresolved" href="#">@name='GreeterAsync'</a></u>"&gt;</code>
in the preceding binding declaration.</p><p>Assuming that the binding declaration
is stored in a file, <code>async_binding.xml</code>, you can generate the requisite
stub files with asynchronous support b
 y entering the following wsdl2java command:</p><div class="panel" style="border-width:
1px;"><div class="panelContent">
 <p><code>wsdl2java -ant -client -d ClientDir -b async_binding.xml hello_world.wsdl</code></p>
 </div></div><p>When you run the wsdl2java command, you specify the location
of the binding declaration file using the -b option. After generating the stub code in this
way, the <code>GreeterAsync</code> service endpoint interface (in the file <code>GreeterAsync.java</code>)
is defined as shown below:</p><p><span class="confluence-anchor-link" id="DevelopingaConsumer-Example8"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Service Endpoint Interface with Methods
for Asynchronous Invocations</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">/*
Generated by WSDLToJava Compiler. */
+<pre class="brush: java; gutter: false; theme: Default">/* Generated by WSDLToJava
Compiler. */
 package org.apache.hello_world_async_soap_http;
 ...
 import java.util.concurrent.Future;
@@ -505,7 +505,7 @@ public interface GreeterAsync {
 }
 </pre>
 </div></div><p>In addition to the usual synchronous method, <code>greetMeSometime()</code>,
two asynchronous methods are also generated for the <code>greetMeSometime</code>
operation, as follows:</p><ul><li><code>greetMeSometimeAsync()</code>
method with <code>Future&lt;?&gt;</code> return type and an extra <code>javax.xml.ws.AsyncHandler</code>
parameter - call this method for the callback approach to asynchronous invocation.</li><li><code>greetMeSometimeAsync()</code>
method with <code>Response&lt;GreetMeSometimeResponse&gt;</code> return
type - call this method for the polling approach to asynchronous invocation.</li></ul><p>The
details of the callback approach and the polling approach are discussed in the following subsections.</p><h4
id="DevelopingaConsumer-Implementinganasynchronousclientwiththepollingapproach">Implementing
an asynchronous client with the polling approach</h4><p>The below sample illustrates
the polling approach to making an asynchronous operation call. Using t
 his approach, the client invokes the operation by calling the special Java method, <code>_OperationName_Async()</code>,
that returns a <code>javax.xml.ws.Response&lt;T&gt;</code> object, where
T is the type of the operation's response message. The <code>Response&lt;T&gt;</code>
object can be polled at a later stage to check whether the operation's response message has
arrived.</p><p><span class="confluence-anchor-link" id="DevelopingaConsumer-Example9"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Polling Approach for an Asynchronous Operation
Call</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package
demo.hw.client;
+<pre class="brush: java; gutter: false; theme: Default">package demo.hw.client;
 
 import java.io.File;
 import java.util.concurrent.Future;
@@ -538,14 +538,14 @@ public final class Client {
 }
 </pre>
 </div></div><p>The <code>greetMeSometimeAsync()</code> method
invokes the <code>greetMeSometimes</code> operation, transmitting the input parameters
to the remote service and returning a reference to a <code>javax.xml.ws.Response&lt;GreetMeSometimeResponse&gt;</code>
object. The <code>Response</code> class is defined by extending the standard <code>java.util.concurrency.Future&lt;T&gt;</code>
interface, which is specifically designed for polling the outcome of work performed by a concurrent
thread. There are essentially two basic approaches to polling using the <code>Response</code>
object:</p><ul><li><p><strong>Non-blocking polling</strong>
- before attempting to get the result, check whether the response has arrived by calling the
non-blocking<br clear="none"> <code>Response&lt;T&gt;.isDone()</code>
method. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">Response&lt;GreetMeSometimeResponse&gt;
greetMeSomeTimeResp = ...;
+<pre class="brush: java; gutter: false; theme: Default">Response&lt;GreetMeSometimeResponse&gt;
greetMeSomeTimeResp = ...;
 
 if (greetMeSomeTimeResp.isDone()) {
   GreetMeSometimeResponse reply = greetMeSomeTimeResp.get();
 }
 </pre>
 </div></div></li><li><p><strong>Blocking polling</strong>
- call <code>Response&lt;T&gt;.get()</code> right away and block until
the response arrives (optionally specifying a timeout). For example, to poll for a response,
with a 60 second timeout:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">Response&lt;GreetMeSometimeResponse&gt;
greetMeSomeTimeResp = ...;
+<pre class="brush: java; gutter: false; theme: Default">Response&lt;GreetMeSometimeResponse&gt;
greetMeSomeTimeResp = ...;
 
 GreetMeSometimeResponse reply = greetMeSomeTimeResp.get(
   60L,
@@ -553,7 +553,7 @@ GreetMeSometimeResponse reply = greetMeS
 );
 </pre>
 </div></div></li></ul><h4 id="DevelopingaConsumer-Implementinganasynchronousclientwiththecallbackapproach">Implementing
an asynchronous client with the callback approach</h4><p>An alternative approach
to making an asynchronous operation invocation is to implement a callback class, by deriving
from the<code> javax.xml.ws.AsyncHandler</code> interface. This callback class
must implement a <code>handleResponse()</code> method, which is called by the
CXF runtime to notify the client that the response has arrived. The following shows an outline
of the <code>AsyncHandler</code> interface that you need to implement.</p><p><span
class="confluence-anchor-link" id="DevelopingaConsumer-Example10"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>The javax.xml.ws.AsyncHandler Interface</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package
javax.xml.ws;
+<pre class="brush: java; gutter: false; theme: Default">package javax.xml.ws;
 
 public interface AsyncHandler&lt;T&gt;
 {
@@ -561,7 +561,7 @@ public interface AsyncHandler&lt;T&gt;
 }
 </pre>
 </div></div><p>In this example, a callback class, <code>TestAsyncHandler</code>,
is defined as shown below.</p><p><span class="confluence-anchor-link" id="DevelopingaConsumer-Example11"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>The TestAsyncHandler Callback Class</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package
demo.hw.client;
+<pre class="brush: java; gutter: false; theme: Default">package demo.hw.client;
 
 import javax.xml.ws.AsyncHandler;
 import javax.xml.ws.Response;
@@ -585,7 +585,7 @@ public class TestAsyncHandler implements
 }
 </pre>
 </div></div><p>The implementation of <code>handleResponse()</code>
shown in <a shape="rect" href="developing-a-consumer.html">#Example11</a> simply
gets the response data and stores it in a member variable, <code>reply</code>.
The extra <code>getResponse()</code> method is just a convenience method that
extracts the sole output parameter (that is, <code>responseType</code>) from the
response.</p><p><a shape="rect" href="developing-a-consumer.html">#Example12</a>
illustrates the callback approach to making an asynchronous operation call. Using this approach,
the client invokes the operation by calling the special Java method, <code>_OperationName_Async()</code>,
that returns a <code>java.util.concurrency.Future&lt;?&gt;</code> object
and takes an extra parameter of <code>AsyncHandler&lt;T&gt;</code>.</p><p><span
class="confluence-anchor-link" id="DevelopingaConsumer-Example12"></span></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" st
 yle="border-bottom-width: 1px;"><b>Callback Approach for an Asynchronous Operation
Call</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package
demo.hw.client;
+<pre class="brush: java; gutter: false; theme: Default">package demo.hw.client;
 
 import java.io.File;
 import java.util.concurrent.Future;



Mime
View raw message