org.apache.avalon.excalibur.lang
Class LayeredThreadContext

java.lang.Object
  |
  +--org.apache.avalon.excalibur.lang.LayeredThreadContext

public final class LayeredThreadContext

extends java.lang.Object

The LayeredThreadContext defines a set of data that is associated with a particular thread. This is a useful feature for many of the same reasons as ThreadContext is useful.

The difference between LayeredThreadContext and ThreadContext is the presence of Layers. When accessing a variable from the context the system will check the top layer. If the variable is not in the top layer it will check the layer underneath and so on until the variable is found or there are no more layers or a "divider" layer occurs.

These variables are managed by the LayeredThreadContext. However as it is not possible to inject code to be executed at the start of a thread, new threads may not be activated and the variables may not be set appropriately. In such cases it is recomended that the developer use InheritableThreadLocal as the underlying representation of the variable. By doing this the InheritableThreadLocal will maintain the appropriate state in newly created Thread.

The policy chosend to manage such state is pluggable by the user. It is expected developers will provide a policy object that will manage thread local variables. For instance an application server may choose to keep the name of the application, the Subject it is running as and perhaps other state in such variables.

Note that the idea for this code was derived from the HPs CSF framework.

Author:

Peter Donald

Constructor Summary

LayeredThreadContext(ThreadContextPolicy policy)
Default constructor to create an empty LayeredThreadContext with specified policy.

Method Summary

protected boolean	contextContainsKey(java.lang.String key) Utility method to search layers to see if key is found.
protected java.lang.Object	contextGet(java.lang.String key) Utility method to search layers to retrieve value for key.
protected LayeredThreadContext	duplicate() Method to allow duplication of ThreadContext for new threads.
static LayeredThreadContext	getThreadContext() Retrieve the LayeredThreadContext associated with the current thread.
void	pop(java.lang.Object key) Pop layers off the top of context stack until you find a layer that has a key that matches specified key.
void	push(java.lang.Object key, java.util.Map map, boolean isDivider) Push a layer onto context stack with specified key.
static void	setThreadContext(LayeredThreadContext threadContext) Set the LayeredThreadContext associated with the current thread.

Methods inherited from class java.lang.Object

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

Constructor Detail

LayeredThreadContext

public LayeredThreadContext(ThreadContextPolicy policy)

Default constructor to create an empty LayeredThreadContext with specified policy.

Method Detail

getThreadContext

public static LayeredThreadContext getThreadContext()

Retrieve the LayeredThreadContext associated with the current thread.

Returns:

the LayeredThreadContext associated with the current thread.

setThreadContext

public static void setThreadContext(LayeredThreadContext threadContext)
                             throws java.lang.SecurityException

Set the LayeredThreadContext associated with the current thread. This code will also call deactivate() on the old LayeredThreadContext if present and activate() on new LayeredThreadContext (if not null).

Parameters:

threadContext - the new LayeredThreadContext

Throws:

java.lang.SecurityException - if the caller does not have permission to set thread pool

pop

public void pop(java.lang.Object key)
         throws java.lang.IllegalArgumentException

Pop layers off the top of context stack until you find a layer that has a key that matches specified key.

Note that no security check is performed because it is expected that anyone with the correct key is allowed to call pop() for the matching layer.

Parameters:

key - the layer key

Throws:

java.lang.IllegalArgumentException - if no layer matches key

push

public void push(java.lang.Object key,
                 java.util.Map map,
                 boolean isDivider)
          throws java.lang.SecurityException,
                 java.lang.IllegalArgumentException

Push a layer onto context stack with specified key. Add entries to layer as specified in map and make the layer a "divider" layer if isDivider == true.

Parameters:

key - the layer key

map - the map of values to place in layer

isDivider - true if the layer is to be a divider layer

Throws:

java.lang.IllegalArgumentException - if the map contains invalid entries

contextGet

protected java.lang.Object contextGet(java.lang.String key)

Utility method to search layers to retrieve value for key.

Parameters:

key - the key to look for

Returns:

the Object found or null

contextContainsKey

protected boolean contextContainsKey(java.lang.String key)

Utility method to search layers to see if key is found.

Parameters:

key - the key to look for

Returns:

true if key found, false otherwise

duplicate

protected LayeredThreadContext duplicate()

Method to allow duplication of ThreadContext for new threads.

Returns:

the duplicated context