Getting started with JRuby

January 29, 2009

This is the 2nd article in the Getting Started with JRuby on Rails tutorial series.  The entire series is as follows:

1. Introduction
2. Getting started with JRuby
3. Getting started with GlassFish
4. Restarting GlassFish
5. Getting started with load balancing (Apache)
6. Load balancing with web server redundancy (Apache)
7. Load balancing with web server failover (Apache)
8. Getting Started with Message Oriented Web Services (Java EE)
9. Setting up a local network using FireWire

Why use JRuby?  Well the quick (and philosophically correct) answer is: “Why not”.  But to be fair to you as the learned techno-adventurer you deserve a better answer.  The almost as quick answer (which is good enough justification for me) is that JRuby happens to be the language that was used to develop Rails.  End of story.  Once you have the opportunity to experience the elegance and grace of using the Rails Web 2.0 framework to develop your data-base savvy web-app, I believe you too will be a convert.  For now though, you’ll have to trust me that the learning curve is small enough and that the long-term benefits to your web-centric project is great enough to proceed…

So here we go…

For starters, I’m running on a MacBook Pro using Mac OS X Version 10.5.6 (Leopard) and using the bash terminal shell.

Download jruby-1.1.6RC1 via one of the following links:

http://dist.codehaus.org/jruby/jruby-bin-1.1.6RC1.zip
http://dist.geotools.org/jruby/jruby-bin-1.1.6RC1.zip

Move the unzipped directory to /opt/jruby-1.1.6RC1 via the following commands from within a Terminal bash window:

cd /opt
sudo mv ~/Downloads/jruby-1.1.6RC1 .

Extend the system environment variables to include JRuby.  This is done by creating (or possibly editing the existing file) ~/.bash_profile with the following command:

vi ~/.bash_profile

and add the following lines of text to the ~/.bash_profile file (the capitalizations are important):

export JRUBY_HOME=/opt/jruby-1.1.6RC1
PATH=$PATH:$JRUBY_HOME/bin

After saving and closing ~/.bash_profile, you’ll need to close the bash window and start a new one to make the modified environment variables take effect.

To verify that your environment variable changes have taken effect, execute the following command:

env

and you should see a whole bunch of environment variables listed.  Two of the listed lines should look something like:

PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/opt/jruby-1.1.6RC1/bin
JRUBY_HOME=/opt/jruby-1.1.6RC1

If perchance (as I accidentally did) you foul up the $PATH statement within ~/.bash_profile, you may inadvertently trash the $PATH environment variable (this is not a good thing).  The ability to do familiar commands such as env, ls and vi will no longer be recognized.  DONT PANIC.  Simply re-edit the ~/.bash_profile file (and don’t forget to subsequently close/open a new bash window each time) until you get it right using the extended command:

/usr/bin/vi ~/.bash_profile

To test that your JRuby is in place and your environment is correctly set up, try the following command from your home directory:

jruby -v

and if everything is copacetic you should see the JRuby version information listed out to you which looks something like:

jruby 1.1.6RC1 (ruby 1.8.6 patchlevel 114) (2008-12-03 rev 8263) [i386-java]

another insightful thing to try is the following command:

jruby –help

which will spit out something like:

-0[octal]       specify record separator (, if no argument)
-a              autosplit mode with -n or -p (splits $_ into $F)
-b              benchmark mode, times the script execution
-c              check syntax only
-Cdirectory     cd to directory, before executing your script
-d              set debugging flags (set $DEBUG to true)
-e ‘command’    one line of script. Several -e’s allowed. Omit [programfile]
-Fpattern       split() pattern for autosplit (-a)
-Idirectory     specify $LOAD_PATH directory (may be used more than once)
-J[java option] pass an option on to the JVM (e.g. -J-Xmx512m)
use –properties to list JRuby properties
run ‘java -help’ for a list of other Java options
-Kkcode         specifies code-set (e.g. -Ku for Unicode
-l              enable line ending processing
-n              assume ‘while gets(); … end’ loop around your script
-p              assume loop like -n but print line also like sed
-rlibrary       require the library, before executing your script
-s              enable some switch parsing for switches after script name
-S              look for the script in bin or using PATH environment variable
-T[level]       turn on tainting checks
-v              print version number, then turn on verbose mode
-w              turn warnings on for your script
-W[level]       set warning level; 0=silence, 1=medium, 2=verbose (default)
-X[option]      enable extended option (omit option to list)
–copyright     print the copyright
–debug         sets the execution mode most suitable for debugger functionality
–jdb           runs JRuby process under JDB
–properties    List all configuration Java properties (pass -J-Dproperty=value)
–sample        run with profiling using the JVM’s sampling profiler
–client        use the non-optimizing “client” JVM (improves startup; default)
–server        use the optimizing “server” JVM (improves perf)
–manage        enable remote JMX management and monitoring of the VM and JRuby
–headless      do not launch a GUI window, no matter what
–1.8           specify Ruby 1.8.x compatibility (default)
–1.9           specify Ruby 1.9.x compatibility
–bytecode      show the JVM bytecode produced by compiling specified code
–version       print the version

Cool, your JRuby interpreter is now successfully installed.  All we need now is some JRuby code to run.

Select an appropriate directory to house the following JRuby test file.  I like to keep all of my projects organized within project directories, one for each project.  As such, I always have a ~/Projects directory.  Therefore, in keeping with my personal directory naming style, would you be so kind as to generate and cd into the following directory using the following commands:

mkdir ~/Projects/JRuby_HelloWorld_Project
cd ~/Projects/JRuby_HelloWorld_Project

and then generate a HelloWorld.rb source file there using the following statement:

vi HelloWorld.rb

Within this new file place the following text:

require “java”
stringHello = “Hello World!”
stringDate  = java.util.Date.new
puts “#{stringHello.to_s}”
puts “Date := #{stringDate.to_s}”

Once the above HelloWorld.rb (Ruby source) file has been generated it can be run using the command:

jruby HelloWorld.rb

which generates something that looks like:

Hello World!

Date := Fri Jan 23 14:40:53 PST 2009

To sum-up what we have just done.  The third line of the Ruby source code HelloWorld.rb invoked a Java utility (java.util.Date).  This HelloWorld.rb file, in its entirety, both Java and Ruby code, was then successfully interpreted by the JRuby interpreter.  The hierarchy of the operational environments which was exercised to make this happen is graphically depicted below: