1 /* 2 * Copyright (C) 2016 The Dagger Authors. 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 dagger; 18 19 import static java.lang.annotation.ElementType.METHOD; 20 import static java.lang.annotation.RetentionPolicy.RUNTIME; 21 22 import java.lang.annotation.Documented; 23 import java.lang.annotation.Retention; 24 import java.lang.annotation.Target; 25 26 /** 27 * Annotates <em>abstract</em> methods of a {@link Module} that delegate bindings. For example, to 28 * bind {@link java.util.Random} to {@link java.security.SecureRandom} a module could declare the 29 * following: {@code @Binds abstract Random bindRandom(SecureRandom secureRandom);} 30 * 31 * <p>{@code @Binds} methods are a drop-in replacement for {@link Provides} methods that simply 32 * return an injected parameter. Prefer {@code @Binds} because the generated implementation is 33 * likely to be more efficient. 34 * 35 * <p>A {@code @Binds} method: 36 * 37 * <ul> 38 * <li>Must be {@code abstract}. 39 * <li>May be {@linkplain javax.inject.Scope scoped}. 40 * <li>May be {@linkplain javax.inject.Qualifier qualified}. 41 * <li>Must have a single parameter whose type is assignable to the return type. The return type 42 * declares the bound type (just as it would for a {@literal @}{@link dagger.Provides} method) 43 * and the parameter is the type to which it is bound. 44 * <p>For {@linkplain dagger.multibindings multibindings}, assignability is checked in similar 45 * ways: 46 * <dl> 47 * <dt>{@link dagger.multibindings.IntoSet} 48 * <dd>The parameter must be assignable to the only parameter of {@link java.util.Set#add} 49 * when viewed as a member of the return type — the parameter must be assignable to the 50 * return type. 51 * <dt>{@link dagger.multibindings.ElementsIntoSet} 52 * <dd>The parameter must be assignable to the only parameter of {@link 53 * java.util.Set#addAll} when viewed as a member of the return type — if the return type 54 * is {@code Set<E>}, the parameter must be assignable to {@code Collection<? extends 55 * E>}. 56 * <dt>{@link dagger.multibindings.IntoMap} 57 * <dd>The parameter must be assignable to the {@code value} parameter of {@link 58 * java.util.Map#put} when viewed as a member of a {@link java.util.Map} in which {@code 59 * V} is bound to the return type — the parameter must be assignable to the return type 60 * </dl> 61 * </ul> 62 */ 63 @Documented 64 @Retention(RUNTIME) 65 @Target(METHOD) 66 public @interface Binds {} 67