org.azyva.dragom.execcontext.support

Class ExecContextHolder

java.lang.Object

org.azyva.dragom.execcontext.support.ExecContextHolder

public class ExecContextHolder
extends Object

Holds and provides access to the ExecContext during the execution of tools.

In Java global variables must be defined within a class. That is what we need here as we want the tools to have access to the ExecContext globally. An alternative would have been to introduce an ExecContext parameter in many if not all methods so that it is available everywhere. But this would have been cumbersome.

Dragom tools are meant to be single-threaded, but thread-safe, meaning that multiple independent instances of such tools should be allowed to execute simultaneously within a single JVM if so desired (within a NaigGun server for example). Therefore, the ExecContext is held in thread-local storage instead of in a truly global static variable. If a tool is multi-threaded, it is its responsibility to copy the ExecContext from one thread to the other using setSecondaryThread(org.azyva.dragom.execcontext.ExecContext).

This class is not meant to be swappable. Tools refer directly to it. It is the responsibility of the initialization phase of tools to set the desired ExecContext instance within this class using setAndStartTool(org.azyva.dragom.execcontext.ExecContext, java.util.Properties). Thereafter during the execution of tools only the method get is expected to be used to obtain the ambient ExecContext.

setAndStartTool registers the fact that the ExecContext is being used by a tool and if the same ExecContext is already being used by a tool (another tool instance in another thread) an exception is raised.

When a tool finishes using an ExecContext, endToolAndUnset() must therefore be called to register the fact that it (the current ExecContext stored in thread-local storage) is not being used anymore. A try/finally construct is generally required for that purpose.

Author:

David Raymond

Constructor Summary

Constructors

Constructor and Description
ExecContextHolder()

Method Summary

Modifier and Type	Method and Description
static void	endToolAndUnset() Ends tool execution and unsets the ExecContext from thread-local storage.
static void	forceUnset(org.azyva.dragom.execcontext.ExecContext execContext) Force-unsets an ExecContext.
static org.azyva.dragom.execcontext.ExecContext	get() Returns the ExecContext stored in thread-local storage.
static void	setAndStartTool(org.azyva.dragom.execcontext.ExecContext execContext, Properties propertiesInit) Sets the ExecContext in thread-local storage and starts tool execution.
static org.azyva.dragom.execcontext.ExecContext	setDummy(org.azyva.dragom.model.Model model) Sets a dummy ExecContext in thread-local storage.
static void	setSecondaryThread(org.azyva.dragom.execcontext.ExecContext execContext) Sets the ExecContext in thread-local storage for a secondary thread for an already started tool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExecContextHolder

public ExecContextHolder()

Method Detail

setAndStartTool

public static void setAndStartTool(org.azyva.dragom.execcontext.ExecContext execContext,
                                   Properties propertiesInit)

Sets the ExecContext in thread-local storage and starts tool execution.

To be called during the initialization phase of a tool.

If the ExecContext implementation implements ToolLifeCycleExecContext ToolLifeCycleExecContext.startTool(java.util.Properties) is called.

Parameters:

execContext - ExecContext.

propertiesInit - Initialization properties specific to the tool.

setDummy

public static org.azyva.dragom.execcontext.ExecContext setDummy(org.azyva.dragom.model.Model model)

Sets a dummy ExecContext in thread-local storage.

Useful in non-tool contexts where an ExecContext is not really required. But since many methods rely on an ExecContext being available, a dummy non-null ExecContext prevents NullPointerException's.

Since a Model is an integral part of the ExecContext, it is specified here as an argument to be associated with the ExecContext.

Parameters:

model - Model.

Returns:

Dummy ExecContext.

setSecondaryThread

public static void setSecondaryThread(org.azyva.dragom.execcontext.ExecContext execContext)

Sets the ExecContext in thread-local storage for a secondary thread for an already started tool.

To be called when a tool is multi-threaded so that each thread gets its own ExecContext, without having ToolLifeCycleExecContext.startTool(java.util.Properties) called.

Parameters:

execContext - ExecContext. Must be one for which setAndStartTool(org.azyva.dragom.execcontext.ExecContext, java.util.Properties) has already been called.

endToolAndUnset

public static void endToolAndUnset()

Ends tool execution and unsets the ExecContext from thread-local storage.

The ExecContext is the one that was set using setAndStartTool(org.azyva.dragom.execcontext.ExecContext, java.util.Properties).

To be called during the termination phase of a tool. Should be called on the same thread as setAndStartTool.

If the ExecContext implementation implements ToolLifeCycleExecContext ToolLifeCycleExecContext.endTool() is called.

forceUnset

public static void forceUnset(org.azyva.dragom.execcontext.ExecContext execContext)

Force-unsets an ExecContext. Used as a last resort after a tool ends abnormally, leaving the ExecContext in the used state.

The ExecContext cannot be obtained with get() since this method is generally not called on the same thread as the one that previously set the ExecContext without releasing it.

Parameters:

execContext - ExecContext.

get

public static org.azyva.dragom.execcontext.ExecContext get()

Returns the ExecContext stored in thread-local storage.

To be called during the execution of tools. Essentially any class (model, plugin, etc.) can call this method to have access to the ExecContext.

Returns:

See description.