Overview

Basic Translation Steps and Runtime Processing

This section introduces the following:

basic steps of the Oracle SQLJ translator in translating SQLJ source code
processing by the Oracle SQLJ runtime when a user runs your application

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.

Translation Steps

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.

The Java VM invokes the SQLJ translator.
The translator parses the source code in the .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 translator invokes the semantics-checker, which checks the semantics of embedded SQL statements.

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.
The translator processes your SQLJ source code, converts SQL operations to SQLJ runtime calls, and generates Java output code and one or more SQLJ profiles. A separate profile is generated for each connection context class in your source code, where a different connection context is typically used for each type of database schema you will connect to.

Generated Java code is put into a .java output file, which contains the following:
- any class definitions and Java code from your .sqlj source file
- class definitions created as a result of your SQLJ declarations (see "Overview of SQLJ Declarations")
- a class definition for a specialized class (known as the profile-keys class) that SQLJ generates and uses in conjunction with your profiles
- calls to the SQLJ runtime to implement the actions of your embedded SQL operations
  
  (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.
The Java VM invokes the Java compiler, which is usually, but not necessarily, the standard javac provided with the Sun Microsystems JDK.
The compiler compiles the Java source file generated in step 4 and produces Java .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.
The Java VM invokes the Oracle SQLJ customizer or other specified customizer.
The customizer customizes the profiles generated in step 4.

Notes:

SQLJ generates profiles and the profile-keys class only if your source code includes SQLJ executable statements.

This is a very generic example. It is also possible to specify pre-existing .java files on the command line to be compiled (and to be available for type resolution as well), or to specify pre-existing profiles to be customized, or to specify .jar files containing profiles to be customized. See "Translator Command Line and Properties Files" for more information.

Runtime Processing

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:

SQLJ-generated application code uses methods in a SQLJ-generated profile-keys class to access the connected profile and read the relevant SQL operations. There is mapping between SQLJ executable statements in the application and SQL operations in the profile.
The SQLJ-generated application code calls the SQLJ runtime, which reads the SQL operations from the profile.
The SQLJ runtime calls the JDBC driver and passes the SQL operations to the driver.
The SQLJ runtime passes any input parameters to the JDBC driver.
The JDBC driver executes the SQL operations.
If any data is to be returned, the database sends it to the JDBC driver, which sends it to the SQLJ runtime for use by your application.

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

Summary of Translator Input and Output

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

Input

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

Output

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 source files will be .java files with the same base names as your .sqlj files.

For example, MyClass.sqlj defines class MyClass and the translator produces MyClass.java.
The application profile files contain information about the SQL operations of your SQLJ application. There will be one profile for each kind of database schema you connect to in your application. The profiles will have names with the same base name as your main .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, -ser2class, that instructs the translator to generate profiles as .class files instead of .ser files. Other than the file extension, the naming is the same.

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:

The class file for each class you define consists of the name of the class with the .class extension.

For example, MyClass.sqlj defines MyClass, the translator produces MyClass.java, and the compiler produces MyClass.class
The class that the translator generates is named according to the base name of your main .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
```
The translator names iterator classes and connection context classes according to how you declare them. For example, if you declare an iterator 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.

Output File Locations

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