JRI

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).

Please report any bugs or wishes related to rJava or JRI using the Bugzilla for rJava.

Important: JRI is now part of rJava, so if you simply want to use JRI, install rJava binary and your'e all set! There will be no further stand-alone JRI releases, JRI is now released only as a part of rJava.
To locate JRI installed with rJava, use system.file("jri",package="rJava") in R.

What's new?

See rJava pages for latest release information.

Download

Current release: JRI 0.5-0 - available as a part of rJava

The best source for the latest stand-alone JRI (without rJava) is the SVN or files section.

Documentation

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

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

Installation

JRI comes bundled with rJava, so the best way is to simply install rJava. It is available from CRAN, so you can use

install.packages("rJava")

in R.

You can also build JRI from sources of the JRI tar ball if desired as follows:

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 and for 64-bit Linux JDK 2.6 is required). 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!