org.jutil.predicate
Interface Predicate

All Superinterfaces:

CollectionOperator

All Known Subinterfaces:

FileSetPredicate

All Known Implementing Classes:

AbstractPredicate

public interface Predicate

extends CollectionOperator

A class of predicates that evaluate to true or false for an object.

The Predicate class is actually an implementation of the Strategy pattern. You can write code that works with predicates (e.g. filters, quantifiers,...) in general, and the user of that code can write the specific predicate.

This class evolved from the ForAll, Exists, Counter and Filter classes (which will be deprecated soon). This class has the advantage that the predicate itself is reusable. Using the classes mentioned above, you'd have to implement a predicate multiple times if you wanted to use it for more than one type of operation. With the Predicate class, you write the predicate once, and the client can do with it whatever he/she wants.

The ForAll, Exists, Counter and Filter classes are replaced by instance methods of this class so they can be removed in the future. The recommended use for operations that do not work on collections is to use an internal iterator (like the forall,... method of this class) in the objects that contain the information. This was not possible for collections since we don't have access to the source code, and so these methods are put in this class.

Typically, this class will be used as an anonymous inner class as follows:

Predicate myPredicate = new AbstractPredicate() {
            /oo
             o also public behavior
             o
             o post postcondition;
             o/
            public boolean eval(Object o) throws MyException {
              //calculate boolean value
              //using the given object
            }
            public int nbSubPredicates() {
              // ...
            }
            public List getSubPredicates() {
              // ...
            }
          };
 

AbstractPredicate implements all methods of this interface except for eval().

If your predicate does not throw an exception, you should use TotalPredicate, so users of your predicate won't have to write try-catch constructions when no exceptions can be thrown.

In case your predicate doesn't wrap another one, use PrimitivePredicate. If it also doesn't throw exceptions, extend PrimitiveTotalPredicate.

Field Summary
static java.lang.String	CVS_REVISION

 

Method Summary
abstract  int	count(java.util.Collection collection)           Count the number of object in the given collection for which this Predicate evaluates to true.
abstract  boolean	equals(java.lang.Object other)           Check whether or not this Predicate equals another object
abstract  boolean	eval(java.lang.Object object)           Evaluate this Predicate for the given object.
abstract  boolean	exists(java.util.Collection collection)           Check wether or not the given collection contains an object for which this predicate evaluates to true.
abstract  void	filter(java.util.Collection collection)           Remove all objects for which this Predicate evaluates to false from the given collection. If you want to remove all object for which this Predicate evaluates to true, wrap a Not predicate around this predicate, and perform the filter using that predicate.
abstract  boolean	forall(java.util.Collection collection)           Check wether or not this Predicate evaluates to true for all object in the given collection.
abstract  java.util.List	getSubPredicates()           Return the subpredicates of this Predicate.
abstract  int	nbSubPredicates()           Return the size of this Predicate.

 

Methods inherited from interface org.jutil.java.collections.CollectionOperator

isValidElement

 

Field Detail

CVS_REVISION

public static final java.lang.String CVS_REVISION

eval

public abstract boolean eval(java.lang.Object object)
                      throws java.lang.Exception

Evaluate this Predicate for the given object.

Parameters:

object - The object for which this Predicate must be evaluated. In general, because collections can contain null, this might be null.

Specifications: pure

public behavior
ensures \result == true|\result == false;
signals (Exception) !isValidElement(object);

exists

public abstract boolean exists(java.util.Collection collection)
                        throws java.util.ConcurrentModificationException,
                               java.lang.Exception

Check wether or not the given collection contains an object for which this predicate evaluates to true.

Parameters:

collection - The collection which has to be searched for an object for which this Predicate evaluates to true.

Specifications: pure

public behavior
ensures collection != null ==> \result == ( \exists Object o; Collections.containsExplicitly(collection,o); eval(o) == true);
ensures collection == null ==> \result == false;
signals (ConcurrentModificationException) (* The collection was modified while accumulating *);
signals (Exception) (collection != null)&&( \exists Object o; (collection != null)&&Collections.containsExplicitly(collection,o); !isValidElement(o));

forall

public abstract boolean forall(java.util.Collection collection)
                        throws java.util.ConcurrentModificationException,
                               java.lang.Exception

Check wether or not this Predicate evaluates to true for all object in the given collection.

Parameters:

collection - The collection of which one wants to know if all object evaluate to true for this Predicate.

Specifications: pure

public behavior
ensures collection != null ==> \result == ( \forall Object o; Collections.containsExplicitly(collection,o); eval(o) == true);
ensures collection == null ==> \result == true;
signals (ConcurrentModificationException) (* The collection was modified while accumulating *);
signals (Exception) (collection != null)&&( \exists Object o; (collection != null)&&Collections.containsExplicitly(collection,o); !isValidElement(o));

count

public abstract int count(java.util.Collection collection)
                   throws java.util.ConcurrentModificationException,
                          java.lang.Exception

Count the number of object in the given collection for which this Predicate evaluates to true.

Parameters:

collection - The collection for which the number of object evaluating to true for this Predicate must be counted.

Specifications: pure

public behavior
ensures collection != null ==> \result == ( \num_of Object o; Collections.containsExplicitly(collection,o); eval(o) == true);
ensures collection == null ==> \result == 0;
signals (ConcurrentModificationException) (* The collection was modified while accumulating *);
signals (Exception) (collection != null)&&( \exists Object o; (collection != null)&&Collections.containsExplicitly(collection,o); !isValidElement(o));

filter

public abstract void filter(java.util.Collection collection)
                     throws java.util.ConcurrentModificationException,
                            java.lang.Exception

Remove all objects for which this Predicate evaluates to false from the given collection.

If you want to remove all object for which this Predicate evaluates to true, wrap a Not predicate around this predicate, and perform the filter using that predicate. For example:

 new Not(myPredicate).filter(collection);
 

Parameters:

collection - The collection to be filtered.

Specifications:

public behavior
ensures collection != null ==> ( \forall Object o; Collections.containsExplicitly(collection,o); eval(o) == true);
ensures collection != null ==> ( \forall Object o; \old(Collections.containsExplicitly(collection,o)); (eval(o) == true) ==> (Collections.nbExplicitOccurrences(o,collection) == \old(Collections.nbExplicitOccurrences(o,collection))));
signals (ConcurrentModificationException) (* The collection was modified while accumulating *);
signals (Exception) (collection != null)&&( \exists Object o; (collection != null)&&Collections.containsExplicitly(collection,o); !isValidElement(o));

getSubPredicates

public abstract java.util.List getSubPredicates()

Return the subpredicates of this Predicate.

Specifications:

public behavior
ensures \result != null;
ensures !\result .contains(null);
ensures !\result .contains(this);

equals

public abstract boolean equals(java.lang.Object other)

Check whether or not this Predicate equals another object

Overrides:

equals in class java.lang.Object

Parameters:

other - The object to compare this Predicate with.

Specifications:

     also

public behavior
ensures \result == (other instanceof Predicate)&&( \forall Object o; ; ((Predicate)other).isValidElement(o) == isValidElement(o)&&((Predicate)other).isValidElement(o) ==> ((Predicate)other).eval(o) == eval(o));

nbSubPredicates

public abstract int nbSubPredicates()

Return the size of this Predicate.

Specifications:

public behavior
ensures \result == getSubPredicates().size();