org.apache.poi.hssf.usermodel
Class HSSFFormulaEvaluator

java.lang.Object
  extended by org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator

public class HSSFFormulaEvaluator
extends java.lang.Object

Evaluates formula cells.

For performance reasons, this class keeps a cache of all previously calculated intermediate cell values. Be sure to call #clearCache() 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

Nested Class Summary
static class HSSFFormulaEvaluator.CellValue
          Mimics the 'data view' of a cell.
 
Constructor Summary
HSSFFormulaEvaluator(HSSFSheet sheet, HSSFWorkbook workbook)
          Deprecated. (Sep 2008) HSSFSheet parameter is ignored
HSSFFormulaEvaluator(HSSFWorkbook workbook)
           
 
Method Summary
 void clearAllCachedResultValues()
          Should be called whenever there are major changes (e.g.
 HSSFFormulaEvaluator.CellValue evaluate(HSSFCell 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(HSSFWorkbook wb)
          Loops over all cells in all sheets of the supplied workbook.
 int evaluateFormulaCell(HSSFCell cell)
          If cell contains formula, it evaluates the formula, and saves the result of the formula.
 HSSFCell evaluateInCell(HSSFCell 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 notifyDeleteCell(HSSFCell cell)
          Should be called to tell the cell value cache that the specified cell has just been deleted.
 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
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)
Method Detail

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


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


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


evaluate

public HSSFFormulaEvaluator.CellValue evaluate(HSSFCell 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 - 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(HSSFCell 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(HSSFCell)

Parameters:
cell - The cell to evaluate
Returns:
-1 for non-formula cells, or the type of the formula result

evaluateInCell

public HSSFCell evaluateInCell(HSSFCell 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(HSSFCell)

Parameters:
cell -

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.



Copyright 2008 The Apache Software Foundation or its licensors, as applicable.