Class Filters<E>

java.lang.Object
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 invalid input: '&'invalid input: '&' 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, Mikhail Mazursky
  • Method Details

    • 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 invalid input: '&'invalid input: '&' 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 invalid input: '&'invalid input: '&' 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<? 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 invalid input: '&'invalid input: '&' 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<? 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 invalid input: '&'invalid input: '&' 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.