Access Java Methods or Fields

DESCRIPTION:

Functions for accessing Java code from S-PLUS. The functions .JaveMethod and .JavaField invoke a static method or get a static field value for a given Java class, .JavaAttachClassPath accesses external Java class files, is.jvm.running determines whether the Java Virtual Machine is currently running, and require.java loads and starts Java if it is not running.

USAGE:

.JavaMethod(X, METHOD, SIGNATURE, ..., client = F)
.JavaField(X, FIELD, SIGNATURE, client = F)
.JavaAttachClassPath(paths, function(paths, client = F)
is.jvm.running()
require.java()

REQUIRED ARGUMENTS:

X
character string naming a Java class specified like this "java.lang.Math" or "java/lang/Math".
METHOD
character string which is the name of a static Java method in the specified class.
FIELD
character string which is the name of a static field in the specified class.
SIGNATURE
character string giving the signature, either the method descriptor or a class descriptor. When calling .JavaMethod this must be the full method descriptor, or signature. When calling .JavaField it is the class descriptor (signature) of the return value.

The javap utility included with the Java 2 SDK can be used to print out the JNI field and method decriptors for a class.

        % javap -s -p java.lang.Math
        Compiled from Math.java
        public final class java.lang.Math extends java.lang.Object {
            public static final double E;
                /*   D   */
            public static final double PI;
                /*   D   */
        ...
            public static double abs(double);
                /*   (D)D   */
            public static float abs(float);
                /*   (F)F   */
            public static int abs(int);
                /*   (I)I   */
            public static long abs(long);
                /*   (J)J   */
        ...
            public static double toDegrees(double);
                /*   (D)D   */
            public static double toRadians(double);
                /*   (D)D   */
        }

paths
character vector containing one or more file names. Each file name can be either a Java jar file or a directory containing java class files. .JavaAttachClassPath adds these to the Java classpath list which is searched to find classes by .JavaMethod and .JavaField.

OPTIONAL ARGUMENTS:

...
all arguments required by the Java method being called. There must be one ... argument for each class descriptor enclosed in the parentheses of the SIGNATURE argument. All S-PLUS atomic types, except complex, can be passed to a Java method. The S-PLUS objects will be converted to Java types according to the class descriptors in the SIGNATURE argument.
client
logical indicating whether to evaluate the call in the client JVM or the server JVM when running with a remote client. This flag is ignored if not running in client/server mode.

VALUE:

.JavaMethod and .JavaField returns an S object containing the value returned by the Java method or the Java class field value.

If the result is a Java primitive, array of primitives, String, or array of Strings, then it will be converted to a vector of the corresponding S-PLUS type.

If the result is an array of non-primitive objects or a class implementing the java.util.Collection interface, then it will be converted to a S-PLUS list with each component of the array or Collection returned as one component of the list. Classes implementing Collection include Vector and ArrayList.

For any other class the result will be converted to a single String using the object's toString() method.

The function is.jvm.running returns true if Java is currently running, otherwise false. The other functions return NULL.

SIDE EFFECTS:

DETAILS:

The functions .JavaMethod and .JavaField and .JavaAttachClassPath will automatically start Java by calling require.java, if it is not already running.

In order for the Java Virtual Machine to find Java classes, either (1) the class file directories and jar files must be included in the Java classpath by setting the CLASSPATH environment variable, or (2) the classes must be placed in a jar file in the directory SHOME/java/jre/lib/ext, or (3) the class file directories and jar files must be attached by a call to .JavaAttachClassPath.

In cases (1) and (3), if the Java classes are in a "jar" file, the location should be the full path to the jar file including the name of the file. If the class files are in a directory, the location should be the full path to the directory.

EXAMPLES:

.JavaMethod("java/lang/Math", "pow", "(DD)D", 2, 10)

.JavaField("java/lang/Math", "PI", "D")

.JavaMethod("java.lang.System", "getProperty", "(Ljava/lang/String;)Ljava/lang/String;", "java.version")

.JavaMethod("java.lang.Double", "isNaN", "(D)Z", NaN)

is.inf(.JavaField("java.lang.Double", "POSITIVE_INFINITY", "D"))

.JavaField("java.lang.Integer", "MAX_VALUE", "I")