com.sun.xml.ws.security.opt.impl.message

Class MessageWrapper

java.lang.Object

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

com.sun.xml.ws.security.opt.impl.message.MessageWrapper

public class MessageWrapper
extends com.sun.xml.ws.api.message.Message

Author:

K.Venugopal@sun.com

Field Summary

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

attachmentSet

Constructor Summary

Constructors

Constructor and Description
MessageWrapper(com.sun.xml.stream.buffer.MutableXMLStreamBuffer msg, boolean oneWay, com.sun.xml.ws.api.message.MessageHeaders hdrs, SecuredMessage sm)
MessageWrapper(SecuredMessage sm, boolean oneWay)

Method Summary

Modifier and Type	Method and Description
MessageWrapper	copy() Creates a copy of a Message.
com.sun.xml.ws.api.message.AttachmentSet	getAttachments() Gets the attachments of this message (attachments live outside a message.)
com.sun.xml.ws.api.message.HeaderList	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.
protected boolean	hasAttachments() Optimization hint for the derived class to check if we may have some attachments.
boolean	hasHeaders() Returns true if headers are present in the message.
boolean	hasPayload() Returns true if a Message has a payload.
boolean	isFault() Returns true if this message is a fault.
boolean	isOneWay(com.sun.xml.ws.api.model.wsdl.WSDLPort port) Returns true if this message is a request message for a one way operation according to the given WSDL.
SOAPMessage	readAsSOAPMessage() Creates the equivalent SOAPMessage from this message.
Source	readEnvelopeAsSource() Consumes this message including the envelope.
XMLStreamReader	readPayload() Reads the payload as a XMLStreamReader This consumes the message.
<T> T	readPayloadAsJAXB(com.sun.xml.bind.api.Bridge<T> bridge) Reads the payload as a JAXB object according to the given Bridge.
<T> T	readPayloadAsJAXB(Unmarshaller unmarshaller) Reads the payload as a JAXB object by using the given unmarshaller.
<T> T	readPayloadAsJAXB(com.sun.xml.ws.spi.db.XMLBridge<T> arg0)
Source	readPayloadAsSource() Returns the payload as a Source object.
void	writePayloadTo(XMLStreamWriter sw) Writes the payload to StAX.
void	writeTo(ContentHandler contentHandler, ErrorHandler errorHandler) Writes the whole SOAP envelope as SAX events.
void	writeTo(XMLStreamWriter sw) Writes the whole SOAP message (but not attachments) to the given writer.

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

addSOAPMimeHeaders, assertOneWay, consume, copyFrom, generateMessageID, getFirstDetailEntryName, getID, getID, getMethod, getOperation, getOperation, getSOAPVersion, getTransportHeaders, getTransportHeaders, readAsSOAPMessage, setMessageMedadata

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageWrapper

public MessageWrapper(SecuredMessage sm,
                      boolean oneWay)

MessageWrapper

public MessageWrapper(com.sun.xml.stream.buffer.MutableXMLStreamBuffer msg,
                      boolean oneWay,
                      com.sun.xml.ws.api.message.MessageHeaders hdrs,
                      SecuredMessage sm)

Method Detail

hasHeaders

public boolean hasHeaders()

Returns true if headers are present in the message.

Specified by:

hasHeaders in class com.sun.xml.ws.api.message.Message

Returns:

true if headers are present.

getHeaders

public com.sun.xml.ws.api.message.HeaderList getHeaders()

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 hasHeaders().

Specified by:

getHeaders in class com.sun.xml.ws.api.message.Message

Returns:

always return the same non-null object.

getAttachments

public com.sun.xml.ws.api.message.AttachmentSet getAttachments()

Gets the attachments of this message (attachments live outside a message.)

Overrides:

getAttachments in class com.sun.xml.ws.api.message.Message

hasAttachments

protected boolean hasAttachments()

Optimization hint for the derived class to check if we may have some attachments.

Overrides:

hasAttachments in class com.sun.xml.ws.api.message.Message

isOneWay

public boolean isOneWay(@NotNull
                        com.sun.xml.ws.api.model.wsdl.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.)

Overrides:

isOneWay in class com.sun.xml.ws.api.message.Message

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.

getPayloadLocalPart

public String getPayloadLocalPart()

Gets the local name of the payload element.

Specified by:

getPayloadLocalPart in class com.sun.xml.ws.api.message.Message

Returns:

null if a Message doesn't have any payload.

isFault

public boolean isFault()

Returns true if this message is a fault.

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

Overrides:

isFault in class com.sun.xml.ws.api.message.Message

getPayloadNamespaceURI

public String getPayloadNamespaceURI()

Gets the namespace URI of the payload element.

Specified by:

getPayloadNamespaceURI in class com.sun.xml.ws.api.message.Message

Returns:

null if a Message doesn't have any payload.

hasPayload

public boolean hasPayload()

Returns true if a Message has a payload.

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

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

Specified by:

hasPayload in class com.sun.xml.ws.api.message.Message

readEnvelopeAsSource

public Source readEnvelopeAsSource()

Consumes this message including the envelope. returns it as a Source object.

Specified by:

readEnvelopeAsSource in class com.sun.xml.ws.api.message.Message

readPayloadAsSource

public Source readPayloadAsSource()

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

Specified by:

readPayloadAsSource in class com.sun.xml.ws.api.message.Message

Returns:

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

readAsSOAPMessage

public SOAPMessage readAsSOAPMessage()
                              throws SOAPException

Creates the equivalent SOAPMessage from this message. This consumes the message.

Specified by:

readAsSOAPMessage in class com.sun.xml.ws.api.message.Message

Throws:

SOAPException - if there's any error while creating a SOAPMessage.

readPayloadAsJAXB

public <T> T readPayloadAsJAXB(Unmarshaller unmarshaller)
                        throws JAXBException

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

Specified by:

readPayloadAsJAXB in class com.sun.xml.ws.api.message.Message

Throws:

JAXBException - If JAXB reports an error during the processing.

readPayloadAsJAXB

public <T> T readPayloadAsJAXB(com.sun.xml.bind.api.Bridge<T> bridge)
                        throws JAXBException

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

Specified by:

readPayloadAsJAXB in class com.sun.xml.ws.api.message.Message

Throws:

JAXBException - If JAXB reports an error during the processing.

readPayload

public XMLStreamReader readPayload()
                            throws XMLStreamException

Reads the payload as a XMLStreamReader This consumes the message.

Specified by:

readPayload in class com.sun.xml.ws.api.message.Message

Returns:

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

Throws:

XMLStreamException

writePayloadTo

public void writePayloadTo(XMLStreamWriter sw)
                    throws 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.

Specified by:

writePayloadTo in class com.sun.xml.ws.api.message.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

Writes the whole SOAP message (but not attachments) to the given writer. This consumes the message.

Specified by:

writeTo in class com.sun.xml.ws.api.message.Message

Throws:

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

writeTo

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

Writes the whole SOAP envelope as SAX events.

This consumes the message.

Specified by:

writeTo in class com.sun.xml.ws.api.message.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 MessageWrapper 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.

Specified by:

copy in class com.sun.xml.ws.api.message.Message

readPayloadAsJAXB

public <T> T readPayloadAsJAXB(com.sun.xml.ws.spi.db.XMLBridge<T> arg0)
                        throws JAXBException

Specified by:

readPayloadAsJAXB in class com.sun.xml.ws.api.message.Message

Throws:

JAXBException