PropertyName and AttributeName
for more details. Be aware that the per-container properties should be set prior to
get Ruby runtime being instantiated; otherwise, default values are applied to.
ScriptingContainer delays Ruby runtime initialization as much as possible to
improve startup time. When values are put into the ScriptingContainer, or runScriptlet
method gets run the runtime is created internally. However, the default, singleton
local context scope behave slightly different. If a Ruby runtime has been already
instantiated by another ScriptingContainer, application, etc, the same runtime
will be re-used.
Below are examples.
The first Example is a very simple Hello World. After initializing a ScriptingContainer,
a Ruby script, puts "Hello World!", runs and produces "Hello World!."
Example 1:
ScriptingContainer container = new ScriptingContainer();
container.runScriptlet("puts \"Hello World!\"");
Produces:
Hello World!
The second example shows how to share variables between Java and Ruby.
In this example, a local variable "x" is shared. To make this happen,
a local variable behavior should be transient or persistent.
As for JSR223 JRuby engine, set these types using a System property,
org.jruby.embed.localvariable.behavior.
If the local variable behavior is one of transient or persistent,
Ruby's local, instance, global variables and constants are available to share
between Java and Ruby. (A class variable sharing does not work on current version)
Thus, "x" in Java is also "x" in Ruby.
Example 2:
ScriptingContainer container = new ScriptingContainer();
container.put("x", 12345);
container.runScriptlet("puts x.to_s(2)");
Produces:
11000000111001
The third examples shows how to keep local variables across multiple evaluations.
This feature simulates BSF engine for JRuby. In terms of Ruby semantics,
local variables should not survive after the evaluation has completed. Thus,
this behavior is optional, and users need to specify LocalVariableBehavior.PERSISTENT
when the container is instantiated.
Example 3:
ScriptingContainer container = new ScriptingContainer(LocalVariableBehavior.PERSISTENT);
container.runScriptlet("p=9.0");
container.runScriptlet("q = Math.sqrt p");
container.runScriptlet("puts \"square root of #{p} is #{q}\"");
System.out.println("Ruby used values: p = " + container.get("p") + ", q = " + container.get("q"));
Produces:
square root of 9.0 is 3.0
Ruby used values: p = 9.0, q = 3.0
Also, ScriptingContainer provides better i18n support. For example,
Unicode Escape Sequence can be included in Ruby scripts.
In addition, ScriptingContainer supports a parse-once-eval-many-times feature, invoking methods defined by Ruby, and getting an instance of a specified interface that has been implemented by Ruby.
Example 4:
ScriptingContainer container = new ScriptingContainer();
String script =
"def message\n" +
"\"message: #{@message}\"\n" +
"end\n" +
"message";
container.put("@message", "What's up?");
JavaEmbedUtils.EvalUnit unit = container.parse(script);
IRubyObject msg = unit.run(); // a RubyString instance
System.out.println(JavaEmbedUtils.rubyToJava(msg));
container.put("@message", "Fabulous!");
msg = unit.run();
System.out.println(JavaEmbedUtils.rubyToJava(msg));
container.put("@message", "That's the way you are.");
msg = unit.run();
System.out.println(JavaEmbedUtils.rubyToJava(msg));
Produces:
message: What's up?
message: Fabulous!
message: That's the way you are.
See more details at project's
| Modifier and Type | Field and Description |
|---|---|
| private final Map | |
| private final EmbedRubyInterfaceAdapter | |
| private final EmbedRubyObjectAdapter | |
| private final LocalContextProvider | |
| private final EmbedRubyRuntimeAdapter | |
| private final LocalContextScope |
| Access | Constructor and Description |
|---|---|
| public | |
| public | ScriptingContainer(LocalContextScope
a local context type. scope)Constructs a ScriptingContainer with a specified local context type. |
| public | ScriptingContainer(LocalVariableBehavior
a local variable behavior behavior)Constructs a ScriptingContainer with a specified local variable behavior. |
| public | ScriptingContainer(LocalContextScope
a local context type scope, LocalVariableBehavior a local variable behavior behavior)Constructs a ScriptingContainer with a specified local context type and variable behavior. |
| public | ScriptingContainer(LocalContextScope
is one of a local context scope defined by scope, LocalVariableBehavior LocalContextScopeis one of a local variable behavior defined by behavior, boolean LocalVariableBehavioris a switch to do lazy retrieval of variables/constants from
Ruby runtime. Default is true. When this value is true, ScriptingContainer tries to
get as many variables/constants as possible from Ruby runtime. lazy)Constructs a ScriptingContainer with a specified local context scope, local variable behavior and laziness. |
| public | ScriptingContainer(LocalContextScope scope, LocalVariableBehavior behavior, boolean lazy, boolean wrapExceptions)
|
| Modifier and Type | Method and Description |
|---|---|
| public void | |
| public void | |
| protected void | |
| public void | |
| protected void | |
| public Object | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Object... is an array of method arguments args)Executes a method defined in Ruby script. |
| public Object | Returns: an instance of requested Java typeis an instance that will receive this method call
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Block is a block to be executed in this method block, Object... is an array of method arguments args)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Class<T> is the type we want it to convert to returnType)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Object is an method argument singleArg, Class<T> returnType is the type we want it to convert to returnType)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Object[] is an array of method arguments args, Class<T> is the type we want it to convert to returnType)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Object[] is an array of method arguments except a block args, Block is a block to be executed in this method block, Class<T> is the type we want it to convert to returnType)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Class<T> is the type we want it to convert to returnType, EmbedEvalUnit is parsed unit unit)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Object[] is an array of method arguments args, Class<T> is the type we want it to convert to returnType, EmbedEvalUnit is parsed unit unit)Executes a method defined in Ruby script. |
| public <T> T | Returns: is the type we want it to convert tois an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, String is a method name to be called methodName, Object[] is an array of method arguments except a block args, Block is a block to be executed in this method block, Class<T> is the type we want it to convert to returnType, EmbedEvalUnit is parsed unit unit)Executes a method defined in Ruby script. |
| public <T> T | |
| public <T> T | Returns: is the type we want it to convert tois an instance that will receive this method call.
Ruby's self object will be used if no appropriate receiver
is given. receiver, Object[] is an array of method arguments except a block args, Block is a block to be executed in this method block, Class<T> is the type we want it to convert to returnType)
|
| public void | |
| private String | |
| public void | finalize()
Overrides java. Ensure this ScriptingContainer instance is terminated when nobody holds any references to it (and GC wants to reclaim it). |
| public Object | |
| public Object | Returns: a value to which the specified key is mapped, or null if this map contains no mapping for the keya receiver to get the value from receiver, String is a key whose associated value is to be returned key)Returns a value of a specified key in a specified receiver or null if a variable map doesn't have a mapping for the key in a given receiver. |
| public String[] | Returns: an arguments' list.Implements org. Returns a list of argument. |
| public Object | Returns: value is a value associated to the specified keyis the attribute key key)Returns an attribute value associated with the specified key in a attribute map. |
| public Map | Returns: an attribute map specific to the current threadReturns a attribute map in one of |
| private static Map | |
| public ClassLoader | Returns: a class loader object that is currently used.Implements org. Returns a class loader object that is currently used. |
| public boolean | |
| public CompatVersion | getCompatVersion()
Implements org.
Deprecated
|
| public RubyInstanceConfig. | Returns: a compile mode.Implements org. Returns a compile mode currently chosen, which is one of CompileMode.JIT, CompileMode.FORCE, CompileMode.OFF. |
| public String | Returns: a current directory.Implements org. Returns a current directory. |
| public Map | Returns: a map that has environment variables' key-value pairs.Implements org. Returns a map of environment variables. |
| public PrintStream | Returns: an error output stream that Ruby runtime has
Deprecated
As of JRuby 1.5.0, Replaced by getError()
Returns an error output stream that Ruby runtime has. |
| public PrintStream | Returns: output stream for error streamImplements org. Returns an error stream assigned to STDERR and $stderr. |
| public Writer | Returns: an error writer in a attribute mapReturns an error writer set in an attribute map. |
| public String | Returns: a JRuby home directory.Implements org. Returns a JRuby home directory. |
| public InputStream | Returns: an input stream that Ruby runtime has.
Deprecated
As of JRuby 1.5.0, replaced by getInput().
Returns an input stream that Ruby runtime has. |
| public InputStream | Returns: input stream of STDIN and $stdinImplements org. Returns an input stream assigned to STDIN and $stdin. |
| public <T> T | Returns: an instance of a requested interface typeis an instance that implements the interface receiver, Class<T> is a requested interface clazz)Returns an instance of a requested interface type. |
| public int | Returns: a value that determines how often jitted methods are logged.Implements org. Returns the value of n, which means that jitted methods are logged in every n methods. |
| public int | Returns: a value of a max class cache size.Implements org. Returns a value of a max class cache size. |
| public int | Returns: a value of a max size of the bytecode.Implements org. Returns a value of a max size of the bytecode generated by compiler. |
| public int | Returns: a value of the threshold.Implements org. Returns a value of the threshold that determines whether jitted methods' call reached to the limit or not. |
| public KCode | Returns: a KCode value.Implements org. Returns a value of KCode currently used. |
| public List | Returns: a list of load paths.Implements org. Returns a list of load paths for Ruby scripts/libraries. |
| public RubyInstanceConfig. | Returns: a current LoadServiceCreator.Implements org. Returns a LoadServiceCreator currently used. |
| public PrintStream | Returns: an output stream that Ruby runtime has
Deprecated
As of JRuby 1.5.0, replaced by getOutput().
Returns an output stream that Ruby runtime has. |
| public PrintStream | Returns: an output stream of STDOUT and $stdoutImplements org. Returns an output stream assigned to STDOUT and $stdout. |
| public Profile | Returns: a current profiler.Implements org. Returns a Profile currently used. |
| public ProfileOutput | Returns: current profiling output location.Returns currently configured ProfileOutput object, which determines where the output of profiling operations will be sent. |
| public RubyInstanceConfig. | |
| public String[] | Returns: values associated to the keyis a key in a property file key)Returns an array of values associated to a key. |
| public LocalContextProvider | Returns: a provider ofLocalContextProviderReturns a provider instance of |
| pack-priv static LocalContextProvider | |
| public Reader | |
| public String | Returns: a record separator.Implements org. Returns a record separator. |
| public Ruby | Returns: Ruby runtime of a specified local context
Deprecated
As of JRuby 1.5.0. Use getProvider().getRuntime() method instead.
Returns a Ruby runtime in one of |
| public String | Returns: a script filename.Implements org. Returns a script filename to run. |
| public String | Returns: version information.Implements org. Returns version information about JRuby and Ruby supported by this platform. |
| public BiVariableMap | Returns: a variable map specific to the current threadReturns a variable map in one of |
| public Writer | |
| private void | |
| public boolean | Returns: true if native code is enabled; false otherwise.Get whether native code is enabled for this config. |
| public boolean | Returns: true if the Object Space is able to use, otherwise, false.Implements org. Tests whether the Object Space is enabled or not. |
| public boolean | Returns: true if Ruby is configured to run in a process, otherwise, false.Implements org. Tests whether Ruby runs in a process or not. |
| public EmbedRubyObjectAdapter | Returns: an instance ofEmbedRubyObjectAdapterReturns an instance of |
| public EmbedRubyRuntimeAdapter | Returns: an instance ofEmbedRubyRuntimeAdapter.Returns an instance of |
| public EmbedEvalUnit | Returns: an object which can be runis a Ruby script to be parsed script, int... are linenumbers to display for parse errors and backtraces.
This field is optional. Only the first argument is used for parsing.
When no line number is specified, 0 is applied to. lines)Parses a script and return an object which can be run(). |
| public EmbedEvalUnit | Returns: an object which can be runis used to read a script from reader, String is used as in information, for example, appears in a stack trace
of an exception filename, int... are linenumbers to display for parse errors and backtraces.
This field is optional. Only the first argument is used for parsing.
When no line number is specified, 0 is applied to. lines)Parses a script given by a reader and return an object which can be run(). |
| public EmbedEvalUnit | Returns: an object which can be runis one of the types type, String PathType definesis used as in information, for example, appears in a stack trace
of an exception filename, int... are linenumbers to display for parse errors and backtraces.
This field is optional. Only the first argument is used for parsing.
When no line number is specified, 0 is applied to. lines)Parses a script read from a specified path and return an object which can be run(). |
| public EmbedEvalUnit | Returns: an object which can be runis an input stream to get a script from istream, String filename is used as in information, for example, appears in a stack trace
of an exception filename, int... are linenumbers to display for parse errors and backtraces.
This field is optional. Only the first argument is used for parsing.
When no line number is specified, 0 is applied to. lines)Parses a script given by a input stream and return an object which can be run(). |
| public Object | Returns: a previous value associated with a key, or null if there was no mapping for this key.is a key that the specified value is to be associated with key, Object is a value to be associated with the specified key value)Associates the specified value with the specified key in a variable map. |
| public Object | Returns: a previous value associated with a key, or null if there was no mapping for this key.a receiver to put the value in receiver, String is a key that the specified value is to be associated with key, Object is a value to be associated with the specified key value)Associates the specified value with the specified key in a variable map. |
| public Object | |
| public Object | Returns: a previous value associated with a key, or null if there was no mapping for this key.a receiver to remove the value from receiver, String is a key that the specified value is to be associated with key)Removes the specified Ruby variable with the specified variable name in a variable map and given receiver. |
| public Object | Returns: the previous value associated with key, or null if there was no mapping for key.is a key that the specified value is to be removed from key)Removes the specified value with the specified key in a attribute map. |
| public void | |
| public void | |
| public <T> T | Returns: an instance of requested Java typeis the type we want it to convert to returnType, Object is an instance that will receive this method call. The receiver
can be null or other Java objects as well as RubyObject.
The null will be converted to RubyNil. Java objects will be
wrapped in RubyObject. receiver, String is a method name to be called methodName, Object... is an array of method arguments args)Executes a method defined in Ruby script. |
| public <T> T | Returns: an instance of requested Java typeis the type we want it to convert to returnType, Object is an instance that will receive this method call. The receiver
can be null or other Java objects as well as RubyObject.
The null will be converted to RubyNil. Java objects will be
wrapped in RubyObject. receiver, String is a method name to be called methodName, Block is an optional Block object. Send null for no block. block, Object... is an array of method arguments args)Executes a method defined in Ruby script. |
| public Object | Returns: an evaluated result converted to a Java objectis a Ruby script to get run script)Evaluates a script under the current scope (perhaps the top-level scope) and returns a result only if a script returns a value. |
| public Object | Returns: an evaluated result converted to a Java objectis used to read a script from reader, String is used as in information, for example, appears in a stack trace
of an exception filename)Evaluates a script read from a reader under the current scope (perhaps the top-level scope) and returns a result only if a script returns a value. |
| public Object | Returns: an evaluated result converted to a Java objectis used to input a script from istream, String is used as in information, for example, appears in a stack trace
of an exception filename)Evaluates a script read from a input stream under the current scope (perhaps the top-level scope) and returns a result only if a script returns a value. |
| public Object | Returns: an evaluated result converted to a Java objectis one of the types type, String PathType definesis used to read the script from and an information filename)Reads a script file from specified path and evaluates it under the current scope (perhaps the top-level scope) and returns a result only if a script returns a value. |
| private Object | |
| public void | setArgv(String[]
a new arguments' list. argv)Implements org. Changes values of the arguments' list. |
| public Object | Returns: the previous value associated with key, or null if there was no mapping for key.is a key that the specified value is to be associated with key, Object is a value to be associated with the specified key value)Associates the specified value with the specified key in a attribute map. |
| public void | setClassLoader(ClassLoader
a new class loader to be set. loader)Implements org. Changes a class loader to a given loader. |
| public void | setClassloaderDelegate(boolean
set whether prefer the JRuby classloader to delegate first
to the parent classloader when dynamically loading classes classloaderDelegate)Force dynamically-loaded Java classes to load first from the classloader provided by JRuby before searching parent classloaders. |
| public void | setCompatVersion(CompatVersion version)
Implements org.
Deprecated
|
| public void | setCompileMode(RubyInstanceConfig.
compile mode modeImplements org. Changes a compile mode to a given mode, which should be one of CompileMode.JIT, CompileMode.FORCE, CompileMode.OFF. |
| public void | setCurrentDirectory(String
a new directory to be set. directory)Implements org. Changes a current directory to a given directory. |
| public void | setEnvironment(Map<K, V>
a new map of environment variables. environment)Implements org. Changes an environment variables' map. |
| public void | setError(PrintStream
a print stream to be set pstream)Implements org. Changes STDERR and $stderr to a given print stream. |
| public void | setError(Writer
a writer to be set writer)Implements org. Changes STDERR and $stderr to a given writer. |
| private void | |
| public void | setErrorWriter(Writer
is a writer to be set errorWriter)Replaces a standard error by a specified writer. |
| public void | setHomeDirectory(String
a name of new JRuby home directory. home)Implements org. Changes a JRuby home directory to a directory of a given name. |
| public void | setInput(InputStream
an input stream to be set istream)Implements org. Changes STDIN and $stdin to a given input stream. |
| public void | setInput(Reader
a reader to be set reader)Implements org. Changes STDIN and $stdin to a given reader. |
| public void | setJitLogEvery(int
a new number of methods. logEvery)Implements org. Changes a value of n, so that jitted methods are logged in every n methods. |
| public void | setJitMax(int
a new value of a max class cache size. max)Implements org. Changes a value of a max class cache size. |
| public void | setJitMaxSize(int
a new value of a max size of the bytecode. maxSize)Implements org. Changes a value of a max size of the bytecode generated by compiler. |
| public void | setJitThreshold(int
a new value of the threshold. threshold)Implements org. Changes a value of the threshold that determines whether jitted methods' call reached to the limit or not. |
| public void | setKCode(KCode
a new KCode value. kcode)Implements org. Changes a value of KCode to a given value. |
| public void | setLoadPaths(List<String>
a new list of load paths. paths)Implements org. Changes a list of load paths Ruby scripts/libraries. |
| public void | setLoadServiceCreator(RubyInstanceConfig.
a new LoadServiceCreator creatorImplements org. Changes a LoadServiceCreator to a given one. |
| public void | setNativeEnabled(boolean
new value indicating whether native code is enabled b)Set whether native code is enabled for this config. |
| public void | setObjectSpaceEnabled(boolean
true to enable the Object Space, or false to disable. enable)Implements org. Changes the value to determine whether the Object Space is enabled or not. |
| public void | setOutput(PrintStream
an output stream to be set pstream)Implements org. Changes STDOUT and $stdout to a given output stream. |
| public void | setOutput(Writer
a writer to be set writer)Implements org. Changes STDOUT and $stdout to a given writer. |
| private void | |
| public void | setProfile(Profile
a new profiler to be set. profile)Implements org. Changes a Profile to a given one. |
| public void | setProfile(RubyInstanceConfig.
a new profiling mode to be set. mode
Deprecated
Use setProfilingMode instead
Changes a ProfilingMode to a given one. |
| public void | setProfileOutput(ProfileOutput
a new ProfileOutput object, to which profiling data should be written out)Changes ProfileOutput to given one. |
| public void | setProfilingMode(RubyInstanceConfig.
a new profiling mode to be set. modeChanges a ProfilingMode to a given one. |
| public void | |
| public void | setRecordSeparator(String
a new record separator value, "0" or "777" separator)Implements org. Changes a record separator to a given value. |
| public void | setRunRubyInProcess(boolean
true when Ruby is set to run in the process, or false not to
run in the process. inprocess)Implements org. Changes the value to determine whether Ruby runs in a process or not. |
| public void | setScriptFilename(String
a new script filename. filename)Implements org. Changes a script filename to run. |
| public void | |
| public void |