Filters (AssertJ fluent assertions 3.2.0 API)

java.lang.Object
- org.assertj.core.api.filter.Filters<E>

Type Parameters:: E - the type of element of group to filter.

public class Filters<E>
extends Object

Filters the elements of a given Iterable or array according to the specified filter criteria.

Filter criteria can be expressed either by a Condition or a pseudo filter language on elements properties.

With fluent filter language on element properties/fields :

 assertThat(filter(players).with("pointsPerGame").greaterThan(20)
                           .and("assistsPerGame").greaterThan(7).get())
                           .containsOnly(james, rose);

With Condition :

 List<Player> players = ...; 
   
 Condition<Player> potentialMVP = new Condition<Player>("is a possible MVP"){
   public boolean matches(Player player) {
     return player.getPointsPerGame() > 20 && player.getAssistsPerGame() > 7;
   };
 };
 
 // use filter static method to build Filters
 assertThat(filter(players).being(potentialMVP).get()).containsOnly(james, rose);

Author:: Joel Costigliola, Mikhail Mazursky

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Filters<E>`	`and(String propertyOrFieldName)` Alias of `with(String)` for synthetic sugar to write things like :
`Filters<E>`	`being(Condition<? super E> condition)` Filter the underlying group, keeping only elements satisfying the given `Condition`. Same as `having(Condition)` - pick the method you prefer to have the most readable code.
`Filters<E>`	`equalsTo(Object propertyValue)` Filters the underlying iterable to keep object with property (specified by `with(String)`) equals to given value.
`static <E> Filters<E>`	`filter(E[] array)` Creates a new `Filters` with the array to filter.
`static <E> Filters<E>`	`filter(Iterable<E> iterable)` Creates a new `Filters` with the `Iterable` to filter.
`Iterable<E>`	`get()` Returns the resulting filtered Iterable<E> (even if the constructor parameter type was an array).
`Filters<E>`	`having(Condition<? super E> condition)` Filter the underlying group, keeping only elements satisfying the given `Condition`. Same as `being(Condition)` - pick the method you prefer to have the most readable code.
`Filters<E>`	`in(Object... propertyValues)` Filters the underlying iterable to keep object with property (specified by `with(String)`) equals to one of the given values.
`Filters<E>`	`notEqualsTo(Object propertyValue)` Filters the underlying iterable to keep object with property (specified by `with(String)`) not equals to given value.
`Filters<E>`	`notIn(Object... propertyValues)` Filters the underlying iterable to keep object with property (specified by `with(String)`) not in the given values.
`Filters<E>`	`with(String propertyOrFieldName)` Sets the name of the property used for filtering, it may be a nested property like `"adress.street.name"`.
`Filters<E>`	`with(String propertyOrFieldName, Object propertyValue)` Filter the underlying group, keeping only elements with a property equals to given value.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - filter
```
public static <E> Filters<E> filter(Iterable<E> iterable)
```
    Creates a new Filters with the Iterable to filter.
    Chain this call to express filter criteria either by a Condition or a pseudo filter language on elements properties or fields (reading private fields is supported but disabled by calling Assertions.setAllowExtractingPrivateFields(false).
    Note that the given Iterable is not modified, the filters are performed on a copy.
    With fluent filter language on element properties/fields :
```
 List<Player> players = ...; 
   
 assertThat(filter(players).with("pointsPerGame").greaterThan(20)
                           .and("assistsPerGame").greaterThan(7).get())
                           .containsOnly(james, rose);
```
    With Condition :
```
   public boolean matches(Player player) {
     return player.getPointsPerGame() > 20 && player.getAssistsPerGame() > 7;
   };
 };
 
 // use filter static method to build Filters
 assertThat(filter(players).being(potentialMVP).get()).containsOnly(james, rose);
```
    Parameters:
    
    iterable - the Iterable to filter.
    
    Returns:
    
    the created Filters.
    
    Throws:
    
    NullPointerException - if the given iterable is null.
  - filter
```
public static <E> Filters<E> filter(E[] array)
```
    Creates a new Filters with the array to filter.
    Chain this call to express filter criteria either by a Condition or a pseudo filter language on elements properties.
    Note that the given array is not modified, the filters are performed on an Iterable copy of the array.
    With Condition :
```
 Player[] players = ...; 
   
 assertThat(filter(players).with("pointsPerGame").greaterThan(20)
                           .and("assistsPerGame").greaterThan(7).get())
                           .containsOnly(james, rose);
```
    With Condition :
```
 Condition<Player> potentialMVP = new Condition<Player>("is a possible MVP"){
   public boolean matches(Player player) {
     return player.getPointsPerGame() > 20 && player.getAssistsPerGame() > 7;
   };
 };
 
 // use filter static method to build Filters
 assertThat(filter(players).being(potentialMVP).get()).containsOnly(james, rose);
```
    Parameters:
    
    array - the array to filter.
    
    Returns:
    
    the created Filters.
    
    Throws:
    
    NullPointerException - if the given array is null.
  - being
```
public Filters<E> being(Condition<? super E> condition)
```
    Filter the underlying group, keeping only elements satisfying the given Condition.
    Same as having(Condition) - pick the method you prefer to have the most readable code.
```
 List<Player> players = ...;
   
 Condition<Player> potentialMVP = new Condition<Player>("is a possible MVP") {
   public boolean matches(Player player) {
     return player.getPointsPerGame() > 20 && player.getAssistsPerGame() > 7;
   };
 };
 
 // use filter static method to build Filters
 assertThat(filter(players).being(potentialMVP).get()).containsOnly(james, rose);
```
    Parameters:
    
    condition - the filter Condition.
    
    Returns:
    
    this Filters to chain other filter operations.
    
    Throws:
    
    IllegalArgumentException - if the given condition is null.
  - having
```
public Filters<E> having(Condition<? super E> condition)
```
    Filter the underlying group, keeping only elements satisfying the given Condition.
    Same as being(Condition) - pick the method you prefer to have the most readable code.
```
 List<Player> players = ...;
   
 Condition<Player> mvpStats = new Condition<Player>("is a possible MVP") {
   public boolean matches(Player player) {
     return player.getPointsPerGame() > 20 && player.getAssistsPerGame() > 7;
   };
 };
 
 // use filter static method to build Filters
 assertThat(filter(players).having(mvpStats).get()).containsOnly(james, rose);
```
    Parameters:
    
    condition - the filter Condition.
    
    Returns:
    
    this Filters to chain other filter operations.
    
    Throws:
    
    IllegalArgumentException - if the given condition is null.
  - with
```
public Filters<E> with(String propertyOrFieldName,
                       Object propertyValue)
```
    Filter the underlying group, keeping only elements with a property equals to given value.
    Let's, for example, filter Employees with name "Alex" :
```
 filter(employees).with("name", "Alex").get();
```
    which is shortcut of :
```
 filter(employees).with("name").equalsTo("Alex").get();
```
    Parameters:
    
    propertyOrFieldName - the name of the property/field whose value will compared to given value. It may be a nested property.
    
    propertyValue - the expected property value.
    
    Returns:
    
    this Filters to chain other filter operations.
    
    Throws:
    
    IntrospectionError - if an element in the given Iterable does not have a property with a given propertyOrFieldName.
    
    IllegalArgumentException - if the given propertyOrFieldName is null.
  - with
```
public Filters<E> with(String propertyOrFieldName)
```
    Sets the name of the property used for filtering, it may be a nested property like "adress.street.name".
    The typical usage is to chain this call with a comparison method, for example :
```
 filter(employees).with("name").equalsTo("Alex").get();
```
    Parameters:
    
    propertyOrFieldName - the name of the property/field used for filtering. It may be a nested property.
    
    Returns:
    
    this Filters to chain other filter operation.
    
    Throws:
    
    IllegalArgumentException - if the given propertyOrFieldName is null.
  - and
```
public Filters<E> and(String propertyOrFieldName)
```
    Alias of with(String) for synthetic sugar to write things like :
```
 filter(employees).with("name").equalsTo("Alex").and("job").notEqualsTo("lawyer").get();
```
    Parameters:
    
    propertyOrFieldName - the name of the property/field used for filtering. It may be a nested property.
    
    Returns:
    
    this Filters to chain other filter operation.
    
    Throws:
    
    IllegalArgumentException - if the given propertyOrFieldName is null.
  - equalsTo
```
public Filters<E> equalsTo(Object propertyValue)
```
    Filters the underlying iterable to keep object with property (specified by with(String)) equals to given value.
    Typical usage :
```
 filter(employees).with("name").equalsTo("Luke").get();
```
    Parameters:
    
    propertyValue - the filter value.
    
    Returns:
    
    this Filters to chain other filter operation.
    
    Throws:
    
    IllegalArgumentException - if the property name to filter on has not been set.
  - notEqualsTo
```
public Filters<E> notEqualsTo(Object propertyValue)
```
    Filters the underlying iterable to keep object with property (specified by with(String)) not equals to given value.
    Typical usage :
```
 filter(employees).with("name").notEqualsTo("Vader").get();
```
    Parameters:
    
    propertyValue - the filter value.
    
    Returns:
    
    this Filters to chain other filter operation.
    
    Throws:
    
    IllegalArgumentException - if the property name to filter on has not been set.
  - in
```
public Filters<E> in(Object... propertyValues)
```
    Filters the underlying iterable to keep object with property (specified by with(String)) equals to one of the given values.
    Typical usage :
```
filter(players).with("team").in("Bulls", "Lakers").get();
```
    Parameters:
    
    propertyValues - the filter values.
    
    Returns:
    
    this Filters to chain other filter operation.
    
    Throws:
    
    IllegalArgumentException - if the property name to filter on has not been set.
  - notIn
```
public Filters<E> notIn(Object... propertyValues)
```
    Filters the underlying iterable to keep object with property (specified by with(String)) not in the given values.
    Typical usage :
```
 filter(players).with("team").notIn("Heat", "Lakers").get();
```
    Parameters:
    
    propertyValues - the filter values.
    
    Returns:
    
    this Filters to chain other filter operation.
    
    Throws:
    
    IllegalArgumentException - if the property name to filter on has not been set.
  - get
```
public Iterable<E> get()
```
    Returns the resulting filtered Iterable<E> (even if the constructor parameter type was an array).
    
    Returns:
    
    the Iterable<E> containing the filtered elements.

Class Filters<E>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

filter

filter

being

having

with

with

and

equalsTo

notEqualsTo

in

notIn

get