tyrex.tm
Class RuntimeContext

java.lang.Object
  tyrex.tm.RuntimeContext

public abstract class RuntimeContext

extends java.lang.Object

The runtime context provides an association between a component or client, the current thread, and resources used by the application.

The runtime context keeps track of active transaction, JNDI ENC, security subject, and open connections. It is associated with a component or client, and can be preserved across method invocations by associating it with the current thread.

Each thread is associated with a runtime context, whether explicitly or implicitly. A thread can be associated with a particular runtime context by calling setRuntimeContext. If this method was not called, a default runtime context is created on demand.

A new runtime context can be created with one of the newRuntimeContext methods and populated with JNDI bindings and security context. The runtime context is then associated with the current thread across method invocations belonging to the same component or client.

The current thread association behaves like a FIFO stack. The current runtime context is the last context associated with a call to setRuntimeContext. Calling this method multiple times pushes runtime contexts down the stack. The previous runtime context can be restored by calling unsetRuntimeContext.

The runtime context keeps track of the current active transaction. When the runtime context is associated with the current thread, this is the same transaction available from TransactionManager.

The runtime context keeps track of the JNDI environment naming context. The JNDI bindings are accessible from the java: URL when the runtime context is associated with the current thread. The bindings can be changed by obtaining a read-write JNDI context from the runtime context.

The runtime context keeps track of the security subject used for authentication and authorization when the runtime context is associated with the current thread.

The runtime context keeps track of all connections obtained from the environment naming context. Open connections can be retained across method invocations.

This runtime context is thread-safe.

Version:

$Revision: 1.1 $ $Date: 2001/03/12 19:23:40 $

Author:

Assaf Arkin

Constructor Summary

RuntimeContext()

Method Summary

abstract void	cleanup() Cleanup the runtime context and discard all resources associated with it.
static void	cleanup(java.lang.Thread thread) Called to destroy all association with a thread.
abstract javax.naming.Context	getEnvContext() Returns the JNDI environment context associated with this runtime context.
static RuntimeContext	getRuntimeContext() Returns the runtime context associated with the current thread.
abstract javax.security.auth.Subject	getSubject() Returns the security subject associated with this runtime context.
abstract javax.transaction.Transaction	getTransaction() Returns the transaction associated with this runtime context.
static javax.naming.Context	newEnvContext() Creates and returns an new JNDI context.
static RuntimeContext	newRuntimeContext() Creates and returns a new runtime context.
static RuntimeContext	newRuntimeContext(javax.naming.Context envContext, javax.security.auth.Subject subject) Creates and returns a new runtime context.
static void	setRuntimeContext(RuntimeContext context) Associates a runtime context with the current thread.
static RuntimeContext	unsetRuntimeContext() Dissociates the runtime context from the current thread,

Methods inherited from class java.lang.Object

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

Constructor Detail

RuntimeContext

public RuntimeContext()

Method Detail

getEnvContext

public abstract javax.naming.Context getEnvContext()

Returns the JNDI environment context associated with this runtime context.

The returned context is read-write and can be populated with objects available from the JNDI environment context when this runtime context is associated with the current thread.

Returns:

The JNDI environment context

getTransaction

public abstract javax.transaction.Transaction getTransaction()

Returns the transaction associated with this runtime context.

If the runtime context is associated with any open transaction, the transaction will be returned. When the runtime context is associated with the current thread, this method will return the same transaction as TransactionManager#getTransaction.

Returns:

The transaction, or null

getSubject

public abstract javax.security.auth.Subject getSubject()

Returns the security subject associated with this runtime context.

This security subject is used for authentication and authorization.

Returns:

The security subject, or null

cleanup

public abstract void cleanup()

Cleanup the runtime context and discard all resources associated with it.

This method is called when it has been determined that this runtime context will no longer be used.

newRuntimeContext

public static RuntimeContext newRuntimeContext(javax.naming.Context envContext,
                                               javax.security.auth.Subject subject)
                                        throws javax.naming.NamingException

Creates and returns a new runtime context.

If a JNDI context is provided, it's bindings will be used for the JNDI environment naming context available when this context is associated with the current thread.

If not JNDI context is provided, a new context will be created. The context can be populated with objects by calling getEnvContext() on the new runtime context.

If a security subject is provided, it will be used for authentication and authorization when this context is associated with the current thread.

The runtime context is not associated with any thread. To associate the runtime context with a thread, use setRuntimeContext.

Parameters:

envContext - The JNDI environment context to use, or null

subject - The security subject, or null

Throws:

javax.naming.NamingException - The context is not a valid context

newRuntimeContext

public static RuntimeContext newRuntimeContext()

Creates and returns a new runtime context.

A new context will be created. The context can be populated with objects by calling getEnvContext() on the new runtime context.

The runtime context is not associated with any thread. To associate the runtime context with a thread, use setRuntimeContext.

getRuntimeContext

public static RuntimeContext getRuntimeContext()

Returns the runtime context associated with the current thread.

This method returns the last runtime context associated with the current thread by calling setRuntimeContext.

If the thread was not previously associated with any runtime context, a new runtime context is created and associated with the thread. This method never returns null.

Returns:

The runtime context

setRuntimeContext

public static void setRuntimeContext(RuntimeContext context)

Associates a runtime context with the current thread.

While in effect, this runtime context will provide the transaction, JNDI environment context, security subject and resources for all operations performed in the current thread.

If the current thread is assocaited with any other runtime context, the association will be suspended until a subsequent call to unsetRuntimeContext().

The runtime context must have previoulsy been created with one of the newRuntimeContext methods listed here.

Parameters:

context - The runtime context to be associated with the current thread

unsetRuntimeContext

public static RuntimeContext unsetRuntimeContext()

Dissociates the runtime context from the current thread,

This method dissociates the last current runtime associated using setRuntimeContext, and restores a previous runtime context.

The dissociated runtime context is returned. Call cleanup(), if the dissociated runtime context will not be used in the future.

Returns:

The previous runtime context, or null

cleanup

public static void cleanup(java.lang.Thread thread)

Called to destroy all association with a thread. This method is called when the thread is no longer used.

Parameters:

thread - The thread

newEnvContext

public static javax.naming.Context newEnvContext()

Creates and returns an new JNDI context.

The JNDI context can be populated with objects and passed to a newly created runtime context, to be used for the JNDI environment naming context.

Returns:

A new JNDI context