Package 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 Details

  • Constructor Details

    • EnvironmentModule

      public EnvironmentModule()

  • Method Details

    • bootstrap

      public static void bootstrap() throws ExecutionException
      Throws:
      ExecutionException

    • getWrappedVariableName

      public static final String getWrappedVariableName(Object toBeWrapped)

    • getLoadedModules

      public static List<ModuleDefinition> getLoadedModules(IScriptEngine engine)
      Get all loaded modules for a given script engine.
      Parameters:
      engine - engine to parse
      Returns:
      module definitions for all loaded modules (index 0 references the module loaded last)

    • getModuleInstance

      public Object getModuleInstance(ModuleDefinition definition)

    • loadModule

      public final Object loadModule(String moduleIdentifier, @ScriptParameter(defaultValue="false") boolean useCustomNamespace) throws ExecutionException
      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
      Throws:
      ExecutionException - when execution of wrapped module code fails

    • getModule

      public final Object getModule(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 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 List<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)

    • getModuleDefinition

      public ModuleDefinition getModuleDefinition(Object moduleInstance)
      Description copied from interface: IEnvironment
      Retrieve a definition for a given module instance.
      Specified by:
      getModuleDefinition in interface IEnvironment
      Parameters:
      moduleInstance - instance of module to retrieve definition for
      Returns:
      module definition

    • print

      public final void print(@ScriptParameter(defaultValue="") 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

    • formatText

      public String formatText(String format, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg1, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg2, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg3, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg4, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg5, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg6, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg7, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg8, @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object arg9)
      Format a text with format qualifiers. Using parameters you may format numbers and objects according to Formatter rules. Further inline tokens in the form ${identifier} will be replaced by script variables, system properties and environment variables.
      Parameters:
      format - format string
      arg1 - formatter content
      arg2 - formatter content
      arg3 - formatter content
      arg4 - formatter content
      arg5 - formatter content
      arg6 - formatter content
      arg7 - formatter content
      arg8 - formatter content
      arg9 - formatter content
      Returns:
      formatted string

    • printError

      public final void printError(@ScriptParameter(defaultValue="") Object text, @ScriptParameter(defaultValue="false") boolean printOnce)
      Write a message to the error stream of the script engine.
      Parameters:
      text - message to write
      printOnce - If true, the text in parameter will be printed only once and ignored in other calls of this method. If false, it will be printed in all cases.

    • 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 String readInput(@ScriptParameter(defaultValue="true") boolean blocking) throws 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 any 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
      Throws:
      IOException - when reading on the input stream fails

    • wrap

      public Object wrap(Object toBeWrapped, @ScriptParameter(defaultValue="false") boolean useCustomNamespace) throws ExecutionException
      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
      Throws:
      ExecutionException - when execution of wrapped code fails

    • execute

      public final Object execute(Object data) throws ExecutionException
      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
      Throws:
      ExecutionException - when execution of data fails

    • exit

      public final void exit(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") Object value) throws ExitException
      Terminates script execution immediately. Code following this command will not be executed anymore.
      Parameters:
      value - return code
      Throws:
      ExitException - always

    • include

      public final Object include(Object resource) throws ExecutionException
      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:
      resource - name or instance of resource to be included
      Returns:
      result of include operation
      Throws:
      ExecutionException - when included code fails

    • getScriptEngine

      public IScriptEngine getScriptEngine()
      Get the current script engine instance.
      Specified by:
      getScriptEngine in interface IEnvironment
      Returns:
      IScriptEngine instance

    • loadJar

      public boolean loadJar(Object location) throws 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:
      MalformedURLException - invalid URL detected

    • help

      public void help(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null") 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)

    • toInt

      public Integer toInt(Object element)
      Convert input to a Java int.
      Parameters:
      element - element to convert
      Returns:
      converted value

    • toDouble

      public Double toDouble(Object element)
      Convert input to a Java double.
      Parameters:
      element - element to convert
      Returns:
      converted value

    • toString

      public String toString(Object element)
      Convert input to a Java String.
      Parameters:
      element - element to convert
      Returns:
      converted value

    • 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(String methodToken)
      Check if java callbacks are registered for a module method. This method get called on each module function invocation.

      ATTENTION: needed by dynamic script code, do not alter synopsis!

      Parameters:
      methodToken - unique method token
      Returns:
      true when callbacks are registered

    • preMethodCallback

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

    • postMethodCallback

      public void postMethodCallback(String methodToken, Object result)

    • registerMethod

      public String registerMethod(Method method)
      Description copied from interface: IEnvironment
      Register a method in the environment to allow for callbacks.
      Specified by:
      registerMethod in interface IEnvironment
      Parameters:
      method - method to be registered
      Returns:
      unique ID identifying the method