Package jmri.script
Class JmriScriptEngineManager
- java.lang.Object
-
- jmri.script.JmriScriptEngineManager
-
- All Implemented Interfaces:
InstanceManagerAutoDefault
public final class JmriScriptEngineManager extends java.lang.Object implements InstanceManagerAutoDefault
Provide a manager forScriptEngine
s. The following methods are the only mechanisms for evaluating a Python script that respect thejython.exec
property in the python.properties file:eval(java.io.File)
eval(java.io.File, javax.script.Bindings)
eval(java.io.File, javax.script.ScriptContext)
eval(java.lang.String, javax.script.ScriptEngine)
runScript(java.io.File)
getEngine*(java.lang.String).eval(...)
methods will not respect thejython.exec
property, although all methods will respect all other properties of that file.
-
-
Field Summary
Fields Modifier and Type Field Description static boolean
dontWarnJavaScript
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 ofBindings
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 promptstatic JmriScriptEngineManager
getDefault()
Get the default instance of a JmriScriptEngineManager.javax.script.ScriptContext
getDefaultContext()
Get the defaultScriptContext
for allScriptEngine
s.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.
-
-
-
Field Detail
-
JYTHON_DEFAULTS
static final java.lang.String JYTHON_DEFAULTS
- See Also:
- Constant Field Values
-
JYTHON
public static final java.lang.String JYTHON
- See Also:
- Constant Field Values
-
dontWarnJavaScript
public static boolean dontWarnJavaScript
-
-
Constructor Detail
-
JmriScriptEngineManager
public JmriScriptEngineManager()
Create a JmriScriptEngineManager. In most cases, it is preferable to usegetDefault()
to get existingScriptEngine
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 ofBindings
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 defaultScriptContext
for allScriptEngine
s.- 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
-
getPythonInterpreter
@CheckForNull org.python.util.PythonInterpreter getPythonInterpreter()
-
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 enginelanguageName
- Names of language supported by the engine- Returns:
- Human readable string, i.e. Jython Files
-
-