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 */ 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 }