Oracle8i Java Stored Procedures Developer's Guide
Release 8.1.5






Prev  Chap Top Next

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:


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

Table 2-1 loadjava Options
Option  Description 

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 run time. See "Resolution Modes".  


Generates debug information. This option is equivalent to javac -g.  


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".  


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). The compiler uses this value, so the encoding of uploaded source files must match the specified encoding.  


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.  


Grants the EXECUTE privilege on uploaded classes to the listed users and/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.  


Directs loadjava to communicate with the database using the OCI JDBC driver. This option (the default) and -thin are mutually exclusive.  


Binds newly created class schema objects to the following predefined resolver spec:

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

This option (the default) detects missing classes immediately. It and -resolver are mutually exclusive.  


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 run time.

Specify this option to compile (if necessary) and resolve a class that was loaded previously. You need not specify the option -force because resolution is done independently, after loading.  


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.  


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.  


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.  


Directs loadjava to communicate with the database using the thin JDBC driver. This option and -oci8 (the default) are mutually exclusive.  


Enables verbose mode, in which progress messages are displayed.  

Specifying the User

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


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:


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:


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


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


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:

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:

PROMPT A)ll or J)ava only? 

  choice CHAR(1) := UPPER('&x');
  printable BOOLEAN;
  bad_choice EXCEPTION;
  IF choice NOT IN ('A', 'J') THEN RAISE bad_choice; END IF;
  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)
    /* 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;
  WHEN bad_choice THEN
    DBMS_OUTPUT.PUT_LINE('Bad choice');

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
Column Name  Datatype  Description 



name of object  



name of any sub-object (a partition for example)  



object number of object  



object number of segment that contains the object  



type of object (a table or index for example)  



date on which object was created  



date of last DDL operation on the object  



character string containing date and time the object was created  



status (valid or invalid) of object  



indicator (y/n) of whether current session sees only the data that it stores in the object  



indicator of whether name of the object was generated by the system  



indicator of whether object is a secondary object created for domain indexes  



Copyright © 1999 Oracle Corporation.

All Rights Reserved.