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

## Loading SQLJ Source and Translating in the Server

Another approach to developing SQLJ code for the server is loading the source code into the server and translating it directly in the server. This employs the embedded SQLJ translator in the Oracle8i JServer JVM. This discussion still assumes you created the source on a client machine.

As a general rule, loading SQLJ source into the server is identical to loading Java source into the server, with translation taking place implicitly when a compilation option is set (such as the `loadjava -resolve` option, discussed below).

When you load `.sqlj` source files into the server, either directly or using a `.jar` file, the resulting database library units containing the source code are referred to as Java source schema objects. A separate schema object is created for each source file.

When translation and compilation take place, the resulting library units for the generated classes and profiles are referred to as Java class schema objects (for classes) and Java resource schema objects (for profiles), just as they are when loaded directly into the server from `.class` files and `.ser` files created on a client. A separate schema object is created for each class and for each profile.

Resource schema objects are also used for properties files that you load into the server.

Note: When you translate your SQLJ application in the server, profiles are always generated as resources, not classes, because there is no `-ser2class` option in SQLJ server-side translator.

### Loading SQLJ Source Code into the Server

Use the Oracle `loadjava` client-side utility on a `.sqlj` file (instead of on `.class` and `.ser` files) to load source into the server. This utility is discussed in detail in the Oracle8i Java Developer's Guide.

If you enable the `loadjava -resolve` option in loading a `.sqlj` file, then the server-side embedded translator is run to perform the translation, compilation, and customization of your application as it is loaded. Otherwise, the source is loaded into a source schema object without any translation. In this case, however, the source is implicitly translated, compiled, and customized the first time an attempt is made to use a class defined in the source. Such implicit translation might seem surprising at first, because there is nothing comparable in client-side SQLJ.

For example, run `loadjava` as follows:

    loadjava -user scott/tiger -resolve Foo.sqlj

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

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

Either of these will result in appropriate class schema objects and resource schema objects being created in addition to the source schema object. For information, see "Loaded Source and Generated Class and Resource Schema Objects".

Before running `loadjava`, however, you must set SQLJ options appropriately. For more information, see "Option Support in the Server Embedded Translator". Note that encoding can be set on the `loadjava` command line, instead of through the server-side SQLJ `encoding` option, as follows:

    loadjava -user scott/tiger -resolve -encoding SJIS Foo.sqlj

The `loadjava` script, which runs the actual utility, is in the `bin` subdirectory under your `[Oracle Home]` directory. This directory should already be in your path once Oracle has been installed.

Notes: You cannot load a `.sqlj` file along with `.class` files or `.ser` files that were generated from processing of the same `.sqlj` file. This would create an obvious conflict, because the server would be trying to load the same classes and profiles that it would also be trying to generate. (In processing a `.jar` file, `loadjava` first processes `.sqlj`, `.java`, and `.class` files. It then makes a second pass and processes everything else as Java resource files.) You can put multiple `.sqlj` files into a `.jar` file and specify the `.jar` file to `loadjava`. 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 COMPILE> JAVA SOURCE <NAMED srcname> <AS loadname>;

If you specify `AND COMPILE` for a `.sqlj` file, then the source is translated, compiled, and customized at that time, creating class schema objects and resource schema objects as appropriate in addition to the source schema object. Otherwise, it is not translated and compiled--in this case only the source schema object is created. In this latter case, however, the source is implicitly translated, compiled, and customized the first time an attempt is made to use a class contained in the source.

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

Note: When you first load a source file, some checking of the source code is performed, such as determining what classes are defined. If any errors are detected at this time, then the load fails.

### Option Support in the Server Embedded Translator

The following options are available in the server-side SQLJ translator:

- `encoding`

- `online`

- `debug`

  Note: Class schema objects created during server-side translation reference line numbers that map to the SQLJ source code. This is equivalent to enabling the `-linemap` option when you translate on a client. (For a discussion of this option, see "Line-Mapping to SQLJ Source File (-linemap)".)

This section includes discussion of the `loadjava` utility and its `-resolve` option. For more information, see the Oracle8i Java Developer's Guide.

#### The encoding Option

This option determines any encoding (for example, `SJIS`) employed to interpret your source code when it is loaded into the server. The `encoding` option is used at the time the source is loaded, regardless of whether it is also compiled.

Alternatively, when using `loadjava` to load your SQLJ application into the server, you can specify encoding on the `loadjava` command line, as discussed in "Loading SQLJ Source Code into the Server". Any `loadjava` command-line setting for encoding overrides this `encoding` option.

See "Encoding for Input and Output Source Files (-encoding)" for general information about this option.

Note: If no encoding is specified, either through this option or through `loadjava`, then encoding is performed according to the `file.encoding` setting of the client from which you run `loadjava`.

#### The online Option

Setting this option to `TRUE` (the default value) enables online semantics-checking. Semantics-checking is performed relative to the schema in which the source is loaded. You do not specify an exemplar schema, as you do for online-checking on a client.

If the `online` option is set to `FALSE`, offline checking is performed.

In either case, the default checker is `oracle.sqlj.checker.OracleChecker`, which will choose an appropriate checker, depending on your JDBC driver version and database version. For information about `OracleChecker`, see "Semantics-Checkers and the OracleChecker Front End (default checker)".

The `online` option is used at the time the source is translated and compiled. If you load it with the `loadjava` `-resolve` option enabled, this will occur immediately. Otherwise it will occur the first time an attempt is made to use a class defined in the source (resulting in implicit translation and compilation).

Note: The `online` option is used differently in the server than on a client. In the server, the `online` option is only a flag that enables online checking using a default checker. On a client, the `-online` option specifies which checker to use, but it is the `-user` option that enables online checking.

#### The debug Option

Setting this option to `TRUE` instructs the server-side Java compiler to output debugging information when a `.sqlj` or `.java` source file is compiled in the server. This is equivalent to using the `-g` option when running the standard `javac` compiler on a client.

The `debug` option is used at the time the source is compiled. If you load it with the `loadjava` `-resolve` option enabled, this will occur immediately (right after SQLJ translation, in the case of a `.sqlj` file). Otherwise it will occur the first time an attempt is made to use a class defined in the source (resulting in implicit translation and compilation).

#### Setting SQLJ Options in the Server

There is no command line and there are no properties files when running the SQLJ translator in the server. Information about translator and compiler options is held in each schema in a table named `JAVA$OPTIONS`. Manipulate options in this table through the following functions and procedures of the package `DBMS_JAVA`:

- `dbms_java.get_compiler_option()`

- `dbms_java.set_compiler_option()`

- `dbms_java.reset_compiler_option()`

Use `set_compiler_option()` to specify separate option settings for individual packages or sources. It takes the following as input, with each parameter enclosed by single-quotes:

- package name, using dotted names, or source name

  Specify this as a full name, not a short name.

  If you specify a package name, the option setting applies to all sources in that package and subpackages, except where you override the setting for a particular subpackage or source.

- option name

- option setting

Execute the `DBMS_JAVA` routines using `SQL*Plus`, for example, as follows:

    sqlplus> execute dbms_java.set_compiler_option('x.y', 'online', 'true');
    sqlplus> execute dbms_java.set_compiler_option('x.y.Create', 'online', 'false');

These two commands enable online checking for all sources in the package `x.y`, then override that for the `Create` source by disabling online checking for that particular source.

Similarly, set encoding for package `x.y` to `SJIS` as follows:

    sqlplus> execute dbms_java.set_compiler_option('x.y', 'encoding', 'SJIS');

- Notes: The `set_compiler_option()` parameter for package and source names uses dotted names (such as `abc.def` as a package name) even though schema object names use slash syntax (such as `abc/def` as a package name). When you specify a package name, be aware that the option will apply to any included packages as well. A setting of `a.b.MyPackage` sets the option for any source schema objects whose names are of the following form:
       a/b/MyPackage/subpackage/...
Specifying `''` (empty set of single-quotes) as a package name makes the option apply to the root and all subpackages, effectively making it apply to all packages in your schema.

### Loaded Source and Generated Class and Resource Schema Objects

When you use the server-side SQLJ translator, such as when you use `loadjava` on a `.sqlj` file with the `-resolve` option enabled, the output generated by the server-side translator is essentially identical to what would be generated on a client--a compiled class for each class you defined in the source, a compiled class for each iterator and connection context class, a compiled profile-keys class, and one or more customized profiles.

As a result, the following schema objects will be produced when you load a `.sqlj` file into the server with `loadjava` and have it translated and compiled:

- a source schema object for the original source code

- a class schema object for each class you defined in the source

- a class schema object for each iterator or connection context class you declared in the source (but presumably you do not declare connection context classes in code that will run in the server)

- a class schema object for the profile-keys class (created by the translator, as on a client, presuming you use SQLJ executable statements in your code)

- a resource schema object for the profile (presumably there is just one profile)

The full names of these schema objects are determined as described in the following subsections. Use the `loadjava` `-verbose` option for a report of schema objects produced and what they are named.

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 Name of Source

When you load a source file into the server, regardless of whether it is translated and compiled, a source schema object is produced. The full name of this schema object is determined by the package and class names in the source code. Any path information you supply on the command line (so `loadjava` can find it) is irrelevant to the determination of the name of the schema object.

For example, if `Foo.sqlj` defines a class `Foo` in package `x.y` and defines or declares no other classes, then the full name of the resulting source schema object is:

    x/y/Foo

Note that ".sqlj" is dropped.

If you define additional classes or declare iterator or connection context classes, then the source schema object is named according to the first public class definition or declaration encountered, or, if there are no public classes, the first class definition. (In the server, there can be more than one public class definition in a single source.)

For example, if `Foo.sqlj` is still in package `x.y`, defines public class `Bar` first and then class `Foo`, and has no public iterator or connection context class declarations preceding the definition of `Bar`, then the full name of the resulting source schema object is:

    x/y/Bar

If, however, the declaration of public iterator class `MyIter` precedes the `Bar` and `Foo` class definitions, then the full name of the resulting source schema object is:

    x/y/MyIter

#### Full Names of Generated Classes

Class schema objects are generated for each class you defined in the source, each iterator you declared, and the profile-keys class. The naming of the class schema objects is based on the class names and the package name from the source code.

This discussion continues the example in "Full Name of Source". Presume your source code specifies package `x.y`, defines public class `Bar` then class `Foo`, then declares public iterator class `MyIter`. The full names of the class schema objects for the classes you define and declare are as follows:

    x/y/Bar
    x/y/Foo
    x/y/MyIter

Note that ".class" is not appended.

The profile-keys class is named according to the name of the source schema object, appended by:

    _SJProfileKeys

If the `Bar` definition precedes the `Foo` definition and `MyIter` declaration, then the class schema object for the profile-keys class is named:

    x/y/Bar_SJProfileKeys

If the `MyIter` declaration precedes either of the class definitions, then the profile-keys class schema object is named:

    x/y/MyIter_SJProfileKeys

Note: It is recommended that the source name always match the first public class defined, or, if there are no public classes, the first class defined. This will avoid possible differences between client-side and server-side behavior.

The name of the original source file, as well as any path information you specify when loading the source into the server, is irrelevant in determining the names of the generated classes.

If you define inner classes or anonymous classes in your code, then they are named according to the conventions of the standard `javac` compiler.

#### Full Names of Generated Profiles

Resource schema objects for generated profiles are named in the same way as the profile-keys class schema object--based on the source schema object name, using package and class information from the source code in the same way. Any directory information specified on the command line (the `loadjava` command line, for example) or in a `.jar` file is irrelevant in determining the profile name.

When a source file is loaded and translated, the generated profiles use the source schema object name as a base name, followed by:

    _SJProfile0.ser
    _SJProfile1.ser
    ...

Note that ".ser" is included.

This is identical to what is appended to produce a profile name on the client.

Using the examples in "Full Name of Source", where the source schema object was named either `x/y/Foo`, `x/y/Bar`, or `x/y/MyIter` (depending on the situation, as discussed), the name of the profile would be:

    x/y/Foo_SJProfile0.ser

or:

    x/y/Bar_SJProfile0.ser

or:

    x/y/MyIter_SJProfile0.ser

Note: Usually there will be no declared connection context classes--and, therefore, only one profile--in an application that runs in the server.

### Error Output from the Server Embedded Translator

SQLJ error processing in the server is similar to general Java error processing in the server. SQLJ errors are directed into the `USER_ERRORS` table of the user schema. You can `SELECT` from the `TEXT` column of this table to get the text of a given error message.

If you use `loadjava` to load your SQLJ source, however, `loadjava` also captures and outputs the error messages from the server-side translator.

Informational messages and suppressable warnings are withheld by the server-side translator in a way that is equivalent to the operation of the client-side translator with a `-warn=noportable,noverbose` setting (which is the default). See "Translator Warnings (-warn)" for more information about the `-warn` option of the client-side translator.

### Publishing the Application After Loading Source 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.

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