/* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ==================================================================== */ package org.apache.poi.ss.formula; import java.util.Arrays; import java.util.Collection; import java.util.Collections; import java.util.IdentityHashMap; import java.util.Map; import java.util.Stack; import java.util.TreeSet; import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; import org.apache.logging.log4j.message.SimpleMessage; import org.apache.poi.ss.SpreadsheetVersion; import org.apache.poi.ss.formula.CollaboratingWorkbooksEnvironment.WorkbookNotFoundException; import org.apache.poi.ss.formula.atp.AnalysisToolPak; import org.apache.poi.ss.formula.eval.*; import org.apache.poi.ss.formula.function.FunctionMetadataRegistry; import org.apache.poi.ss.formula.functions.*; import org.apache.poi.ss.formula.ptg.*; import org.apache.poi.ss.formula.udf.AggregatingUDFFinder; import org.apache.poi.ss.formula.udf.UDFFinder; import org.apache.poi.ss.usermodel.CellType; import org.apache.poi.ss.util.CellRangeAddressBase; import org.apache.poi.ss.util.CellReference; import org.apache.poi.util.Internal; import static org.apache.logging.log4j.util.Unbox.box; /** * Evaluates formula cells.
* * For performance reasons, this class keeps a cache of all previously calculated intermediate * cell values. Be sure to call {@link #clearAllCachedResultValues()} if any workbook cells are changed between * calls to evaluate~ methods on this class.null
for default (AnalysisToolPak only)
*/
public WorkbookEvaluator(EvaluationWorkbook workbook, IStabilityClassifier stabilityClassifier, UDFFinder udfFinder) {
this (workbook, null, stabilityClassifier, udfFinder);
}
/* package */ WorkbookEvaluator(EvaluationWorkbook workbook, IEvaluationListener evaluationListener,
IStabilityClassifier stabilityClassifier, UDFFinder udfFinder) {
_workbook = workbook;
_evaluationListener = evaluationListener;
_cache = new EvaluationCache(evaluationListener);
_sheetIndexesBySheet = new IdentityHashMap<>();
_sheetIndexesByName = new IdentityHashMap<>();
_collaboratingWorkbookEnvironment = CollaboratingWorkbooksEnvironment.EMPTY;
_workbookIx = 0;
_stabilityClassifier = stabilityClassifier;
AggregatingUDFFinder defaultToolkit = // workbook can be null in unit tests
workbook == null ? null : (AggregatingUDFFinder)workbook.getUDFFinder();
if(defaultToolkit != null && udfFinder != null) {
defaultToolkit.add(udfFinder);
}
_udfFinder = defaultToolkit;
}
/**
* also for debug use. Used in toString methods
*/
/* package */ String getSheetName(int sheetIndex) {
return _workbook.getSheetName(sheetIndex);
}
/* package */ EvaluationSheet getSheet(int sheetIndex) {
return _workbook.getSheet(sheetIndex);
}
/* package */ EvaluationWorkbook getWorkbook() {
return _workbook;
}
/* package */ EvaluationName getName(String name, int sheetIndex) {
return _workbook.getName(name, sheetIndex);
}
/* package */ void attachToEnvironment(CollaboratingWorkbooksEnvironment collaboratingWorkbooksEnvironment, EvaluationCache cache, int workbookIx) {
_collaboratingWorkbookEnvironment = collaboratingWorkbooksEnvironment;
_cache = cache;
_workbookIx = workbookIx;
}
/* package */ CollaboratingWorkbooksEnvironment getEnvironment() {
return _collaboratingWorkbookEnvironment;
}
/**
* Discards the current workbook environment and attaches to the default 'empty' environment.
* Also resets evaluation cache.
*/
/* package */ void detachFromEnvironment() {
_collaboratingWorkbookEnvironment = CollaboratingWorkbooksEnvironment.EMPTY;
_cache = new EvaluationCache(_evaluationListener);
_workbookIx = 0;
}
/**
* @return the evaluator for another workbook which is part of the same {@link CollaboratingWorkbooksEnvironment}
*/
/* package */ WorkbookEvaluator getOtherWorkbookEvaluator(String workbookName) throws WorkbookNotFoundException {
return _collaboratingWorkbookEnvironment.getWorkbookEvaluator(workbookName);
}
/* package */ IEvaluationListener getEvaluationListener() {
return _evaluationListener;
}
/**
* 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
*/
public void clearAllCachedResultValues() {
_cache.clear();
_sheetIndexesBySheet.clear();
_workbook.clearAllCachedResultValues();
}
/**
* Should be called to tell the cell value cache that the specified (value or formula) cell
* has changed.
*/
public void notifyUpdateCell(EvaluationCell cell) {
int sheetIndex = getSheetIndex(cell.getSheet());
_cache.notifyUpdateCell(_workbookIx, sheetIndex, cell);
}
/**
* Should be called to tell the cell value cache that the specified cell has just been
* deleted.
*/
public void notifyDeleteCell(EvaluationCell cell) {
int sheetIndex = getSheetIndex(cell.getSheet());
_cache.notifyDeleteCell(_workbookIx, sheetIndex, cell);
}
private int getSheetIndex(EvaluationSheet sheet) {
Integer result = _sheetIndexesBySheet.get(sheet);
if (result == null) {
int sheetIndex = _workbook.getSheetIndex(sheet);
if (sheetIndex < 0) {
throw new RuntimeException("Specified sheet from a different book");
}
result = Integer.valueOf(sheetIndex);
_sheetIndexesBySheet.put(sheet, result);
}
return result.intValue();
}
public ValueEval evaluate(EvaluationCell srcCell) {
int sheetIndex = getSheetIndex(srcCell.getSheet());
return evaluateAny(srcCell, sheetIndex, srcCell.getRowIndex(), srcCell.getColumnIndex(), new EvaluationTracker(_cache));
}
/**
* Case-insensitive.
* @return -1 if sheet with specified name does not exist
*/
/* package */ int getSheetIndex(String sheetName) {
Integer result = _sheetIndexesByName.get(sheetName);
if (result == null) {
int sheetIndex = _workbook.getSheetIndex(sheetName);
if (sheetIndex < 0) {
return -1;
}
result = Integer.valueOf(sheetIndex);
_sheetIndexesByName.put(sheetName, result);
}
return result.intValue();
}
/* package */ int getSheetIndexByExternIndex(int externSheetIndex) {
return _workbook.convertFromExternSheetIndex(externSheetIndex);
}
/**
* @return never null
, never {@link BlankEval}
*/
private ValueEval evaluateAny(EvaluationCell srcCell, int sheetIndex,
int rowIndex, int columnIndex, EvaluationTracker tracker) {
// avoid tracking dependencies to cells that have constant definition
boolean shouldCellDependencyBeRecorded = _stabilityClassifier == null ? true
: !_stabilityClassifier.isCellFinal(sheetIndex, rowIndex, columnIndex);
if (srcCell == null || srcCell.getCellType() != CellType.FORMULA) {
ValueEval result = getValueFromNonFormulaCell(srcCell);
if (shouldCellDependencyBeRecorded) {
tracker.acceptPlainValueDependency(_workbook, _workbookIx, sheetIndex, rowIndex, columnIndex, result);
}
return result;
}
FormulaCellCacheEntry cce = _cache.getOrCreateFormulaCellEntry(srcCell);
if (shouldCellDependencyBeRecorded || cce.isInputSensitive()) {
tracker.acceptFormulaDependency(cce);
}
IEvaluationListener evalListener = _evaluationListener;
ValueEval result;
if (cce.getValue() == null) {
if (!tracker.startEvaluate(cce)) {
return ErrorEval.CIRCULAR_REF_ERROR;
}
try {
Ptg[] ptgs = _workbook.getFormulaTokens(srcCell);
OperationEvaluationContext ec = new OperationEvaluationContext
(this, _workbook, sheetIndex, rowIndex, columnIndex, tracker);
if (evalListener == null) {
result = evaluateFormula(ec, ptgs);
} else {
evalListener.onStartEvaluate(srcCell, cce);
result = evaluateFormula(ec, ptgs);
evalListener.onEndEvaluate(cce, result);
}
tracker.updateCacheResult(result);
}
catch (NotImplementedException e) {
throw addExceptionInfo(e, sheetIndex, rowIndex, columnIndex);
} catch (RuntimeException re) {
if (re.getCause() instanceof WorkbookNotFoundException && _ignoreMissingWorkbooks) {
LOG.atInfo().log("{} - Continuing with cached value!", re.getCause().getMessage());
switch(srcCell.getCachedFormulaResultType()) {
case NUMERIC:
result = new NumberEval(srcCell.getNumericCellValue());
break;
case STRING:
result = new StringEval(srcCell.getStringCellValue());
break;
case BLANK:
result = BlankEval.instance;
break;
case BOOLEAN:
result = BoolEval.valueOf(srcCell.getBooleanCellValue());
break;
case ERROR:
result = ErrorEval.valueOf(srcCell.getErrorCellValue());
break;
case FORMULA:
default:
throw new RuntimeException("Unexpected cell type '" + srcCell.getCellType()+"' found!");
}
} else {
throw re;
}
} finally {
tracker.endEvaluate(cce);
}
} else {
if(evalListener != null) {
evalListener.onCacheHit(sheetIndex, rowIndex, columnIndex, cce.getValue());
}
return cce.getValue();
}
final ValueEval resultForLogging = result;
LOG.atDebug().log(()->{
String sheetName = getSheetName(sheetIndex);
CellReference cr = new CellReference(rowIndex, columnIndex);
return new SimpleMessage("Evaluated " + sheetName + "!" + cr.formatAsString() + " to " + resultForLogging);
});
// Usually (result === cce.getValue())
// But sometimes: (result==ErrorEval.CIRCULAR_REF_ERROR, cce.getValue()==null)
// When circular references are detected, the cache entry is only updated for
// the top evaluation frame
return result;
}
/**
* Adds the current cell reference to the exception for easier debugging.
* Would be nice to get the formula text as well, but that seems to require
* too much digging around and casting to get the FormulaRenderingWorkbook.
*/
private NotImplementedException addExceptionInfo(NotImplementedException inner, int sheetIndex, int rowIndex, int columnIndex) {
try {
String sheetName = _workbook.getSheetName(sheetIndex);
CellReference cr = new CellReference(sheetName, rowIndex, columnIndex, false, false);
String msg = "Error evaluating cell " + cr.formatAsString();
return new NotImplementedException(msg, inner);
} catch (Exception e) {
// avoid bombing out during exception handling
LOG.atError().withThrowable(e).log("Can't add exception info");
return inner; // preserve original exception
}
}
/**
* Gets the value from a non-formula cell.
* @param cell may be null
* @return {@link BlankEval} if cell is null
or blank, never null
*/
/* package */ static ValueEval getValueFromNonFormulaCell(EvaluationCell cell) {
if (cell == null) {
return BlankEval.instance;
}
CellType cellType = cell.getCellType();
switch (cellType) {
case NUMERIC:
return new NumberEval(cell.getNumericCellValue());
case STRING:
return new StringEval(cell.getStringCellValue());
case BOOLEAN:
return BoolEval.valueOf(cell.getBooleanCellValue());
case BLANK:
return BlankEval.instance;
case ERROR:
return ErrorEval.valueOf(cell.getErrorCellValue());
default:
throw new RuntimeException("Unexpected cell type (" + cellType + ")");
}
}
// visibility raised for testing
@Internal
/* package */ ValueEval evaluateFormula(OperationEvaluationContext ec, Ptg[] ptgs) {
String dbgIndentStr = ""; // always init. to non-null just for defensive avoiding NPE
if (dbgEvaluationOutputForNextEval) {
// first evaluation call when ouput is desired, so iit. this evaluator instance
dbgEvaluationOutputIndent = 1;
dbgEvaluationOutputForNextEval = false;
}
if (dbgEvaluationOutputIndent > 0) {
// init. indent string to needed spaces (create as substring from very long space-only string;
// limit indentation for deep recursions)
dbgIndentStr = " ";
dbgIndentStr = dbgIndentStr.substring(0, Math.min(dbgIndentStr.length(), dbgEvaluationOutputIndent*2));
String finalDbgIndentStr = dbgIndentStr;
EVAL_LOG.atWarn().log(() -> {
String message = finalDbgIndentStr
+ "- evaluateFormula('" + ec.getRefEvaluatorForCurrentSheet().getSheetNameRange()
+ "'/" + new CellReference(ec.getRowIndex(), ec.getColumnIndex()).formatAsString()
+ "): " + Arrays.toString(ptgs).replaceAll("\\Qorg.apache.poi.ss.formula.ptg.\\E", "");
return new SimpleMessage(message);
});
dbgEvaluationOutputIndent++;
}
EvaluationSheet evalSheet = ec.getWorkbook().getSheet(ec.getSheetIndex());
EvaluationCell evalCell = evalSheet.getCell(ec.getRowIndex(), ec.getColumnIndex());
Stacknull
. {@link BlankEval} is
* converted to {@link NumberEval#ZERO}
*/
private static ValueEval dereferenceResult(ValueEval evaluationResult, OperationEvaluationContext ec) {
ValueEval value;
if (ec == null) {
throw new IllegalArgumentException("OperationEvaluationContext ec is null");
}
if (ec.getWorkbook() == null) {
throw new IllegalArgumentException("OperationEvaluationContext ec.getWorkbook() is null");
}
EvaluationSheet evalSheet = ec.getWorkbook().getSheet(ec.getSheetIndex());
EvaluationCell evalCell = evalSheet.getCell(ec.getRowIndex(), ec.getColumnIndex());
if (evalCell != null && evalCell.isPartOfArrayFormulaGroup() && evaluationResult instanceof AreaEval) {
value = OperandResolver.getElementFromArray((AreaEval) evaluationResult, evalCell);
}
else {
value = dereferenceResult(evaluationResult, ec.getRowIndex(), ec.getColumnIndex());
}
if (value == BlankEval.instance) {
// Note Excel behaviour here. A blank final final value is converted to zero.
return NumberEval.ZERO;
// Formulas _never_ evaluate to blank. If a formula appears to have evaluated to
// blank, the actual value is empty string. This can be verified with ISBLANK().
}
return value;
}
/**
* Dereferences a single value from any AreaEval or RefEval evaluation
* result. If the supplied evaluationResult is just a plain value, it is
* returned as-is.
*
* @return a {@link NumberEval}, {@link StringEval}, {@link BoolEval}, or
* {@link ErrorEval}. Never null
. {@link BlankEval} is
* converted to {@link NumberEval#ZERO}
*/
public static ValueEval dereferenceResult(ValueEval evaluationResult, int srcRowNum, int srcColNum) {
ValueEval value;
try {
value = OperandResolver.getSingleValue(evaluationResult, srcRowNum, srcColNum);
} catch (EvaluationException e) {
return e.getErrorEval();
}
if (value == BlankEval.instance) {
// Note Excel behaviour here. A blank final final value is converted to zero.
return NumberEval.ZERO;
// Formulas _never_ evaluate to blank. If a formula appears to have evaluated to
// blank, the actual value is empty string. This can be verified with ISBLANK().
}
return value;
}
/**
* returns an appropriate Eval impl instance for the Ptg. The Ptg must be
* one of: Area3DPtg, AreaPtg, ReferencePtg, Ref3DPtg, IntPtg, NumberPtg,
* StringPtg, BoolPtg * Returns a single value e.g. a cell formula result or boolean value for conditional formatting. * * @param formula The formula to evaluate * @param target cell context for the operation * @param region containing the cell * @return value * @throws IllegalArgumentException if target does not define a sheet name to evaluate the formula on. */ public ValueEval evaluate(String formula, CellReference target, CellRangeAddressBase region) { return evaluate(formula, target, region, FormulaType.CELL); } /** * Some expressions need to be evaluated in terms of an offset from the top left corner of a region, * such as some data validation and conditional format expressions, when those constraints apply * to contiguous cells. When a relative formula is used, it must be evaluated by shifting by the target * offset position relative to the top left of the range. *
* Returns a ValueEval that may be one or more values, such as the allowed values for a data validation constraint. * * @param formula The formula to evaluate * @param target cell context for the operation * @param region containing the cell * @return ValueEval for one or more values * @throws IllegalArgumentException if target does not define a sheet name to evaluate the formula on. */ public ValueEval evaluateList(String formula, CellReference target, CellRangeAddressBase region) { return evaluate(formula, target, region, FormulaType.DATAVALIDATION_LIST); } private ValueEval evaluate(String formula, CellReference target, CellRangeAddressBase region, FormulaType formulaType) { final String sheetName = target == null ? null : target.getSheetName(); if (sheetName == null) throw new IllegalArgumentException("Sheet name is required"); final int sheetIndex = getWorkbook().getSheetIndex(sheetName); Ptg[] ptgs = FormulaParser.parse(formula, (FormulaParsingWorkbook) getWorkbook(), formulaType, sheetIndex, target.getRow()); adjustRegionRelativeReference(ptgs, target, region); final OperationEvaluationContext ec = new OperationEvaluationContext(this, getWorkbook(), sheetIndex, target.getRow(), target.getCol(), new EvaluationTracker(_cache), formulaType.isSingleValue()); return evaluateNameFormula(ptgs, ec); } /** * Adjust formula relative references by the offset between the start of the given region and the given target cell. * That is, treat the region top-left cell as "A1" for the purposes of evaluating relative reference components (row and/or column), * and further move references by the position of the target within the region. *
formula ref + range top-left + current cell range offset* which simplifies to *
formula ref + current cell ref* @param ptgs * @param target cell within the region to use. * @param region containing the cell, OR, for conditional format rules with multiple ranges, the region with the top-left-most cell * @return true if any Ptg references were shifted * @throws IndexOutOfBoundsException if the resulting shifted row/column indexes are over the document format limits * @throws IllegalArgumentException if target is not within region. */ protected boolean adjustRegionRelativeReference(Ptg[] ptgs, CellReference target, CellRangeAddressBase region) { // region may not be the one that contains the target, if a conditional formatting rule applies to multiple regions int deltaRow = target.getRow() - region.getFirstRow(); int deltaColumn = target.getCol() - region.getFirstColumn(); boolean shifted = false; for (Ptg ptg : ptgs) { // base class for cell reference "things" if (ptg instanceof RefPtgBase) { RefPtgBase ref = (RefPtgBase) ptg; // re-calculate cell references final SpreadsheetVersion version = _workbook.getSpreadsheetVersion(); if (ref.isRowRelative() && deltaRow > 0) { final int rowIndex = ref.getRow() + deltaRow; if (rowIndex > version.getMaxRows()) { throw new IndexOutOfBoundsException(version.name() + " files can only have " + version.getMaxRows() + " rows, but row " + rowIndex + " was requested."); } ref.setRow(rowIndex); shifted = true; } if (ref.isColRelative() && deltaColumn > 0) { final int colIndex = ref.getColumn() + deltaColumn; if (colIndex > version.getMaxColumns()) { throw new IndexOutOfBoundsException(version.name() + " files can only have " + version.getMaxColumns() + " columns, but column " + colIndex + " was requested."); } ref.setColumn(colIndex); shifted = true; } } } return shifted; } /** * 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: *