The java::new command is used to create new instances of accessible Java objects from Tcl. The first form of the command accepts a signature argument which specifies the signature of the constructor for the Java object that will be created. The second form accepts an arraySignature argument which specifies the class type of the array and the number of dimensions in the array.
When java::new is called with a non-array signature, the appropriate constructor for the Java object is invoked with the arguments to the java::new command provided as arguments to the Java constructor. If the arguments to java::new are not already Java objects, then those Tcl values are converted to Java objects or primitive values before being passed to the constructor. When the constructor finishes, a Java object handle is returned by the java::new command. Because the specification of signatures for constructors and methods is very simmilar, a seperate Signatures section covers them both.
When java::new is called with an arraySignature argument, the signature is examined to determine the type of the array and the number of dimensions. The arraySignature argument consists of a class or a primitive data type followed by one or more pairs of brackets. The number of pairs of brackets determines the dimension of the array. For example, {int[][][]} indicates a three dimensional array of integers; the curly braces keeps the Tcl interpreter from evaluating the empty brackets as empty commands.
The sizeList argument determines the number of array elements allocated for each dimension in the array. The i'th element of sizeList specifies the size of the i'th dimension of the array. If sizeList contains more elements than the number of dimensions specified by the arraySignature, then an error is returned. If sizeList contains fewer elements than the number of dimensions specified by the arraySignature, then the size will be determined by the valueList, if present.
The valueList argument is used to set initial values of the array cells. Elements of the valueList must be of the same type as the base class of the array. If the array is multidimensional, then the list must contain sublists of a depth equal to the number of dimensions of the array. If no element is specified in the valueList for a particular array cell, the cell will be initialized to the standard default value for the corresponding Java array type. If the length of the sizeList is smaller than the number of array dimensions, the size of each row whose size is not specified by the sizeList is determined by the length of the corresponding sublist in valueList, or 0 if the valueList contains no corresponding sublist. An error occurs if any dimension other than the last has size 0.
The Conversions section describes how arguments to the java::new command might be converted to Java objects or primitive types.
# Allocate an instance of a String object.
set jstring [java::new String "Hello World"]
# Convert the Java string to a Tcl string
set tstring [$jstring toString]
In this example, we see how to allocate an array of java.lang.String
objects. This example also demonstrates Java array object commands and their
equivalent Java statements, see the javaArrayObj
section for more information.
# This is equivalent to the Java statement.
# String[] arr = new String[2];
set arr [java::new {String[]} {2}]
# Set the values of the array elements.
# This is equivalent to the following Java statements.
# arr[0] = "Hello";
# arr[1] = "World";
$arr set 0 "Hello"
$arr set 1 "World"
Copyright © 1997-1998 Sun Microsystems, Inc.