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.
When working with a binding that does not use special wrappers, such as the XML binding, payload mode and message mode provide the same results.
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> { ... }
If you do not provide the @ServiceMode
annotation, the Provider
implementation will default to using payload mode.
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 ofNode
objects that can be accessed using thegetNode()
method. Nodes can be updated or added to the DOM tree using thesetNode()
method.SAXSource
holds XML messages as a Simple API for XML (SAX) object. SAX objects contain anInputSource
object that contains the raw data and anXMLReader
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 aProvider<T>
interface. You must implement a version of the interface that uses a concrete data type. For example, you can implement an instance of aProvider<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 thewsdl: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:
- Specifies that the following class implements a
Provider
object that implements the service whosewsdl:service
element is namedstockQuoteReporter
and whosewsdl:port
element is namedstockQuoteReporterPort
. - Specifies that this
Provider
implementation uses message mode. - Provides the required default public constructor.
- Provides an implementation of the
invoke()
method that takesa SOAPMessage
object and returns aSOAPMessage
object. - Extracts the request message from the body of the incoming SOAP message.
- Checks the root element of the request message to determine how to process the request.
- Creates the factories needed for building the response.
- Builds the SOAP message for the response.
- 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:
- Specifies that the class implements a
Provider
object that implements the service whosewsdl:service
element is namedstockQuoteReporter
and whosewsdl:port
element is namedstockQuoteReporterPort
. - Specifies that this Provider implementation uses payload mode.
- Provides the required default public constructor.
- Provides an implementation of the
invoke()
method that takes aDOMSource
object and returns aDOMSource
object.