1 /* 2 * Copyright (C) 2020 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.assisted; 18 19 import static java.lang.annotation.ElementType.PARAMETER; 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 a parameter within an {@link AssistedInject}-annotated constructor. 28 * 29 * <p>See {@link AssistedInject}. 30 */ 31 @Documented 32 @Retention(RUNTIME) 33 @Target(PARAMETER) 34 public @interface Assisted { 35 36 /** 37 * Returns an identifier for an {@link Assisted} parameter. 38 * 39 * <p>Within an {@link AssistedInject} constructor, each {@link Assisted} parameter must be 40 * uniquely defined by the combination of its identifier and type. If no identifier is specified, 41 * the default identifier is an empty string. Thus, the following parameters are equivalent within 42 * an {@link AssistedInject} constructor: 43 * 44 * <ul> 45 * <li> {@code @Assisted Foo foo} 46 * <li> {@code @Assisted("") Foo foo} 47 * </ul> 48 * 49 * <p>Within an {@link AssistedFactory} method, each parameter must match an {@link Assisted} 50 * parameter in the associated {@link AssistedInject} constructor (i.e. identifier + type). 51 * A parameter with no {@code @Assisted} annotation will be assigned the default identifier. Thus, 52 * the following parameters are equivalent within an {@link AssistedFactory} method: 53 * 54 * <ul> 55 * <li> {@code Foo foo} 56 * <li> {@code @Assisted Foo foo} 57 * <li> {@code @Assisted("") Foo foo} 58 * </ul> 59 * 60 * <p>Example: 61 * 62 * <pre><code> 63 * final class DataService { 64 * {@literal @}AssistedInject 65 * DataService( 66 * BindingFromDagger bindingFromDagger, 67 * {@literal @}Assisted String name, 68 * {@literal @}Assisted("id") String id, 69 * {@literal @}Assisted("repo") String repo) {} 70 * } 71 * 72 * {@literal @}AssistedFactory 73 * interface DataServiceFactory { 74 * DataService create( 75 * String name, 76 * {@literal @}Assisted("id") String id, 77 * {@literal @}Assisted("repo") String repo); 78 * } 79 * </code></pre> 80 */ value()81 String value() default ""; 82 } 83