...
DOMSource
SAXSource
StreamSource
Info When using
Source
objects the developer is responsible for ensuring that all required binding specific wrappers are added to the message. For example, when interacting with a service expecting SOAP messages, the developer must ensure that the required SOAP envelope is added to the outgoing request and that the SOAP envelope's contents are correct.
Using SOAPMessage
objects
Dispatch
objects can use javax.xml.soap.SOAPMessage
objects when the following conditions are true:
...
You can pass any JAXB object understood by the JAXBContext
object as the parameter to the invoke()
method. You can also cast the returned message into any JAXB object understood by the JAXBContext
object.
Working with Dispatch
Objects
Procedure
To use a Dispatch object to invoke a remote service you do the following:
- Create a
Dispatch
object. - Construct a request message.
- Call the proper
invoke()
method. - Parse the response message.
Creating a Dispatch
object
To create a Dispatch
object do the following:
- Create a
Service
object to represent thewsdl:service
element defining the service on which theDispatch
object will make invocations. - Create the
Dispatch
object using theService
object'screateDispatch()
method.Code Block public Dispatch<T> createDispatch(QName portName, java.lang.Class<T> type, Service.Mode mode) throws WebServiceException;
Note If you are using JAXB objects the method signature for
createDispatch()
is:Code Block public Dispatch<T> createDispatch(QName portName, javax.xml.bind.JAXBContext context, Service.Mode mode) throws WebServiceException;
The following table describes the parameters for createDispatch()
.
Parameter | Description |
---|---|
portName | Specifies the QName of the |
type | Specifies the data type of the objects used by the |
mode | Specifies the usage mode for the |
The code bellow creates a Dispatch
object that works with DOMSource
objects in payload mode.
Code Block |
---|
package com.iona.demo; import javax.xml.namespace.QName; import javax.xml.ws.Service; public class Client { public static void main(String args[]) { |
...
QName serviceName = new QName("http://org.apache.cxf", "stockQuoteReporter");
Service s = Service.create(serviceName);
QName portName = new QName("http://org.apache.cxf", "stockQuoteReporterPort");
Dispatch<DOMSource> dispatch = createDispatch(portName,
DOMSource.class,
Service.Mode.PAYLOAD);
...
|
Constructing request messages
When working with Dispatch
objects requests must be built from scratch. The developer is responsible for ensuring that the messages passed to a Dispatch
object match a request that the targeted service provider can process. This requires precise knowledge about the messages used by the service provider and what, if any, header information it requires.
This information can be provided by a WSDL document or an XMLSchema document that defines the messages. While service providers vary greatly there are a few guidelines that can be followed:
- The root element of the request is based in the value of the name attribute of the
wsdl:operation
element that corresponds to the operation being invoked.Warning If the service being invoked uses doc/literal bare messages, the root element of the request will be based on the value of name attribute of the
wsdl:part
element refered to by thewsdl:operation
element. - The root element of the request will be namespace qualified.
- If the service being invoked uses rpc/literal messages, the top-level elements in the request will not be namespace qualified.
Info The children of top-level elements may be namespace qualified. To be certain you will need to check their schema definitions.
- If the service being invoked uses rpc/literal messages, none of the top-level elements can be null.
- If the service being invoked uses doc/literal messages, the schema definition of the message determines if any of the elements are namespace qualified.
For more information about how services use XML messages see the WS-I Basic Profile.
Synchronous invocation
For consumers that make synchronous invocations that generate a response, you use the Dispatch
object's invoke()
method shown bellow.
Code Block |
---|
T invoke(T msg)
throws WebServiceException;
|
The type of both the response and the request passed to the invoke()
method are determined when the Dispatch object is created. For example if you created a Dispatch
object using createDispatch(portName, SOAPMessage.class, Service.Mode.MESSAGE)
the response and the request would both be SOAPMessage
objects.
Note |
---|
When using JAXB objects, the response and the request can be of any type the provided |
The code bellow makes a synchronous invocation on a remote service using a DOMSource
object.
Code Block |
---|
// Creating a DOMSource Object for the request
DocumentBuilder db = DocumentBuilderFactory.newDocumentBuilder();
Document requestDoc = db.newDocument();
Element root = requestDoc.createElementNS("http://org.apache.cxf/stockExample", "getStockPrice");
root.setNodeValue("DOW");
DOMSource request = new DOMSource(requestDoc);
// Dispatch disp created previously
DOMSource response = disp.invoke(request);
|
Asynchronous invocation
Dispatch
objects also support asynchronous invocations. As with the higher level asynchronous APIs discussed in Chapter 4, Dispatch
objects can use both the polling approach and the callback approach.
When using the polling approach the invokeAsync()
method returns a Response<t>
object that can be periodically polled to see if the response has arrived.
Code Block |
---|
Response <T> invokeAsync(T msg)
throws WebServiceException;
|
When using the callback approach the invokeAsync()
method takes an AsyncHandler
implementation that processes the response when it is returned.
Code Block |
---|
Future<?> invokeAsync(T msg, AsyncHandler<T> handler)
throws WebServiceException;
|
Note |
---|
As with the synchronous |
Oneway invocation
When a request does not generate a response, you make remote invocations using the Dispatch
object's invokeOneWay()
.
Code Block |
---|
void invokeOneWay(T msg)
throws WebServiceException;
|
The type of object used to package the request is determined when the Dispatch
object is created. For example if the Dispatch
object is created using createDispatch(portName, DOMSource.class, Service.Mode.PAYLOAD)
the request would be packaged into a DOMSource
object.
Note |
---|
When using JAXB objects, the response and the request can be of any type the provided |
The code bellow makes a one way invocation on a remote service using a JAXB object.
Code Block |
---|
// Creating a JAXBContext and an Unmarshaller for the request
JAXBContext jbc = JAXBContext.newInstance("org.apache.cxf.StockExample");
Unmarshaller u = jbc.createUnmarshaller();
// Read the request from disk
File rf = new File("request.xml");
GetStockPrice request = (GetStockPrice)u.unmarshal(rf);
// Dispatch disp created previously
disp.invokeOneWay(request);
|