Package com.smartgwt.client.docs.serverds

# Class AdvancedCriteria

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

public class AdvancedCriteria extends Object
AdvancedCriteria is a format for representing search criteria which may include operators on field values such as "less than", or may include sub-clauses such as several criteria applied to fields joined by an "OR" operator.

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.

Smart GWT DataSources can use AdvancedCriteria to search a list of `Record`s, and the Smart GWT Java Server can translate AdvancedCriteria to either SQL or Hibernate queries (Note: The server-side AdvancedCriteria handling feature is only available with the Power and Enterprise Editions of Smart GWT; the Pro Edition is limited to ordinary criteria handling on the server side).

If the entire dataset is cached locally, Smart GWT can perform AdvancedCriteria filtering on the client, avoiding a server call.

AdvancedCriteria objects can be created directly in java. For example:

      AdvancedCriteria criteria = new AdvancedCriteria(OperatorId.AND, new Criterion[]{
          new Criterion("salary", OperatorId.LESS_THAN, 80000),
          new AdvancedCriteria(OperatorId.OR, new Criterion[]{
              new Criterion("title", OperatorId.ICONTAINS, "Manager"),
              new Criterion("reports", OperatorId.NOT_NULL)
          })
      });

AdvancedCriteria can also be specified in `Component XML`:

      <AdvancedCriteria operator="and" _constructor="AdvancedCriteria">
          <criteria>
              <Criterion fieldName="salary" operator="lessThan">
                  <value xsi:type="xsd:float">80000</value>
              </Criterion>
              <Criterion operator="or">
                  <criteria>
                      <Criterion fieldName="title" operator="iContains">
                          <value xsi:type="xsd:text">Manager</value>
                      </Criterion>
                      <Criterion fieldName="reports" operator="notNull"/>
                  </criteria>
              </Criterion>
              <Criterion fieldName="startDate" operator="greaterThan">
                  <value xsi:type="xsd:datetime">2014-01-01T05:00:00.000</value>
              </Criterion>
          </criteria>
      </AdvancedCriteria>

An AdvancedCriteria is in effect a `Criterion` that has been marked with _constructor:"AdvancedCriteria" to mark it as complete criteria.

In addition to directly creating an AdvancedCriteria object as described above, the `DataSource.convertCriteria()` and `DataSource.combineCriteria()` methods may be used to create and modify criteria based on simple fieldName / value mappings.

`Shorthand formats are allowed` when defining AdvancedCriteria.

When passed to the Smart GWT Server, a server-side AdvancedCriteria instance (in the package com.isomorphic.criteria) can be retrieved from a DSRequest via com.isomorphic.datasource.DSRequest.getAdvancedCriteria(). These same AdvancedCriteria objects can be directly created server side, and applied to a DSRequest via setAdvancedCriteria().

`RestDataSource`, the recommended way of integration with servers that are not running the Smart GWT Server Framework, defines a standard XML and JSON serialization of `AdvancedCriteria`. Date, DateTime and Time values use the same XML Schema representation used for other XML serialization like RestDataSource. Further details can be found at `DateFormatAndStorage`.

It's a best practice for XML representation to have `<value>` as a subelement with `xsi:type`. Although most systems will auto-convert criteria explicitly setting type leaves the least room for error or ambiguity.

For other servers, you can translate `AdvancedCriteria` into whatever format is expected by the server, typically by implementing `DataSource.transformRequest()`.

The internal representation of AdvancedCriteria is a simple JavaScript structure, available via AdvancedCriteria.getJsObj():

      // an AdvancedCriteria
      {
          _constructor:"AdvancedCriteria",
          operator:"and",
          criteria:[
              // this is a Criterion
              { fieldName:"salary", operator:"lessThan", value:"80000" },
              { operator:"or", criteria:[
                  { fieldName:"title", operator:"iContains", value:"Manager" },
                  { fieldName:"reports", operator:"notNull" }
                ]
              }
          ]
      }

And an AdvancedCriteria can also be created from a JavaScriptObject. This makes AdvancedCriteria very easy to store and retrieve as JSON strings, using `JSONEncoder`. See `Criteria Editing` for information about editing AdvancedCriteria in a DynamicForm.

When using the Smart GWT Server, AdvancedCriteria created on the client and stored as JSON can be used directly by server code (without involvement of the browser and client-side system). Use the server-side API AdvancedCriteria.decodeClientCriteria() to obtain an AdvancedCriteria that can then be used with a server-created DSRequest object. Note that the client must be serialized by the `JSONEncoder` class, using `JSONEncoder.dateFormat` "logicalDateConstructor".

See Also:
  - `ResultTree.getUseSimpleCriteriaLOD()`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `String`
  `_constructor`
  Identifies this as an AdvancedCriteria object for systems that need to distinguish AdvancedCriteria from simple criteria.
  `Boolean`
  `strictSQLFiltering`
  When set to true, causes filtering using this criteria object to follow SQL99 behavior for dealing with NULL values.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AdvancedCriteria()`

- ## Method Summary

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

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

- ## Field Details

  - ### strictSQLFiltering

    public Boolean strictSQLFiltering
    When set to true, causes filtering using this criteria object to follow SQL99 behavior for dealing with NULL values. See `this discussion` for more detail.

    Default value is null

    See Also:
      - `Advanced Filtering`

  - ### _constructor

    public String _constructor
    Identifies this as an AdvancedCriteria object for systems that need to distinguish AdvancedCriteria from simple criteria. Set to `"AdvancedCriteria"`.

    In JavaScript, this marker property is commonly used to identify criteria objects as AdvancedCriteria when serializing to JSON or passing between systems. For example:

              { _constructor:"AdvancedCriteria", operator:"and", criteria:[...] }

    Default value is null

    See Also:
      - `Advanced Filtering`

- ## Constructor Details

  - ### AdvancedCriteria

    public AdvancedCriteria()