org.jboss.soa.esb.message
Class MessagePayloadProxy

java.lang.Object
  extended by org.jboss.soa.esb.message.MessagePayloadProxy

public class MessagePayloadProxy
extends java.lang.Object

Utility class to help make accessing the message payload a little more deterministic.

This class can be used by actions/listeners to manage access to the payload on a Message instance. The class is constructed from the configuration of the component (listener, actions etc) using the proxy instance. It checks the configuration for "get-payload-location" and "set-payload-location" configuration properties, defaulting both to the Default Body Location (Body.DEFAULT_LOCATION).

Prior to the introduction of this class, there was no standardised pattern for components exchanging data through the ESB Message. It was adhoc in nature, with components needing to have knowledge of where other components set the data in the message. This functionality is still supported through the "get-payload-location" and "set-payload-location" configuration properties, but all ESB now (by default) get and set their data on the Body.DEFAULT_LOCATION.

Code writen to work against ESB version up to and including version 4.2GA can still use the old adhoc exchange patterns by setting the "core:use.legacy.message.payload.exchange.patterns" config property in the jbossesb-properties.xml file.

Author:
tom.fennelly@jboss.com

Nested Class Summary
static class MessagePayloadProxy.NullPayloadHandling
           
 
Field Summary
static java.lang.String GET_PAYLOAD_LOCATION
          Component property for the message location used in the getPayload(Message) method.
static java.lang.String MIME_TYPE
          Mime type message property key.
static java.lang.String SET_PAYLOAD_LOCATION
          Component property for the message location used in the setPayload(Message, Object) method.
static java.lang.String USE_LEGACY_EXCHANGE_PATTERNS_CONFIG
          jbossesb-properties.xml config key for switching on and off legacy (adhoc) message payload location getting/setting.
 
Constructor Summary
MessagePayloadProxy(ConfigTree config)
          Public constructor.
MessagePayloadProxy(ConfigTree config, java.lang.String[] legacyGetPayloadLocations, java.lang.String[] legacySetPayloadLocations)
          Deprecated. Use the non-legacy constructor. This method is here simply to support code that is dependent on the 4.2.x message payload exchange patterns an will be removed in a subsequent release. New code should use the MessagePayloadProxy(org.jboss.soa.esb.helpers.ConfigTree) constructor.
MessagePayloadProxy(java.lang.String getPayloadLocation, java.lang.String setPayloadLocation)
          Public constructor.
 
Method Summary
 java.lang.String getGetPayloadLocation()
          Get the primary message input Location as configured on the component config ("get-payload-location").
 MessagePayloadProxy.NullPayloadHandling getNullGetPayloadHandling()
          Get the null set-payload handling config.
 MessagePayloadProxy.NullPayloadHandling getNullSetPayloadHandling()
          Get the null get-payload handling config.
 java.lang.Object getPayload(Message message)
          Get the primary message payload from the supplied message.
 java.lang.String getSetPayloadLocation()
          Get the primary message output Location as configured on the component config ("set-payload-location").
static boolean isUsingLegacyPatterns()
           
 void setNullGetPayloadHandling(MessagePayloadProxy.NullPayloadHandling nullGetPayloadHandling)
          Set the null set-payload handling config.
 void setNullSetPayloadHandling(MessagePayloadProxy.NullPayloadHandling nullSetPayloadHandling)
          Set the null get-payload handling config.
 void setPayload(Message message, java.lang.Object payload)
          Set the primary message payload on the supplied message.
static void setUseLegacyPatterns(boolean useLegacyPatterns)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

USE_LEGACY_EXCHANGE_PATTERNS_CONFIG

public static final java.lang.String USE_LEGACY_EXCHANGE_PATTERNS_CONFIG
jbossesb-properties.xml config key for switching on and off legacy (adhoc) message payload location getting/setting.

See Also:
Constant Field Values

GET_PAYLOAD_LOCATION

public static final java.lang.String GET_PAYLOAD_LOCATION
Component property for the message location used in the getPayload(Message) method. Defaults to Body.DEFAULT_LOCATION.

See Also:
Constant Field Values

SET_PAYLOAD_LOCATION

public static final java.lang.String SET_PAYLOAD_LOCATION
Component property for the message location used in the setPayload(Message, Object) method. Defaults to Body.DEFAULT_LOCATION.

See Also:
Constant Field Values

MIME_TYPE

public static final java.lang.String MIME_TYPE
Mime type message property key.

See Also:
Constant Field Values
Constructor Detail

MessagePayloadProxy

public MessagePayloadProxy(ConfigTree config,
                           java.lang.String[] legacyGetPayloadLocations,
                           java.lang.String[] legacySetPayloadLocations)
Deprecated. Use the non-legacy constructor. This method is here simply to support code that is dependent on the 4.2.x message payload exchange patterns an will be removed in a subsequent release. New code should use the MessagePayloadProxy(org.jboss.soa.esb.helpers.ConfigTree) constructor.

Public constructor.

Parameters:
config - The component configuration.
legacyGetPayloadLocations - The message input locations as defined in the 4.2.x codebase.
legacySetPayloadLocations - The message output locations as defined in the 4.2.x codebase.

MessagePayloadProxy

public MessagePayloadProxy(ConfigTree config)
Public constructor.

Parameters:
config - The component configuration.

MessagePayloadProxy

public MessagePayloadProxy(java.lang.String getPayloadLocation,
                           java.lang.String setPayloadLocation)
Public constructor.

Parameters:
config - The component configuration.
Method Detail

getPayload

public java.lang.Object getPayload(Message message)
                            throws MessageDeliverException
Get the primary message payload from the supplied message.

Parameters:
message - The Message instance.
Returns:
The primary message payload.
Throws:
MessageDeliverException - See setNullGetPayloadHandling(org.jboss.soa.esb.message.MessagePayloadProxy.NullPayloadHandling).

setPayload

public void setPayload(Message message,
                       java.lang.Object payload)
                throws MessageDeliverException
Set the primary message payload on the supplied message.

Parameters:
message - The message instance.
payload - The message primary payload.
Throws:
MessageDeliverException - See setNullSetPayloadHandling(org.jboss.soa.esb.message.MessagePayloadProxy.NullPayloadHandling).

getGetPayloadLocation

public java.lang.String getGetPayloadLocation()
Get the primary message input Location as configured on the component config ("get-payload-location").

Returns:
The message input location.

getSetPayloadLocation

public java.lang.String getSetPayloadLocation()
Get the primary message output Location as configured on the component config ("set-payload-location").

Returns:
The message output location.

getNullGetPayloadHandling

public MessagePayloadProxy.NullPayloadHandling getNullGetPayloadHandling()
Get the null set-payload handling config.

Returns:
Null set-payload Handling config.

setNullGetPayloadHandling

public void setNullGetPayloadHandling(MessagePayloadProxy.NullPayloadHandling nullGetPayloadHandling)
Set the null set-payload handling config.

If not set, defaults to MessagePayloadProxy.NullPayloadHandling.EXCEPTION.

Parameters:
nullGetPayloadHandling - Null set-payload Handling config.

getNullSetPayloadHandling

public MessagePayloadProxy.NullPayloadHandling getNullSetPayloadHandling()
Get the null get-payload handling config.

Returns:
Null get-payload Handling config.

setNullSetPayloadHandling

public void setNullSetPayloadHandling(MessagePayloadProxy.NullPayloadHandling nullSetPayloadHandling)
Set the null get-payload handling config.

If not set, defaults to MessagePayloadProxy.NullPayloadHandling.NONE.

Parameters:
nullSetPayloadHandling - Null get-payload Handling config.

setUseLegacyPatterns

public static void setUseLegacyPatterns(boolean useLegacyPatterns)

isUsingLegacyPatterns

public static boolean isUsingLegacyPatterns()