NAME
Java - Java method invocation package
SYNOPSIS
package require java ?1.0?
java::new signature ?arg arg ...?
java::call class signature ?arg arg ...?
java::field objOrClass fieldSignature ?value fieldSignature value ...?
java::instanceof javaObj type
java::prop javaObj property ?value property value ...?
java::info option ?arg arg ...?
java::null
javaObj signature ?arg arg ...?
DESCRIPTION
java::new
java::call
java::field
java::instanceof
java::prop
java::info
class javaObj
fields ?-type? ?-static? objOrClass
methods ?-type? ?-static? objOrClass
constructors objOrClass
properties objOrClass ?-type?
superclass objOrClass
java::null
OBJECT COMMAND
CLASS NAMES
SIGNATURE
RETURN VALUES AND EXCEPTIONS
OBJECT GARBAGE COLLECTION
KEYWORDS
SEE ALSO

NAME

Java - Java method invocation package

SYNOPSIS

package require java ?1.0?
java::new signature ?arg arg ...?
java::call class signature ?arg arg ...?
java::field objOrClass fieldSignature ?value fieldSignature value ...?
java::instanceof javaObj type
java::prop javaObj property ?value property value ...?
java::info option ?arg arg ...?
java::null
javaObj signature ?arg arg ...?

DESCRIPTION

The java package provides an interface for creating and manipulating Java objects. When the package is loaded, Tcl will use an existing Java VM or initialize a new one as needed. Note that tcl.lang and the JDK 1.1 need to be on the class path.

java::new

The java::new command is used to create new instances of Java objects from Tcl. The signature argument specifies which class constructor to use for creating the object. See SIGNATURE below for a full description of how to specify the signature. Additional parameters to the java::new command are converted to Java objects or primitive values and passed to the constructor. The RETURN VALUES AND EXCEPTIONS section below describes the result (and possible error conditions) of the java::new command.

java::call

The java::call command is used to invoke public static methods from Tcl. The class argument specifies the fully qualified name of the declaring class of the method to invoke. See the CLASS NAMES below for a full description of fully qualified class names. The signature argument specifies which class method to invoke (see SIGNATURE below). Additional parameters to the java::call command are converted to Java objects or primitive types and passed to the method. The RETURN VALUES AND EXCEPTIONS section below describes the result (and possible error conditions) of the java::call command.

java::field

The java::field command is used to manipulate public fields from Tcl. The objOrClass argument specifies either a fully qualified name of the declaring class of the field to access, or an object handle, as returned by java::new, java::call, or an object command. The fieldSignature argument specifies which field to manipulate (see SIGNATURE below). If an additional value parameter exists, then the field will be set to value, otherwise the current value of the field is returned. Multiple fields may be set via additional parameters by alternating field signatures and values.

java::instanceof

The java::instanceof command is used to tell whether a Java object is of a given type. The javaObj argument specifies an object handle, as returned by java::new, java::call, or the object command. The type argument specifies a fully qualified interface or class name (see CLASS NAMES below). If the type argument is a class name, java::instanceof returns 1 if the javaObj argument is an instance of type or an instance of a subclass of type. If the type argument is an interface name, java::instanceof returns true if the javaObj argument implements this interface. Otherwise, java::instanceof returns 0.

java::prop

The java::prop command is used to manipulate Java Bean properties from Tcl. The javaObj argument specifies an object handle, as returned by java::new, java::call, or an object command. The property argument specifies a Java Bean property that has corresponding get and set methods. If an additional value parameter exists, then the property will be set to value, otherwise the current value of the property is returned. Multiple properties may be set via additional parameters by alternating properties and values.

java::info

The java::info command provides introspection for Java classes, object, and Beans. The valid options for this command are:

class javaObj
Returns the class name of the specified Java object.

fields ?-type? ?-static? objOrClass
Returns a list of fieldSignatures of public fields of the specified class or Java object. For shadowed superclass fields, the fieldSignature is full. For all other fields, the fieldSignature is simple. If the ?-type? flag is used, then each element of the result list is a pair containing the data type and fieldSignature. If the -static flag is used, only static fields will appear in the result list. Otherwise, only non-static fields will appear in the result list.

methods ?-type? ?-static? objOrClass
Returns a list of the full signatures of methods of the specified class or Java object. If the -type flag is used, the result is a list of pairs of the method's return type and full signature. If the -static flag is used, only static methods will appear in the result list. Otherwise, only non-static methods will appear in the result list.

constructors objOrClass
Returns a list of the full signatures of constructors of the specified class or Java object.

properties objOrClass ?-type?
Returns a list of the names of Java Bean properties of the specified class or Java object. If the ?-type? flag is used, then each element of the result list is a pair containing the data type and name of the property.

superclass objOrClass
Returns the name of the immediate superclass of the specified Java object or class.

java::null

The java::null command returns an object handle that represents the "null" value in Java. To check for null results from Java method invocations, compare the methods' return values to the result of java::null. The exact form of the return value of java::null is not specified and is likely to change.

OBJECT COMMAND

The object handle returned by java::new, java::call, or an object command, is also the name of a Tcl command that can be used to invoke public methods of that object from Tcl. The signature argument specifies which class method to invoke (see SIGNATURE below). Additional parameters to an object command are converted to Java objects or primitive values and passed to the method. The RETURN VALUES AND EXCEPTIONS section below describes the result (and possible error conditions) of the java::call command.

CLASS NAMES

Any command which takes as input or returns a class name, interface name, or primitive value expects a fully qualified Java class name (e.g. java.awt.Button). If a name is not fully qualified, it is assumed to be in java.lang.*.

SIGNATURE

A signature is the string which specifies a class constructor, method, or field, thereby distinguishing it from other constructors, methods, and fields. We will refer to signatures of fields as fieldSignatures. Any further mention of signatures refers to those of both constructors and methods. Two forms of signatures are accepted: simple and full. The simple signature is a single element list containing the method or constructor name. If the simple signature is used to invoke an overloaded method, then a method will be picked based on the number of arguments passed to the command invoking the method. The full signature is used to distinguish between two or more methods with the same name and number of arguments. The full signature of a method is a Tcl list containing the method name followed by the type of each parameter of the method. Two forms of fieldSignatures are accepted: simple and full. A simple fieldSignature is a single element list containing the filed name. A full fieldSignature is a Tcl list containing the field name and the name of the class in which the field is declared. The full form of fieldSignature is required to specify shadowed fields of superclasses.

RETURN VALUES AND EXCEPTIONS

When a constructor or other method is invoked by java::new, java::call, or an object command, Tcl automatically converts the result to a corresponding Tcl value. If the type of the return is a boolean or numeric type, it will be converted to an integer (or floating-point) value. If the result is a string, then the contents of the string are returned. For all other object types, a new Java object handle is created and returned. If the method throws an exception, the string representation of the exception is returned as an error and errorCode will contain a list whose first element is the string "JAVA" and whose second element is the object handle of the exception object.

OBJECT GARBAGE COLLECTION

The object handle associated with a Java object is considered to be an object reference by the Java VM, ensuring that the Java object is not garbage collected while Tcl is using it. Tcl will release the object handle when the last reference to the handle in a Tcl script goes away. A handle is considered to be active as long as at least one Tcl_Obj points to the handle. In practice this means that Java object handles must be stored in Tcl variables or passed as arguments to other commands to keep them from being released. Constructing a Java object handle using concat or some other string manipulation command will produce a string that can be used where a Java object handle is expected, but it will not count as a reference to the object for garbage collection purposes.

KEYWORDS

java, tcl

SEE ALSO

java::load
Copyright © 1997 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.