Apache POI - Common 5.3.0 · org.apache.poi.ss.usermodel.FormulaEvaluator

Method Summary

Modifier and Type	Method and Description
public void	clearAllCachedResultValues() Should be called whenever there are changes to input cells in the evaluated workbook.
public CellValue	evaluate(Cell The `Cell` to evaluate 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.
public void	evaluateAll() Loops over all cells in all sheets of the associated workbook.
public CellType	Returns: The type of the formula result, i.e. -1 if the cell is not a formula, or one of `CellType#NUMERIC`, `CellType#STRING`, `CellType#BOOLEAN`, `CellType#ERROR` Note the cell's type remains as CellType.FORMULA however. evaluateFormulaCell(Cell The cell to evaluate cell) If cell contains formula, it evaluates the formula, and saves the result of the formula.
public Cell	evaluateInCell(Cell The `Cell` to evaluate and modify. cell) If cell contains formula, it evaluates the formula, and puts the formula result back into the cell, in place of the old formula.
public void	notifyDeleteCell(Cell cell) Should be called to tell the cell value cache that the specified cell has just become a formula cell, or the formula text has changed
public void	notifySetFormula(Cell cell) Should be called to tell the cell value cache that the specified (value or formula) cell has changed.
public void	notifyUpdateCell(Cell cell) Should be called to tell the cell value cache that the specified (value or formula) cell has changed.
public void	setDebugEvaluationOutputForNextEval(boolean whether to perform detailed output value) Perform detailed output of formula evaluation for next evaluation only?
public void	setIgnoreMissingWorkbooks(boolean whether to ignore missing references to external workbooks ignore) Whether to ignore missing references to external workbooks and use cached formula results in the main workbook instead.
public void	setupReferencedWorkbooks(Map<String, FormulaEvaluator> Map of workbook names (no square brackets) to an evaluator on that workbook workbooks) Sets up the Formula Evaluator to be able to reference and resolve links to other workbooks, eg [Test.xls]Sheet1!A1.

Method Detail

clearAllCachedResultValues	back to summary
public void clearAllCachedResultValues() Should be called whenever there are changes to input cells in the evaluated workbook. Failure to call this method after changing cell values will cause incorrect behaviour of the evaluate~ methods of this class

evaluate back to summary

evaluate	back to summary
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. Parameters cell:Cell The `Cell` to 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.

Parameters

cell:Cell: The Cell to evaluate

evaluateAll	back to summary
public void evaluateAll() Loops over all cells in all sheets of the associated 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.

evaluateFormulaCell back to summary

evaluateFormulaCell	back to summary
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. int 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 `evaluateInCell(Cell)` Parameters cell:Cell The cell to evaluate Returns:CellType The type of the formula result, i.e. -1 if the cell is not a formula, or one of `CellType#NUMERIC`, `CellType#STRING`, `CellType#BOOLEAN`, `CellType#ERROR` Note the cell's type remains as CellType.FORMULA however.

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.

int 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 evaluateInCell(Cell)

Parameters

cell:Cell: The cell to evaluate

Returns:CellType

The type of the formula result, i.e. -1 if the cell is not a formula, or one of CellType#NUMERIC, CellType#STRING, CellType#BOOLEAN, CellType#ERROR

Note

the cell's type remains as CellType.FORMULA however.

evaluateInCell back to summary

evaluateInCell	back to summary
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)` Parameters cell:Cell The `Cell` to evaluate and modify.

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)

Parameters

cell:Cell: The Cell to evaluate and modify.

notifyDeleteCell	back to summary
public void notifyDeleteCell(Cell cell) Should be called to tell the cell value cache that the specified cell has just become a formula cell, or the formula text has changed

notifySetFormula	back to summary
public void notifySetFormula(Cell cell) Should be called to tell the cell value cache that the specified (value or formula) cell has changed. Failure to call this method after changing cell values will cause incorrect behaviour of the evaluate~ methods of this class

notifyUpdateCell	back to summary
public void notifyUpdateCell(Cell cell) Should be called to tell the cell value cache that the specified (value or formula) cell has changed. Failure to call this method after changing cell values will cause incorrect behaviour of the evaluate~ methods of this class

setDebugEvaluationOutputForNextEval	back to summary
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. Parameters value:boolean whether to perform detailed output

setDebugEvaluationOutputForNextEval

back to summary

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.

Parameters

value:boolean: whether to perform detailed output

setIgnoreMissingWorkbooks back to summary

setIgnoreMissingWorkbooks	back to summary
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 `org.apache.poi.ss.formula.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 Parameters ignore:boolean whether to ignore missing references to external workbooks

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 org.apache.poi.ss.formula.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

Parameters

ignore:boolean: whether to ignore missing references to external workbooks

setupReferencedWorkbooks	back to summary
public void setupReferencedWorkbooks(Map<String, FormulaEvaluator> workbooks) 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. Parameters workbooks:Map<String, FormulaEvaluator> Map of workbook names (no square brackets) to an evaluator on that workbook

setupReferencedWorkbooks

back to summary

public void setupReferencedWorkbooks(Map<String, FormulaEvaluator> workbooks)

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.

Parameters

workbooks:Map<String, FormulaEvaluator>: Map of workbook names (no square brackets) to an evaluator on that workbook

public Interface FormulaEvaluator

Method Summary

Method Detail