NAME

java::load - Load a new extension into the current interpreter.

SYNOPSIS

java::load extensionName
java::load ?-classpath pathList? extensionName

DESCRIPTION

The java::load command loads extensions into the Java VM. An Extension is a Java class that specifies a set of class files to load into the VM, as well as specifying how the Tcl interpreter should interact with these classes. The primary use for this function is to load additional functionality (i.e. new commands) into the Tcl interpreter, but it may also be used to load classes into the VM that can be used by the Reflection API.

The argument extensionName is the name of a class file that specifies which classes should be loaded as well as creating the binding between Tcl commands and their Java counterparts. The class referenced by extensionName must be a subclass of tcl.lang.Extension.

Any class referenced by extensionName will also be loaded into the VM. This includes classes used in new expressions as well as those whose instances are reported (i.e. the use of static methods.) Due to the recursive nature of class loading, any class referenced must be located in CLASSPATH, env(TCL_CLASSPATH) or pathList. If a class cannot be located in one of the three locations, a Tcl error is generated.

The pathList argument specifies additional paths to search in addition to the CLASSPATH and env(TCL_CLASSPATH) variables. The env(TCL_CLASSPATH) can be set to contain a list of paths to search on every call to java::load. If a path in pathList or env(TCL_CLASSPATH) is not an absolute path, it is assumed to be a relative path from the interpreters' current directory. If a class, or any referenced class, cannot be resolved a Tcl error is generated.

The process of resolving the class is done by searching, in order, one of the following locations.

1) The cache of previously loaded classes.

2) The CLASSPATH list.

3) The pathList list.

4) The env(TCL_CLASSPATH) list, if it exists.

All JAR and ZIP files found in any of the paths will be searched in an attempt to find the class file. The class will be automatically extracted from the JAR or ZIP file and loaded into the VM.

If the system class loader fails to load the class (step 2 above), a security check is done. If the extension name begins with "java." or "tcl.", a Tcl error is generated. This is done to assure that the class does not have access to extension-protected variables.

Currently it is not possible to unload or reload a extension.

EXAMPLE

To load an extension stored in /proj/Jacl/Foo.class,
java::load -classpath /home/user/Jacl Foo

BUGS

Currently '~' substitution is not performed on Unix systems. The path must be absolute or relative from the current directory.
Copyright © 1997 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.