org.eclipse.ease.modules

## Class EnvironmentModule

- java.lang.Object
- - org.eclipse.ease.modules.AbstractScriptModule
  - - org.eclipse.ease.modules.EnvironmentModule

All Implemented Interfaces:
  IEnvironment, IScriptModule

    public class EnvironmentModule
    extends AbstractScriptModule
    implements IEnvironment

The Environment provides base functions for all script interpreters. It is automatically loaded by any interpreter upon startup.

### Field Summary

Fields
`static java.lang.String` `EASE_CODE_PREFIX`
`static java.lang.String` `MODULE_NAME`
`static java.lang.String` `MODULE_PREFIX`

### Constructor Summary

Constructors
Constructor and Description
`EnvironmentModule()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addModuleCallback(IModuleCallbackProvider callbackProvider)` Register a callback provider for module functions.
`void` `addModuleListener(IModuleListener listener)`
`static void` `bootstrap()`
`java.lang.Object` `execute(java.lang.Object data)` Execute script code.
`void` `exit(java.lang.Object value)` Terminates script execution immediately.
`java.lang.Object` `getModule(java.lang.String name)` Resolves a loaded module and returns the Java instance.
`<T,U extends java.lang.Class<T>> T` `getModule(U clazz)` Resolves a loaded module by its class.
`java.lang.Object` `getModuleInstance(ModuleDefinition definition)`
`java.util.List<java.lang.Object>` `getModules()` Retrieve a list of loaded modules.
`IScriptEngine` `getScriptEngine()` Get the current script engine instance.
`static java.lang.String` `getWrappedVariableName(java.lang.Object toBeWrapped)`
`boolean` `hasMethodCallback(java.lang.String methodToken)`
`void` `help(java.lang.String topic)` Open help page on addressed topic.
`java.lang.Object` `include(java.lang.String filename)` Include and execute a script file.
`boolean` `loadJar(java.lang.Object location)` Add a jar file to the classpath.
`java.lang.Object` `loadModule(java.lang.String moduleIdentifier, boolean useCustomNamespace)` Load a module.
`void` `postMethodCallback(java.lang.String methodToken, java.lang.Object result)`
`void` `preMethodCallback(java.lang.String methodToken, java.lang.Object... parameters)`
`void` `print(java.lang.Object text, boolean lineFeed)` Write a message to the output stream of the script engine.
`void` `printError(java.lang.Object text)` Write a message to the error stream of the script engine.
`java.lang.String` `readInput(boolean blocking)` Read a single line of data from the default input stream of the script engine.
`java.lang.String` `registerMethod(java.lang.reflect.Method method)`
`void` `removeModuleListener(IModuleListener listener)`
`java.lang.Object` `wrap(java.lang.Object toBeWrapped, boolean useCustomNamespace)` Wrap a java instance.

### Methods inherited from class org.eclipse.ease.modules.AbstractScriptModule

`initialize`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.eclipse.ease.modules.IEnvironment

`getEnvironment, getEnvironment`

### Field Detail

#### MODULE_NAME

    public static final java.lang.String MODULE_NAME

See Also:
  Constant Field Values

#### EASE_CODE_PREFIX

    public static final java.lang.String EASE_CODE_PREFIX

See Also:
  Constant Field Values

#### MODULE_PREFIX

    public static final java.lang.String MODULE_PREFIX

See Also:
  Constant Field Values

### Constructor Detail

#### EnvironmentModule

    public EnvironmentModule()

### Method Detail

#### bootstrap

    public static void bootstrap()

#### getModuleInstance

    public java.lang.Object getModuleInstance(ModuleDefinition definition)

#### loadModule

    public final java.lang.Object loadModule(java.lang.String moduleIdentifier,
                                             @ScriptParameter(defaultValue="false")
                                             boolean useCustomNamespace)

Description copied from interface: `IEnvironment`
Load a module. Loading a module generally enhances the script environment with new functions and variables. If a module was already loaded before, it gets refreshed and moved to the top of the module stack. When a module is loaded, all its dependencies are loaded too. So loading one module might change the whole module stack.

When not using a custom namespace all variables and functions are loaded to the global namespace, possibly overriding existing functions. In such cases the Java module instance is returned. When useCustomNamespace is used a dynamic script object is created and returned.In such cases the global namespace is not changed. The namespace behavior is also used for loading dependencies.

Specified by:
  `loadModule` in interface `IEnvironment`
Parameters:
  `moduleIdentifier` - name of module to load
  `useCustomNamespace` - set to `true` if functions and constants should not be stored to the global namespace but to a custom object
Returns:
  loaded module instance

#### getModule

    public final java.lang.Object getModule(java.lang.String name)

Resolves a loaded module and returns the Java instance. Will only query previously loaded modules.

Specified by:
  `getModule` in interface `IEnvironment`
Parameters:
  `name` - name of the module to resolve
Returns:
  resolved module instance or `null`

#### getModule

    public <T,U extends java.lang.Class<T>> T getModule(U clazz)

Resolves a loaded module by its class.

Specified by:
  `getModule` in interface `IEnvironment`
Parameters:
  `clazz` - module class to look resolve
Returns:
  resolved module instance or `null`

#### getModules

    public java.util.List<java.lang.Object> getModules()

Description copied from interface: `IEnvironment`
Retrieve a list of loaded modules. The returned list is read only.

Specified by:
  `getModules` in interface `IEnvironment`
Returns:
  list of modules (might be empty)

#### print

    public final void print(@ScriptParameter(defaultValue="")
                            java.lang.Object text,
                            @ScriptParameter(defaultValue="true")
                            boolean lineFeed)

Write a message to the output stream of the script engine.

Specified by:
  `print` in interface `IEnvironment`
Parameters:
  `text` - message to write
  `lineFeed` - `true` to add a line feed after the text

#### printError

    public final void printError(@ScriptParameter(defaultValue="")
                                 java.lang.Object text)

Write a message to the error stream of the script engine.

Parameters:
  `text` - message to write

#### addModuleListener

    public void addModuleListener(IModuleListener listener)

Specified by:
  `addModuleListener` in interface `IEnvironment`

#### removeModuleListener

    public void removeModuleListener(IModuleListener listener)

Specified by:
  `removeModuleListener` in interface `IEnvironment`

#### readInput

    public java.lang.String readInput(@ScriptParameter(defaultValue="true")
                                      boolean blocking)
                               throws java.io.IOException

Read a single line of data from the default input stream of the script engine. Depending on the blocking parameter this method will wait for user input or return immediately with available data.

Parameters:
  `blocking` - `true` results in a blocking call until data is available, `false` returns in any case
Returns:
  string data from input stream or `null`
Throws:
  `java.io.IOException` - when reading on the input stream fails

#### wrap

    public java.lang.Object wrap(java.lang.Object toBeWrapped,
                                 @ScriptParameter(defaultValue="false")
                                 boolean useCustomNamespace)

Description copied from interface: `IEnvironment`
Wrap a java instance. Will create accessors in the target language for methods and constants defined by the java instance toBeWrapped. If the instance contains annotations of type `WrapToScript` only these will be wrapped. If no annotation can be found, all public methods/constants will be wrapped. As some target languages might not support method overloading this might result in some methods not wrapped correctly.

Specified by:
  `wrap` in interface `IEnvironment`
Parameters:
  `toBeWrapped` - instance to be wrapped
  `useCustomNamespace` - set to `true` if functions and constants should not be stored to the global namespace but to the return value only
Returns:
  wrapped object instance or java class when put to global namespace

#### getWrappedVariableName

    public static final java.lang.String getWrappedVariableName(java.lang.Object toBeWrapped)

#### execute

    public final java.lang.Object execute(java.lang.Object data)

Execute script code. This method executes script code directly in the running interpreter. Execution is done in the same thread as the caller thread.

Parameters:
  `data` - code to be interpreted
Returns:
  result of code execution

#### exit

    public final void exit(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                           java.lang.Object value)

Terminates script execution immediately. Code following this command will not be executed anymore.

Parameters:
  `value` - return code

#### include

    public final java.lang.Object include(java.lang.String filename)

Include and execute a script file. Quite similar to eval(Object) a source file is opened and its content is executed. Multiple sources are available: "workspace://" opens a file relative to the workspace root, "project://" opens a file relative to the current project, "file://" opens a file from the file system. All other types of URIs are supported too (like http:// ...). You may also use absolute and relative paths as defined by your local file system.

Parameters:
  `filename` - name of file to be included
Returns:
  result of include operation
Throws:
  `java.lang.Throwable`

#### getScriptEngine

    public IScriptEngine getScriptEngine()

Get the current script engine instance.

Specified by:
  `getScriptEngine` in interface `IEnvironment`
Overrides:
  `getScriptEngine` in class `AbstractScriptModule`
Returns:
  `IScriptEngine` instance

#### loadJar

    public boolean loadJar(java.lang.Object location)
                    throws java.net.MalformedURLException

Add a jar file to the classpath. Contents of the jar can be accessed right after loading. location can be an URL, a path, a File or an IFile instance. Adding a jar location does not necessary mean that its classes can be accessed. If the source is not accessible, then its classes are not available for scripting, too.

Parameters:
  `location` - `URL`, `Path`, `File` or `IFile`
Returns:
  `true` when input could be converted to a URL
Throws:
  `java.net.MalformedURLException` - invalid URL detected

#### help

    public void help(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                     java.lang.String topic)

Open help page on addressed topic. If the given topic matches a method or field from a loaded module, the definition will be opened. If the topic is unknown, a search in the whole eclipse help will be launched.

Parameters:
  `topic` - help topic to open (typically a function name)

#### addModuleCallback

    public void addModuleCallback(IModuleCallbackProvider callbackProvider)

Description copied from interface: `IEnvironment`
Register a callback provider for module functions.

Specified by:
  `addModuleCallback` in interface `IEnvironment`
Parameters:
  `callbackProvider` - callback provider instance

#### hasMethodCallback

    public boolean hasMethodCallback(java.lang.String methodToken)

#### preMethodCallback

    public void preMethodCallback(java.lang.String methodToken,
                                  java.lang.Object... parameters)

#### postMethodCallback

    public void postMethodCallback(java.lang.String methodToken,
                                   java.lang.Object result)

#### registerMethod

    public java.lang.String registerMethod(java.lang.reflect.Method method)