1 /* Copyright (c) 2008 Sascha Kohlmann
2 *
3 * This program is free software: you can redistribute it and/or modify
4 * it under the terms of the GNU Affero General Public License as published by
5 * the Free Software Foundation, either version 3 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Affero General Public License for more details.
12 *
13 * You should have received a copy of the GNU Affero General Public License
14 * along with this program. If not, see <http://www.gnu.org/licenses/>.
15 */
16 package net.sf.eos;
17
18 /**
19 * <p>Represents a {@code Predicate}, that is, a function with
20 * one argument returning a {@code boolean} value. It not extends
21 * function since implementing this would entail
22 * changing the signature of the {@link Function#apply} method
23 * to return a {@link Boolean} instead of a {@code boolean}, which
24 * would in turn allow people to return {@code null} from their
25 * predicate, which would in turn enable code that looks like
26 * {@code if (myPredicate.apply(myObject)) ... } to throw a
27 * {@link NullPointerException}.<p>
28 *
29 * <p><strong>Note:</strong> experimental - inspired by <em>guice</em></p>
30 *
31 * @author Sascha Kohlmann
32 * @since 0.1.0
33 * @param <T> the value type
34 */
35 @Experimental
36 public interface Predicate<T> {
37
38 /**
39 * Evaluates this predicate for the given value.
40 *
41 * @param value a value to be evaluated; should not be changed.
42 *
43 * @return a boolean value.
44 */
45 boolean evaluate(@Nullable T value);
46
47 /**
48 * Indicates whether some other object is equal to this {@code Predicate}.
49 * This method can return {@code true} <em>only</em> if the specified object
50 * is also a {@code Predicate} and, for every input object {@code o}, it
51 * returns exactly the same value. Thus,
52 * {@code predicate1.equals(predicate2)} implies that either
53 * {@code predicate1.apply(o)} and {@code predicate2.apply(o)} are both
54 * {@code true}, or both {@code false}.
55 *
56 * <p>Note that it is <em>always</em> safe <em>not</em> to override
57 * {@code Object.equals(Object)}.
58 */
59 boolean equals(Object obj);
60 }