001: /**
002: * ===========================================
003: * JFreeReport : a free Java reporting library
004: * ===========================================
005: *
006: * Project Info: http://reporting.pentaho.org/
007: *
008: * (C) Copyright 2001-2007, by Object Refinery Ltd, 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: * Expression.java
027: * ------------
028: * (C) Copyright 2001-2007, by Object Refinery Ltd, Pentaho Corporation and Contributors.
029: */package org.jfree.report.function;
030:
031: import org.jfree.report.DataRow;
032: import org.jfree.report.ResourceBundleFactory;
033: import org.jfree.util.Configuration;
034:
035: /**
036: * An expression is a lightweight function that does not maintain a state. Expressions are used to calculate values
037: * within a single row of a report. Expressions can use a dataRow to access other fields, expressions or functions
038: * within the current row in the report.
039: *
040: * @author Thomas Morgner
041: */
042: public interface Expression extends Cloneable {
043: /**
044: * Returns the name of the expression.
045: * <p/>
046: * Every expression, function and column in the datamodel within a report is required to have a unique name.
047: *
048: * @return the function name.
049: */
050: public String getName();
051:
052: /**
053: * Sets the name of the expression.
054: * <p/>
055: * The name must not be null and must be unique within the expression group.
056: *
057: * @param name the name.
058: */
059: public void setName(String name);
060:
061: /**
062: * Return the current expression value.
063: * <p/>
064: * The value depends (obviously) on the expression implementation.
065: *
066: * @return the value of the function.
067: */
068: public Object getValue();
069:
070: /**
071: * Returns true if this expression contains autoactive content and should be called by the system, regardless whether
072: * this expression is referenced in the datarow.
073: *
074: * @return true, if the expression is activated automaticly, false otherwise.
075: * @deprecated The Active-Flag is no longer evaluated. We always assume it to be true.
076: */
077: public boolean isActive();
078:
079: /**
080: * Returns the DataRow used in this expression. The dataRow is set when the report processing starts and can be used
081: * to access the values of functions, expressions and the reports datasource.
082: *
083: * @return the assigned DataRow for this report processing.
084: */
085: public DataRow getDataRow();
086:
087: /**
088: * Clones the expression, expression should be reinitialized after the cloning.
089: * <p/>
090: * Expression maintain no state, cloning is done at the beginning of the report processing to disconnect the used
091: * expression from any other object space.
092: *
093: * @return A clone of this expression.
094: * @throws CloneNotSupportedException this should never happen.
095: */
096: public Object clone() throws CloneNotSupportedException;
097:
098: /**
099: * The dependency level defines the level of execution for this function. Higher dependency functions are executed
100: * before lower dependency functions. For ordinary functions and expressions, the range for dependencies is defined to
101: * start from 0 (lowest dependency possible) to 2^31 (upper limit of int).
102: * <p/>
103: * Levels below 0 are reserved for system-functionality (printing and layouting).
104: * <p/>
105: * The level must not change during the report processing, or the result is invalid.
106: *
107: * @return the level.
108: */
109: public int getDependencyLevel();
110:
111: /**
112: * Sets the dependency level for the expression.
113: *
114: * @param level the level.
115: */
116: public void setDependencyLevel(int level);
117:
118: /**
119: * Return a new instance of this expression. The copy is initialized and uses the same parameters as the original, but
120: * does not share any objects.
121: *
122: * @return a copy of this function.
123: */
124: public Expression getInstance();
125:
126: /**
127: * Returns the resource-bundle factory of the report. This factory encapsulates the Locale and allows to create a
128: * resource-bundle in a implementation-independent way.
129: *
130: * @return the resource-bundle factory.
131: */
132: public ResourceBundleFactory getResourceBundleFactory();
133:
134: /**
135: * Returns the report's current configuration.
136: *
137: * @return the configuration of the report.
138: */
139: public Configuration getReportConfiguration();
140:
141: /**
142: * Defines the DataRow used in this expression. The dataRow is set when the report processing starts and can be used
143: * to access the values of functions, expressions and the reports datasource.
144: *
145: * @param runtime the runtime information for the expression
146: */
147: public void setRuntime(ExpressionRuntime runtime);
148:
149: /**
150: * Retrieves the runtime instance.
151: *
152: * @return the runtime, can be null, if the expression is abused outside of the report processing.
153: */
154: public ExpressionRuntime getRuntime();
155:
156: /**
157: * Checks, whether this expression is a deep-traversing expression. Deep-traversing expressions receive events from
158: * all sub-reports.
159: *
160: * @return the deep-traversing flag.
161: */
162: public boolean isDeepTraversing();
163:
164: /**
165: * Checks, whether this expression's last value is preserved after the expression goes out of scope.
166: *
167: * @return true, if the expression's last value is preserved, false otherwise.
168: */
169: public boolean isPreserve();
170: }
|