Package com.smartgwt.client.data

# Class AdvancedCriteria

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.data.Criteria
com.smartgwt.client.data.Criterion
com.smartgwt.client.data.AdvancedCriteria

All Implemented Interfaces:
  `HasHandlers`

public class AdvancedCriteria extends Criterion
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.

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()`
  - `Advanced Filtering`

- ## Field Summary

  ### Fields inherited from class com.smartgwt.client.core.DataClass

  `factoryCreated, factoryProperties`

  ### Fields inherited from class com.smartgwt.client.core.JsObject

  `jsObj`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AdvancedCriteria()`
  `AdvancedCriteria(JavaScriptObject jsObj)`
  `AdvancedCriteria(Criterion c)`
  `AdvancedCriteria(OperatorId operator)`
  `AdvancedCriteria(OperatorId operator, Criterion[] criterias)`
  `AdvancedCriteria(String fieldName, OperatorId operator)`
  `AdvancedCriteria(String fieldName, OperatorId operator, RelativeDate value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, RelativeDate start, RelativeDate end)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Boolean value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Boolean[] value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Float value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Float[] value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Float start, Float end)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Integer value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Integer[] value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Integer start, Integer end)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Long value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Long[] value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Long start, Long end)`
  `AdvancedCriteria(String fieldName, OperatorId operator, String value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, String[] value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, String start, String end)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Date value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Date[] value)`
  `AdvancedCriteria(String fieldName, OperatorId operator, Date start, Date end)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `asString()`
  Gets a string encoding of an AdvancedCriteria object.
  `static AdvancedCriteria`
  `fromJSObject(JavaScriptObject jsObj)`
  Creates an AdvancedCriteria from a JavaScriptObject with the format described in `AdvancedCriteria`
  `static AdvancedCriteria`
  `fromJSON(String json)`
  Creates an AdvancedCriteria from a JSON String in the format described in `AdvancedCriteria`.
  `static AdvancedCriteria`
  `fromString(String json)`
  Creates an AdvancedCriteria from a String in the format described in `AdvancedCriteria` Unlike fromJSON(), dates, times and datetimes round-trip correctly, because they serialize via the LOGICAL_DATE_CONSTRUCTOR mode of JSONEncoder.
  `static AdvancedCriteria`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `Boolean`
  `getStrictSQLFiltering()`
  When set to true, causes filtering using this criteria object to follow SQL99 behavior for dealing with NULL values.
  `AdvancedCriteria`
  `setStrictSQLFiltering(Boolean strictSQLFiltering)`
  When set to true, causes filtering using this criteria object to follow SQL99 behavior for dealing with NULL values.
  `String`
  `toJSON()`
  Gets a JSON encoding of an AdvancedCriteria object.

  ### Methods inherited from class com.smartgwt.client.data.Criterion

  `addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, appendToCriterionList, asAdvancedCriteria, buildCriterionFromList, getCriteria, getFieldName, getFieldQuery, getOperator, getValueAsBoolean, getValueAsDate, getValueAsFloat, getValueAsInt, getValueAsIntArray, getValueAsInteger, getValueAsString, getValueAsStringArray, getValuePath, getValueQuery, instanceOf, markAdvancedCriteria, setCriteria, setCustomOperator, setFieldName, setFieldQuery, setOperator, setValuePath, setValueQuery, unmarkAdvancedCriteria`

  ### Methods inherited from class com.smartgwt.client.data.Criteria

  `addCriteria, addCriteria, addCriteria, addCriteria, addCriteria, convertToCriteriaArray, getValues, isAdvanced`

  ### Methods inherited from class com.smartgwt.client.core.DataClass

  `applyFactoryProperties, doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated`

  ### Methods inherited from class com.smartgwt.client.core.JsObject

  `equals, getJsObj, hashCode, isCreated, setJavaScriptObject, setJsObj`

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

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

- ## Constructor Details

  - ### AdvancedCriteria

    public AdvancedCriteria()

  - ### AdvancedCriteria

    public AdvancedCriteria(JavaScriptObject jsObj)

  - ### AdvancedCriteria

    public AdvancedCriteria(Criterion c)

  - ### AdvancedCriteria

    public AdvancedCriteria(OperatorId operator, Criterion[] criterias)

  - ### AdvancedCriteria

    public AdvancedCriteria(OperatorId operator)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Integer value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, String value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Float value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Date value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, RelativeDate value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Boolean value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Integer[] value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, String[] value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Float[] value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Date[] value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Boolean[] value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Date start, Date end)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, RelativeDate start, RelativeDate end)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Float start, Float end)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Integer start, Integer end)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Long value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Long[] value)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, Long start, Long end)

  - ### AdvancedCriteria

    public AdvancedCriteria(String fieldName, OperatorId operator, String start, String end)

- ## Method Details

  - ### getOrCreateRef

    public static AdvancedCriteria getOrCreateRef(JavaScriptObject jsObj)

  - ### setStrictSQLFiltering

    public AdvancedCriteria setStrictSQLFiltering(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.

    Note : This is an advanced setting

    Parameters:
      `strictSQLFiltering` - New strictSQLFiltering value. Default value is null
    Returns:
      `AdvancedCriteria` instance, for chaining setter calls
    See Also:
      - `Advanced Filtering`

  - ### getStrictSQLFiltering

    public Boolean getStrictSQLFiltering()
    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.
    Returns:
      Current strictSQLFiltering value. Default value is null
    See Also:
      - `Advanced Filtering`

  - ### fromJSObject

    public static AdvancedCriteria fromJSObject(JavaScriptObject jsObj)
    Creates an AdvancedCriteria from a JavaScriptObject with the format described in `AdvancedCriteria`
    Parameters:
      `jsObj` - the passed JavaScriptObject object
    Returns:
      AdvancedCriteria

  - ### fromJSON

    public static AdvancedCriteria fromJSON(String json)
    Creates an AdvancedCriteria from a JSON String in the format described in `AdvancedCriteria`. Note that dates will not round-trip perfectly because JSON has no way of accurately representing date values, nor a method of differentiating between dates, times and datetimes. To have dates, times and datetimes round-trip correctly, use asString() and fromString(), which serialize via the LOGICAL_DATE_CONSTRUCTOR mode of JSONEncoder.
    Parameters:
      `json` - the passed JSON string
    Returns:
      AdvancedCriteria

  - ### toJSON

    public String toJSON()
    Gets a JSON encoding of an AdvancedCriteria object. Note that dates will not round-trip perfectly because JSON has no way of representing date values, nor a method of differentiating between dates, times and datetimes. To have dates, times and datetimes round-trip correctly, use asString() and fromString(), which serialize via the LOGICAL_DATE_CONSTRUCTOR mode of JSONEncoder.
    Returns:
      String A JSON string of this AdvancedCriteria object

  - ### fromString

    public static AdvancedCriteria fromString(String json)
    Creates an AdvancedCriteria from a String in the format described in `AdvancedCriteria` Unlike fromJSON(), dates, times and datetimes round-trip correctly, because they serialize via the LOGICAL_DATE_CONSTRUCTOR mode of JSONEncoder.
    Parameters:
      `json` - the passed JSON string
    Returns:
      AdvancedCriteria

  - ### asString

    public String asString()
    Gets a string encoding of an AdvancedCriteria object. The return value is a JSON string, except for date values, which JSON has no way of representing. Unlike toJSON(), dates, times and datetimes round-trip correctly, because they serialize via the LOGICAL_DATE_CONSTRUCTOR mode of JSONEncoder.
    Returns:
      String A string similar to JSON but containing calls to framework APIs that provide accurate round-tripping of date values