com.sun.xml.ws.api.message
Class Message

java.lang.Object
  extended by com.sun.xml.ws.api.message.Message
Direct Known Subclasses:
AbstractMessageImpl, ProtocolSourceMessage, SAAJMessage

public abstract class Message
extends Object

Represents a SOAP message.

What is a message?

A Message consists of the following:

  1. Random-accessible list of headers. a header is a representation of an element inside <soap:Header>. It can be read multiple times, can be added or removed, but it is not modifiable. See HeaderList for more about headers.
  2. The payload of the message, which is a representation of an element inside <soap:Body>. the payload is streamed, and therefore it can be only read once (or can be only written to something once.) once a payload is used, a message is said to be consumed. A message may not have any payload.
  3. Attachments. TODO: can attachments be streamed? I suspect so. does anyone need to read attachment twice?

How does this abstraction work?

The basic idea behind the Message is to hide the actual data representation. For example, a Message might be constructed on top of an InputStream from the accepted HTTP connection, or it might be constructed on top of a JAXB object as a result of the method invocation through Proxy. There will be a Message implementation for each of those cases.

This interface provides a lot of methods that access the payload in many different forms, and implementations can implement those methods in the best possible way.

A particular attention is paid to make sure that a Message object can be constructed on a stream that is not fully read yet. We believe this improves the turn-around time on the server side.

It is often useful to wrap a Message into another Message, for example to encrypt the body, or to verify the signature as the body is read.

This representation is also used for a REST-ful XML message. In such case we'll construct a Message with empty attachments and headers, and when serializing all headers and attachments will be ignored.

Message and XOP

XOP is considered as an Codec, and therefore when you are looking at Message, you'll never see <xop:Include> or any such elements (instead you'll see the base64 data inlined.) If a consumer of infoset isn't interested in handling XOP by himself, this allows him to work with XOP correctly even without noticing it.

For producers and consumers that are interested in accessing the binary data more efficiently, they can use XMLStreamReaderEx and XMLStreamWriterEx.

Message lifespan

Often Packet include information local to a particular invocaion (such as HttpServletRequest, from this angle, it makes sense to tie a lifespan of a message to one pipeline invocation.

On the other hand, if you think about WS-RM, it often needs to hold on to a message longer than a pipeline invocation (you might get an HTTP request, get a message X, get a second HTTP request, get another message Y, and only then you might want to process X.)

TODO: what do we do about this?

 TODO: can body element have foreign attributes? maybe ID for security?
       Yes, when the SOAP body is signed there will be an ID attribute present
       But in this case any security based impl may need access
       to the concrete representation.
 TODO: HTTP headers?
       Yes. Abstracted as transport-based properties.
 TODO: who handles SOAP 1.1 and SOAP 1.2 difference?
       As separate channel implementations responsible for the creation of the
       message?
 TODO: session?
 TODO: Do we need to expose SOAPMessage explicitly?
       SOAPMessage could be the concrete representation but is it necessary to
       transform between different concrete representations?
       Perhaps this comes down to how use channels for creation and processing.
 TODO: Do we need to distinguish better between creation and processing?
       Do we really need the requirement that a created message can be resused
       for processing. Shall we bifurcate?

 TODO: SOAP version issue
       SOAP version is determined by the context, so message itself doesn't carry it around (?)

 TODO: wrapping message needs easier. in particular properties and attachments.
 


Field Summary
protected  AttachmentSet attachmentSet
           
 
Constructor Summary
Message()
           
 
Method Summary
 void assertOneWay(boolean value)
          Makes an assertion that this Message is a request message for an one-way operation according to the context WSDL.
 void consume()
          Marks the message as consumed, without actually reading the contents.
abstract  Message copy()
          Creates a copy of a Message.
 AttachmentSet getAttachments()
          Gets the attachments of this message (attachments live outside a message.)
abstract  HeaderList getHeaders()
          Gets all the headers of this message.
 String getID(AddressingVersion av, SOAPVersion sv)
          Retuns a unique id for the message.
 String getID(WSBinding binding)
          Retuns a unique id for the message.
 JavaMethod getMethod(SEIModel seiModel)
          Returns the java Method of which this message is an instance of.
 WSDLBoundOperation getOperation(WSDLBoundPortType boundPortType)
          Returns the operation of which this message is an instance of.
 WSDLBoundOperation getOperation(WSDLPort port)
          The same as getOperation(WSDLBoundPortType) but takes WSDLPort for convenience.
abstract  String getPayloadLocalPart()
          Gets the local name of the payload element.
abstract  String getPayloadNamespaceURI()
          Gets the namespace URI of the payload element.
protected  boolean hasAttachments()
          Optimization hint for the derived class to check if we may have some attachments.
abstract  boolean hasHeaders()
          Returns true if headers are present in the message.
abstract  boolean hasPayload()
          Returns true if a Message has a payload.
 boolean isFault()
          Returns true if this message is a fault.
 boolean isOneWay(WSDLPort port)
          Returns true if this message is a request message for a one way operation according to the given WSDL.
abstract  javax.xml.soap.SOAPMessage readAsSOAPMessage()
          Creates the equivalent SOAPMessage from this message.
 javax.xml.soap.SOAPMessage readAsSOAPMessage(Packet packet, boolean inbound)
          Creates the equivalent SOAPMessage from this message.
abstract  Source readEnvelopeAsSource()
          Consumes this message including the envelope.
abstract  javax.xml.stream.XMLStreamReader readPayload()
          Reads the payload as a XMLStreamReader This consumes the message.
abstract
<T> T
readPayloadAsJAXB(Bridge<T> bridge)
          Reads the payload as a JAXB object according to the given Bridge.
abstract
<T> T
readPayloadAsJAXB(Unmarshaller unmarshaller)
          Reads the payload as a JAXB object by using the given unmarshaller.
abstract  Source readPayloadAsSource()
          Returns the payload as a Source object.
abstract  void writePayloadTo(javax.xml.stream.XMLStreamWriter sw)
          Writes the payload to StAX.
abstract  void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler)
          Writes the whole SOAP envelope as SAX events.
abstract  void writeTo(javax.xml.stream.XMLStreamWriter sw)
          Writes the whole SOAP message (but not attachments) to the given writer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

attachmentSet

protected AttachmentSet attachmentSet
Constructor Detail

Message

public Message()
Method Detail

hasHeaders

public abstract boolean hasHeaders()
Returns true if headers are present in the message.

Returns:
true if headers are present.

getHeaders

@NotNull
public abstract HeaderList getHeaders()
Gets all the headers of this message.

Implementation Note

Message implementation is allowed to defer the construction of HeaderList object. So if you only want to check for the existence of any header element, use hasHeaders().

Returns:
always return the same non-null object.

getAttachments

@NotNull
public AttachmentSet getAttachments()
Gets the attachments of this message (attachments live outside a message.)


hasAttachments

protected boolean hasAttachments()
Optimization hint for the derived class to check if we may have some attachments.


getOperation

@Nullable
public final WSDLBoundOperation getOperation(@NotNull
                                                      WSDLBoundPortType boundPortType)
Returns the operation of which this message is an instance of.

This method relies on WSDLBoundPortType.getOperation(String, String) but it does so in an efficient way.

This method works only for a request. A pipe can determine an operation for a request, and then keep it in a local variable to use it with a response, so there should be no need to find out operation from a response (besides, there might not be any response!).

Parameters:
boundPortType - This represents the port for which this message is used. Most Pipes should get this information when they are created, since a pippeline always work against a particular type of WSDLPort.
Returns:
Null if the operation was not found. This is possible, for example when a protocol message is sent through a pipeline, or when we receive an invalid request on the server, or when we are on the client and the user appliation sends a random DOM through Dispatch, so this error needs to be handled gracefully.

getOperation

@Nullable
public final WSDLBoundOperation getOperation(@NotNull
                                                      WSDLPort port)
The same as getOperation(WSDLBoundPortType) but takes WSDLPort for convenience.


getMethod

@Nullable
public final JavaMethod getMethod(@NotNull
                                           SEIModel seiModel)
Returns the java Method of which this message is an instance of.

This method works only for a request. A pipe can determine a Method for a request, and then keep it in a local variable to use it with a response, so there should be no need to find out operation from a response (besides, there might not be any response!).

Parameters:
seiModel - This represents the java model for the endpoint Some server Pipes would get this information when they are created.
Returns:
Null if there is no corresponding Method for this message. This is possible, for example when a protocol message is sent through a pipeline, or when we receive an invalid request on the server, or when we are on the client and the user appliation sends a random DOM through Dispatch, so this error needs to be handled gracefully.

isOneWay

public boolean isOneWay(@NotNull
                        WSDLPort port)
Returns true if this message is a request message for a one way operation according to the given WSDL. False otherwise.

This method is functionally equivalent as doing getOperation(port).getOperation().isOneWay() (with proper null check and all.) But this method can sometimes work faster than that (for example, on the client side when used with SEI.)

Parameters:
port - Messages are always created under the context of one WSDLPort and they never go outside that context. Pass in that "governing" WSDLPort object here. We chose to receive this as a parameter instead of keeping WSDLPort in a message, just to save the storage.

The implementation of this method involves caching the return value, so the behavior is undefined if multiple callers provide different WSDLPort objects, which is a bug of the caller.


assertOneWay

public final void assertOneWay(boolean value)
Makes an assertion that this Message is a request message for an one-way operation according to the context WSDL.

This method is really only intended to be invoked from within the JAX-WS runtime, and not by any code building on top of it.

This method can be invoked only when the caller "knows" what WSDL says. Also, there's no point in invoking this method if the caller is doing getOperation(port).getOperation().isOneWay(), or sniffing the payload tag name. In particular, this includes DispatchImpl.

Once called, this allows isOneWay(WSDLPort) method to return a value quickly.

See Also:
isOneWay(WSDLPort)

getPayloadLocalPart

@Nullable
public abstract String getPayloadLocalPart()
Gets the local name of the payload element.

Returns:
null if a Message doesn't have any payload.

getPayloadNamespaceURI

public abstract String getPayloadNamespaceURI()
Gets the namespace URI of the payload element.

Returns:
null if a Message doesn't have any payload.

hasPayload

public abstract boolean hasPayload()
Returns true if a Message has a payload.

A message without a payload is a SOAP message that looks like:


 <S:Envelope>
   <S:Header>
     ...
   </S:Header>
   <S:Body />
 </S:Envelope>
 


isFault

public boolean isFault()
Returns true if this message is a fault.

Just a convenience method built on getPayloadNamespaceURI() and getPayloadLocalPart().


readEnvelopeAsSource

public abstract Source readEnvelopeAsSource()
Consumes this message including the envelope. returns it as a Source object.


readPayloadAsSource

public abstract Source readPayloadAsSource()
Returns the payload as a Source object. This consumes the message.

Returns:
if there's no payload, this method returns null.

readAsSOAPMessage

public abstract javax.xml.soap.SOAPMessage readAsSOAPMessage()
                                                      throws javax.xml.soap.SOAPException
Creates the equivalent SOAPMessage from this message. This consumes the message.

Throws:
javax.xml.soap.SOAPException - if there's any error while creating a SOAPMessage.

readAsSOAPMessage

public javax.xml.soap.SOAPMessage readAsSOAPMessage(Packet packet,
                                                    boolean inbound)
                                             throws javax.xml.soap.SOAPException
Creates the equivalent SOAPMessage from this message. It also uses transport specific headers from Packet during the SOAPMessage construction so that SOAPMessage.getMimeHeaders() gives meaningful transport headers. This consumes the message.

Throws:
javax.xml.soap.SOAPException - if there's any error while creating a SOAPMessage.

readPayloadAsJAXB

public abstract <T> T readPayloadAsJAXB(Unmarshaller unmarshaller)
                             throws JAXBException
Reads the payload as a JAXB object by using the given unmarshaller. This consumes the message.

Throws:
JAXBException - If JAXB reports an error during the processing.

readPayloadAsJAXB

public abstract <T> T readPayloadAsJAXB(Bridge<T> bridge)
                             throws JAXBException
Reads the payload as a JAXB object according to the given Bridge. This consumes the message.

Returns:
null if there's no payload.
Throws:
JAXBException - If JAXB reports an error during the processing.

readPayload

public abstract javax.xml.stream.XMLStreamReader readPayload()
                                                      throws javax.xml.stream.XMLStreamException
Reads the payload as a XMLStreamReader This consumes the message. The caller is encouraged to call XMLStreamReaderFactory.recycle(XMLStreamReader) when finished using the instance.

Returns:
If there's no payload, this method returns null. Otherwise always non-null valid XMLStreamReader that points to the payload tag name.
Throws:
javax.xml.stream.XMLStreamException

consume

public void consume()
Marks the message as consumed, without actually reading the contents.

This method provides an opportunity for implementations to reuse any reusable resources needed for representing the payload.


writePayloadTo

public abstract void writePayloadTo(javax.xml.stream.XMLStreamWriter sw)
                             throws javax.xml.stream.XMLStreamException
Writes the payload to StAX. This method writes just the payload of the message to the writer. This consumes the message. The implementation will not write XMLStreamWriter.writeStartDocument() nor XMLStreamWriter.writeEndDocument()

If there's no payload, this method is no-op.

Throws:
javax.xml.stream.XMLStreamException - If the XMLStreamWriter reports an error, or some other errors happen during the processing.

writeTo

public abstract void writeTo(javax.xml.stream.XMLStreamWriter sw)
                      throws javax.xml.stream.XMLStreamException
Writes the whole SOAP message (but not attachments) to the given writer. This consumes the message.

Throws:
javax.xml.stream.XMLStreamException - If the XMLStreamWriter reports an error, or some other errors happen during the processing.

writeTo

public abstract void writeTo(ContentHandler contentHandler,
                             ErrorHandler errorHandler)
                      throws SAXException
Writes the whole SOAP envelope as SAX events.

This consumes the message.

Parameters:
contentHandler - must not be nulll.
errorHandler - must not be null. any error encountered during the SAX event production must be first reported to this error handler. Fatal errors can be then thrown as SAXParseException. SAXExceptions thrown from ErrorHandler should propagate directly through this method.
Throws:
SAXException

copy

public abstract Message copy()
Creates a copy of a Message.

This method creates a new Message whose header/payload/attachments/properties are identical to this Message. Once created, the created Message and the original Message behaves independently --- adding header/ attachment to one Message doesn't affect another Message at all.

This method does NOT consume a message.

To enable efficient copy operations, there's a few restrictions on how copied message can be used.

  1. The original and the copy may not be used concurrently by two threads (this allows two Messages to share some internal resources, such as JAXB marshallers.) Note that it's OK for the original and the copy to be processed by two threads, as long as they are not concurrent.
  2. The copy has the same 'life scope' as the original (this allows shallower copy, such as JAXB beans wrapped in JAXBMessage.)

A 'life scope' of a message created during a message processing in a pipeline is until a pipeline processes the next message. A message cannot be kept beyond its life scope. (This experimental design is to allow message objects to be reused --- feedback appreciated.)

Design Rationale

Since a Message body is read-once, sometimes (such as when you do fail-over, or WS-RM) you need to create an idential copy of a Message.

The actual copy operation depends on the layout of the data in memory, hence it's best to be done by the Message implementation itself.

The restrictions placed on the use of copied Message can be relaxed if necessary, but it will make the copy method more expensive.


getID

@NotNull
public String getID(@NotNull
                            WSBinding binding)
Retuns a unique id for the message. The id can be used for various things, like debug assistance, logging, and MIME encoding(say for boundary).

This method will check the existence of the addressing header, and if present uses that value. Otherwise it generates one from UUID.random(), and return it without adding a new header. But it doesn't add a to the header list since we expect them to be added before calling this method.

Addressing tube will go do a separate verification on inbound headers to make sure that header is present when it's supposed to be.

Parameters:
binding - object created by BindingID.createBinding()
Returns:
unique id for the message

getID

@NotNull
public String getID(AddressingVersion av,
                            SOAPVersion sv)
Retuns a unique id for the message.

Parameters:
av - WS-Addressing version
sv - SOAP version
Returns:
unique id for the message
See Also:
#getID(com.sun.xml.ws.api.WSBinding)} for detailed description.