com.github.adchilds.jython

Class JythonScript

java.lang.Object

com.github.adchilds.jython.JythonScript

public class JythonScript
extends Object

JythonScript provides an easy to use wrapper for executing and/or evaluating Python expressions or scripts for JVM-based languages. JythonScript packages the Jython standalone JAR as part of it's distribution, so no further dependencies should be required. JythonScript operates on a couple of select criteria:

1. A Jython or Python script accessible by the JVM via a String file path, File, or InputStream
2. Optional arguments to be passed to the given script

To use this utility class, you must follow a few strict rules in creating Jython scripts:

• Each script passed to an #evaluate(...) or #execute(...) function, such as evaluate(String, Object...) or execute(String, Object...) MUST be setup as a standard Python main module. This means that the following code must exist:

        if __name__ == '__main__':
            ...
            ...
       
       

• If running an evaluation via any of the #evaluate(...) functions, and expecting a valid result to be returned, you MUST push the resulting value to a local Python variable named 'result', otherwise JythonScript will not be able to locate this value within the Python interpreter.

When consuming arguments passed to a Jython script via the 'Object... args' parameter of an execute or evaluate method, the arguments will be available via Python's sys.argv list. It's important to note that the first argument (index 0 [sys.argv[0]]) is reserved. Therefore, Jython scripts should always access these arguments beginning with the second index of sys.argv (i.e. sys.argv[1]).

JythonScript provides #compile(...) functions that compile the given scripts into PyCode objects. For speed increases at runtime, it's better to pre-compile Jython scripts with these functions, maintain the PyCode objects via an in-memory cache or local variable, and execute or evaluate against the compiled scripts. JythonScript provides the necessary evaluate(PyCode, Object...) and execute(PyCode, Object...) methods to foster these speed increases.

Note: JythonScript does not dictate any other strict code structure. You are free to use any of the features provided by Java, Python and Jython, including, but not limited to:

• OOP
• Python Standard Library
• Java Standard Library
• etc.

For more information, follow the respective links to documentation:

• JythonScript - https://github.com/adchilds/JythonScript
• Python - https://www.python.org
• Jython - http://www.jython.org

Since:

1.0

Author:

Adam Childs

Method Summary

Modifier and Type	Method and Description
static org.python.core.PyCode	compile(File file) Compiles the given Jython script into a PyCode object.
static org.python.core.PyCode	compile(String filePath) Compiles the Jython script at the given filePath into a PyCode object.
static org.python.core.PyCode	compile(URL fileUrl) Compiles the Jython script at the given fileUrl into a PyCode object.
static org.python.core.PyCode	compileString(String script) Compiles the given Jython script into a PyCode object.
static Object	evaluate(File scriptFile, Object... args) Evaluates the given Jython script, returning the result as its equivalent Java type.
static Object	evaluate(InputStream inputStream, Object... args) Evaluates the given Jython script, returning the result as its equivalent Java type.
static Object	evaluate(org.python.core.PyCode pyCode, Object... args) Evaluates the given Jython script, returning the result as it's equivalent Java type.
static Object	evaluate(String scriptPath, Object... args) Evaluates the Jython script at the given scriptPath, returning the result as its equivalent Java type.
static Object	evaluate(URL scriptUrl, Object... args) Evaluates the Jython script at the given scriptUrl, returning the result as its equivalent Java type.
static void	execute(File scriptFile, Object... args) Executes the given Jython script with optional arguments passed to the script at runtime.
static void	execute(InputStream inputStream, Object... args) Executes the given Jython script with optional arguments passed to the script at runtime.
static void	execute(org.python.core.PyCode pyCode, Object... args) Executes the given Jython script with optional arguments passed to the script at runtime.
static void	execute(String scriptPath, Object... args) Executes the Jython script at the given scriptPath with optional arguments passed to the script at runtime.
static void	execute(URL scriptUrl, Object... args) Executes the Jython script at the given scriptUrl with optional arguments passed to the script at runtime.

Methods inherited from class java.lang.Object

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

Method Detail

compile

public static org.python.core.PyCode compile(String filePath)
                                      throws JythonScriptException

Compiles the Jython script at the given filePath into a PyCode object.

Parameters:

filePath - the absolute path of the Jython file to compile

Returns:

a compiled Jython script

Throws:

JythonScriptException - when the given file path is empty or null

Since:

1.0

compile

public static org.python.core.PyCode compile(URL fileUrl)
                                      throws JythonScriptException

Compiles the Jython script at the given fileUrl into a PyCode object.

Parameters:

fileUrl - the URL to a Jython file to compile

Returns:

a compile Jython script

Throws:

JythonScriptException - when the given URL is empty, null, or not a valid path

Since:

2.0

compile

public static org.python.core.PyCode compile(File file)
                                      throws JythonScriptException

Compiles the given Jython script into a PyCode object.

Parameters:

file - the Jython file to compile

Returns:

a compiled Jython script

Throws:

JythonScriptException - when the given file is null or is not a file (i.e. a directory)

Since:

1.0

compileString

public static org.python.core.PyCode compileString(String script)
                                            throws JythonScriptException

Compiles the given Jython script into a PyCode object.

Parameters:

script - the Jython script to compile (this should be actual Jython code represented as a String)

Returns:

a compiled Jython script

Throws:

JythonScriptException - when the given script is null or empty

Since:

2.0

evaluate

public static Object evaluate(String scriptPath,
                              Object... args)
                       throws JythonScriptException

Evaluates the Jython script at the given scriptPath, returning the result as its equivalent Java type. Accepts optional arguments to be passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

scriptPath - the fully qualified path of the Jython script to execute

args - arguments to be passed to the script

Returns:

the result from executing the given script

Throws:

JythonScriptException - when the given file path is null, a directory, or cannot be found

Since:

1.0

evaluate

public static Object evaluate(URL scriptUrl,
                              Object... args)
                       throws JythonScriptException

Evaluates the Jython script at the given scriptUrl, returning the result as its equivalent Java type. Accepts optional arguments to be passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

scriptUrl - the URL to a Jython script to execute

args - arguments to be passed to the script

Returns:

the result from executing the given script

Throws:

JythonScriptException - when the given script is null, a directory, or cannot be found

Since:

2.0

evaluate

public static Object evaluate(File scriptFile,
                              Object... args)
                       throws JythonScriptException

Evaluates the given Jython script, returning the result as its equivalent Java type. Accepts optional arguments to be passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

scriptFile - the Jython script to execute

args - arguments to be passed to the script

Returns:

the result from executing the given script

Throws:

JythonScriptException - when the given file is null, a directory, or cannot be found

Since:

1.0

evaluate

public static Object evaluate(InputStream inputStream,
                              Object... args)
                       throws JythonScriptException

Evaluates the given Jython script, returning the result as its equivalent Java type. Accepts optional arguments to be passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

inputStream - the InputStream that represents the Jython script to be executed

args - arguments to be passed to the script

Returns:

the result from executing the given script

Throws:

JythonScriptException - when a script execution error occurs or when a local Python variable named 'result' is not found

Since:

1.0

evaluate

public static Object evaluate(org.python.core.PyCode pyCode,
                              Object... args)
                       throws JythonScriptException

Evaluates the given Jython script, returning the result as it's equivalent Java type. Accepts optional arguments to be passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

pyCode - the compiled Jython script to evaluate

args - arguments to be passed to the script

Returns:

the result from executing the given script

Throws:

JythonScriptException - when a script execution error occurs or when a local Python variable named 'result' is not found

Since:

1.0

execute

public static void execute(String scriptPath,
                           Object... args)
                    throws JythonScriptException

Executes the Jython script at the given scriptPath with optional arguments passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

scriptPath - the fully qualified path of the Jython script to execute

args - arguments to be passed to the script

Throws:

JythonScriptException - when the given file path is null, a directory, or cannot be found

Since:

1.0

execute

public static void execute(URL scriptUrl,
                           Object... args)
                    throws JythonScriptException

Executes the Jython script at the given scriptUrl with optional arguments passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

scriptUrl - the URL to a Jython script to execute

args - arguments to be passed to the script

Throws:

JythonScriptException - when the given file is null, a directory, or cannot be found

Since:

2.0

execute

public static void execute(File scriptFile,
                           Object... args)
                    throws JythonScriptException

Executes the given Jython script with optional arguments passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

scriptFile - the Jython script to execute

args - arguments to be passed to the script

Throws:

JythonScriptException - when the given file is null, a directory, or cannot be found

Since:

1.0

execute

public static void execute(InputStream inputStream,
                           Object... args)
                    throws JythonScriptException

Executes the given Jython script with optional arguments passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

inputStream - the InputStream that represents the Jython script to be executed

args - arguments to be passed to the script

Throws:

JythonScriptException - when the given inputstream is null or a script execution error occurs

Since:

1.0

execute

public static void execute(org.python.core.PyCode pyCode,
                           Object... args)
                    throws JythonScriptException

Executes the given Jython script with optional arguments passed to the script at runtime. args should be interpreted as 'sys.argv' arguments in the given script. Note that the arguments passed in here will begin at the first index in a Jython scripts sys.argv list.

Parameters:

pyCode - the compiled Jython script to evaluate

args - arguments to be passed to the script

Throws:

JythonScriptException - when the given PyCode is null or a script execution error occurs

Since:

1.0