org.azyva.dragom.execcontext

Interface ExecContext

public interface ExecContext

Provides contextual information and behavior during the execution of tools.

Classes generally use ExecContextHolder from dragom-core to retrieve an ExecContext when needed.

The initialization phase of tools generally use ExecContextFactory to instantiate or retrieve existing ExecContext's that will be set within ExecContextHolder and used throughout the tool execution. DefaultExecContextFactory from dragom-core is an implementation of ExecContextFactory.

Although it is not entirely explicit, ExecContext's conceptually manage 3 information scopes:

• Global: Information that is considered constant among workspaces and tool invocations. Global information essentially includes the Model;
• Workspace: Information that is specific to a workspace. Such information can be changed during the execution of tools and is expected to be persisted within the workspace. Workspace information includes the non-transient properties (getProperty(java.lang.String), etc.). It also includes any information which ExecContextPlugin's decide to manage with workspace scope;
• Tool: Information that is local to a tool execution. Tools and plugins that execute within the context of a tool can manage such information which is expected to be released when the tool execution ends. Tool information includes the transient data (getTransientData(java.lang.String), etc.). It also includes any information which ExecContextPlugin's decide to manage with tool scope.

The distinction between the various scopes can be somewhat blurry, especially if each tool execution is performed in its own JVM, which is often the case. In such a case, it can be argued to some extent that all information is transient given that when the JVM terminates, all information vanishes with it, at least from memory. But it is possible to configure multiple tool executions to share a JVM instance which would behave as a background service with which a front- end would interact to start tool executions (NaigGun can be useful in that regard). In such cases the distinction between scopes become clearer. In particular, it is more obvious that care must be taken to distinguish between workspace and tool scopes as even if the JVM is not terminated at the end of a tool execution, another tool execution must not see the tool-scope properties. Such sharing of a single JVM instance can be done to improve tool initialization time (JVM startup, Model initialization, etc.).

ExecContext provide access to ExecContextPlugin's (getExecContextPlugin(java.lang.Class<ExecContextPluginInterface>)). During tool execution, the tool and {org.azyva.dragom.model.plugin.NodePlugin} collaborate to provide the required Functionality. But in doing so they need to have access to the various aspects of the ExecContext which, apart from general workspace properties, are provided by plugins, such as WorkspacePlugin for workspace directories and UserInteractionCallbackPlugin) for user interaction.

A relation between ExecContextPlugin's and information scope exists. See ToolLifeCycleExecContext for more information.

ExecContextPlugin's can access workspace properties (getProperty, etc.) and transient data (getTransientData, etc.), and there is no explicit and enforced relation between an ExecContextPlugin scope and the scope of information it accessed. However, it is the plugin implementation's responsibility to remain coherent. For example an ExecContextPlugin bound to the workspace can access transient data during its execution, but this data should not affect its internal state. Otherwise, a tool execution could unpredictably affect the behavior of another tool execution.

Generally a workspace is understood to correspond to a file system directory, and it probably always will be the case. However, ExecContext does not make this assumption. This is up to the ExecContextFactory implementation.

An ExecContext implementation that supports the concept of workspace directory should implement WorkspaceExecContext and its corresponding ExecContextFactory should implement WorkspaceExecContextFactory.

But one important ExecContextPlugin is WorkspacePlugin which does assume that a workspace corresponds to a directory. So WorkspacePlugin implementations will generally make assumptions about ExecContext implementations' support for the concept of workspace directory. Other ExecContextPlugin can also make such assumptions as required.

To indicate that an ExecContext implementation supports the workspace directory concept it should implement WorkspaceExecContext, on top of ExecContext. Similarly, the corresponding ExecContextFactory should implement WorkspaceExecContextFactory.

In such a case where the ExecContext implementation supports the concept of workspace directory, the workspace properties are expected to be stored in a Properties file within the workspace directory.

Workspace properties and transient data are not handled symmetrically. Workspace properties are simple String's since they are meant to be persisted within the workspace. Granted, Object's can also be persisted (if they are serializable), but it was decided to support only String properties for the sake of simplicity and human interaction. However transient data does not need to be persisted and so are general Object's, allowing tools and plugins to store arbitrary data in tool scope.

Author:

David Raymond

Method Summary

Modifier and Type	Method and Description
<ExecContextPluginInterface extends ExecContextPlugin> ExecContextPluginInterface	getExecContextPlugin(Class<ExecContextPluginInterface> classExecContextPluginInterface) Returns an ExecContextPlugin.
String	getInitProperty(String name) Returns an initialization property.
Model	getModel() Returns the Model Model.
String	getName()
String	getProperty(String name) Returns a workspace property.
Set<String>	getSetInitProperty()
Set<String>	getSetProperty(String prefix) Returns a Set of all workspace property names having a given prefix.
Object	getTransientData(String name) Returns a transient data.
void	release() If the ExecContext is cached, releases it so that a subsequent request for the same ExecContext (for instance an ExecContext based on the same workspace) will recreate it.
void	removeProperties(String prefix) Removes all properties having a given prefix.
void	removeProperty(String name) Removes a workspace property.
void	setProperty(String name, String value) Sets a workspace property.
void	setTransientData(String name, Object value) Sets a transient data.

Method Detail

getModel

Model getModel()

Returns the Model Model.

The Model is at global scope. During the configuration of the ExecContext during a tool initialization, a shared instance Model can be set (if tool executions share a single JVM instance).

Returns:

See description.

getExecContextPlugin

<ExecContextPluginInterface extends ExecContextPlugin> ExecContextPluginInterface getExecContextPlugin(Class<ExecContextPluginInterface> classExecContextPluginInterface)

Returns an ExecContextPlugin.

ExecContextPlugin's are identified by their (interface) class.

Type Parameters:

ExecContextPluginInterface - Interface of the ExecContextPlugin.

Parameters:

classExecContextPluginInterface - Class of the ExecContextPlugin.

Returns:

ExecContextPlugin. null if not found.

getSetInitProperty

Set<String> getSetInitProperty()

Returns:

Set of all initialization properties.

getInitProperty

String getInitProperty(String name)

Returns an initialization property.

Parameters:

name - Name of the property.

Returns:

Value of the property.

getProperty

String getProperty(String name)

Returns a workspace property.

Parameters:

name - Name of the property.

Returns:

Value of the property.

setProperty

void setProperty(String name,
                 String value)

Sets a workspace property.

Parameters:

name - Name of the property.

value - Value of the property. Can be null, in which case the behavior is expected to be identical to removeProperty(java.lang.String).

getSetProperty

Set<String> getSetProperty(String prefix)

Returns a Set of all workspace property names having a given prefix.

Parameters:

prefix - Prefix of the properties. Can be null in which case all properties are returned.

Returns:

See description.

removeProperty

void removeProperty(String name)

Removes a workspace property.

Parameters:

name - Name of the property.

removeProperties

void removeProperties(String prefix)

Removes all properties having a given prefix.

Parameters:

prefix - Prefix of the properties.

getTransientData

Object getTransientData(String name)

Returns a transient data.

Parameters:

name - Name of the data.

Returns:

Value of the data.

setTransientData

void setTransientData(String name,
                      Object value)

Sets a transient data.

Transient data are generally very specific to and implementation details of the class that sets them. The name of a transient data should therefore be prefixed with the name of the caller class in order to avoid name clashes.

Parameters:

name - Name of the data.

value - Value of the data. Can be null, in which case the data is effectively removed.

getName

String getName()

Returns:

Name given to the ExecContext so that it can be identified by users. Typically if the ExecContext is based on a workspace directory the name could include a reference to that directory.

release

void release()

If the ExecContext is cached, releases it so that a subsequent request for the same ExecContext (for instance an ExecContext based on the same workspace) will recreate it.

This method is not a regular release method that is meant to be called whenever a tool is done with the ExecContext. It is a special method meant to be called in exceptional situations when the user wants to do as if the ExecContext had never been created, such as if data on disk has changed outside of the control of the ExecContext.

If the ExecContext is not cached, this should be a noop operation.