HSSFFormulaEvaluator (zss 3.9.3 API)

java.lang.Object
- org.zkoss.poi.hssf.usermodel.HSSFFormulaEvaluator

All Implemented Interfaces:

FormulaEvaluator
```
public class HSSFFormulaEvaluator
extends java.lang.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, henrichen@zkoss.org: handle HYPERLINK function

Constructor Summary

Constructors
Constructor and Description
`HSSFFormulaEvaluator(HSSFSheet sheet, HSSFWorkbook workbook)` Deprecated. (Sep 2008) HSSFSheet parameter is ignored
`HSSFFormulaEvaluator(HSSFWorkbook workbook)`
`HSSFFormulaEvaluator(HSSFWorkbook workbook, IStabilityClassifier stabilityClassifier)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`clearAllCachedResultValues()` Should be called whenever there are major changes (e.g. moving sheets) to input cells in the evaluated workbook.
`static HSSFFormulaEvaluator`	`create(HSSFWorkbook 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(HSSFWorkbook wb)` Loops over all cells in all sheets of the supplied workbook.
`static void`	`evaluateAllFormulaCells(Workbook wb)` Loops over all cells in all sheets of the supplied workbook.
`CellValue`	`evaluateFormula(int sheetIndex, java.lang.String formula, java.lang.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, java.lang.String formula, boolean ignoreDereference, java.lang.Object ref)`
`HSSFCell`	`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`	`notifyDeleteCell(HSSFCell cell)` Should be called to tell the cell value cache that the specified cell has just been deleted.
`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`	`notifyUpdateCell(HSSFCell cell)` Should be called to tell the cell value cache that the specified (value or formula) cell has changed.
`void`	`setCurrentRow(HSSFRow row)` Deprecated. (Aug 2008) - not needed, since the current row can be derived from the cell
`void`	`setDebugEvaluationOutputForNextEval(boolean value)` Perform detailed output of formula evaluation for next evaluation only?
`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, HSSFFormulaEvaluator[] evaluators)` Coordinates several formula evaluators together so that formulas that involve external references can be evaluated.

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

- Constructor Detail
  - HSSFFormulaEvaluator
```
public HSSFFormulaEvaluator(HSSFSheet sheet,
                            HSSFWorkbook workbook)
```
    Deprecated. (Sep 2008) HSSFSheet parameter is ignored
  - HSSFFormulaEvaluator
```
public HSSFFormulaEvaluator(HSSFWorkbook workbook)
```
  - HSSFFormulaEvaluator
```
public HSSFFormulaEvaluator(HSSFWorkbook workbook,
                            IStabilityClassifier stabilityClassifier)
```
    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 HSSFFormulaEvaluator create(HSSFWorkbook 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)
  - setupEnvironment
```
public static void setupEnvironment(java.lang.String[] workbookNames,
                                    HSSFFormulaEvaluator[] 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.
  - setCurrentRow
```
public void setCurrentRow(HSSFRow row)
```
    Deprecated. (Aug 2008) - not needed, since the current row can be derived from the cell
    
    Does nothing
  - 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
  - notifyUpdateCell
```
public void notifyUpdateCell(HSSFCell 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
```
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
  - notifyDeleteCell
```
public void notifyDeleteCell(HSSFCell cell)
```
    Should be called to tell the cell value cache that the specified cell has just been deleted. Failure to call this method after changing cell values will cause incorrect behaviour of the evaluate~ methods of this class
  - 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
  - notifySetFormula
```
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
    
    Specified by:
    
    notifySetFormula 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
  - 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. If the cell does not contain formula, this method returns -1 and leaves the cell unchanged. Note that the type of the formula result is returned, so you know what kind of cached formula result 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(org.zkoss.poi.ss.usermodel.Cell)
    Specified by:
    
    evaluateFormulaCell in interface FormulaEvaluator
    
    Parameters:
    
    cell - The cell to evaluate
    
    Returns:
    
    -1 for non-formula cells, or the type of the formula result
  - evaluateInCell
```
public HSSFCell 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(Cell)}
    Specified by:
    
    evaluateInCell in interface FormulaEvaluator
  - evaluateAllFormulaCells
```
public static void evaluateAllFormulaCells(HSSFWorkbook 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
```
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.
  - 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
  - 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 exetrnal workbooks referenced by formulas in the main workbook are not avaiable. 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
    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
  - evaluateFormula
```
public CellValue evaluateFormula(int sheetIndex,
                                 java.lang.String formula,
                                 java.lang.Object ref)
```
    Specified by:
    
    evaluateFormula in interface FormulaEvaluator
  - evaluateFormulaValueEval
```
public ValueEval evaluateFormulaValueEval(int sheetIndex,
                                          java.lang.String formula,
                                          boolean ignoreDereference,
                                          java.lang.Object ref)
```
    Specified by:
    
    evaluateFormulaValueEval in interface FormulaEvaluator

Class HSSFFormulaEvaluator

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

HSSFFormulaEvaluator

HSSFFormulaEvaluator

HSSFFormulaEvaluator

Method Detail

create

setupEnvironment

setCurrentRow

clearAllCachedResultValues

notifyUpdateCell

notifyUpdateCell

notifyDeleteCell

notifyDeleteCell

notifySetFormula

evaluate

evaluateFormulaCell

evaluateInCell

evaluateAllFormulaCells

evaluateAllFormulaCells

evaluateAll

getWorkbookEvaluator

getCellValueByValueEval

setIgnoreMissingWorkbooks

setDebugEvaluationOutputForNextEval

evaluateFormula

evaluateFormulaValueEval