1 /* 2 * Copyright (C) 2009 The JSR-330 Expert Group 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package javax.inject; 18 19 /** 20 * Provides instances of {@code T}. Typically implemented by an injector. For 21 * any type {@code T} that can be injected, you can also inject 22 * {@code Provider<T>}. Compared to injecting {@code T} directly, injecting 23 * {@code Provider<T>} enables: 24 * 25 * <ul> 26 * <li>retrieving multiple instances.</li> 27 * <li>lazy or optional retrieval of an instance.</li> 28 * <li>breaking circular dependencies.</li> 29 * <li>abstracting scope so you can look up an instance in a smaller scope 30 * from an instance in a containing scope.</li> 31 * </ul> 32 * 33 * <p>For example: 34 * 35 * <pre> 36 * class Car { 37 * @Inject Car(Provider<Seat> seatProvider) { 38 * Seat driver = seatProvider.get(); 39 * Seat passenger = seatProvider.get(); 40 * ... 41 * } 42 * }</pre> 43 */ 44 public interface Provider<T> { 45 46 /** 47 * Provides a fully-constructed and injected instance of {@code T}. 48 * 49 * @throws RuntimeException if the injector encounters an error while 50 * providing an instance. For example, if an injectable member on 51 * {@code T} throws an exception, the injector may wrap the exception 52 * and throw it to the caller of {@code get()}. Callers should not try 53 * to handle such exceptions as the behavior may vary across injector 54 * implementations and even different configurations of the same injector. 55 */ 56 T get(); 57 } 58
