Source for org.jfree.report.ReportData

   1: /**
   2:  * ========================================
   3:  * JFreeReport : a free Java report library
   4:  * ========================================
   5:  *
   6:  * Project Info:  http://reporting.pentaho.org/
   7:  *
   8:  * (C) Copyright 2000-2007, by Object Refinery Limited, Pentaho Corporation and Contributors.
   9:  *
  10:  * This library is free software; you can redistribute it and/or modify it under the terms
  11:  * of the GNU Lesser General Public License as published by the Free Software Foundation;
  12:  * either version 2.1 of the License, or (at your option) any later version.
  13:  *
  14:  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
  15:  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  16:  * See the GNU Lesser General Public License for more details.
  17:  *
  18:  * You should have received a copy of the GNU Lesser General Public License along with this
  19:  * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  20:  * Boston, MA 02111-1307, USA.
  21:  *
  22:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
  23:  * in the United States and other countries.]
  24:  *
  25:  * ------------
  26:  * $Id: ReportData.java 2890 2007-06-10 15:54:22Z taqua $
  27:  * ------------
  28:  * (C) Copyright 2000-2005, by Object Refinery Limited.
  29:  * (C) Copyright 2005-2007, by Pentaho Corporation.
  30:  */
  31: package org.jfree.report;
  32: 
  33: /**
  34:  * A report data source is a ordered set of rows. For a report, we assume that
  35:  * the report dataset does not change while the report is processed. Concurrent
  36:  * updates will invalidate the whole precomputed layout.
  37:  *
  38:  * A report dataset will be accessed in a linear fashion. On certain points, the
  39:  * cursor will be reset to the a previously read position, and processing the
  40:  * data will restart from there. It is guaranteed, that the cursor will never
  41:  * be set to a row that is beyond the last row that has been read with 'next()'.
  42:  *
  43:  * If the cursor is out of range, any call to get must return 'null'. 
  44:  *
  45:  * @author Thomas Morgner
  46:  */
  47: public interface ReportData extends DataSet
  48: {
  49:   public static final int BEFORE_FIRST_ROW = 0;
  50: 
  51:   public int getCursorPosition() throws DataSourceException;
  52: 
  53:   /**
  54:    * Moves the cursor back to an already visited position. Calling this method
  55:    * for an row number that has not yet been read using 'next' is undefined,
  56:    * whether that call succeeds is implementation dependent.
  57:    *
  58:    * Calls to position zero (aka BEFORE_FIRST_ROW) will always succeeed (unless there is a physical
  59:    * error, which invalidated the whole report-data object).
  60:    *
  61:    * @param cursor
  62:    * @return true, if moving the cursor succeeded, false otherwise.
  63:    * @throws DataSourceException
  64:    */
  65:   public boolean setCursorPosition(int cursor) throws DataSourceException;
  66: 
  67:   /**
  68:    * This operation checks, whether a call to next will be likely to succeed.
  69:    * If there is a next data row, this should return true.
  70:    *
  71:    * @return
  72:    * @throws DataSourceException
  73:    */
  74:   public boolean isAdvanceable () throws DataSourceException;
  75: 
  76:   /**
  77:    * This method produces the same result as 'setCursorPosition(getCursorPosition() + 1);'
  78:    *
  79:    * @return
  80:    * @throws DataSourceException
  81:    */
  82:   public boolean next() throws DataSourceException;
  83: 
  84:   /**
  85:    * Closes the datasource. This should be called at the end of each report
  86:    * processing run. Whether this closes the underlying data-source backend
  87:    * depends on the ReportDataFactory. Calling 'close()' on the ReportDataFactory
  88:    * *must* close all report data objects.
  89:    *
  90:    * @throws DataSourceException
  91:    */
  92:   public void close() throws DataSourceException;
  93: 
  94:   /**
  95:    * Checks, whether this report-data instance is currently readable. A report-data instance cannot be
  96:    * readable if it is positioned before the first row. (The look-ahead system of 'isAdvanceable()' will
  97:    * prevent that the datasource is positioned behind the last row.)
  98:    *
  99:    * @return true, if the datarow is valid, false otherwise.
 100:    * @throws DataSourceException
 101:    */
 102:   public boolean isReadable() throws DataSourceException;
 103: }