Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
Library | Service | Contents | Index

## Basic Translation Steps and Runtime Processing

This section introduces the following:

- basic steps of the Oracle SQLJ translator in translating SQLJ source code

- a summary of translator input and output

- processing by the Oracle SQLJ runtime when a user runs your application

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.

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

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 connection class that you use 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 name 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, 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 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 the `MyClass.java` source file, and the compiler produces the `MyClass.class` class file.

- 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`, there will be a `MyIter.class` class file.

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

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

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

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index