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