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: * An interface for implementing classes that deal with report variables. This interface defines constants for names of
032: * built-in variables and for reset, increment and calculation types.
033: * <p>
034: * When declaring a report group, the engine will automatically create a count variable that will calculate
035: * the number of records that make up the current group (number of records processed between group ruptures).
036: * The name for this variable comes from the name of the group it corresponds to, suffixed with the
037: * "_COUNT" sequence. It can be used like any other report variable, in any report expression (even in the
038: * current group expression like you can see done in the "BreakGroup" of the <i>jasper</i> sample).
039: *
040: * @author Teodor Danciu (teodord@users.sourceforge.net)
041: * @version $Id: JRVariable.java 1311 2006-06-23 09:19:26Z teodord $
042: */
043: public interface JRVariable {
044: /**
045: * Built-in variable that contains the total number of records read from the datasource. After finishing iterating throught the
046: * datasource, it will contain the total number of records that were processed.
047: */
048: public static final String REPORT_COUNT = "REPORT_COUNT";
049:
050: /**
051: * Built-in variable containing the number of records that were processed when generating the current page.
052: */
053: public static final String PAGE_COUNT = "PAGE_COUNT";
054:
055: /**
056: * This variable contains the number of records that were processed when generating the current column.
057: */
058: public static final String COLUMN_COUNT = "COLUMN_COUNT";
059:
060: /**
061: * Built-in variable containing the current page number. At the end of the report filling process, it will contain the total
062: * number of pages for the resulting document.
063: */
064: public static final String PAGE_NUMBER = "PAGE_NUMBER";
065:
066: /**
067: * Built-in variable containing the current column number.
068: */
069: public static final String COLUMN_NUMBER = "COLUMN_NUMBER";
070:
071: /**
072: * The variable is initialized only once, at the beginning of the report filling process, with the value returned by
073: * the variable's initial value expression.
074: */
075: public static final byte RESET_TYPE_REPORT = 1;
076:
077: /**
078: * The variable is reinitialized at the beginning of each new page.
079: */
080: public static final byte RESET_TYPE_PAGE = 2;
081:
082: /**
083: * The variable is reinitialized at the beginning of each new column.
084: */
085: public static final byte RESET_TYPE_COLUMN = 3;
086:
087: /**
088: * The variable is reinitialized every time the group specified by the {@link JRVariable#getResetGroup()} method breaks.
089: */
090: public static final byte RESET_TYPE_GROUP = 4;
091:
092: /**
093: * The variable will never be initialized using its initial value expression and will only contain values obtained by
094: * evaluating the variable's expression.
095: */
096: public static final byte RESET_TYPE_NONE = 5;
097:
098: /**
099: * The value is calculated by simply evaluating the variable expression.
100: */
101: public static final byte CALCULATION_NOTHING = 0;
102:
103: /**
104: * The value is calculated by counting the non-null values of the variable expression with every iteration in the data source.
105: * The count variable must be numeric, but the variable expression needs not, since its value is not important.
106: * On the other hand, the initial value expression must be numeric since it will be the count variable initial value.
107: */
108: public static final byte CALCULATION_COUNT = 1;
109:
110: /**
111: * The value is calculated by summing up the values returned by the variable's expression. Both the main expression and initial
112: * expression must have numeric type.
113: *
114: */
115: public static final byte CALCULATION_SUM = 2;
116:
117: /**
118: * The value is obtained by calculating the average for the series of values obtained by evaluating the variable's
119: * expression for each record in the data source. Both the main expression and initial expression must have numeric type.
120: * <p>
121: * In order to calculate the average, the engine creates behind the scenes a helper report variable that calculates
122: * the sum of the values and uses it to calculate the average for those values. This helper sum variable gets its
123: * name from the corresponding average variable suffixed with "_SUM" sequence. This helper variable can be used
124: * in other report expressions just like any normal variable.
125: */
126: public static final byte CALCULATION_AVERAGE = 3;
127:
128: /**
129: * The value of the variable represents the lowest in the series of values obtained by evaluating the variable's
130: * expression for each data source record.
131: */
132: public static final byte CALCULATION_LOWEST = 4;
133:
134: /**
135: * The value of the variable represents the highest in the series of values obtained by evaluating the variable's
136: * expression for each data source record.
137: */
138: public static final byte CALCULATION_HIGHEST = 5;
139:
140: /**
141: * The value is obtained by calculating the standard deviation for the series of values returned by evaluating the
142: * variable's expression.
143: * <p>
144: * Just like for the variables that calculate the average, the engine creates and uses helper report variables
145: * for first obtaining the sum and the count that correspond to your current series of values. The name for
146: * those helper variables that are created behind the scenes is obtained by suffixing the user variable with
147: * the "_SUM" or "_COUNT" suffix and they can be used in other report expressions like any other report variable.
148: * <p>
149: * For variables that calculate the standard deviation, there is always a helper variable present, that first
150: * calculates the variance for the series of values and it has the "_VARIANCE" suffix added to its name.
151: */
152: public static final byte CALCULATION_STANDARD_DEVIATION = 6;
153:
154: /**
155: * The value is obtained by calculating the variance for the series of values returned by evaluating the
156: * variable's expression.
157: */
158: public static final byte CALCULATION_VARIANCE = 7;
159:
160: /**
161: * The value is not calculated by JasperReports. The user must calculate the value of the variable, almost
162: * certainly using the scriptlets functionality. For this type of calculation, the only thing the engine does is
163: * to conserve the value users have calculated, from one iteration in the data source to the next.
164: */
165: public static final byte CALCULATION_SYSTEM = 8;
166:
167: /**
168: * The variable keeps the first value and does not increment it on subsequent iterations.
169: */
170: public static final byte CALCULATION_FIRST = 9;
171:
172: /**
173: * The value is calculated by counting the distinct non-null values of the variable expression with every iteration in the data source.
174: * The count variable must be numeric, but the variable expression needs not, since its value is not important.
175: * On the other hand, the initial value expression must be numeric since it will be the count variable initial value.
176: */
177: public static final byte CALCULATION_DISTINCT_COUNT = 10;
178:
179: /**
180: * Returns the name of the variable. Since all variables are stored in a map, the variable names are the keys in the map.
181: * @return a string containing the variable name
182: */
183: public String getName();
184:
185: /**
186: * Returns the class of the variable value. Any class is allowed as long as it is in the classpath at compile and run time.
187: * @return a <tt>Class</tt> instance representing the variable value class
188: */
189: public Class getValueClass();
190:
191: /**
192: * Returns the string name of the variable value class.
193: */
194: public String getValueClassName();
195:
196: /**
197: * Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
198: * @return the <tt>Class</tt> instance of the incrementer factory
199: * @see net.sf.jasperreports.engine.fill.JRIncrementer
200: * @see net.sf.jasperreports.engine.fill.JRIncrementerFactory
201: */
202: public Class getIncrementerFactoryClass();
203:
204: /**
205: * Returns the string name of the variable value class.
206: */
207: public String getIncrementerFactoryClassName();
208:
209: /**
210: * Returns the variable reset type. This value must be one of the reset type constants declared in this class.
211: */
212: public byte getResetType();
213:
214: /**
215: * Returns the variable increment type. This value must be one of the reset type constants declared in this class, since the
216: * increment type uses the same constants as the reset type.
217: */
218: public byte getIncrementType();
219:
220: /**
221: * Returns the variable calculation type. This value must be one of the calculation constants declared in this class.
222: */
223: public byte getCalculation();
224:
225: /**
226: * Returns <code>true</code> if the variable calculation type is system defined.
227: * @see JRVariable#CALCULATION_SYSTEM
228: */
229: public boolean isSystemDefined();
230:
231: /**
232: * Returns the main expression for this variable. The expression must be numeric for certain calculation types.
233: * @return a {@link JRExpression} instance containing the expression.
234: */
235: public JRExpression getExpression();
236:
237: /**
238: * Returns the initial value expression for this variable. The expression must be numeric for certain calculation types.
239: * @return a {@link JRExpression} instance containing the initial expression.
240: */
241: public JRExpression getInitialValueExpression();
242:
243: /**
244: * Returns the group whose break triggers the variable reset. Only used when {@link JRVariable#getResetType()} returns
245: * {@link JRVariable#RESET_TYPE_GROUP}.
246: */
247: public JRGroup getResetGroup();
248:
249: /**
250: * Returns the group whose break triggers the variable increment. Only used when {@link JRVariable#getIncrementType()} returns
251: * {@link JRVariable#RESET_TYPE_GROUP}.
252: */
253: public JRGroup getIncrementGroup();
254:
255: }
|