Oracle8i Java Stored Procedures Developer's Guide Release 2 (8.1.6) Part Number A81358-01 |
Library | Service | Contents | Index

## 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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index