org.zkoss.poi.xssf.usermodel

Class XSSFFormulaEvaluator

java.lang.Object

org.zkoss.poi.xssf.usermodel.XSSFFormulaEvaluator

All Implemented Interfaces:

FormulaEvaluator

public class XSSFFormulaEvaluator
extends Object
implements FormulaEvaluator

Evaluates formula cells.

For performance reasons, this class keeps a cache of all previously calculated intermediate cell values. Be sure to call clearAllCachedResultValues() if any workbook cells are changed between calls to evaluate~ methods on this class.

Author:

Amol S. Deshmukh < amolweb at ya hoo dot com >, Josh Micich

Constructor Summary

Constructors

Constructor and Description
XSSFFormulaEvaluator(XSSFWorkbook workbook)
XSSFFormulaEvaluator(XSSFWorkbook workbook, IStabilityClassifier stabilityClassifier) Deprecated. (Sep 2009) (reduce overloading) use #create(XSSFWorkbook, org.zkoss.poi.ss.formula.IStabilityClassifier, org.zkoss.poi.hssf.record.formula.udf.UDFFinder)

Method Summary

Modifier and Type	Method and Description
void	clearAllCachedResultValues() Should be called whenever there are major changes (e.g.
static XSSFFormulaEvaluator	create(XSSFWorkbook workbook, IStabilityClassifier stabilityClassifier, UDFFinder udfFinder)
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.
void	evaluateAll() Loops over all cells in all sheets of the supplied workbook.
static void	evaluateAllFormulaCells(XSSFWorkbook wb) Loops over all cells in all sheets of the supplied workbook.
CellValue	evaluateFormula(int sheetIndex, String formula, Object ref)
int	evaluateFormulaCell(Cell cell) If cell contains formula, it evaluates the formula, and saves the result of the formula.
ValueEval	evaluateFormulaValueEval(int sheetIndex, String formula, boolean ignoreDereference, Object ref)
XSSFCell	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.
CellValue	getCellValueByValueEval(ValueEval eval)
WorkbookEvaluator	getWorkbookEvaluator()
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
void	notifySetFormula(Cell cell) Should be called to tell the cell value cache that the specified (value or formula) cell has changed.
void	notifyUpdateCell(Cell cell) Should be called to tell the cell value cache that the specified (value or formula) cell has changed.
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).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XSSFFormulaEvaluator

public XSSFFormulaEvaluator(XSSFWorkbook workbook)

XSSFFormulaEvaluator

@Deprecated
public XSSFFormulaEvaluator(XSSFWorkbook workbook,
                                        IStabilityClassifier stabilityClassifier)

Deprecated. (Sep 2009) (reduce overloading) use #create(XSSFWorkbook, org.zkoss.poi.ss.formula.IStabilityClassifier, org.zkoss.poi.hssf.record.formula.udf.UDFFinder)

Parameters:

stabilityClassifier - used to optimise caching performance. Pass null for the (conservative) assumption that any cell may have its definition changed after evaluation begins.

Method Detail

create

public static XSSFFormulaEvaluator create(XSSFWorkbook workbook,
                                          IStabilityClassifier stabilityClassifier,
                                          UDFFinder udfFinder)

Parameters:

stabilityClassifier - used to optimise caching performance. Pass null for the (conservative) assumption that any cell may have its definition changed after evaluation begins.

udfFinder - pass null for default (AnalysisToolPak only)

clearAllCachedResultValues

public void clearAllCachedResultValues()

Should be called whenever there are major changes (e.g. moving sheets) 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

Specified by:

clearAllCachedResultValues in interface FormulaEvaluator

notifySetFormula

public void notifySetFormula(Cell cell)

Description copied from interface: FormulaEvaluator

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

Specified by:

notifySetFormula in interface FormulaEvaluator

notifyDeleteCell

public void notifyDeleteCell(Cell cell)

Description copied from interface: FormulaEvaluator

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

Specified by:

notifyDeleteCell in interface FormulaEvaluator

notifyUpdateCell

public void notifyUpdateCell(Cell cell)

Description copied from interface: FormulaEvaluator

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

Specified by:

notifyUpdateCell 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 -

evaluateFormulaCell

public int 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 evaluate(org.zkoss.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 HSSFCell.CELL_TYPE_FORMULA however)

evaluateInCell

public XSSFCell 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 HSSFCell 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(org.zkoss.poi.ss.usermodel.Cell) }

Specified by:

evaluateInCell in interface FormulaEvaluator

Parameters:

cell -

evaluateAllFormulaCells

public static void evaluateAllFormulaCells(XSSFWorkbook 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.

evaluateAll

public void evaluateAll()

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.

Specified by:

evaluateAll in interface FormulaEvaluator

getWorkbookEvaluator

public WorkbookEvaluator getWorkbookEvaluator()

Specified by:

getWorkbookEvaluator in interface FormulaEvaluator

getCellValueByValueEval

public CellValue getCellValueByValueEval(ValueEval eval)

Specified by:

getCellValueByValueEval in interface FormulaEvaluator

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

evaluateFormula

public CellValue evaluateFormula(int sheetIndex,
                                 String formula,
                                 Object ref)

Specified by:

evaluateFormula in interface FormulaEvaluator

evaluateFormulaValueEval

public ValueEval evaluateFormulaValueEval(int sheetIndex,
                                          String formula,
                                          boolean ignoreDereference,
                                          Object ref)

Specified by:

evaluateFormulaValueEval in interface FormulaEvaluator