Messaging Modes

Overview

Objects that implement the Provider interface have two messaging modes:

• Message mode
• Payload mode

The messaging mode you specify determines the level of messaging detail that is passed to your implementation.

Message mode

When using message mode, a Provider implementation works with complete messages. A complete message includes any binding specific headers and wrappers. For example, a Provider implementation that uses a SOAP binding would receive requests as fully specified SOAP message. Any response returned from the implementation would also need to be a fully specified SOAP message.

You specify that a Provider implementation uses message mode by providing the value java.xml.ws.Service.Mode.MESSAGE as the value to the javax.xml.ws.ServiceMode annotation.

@WebServiceProvider
@ServiceMode(value=Service.Mode.MESSAGE)
public class stockQuoteProvider implements Provider<SOAPMessage>
{
  ...
}

Payload mode

In payload mode a Provider implementation works with only the payload of a message. For example, a Provider implementation working in payload mode works only with the body of a SOAP message. The binding layer processes any binding level wrappers and headers.

You specify that a Provider implementation uses payload mode by providing the value java.xml.ws.Service.Mode.PAYLOAD as the value to the javax.xml.ws.ServiceMode annotation.

@WebServiceProvider
@ServiceMode(value=Service.Mode.PAYLOAD)
public class stockQuoteProvider implements Provider<DOMSource>
{
  ...
}

Data Types

Overview

Provider implementations, because they are low-level objects, cannot use the same JAXB generated types as the higher level consumer APIs. Provider implementations work with the following types of objects:

• javax.xml.transform.Source
• javax.xml.soap.SOAPMessage
• javax.activation.DataSource

Using Source objects

A Provider implementation can accept and return objects that are derived from the javax.xml.transform.Source interface. Source objects are low level objects that hold XML documents. Each Source implementation provides methods that access the stored XML documents and 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 can be accessed using the getNode() method. Nodes can be 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 contains 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 as would any other data stream.

  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

Provider implementations can use javax.xml.soap.SOAPMessage objects when the following conditions are true:

• the Provider implementation is using the SOAP binding.
• the Provider implementation is using message mode.

A SOAPMessage object, as the name implies, 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 was passed as an attachment.

Using DataSource objects

Provider implementations can use objects that implement the javax.activation.DataSource interface when the following conditions are true:

• the implementation is using the HTTP binding.
• the implementation 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.

Implementing a Provider Object

Overview

The Provider interface is relatively easy to implement. It only has one method, invoke(), that needs to be implemented. In addition it has three simple requirements:

• An implementation must have the @WebServiceProvider annotation.
• An implementation must have a default public constructor.
• An implementation must implement a typed version of the Provider interface.
  In other words, you cannot implement a Provider<T> interface. You must implement a version of the interface that uses a concrete data type. For example, you can implement an instance of a Provider<SAXSource>.

The complexity of implementing the Provider interface surrounds handling the request messages and building the proper responses.

Working with messages

Unlike the higher-level SEI based service implementations, Provider implementations receive requests as raw XML data and must send responses as raw XML data. This requires that the developer has intimate knowledge of the messages used by the service being implemented. These details can typically be found in the WSDL document describing the service.

WS-I Basic Profile provides guidelines about the messages used by services including:

• The root element of a request is based in the value of the name attribute of the wsdl:operation element that corresponds to the operation being invoked.

  If the service 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 referred to by the wsdl:operation element.

• The root element of all messages will be namespace qualified.
• If the service uses rpc/literal messages, the top-level elements in the messages will not be namespace qualified.

  The children of top-level elements may be namespace qualified. To be certain you will need to check their schema definitions.

• If the service uses rpc/literal messages, none of the top-level elements can be null.
• If the service uses doc/literal messages, the schema definition of the message determines if any of the elements are namespace qualified.

Implementing the invoke() method

The Provider interface has only one method, invoke(), that needs to be implemented. invoke() receives the incoming request packaged into the type of object declared by the type of Provider interface being implemented and returns the response message packaged into the same type of object. For example, an implementation of a Provider<SOAPMessage> interface would receive the request as a SOAPMessage object and return the response as a SOAPMessage object.

The messaging mode used by the Provider implementation determines the amount of binding specific information the request and response messages contain. Implementation using message mode receive all of the binding specific wrappers and headers along with the request. They must also add all of the binding specific wrappers and headers to the response message. Implementations using payload mode only receive the body of the request. The XML document returned by an implementation using payload mode will be placed into the body of the request message.

Examples

The following shows a Provider implementation that works with SOAPMessage objects in message mode.

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort" 
    serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.MESSAGE")
public class  stockQuoteReporterProvider 
    implements Provider<SOAPMessage> 
{
  public stockQuoteReporterProvider() 
  {
  }

  public SOAPMessage invoke(SOAPMessage request) 
  {
    SOAPBody requestBody = request.getSOAPBody();
    if(requestBody.getElementName.getLocalName.equals("getStockPrice"))
    {
      MessageFactory mf = MessageFactory.newInstance();
      SOAPFactory sf = SOAPFactory.newInstance();

      SOAPMessage response = mf.createMessage();
      SOAPBody respBody = response.getSOAPBody();
      Name bodyName = sf.createName("getStockPriceResponse");
      respBody.addBodyElement(bodyName);
      SOAPElement respContent = respBody.addChildElement("price");
      respContent.setValue("123.00");
      response.saveChanges();
      return response;
    }
    ...
  }
}

The code does the following:

1. Specifies that the following class implements a Provider object that implements the service whose wsdl:service element is named stockQuoteReporter and whose wsdl:port element is named stockQuoteReporterPort.
2. Specifies that this Provider implementation uses message mode.
3. Provides the required default public constructor.
4. Provides an implementation of the invoke() method that takes a SOAPMessage object and returns a SOAPMessage object.
5. Extracts the request message from the body of the incoming SOAP message.
6. Checks the root element of the request message to determine how to process the request.
7. Creates the factories needed for building the response.
8. Builds the SOAP message for the response.
9. Returns the response as a SOAPMessage object.

The following shows an example of a Provider implementation using DOMSource objects in payload mode.

import javax.xml.ws.Provider;
import javax.xml.ws.Service;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;

@WebServiceProvider(portName="stockQuoteReporterPort"
  serviceName="stockQuoteReporter")
@ServiceMode(value="Service.Mode.PAYLOAD")
public class  stockQuoteReporterProvider implements Provider<DOMSource>
{
  public stockQuoteReporterProvider()
  {
  }

  public DOMSource invoke(DOMSource request)
  {
    DOMSource response = new DOMSource();
    ...
    return response;
  }
}

The code does the following:

1. Specifies that the class implements a Provider object that implements the service whose wsdl:service element is named stockQuoteReporter and whose wsdl:port element is named stockQuoteReporterPort.
2. Specifies that this Provider implementation uses payload mode.
3. Provides the required default public constructor.
4. Provides an implementation of the invoke() method that takes a DOMSource object and returns a DOMSource object.