com.inet.report

Class FormulaField

java.lang.Object

com.inet.report.Field

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.

Since:

6.0

See Also:

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

Field Summary

Fields

Modifier and Type	Field and Description
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	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

Modifier and Type	Method and Description
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<java.lang.String>	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	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

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

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

Since:

6.0

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'.

Since:

6.0

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

Since:

6.0

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

Since:

6.0

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.

Since:

6.0

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

Since:

6.0

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.

Since:

6.0

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.

Since:

6.0

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. Therefore use constant "currentFieldValue" in formula. The field of the field element is needed to get the value from.

defaultAttribute - When processing 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.

Since:

6.0

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. Therefore use constant "currentFieldValue" in formula. The field of the field element is needed to get the value from.

defaultAttribute - When processing 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.

Since:

6.0

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. Therefore use constant "currentFieldValue" in formula. The field of the field element is needed to get the value from.

defaultAttribute - When processing 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.

Since:

6.0

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

Since:

6.0

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.

Since:

6.0

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.

Since:

6.0

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

Since:

6.0

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. Invalid values will set the value to the next valid value.

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<java.lang.String> 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