SJava (version 0.98.0)

.JavaConstructor: Create a Java object

Description

Creates a Java object by calling a constructor from the desired class. The object is (almost always) stored in the Omegahat session and a reference to it returned. One must create and initialize the Java virtual machine before calling this function. See .JavaInit. .JNew is a simple alias of .JavaConstructor.

Usage

.JavaConstructor(className, ..., .name="", .sigs="", .convert=FALSE)
.JNew(className, ..., .name="", .sigs="", .convert=FALSE)

Arguments

className

The name of the Java class to be instantiated. This can be either the full name or a partially qualified name which will use the Omegahat class locator mechanism to find the class. It is better (but less convenient) to give the full name as this avoids the lengthy one-time construction of the class lists in Omegahat. It makes sense to give partially qualified names for a) the user's convenience, b) when one expects to substitute different packages with same-named classes that can be used in place of each other.

...

the arguments used to identify and be passed to the constructor in the target class being instantiated.

.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.

.convert

a logical value indicating whether the Omegahat interpreter should attempt to convert the newly created object to an R object (TRUE) or simply leave it in the Omegahat database. This is ignored if a value for .name is supplied.

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

If a value for the argument .name is provided, this returns a NamedReference to a Java object stored in the Omegahat session. Otherwise, usually an AnonymousReference is returned. However, if a converter to R exists for the particular Java class being created and no value for the .name argument is given in the call, the Java object will be converted directly to an R object. This is sometimes useful when the constructor populates the object's fields and one has no further user for the object itself, but just its contents. For example, the basic constructor for the class StatDataURL takes a URL name and reads its contents. A converter could be registered for this class that returns the lines of text.

Details

This creates a new Java object by first converting the R arguments to Java objects and then looking for a constructor in the target class that accepts arguments of these types. The resulting Java object is available for future computations as arguments to .Java, .JavaConstructor, and .OmegahatExpression. At present, the object must be explicitly freed by the caller. This is always true if a value is given for the .name argument.

References

http://www.omegahat.org/RSJava

See Also

.Java .OmegahatExpression

Examples

 tmp <- .JavaConstructor("util.Vector", as.integer(10))
 .Java(tmp, "add", "This is a string")
 .Java(tmp, "add", 1.5)

 b <- .JavaConstructor("JButton","R Java Button")
 .Java(tmp, "add", b)
 
 f <- .JavaConstructor("GenericFrame", b)

 f <- .JNew("GenericFrame", b)