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: DataRow.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     * This is the base interface for all data access collectors. A data-row adds a
035     * certain order to the elements in the dataset. It also allows statefull
036     * comparisions and data attributes using DataFlags.
037     * <p/>
038     * The data-row is an internal concept of JFreeReport. The report engine will be
039     * responsible for creating and maintaining these implementations. Authors of
040     * functions and expressions usually dont have to care where a datarow comes
041     * from or at which particular instance they are looking right now.
042     * <p/>
043     * Note: Do not attempt to cache the datarow outside the core engine. This can
044     * have funny sideeffects and might trigger the end of the world.
045     *
046     * @author Thomas Morgner
047     */
048    public interface DataRow extends DataSet
049    {
050      /**
051       * Returns the value of the expression or column in the tablemodel using the
052       * given column number as index. For functions and expressions, the
053       * <code>getValue()</code> method is called and for columns from the
054       * tablemodel the tablemodel method <code>getValueAt(row, column)</code> gets
055       * called.
056       *
057       * @param col the item index.
058       * @return the value.
059       * @throws IllegalStateException if the datarow detected a deadlock.
060       * @throws DataSourceException   if an error occured.
061       */
062      public Object get(int col) throws DataSourceException;
063    
064      /**
065       * Returns the value of the function, expression or column using its specific
066       * name. The given name is translated into a valid column number and the the
067       * column is queried. For functions and expressions, the
068       * <code>getValue()</code> method is called and for columns from the
069       * tablemodel the tablemodel method <code>getValueAt(row, column)</code> gets
070       * called.
071       *
072       * @param col the item index.
073       * @return the value.
074       * @throws IllegalStateException if the datarow detected a deadlock.
075       * @throws DataSourceException   if an error occured.
076       */
077      public Object get(String col) throws DataSourceException;
078    
079      /**
080       * Returns the name of the column, expression or function. For columns from
081       * the tablemodel, the tablemodels <code>getColumnName</code> method is
082       * called. For functions, expressions and report properties the assigned name
083       * is returned.
084       *
085       * @param col the item index.
086       * @return the name.
087       * @throws DataSourceException if an error occured.
088       */
089      public String getColumnName(int col) throws DataSourceException;
090    
091      /**
092       * Returns the number of columns, expressions and functions and marked
093       * ReportProperties in the report.
094       *
095       * @return the item count.
096       * @throws DataSourceException if an error occured.
097       */
098      public int getColumnCount() throws DataSourceException;
099    
100      /**
101       * Queries lowlevel meta-data for the current value of the specified column.
102       *
103       * @param col the colum for which to query the meta-data flags
104       * @return the dataflag collection for the value in the named column
105       * @throws DataSourceException if an error occured.
106       */
107      public DataFlags getFlags(String col) throws DataSourceException;
108    
109      /**
110       * Queries lowlevel meta-data for the current value of the specified column.
111       *
112       * @param col the colum for which to query the meta-data flags
113       * @return the dataflag collection for the value in the specified column
114       * @throws DataSourceException if an error occured.
115       */
116      public DataFlags getFlags(int col) throws DataSourceException;
117    }