[SPARK-16581][SPARKR] Make JVM backend calling functions public

R/pkg/NAMESPACE

@@ -363,4 +363,9 @@ S3method(structField, jobj)
 S3method(structType, jobj)
 S3method(structType, structField)
 
+export("newJObject")
+export("callJMethod")
+export("callJStatic")
+export("cleanup.jobj")
+
 export("install.spark")

R/pkg/R/backend.R

@@ -25,9 +25,23 @@ isInstanceOf <- function(jobj, className) {
   callJMethod(cls, "isInstance", jobj)
 }
 
-# Call a Java method named methodName on the object
-# specified by objId. objId should be a "jobj" returned
-# from the SparkRBackend.
+#' Call Java Methods
+#'
+#' Call a Java method in the JVM running the Spark driver.
+#'
+#' @param objId object to invoke the method on. Should be a "jobj" created by newJObject.
+#' @param methodName method name to call.
+#' @param ... parameters to pass to the Java method.
+#' @export
+#' @seealso callJStatic, newJObject
+#' @examples
+#' \dontrun{
+#' sparkR.session() # Need to have a Spark JVM running before calling newJObject
+#' # Create a Java ArrayList and populate it
+#' jarray <- newJObject("java.util.ArrayList")
+#' callJMethod(jarray, "add", 42L)
+#' callJMethod(jarray, "get", 0L) # Will print 42
+#' }
 callJMethod <- function(objId, methodName, ...) {
   stopifnot(class(objId) == "jobj")
   if (!isValidJobj(objId)) {
@@ -37,12 +51,42 @@ callJMethod <- function(objId, methodName, ...) {
   invokeJava(isStatic = FALSE, objId$id, methodName, ...)
 }
 
-# Call a static method on a specified className
+#' Call Static Java Methods
+#'
+#' Call a static method in the JVM running the Spark driver.
+#'
+#' @param className class containing the static method to invoke.
+#' @param methodName name of static method to invoke.
+#' @param ... parameters to pass to the Java method.
+#' @export
+#' @seealso callJMethod, newJObject
+#' @examples
+#' \dontrun{
+#' sparkR.session() # Need to have a Spark JVM running before calling callJStatic
+#' callJStatic("java.lang.System", "currentTimeMillis")
+#' callJStatic("java.lang.System", "getProperty", "java.home")
+#' }
 callJStatic <- function(className, methodName, ...) {
   invokeJava(isStatic = TRUE, className, methodName, ...)
 }
 
-# Create a new object of the specified class name
+#' Create Java Objects
+#'
+#' Create a new Java object in the JVM running the Spark driver.
+#'
+#' @param className name of the class to create
+#' @param ... arguments to be passed to the constructor
+#' @export
+#' @seealso callJMethod, callJStatic
+#' @examples
+#' \dontrun{
+#' sparkR.session() # Need to have a Spark JVM running before calling newJObject
+#' # Create a Java ArrayList and populate it
+#' jarray <- newJObject("java.util.ArrayList")
+#' callJMethod(jarray, "add", 42L)
+#' callJMethod(jarray, "get", 0L) # Will print 42
+#' }
+#' @note newJObject since 2.0.1
 newJObject <- function(className, ...) {
   invokeJava(isStatic = TRUE, className, methodName = "<init>", ...)
 }

R/pkg/R/jobj.R

@@ -82,7 +82,20 @@ getClassName.jobj <- function(x) {
   callJMethod(cls, "getName")
 }
 
-cleanup.jobj <- function(jobj) {
+#' Garbage collect Java Objects
+#'
+#' Garbage collect an object allocated on Spark driver JVM heap.
+#'
+#' cleanup.jobj is a low level method that lets developers manually garbage collect objects
+#' allocated using newJObject. This is only to be used for advanced use cases as objects allocated
+#' on the JVM heap are automatically garbage collected when the corresponding R reference goes out
+#' of scope.
+#'
+#' @param x the Java object that should be garbage collected.
+#' @note cleanup.jobj since 2.0.1
+#' @export
+cleanup.jobj <- function(x) {
+  jobj <- x
   if (isValidJobj(jobj)) {
     objId <- jobj$id
     # If we don't know anything about this jobj, ignore it

R/pkg/inst/tests/testthat/test_jvm_api.R

@@ -0,0 +1,41 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+context("JVM API")
+
+sparkSession <- sparkR.session(enableHiveSupport = FALSE)
+
+test_that("Create and call methods on object", {
+  jarr <- newJObject("java.util.ArrayList")
+  # Add an element to the array
+  callJMethod(jarr, "add", 1L)
+  # Check if get returns the same element
+  expect_equal(callJMethod(jarr, "get", 0L), 1L)
+})
+
+test_that("Call static methods", {
+  # Convert a boolean to a string
+  strTrue <- callJStatic("java.lang.String", "valueOf", TRUE)
+  expect_equal(strTrue, "true")
+})
+
+test_that("Manually garbage collect objects", {
+  jarr <- newJObject("java.util.ArrayList")
+  cleanup.jobj(jarr)
+  # Using a jobj after GC should throw an error
+  expect_error(print(jarr), "Error in invokeJava.*")
+})