Loading Java Classes

Using loadjava

Using a built-in package named LOADLOBS, the loadjava utility uploads Java files into a BLOB column in the database table CREATE$JAVA$LOB$TABLE, which the utility creates in the logon schema. Then, it uses the SQL CREATE JAVA statement to load the Java files into the Oracle database as schema objects.

You need the JVM permissions in JServerPermission.loadLibraryInClass and the database privileges CREATE PROCEDURE and CREATE TABLE to upload classes. (For more information, see the Oracle8i Java Developer's Guide.)

On the command line, you can enter the names of Java source, class, and resource files, SQLJ files, JARs, and ZIP archives in any order. Here is the syntax:

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

where option_name stands for the following syntax:

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

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

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

However, in a list of users, names must be separated only by commas:

SCOTT, UTIL, BLAKE  // No
SCOTT,UTIL,BLAKE    // Yes

Table 2-1 describes the loadjava command-line options. The next two sections describe the required arguments -user and file_name.

Table 2-1 loadjava Options

Option	Description
`andresolve`	Compiles uploaded 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. Unlike `-resolve`, this option does not compile (if necessary) and resolve previously loaded classes.
`debug`	Directs `loadjava` to generate and display debugging information.
`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. For more information, see "Invoker Rights versus Definer Rights".
`encoding`	Sets (or resets) the option `-encoding` 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`). This option applies only to uploaded source files. The compiler uses this value, so the encoding of those files must match the encoding you specify.
`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. (To call the methods of a class directly, users need the `EXECUTE` privilege.) This option is cumulative--users 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 need the privilege `CREATE` `PROCEDURE` `WITH` `GRANT`. This option cannot grant the `EXECUTE` privilege to roles.
help	Displays the `loadjava` help screen.
`oci8`	Directs `loadjava` to communicate with the database using the JDBC OCI driver. This option (the default) and `-thin` are mutually exclusive.
noverify	Turns off the bytecode verifier so that uploaded classes are not verified. However, if a class is later invalidated and re-resolved, it is also verified. You need the permission J`ServerPermission.Verifier` to use this option. If you specify this option, you must also specify `-resolve`.
`oracleresolver`	Binds newly created class schema objects to the following predefined resolver spec: "((* definer's_schema) (* public))" You can use this option to detect missing classes immediately. This option (the default) and `-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. This option and `-andresolve` are mutually exclusive. If neither is specified, files are loaded but not compiled or resolved until run time. Specify this option to compile (if necessary) and resolve a class that was loaded previously. You need not specify `-force` 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`	Uploads newly created Java schema objects into the specified schema. If this option is not specified, then the logon schema is used. To upload into another user's schema, you need the privileges `CREATE` `ANY` `PROCEDURE` and `CREATE` `ANY` `TABLE`.
`synonym`	Creates a public synonym for uploaded Java classes, making them accessible outside the schema into which they are loaded. To specify this option, you need 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 client-side JDBC Thin driver. This option and `-oci8` (the default) are mutually exclusive.
`verbose`	Directs `loadjava` to display progress messages.

Specifying the User

The argument -user specifies a username, password, and optional database connect string in the following format:

username/password[@database]

With option -oci8 (the default), the connect string database is optional. If you specify database, which can be a TNS name or Net8 name-value list, classes are loaded into the designated database. Otherwise, classes are loaded into the user's default database.

With option -thin, you must specify the connect string database in this format:

@host:lport:SID

where host names the host computer, lport is the port configured to listen for Net8 connections, and SID is the database system identifier. With a default configuration, lport is 5521 and SID is ORCL.

Specifying File Names

On the command line, you can enter as many names of Java source, class, and resource files, SQLJ files, JARs, and ZIP archives as you like, in any order. Archives cannot be schema objects. Therefore, when passed a JAR or ZIP archive, loadjava loads the archived files individually. However, loadjava cannot process nested JARs or ZIP archives.

The best way to upload files is to store them in a JAR or ZIP archive. By loading archives, you avoid schema object naming complications (discussed below). Any JAR or ZIP archive that works with the JDK will work with loadjava.

The names of schema objects differ slightly from file names, and different schema objects have different naming conventions. Class files are self-identifying, so loadjava can map their file names to the names of schema objects automatically. loadjava can also map source file names automatically. It simply gives the schema object the full name of the first class defined in the file. Likewise, JARs and ZIP archives include the names of the files they contain.

However, resource files are not self identifying; loadjava derives the names of Java resource schema objects from the literal names you enter on the command-line (or the literal names in a JAR or ZIP archive). Running programs use resource schema objects, so make sure you enter resource file names correctly.

The best way to load individual resource files is to specify their names relative to the directory you would list in CLASSPATH, and then run loadjava from that directory. For your information, the details of resource file naming follow.

When you load a resource file, loadjava derives the name of the resource schema object from the file name that you enter on the command line. Suppose you type the following relative and absolute pathnames on the command line:

alpha/beta/x.properties
/home/scott/javastuff/alpha/beta/x.properties

Although you specified the same file, loadjava creates two schema objects:

alpha/beta/x.properties
ROOT/home/scott/javastuff/alpha/beta/x.properties

loadjava prefixes ROOT to the second name because the names of schema objects cannot begin with a slash (/).

Classes can refer to resource files relatively (for example, b.properties) or absolutely (for example, /a/b.properties). To ensure that loadjava and the class loader use the same name for a resource schema object, enter the name that the class passes to method getResource() or getResourceAsString().

To make sure the correct names are used, before uploading resource files, store them in a JAR, as shown in the following example:

> cd /home/scott/javastuff
> jar -cf alphaResources.jar alpha/*.properties
> loadjava ... alphaResources.jar

Even better, store both the class and resource files in a JAR. That way, the following invocations are equivalent because you can use any pathname to load the contents of a JAR:

> loadjava ... alpha.jar
> loadjava ... /home/scott/javastuff/alpha.jar

Examples

In the following example, loadjava connects to the database using the thin JDBC driver, loads two class files, then resolves them:

> loadjava -user scott/tiger@dbhost:5521:orcl -thin
    -resolve Agent.class Alerter.class

In the next example, loadjava connects to the default database using the default JDBC OCI driver, loads files from a JAR into schema BLAKE, then resolves them:

> loadjava -user scott/tiger -resolve -schema BLAKE serverObjs.jar

In the final example, loadjava adds NILES and FORD to the list of users who can execute Manager.class:

> loadjava -user scott/tiger@localhost:5521:orcl -thin
    -grant NILES,FORD Manager.class

Reloading Files

If you upload the same file multiple times but specify different options, the options specified for the last upload prevail. The two exceptions are:

If loadjava does not load a file because it matches a digest table entry, then most options have no effect on the schema object. However, the options -andresolve, -grant, and -resolve are always obeyed. To have loadjava skip the digest table lookup, specify the option -force.
The option -grant is cumulative. All the users specified in every upload of a given class into a given schema are granted the EXECUTE privilege.

Also, if you use the SQL DROP JAVA statement to drop a Java class and then use loadjava to reload the same class, you must specify the option -force. Otherwise, the upload fails.

Running loadjava from an Application

An overloaded procedure named loadjava() in package DBMS_JAVA enables you to run the loadjava utility from an application. Here are the procedure specs:

PROCEDURE loadjava (options VARCHAR2);
PROCEDURE loadjava (options VARCHAR2, resolver VARCHAR2);

You can specify all the options except -user, -oci8, and -thin (because this version of loadjava always connects to the current session). To use the option -resolver (-R), you must pass it as a second parameter to the second form of procedure loadjava(). Enclose parameters with single quotes, as shown in the following example:

CALL dbms_java.loadjava('-r Agent.class', '-R "((* SCOTT) (* -))"');

Relative path names are interpreted as relative to ORACLE_HOME. Output is directed to stderr.

Checking Upload Results

To check upload results, you can query the database view USER_OBJECTS, which contains information about schema objects owned by the user (SCOTT in this case). For example, the following SQL*Plus script formats and displays useful information about Java source, class, and resource schema objects:

SET SERVEROUTPUT ON
SET VERIFY OFF
PROMPT A)ll or J)ava only? 
ACCEPT x CHAR PROMPT 'Choice: '

DECLARE
  choice CHAR(1) := UPPER('&x');
  printable BOOLEAN;
  bad_choice EXCEPTION;
BEGIN
  IF choice NOT IN ('A', 'J') THEN RAISE bad_choice; END IF;
  DBMS_OUTPUT.PUT_LINE(CHR(0));
  DBMS_OUTPUT.PUT_LINE('Object Name                    ' ||
    'Object Type   Status  Timestamp');
  DBMS_OUTPUT.PUT_LINE('------------------------------ ' ||
    '------------- ------- ----------------');
  FOR i IN (SELECT object_name, object_type, status, timestamp
    FROM user_objects ORDER BY object_type, object_name)
  LOOP
    /* Exclude objects generated for loadjava and dropjava. */
    printable := i.object_name NOT LIKE 'SYS_%'
      AND i.object_name NOT LIKE 'CREATE$%'
      AND i.object_name NOT LIKE 'JAVA$%'
      AND i.object_name NOT LIKE 'LOADLOB%';
    IF choice = 'J' THEN
      printable := i.object_type LIKE 'JAVA %';
    END IF;
    IF printable THEN
      DBMS_OUTPUT.PUT_LINE(RPAD(i.object_name,31) || 
        RPAD(i.object_type,14) || 
        RPAD(i.status,8) || SUBSTR(i.timestamp,1,16));
    END IF;
  END LOOP;
EXCEPTION
  WHEN bad_choice THEN
    DBMS_OUTPUT.PUT_LINE('Bad choice');
END;
/

You can choose to display all your schema objects or only the Java objects:

SQL> @usr_obj
A)ll or J)ava only?
Choice: a

Object Name                   Object Type   Status  Timestamp
----------------------------- ------------- ------- ----------------
Alerter                       JAVA CLASS    VALID   1998-10-08:13:42
POManager                     JAVA CLASS    VALID   1998-10-08:17:14
Alerter                       JAVA SOURCE   VALID   1998-10-08:13:42
POManager                     JAVA SOURCE   VALID   1998-10-08:17:11
BONUS                         TABLE         VALID   1998-10-08:14:02
DEPT                          TABLE         VALID   1998-10-08:14:02
EMP                           TABLE         VALID   1998-10-08:14:02
SALGRADE                      TABLE         VALID   1998-10-08:14:02

SQL> @usr_obj
A)ll or J)ava only?
Choice: j

Object Name                   Object Type   Status  Timestamp
----------------------------- ------------- ------- ----------------
Alerter                       JAVA CLASS    VALID   1998-10-08:13:42
POManager                     JAVA CLASS    VALID   1998-10-08:17:14
Alerter                       JAVA SOURCE   VALID   1998-10-08:13:42
POManager                     JAVA SOURCE   VALID   1998-10-08:17:11

The column object_name stores the full names of Java schema objects. However, if a name is longer than 30 characters or contains an untranslatable character, then the short name is stored instead. To convert short names to full names, you can use the function longname in package DBMS_JAVA, as follows:

SQL> SELECT dbms_java.longname(object_name) FROM user_objects
  2    WHERE object_type = 'JAVA SOURCE';

This query returns the full names of all Java source schema objects.

As you might expect, the column status stores character strings indicating the status (valid or invalid) of a Java schema object. A source schema object is valid if it was compiled successfully. A class schema object is valid if it was resolved successfully. A resource schema object is always valid because resources are not compiled or resolved.

Table 2-2 describes all the columns in database view USER_OBJECTS.

Table 2-2 Columns in USER_OBJECTS

Column Name	Datatype	Description
`OBJECT_NAME`	`VARCHAR2(128)`	name of object
`SUBOBJECT_NAME`	`VARCHAR2(30)`	name of any sub-object (a partition for example)
`OBJECT_ID`	`NUMBER`	object number of object
`DATA_OBJECT_ID`	`NUMBER`	object number of segment that contains the object
`OBJECT_TYPE`	`VARCHAR2(15)`	type of object (a table or index for example)
`CREATED`	`DATE`	date on which object was created
`LAST_DDL_TIME`	`DATE`	date of last DDL operation on the object
`TIMESTAMP`	`VARCHAR2(19)`	character string containing date and time the object was created
`STATUS`	`VARCHAR2(7)`	status (valid or invalid) of object
`TEMPORARY`	`VARCHAR2(1)`	indicator (y/n) of whether current session sees only the data that it stores in the object
`GENERATED`	`VARCHAR2(1)`	indicator of whether name of the object was generated by the system
`SECONDARY`	`VARCHAR2(1)`	indicator of whether object is a secondary object created for domain indexes