- 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
Java - Java method invocation package
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 ...?
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.*.
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.
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.
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.
java, tcl
java::load
Copyright © 1997 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.