Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
Library | Service | Contents | Index

## Translating SQLJ Source on a Client and Loading Components

One approach to developing SQLJ code for the server is to first run the SQLJ translator on a client machine to take care of translation, compilation, and profile customization. Then load the resulting class and resource files (including your SQLJ profiles) into the server, typically using a Java archive (`.jar`) file.

If you are developing your source on a client machine, as is usually the case, and have a SQLJ translator available there, this approach is advisable. It allows the most flexibility in running the translator, because option-setting and error-processing are not as convenient in the server.

It might also be advisable to use the SQLJ `-ser2class` option during translation when you intend to load an application into the server. This results in SQLJ profiles being converted from `.ser` serialized resource files to `.class` files and simplifies their naming. Be aware, however, that profiles converted to `.class` files cannot be further customized. To further customize, you would have to rerun the translator and regenerate the profiles. For information about the `-ser2class` option, see "Conversion of .ser File to .class File (-ser2class)".

When you load `.class` files and `.ser` resource files into the server, either directly or using a `.jar` file, the resulting database library units are referred to as Java class schema objects (for Java classes) and Java resource schema objects (for Java resources). Your SQLJ profiles will be in resource schema objects if you load them as `.ser` files, or in class schema objects if you enabled `-ser2class` during translation and load them as `.class` files.

### Loading Classes and Resources into the Server

Once you run the translator on the client, use the Oracle `loadjava` client-side utility to load class and resource files into schema objects in the server. This utility is discussed in detail in the Oracle8i Java Developer's Guide.

Either specify the class and resource files individually on the `loadjava` command line, or put them into a `.jar` file and specify the `.jar` file on the command line. A separate schema object is created for each `.class` or `.ser` file in the `.jar` file or on the command line.

Note: As of release 8.1.6, the `loadjava` utility does support compressed files.

Consider an example where you: 1) translate and compile `Foo.sqlj`, which includes an iterator declaration for `MyIter`; 2) enable the `-ser2class` option when you translate `Foo.sqlj`; and 3) archive the resulting files (`Foo.class`, `MyIter.class`, `Foo_SJProfileKeys.class`, and `Foo_SJProfile0.class`) into `Foo.jar`. Then run `loadjava` with the following command line (plus any options you want to specify). This examples uses the default OCI driver:

    loadjava -user scott/tiger Foo.jar

Or, alternatively, use the original files:

    loadjava -user scott/tiger Foo.class MyIter.class Foo_SJProfileKeys.class Foo_SJProfile0.class

or:

    loadjava -user scott/tiger Foo*.class MyIter.class

Or, to use the Thin driver for loading (specifying the `-thin` option and an appropriate URL):

    loadjava -thin -user scott/tiger@localhost:1521:ORCL Foo.jar

For information about files generated by the SQLJ translator, see "Code Generation" and "Java Compilation".

Notes: When you load a profile into the server as a `.ser` file, it is first customized if it was not already customized on the client. If it was already customized, it is loaded as is. You can access the `USER_OBJECTS` view in your database schema to verify that your classes and resources are loaded properly. This is discussed in the Oracle8i Java Developer's Guide

.

Although the `loadjava` utility is recommended for loading your SQLJ and Java applications into the server, you can also use Oracle SQL `CREATE JAVA` commands such as the following:

    CREATE OR REPLACE <AND RESOLVE> JAVA CLASS <NAMED name>;

    CREATE OR REPLACE JAVA RESOURCE <NAMED name>;

See the Oracle8i SQL Reference for more information about the `CREATE JAVA` commands.

### Loaded Class and Resource Schema Objects

This section discusses how schema objects for classes and profiles are named when you load classes and profiles into the server.

If the SQLJ `-ser2class` option was enabled when you translated your application on the client, then profiles were converted to `.class` files and will be loaded into class schema objects in the server. If `-ser2class` was not enabled, then profiles were generated as `.ser` serialized resource files and will be loaded into resource schema objects in the server.

In the following discussion, it is assumed that you use only the default connection context class for any application that will run in the server; therefore, there will be only one profile.

Note: There are two forms of schema object names in the server: full names and short names. Full names are fully qualified and are used as the schema object names wherever possible. If any full name is longer than 31 characters, however, or contains characters that are illegal or cannot be converted to characters in the database character set, then the Oracle8i server converts the full name to a short name to employ as the name of the schema object, keeping track of both names and how to convert between them. If the full name is 31 characters or less and has no illegal or inconvertible characters, then the full name is used as the schema object name. For more information about these and about other file naming considerations, including `DBMS_JAVA` procedures to retrieve a full name from a short name and the converse, see the Oracle8i Java Developer's Guide

.

#### Full Names of Loaded Classes (including profiles if -ser2class enabled)

The full name of the class schema object produced when you load a `.class` file into the server is determined by the package and class name in the original source code. Any path information you supply on the command line (so that `loadjava` can find it, for example) or in the `.jar` file is irrelevant in determining the name of the schema object. For example, if `Foo.class` consists of a class `Foo` which was specified in the source code as being in package `x.y`, then the full name of the resulting class schema object is as follows:

    x/y/Foo

Note that ".class" is dropped.

If `Foo.sqlj` declares an iterator `MyIter`, then the full name of its class schema object is:

    x/y/MyIter

(Unless it is a nested class, in which case it will not have its own schema object.)

The related profile-keys class file, generated by SQLJ when you translate `Foo.sqlj`, is `Foo_SJProfileKeys.class`; therefore, the full name of its class schema object is:

    x/y/Foo_SJProfileKeys

If the `-ser2class` option was enabled when you translated your application, then the resulting profile was generated in file `Foo_SJProfile0.class`; therefore, the full name of the class schema object is:

    x/y/Foo_SJProfile0

#### Full Names of Loaded Resources (including profiles if -ser2class not enabled)

This discussion is relevant only if you did not enable the `-ser2class` option when you translated your application, or if you use other Java serialized resource (`.ser`) files in your application.

The naming of resource schema objects is handled differently from class schema objects--their names are not determined from the contents of the resources. Instead, their full names are identical to the names that appear in a `.jar` file or on the `loadjava` command line, including path information. Note also that the `.ser` extension is not dropped.

It is important to note that because resource names are used to locate the resources at runtime, their names must include the correct path information. In the server, the correct full name of a resource is identical to the relative path and file name that Java would use to look it up on a client.

In the case of a SQLJ profile, this is a subdirectory under the directory specified by the translator `-d` option, according to the package name. If the `-d` option, used to specify the top-level output directory for generated `.class` and `.ser` files, is set to `/mydir` and the application is in package `abc.def`, then `.class` and `.ser` files generated during translation will be placed in the `/mydir/abc/def` directory. (For more information about the SQLJ `-d` option, including the default value, see "Output Directory for Generated .ser and .class Files (-d)".)

At runtime, `/mydir` would presumably be in your `CLASSPATH`, and Java will look for your application components in the `abc/def` directory underneath it.

Therefore, when you load this application into the server, you must run `loadjava` or `jar` from the `-d` directory so that the path you specify on the command line to find the files also indicates the package name, as follows:

    cd /mydir
    loadjava <...options...> abc/def/*.class abc/def/*.ser

Or, if you use a `.jar` file:

    cd /mydir
    jar -cvf myjar.jar abc/def/*.class abc/def/*.ser
    loadjava <...options...> myjar.jar

If your application is `App` and your profile is `App_SJProfile0.ser`, then either of the above examples will correctly result in the following full name of the created resource schema object:

    abc/def/App_SJProfile0.ser

Note that ".ser" is retained.

Note also that if you set`-d` to a directory whose hierarchy has no other contents (which is advisable), you can simply run `jar` as follows to recursively get your application components:

    cd /mydir
    jar -cvf myjar.jar *
    loadjava <...options...> myjar.jar

### Publishing the Application After Loading Class and Resource Files

Before using your SQLJ code in the server, you must publish the top-level methods, as is true of any Java code you use in the server. Publishing includes writing call descriptors, mapping datatypes, and setting parameter modes. For information, see the Oracle8i Java Stored Procedures Developer's Guide.

### Summary: Running a Client Application in the Server

This section summarizes the typical steps of running a client application in the server. As an example, it uses the `NamedIterDemo` sample application provided in "Named Iterator--NamedIterDemo.sqlj".

1. Create a `.jar` file for your application components. For `NamedIterDemo`, the components include `SalesRec.class` as well as the application class and profile.

   You can create a `.jar` file `niter-server.jar` as follows:

       jar cvf niter-server.jar Named*.class Named*.ser SalesRec.class connect.properties

2. Load the `.jar` file into the server.

   Use `loadjava` as follows. This example instructs `loadjava` to use the OCI8 driver in loading the files. The `-resolve` option results in the class files being resolved.

       loadjava -oci8 -resolve -force -user scott/tiger niter-server.jar

3. Create a SQL wrapper in the server for your application.

   For example, run a SQL*Plus script that executes the following:

       set echo on
       set serveroutput on
       set termout on
       set flush on

       execute dbms_java.set_output(10000);

       create or replace procedure SQLJ_NAMED_ITER_DEMO as language java
       name 'NamedIterDemo.main (java.lang.String[])';
       /

   The `DBMS_JAVA.SET_OUTPUT()` routine reroutes default output to your screen, instead of to a trace file; the input parameter is the buffer size in bytes.

4. Execute the wrapper.

   For example:

       sqlplus> call SQLJ_NAMED_ITER_DEMO();

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