Interface ComposablePredicate<T>

Type Parameters:
T - the type of the value being tested
All Superinterfaces:
Predicate<T>
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface public interface ComposablePredicate<T> extends Predicate<T>
An extension of Predicate that acts as a bridge between Predicate and the relational interfaces in this package. It enables the composition of new tests from any number of instances of Predicate, IntPredicate, Relation, IntRelation and IntObjRelation. ComposablePredicate extends Predicate with a set of default methods that allow the composition to take place. These methods can be divided along two axes:
  1. and() versus or() methods
  2. methods that execute two checks on a single value versus methods that effectively constitute a single check on two interrelated values

AND vs. OR Compositions

Generally, you will have more use for compositions expressing a logical disjunction (OR), as the chain of checks following Check.that(...) already constitutes a logical conjunction (AND). For example, this statement:


 Check.that(numChairs).is(positive()).is(lte(), 4).is(even());
 

requires the number of chairs to be positive and less than, or equal to 4 and even. If the number of chairs needs to pass just one of these tests, write:


 Check.that(numChairs).is(positive().orElse(lte(), 4).orElse(even()));
 

Nevertheless, you might still want to use the and() methods for conciseness:


 Check.that(string).is(notNull().and(hasSubstring(), allOf(), "to", "be", "or", "not"));
 // is equivalent to:
 Check.that(string).is(notNull())
    .is(hasSubstring(), "to")
    .is(hasSubstring(), "be")
    .is(hasSubstring(), "or")
    .is(hasSubstring(), "not")
 

(See Quantifier for the allOf() argument.)

Validating Interrelated Values

Sometimes, an argument, field or variable cannot be tested in isolation. Its validity depends on the value of another argument, field or variable:


 Check.that(engine.ready()).is(yes().or(buffer.size(), eq(), 0);
 

In the above example, the engine only needs to be ready if there is more data in the buffer.

Notice that the second check continues nicely in the idiom of Klojang Check, even though it is now just syntactic sugar. Depending on your taste you can also just write:


 Check.that(engine.ready()).is(yes().or(buffer.size() == 0);
 

(Contrary to what you might perhaps expect, it will not make your code run faster, though.)

Generics

Even though the type parameter for ComposablePredicate is <T>, the type parameter for the predicates and relations passed to the values and() and or() methods is simply <?>. This allows checks like notNull() and notEmpty(), which can be applied to any non-primitive type, to be followed by checks that can only be applied to a specific type. For example, the following code would not compile if the argument to andAlso() were Predicate<? super T> instead of Predicate<?>:


 Check.that(file).is(empty().andAlso(writable()));
 

The downside is that it is easier for a composition of tests to harbor a type error without the compiler noticing it, resulting in a ClassCastException at runtime. For example, the following nonsensical statement compiles just fine:


 Check.that(list).is(empty().andAlso(writable()));
 

In addition, when using lambdas, you will now have to specify the type of the lambda parameter:


 Check.that(file).is(empty().andAlso(f -> f.canWrite())); // WON'T COMPILE!!
 Check.that(file).is(empty().andAlso((File f) -> f.canWrite())); // OK
 

If you are not comfortable with this, you can instead use the orThat() method and repeat the argument for every call to orThat():


 Check.that(list).is(empty().orThat(list, contains(), "foo"));
 

Note, however, that the orThat() method is primarily meant to test interrelated values (see above).

See Also:
  • Method Details

    • negated

      default ComposablePredicate<T> negated()
      Returns the negation of this predicate.
      Returns:
      the negation of this predicate
      See Also:
    • orElse

      default <V> ComposablePredicate<V> orElse(Predicate<?> test)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test or the specified test.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • orElse

      default <O, V> ComposablePredicate<V> orElse(Relation<?,O> relation, O object)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test or if it has the specified relation to the specified value.
      
       Check.that("foo bar").is(empty().orElse(hasSubstring(), "foo"));
       
      Type Parameters:
      O - the type of the object of the provided Relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      relation - the relationship test to combine this test with
      object - the object of the specified relation, with the value of this ComposablePredicate now becoming the subject of that relation
      Returns:
      a new test combining this test and the specified test
    • orNot

      default <V> ComposablePredicate<V> orNot(Predicate<?> test)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test or the negation of the specified test.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • orNot

      default <O, V> ComposablePredicate<V> orNot(Relation<?,O> relation, O object)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test or if it does not have the specified relation to the specified value.
      Type Parameters:
      O - the type of the object of the provided Relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      relation - the relationship test to combine this test with
      object - the object of the provided Relation, with the value of this ComposablePredicate now becoming the subject of that relation
      Returns:
      a new test combining this test and the specified test
    • or

      default <O, P extends O, V> ComposablePredicate<V> or(Relation<V,O> relation, Quantifier quantifier, P... objects)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test or if it has a particular relation to the specified set of values.
      Type Parameters:
      O - the type of the object of the relation
      P - the type of the values fed as "objects" into the relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      relation - the relationship test to combine this test with
      quantifier - a logical quantifier modulating the relationship
      objects - the set of values to test the value against
      Returns:
      a new test combining this test and the specified test
    • orThat

      default <U, V> ComposablePredicate<V> orThat(U value, Predicate<U> test)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value manages to pass the other test.
      
       Check.that(file1).is(readable().orThat(file2, writable()));
       
      Type Parameters:
      U - the type of the value being tested by the specified predicate
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      value - the value to be tested by the specified test
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • orThat

      default <V> ComposablePredicate<V> orThat(int value, IntPredicate test)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value manages to pass the other test.
      
       Check.that(file1).is(readable().orThat(file2, writable()));
       
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      value - the value to be tested by the specified test
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • orThat

      default <S, O, V> ComposablePredicate<V> orThat(S subject, Relation<S,O> relation, O object)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value manages to pass the other test.
      Type Parameters:
      S - the type of the subject of the specified relation
      O - the type of the object of the specified relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified relation
      relation - the relationship test to combine this test with
      object - the object of the specified relation
      Returns:
      a new test combining this test and the specified test
    • orThat

      default <V> ComposablePredicate<V> orThat(int subject, IntRelation relation, int object)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value manages to pass the other test.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified relation
      relation - the relationship test to combine this test with
      object - the object of the specified relation
      Returns:
      a new test combining this test and the specified test
    • orNot

      default <U, V> ComposablePredicate<V> orNot(U value, Predicate<U> test)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value manages to pass the negation of the other test.
      
       Check.that(file1).is(readable().orThat(file2, writable()));
       
      Type Parameters:
      U - the type of the value being tested by the specified predicate
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      value - the value to be tested by the specified test
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • orNot

      default <S, O, V> ComposablePredicate<V> orNot(S subject, Relation<S,O> relation, O object)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value manages to pass the negation of the other test.
      Type Parameters:
      S - the type of the subject of the specified relation
      O - the type of the object of the specified relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified relation
      relation - the relationship test to combine this test with
      object - the object of the specified relation
      Returns:
      a new test combining this test and the specified test
    • or

      default <S, O, P extends O, V> ComposablePredicate<V> or(S subject, Relation<S,O> relation, Quantifier quantifier, P... objects)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test or if another value (subject) has a particular relation to the specified set of values.
      Type Parameters:
      S - the type of the subject of the relation
      O - the type of the object of the relation
      P - the type of the values fed as "objects" into the relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified Relation
      relation - the relationship test to combine this test with
      quantifier - a logical quantifier modulating the relationship
      objects - the set of values to test the subject against
      Returns:
      a new test combining this test and the specified test
    • or

      default <V> ComposablePredicate<V> or(int subject, IntRelation relation, Quantifier quantifier, int... objects)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value (subject) has a particular relation to the specified set of values.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the relation
      relation - the relationship test to combine this test with
      quantifier - a logical quantifier modulating the relationship
      objects - the set of values to test the subject against
      Returns:
      a new test combining this test and the specified test
    • or

      default <V> ComposablePredicate<V> or(boolean test)
      Returns a new test combining this test with the specified free-form test. A value will pass the new test if it passes this test or if the provided expression evaluates to true.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the boolean expression to evaluate if the value fails to pass this test
      Returns:
      a new test combining this test and the specified free-form test
    • orEval

      default <V> ComposablePredicate<V> orEval(Supplier<Boolean> test)
      Returns a new test combining this test with the free-form test supplied by the specified Supplier. A value will pass the new test if it passes this test or if the expression supplied by the Supplier evaluates to true. The supplier's get() method will only be called if the value fails to pass this test. Useful if evaluating the expression could be expensive.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the supplier of a boolean expression
      Returns:
      a new test combining this test and the specified free-form test
    • andAlso

      default <V> ComposablePredicate<V> andAlso(Predicate<?> test)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes both this test and the specified test.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • andAlso

      default <O, V> ComposablePredicate<V> andAlso(Relation<?,O> relation, O object)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test and if it has the specified relation to the specified value.
      Type Parameters:
      O - the type of the object of the provided Relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      relation - the relationship test to combine this test with
      object - the object of the relation, with the value being tested now becoming the subject of the relation
      Returns:
      a new test combining this test and the specified test
    • and

      default <V> ComposablePredicate<V> and(boolean test)
      Returns a new test combining this test with the specified free-form test. A value will pass the new test if it passes this test and if the provided expression evaluates to true.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the boolean expression to evaluate if the value fails to pass this test
      Returns:
      a new test combining this test and the specified free-form test
    • andEval

      default <V> ComposablePredicate<V> andEval(Supplier<Boolean> test)
      Returns a new test combining this test with the free-form test supplied by the specified Supplier. A value will pass the new test if it passes this test and if the expression supplied by the Supplier evaluates to true. The supplier's get() method will only be called if the value passes this test. Useful if evaluating the boolean expression could be expensive.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the supplier of a boolean expression
      Returns:
      a new test combining this test and the specified free-form test
    • andNot

      default <V> ComposablePredicate<V> andNot(Predicate<?> test)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes both this test and the negation of the specified test.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • andNot

      default <O, V> ComposablePredicate<V> andNot(Relation<?,O> relation, O object)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test and if it does not have the specified relation to the specified value.
      Type Parameters:
      O - the type of the object of the provided Relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      relation - the relationship test to combine this test with
      object - the object of the relation, with the value being tested now becoming the subject of the relation
      Returns:
      a new test combining this test and the specified test
    • and

      default <O, P extends O, V> ComposablePredicate<V> and(Relation<V,O> relation, Quantifier quantifier, P... objects)
      Returns a new test combining this test and the specified test. A value will pass the new test if it passes this test and if it has a particular relation to the specified set of values.
      Type Parameters:
      O - the type of the object of the relation
      P - the type of the values fed as "objects" into the relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      relation - the relationship test to combine this test with
      quantifier - a logical quantifier modulating the relationship
      objects - the set of values to test the value against
      Returns:
      a new test combining this test and the specified test
    • andThat

      default <U, V> ComposablePredicate<V> andThat(U value, Predicate<U> test)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value manages to pass the other test.
      
       Check.that(file1).is(readable().andThat(file2, writable()));
       
      Type Parameters:
      U - the type of the value being tested by the specified predicate
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      value - the value to be tested by the specified test
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • andThat

      default <V> ComposablePredicate<V> andThat(int value, IntPredicate test)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value manages to pass the other test.
      
       Check.that(file1).is(readable().andThat(file2, writable()));
       
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      value - the value to be tested by the specified test
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • andThat

      default <S, O, V> ComposablePredicate<V> andThat(S subject, Relation<S,O> relation, O object)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value manages to pass the other test.
      Type Parameters:
      S - the type of the subject of the specified relation
      O - the type of the object of the specified relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified relation
      relation - the relationship test to combine this test with
      object - the object of the specified relation
      Returns:
      a new test combining this test and the specified test
    • andThat

      default <V> ComposablePredicate<V> andThat(int subject, IntRelation relation, int object)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value manages to pass the other test.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified relation
      relation - the relationship test to combine this test with
      object - the object of the specified relation
      Returns:
      a new test combining this test and the specified test
    • andNot

      default <U, V> ComposablePredicate<V> andNot(U value, Predicate<U> test)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value manages to pass the negation of the other test.
      
       Check.that(file1).is(readable().andThat(file2, writable()));
       
      Type Parameters:
      U - the type of the value being tested by the specified predicate
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      value - the value to be tested by the specified test
      test - the test to combine this test with
      Returns:
      a new test combining this test and the specified test
    • andNot

      default <S, O, V> ComposablePredicate<V> andNot(S subject, Relation<S,O> relation, O object)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value manages to pass the negation of the other test.
      Type Parameters:
      S - the type of the subject of the specified relation
      O - the type of the object of the specified relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified relation
      relation - the relationship test to combine this test with
      object - the object of the specified relation
      Returns:
      a new test combining this test and the specified test
    • and

      default <S, O, P extends O, V> ComposablePredicate<V> and(S subject, Relation<S,O> relation, Quantifier quantifier, P... objects)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value (subject) has a particular relation to the specified set of values.
      Type Parameters:
      S - the type of the subject of the relation
      O - the type of the object of the relation
      P - the type of the values fed as "objects" into the relation
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the specified Relation
      relation - the relationship test to combine this test with
      quantifier - a logical quantifier modulating the relationship
      objects - the set of values to test the subject against
      Returns:
      a new test combining this test and the specified test
    • and

      default <V> ComposablePredicate<V> and(int subject, IntRelation relation, Quantifier quantifier, int... objects)
      Returns a new test combining this test and the specified test. It combines two checks on two different values. A value will pass the new test if it passes this test and if another value (subject) has a particular relation to the specified set of values.
      Type Parameters:
      V - the type of the value that is tested by the returned ComposablePredicate. Note that in actual fact, that really is the type of the value being tested by this ComposablePredicate.
      Parameters:
      subject - the subject of the relation
      relation - the relationship test to combine this test with
      quantifier - a logical quantifier modulating the relationship
      objects - the set of values to test the subject against
      Returns:
      a new test combining this test and the specified test