001 /**
002 Licensed to the Apache Software Foundation (ASF) under one or more
003 contributor license agreements. See the NOTICE file distributed with
004 this work for additional information regarding copyright ownership.
005 The ASF licenses this file to You under the Apache License, Version 2.0
006 (the "License"); you may not use this file except in compliance with
007 the License. You may obtain a copy of the License at
008
009 http://www.apache.org/licenses/LICENSE-2.0
010
011 Unless required by applicable law or agreed to in writing, software
012 distributed under the License is distributed on an "AS IS" BASIS,
013 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 See the License for the specific language governing permissions and
015 limitations under the License.
016 */
017 package org.apache.commons.inject.api;
018
019 /**
020 * The {@link IInjector injector} is used to build objects for your application.
021 * It does so by maintaining a map of {@link IKey keys} and associated
022 * {@link IBinding bindings}. The map is created by {@link IModule modules}.
023 *
024 * Some bindings are present automatically:
025 * - The {@link Injector} itself.
026 * - For any {@link IBinding IBinding<T>} (binding of type T), there is also
027 * a {@link IProvider provider} of type T.
028 *
029 * To create an {@link IInjector injector}, use the class {@link CommonsInject}.
030 */
031 public interface IInjector {
032 /**
033 * Returns an instance of {@code pType}, if a matching binding is present.
034 * This is a shortcut for
035 * <pre>
036 * getInstance(pType, "")
037 * </pre>
038 * or
039 * <pre>
040 * getInstance(pType, Key.NO_NAME)
041 * </pre>
042 * @param pType The requested type.
043 * @return The created instance, or null.
044 * @see #getInstance(Class, String)
045 * @see #getInstance(IKey)
046 * @see #requireInstance(Class)
047 */
048 <T> T getInstance(Class<T> pType);
049 /**
050 * Returns an instance of the given type, with the given name, if a
051 * matching binding is present. This is a shortcut for
052 * <pre>
053 * Key key = new Key(pType, pName);
054 * getInstance(key)
055 * </pre>
056 * or
057 * <pre>
058 * Key key = new Key(pType, pName, Key.NO_ANNOTATIONS);
059 * getInstance(key)
060 * </pre>
061 * @param pType The requested type.
062 * @param pName The requested objects name.
063 * @return The created instance, or null.
064 * @see #getInstance(IKey)
065 * @see #requireInstance(Class, String)
066 */
067 <T> T getInstance(Class<T> pType, String pName);
068 /**
069 * Returns an instance of the binding that has been registered for the
070 * given key.
071 * @param pKey A binding key, for which a binding has been registered.
072 * @return The created instance, or null.
073 * @see #getInstance(Class)
074 * @see #getInstance(Class, String)
075 * @see #requireInstance(IKey)
076 */
077 <T> T getInstance(IKey<T> pKey);
078
079 /**
080 * Returns an instance of {@code pType}, if a matching binding is present.
081 * This is a shortcut for
082 * <pre>
083 * requireInstance(pType, "")
084 * </pre>
085 * or
086 * <pre>
087 * requireInstance(pType, Key.NO_NAME)
088 * </pre>
089 * @param pType The requested type.
090 * @return The created instance.
091 * @throws NoSuchBindingException No matching binding has been registered with
092 * the injector.
093 * @see #getInstance(Class, String)
094 * @see #getInstance(IKey)
095 * @see #requireInstance(Class)
096 */
097 <T> T requireInstance(Class<T> pType) throws NoSuchBindingException;
098 /**
099 * Returns an instance of the given type, with the given name, if a
100 * matching binding is present. This is a shortcut for
101 * <pre>
102 * Key key = new Key(pType, pName);
103 * requireInstance(key)
104 * </pre>
105 * or
106 * <pre>
107 * Key key = new Key(pType, pName, Key.NO_ANNOTATIONS);
108 * requireInstance(key)
109 * </pre>
110 * @param pType The requested type.
111 * @param pName The requested objects name.
112 * @return The created instance.
113 * @throws NoSuchBindingException No matching binding has been registered with
114 * the injector.
115 * @see #getInstance(Class, String)
116 * @see #requireInstance(Class)
117 * @see #requireInstance(IKey)
118 */
119 <T> T requireInstance(Class<T> pType, String pName) throws NoSuchBindingException;
120 /**
121 * Returns an instance of the binding that has been registered for the
122 * given key.
123 * @param pKey A binding key, for which a binding has been registered.
124 * @return The created instance.
125 * @throws NoSuchBindingException No matching binding has been registered with
126 * the injector.
127 * @see #getInstance(IKey)
128 * @see #requireInstance(Class)
129 * @see #requireInstance(Class, String)
130 */
131 <T> T requireInstance(IKey<T> pKey) throws NoSuchBindingException;
132
133 /**
134 * Injects members into the given instance, as if it where created by
135 * the {@link IInjector injector} itself. In other words, fills fields
136 * and invokes methods annotated with @Inject, assuming that a binding
137 * is present for those fields, and method parameters.
138 */
139 void injectMembers(Object pInstance);
140 }