AdvancedCriteria (SmartClient Enterprise Server API 13.0p (2024-11-16))

java.lang.Object
- com.isomorphic.criteria.AdvancedCriteria

```
public class AdvancedCriteria
extends java.lang.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.
The server-side AdvancedCriteria handling feature is only available with the Power and Enterprise Editions of SmartClient; the Pro Edition is limited to ordinary criteria handling on the server side)
AdvancedCriteria objects can be created directly in java. For example:
```
 AdvancedCriteria criteria = new AdvancedCriteria(DefaultOperators.And, new Criterion[]{
   new SimpleCriterion("countryCode", "contains", "C"),
   new SimpleCriterion("countryName", "startsWith", "C")
 });
 
```
In addition to building a raw AdvancedCriteria object as described above, the DataSource.parseAdvancedCriteria(Map) and Evaluator.parseAdvancedCriteria(Map) methods may be used to create AdvancedCriteria based on simple fieldName / value mappings.
Also an AdvancedCriteria instance can be retrieved from a DSRequest via DSRequest.getAdvancedCriteria() These same AdvancedCriteria objects can be directly created server side, and applied to a DSRequest via DSRequest.setAdvancedCriteria(AdvancedCriteria).

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String CONSTRUCTOR_NAME
_constructor attribute value

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`CONSTRUCTOR_NAME` _constructor attribute value

Constructor Summary

Constructors
Constructor and Description
`AdvancedCriteria(Criterion _criteria)` Convert existing Criterion to AdvancedCriteria.
`AdvancedCriteria(Operator operator, Criterion[] criteria)` Combine an array of criterion into AdvancedCriteria instance using operator.
`AdvancedCriteria(java.lang.String operator, Criterion[] criteria)` Combine an array of criterion into AdvancedCriteria instance using operator in the format of String.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCriteria(Criterion criterion)` Adds the passed criteria to the existing list of Criterion if the outermost operator is a logical "and".
`void`	`addCriteria(java.lang.String field, OperatorBase operator, java.lang.Object value)` Creates and adds a new Criterion to the AdvancedCriteria via `AdvancedCriteria.addCriteria(Criterion)`.
`void`	`addCriteria(java.lang.String field, OperatorBase operator, java.lang.Object start, java.lang.Object end)` Creates and adds a new Criterion to the AdvancedCriteria via `AdvancedCriteria.addCriteria(Criterion)`.
`Criterion`	`asCriterion()` Convert AdvancedCriteria into Criterion format.
`void`	`convertRelativeDates()` Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time.
`void`	`convertRelativeDates(DataSource ds)` Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time.
`void`	`convertRelativeDates(java.util.Date baseDate)` Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time.
`void`	`convertRelativeDates(java.util.Date baseDate, DataSource ds)` Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time.
`void`	`convertRelativeDates(java.util.Date baseDate, DataSource ds, boolean useEmbeddedTZ)` Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time.
`static AdvancedCriteria`	`decodeClientCriteria(java.lang.String clientCriteria)` Decodes a client side criteria which has been serialized for storage.
`static AdvancedCriteria`	`fromCollections(java.lang.Object criteria)` Creates an AdvancedCriteria object from Java collections.
`static AdvancedCriteria`	`fromCollections(java.lang.Object criteria, OperatorBase operator)` Creates an AdvancedCriteria object from Java collections.
`static AdvancedCriteria`	`fromCollections(java.lang.Object criteria, java.lang.String operator)` Creates an AdvancedCriteria object from Java collections.
`java.util.Map`	`getCriteriaAsMap()` Convert AdvancedCriteria into Map object.
`Criterion`	`getFieldCriterion(java.lang.String fieldName)` Returns the depth-first match of a criterion matching the given fieldName.
`java.util.Set`	`getFieldCriterions(java.lang.String fieldName)` Returns all criterions matching the given fieldName.
`java.lang.Object`	`getFieldValue(java.lang.String fieldName)` Returns the depth-first value of a criterion matching the given fieldName.
`static java.util.Map`	`toCollections(Criterion criterion)` The "collections" format of AdvancedCriteria is a simple Java representation of criteria that is equivalent to the typical JavaScript / JSON representation.

- Field Detail
  - CONSTRUCTOR_NAME
```
public static final java.lang.String CONSTRUCTOR_NAME
```
    _constructor attribute value
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - AdvancedCriteria
```
public AdvancedCriteria(Criterion _criteria)
```
    Convert existing Criterion to AdvancedCriteria.
    
    Parameters:
    
    _criteria - - criteria to use in AdvancedCriteria.
  - AdvancedCriteria
```
public AdvancedCriteria(Operator operator,
                        Criterion[] criteria)
```
    Combine an array of criterion into AdvancedCriteria instance using operator. For example:
```
 AdvancedCriteria criteria = new AdvancedCriteria(DefaultOperators.And, new Criterion[]{
   new SimpleCriterion("countryCode", "contains", "C"),
   new SimpleCriterion("countryName", "startsWith", "C")
 });
 
```
    You can pass another AdvancedCriteria in the array of criteria by using AdvancedCriteria.asCriterion() method.
    Parameters:
    
    operator - - operator that will be used to combine criteria.
    
    criteria - - criteria that will be combined.
  - AdvancedCriteria
```
public AdvancedCriteria(java.lang.String operator,
                        Criterion[] criteria)
```
    Combine an array of criterion into AdvancedCriteria instance using operator in the format of String. For example:
```
 AdvancedCriteria criteria = new AdvancedCriteria("and", new Criterion[]{
   new SimpleCriterion("countryCode", "contains", "C"),
   new SimpleCriterion("countryName", "startsWith", "C")
 });
 
```
    You can pass another AdvancedCriteria in the array of criteria by using AdvancedCriteria.asCriterion() method.
    Parameters:
    
    operator - - operator that will be used to combine criteria.
    
    criteria - - criterias that will be combined.
- Method Detail
  - getFieldValue
```
public java.lang.Object getFieldValue(java.lang.String fieldName)
```
    Returns the depth-first value of a criterion matching the given fieldName.
    
    Parameters:
    
    fieldName - - name of field to search value for.
    
    Returns:
    
    first found value or null if no value was found.
  - getFieldCriterion
```
public Criterion getFieldCriterion(java.lang.String fieldName)
```
    Returns the depth-first match of a criterion matching the given fieldName.
    
    Parameters:
    
    fieldName - - name of field to search value for.
    
    Returns:
    
    first found value or null if no value was found.
  - convertRelativeDates
```
public void convertRelativeDates()
```
    Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time. Note that this API is not able to distinguish between "date" and "datetime" fields, so it may not convert values as you expect. If this causes a problem in your use case, consider using AdvancedCriteria.convertRelativeDates(DataSource)
    See DataSource.convertRelativeDates(Criterion) for more information on relative date conversion.
    
    See Also:
    
    DataSource.convertRelativeDates(Criterion)
  - convertRelativeDates
```
public void convertRelativeDates(DataSource ds)
```
    Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time. See DataSource.convertRelativeDates(Criterion) for more information on relative date conversion. Note that this API is able to distinguish between "date" and "datetime" fields, unlike AdvancedCriteria.convertRelativeDates().
    
    See Also:
    
    DataSource.convertRelativeDates(Criterion)
  - convertRelativeDates
```
public void convertRelativeDates(java.util.Date baseDate)
```
    Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time. See DataSource.convertRelativeDates(Criterion) for more information on relative date conversion. Note that this API is not able to distinguish between "date" and "datetime" fields, so it may not convert values as you expect. If this causes a problem in your use case, consider using AdvancedCriteria.convertRelativeDates(Date, DataSource) or DataSource.convertRelativeDates(Criterion, Date, DataSource)
    
    Parameters:
    
    baseDate - the point in time to convert the relative dates against. If null, it will be defaulted to now.
    
    See Also:
    
    DataSource.convertRelativeDates(Criterion)
  - convertRelativeDates
```
public void convertRelativeDates(java.util.Date baseDate,
                                 DataSource ds)
```
    Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time. See DataSource.convertRelativeDates(Criterion) for more information on relative date conversion. Note that this API is able to distinguish between "date" and "datetime" fields, unlike AdvancedCriteria.convertRelativeDates(Date). This API always uses the server's local timezone to determine what is meant by concepts such as "the staert of today" or "the end of tomorrow"
    
    Parameters:
    
    baseDate - the point in time to convert the relative dates against. If null, it will be defaulted to now.
    
    ds - the DataSource associated with this AdvancedCriteria. The dataSource definition is used to determine whether a Java Date value should be treated as a logical "date" or a "datetime".
    
    See Also:
    
    DataSource.convertRelativeDates(Criterion, Date, DataSource)
  - convertRelativeDates
```
public void convertRelativeDates(java.util.Date baseDate,
                                 DataSource ds,
                                 boolean useEmbeddedTZ)
```
    Converts any relative dates in this AdvancedCriteria into absolute dates with now as the relative point in time. See DataSource.convertRelativeDates(Criterion) for more information on relative date conversion. Note that this API is able to distinguish between "date" and "datetime" fields, unlike AdvancedCriteria.convertRelativeDates(Date). This API can potentially use the client's timezone to determine what is meant by concepts such as "the start of today" or "the end of tomorrow", if the client supplies its timezone in the relativeDate definition. See DataSource.convertRelativeDates(Criterion, Date, DataSource, boolean) for important information about using the client timezone when converting relative dates.
    
    Parameters:
    
    baseDate - the point in time to convert the relative dates against. If null, it will be defaulted to now.
    
    ds - the DataSource associated with this AdvancedCriteria. The dataSource definition is used to determine whether a Java Date value should be treated as a logical "date" or a "datetime"
    
    useEmbeddedTZ - If true, the conversion will use the timezone embedded in the relativeDate definition sent up by the client (if the client sent that information). This allows the server to perform date conversions that match what the client would have done, even if the server and the client are configured for different timezones
    
    See Also:
    
    DataSource.convertRelativeDates(Criterion, Date, DataSource, boolean)
  - decodeClientCriteria
```
public static AdvancedCriteria decodeClientCriteria(java.lang.String clientCriteria)
                                             throws java.lang.Exception
```
    Decodes a client side criteria which has been serialized for storage. Criteria are expected to be serialized as JSON, specifically using the "logicalDateConstructor" mode of the client-side JSONEncoder class.
    
    Parameters:
    
    clientCriteria - a string of the encoded/serialized criteria to decode.
    
    Returns:
    
    the advanced criteria representation of the client criteria.
    
    Throws:
    
    java.lang.Exception - if there is a problem parsing the client criteria.
    
    See Also:
    
    DataSource.convertRelativeDates(Criterion)
  - getFieldCriterions
```
public java.util.Set getFieldCriterions(java.lang.String fieldName)
```
    Returns all criterions matching the given fieldName.
    
    Parameters:
    
    fieldName - - name of field to search value for.
    
    Returns:
    
    all criterions matching fieldName. The Set will be empty if no matches were found.
  - getCriteriaAsMap
```
public java.util.Map getCriteriaAsMap()
```
    Convert AdvancedCriteria into Map object.
    
    Returns:
    
    AdvancedCriteria represented as Map.
  - fromCollections
```
public static AdvancedCriteria fromCollections(java.lang.Object criteria)
```
    Creates an AdvancedCriteria object from Java collections.
    You may pass collections reflecting simple or advanced criteria to this method.
    If criteria were passed as simple Criteria this method will convert them to the more general AdvancedCriteria format by turning them into an AND Criterion containing one or more "equals" Criteria.
    Note that AdvancedCriteria will only be able to be executed by the built-in server DataSources (JPA, Hibernate, SQL) in Power Edition and above.
    
    Parameters:
    
    criteria - - criteria in java collections (nested maps) format
    
    Returns:
    
    The resulting advanced criteria
  - fromCollections
```
public static AdvancedCriteria fromCollections(java.lang.Object criteria,
                                               java.lang.String operator)
```
    Creates an AdvancedCriteria object from Java collections.
    You may pass collections reflecting simple or advanced criteria to this method.
    If criteria were passed as simple Criteria this method will convert them to the more general AdvancedCriteria format by turning them into an AND Criterion containing one or more Criteria with the operator specified by the operator argument to this method.
    Note that AdvancedCriteria will only be able to be executed by the built-in server DataSources (JPA, Hibernate, SQL) in Power Edition and above.
    
    Parameters:
    
    criteria - - criteria in java collections (nested maps) format
    
    operator - - default operator to use
    
    Returns:
    
    The resulting advanced criteria
  - fromCollections
```
public static AdvancedCriteria fromCollections(java.lang.Object criteria,
                                               OperatorBase operator)
```
    Creates an AdvancedCriteria object from Java collections.
    You may pass collections reflecting simple or advanced criteria to this method.
    If criteria were passed as simple Criteria this method will convert them to the more general AdvancedCriteria format by turning them into an AND Criterion containing one or more Criteria with the operator specified by the operator argument to this method.
    Note that AdvancedCriteria will only be able to be executed by the built-in server DataSources (JPA, Hibernate, SQL) in Power Edition and above.
    
    Parameters:
    
    criteria - - criteria in java collections (nested maps) format
    
    operator - - default operator to use
    
    Returns:
    
    The resulting advanced criteria
  - toCollections
```
public static java.util.Map toCollections(Criterion criterion)
```
    The "collections" format of AdvancedCriteria is a simple Java representation of criteria that is equivalent to the typical JavaScript / JSON representation.
    Each normal Criterion is represented as a Java Map with "fieldName" and "operator" keys, and a possible "value" or "start" and "end" keys based on the OperatorValueType com.smartgwt.client.types.OperatorValueType.
    A Criterion which is a logical operator ("and", "or", "not") has a key "criteria" which contains sub-criteria as a List of Maps.
    This is a useful format for serialization, although note that serializing to JSON will not correctly round-trip Date objects without further processing, since JSON has no way of directly serializing dates.
    Use AdvancedCriteria.fromCollections(Object) to create an AdvancedCriteria object from the result of this method.
    
    Parameters:
    
    criterion - The passed criterion.
    
    Returns:
    
    AdvancedCriteria represented as Map.
  - addCriteria
```
public void addCriteria(Criterion criterion)
```
    Adds the passed criteria to the existing list of Criterion if the outermost operator is a logical "and". Otherwise, the existing criteria becomes an "AND" Criterion, with two sub-criteria: the existing criteria, and the passed criteria.
    Note that if the existing criteria is null (as would happen if new AdvancedCriteria(null) were called with NULL as the only argument), the existing criteria becomes an "AND" Criterion with the passed criteria as the only entry.
    
    Parameters:
    
    criterion - The passed criterion
  - addCriteria
```
public void addCriteria(java.lang.String field,
                        OperatorBase operator,
                        java.lang.Object start,
                        java.lang.Object end)
```
    Creates and adds a new Criterion to the AdvancedCriteria via AdvancedCriteria.addCriteria(Criterion).
    If the passed operator is not of a type that takes a start and end value (for example, "greaterThan" is passed), an Exception is thrown.
    
    Parameters:
    
    field - The field name to use in the criteria
    
    operator - The operatorBase to use
    
    start - The range-start value to apply, for range operators like "between"
    
    end - The range-end value to apply, for range operators like "between"
  - addCriteria
```
public void addCriteria(java.lang.String field,
                        OperatorBase operator,
                        java.lang.Object value)
```
    Creates and adds a new Criterion to the AdvancedCriteria via AdvancedCriteria.addCriteria(Criterion).
    If the passed operator is not of a type that takes a singular value (for example, "between" is passed), an Exception is thrown.
    
    Parameters:
    
    field - The field name to use in the criteria
    
    operator - The operatorBase to use
    
    value - The filter value to apply
  - asCriterion
```
public Criterion asCriterion()
```
    Convert AdvancedCriteria into Criterion format.
    
    Returns:
    
    AdvancedCriteria represented as Criterion.

Class AdvancedCriteria

Field Summary

Constructor Summary

Method Summary

Field Detail

CONSTRUCTOR_NAME

Constructor Detail

AdvancedCriteria

AdvancedCriteria

AdvancedCriteria

Method Detail

getFieldValue

getFieldCriterion

convertRelativeDates

convertRelativeDates

convertRelativeDates

convertRelativeDates

convertRelativeDates

decodeClientCriteria

getFieldCriterions

getCriteriaAsMap

fromCollections

fromCollections

fromCollections

toCollections

addCriteria

addCriteria

addCriteria

asCriterion