Package org.assertj.core.api.filter

Class Filters<E>

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

Field Summary

Fields

Modifier and Type	Field	Description
(package private) List<E>	filteredIterable
(package private) Iterable<E>	initialIterable
private String	propertyOrFieldNameToFilterOn	The name of the property used for filtering.
private PropertyOrFieldSupport	propertyOrFieldSupport

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Filters(E[] array)
private	Filters(Iterable<E> iterable)

Method Summary

Modifier and Type	Method	Description
Filters<E>	and(String propertyOrFieldName)	Alias of with(String) for synthetic sugar to write things like :
private Filters<E>	applyFilterCondition(Condition<? super E> condition)
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.
private void	checkPropertyNameToFilterOnIsNotNull()
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.
List<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.
private static boolean	isItemInArray(Object item, Object[] arrayOfValues)	Returns true if given item is in given array, false otherwise.
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.
private void	validatePropertyOrFieldName(String propertyOrFieldName)
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

Field Detail

initialIterable

final Iterable<E> initialIterable

filteredIterable

List<E> filteredIterable

propertyOrFieldSupport

private final PropertyOrFieldSupport propertyOrFieldSupport

propertyOrFieldNameToFilterOn

private String propertyOrFieldNameToFilterOn

The name of the property used for filtering.

Constructor Detail

Filters

private Filters(Iterable<E> iterable)

Filters

private Filters(E[] array)

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);

Type Parameters:

E - the iterable elements type.

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);

Type Parameters:

E - the array elements type.

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.

applyFilterCondition

private Filters<E> applyFilterCondition(Condition<? super E> condition)

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.

validatePropertyOrFieldName

private void validatePropertyOrFieldName(String propertyOrFieldName)

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.

checkPropertyNameToFilterOnIsNotNull

private void checkPropertyNameToFilterOnIsNotNull()

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.

isItemInArray

private static boolean isItemInArray(Object item,
                                     Object[] arrayOfValues)

Returns true if given item is in given array, false otherwise.

Parameters:

item - the object to look for in arrayOfValues

arrayOfValues - the array of values

Returns:

true if given item is in given array, false otherwise.

get

public List<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.