This project has retired. For details please refer to its Attic page.
Source code
001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.tang;
020
021import org.apache.reef.tang.annotations.Name;
022import org.apache.reef.tang.exceptions.BindException;
023import org.apache.reef.tang.exceptions.InjectionException;
024import org.apache.reef.tang.exceptions.NameResolutionException;
025import org.apache.reef.tang.implementation.InjectionPlan;
026
027public interface Injector {
028
029  /**
030   * Gets an instance of iface, or the implementation that has been bound to it.
031   * If an instance has already been created in this (or a parent) scope, then
032   * the existing instance will be returned. Otherwise, a new instance will be
033   * returned, and registered in the current scope.
034   *
035   * @param <U> a type
036   * @param iface an interface
037   * @return an instance
038   * @throws InjectionException if it fails to find corresponding class
039   */
040  <U> U getInstance(Class<U> iface) throws InjectionException;
041
042  /**
043   * Gets an instance of iface, or the implementation that has been bound to it.
044   * If an instance has already been created in this (or a parent) scope, then
045   * the existing instance will be returned. Otherwise, a new instance will be
046   * returned, and registered in the current scope.
047   *
048   * @param <U> a type
049   * @param iface a name of interface
050   * @return an instance
051   * @throws InjectionException if it fails to find corresponding class
052   * @throws NameResolutionException if name resolution fails
053   */
054  <U> U getInstance(String iface) throws InjectionException,
055      NameResolutionException;
056
057  /**
058   * Gets the value stored for the given named parameter.
059   *
060   * @param <U> a type
061   * @param iface the name of interface
062   * @return an Instance of the class configured as the implementation for the
063   * given interface class.
064   * @throws InjectionException if name resolution fails
065   */
066  <U> U getNamedInstance(Class<? extends Name<U>> iface)
067      throws InjectionException;
068
069  /**
070   * Binds the given object to the class. Note that this only affects objects
071   * created by the returned Injector and its children. Also, like all
072   * Injectors, none of those objects can be serialized back to a configuration
073   * file).
074   *
075   * @param <T> a type
076   * @param iface an interface cass
077   * @param inst an instance
078   * @throws BindException when trying to re-bind
079   */
080  <T> void bindVolatileInstance(Class<T> iface, T inst)
081      throws BindException;
082
083  <T> void bindVolatileParameter(Class<? extends Name<T>> iface, T inst)
084      throws BindException;
085
086  /**
087   * Binds a TANG Aspect to this injector.  Tang Aspects interpose on each
088   * injection performed by an injector, and return an instance of their choosing.
089   * <p>
090   * A given aspect will be invoked once for each object that Tang injects, and aspects
091   * will be copied in a way that mirrors the scoping that Tang creates at runtime.
092   *
093   * @param <T> a type
094   * @param a aspect
095   * @throws BindException if there exists a bound aspect already
096   */
097  <T> void bindAspect(Aspect a) throws BindException;
098
099  /**
100   * Allows InjectionFuture to tell the aspect when get() is invoked.  Package private.
101   *
102   * @return the aspect
103   */
104  Aspect getAspect();
105
106  /**
107   * Create a copy of this Injector that inherits the instances that were already
108   * created by this Injector, but reflects additional Configuration objects.
109   * This can be used to create trees of Injectors that obey hierarchical
110   * scoping rules.
111   * <p>
112   * Except for the fact that the child Injector will have references to this
113   * injector's instances, the returned Injector is equivalent to the one you
114   * would get by using ConfigurationBuilder to build a merged Configuration,
115   * and then using the merged Configuration to create an Injector. Injectors
116   * returned by ConfigurationBuilders are always independent, and never
117   * share references to the same instances of injected objects.
118   *
119   * @param configurations configurations
120   * @return an injector
121   * @throws BindException If any of the configurations conflict with each other, or the
122   *                       existing Injector's Configuration.
123   */
124  Injector forkInjector(Configuration... configurations) throws BindException;
125
126  /**
127   * Returns true if this Injector is able to instantiate the object named by
128   * name.
129   *
130   * @param name a name of object
131   * @return whether the name is injectable
132   * @throws BindException if there is a loop or the name is package name
133   */
134  boolean isInjectable(String name) throws BindException;
135
136  boolean isParameterSet(String name) throws BindException;
137
138  boolean isInjectable(Class<?> clazz) throws BindException;
139
140  boolean isParameterSet(Class<? extends Name<?>> name) throws BindException;
141
142  InjectionPlan<?> getInjectionPlan(String name) throws NameResolutionException;
143
144  <T> InjectionPlan<T> getInjectionPlan(Class<T> name);
145
146  Injector forkInjector();
147}