Package com.isomorphic.criteria

# Class Evaluator

java.lang.Object
com.isomorphic.criteria.Evaluator

public class Evaluator extends Object
Helper class for evaluating criteria.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Evaluator(Object criteria, String textMatchStyle, com.isomorphic.criteria.SubqueryResolver resolver)`
  Constructor that also accepts a SubqueryResolver, enabling automatic resolution of fieldQuery/valueQuery criteria elements during evaluation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addSearchOperator(Operator op)`
  Adding custom operator for using in evaluations.
  `boolean`
  `evaluateCriterion(Map values, Criterion criterion)`
  Evaluating criterion with map of values.
  `List<Map>`
  `filterRecords(List<Map> records)`
  Filters a list of records using the criteria provided to this Evaluator.
  `List<Map>`
  `filterRecords(List<Map> records, BasicDataSource parentDS)`
  Filters a list of records using the criteria provided to this Evaluator, automatically creating a DSRequestSubqueryResolver if the criteria contain fieldQuery/valueQuery elements and no SubqueryResolver has been set.
  `static Object`
  `getPathValue(Map values, String fieldPath)`
  Fetches the value stored at the given dot notation path in the map of values.
  `static String`
  `getPathValueAsString(Map values, String fieldPath)`
  Fetches the value stored at the given dot notation path in the map of values as a string.
  `static AdvancedCriteria`
  `parseAdvancedCriteria(Map rawCriteria)`
  Builds an `AdvancedCriteria` instance from a structure expressing `AdvancedCriteria` as simple Java Collections, that is, nested `Maps` and `Lists` where a `Criterion` is expressed as a `Map` containing keys such as "fieldName", "operator", and "value".
  `static Criterion`
  `parseCriterion(Map rawCriteria)`
  Parse criterion represented as map (usually passed from client-side) into Criterion instance.
  `void`
  `setSubqueryResolver(com.isomorphic.criteria.SubqueryResolver resolver)`
  Sets a SubqueryResolver on this Evaluator, enabling automatic resolution of fieldQuery/valueQuery elements during evaluation.
  `boolean`
  `valuesMatchCriteria(Map values, AdvancedCriteria ac)`
  Check values map for matching passed AdvancedCriteria.
  `boolean`
  `valuesMatchCriteria(Map values, SimpleCriteria sc, String textMatchStyle)`
  Check values map for matching passed Criteria.

- ## Constructor Details

  - ### Evaluator

    public Evaluator(Object criteria, String textMatchStyle, com.isomorphic.criteria.SubqueryResolver resolver)
    Constructor that also accepts a SubqueryResolver, enabling automatic resolution of fieldQuery/valueQuery criteria elements during evaluation. Without a resolver, criteria containing subqueries will throw an Exception.
    Parameters:
      `criteria` - the criteria to evaluate (AdvancedCriteria, Criterion, SimpleCriteria, or Map)
      `textMatchStyle` - the textMatchStyle (only relevant for SimpleCriteria)
      `resolver` - a SubqueryResolver for resolving fieldQuery/valueQuery elements

- ## Method Details

  - ### setSubqueryResolver

    public void setSubqueryResolver(com.isomorphic.criteria.SubqueryResolver resolver)
    Sets a SubqueryResolver on this Evaluator, enabling automatic resolution of fieldQuery/valueQuery elements during evaluation.
    Parameters:
      `resolver` - the SubqueryResolver to use

  - ### addSearchOperator

    public void addSearchOperator(Operator op)
    Adding custom operator for using in evaluations.
    Parameters:
      `op` - - operator to be added.

  - ### valuesMatchCriteria

    public boolean valuesMatchCriteria(Map values, SimpleCriteria sc, String textMatchStyle) throws Exception
    Check values map for matching passed Criteria.
    Parameters:
      `values` - - map of values to check.
      `sc` - - criteria to check.
      `textMatchStyle` - - style to be used when checking.
    Returns:
      true if values match criteria.
    Throws:
      `Exception` - if an error occurs during criteria evaluation

  - ### valuesMatchCriteria

    public boolean valuesMatchCriteria(Map values, AdvancedCriteria ac) throws Exception
    Check values map for matching passed AdvancedCriteria.
    Parameters:
      `values` - - map of values to check.
      `ac` - - AdvancedCriteria to check.
    Returns:
      true if values match AdvancedCriteria.
    Throws:
      `Exception` - if an error occurs during criteria evaluation

  - ### evaluateCriterion

    public boolean evaluateCriterion(Map values, Criterion criterion) throws Exception
    Evaluating criterion with map of values. The method check that passed criterion match passed values.
    Parameters:
      `values` - - map of values to check.
      `criterion` - - criterion to check.
    Returns:
      true if values match Criterion.
    Throws:
      `Exception` - if an error occurs during criterion evaluation

  - ### parseAdvancedCriteria

    public static AdvancedCriteria parseAdvancedCriteria(Map rawCriteria)
    Builds an `AdvancedCriteria` instance from a structure expressing `AdvancedCriteria` as simple Java Collections, that is, nested `Maps` and `Lists` where a `Criterion` is expressed as a `Map` containing keys such as "fieldName", "operator", and "value".

    For all built-in operators (see `DefaultOperators`), instances of the most specific `Criterion` class available will be created. Custom operators passed to `addSearchOperator(Operator)` with a `criterionClass` specified will create an instance of that `criterionClass` and apply the key/value pairs found in the `Map` specifying the criterion via `DataTools.setProperties(Map, Object)`.

    For unrecoginized operators, an instance of `CustomCriterion` will be created and populated with values from the `Map` specifying the `Criterion`.

    Parameters:
      `rawCriteria` - map representation of the criteria to parse
    Returns:
      parsed AdvancedCriteria instance

  - ### parseCriterion

    public static Criterion parseCriterion(Map rawCriteria)
    Parse criterion represented as map (usually passed from client-side) into Criterion instance.
    Parameters:
      `rawCriteria` - - criterion represented as map.
    Returns:
      parsed criterion.

  - ### filterRecords

    public List<Map> filterRecords(List<Map> records) throws Exception
    Filters a list of records using the criteria provided to this Evaluator.

    If a SubqueryResolver was provided (via constructor or setSubqueryResolver()), any fieldQuery/valueQuery elements in the criteria will be resolved automatically before filtering begins. This is the preferred API for filtering records with criteria that may contain subqueries.

    Subqueries are resolved once before filtering begins, rather than per-record, making this method efficient for filtering large record sets.

    Parameters:
      `records` - the list of records to filter
    Returns:
      a new list containing only records that match the criteria
    Throws:
      `Exception` - if an error occurs during evaluation or subquery resolution

  - ### filterRecords

    public List<Map> filterRecords(List<Map> records, BasicDataSource parentDS) throws Exception
    Filters a list of records using the criteria provided to this Evaluator, automatically creating a DSRequestSubqueryResolver if the criteria contain fieldQuery/valueQuery elements and no SubqueryResolver has been set.

    This is a convenience overload for standalone (non-DSRequest) usage where subquery resolution should happen via DSRequest execution. The parentDS is used by the resolver to discover FK relations between the subquery DataSource and the main DataSource.

    Subqueries are resolved once before filtering begins, rather than per-record, making this method efficient for filtering large record sets.

    Parameters:
      `records` - the list of records to filter
      `parentDS` - the DataSource that owns the criteria (used for FK relation discovery)
    Returns:
      a new list containing only records that match the criteria
    Throws:
      `Exception` - if an error occurs during evaluation or subquery resolution

  - ### getPathValue

    public static Object getPathValue(Map values, String fieldPath)
    Fetches the value stored at the given dot notation path in the map of values.
    Parameters:
      `values` - the map of values to look through.
      `fieldPath` - the dot notation path to look up.
    Returns:
      the value stored at the given path.

  - ### getPathValueAsString

    public static String getPathValueAsString(Map values, String fieldPath)
    Fetches the value stored at the given dot notation path in the map of values as a string.
    Parameters:
      `values` - the map of values to look through.
      `fieldPath` - the dot notation path to look up.
    Returns:
      the value stored at the given path or empty string if the value was null.