SQLJ in the Server

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 Java VM. 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 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 resources, primarily profiles). A separate schema object is created for each class and for each profile or other resource.

Class schema objects are created when source is loaded; resource schema objects for profiles are created when source is translated.

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.

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 that is contained in the source. Such implicit translation may seem surprising at first because there is nothing comparable in client-side SQLJ.

The loadjava utility defaults to the JDBC OCI 8 driver, for which you do not specify a URL. Alternatively, you can use the Thin driver by using the -thin option and specifying an appropriate URL through the -user option, as shown in one of the examples below.

Notes:

The -resolve option directs loadjava to resolve external references in each class after all classes on the command line (or in a .jar file) are loaded.

If you enable -resolve, loadjava will output any translation or compilation error messages to your screen.

If you do not enable -resolve but the source is later translated and compiled implicitly, then translation and compilation error messages are inserted in the user schema USER_ERRORS table.

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

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 "Generated Output from loadjava and the Server Embedded Translator".

Before running loadjava, however, you must first set SQLJ options appropriately. For more information, see "Option Support in the Server Embedded Translator". Note that encoding is set on the loadjava command line instead of as a SQLJ 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.

For more information about the loadjava utility, see the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide.

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

Once you load classes and resources from a source file, you cannot subsequently load the classes and resources directly unless you first drop the source. (See "Dropping Java Schema Objects".)

You can put multiple .sqlj files into a .jar file and specify the .jar file to loadjava. When you create the .jar file, the files it contains must be uncompressed. The loadjava utility does not support compressed files.

By default, loadjava loads into the login schema specified by the -user option. Use the -schema option to specify a different schema to load into. This does not involve a login to that schema, but does require that you have sufficient permissions to alter it.

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 that is contained in the source. Such implicit translation may seem surprising at first because there is nothing comparable in client-side SQLJ.

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

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

Option Support in the Server Embedded Translator

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

encoding
online
debug

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 or not 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.

See the Oracle8i Enterprise JavaBeans and CORBA Developer's Guide for more information about the loadjava utility.

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.

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

Generated Output from loadjava and the Server Embedded Translator

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.

Notes:

There are two forms of schema object names in the server: full names and short names. For information about these and about other file naming considerations, see "Full Names vs. Short Names in the Server".

Use the loadjava -verbose option for a report of schema objects produced and what they are named.

Full Name of Source

When you load a source file into the server, whether or not 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

If you define additional classes or declare iterator or connection context classes, then the source schema object is named according to the first class definition or declaration encountered. Whether any of the classes is public is irrelevant in naming the source schema object.

For example, if Foo.sqlj is still in package x.y, defines class Bar first and then class Foo, and has no 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 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

Classes 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 class Bar then class Foo, then declares 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

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

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

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

Presume for this example that there is only one profile.

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

Additional Steps After Loading Source Files

You can access the USER_OBJECTS view in your database schema to verify that your source file and the generated classes and profiles are loaded properly. See "Checking Java Uploads" for more information.

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