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;
21
22 import javax.annotation.Nonnull;
23 import javax.annotation.Nullable;
24 import javax.inject.Qualifier;
25 import java.io.Closeable;
26 import java.lang.annotation.Annotation;
27
28 /**
29 * <p>
30 * Injector uses dependency injection to act as a factory for creating instances
31 * with complex dependencies. A default implementation of Injector can easily be
32 * created by using an {@link InjectorBuilder}:
33 *
34 * <pre>
35 * InjectorBuilder b = new InjectorBuilder();
36 * b.bind(Foo.class).to(Bar.class);
37 * b.applyModule(new MyCustomModule());
38 * // other bindings
39 * Injector i = b.build();
40 * assert (i.getInstance(Foo.class) instanceof Bar);
41 * </pre>
42 * <p>
43 * Alternatively, {@link BindingFunctionBuilder} and {@link org.grouplens.grapht.solver.DependencySolver}
44 * can be used to create your own Injector implementations.
45 *
46 * @author <a href="http://grouplens.org">GroupLens Research</a>
47 */
48 public interface Injector extends AutoCloseable {
49 /**
50 * Get an instance of T based on the bindings that this Injector was
51 * configured with. An exception is thrown if the request type cannot be
52 * instantiated with dependency injection.
53 * <p>
54 * Injectors may memoize or cache previously created objects. As an example,
55 * the Injector created by {@link InjectorBuilder} reuses instances where
56 * possible.
57 *
58 * @param <T> The object type being created
59 * @param type The class type
60 * @return An instance of type T
61 * @throws ConstructionException if type cannot be instantiated
62 */
63 @Nonnull
64 <T> T getInstance(Class<T> type) throws InjectionException;
65
66 /**
67 * Get an instance of T with the given {@link Qualifier} annotation.
68 *
69 * @param <T> The object type
70 * @param qualifier The qualifier on of the returned instance
71 * @param type The class type
72 * @return An instance of type T
73 * @throws ConstructionException if type cannot be instantiated
74 */
75 @Nonnull
76 <T> T getInstance(Annotation qualifier, Class<T> type) throws InjectionException;
77
78 /**
79 * Try to get an instance of a component, returning {@code null} if the component
80 * does not have a configured implementation.
81 *
82 * @param qualifier The qualifier, or {@code null} for an unqualified component.
83 * @param type The component type.
84 * @param <T> The component type.
85 * @return An instance of type {@code T}, or {@code null} if no implemenation of {@code T} is configured.
86 * @throws InjectionException if there is some other error injecting the instance.
87 */
88 @Nullable
89 <T> T tryGetInstance(Annotation qualifier, Class<T> type) throws InjectionException;
90
91 /**
92 * Close the injector, shutting down any instantiated components that require shutdown.
93 */
94 void close();
95 }