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,v 1.7 2007/06/10 15:54:21 taqua Exp $
027 * ------------
028 * (C) Copyright 2000-2005, by Object Refinery Limited.
029 * (C) Copyright 2005-2007, by Pentaho Corporation.
030 */
031 package org.jfree.report;
032
033 /**
034 * A report data source is a ordered set of rows. For a report, we assume that
035 * the report dataset does not change while the report is processed. Concurrent
036 * updates will invalidate the whole precomputed layout.
037 *
038 * A report dataset will be accessed in a linear fashion. On certain points, the
039 * cursor will be reset to the a previously read position, and processing the
040 * data will restart from there. It is guaranteed, that the cursor will never
041 * be set to a row that is beyond the last row that has been read with 'next()'.
042 *
043 * If the cursor is out of range, any call to get must return 'null'.
044 *
045 * @author Thomas Morgner
046 */
047 public interface ReportData extends DataSet
048 {
049 public static final int BEFORE_FIRST_ROW = 0;
050
051 public int getCursorPosition() throws DataSourceException;
052
053 /**
054 * Moves the cursor back to an already visited position. Calling this method
055 * for an row number that has not yet been read using 'next' is undefined,
056 * whether that call succeeds is implementation dependent.
057 *
058 * Calls to position zero (aka BEFORE_FIRST_ROW) will always succeeed (unless there is a physical
059 * error, which invalidated the whole report-data object).
060 *
061 * @param cursor
062 * @return true, if moving the cursor succeeded, false otherwise.
063 * @throws DataSourceException
064 */
065 public boolean setCursorPosition(int cursor) throws DataSourceException;
066
067 /**
068 * This operation checks, whether a call to next will be likely to succeed.
069 * If there is a next data row, this should return true.
070 *
071 * @return
072 * @throws DataSourceException
073 */
074 public boolean isAdvanceable () throws DataSourceException;
075
076 /**
077 * This method produces the same result as 'setCursorPosition(getCursorPosition() + 1);'
078 *
079 * @return
080 * @throws DataSourceException
081 */
082 public boolean next() throws DataSourceException;
083
084 /**
085 * Closes the datasource. This should be called at the end of each report
086 * processing run. Whether this closes the underlying data-source backend
087 * depends on the ReportDataFactory. Calling 'close()' on the ReportDataFactory
088 * *must* close all report data objects.
089 *
090 * @throws DataSourceException
091 */
092 public void close() throws DataSourceException;
093
094 /**
095 * Checks, whether this report-data instance is currently readable. A report-data instance cannot be
096 * readable if it is positioned before the first row. (The look-ahead system of 'isAdvanceable()' will
097 * prevent that the datasource is positioned behind the last row.)
098 *
099 * @return true, if the datarow is valid, false otherwise.
100 * @throws DataSourceException
101 */
102 public boolean isReadable() throws DataSourceException;
103 }