Package jmri.script

Class JmriScriptEngineManager

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String JYTHON  
      (package private) static java.lang.String JYTHON_DEFAULTS  

    • Constructor Summary

      Constructors 
      Constructor Description
      JmriScriptEngineManager()
      Create a JmriScriptEngineManager.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object eval​(java.io.File file)
      Evaluate a script contained in a file.
      java.lang.Object eval​(java.io.File file, javax.script.Bindings bindings)
      Evaluate a script contained in a file given a set of Bindings to add to the script's context.
      java.lang.Object eval​(java.io.File file, javax.script.ScriptContext context)
      Evaluate a script contained in a file given a special context for the script.
      java.lang.Object eval​(java.lang.String script, javax.script.ScriptEngine engine)
      Evaluate a script using the given ScriptEngine.
      static java.lang.String fileForLanguage​(java.lang.String engineName, java.lang.String languageName)
      Service routine to make engine-type strings to a human-readable prompt
      static JmriScriptEngineManager getDefault()
      Get the default instance of a JmriScriptEngineManager.
      javax.script.ScriptContext getDefaultContext()
      Get the default ScriptContext for all ScriptEngines.
      javax.script.ScriptEngine getEngine​(java.lang.String name)
      Get a ScriptEngine by its name(s), mime type, or supported extensions.
      javax.script.ScriptEngine getEngineByExtension​(java.lang.String extension)
      Given a file extension, get the ScriptEngine registered to handle that extension.
      javax.script.ScriptEngine getEngineByMimeType​(java.lang.String mimeType)
      Given a mime type, get the ScriptEngine registered to handle that mime type.
      javax.script.ScriptEngine getEngineByName​(java.lang.String shortName)
      Given a short name, get the ScriptEngine registered by that name.
      javax.script.ScriptEngineFactory getFactory​(java.lang.String name)
      Get a ScriptEngineFactory by its name(s), mime types, or supported extensions.
      javax.script.ScriptEngineFactory getFactoryByExtension​(java.lang.String extension)
      Given a file extension, get the ScriptEngineFactory registered to handle that extension.
      javax.script.ScriptEngineFactory getFactoryByMimeType​(java.lang.String mimeType)
      Given a mime type, get the ScriptEngineFactory registered to handle that mime type.
      javax.script.ScriptEngineFactory getFactoryByName​(java.lang.String shortName)
      Given a short name, get the ScriptEngineFactory registered by that name.
      javax.script.ScriptEngineManager getManager()
      Get the Java ScriptEngineManager that this object contains.
      (package private) org.python.util.PythonInterpreter getPythonInterpreter()  
      void initializeAllEngines()
      Initialize all ScriptEngines.
      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.
      org.python.util.PythonInterpreter newPythonInterpreter()
      Create a new PythonInterpreter with the default bindings.
      void runScript​(java.io.File file)
      Run a script, suppressing common errors.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • JmriScriptEngineManager

        public JmriScriptEngineManager()
        Create a JmriScriptEngineManager. In most cases, it is preferable to use getDefault() to get existing ScriptEngine instances.

    • Method Detail

      • 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 javax.script.ScriptEngineManager getManager()
        Get the Java ScriptEngineManager that this object contains.
        Returns:
        the ScriptEngineManager

      • getEngineByExtension

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

      • getEngineByMimeType

        @Nonnull
public javax.script.ScriptEngine getEngineByMimeType​(java.lang.String mimeType)
                                              throws javax.script.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:
        javax.script.ScriptException - if unable to get a matching ScriptEngine

      • getEngineByName

        @Nonnull
public javax.script.ScriptEngine getEngineByName​(java.lang.String shortName)
                                          throws javax.script.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:
        javax.script.ScriptException - if unable to get a matching ScriptEngine

      • getEngine

        @CheckForNull
public javax.script.ScriptEngine getEngine​(@CheckForNull
                                           java.lang.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 java.lang.Object eval​(java.lang.String script,
                             javax.script.ScriptEngine engine)
                      throws javax.script.ScriptException
        Evaluate a script using the given ScriptEngine.
        Parameters:
        script - The script.
        engine - The script engine.
        Returns:
        The results of evaluating the script.
        Throws:
        javax.script.ScriptException - if there is an error in the script.

      • eval

        public java.lang.Object eval​(java.io.File file)
                      throws javax.script.ScriptException,
                             java.io.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:
        javax.script.ScriptException - if there is an error evaluating the script.
        java.io.FileNotFoundException - if the script file cannot be found.
        java.io.IOException - if the script file cannot be read.

      • eval

        public java.lang.Object eval​(java.io.File file,
                             javax.script.Bindings bindings)
                      throws javax.script.ScriptException,
                             java.io.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:
        javax.script.ScriptException - if there is an error evaluating the script.
        java.io.FileNotFoundException - if the script file cannot be found.
        java.io.IOException - if the script file cannot be read.

      • eval

        public java.lang.Object eval​(java.io.File file,
                             javax.script.ScriptContext context)
                      throws javax.script.ScriptException,
                             java.io.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:
        javax.script.ScriptException - if there is an error evaluating the script.
        java.io.FileNotFoundException - if the script file cannot be found.
        java.io.IOException - if the script file cannot be read.

      • runScript

        public void runScript​(java.io.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 javax.script.ScriptContext getDefaultContext()
        Get the default ScriptContext for all ScriptEngines.
        Returns:
        the default ScriptContext;

      • getFactoryByExtension

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

      • getFactoryByMimeType

        @Nonnull
public javax.script.ScriptEngineFactory getFactoryByMimeType​(java.lang.String mimeType)
                                                      throws javax.script.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:
        javax.script.ScriptException - if unable to get a matching ScriptEngineFactory

      • getFactoryByName

        @Nonnull
public javax.script.ScriptEngineFactory getFactoryByName​(java.lang.String shortName)
                                                  throws javax.script.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:
        javax.script.ScriptException - if unable to get a matching ScriptEngineFactory

      • getFactory

        @CheckForNull
public javax.script.ScriptEngineFactory getFactory​(@CheckForNull
                                                   java.lang.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

      • fileForLanguage

        @Nonnull
public static java.lang.String fileForLanguage​(@Nonnull
                                               java.lang.String engineName,
                                               @Nonnull
                                               java.lang.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