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

java.lang.Object
  extended by com.sun.xml.ws.api.message.Message
      extended by com.sun.xml.ws.message.AbstractMessageImpl
          extended by com.sun.xml.ws.message.stream.StreamMessage
              extended by com.sun.xml.ws.api.message.MessageWrapper

 class MessageWrapper
extends StreamMessage

A MessageWrapper wraps the Message for the access through Packet.


Field Summary
(package private)  Message delegate
           
(package private)  Packet packet
           
(package private)  StreamMessage streamDelegate
           
 
Fields inherited from class com.sun.xml.ws.message.AbstractMessageImpl
EMPTY_ATTS, NULL_LOCATOR, soapVersion
 
Fields inherited from class com.sun.xml.ws.api.message.Message
attachmentSet
 
Constructor Summary
MessageWrapper(Packet p, Message m)
           
 
Method Summary
 void consume()
          Marks the message as consumed, without actually reading the contents.
 Message copy()
          Creates a copy of a Message.
 boolean equals(Object obj)
           
 AttachmentSet getAttachments()
          Gets the attachments of this message (attachments live outside a message.)
 String getBodyEpilogue()
           
 String getBodyPrologue()
           
 QName getFirstDetailEntryName()
          It gives S:Envelope/S:Body/S:Fault/detail 's first child's name.
 HeaderList getHeaders()
          Deprecated. 
 String getID(AddressingVersion av, SOAPVersion sv)
          Retuns a unique id for the message.
 String getID(WSBinding binding)
          Retuns a unique id for the message.
 MessageHeaders getMessageHeaders()
          Default implementation of getMessageHeaders just calls getHeaders() for now.
 String getPayloadLocalPart()
          Gets the local name of the payload element.
 String getPayloadNamespaceURI()
          Gets the namespace URI of the payload element.
 SOAPVersion getSOAPVersion()
           
 int hashCode()
           
 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(WSDLPort port)
          Returns true if this message is a request message for a one way operation according to the given WSDL.
 javax.xml.soap.SOAPMessage readAsSOAPMessage()
          Default implementation that uses AbstractMessageImpl.writeTo(ContentHandler, ErrorHandler)
 javax.xml.soap.SOAPMessage readAsSOAPMessage(Packet p, boolean inbound)
          Creates the equivalent SOAPMessage from this message.
 Source readEnvelopeAsSource()
          Consumes this message including the envelope.
 javax.xml.stream.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.
 Object readPayloadAsJAXB(Unmarshaller unmarshaller)
          Reads the payload as a JAXB object by using the given unmarshaller.
<T> T
readPayloadAsJAXB(XMLBridge<T> bridge)
          Reads the payload as a Data-Bond object This consumes the message.
 Source readPayloadAsSource()
          Returns the payload as a Source object.
 String toString()
           
 void writePayloadTo(ContentHandler contentHandler, ErrorHandler errorHandler, boolean fragment)
          Writes the payload to SAX events.
 void writePayloadTo(javax.xml.stream.XMLStreamWriter sw)
          Writes the payload to StAX.
 void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler)
          Writes the whole envelope as SAX events.
 void writeTo(javax.xml.stream.XMLStreamWriter sw)
          Default implementation that relies on Message.writePayloadTo(XMLStreamWriter)
 
Methods inherited from class com.sun.xml.ws.message.stream.StreamMessage
getReader
 
Methods inherited from class com.sun.xml.ws.message.AbstractMessageImpl
toSAAJ
 
Methods inherited from class com.sun.xml.ws.api.message.Message
addSOAPMimeHeaders, assertOneWay, generateMessageID, getMethod, getOperation, getOperation, getTransportHeaders, getTransportHeaders, hasAttachments
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

packet

Packet packet

delegate

Message delegate

streamDelegate

StreamMessage streamDelegate
Constructor Detail

MessageWrapper

MessageWrapper(Packet p,
               Message m)
Method Detail

writePayloadTo

public void writePayloadTo(ContentHandler contentHandler,
                           ErrorHandler errorHandler,
                           boolean fragment)
                    throws SAXException
Description copied from class: AbstractMessageImpl
Writes the payload to SAX events.

Overrides:
writePayloadTo in class StreamMessage
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

getBodyPrologue

public String getBodyPrologue()
Overrides:
getBodyPrologue in class StreamMessage

getBodyEpilogue

public String getBodyEpilogue()
Overrides:
getBodyEpilogue in class StreamMessage

hashCode

public int hashCode()
Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)
Overrides:
equals in class Object

hasHeaders

public boolean hasHeaders()
Description copied from class: Message
Returns true if headers are present in the message.

Overrides:
hasHeaders in class StreamMessage
Returns:
true if headers are present.

getHeaders

@Deprecated
public HeaderList getHeaders()
Deprecated. 

Deprecated - use getMessageHeaders() instead

Overrides:
getHeaders in class StreamMessage
Returns:
always return the same non-null object.

getAttachments

public AttachmentSet getAttachments()
Description copied from class: Message
Gets the attachments of this message (attachments live outside a message.)

Overrides:
getAttachments in class Message

toString

public String toString()
Overrides:
toString in class Object

isOneWay

public boolean isOneWay(WSDLPort port)
Description copied from class: Message
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 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()
Description copied from class: Message
Gets the local name of the payload element.

Overrides:
getPayloadLocalPart in class StreamMessage
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.

Overrides:
getPayloadNamespaceURI in class StreamMessage
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>
 

Overrides:
hasPayload in class StreamMessage

isFault

public boolean isFault()
Description copied from class: Message
Returns true if this message is a fault.

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

Overrides:
isFault in class Message

getFirstDetailEntryName

public QName getFirstDetailEntryName()
Description copied from class: Message
It gives S:Envelope/S:Body/S:Fault/detail 's first child's name. Should be called for messages that have SOAP Fault.

This implementation is expensive so concrete implementations are expected to override this one.

Overrides:
getFirstDetailEntryName in class Message
Returns:
first detail entry's name, if there is one else null

readEnvelopeAsSource

public Source readEnvelopeAsSource()
Description copied from class: Message
Consumes this message including the envelope. returns it as a Source object.

Overrides:
readEnvelopeAsSource in class AbstractMessageImpl

readPayloadAsSource

public Source readPayloadAsSource()
Description copied from class: Message
Returns the payload as a Source object. This consumes the message.

Overrides:
readPayloadAsSource in class StreamMessage
Returns:
if there's no payload, this method returns null.

readAsSOAPMessage

public javax.xml.soap.SOAPMessage readAsSOAPMessage()
                                             throws javax.xml.soap.SOAPException
Description copied from class: AbstractMessageImpl
Default implementation that uses AbstractMessageImpl.writeTo(ContentHandler, ErrorHandler)

Overrides:
readAsSOAPMessage in class AbstractMessageImpl
Throws:
javax.xml.soap.SOAPException - if there's any error while creating a SOAPMessage.

readAsSOAPMessage

public javax.xml.soap.SOAPMessage readAsSOAPMessage(Packet p,
                                                    boolean inbound)
                                             throws javax.xml.soap.SOAPException
Description copied from class: Message
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.

Overrides:
readAsSOAPMessage in class AbstractMessageImpl
Throws:
javax.xml.soap.SOAPException - if there's any error while creating a SOAPMessage.

readPayloadAsJAXB

public Object readPayloadAsJAXB(Unmarshaller unmarshaller)
                         throws 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 StreamMessage
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
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 StreamMessage
Returns:
null if there's no payload.
Throws:
JAXBException - If JAXB reports an error during the processing.

readPayloadAsJAXB

public <T> T readPayloadAsJAXB(XMLBridge<T> bridge)
                    throws JAXBException
Description copied from class: Message
Reads the payload as a Data-Bond object This consumes the message.

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

readPayload

public javax.xml.stream.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.

Overrides:
readPayload in class StreamMessage
Returns:
If there's no payload, this method returns null. Otherwise always non-null valid XMLStreamReader that points to the payload tag name.

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 StreamMessage

writePayloadTo

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

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

writeTo

public void writeTo(javax.xml.stream.XMLStreamWriter sw)
             throws javax.xml.stream.XMLStreamException
Description copied from class: AbstractMessageImpl
Default implementation that relies on Message.writePayloadTo(XMLStreamWriter)

Overrides:
writeTo in class StreamMessage
Throws:
javax.xml.stream.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
Description copied from class: AbstractMessageImpl
Writes the whole envelope as SAX events.

Overrides:
writeTo in class StreamMessage
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 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 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.

Overrides:
copy in class StreamMessage

getID

public String getID(WSBinding binding)
Description copied from class: Message
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.

Overrides:
getID in class Message
Parameters:
binding - object created by BindingID.createBinding()
Returns:
unique id for the message

getID

public String getID(AddressingVersion av,
                    SOAPVersion sv)
Description copied from class: Message
Retuns a unique id for the message.

Overrides:
getID in class 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.

getSOAPVersion

public SOAPVersion getSOAPVersion()
Overrides:
getSOAPVersion in class AbstractMessageImpl

getMessageHeaders

@NotNull
public MessageHeaders getMessageHeaders()
Description copied from class: AbstractMessageImpl
Default implementation of getMessageHeaders just calls getHeaders() for now. Subclasses may override if they choose

Overrides:
getMessageHeaders in class AbstractMessageImpl


Copyright (c) 1997-2012 Oracle and/or its affiliates. All rights reserved.