Class Message
- Direct Known Subclasses:
AbstractMessageImpl
,FilterMessageImpl
,LazyStreamBasedMessage
,MessageWrapper
,ProtocolSourceMessage
,SAAJMessage
What is a message?
A Message
consists of the following:
-
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. -
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.
- 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.
- Author:
- Kohsuke Kawaguchi
-
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
addSOAPMimeHeaders
(javax.xml.soap.MimeHeaders mh, Map<String, List<String>> headers) final void
assertOneWay
(boolean value) Makes an assertion that thisMessage
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 aMessage
.final Message
Thecopy()
method is used as a shorthand throughout the codecase in place of calling a copy constructor.static String
Generates a UUID suitable for use as a MessageID valueGets the attachments of this message (attachments live outside a message.)It gives S:Envelope/S:Body/S:Fault/detail 's first child's name.abstract MessageHeaders
Gets all the headers of this message.getID
(AddressingVersion av, SOAPVersion sv) Deprecated.Deprecated.final JavaMethod
Deprecated.final WSDLBoundOperation
getOperation
(WSDLBoundPortType boundPortType) Deprecated.It is not always possible to uniquely identify the WSDL Operation from just the information in the Message.final WSDLBoundOperation
getOperation
(WSDLPort port) Deprecated.It is not always possible to uniquely identify the WSDL Operation from just the information in the Message.abstract String
Gets the local name of the payload element.abstract String
Gets the namespace URI of the payload element.getTransportHeaders
(Packet packet) getTransportHeaders
(Packet packet, boolean inbound) protected boolean
Optimization hint for the derived class to check if we may have some attachments.abstract boolean
Returns true if headers are present in the message.abstract boolean
Returns true if aMessage
has a payload.boolean
isFault()
Returns true if this message is a fault.boolean
Returns true if this message is a request message for a one way operation according to the given WSDL.abstract javax.xml.soap.SOAPMessage
Creates the equivalentSOAPMessage
from this message.javax.xml.soap.SOAPMessage
readAsSOAPMessage
(Packet packet, boolean inbound) Creates the equivalentSOAPMessage
from this message.abstract Source
Consumes this message including the envelope.abstract XMLStreamReader
Reads the payload as aXMLStreamReader
This consumes the message.abstract <T> T
readPayloadAsJAXB
(Bridge<T> bridge) Deprecated.abstract <T> T
readPayloadAsJAXB
(XMLBridge<T> bridge) Reads the payload as a Data-Bond object This consumes the message.abstract <T> T
readPayloadAsJAXB
(javax.xml.bind.Unmarshaller unmarshaller) Reads the payload as a JAXB object by using the given unmarshaller.abstract Source
Returns the payload as aSource
object.void
setMessageMedadata
(MessageMetadata metadata) abstract void
Writes the payload to StAX.abstract void
Writes the whole SOAP message (but not attachments) to the given writer.abstract void
writeTo
(ContentHandler contentHandler, ErrorHandler errorHandler) Writes the whole SOAP envelope as SAX events.
-
Field Details
-
attachmentSet
-
-
Constructor Details
-
Message
public Message()
-
-
Method Details
-
hasHeaders
public abstract boolean hasHeaders()Returns true if headers are present in the message.- Returns:
- true if headers are present.
-
getHeaders
Gets all the headers of this message.Implementation Note
Message
implementation is allowed to defer the construction ofMessageHeaders
object. So if you only want to check for the existence of any header element, usehasHeaders()
.- Returns:
- always return the same non-null object.
-
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. -
setMessageMedadata
-
getOperation
@Deprecated @Nullable public final WSDLBoundOperation getOperation(@NotNull WSDLBoundPortType boundPortType) Deprecated.It is not always possible to uniquely identify the WSDL Operation from just the information in the Message. Instead, UsePacket.getWSDLOperation()
to get it correctly.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!).
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.- Parameters:
boundPortType
- This represents the port for which this message is used. MostPipe
s should get this information when they are created, since a pippeline always work against a particular type ofWSDLPort
.- 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
Deprecated.It is not always possible to uniquely identify the WSDL Operation from just the information in the Message. Instead, UsePacket.getWSDLOperation()
to get it correctly.The same asgetOperation(WSDLBoundPortType)
but takesWSDLPort
for convenience. -
getMethod
Deprecated.Returns the java Method of which this message is an instance of. It is not always possible to uniquely identify the WSDL Operation from just the information in the Message. Instead, UsePacket.getWSDLOperation()
to get the QName of the associated wsdl operation correctly.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 serverPipe
s 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
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
-Message
s are always created under the context of oneWSDLPort
and they never go outside that context. Pass in that "governing"WSDLPort
object here. We chose to receive this as a parameter instead of keepingWSDLPort
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 thisMessage
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 includesDispatchImpl
.Once called, this allows
isOneWay(WSDLPort)
method to return a value quickly.- See Also:
-
getPayloadLocalPart
Gets the local name of the payload element.- Returns:
- null if a
Message
doesn't have any payload.
-
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 aMessage
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()
andgetPayloadLocalPart()
. -
getFirstDetailEntryName
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.
- Returns:
- first detail entry's name, if there is one else null
-
readEnvelopeAsSource
Consumes this message including the envelope. returns it as aSource
object. -
readPayloadAsSource
Returns the payload as aSource
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.SOAPExceptionCreates the equivalentSOAPMessage
from this message. This consumes the message.- Throws:
javax.xml.soap.SOAPException
- if there's any error while creating aSOAPMessage
.
-
readAsSOAPMessage
public javax.xml.soap.SOAPMessage readAsSOAPMessage(Packet packet, boolean inbound) throws javax.xml.soap.SOAPException Creates the equivalentSOAPMessage
from this message. It also uses transport specific headers from Packet during the SOAPMessage construction so thatSOAPMessage.getMimeHeaders()
gives meaningful transport headers. This consumes the message.- Throws:
javax.xml.soap.SOAPException
- if there's any error while creating aSOAPMessage
.
-
getTransportHeaders
-
getTransportHeaders
-
addSOAPMimeHeaders
-
readPayloadAsJAXB
public abstract <T> T readPayloadAsJAXB(javax.xml.bind.Unmarshaller unmarshaller) throws javax.xml.bind.JAXBException Reads the payload as a JAXB object by using the given unmarshaller. This consumes the message.- Throws:
javax.xml.bind.JAXBException
- If JAXB reports an error during the processing.
-
readPayloadAsJAXB
Deprecated.Reads the payload as a JAXB object according to the givenBridge
. This consumes the message.- Returns:
- null if there's no payload.
- Throws:
javax.xml.bind.JAXBException
- If JAXB reports an error during the processing.
-
readPayloadAsJAXB
Reads the payload as a Data-Bond object This consumes the message.- Returns:
- null if there's no payload.
- Throws:
javax.xml.bind.JAXBException
- If JAXB reports an error during the processing.
-
readPayload
Reads the payload as aXMLStreamReader
This consumes the message. The caller is encouraged to callXMLStreamReaderFactory.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:
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.
This method may not be called more than once since it may have released the reusable resources.
-
writePayloadTo
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 writeXMLStreamWriter.writeStartDocument()
norXMLStreamWriter.writeEndDocument()
If there's no payload, this method is no-op.
- Throws:
XMLStreamException
- If theXMLStreamWriter
reports an error, or some other errors happen during the processing.
-
writeTo
Writes the whole SOAP message (but not attachments) to the given writer. This consumes the message.- Throws:
XMLStreamException
- If theXMLStreamWriter
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 asSAXParseException
.SAXException
s thrown fromErrorHandler
should propagate directly through this method.- Throws:
SAXException
-
copy
Creates a copy of aMessage
.This method creates a new
Message
whose header/payload/attachments/properties are identical to thisMessage
. Once created, the createdMessage
and the originalMessage
behaves independently --- adding header/ attachment to oneMessage
doesn't affect anotherMessage
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.
- The original and the copy may not be
used concurrently by two threads (this allows two
Message
s 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. - 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 aMessage
.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
copy()
METHOD, YOU MUST USE THEcopyFrom(com.sun.xml.ws.api.message.Message)
METHOD IN THE IMPLEMENTATION. - The original and the copy may not be
used concurrently by two threads (this allows two
-
copyFrom
Thecopy()
method is used as a shorthand throughout the codecase in place of calling a copy constructor. However, that shorthand make it difficult to have a concrete method here in the base to do common work.Rather than have each
copy
method duplicate code, the following method is used in eachcopy
implementation. It MUST be called.- Returns:
- The Message that calls
copyFrom
inside thecopy
method after the copy constructor
-
getID
Deprecated.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
<MessageID>
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<MessageID>
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
<MessageID>
header is present when it's supposed to be.- Parameters:
binding
- object created byBindingID.createBinding()
- Returns:
- unique id for the message
-
getID
Deprecated.Retuns a unique id for the message.- Parameters:
av
- WS-Addressing versionsv
- SOAP version- Returns:
- unique id for the message
- See Also:
-
generateMessageID
Generates a UUID suitable for use as a MessageID value- Returns:
- generated UUID
-
getSOAPVersion
-