Oracle8i SQLJ Developer's Guide and Reference Release 8.1.5 A64684-01 |
|
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 |
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.
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:
|
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.
The following options are available in the server-side SQLJ translator:
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 |
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).
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).
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
:
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:
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.
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');
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:
The full names of these schema objects are determined as described in the following subsections.
Notes:
|
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
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.
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. |
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.
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.