fflib-apex-extensions/docs/fflib_Criteria.asciidoc

= fflib_Criteria Class
:Author:    Wilhelmus G.J. Velzeboer
:Email:     wim@velzeboer.nl
:Date:      2021
:Revision:  version 1

link:README.asciidoc[<- _Back to main overview_]

A evaluator based on criteria

== Methods

- <<orCriteria, orCriteria()>> +
Changes the default comparator for each criteria to OR
- <<andCriteria, andCriteria()>> +
Changes the default comparator for each criteria to AND
- <<addOrCriteria, addOrCriteria(fflib_Criteria subCriteria)>> +
Adds a sub criteria with OR comparator
- <<addAndCriteria, addAndCriteria(fflib_Criteria subCriteria)>> +
Adds a sub criteria with AND comparator
- <<equalTo, equalTo(Schema.SObjectField field, Object value)>> +
Add an equal to criteria comparing a fields value to a given value
- <<equalTo2, equalTo(String relatedField, Object value)>> +
Add an equal to criteria comparing a related fields value to a given value
- <<evaluate, evaluate(Object record)>> +
Evaluates the stored criteria based on the given SObject
- <<greaterOrEqualTo, greaterOrEqualTo(Schema.SObjectField field, Object value)>> +
Compares the fields values to be greater or equal to the given value
- <<greaterOrEqualTo2, greaterOrEqualTo(String relatedField, Object value)>> +
Compares the related field values to be greater or equal to the given value
- <<greaterThan, greaterThan(Schema.SObjectField field, Object value)>> +
Compares the fields values to be greater or equal to the given value
- <<greaterThan2, greaterThan(String relatedField, Object value)>> +
Compares the related field values to be greater or equal to the given value
- <<inSet, inSet(Schema.SObjectField field, Set<Object> values)>> +
Checks if the given sets contains the fields values
- <<lessOrEqualTo, lessOrEqualTo(Schema.SObjectField field, Object value)>> +
Compares the fields values to be less or equal to the given value
- <<lessOrEqualTo2, lessOrEqualTo(String relatedField, Object value)>> +
Compares the related field values to be less or equal to the given value
- <<lessThan, lessThan(Schema.SObjectField field, Object value)>> +
Compares the fields values to be greater or equal to the given value
- <<lessThan2, lessThan(String relatedField, Object value)>> +
Compares the related field values to be greater or equal to the given value
- <<notEqualTo, notEqualTo(Schema.SObjectField field, Object value)>> +
Add an equal to criteria comparing a fields value to a given value
- <<notEqualTo2, notEqualTo(String relatedField, Object value)>> +
Add an equal to criteria comparing a related fields value to a given value
- <<notInSet, notInSet(Schema.SObjectField field, Set<Date> values)>> +
Checks if the given sets does not contain the fields values
- <<toSQL, toSOQL()>> +
Generates the SOQL equivalent of the criteria provided



[[orCriteria]]
=== orCriteria()
Changes the default comparator for each criteria to OR

==== _Signature_
```java
public virtual fflib_Criteria orCriteria()
```

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .orCriteria()
        .equalTo(Account.Name, 'Example')
        .equalTo(Account.AccountNumber, '1234567')

// Evaluates:
// Name = 'Example' OR AccountNumber = '1234567'
```

___


[[andCriteria]]
=== andCriteria()
Changes the default comparator for each criteria to AND. +
By default the comparator is set to AND, so this method should only be used in custom implementations extended from fflib_Criteria.

==== _Signature_
```java
public virtual fflib_Criteria andCriteria()
```
==== _Example_
```java
new fflib_Criteria()
        .andCriteria()
        .equalTo(Account.Name, 'Example')
        .equalTo(Account.AccountNumber, '1234567')

// Evaluates:
// Name = 'Example' AND AccountNumber = '1234567'
```

==== _Returns_
An instance of itself to enable method chaining

___




[[addOrCriteria]]
=== addOrCriteria(fflib_Criteria subCriteria)
Adds a sub criteria with OR comparator

==== _Signature_
```java
public virtual fflib_Criteria addOrCriteria(fflib_Criteria subCriteria)
```
==== _Parameters_

_subCriteria_ +
The condition of the sub criteria

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .equalTo(Account.Name, 'Example')
        .addOrCriteria(
                new fflib_Criteria()
                        .equalTo(Account.AccountNumber, '0001')
                        .equalTo(Account.AccountNumber, '0002'))
// Evaluates:
// Account.Name = 'Example' AND (Account.AccountNumber = '0001' OR Account.AccountNumber = '0002')
```
___

[[addAndCriteria]]
=== addAndCriteria(fflib_Criteria subCriteria)
Adds a sub criteria with AND comparator

==== _Signature_
```java
public virtual fflib_Criteria addAndCriteria(fflib_Criteria subCriteria)
```

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .orCriteria()
        .equalTo(Account.Name, 'Example')
        .addAndCriteria(
                new fflib_Criteria()
                        .equalTo(Account.AccountNumber, '0001')
                        .equalTo(Account.ShippingCountry, 'USA'))
// Evaluates:
// Name = 'Example' OR (AccountNumber = '0001' AND ShippingCountry = 'USA')
```

___

[[equalTo]]
=== equalTo(Schema.SObjectField field, Object value)
Add an equal to criteria comparing a fields value to a given value

==== _Signature_
```java
public virtual fflib_Criteria equalTo(Schema.SObjectField field, Object value)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to evaluate

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .equalTo(Account.Name, 'Example')

// Evaluates:
// Name = 'Example'
```
___
[[equalTo2]]
=== equalTo(String relatedField, Object value)
Add an equal to criteria comparing a related fields value to a given value

==== _Signature_
```java
public virtual fflib_Criteria equalTo(String relatedField, Object value)
```
==== _Parameters_

_**relatedField**_ +
The related field to evaluate

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
Contact record = [SELECT Id, Account.Name FROM Contact LIMIT 1];
new fflib_Criteria()
        .equalTo('Account.Name', 'Example')
        .evaluate(record)

// Evaluates:
// Account.Name = 'Example'
```
___
[[evaluate]]
=== evaluate(Object record)
Evaluates the stored criteria based on the given SObject

==== _Signature_
```java
public virtual Boolean evaluate(Object record)
```
==== _Parameters_

_**record**_ +
The SObject to evaluate

==== _Returns_
The Boolean result of the evaluated criteria

==== _Example_
```java
Account record = new Account( Name = 'Example );
System.assert(
    new fflib_Criteria()
            .equalTo(Account.Name, 'Example')
            .evaluate(record)
);
```

___
[[greaterOrEqualTo]]
=== greaterOrEqualTo(Schema.SObjectField field, Object value)
Compares the fields values to be greater or equal to the given value.
Evaluates to false if the field value is null.

==== _Signature_
```java
public virtual fflib_Criteria greaterOrEqualTo(Schema.SObjectField field, Object value)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .greaterOrEqualTo(Account.AnnualRevenue, 54321)

// Evaluates:
// AnnualRevenue >= 54321
```

___
[[greaterOrEqualTo2]]
=== greaterOrEqualTo(String relatedField, Object value)
Compares the fields values to be greater or equal to the given value.
Evaluates to false if the field value is null.

==== _Signature_
```java
public virtual fflib_Criteria greaterOrEqualTo(String relatedField, Object value)
```
==== _Parameters_

_**relatedField**_ +
The relatedField name to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
Contact record = [SELECT Id, Account.AnnualRevenue FROM Contact LIMIT 1];
new fflib_Criteria()
        .greaterOrEqualTo('Account.AnnualRevenue', 54321)
        .evaluate(record);

// Evaluates:
// Account.AnnualRevenue >= 54321
```

___
[[greaterThan]]
=== greaterThan(Schema.SObjectField field, Object value)
Compares the fields values to be greater or equal to the given value
Evaluates to false if the field value is null

==== _Signature_
```java
public virtual fflib_Criteria greaterThan(Schema.SObjectField field, Object value)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .greaterThan(Account.AnnualRevenue, 54321)

// Evaluates:
// AnnualRevenue > 54321
```

___
[[greaterThan2]]
=== greaterThan(String relatedField, Object value)
Compares the fields values to be greater or equal to the given value
Evaluates to false if the field value is null

==== _Signature_
```java
public virtual fflib_Criteria greaterThan(String relatedField, Object value)
```
==== _Parameters_

_**relatedField**_ +
The relatedField name to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
Contact record = [SELECT Id, Account.AnnualRevenue FROM Contact LIMIT 1];
new fflib_Criteria()
        .greaterThan('Account.AnnualRevenue', 54321)
        .evaluate(record);

// Evaluates:
// Account.AnnualRevenue > 54321
```

___

[[inSet]]
=== inSet(Schema.SObjectField field, Set<Object> values)
Checks if the given sets contains the fields values

==== _Signature_
```java
public virtual fflib_Criteria inSet(Schema.SObjectField field, Set<Object> values)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to use its value

_**values**_ +
The values to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .inSet(Account.Type, new Set<Object>{'Customer', 'Competitor', 'Partner'})

// Evaluates:
// Account.Type IN ('Customer','Competitor','Partner')
```

___
[[lessOrEqualTo]]
=== lessOrEqualTo(Schema.SObjectField field, Object value)
Compares the fields values to be less or equal to the given value
Evaluates to true if the field value is null

==== _Signature_
```java
public virtual fflib_Criteria lessOrEqualTo(Schema.SObjectField field, Object value)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .lessOrEqualTo(Account.AnnualRevenue, 54321)

// Evaluates:
// AnnualRevenue > 54321
```

___
[[lessOrEqualTo2]]
=== lessOrEqualTo(String relatedField, Object value)
Compares the related fields values to be less or equal to the given value
Evaluates to true if the field value is null

==== _Signature_
```java
public virtual fflib_Criteria lessOrEqualTo(String relatedField, Object value)
```
==== _Parameters_

_**relatedField**_ +
The relatedField name to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
Contact record = [SELECT Id, Account.AnnualRevenue FROM Contact LIMIT 1];
new fflib_Criteria()
        .lessOrEqualTo('Account.AnnualRevenue', 54321)
        .evaluate(record);
// Evaluates:
// Account.AnnualRevenue > 54321
```

___

[[lessThan]]
=== lessThan(Schema.SObjectField field, Object value)
Compares the fields values to be less or equal to the given value
Evaluates to true if the field value is null

==== _Signature_
```java
public virtual fflib_Criteria lessThan(Schema.SObjectField field, Object value)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .lessThan(Account.AnnualRevenue, 54321)

// Evaluates:
// AnnualRevenue < 54321
```

[[lessThan2]]
=== lessThan(String relatedField, Object value)
Compares the related fields values to be less or equal to the given value
Evaluates to true if the field value is null

==== _Signature_
```java
public virtual fflib_Criteria lessThan(String relatedField, Object value)
```
==== _Parameters_

_**relatedField**_ +
The relatedField name to use its value

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
Contact record = [SELECT Id, Account.AnnualRevenue FROM Contact LIMIT 1];
new fflib_Criteria()
        .lessThan('Account.AnnualRevenue', 54321)
        .evaluate(record);

// Evaluates:
// AnnualRevenue < 54321
```

___

[[notEqualTo]]
=== notEqualTo(Schema.SObjectField field, Object value)
Add a not equal to criteria comparing a fields value to a given value

==== _Signature_
```java
public virtual fflib_Criteria notEqualTo(Schema.SObjectField field, Object value)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to evaluate

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .notEqualTo(Account.Name, 'Example')

// Evaluates:
// Name != 'Example'
```
___
[[notEqualTo2]]
=== notEqualTo(String relatedField, Object value)
Add a not equal to criteria comparing a related fields value to a given value

==== _Signature_
```java
public virtual fflib_Criteria notEqualTo(String relatedField, Object value)
```
==== _Parameters_

_**relatedField**_ +
The relatedField name to evaluate

_**value**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
Contact record = [SELECT Id, Account.Name FROM Contact LIMIT 1];
new fflib_Criteria()
        .notEqualTo('Account.Name', 'Example')
        .evaluate(record);

// Evaluates:
// Account.Name != 'Example'
```
___

[[notInSet]]
=== notInSet(Schema.SObjectField field, Set<Object> values)
Checks if the given sets does not contain the fields values

==== _Signature_
```java
public fflib_Criteria notInSet(Schema.SObjectField field, Set<Object> values)
```
==== _Parameters_

_**field**_ +
The Schema.sObjectField to use its value

_**values**_ +
The value to be compared to the fields value

==== _Returns_
An instance of itself to enable method chaining

==== _Example_
```java
new fflib_Criteria()
        .notInSet(Account.Type, new Set<Object>{'Customer', 'Competitor', 'Partner'})

// Evaluates:
// Account.Type NOT IN ('Customer','Competitor','Partner')
```

___

[[toSQL]]
=== toSOQL()
Generates the SOQL equivalent of the criteria provided

==== _Signature_
```java
public virtual String toSOQL()
```

==== _Returns_
The "where" part in the SOQL statement

___