com.vordel.circuit
Class Message

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap<java.lang.String,java.lang.Object>
          com.vordel.circuit.Message

All Implemented Interfaces:

com.vordel.common.Dictionary, java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.String,java.lang.Object>

public class Message
extends java.util.HashMap<java.lang.String,java.lang.Object>
implements java.util.Map<java.lang.String,java.lang.Object>, com.vordel.common.Dictionary

Represents the state of a request as it passes through a Circuit This object maps property names to Objects.

MessageProcessors can inspect, add, and remove properties as they perform their work. Co-operating MessageProcessors can share these properties, once a type is agreed for them.

The MessageListener interface can be used to listen to Message lifecycle events. A MessageListener can be registered with a Message instance by listening first for a Message creation event via the addCreationListener(MessageCreationListener) then calling the addMessageListener(MessageListener) method on the Message parameter, e.g.

   Message.addCreationListener(new MessageCreationListener() {
      public void messageCreated(Message m, Object source) {
          m.addMessageListener(new MessageListenerAdapter(){
              public void preCircuitProcessing(Circuit initialContext, Message message, Object context) {
                  System.out.println("Message about to be processed in circuits, id: "+message.correlationId);
              }
          });
       }                
   });
 

Notification of completion of a message in the circuit can be monitored, to allow for cleanup of resources when the message is no longer useful. MessageListener.onMessageCompletion(com.vordel.circuit.Message) callbacks are called in the reverse order to that in which they are registered.

See Also:

MessageProperties, which contains a list of well-known message properties., Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Nested classes/interfaces inherited from interface com.vordel.common.Dictionary

com.vordel.common.Dictionary.MapAs

Field Summary

com.vordel.dwe.CorrelationID	correlationId
protected static java.util.List<MessageCreationListener>	creationCallbacks
long	creationTime

Constructor Summary

Message(com.vordel.dwe.CorrelationID correlationId, java.lang.Object source)
Create a new message object.

Method Summary

static void	addCreationListener(MessageCreationListener mcl) When a new message is created, each MessageCreationListener is informed, so it may decorate the message with its own private annotations.
void	addMessageListener(MessageListener listener) Add a listener to intercept this Message before and after filter and circuit invocations.
void	addPropertiesListener(java.beans.PropertyChangeListener listener)
void	addPropertiesListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
java.lang.String	allocID()
void	complete() Called once the message has been entirely processed and the client transaction complete.
boolean	containsKey(java.lang.String key)
static void	deregisterMessageLocalStorage(int slot) Deregister a message local slot.
void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
void	forceGenerateAttributes()
java.lang.Object	get(java.lang.String key)
com.vordel.dwe.CorrelationID	getIDBase()
int	getLogMask()
java.lang.Object	getMessageLocalStorage(int slot) Get the caller-specific Object previously set in the Message by setMessageLocalStorage(int, java.lang.Object).
int	getPayloadMask()
com.vordel.circuit.log.LogMessagePayloadProcessor	getPayloadProcessor()
void	logPayload(Circuit c, int maskItem, MessageProcessor caller)
java.lang.Object	put(java.lang.String key, java.lang.Object value)
static void	registerGenerator(java.lang.String property, MessagePropertyGenerator generator)
static int	registerMessageLocalStorage() Reserve a slot in each new Message instance in which to store an Object.
java.lang.Object	remove(java.lang.String key)
static boolean	removeCreationListener(MessageCreationListener mcl) Remove the message creation listener
void	removeMessageListener(MessageListener listener) Remove all occurrences of a listener added in the corresponding addMessageListener(com.vordel.circuit.MessageListener) method.
void	removePropertiesListener(java.beans.PropertyChangeListener listener)
void	removePropertiesListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
java.lang.String	replaceAttributeValues(java.lang.String inputString) takes a string containing message attribute names delimited by "%" characters and replaces the so-encoded substrings with the named values from the message.
void	setLogMask(int logMask)
void	setMessageLocalStorage(int slot, java.lang.Object o) Set a caller-specific Object in a previously registered slot in the Message.
void	setPayloadMask(int payloadMask)
void	setPayloadProcessor(com.vordel.circuit.log.LogMessagePayloadProcessor payloadProcessor)
void	storeOpsField(com.vordel.dwe.http.Transaction txn, java.lang.String msgField, java.lang.String opsDBField)

Methods inherited from class java.util.HashMap

clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, putAll, remove, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, putAll, remove, size, values

Field Detail

correlationId

public final com.vordel.dwe.CorrelationID correlationId

creationTime

public final long creationTime

creationCallbacks

protected static final java.util.List<MessageCreationListener> creationCallbacks

Constructor Detail

Message

public Message(com.vordel.dwe.CorrelationID correlationId,
               java.lang.Object source)

Create a new message object. At a minimum, the following fields are initialised:

• correlationId: A unique id for this message
• creationTime: The creation time of this message

and the following properties are initialized:

• MessageProperties.MESSAGE_RECEPTION_TIME: The creationTime available via the properties

Any registered MessageCreationListeners are informed of the construction of this message, after the specified fields are initialized.

Method Detail

getIDBase

public com.vordel.dwe.CorrelationID getIDBase()

allocID

public java.lang.String allocID()

registerMessageLocalStorage

public static final int registerMessageLocalStorage()

Reserve a slot in each new Message instance in which to store an Object. There are a maximum of 64 slots available for message local storage, if attempts are made to register additional slots a RuntimeException will occur. A likely caller of this method would be a LoadableModule, via its LoadableModule.load(com.vordel.dwe.LoadableModule, java.lang.String) method, which may wish to reserve one slot for all instances of its type to say track transport-specific information in each Message. Lookup of Message-local Objects is optimized as it is a simple indexing into an internal array, and Objects stored in this way are isolated from the MessageProperties.

Returns:

The slot which has been reserved by the caller. This slot number will be the same for all Message instances, and the caller can use this slot to store an arbitrary Object for the duration of its lifetime.

Throws:

java.lang.RuntimeException - if the 64 slot maximum is exceeded.

See Also:

getMessageLocalStorage(int), setMessageLocalStorage(int, Object), deregisterMessageLocalStorage(int)

deregisterMessageLocalStorage

public static final void deregisterMessageLocalStorage(int slot)

Deregister a message local slot. Typically called by a LoadableModule.unload() method.

Parameters:

slot - The slot number to release. This slot becomes available to further registerMessageLocalStorage() calls. There is no guarantee that subsequent calls to registerMessageLocalStorage() by the same caller will result in the same slot being returned.

setMessageLocalStorage

public void setMessageLocalStorage(int slot,
                                   java.lang.Object o)

Set a caller-specific Object in a previously registered slot in the Message. Typically called via a MessageListener callback method, early on in the Message lifecycle.

Parameters:

slot - The slot in which to set the Object.

o - The Object.

getMessageLocalStorage

public java.lang.Object getMessageLocalStorage(int slot)

Get the caller-specific Object previously set in the Message by setMessageLocalStorage(int, java.lang.Object).

Parameters:

slot - The slot to lookup.

Returns:

The Object previously set.

complete

public void complete()

Called once the message has been entirely processed and the client transaction complete. Typically called by a TransportModule when finished with the client transactions on this Message.

addCreationListener

public static final void addCreationListener(MessageCreationListener mcl)

When a new message is created, each MessageCreationListener is informed, so it may decorate the message with its own private annotations.

removeCreationListener

public static final boolean removeCreationListener(MessageCreationListener mcl)

Remove the message creation listener

Returns:

true if this list contained the specified message creation listener.

addMessageListener

public final void addMessageListener(MessageListener listener)

Add a listener to intercept this Message before and after filter and circuit invocations.

Parameters:

listener - The MessageListener

removeMessageListener

public final void removeMessageListener(MessageListener listener)

Remove all occurrences of a listener added in the corresponding addMessageListener(com.vordel.circuit.MessageListener) method.

Parameters:

listener - The MessageListener

setLogMask

public void setLogMask(int logMask)

getLogMask

public int getLogMask()

setPayloadMask

public void setPayloadMask(int payloadMask)

getPayloadMask

public int getPayloadMask()

setPayloadProcessor

public void setPayloadProcessor(com.vordel.circuit.log.LogMessagePayloadProcessor payloadProcessor)

getPayloadProcessor

public com.vordel.circuit.log.LogMessagePayloadProcessor getPayloadProcessor()

addPropertiesListener

public final void addPropertiesListener(java.beans.PropertyChangeListener listener)

addPropertiesListener

public final void addPropertiesListener(java.lang.String propertyName,
                                        java.beans.PropertyChangeListener listener)

removePropertiesListener

public final void removePropertiesListener(java.beans.PropertyChangeListener listener)

removePropertiesListener

public final void removePropertiesListener(java.lang.String propertyName,
                                           java.beans.PropertyChangeListener listener)

firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.Object newValue)

put

public java.lang.Object put(java.lang.String key,
                            java.lang.Object value)

Specified by:

put in interface java.util.Map<java.lang.String,java.lang.Object>

Overrides:

put in class java.util.HashMap<java.lang.String,java.lang.Object>

remove

public java.lang.Object remove(java.lang.String key)

registerGenerator

public static void registerGenerator(java.lang.String property,
                                     MessagePropertyGenerator generator)

forceGenerateAttributes

public void forceGenerateAttributes()

replaceAttributeValues

public java.lang.String replaceAttributeValues(java.lang.String inputString)

takes a string containing message attribute names delimited by "%" characters and replaces the so-encoded substrings with the named values from the message.

Parameters:

inputString - The string with the attributes names.

Returns:

The string with names replaced with values.

get

public java.lang.Object get(java.lang.String key)

Specified by:

get in interface com.vordel.common.Dictionary

containsKey

public boolean containsKey(java.lang.String key)

Specified by:

containsKey in interface com.vordel.common.Dictionary

logPayload

public void logPayload(Circuit c,
                       int maskItem,
                       MessageProcessor caller)

storeOpsField

public void storeOpsField(com.vordel.dwe.http.Transaction txn,
                          java.lang.String msgField,
                          java.lang.String opsDBField)