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 dagger.internal.Beta; 23 import java.lang.annotation.Documented; 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.Target; 26 import javax.inject.Inject; 27 import javax.inject.Qualifier; 28 29 /** 30 * Annotates methods that declare bindings for {@code Optional} containers of values from bindings 31 * that may or may not be present in the component. 32 * 33 * <p>If a module contains a method declaration like this: 34 * 35 * <pre> 36 * {@literal @BindsOptionalOf} abstract Foo optionalFoo();</pre> 37 * 38 * then any binding in the component can depend on an {@code Optional} of {@code Foo}. If there is 39 * no binding for {@code Foo} in the component, the {@code Optional} will be absent. If there is a 40 * binding for {@code Foo} in the component, the {@code Optional} will be present, and its value 41 * will be the value given by the binding for {@code Foo}. 42 * 43 * <p>A {@code @BindsOptionalOf} method: 44 * 45 * <ul> 46 * <li>must be {@code abstract} 47 * <li>may have a {@linkplain Qualifier qualifier} annotation 48 * <li>must not return {@code void} 49 * <li>must not have parameters 50 * <li>must not throw exceptions 51 * <li>must not return an unqualified type with an {@link Inject @Inject}-annotated constructor, 52 * since such a type is always present 53 * </ul> 54 * 55 * <p>Other bindings may inject any of: 56 * 57 * <ul> 58 * <li>{@code Optional<Foo>} (unless there is a {@code @Nullable} binding for {@code Foo}; see 59 * below) 60 * <li>{@code Optional<Provider<Foo>>} 61 * <li>{@code Optional<Lazy<Foo>>} 62 * <li>{@code Optional<Provider<Lazy<Foo>>>} 63 * </ul> 64 * 65 * <p>If there is a binding for {@code Foo}, and that binding is {@code @Nullable}, then it is a 66 * compile-time error to inject {@code Optional<Foo>}, because {@code Optional} cannot contain 67 * {@code null}. You can always inject the other forms, because {@link Provider} and {@link Lazy} 68 * can always return {@code null} from their {@code get()} methods. 69 * 70 * <p>Explicit bindings for any of the above will conflict with a {@code @BindsOptionalOf} binding. 71 * 72 * <p>If the binding for {@code Foo} is a {@code @Produces} binding, then another {@code @Produces} 73 * binding can depend on any of: 74 * 75 * <ul> 76 * <li>{@code Optional<Foo>} 77 * <!-- TODO(dpb): Update this once producers support nullability checks --> 78 * <li>{@code Optional<Producer<Foo>>} 79 * <li>{@code Optional<Produced<Foo>>} 80 * </ul> 81 * 82 * <p>You can inject either {@code com.google.common.base.Optional} or {@code java.util.Optional}. 83 */ 84 @Documented 85 @Beta 86 @Retention(RUNTIME) 87 @Target(METHOD) 88 public @interface BindsOptionalOf {} 89