1 /** 2 * Copyright (C) 2010 Google Inc. 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 com.google.inject.multibindings; 18 19 import com.google.inject.Binding; 20 import com.google.inject.Key; 21 import com.google.inject.TypeLiteral; 22 import com.google.inject.spi.Element; 23 import com.google.inject.spi.Elements; 24 25 import java.util.List; 26 import java.util.Map; 27 28 /** 29 * A binding for a MapBinder. 30 * <p> 31 * Although MapBinders may be injected through a variety of generic types (Map<K, V>, Map 32 * <K, Provider<V>>, Map<K, Set<V>>, Map<K, Set< 33 * Provider<V>>, and even Set<Map.Entry<K, Provider<V>>), a 34 * MapBinderBinding exists only on the Binding associated with the Map<K, V> key. Other 35 * bindings can be validated to be derived from this MapBinderBinding using 36 * {@link #containsElement(Element)}. 37 * 38 * @param <T> The fully qualified type of the map, including Map. For example: 39 * <code>MapBinderBinding<Map<String, Snack>></code> 40 * 41 * @since 3.0 42 * @author sameb (at) google.com (Sam Berlin) 43 */ 44 public interface MapBinderBinding<T> { 45 46 /** Returns the {@link Key} for the map. */ 47 Key<T> getMapKey(); 48 49 /** 50 * Returns the TypeLiteral describing the keys of the map. 51 * <p> 52 * The TypeLiteral will always match the type Map's generic type. For example, if getMapKey 53 * returns a key of <code>Map<String, Snack></code>, then this will always return a 54 * <code>TypeLiteral<String></code>. 55 */ 56 TypeLiteral<?> getKeyTypeLiteral(); 57 58 /** 59 * Returns the TypeLiteral describing the values of the map. 60 * <p> 61 * The TypeLiteral will always match the type Map's generic type. For example, if getMapKey 62 * returns a key of <code>Map<String, Snack></code>, then this will always return a 63 * <code>TypeLiteral<Snack></code>. 64 */ 65 TypeLiteral<?> getValueTypeLiteral(); 66 67 /** 68 * Returns all entries in the Map. The returned list of Map.Entries contains the key and a binding 69 * to the value. Duplicate keys or values will exist as separate Map.Entries in the returned list. 70 * This is only supported on bindings returned from an injector. This will throw 71 * {@link UnsupportedOperationException} if it is called on an element retrieved from 72 * {@link Elements#getElements}. 73 * <p> 74 * The elements will always match the type Map's generic type. For example, if getMapKey returns a 75 * key of <code>Map<String, Snack></code>, then this will always return a list of type 76 * <code>List<Map.Entry<String, Binding<Snack>>></code>. 77 */ 78 List<Map.Entry<?, Binding<?>>> getEntries(); 79 80 /** 81 * Returns true if the MapBinder permits duplicates. This is only supported on bindings returned 82 * from an injector. This will throw {@link UnsupportedOperationException} if it is called on a 83 * MapBinderBinding retrieved from {@link Elements#getElements}. 84 */ 85 boolean permitsDuplicates(); 86 87 /** 88 * Returns true if this MapBinder contains the given Element in order to build the map or uses the 89 * given Element in order to support building and injecting the map. This will work for 90 * MapBinderBindings retrieved from an injector and {@link Elements#getElements}. Usually this is 91 * only necessary if you are working with elements retrieved from modules (without an Injector), 92 * otherwise {@link #getEntries} and {@link #permitsDuplicates} are better options. 93 * <p> 94 * If you need to introspect the details of the map, such as the keys, values or if it permits 95 * duplicates, it is necessary to pass the elements through an Injector and use 96 * {@link #getEntries()} and {@link #permitsDuplicates()}. 97 */ 98 boolean containsElement(Element element); 99 } 100
