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:
    com.google.gwt.event.shared.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 and Description
    `AdvancedCriteria()`
    `AdvancedCriteria(Criterion c)`
    `AdvancedCriteria(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `AdvancedCriteria(OperatorId operator)`
    `AdvancedCriteria(OperatorId operator, Criterion[] criterias)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Boolean value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Boolean[] value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.util.Date value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.util.Date[] value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.util.Date start, java.util.Date end)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Float value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Float[] value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Float start, java.lang.Float end)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Integer value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Integer[] value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Integer start, java.lang.Integer end)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Long value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Long[] value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.Long start, java.lang.Long end)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, RelativeDate value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, RelativeDate start, RelativeDate end)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.String value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.String[] value)`
    `AdvancedCriteria(java.lang.String fieldName, OperatorId operator, java.lang.String start, java.lang.String end)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `asString()` Gets a string encoding of an AdvancedCriteria object.
    `static AdvancedCriteria` | `fromJSObject(com.google.gwt.core.client.JavaScriptObject jsObj)` Creates an AdvancedCriteria from a JavaScriptObject with the format described in `AdvancedCriteria`
    `static AdvancedCriteria` | `fromJSON(java.lang.String json)` Creates an AdvancedCriteria from a JSON String in the format described in `AdvancedCriteria`.
    `static AdvancedCriteria` | `fromString(java.lang.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(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `java.lang.Boolean` | `getStrictSQLFiltering()` When set to true, causes filtering using this criteria object to follow SQL99 behavior for dealing with NULL values.
    `AdvancedCriteria` | `setStrictSQLFiltering(java.lang.Boolean strictSQLFiltering)` When set to true, causes filtering using this criteria object to follow SQL99 behavior for dealing with NULL values.
    `java.lang.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, getOperator, getValueAsBoolean, getValueAsDate, getValueAsFloat, getValueAsInt, getValueAsIntArray, getValueAsInteger, getValueAsString, getValueAsStringArray, getValuePath, instanceOf, markAdvancedCriteria, setCriteria, setCustomOperator, setFieldName, setOperator, setValuePath, 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 Detail

    - #### AdvancedCriteria

          public AdvancedCriteria()

    - #### AdvancedCriteria

          public AdvancedCriteria(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### AdvancedCriteria

          public AdvancedCriteria(Criterion c)

    - #### AdvancedCriteria

          public AdvancedCriteria(OperatorId operator,
                                  Criterion[] criterias)

    - #### AdvancedCriteria

          public AdvancedCriteria(OperatorId operator)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.lang.Integer value)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.lang.String value)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.lang.Float value)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.util.Date value)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  RelativeDate value)

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.lang.Boolean value)

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.util.Date[] value)

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.util.Date start,
                                  java.util.Date end)

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.lang.Long value)

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

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

    - #### AdvancedCriteria

          public AdvancedCriteria(java.lang.String fieldName,
                                  OperatorId operator,
                                  java.lang.String start,
                                  java.lang.String end)

  - ### Method Detail

    - #### getOrCreateRef

          public static AdvancedCriteria getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### setStrictSQLFiltering

          public AdvancedCriteria setStrictSQLFiltering(java.lang.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 java.lang.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(com.google.gwt.core.client.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(java.lang.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 java.lang.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(java.lang.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 java.lang.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