From 881015618a7932edb37bc85af116c0dcf75e080f Mon Sep 17 00:00:00 2001
From: Greg Woolsey <gwoolsey@apache.org>
Date: Wed, 18 Apr 2018 18:25:08 +0000
Subject: [PATCH] add some javadoc to warn that stale cached formula cell
 values may result in incorrect evaluations, and what to do about it (evaluate
 formula cells before asking the rule if it applies).

Doing it for the user turns out to not be that easy, as the FormulaEvaluator instance in use is not known in this context.

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1829471 13f79535-47bb-0310-9956-ffa450edef68
---
 .../ss/formula/ConditionalFormattingEvaluator.java    | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/java/org/apache/poi/ss/formula/ConditionalFormattingEvaluator.java b/src/java/org/apache/poi/ss/formula/ConditionalFormattingEvaluator.java
index e50da917b0..269b8f292a 100644
--- a/src/java/org/apache/poi/ss/formula/ConditionalFormattingEvaluator.java
+++ b/src/java/org/apache/poi/ss/formula/ConditionalFormattingEvaluator.java
@@ -26,6 +26,7 @@ import java.util.Map;
 import org.apache.poi.ss.usermodel.Cell;
 import org.apache.poi.ss.usermodel.ConditionalFormatting;
 import org.apache.poi.ss.usermodel.ConditionalFormattingRule;
+import org.apache.poi.ss.usermodel.FormulaEvaluator;
 import org.apache.poi.ss.usermodel.Row;
 import org.apache.poi.ss.usermodel.Sheet;
 import org.apache.poi.ss.usermodel.SheetConditionalFormatting;
@@ -142,6 +143,11 @@ public class ConditionalFormattingEvaluator {
      * Note that to properly apply conditional rules, care must be taken to offset the base 
      * formula by the relative position of the current cell, or the wrong value is checked.
      * This is handled by {@link WorkbookEvaluator#evaluate(String, CellReference, CellRangeAddressBase)}.
+     * <p>
+     * If the cell exists and is a formula cell, its cached value may be used for rule evaluation, so
+     * make sure it is up to date.  If values have changed, it is best to call 
+     * {@link FormulaEvaluator#evaluateFormulaCell(Cell)} or {@link FormulaEvaluator#evaluateAll()} first,
+     * or the wrong conditional results may be returned. 
      * 
      * @param cellRef NOTE: if no sheet name is specified, this uses the workbook active sheet
      * @return Unmodifiable List of {@link EvaluationConditionalFormatRule}s that apply to the current cell value,
@@ -198,6 +204,11 @@ public class ConditionalFormattingEvaluator {
      * Note that to properly apply conditional rules, care must be taken to offset the base 
      * formula by the relative position of the current cell, or the wrong value is checked.
      * This is handled by {@link WorkbookEvaluator#evaluate(String, CellReference, CellRangeAddressBase)}.
+     * <p>
+     * If the cell exists and is a formula cell, its cached value may be used for rule evaluation, so
+     * make sure it is up to date.  If values have changed, it is best to call 
+     * {@link FormulaEvaluator#evaluateFormulaCell(Cell)} or {@link FormulaEvaluator#evaluateAll()} first,
+     * or the wrong conditional results may be returned. 
      * 
      * @param cell The cell to look for
      * @return Unmodifiable List of {@link EvaluationConditionalFormatRule}s that apply to the current cell value,
-- 
2.39.5