com.vordel.circuit
Class Message

java.lang.Object
  com.vordel.circuit.Message

All Implemented Interfaces:

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

public class Message
extends 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.

Nested Class Summary

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

Fields inherited from interface com.vordel.common.Dictionary

empty

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	clear()
void	complete() Called once the message has been entirely processed and the client transaction complete.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
static void	deregisterMessageLocalStorage(int slot) Deregister a message local slot.
java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.Object>>	entrySet()
void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
void	forceGenerateAttributes()
java.lang.Object	get(java.lang.Object key)
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()
boolean	isEmpty()
java.util.Set<java.lang.String>	keySet()
void	logPayload(Circuit c, int maskItem, MessageProcessor caller)
java.util.Map<java.lang.String,java.lang.Object>	pop()
void	push(java.util.Map<java.lang.String,java.lang.Object> map)
java.lang.Object	put(java.lang.String key, java.lang.Object value)
void	putAll(java.util.Map<? extends java.lang.String,? extends java.lang.Object> m)
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.Object key)
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)
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)
int	size()
void	storeOpsField(com.vordel.vary.VariantObject object, java.lang.String msgField, com.vordel.vary.IntegerField opsDBField)
void	storeOpsField(com.vordel.vary.VariantObject object, java.lang.String msgField, com.vordel.vary.StringField opsDBField)
java.util.Collection<java.lang.Object>	values()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

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

push

public void push(java.util.Map<java.lang.String,java.lang.Object> map)

pop

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

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>

get

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

Specified by:

get in interface com.vordel.common.Dictionary

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)

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()

logPayload

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

storeOpsField

public void storeOpsField(com.vordel.vary.VariantObject object,
                          java.lang.String msgField,
                          com.vordel.vary.StringField opsDBField)

storeOpsField

public void storeOpsField(com.vordel.vary.VariantObject object,
                          java.lang.String msgField,
                          com.vordel.vary.IntegerField opsDBField)

size

public int size()

Specified by:

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

isEmpty

public boolean isEmpty()

Specified by:

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

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

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

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

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

get

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

Specified by:

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

remove

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

Specified by:

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

putAll

public void putAll(java.util.Map<? extends java.lang.String,? extends java.lang.Object> m)

Specified by:

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

clear

public void clear()

Specified by:

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

keySet

public java.util.Set<java.lang.String> keySet()

Specified by:

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

values

public java.util.Collection<java.lang.Object> values()

Specified by:

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

entrySet

public java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.Object>> entrySet()

Specified by:

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