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 Records, 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

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