View Javadoc

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 }