Preparing a .jar archive for use

Getting back to our example with running the main method of our HelloWorldDummy class from the first part of this primer, in practice we most likely want to actually create objects and invoke methods for such classes rather than simply call the main method.

For our resources to be available to rJava, we need to create a .jar archive and add it to the class path. An example of the process can be as follows. Compile our code to create the class file, and jar it:

$ javac DummyJavaClassJustForFun/HelloWorldDummy.java
$ cd DummyJavaClassJustForFun/
$ jar cvf HelloWorldDummy.jar HelloWorldDummy.class

Adding the .jar file to the class path

Within R, attach rJava, initialize the JVM and investigate our current class path using .jclassPath:

library(rJava)
.jinit()
.jclassPath()

Now, we add our newly created .jar to the class path using .jaddClassPath:

.jaddClassPath(paste0(jardir, "HelloWorldDummy.jar"))

If this worked, we can see the added jar(s) in the class path if we call .jclassPath() again.

Creating objects, investigating methods and fields

Now that we have our .jar in the class path, we can create a new Java object from our class:

dummyObj <- .jnew("DummyJavaClassJustForFun/HelloWorldDummy")
str(dummyObj)
## Formal class 'jobjRef' [package "rJava"] with 2 slots
##   ..@ jobj  :<externalptr> 
##   ..@ jclass: chr "DummyJavaClassJustForFun/HelloWorldDummy"

We can also investigate the available constructors, methods and fields for our class (or provide the object as argument, then its class will be queried):

• .jconstructors returns a character vector with all constructors for a given class or object
• .jmethods returns a character vector with all methods for a given class or object
• .jfields returns a character vector with all fields (aka attributes) for a given class or object
• .DollarNames returns all fields and methods associated with the object. Method names are followed by ( or () depending on arity.

# Requesting vectors of methods, constructors and fields by class
.jmethods("DummyJavaClassJustForFun/HelloWorldDummy")
##  [1] "public java.lang.String DummyJavaClassJustForFun.HelloWorldDummy.SayMyName()"              
##  [2] "public static void DummyJavaClassJustForFun.HelloWorldDummy.main(java.lang.String[])"      
##  [3] "public final void java.lang.Object.wait(long,int) throws java.lang.InterruptedException"   
##  [4] "public final native void java.lang.Object.wait(long) throws java.lang.InterruptedException"
##  [5] "public final void java.lang.Object.wait() throws java.lang.InterruptedException"           
##  [6] "public boolean java.lang.Object.equals(java.lang.Object)"                                  
##  [7] "public java.lang.String java.lang.Object.toString()"                                       
##  [8] "public native int java.lang.Object.hashCode()"                                             
##  [9] "public final native java.lang.Class java.lang.Object.getClass()"                           
## [10] "public final native void java.lang.Object.notify()"                                        
## [11] "public final native void java.lang.Object.notifyAll()"
.jconstructors("DummyJavaClassJustForFun/HelloWorldDummy")
## [1] "public DummyJavaClassJustForFun.HelloWorldDummy()"
.jfields("DummyJavaClassJustForFun/HelloWorldDummy")
## NULL
# Requesting vectors of methods, constructors and fields by object
.jmethods(dummyObj)
##  [1] "public java.lang.String DummyJavaClassJustForFun.HelloWorldDummy.SayMyName()"              
##  [2] "public static void DummyJavaClassJustForFun.HelloWorldDummy.main(java.lang.String[])"      
##  [3] "public final void java.lang.Object.wait(long,int) throws java.lang.InterruptedException"   
##  [4] "public final native void java.lang.Object.wait(long) throws java.lang.InterruptedException"
##  [5] "public final void java.lang.Object.wait() throws java.lang.InterruptedException"           
##  [6] "public boolean java.lang.Object.equals(java.lang.Object)"                                  
##  [7] "public java.lang.String java.lang.Object.toString()"                                       
##  [8] "public native int java.lang.Object.hashCode()"                                             
##  [9] "public final native java.lang.Class java.lang.Object.getClass()"                           
## [10] "public final native void java.lang.Object.notify()"                                        
## [11] "public final native void java.lang.Object.notifyAll()"
.jconstructors(dummyObj)
## [1] "public DummyJavaClassJustForFun.HelloWorldDummy()"
.jfields(dummyObj)
## NULL

Calling methods 3 different ways

We can now invoke our SayMyName method on this object in the three ways as discussed is the first part of this primer:

# low level
lres <- .jcall(dummyObj, "Ljava/lang/String;", "SayMyName")

# high level
hres <- J(dummyObj, method = "SayMyName") 

# convenient $ shorthand
dres <- dummyObj$SayMyName() 

c(lres, hres, dres)
## [1] "My name is DummyJavaClassJustForFun.HelloWorldDummy"
## [2] "My name is DummyJavaClassJustForFun.HelloWorldDummy"
## [3] "My name is DummyJavaClassJustForFun.HelloWorldDummy"

Setting java.parameters

The .jpackage function calls .jinit with the default parameters = getOption("java.parameters"), so if we want to set some of the java parameters, we can do it for example like so:

.onLoad <- function(libname, pkgname) {
  options(java.parameters = c("-Xmx1000m"))
  .jpackage(pkgname, lib.loc = libname)
}

Note that the options call needs to be done before the call to .jpackage, as Java parameters can only be used during JVM initialization. Consequently, this will only work if other package did not intialize the JVM already.