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 RDBMS as schema objects.

On the command line, you can enter the names of Java source, class, and resource files, SQLJ input files (.sqlj files), and uncompressed JARs and ZIP archives in any order. 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} }

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

However, in a list of users and/or roles, names must be separated only by commas:

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

Table 2-1 describes the loadjava command-line options.

Table 2-1 loadjava Options

andresolve

debug

definer

encoding

force

grant

oci8

oracleresolver

"((* definer's_schema) (* public))"

resolve

resolver

schema

synonym

thin

verbose

Specifying the User

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

username/password[@database]

Files are loaded into the designated database instance. With option -oci8 (the default), the connect string database is optional. If database is specified, it can be a TNS name or a Net8 name-value list. If it is not specified, then the user's default database is used.

With option -thin, the connect string database must be specified in this format:

@host:lport:SID 

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

Specifying Filenames

On the command line, you can enter as many names of Java source, class, and resource files, SQLJ input files, and uncompressed 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.

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). If you have a JAR or ZIP archive that works with the JDK, you can be sure that it will also work with loadjava.

The names of schema objects differ slightly from filenames, and different schema objects have different naming conventions. Class files are self-identifying, so loadjava can map their filenames to the names of schema objects automatically. loadjava can also map source filenames 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). Resource schema objects are used by running programs, so make sure you enter resource filenames correctly.

The best way to load individual resource files is to run loadjava from the top of the package tree, specifying resource filenames relative to that directory. If you decide not to follow that rule, the details of resource file naming follow.

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

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

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

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

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.props) or absolutely (for example, /a/b.props). 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/*.props
> 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 default database using the default OCI JDBC driver, loads files from a JAR into schema BLAKE, then resolves them:

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

In the next example, loadjava connects using the thin JDBC driver, loads a class and a resource file, then resolves them:

> loadjava -u scott/tiger@dbhost:5521:orcl -t -r Agent.class images.dat

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

> loadjava -thin -user scott/tiger@localhost:5521:orcl \
    -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 -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 and roles specified in every upload of a given class in 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.

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 the utility package DBMS_JAVA, as follows:

SQL> SELECT dbms_java.longname(object_name), ... FROM user_objects;

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

Table 2-2 Columns in USER_OBJECTS