[Chapter 9] 9.4 Using loadjava

9.4 Using loadjava

The loadjava utility is an operating system command-line utility that uploads Java files into the database. The first time you run loadjava in a schema, it creates a number of elements for its own use:

CREATE$JAVA$LOB$TABLE: A table created in each schema, containing Java code elements
JAVA$CLASS$MD5$TABLE: A hash table, also referred to as the digest table, used to track the loading of Java elements into a given schema
LOADLOBS: A package that is installed in each schema, used to load Java code elements as large objects (LOBs) into the database

Using LOADLOBS, loadjava moves Java files into a BLOB column in the database table CREATE$JAVA$LOB$TABLE. It also checks the JAVA$CLASS$MD5$TABLE.MD5 hash value to see if the loaded classes have been loaded previously and whether they have been changed (thereby minimizing the need to reload).[1] This is done to avoid unnecessary invalidation of dependent classes. It then calls the new DDL command CREATE JAVA to load the Java classes from the BLOB column of CREATE$JAVA$LOB$TABLE into the RDBMS as schema objects. This loading occurs only if:

[1] MD5 is RSA Data Security's MD5 Message-Digest Algorithm; more information can be found on http://www.columbia.edu/~ariel/ssleay/rfc1321.html.

The class is being loaded for the first time
The class has been changed
The -force option is supplied

Figure 9.3 illustrates the loading of Java objects into the Oracle database.

Figure 9.3: Loading Java elements into Oracle

Here is the syntax:

loadjava {-user | -u} username/password[@database]
  [-option_name [-option_name] ...] filename [filename ]...

where option_name stands for the following syntax:

{  {andresolve | a}
 | debug
 | {definer | d}
 | {encoding | e} encoding_scheme_name
 | {force | f}
 | {grant | g} {username | role_name}[,{username | role_name}]...
 | {oci8 | o}
 | oracleresolver
 | {resolve | r}
 | {resolver | R} "resolver_spec"
 | {schema | S} schema_name
 | {synonym | s}
 | {thin | t}
 | {verbose | v} }

On the command line, you can enter the names of Java source, class, and resource files, SQLJ input files (.sqlj files), and uncompressed .jar files and .zip archives, in any order.

The following command, for example, loads the JFile class into the SCOTT schema:

loadjava -user scott/tiger -oci8 -resolve JFile.class

You can run this command from within a DOS window on Windows NT or from the command line in a Unix session. You can also execute it from within SQL*Plus as shown:

host loadjava -user scott/tiger -oci8 -resolve JFile.class

To make it easier for me to load classes into Oracle, I created a file named lj.bat for Windows NT as follows:

javac %1.java
loadjava -user %1 -oci8 -resolve %2.class

Now I can compile and load a Java class in one step:

D:\Java> lj scott/tiger JFile

Here are some things to keep in mind about loadjava. To display a help screen, use this syntax:

loadjava {-help | -h}

In a list of options or files, names must be separated only by spaces:

-force, -resolve, -thin  // No
-force -resolve -thin    // Yes

In a list of users or roles, however, names must be separated only by commas:

SCOTT, PAYROLL, BLAKE  // No
SCOTT,PAYROLL,BLAKE    // Yes

Table 9.2 describes the loadjava command-line options.

As you can probably imagine, there are a number of nuances to using loadjava, such as whether to load individual classes or compressed groups of elements in a .zip or .jar file. See the Oracle documentation for more information about the loadjava command.

Table 9.2: loadjava Options
Option	Description
-andresolve	Compiles source files and resolves each class file as it is loaded. This option and -resolve are mutually exclusive. If neither is specified, files are loaded but not compiled or resolved. In general, this mode is not recommended because it can leave classes that have unresolved references marked valid, causing an error at runtime.
-debug	Generates debug information. This option is equivalent to `javac -g`.
-definer	Specifies that the methods of uploaded classes will execute with the privileges of their definer, not their invoker. (By default, methods execute with the privileges of their invoker.) Different definers can have different privileges, and an application can have many classes, so make sure the methods of a given class execute only with the privileges they need. Note that Oracle8i Release 8.1.5 does not seem to conform to the Oracle documentation; the default seems to be to run with definer rights.
-encoding	Sets (or resets) the -encoding option in the database table JAVA$OPTIONS to the specified value, which must be the name of a standard JDK encoding scheme (the default is "latin1"). The compiler uses this value, so the encoding of uploaded source files must match the specified encoding.
-force	Forces the loading of Java class files, whether or not they have been loaded before. By default, previously loaded class files are rejected. You cannot force the loading of a class file if you previously loaded the source file. You must drop the source schema object first.
-grant	Grants the EXECUTE privilege on uploaded classes to the listed users or roles. (To call the methods of a class directly, users must have the EXECUTE privilege.) This option is cumulative. Users and roles are added to the list of those having the EXECUTE privilege. To revoke the privilege, either drop and reload the schema object without specifying -grant, or use the SQL REVOKE statement. To grant the privilege on an object in another user's schema, you must have the CREATE PROCEDURE WITH GRANT privilege.
-oci8	Directs loadjava to communicate with the database using the OCI JDBC driver. This option (the default) and -thin are mutually exclusive.
-oracleresolver	Binds newly created class schema objects to the following predefined resolver spec: "((* definer's_schema) (* public))" -resolver are mutually exclusive.
-resolve	After all class files on the command line are loaded and compiled (if necessary), resolves all external references in those classes. If this option is not specified, files are loaded but not compiled or resolved until runtime. Specify this option to compile (if necessary) and resolve a class that was loaded previously. You need not specify the -force option because resolution is done independently, after loading.
-resolver	Binds newly created class schema objects to a user-defined resolver spec. Because it contains spaces, the resolver spec must be enclosed by double quotes. This option and -oracleresolver (the default) are mutually exclusive.
-schema	Assigns newly created Java schema objects to the specified schema. If this option is not specified, then the logon schema is used. You must have the CREATE ANY PROCEDURE privilege to load into another user's schema.
-synonym	Creates a public synonym for uploaded classes, making them accessible outside the schema into which they are loaded. To specify this option, you must have the CREATE PUBLIC SYNONYM privilege. If you specify this option for source files, it also applies to classes compiled from those source files.
-thin	Directs loadjava to communicate with the database using the thin JDBC driver. This option and -oci8 (the default) are mutually exclusive.
-verbose	Enables the verbose mode, in which progress messages are displayed.


9.3 A Simple Demonstration		9.5 Using dropjava