Lehrstuhl fuer Rechnerorientierte Statistik und Datenanalyse Uni Augsburg  
Institut Forschung Lehre Mitarbeiter News Allgemeines Research Staff Software
JRI

About JRI

printable form

About JRI

Note: JRI is now part of rJava and the official rJava development page has moved to rJava project at RForge.net

What is JRI?
        

JRI is a Java/R Interface, which allows to run R inside Java applications as a single thread. Basically it loads R dynamic library into Java and provides a Java API to R functionality. It supports both simple calls to R functions and a full running REPL.

In a sense JRI is the inverse of rJava and both can be combined (i.e. you can run R code inside JRI that calls back to the JVM via rJava). The JGR project makes the full use of both JRI and rJava to provide a full Java GUI for R.

JRI uses native code, but it supports all platforms where Sun's Java (or compatible) is available, including Windows, Mac OS X, Sun and Linux (both 32-bit and 64-bit).

What's new?
2005/05/06 - JRI 0.2-4 released. JRI is now also supplied as a part of rJava 0.4 on CRAN.

2005/12/19 - JRI 0.2-0 is released.
The new JRI uses autoconf to detect Java and R. It also adds support for 64-bit platforms. The Java-side API does not change, so it still reports 0x103 as API version number.

2005/05/09 - JRI 0.1-3 is released
Added support for R 2.1.x and removed dependency on R sources alltogether. Examples have been cleaned up.

Download

Current release: JRI_0.2-4.tar.gz

The best source for the latest JRI is the nightly builds page (at the bottom).

Documentation

Most functions are documented by JavaDoc (see org.rosuda.JRI). For documentation concerning the installation, see the following sections.

There are simple examples in the examples directory of the tar ball.

Installation
Binaries of JRI come with JGR so that is one alternative. Another is to build JRI yourself from the sources and here is how:

Unix platforms (incl. Mac OS X)
Since the 0.2 release, installation follows the standard autoconf pattern:

./configure
make
You will need R 2.x and JDK 1.4 or later (for Linux JDK 1.5 is required due to fatal bugs in JDK 1.4). The configure script attempts to find a working JDK and R - both should be on your PATH preferably (i.e. typing java and R should both work). If the auto-detection doesn't work, you can set JAVA_HOME and/or R_HOME variables correspondingly.

To run the supplied examples, you can type

./run rtest
./run rtest2

If you have your own code, you can set CLASSPATH variable accordingly and use the run script to launch your code.

Windows
On Windows you will need the same tools necesasry for building R in order to build JRI (i.e. MinGW and the /bin toolset to the least). The you can use

sh configure.win
make
to build JRI. Again, the configuration is fully automatic (you will need R registry entries, but those are present if you installed R using the Windows installer with default settings). You can set the same variaibles as in the unix case, because the building process is identical. As a part of the make process a run script run.bat is generated. It is recommended to use the script or its variations when starting your JRI programs.

For more enhanced launcher strategy, see JGR launcher for Windows that automatically detects the paths to R and JRE.

FAQ
Q:...
A:Hold on, did you actually notice the README file? No? Well, please, have a look at it, too.

Q: There are no examples!
A: There actually are examples in the examples directory of JRI and they are even compiled by default so you can try them right away.

Q: Do I need a good knowledge of R to use JRI?
A: JRI version 0.2 and earlier provide low-level API only, which is comparable to the C API that R provides. This implies that at least some knowledge of R internals is required.
However, JRI version 0.3 introduces higher-level API which you may be familiar with from the JRclient of Rserve. Unless you want to use more advanced features of JRI (such as running the event loop and registering own callbacks), basic knowledge of R should be sufficient.

Q: I get the following error, what's wrong?
java.lang.UnsatisfiedLinkError: no jri in java.library.path
A: Usually it means that you didn't setup the necessary environment variables properly or the JRI library is not where it is expected to be. The recommended way to start JRI programs is to use the run script which is generated along with the library. It sets everything up and is tested to work. If you want to write your own script or launcher, you must observe at least the following points:
  • R_HOME must be set correctly
  • (Windows): The directory containing R.dll must be in your PATH
  • (Mac): Well, it's a Mac, so it just works ;).
  • (unix): R must be compiled using --enable-R-shlib and the directory containing libR.so must be in LD_LIBRARY_PATH. Also libjvm.so and other dependent Java libraries must be on LD_LIBRARY_PATH.
  • JRI library must be in the current directory or any directory listed in java.library.path. Alternatively you can specify its path with
    -Djava.library.path= when starting the JVM. When you use the latter, make sure you check java.library.path property first such that you won't break your Java.
  • Depending on your system, the R verison and other features you want to use, you may have to set additional settings such as R_SHARE_DIR, R_INCLUDE_DIR and R_DOC_DIR.
Again, I don't think you want to worry about all of the above - just use the start script!

Last updated: 2006/06/13


[Institut] [Forschung] [Lehre] [Mitarbeiter] [News] [Allgemeines] [Software]