Adhearsion using JRuby

As of this writing, getting Adhearsion to run under JRuby requires a slight modification to one of the files in your project. I will be digging in and following up with the JRuby developers to find out more information. Feel free to update this documentation if you are able to get Adhearsion to run without the minor tweak to the .ahnrc file fix mentioned below.

 

The fact that we can run Adhearsion from within the Java JVM open up a whole wealth of opportunity for Adhearsion in terms of leveraging libaries and being accepted and run in corporate environments. To summarize, what we will cover, here are the steps that I will be following:

 

1. Download and install JRuby.

2. Checkout Adhearsion from Subversion.

3. Create a "jahn" (jan) script that uses the JRuby interpreter.

5. Create an Adhearsion project using JRuby.

4. Modify the .ahnrc file to work with JRuby.

6. Modify the dialplan.rb to call out a Java library.

7. Run our application!

 

OK, now that we have the steps down, let's get down to business.

 

Download JRuby

From the JRuby website - JRuby is an 100% pure-Java implementation of the Ruby programming language. It therefore allows you to run Ruby scripts within the JVM. Steps on downloading and configuring JRuby are pretty straightforward. You will want to either get the lastest from SVN or else the latest distribution from the website.

 

All of the dertails can be found at:

 

http://jruby.codehaus.org/

 

After you have downloaded an installed JRuby the next step is to get the latest version of Adhearsion.

Checkout Adhearsion

Some people prefer to use the Adhearsion Gem, but I'd much rather enjoy the benefits of having the latest and greatest code. Therefore, to do that you'll need to checkout the code from Subversion. To checkout Adhearsion, you'll need a subversion client and issue the following command.

 

> svn checkout svn://rubyforge.org/var/svn/adhearsion

 

This will checkout all of the latest Adhearsion code and put it into a directory called "adhearsion" in your current directory with a directory call "trunk" with all of the code inside of it.

 

Create "jahn"

 

The next step is to create a script that will allow you to run the JRuby interpreter when running Adhearsion. The easiest way to do this is to create another launch script that calls JRuby. Look in the directory where you checked out Adhearsion to. You see a file at "trunk/bin/ahn". Copy this file in the same directory and name it to "trunk/bin/jahn".

 

Next, we'll open up the file and change the first line to:

 

#!/usr/bin/env jruby

 

this tells jruby that it should be invoked when this script is executed.

 

Create a project using JRuby

Now it's time to create a project using JRuby. Execute the command to call our "jahn" script passing in "create" and the project name. Use the path to your Adhearsion install and execute something like:

 

>[ADHEARSION_INSTALL_PATH]/bin/jahn create adhearsion_with_jruby

 

NOTE: If this a fresh install of JRuby there most likely will be some Gems that will need to be installed. Follow the steps of installing the Gems using the: jruby gem install XXXX command. Keep installing the gems that it asks for when creating the project. Once you have an adhearsion project created, you may move on to the next step.

 

Modify .ahnrc file

If you try and start up you project with:

 

>[ADHEARSION_INSTALL_PATH]/bin/jahn start adhearsion_with_jruby

 

You may seen an error similar to:

 

/Users/justin/development/adhearsion/trunk/lib/adhearsion/initializer.rb:198:in `get_rules_from': ScannerException while scanning an alias we had this expected alphabetic or numeric character, but found something else... (ArgumentError)

    from /Users/justin/development/adhearsion/trunk/lib/adhearsion/initializer.rb:198:in `bootstrap_rc'

    from /Users/justin/development/adhearsion/trunk/lib/adhearsion/initializer.rb:92:in `initialize'

    from /Users/justin/development/adhearsion/trunk/lib/adhearsion/cli.rb:70:in `new'

    from /Users/justin/development/adhearsion/trunk/lib/adhearsion/cli.rb:70:in `start'

    from /Users/justin/development/adhearsion/trunk/lib/adhearsion/cli.rb:18:in `execute!'

    from /Users/justin/development/adhearsion/trunk/bin/jahn:28

 

This is the step that will eventually be able to be eliminated, but for now one solution is to change the "*" in the .ahnrc file. So open up the .ahnrc file and replace all of the occurances of "*" with "\*". This will fix your problem.

 

Now, starting your application with

 

>[ADHEARSION_INSTALL_PATH]/bin/jahn start adhearsion_with_jruby

 

should work just fine and you'll get:

 

INFO ahn: Adhearsion initialized!

 

in the console. We are now running Adhearsion under JRuby!

 

 

Modify the dailplan.rb to call Java Library

Change into the adhearsion_with_jruby directory and open up the diaplan.rb file.

 

 

Let's try for fun, printing the current Java date in our diallan.rb using JRuby. 

 

Change your diaplan.rb to read.

 

-- dialplan.rb --

require 'java'

include_class java.util.Date

rumpresentation {

  d = Date.new

  p "Today's date is #{d}"

  simon = new_simon_game

  simon.start

}

--

 

So what is going on here? Well, since we are using JRuby, we should be able to pull in a very simple Date class and output it to the console. I'm assuming you already have configured a phone and the basics in the extensions.conf. After you make the changes to dialplan.rb, restart Adhearsion with the command.

 

>[ADHEARSION_INSTALL_PATH]/bin/jahn start adhearsion_with_jruby

Test the Application!

Finally, make a phone into the Asterisk context that will redirect calls to your Adhearsion process. You should see something similar to the following in the console, which shows that Adhearsion is being called and exercised.

 

The following line will be output:

"Date is Thu Apr 17 00:26:34 CDT 2008"

 

which proves that the dialplan.rb is JRuby aware!

Conculsion

The fact that we just showed the Java Date implementation is a big step in the right direction, it proves that we can load Java classes into our dialplan and leverage Java or any of our heavy lifting. Additionally, the fact that JRuby is run in the JVM means that it should scale and perform as well as any other process that is run within the JVM. This means high availability and a wealth of libraries the we have access to from within Adhearsion. Very powerful stuff!