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,v 1.5 2007/04/01 18:49:25 taqua Exp $
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 }