rjni: Java binding for Ruby through JNI

What is rjni?

rjni exposes the Java Native Interface to Ruby. This allows the programmer to instantiate Java objects, manipulate them, define Java classes, etc.. from Ruby.

Note that rjni is not meant to embed Ruby into Java, although it can be used to ease integration in that case.

License

For the time being, the same as Ruby. Might switch to LGPL in the future.

Feedback

Please don’t hesitate to contact me to criticize, suggest new features or help with the development :)

Status

• The APIs are quickly stabilizing.
• The base layer still needs some work and further testing.
• Several low-level issues remain to be solved.
• The higher-level APIs have yet to be documented and tested rigorously.

Current features

• almost complete mapping of JNI to Ruby
• functional mapping of java.lang.reflect
• Java exceptions are caught and transformed into Ruby’s
• automagic reflection:
  • getting metaclass objects representing classes
  • Java object instantiation from Ruby
  • static methods become class singleton methods
  • Java method dispatching from Ruby considers overloading
  • some basic type conversions (String <=> java.lang.String, etc…)
  • automatic accessors for fields:
    • readers: javaobject.field?
    • setters: javaobject.field = value

Download

Get the sources.

WARNING: THIS IS A TECHNOLOGY PREVIEW. THE SOFTWARE IS NOT EVEN ALPHA QUALITY AT THE MOMENT AND IS NOT MEANT TO BE USED YET. IT IS ONLY PROVIDED TO PRESENT THE TECHNIQUES EMPLOYED AND (HOPEFULLY) TO ACCELERATE THE DEVELOPMENT.

Documentation

Please refer to the current documentation.

Building

This technology preview is meant to illustrate the possibilities offered by rjni. It is by no means a usable library yet. The build process is quite tricky, as it involves linking against the Java libraries and is therefore highly system-dependent.

The steps are:

1. Setting up build environment

     ruby install.rb config
   

   You might need to specify the location of your J2SDK with the following options:

     ruby install.rb config \
      --jsdk-include=/usr/local/java/j2sdk1.4.1/include/ \
      --jsdk-lib=/usr/local/java/j2sdk1.4.1/jre/lib/i386/ \
          --jsdk-so-include=/usr/local/java/j2sdk1.4.1/include/linux/
   

   You have to replace the paths above by the appropriate values for your local Java installation. Note that rjni has been tested with Blackdown 1.4.1, and, although it should be possible to build it with other JSDKs, compilation and/or linking might fail unless you get the above options right (or end up modifying the Makefiles by hand).

2. Compiling & installing

     ruby install.rb setup
     ruby install.rb install
   

3. You can now run the the tests and examples in test/ and examples/ You will notice a short pause after the execution of the scripts. This is normal and expected at the moment. Sometimes a ruby might stay around after termination of the script; you can kill it manually.

Problems

Execution

Sometimes ld.so will be unable to resolve symbols at runtime; you will then need to set the LD_LIBRARY_PATH environment variable to some sensible value.

API

rjni offers the following 3 API:

RJNI

a low-level straight-forward mapping of the Java Native Interface to Ruby. All operations on Java objects and classes are ultimately performed through this layer.

RJNI::Java

a direct conversion of java.lang.reflect and associated classes to Ruby. It is built upon RJNI. Usage of this API is not recommended since it offers no significant advantages against the 2 others, and is fairly slow.

RJNI::Reflect

magic reflection of Java objects to Ruby, such that they can seemingly be manipulated exactly like Ruby objects. This involves automatic method dispatching, singleton class abstraction (static methods become singleton methods of the class object), some automatic type conversions, attribute setters and getters, etc.