INSTALL JAVA statement

Makes Java classes available for use within a database.

Syntax

INSTALL JAVA
[ NEW | UPDATE ]
[ JAR jar-name ]
FROM { FILE filename | expression }
[ AS USER user-name ]

Parameters

NEW and UPDATE keyword clauses
If you specify NEW, the referenced Java class or JAR file must contain new classes, rather than updates of currently installed classes or JAR files. An error occurs if a class or JAR file with the same name exists in the database and NEW is used.

If you specify UPDATE, the referenced file may include replacements for Java classes or JAR files that are already installed in the given database.

If omitted, the default is NEW.
JAR clause
If this is specified, then the filename must designate a JAR file. JAR files typically have extensions of .jar or .zip.

Installed JAR and ZIP files can be compressed or uncompressed. Due to differences in compression schemes, it is recommended that JAR files containing textual resources be created with compression turned off.

If the JAR clause is specified, the JAR file is retained as a JAR after the classes that it contains have been installed. That JAR is the associated JAR of each of those classes. The JAR files installed in a database with the JAR clause are called the retained JAR files of the database.

The jar-name is a character string value, of up to 255 bytes long. The jar-name is used to identify the retained JAR in subsequent INSTALL JAVA UPDATE and REMOVE JAVA statements.
FROM FILE clause
Specifies the location of the Java class or JAR file to be installed.

The formats supported for filename include fully qualified file names, such as 'c:\\libs\\jarname.jar' and '/usr/u/libs/jarname.jar', and relative file names, which are relative to the current working directory of the database server. If the database server's CLASSPATH includes the path to the class or JAR file, then the path does not need to be included with the file name.

The filename must identify either a class, JAR or ZIP file.
FROM clause
Expressions must evaluate to a binary type whose value contains a valid class or JAR file.
AS USER clause
Specifies the owner of the object.

Remarks

The class definition for each class is loaded by each connection's VM the first time that class is used. When you INSTALL a class, the VM on your connection is implicitly restarted. Therefore, you have immediate access to the new class. Because the VM is restarted, any values stored in Java static variables are lost, and any SQL variables with Java class types are dropped.

For other connections, the new class is loaded the next time a VM accesses the class for the first time. If the class is already loaded by a VM, that connection does not see the new class until the VM is restarted for that connection.

All installed classes can be referenced in any way by any user.

Privileges

You must have the MANAGE ANY EXTERNAL OBJECT system privilege.

Standards

ANSI/ISO SQL Standard
Not in the standard.

Example

This example installs a fictitious Java class named Demo, by providing the file name and location of the class.

INSTALL JAVA NEW
FROM FILE 'D:\\JavaClass\\Demo.class';

This example installs all the classes contained in a fictitious ZIP file, and associates them within the database with the JAR name Widgets. After the installation, the location of the ZIP file is not retained and classes must be referenced using the fully qualified class name (package name and class name).

INSTALL JAVA
JAR 'Widgets'
FROM FILE 'C:\\Jars\\Widget.zip';