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

## SQLJ Runtime

This section presents information about the Oracle SQLJ runtime, which is a thin layer of pure Java code that runs above the JDBC driver. When Oracle SQLJ translates your SQLJ source code, embedded SQL commands in your Java application are replaced by calls to the SQLJ runtime. Runtime classes act as wrappers for equivalent JDBC classes, providing special SQLJ functionality. When the end user runs the application, the SQLJ runtime acts as an intermediary, reading information about your SQL operations from your profile and passing instructions along to the JDBC driver.

A SQLJ runtime can be implemented to use any JDBC driver or vendor-proprietary means of accessing the database. The Oracle SQLJ runtime requires a JDBC driver but can use any standard JDBC driver. To use Oracle-specific database types and features, however, you must use an Oracle JDBC driver. For the purposes of this document, it is generally assumed that you are using an Oracle database and one of the Oracle JDBC drivers.

Notes: The generic SQLJ runtime will be used if your application has no customizations, or none suitable for the connection. The Oracle SQLJ runtime and an Oracle JDBC driver will be required by your application whenever you use the Oracle customizer during translation, even if you do not use Oracle extensions in your code.

### Runtime Packages

The Oracle SQLJ runtime includes packages that you will likely import and use directly, and others that are used only indirectly.

Note: These packages are included in the `runtime.zip` file, which contains classes used only at runtime, in addition to being in the `translator.zip` file.

#### Packages Used Directly

This section lists packages containing classes you can import and use directly in your application. Packages whose names begin with `oracle` are for Oracle-specific SQLJ features.

- `sqlj.runtime`

  This package includes the `ExecutionContext` class, `ConnectionContext` interface, `ResultSetIterator` interface, and wrapper classes for streams (binary, ASCII, and Unicode).

  Interfaces and abstract classes in this package are implemented by classes in the `sqlj.runtime.ref` package or by classes generated by the SQLJ translator.

- `sqlj.runtime.ref`

  The classes in this package implement interfaces and abstract classes in the `sqlj.runtime` package. You will likely use the `sqlj.runtime.ref.DefaultContext` class, which is used to specify your default connection and create default connection context instances. The other classes in this package are used internally by SQLJ in defining classes during code generation, such as iterator classes and connection context classes that you declare in your SQLJ code.

- `oracle.sqlj.runtime`

  This package contains the `Oracle` class that you can use to instantiate the `DefaultContext` class and establish your default connection. It also contains Oracle-specific runtime classes used by the Oracle implementation of SQLJ, including functionality to convert to and from Oracle type extensions.

#### Packages Used Indirectly

This section lists packages containing classes that are for internal use by SQLJ.

- `sqlj.runtime.profile`

  This package contains interfaces and abstract classes that define what SQLJ profiles look like. This includes the `EntryInfo` class and `TypeInfo` class. Each entry in a profile is described by an `EntryInfo` object (where a profile entry corresponds to a SQL operation in your application). Each parameter in a profile entry is described by a `TypeInfo` object.

  The interfaces and classes in this package are implemented by classes in the `sqlj.runtime.profile.ref` package.

- `sqlj.runtime.profile.ref`

  This package contains classes that implement the interfaces and abstract classes of the `sqlj.runtime.profile` package, and are used internally by the SQLJ translator in defining profiles. It also provides the default JDBC-based runtime implementation.

- `sqlj.runtime.error`

  This package, used internally by SQLJ, contains resource files for all generic (non-Oracle-specific) error messages that can be generated by the SQLJ translator.

- `oracle.sqlj.runtime.error`

  This package, used internally by SQLJ, contains resource files for all Oracle-specific error messages that can be generated by the SQLJ translator.

### Categories of Runtime Errors

Runtime errors can be generated by any of the following:

- SQLJ runtime

- JDBC driver

- RDBMS

In any of these cases, a SQL exception is generated as an instance of the `java.sql.SQLException` class or a subclass (such as `sqlj.runtime.SQLNullException)`.

Depending on where the error came from, there might be meaningful information you can retrieve from an exception using the `getSQLState()`, `getErrorCode()`, and `getMessage()` methods. SQLJ errors, for example, include meaningful SQL states and messages. For information, see "Retrieving SQL States and Error Codes".

If errors are generated by the Oracle JDBC driver or RDBMS at runtime, look at the prefix and consult the appropriate documentation:

- Oracle8i JDBC Developer's Guide and Reference for JDBC errors

- Oracle8i Error Messages reference for RDBMS errors

For a list of SQLJ runtime errors, see "Runtime Messages".

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