JRVariable


1   /*
2    * ============================================================================
3    * GNU Lesser General Public License
4    * ============================================================================
5    *
6    * JasperReports - Free Java report-generating library.
7    * Copyright (C) 2001-2006 JasperSoft Corporation http://www.jaspersoft.com
8    * 
9    * This library is free software; you can redistribute it and/or
10   * modify it under the terms of the GNU Lesser General Public
11   * License as published by the Free Software Foundation; either
12   * version 2.1 of the License, or (at your option) any later version.
13   * 
14   * This library is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17   * Lesser General Public License for more details.
18   * 
19   * You should have received a copy of the GNU Lesser General Public
20   * License along with this library; if not, write to the Free Software
21   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.
22   * 
23   * JasperSoft Corporation
24   * 303 Second Street, Suite 450 North
25   * San Francisco, CA 94107
26   * http://www.jaspersoft.com
27   */
28  package net.sf.jasperreports.engine;
29  
30  
31  /**
32   * An interface for implementing classes that deal with report variables. This interface defines constants for names of
33   * built-in variables and for reset, increment and calculation types.
34   * <p>
35   * When declaring a report group, the engine will automatically create a count variable that will calculate
36   * the number of records that make up the current group (number of records processed between group ruptures).
37   * The name for this variable comes from the name of the group it corresponds to, suffixed with the
38   * "_COUNT" sequence. It can be used like any other report variable, in any report expression (even in the
39   * current group expression like you can see done in the "BreakGroup" of the <i>jasper</i> sample).
40   *
41   * @author Teodor Danciu (teodord@users.sourceforge.net)
42   * @version $Id: JRVariable.java 1311 2006-06-23 12:19:26 +0300 (Fri, 23 Jun 2006) teodord $
43   */
44  public interface JRVariable
45  {
46      /**
47       * Built-in variable that contains the total number of records read from the datasource. After finishing iterating throught the
48       * datasource, it will contain the total number of records that were processed.
49       */
50      public static final String   REPORT_COUNT = "REPORT_COUNT";
51  
52  
53      /**
54       * Built-in variable containing the number of records that were processed when generating the current page.
55       */
56      public static final String   PAGE_COUNT = "PAGE_COUNT";
57  
58  
59      /**
60       * This variable contains the number of records that were processed when generating the current column.
61       */
62      public static final String   COLUMN_COUNT = "COLUMN_COUNT";
63  
64  
65      /**
66       * Built-in variable containing the current page number. At the end of the report filling process, it will contain the total
67       * number of pages for the resulting document.
68       */
69      public static final String   PAGE_NUMBER = "PAGE_NUMBER";
70  
71  
72      /**
73       * Built-in variable containing the current column number.
74       */
75      public static final String   COLUMN_NUMBER = "COLUMN_NUMBER";
76  
77  
78  
79  
80      /**
81       * The variable is initialized only once, at the beginning of the report filling process, with the value returned by
82       * the variable's initial value expression.
83       */
84      public static final byte RESET_TYPE_REPORT = 1;
85  
86  
87      /**
88       * The variable is reinitialized at the beginning of each new page.
89       */
90      public static final byte RESET_TYPE_PAGE = 2;
91  
92  
93      /**
94       * The variable is reinitialized at the beginning of each new column.
95       */
96      public static final byte RESET_TYPE_COLUMN = 3;
97  
98  
99      /**
100      * The variable is reinitialized every time the group specified by the {@link JRVariable#getResetGroup()} method breaks.
101      */
102     public static final byte RESET_TYPE_GROUP = 4;
103 
104 
105     /**
106      * The variable will never be initialized using its initial value expression and will only contain values obtained by
107      * evaluating the variable's expression.
108      */
109     public static final byte RESET_TYPE_NONE = 5;
110 
111 
112 
113 
114 
115     /**
116      * The value is calculated by simply evaluating the variable expression.
117      */
118     public static final byte CALCULATION_NOTHING = 0;
119 
120 
121     /**
122      * The value is calculated by counting the non-null values of the variable expression with every iteration in the data source.
123      * The count variable must be numeric, but the variable expression needs not, since its value is not important.
124      * On the other hand, the initial value expression must be numeric since it will be the count variable initial value.
125      */
126     public static final byte CALCULATION_COUNT = 1;
127 
128 
129     /**
130      * The value is calculated by summing up the values returned by the variable's expression. Both the main expression and initial
131      * expression must have numeric type.
132      *
133      */
134     public static final byte CALCULATION_SUM = 2;
135 
136 
137     /**
138      * The value is obtained by calculating the average for the series of values obtained by evaluating the variable's
139      * expression for each record in the data source. Both the main expression and initial expression must have numeric type.
140      * <p>
141      * In order to calculate the average, the engine creates behind the scenes a helper report variable that calculates
142      * the sum of the values and uses it to calculate the average for those values. This helper sum variable gets its
143      * name from the corresponding average variable suffixed with "_SUM" sequence. This helper variable can be used
144      * in other report expressions just like any normal variable.
145      */
146     public static final byte CALCULATION_AVERAGE = 3;
147 
148 
149     /**
150      * The value of the variable represents the lowest in the series of values obtained by evaluating the variable's
151      * expression for each data source record.
152      */
153     public static final byte CALCULATION_LOWEST = 4;
154 
155 
156     /**
157      * The value of the variable represents the highest in the series of values obtained by evaluating the variable's
158      * expression for each data source record.
159      */
160     public static final byte CALCULATION_HIGHEST = 5;
161 
162 
163     /**
164      * The value is obtained by calculating the standard deviation for the series of values returned by evaluating the
165      * variable's expression.
166      * <p>
167      * Just like for the variables that calculate the average, the engine creates and uses helper report variables
168      * for first obtaining the sum and the count that correspond to your current series of values. The name for
169      * those helper variables that are created behind the scenes is obtained by suffixing the user variable with
170      * the "_SUM" or "_COUNT" suffix and they can be used in other report expressions like any other report variable.
171      * <p>
172      * For variables that calculate the standard deviation, there is always a helper variable present, that first
173      * calculates the variance for the series of values and it has the "_VARIANCE" suffix added to its name.
174      */
175     public static final byte CALCULATION_STANDARD_DEVIATION = 6;
176 
177 
178     /**
179      * The value is obtained by calculating the variance for the series of values returned by evaluating the
180      * variable's expression.
181      */
182     public static final byte CALCULATION_VARIANCE = 7;
183 
184 
185     /**
186      * The value is not calculated by JasperReports. The user must calculate the value of the variable, almost
187      * certainly using the scriptlets functionality. For this type of calculation, the only thing the engine does is
188      * to conserve the value users have calculated, from one iteration in the data source to the next.
189      */
190     public static final byte CALCULATION_SYSTEM = 8;
191     
192     
193     /**
194      * The variable keeps the first value and does not increment it on subsequent iterations.
195      */
196     public static final byte CALCULATION_FIRST = 9;
197 
198 
199     /**
200      * The value is calculated by counting the distinct non-null values of the variable expression with every iteration in the data source.
201      * The count variable must be numeric, but the variable expression needs not, since its value is not important.
202      * On the other hand, the initial value expression must be numeric since it will be the count variable initial value.
203      */
204     public static final byte CALCULATION_DISTINCT_COUNT = 10;
205 
206 
207     /**
208      * Returns the name of the variable. Since all variables are stored in a map, the variable names are the keys in the map.
209      * @return a string containing the variable name
210      */
211     public String   getName();
212 
213 
214     /**
215      * Returns the class of the variable value. Any class is allowed as long as it is in the classpath at compile and run time.
216      * @return a <tt>Class</tt> instance representing the variable value class
217      */
218     public Class   getValueClass();
219         
220     /**
221      * Returns the string name of the variable value class.
222      */
223     public String   getValueClassName();
224         
225     /**
226      * Returns the class of the incrementer factory used for choosing the right incrementer for the variable value.
227      * @return the <tt>Class</tt> instance of the incrementer factory
228      * @see net.sf.jasperreports.engine.fill.JRIncrementer
229      * @see net.sf.jasperreports.engine.fill.JRIncrementerFactory
230      */
231     public Class   getIncrementerFactoryClass();
232         
233     /**
234      * Returns the string name of the variable value class.
235      */
236     public String   getIncrementerFactoryClassName();
237         
238     /**
239      *  Returns the variable reset type. This value must be one of the reset type constants declared in this class.
240      */
241     public byte getResetType();
242         
243     /**
244      * Returns the variable increment type. This value must be one of the reset type constants declared in this class, since the
245      * increment type uses the same constants as the reset type.
246      */
247     public byte getIncrementType();
248         
249     /**
250      * Returns the variable calculation type. This value must be one of the calculation constants declared in this class.
251      */
252     public byte getCalculation();
253 
254     /**
255      * Returns <code>true</code> if the variable calculation type is system defined.
256      * @see JRVariable#CALCULATION_SYSTEM
257      */
258     public boolean isSystemDefined();
259 
260     /**
261      * Returns the main expression for this variable. The expression must be numeric for certain calculation types.
262      * @return a {@link JRExpression} instance containing the expression.
263      */
264     public JRExpression getExpression();
265         
266     /**
267      * Returns the initial value expression for this variable. The expression must be numeric for certain calculation types.
268      * @return a {@link JRExpression} instance containing the initial expression.
269      */
270     public JRExpression getInitialValueExpression();
271         
272     /**
273      * Returns the group whose break triggers the variable reset. Only used when {@link JRVariable#getResetType()} returns
274      * {@link JRVariable#RESET_TYPE_GROUP}.
275      */
276     public JRGroup getResetGroup();
277         
278     /**
279      * Returns the group whose break triggers the variable increment. Only used when {@link JRVariable#getIncrementType()} returns
280      * {@link JRVariable#RESET_TYPE_GROUP}.
281      */
282     public JRGroup getIncrementGroup();
283         
284 }
285
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags