Oracle8i SQLJ Developer's Guide and Reference Release 2 (8.1.6) A81360-01 |
|
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".
Any named iterator class you declare will be generated by the SQLJ translator to implement the sqlj.runtime.NamedIterator
interface. 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 sqlj.runtime.PositionedIterator
interface. 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 sqlj.runtime.ResultSetIterator
interface.
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:
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; do not explicitly use the next()
method in a positional iterator. The FETCH INTO
statement also 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".
Note:
You can use a |
There might 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 might, 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 instances of the interface type to the user instead of exposing instances of the iterator class type.
For example, assume you are creating a named iterator of employee data, with columns ENAME
(employee name), EMPNO
(employee number), and SAL
(salary). Accomplish this as follows:
#sql iterator EmpIter (String ename, int empno, float sal);
This generates a class EmpIter
with ename()
, empno()
, and sal()
accessor methods.
Assume, though, that you want to prevent access to the SAL
column. You can create an interface EmpIterIntfc
that has ename()
and empno()
methods but no sal()
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 emame, int empno, float sal);
Then if you code your application so that users can access data only through EmpIterIntfc
instances, they will not have access to the SAL
column.
With release 8.1.6, SQLJ supports the ability to subclass iterator classes. This feature can be very useful in allowing you to add functionality to your queries and query results. For example, see "Subclassing Iterators--SubclassIterDemo.sqlj" for an example of an iterator subclass that treats rows of a query as individual objects and writes them into a Java vector.
The one key requirement of an iterator subclass is that you supply a public constructor that takes an instance of sqlj.runtime.RTResultSet
as input. The SQLJ runtime will call this constructor in assigning query results to an instance of your subclass. Beyond that, you provide functionality as you choose.
As convenient, you can continue to use functionality of the original iterator class (the superclass of your subclass). For example, you can advance through query results by calling the super.next()
method.