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,v 1.11 2007/04/01 18:49:23 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 * 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 }