Developing a Consumer

Generating the Stub Code

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 wsdl2java 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. For CXF clients, the wsdl2java utility can generate the following kinds of code:

Stub code - supporting files for implementing a CXF client.
Client starting point code - sample client code that connects to the remote service and invokes every operation on the remote service.
Ant build file - a build.xml file intended for use with the ant build utility. It has targets for building and for running the sample client application.

HelloWorld WSDL Contract

The below shows the HelloWorld WSDL contract. This contract defines a single port type, Greeter, with a SOAP binding, Greeter_SOAPBinding, and a service, SOAPService, which has a single port, SoapPort.

<?xml version="1.0" encoding="UTF-8"?>
            <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"
            xmlns:x1="http://apache.org/hello_world_soap_http/types"
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
            xmlns:xsd="http://www.w3.org/2001/XMLSchema">
            <wsdl:types>
            <schema targetNamespace=
            "http://apache.org/hello_world_soap_http/types" 
            xmlns="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://apache.org/hello_world_soap_http/types"
            elementFormDefault="qualified">
            <simpleType name="MyStringType">
            <restriction base="string">
            <maxLength value="30" />
            </restriction>
            </simpleType>
            <element name="sayHi">
            <complexType/>
            </element>
            <element name="sayHiResponse">
            <complexType>
            <sequence>
            <element name="responseType" type="string"/>
            </sequence>
            </complexType>
            </element>
            <element name="greetMe">
            <complexType>
            <sequence>
            <element name="requestType" type="tns:MyStringType"/>
            </sequence>
            </complexType>
            </element>
            <element name="greetMeResponse">
            <complexType>
            <sequence>
            <element name="responseType" type="string"/>
            </sequence>
            </complexType>
            </element>
            <element name="greetMeOneWay">
            <complexType>
            <sequence>
            <element name="requestType" type="string"/>
            </sequence>
            </complexType>
            </element>
            <element name="pingMe">
            <complexType/>
            </element>
            <element name="pingMeResponse">
            <complexType/>
            </element>
            <element name="faultDetail">
            <complexType>
            <sequence>
            <element name="minor" type="short"/>
            <element name="major" type="short"/>
            </sequence>
            </complexType>
            </element>
            </schema>
            </wsdl:types>

<wsdl:message name="sayHiRequest">
            <wsdl:part element="x1:sayHi" name="in"/>
            </wsdl:message>
            <wsdl:message name="sayHiResponse">
            <wsdl:part element="x1:sayHiResponse" name="out"/>
            </wsdl:message>
            <wsdl:message name="greetMeRequest">
            <wsdl:part element="x1:greetMe" name="in"/>
            </wsdl:message>
            <wsdl:message name="greetMeResponse">
            <wsdl:part element="x1:greetMeResponse" name="out"/>
            </wsdl:message>
            <wsdl:message name="greetMeOneWayRequest">
            <wsdl:part element="x1:greetMeOneWay" name="in"/>
            </wsdl:message>
            <wsdl:message name="pingMeRequest">
            <wsdl:part name="in" element="x1:pingMe"/>
            </wsdl:message>
            <wsdl:message name="pingMeResponse">
            <wsdl:part name="out" element="x1:pingMeResponse"/>
            </wsdl:message>       
            <wsdl:message name="pingMeFault">
            <wsdl:part name="faultDetail" element="x1:faultDetail"/>
            </wsdl:message>  
            <wsdl:portType name="Greeter">
            <wsdl:operation name="sayHi">
            <wsdl:input message="tns:sayHiRequest" name="sayHiRequest"/>
            <wsdl:output message="tns:sayHiResponse" name="sayHiResponse"/>
            </wsdl:operation>
            
            <wsdl:operation name="greetMe">
            <wsdl:input message="tns:greetMeRequest" 
            name="greetMeRequest"/>
            <wsdl:output message="tns:greetMeResponse" 
            name="greetMeResponse"/>
            </wsdl:operation>
            
            <wsdl:operation name="greetMeOneWay">
            <wsdl:input message="tns:greetMeOneWayRequest" 
            name="greetMeOneWayRequest"/>
            </wsdl:operation>
            
            <wsdl:operation name="pingMe">
            <wsdl:input name="pingMeRequest" message="tns:pingMeRequest"/>
            <wsdl:output name="pingMeResponse" message="tns:pingMeResponse"/>
            <wsdl:fault name="pingMeFault" message="tns:pingMeFault"/>
            </wsdl:operation> 
            </wsdl:portType>

<wsdl:binding name="Greeter_SOAPBinding" type="tns:Greeter">
            <soap:binding style="document" 
            transport="http://schemas.xmlsoap.org/soap/http"/>
            
            <wsdl:operation name="sayHi">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="sayHiRequest">
            <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output name="sayHiResponse">
            <soap:body use="literal"/>
            </wsdl:output>
            </wsdl:operation>
            
            <wsdl:operation name="greetMe">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="greetMeRequest">
            <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output name="greetMeResponse">
            <soap:body use="literal"/>
            </wsdl:output>
            </wsdl:operation>
            
            <wsdl:operation name="greetMeOneWay">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="greetMeOneWayRequest">
            <soap:body use="literal"/>
            </wsdl:input>
            </wsdl:operation>
            
            <wsdl:operation name="pingMe">
            <soap:operation style="document"/>
            <wsdl:input>
            <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
            <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="pingMeFault">
            <soap:fault name="pingMeFault" use="literal"/>
            </wsdl:fault>
            </wsdl:operation>
            
            </wsdl:binding>
            
            <wsdl:service name="SOAPService">
            <wsdl:port binding="tns:Greeter_SOAPBinding" name="SoapPort">
            <soap:address 
            location="http://localhost:9000/SoapContext/SoapPort"/>
            </wsdl:port>
            </wsdl:service>
            </wsdl:definitions>

The Greeter port type from the example above defines the following WSDL operations:

sayHi - has a single output parameter, of xsd:string .
greetMe - has an input parameter, of xsd:string , and an output parameter, of xsd:string .
greetMeOneWay - has a single input parameter, of xsd:string . 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).
pingMe - has no input parameters and no output parameters, but it can raise a fault exception.

The above example also defines a binding, Greeter_SOAPBinding , 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 SOAPService service can be generated automatically by running the CXF wsdl2service utility.

Generating the stub code from the WSDL contract

After defining the WSDL contract, you can generate client code using the CXF wsdl2java utility. Enter the following command at a command-line prompt:

wsdl2java -client -d ClientDir hello_world.wsdl

Where ClientDir is the location of a directory where you would like to put the generated files and hello_world.wsdl is a file containing the contract shown in the above WSDL. The -client option generates starting point code for a client main() method.

The preceding wsdl2java command generates the following Java packages:

org.apache.hello_world_soap_http This package name is generated from the http://apache.org/hello_world_soap_http 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.
org.apache.hello_world_soap_http.types This package name is generated from the http://apache.org/hello_world_soap_http/types" target namespace. All of the XML types defined in this target namespace (that is, everything defined in the wsdl:types element of the HelloWorld contract) map to Java classes in the corresponding Java package.

The stub files generated by the wsdl2java command fall into the following categories:

Classes representing WSDL entities (in the org.apache.hello_world_soap_http package) - the following classes are generated to represent WSDL entities:
- Greeter is a Java interface that represents the Greeter WSDL port type. In JAX-WS terminology, this Java interface is a service endpoint interface.
- SOAPService is a Java class that represents the SOAPService WSDL service element.
- PingMeFault is a Java exception class (extending java.lang.Exception ) that represents the pingMeFault WSDL fault element.
Classes representing XML types (in the org.apache.hello_world_soap_http.types 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.

Generating the Stub Code

HelloWorld WSDL Contract

Generating the stub code from the WSDL contract

In this section

Did this page help you?