Oracle GlassFish Server 3.0.1 Scripting Framework Guide

Configuring JRuby for GlassFish Server

After performing the basic installation, you can further configure several aspects of JRuby to work with GlassFish Server:

Configuring the JRuby Container

The GlassFish Server asadmin configure-jruby-container subcommand provides several options for configuring a JRuby container. Changes made to a JRuby container using the configure-jruby-container subcommand are written to the GlassFish Server domain's domain.xml file, which makes the changes persistent.

The general syntax for configuring the JRuby container is:

asadmin configure-jruby-container --property=value

For example, the following command sets the jruby-home property:

asadmin configure-jruby-container --jruby-home=jruby-install

Table 1–1 lists the options provided by the asdmin configure-jruby-container subcommand.

Table 1–1 asdmin configure-jruby-container Options


Option	Description
`--help` `\|` `-?`	Displays the help text for the subcommand.
`--monitoring`	If set to `true`, enables monitoring for the JRuby container. The default is `false`.
`--jruby-home`	The directory in which JRuby itself (not the GlassFish Server JRuby container) is installed. The specified directory must exist or an error will occur. Note, however, that the `configure-jruby-container` subcommand does not check whether JRuby is installed in the directory. The default directory is `as-install/jruby`, which is the directory in which Update Tool installs JRuby. Therefore, if you obtained JRuby from Update Tool, this option is not required.
`--jruby-runtime`	The initial number of JRuby runtime instances in the pool. This number must be greater than `0`, greater than or equal to `--jruby-runtime-min`, and less than or equal to `--jruby-runtime-max`. The default is `1`.
`--jruby-runtime-min`	The minimum number of JRuby runtime instances in the pool. This number must be greater than `0`, and less than or equal to `--jruby-runtime` and `--jruby-runtime-max`. The pool will always be at least this large, but can also be larger. The default is `1`.
`--jruby-runtime-max`	The maximum number of JRuby runtime instances in the pool. This number must be greater than `0`, and greater than or equal to `--jruby-runtime` and `--ruby-runtime-min`. The default is `1`. Setting this value too high can cause `OutOfMemory` errors, either in the heap or `PermGen`.
`--show`	If set to `true`, displays the current settings of the Enterprise Server JRuby container. The default is `true`.

For additional information about the asadmin JRuby configuration options, see the configure-jruby-container(1) man page.

Configuring JRuby Deployment Options

You can change deployment-specific options for the JRuby application using the following command syntax:

asadmin deploy --property property=value[:property=value]

For example, the following command deploys an application using a JRuby instance that is different from the one configured for the GlassFish Server instance:

asadmin deploy --property jruby-home=latest-jruby-install application

See the Appendix A, The asadmin Deployment Subcommands, in Oracle GlassFish Server 3.0.1 Application Deployment Guide for detailed instructions on using the extensive list of asadmin deploy options to deploy applications, including JRuby, on GlassFish Server.

Configuring the JRuby Runtime Pool

GlassFish Server 3.0.1 provides a JRuby runtime pool to enable the servicing of multiple concurrent requests. It should be noted, however, that Rails is not currently thread-safe, and while JRuby is able to take advantage of Java's native threading, Rails cannot benefit from it. Each JRuby runtime runs a single instance of Rails, and requests are handed off to whichever instance happens to be available at the time of the request.

See Table 1–1 for descriptions of the JRuby runtime pool options.

The following are some important points to remember when configuring the JRuby runtime pool:

To allow consistent and fast runtime access for the requesting applications, the dynamic runtime pool maintains itself with the minimum number of runtimes possible. The pool may take an initial runtime value, but that value is not used after pool creation.
The JRuby runtime pool values can be set either at the container level or at deploy time:
- To set the runtime pool values at the container level, use the asadmin configure-jruby-container subcommand, as described in Configuring the JRuby Container.
- To set the runtime pool values at deploy time, use the asadmin deploy subcommand, as described in Configuring JRuby Deployment Options.
Runtime pool properties can be set simultaneously at both the container level and at deploy time. If both settings are used, the deploy runtime settings take precedence over the container runtime settings.

Configuring the JRuby Container Through GlassFish Server Administration Console

You can use the GlassFish Server Administration Console to configure a subset of JRuby container options:

JRuby Home
Initial Pool Size
Minimum Pool Size
Maximum Pool Size

These options are the same as those described in Table 1–1.

Note –

When configured through the Administration Console, these settings apply to the currently running GlassFish Server instance only. When the instance is shut down, the changes will be lost. To make your changes persistent from instance to instance, use the asadmin configure-jruby-container command instead.

For complete information about using the GlassFish Server Administration Console, see Administration Console in Oracle GlassFish Server 3.0.1 Administration Guide.

To Configure JRuby Container from the GlassFish ServerAdministration Console

The following procedure explains how to access a JRuby Container from the GlassFish Server Administration Console.

Open the GlassFish Server Administration Console from a Web browser.

For example:
http://localhost:4848

Log in to the Administration Console, if configured for secure login.

Depending on your GlassFish Server configuration, your Administration Console may not require login credentials.

Select Common Tasks->Configuration->JRuby Container from the tree in the panel on the left side of the Administration Console.

Change JRuby Container properties, as desired, in the Details panel.

See Configuring the JRuby Container for explanations of JRuby container properties. For detailed descriptions of the JRuby configuration options, see the configure-jruby-container(1) man page.