|Oracle8i SQLJ Developer's Guide and Reference
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:
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.
.sqljfile, 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:
(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.
javacprovided with the Sun Microsystems JDK.
.classfiles as appropriate. This will include a
.classfile for each class you defined, a
.classfile for each of your SQLJ declarations, and a
.classfile for the profile-keys class.
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:
Passing input parameters (step 4) can also be referred to as "binding input parameters" or "binding host expressions". The terms host variables, host expressions, bind variables, and bind expressions are all used to describe Java variables or expressions that are used as input to or output from SQL operations.
This section summarizes what the SQLJ translator takes as input, what it produces as output, and where it puts its output.
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
If your main
.sqlj file defines class
MyClass, then the source file name must be:
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:
.javafiles with the same base names as your
MyClass.sqlj defines class
MyClass and the translator produces
.sqljfile, plus the following extensions:
For example, for
MyClass.sqlj the translator produces:
.ser file extension reflects the fact that the profiles are serialized. The
.ser files are binary files.
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:
MyClass, the translator produces
MyClass.java, and the compiler produces
.sqljfile, plus the following:
So the class file has the following extension:
For example, for
MyClass.sqlj, the translator together with the compiler produce:
MyIter, the resulting class file will be
The customization step alters the profiles but produces no additional output.
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
By default, SQLJ places generated
.ser files in the same directory as the generated
.java files. You can specify a different
.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
-dir option, you must specify a directory that already exists. For more information about these options, see "Options for Output Files and Directories".