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 Artix ESB 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.