You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 lines
3.6 KiB
117 lines
3.6 KiB
/*
|
|
* Copyright (C) 2014 The Dagger Authors.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
package dagger;
|
|
|
|
import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
|
|
import static java.lang.annotation.RetentionPolicy.RUNTIME;
|
|
|
|
import java.lang.annotation.Documented;
|
|
import java.lang.annotation.Retention;
|
|
import java.lang.annotation.Target;
|
|
import java.util.Map;
|
|
|
|
/**
|
|
* Identifies annotation types that are used to associate keys with values returned by {@linkplain
|
|
* Provides provider methods} in order to compose a {@linkplain dagger.multibindings.IntoMap map}.
|
|
*
|
|
* <p>Every provider method annotated with {@code @Provides} and {@code @IntoMap} must also have an
|
|
* annotation that identifies the key for that map entry. That annotation's type must be annotated
|
|
* with {@code @MapKey}.
|
|
*
|
|
* <p>Typically, the key annotation has a single member, whose value is used as the map key.
|
|
*
|
|
* <p>For example, to add an entry to a {@code Map<SomeEnum, Integer>} with key {@code
|
|
* SomeEnum.FOO}, you could use an annotation called {@code @SomeEnumKey}:
|
|
*
|
|
* <pre><code>
|
|
* {@literal @}MapKey
|
|
* {@literal @}interface SomeEnumKey {
|
|
* SomeEnum value();
|
|
* }
|
|
*
|
|
* {@literal @}Module
|
|
* class SomeModule {
|
|
* {@literal @}Provides
|
|
* {@literal @}IntoMap
|
|
* {@literal @}SomeEnumKey(SomeEnum.FOO)
|
|
* Integer provideFooValue() {
|
|
* return 2;
|
|
* }
|
|
* }
|
|
*
|
|
* class SomeInjectedType {
|
|
* {@literal @}Inject
|
|
* SomeInjectedType({@literal Map<SomeEnum, Integer>} map) {
|
|
* assert map.get(SomeEnum.FOO) == 2;
|
|
* }
|
|
* }
|
|
* </code></pre>
|
|
*
|
|
* <p>If {@code unwrapValue} is true, the annotation's single member can be any type except an
|
|
* array.
|
|
*
|
|
* <p>See {@link dagger.multibindings} for standard unwrapped map key annotations for keys that are
|
|
* boxed primitives, strings, or classes.
|
|
*
|
|
* <h2>Annotations as keys</h2>
|
|
*
|
|
* <p>If {@link #unwrapValue} is false, then the annotation itself is used as the map key. For
|
|
* example, to add an entry to a {@code Map<MyMapKey, Integer>} map:
|
|
*
|
|
* <pre><code>
|
|
* {@literal @}MapKey(unwrapValue = false)
|
|
* {@literal @}interface MyMapKey {
|
|
* String someString();
|
|
* MyEnum someEnum();
|
|
* }
|
|
*
|
|
* {@literal @}Module
|
|
* class SomeModule {
|
|
* {@literal @}Provides
|
|
* {@literal @}IntoMap
|
|
* {@literal @}MyMapKey(someString = "foo", someEnum = BAR)
|
|
* Integer provideFooBarValue() {
|
|
* return 2;
|
|
* }
|
|
* }
|
|
*
|
|
* class SomeInjectedType {
|
|
* {@literal @}Inject
|
|
* SomeInjectedType({@literal Map<MyMapKey, Integer>} map) {
|
|
* assert map.get(new MyMapKeyImpl("foo", MyEnum.BAR)) == 2;
|
|
* }
|
|
* }
|
|
* </code></pre>
|
|
*
|
|
* <p>(Note that there must be a class {@code MyMapKeyImpl} that implements {@code MyMapKey} in
|
|
* order to call {@link Map#get(Object)} on the provided map.)
|
|
*
|
|
* @see <a href="https://dagger.dev/multibindings#map-multibindings">Map multibinding</a>
|
|
*/
|
|
@Documented
|
|
@Target(ANNOTATION_TYPE)
|
|
@Retention(RUNTIME)
|
|
public @interface MapKey {
|
|
/**
|
|
* True to use the value of the single member of the annotated annotation as the map key; false
|
|
* to use the annotation instance as the map key.
|
|
*
|
|
* <p>If true, the single member must not be an array.
|
|
*/
|
|
boolean unwrapValue() default true;
|
|
}
|