com.soa.message

Interface Message

All Known Subinterfaces:

SOAPMessage

All Known Implementing Classes:

AbstractMessage, SimpleMessage

public interface Message

Represents an XML service message with optional properties and attachments.

Since:

5.0

Method Summary

Modifier and Type	Method and Description
void	addAttachment(javax.activation.DataHandler content, Headers headers) Adds an attachment to the message.
void	addPart(java.lang.String name, java.lang.Object part) Normalized messages can support multiple parts.
boolean	arePartsEmpty() Returns whether there are any parts or not (empty) in the message.
boolean	canCarryBindingHeaders() Returns if the message can carry binding headers.
boolean	canNormalize() Returns whether the message can be normalized or not.
Message	copy() Create a copy of the message.
MessageAttachments	getAttachments() Provides direct access to the attachments for the message.
java.lang.String	getBindingURI() Returns the URI of the message's binding if the message is bound (not normalized).
javax.xml.transform.Source	getContent() Returns the content of the message.
java.lang.String	getContentPartName() When using parts in a message one of those parts can be considered the content of the message (see getContent()).
java.lang.String	getContentType() Returns the type of content of the message, i.e., application/xml, application/json.
java.lang.String	getCorrelationID() Returns a correlation identifier (if any) that can be used to correlate this message with another.
java.lang.String	getID() Returns the ID of the message (if any).
java.lang.Object	getPart(java.lang.String name) Returns the value/content of the part with the given name.
java.util.Set<java.lang.String>	getPartNames() Returns the names of the parts in the message (if any).
java.util.Map<java.lang.String,java.lang.Object>	getParts() Returns a map of parts keyed by their name.
java.util.Map	getProperties() Provides direct access to the Map of properties for the message.
java.lang.Object	getProperty(java.lang.String name) Returns the property with the given name.
java.util.Set	getPropertyNames() Returns the names of the properties associated with the message.
javax.security.auth.Subject	getSecuritySubject() Returns the security subject for the message with the consumer subject category (urn:org:federatedgovernance:security:subject-category:consumer).
Headers	getTransportHeaders() Returns the transport headers associated with the message (if any).
boolean	isFault() Returns whether or not the message is a fault message.
boolean	isNormalized() Returns whether the message is normalized or not.
Message	normalize() Normalizes the message.
Message	normalizeCopy() Normalizes the message leaving the original bound object unchanged.
Message	normalizeCopyToXML() Normalizes the message to an XML format leaving the original bound object unchanged.
Message	normalizeToXML() Normalizes the message to an XML format.
void	setAttachments(MessageAttachments attachments) Replaces the attachments of the message in one call for optimization.
void	setContent(javax.xml.transform.Source content) Changes the message content.
void	setContentPartName(java.lang.String name) When using parts in a message one of those parts can be considered the content of the message (see getContent()).
void	setContentType(java.lang.String contentType) Changes the type of content of the message, i.e., application/xml, application/json.
void	setCorrelationID(java.lang.String id) Changes the correlation ID of the message.
void	setID(java.lang.String id) Changes the ID of the message.
void	setProperties(java.util.Map properties) Replaces the properties of the message in one call for optimization.
void	setProperty(java.lang.String name, java.lang.Object property) Associates a property with the message.
void	setSecuritySubject(javax.security.auth.Subject subject) Changes the security subject for the message with the consumer subject category (urn:org:federatedgovernance:security:subject-category:consumer).
void	setTransportHeaders(Headers headers) Replaces the set of transport headers associated with the message.

Method Detail

getID

java.lang.String getID()

Returns the ID of the message (if any). An ID is typically used when the message is part of an asynchronous exchange. It may not be available for synchronous exchanges. If present, the ID will be unique between the producer and consumer of the messsage while the exchange it is part of is active.

Returns:

String identifier of the message, null if none available.

setID

void setID(java.lang.String id)

Changes the ID of the message. The ID will be unique between the producer and consumer of the messsage while the exchange it is part of is active.

Parameters:

id - String identifier of the message.

getCorrelationID

java.lang.String getCorrelationID()

Returns a correlation identifier (if any) that can be used to correlate this message with another. The most common example is for correlating an asynchronous response to a request message. This would be done by using the request message's ID as the response message's correlation ID.

Returns:

String correlation identifier, null if none available.

setCorrelationID

void setCorrelationID(java.lang.String id)

Changes the correlation ID of the message. The most common use is for asynchronous messaging. The request message ID would be set as the response message's correlation ID.

Parameters:

id - String correlation identifier.

setSecuritySubject

void setSecuritySubject(javax.security.auth.Subject subject)

Changes the security subject for the message with the consumer subject category (urn:org:federatedgovernance:security:subject-category:consumer). The security subject identifies the entity sending the message. This is a convenience method as a Map of all subjects associated with the message can be accessed through the MessageProperties.SECURITY_SUBJECTS property.

Parameters:

subject - Subject identifying the application sending the message.

getSecuritySubject

javax.security.auth.Subject getSecuritySubject()

Returns the security subject for the message with the consumer subject category (urn:org:federatedgovernance:security:subject-category:consumer). The security subject identifies the entity sending the message. This is a convenience method as a Map of all subjects associated with the message can be accessed through the MessageProperties.SECURITY_SUBJECTS property.

Returns:

Subject identifying the application sending the message.

getContent

javax.xml.transform.Source getContent()
                               throws GException

Returns the content of the message. WARNING: Do not make changes directly to the returned Source object without calling setContent(Source).

Returns:

Source holding the message content.

Throws:

GException - Thrown if unable to retrieve message content. Possibly caused by badly formed content.

setContent

void setContent(javax.xml.transform.Source content)
         throws GException

Changes the message content. If normalized either use this method for setting content or addPart(String,Object) if multiple parts are needed. Do not use both methods.

Parameters:

content - Source holding the message content.

Throws:

GException - Thrown if unable to change the content. Possibly caused by passing in badly formed content.

addAttachment

void addAttachment(javax.activation.DataHandler content,
                   Headers headers)
            throws GException

Adds an attachment to the message.

Parameters:

content - Content of the attachment.

headers - Any headers that are transported along with the attachment content.

Throws:

GException

setAttachments

void setAttachments(MessageAttachments attachments)
             throws GException

Replaces the attachments of the message in one call for optimization.

Parameters:

attachments - MessageAttachments instance.

Throws:

GException

getAttachments

MessageAttachments getAttachments()

Provides direct access to the attachments for the message.

Returns:

MessageAttachments, will be null if there are no attachments for this message.

getProperty

java.lang.Object getProperty(java.lang.String name)

Returns the property with the given name.

Parameters:

name - Name of the property.

Returns:

Object value of the property, null if not found.

setProperty

void setProperty(java.lang.String name,
                 java.lang.Object property)

Associates a property with the message.

Parameters:

name - Name of the property.

property - Value of the property.

getPropertyNames

java.util.Set getPropertyNames()

Returns the names of the properties associated with the message. Changes made to the Set are reflected in the message, so if a name is removed from the Set, the property is removed from the message. Names cannot be added however.

Returns:

Set of String property names.

setProperties

void setProperties(java.util.Map properties)

Replaces the properties of the message in one call for optimization.

Parameters:

properties - Map of properties keyed by a String.

getProperties

java.util.Map getProperties()

Provides direct access to the Map of properties for the message. Do NOT make changes to the returned Map.

Returns:

Map of properties keyed by Strings.

getTransportHeaders

Headers getTransportHeaders()

Returns the transport headers associated with the message (if any). This is a convenience method as the same headers can be accessed through the MessageProperties.TRANSPORT_HEADERS property.

Returns:

Headers holding transport headers for the message, null if none present.

setTransportHeaders

void setTransportHeaders(Headers headers)

Replaces the set of transport headers associated with the message. This is a convenience method as the same headers can be accessed through the MessageProperties.TRANSPORT_HEADERS property.

Parameters:

headers - Headers holding transport headers for the message.

isFault

boolean isFault()
         throws GException

Returns whether or not the message is a fault message.

Returns:

True if a fault, false if not.

Throws:

GException

isNormalized

boolean isNormalized()

Returns whether the message is normalized or not.

Returns:

True if normalized, false if not.

canNormalize

boolean canNormalize()

Returns whether the message can be normalized or not. Some types of messages may not support normalization.

Returns:

True if can be normalized, false if not.

copy

Message copy()
      throws GException

Create a copy of the message. Message normalization state and content are left intact. The returned message will have a copy of the message internal state, including any message properties.

Returns:

A copy of this Message.

Throws:

GException - Thrown if unable to copy.

normalize

Message normalize()
           throws GException

Normalizes the message. All defined message parts are taken from their bound encodings and placed in the message's parts map. A new normalized version of the message is returned. Due to the possibility of this original object using InputStreams to hold its content, after normalization this object's InputStreams will most likely be exhausted making this object unusable. To continue to use this object after normalization in its original bound format, use normalizeCopyToXML() instead.

Returns:

Normalized Message.

Throws:

GException - Thrown if unable to normalize.

normalizeCopy

Message normalizeCopy()
               throws GException

Normalizes the message leaving the original bound object unchanged. All defined message parts are taken from their bound encodings and placed in the message's parts map. A new normalized version of the message is returned. In order to leave the original object intact it must be copied which may be expensive from a performance perspective.

Returns:

Normalized Message.

Throws:

GException - Thrown if unable to normalize.

normalizeToXML

Message normalizeToXML()
                throws GException

Normalizes the message to an XML format. All defined message parts are taken from their bound encodings and placed in the message's parts map. The part identified as the content part (see getContentPartName()) will be translated into an XML representation. A new normalized version of the message is returned. Due to the possibility of this original object using InputStreams to hold its content, after normalization this object's InputStreams will most likely be exhausted making this object unusable. To continue to use this object after normalization in its original bound format, use normalizeCopyToXML() instead.

Returns:

Normalized Message.

Throws:

GException - Thrown if unable to normalize.

normalizeCopyToXML

Message normalizeCopyToXML()
                    throws GException

Normalizes the message to an XML format leaving the original bound object unchanged. All defined message parts are taken from their bound encodings and placed in the message's parts map. The part identified as the content part (see getContentPartName()) will be translated into an XML representation. A new normalized version of the message is returned. In order to leave the original object in tact it must be copied which may be expensive from a performance perspective.

Returns:

Normalized Message.

Throws:

GException - Thrown if unable to normalize.

canCarryBindingHeaders

boolean canCarryBindingHeaders()

Returns if the message can carry binding headers. Some types of messages are sent using protocols that don't support binding headers. Indicating that can save processing time during mediation.

Returns:

true if binding headers may be use, false if not.

getBindingURI

java.lang.String getBindingURI()

Returns the URI of the message's binding if the message is bound (not normalized).

Returns:

String URI of the message's binding, null if normalized.

getContentType

java.lang.String getContentType()

Returns the type of content of the message, i.e., application/xml, application/json.

Returns:

Type of message content.

setContentType

void setContentType(java.lang.String contentType)

Changes the type of content of the message, i.e., application/xml, application/json. This must match what is returned in getContent().

Parameters:

contentType - Type of message content.

addPart

void addPart(java.lang.String name,
             java.lang.Object part)

Normalized messages can support multiple parts. A part is synonymous with a message part as defined in the WSDL 1.1 spec, it is a named piece of content. The parts of a normalized message can then be encoded in a protocol specific way by a binding, i.e., query parameters, path parameteters, headers, or RPC encoded XML elements. If the message is not normalized there will be no parts. Use getContent() to get the content of the message. If the message is normalized there may be content accessed using getContent() instead of parts.

Parameters:

name - Name of the part, should correspond to a WSDL definend message part.

part - Value/content of the part. Typically a part should be an XML element that corresponds to what is defined in the WSDL definition. A part could be something other than that but unless the consumer of the message can read the content it will fail.

getPart

java.lang.Object getPart(java.lang.String name)

Returns the value/content of the part with the given name.

Parameters:

name - Name of the part.

Returns:

Value/content of the part.

getContentPartName

java.lang.String getContentPartName()

When using parts in a message one of those parts can be considered the content of the message (see getContent()). This method will return the name of the part that holds the content.

Returns:

Part name holding the message content.

setContentPartName

void setContentPartName(java.lang.String name)

When using parts in a message one of those parts can be considered the content of the message (see getContent()). This method can be used to specify the name of the part that should be considered the message content.

Parameters:

name - Name of the part holding the message content.

getPartNames

java.util.Set<java.lang.String> getPartNames()

Returns the names of the parts in the message (if any).

Returns:

Set of part names. The set is mutable so changes to the set will be reflected in the message.

arePartsEmpty

boolean arePartsEmpty()

Returns whether there are any parts or not (empty) in the message. If there are no parts there is likely content returned in getContent().

Returns:

true if no parts in message, false if there are.

getParts

java.util.Map<java.lang.String,java.lang.Object> getParts()

Returns a map of parts keyed by their name.

Returns:

Map of parts keyed by their name. The map is muutable so any changes will be reflected in the message. If there are no parts defined null will be returned.