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.reflect;
21
22 import org.grouplens.grapht.*;
23
24 import javax.annotation.Nonnull;
25 import javax.annotation.Nullable;
26 import javax.inject.Singleton;
27 import java.io.Serializable;
28 import java.lang.reflect.Type;
29 import java.util.List;
30 import java.util.Map;
31
32
33 /**
34 * A concrete type. It has a set of dependencies which must be satisfied in
35 * order to instantiate it. It can also be viewed as an instantiable extension
36 * of {@link Type}.
37 * <p>
38 * Satisfactions are expected to provide a reasonable implementation of
39 * {@link Object#equals(Object)} and {@link Object#hashCode()} so that they can
40 * be de-duplicated, etc.
41 *
42 * @author <a href="http://grouplens.org">GroupLens Research</a>
43 */
44 public interface Satisfaction extends Serializable {
45 /**
46 * Get this satisfaction's dependencies.
47 *
48 * @return A list of dependencies which must be satisfied in order to
49 * instantiate this satisfaction.
50 */
51 List<Desire> getDependencies();
52
53 /**
54 * Get the type of this satisfaction. If this is a synthetic Satisfaction,
55 * then a null type is returned.
56 *
57 * @return The type of objects to be instantiated by this satisfaction.
58 */
59 Type getType();
60
61 /**
62 * Get the type-erased class of this satisfaction's type. If this is a
63 * synthetic Satisfaction, then null is returned.
64 *
65 * @return The class object for this satisfaction's type.
66 */
67 Class<?> getErasedType();
68
69 /**
70 * Query whether this satisfaction already has an instance to return. If
71 * true, then this satisfaction's provider will just return an instance
72 * that is already in existence; if false, then its provider may create
73 * new instances.
74 *
75 * @return whether the satisfaction already has an instance.
76 */
77 boolean hasInstance();
78
79 /**
80 * Visit the satisfaction. This method invokes the appropriate method on the
81 * provided visitor to report information on itself.
82 *
83 * @param visitor The visitor object.
84 * @param <T> The type returned from the visitor.
85 * @return The return value from the invoked visitor method.
86 */
87 <T> T visit(SatisfactionVisitor<T> visitor);
88
89 /**
90 * Get the default cache policy for instances created by this satisfaction.
91 * In most cases this should be NO_PREFERENCE, but annotations such as
92 * {@link Singleton} can be used to specify a default. BindingFunctions are
93 * allowed to overrule the default cache policy.
94 *
95 * @return The default cache policy if no function overrules it
96 */
97 CachePolicy getDefaultCachePolicy();
98
99 /**
100 * <p>
101 * Create an instantiator from this satisfaction.
102 * <p>
103 * If the details of the Satisfaction require instantiation (e.g. a class or
104 * provider class satisfaction), the returned provider should be a new
105 * instance, and it should perform no memoization of its own. Caching is the
106 * purview of {@link Injector} implementations.
107 * <p>
108 * If the satisfaction is configured to use specific instances, this rule is
109 * obviously void.
110 *
111 * @param dependencies A function mapping desires to providers of their
112 * instances.
113 * @param lm The lifecycle manager (if one should be used).
114 * @return An instantiator of new instances of the type specified by this
115 * satisfaction, instantiated using the specified dependency
116 * mapping.
117 */
118 Instantiator makeInstantiator(@Nonnull Map<Desire,Instantiator> dependencies,
119 @Nullable LifecycleManager lm);
120 }