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    }