001: /*
002: * ============================================================================
003: * GNU Lesser General Public License
004: * ============================================================================
005: *
006: * JasperReports - Free Java report-generating library.
007: * Copyright (C) 2001-2006 JasperSoft Corporation http://www.jaspersoft.com
008: *
009: * This library is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU Lesser General Public
011: * License as published by the Free Software Foundation; either
012: * 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,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017: * Lesser General Public License for more details.
018: *
019: * You should have received a copy of the GNU Lesser General Public
020: * License along with this library; if not, write to the Free Software
021: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
022: *
023: * JasperSoft Corporation
024: * 303 Second Street, Suite 450 North
025: * San Francisco, CA 94107
026: * http://www.jaspersoft.com
027: */
028: package net.sf.jasperreports.engine;
029:
030: /**
031: * Interface representing a data set that can be used in a report.
032: * <p>
033: * A data set consists of parameters, fields, variables, groups and an optional query.
034: * When a data set gets instantiated, parameter values and a data source is passed to it.
035: * <p>
036: * A report has one main data set and multiple sub data sets that can be instantiated by charts and crosstabs.
037: *
038: * @author Lucian Chirita (lucianc@users.sourceforge.net)
039: * @version $Id: JRDataset.java 1669 2007-03-26 14:50:07Z lucianc $
040: *
041: * @see net.sf.jasperreports.engine.JRDatasetRun
042: * @see net.sf.jasperreports.engine.JRReport#getMainDataset()
043: * @see net.sf.jasperreports.engine.JRReport#getDatasets()
044: */
045: public interface JRDataset extends JRPropertiesHolder {
046: /**
047: * Return NULL when a resource is missing.
048: */
049: public static final byte WHEN_RESOURCE_MISSING_TYPE_NULL = 1;
050: /**
051: * Return empty string when a resource is missing.
052: */
053: public static final byte WHEN_RESOURCE_MISSING_TYPE_EMPTY = 2;
054: /**
055: * Return the key when a resource is missing.
056: */
057: public static final byte WHEN_RESOURCE_MISSING_TYPE_KEY = 3;
058: /**
059: * Throw an exception when a resource is missing.
060: */
061: public static final byte WHEN_RESOURCE_MISSING_TYPE_ERROR = 4;
062:
063: /**
064: * Returns the dataset name.
065: *
066: * @return the name of the dataset
067: */
068: public String getName();
069:
070: /**
071: * The name of the scriptlet class to be used when iterating this dataset.
072: *
073: * @return the scriplet class name
074: */
075: public String getScriptletClass();
076:
077: /**
078: * Returns the dataset's parameters.
079: *
080: * @return the dataset's parameters
081: */
082: public JRParameter[] getParameters();
083:
084: /**
085: * Returns the query of the dataset.
086: * <p>
087: * The query is used by passing a connection is passed to the dataset when instantiating.
088: *
089: * @return the query of the dataset
090: */
091: public JRQuery getQuery();
092:
093: /**
094: * Returns the dataset's fields.
095: *
096: * @return the dataset's fields
097: */
098: public JRField[] getFields();
099:
100: /**
101: * Returns the dataset's sort fields.
102: *
103: * @return the dataset's sort fields
104: */
105: public JRSortField[] getSortFields();
106:
107: /**
108: * Returns the dataset's variables.
109: *
110: * @return the dataset's variables
111: */
112: public JRVariable[] getVariables();
113:
114: /**
115: * Returns the dataset's groups.
116: *
117: * @return the dataset's groups
118: */
119: public JRGroup[] getGroups();
120:
121: /**
122: * Decides whether this dataset is the main report dataset or a sub dataset.
123: *
124: * @return <code>true</code> iff this dataset is the main report dataset
125: */
126: public boolean isMainDataset();
127:
128: /**
129: * Returns the resource bundle base name.
130: * <p>
131: * The resource bundle is used when evaluating expressions.
132: *
133: * @return the resource bundle base name
134: */
135: public String getResourceBundle();
136:
137: /**
138: * Returns the resource missing handling type.
139: *
140: * @return the resource missing handling type
141: */
142: public byte getWhenResourceMissingType();
143:
144: /**
145: * Sets the resource missing handling type.
146: * @param whenResourceMissingType the resource missing handling type
147: */
148: public void setWhenResourceMissingType(byte whenResourceMissingType);
149:
150: /**
151: * Returns the dataset filter expression.
152: * <p>
153: * This expression is used to filter the rows of the
154: * {@link JRDataSource data source} that this dataset will iterate on.
155: * </p>
156: * <p>
157: * This expression (if not null) is evaluated immediately after a new row is
158: * {@link JRDataSource#next() produced} by the data source.
159: * The evaluation is performed using field and variable values corresponding to the new row.
160: * When the result of the evaluation is <code>Boolean.TRUE</code> the row gets processed by the report
161: * filling engine.
162: * When the result is null or <code>Boolean.FALSE</code>, the current row will be skipped and the datasource will be asked for the next row.
163: * </p>
164: *
165: * @return the dataset filter expression
166: */
167: public JRExpression getFilterExpression();
168: }
|