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 2890 2007-06-10 15:54:22Z taqua $
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    }