| jpackage {rJava} | R Documentation |
.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.
.jpackage(name, jars='*', morePaths='', nativeLibrary=FALSE,
lib.loc=NULL, parameters = getOption("java.parameters"),
own.loader = FALSE)
name |
name of the package. It should correspond to the
|
jars |
Java archives in the |
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
|
parameters |
optional JVM initialization parameters which will be
used if JVM is not initilized yet (see |
own.loader |
if |
.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.
The return value is an invisible TRUE if the initialization was successful.
## Not run:
.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)))
}
## End(Not run)