001: /**
002: * ========================================
003: * JFreeReport : a free Java report library
004: * ========================================
005: *
006: * Project Info: http://reporting.pentaho.org/
007: *
008: * (C) Copyright 2000-2007, by Object Refinery Limited, Pentaho Corporation and Contributors.
009: *
010: * This library is free software; you can redistribute it and/or modify it under the terms
011: * of the GNU Lesser General Public License as published by the Free Software Foundation;
012: * either version 2.1 of the License, or (at your option) any later version.
013: *
014: * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
015: * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: * See the GNU Lesser General Public License for more details.
017: *
018: * You should have received a copy of the GNU Lesser General Public License along with this
019: * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
020: * Boston, MA 02111-1307, USA.
021: *
022: * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
023: * in the United States and other countries.]
024: *
025: * ------------
026: * $Id: ReportData.java 3048 2007-07-28 18:02:42Z tmorgner $
027: * ------------
028: * (C) Copyright 2000-2005, by Object Refinery Limited.
029: * (C) Copyright 2005-2007, by Pentaho Corporation.
030: */package org.jfree.report;
031:
032: /**
033: * A report data source is a ordered set of rows. For a report, we assume that
034: * the report dataset does not change while the report is processed. Concurrent
035: * updates will invalidate the whole precomputed layout.
036: *
037: * A report dataset will be accessed in a linear fashion. On certain points, the
038: * cursor will be reset to the a previously read position, and processing the
039: * data will restart from there. It is guaranteed, that the cursor will never
040: * be set to a row that is beyond the last row that has been read with 'next()'.
041: *
042: * If the cursor is out of range, any call to get must return 'null'.
043: *
044: * @author Thomas Morgner
045: */
046: public interface ReportData extends DataSet {
047: public static final int BEFORE_FIRST_ROW = 0;
048:
049: public int getCursorPosition() throws DataSourceException;
050:
051: /**
052: * Moves the cursor back to an already visited position. Calling this method
053: * for an row number that has not yet been read using 'next' is undefined,
054: * whether that call succeeds is implementation dependent.
055: *
056: * Calls to position zero (aka BEFORE_FIRST_ROW) will always succeeed (unless there is a physical
057: * error, which invalidated the whole report-data object).
058: *
059: * @param cursor
060: * @return true, if moving the cursor succeeded, false otherwise.
061: * @throws DataSourceException
062: */
063: public boolean setCursorPosition(int cursor)
064: throws DataSourceException;
065:
066: /**
067: * This operation checks, whether a call to next will be likely to succeed.
068: * If there is a next data row, this should return true.
069: *
070: * @return
071: * @throws DataSourceException
072: */
073: public boolean isAdvanceable() throws DataSourceException;
074:
075: /**
076: * This method produces the same result as 'setCursorPosition(getCursorPosition() + 1);'
077: *
078: * @return
079: * @throws DataSourceException
080: */
081: public boolean next() throws DataSourceException;
082:
083: /**
084: * Closes the datasource. This should be called at the end of each report
085: * processing run. Whether this closes the underlying data-source backend
086: * depends on the ReportDataFactory. Calling 'close()' on the ReportDataFactory
087: * *must* close all report data objects.
088: *
089: * @throws DataSourceException
090: */
091: public void close() throws DataSourceException;
092:
093: /**
094: * Checks, whether this report-data instance is currently readable. A report-data instance cannot be
095: * readable if it is positioned before the first row. (The look-ahead system of 'isAdvanceable()' will
096: * prevent that the datasource is positioned behind the last row.)
097: *
098: * @return true, if the datarow is valid, false otherwise.
099: * @throws DataSourceException
100: */
101: public boolean isReadable() throws DataSourceException;
102: }
|