Author: buildbot
Date: Fri Apr 13 10:57:25 2018
New Revision: 1028349
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 Fri Apr 13
10:57:25 2018
@@ -32,8 +32,8 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
-<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -283,15 +283,14 @@ Apache CXF -- Developing a Consumer
</wsdl:service>
</wsdl:definitions>
</pre>
-</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<br clear="none"> automatically -
for example, by running either of the CXF wsdl2soap or wsdl2xml utilities.
Likewise, the <code>SOAPService</code> ser
vice can be generated 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">
+</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<br clear="none">
<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>
+</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>
</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>
- </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<br clear="none"> 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><s
pan class="confluence-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
-{
+ </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 {
...
public ServiceName(URL wsdlLocation, QName serviceName) { }
@@ -310,8 +309,7 @@ Apache CXF -- Developing a Consumer
package org.objectweb.hello_world_soap_http;
...
-public interface Greeter
-{
+public interface Greeter {
public java.lang.String sayHi();
public java.lang.String greetMe(java.lang.String requestType);
@@ -337,26 +335,19 @@ public final class Client {
new QName("http://apache.org/hello_world_soap_http";,
"SOAPService");
- private Client()
- {
- }
+ private Client() { }
- public static void main(String args[]) throws Exception
- {
- if (args.length == 0)
- {
+ public static void main(String args[]) throws Exception {
+ if (args.length == 0) {
System.out.println("please specify wsdl");
System.exit(1);
}
URL wsdlURL;
File wsdlFile = new File(args[0]);
- if (wsdlFile.exists())
- {
+ if (wsdlFile.exists()) {
wsdlURL = wsdlFile.toURL();
- }
- else
- {
+ } else {
wsdlURL = new URL(args[0]);
}
@@ -488,7 +479,7 @@ PropertyType propValue = (PropertyType)
</bindings>
</bindings>
</pre>
-</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><bindings
node="wsdl:definitions/wsdl:portType<a shape="rect" class="unresolved"
href="#">@name='GreeterAsync'</a>"></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 by enter
ing the following wsdl2java command:</p><div class="panel"
style="border-width: 1px;"><div class="panelContent">
+</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><bindings
node="wsdl:definitions/wsdl:portType<u><a shape="rect" class="unresolved"
href="#">@name='GreeterAsync'</a></u>"></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. */
@@ -513,7 +504,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<?></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<GreetMeSometimeResponse></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<br clear="none"> operation by calling the
special Java method, <code>_OperationName_Async()</code>, that returns a
<code>javax.xml.ws.Response<T></code> object, where T is the type of the
operation's response message. The <code>Response<T></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">
+</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<?></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<GreetMeSometimeResponse></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<T></code> object, where T is the type of the
operation's response message. The <code>Response<T></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;
import java.io.File;
@@ -528,8 +519,7 @@ import org.apche.hello_world_async_soap_
public final class Client {
private static final QName SERVICE_NAME
- = new QName("http://objectweb.org/hello_world_async_soap_http";,
- "SOAPService");
+ = new QName("http://objectweb.org/hello_world_async_soap_http";,
"SOAPService");
private Client() {}
@@ -562,7 +552,7 @@ GreetMeSometimeResponse reply = greetMeS
java.util.concurrent.TimeUnit.SECONDS
);
</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<br clear="none">
<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">
+</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;
public interface AsyncHandler<T>
