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 }