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.

---