Oracle8i SQLJ Developer's Guide and Reference Release 8.1.5 A64684-01 |
|
This section introduces the following:
This is followed by a summary of translator input and output.
For more detailed information about the translation steps, see "Internal Translator Operations".
SQLJ source code contains a mixture of standard Java source together with SQLJ class declarations and SQLJ executable statements containing embedded SQL operations.
SQLJ source files have the .sqlj
file name extension. If the source file declares a public class (maximum of one), then the file name must match the name of this class. If the source file does not declare a public class, then the file name must still be a legal Java identifier, and it is recommended that the file name match one of the defined classes.
After you have completed your .sqlj
file, you must run SQLJ to process the files. This example, for the source file Foo.sqlj
whose first public class is Foo
, shows SQLJ being run in its simplest form, with no command-line options:
sqlj Foo.sqlj
What this command actually runs is a front-end script or utility (depending on the platform) that reads the command line, invokes a Java VM, and passes arguments to the VM. The Java VM invokes the SQLJ translator and acts as a front end.
This document refers to running the front-end as "running SQLJ" and to its command line as the "SQLJ command line". For information about command-line syntax, see "Command-Line Syntax and Operations".
From this point the following sequence of events occurs, presuming each step completes without fatal error.
.sqlj
file, checking for proper SQLJ syntax and looking for type mismatches between your declared SQL datatypes and corresponding Java host variables. (Host variables are local Java variables that are used as input or output parameters in your SQL operations. "Java Host Expressions, Context Expressions, and Result Expressions" describes them.)
The developer can use online or offline checking, according to SQLJ option settings. If online checking is performed, then SQLJ will connect to the database to verify that the database supports all of the database tables, stored procedures, and SQL syntax that the application uses, and that the host variable types in the SQLJ application are compatible with datatypes of corresponding database columns.
Generated Java code is put into a .java
output file, which contains the following:
.sqlj
source file
(The SQLJ runtime, in turn, uses the JDBC driver to access the database. See "SQLJ Runtime" for more information.)
Generated profiles contain information about all of the embedded SQL statements in your SQLJ source code, such as actions to take, datatypes being manipulated, and tables being accessed. When your application is run, the SQLJ runtime accesses the profiles to retrieve your SQL operations and pass them to the JDBC driver.
By default, profiles are put into .ser
serialized resource files, but SQLJ can optionally convert the .ser
files to .class
files as part of the translation.
javac
provided with the Sun Microsystems JDK.
.class
files as appropriate. This will include a .class
file for each class you defined, a .class
file for each of your SQLJ declarations, and a .class
file for the profile-keys class.
Notes:
|
When a user runs the application, the SQLJ runtime reads the profiles and creates "connected profiles", which incorporate database connections. Then the following occurs each time the application must access the database:
This section summarizes what the SQLJ translator takes as input, what it produces as output, and where it puts its output.
Note: This discussion mentions iterator class and connection context class declarations. Iterators are similar to JDBC result sets; connection contexts are used for database connections. For more information about these class declarations, see "Overview of SQLJ Declarations". |
In its most basic operation, the SQLJ translator takes one or more .sqlj
source files as input in its command line. The name of your main .sqlj
file is based on the public class it defines, if it defines one, or else on the first class it defines if there are no public class definitions. Each public class you define must be in its own .sqlj
file.
If your main .sqlj
file defines class MyClass
, then the source file name must be:
MyClass.sqlj
This will also be the file name if there are no public class definitions but MyClass
is the first class defined.
When you run SQLJ, you can also specify numerous SQLJ options in the command line or properties files.
For more information about SQLJ input, including additional types of files you can specify in the command line, see "Translator Command Line and Properties Files".
The translation step produces a Java source file for each .sqlj
file in your application, and at least one application profile (presuming your source code uses SQLJ executable statements).
SQLJ generates source files and profiles as follows:
.java
files with the same base names as your .sqlj
files.
For example, MyClass.sqlj
defines class MyClass
and the translator produces MyClass.java
.
.sqlj
file, plus the following extensions:
_SJProfile0.ser _SJProfile1.ser _SJProfile2.ser ...
For example, for MyClass.sqlj
the translator produces:
MyClass_SJProfile0.ser
The .ser
file extension reflects the fact that the profiles are serialized. The .ser
files are binary files.
Note:
There is a translator option, |
The compilation step compiles the Java source file into multiple class files. There are at least two class files: one for each class you define in your .sqlj
source file (minimum of one) and one for a class that the translator generates and uses with the profiles to implement your SQL operations (presuming your source code uses SQLJ executable statements). Additional .class
files are produced if you declared any SQLJ iterators or connection contexts (see "Overview of SQLJ Declarations"). The .class
files are named as follows:
.class
extension.
For example, MyClass.sqlj
defines MyClass
, the translator produces MyClass.java
, and the compiler produces MyClass.class
.sqlj
file, plus the following:
_SJProfileKeys
So the class file has the following extension:
_SJProfileKeys.class
For example, for MyClass.sqlj
, the translator together with the compiler produce:
MyClass_SJProfileKeys.class
MyIter
, the resulting class file will be MyIter.class
.
The customization step alters the profiles but produces no additional output.
Note: It is not necessary to reference SQLJ profiles or the profile-keys class directly. This is all handled automatically. |
By default, SQLJ places generated .java
files in the same directory as your .sqlj
file. You can specify a different .java
file location, however, using the SQLJ -dir
option.
By default, SQLJ places generated .class
and .ser
files in the same directory as the generated .java
files. You can specify a different .class
and .ser
file location, however, using the SQLJ -d
option. This option setting is passed to the Java compiler so that .class
files and .ser
files will be in the same location.
For either the -d
or -dir
option, you must specify a directory that already exists. For more information about these options, see "Options for Output Files and Directories".