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}