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


Copyright 2001 Apache Jakarta Project. All Rights Reserved.