The nsjava::new Command


nsjava::new signature ?arg arg ...?
nsjava::new arraySignature sizeList ?valueList?
nsjava::new -handle javaObj

The nsjava::new command is used to create new instances of 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 nsjava::new is called with a non-array signature, the appropriate constructor for the Java object is invoked with the arguments to the nsjava::new command provided as arguments to the Java constructor. If the arguments to nsjava::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 nsjava::new command. Because the specification of signatures for constructors and methods is very simmilar, a seperate Signatures section covers them both.

When nsjava::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.

When nsjava::new is called with the -handle switch, a new tcl reference to an existing java object is created. This is useful for recreating a java object reference in a thread other than the one where it was intially created.

The Conversions section describes how arguments to the nsjava::new command might be converted to Java objects or primitive types.


The following example shows how to allocate an instance of the Java class java.lang.String, and how to get a Tcl string representation of the java.lang.String object.
# Allocate an instance of a String object.
set jstring [nsjava::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 [nsjava::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"

This example demonstrates how to access long-lived java objects created during startup. The -handle switch then provides a method for accessing the object later on in a connection thread. The coding pattern is as follows:

In startup thread

# create java object that needs to be preserved for connection threads
set obj [nsjava::new {FooClass java.lang.String} {This is foo}]

# lock the java object so that it is not garbage collected by tcl or java
nsjava::lock $obj

# save the object handle in an nsv_set so that it can be accessed later
nsv_set myappvars myobj $obj

... Now later on in a connection thread

#get the saved object handle
set handle [nsv_get myappvars myobj]

# now get a new reference to the saved java object
set new_handle [nsjava::new -handle $handle]

# if the object will no longer be needed, unlock the saved java object.
# if other connections need to access the same object, then skip this 
# step.
nsjava::unlock $handle

# Now use the object as any other nsjava object would be used.
# Here we call the bar method of the FooClass class.
set a [$new_handle bar]

Copyright © 1997-1998 Sun Microsystems, Inc.