Package org.apache.poi.ss.formula

Class DataValidationEvaluator

java.lang.Object

org.apache.poi.ss.formula.DataValidationEvaluator

public class DataValidationEvaluator
extends 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	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	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

Modifier and Type	Method	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.
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 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 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 ValueEvals if applicable, or null

getValidationValuesForConstraint

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

static so enums can reference it without creating a whole instance

Returns:

returns an unmodifiable List of ValueEvals, 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