org.apache.empire.db
Class DBReader

java.lang.Object
  extended by org.apache.empire.commons.ErrorObject
      extended by org.apache.empire.db.DBObject
          extended by org.apache.empire.db.DBRecordData
              extended by org.apache.empire.db.DBReader
All Implemented Interfaces:
ErrorInfo, RecordData

public class DBReader
extends DBRecordData

This class is used to perform database queries from a DBCommand object and access the results.
In oder to perform a query call the open() function or - for single row queries - call getRecordData();
You can iterate through the rows using moveNext() or an iterator.

However take care: A reader must always be explcitly closed using the close() method!
Otherwise you may lock the JDBC connection and run out of resources.
Use

try { ... } finally { reader.close(); } 
to make sure the reader is closed.

To access and work with the query result you can do one of the following:


Nested Class Summary
 class DBReader.DBReaderForwardIterator
          This is an iterator for forward only resultsets.
 class DBReader.DBReaderIterator
           
 class DBReader.DBReaderScrollableIterator
          This is an iterator for scrolling resultsets.
 
Constructor Summary
DBReader()
          Constructs an empty DBRecordSet object.
 
Method Summary
 boolean addColumnDesc(org.w3c.dom.Element parent)
          Moves the cursor down one row from its current position.
 int addRows(org.w3c.dom.Element parent)
          Adds all children to a parent.
 boolean addRowValues(org.w3c.dom.Element parent)
          Adds all children to a parent.
static void checkOpenResultSets()
           Call this if you want to check whether there are any unclosed resultsets It logs stack traces to help find piece of code where a DBReader was opened but not closed.
 void close()
          Closes the DBRecordSet object, the Statement object and detach the columns.
<T> java.util.ArrayList<T>
getBeanList(java.lang.Class<T> c)
          Returns the result of a query as a list of objects.
<T> java.util.ArrayList<T>
getBeanList(java.lang.Class<T> c, int maxCount)
          Returns the result of a query as a list of objects resticted to a maximum number of objects (unless maxCount is -1).
 DBColumnExpr getColumnExpr(int iColumn)
          Get the column Expression at position
 DBDatabase getDatabase()
          Returns the current DBDatabase object.
 int getFieldCount()
          returns the number of the elements of the colList array
 int getFieldIndex(ColumnExpr column)
          Returns the index value by a specified DBColumnExpr object.
 int getFieldIndex(java.lang.String column)
          Returns the index value by a specified column name.
 boolean getRecordData(DBCommandExpr cmd, java.sql.Connection conn)
           Opens the reader by executing the given SQL command and moves to the first row.
 boolean getScrollable()
           
 java.lang.Object getValue(int index)
          Returns a data value identified by the column index.
 org.w3c.dom.Document getXmlDocument()
          Returns a XML document with the field descriptiona an values of this record.
 boolean initRecord(DBRowSet rowset, DBRecord rec)
           initializes a DBRecord object with the values of the current row.
 boolean isNull(int index)
          Checks wehter a column value is null Unlike the base class implementation, this class directly check the value fromt the resultset.
 boolean isOpen()
          returns null true if the Rowset is not null, and otherwise false
 java.util.Iterator<DBRecordData> iterator()
           Returns an row iterator for this reader.
 java.util.Iterator<DBRecordData> iterator(int maxCount)
          Returns an row iterator for this reader.
 boolean moveNext()
          Moves the cursor down one row from its current position.
 boolean open(DBCommandExpr cmd, boolean scrollable, java.sql.Connection conn)
          Opens the reader by executing the given SQL command.
 boolean open(DBCommandExpr cmd, java.sql.Connection conn)
          Opens the reader by executing the given SQL command.
 boolean skipRows(int count)
          Moves the cursor down the given number of rows.
 
Methods inherited from class org.apache.empire.db.DBRecordData
getBeanProperties, getBeanProperties, getBoolean, getBoolean, getDateTime, getDateTime, getDouble, getDouble, getInt, getInt, getLong, getLong, getString, getString, getValue, isNull
 
Methods inherited from class org.apache.empire.commons.ErrorObject
clearError, getErrorMessage, getErrorParams, getErrorSource, getErrorType, getMessage, hasError, isExceptionsEnabled, setExceptionsEnabled
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DBReader

public DBReader()
Constructs an empty DBRecordSet object.

Method Detail

getDatabase

public DBDatabase getDatabase()
Returns the current DBDatabase object.

Specified by:
getDatabase in class DBObject
Returns:
the current DBDatabase object

getScrollable

public boolean getScrollable()

getFieldIndex

public int getFieldIndex(ColumnExpr column)
Returns the index value by a specified DBColumnExpr object.

Specified by:
getFieldIndex in interface RecordData
Specified by:
getFieldIndex in class DBRecordData
Parameters:
column - the column for which to return the index
Returns:
the index value

getColumnExpr

public DBColumnExpr getColumnExpr(int iColumn)
Get the column Expression at position

Specified by:
getColumnExpr in interface RecordData
Specified by:
getColumnExpr in class DBRecordData
Parameters:
iColumn - field index of the column expression
Returns:
the column expression object or null if the index is out of range

getFieldIndex

public int getFieldIndex(java.lang.String column)
Returns the index value by a specified column name.

Specified by:
getFieldIndex in interface RecordData
Specified by:
getFieldIndex in class DBRecordData
Parameters:
column - the column name
Returns:
the index value

isNull

public boolean isNull(int index)
Checks wehter a column value is null Unlike the base class implementation, this class directly check the value fromt the resultset.

Specified by:
isNull in interface RecordData
Overrides:
isNull in class DBRecordData
Parameters:
index - index of the column
Returns:
true if the value is null or false otherwise

getValue

public java.lang.Object getValue(int index)
Returns a data value identified by the column index.

Specified by:
getValue in interface RecordData
Specified by:
getValue in class DBRecordData
Parameters:
index - index of the column
Returns:
the value

isOpen

public boolean isOpen()
returns null true if the Rowset is not null, and otherwise false


open

public boolean open(DBCommandExpr cmd,
                    boolean scrollable,
                    java.sql.Connection conn)
Opens the reader by executing the given SQL command.
After the reader is open, the reader's position is before the first record.
Use moveNext or iterator() to step through the rows.
Data of the current row can be accessed through the functions on the RecordData interface.

ATTENTION: After using the reader it must be closed using the close() method!
Use

try { ... } finally { reader.close(); } 
to make sure the reader is closed.

Parameters:
cmd - the SQL-Command with cmd.getSelect()
scrollable - true if the reader should be scrollable or false if not
conn - a valid JDBC connection.
Returns:
true if successful

open

public boolean open(DBCommandExpr cmd,
                    java.sql.Connection conn)
Opens the reader by executing the given SQL command.

see open(DBCommandExpr, boolean, Connection)

Parameters:
cmd - the SQL-Command with cmd.getSelect()
conn - a valid JDBC connection.
Returns:
true if successful

getRecordData

public boolean getRecordData(DBCommandExpr cmd,
                             java.sql.Connection conn)

Opens the reader by executing the given SQL command and moves to the first row.
If true is returned data of the row can be accessed through the functions on the RecordData interface.
This function is intended for single row queries and provided for convenience.
However it behaves exacly as calling reader.open() and reader.moveNext()

ATTENTION: After using the reader it must be closed using the close() method!
Use

try { ... } finally { reader.close(); } 
to make sure the reader is closed.

Parameters:
cmd - the SQL-Command with cmd.getSelect()
conn - a valid JDBC connection.
Returns:
true if successful

close

public void close()
Closes the DBRecordSet object, the Statement object and detach the columns.
A reader must always be closed immediately after using it.

Specified by:
close in class DBRecordData

skipRows

public boolean skipRows(int count)
Moves the cursor down the given number of rows.

Returns:
true if the reader is on a valid record or false otherwise

moveNext

public boolean moveNext()
Moves the cursor down one row from its current position.

Returns:
true if the reader is on a valid record or false otherwise

iterator

public java.util.Iterator<DBRecordData> iterator(int maxCount)
Returns an row iterator for this reader.
There can only be one iterator at a time.

Parameters:
maxCount - the maximum number of item that shold be returned by this iterator
Returns:
the row interator

iterator

public final java.util.Iterator<DBRecordData> iterator()
 Returns an row iterator for this reader.
 There can only be one iterator at a time.
 

Returns:
the row interator

initRecord

public boolean initRecord(DBRowSet rowset,
                          DBRecord rec)
 initializes a DBRecord object with the values of the current row.
 At least all primary key columns of the target rowset must be provided by this reader.
 This function is equivalent to calling rowset.initRecord(rec, reader) 
 set also DBRowSet.initRecord(DBRecord, DBRecordData));
 

Parameters:
rowset - the rowset to which to attach
rec - the record which to initialize
Returns:
true if the record has been initialized sucessfully or false otherwise

getBeanList

public <T> java.util.ArrayList<T> getBeanList(java.lang.Class<T> c,
                                              int maxCount)
Returns the result of a query as a list of objects resticted to a maximum number of objects (unless maxCount is -1).


getBeanList

public <T> java.util.ArrayList<T> getBeanList(java.lang.Class<T> c)
Returns the result of a query as a list of objects.


addColumnDesc

public boolean addColumnDesc(org.w3c.dom.Element parent)
Moves the cursor down one row from its current position.

Specified by:
addColumnDesc in class DBRecordData
Returns:
true if successful

addRowValues

public boolean addRowValues(org.w3c.dom.Element parent)
Adds all children to a parent.

Specified by:
addRowValues in class DBRecordData
Parameters:
parent - the parent element below which to search the child
Returns:
true if successful

addRows

public int addRows(org.w3c.dom.Element parent)
Adds all children to a parent.

Parameters:
parent - the parent element below which to search the child
Returns:
true if successful

getXmlDocument

public org.w3c.dom.Document getXmlDocument()
Returns a XML document with the field descriptiona an values of this record.

Specified by:
getXmlDocument in class DBRecordData
Returns:
the new XML Document object

getFieldCount

public int getFieldCount()
returns the number of the elements of the colList array

Specified by:
getFieldCount in interface RecordData
Specified by:
getFieldCount in class DBRecordData
Returns:
field count

checkOpenResultSets

public static void checkOpenResultSets()
 Call this if you want to check whether there are any unclosed resultsets
 It logs stack traces to help find piece of code 
 where a DBReader was opened but not closed.