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 /**
20 * A Function provides a transformation on an object and returns the resulting
21 * object. For example, a {@code StringToIntegerFunction} may implement
22 * {@literal Function<String,Integer>} and transform integers in {@link String}
23 * format to {@link Integer} format.</p>
24 *
25 * <p>The transformation on the source object does not necessarily result in
26 * an object of a different type. For example, a
27 * {@code MeterToFeetFunction} may implement
28 * {@literal Function<Integer, Integer>}.</p>
29 *
30 * <p>Implementations which may cause side effects upon evaluation are strongly
31 * encouraged to state this fact clearly in their API documentation.</p>
32 *
33 * <p><strong>Note:</strong> experimental - inspired by <em>guice</em></p>
34 *
35 * @author Sascha Kohlmann
36 * @since 0.1.0
37 * @param <F> the <em>from</em> type to handle in the function
38 * @param <T> the <em>to</em> type results from {@link #apply}
39 */
40 @Experimental
41 public interface Function<F, T> {
42
43 /**
44 * Applies the function to an object of type {@code F}, resulting in an object
45 * of type {@code T}. Note that types {@code F} and {@code T} may or may not
46 * be the same.
47 * @param from The source object.
48 * @return The resulting object.
49 */
50 T apply(@Nullable F from);
51
52 /**
53 * Indicates whether some other object is equal to this {@code Function}.
54 * This method can return {@code true} <em>only</em> if the specified object
55 * is also a {@code Function} and, for every input object {@code o}, it
56 * returns exactly the same value. Thus, {@code function1.equals(function2)}
57 * implies that either {@code function1.apply(o)} and
58 * {@code function1.apply(o)} are both {@code null}, or
59 * {@code function1.apply(o).equals(function2.apply(o))}.</p>
60 *
61 * <p>Note that it is <em>always</em> safe <em>not</em> to override
62 * {@code Object.equals(Object)}.</p>
63 */
64 boolean equals(Object obj);
65 }