Page History

...

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.

...

The Greeter port type from #Example1 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.

#Example1 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.

...

• 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.

...

The ServiceName class in #Example2 defines the following methods:

• Constructor methods â?? â€" the following forms of constructor are defined:
  • ServiceName(URL wsdlLocation, QName serviceName) constructs a service object based on the data in the serviceName service in the WSDL contract that is obtainable from wsdlLocation.
  • ServiceName() 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 CeltiXfire wsdl2java command). Using this constructor presupposes that the WSDL contract remains available at its original location.
• get_PortName_() methods â?? â€" for every PortName port defined on the ServiceName service, CXF generates a corresponding get_PortName_() method in Java. Therefore, a wsdl:service element that defines multiple ports will generate a service class with multiple get_PortName_() methods.

...

1. 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.
2. The client expects a single string argument that gives the location of the WSDL contract for HelloWorld. The WSDL location is stored in wsdlURL.
3. 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:

   Code Block
   SOAPService ss = new SOAPService(wsdlURL, SERVICE_NAME); Greeter port = ss.getSoapPort();

   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 get PortName () method to obtain an instance of the particular port you need. In this case, the SOAPService service supports only the SoapPort port, which is of Greeter type.
4. The client proceeds to call each of the methods supported by the Greeter service endpoint interface.
5. In the case of the pingMe() operation, the example code shows how to catch the PingMeFault fault exception.

...

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:

• Request context â?? â€" 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.</para>
• Response context â?? â€" 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 from the last inbound message.

...

In addition to the usual synchronous mode of invocation, CXF also supports two forms of asynchronous invocation, as follows:

• Polling approach â?? â€" in this case, to invoke the remote operation, you call a special method that has no output parameters, but returns a javax.xml.ws.Response instance. The Response object (which inherits from the javax.util.concurrency.Future interface) can be polled to check whether or not a response message has arrived.
• Callback approach â?? â€" in this case, to invoke the remote operation, you call another special method that takes a reference to a callback object (of javax.xml.ws.AsyncHandler type) as one of its parameters. Whenever the response message arrives at the client, the CXF runtime calls back on the AsyncHandler object to give it the contents of the response message.

...

• External binding declaration â?? â€" the jaxws:bindings 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.
• Embedded binding declaration â?? â€" you can also embed the jaxws:bindings element directly in a WSDL contract, treating it as a WSDL extension. In this case, the settings in jaxws:bindings apply only to the immediate parent element.

...

• greetMeSometimeAsync() method with Future<?> return type and an extra javax.xml.ws.AsyncHandler parameter â?? â€" call this method for the callback approach to asynchronous invocation.
• greetMeSometimeAsync() method with Response<GreetMeSometimeResponse> return type â?? â€" call this method for the polling approach to asynchronous invocation.

...

The greetMeSometimeAsync() method invokes the greetMeSometimes operation, transmitting the input parameters to the remote service and returning a reference to a javax.xml.ws.Response<GreetMeSometimeResponse> object. The Response class is defined by extending the standard java.util.concurrency.Future<T> 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 Response object:

• Non-blocking polling â?? â€" before attempting to get the result, check whether the response has arrived by calling the non-blocking
  Response<T>.isDone() method. For example:

  Code Block
  Response<GreetMeSometimeResponse> greetMeSomeTimeResp = ...; if (greetMeSomeTimeResp.isDone()) { GreetMeSometimeResponse reply = greetMeSomeTimeResp.get(); }

• Blocking polling â?? â€" call Response<T>.get() right away and block until the response arrives (optionally specifying a timeout). For example, to poll for a response, with a 60 second timeout:

  Code Block
  Response<GreetMeSometimeResponse> greetMeSomeTimeResp = ...; GreetMeSometimeResponse reply = greetMeSomeTimeResp.get( 60L, java.util.concurrent.TimeUnit.SECONDS );

...

The Future<?> object returned by greetMeSometimeAsync() can be used only to test whether or not a response has arrived yet â?? â€" for example, by calling response.isDone(). The value of the response is only made available to the callback object, testAsyncHandler.