BaseFormulaEvaluator (POI API Documentation)

java.lang.Object
- org.apache.poi.ss.formula.BaseFormulaEvaluator

All Implemented Interfaces:

WorkbookEvaluatorProvider, FormulaEvaluator

Direct Known Subclasses:

BaseXSSFFormulaEvaluator, HSSFFormulaEvaluator
```
public abstract class BaseFormulaEvaluator
extends java.lang.Object
implements FormulaEvaluator, WorkbookEvaluatorProvider
```
Common functionality across file formats for evaluating formula cells.

Field Summary

Fields
Modifier and Type Field and Description

protected WorkbookEvaluator _bookEvaluator

Fields
Modifier and Type	Field and Description
`protected WorkbookEvaluator`	`_bookEvaluator`

Constructor Summary

Constructors
Modifier Constructor and Description

protected BaseFormulaEvaluator(WorkbookEvaluator bookEvaluator)

Constructors
Modifier	Constructor and Description
`protected`	`BaseFormulaEvaluator(WorkbookEvaluator bookEvaluator)`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`WorkbookEvaluator`	`_getWorkbookEvaluator()` Provide the underlying WorkbookEvaluator
`void`	`clearAllCachedResultValues()` Should be called whenever there are major changes (e.g.
`protected abstract RichTextString`	`createRichTextString(java.lang.String str)`
`CellValue`	`evaluate(Cell cell)` If cell contains a formula, the formula is evaluated and returned, else the CellValue simply copies the appropriate cell value from the cell and also its cell type.
`static void`	`evaluateAllFormulaCells(Workbook wb)` Loops over all cells in all sheets of the supplied workbook.
`protected static void`	`evaluateAllFormulaCells(Workbook wb, FormulaEvaluator evaluator)`
`CellType`	`evaluateFormulaCell(Cell cell)` If cell contains formula, it evaluates the formula, and saves the result of the formula.
`protected abstract CellValue`	`evaluateFormulaCellValue(Cell cell)`
`Cell`	`evaluateInCell(Cell cell)` If cell contains formula, it evaluates the formula, and puts the formula result back into the cell, in place of the old formula.
`protected EvaluationWorkbook`	`getEvaluationWorkbook()` internal use
`protected void`	`setCellType(Cell cell, CellType cellType)` Override if a different variation is needed, e.g.
`protected void`	`setCellType(Cell cell, CellValue cv)` Set the cell type based on the computed cell type as part of a formula evaluation.
`protected void`	`setCellValue(Cell cell, CellValue cv)`
`void`	`setDebugEvaluationOutputForNextEval(boolean value)` Perform detailed output of formula evaluation for next evaluation only? Is for developer use only (also developers using POI for their XLS files).
`void`	`setIgnoreMissingWorkbooks(boolean ignore)` Whether to ignore missing references to external workbooks and use cached formula results in the main workbook instead.
`static void`	`setupEnvironment(java.lang.String[] workbookNames, BaseFormulaEvaluator[] evaluators)` Coordinates several formula evaluators together so that formulas that involve external references can be evaluated.
`void`	`setupReferencedWorkbooks(java.util.Map<java.lang.String,FormulaEvaluator> evaluators)` Sets up the Formula Evaluator to be able to reference and resolve links to other workbooks, eg [Test.xls]Sheet1!A1.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.poi.ss.usermodel.FormulaEvaluator
evaluateAll, notifyDeleteCell, notifySetFormula, notifyUpdateCell

- Field Detail
  - _bookEvaluator
```
protected final WorkbookEvaluator _bookEvaluator
```
- Constructor Detail
  - BaseFormulaEvaluator
```
protected BaseFormulaEvaluator(WorkbookEvaluator bookEvaluator)
```
- Method Detail
  - setupEnvironment
```
public static void setupEnvironment(java.lang.String[] workbookNames,
                                    BaseFormulaEvaluator[] evaluators)
```
    Coordinates several formula evaluators together so that formulas that involve external references can be evaluated.
    
    Parameters:
    
    workbookNames - the simple file names used to identify the workbooks in formulas with external links (for example "MyData.xls" as used in a formula "[MyData.xls]Sheet1!A1")
    
    evaluators - all evaluators for the full set of workbooks required by the formulas.
  - setupReferencedWorkbooks
```
public void setupReferencedWorkbooks(java.util.Map<java.lang.String,FormulaEvaluator> evaluators)
```
    Description copied from interface: FormulaEvaluator
    
    Sets up the Formula Evaluator to be able to reference and resolve links to other workbooks, eg [Test.xls]Sheet1!A1.
    For a workbook referenced as [Test.xls]Sheet1!A1, you should supply a map containing the key Test.xls (no square brackets), and an open FormulaEvaluator onto that Workbook.
    
    Specified by:
    
    setupReferencedWorkbooks in interface FormulaEvaluator
    
    Parameters:
    
    evaluators - Map of workbook names (no square brackets) to an evaluator on that workbook
  - _getWorkbookEvaluator
```
public WorkbookEvaluator _getWorkbookEvaluator()
```
    Description copied from interface: WorkbookEvaluatorProvider
    
    Provide the underlying WorkbookEvaluator
    
    Specified by:
    
    _getWorkbookEvaluator in interface WorkbookEvaluatorProvider
  - getEvaluationWorkbook
```
protected EvaluationWorkbook getEvaluationWorkbook()
```
    internal use
    
    Returns:
    
    evaluation workbook
  - clearAllCachedResultValues
```
public void clearAllCachedResultValues()
```
    Should be called whenever there are major changes (e.g. moving sheets) to input cells in the evaluated workbook. If performance is not critical, a single call to this method may be used instead of many specific calls to the notify~ methods. Failure to call this method after changing cell values will cause incorrect behaviour of the evaluate~ methods of this class
    
    Specified by:
    
    clearAllCachedResultValues in interface FormulaEvaluator
  - evaluate
```
public CellValue evaluate(Cell cell)
```
    If cell contains a formula, the formula is evaluated and returned, else the CellValue simply copies the appropriate cell value from the cell and also its cell type. This method should be preferred over evaluateInCell() when the call should not modify the contents of the original cell.
    
    Specified by:
    
    evaluate in interface FormulaEvaluator
    
    Parameters:
    
    cell - may be null signifying that the cell is not present (or blank)
    
    Returns:
    
    null if the supplied cell is null or blank
  - evaluateInCell
```
public Cell evaluateInCell(Cell cell)
```
    If cell contains formula, it evaluates the formula, and puts the formula result back into the cell, in place of the old formula. Else if cell does not contain formula, this method leaves the cell unchanged. Note that the same instance of Cell is returned to allow chained calls like:
```
 int evaluatedCellType = evaluator.evaluateInCell(cell).getCellType();
 
```
    Be aware that your cell value will be changed to hold the result of the formula. If you simply want the formula value computed for you, use evaluateFormulaCell(Cell)}
    Specified by:
    
    evaluateInCell in interface FormulaEvaluator
    
    Parameters:
    
    cell - The Cell to evaluate and modify.
    
    Returns:
    
    the cell that was passed in, allowing for chained calls
  - evaluateFormulaCellValue
```
protected abstract CellValue evaluateFormulaCellValue(Cell cell)
```
  - evaluateFormulaCell
```
public CellType evaluateFormulaCell(Cell cell)
```
    If cell contains formula, it evaluates the formula, and saves the result of the formula. The cell remains as a formula cell. Else if cell does not contain formula, this method leaves the cell unchanged. Note that the type of the formula result is returned, so you know what kind of value is also stored with the formula.
```
 CellType evaluatedCellType = evaluator.evaluateFormulaCell(cell);
 
```
    Be aware that your cell will hold both the formula, and the result. If you want the cell replaced with the result of the formula, use evaluate(org.apache.poi.ss.usermodel.Cell) }
    Specified by:
    
    evaluateFormulaCell in interface FormulaEvaluator
    
    Parameters:
    
    cell - The cell to evaluate
    
    Returns:
    
    The type of the formula result (the cell's type remains as CellType.FORMULA however) If cell is not a formula cell, returns CellType._NONE rather than throwing an exception.
  - setCellType
```
protected void setCellType(Cell cell,
                           CellValue cv)
```
    Set the cell type based on the computed cell type as part of a formula evaluation.
    
    Parameters:
    
    cell - The Cell to populate
    
    cv - The CellValue to read the result type from
  - setCellType
```
protected void setCellType(Cell cell,
                           CellType cellType)
```
    Override if a different variation is needed, e.g. passing the evaluator to the cell method
    
    Parameters:
    
    cell - The Cell to populate
    
    cellType - The wanted type for this Cell
  - createRichTextString
```
protected abstract RichTextString createRichTextString(java.lang.String str)
```
  - setCellValue
```
protected void setCellValue(Cell cell,
                            CellValue cv)
```
  - evaluateAllFormulaCells
```
public static void evaluateAllFormulaCells(Workbook wb)
```
    Loops over all cells in all sheets of the supplied workbook. For cells that contain formulas, their formulas are evaluated, and the results are saved. These cells remain as formula cells. For cells that do not contain formulas, no changes are made. This is a helpful wrapper around looping over all cells, and calling evaluateFormulaCell on each one.
  - evaluateAllFormulaCells
```
protected static void evaluateAllFormulaCells(Workbook wb,
                                              FormulaEvaluator evaluator)
```
  - setIgnoreMissingWorkbooks
```
public void setIgnoreMissingWorkbooks(boolean ignore)
```
    Whether to ignore missing references to external workbooks and use cached formula results in the main workbook instead.
    In some cases external workbooks referenced by formulas in the main workbook are not available. With this method you can control how POI handles such missing references:
    - by default ignoreMissingWorkbooks=false and POI throws CollaboratingWorkbooksEnvironment.WorkbookNotFoundException if an external reference cannot be resolved
    - if ignoreMissingWorkbooks=true then POI uses cached formula result that already exists in the main workbook
    Specified by:
    
    setIgnoreMissingWorkbooks in interface FormulaEvaluator
    
    Parameters:
    
    ignore - whether to ignore missing references to external workbooks
  - setDebugEvaluationOutputForNextEval
```
public void setDebugEvaluationOutputForNextEval(boolean value)
```
    Perform detailed output of formula evaluation for next evaluation only? Is for developer use only (also developers using POI for their XLS files). Log-Level WARN is for basic info, INFO for detailed information. These quite high levels are used because you have to explicitly enable this specific logging.
    
    Specified by:
    
    setDebugEvaluationOutputForNextEval in interface FormulaEvaluator
    
    Parameters:
    
    value - whether to perform detailed output

Class BaseFormulaEvaluator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.apache.poi.ss.usermodel.FormulaEvaluator

Field Detail

_bookEvaluator

Constructor Detail

BaseFormulaEvaluator

Method Detail

setupEnvironment

setupReferencedWorkbooks

_getWorkbookEvaluator

getEvaluationWorkbook

clearAllCachedResultValues

evaluate

evaluateInCell

evaluateFormulaCellValue

evaluateFormulaCell

setCellType

setCellType

createRichTextString

setCellValue

evaluateAllFormulaCells

evaluateAllFormulaCells

setIgnoreMissingWorkbooks

setDebugEvaluationOutputForNextEval