Package jmri.script

Class JmriScriptEngineManager

java.lang.Object
jmri.script.JmriScriptEngineManager
All Implemented Interfaces:
InstanceManagerAutoDefault
public final class JmriScriptEngineManager extends Object implements InstanceManagerAutoDefault
Provide a manager for ScriptEngines. The following methods are the only mechanisms for evaluating a Python script that respect the jython.exec property in the python.properties file: Evaluating a script using getEngine*(java.lang.String).eval(...) methods will not respect the jython.exec property, although all methods will respect all other properties of that file.

  • Field Details

  • Constructor Details

  • Method Details

    • getDefault

      @Nonnull public static JmriScriptEngineManager getDefault()
      Get the default instance of a JmriScriptEngineManager. Using the default instance ensures that a script retains the context of the prior script.
      Returns:
      the default JmriScriptEngineManager

    • getManager

      @Nonnull public ScriptEngineManager getManager()
      Get the Java ScriptEngineManager that this object contains.
      Returns:
      the ScriptEngineManager

    • getEngineByExtension

      @Nonnull public ScriptEngine getEngineByExtension(String extension) throws ScriptException
      Given a file extension, get the ScriptEngine registered to handle that extension.
      Parameters:
      extension - a file extension
      Returns:
      a ScriptEngine or null
      Throws:
      ScriptException - if unable to get a matching ScriptEngine

    • getEngineByMimeType

      @Nonnull public ScriptEngine getEngineByMimeType(String mimeType) throws ScriptException
      Given a mime type, get the ScriptEngine registered to handle that mime type.
      Parameters:
      mimeType - a mimeType for a script
      Returns:
      a ScriptEngine or null
      Throws:
      ScriptException - if unable to get a matching ScriptEngine

    • getEngineByName

      @Nonnull public ScriptEngine getEngineByName(String shortName) throws ScriptException
      Given a short name, get the ScriptEngine registered by that name.
      Parameters:
      shortName - the short name for the ScriptEngine
      Returns:
      a ScriptEngine or null
      Throws:
      ScriptException - if unable to get a matching ScriptEngine

    • getEngine

      @CheckForNull public ScriptEngine getEngine(@CheckForNull String name)
      Get a ScriptEngine by its name(s), mime type, or supported extensions.
      Parameters:
      name - the complete name, mime type, or extension for the ScriptEngine
      Returns:
      a ScriptEngine or null if matching engine not found

    • eval

      public Object eval(String script, ScriptEngine engine) throws ScriptException
      Evaluate a script using the given ScriptEngine.
      Parameters:
      script - The script.
      engine - The script engine.
      Returns:
      The results of evaluating the script.
      Throws:
      ScriptException - if there is an error in the script.

    • eval

      public Object eval(File file) throws ScriptException, IOException
      Evaluate a script contained in a file. Uses the extension of the file to determine which ScriptEngine to use.
      Parameters:
      file - the script file to evaluate.
      Returns:
      the results of the evaluation.
      Throws:
      ScriptException - if there is an error evaluating the script.
      FileNotFoundException - if the script file cannot be found.
      IOException - if the script file cannot be read.

    • eval

      public Object eval(File file, Bindings bindings) throws ScriptException, IOException
      Evaluate a script contained in a file given a set of Bindings to add to the script's context. Uses the extension of the file to determine which ScriptEngine to use.
      Parameters:
      file - the script file to evaluate.
      bindings - script bindings to evaluate against.
      Returns:
      the results of the evaluation.
      Throws:
      ScriptException - if there is an error evaluating the script.
      FileNotFoundException - if the script file cannot be found.
      IOException - if the script file cannot be read.

    • eval

      public Object eval(File file, ScriptContext context) throws ScriptException, IOException
      Evaluate a script contained in a file given a special context for the script. Uses the extension of the file to determine which ScriptEngine to use.
      Parameters:
      file - the script file to evaluate.
      context - script context to evaluate within.
      Returns:
      the results of the evaluation.
      Throws:
      ScriptException - if there is an error evaluating the script.
      FileNotFoundException - if the script file cannot be found.
      IOException - if the script file cannot be read.

    • runScript

      public void runScript(File file)
      Run a script, suppressing common errors. Note that the file needs to have a registered extension, or a NullPointerException will be thrown.

      Note: this will eventually be deprecated in favor of using eval(File) and having callers handle exceptions.

      Parameters:
      file - the script to run.

    • initializeAllEngines

      public void initializeAllEngines()
      Initialize all ScriptEngines. This can be used to prevent the on-demand initialization of a ScriptEngine from causing a pause in JMRI.

    • getDefaultContext

      @Nonnull public ScriptContext getDefaultContext()
      Get the default ScriptContext for all ScriptEngines.
      Returns:
      the default ScriptContext;

    • getFactoryByExtension

      @Nonnull public ScriptEngineFactory getFactoryByExtension(String extension) throws ScriptException
      Given a file extension, get the ScriptEngineFactory registered to handle that extension.
      Parameters:
      extension - a file extension
      Returns:
      a ScriptEngineFactory or null
      Throws:
      ScriptException - if unable to get a matching ScriptEngineFactory

    • getFactoryByMimeType

      @Nonnull public ScriptEngineFactory getFactoryByMimeType(String mimeType) throws ScriptException
      Given a mime type, get the ScriptEngineFactory registered to handle that mime type.
      Parameters:
      mimeType - the script mimeType
      Returns:
      a ScriptEngineFactory or null
      Throws:
      ScriptException - if unable to get a matching ScriptEngineFactory

    • getFactoryByName

      @Nonnull public ScriptEngineFactory getFactoryByName(String shortName) throws ScriptException
      Given a short name, get the ScriptEngineFactory registered by that name.
      Parameters:
      shortName - the short name for the factory
      Returns:
      a ScriptEngineFactory or null
      Throws:
      ScriptException - if unable to get a matching ScriptEngineFactory

    • getFactory

      @CheckForNull public ScriptEngineFactory getFactory(@CheckForNull String name)
      Get a ScriptEngineFactory by its name(s), mime types, or supported extensions.
      Parameters:
      name - the complete name, mime type, or extension for a factory
      Returns:
      a ScriptEngineFactory or null

    • initializePython

      public void initializePython()
      The Python ScriptEngine can be configured using a custom python.properties file and will run jmri_defaults.py if found in the user's configuration profile or settings directory. See python.properties in the JMRI installation directory for details of how to configure the Python ScriptEngine.

    • newPythonInterpreter

      public org.python.util.PythonInterpreter newPythonInterpreter()
      Create a new PythonInterpreter with the default bindings.
      Returns:
      a new interpreter

    • getPythonInterpreter

      @CheckForNull org.python.util.PythonInterpreter getPythonInterpreter()

    • fileForLanguage

      @Nonnull public static String fileForLanguage(@Nonnull String engineName, @Nonnull String languageName)
      Service routine to make engine-type strings to a human-readable prompt
      Parameters:
      engineName - Self-provided name of the engine
      languageName - Names of language supported by the engine
      Returns:
      Human readable string, i.e. Jython Files