org.fest.assertions.api.filter
Class Filters<E>

java.lang.Object
  extended by org.fest.assertions.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.

Note that the given Iterable or array is not modified, the filters are performed on a copy.

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)
 
With pseudo filter language on element properties :
 assertThat(filter(players).with("pointsPerGame").greaterThan(20)
                           .and("assistsPerGame").greaterThan(7)
                           .get()).containsOnly(james, rose);

Author:
Joel Costigliola

Method Summary
 Filters<E> and(String propertyName)
          Alias of with(String) for synthetic sugar to write things like :.
 Filters<E> being(Condition<E> condition)
          Filter the underlying group, keeping only elements satisfying the given Condition.
 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<E> condition)
          Filter the underlying group, keeping only elements satisfying the given Condition.
 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 propertyName)
          Sets the name of the property used for filtering, it may be a nested property like "adress.street.name".
 Filters<E> with(String propertyName, 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.

Note that the given Iterable is not modified, the filters are performed on a copy.

- 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)
 
- With pseudo filter language on element properties :
 assertThat(filter(players).with("pointsPerGame").greaterThan(20)
                           .and("assistsPerGame").greaterThan(7).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 :

 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);
 
With pseudo filter language on element properties :
 assertThat(filter(players).with("pointsPerGame").greaterThan(20)
                           .and("assistsPerGame").greaterThan(7)
                           .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<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:
NullPointerException - if the given condition is null.

having

public Filters<E> having(Condition<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:
NullPointerException - if the given condition is null.

with

public Filters<E> with(String propertyName,
                       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:
propertyName - the name of the property 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:
org.fest.util.IntrospectionError - if an element in the given Iterable does not have a property with a given propertyName.
NullPointerException - if the given propertyName is null.

with

public Filters<E> with(String propertyName)
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:
propertyName - the name of the property used for filtering. It may be a nested property.
Returns:
this Filters to chain other filter operation.
Throws:
NullPointerException - if the given propertyName is null.

and

public Filters<E> and(String propertyName)
Alias of with(String) for synthetic sugar to write things like :.
 filter(employees).with("name").equalsTo("Alex").and("job").notEqualsTo("lawyer").get();
 

Parameters:
propertyName - the name of the property used for filtering. It may be a nested property.
Returns:
this Filters to chain other filter operation.
Throws:
NullPointerException - if the given propertyName 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:
NullPointerException - 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:
NullPointerException - 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:
NullPointerException - 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:
NullPointerException - 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.


Copyright © 2007-2012 FEST (Fixtures for Easy Software Testing). All Rights Reserved.