1 /*
2 * Grapht, an open source dependency injector.
3 * Copyright 2014-2015 various contributors (see CONTRIBUTORS.txt)
4 * Copyright 2010-2014 Regents of the University of Minnesota
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU Lesser General Public License as
8 * published by the Free Software Foundation; either version 2.1 of the
9 * License, or (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
14 * details.
15 *
16 * You should have received a copy of the GNU General Public License along with
17 * this program; if not, write to the Free Software Foundation, Inc., 51
18 * Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 */
20 package org.grouplens.grapht.solver;
21
22 import org.grouplens.grapht.CachePolicy;
23 import org.grouplens.grapht.reflect.Desire;
24
25 import java.util.EnumSet;
26
27 /**
28 * BindRule is a partial function from desire to desire that acts as a binding.
29 * The {@link RuleBasedBindingFunction} takes a collection of BindRules grouped
30 * into their activating contexts to form a {@link BindingFunction}.
31 *
32 * <p><b>Note:</b> this interface's ordering is inconsistent with {@link Object#equals(Object)}. See
33 * {@link #compareTo(BindRule)} for more details.
34 *
35 * @see BindRules
36 */
37 public interface BindRule extends Comparable<BindRule> {
38 /**
39 * Get the rule's cache policy.
40 * @return The CachePolicy to use for satisfactions created with this rule.
41 */
42 CachePolicy getCachePolicy();
43
44 /**
45 * Apply this BindRule to the given Desire, and return a restricted and
46 * possibly satisfied desire. It is assumed that {@link #matches(org.grouplens.grapht.reflect.Desire)}
47 * returns true.
48 *
49 * @param desire The desire that is input to this partial binding function
50 * @return The restricted desire
51 */
52 Desire apply(Desire desire);
53
54 /**
55 * Query whether this rule is terminal. Terminal rules have no further lookup
56 * applied in order to find the final binding target.
57 *
58 * @return True if this should be the last bind rule applied to the desire
59 * chain when attempting to find a satisfaction
60 */
61 boolean isTerminal();
62
63 /**
64 * Get the flags attached to this bind rule.
65 *
66 * @return The flags attached to the bind rule.
67 */
68 EnumSet<BindingFlag> getFlags();
69
70 /**
71 * @param desire The input desire
72 * @return True if this desire matches this BindRule and can be passed to
73 * {@link #apply(org.grouplens.grapht.reflect.Desire)}
74 */
75 boolean matches(Desire desire);
76
77 /**
78 * Create a new bind rule builder initialized to copy this bind rule. Use this to create a copy
79 * of this bind rule that differs in some way.
80 *
81 * @return A new bind rule builder whose {@link BindRuleBuilder#build()} method will return a
82 * copy of this bind rule.
83 * @throws UnsupportedOperationException if the bind rule cannot be reconfigured in this manner.
84 */
85 BindRuleBuilder newCopyBuilder();
86
87 /**
88 * Compare this bind rule to another. More-specific bind rules compare less than less-specific
89 * rules.
90 *
91 * <p><b>Note:</b> This implements an ordering inconsistent with {@link Object#equals(Object)}. Equal
92 * rules will compare the same (and implementations are required to enforce this), but unequal
93 * rules may compare equal to each other when compared with this method.
94 *
95 * @param other The bind rule to compare with.
96 * @return The comparison result.
97 * @throws IllegalArgumentException if called with an incompatible bind rule. This should not
98 * arise in practice, but if you implement your own bind rules
99 * they will not be comparable with the ones provided by
100 * Grapht.
101 */
102 @Override
103 int compareTo(BindRule other);
104 }