Package com.smartgwt.client.docs.serverds

# Class Criterion

java.lang.Object
com.smartgwt.client.docs.serverds.Criterion

public class Criterion extends Object
An object representing a criterion to apply to a record.

This class is not meant to be created and used, it is actually documentation of settings allowed in a DataSource descriptor (.ds.xml file), for use with Smart GWT Pro Edition and above. See `com.smartgwt.client.docs.serverds` for how to use this documentation.

A criterion is part of the definition of an `AdvancedCriteria` object, which is used to filter records according to search criteria.

A criterion consists of an `operator` and typically a `fieldName` from a `Record` and a `value` to compare to. However some operators either don't require a value (eg, isNull) or act on other criteria rather than directly on a `Record`'s fields (eg, the "and" and "or" logical operators). Also, it is possible to specify a `fieldQuery` instead of a `fieldName` and/or a `valueQuery` instead of a `value`

A shortcut form is also allowed where only `fieldName` and `value` values are provided. In this case the `operator` is assumed to be "equals".

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `Criterion[]`
  `criteria`
  For a criterion with an operator that acts on other criteria (eg "and", "or"), a list of sub-criteria that are grouped together by the operator.
  `Object`
  `end`
  End value of a criterion with an operator of type `"valueRange"`.
  `String`
  `fieldName`
  Name of the field in each `Record` that this criterion applies to.
  `AdvancedCriterionSubquery`
  `fieldQuery`
  A subquery to use instead of a `fieldName`.
  `Object`
  `fieldStaticValue`
  A constant value to use as the left-hand side of the comparison, instead of using a field value from the record.
  `OperatorId`
  `operator`
  Operator this criterion applies.
  `Object`
  `start`
  Start value of a criterion with an operator of type `"valueRange"`.
  `Object`
  `value`
  Value to be used in the application of this criterion.
  `AdvancedCriterionSubquery`
  `valueQuery`
  A subquery to use instead of a `value`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Criterion()`

- ## Method Summary

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

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

- ## Field Details

  - ### operator

    public OperatorId operator
    Operator this criterion applies.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### fieldName

    public String fieldName
    Name of the field in each `Record` that this criterion applies to. Not applicable for a criterion with `sub-criteria`. Can be specified as a dataPath to allow matching nested objects. Use '/' as delimiters for dataPath. See `dataPath` for more information.

    #### `fieldQuery` shortcuts

    `fieldName` can also be used to express a compact form of related-field filtering. If you set this property to the qualified name of a field on a related DataSource, it will be transformed into a basic `AdvancedCriterionSubquery`. For example, say you have an `Order` dataSource, which has a `foreign key relation` to your `Customer` dataSource, and your `Customer` dataSource has a "region" field. If you wanted to fetch all Orders for Customers in the EMEA region, you could declare criteria like this:

             {fieldName: "Customer.region", operator: "equals", value: "EMEA"}

    This would be transformed into a subquery filter that would select only the records you want:

          {
               fieldQuery: {
                   dataSource: "Customer",
                   queryOutput: "region"
               }, operator: "equals", value: "EMEA"
          }

    This transformation takes place before the filtering subsystem even sees the criteria, so declaring the shortcut form via `fieldName` leads to exactly the same filtering behavior as if you specified the subquery directly as a `fieldQuery`

    See the `AdvancedCriterionSubquery` overview linked above for more details of the extremely powerful subquery filtering options.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### valueQuery

    public AdvancedCriterionSubquery valueQuery
    A subquery to use instead of a `value`. When you use a `valueQuery` instead of a `value`, you are comparing the values in the record field named in the criterion `fieldName` to the result of running a per-record subquery, rather than a literal scalar value. . Note, it is also possible to specify both a `valueQuery` and a `fieldQuery`.

    See the `subquery overview` for more details of the criteria subquery feature, and examples of use.

    Note, if you specify both `valueQuery` and `value` in a criterion, we use the `value` and the `valueQuery` is ignored

    `valueQuery` is supported for client-side filtering of `clientOnly` DataSources, `MockDataSource`s, and cached DataSources. See the "Client-Side Subquery Support" section in the `subquery overview` for details.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### fieldQuery

    public AdvancedCriterionSubquery fieldQuery
    A subquery to use instead of a `fieldName`. When you use a `fieldQuery` instead of a `fieldName`, you are comparing the criterion `value` to the result of running a per-record subquery, rather than a field value found directly on the record. Note, it is also possible to specify both a `fieldQuery` and a `valueQuery`.

    See the `subquery overview` for more details of the criteria subquery feature, and examples of use.

    Note, if you specify both `fieldQuery` and `fieldName` in a criterion, we use the `fieldName` and the `fieldQuery` is ignored.

    Note also that `fieldName` supports a special shortcut syntax for declaring a `fieldQuery` as a simple qualified reference to a related field. See the `fieldName` doc linked above for details

    `fieldQuery` is supported for client-side filtering of `clientOnly` DataSources, `MockDataSource`s, and cached DataSources. See the "Client-Side Subquery Support" section in the `subquery overview` for details.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### fieldStaticValue

    public Object fieldStaticValue
    A constant value to use as the left-hand side of the comparison, instead of using a field value from the record. When set, this value is used in place of the field value that would normally be derived from `fieldName` or `fieldQuery`.

    This is useful when comparing a known constant against the result of a `valueQuery`. For example, to check whether a particular product code appears in the set of products ordered by a customer:

          {
              fieldStaticValue: "PROD-001",
              operator: "inSet",
              valueQuery: {
                  dataSource: "OrderLine",
                  queryOutput: "productCode"
              }
          }

    If both `fieldStaticValue` and `fieldName` are specified, `fieldStaticValue` is used instead. If both `fieldStaticValue` and `fieldQuery` are specified, `fieldStaticValue` is used instead.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### end

    public Object end
    End value of a criterion with an operator of type `"valueRange"`.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### start

    public Object start
    Start value of a criterion with an operator of type `"valueRange"`.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### criteria

    public Criterion[] criteria
    For a criterion with an operator that acts on other criteria (eg "and", "or"), a list of sub-criteria that are grouped together by the operator.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### value

    public Object value
    Value to be used in the application of this criterion.

    Value may be required or not required, or may be an Array, according to the `OperatorValueType` of the operator.

    Default value is null

    See Also:
      - `Advanced Filtering`

- ## Constructor Details

  - ### Criterion

    public Criterion()