org.apache.empire.db
Class DBReader

java.lang.Object
  extended by org.apache.empire.db.DBObject
      extended by org.apache.empire.db.DBRecordData
          extended by org.apache.empire.db.DBReader
All Implemented Interfaces:
Serializable, 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 explicitly 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:

See Also:
Serialized Form

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.
 
Field Summary
protected static org.slf4j.Logger log
           
protected  ResultSet rset
           
 
Constructor Summary
DBReader()
          Constructs an empty DBRecordSet object.
 
Method Summary
 int addColumnDesc(Element parent)
          Moves the cursor down one row from its current position.
 int addRows(Element parent)
          Adds all children to a parent.
 int addRowValues(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.
A reader must always be closed immediately after using it.
<C extends Collection<T>,T>
C
getBeanList(C c, Class<T> t, int maxCount)
          Returns the result of a query as a list of objects restricted to a maximum number of objects (unless maxCount is -1).
<T> ArrayList<T>
getBeanList(Class<T> t)
          Returns the result of a query as a list of objects.
<T> ArrayList<T>
getBeanList(Class<T> t, int maxItems)
          Returns the result of a query as a list of objects.
 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(String column)
          Returns the index value by a specified column name.
 void getRecordData(DBCommandExpr cmd, 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()
 boolean getScrollable()
           
 Object getValue(int index)
          Returns a data value identified by the column index.
protected  DBXmlDictionary getXmlDictionary()
          returns the DBXmlDictionary that should used to generate XMLDocuments
 Document getXmlDocument()
          Returns a XML document with the field description an values of this record.
 void 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()
          Checks if the rowset is open
 Iterator<DBRecordData> iterator()
           Returns an row iterator for this reader.
 Iterator<DBRecordData> iterator(int maxCount)
          Returns an row iterator for this reader.
There can only be one iterator at a time.
 boolean moveNext()
          Moves the cursor down one row from its current position.
 void open(DBCommandExpr cmd, boolean scrollable, 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.
 void open(DBCommandExpr cmd, 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, getBeanProperty, getBoolean, getBoolean, getDateTime, getDateTime, getDecimal, getDecimal, getDouble, getDouble, getInt, getInt, getLong, getLong, getString, getString, getValue, isNull
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

protected static final org.slf4j.Logger log

rset

protected ResultSet rset
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(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 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()
Checks if the rowset is open

Returns:
true if the rowset is open

open

public void open(DBCommandExpr cmd,
                 boolean scrollable,
                 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.

open

public final void open(DBCommandExpr cmd,
                       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.

getRecordData

public void getRecordData(DBCommandExpr cmd,
                          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.

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.

Parameters:
count - the number of rows to skip
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 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 should be returned by this iterator
Returns:
the row iterator

iterator

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

Returns:
the row iterator

initRecord

public void 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

getBeanList

public <C extends Collection<T>,T> C getBeanList(C c,
                                                 Class<T> t,
                                                 int maxCount)
Returns the result of a query as a list of objects restricted to a maximum number of objects (unless maxCount is -1).

Parameters:
c - the collection to add the objects to
t - the class type of the objects in the list
maxCount - the maximum number of objects
Returns:
the list of

getBeanList

public final <T> ArrayList<T> getBeanList(Class<T> t,
                                          int maxItems)
Returns the result of a query as a list of objects.

Parameters:
t - the class type of the objects in the list
maxItems - the maximum number of objects
Returns:
the list of

getBeanList

public final <T> ArrayList<T> getBeanList(Class<T> t)
Returns the result of a query as a list of objects.

Parameters:
t - the class type of the objects in the list
Returns:
the list of

addColumnDesc

public int addColumnDesc(Element parent)
Moves the cursor down one row from its current position.

Specified by:
addColumnDesc in class DBRecordData
Returns:
the number of column descriptions added to the Element

addRowValues

public int addRowValues(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:
the number of row values added to the element

addRows

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

Parameters:
parent - the parent element below which to search the child
Returns:
the number of rows added to the element

getXmlDictionary

protected DBXmlDictionary getXmlDictionary()
returns the DBXmlDictionary that should used to generate XMLDocuments

Returns:
the DBXmlDictionary

getXmlDocument

public Document getXmlDocument()
Returns a XML document with the field description 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.
 



Copyright © 2008-2012 Apache Software Foundation. All Rights Reserved.