org.jsecurity.util
Class ThreadContext

java.lang.Object
  org.jsecurity.util.ThreadContext

public abstract class ThreadContext
extends Object

A ThreadContext provides a means of binding and unbinding objects to the current thread based on key/value pairs.

An internal HashMap is used to maintain the key/value pairs for each thread.

If the desired behavior is to ensure that bound data is not shared across threads in a pooled or reusable threaded environment, the application (or more likely a framework) must bind and remove any necessary values at the beginning and end of stack execution, respectively (i.e. individually explicitly or all via the clear method).

Since:

0.1

Author:

Les Hazlewood

See Also:

clear()

Field Summary

static String	INET_ADDRESS_KEY
protected static ThreadLocal<Map<Object,Object>>	resources
static String	SECURITY_MANAGER_KEY
static String	SUBJECT_KEY

Constructor Summary

protected

ThreadContext() Default no-argument constructor.

Method Summary

static void	bind(InetAddress inetAddress) Convenience method that simplifies binding an InetAddress to the ThreadContext.
static void	bind(SecurityManager securityManager) Convenience method that simplifies binding the application's SecurityManager instance to the ThreadContext.
static void	bind(Subject subject) Convenience method that simplifies binding a Subject to the ThreadContext.
static void	clear() Removes all values bound to this ThreadContext, which includes any Subject, Session, or InetAddress that may be bound by these respective objects' conveninece methods, as well as all values bound by your application code.
static boolean	containsKey(Object key) Returns true if a value for the key is bound to the current thread, false otherwise.
static Object	get(Object key) Returns the object for the specified key that is bound to the current thread.
static InetAddress	getInetAddress() Convenience method that simplifies retrieval of a thread-bound InetAddress.
protected static Map<Object,Object>	getResources() Returns the ThreadLocal Map.
static SecurityManager	getSecurityManager() Convenience method that simplifies retrieval of the application's SecurityManager instance from the current thread.
static Subject	getSubject() Convenience method that simplifies retrieval of a thread-bound Subject.
static void	put(Object key, Object value) Binds value for the given key to the current thread.
static Object	remove(Object key) Unbinds the value for the given key from the current thread.
static InetAddress	unbindInetAddress() Convenience method that simplifies removal of a thread-local InetAddress from the thread.
static SecurityManager	unbindSecurityManager() Convenience method that simplifies removal of the application's SecurityManager instance from the thread.
static Subject	unbindSubject() Convenience method that simplifies removal of a thread-local Subject from the thread.

Methods inherited from class java.lang.Object

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

Field Detail

SECURITY_MANAGER_KEY

public static final String SECURITY_MANAGER_KEY

SUBJECT_KEY

public static final String SUBJECT_KEY

INET_ADDRESS_KEY

public static final String INET_ADDRESS_KEY

resources

protected static ThreadLocal<Map<Object,Object>> resources

Constructor Detail

ThreadContext

protected ThreadContext()

Default no-argument constructor.

Method Detail

getResources

protected static Map<Object,Object> getResources()

Returns the ThreadLocal Map. This Map is used internally to bind objects to the current thread by storing each object under a unique key.

Returns:

the map of bound resources

get

public static Object get(Object key)

Returns the object for the specified key that is bound to the current thread.

Parameters:

key - the key that identifies the value to return

Returns:

the object keyed by key or null if no value exists for the specified key

put

public static void put(Object key,
                       Object value)

Binds value for the given key to the current thread.

A null value has the same effect as if remove was called for the given key, i.e.:

 if ( value == null ) {
     remove( key );
 }

Parameters:

key - The key with which to identify the value.

value - The value to bind to the thread.

Throws:

IllegalArgumentException - if the key argument is null.

remove

public static Object remove(Object key)

Unbinds the value for the given key from the current thread.

Parameters:

key - The key identifying the value bound to the current thread.

Returns:

the object unbound or null if there was nothing bound under the specified key name.

containsKey

public static boolean containsKey(Object key)

Returns true if a value for the key is bound to the current thread, false otherwise.

Parameters:

key - the key that may identify a value bound to the current thread.

Returns:

true if a value for the key is bound to the current thread, false otherwise.

clear

public static void clear()

Removes all values bound to this ThreadContext, which includes any Subject, Session, or InetAddress that may be bound by these respective objects' conveninece methods, as well as all values bound by your application code.

This operation is meant as a clean-up operation that may be called at the end of thread execution to prevent data corruption in a pooled thread environment.

getSecurityManager

public static SecurityManager getSecurityManager()

Convenience method that simplifies retrieval of the application's SecurityManager instance from the current thread. If there is no SecurityManager bound to the thread (probably because framework code did not bind it to the thread), this method returns null.

It is merely a convenient wrapper for the following:

return (SecurityManager)get( SECURITY_MANAGER_KEY );

This method only returns the bound value if it exists - it does not remove it from the thread. To remove it, one must call unbindSecurityManager() instead.

Returns:

the Subject object bound to the thread, or null if there isn't one bound.

Since:

0.9

bind

public static void bind(SecurityManager securityManager)

Convenience method that simplifies binding the application's SecurityManager instance to the ThreadContext.

The method's existence is to help reduce casting in code and to simplify remembering of ThreadContext key names. The implementation is simple in that, if the SecurityManager is not null, it binds it to the thread, i.e.:

 if (securityManager != null) {
     put( SECURITY_MANAGER_KEY, securityManager);
 }

Parameters:

securityManager - the application's SecurityManager instance to bind to the thread. If the argument is null, nothing will be done.

Since:

0.9

unbindSecurityManager

public static SecurityManager unbindSecurityManager()

Convenience method that simplifies removal of the application's SecurityManager instance from the thread.

The implementation just helps reduce casting and remembering of the ThreadContext key name, i.e it is merely a conveient wrapper for the following:

return (SecurityManager)remove( SECURITY_MANAGER_KEY );

If you wish to just retrieve the object from the thread without removing it (so it can be retrieved later during thread execution), use the getSecurityManager() method instead.

Returns:

the application's SecurityManager instance previously bound to the thread, or null if there was none bound.

Since:

0.9

getSubject

public static Subject getSubject()

Convenience method that simplifies retrieval of a thread-bound Subject. If there is no Subject bound to the thread, this method returns null. It is merely a convenient wrapper for the following:

return (Subject)get( SUBJECT_KEY );

This method only returns the bound value if it exists - it does not remove it from the thread. To remove it, one must call unbindSubject() instead.

Returns:

the Subject object bound to the thread, or null if there isn't one bound.

Since:

0.2

bind

public static void bind(Subject subject)

Convenience method that simplifies binding a Subject to the ThreadContext.

The method's existence is to help reduce casting in your own code and to simplify remembering of ThreadContext key names. The implementation is simple in that, if the Subject is not null, it binds it to the thread, i.e.:

 if (subject != null) {
     put( SUBJECT_KEY, subject );
 }

Parameters:

subject - the Subject object to bind to the thread. If the argument is null, nothing will be done.

Since:

0.2

unbindSubject

public static Subject unbindSubject()

Convenience method that simplifies removal of a thread-local Subject from the thread.

The implementation just helps reduce casting and remembering of the ThreadContext key name, i.e it is merely a conveient wrapper for the following:

return (Subject)remove( SUBJECT_KEY );

If you wish to just retrieve the object from the thread without removing it (so it can be retrieved later during thread execution), you should use the getSubject() method for that purpose.

Returns:

the Subject object previously bound to the thread, or null if there was none bound.

Since:

0.2

getInetAddress

public static InetAddress getInetAddress()

Convenience method that simplifies retrieval of a thread-bound InetAddress. If there is no InetAddress bound to the thread, this method returns null. It is merely a convenient wrapper for the following:

return (InetAddress)get( INET_ADDRESS_KEY );

This method only returns the bound value if it exists - it does not remove it from the thread. To remove it, one must call unbindInetAddress instead.

Returns:

the InetAddress object bound to the thread, or null if there isn't one bound.

Since:

0.2

bind

public static void bind(InetAddress inetAddress)

Convenience method that simplifies binding an InetAddress to the ThreadContext.

The method's existence is to help reduce casting in your own code and to simplify remembering of ThreadContext key names. The implementation is simple in that, if the inetAddress is not null, it binds it to the thread, i.e.:

 if (inetAddress != null) {
     put( INET_ADDRESS_KEY, inetAddress );
 }

Parameters:

inetAddress - the InetAddress to bind to the thread. If the argument is null, nothing will be done.

Since:

0.2

unbindInetAddress

public static InetAddress unbindInetAddress()

Convenience method that simplifies removal of a thread-local InetAddress from the thread.

The implementation just helps reduce casting and remembering of the ThreadContext key name, i.e it is merely a conveient wrapper for the following:

return (InetAddress)remove( INET_ADDRESS_KEY );

If you wish to just retrieve the object from the thread without removing it (so it can be retrieved later during thread execution), you should use the getInetAddress() method for that purpose.

Returns:

the InetAddress object previously bound to the thread, or null if there was none bound.

Since:

0.2