org.apache.poi.ss.formula

## Class DataValidationEvaluator

- java.lang.Object
- - org.apache.poi.ss.formula.DataValidationEvaluator

-     public class DataValidationEvaluator
      extends java.lang.Object

  Evaluates Data Validation constraints.

  For performance reasons, this class keeps a cache of all previously retrieved `DataValidation` instances. Be sure to call `clearAllCachedValues()` if any workbook validation definitions are added, modified, or deleted.

  Changing cell values should be fine, as long as the corresponding `WorkbookEvaluator.clearAllCachedResultValues()` is called as well.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DataValidationEvaluator.DataValidationContext` This class organizes and encapsulates all the pieces of information related to a single data validation configuration for a single cell.
    `static class` | `DataValidationEvaluator.OperatorEnum` Not calling it OperatorType to avoid confusion for now with DataValidationConstraint.OperatorType.
    `static class` | `DataValidationEvaluator.ValidationEnum` Not calling it ValidationType to avoid confusion for now with DataValidationConstraint.ValidationType.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataValidationEvaluator(Workbook wb, WorkbookEvaluatorProvider provider)` Use the same formula evaluation context used for other operations, so cell value changes are automatically noticed

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearAllCachedValues()` Call this whenever validation structures change, so future results stay in sync with the Workbook state.
    `DataValidationEvaluator.DataValidationContext` | `getValidationContextForCell(CellReference cell)` Finds and returns the `DataValidationEvaluator.DataValidationContext` for the cell, if there is one.
    `DataValidation` | `getValidationForCell(CellReference cell)` Finds and returns the `DataValidation` for the cell, if there is one.
    `java.util.List<ValueEval>` | `getValidationValuesForCell(CellReference cell)` If `getValidationForCell(CellReference)` returns an instance, and the `DataValidationConstraint.ValidationType` is `DataValidationConstraint.ValidationType.LIST`, return the valid values, whether they are from a static list or cell range.
    `protected static java.util.List<ValueEval>` | `getValidationValuesForConstraint(DataValidationEvaluator.DataValidationContext context)` static so enums can reference it without creating a whole instance
    `protected WorkbookEvaluator` | `getWorkbookEvaluator()`
    `static boolean` | `isType(Cell cell, CellType type)` Note that this assumes the cell cached value is up to date and in sync with data edits
    `boolean` | `isValidCell(CellReference cellRef)` Use the validation returned by `getValidationForCell(CellReference)` if you want the error display details.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DataValidationEvaluator

          public DataValidationEvaluator(Workbook wb,
                                         WorkbookEvaluatorProvider provider)

      Use the same formula evaluation context used for other operations, so cell value changes are automatically noticed
      Parameters:
        `wb` - the workbook this operates on
        `provider` - provider for formula evaluation

  - ### Method Detail

    - #### getWorkbookEvaluator

          protected WorkbookEvaluator getWorkbookEvaluator()

      Returns:
        evaluator

    - #### clearAllCachedValues

          public void clearAllCachedValues()

      Call this whenever validation structures change, so future results stay in sync with the Workbook state.

    - #### getValidationForCell

          public DataValidation getValidationForCell(CellReference cell)

      Finds and returns the `DataValidation` for the cell, if there is one. Lookup is based on the first match from `DataValidation.getRegions()` for the cell's sheet. DataValidation regions must be in the same sheet as the DataValidation. Allowed values expressions may reference other sheets, however.
      Parameters:
        `cell` - reference to check - use this in case the cell does not actually exist yet
      Returns:
        the DataValidation applicable to the given cell, or null if no validation applies

    - #### getValidationContextForCell

          public DataValidationEvaluator.DataValidationContext getValidationContextForCell(CellReference cell)

      Finds and returns the `DataValidationEvaluator.DataValidationContext` for the cell, if there is one. Lookup is based on the first match from `DataValidation.getRegions()` for the cell's sheet. DataValidation regions must be in the same sheet as the DataValidation. Allowed values expressions may reference other sheets, however.
      Parameters:
        `cell` - reference to check
      Returns:
        the DataValidationContext applicable to the given cell, or null if no validation applies

    - #### getValidationValuesForCell

          public java.util.List<ValueEval> getValidationValuesForCell(CellReference cell)

      If `getValidationForCell(CellReference)` returns an instance, and the `DataValidationConstraint.ValidationType` is `DataValidationConstraint.ValidationType.LIST`, return the valid values, whether they are from a static list or cell range.

      For all other validation types, or no validation at all, this method returns null.

      This method could throw an exception if the validation type is not LIST, but since this method is mostly useful in UI contexts, null seems the easier path.

      Parameters:
        `cell` - reference to check - use this in case the cell does not actually exist yet
      Returns:
        returns an unmodifiable `List` of `ValueEval`s if applicable, or null

    - #### getValidationValuesForConstraint

          protected static java.util.List<ValueEval> getValidationValuesForConstraint(DataValidationEvaluator.DataValidationContext context)

      static so enums can reference it without creating a whole instance
      Returns:
        returns an unmodifiable `List` of `ValueEval`s, which may be empty

    - #### isValidCell

          public boolean isValidCell(CellReference cellRef)

      Use the validation returned by `getValidationForCell(CellReference)` if you want the error display details. This is the validation checked by this method, which attempts to replicate Excel's data validation rules.

      Note that to properly apply some validations, care must be taken to offset the base validation formula by the relative position of the current cell, or the wrong value is checked.

      Parameters:
        `cellRef` - The reference of the cell to evaluate
      Returns:
        true if the cell has no validation or the cell value passes the defined validation, false if it fails

    - #### isType

          public static boolean isType(Cell cell,
                                       CellType type)

      Note that this assumes the cell cached value is up to date and in sync with data edits
      Parameters:
        `cell` - The `Cell` to check.
        `type` - The `CellType` to check for.
      Returns:
        true if the cell or cached cell formula result type match the given type

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