Oracle8i SQLJ Developer's Guide and Reference
Release 3 (8.1.7)

Part Number A83723-01


Solution Area



Go to previous page Go to beginning of chapter Go to next page

Basic Translation Steps and Runtime Processing

This section introduces the following:

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. The file name must be a legal Java identifier. 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 should match the first defined class.

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 virtual machine (JVM), and passes arguments to it. The JVM 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.

  1. The JVM invokes the SQLJ translator.

  2. 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 used as input or output parameters in your SQL operations. "Java Host Expressions, Context Expressions, and Result Expressions" describes them.)

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

  4. 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 class is typically used for each interrelated set of SQL entities that you use in your database operations.

    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 iterator and connection context 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 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.

  5. The JVM invokes the Java compiler, which is usually, but not necessarily, the standard javac provided with the Sun Microsystems JDK.

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

  7. The JVM invokes the Oracle SQLJ customizer or other specified customizer.

  8. The customizer customizes the profiles generated in step 4.


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

    • When you use the Oracle customizer during translation, your application will require the Oracle SQLJ runtime and an Oracle JDBC driver when it runs, even if you do not actually use Oracle-specific features.

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


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.


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:


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:

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, known as the profile-keys 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"). Also, separate .class files will be produced for any inner classes or anonymous classes in your code.

The .class files are named as follows:

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.  

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

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:

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

  2. The SQLJ-generated application code calls the SQLJ runtime, which reads the SQL operations from the profile.

  3. The SQLJ runtime calls the JDBC driver and passes the SQL operations to the driver.

  4. The SQLJ runtime passes any input parameters to the JDBC driver.

  5. The JDBC driver executes the SQL operations.

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


    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 or output for SQL operations.  

Go to previous page
Go to beginning of chapter
Go to next page
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.


Solution Area