jpackage: Initialize an R package containing Java code

Description

.jpackage initializes the Java Virtual Machine (JVM) for an R package. In addition to starting the JVM it also registers Java classes and native code contained in the package with the JVM. function must be called before any rJava functions can be used.

Usage

.jpackage(name, jars='*', morePaths='', nativeLibrary=FALSE,
          lib.loc=NULL, parameters = getOption("java.parameters"),
          own.loader = FALSE)

Value

The return value is an invisible TRUE if the initialization was successful.

Arguments

name: name of the package. It should correspond to the pkgname parameter of .onLoad or .First.lib function.
jars: Java archives in the java directory of the package that should be added to the class path. The paths must be relative to package's java directory. A special value of '*' adds all .jar files from the java the directory.
morePaths: vector listing any additional entries that should be added to the class path.
nativeLibrary: a logical determining whether rJava should look for native code in the R package's shared object or not.
lib.loc: a character vector with path names of R libraries, or NULL (see system.file and examples below).
parameters: optional JVM initialization parameters which will be used if JVM is not initilized yet (see .jinit).
own.loader: if TRUE then a new, separate class loader will be initilized for the package and assigned to the .pkg.class.loader variable in the package namespace. New packages should make use of this feature.

Details

.jpackage initializes a Java R package as follows: first the JVM is initialized via .jinit (if it is not running already). Then the java directory of the package is added to the class path. Then .jpackage prepends jars with the path to the java directory of the package and adds them to the class path (or all .jar files if '*' was specified). Finally the morePaths parameter (if set) is passed to a call to .jaddClassPath.

Therefore the easiest way to create a Java package is to add .jpackage(pkgname, lib.loc=libname) in .onLoad or .First.lib, and copy all necessary classes to a JAR file(s) which is placed in the inst/java/ directory of the source package.

If a package needs special Java parameters, "java.parameters" option can be used to set them on initialization. Note, however, that Java parameters can only be used during JVM initialization and other package may have intialized JVM already.

Since rJava 0.9-14 there is support of package-specific class loaders using the own.loader=TRUE option. This is important for packages that may be using classes that conflict with other packages are therefore is highly recommended for new packages. Before this feature, there was only one global class loader which means that the class path was shared for all class look ups. If two packages use the same (fully qualified) class name, even in a dependency, they are likely to clash with each if they don't use exactly the same version. Therefore it is safer for each package use use a private class loader for its classes to guarantee that the only the classes supplied with the package will be used. To do that, a package will set own.loader=TRUE which instructs rJava to not change the global loader, but instead create a separate one for the package and assign it to .rJava.class.loader in the package namespace. Then if package wants to instantiate a new class, it would use .jnew("myClass", class.loader=.rJava.class.loader) to use its own loader instead of the global one. The global loader's class path won't be touched, so it won't find the package's classes. It is possible to get the loader used in a package using .jclassLoader(package="foo") which will return the global one if the package has not registered its own. Similarly, to retrieve the class path used by a package, one would use .jclassPath(.jclassLoader(package="foo")).

Note that with the advent of multiple class loaders the value of the java.class.path property is no longer meaningful as it can reflect only one of the loaders.

Examples

Run this code

if (FALSE) {
.onLoad <- function(libname, pkgname) {
  .jpackage(pkgname, lib.loc=libname, own.loader=TRUE)
  ## do not use, just an illustration of the concept:
  cat("my Java class path: ")
  print(.jclassPath(.jclassLoader(package=pkgname)))
}
}