Package 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, 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:

  • Field Details

    • FORMULA_USER

      public static final int FORMULA_USER
      user defined formula
      See Also:

    • FORMULA_RECORD_SELECTION

      public static final int FORMULA_RECORD_SELECTION
      record selection formula
      See Also:

    • FORMULA_GROUP_SELECTION

      public static final int FORMULA_GROUP_SELECTION
      group selection formula
      See Also:

    • FORMULA_PROPERTY

      public static final int FORMULA_PROPERTY
      property formula
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • SYNTAX_CRYSTAL

      public static final int SYNTAX_CRYSTAL
      Formula in Crystal Syntax
      See Also:

    • SYNTAX_BASIC

      public static final int SYNTAX_BASIC
      Formula in Basic Syntax
      See Also:

    • loopCount

      @Deprecated public int loopCount
      Deprecated.
      as of i-net Clear Reports 14
      FOR INTERNAL USE ONLY

  • Method Details

    • getElementOfPropertyFormula

      public ReportComponent getElementOfPropertyFormula()
      FOR INTERNAL USE ONLY Returns the element which is the owner of this formula if this formula is a property formula.
      Returns:
      If this formula is a property formula the element will be returned otherwise null
      Since:
      6.1

    • rename

      public void rename(String newName) throws ReportException
      FOR INTERNAL USE ONLY
      Overrides:
      rename in class Field
      Throws:
      ReportException

    • setName

      public void setName(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:
      IllegalArgumentException - if the name already exists
      Since:
      6.0

    • getFormula

      public 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.
      Specified by:
      getFormula in interface com.inet.report.formula.IFormulaData
      Returns:
      The value of the property 'formula text'.
      Since:
      6.0
      See Also:

    • setFormula

      public void setFormula(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.
      Specified by:
      setFormula in interface com.inet.report.formula.IFormulaData
      Parameters:
      formula - the new formula
      Since:
      6.0
      See Also:

    • getSyntax

      public int getSyntax()
      Returns the syntax for this formula. The two supported syntaxes are Crystal or Basic Syntax.
      Specified by:
      getSyntax in interface com.inet.report.formula.IFormulaData
      Returns:
      the syntax used by this formula
      Since:
      6.0
      See Also:

    • setSyntax

      public void setSyntax(int syntax)
      Set the syntax for this formula. The two supported syntaxes are Crystal or Basic Syntax.
      Specified by:
      setSyntax in interface com.inet.report.formula.IFormulaData
      Parameters:
      syntax - the syntax to use for this formula
      Throws:
      IllegalArgumentException - If the syntax is not one of the valid types.
      Since:
      6.0
      See Also:

    • 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:

    • 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:
      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:

    • checkFormula

      public static int checkFormula(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(String formula, boolean basic, Engine engine, Field currentField, 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(String formula, boolean basic, Engine engine, Field currentField, 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(String formula, boolean basic, Engine engine, Field currentField, 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(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:

    • 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(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(String formula, boolean basic, Engine engine, Field currentField, 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 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.

    • toSql

      public com.inet.report.formula.ToSQLResult toSql(com.inet.report.database.sql.SqlSyntax syntax, com.inet.report.formula.FieldFilter filter, boolean useDesignMode) throws ReportException
      FOR INTERNAL USE ONLY Converts the content of this formula to an SQL statement. The result will only contain the convertable part. The non-convertible part will remain in the AST of this field.
      Parameters:
      syntax - the SQL conversion syntax to be used. This depends on the database where the SQL is to be executed. Must not be null
      filter - the filter for the tables which are present on the target database. This is especially relevant if several datasources are used in one report. If null, all fields are allowed
      useDesignMode - if set to false, the SQL will optimized with the assumption that all referenced fields have their final value. This may lead to wrong results or exceptions in case any value yet undefined. If set to true, all undefined values (e.G. Prompts) will be optimized and the parts of the formula which will be final at runtime will be marked as such.
      Returns:
      the conversion result, may be null if the formula is empty
      Throws:
      ReportException - in case the formula is completely not executable in this database
      Since:
      6.0

    • saveFieldXML2

      protected void saveFieldXML2(PrintWriter pw, int depth)
      FOR INTERNAL USE ONLY Saves this field in XML format
      Specified by:
      saveFieldXML2 in class Field
      Parameters:
      pw - the writer to write to
      depth - the XML indentication depth

    • 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:

    • 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:

    • addReferencedObject

      public void addReferencedObject(com.inet.report.ReferencedObject reference)
      FOR INTERNAL USE ONLY
      Specified by:
      addReferencedObject in interface com.inet.report.ReferenceHolder
      Parameters:
      reference - the object to refer to
      Since:
      6.0

    • getReferencedObjects

      public com.inet.report.ReferencedObject[] getReferencedObjects()
      FOR INTERNAL USE ONLY
      Specified by:
      getReferencedObjects in interface com.inet.report.ReferenceHolder
      Returns:
      the objects this field refers to

    • getReferencedObjectCount

      public int getReferencedObjectCount()
      FOR INTERNAL USE ONLY
      Specified by:
      getReferencedObjectCount in interface com.inet.report.ReferenceHolder
      Returns:
      the number of distinct objects this field refers to

    • getRealReferencedObjectCount

      public int getRealReferencedObjectCount()
      FOR INTERNAL USE ONLY
      Specified by:
      getRealReferencedObjectCount in interface com.inet.report.ReferenceHolder
      Returns:
      the number of total references, not distinct
      Since:
      6.0

    • removeReferencedObject

      public void removeReferencedObject(com.inet.report.ReferencedObject reference)
      FOR INTERNAL USE ONLY
      Specified by:
      removeReferencedObject in interface com.inet.report.ReferenceHolder
      Parameters:
      reference - the reference to remove
      Since:
      6.0

    • setReferences

      public void setReferences()
      FOR INTERNAL USE ONLY
      Specified by:
      setReferences in interface com.inet.report.ReferenceHolder

    • resetReferences

      public void resetReferences()
      FOR INTERNAL USE ONLY
      Specified by:
      resetReferences in interface com.inet.report.ReferenceHolder

    • isUsed

      public boolean isUsed()
      FOR INTERNAL USE ONLY
      Overrides:
      isUsed in class Field
      Returns:
      true, if this field is used by the report or by another field
      Since:
      6.0

    • setOptimized

      public void setOptimized()
      FOR INTERNAL USE ONLY
      Specified by:
      setOptimized in interface com.inet.report.formula.IFormulaData

    • isOptimized

      public boolean isOptimized()
      FOR INTERNAL USE ONLY
      Specified by:
      isOptimized in interface com.inet.report.formula.IFormulaData
      Returns:
      true if the AST of this formula field is optimized

    • parseElement

      public NodeParser parseElement(com.inet.report.parser.XMLTag group, String tag, Attributes atts, Map<String,Object> parserMap) throws FatalParserException
      FOR INTERNAL USE ONLY FOR INTERNAL USE ONLY Internal method for reading report XML

      Parses an XML node with the given information, and returns either a sub-element which was created as a result, or null if no sub-element was created, i.e. the information was applied to the ReportComponent itself. Note that the parsing is highly tolerant, i.e. exceptions are intercepted and suppressed if at all possible.

      Specified by:
      parseElement in interface NodeParser
      Overrides:
      parseElement in class Field
      Parameters:
      group - XMLTag of the current node to be parsed, or null if there is no such current group. An XMLTag is a group of nodes bundled together, usually it is a Properties node such as CommonProperties, BorderProperties, etc.
      tag - The XMLTag to be parsed
      atts - The set of attributes in the current XMLTag
      parserMap - The map of current Parser.
      Returns:
      The NodeParser sub-element if one needed to be created, or null if none was created.
      Throws:
      FatalParserException - if an exception occurs which causes the report to not be able to be read: causes the abortion of the reading of the report.

    • parseEndElement

      public void parseEndElement(com.inet.report.parser.XMLTag group, String tag, Map<String,Object> parserMap) throws FatalParserException
      FOR INTERNAL USE ONLY FOR INTERNAL USE ONLY Internal method for reading report XML

      Receive notification of the end of an XML tag.

      Specified by:
      parseEndElement in interface NodeParser
      Overrides:
      parseEndElement in class Field
      Parameters:
      group - XMLTag of the current node to be parsed, or null if there is no such current group.
      tag - The XMLTag to be parsed
      parserMap - The map of current Parser.
      Throws:
      FatalParserException - if an exception occurs which causes the report to not be able to be read: causes the abortion of the reading of the report.

    • parseText

      public void parseText(String text, Map<String,Object> parserMap)
      FOR INTERNAL USE ONLY FOR INTERNAL USE ONLY Internal method for reading report XML

      This method is called if text was encountered in the context of this node. (Examples would be a formula's text or a text element's text)

      Specified by:
      parseText in interface NodeParser
      Overrides:
      parseText in class Field
      Parameters:
      text - text encountered and to be stored
      parserMap - The map of current Parser.

    • duplicate

      public Field duplicate(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:

    • 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:

    • 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 Set<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
      Specified by:
      getLocalVariables in interface com.inet.report.formula.IFormulaData
      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
      Specified by:
      clearLocalVariables in interface com.inet.report.formula.IFormulaData
      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

    • setFormulaTree

      public void setFormulaTree(com.inet.report.formula.Evaluable tree)
      FOR INTERNAL USE ONLY
      Specified by:
      setFormulaTree in interface com.inet.report.formula.IFormulaData
      Since:
      10.1

    • getFormulaTree

      public com.inet.report.formula.Evaluable getFormulaTree()
      FOR INTERNAL USE ONLY
      Specified by:
      getFormulaTree in interface com.inet.report.formula.IFormulaData
      Since:
      10.1