Iterator Class Implementation and Advanced Functionality

This section discusses how iterator classes are implemented and what additional functionality they offer beyond the essential methods discussed in "Using Named Iterators" and "Using Positional Iterators".

Implementation and Functionality of Iterator Classes

Any named iterator class you declare will be generated by the SQLJ translator to implement the interface sqlj.runtime.NamedIterator. Classes implementing the NamedIterator interface have functionality that maps iterator columns to database columns by name, as opposed to by position.

Any positional iterator class you declare will be generated by the SQLJ translator to implement the interface sqlj.runtime.PositionedIterator. Classes implementing the PositionedIterator interface have functionality that maps iterator columns to database columns by position, as opposed to by name.

Both the NamedIterator interface and the PositionedIterator interface, and therefore all generated SQLJ iterator classes as well, implement or extend the interface sqlj.runtime.ResultSetIterator.

The ResultSetIterator interface specifies the following methods for all SQLJ iterators (both named and positional):

• close()--Closes the iterator.

• getResultSet()--Extracts the underlying JDBC result set from the iterator.

• isClosed()--Determines if the iterator has been closed.

• next()--Moves to the next row of the iterator.

The PositionedIterator interface adds the following method specification for positional iterators:

• endFetch()--Determines if you have reached the last row of a positional iterator.

As discussed in "Using Named Iterators", use the next() method to advance through the rows of a named iterator, and accessor methods to retrieve the data. The SQLJ generation of a named iterator class defines an accessor method for each iterator column, where each method name is identical to the corresponding column name. For example, if you declare a name column, then a name() method will be generated.

As discussed in "Using Positional Iterators", use a FETCH INTO statement together with the endFetch() method to advance through the rows of a positional iterator and retrieve the data. A FETCH INTO statement implicitly calls the next() method and implicitly calls accessor methods that are named according to iterator column numbers. The SQLJ generation of a positional iterator class defines an accessor method for each iterator column, where each method name corresponds to the column position.

Use the close() method to close any iterator once you are done with it.

The getResultSet() method is central to SQLJ-JDBC interoperability and is discussed in "SQLJ Iterator and JDBC Result Set Interoperability".

Use of the IMPLEMENTS Clause in Iterator Declarations

There may be situations where it will be useful to implement an interface in your iterator declaration. For general information and syntax, see "Declaration IMPLEMENTS Clause".

You may, for example, have an iterator class where you want to restrict access to one or more columns. As discussed in "Using Named Iterators", a named iterator class generated by SQLJ will have an accessor method for each column in the iterator. If you want to restrict access to certain columns, you can create an interface with only a subset of the accessor methods, then expose objects of the interface type to the user instead of exposing objects of the iterator class type.

Presume you are creating a named iterator of employee data, with columns empname, empnum, and empsalary. Accomplish this as follows:

#sql iterator EmpIter (String empname, int empnum, float empsalary);

This generates a class EmpIter with accessor methods empname(), empnum(), and empsalary().

Presume, though, that you want to prevent access to the empsalary column. You can create an interface EmpIterIntfc that has empname() and empnum() methods but no empsalary() method, then you can use the following iterator declaration instead of the declaration above (presume EmpIterIntfc is in package mypackage):

#sql iterator EmpIter implements mypackage.EmpIterIntfc 
     (String empname, int empnum, float empsalary);

Then if you code your application so that users can access data only through EmpIterIntfc objects, they will not have access to the empsalary column.

---