Overview of SQLJ Declarations

A SQLJ declaration consists of the #sql token followed by the declaration of a class. SQLJ declarations introduce specialized Java types into your application. There are currently two kinds of SQLJ declarations, iterator declarations and connection context declarations, defining Java classes as follows:

• Iterator declarations define iterator classes. Iterators are conceptually similar to JDBC result sets and are used to receive multi-row query data. An iterator is implemented as an instance of an iterator class.

• Connection context declarations define connection context classes. Different connection context classes are typically used for connections to different types of database schemas. That is to say, instances of a particular connection context class are typically used to connect to schemas that have the same SQL objects (tables, views, stored procedures, and so on). SQLJ implements each database connection as an instance of a connection context class.

In any iterator or connection context declaration, you may optionally include the following clauses:

• implements clause--Specifies one or more interfaces that the generated class will implement.

• with clause--Specifies one or more initialized constants to be included in the generated class.

These are described in "Declaration IMPLEMENTS Clause" and in "Declaration WITH Clause".

Rules for SQLJ Declarations

SQLJ declarations are allowed in your SQLJ source code in the top-level scope, a class scope, or a nested-class scope but not inside method blocks. For example:

SQLJ declaration;   // OK (top level scope)

class Outer
{
   SQLJ declaration; // OK (class level scope)

   class Inner
   {
      SQLJ declaration; // OK (nested class scope)
   }

   void func()
   {
      SQLJ declaration; // ILLEGAL (method block)
   }
}

Iterator Declarations

An iterator declaration creates a class that defines a kind of iterator for receiving query data. The declaration will specify the column types of the iterator instances, which must match the column types being selected from the database table.

Basic iterator declarations use the following syntax:

#sql <modifiers> iterator iterator_classname (type declarations);

Modifiers are optional and can be any standard Java class modifiers such as public, static, etc. Type declarations are separated by commas.

There are two categories of iterators--named iterators and positional iterators. For named iterators, you specify column names and types; for positional iterators, you specify only types.

The following is an example of a named iterator declaration:

#sql public iterator EmpIter (String ename, double sal);

This statement results in the SQLJ translator creating a public EmpIter class with a String attribute ename and a double attribute sal. You can use this iterator to select data from a database table with corresponding employee name and salary columns of matching names (ENAME and SAL) and datatypes (CHAR and NUMBER).

Note: As with standard Java, any public class should be declared in a separate source file (this is a requirement if you are using the standard javac compiler provided with the Sun JDK). The base name of the file should be the same as the class name. Given the above example, declare the iterator class in a file EmpIter.sqlj.

Declaring EmpIter as a positional iterator instead of a named iterator would be done as follows:

#sql public iterator EmpIter (String, double);

For more information about iterators, see "Multi-Row Query Results--SQLJ Iterators".

Connection Context Declarations

A connection context declaration creates a connection context class, whose instances are typically used for database connections to a particular type of database schema.

Basic connection context declarations use the following syntax:

#sql <modifiers> context context_classname;

As for iterator declarations, modifiers are optional and can be any standard Java class modifiers. The following is an example:

#sql public context MyContext;

As a result of this statement, the SQLJ translator creates a public MyContext class. In your SQLJ code you can use instances of this class to create database connections to a schema of a given type, where a schema type has a particular set of objects, such as tables, views, and stored procedures.

Note: As with standard Java, any public class should be declared in a separate source file (this is a requirement if you are using the standard javac compiler provided with the Sun JDK). The base name of the file should be the same as the class name. Given the above example, declare the connection context class in a file MyContext.sqlj.

Specified connection contexts are an advanced topic and are not necessary for basic SQLJ applications that connect to only one type of schema. In more basic scenarios you can use multiple connections by creating multiple instances of the sqlj.runtime.ref.DefaultContext class, which does not require any connection context declarations.

See "Connection Considerations" for an overview of connections and connection contexts.

For information about creating additional connection contexts, see "Connection Contexts".

Declaration IMPLEMENTS Clause

In declaring any iterator class or connection context class, you can specify one or more interfaces to be implemented by the generated class. Use the following syntax for an iterator class:

#sql <modifiers> iterator iterator_classname implements intfc1,..., intfcN 
     (type declarations);

The portion implements intfc1,..., intfcN is known as the implements clause. Note that in an iterator declaration, the implements clause precedes the iterator type declarations.

Here is the syntax for a connection context declaration:

#sql <modifiers> context context_classname implements intfc1,..., intfcN;

There is potential usefulness for the implements clause in either an iterator declaration or a connection context declaration, but as a general comment it is more likely to be useful in iterator declarations. For information, see "Use of the IMPLEMENTS Clause in Iterator Declarations" and "Use of the IMPLEMENTS Clause in Connection Context Declarations".

Note: The SQLJ implements clause corresponds to the Java implements clause.

The following example uses an implements clause in declaring a named iterator class (presume you have created a package mypackage that includes an iterator interface MyIterIntfc).

#sql public iterator MyIter implements mypackage.MyIterIntfc 
     (String empname, int empnum);

The declared class, MyIter, will implement the interface mypackage.MyIterIntfc.

This next example declares a connection context class that implements an interface named MyConnCtxtIntfc (presume it also is in package mypackage).

#sql public context MyContext implements mypackage.MyConnCtxtIntfc; 

Declaration WITH Clause

In declaring any iterator class or connection context class, you can specify and initialize one or more constants to be included in the definition of the generated class. The constants produced are always public static final. Use the following syntax for an iterator class:

#sql <modifiers> iterator iterator_classname with (var1=value1,..., varN=valueN)
     (type declarations);

The portion with (var1=value1,..., varN=valueN) is known as the with clause. Note that in an iterator declaration, the with clause precedes the iterator type declarations.

Where there is both a with clause and an implements clause, the implements clause must come first. Note that parentheses are used to enclose with lists but not implements lists.

Here is the syntax for a connection context declaration:

#sql <modifiers> context context_classname 
     with (var1=value1,..., varN=valueN);

Note: Unlike the implements clause, there is no Java clause that corresponds to the SQLJ with clause.

Note: There is a predefined set of standard SQLJ constants that can be defined in a with clause. Attempts to define constants other than the standard constants (as in the example below) is legal with an Oracle8i database, but may not be portable to other SQLJ implementations and will generate a warning if you have the -warn=portable flag enabled. (For information about this flag, see "Translator Warnings (-warn)".) The standard constants mostly involve cursor states and can take only particular values. These constants are not meaningful to an Oracle8i database, but because they are supported by the SQLJ standard, they are listed here with their possible values: sensitivity (SENSITIVE/ASENSITIVE/INSENSITIVE) holdability (true/false) returnability (true/false) updateColumns (a String literal containing a comma-separated list of column names) An iterator declaration with a with clause that specifies updateColumns must also have an implements clause that specifies sqlj.runtime.ForUpdate.

The following example uses a with clause in declaring a named iterator.

#sql public iterator MyIter with (TYPECODE=OracleTypes.NUMBER) 
     (String empname, int empnum);

The declared class, MyIter, will define an attribute TYPECODE that will be public static final of type int and initialized to the value of the typecode for the NUMBER datatype, as defined in the Oracle JDBC class oracle.jdbc.driver.OracleTypes.

Here is another example:

#sql public iterator MyAsensitiveIter with (sensitivity=ASENSITIVE) 
     (String empname, int empnum);

This declaration sets the cursor sensitivity to ASENSITIVE for a named iterator class (but note that sensitivity is not supported in the Oracle8i database).

The following example uses both an implements clause and a with clause.

#sql public iterator MyIter implements mypackage.MyIterIntfc 
     with (holdability=true) (String empname, int empnum);

Note that the implements clause must precede the with clause.

This declaration implements the interface mypackage.MyIterIntfc and enables cursor holdability for a named iterator class (but note that holdability is not currently supported in the Oracle8i database).

---