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: Expression.java 2725 2007-04-01 18:49:29Z taqua $ 027 * ------------ 028 * (C) Copyright 2000-2005, by Object Refinery Limited. 029 * (C) Copyright 2005-2007, by Pentaho Corporation. 030 */ 031 032 package org.jfree.report.expressions; 033 034 import java.io.Serializable; 035 036 import org.jfree.report.DataSourceException; 037 038 /** 039 * An expression is a lightweight computation that does not maintain a state. 040 * 041 * Expressions are used to calculate values within a single row of a report. 042 * Expressions can use a dataRow to access other fields, expressions or 043 * functions within the current row in the report. 044 * 045 * Statefull computations can be implemented using functions. 046 * 047 * @author Thomas Morgner 048 * @see Function 049 */ 050 public interface Expression extends Cloneable, Serializable 051 { 052 /** 053 * Returns the name of the expression. An expression without a name cannot be 054 * referenced from outside the element. 055 * 056 * @return the function name. 057 */ 058 public String getName(); 059 060 /** 061 * Sets the name of the expression. 062 * 063 * @param name the name. 064 */ 065 public void setName(String name); 066 067 /** 068 * Return the current expression value. <P> The value depends (obviously) on 069 * the expression implementation. 070 * 071 * @return the value of the function. 072 */ 073 public Object computeValue() throws DataSourceException; 074 075 /** 076 * Clones the expression, expression should be reinitialized after the 077 * cloning. <P> Expression maintain no state, cloning is done at the beginning 078 * of the report processing to disconnect the used expression from any other 079 * object space. 080 * 081 * @return A clone of this expression. 082 * @throws CloneNotSupportedException this should never happen. 083 */ 084 public Object clone() 085 throws CloneNotSupportedException; 086 087 088 /** 089 * Return a new instance of this expression. The copy is initialized and uses 090 * the same parameters as the original, but does not share any objects. 091 * 092 * @return a copy of this function. 093 */ 094 public Expression getInstance(); 095 096 /** 097 * Defines the DataRow used in this expression. The dataRow is set when the 098 * report processing starts and can be used to access the values of functions, 099 * expressions and the reports datasource. 100 * 101 * @param runtime the runtime information for the expression 102 */ 103 public void setRuntime(ExpressionRuntime runtime); 104 105 /** 106 * A deep-traversing expression declares that it should receive updates from 107 * all subreports. This mode should be activated if the expression's result 108 * depends on values contained in the subreport. 109 * 110 * @return true, if the expression is deep-traversing, false otherwise. 111 */ 112 public boolean isDeepTraversing (); 113 114 /** 115 * Defines, whether the expression is deep-traversing. 116 * 117 * @param deepTraversing true, if the expression is deep-traversing, false 118 * otherwise. 119 */ 120 public void setDeepTraversing (boolean deepTraversing); 121 122 /** 123 * Returns, whether the expression will be precomputed. For precomputed 124 * expressions a parallel evaluation process is started and the result to 125 * which the expression evaluates before it gets out of scope will be used 126 * whenever an other expression queries this expression's value. 127 * 128 * @return true, if the expression is precomputed, false otherwise. 129 */ 130 public boolean isPrecompute(); 131 132 /** 133 * Defines, whether the expression will be precomputed. For precomputed 134 * expressions a parallel evaluation process is started and the result to 135 * which the expression evaluates before it gets out of scope will be used 136 * whenever an other expression queries this expression's value. 137 * 138 * @param precompute true, if the expression is precomputed, false otherwise. 139 */ 140 public void setPrecompute(boolean precompute); 141 142 /** 143 * Checks, whether the expression's result should be preserved in the 144 * precomputed value registry. This way, the last value for that expression 145 * can be retrieved after the report has been finished. 146 * 147 * The preserve-function will only preserve the last value that has been 148 * evaluated before the expression went out of scope. 149 * 150 * @return true, if the expression's results should be preserved, 151 * false otherwise. 152 */ 153 public boolean isPreserve(); 154 155 /** 156 * Defines, whether the expression's result should be preserved in the 157 * precomputed value registry. This way, the last value for that expression 158 * can be retrieved after the report has been finished. 159 * 160 * @param preserve true, if the expression's results should be preserved, 161 * false otherwise. 162 */ 163 public void setPreserve(boolean preserve); 164 }