Package org.apache.empire.db

Class DBReader

java.lang.Object
org.apache.empire.db.DBObject
org.apache.empire.db.DBRecordData
org.apache.empire.db.DBReader
All Implemented Interfaces:
Closeable, AutoCloseable, RecordData, DBContextAware
public class DBReader extends DBRecordData implements Closeable

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:

  • Field Details

    • log

      protected static final org.slf4j.Logger log

    • context

      protected final DBContext context

  • Constructor Details

    • DBReader

      public DBReader(DBContext context, boolean useFieldIndexMap)
      Constructs an empty DBRecordSet object.
      Parameters:
      context - the database context
      useFieldIndexMap - flag whether to use a fieldIndexMap

    • DBReader

      public DBReader(DBContext context)
      Constructs a default DBReader object with the fieldIndexMap enabled.
      Parameters:
      context - the database context

  • Method Details

    • getContext

      public DBContext getContext()
      Returns the current Context
      Specified by:
      getContext in interface DBContextAware
      Returns:
      the database context

    • getDatabase

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

    • getColumn

      public DBColumnExpr getColumn(int iColumn)
      Get the column Expression at position
      Specified by:
      getColumn in interface RecordData
      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

    • getRecordKey

      public Object[] getRecordKey(Entity entity)
      Returns the record key for a type of entity
      Parameters:
      entity - the entity type or rowset for which to get key
      Returns:
      the record key

    • getRecordId

      public long getRecordId(Entity entity)
      Returns the record id for a type of entity which has a single numeric primary key
      Parameters:
      entity - the entity type or rowset for which to get key
      Returns:
      the record id
      Throws:
      InvalidArgumentException - if the entity has not a single numeric primary key

    • 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)
      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

    • open

      public final void open(DBCommandExpr cmd)
      Opens the reader by executing the given SQL command.

      see open(DBCommandExpr, boolean)

      Parameters:
      cmd - the SQL-Command with cmd.getSelect()

    • getRecordData

      public void getRecordData(DBCommandExpr cmd)

      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()

    • 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 interface AutoCloseable
      Specified by:
      close in interface Closeable

    • 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(DBRecordBase 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(DBRecordBase, RecordData));
      Parameters:
      rec - the record which to initialize

    • getBeanList

      public <L extends List<T>, T> L getBeanList(L list, Class<T> t, Object parent, int maxCount)
      Returns the result of a query as a list of objects restricted to a maximum number of objects (unless maxCount is -1).
      Type Parameters:
      L - the list type
      T - the list item type
      Parameters:
      list - the collection to add the objects to
      t - the class type of the objects in the list
      parent - the bean parent
      maxCount - the maximum number of objects
      Returns:
      the list of T

    • getBeanList

      public final <T> List<T> getBeanList(Class<T> t, int maxItems)
      Returns the result of a query as a list of objects.
      Type Parameters:
      T - the list item type
      Parameters:
      t - the class type of the objects in the list
      maxItems - the maximum number of objects
      Returns:
      the list of T

    • getBeanList

      public final <T> List<T> getBeanList(Class<T> t)
      Returns the result of a query as a list of objects.
      Type Parameters:
      T - the list item type
      Parameters:
      t - the class type of the objects in the list
      Returns:
      the list of T

    • addXmlMeta

      public int addXmlMeta(Element parent)
      Moves the cursor down one row from its current position.
      Specified by:
      addXmlMeta in class DBRecordData
      Returns:
      the number of column descriptions added to the Element

    • addXmlData

      public int addXmlData(Element parent)
      Adds all children to a parent.
      Specified by:
      addXmlData 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

    • init

      protected void init(DBDatabase db, DBColumnExpr[] columns, ResultSet rset)
      Initialize the reader from an open JDBC-ResultSet
      Parameters:
      db - the database
      columns - the query column expressions
      rset - the JDBC-ResultSet

    • getColumnExprList

      protected final DBColumnExpr[] getColumnExprList()
      Access the column expression list
      Returns:
      the column expression list

    • getResultSet

      protected final ResultSet getResultSet()
      Access the JDBC-ResultSet
      Returns:
      the JDBC-ResultSet

    • findFieldIndex

      protected int findFieldIndex(ColumnExpr column)
      finds the field Index of a given column expression Internally used as helper for getFieldIndex()
      Parameters:
      column - the column to find
      Returns:
      the index value

    • findBeanConstructor

      protected Constructor<?> findBeanConstructor(Class<?> beanClass)
      Returns a constructor for a bean class for the set of parameters or null if no suitable constructor is found
      Parameters:
      beanClass - the bean class
      Returns:
      a constructor for the readers columns or null if not suitable constructor is available

    • trackThisResultSet

      protected void trackThisResultSet()
      Support for finding code errors where a DBRecordSet is opened but not closed.

    • endTrackingThisResultSet

      protected void endTrackingThisResultSet()
      Support for finding code errors where a DBRecordSet is opened but not closed.

    • enableOpenResultSetTracking

      public static boolean enableOpenResultSetTracking(boolean enable)
      Enables or disabled tracking of open ResultSets
      Parameters:
      enable - true to enable or false otherwise
      Returns:
      the previous state of the trackOpenResultSets

    • 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.