Package org.apache.poi.ss.formula
Class BaseFormulaEvaluator
 java.lang.Object

 org.apache.poi.ss.formula.BaseFormulaEvaluator

 All Implemented Interfaces:
WorkbookEvaluatorProvider
,FormulaEvaluator
 Direct Known Subclasses:
BaseXSSFFormulaEvaluator
,HSSFFormulaEvaluator
public abstract class BaseFormulaEvaluator extends Object implements FormulaEvaluator, WorkbookEvaluatorProvider
Common functionality across file formats for evaluating formula cells.


Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description WorkbookEvaluator
_getWorkbookEvaluator()
Provide the underlying WorkbookEvaluatorvoid
clearAllCachedResultValues()
Should be called whenever there are major changes (e.g.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.CellType
evaluateFormulaCell(Cell cell)
If cell contains formula, it evaluates the formula, and saves the result of the formula.CellType
evaluateFormulaCellEnum(Cell cell)
Deprecated.useevaluateFormulaCell(cell)
insteadCell
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.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(String[] workbookNames, BaseFormulaEvaluator[] evaluators)
Coordinates several formula evaluators together so that formulas that involve external references can be evaluated.void
setupReferencedWorkbooks(Map<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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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




Method Detail

setupEnvironment
public static void setupEnvironment(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(Map<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 interfaceFormulaEvaluator
 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 interfaceWorkbookEvaluatorProvider

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 interfaceFormulaEvaluator

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 interfaceFormulaEvaluator
 Parameters:
cell
 may benull
signifying that the cell is not present (or blank) Returns:
null
if the supplied cell isnull
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 ofCell
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, useevaluateFormulaCell(Cell)
} Specified by:
evaluateInCell
in interfaceFormulaEvaluator
 Parameters:
cell
 TheCell
to evaluate and modify. Returns:
 the
cell
that was passed in, allowing for chained calls

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, useevaluate(org.apache.poi.ss.usermodel.Cell)
} Specified by:
evaluateFormulaCell
in interfaceFormulaEvaluator
 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.

evaluateFormulaCellEnum
@Deprecated @Removal(version="4.2") public CellType evaluateFormulaCellEnum(Cell cell)
Deprecated.useevaluateFormulaCell(cell)
insteadIf 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, useevaluate(org.apache.poi.ss.usermodel.Cell)
} Specified by:
evaluateFormulaCellEnum
in interfaceFormulaEvaluator
 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.  Since:
 POI 3.15 beta 3

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.

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 interfaceFormulaEvaluator
 Parameters:
ignore
 whether to ignore missing references to external workbooks
 by default ignoreMissingWorkbooks=false and POI throws

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). LogLevel 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 interfaceFormulaEvaluator
 Parameters:
value
 whether to perform detailed output

