org.jruby.embed
Class ScriptingContainer

java.lang.Object
  extended by org.jruby.embed.ScriptingContainer
All Implemented Interfaces:
EmbedRubyInstanceConfigAdapter
Direct Known Subclasses:
OSGiScriptingContainer

public class ScriptingContainer
extends java.lang.Object
implements EmbedRubyInstanceConfigAdapter

ScipritngContainer provides various methods and resources that are useful for embedding Ruby in Java. Using this class, users can run Ruby scripts from Java programs easily. Also, users can use methods defined or implemented by Ruby. ScriptingContainer allows users to set configuration parameters, which are per-container properties and per-evaluation attributes. For example, a local context scope, local variable behavior, load paths are per-container properties. Please see PropertyName and AttributeName for more details. The per-container properties should be given prior to the Ruby runtime is instantiated; otherwise, default values are applied to. SCriptingContainer delays Ruby runtime initialization as much as possible to improve startup time. When some values are put into the ScriptingContainer, or runScriptlet method is used, Ruby runtime is created internally. 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 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 LocalVariableBehvior.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();
         script =
          "def message\n" +
              "\"message: #\"\n" +
          "end\n" +
          "message";
         container.put("@message", "What's up?");
         EvalUnit unit = container.parse(script);
         IRubyObject ret = unit.run();
         System.out.println(JavaEmbedUtils.rubyToJava(ret));
         container.put("@message", "Fabulous!");
         ret = unit.run();
         System.out.println(JavaEmbedUtils.rubyToJava(ret));
         container.put("@message", "That's the way you are.");
         ret = unit.run();
         System.out.println(JavaEmbedUtils.rubyToJava(ret));
 
 Produces:
     message: What's up?
     message: Fabulous!
     message: That's the way you are.
See more details at project's Wiki

Author:
Yoko Harada

Constructor Summary
ScriptingContainer()
          Constructs a ScriptingContainer with a default values.
ScriptingContainer(LocalContextScope scope)
          Constructs a ScriptingContainer with a specified local context type.
ScriptingContainer(LocalContextScope scope, LocalVariableBehavior behavior)
          Constructs a ScriptingContainer with a specified local context type and variable behavior.
ScriptingContainer(LocalContextScope scope, LocalVariableBehavior behavior, boolean lazy)
          Constructs a ScriptingContainer with a specified local context scope, local variable behavior and laziness.
ScriptingContainer(LocalVariableBehavior behavior)
          Constructs a ScriptingCOntainer with a specified local variable behavior.
 
Method Summary
 java.lang.Object callMethod(java.lang.Object receiver, java.lang.String methodName, Block block, java.lang.Object... args)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Class<T> returnType)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Class<T> returnType, EmbedEvalUnit unit)
          Executes a method defined in Ruby script.
 java.lang.Object callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Object... args)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Object[] args, Block block, java.lang.Class<T> returnType)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Object[] args, Block block, java.lang.Class<T> returnType, EmbedEvalUnit unit)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Object[] args, java.lang.Class<T> returnType)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Object[] args, java.lang.Class<T> returnType, EmbedEvalUnit unit)
          Executes a method defined in Ruby script.
<T> T
callMethod(java.lang.Object receiver, java.lang.String methodName, java.lang.Object singleArg, java.lang.Class<T> returnType)
          Executes a method defined in Ruby script.
<T> T
callSuper(java.lang.Object receiver, java.lang.Object[] args, Block block, java.lang.Class<T> returnType)
           
<T> T
callSuper(java.lang.Object receiver, java.lang.Object[] args, java.lang.Class<T> returnType)
           
 void clear()
          Removes all of the mappings from this map.
 void finalize()
          Ensure this ScriptingContainer instance is terminated when nobody holds any references to it (and GC wants to reclaim it).
 java.lang.Object get(java.lang.Object receiver, java.lang.String 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.
 java.lang.Object get(java.lang.String key)
          Returns a value of the specified key in a top level of runtime or null if this map doesn't have a mapping for the key.
 java.lang.String[] getArgv()
          Returns a list of argument.
 java.lang.Object getAttribute(java.lang.Object key)
          Returns an attribute value associated with the specified key in a attribute map.
 java.util.Map getAttributeMap()
          Returns a attribute map in one of LocalContextScope.
 ClassCache getClassCache()
          Returns a ClassCache object that is tied to a class loader.
 java.lang.ClassLoader getClassLoader()
          Returns a class loader object that is currently used.
 CompatVersion getCompatVersion()
          Returns a Ruby version currently chosen, which is one of CompatVersion.RUBY1_8, CompatVersion.RUBY1_9, or CompatVersion.BOTH.
 RubyInstanceConfig.CompileMode getCompileMode()
          Returns a compile mode currently chosen, which is one of CompileMode.JIT, CompileMode.FORCE, CompileMode.OFF.
 java.lang.String getCurrentDirectory()
          Returns a current directory.
 java.util.Map getEnvironment()
          Returns a map of environment variables.
 java.io.PrintStream getErr()
          Deprecated. As of JRuby 1.5.0, Replaced by getError()
 java.io.PrintStream getError()
          Returns an error stream assigned to STDERR and $stderr.
 java.io.Writer getErrorWriter()
          Returns an error writer set in an attribute map.
 java.lang.String getHomeDirectory()
          Returns a JRuby home directory.
 java.io.InputStream getIn()
          Deprecated. As of JRuby 1.5.0, replaced by getInput().
 java.io.InputStream getInput()
          Returns an input stream assigned to STDIN and $stdin.
<T> T
getInstance(java.lang.Object receiver, java.lang.Class<T> clazz)
          Returns an instance of a requested interface type.
 int getJitLogEvery()
          Returns the value of n, which means that jitted methods are logged in every n methods.
 int getJitMax()
          Returns a value of a max class cache size.
 int getJitMaxSize()
          Returns a value of a max size of the bytecode generated by compiler.
 int getJitThreshold()
          Returns a value of the threshold that determines whether jitted methods' call reached to the limit or not.
 KCode getKCode()
          Returns a value of KCode currently used.
 java.util.List<java.lang.String> getLoadPaths()
          Returns a list of load paths for Ruby scripts/libraries.
 RubyInstanceConfig.LoadServiceCreator getLoadServiceCreator()
          Returns a LoadServiceCreator currently used.
 java.io.PrintStream getOut()
          Deprecated. As of JRuby 1.5.0, replaced by getOutput().
 java.io.PrintStream getOutput()
          Returns an output stream assigned to STDOUT and $stdout.
 Profile getProfile()
          Returns a Profile currently used.
 RubyInstanceConfig.ProfilingMode getProfilingMode()
          Returns a ProfilingMode currently used.
 java.lang.String[] getProperty(java.lang.String key)
          Returns an array of values associated to a key.
 LocalContextProvider getProvider()
          Returns a provider instance of LocalContextProvider.
 java.io.Reader getReader()
          Returns a reader set in an attribute map.
 java.lang.String getRecordSeparator()
          Returns a record separator.
 Ruby getRuntime()
          Deprecated. As of JRuby 1.5.0. Use getProvider().getRuntime() method instead.
 java.lang.String getScriptFilename()
          Returns a script filename to run.
 java.lang.String getSupportedRubyVersion()
          Returns version information about JRuby and Ruby supported by this platform.
 IRubyObject getTopSelf()
           
 BiVariableMap getVarMap()
          Returns a variable map in one of LocalContextScope.
 java.io.Writer getWriter()
          Returns a writer set in an attribute map.
 boolean isObjectSpaceEnabled()
          Tests whether the Object Space is enabled or not.
 boolean isRunRubyInProcess()
          Tests whether Ruby runs in a process or not.
 EmbedRubyObjectAdapter newObjectAdapter()
          Returns an instance of EmbedRubyObjectAdapter for embedders to invoke methods defined by Ruby.
 EmbedRubyRuntimeAdapter newRuntimeAdapter()
          Returns an instance of EmbedRubyRuntimeAdapter for embedders to parse scripts.
 EmbedEvalUnit parse(java.io.InputStream istream, java.lang.String filename, int... lines)
          Parses a script given by a input stream and return an object which can be run().
 EmbedEvalUnit parse(PathType type, java.lang.String filename, int... lines)
          Parses a script read from a specified path and return an object which can be run().
 EmbedEvalUnit parse(java.io.Reader reader, java.lang.String filename, int... lines)
          Parses a script given by a reader and return an object which can be run().
 EmbedEvalUnit parse(java.lang.String script, int... lines)
          Parses a script and return an object which can be run().
 java.lang.Object put(java.lang.Object receiver, java.lang.String key, java.lang.Object value)
          Associates the specified value with the specified key in a variable map.
 java.lang.Object put(java.lang.String key, java.lang.Object value)
          Associates the specified value with the specified key in a variable map.
 java.lang.Object remove(java.lang.Object receiver, java.lang.String key)
          Removes the specified Ruby variable with the specified variable name in a variable map and given receiver.
 java.lang.Object remove(java.lang.String key)
          Removes the specified Ruby variable with the specified variable name from a variable map and runtime top level.
 java.lang.Object removeAttribute(java.lang.Object key)
          Removes the specified value with the specified key in a attribute map.
 void resetErrorWriter()
           
 void resetWriter()
           
 java.lang.Object runScriptlet(java.io.InputStream istream, java.lang.String 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.
 java.lang.Object runScriptlet(PathType type, java.lang.String 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.
 java.lang.Object runScriptlet(java.io.Reader reader, java.lang.String 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.
 java.lang.Object runScriptlet(java.lang.String script)
          Evaluates a script under the current scope (perhaps the top-level scope) and returns a result only if a script returns a value.
 void setArgv(java.lang.String[] argv)
          Changes values of the arguments' list.
 java.lang.Object setAttribute(java.lang.Object key, java.lang.Object value)
          Associates the specified value with the specified key in a attribute map.
 void setClassCache(ClassCache cache)
          Changes a ClassCache object to a given one.
 void setClassLoader(java.lang.ClassLoader loader)
          Changes a class loader to a given loader.
 void setCompatVersion(CompatVersion version)
          Changes a Ruby version to be evaluated into one of CompatVersion.RUBY1_8, CompatVersion.RUBY1_9, or CompatVersion.BOTH.
 void setCompileMode(RubyInstanceConfig.CompileMode mode)
          Changes a compile mode to a given mode, which should be one of CompileMode.JIT, CompileMode.FORCE, CompileMode.OFF.
 void setCurrentDirectory(java.lang.String directory)
          Changes a current directory to a given directory.
 void setEnvironment(java.util.Map environment)
          Changes an environment variables' map.
 void setError(java.io.PrintStream pstream)
          Changes STDERR and $stderr to a given print stream.
 void setError(java.io.Writer writer)
          Changes STDERR and $stderr to a given writer.
 void setErrorWriter(java.io.Writer errorWriter)
          Replaces a standard error by a specified writer.
 void setHomeDirectory(java.lang.String home)
          Changes a JRuby home directory to a directory of a given name.
 void setInput(java.io.InputStream istream)
          Changes STDIN and $stdin to a given input stream.
 void setInput(java.io.Reader reader)
          Changes STDIN and $stdin to a given reader.
 void setJitLogEvery(int logEvery)
          Changes a value of n, so that jitted methods are logged in every n methods.
 void setJitMax(int max)
          Changes a value of a max class cache size.
 void setJitMaxSize(int maxSize)
          Changes a value of a max size of the bytecode generated by compiler.
 void setJitThreshold(int threshold)
          Changes a value of the threshold that determines whether jitted methods' call reached to the limit or not.
 void setKCode(KCode kcode)
          Changes a value of KCode to a given value.
 void setLoadPaths(java.util.List<java.lang.String> paths)
          Changes a list of load paths Ruby scripts/libraries.
 void setLoadServiceCreator(RubyInstanceConfig.LoadServiceCreator creator)
          Changes a LoadServiceCreator to a given one.
 void setObjectSpaceEnabled(boolean enable)
          Changes the value to determine whether the Object Space is enabled or not.
 void setOutput(java.io.PrintStream pstream)
          Changes STDOUT and $stdout to a given output stream.
 void setOutput(java.io.Writer writer)
          Changes STDOUT and $stdout to a given writer.
 void setProfile(Profile profile)
          Changes a Profile to a given one.
 void setProfile(RubyInstanceConfig.ProfilingMode mode)
          Changes a ProfilingMode to a given one.
 void setReader(java.io.Reader reader)
          Replaces a standard input by a specified reader
 void setRecordSeparator(java.lang.String separator)
          Changes a record separator to a given value.
 void setRunRubyInProcess(boolean inprocess)
          Changes the value to determine whether Ruby runs in a process or not.
 void setScriptFilename(java.lang.String filename)
          Changes a script filename to run.
 void setWriter(java.io.Writer writer)
          Replaces a standard output by a specified writer.
 void terminate()
          Cleanly shut down this ScriptingContainer and any JRuby resources it holds.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ScriptingContainer

public ScriptingContainer()
Constructs a ScriptingContainer with a default values.


ScriptingContainer

public ScriptingContainer(LocalContextScope scope)
Constructs a ScriptingContainer with a specified local context type.

Parameters:
scope - a local context type.

ScriptingContainer

public ScriptingContainer(LocalVariableBehavior behavior)
Constructs a ScriptingCOntainer with a specified local variable behavior.

Parameters:
behavior - a local variable behavior

ScriptingContainer

public ScriptingContainer(LocalContextScope scope,
                          LocalVariableBehavior behavior)
Constructs a ScriptingContainer with a specified local context type and variable behavior.

Parameters:
scopea - a local context type
behavior - a local variable behavior

ScriptingContainer

public ScriptingContainer(LocalContextScope scope,
                          LocalVariableBehavior behavior,
                          boolean lazy)
Constructs a ScriptingContainer with a specified local context scope, local variable behavior and laziness.

Parameters:
scope - is one of a local context scope defined by LocalContextScope
behavior - is one of a local variable behavior defined by LocalVariableBehavior
lazy - is a switch to do lazy retrieval of variabes/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.
Method Detail

getLoadPaths

public java.util.List<java.lang.String> getLoadPaths()
Returns a list of load paths for Ruby scripts/libraries. If no paths is given, the list is created from java.class.path System property.

Specified by:
getLoadPaths in interface EmbedRubyInstanceConfigAdapter
Returns:
a list of load paths.
Since:
JRuby 1.5.0.

setLoadPaths

public void setLoadPaths(java.util.List<java.lang.String> paths)
Changes a list of load paths Ruby scripts/libraries. The default value is an empty array. If no paths is given, the list is created from java.class.path System property. This value can be set by org.jruby.embed.class.path System property, also. Call this method before you use put/get, runScriptlet, and parse methods so that the given paths will be used.

Specified by:
setLoadPaths in interface EmbedRubyInstanceConfigAdapter
Parameters:
paths - a new list of load paths.
Since:
JRuby 1.5.0.

getInput

public java.io.InputStream getInput()
Returns an input stream assigned to STDIN and $stdin.

Specified by:
getInput in interface EmbedRubyInstanceConfigAdapter
Returns:
input stream of STDIN and $stdin
Since:
JRuby 1.5.0.

setInput

public void setInput(java.io.InputStream istream)
Changes STDIN and $stdin to a given input stream. The default standard input is java.lang.System.in. Call this method before you use put/get, runScriptlet, and parse methods so that the given input stream will be used.

Specified by:
setInput in interface EmbedRubyInstanceConfigAdapter
Parameters:
istream - an input stream to be set
Since:
JRuby 1.5.0.

setInput

public void setInput(java.io.Reader reader)
Changes STDIN and $stdin to a given reader. No reader is set by default. Call this method before you use put/get, runScriptlet, and parse methods so that the given reader will be used.

Specified by:
setInput in interface EmbedRubyInstanceConfigAdapter
Parameters:
reader - a reader to be set
Since:
JRuby 1.5.0.

getOutput

public java.io.PrintStream getOutput()
Returns an output stream assigned to STDOUT and $stdout.

Specified by:
getOutput in interface EmbedRubyInstanceConfigAdapter
Returns:
an output stream of STDOUT and $stdout
Since:
JRuby 1.5.0.

setOutput

public void setOutput(java.io.PrintStream pstream)
Changes STDOUT and $stdout to a given output stream. The default standard output is java.lang.System.out. Call this method before you use put/get, runScriptlet, and parse methods so that the given output stream will be used.

Specified by:
setOutput in interface EmbedRubyInstanceConfigAdapter
Parameters:
pstream - an output stream to be set
Since:
JRuby 1.5.0.

setOutput

public void setOutput(java.io.Writer writer)
Changes STDOUT and $stdout to a given writer. No writer is set by default. Call this method before you use put/get, runScriptlet, and parse methods so that the given writer will be used.

Specified by:
setOutput in interface EmbedRubyInstanceConfigAdapter
Parameters:
writer - a writer to be set
Since:
JRuby 1.5.0.

getError

public java.io.PrintStream getError()
Returns an error stream assigned to STDERR and $stderr.

Specified by:
getError in interface EmbedRubyInstanceConfigAdapter
Returns:
output stream for error stream
Since:
JRuby 1.5.0.

setError

public void setError(java.io.PrintStream pstream)
Changes STDERR and $stderr to a given print stream. The default standard error is java.lang.System.err. Call this method before you use put/get, runScriptlet, and parse methods so that the given print stream will be used.

Specified by:
setError in interface EmbedRubyInstanceConfigAdapter
Parameters:
pstream - a print stream to be set
Since:
JRuby 1.5.0.

setError

public void setError(java.io.Writer writer)
Changes STDERR and $stderr to a given writer. No writer is set by default. Call this method before you use put/get, runScriptlet, and parse methods so that the given writer will be used.

Specified by:
setError in interface EmbedRubyInstanceConfigAdapter
Parameters:
writer - a writer to be set
Since:
JRuby 1.5.0.

getCompileMode

public RubyInstanceConfig.CompileMode getCompileMode()
Returns a compile mode currently chosen, which is one of CompileMode.JIT, CompileMode.FORCE, CompileMode.OFF. The default mode is CompileMode.OFF if CompatVersion.RUBY1_9 is chosen, otherwise, CompileMode.JIT. Also, ComileMode.OFF is chosen when a security restriction is set.

Specified by:
getCompileMode in interface EmbedRubyInstanceConfigAdapter
Returns:
a compile mode.
Since:
JRuby 1.5.0.

setCompileMode

public void setCompileMode(RubyInstanceConfig.CompileMode mode)
Changes a compile mode to a given mode, which should be one of CompileMode.JIT, CompileMode.FORCE, CompileMode.OFF. Call this method before you use put/get, runScriptlet, and parse methods so that the given mode will be used.

Specified by:
setCompileMode in interface EmbedRubyInstanceConfigAdapter
Parameters:
mode - compile mode
Since:
JRuby 1.5.0.

isRunRubyInProcess

public boolean isRunRubyInProcess()
Tests whether Ruby runs in a process or not.

Specified by:
isRunRubyInProcess in interface EmbedRubyInstanceConfigAdapter
Returns:
true if Ruby is configured to run in a process, otherwise, false.
Since:
JRuby 1.5.0.

setRunRubyInProcess

public void setRunRubyInProcess(boolean inprocess)
Changes the value to determine whether Ruby runs in a process or not. The default value is true. Call this method before you use put/get, runScriptlet, and parse methods so that the given condition will be set.

Specified by:
setRunRubyInProcess in interface EmbedRubyInstanceConfigAdapter
Parameters:
inprocess - true when Ruby is set to run in the process, or false not to run in the process.
Since:
JRuby 1.5.0.

getCompatVersion

public CompatVersion getCompatVersion()
Returns a Ruby version currently chosen, which is one of CompatVersion.RUBY1_8, CompatVersion.RUBY1_9, or CompatVersion.BOTH. The default version is CompatVersion.RUBY1_8.

Specified by:
getCompatVersion in interface EmbedRubyInstanceConfigAdapter
Returns:
a Ruby version
Since:
JRuby 1.5.0.

setCompatVersion

public void setCompatVersion(CompatVersion version)
Changes a Ruby version to be evaluated into one of CompatVersion.RUBY1_8, CompatVersion.RUBY1_9, or CompatVersion.BOTH. The default version is CompatVersion.RUBY1_8. Call this method before you use put/get, runScriptlet, and parse methods so that the given version will be set.

Specified by:
setCompatVersion in interface EmbedRubyInstanceConfigAdapter
Parameters:
version - a Ruby version
Since:
JRuby 1.5.0.

isObjectSpaceEnabled

public boolean isObjectSpaceEnabled()
Tests whether the Object Space is enabled or not.

Specified by:
isObjectSpaceEnabled in interface EmbedRubyInstanceConfigAdapter
Returns:
true if the Object Space is able to use, otherwise, false.
Since:
JRuby 1.5.0.

setObjectSpaceEnabled

public void setObjectSpaceEnabled(boolean enable)
Changes the value to determine whether the Object Space is enabled or not. The default value is false. Call this method before you use put/get, runScriptlet, and parse methods so that the given condition will be used.

Specified by:
setObjectSpaceEnabled in interface EmbedRubyInstanceConfigAdapter
Parameters:
enable - true to enable the Object Space, or false to disable.
Since:
JRuby 1.5.0. This value can be set by jruby.objectspace.enabled system property.

getEnvironment

public java.util.Map getEnvironment()
Returns a map of environment variables.

Specified by:
getEnvironment in interface EmbedRubyInstanceConfigAdapter
Returns:
a map that has environment variables' key-value pairs.
Since:
JRuby 1.5.0.

setEnvironment

public void setEnvironment(java.util.Map environment)
Changes an environment variables' map. Call this method before you use put/get, runScriptlet, and parse methods so that initial configurations will work.

Specified by:
setEnvironment in interface EmbedRubyInstanceConfigAdapter
Parameters:
environment - a new map of environment variables.
Since:
JRuby 1.5.0.

getCurrentDirectory

public java.lang.String getCurrentDirectory()
Returns a current directory. The default current directory is identical to a value of "user.dir" system property if no security restriction is set. If the "user.dir" directory is protected by the security restriction, the default value is "/".

Specified by:
getCurrentDirectory in interface EmbedRubyInstanceConfigAdapter
Returns:
a current directory.
Since:
JRuby 1.5.0.

setCurrentDirectory

public void setCurrentDirectory(java.lang.String directory)
Changes a current directory to a given directory. The current directory can be changed anytime.

Specified by:
setCurrentDirectory in interface EmbedRubyInstanceConfigAdapter
Parameters:
directory - a new directory to be set.
Since:
JRuby 1.5.0.

getHomeDirectory

public java.lang.String getHomeDirectory()
Returns a JRuby home directory. The default JRuby home is the value of JRUBY_HOME environment variable, or "jruby.home" system property when no security restriction is set to those directories. If none of JRUBY_HOME or jruby.home is set and jruby-complete.jar is used, the default JRuby home is "/META-INF/jruby.home" in the jar archive. Otherwise, "java.io.tmpdir" system property is the default value.

Specified by:
getHomeDirectory in interface EmbedRubyInstanceConfigAdapter
Returns:
a JRuby home directory.
Since:
JRuby 1.5.0.

setHomeDirectory

public void setHomeDirectory(java.lang.String home)
Changes a JRuby home directory to a directory of a given name. Call this method before you use put/get, runScriptlet, and parse methods so that the given directory will be used.

Specified by:
setHomeDirectory in interface EmbedRubyInstanceConfigAdapter
Parameters:
home - a name of new JRuby home directory.
Since:
JRuby 1.5.0.

getClassCache

public ClassCache getClassCache()
Returns a ClassCache object that is tied to a class loader. The default ClassCache object is tied to a current thread' context loader if it exists. Otherwise, it is tied to the class loader that loaded RubyInstanceConfig.

Specified by:
getClassCache in interface EmbedRubyInstanceConfigAdapter
Returns:
a ClassCache object.
Since:
JRuby 1.5.0.

setClassCache

public void setClassCache(ClassCache cache)
Changes a ClassCache object to a given one. Call this method before you use put/get, runScriptlet, and parse methods so that the given class cache will be used.

Specified by:
setClassCache in interface EmbedRubyInstanceConfigAdapter
Parameters:
cache - a new ClassCache object to be set.
Since:
JRuby 1.5.0.

getClassLoader

public java.lang.ClassLoader getClassLoader()
Returns a class loader object that is currently used. This loader loads Ruby files and libraries.

Specified by:
getClassLoader in interface EmbedRubyInstanceConfigAdapter
Returns:
a class loader object that is currently used.
Since:
JRuby 1.5.0.

setClassLoader

public void setClassLoader(java.lang.ClassLoader loader)
Changes a class loader to a given loader. Call this method before you use put/get, runScriptlet, and parse methods so that the given class loader will be used.

Specified by:
setClassLoader in interface EmbedRubyInstanceConfigAdapter
Parameters:
loader - a new class loader to be set.
Since:
JRuby 1.5.0.

getProfile

public Profile getProfile()
Returns a Profile currently used. The default value is Profile.DEFAULT, which has the same behavior to Profile.ALL. Profile allows you to define a restricted subset of code to be loaded during the runtime initialization. When you use JRuby in restricted environment such as Google App Engine, Profile is a helpful option.

Specified by:
getProfile in interface EmbedRubyInstanceConfigAdapter
Returns:
a current profiler.
Since:
JRuby 1.5.0.

setProfile

public void setProfile(Profile profile)
Changes a Profile to a given one. The default value is Profile.DEFAULT, which has the same behavior to Profile.ALL. Call this method before you use put/get, runScriptlet, and parse methods so that initial configurations will work. Profile allows you to define a restricted subset of code to be loaded during the runtime initialization. When you use JRuby in restricted environment such as Google App Engine, Profile is a helpful option. For example, Profile.NO_FILE_CLASS doesn't load File class.

Specified by:
setProfile in interface EmbedRubyInstanceConfigAdapter
Parameters:
profile - a new profiler to be set.
Since:
JRuby 1.5.0.

getProfilingMode

public RubyInstanceConfig.ProfilingMode getProfilingMode()
Returns a ProfilingMode currently used. The default value is ProfilingMode.OFF.

Returns:
a current profiling mode.
Since:
JRuby 1.6.6.

setProfile

public void setProfile(RubyInstanceConfig.ProfilingMode mode)
Changes a ProfilingMode to a given one. The default value is Profiling.OFF. Call this method before you use put/get, runScriptlet, and parse methods so that initial configurations will work. ProfilingMode allows you to change profiling style. Profiling.OFF - default. profiling off. Profiling.API - activates Ruby profiler API. equivalent to --profile.api command line option Profiling.FLAT - synonym for --profile command line option equivalent to --profile.flat command line option Profiling.GRAPH - runs with instrumented (timed) profiling, graph format. equivalent to --profile.graph command line option.

Parameters:
mode - a new profiling mode to be set.
Since:
JRuby 1.6.6.

getLoadServiceCreator

public RubyInstanceConfig.LoadServiceCreator getLoadServiceCreator()
Returns a LoadServiceCreator currently used.

Specified by:
getLoadServiceCreator in interface EmbedRubyInstanceConfigAdapter
Returns:
a current LoadServiceCreator.
Since:
JRuby 1.5.0.

setLoadServiceCreator

public void setLoadServiceCreator(RubyInstanceConfig.LoadServiceCreator creator)
Changes a LoadServiceCreator to a given one. Call this method before you use put/get, runScriptlet, and parse methods so that initial configurations will work.

Specified by:
setLoadServiceCreator in interface EmbedRubyInstanceConfigAdapter
Parameters:
creator - a new LoadServiceCreator
Since:
JRuby 1.5.0.

getArgv

public java.lang.String[] getArgv()
Returns a list of argument.

Specified by:
getArgv in interface EmbedRubyInstanceConfigAdapter
Returns:
an arguments' list.
Since:
JRuby 1.5.0.

setArgv

public void setArgv(java.lang.String[] argv)
Changes values of the arguments' list.

Specified by:
setArgv in interface EmbedRubyInstanceConfigAdapter
Parameters:
argv - a new arguments' list.
Since:
JRuby 1.5.0.

getScriptFilename

public java.lang.String getScriptFilename()
Returns a script filename to run. The default value is "<script>".

Specified by:
getScriptFilename in interface EmbedRubyInstanceConfigAdapter
Returns:
a script filename.
Since:
JRuby 1.5.0.

setScriptFilename

public void setScriptFilename(java.lang.String filename)
Changes a script filename to run. The default value is "<script>". Call this before you use put/get, runScriptlet, and parse methods so that initial configurations will work.

Specified by:
setScriptFilename in interface EmbedRubyInstanceConfigAdapter
Parameters:
filename - a new script filename.
Since:
JRuby 1.5.0.

getRecordSeparator

public java.lang.String getRecordSeparator()
Returns a record separator. The default value is "\n".

Specified by:
getRecordSeparator in interface EmbedRubyInstanceConfigAdapter
Returns:
a record separator.
Since:
JRuby 1.5.0.

setRecordSeparator

public void setRecordSeparator(java.lang.String separator)
Changes a record separator to a given value. If "0" is given, the record separator goes to "\n\n", "777" goes to "￿", otherwise, an octal value of the given number. Call this before you use put/get, runScriptlet, and parse methods so that initial configurations will work.

Specified by:
setRecordSeparator in interface EmbedRubyInstanceConfigAdapter
Parameters:
separator - a new record separator value, "0" or "777"
Since:
JRuby 1.5.0.

getKCode

public KCode getKCode()
Returns a value of KCode currently used. The default value is KCode.NONE.

Specified by:
getKCode in interface EmbedRubyInstanceConfigAdapter
Returns:
a KCode value.
Since:
JRuby 1.5.0.

setKCode

public void setKCode(KCode kcode)
Changes a value of KCode to a given value. The value should be one of KCode.NONE, KCode.UTF8, KCode.SJIS, or KCode.EUC. The default value is KCode.NONE. Call this method before you use put/get, runScriptlet, and parse methods so that the given value will be used.

Specified by:
setKCode in interface EmbedRubyInstanceConfigAdapter
Parameters:
kcode - a new KCode value.
Since:
JRuby 1.5.0.

getJitLogEvery

public int getJitLogEvery()
Returns the value of n, which means that jitted methods are logged in every n methods. The default value is 0.

Specified by:
getJitLogEvery in interface EmbedRubyInstanceConfigAdapter
Returns:
a value that determines how often jitted methods are logged.
Since:
JRuby 1.5.0.

setJitLogEvery

public void setJitLogEvery(int logEvery)
Changes a value of n, so that jitted methods are logged in every n methods. The default value is 0. This value can be set by the jruby.jit.logEvery System property. Call this method before you use put/get, runScriptlet, and parse methods so that the configurations will work.

Specified by:
setJitLogEvery in interface EmbedRubyInstanceConfigAdapter
Parameters:
logEvery - a new number of methods.
Since:
JRuby 1.5.0.

getJitThreshold

public int getJitThreshold()
Returns a value of the threshold that determines whether jitted methods' call reached to the limit or not. The default value is -1 when security restriction is applied, or 50 when no security restriction exists.

Specified by:
getJitThreshold in interface EmbedRubyInstanceConfigAdapter
Returns:
a value of the threshold.
Since:
JRuby 1.5.0.

setJitThreshold

public void setJitThreshold(int threshold)
Changes a value of the threshold that determines whether jitted methods' call reached to the limit or not. The default value is -1 when security restriction is applied, or 50 when no security restriction exists. This value can be set by jruby.jit.threshold System property. Call this method before you use put/get, runScriptlet, and parse methods so that the configurations will work.

Specified by:
setJitThreshold in interface EmbedRubyInstanceConfigAdapter
Parameters:
threshold - a new value of the threshold.
Since:
JRuby 1.5.0.

getJitMax

public int getJitMax()
Returns a value of a max class cache size. The default value is 0 when security restriction is applied, or 4096 when no security restriction exists.

Specified by:
getJitMax in interface EmbedRubyInstanceConfigAdapter
Returns:
a value of a max class cache size.
Since:
JRuby 1.5.0.

setJitMax

public void setJitMax(int max)
Changes a value of a max class cache size. The default value is 0 when security restriction is applied, or 4096 when no security restriction exists. This value can be set by jruby.jit.max System property. Call this method before you use put/get, runScriptlet, and parse methods so that the configurations will work.

Specified by:
setJitMax in interface EmbedRubyInstanceConfigAdapter
Parameters:
max - a new value of a max class cache size.
Since:
JRuby 1.5.0.

getJitMaxSize

public int getJitMaxSize()
Returns a value of a max size of the bytecode generated by compiler. The default value is -1 when security restriction is applied, or 10000 when no security restriction exists.

Specified by:
getJitMaxSize in interface EmbedRubyInstanceConfigAdapter
Returns:
a value of a max size of the bytecode.
Since:
JRuby 1.5.0.

setJitMaxSize

public void setJitMaxSize(int maxSize)
Changes a value of a max size of the bytecode generated by compiler. The default value is -1 when security restriction is applied, or 10000 when no security restriction exists. This value can be set by jruby.jit.maxsize System property. Call this method before you use put/get, runScriptlet, and parse methods so that the configurations will work.

Specified by:
setJitMaxSize in interface EmbedRubyInstanceConfigAdapter
Parameters:
maxSize - a new value of a max size of the bytecode.
Since:
JRuby 1.5.0.

getSupportedRubyVersion

public java.lang.String getSupportedRubyVersion()
Returns version information about JRuby and Ruby supported by this platform.

Specified by:
getSupportedRubyVersion in interface EmbedRubyInstanceConfigAdapter
Returns:
version information.

getProperty

public java.lang.String[] getProperty(java.lang.String key)
Returns an array of values associated to a key.

Parameters:
key - is a key in a property file
Returns:
values associated to the key

getProvider

public LocalContextProvider getProvider()
Returns a provider instance of LocalContextProvider. When users want to configure Ruby runtime, they can do by setting class loading paths, RubyInstanceConfig or ClassCache to the provider before they get Ruby runtime.

Returns:
a provider of LocalContextProvider

getRuntime

@Deprecated
public Ruby getRuntime()
Deprecated. As of JRuby 1.5.0. Use getProvider().getRuntime() method instead.

Returns a Ruby runtime in one of LocalContextScope.

Returns:
Ruby runtime of a specified local context

getVarMap

public BiVariableMap getVarMap()
Returns a variable map in one of LocalContextScope. Variables in this map is used to share between Java and Ruby. Map keys are Ruby's variable names, thus they must be valid Ruby names.

Returns:
a variable map specific to the current thread

getAttributeMap

public java.util.Map getAttributeMap()
Returns a attribute map in one of LocalContextScope. Attributes in this map accept any key value pair, types of which are java.lang.Object. Ruby scripts do not look up this map.

Returns:
an attribute map specific to the current thread

getAttribute

public java.lang.Object getAttribute(java.lang.Object key)
Returns an attribute value associated with the specified key in a attribute map. This is a short cut method of ScriptingContainer#getAttributeMap().get(key).

Parameters:
key - is the attribute key
Returns:
value is a value associated to the specified key

setAttribute

public java.lang.Object setAttribute(java.lang.Object key,
                                     java.lang.Object value)
Associates the specified value with the specified key in a attribute map. If the map previously contained a mapping for the key, the old value is replaced. This is a short cut method of ScriptingContainer#getAttributeMap().put(key, value).

Parameters:
key - is a key that the specified value is to be associated with
value - is a value to be associated with the specified key
Returns:
the previous value associated with key, or null if there was no mapping for key.

removeAttribute

public java.lang.Object removeAttribute(java.lang.Object key)
Removes the specified value with the specified key in a attribute map. If the map previously contained a mapping for the key, the old value is returned. This is a short cut method of ScriptingContainer#getAttributeMap().remove(key).

Parameters:
key - is a key that the specified value is to be removed from
Returns:
the previous value associated with key, or null if there was no mapping for key.

get

public java.lang.Object get(java.lang.String key)
Returns a value of the specified key in a top level of runtime or null if this map doesn't have a mapping for the key. The key must be a valid Ruby variable or constant name.

Parameters:
key - is a key whose associated value is to be returned
Returns:
a value to which the specified key is mapped, or null if this map contains no mapping for the key

get

public java.lang.Object get(java.lang.Object receiver,
                            java.lang.String 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. The key must be a valid Ruby variable or constant name. A global variable doesn't depend on the receiver.

Parameters:
receiver - a receiver to get the value from
key - is a key whose associated value is to be returned
Returns:
a value to which the specified key is mapped, or null if this map contains no mapping for the key

put

public java.lang.Object put(java.lang.String key,
                            java.lang.Object value)
Associates the specified value with the specified key in a variable map. This key-value pair is injected to a top level of runtime during evaluation. If the map previously contained a mapping for the key, the old value is replaced. The key must be a valid Ruby variable or constant name. It will be a top level variable or constant.

Parameters:
key - is a key that the specified value is to be associated with
value - is a value to be associated with the specified key
Returns:
a previous value associated with a key, or null if there was no mapping for this key.

put

public java.lang.Object put(java.lang.Object receiver,
                            java.lang.String key,
                            java.lang.Object value)
Associates the specified value with the specified key in a variable map. This key-value pair is injected to a given receiver during evaluation. If the map previously contained a mapping for the key, the old value is replaced. The key must be a valid Ruby variable or constant name. A given receiver limits the scope of a variable or constant. However, a global variable is accecible globally always.

Parameters:
receiver - a receiver to put the value in
key - is a key that the specified value is to be associated with
value - is a value to be associated with the specified key
Returns:
a previous value associated with a key, or null if there was no mapping for this key.

remove

public java.lang.Object remove(java.lang.String key)
Removes the specified Ruby variable with the specified variable name from a variable map and runtime top level. If the map previously contained a mapping for the key, the old value is returned. The key must be a valid Ruby variable name.

Parameters:
key - is a key that the specified value is to be associated with
Returns:
a previous value associated with a key, or null if there was no mapping for this key.

remove

public java.lang.Object remove(java.lang.Object receiver,
                               java.lang.String key)
Removes the specified Ruby variable with the specified variable name in a variable map and given receiver. If the map previously contained a mapping for the key, the old value is returned. The key must be a valid Ruby variable name. This is a short cut method of ScriptingContainer#getVarMap().remove(key).

Parameters:
receiver - a receiver to remove the value from
key - is a key that the specified value is to be associated with
Returns:
a previous value associated with a key, or null if there was no mapping for this key.

clear

public void clear()
Removes all of the mappings from this map. The map will be empty after this call returns. Ruby variables are also removed from Ruby instance. However, Ruby instance keep having global variable names with null value. This is a short cut method of ScriptingContainer#getVarMap().clear().


parse

public EmbedEvalUnit parse(java.lang.String script,
                           int... lines)
Parses a script and return an object which can be run(). This allows the script to be parsed once and evaluated many times.

Parameters:
script - is a Ruby script to be parsed
lines - 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.
Returns:
an object which can be run

parse

public EmbedEvalUnit parse(java.io.Reader reader,
                           java.lang.String filename,
                           int... lines)
Parses a script given by a reader and return an object which can be run(). This allows the script to be parsed once and evaluated many times.

Parameters:
reader - is used to read a script from
filename - is used as in information, for example, appears in a stack trace of an exception
lines - 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.
Returns:
an object which can be run

parse

public EmbedEvalUnit parse(PathType type,
                           java.lang.String filename,
                           int... lines)
Parses a script read from a specified path and return an object which can be run(). This allows the script to be parsed once and evaluated many times.

Parameters:
type - is one of the types PathType defines
filename - is used as in information, for example, appears in a stack trace of an exception
lines - 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.
Returns:
an object which can be run

parse

public EmbedEvalUnit parse(java.io.InputStream istream,
                           java.lang.String filename,
                           int... lines)
Parses a script given by a input stream and return an object which can be run(). This allows the script to be parsed once and evaluated many times.

Parameters:
istream - is an input stream to get a script from
filename - filename is used as in information, for example, appears in a stack trace of an exception
lines - 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.
Returns:
an object which can be run

runScriptlet

public java.lang.Object runScriptlet(java.lang.String script)
Evaluates a script under the current scope (perhaps the top-level scope) and returns a result only if a script returns a value. Right after the parsing, the script is evaluated once.

Parameters:
script - is a Ruby script to get run
Returns:
an evaluated result converted to a Java object

runScriptlet

public java.lang.Object runScriptlet(java.io.Reader reader,
                                     java.lang.String 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. Right after the parsing, the script is evaluated once.

Parameters:
reader - is used to read a script from
filename - is used as in information, for example, appears in a stack trace of an exception
Returns:
an evaluated result converted to a Java object

runScriptlet

public java.lang.Object runScriptlet(java.io.InputStream istream,
                                     java.lang.String 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. Right after the parsing, the script is evaluated once.

Parameters:
istream - is used to input a script from
filename - is used as in information, for example, appears in a stack trace of an exception
Returns:
an evaluated result converted to a Java object

runScriptlet

public java.lang.Object runScriptlet(PathType type,
                                     java.lang.String 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. Right after the parsing, the script is evaluated once.

Parameters:
type - is one of the types PathType defines
filename - is used to read the script from and an information
Returns:
an evaluated result converted to a Java object

newRuntimeAdapter

public EmbedRubyRuntimeAdapter newRuntimeAdapter()
Returns an instance of EmbedRubyRuntimeAdapter for embedders to parse scripts.

Returns:
an instance of EmbedRubyRuntimeAdapter.

newObjectAdapter

public EmbedRubyObjectAdapter newObjectAdapter()
Returns an instance of EmbedRubyObjectAdapter for embedders to invoke methods defined by Ruby. The script must be evaluated prior to a method call. In most cases, users don't need to use this method. ScriptingContainer's callMethods are the shortcut and work in the same way.
Example
         # calendar.rb
         require 'date'
         class Calendar
           def initialize;@today = DateTime.now;end
           def next_year;@today.year + 1;end
         end
         Calendar.new


         ScriptingContainer container = new ScriptingContainer();
         String filename =  "ruby/calendar.rb";
         Object receiver = instance.runScriptlet(PathType.CLASSPATH, filename);
         EmbedRubyObjectAdapter adapter = instance.newObjectAdapter();
         Integer result =
             (Integer) adapter.callMethod(receiver, "next_year", Integer.class);
         System.out.println("next year: " + result);
         System.out.println(instance.get("@today"));

 Outputs:
     next year: 2010
     2009-05-19T17:46:44-04:00

Returns:
an instance of EmbedRubyObjectAdapter

callMethod

public java.lang.Object callMethod(java.lang.Object receiver,
                                   java.lang.String methodName,
                                   java.lang.Object... args)
Executes a method defined in Ruby script. This method is used when a Ruby method does not have any argument.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
returnType - is the type we want it to convert to
Returns:
an instance of requested Java type

callMethod

public java.lang.Object callMethod(java.lang.Object receiver,
                                   java.lang.String methodName,
                                   Block block,
                                   java.lang.Object... args)
Executes a method defined in Ruby script. This method is used when a Ruby method does not have any argument.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
returnType - is the type we want it to convert to
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Class<T> returnType)
Executes a method defined in Ruby script. This method is used when a Ruby method does not have any argument.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
returnType - is the type we want it to convert to
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Object singleArg,
                        java.lang.Class<T> returnType)
Executes a method defined in Ruby script. This method is used when a Ruby method have only one argument.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
singleArg - is an method argument
returnType - returnType is the type we want it to convert to
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Object[] args,
                        java.lang.Class<T> returnType)
Executes a method defined in Ruby script. This method is used when a Ruby method have multiple arguments.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
args - is an array of method arguments
returnType - is the type we want it to convert to
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Object[] args,
                        Block block,
                        java.lang.Class<T> returnType)
Executes a method defined in Ruby script. This method is used when a Ruby method have multiple arguments, one of which is a block.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
args - is an array of method arguments except a block
block - is a block to be executed in this method
returnType - is the type we want it to convert to
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Class<T> returnType,
                        EmbedEvalUnit unit)
Executes a method defined in Ruby script. This method is used when a Ruby method does not have any argument, and users want to inject Ruby's local variables' values from Java.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
returnType - is the type we want it to convert to
unit - is parsed unit
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Object[] args,
                        java.lang.Class<T> returnType,
                        EmbedEvalUnit unit)
Executes a method defined in Ruby script. This method is used when a Ruby method have multiple arguments, and users want to inject Ruby's local variables' values from Java.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
args - is an array of method arguments
returnType - is the type we want it to convert to
unit - is parsed unit
Returns:
an instance of requested Java type

callMethod

public <T> T callMethod(java.lang.Object receiver,
                        java.lang.String methodName,
                        java.lang.Object[] args,
                        Block block,
                        java.lang.Class<T> returnType,
                        EmbedEvalUnit unit)
Executes a method defined in Ruby script. This method is used when a Ruby method have multiple arguments, one of which is a block, and users want to inject Ruby's local variables' values from Java.

Parameters:
receiver - is an instance that will receive this method call
methodName - is a method name to be called
args - is an array of method arguments except a block
block - is a block to be executed in this method
returnType - is the type we want it to convert to
unit - is parsed unit
Returns:
is the type we want it to convert to

callSuper

public <T> T callSuper(java.lang.Object receiver,
                       java.lang.Object[] args,
                       java.lang.Class<T> returnType)
Parameters:
receiver - is an instance that will receive this method call
args - is an array of method arguments
returnType - is the type we want it to convert to
Returns:
is the type we want it to convert to

callSuper

public <T> T callSuper(java.lang.Object receiver,
                       java.lang.Object[] args,
                       Block block,
                       java.lang.Class<T> returnType)
Parameters:
receiver - is an instance that will receive this method call
args - is an array of method arguments except a block
block - is a block to be executed in this method
returnType - is the type we want it to convert to
Returns:
is the type we want it to convert to

getInstance

public <T> T getInstance(java.lang.Object receiver,
                         java.lang.Class<T> clazz)
Returns an instance of a requested interface type. An implementation of the requested interface is done by a Ruby script, which has been evaluated before getting the instance. In most cases, users don't need to use this method. ScriptingContainer's runScriptlet method returns an instance of the interface type that is implemented by Ruby.
Example
 Interface
     //QuadraticFormula.java
     package org.jruby.embed;
     import java.util.List;
     public interface QuadraticFormula {
         List solve(int a, int b, int c) throws Exception;
     }

 Implementation
     #quadratic_formula.rb
     def solve(a, b, c)
       v = b ** 2 - 4 * a * c
       if v < 0: raise RangeError end
       s0 = ((-1)*b - Math.sqrt(v))/(2*a)
       s1 = ((-1)*b + Math.sqrt(v))/(2*a)
       return s0, s1
     end

 Usage
     ScriptingcContainer container = new ScriptingContaier();
     String filename = "ruby/quadratic_formula_class.rb";
     Object receiver = container.runScriptlet(PathType.CLASSPATH, filename);
     QuadraticFormula qf = container.getInstance(receiver, QuadraticFormula.class);
     try {
          List solutions = qf.solve(1, -2, -13);
          printSolutions(solutions);
          solutions = qf.solve(1, -2, 13);
          for (double s : solutions) {
              System.out.print(s + ", ");
          }
     } catch (Exception e) {
          e.printStackTrace();
     }

 Output
     -2.7416573867739413, 4.741657386773941, 
 

Parameters:
receiver - is an instance that implements the interface
clazz - is a requested interface
Returns:
an instance of a requested interface type

setReader

public void setReader(java.io.Reader reader)
Replaces a standard input by a specified reader

Parameters:
reader - is a reader to be set

getReader

public java.io.Reader getReader()
Returns a reader set in an attribute map.

Returns:
a reader in an attribute map

getIn

@Deprecated
public java.io.InputStream getIn()
Deprecated. As of JRuby 1.5.0, replaced by getInput().

Returns an input stream that Ruby runtime has. The stream is set when Ruby runtime is initialized.

Returns:
an input stream that Ruby runtime has.

setWriter

public void setWriter(java.io.Writer writer)
Replaces a standard output by a specified writer.

Parameters:
writer - is a writer to be set

resetWriter

public void resetWriter()

getWriter

public java.io.Writer getWriter()
Returns a writer set in an attribute map.

Returns:
a writer in a attribute map

getOut

@Deprecated
public java.io.PrintStream getOut()
Deprecated. As of JRuby 1.5.0, replaced by getOutput().

Returns an output stream that Ruby runtime has. The stream is set when Ruby runtime is initialized.

Returns:
an output stream that Ruby runtime has

setErrorWriter

public void setErrorWriter(java.io.Writer errorWriter)
Replaces a standard error by a specified writer.

Parameters:
errorWriter - is a writer to be set

resetErrorWriter

public void resetErrorWriter()

getErrorWriter

public java.io.Writer getErrorWriter()
Returns an error writer set in an attribute map.

Returns:
an error writer in a attribute map

getErr

@Deprecated
public java.io.PrintStream getErr()
Deprecated. As of JRuby 1.5.0, Replaced by getError()

Returns an error output stream that Ruby runtime has. The stream is set when Ruby runtime is initialized.

Returns:
an error output stream that Ruby runtime has

terminate

public void terminate()
Cleanly shut down this ScriptingContainer and any JRuby resources it holds. All ScriptingContainer instances should be terminated when you are done with them, rather then leaving them for GC to finalize.

Since:
JRuby 1.5.0

finalize

public void finalize()
              throws java.lang.Throwable
Ensure this ScriptingContainer instance is terminated when nobody holds any references to it (and GC wants to reclaim it).

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable
Since:
JRuby 1.6.0

getTopSelf

public IRubyObject getTopSelf()


Copyright © 2002-2009 JRuby Team. All Rights Reserved.