org.jruby.embed.ScriptingContainer

http://jruby.org/apidocs/org/jruby/embed/ScriptingContainer.html 

org.jruby.embed
Class ScriptingContainer

java.lang.Object
  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.