SupportConsoleDevelopersStart a trialContact

Chapter 41. Using Raw XML Messages

Abstract

The high-level JAX-WS APIs shield the developer from using native XML messages by marshaling the data into JAXB objects. However, there are cases when it is better to have direct access to the raw XML message data that is passing on the wire. The JAX-WS APIs provide two interfaces that provide access to the raw XML: the Dispatch interface is the client-side interface, and the Provider interface is the server-side interface.

41.1. Using XML in a Consumer

Abstract

The Dispatch interface is a low-level JAX-WS API that allows you work directly with raw messages. It accepts and returns messages, or payloads, of a number of types including DOM objects, SOAP messages, and JAXB objects. Because it is a low-level API, the Dispatch interface does not perform any of the message preparation that the higher-level JAX-WS APIs perform. You must ensure that the messages, or payloads, that you pass to the Dispatch object are properly constructed, and make sense for the remote operation being invoked.

41.1.1. Usage Modes

Overview

Dispatch objects have two usage modes:
The usage mode you specify for a Dispatch object determines the amount of detail that is passed to the user level code.

Message mode

In message mode, a Dispatch object works with complete messages. A complete message includes any binding specific headers and wrappers. For example, a consumer interacting with a service that requires SOAP messages must provide the Dispatch object's invoke() method a fully specified SOAP message. The invoke() method also returns a fully specified SOAP message. The consumer code is responsible for completing and reading the SOAP message's headers and the SOAP message's envelope information.
Tip
Message mode is not ideal when working with JAXB objects.
To specify that a Dispatch object uses message mode provide the value java.xml.ws.Service.Mode.MESSAGE when creating the Dispatch object. For more information about creating a Dispatch object see the section called “Creating a Dispatch object”.

Payload mode

In payload mode, also called message payload mode, a Dispatch object works with only the payload of a message. For example, a Dispatch object working in payload mode works only with the body of a SOAP message. The binding layer processes any binding level wrappers and headers. When a result is returned from the invoke() method the binding level wrappers and headers are already striped away, and only the body of the message is left.
Tip
When working with a binding that does not use special wrappers, such as the Apache CXF XML binding, payload mode and message mode provide the same results.
To specify that a Dispatch object uses payload mode provide the value java.xml.ws.Service.Mode.PAYLOAD when creating the Dispatch object. For more information about creating a Dispatch object see the section called “Creating a Dispatch object”.

41.1.2. Data Types

Overview

Because Dispatch objects are low-level objects, they are not optimized for using the same JAXB generated types as the higher level consumer APIs. Dispatch objects work with the following types of objects:

Using Source objects

A Dispatch object accepts and returns objects that are derived from the javax.xml.transform.Source interface. Source objects are supported by any binding, and in either message mode or payload mode.
Source objects are low level objects that hold XML documents. Each Source implementation provides methods that access the stored XML documents and then manipulate its contents. The following objects implement the Source interface:
DOMSource
Holds XML messages as a Document Object Model(DOM) tree. The XML message is stored as a set of Node objects that are accessed using the getNode() method. Nodes can be either updated or added to the DOM tree using the setNode() method.
SAXSource
Holds XML messages as a Simple API for XML (SAX) object. SAX objects contain an InputSource object that holds the raw data and an XMLReader object that parses the raw data.
StreamSource
Holds XML messages as a data stream. The data stream can be manipulated the same as any other data stream.
If you create your Dispatch object so that it uses generic Source objects, Apache CXF returns the messages as SAXSource objects.
This behavior can be changed using the endpoint's source-preferred-format property. See Part IV, “Configuring Web Service Endpoints” for information about configuring the Apache CXF runtime.

Using SOAPMessage objects

Dispatch objects can use javax.xml.soap.SOAPMessage objects when the following conditions are true:
  • The Dispatch object is using the SOAP binding
  • The Dispatch object is using message mode
A SOAPMessage object holds a SOAP message. They contain one SOAPPart object and zero or more AttachmentPart objects. The SOAPPart object contains the SOAP specific portions of the SOAP message including the SOAP envelope, any SOAP headers, and the SOAP message body. The AttachmentPart objects contain binary data that is passed as an attachment.

Using DataSource objects

Dispatch objects can use objects that implement the javax.activation.DataSource interface when the following conditions are true:
  • The Dispatch object is using the HTTP binding
  • The Dispatch object is using message mode
DataSource objects provide a mechanism for working with MIME typed data from a variety of sources, including URLs, files, and byte arrays.

Using JAXB objects

While Dispatch objects are intended to be low level APIs that allow you to work with raw messages, they also allow you to work with JAXB objects. To work with JAXB objects a Dispatch object must be passed a JAXBContext that can marshal and unmarshal the JAXB objects in use. The JAXBContext is passed when the Dispatch object is created.
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.
For information on creating a JAXBContext object see Chapter 39, Using A JAXBContext Object.

41.1.3. Working with Dispatch Objects

Procedure

To use a Dispatch object to invoke a remote service the following sequence should be followed:
  1. Create a Dispatch object.
  2. Construct a request message.
  3. Call the proper invoke() method.
  4. Parse the response message.

Creating a Dispatch object

To create a Dispatch object do the following:
  1. Create a Service object to represent the wsdl:service element that defines the service on which the Dispatch object will make invocations. See Section 25.2, “Creating a Service Object”.
  2. Create the Dispatch object using the Service object's createDispatch() method, shown in Example 41.1, “The createDispatch() Method”.

    Example 41.1. The createDispatch() Method

    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:
    public Dispatch<T> createDispatch(QName portName,
                                      javax.xml.bind.JAXBContext context,
                                      Service.Mode mode)
        throws WebServiceException;
    Table 41.1, “Parameters for createDispatch()” describes the parameters for the createDispatch() method.
    Table 41.1. Parameters for createDispatch()
    ParameterDescription
    portNameSpecifies the QName of the wsdl:port element that represents the service provider where the Dispatch object will make invocations.
    type
    Specifies the data type of the objects used by the Dispatch object. See Section 41.1.2, “Data Types”.
    When working with JAXB objects, this parameter specifies the JAXBContext object used to marshal and unmarshal the JAXB objects.
    modeSpecifies the usage mode for the Dispatch object. See Section 41.1.1, “Usage Modes”.
Example 41.2, “Creating a Dispatch Object” shows the code for creating a Dispatch object that works with DOMSource objects in payload mode.

Example 41.2. Creating a Dispatch Object

package com.fusesource.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 = s.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 XML Schema document that defines the messages. While service providers vary greatly there are a few guidelines to be followed:
  • The root element of the request is based in the value of the name attribute of the wsdl:operation element corresponding to the operation being invoked.
    Warning
    If the service being invoked uses doc/literal bare messages, the root element of the request is based on the value of the name attribute of the wsdl:part element referred to by the wsdl:operation element.
  • The root element of the request is namespace qualified.
  • If the service being invoked uses rpc/literal messages, the top-level elements in the request will not be namespace qualified.
    Important
    The children of top-level elements may be namespace qualified. To be certain you must 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, use the Dispatch object's invoke() method shown in Example 41.3, “The Dispatch.invoke() Method”.

Example 41.3. The Dispatch.invoke() Method

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 create a Dispatch object using createDispatch(portName, SOAPMessage.class, Service.Mode.MESSAGE), both the response and the request are SOAPMessage objects.
Note
When using JAXB objects, both the response and the request can be of any type the provided JAXBContext object can marshal and unmarshal. Also, the response and the request can be different JAXB objects.
Example 41.4, “Making a Synchronous Invocation Using a Dispatch Object” shows code for making a synchronous invocation on a remote service using a DOMSource object.

Example 41.4. Making a Synchronous Invocation Using a Dispatch Object

// 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 40, Developing Asynchronous Applications, 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 polled to see if the response has arrived. Example 41.5, “The Dispatch.invokeAsync() Method for Polling” shows the signature of the method used to make an asynchronous invocation using the polling approach.

Example 41.5. The Dispatch.invokeAsync() Method for Polling

Response <T> invokeAsync(T msg)
    throws WebServiceException;
For detailed information on using the polling approach for asynchronous invocations see Section 40.4, “Implementing an Asynchronous Client with the Polling Approach”.
When using the callback approach, the invokeAsync() method takes an AsyncHandler implementation that processes the response when it is returned. Example 41.6, “The Dispatch.invokeAsync() Method Using a Callback” shows the signature of the method used to make an asynchronous invocation using the callback approach.

Example 41.6. The Dispatch.invokeAsync() Method Using a Callback

Future<?> invokeAsync(T msg,
                      AsyncHandler<T> handler)
    throws WebServiceException;
For detailed information on using the callback approach for asynchronous invocations see Section 40.5, “Implementing an Asynchronous Client with the Callback Approach”.
Note
As with the synchronous invoke() method, the type of the response and the type of the request are determined when you create the Dispatch object.

Oneway invocation

When a request does not generate a response, make remote invocations using the Dispatch object's invokeOneWay(). Example 41.7, “The Dispatch.invokeOneWay() Method” shows the signature for this method.

Example 41.7. The Dispatch.invokeOneWay() Method

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), then the request is packaged into a DOMSource object.
Note
When using JAXB objects, the response and the request can be of any type the provided JAXBContext object can marshal and unmarshal.
Example 41.8, “Making a One Way Invocation Using a Dispatch Object” shows code for making a oneway invocation on a remote service using a JAXB object.

Example 41.8. Making a One Way Invocation Using a Dispatch Object

// 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);
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.