Package com.sun.xml.ws.message.stream

Class StreamMessage

java.lang.Object

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

com.sun.xml.ws.message.AbstractMessageImpl

com.sun.xml.ws.message.stream.StreamMessage

All Implemented Interfaces:

StreamingSOAP

public class StreamMessage
extends AbstractMessageImpl
implements StreamingSOAP

Message implementation backed by XMLStreamReader. TODO: we need another message class that keeps XMLStreamReader that points at the start of the envelope element.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static interface	StreamMessage.StreamHeaderDecoder

Field Summary

Fields inherited from class com.sun.xml.ws.message.AbstractMessageImpl

bodyTag, DEFAULT_TAGS, EMPTY_ATTS, envelopeTag, headerTag, NULL_LOCATOR, soapVersion

Fields inherited from class com.sun.xml.ws.api.message.Message

attachmentSet

Constructor Summary

Constructors

Constructor	Description
StreamMessage(MessageHeaders headers, AttachmentSet attachmentSet, XMLStreamReader reader, SOAPVersion soapVersion)	Creates a StreamMessage from a XMLStreamReader that points at the start element of the payload, and headers.
StreamMessage(SOAPVersion v)
StreamMessage(SOAPVersion v, XMLStreamReader envelope, AttachmentSet attachments)
StreamMessage(TagInfoset envelopeTag, TagInfoset headerTag, AttachmentSet attachmentSet, MessageHeaders headers, TagInfoset bodyTag, XMLStreamReader reader, SOAPVersion soapVersion)	Creates a StreamMessage from a XMLStreamReader and the complete infoset of the SOAP envelope.
StreamMessage(TagInfoset envelopeTag, TagInfoset headerTag, AttachmentSet attachmentSet, MessageHeaders headers, String bodyPrologue, TagInfoset bodyTag, String bodyEpilogue, XMLStreamReader reader, SOAPVersion soapVersion)

Method Summary

Modifier and Type	Method	Description
void	consume()	Marks the message as consumed, without actually reading the contents.
Message	copy()	Creates a copy of a Message.
String	getBodyEpilogue()
String	getBodyPrologue()
MessageHeaders	getHeaders()	Gets all the headers of this message.
String	getPayloadLocalPart()	Gets the local name of the payload element.
String	getPayloadNamespaceURI()	Gets the namespace URI of the payload element.
QName	getPayloadQName()
XMLStreamReader	getReader()
boolean	hasHeaders()	Returns true if headers are present in the message.
boolean	hasPayload()	Returns true if a Message has a payload.
boolean	isPayloadStreamReader()
XMLStreamReader	readEnvelope()
XMLStreamReader	readPayload()	Reads the payload as a XMLStreamReader This consumes the message.
<T> T	readPayloadAsJAXB(Bridge<T> bridge)	Deprecated.
<T> T	readPayloadAsJAXB(XMLBridge<T> bridge)	Reads the payload as a Data-Bond object This consumes the message.
Object	readPayloadAsJAXB(javax.xml.bind.Unmarshaller unmarshaller)	Reads the payload as a JAXB object by using the given unmarshaller.
Source	readPayloadAsSource()	Returns the payload as a Source object.
XMLStreamReader	readToBodyStarTag()
void	writePayloadTo(XMLStreamWriter writer)	Writes the payload to StAX.
void	writePayloadTo(ContentHandler contentHandler, ErrorHandler errorHandler, boolean fragment)	Writes the payload to SAX events.
void	writeTo(XMLStreamWriter sw)	Default implementation that relies on Message.writePayloadTo(XMLStreamWriter)
void	writeTo(ContentHandler contentHandler, ErrorHandler errorHandler)	Writes the whole envelope as SAX events.
void	writeToBodyStart(XMLStreamWriter writer)

Methods inherited from class com.sun.xml.ws.message.AbstractMessageImpl

getSOAPVersion, readAsSOAPMessage, readAsSOAPMessage, readEnvelopeAsSource, toSAAJ

Methods inherited from class com.sun.xml.ws.api.message.Message

addSOAPMimeHeaders, assertOneWay, copyFrom, generateMessageID, getAttachments, getFirstDetailEntryName, getID, getID, getMethod, getOperation, getOperation, getTransportHeaders, getTransportHeaders, hasAttachments, isFault, isOneWay, setMessageMedadata

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

StreamMessage

public StreamMessage(SOAPVersion v)

StreamMessage

public StreamMessage(SOAPVersion v,
 @NotNull
 XMLStreamReader envelope,
 @NotNull
 AttachmentSet attachments)

StreamMessage

public StreamMessage(@Nullable
 MessageHeaders headers,
 @NotNull
 AttachmentSet attachmentSet,
 @NotNull
 XMLStreamReader reader,
 @NotNull
 SOAPVersion soapVersion)

Creates a StreamMessage from a XMLStreamReader that points at the start element of the payload, and headers.

This method creates a Message from a payload.

Parameters:

headers - if null, it means no headers. if non-null, it will be owned by this message.

reader - points at the start element/document of the payload (or the end element of the <s:Body> if there's no payload)

StreamMessage

public StreamMessage(@NotNull
 TagInfoset envelopeTag,
 @Nullable
 TagInfoset headerTag,
 @NotNull
 AttachmentSet attachmentSet,
 @Nullable
 MessageHeaders headers,
 @NotNull
 TagInfoset bodyTag,
 @NotNull
 XMLStreamReader reader,
 @NotNull
 SOAPVersion soapVersion)

Creates a StreamMessage from a XMLStreamReader and the complete infoset of the SOAP envelope.

See StreamMessage(MessageHeaders, AttachmentSet, XMLStreamReader, SOAPVersion) for the description of the basic parameters.

Parameters:

headerTag - Null if the message didn't have a header tag.

StreamMessage

public StreamMessage(@NotNull
 TagInfoset envelopeTag,
 @Nullable
 TagInfoset headerTag,
 @NotNull
 AttachmentSet attachmentSet,
 @Nullable
 MessageHeaders headers,
 @Nullable
 String bodyPrologue,
 @NotNull
 TagInfoset bodyTag,
 @Nullable
 String bodyEpilogue,
 @NotNull
 XMLStreamReader reader,
 @NotNull
 SOAPVersion soapVersion)

Method Details

readEnvelope

public XMLStreamReader readEnvelope()

Specified by:

readEnvelope in interface StreamingSOAP

hasHeaders

public boolean hasHeaders()

Description copied from class: Message

Returns true if headers are present in the message.

Specified by:

hasHeaders in class Message

Returns:

true if headers are present.

getHeaders

public MessageHeaders getHeaders()

Description copied from class: Message

Gets all the headers of this message.

Implementation Note

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

Specified by:

getHeaders in class Message

Returns:

always return the same non-null object.

getPayloadLocalPart

public String getPayloadLocalPart()

Description copied from class: Message

Gets the local name of the payload element.

Specified by:

getPayloadLocalPart in class Message

Returns:

null if a Message doesn't have any payload.

getPayloadNamespaceURI

public String getPayloadNamespaceURI()

Description copied from class: Message

Gets the namespace URI of the payload element.

Specified by:

getPayloadNamespaceURI in class Message

Returns:

null if a Message doesn't have any payload.

hasPayload

public boolean hasPayload()

Description copied from class: Message

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>
 

Specified by:

hasPayload in class Message

readPayloadAsSource

public Source readPayloadAsSource()

Description copied from class: Message

Returns the payload as a Source object. This consumes the message.

Specified by:

readPayloadAsSource in class Message

Returns:

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

readPayloadAsJAXB

public Object readPayloadAsJAXB(javax.xml.bind.Unmarshaller unmarshaller)
                         throws javax.xml.bind.JAXBException

Description copied from class: Message

Reads the payload as a JAXB object by using the given unmarshaller. This consumes the message.

Overrides:

readPayloadAsJAXB in class AbstractMessageImpl

Throws:

javax.xml.bind.JAXBException - If JAXB reports an error during the processing.

readPayloadAsJAXB

public <T> T readPayloadAsJAXB(Bridge<T> bridge)
                        throws javax.xml.bind.JAXBException

Deprecated.

Description copied from class: Message

Reads the payload as a JAXB object according to the given Bridge. This consumes the message.

Overrides:

readPayloadAsJAXB in class AbstractMessageImpl

Returns:

null if there's no payload.

Throws:

javax.xml.bind.JAXBException - If JAXB reports an error during the processing.

readPayloadAsJAXB

public <T> T readPayloadAsJAXB(XMLBridge<T> bridge)
                        throws javax.xml.bind.JAXBException

Description copied from class: Message

Reads the payload as a Data-Bond object This consumes the message.

Overrides:

readPayloadAsJAXB in class AbstractMessageImpl

Returns:

null if there's no payload.

Throws:

javax.xml.bind.JAXBException - If JAXB reports an error during the processing.

consume

public void consume()

Description copied from class: Message

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.

This method may not be called more than once since it may have released the reusable resources.

Overrides:

consume in class Message

readPayload

public XMLStreamReader readPayload()

Description copied from class: Message

Reads the payload as a XMLStreamReader This consumes the message. The caller is encouraged to call XMLStreamReaderFactory.recycle(XMLStreamReader) when finished using the instance.

Specified by:

readPayload in interface StreamingSOAP

Specified by:

readPayload in class Message

Returns:

If there's no payload, this method returns null. Otherwise always non-null valid XMLStreamReader that points to the payload tag name.

writePayloadTo

public void writePayloadTo(XMLStreamWriter writer)
                    throws XMLStreamException

Description copied from class: Message

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.

Specified by:

writePayloadTo in interface StreamingSOAP

Specified by:

writePayloadTo in class Message

Throws:

XMLStreamException - If the XMLStreamWriter reports an error, or some other errors happen during the processing.

writeTo

public void writeTo(XMLStreamWriter sw)
             throws XMLStreamException

Description copied from class: AbstractMessageImpl

Default implementation that relies on Message.writePayloadTo(XMLStreamWriter)

Overrides:

writeTo in class AbstractMessageImpl

Throws:

XMLStreamException - If the XMLStreamWriter reports an error, or some other errors happen during the processing.

writeToBodyStart

public void writeToBodyStart(XMLStreamWriter writer)
                      throws XMLStreamException

Specified by:

writeToBodyStart in interface StreamingSOAP

Overrides:

writeToBodyStart in class AbstractMessageImpl

Throws:

XMLStreamException

writePayloadTo

public void writePayloadTo(ContentHandler contentHandler,
 ErrorHandler errorHandler,
 boolean fragment)
                    throws SAXException

Description copied from class: AbstractMessageImpl

Writes the payload to SAX events.

Specified by:

writePayloadTo in class AbstractMessageImpl

fragment - if true, this method will fire SAX events without start/endDocument events, suitable for embedding this into a bigger SAX event sequence. if false, this method generaets a completely SAX event sequence on its own.

Throws:

SAXException

copy

public Message copy()

Description copied from class: Message

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 identical 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.

IMPORTANT

WHEN YOU IMPLEMENT OR CHANGE A Message.copy() METHOD, YOU MUST USE THE Message.copyFrom(com.sun.xml.ws.api.message.Message) METHOD IN THE IMPLEMENTATION.

Specified by:

copy in class Message

writeTo

public void writeTo(ContentHandler contentHandler,
 ErrorHandler errorHandler)
             throws SAXException

Description copied from class: AbstractMessageImpl

Writes the whole envelope as SAX events.

Overrides:

writeTo in class AbstractMessageImpl

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

getBodyPrologue

public String getBodyPrologue()

getBodyEpilogue

public String getBodyEpilogue()

getReader

public XMLStreamReader getReader()

isPayloadStreamReader

public boolean isPayloadStreamReader()

Specified by:

isPayloadStreamReader in interface StreamingSOAP

getPayloadQName

public QName getPayloadQName()

Specified by:

getPayloadQName in interface StreamingSOAP

readToBodyStarTag

public XMLStreamReader readToBodyStarTag()

Specified by:

readToBodyStarTag in interface StreamingSOAP