You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2018/04/13 10:57:25 UTC
svn commit: r1028349 - in /websites/production/cxf/content:
cache/docs.pageCache docs/developing-a-consumer.html
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>