SJava (version 0.98.0)

.Java: Invokes a Java method

Description

Calls a Java method, transferring R arguments to the Java (Omegahat) system as needed. This can be used to call methods in the Omegahat evaluator, not just on previously created user-level objects. One must create and initialize the Java virtual machine before calling this function. See .JavaInit.

Usage

.Java(.qualifier, .methodName, ..., .name=NULL, .sigs="", .convert=TRUE)

Arguments

.qualifier

The Java object whose method is to be invoked. This is the `this' in the Java call and is typically a reference obtained as the result of a previous call to .Java or .JavaConstructor. If this is NULL or omitted, the Omegahat evaluator looks first for an Omegahat function and then a method within its own object.

.methodName

The name of the method (or function if .qualifier is NULL) that is to be invoked in the Java object.

...

arguments to be passed to the Java method call. Any values that are named (i.e. x = 1) are assigned persistently to the Omegahat named reference database and can be referenced directly in future calls.

.name

The name to use to store the result in the omegahat named reference database. If this is missing, an anonymous reference is returned or the value converted to an R object. If the result of the Java method can be converted, this argument can be used to prohibit this conversion and leave the Java value in Omegahat for use in future .Java calls.

.sigs

A character vector of class identifiers that help to identify the Java method to be invoked. This is used to avoid ambiguity introduced by Java's polymorphism/overloaded names and the automatic/implicit conversion performed between R and Java objects. This should have an entry for each argument passed via ... and governs how we convert that S value to a Java value. See .JavaSigs for possible values.

.convert

typically a logical value that indicates whether the Omegahat manager should attempt to convert the result of the method call. This is usually TRUE, but can be explicitly specified to avoid (arrays of) primitive object being converted to an R object when it is to be used in a subsequent .Java call. One can also provide a function which will be called with two arguments - a reference to the Java object and the class name of the Java object. This is the same as the function converters one can register via setJavaFunctionConverter.

Also, one can specify a native routine (i.e. C/C++/Fortran) address. This can be done using getNativeSymbolInfo and accessing the address field of the returned object. See examples in the inst/examples/ directory.

Value

The return value of the Java method invocation, converted to an R object. If the Java value is considered convertible, one of the registered converters is called. By default, these handle primitives (scalars) and Java collections. The user can register others. If no converter is found, a reference to the Java object is returned as an R object. If the .name argument was supplied in the call to this R function, the reference is a NamedReference. Otherwise, it is a AnonymousReference.

Details

This invokes a Java method on the target object by first converting the R arguments to Java objects and then searching the Java object for a method that accepts these Java argument types. Then it invokes the method and converts the result to a Java object using the basic and extensible conversion mechanism between Java and R.

References

http://www.omegahat.org/RSJava

See Also

.JavaConstructor .OmegahatExpression getJavaConverterDescriptions

foreignReference

Examples

  v <- .JavaConstructor("java.util.Vector", as.integer(10))
 .Java(v, "add", "A string element")
 .Java(v, "add", .JavaConstructor("java.util.Hashtable", as.integer(3)))
 .Java(v, "size")

 props <- .Java("System", "getProperties")
 props[["java.class.path"]]

  props <- .Java("System", "getProperties", .convert=FALSE)
  props$getProperty("java.class.path")