i-net Clear Reports

com.inet.report
Class FormulaField

java.lang.Object
  extended by com.inet.report.Field
      extended by com.inet.report.FormulaField
All Implemented Interfaces:
com.inet.report.formula.IFormulaData, NodeParser, com.inet.report.ReferencedObject, com.inet.report.ReferenceHolder, Validatable, java.io.Serializable

public class FormulaField
extends Field
implements com.inet.report.ReferenceHolder, Validatable, com.inet.report.formula.IFormulaData

This class represents a field, which value is calculated by a formula. The formula have to be in Crystal Reports formula syntax or if you set 'basicFmSyntax' to true in basic syntax. To add a FormulaField to the fields set use method Fields.addFormulaField(String,String,int) in class Fields. Note that the usableness of the formula field have to set explicitly at creation time or with method setFormulaType(int).
This class is part of the RDC.

See Also:
Fields.addFormulaField(String, String, int), Fields.getFormulaField(int), Fields.removeFormulaField(int), Fields.getFormulaFieldsCount(), FieldElement, FieldPart, Serialized Form

Field Summary
static int BEFORE_READING_RECORDS
          Constant value of evaluation time.
static int FORMULA_GROUP_SELECTION
          group selection formula
static int FORMULA_PROPERTY
          property formula
static int FORMULA_RECORD_SELECTION
          record selection formula
static int FORMULA_USER
          user defined formula
static int SYNTAX_BASIC
          Formula in Basic Syntax
static int SYNTAX_CRYSTAL
          Formula in Crystal Syntax
static int TREAT_NULL_AS_NULL
          Sets the formula calculation to tolerate null values, if possible.
static int TREAT_NULL_BY_DEFAULT
          Sets the formula calculation to replace null values by the default values of the same type.
static int TREAT_NULL_BY_EXCEPTION
          Sets the formula calculation to always interrupt if there is any null value.
static int UNSPECIFIED_EVALUATE_TIME
          Constant value of evaluation time.
static int VALUE_TYPE_PENDING
          This is a temporary value type, which will be set as long, as this field is determining it's value type.
static int WHILE_PRINTING_RECORDS
          Constant value of evaluation time.
static int WHILE_READING_RECORDS
          Constant value of evaluation time.
 
Fields inherited from class com.inet.report.Field
BINARY, BOOLEAN, CURRENCY, CURSOR, DATABASE_FIELD, DATE, DATETIME, FORMULA_FIELD, GROUP_NAME_FIELD, NUMBER, PARAMETER_FIELD, SORT_FIELD, SPECIAL_FIELD, SQL_FIELD, STRING, SUMMARY_FIELD, TIME, UNKNOWN
 
Method Summary
 void checkContext()
          Checks the evaluation time of the current formula
static int checkFormula(java.lang.String formula, boolean basic, Engine engine)
          Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.
static int checkFormula(java.lang.String formula, boolean basic, Engine engine, Field currentField, java.lang.Object defaultAttribute)
          Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.
static int checkFormula(java.lang.String formula, boolean basic, Engine engine, Field currentField, java.lang.Object defaultAttribute, int formulaType)
          Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.
static int checkFormula(java.lang.String formula, boolean basic, Engine engine, Field currentField, java.lang.Object defaultAttribute, int formulaType, int nullBehavior)
          Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.
 int checkFormula(java.lang.String formula, boolean basic, int nullBehavior)
          Checks a formula as if it was set to to this formula fields.
 void clearLocalVariables()
          Resets the local variables of this field
 Field duplicate(java.lang.String name)
          Duplicates this field with all its settings and returns the created Field with the given name.
 Field getCurrentField()
          This field references the current report field, which contains this formula.
 int getEvaluateTime()
          Returns the lowest theoretically possible evaluation time this formula can have.
 int getEvaluateTimeReal()
          Returns the time of evaluation of this formula that is actually used at runtime.
 java.lang.String getFormula()
          Returns the value of the property 'formula text'.
 int getFormulaType()
          Returns the formula type, i.e. whether the formula is a record selection, group selection, property, or user formula
 com.inet.report.formula.Variables getLocalVariables()
          Returns all local variables of this field
 int getNullBehavior()
          Returns the null behavoir constant which was set for this formula field.
 int getSyntax()
          Returns the syntax for this formula.
 java.util.Set getTranslationKeys()
          Returns a set of all translation keys used in the formula described by this field.
 int getValueType()
          Returns the value type (or return type) of the field.
static boolean isEmpty(java.lang.String formula, boolean basic, Engine engine)
          Checks the syntax of the formula and returns true if the formula (body without layout) is empty.
 boolean isEmpty()
          Checks the syntax of the formula and returns true if the formula (body without layout) is empty.
static boolean isEmpty(java.lang.String formula, boolean basic, Engine engine, Field currentField, java.lang.Object defaultAttribute)
          Checks the syntax of the formula and returns true if the formula (body without layout) is empty.
 java.lang.String paramString()
          Returns a prettified output of this field's name and type.
 void rename(java.lang.String newName)
          FOR INTERNAL USE ONLY
 void setCurrentField(Field currentField)
          This field references the current report field, which contains this formula.
 void setFormula(java.lang.String formula)
          Sets formula text to this element and parses the formula.
 void setFormulaType(int type)
          Sets the formula type.
 void setName(java.lang.String name)
          Sets the name of the formula field.
 void setNullBehavior(int nullBehavior)
          Sets the null behavoir constant.
 void setSyntax(int syntax)
          Set the syntax for this formula.
 boolean usesSummaryFields()
          Returns true, if this formula field references to a summary field and is referenced by a summary field - either directly or indirectly
 Validity validate()
          Check if the object is valid and returns the state and details of possible errors.
 
Methods inherited from class com.inet.report.Field
checkNameExists, extractReference, getField, getGroup, getName, getPlaceholderName, getRefName, getType, indexOf, setField, setGroup, setValueType, trimAwayBrackets
 
Methods inherited from interface com.inet.report.parser.NodeParser
isDOMParser, parseDOM, parseElement, parseEndElement, parseText
 

Field Detail

FORMULA_USER

public static final int FORMULA_USER
user defined formula

See Also:
Constant Field Values

FORMULA_RECORD_SELECTION

public static final int FORMULA_RECORD_SELECTION
record selection formula

See Also:
Constant Field Values

FORMULA_GROUP_SELECTION

public static final int FORMULA_GROUP_SELECTION
group selection formula

See Also:
Constant Field Values

FORMULA_PROPERTY

public static final int FORMULA_PROPERTY
property formula

See Also:
Constant Field Values

TREAT_NULL_AS_NULL

public static final int TREAT_NULL_AS_NULL
Sets the formula calculation to tolerate null values, if possible. This is the default i-net Clear Reports behavior.

See Also:
Constant Field Values

TREAT_NULL_BY_DEFAULT

public static final int TREAT_NULL_BY_DEFAULT
Sets the formula calculation to replace null values by the default values of the same type. If there is no default value for a type, an exception will be thrown an the calculation will be interrupted.

See Also:
Constant Field Values

TREAT_NULL_BY_EXCEPTION

public static final int TREAT_NULL_BY_EXCEPTION
Sets the formula calculation to always interrupt if there is any null value.

See Also:
Constant Field Values

VALUE_TYPE_PENDING

public static final int VALUE_TYPE_PENDING
This is a temporary value type, which will be set as long, as this field is determining it's value type. If the getValueType() algorithm hit's a field with pending value type, this is a loop, an exception will be thrown.

See Also:
Constant Field Values

UNSPECIFIED_EVALUATE_TIME

public static final int UNSPECIFIED_EVALUATE_TIME
Constant value of evaluation time. The evaluate time was not specified by the user.

See Also:
Constant Field Values

BEFORE_READING_RECORDS

public static final int BEFORE_READING_RECORDS
Constant value of evaluation time. The formula will be evaluated before records from database were read.

See Also:
Constant Field Values

WHILE_READING_RECORDS

public static final int WHILE_READING_RECORDS
Constant value of evaluation time. The formula will be evaluated after records from database were read.

See Also:
Constant Field Values

WHILE_PRINTING_RECORDS

public static final int WHILE_PRINTING_RECORDS
Constant value of evaluation time. The formula will be evaluated while records are printed.

See Also:
Constant Field Values

SYNTAX_CRYSTAL

public static final int SYNTAX_CRYSTAL
Formula in Crystal Syntax

See Also:
Constant Field Values

SYNTAX_BASIC

public static final int SYNTAX_BASIC
Formula in Basic Syntax

See Also:
Constant Field Values
Method Detail

rename

public void rename(java.lang.String newName)
            throws ReportException
FOR INTERNAL USE ONLY

Throws:
ReportException

setName

public void setName(java.lang.String name)
Sets the name of the formula field. The name does not exists already, otherwise an exception will be thrown.

Specified by:
setName in class Field
Parameters:
name - New name to assign to this formula field. So that the field name may be used in a formula, the name may not include the special character "}"
Throws:
java.lang.IllegalArgumentException - if the name already exists

getFormula

public java.lang.String getFormula()
Returns the value of the property 'formula text'. The formula text is the expression of the formula. Use crystal syntax or basic syntax. If you want to specify the formula text in basic syntax, you have to set the property 'basic syntax' to true.

Returns:
The value of the property 'formula text'.
See Also:
setSyntax(int)

setFormula

public void setFormula(java.lang.String formula)
Sets formula text to this element and parses the formula. The formula text can be specified either in crystal or in basic syntax. Please set the syntax type by calling setSyntax(int) before calling this function.

Parameters:
formula - the new formula
See Also:
setSyntax(int), getSyntax(), getFormula()

getSyntax

public int getSyntax()
Returns the syntax for this formula. The two supported syntaxes are Crystal or Basic Syntax.

Returns:
the syntax used by this formula
See Also:
SYNTAX_CRYSTAL, SYNTAX_BASIC

setSyntax

public void setSyntax(int syntax)
Set the syntax for this formula. The two supported syntaxes are Crystal or Basic Syntax.

Parameters:
syntax - the syntax to use for this formula
Throws:
java.lang.IllegalArgumentException - If the syntax is not one of the valid types.
See Also:
SYNTAX_CRYSTAL, SYNTAX_BASIC

getFormulaType

public int getFormulaType()
Returns the formula type, i.e. whether the formula is a record selection, group selection, property, or user formula

Returns:
Type of this formula: A record selection, group selection, property, or user formula
See Also:
FORMULA_USER, FORMULA_RECORD_SELECTION, FORMULA_GROUP_SELECTION, FORMULA_PROPERTY

setFormulaType

public void setFormulaType(int type)
Sets the formula type. If the formula is used as a record selection formula then the type is FORMULA_RECORD_SELECTION. If the formula is used as a group selection formula then the type is FORMULA_GROUP_SELECTION. If the formula is used as a property formula then the type is FORMULA_PROPERTY. Otherwise the type is FORMULA_USER.

Parameters:
type - The type of the formula.
Throws:
java.lang.IllegalArgumentException - is thrown if type is not one of FORMULA_USER, FORMULA_RECORD_SELECTION, FORMULA_GROUP_SELECTION and FORMULA_PROPERTY.
See Also:
FORMULA_USER, FORMULA_RECORD_SELECTION, FORMULA_GROUP_SELECTION, FORMULA_PROPERTY

checkFormula

public static int checkFormula(java.lang.String formula,
                               boolean basic,
                               Engine engine)
                        throws ReportException
Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.

Parameters:
formula - The formula as string
basic - true if formula has basic syntax, else if formula has crystal syntax false
engine - The engine that should evaluate the formula
Returns:
the return type of the formula if syntax and type are correct, else -1 is returned.
Throws:
ReportException - will thrown if the syntax or the type of the formula or its expressions and statements is not correct.

checkFormula

public static int checkFormula(java.lang.String formula,
                               boolean basic,
                               Engine engine,
                               Field currentField,
                               java.lang.Object defaultAttribute)
                        throws ReportException
Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.

Parameters:
formula - The formula as string
basic - true if formula has basic syntax, else if formula has crystal syntax false
engine - The engine that should evaluate the formula
currentField - If checked formula is a formula which calculates the property value of a field element then it is possible to use the value of the field in your formula. Therefor use constant "currentFieldValue" in formula. The field of the field element is needed to get the value from.
defaultAttribute - When prossessing formula which calculates the property value of an element in report, then it is possible to use the constant value of the property in your formulas. Therefore the current value of the property is needed as default attribute.
Returns:
the return type of the formula if syntax and type are correct, else -1 is returned.
Throws:
ReportException - will thrown if the syntax or the type of the formula or its expressions and statements is not correct.

checkFormula

public static int checkFormula(java.lang.String formula,
                               boolean basic,
                               Engine engine,
                               Field currentField,
                               java.lang.Object defaultAttribute,
                               int formulaType)
                        throws ReportException
Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.

Parameters:
formula - The formula as string
basic - true if formula has basic syntax, else if formula has crystal syntax false
engine - The engine that should evaluate the formula
currentField - If checked formula is a formula which calculates the property value of a field element then it is possible to use the value of the field in your formula. Therefor use constant "currentFieldValue" in formula. The field of the field element is needed to get the value from.
defaultAttribute - When prossessing formula which calculates the property value of an element in report, then it is possible to use the constant value of the property in your formulas. Therefore the current value of the property is needed as default attribute.
formulaType - The formula's type: FORMULA_USER, FORMULA_RECORD_SELECTION, FORMULA_GROUP_SELECTION, or FORMULA_PROPERTY
Returns:
the return type of the formula if syntax and type are correct, else -1 is returned.
Throws:
ReportException - will thrown if the syntax or the type of the formula or its expressions and statements is not correct.

checkFormula

public static int checkFormula(java.lang.String formula,
                               boolean basic,
                               Engine engine,
                               Field currentField,
                               java.lang.Object defaultAttribute,
                               int formulaType,
                               int nullBehavior)
                        throws ReportException
Checks the syntax and the type of the formula and returns the return type of the formula if formula has no errors.

Parameters:
formula - The formula as string
basic - true if formula has basic syntax, else if formula has crystal syntax false
engine - The engine that should evaluate the formula
currentField - If checked formula is a formula which calculates the property value of a field element then it is possible to use the value of the field in your formula. Therefor use constant "currentFieldValue" in formula. The field of the field element is needed to get the value from.
defaultAttribute - When prossessing formula which calculates the property value of an element in report, then it is possible to use the constant value of the property in your formulas. Therefore the current value of the property is needed as default attribute.
formulaType - The formula's type: FORMULA_USER, FORMULA_RECORD_SELECTION, FORMULA_GROUP_SELECTION, or FORMULA_PROPERTY
nullBehavior - The null behavior constant: TREAT_NULL_AS_NULL, TREAT_NULL_BY_DEFAULT, TREAT_NULL_BY_EXCEPTION
Returns:
the return type of the formula if syntax and type are correct, else -1 is returned.
Throws:
ReportException - will thrown if the syntax or the type of the formula or its expressions and statements is not correct.
Since:
9.0

checkFormula

public int checkFormula(java.lang.String formula,
                        boolean basic,
                        int nullBehavior)
                 throws ReportException
Checks a formula as if it was set to to this formula fields. If you're unsure, whether modifying the formula of this field would be corrct, call this function before calling setFormula.

Parameters:
formula - the formula to check
basic - true if formula has basic syntax, else if formula has crystal syntax false
nullBehavior - The null behavior constant: TREAT_NULL_AS_NULL, TREAT_NULL_BY_DEFAULT, TREAT_NULL_BY_EXCEPTION
Returns:
the resulting value type of the formula
Throws:
ReportException - thrown if the formula causes any error
Since:
10.0

getValueType

public int getValueType()
Returns the value type (or return type) of the field.
NOTE:If DefaultAttribute is used within the formula it has to be set before calling this method. A null-value will cause an exception here. If you don't know the exact value of the DefaultAttribute you may use a dummy-value for getValueType. The reason is that getValueType only regards the type of object not their value.

Overrides:
getValueType in class Field
Returns:
The value of the property 'value type'.
See Also:
Field.NUMBER, Field.CURRENCY, Field.BOOLEAN, Field.DATE, Field.TIME, Field.STRING, Field.DATETIME

checkContext

public void checkContext()
                  throws ReportException
Checks the evaluation time of the current formula

Throws:
ReportException - will be thrown if the formula cannot be executed at the requested time
Since:
9.0

isEmpty

public static boolean isEmpty(java.lang.String formula,
                              boolean basic,
                              Engine engine)
                       throws ReportException
Checks the syntax of the formula and returns true if the formula (body without layout) is empty.

Parameters:
formula - The formula as string
basic - true if formula has basic syntax, else if formula has crystal syntax false
engine - The engine that should evaluate the formula
Returns:
true if formula is empty (except layout like blanks, line feeds, comments) else false
Throws:
ReportException - will thrown if the syntax or the type of the formula or its expressions and statements is not correct.

isEmpty

public boolean isEmpty()
Checks the syntax of the formula and returns true if the formula (body without layout) is empty.

Returns:
true if formula is empty (except layout like blanks, line feeds, comments) else false

isEmpty

public static boolean isEmpty(java.lang.String formula,
                              boolean basic,
                              Engine engine,
                              Field currentField,
                              java.lang.Object defaultAttribute)
                       throws ReportException
Checks the syntax of the formula and returns true if the formula (body without layout) is empty.

Parameters:
formula - The formula as string
basic - true if formula has basic syntax, else if formula has crystal syntax false
engine - The engine that should evaluate the formula
currentField - Field to be viewed as the "currentField" of the report, specifically for the "CurrentField" function.
defaultAttribute - Attribute to be viewed as the "defaultAttribute", specifically for the "DefaultAttribute" function.
Returns:
true if formula is empty (except layout like blanks, line feeds, comments) else false
Throws:
ReportException - will thrown if the syntax or the type of the formula or its expressions and statements is not correct.

paramString

public java.lang.String paramString()
Returns a prettified output of this field's name and type.

Overrides:
paramString in class Field
Returns:
Prettified output of this field's name and type.

getEvaluateTimeReal

public int getEvaluateTimeReal()
                        throws ReportException
Returns the time of evaluation of this formula that is actually used at runtime. The difference to the method getEvaluateTime is that formulas will not return as WHILE_READING_RECORDS unless explicitly requested. Rather they will be optimized to "WHILE_PRINTING_RECORDS" in order to reduce the amount of memory needed. This reflects the actual optimization done at run time.

Returns:
Time of evaluation of the formula actually used at runtime. BEFORE_READING_RECORDS, WHILE_PRINTING_RECORDS, or WHILE_READING_RECORDS.
Throws:
ReportException - If parsing the formula encounters errors.
See Also:
BEFORE_READING_RECORDS, WHILE_READING_RECORDS, WHILE_PRINTING_RECORDS, getEvaluateTime()

getEvaluateTime

public int getEvaluateTime()
                    throws ReportException
Returns the lowest theoretically possible evaluation time this formula can have. At run time, this may be optimized to be a higher evaluation time to save memory. getEvaluateTimeReal returns the evaluation time which is actually used at run time.

Returns:
Lowest theoretically possible time of evaluation for this formula. BEFORE_READING_RECORDS, WHILE_PRINTING_RECORDS, or WHILE_READING_RECORDS.
Throws:
ReportException - If parsing the formula causes any errors
See Also:
BEFORE_READING_RECORDS, WHILE_READING_RECORDS, WHILE_PRINTING_RECORDS, getEvaluateTimeReal(boolean)

duplicate

public Field duplicate(java.lang.String name)
Duplicates this field with all its settings and returns the created Field with the given name. Note that the new formula field will not initially be referenced by any other report objects. If you duplicate a property formula, you will have to set the new formula as a separate property formula.

Overrides:
duplicate in class Field
Parameters:
name - the name the created field should have.
Returns:
the duplicated field.

getNullBehavior

public int getNullBehavior()
Returns the null behavoir constant which was set for this formula field. This constant influences the way null values will be treated on evaluation time.

Returns:
the behavior constant
Since:
9.0
See Also:
TREAT_NULL_AS_NULL, TREAT_NULL_BY_DEFAULT, TREAT_NULL_BY_EXCEPTION

setNullBehavior

public void setNullBehavior(int nullBehavior)
Sets the null behavoir constant. This constant influences the way null values will be treated on evaluation time.

Parameters:
nullBehavior - the behavior constant
Since:
9.0
See Also:
TREAT_NULL_AS_NULL, TREAT_NULL_BY_DEFAULT, TREAT_NULL_BY_EXCEPTION

usesSummaryFields

public boolean usesSummaryFields()
Returns true, if this formula field references to a summary field and is referenced by a summary field - either directly or indirectly

Returns:
true if linked both ways to a summary field
Since:
9.1

getTranslationKeys

public java.util.Set getTranslationKeys()
Returns a set of all translation keys used in the formula described by this field.
NOTE: This will re-parse the formula, which costs time and memory!

Returns:
the translation keys or null, if there is no translation used
Since:
9.1

validate

public Validity validate()
Check if the object is valid and returns the state and details of possible errors.

Specified by:
validate in interface Validatable
Returns:
the current state, never null.

getLocalVariables

public com.inet.report.formula.Variables getLocalVariables()
Returns all local variables of this field

Returns:
the local variables of this field, it's never null
Since:
10.0

clearLocalVariables

public void clearLocalVariables()
Resets the local variables of this field

Since:
10.0

setCurrentField

public void setCurrentField(Field currentField)
This field references the current report field, which contains this formula. If this is a property formula of a field element in a report, this variable will reference the field of the report element.
Whatever is set here, will be returned by the formula function 'currentFieldValue'.

Parameters:
currentField - field to set as "current report field"
Since:
10.0

getCurrentField

public Field getCurrentField()
This field references the current report field, which contains this formula. If this is a property formula of a field element in a report, this variable will reference the field of the report element.
Whatever is set here, will be returned by the formula function 'currentFieldValue'.

Returns:
the "current report field"
Since:
10.0

i-net Clear Reports

Copyright © 1999-2015 by i-net software GmbH