.JavaCall
Call Java Methods and Constructors

### Description

Calls a Java constructor to create a Java object reference, or calls a method on a Java object reference.

### Usage

    .JavaNew(javaClass, ..., SIGNATURE=NULL)
    .JavaCall(object, method, ..., SIGNATURE=NULL, SIMPLIFY=TRUE)

### Arguments

javaClass | a string specifying a full Java classname, such as "Ljava/lang/Math;". This class can also be specified as "java/lang/Math" or "java.lang.Math".
object | any object, including a Java object reference. If object is a string, it should be a Java class name, and .JavaCall calls a static method on this class.
method | a string naming a method within the class.
... | zero or more arguments to pass to the Java method or constructor. These arguments can be simple data values such as numeric vectors, or they can be Java object reference objects.
SIGNATURE | a string describing the method or constructor argument types and the return type.
SIMPLIFY | a logical value. If TRUE (the default), specifies that .JavaCall should call .JavaSimplify to attempt to convert the return value from a Java object reference to a simpler object, such as converting a Java double array to a double vector.

### Details

These functions can create arbitrary Java objects, and then call object and static methods on them, passing simple arguments and other Java objects as their arguments. This design lifts the restriction of .JavaMethod, which can call only static methods with a limited set of simple argument types.
Java objects are specified via "Java Object Reference" objects with class terrJavaRef, which represent a reference to a Java object in the JVM.

- If the SIGNATURE argument is specified, this must be a "JNI method descriptor" string that specifies the types of the method arguments and the method return type that can specify arbitrary Java classes, such as "(D[Ljava/lang/String;)Ljava/lang/Object;" for a method taking a double and an array of strings, and returning a general Java object.
- If the SIGNATURE argument is not specified, .JavaFindMethodSignature is called to find an appropriate signature, given the types of the arguments passed to the method. If you know the exact signature of the method desired, it is best to specify it. In particular, the SIGNATURE argument must be given to access non-public methods.

The .JavaAttachClassPath function allows adding additional Java class files to be searched when creating objects and calling methods.
Value

.JavaNew | returns a Java object reference to the new Java object created.
.JavaCall | returns the value of the method called, which is either a Java object reference, or a simpler data value (if this is possible, and the SIMPLIFY argument is TRUE).

See Also
.JavaArray, .JavaClass, .JavaRef, .JavaFieldGet, .JavaSimplify, .JavaFindMethodSignature, .JavaAttachClassPath, .JavaMethod
Examples

    ## create a Java object reference to string
    xx <- .JavaNew("java.lang.String", as.raw(c(0x61,0x62,0x63)), "UTF-8")
    .JavaSimplify(xx) ## simplify to string "abc"
    ## call a Java static method taking two doubles,
    ## and returning the double value 1024
    .JavaCall("java/lang/Math", "pow", 2, 10)
    ## Create a HashMap object, and add some strings
    xx <- .JavaNew("java.util.HashMap")
    .JavaCall(xx, "put", "a", "aval")
    .JavaCall(xx, "put", "b", "bval")
    .JavaCall(xx, "get", "a") ## returns "aval"
    .JavaCall(xx, "get", "b") ## returns "bval"
    .JavaCall(xx, "get", "c") ## returns NULL
    ## call a static method specifying the signature
    xx <- .JavaCall("java.util.Arrays", "copyOf", LETTERS, 4L,
              SIGNATURE="([Ljava/lang/Object;I)[Ljava/lang/Object;",
              SIMPLIFY=FALSE)
    ## returned object class is "[Ljava.lang.String;"
    .JavaClass(xx)
    ## simplify to string vector: [1] "A" "B" "C" "D"
    .JavaSimplify(xx)

Package terrJava version 6.1.5-18
Package Index