Initialize Java VM

.jinit initializes the Java Virtual Machine (JVM). This function must be called before any rJava functions can be used.

.jvmState() returns the state of the current JVM.

Usage

.jinit(classpath = NULL, parameters = getOption("java.parameters", NA), ...,
       silent = FALSE, force.init = FALSE)
.jvmState()

Arguments

classpath

Any additional classes to include in the Java class paths (i.e. locations of Java classes to use). This path will be prepended to paths specified in the CLASSPATH environment variable. Do NOT set this system class path initializing a package, use .jpackage instead, see details.

parameters

character vector of parameters to be passed to the virtual machine. They are implementation dependent and apply to JDK version 1.2 or higher only. Please note that each parameter must be in a separate element of the array, you cannot use a space-separated string with multiple parameters. The value of NA means "use rJava default" which is "-Xmx1g" currently. NULL is equivalent to character().

...

Other optional Java initialization parameters (implementation-dependent).

silent

If set to TRUE no warnings are issued.

force.init

If set to TRUE JVM is re-initialized even if it is already running.

Value

The return value is an integer specifying whether and how the VM was initialized. Negative values indicate failure, zero denotes successful initialization and positive values signify partially successful initilization (i.e. the VM is up, but parameters or class path could not be set due to an existing or incompatible VM).

.jvmState returns a named list with at least the following elements:

initialized

TRUE if rJava is initialized and has a runing JVM, FALSE otherwise.

state

string representing the current state of the JVM. One of the following values: "none" if there is no JVM, "created" if the current JVM has been created by rJava, "attached" if rJava attached into an existing JVM (typically when R is embedded into a running JVM via JRI), "detached" if there is a JVM (such as embedded R), but rJava has not been initialized to use it, "dead" if the process is about to die due to the JVM forcing en exit or "destroyed" if a JVM existed before, but was destroyed.

Details

Starting with version 0.5 rJava provides a custom class loader that can automatically track classes and native libraries that are provided in R packages. Therefore R packages should NOT use .jinit, but call .jpackage instead. In addition this allows the use of class path modifying function .jaddClassPath.

Important note: if a class is found on the system class path (i.e. on the classpath specified to .jinit) then the system class loader is used instead of the rJava loader, which can lead to problems with reflection and native library support is not enabled. Therefore it is highly recommended to use .jpackage or .jaddClassPath instead of classpath (save for system classes).

Stating with version 0.3-8 rJava is now capable of modifying the class path on the fly for certain Sun-based Java virtual machines, even when attaching to an existing VM. However, this is done by exploiting the way ClassLoader is implemented and may fail in the future. In general it is officially not possible to change the class path of a running VM.

At any rate, it is impossible to change any other VM parameters of a running VM, so when using .jinit in a package, be generous with limits and don't use VM parameters to unnecessarily restrict resources (or preferably use .jpackage instead). JVM parameters can only be set if the initial state of the JVM is "none".

There is a subtle difference between "initialized" and the JVM state. It is in theory possible for "initialized" to be FALSE and still "state" to be "created" or "attached" in case where JVM was created but rJava has not been able to initialize for other reasons, although such state should be rare and problematic in either case. Behavior of rJava functions other than .jinit and .jvmState is undefined unless .jvmState()$initialized is TRUE.

NOTE: .jinit() can be called implicitly by other functions such as .jpackage or J.

See also

.jpackage

Examples

if (FALSE) { # \dontrun{
## set heap size limit to 512MB (see java -X)
.jinit(parameters="-Xmx512m")
.jvmState()
} # }