TclJava Package Commands - java::load manual page

NAME

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

SYNOPSIS

java::load ?-classpath pathList? extensionName

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 the class file to load into the VM. The class referenced by extensionName must be a subclass of tcl.lang.Extension. All subclasses of Extension must implement the abstract init method, which is responsible for loading commands into the Tcl interpreter or loading any additional classes into the java VM. To load classes that do not subclass Extension into the VM, use the java::new, java::class or java::defineclass. See the Java package documentation for more detail.

The CLASS LOADING section below describes the order in which the class loader searches for classes on the file system and how additional classes are automatically loaded. The CLASS LOADING section is also relevant to any command in the java package that makes a reference to a java class (i.e. java::new.) References to unresolved classes will implicitly use the TclClassLoader to find unresolved classes.

CLASS LOADING

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

[1]: Search the cache of previously loaded classes.
[2]: Search the CLASSPATH list.
[3]: Search the pathList list, looking only in directories or jar files specified by pathList. (Available only for the java::load command.)
[4]: Search pathList again, inspecting all jar files found in each directory. (Available only for the java::load command.)
[5]: Search the env(TCL_CLASSPATH) list, looking only in directories or jar files specified by env(TCL_CLASSPATH).
[6]: Search env(TCL_CLASSPATH) again, inspecting all jar files found in each directory.

If a path in pathList or env(TCL_CLASSPATH) is not an absolute path, it is assumed to be a relative path from the interpreter's current directory.

If the system class loader fails to load the class (step [2]), then the class was not found in the CLASSPATH list. A security check is done to assure that the class does not have access to package-protected variables. If the extension name begins with "java." or "tcl.", a Tcl error is generated.

Steps [3] and [5] only use the paths in pathList or env(TCL_CLASSPATH) to locate the class file. If the path is a directory, the loader looks in that directory for the class file. If the path is a jar file, the jar file is inspected to see if it contains the class. Steps [4] and [6] search pathList and env(TCL_CLASSPATH) again. If a path in the list is a directory, the loader looks for jar files in that directory, inspecting any jar files found to locate the class. The loader is capable of extracting files from a compressed jar file.

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 the CLASSPATH, env(TCL_CLASSPATH) or pathList. If a class cannot be located in one of the three locations, a Tcl error is generated.

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

EXAMPLE

Load an extension stored in /proj/TclJava/Foo.class;

java::load -classpath /home/user/TclJava Foo

BUGS

Currently '~' substitution is not performed on Unix systems. The path must be absolute or relative from the current directory.

KEYWORDS

java, tcl, classloader

Copyright © 1998 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.