Source for org.jfree.report.expressions.Expression

   1: /**
   2:  * ========================================
   3:  * JFreeReport : a free Java report library
   4:  * ========================================
   5:  *
   6:  * Project Info:  http://reporting.pentaho.org/
   7:  *
   8:  * (C) Copyright 2000-2007, by Object Refinery Limited, Pentaho Corporation and Contributors.
   9:  *
  10:  * This library is free software; you can redistribute it and/or modify it under the terms
  11:  * of the GNU Lesser General Public License as published by the Free Software Foundation;
  12:  * either 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, but WITHOUT ANY WARRANTY;
  15:  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  16:  * See the GNU Lesser General Public License for more details.
  17:  *
  18:  * You should have received a copy of the GNU Lesser General Public License along with this
  19:  * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  20:  * Boston, MA 02111-1307, USA.
  21:  *
  22:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
  23:  * in the United States and other countries.]
  24:  *
  25:  * ------------
  26:  * $Id: Expression.java 2725 2007-04-01 18:49:29Z taqua $
  27:  * ------------
  28:  * (C) Copyright 2000-2005, by Object Refinery Limited.
  29:  * (C) Copyright 2005-2007, by Pentaho Corporation.
  30:  */
  31: 
  32: package org.jfree.report.expressions;
  33: 
  34: import java.io.Serializable;
  35: 
  36: import org.jfree.report.DataSourceException;
  37: 
  38: /**
  39:  * An expression is a lightweight computation that does not maintain a state.
  40:  *
  41:  * Expressions are used to calculate values within a single row of a report.
  42:  * Expressions can use a dataRow to access other fields, expressions or
  43:  * functions within the current row in the report.
  44:  *
  45:  * Statefull computations can be implemented using functions.
  46:  *
  47:  * @author Thomas Morgner
  48:  * @see Function
  49:  */
  50: public interface Expression extends Cloneable, Serializable
  51: {
  52:   /**
  53:    * Returns the name of the expression. An expression without a name cannot be
  54:    * referenced from outside the element.
  55:    *
  56:    * @return the function name.
  57:    */
  58:   public String getName();
  59: 
  60:   /**
  61:    * Sets the name of the expression.
  62:    *
  63:    * @param name the name.
  64:    */
  65:   public void setName(String name);
  66: 
  67:   /**
  68:    * Return the current expression value. <P> The value depends (obviously) on
  69:    * the expression implementation.
  70:    *
  71:    * @return the value of the function.
  72:    */
  73:   public Object computeValue() throws DataSourceException;
  74: 
  75:   /**
  76:    * Clones the expression, expression should be reinitialized after the
  77:    * cloning. <P> Expression maintain no state, cloning is done at the beginning
  78:    * of the report processing to disconnect the used expression from any other
  79:    * object space.
  80:    *
  81:    * @return A clone of this expression.
  82:    * @throws CloneNotSupportedException this should never happen.
  83:    */
  84:   public Object clone()
  85:           throws CloneNotSupportedException;
  86: 
  87: 
  88:   /**
  89:    * Return a new instance of this expression. The copy is initialized and uses
  90:    * the same parameters as the original, but does not share any objects.
  91:    *
  92:    * @return a copy of this function.
  93:    */
  94:   public Expression getInstance();
  95: 
  96:   /**
  97:    * Defines the DataRow used in this expression. The dataRow is set when the
  98:    * report processing starts and can be used to access the values of functions,
  99:    * 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: }