001 /**
002 * <copyright>
003 *
004 * Copyright (c) 2002-2006 IBM Corporation and others.
005 * All rights reserved. This program and the accompanying materials
006 * are made available under the terms of the Eclipse Public License v1.0
007 * which accompanies this distribution, and is available at
008 * http://www.eclipse.org/legal/epl-v10.html
009 *
010 * Contributors:
011 * IBM - Initial API and implementation
012 *
013 * </copyright>
014 *
015 * $Id: EMap.java,v 1.4 2007/06/12 20:56:17 emerks Exp $
016 */
017 package org.eclipse.emf.common.util;
018
019
020 import java.util.Collection;
021 import java.util.Map;
022 import java.util.Set;
023
024
025 /**
026 * A list of {@link java.util.Map.Entry java.util.Map.Entry} instances, i.e., entries, that
027 * supports a {@link #map} view
028 * as well as the full {@link java.util.Map} API,
029 * with the notable exception of {@link java.util.Map#remove(Object)}.
030 * It's return type conflicts with that of {@link java.util.Collection#remove(Object)}.
031 * The {@link #removeKey removeKey(Object)} method may be used instead.
032 * The implementation of remove may delegate to <code>removeKey</code>
033 * for an object that is not an instance of <code>Map.Entry</code>.
034 */
035 public interface EMap<K, V> extends EList<Map.Entry<K, V>>
036 {
037 /**
038 * Returns the value associated with the key.
039 * The key, the value, or both may be <code>null</code>.
040 * @param key the key of the value.
041 * @return the value associated with the key.
042 */
043 V get(Object key);
044
045 /**
046 * Associates the key with the value
047 * and returns the value previously associated with the key, or <code>null</code>.
048 * The key, the value, or both may be <code>null</code>.
049 * Either the existing entry is updated,
050 * or a new entry is added to the end of the list.
051 * @param key the key of the value.
052 * @param value the value associated with the key.
053 * @return the value formerly associated with the key, or <code>null</code>.
054 */
055 V put(K key, V value);
056
057 /**
058 * Puts each {@link java.util.Map.Entry Map.Entry} of the given map into this one.
059 * @param map the map of entries.
060 * @see #put
061 */
062 void putAll(Map<? extends K, ? extends V> map);
063
064 /**
065 * Puts each {@link java.util.Map.Entry Map.Entry} of the given map into this one.
066 * @param map the map of entries.
067 * @see #put
068 */
069 void putAll(EMap<? extends K, ? extends V> map);
070
071 /**
072 * Returns the index in the list of the entry with the given key,
073 * or <code>-1</code>, if there is no such entry.
074 * @param key a key.
075 * @return the index of the entry with the given key.
076 */
077 int indexOfKey(Object key);
078
079 /**
080 * Returns whether the key is associated with a value.
081 * @param key a key associated with a value.
082 * @return whether the key is associated with a value.
083 */
084 boolean containsKey(Object key);
085
086 /**
087 * Returns whether the value is associated with a key.
088 * @param value a value associated with a key.
089 * @return whether the value is associated with a key.
090 */
091 boolean containsValue(Object value);
092
093 /**
094 * Disassociates the key from its value,
095 * and returns the value formerly associated with the key.
096 * An entry is removed from the list, if the key is found.
097 * @param key the key of a value.
098 * @return the value formerly associated with the key.
099 *
100 */
101 V removeKey(Object key);
102
103 /**
104 * Returns a map view.
105 * @return a map view.
106 */
107 Map<K, V> map();
108
109 /**
110 * Returns a set view of the entries.
111 * @return a set view of the entries.
112 */
113 Set<Map.Entry<K, V>> entrySet();
114
115 /**
116 * Returns a set view of the keys of the entries.
117 * @return a set view of the keys of the entries.
118 */
119 Set<K> keySet();
120
121 /**
122 * Returns a collection view the values of the entries.
123 * @return a collection view the values of the entries.
124 */
125 Collection<V> values();
126
127 /**
128 * An internal interface implemented by the {@link #map() map view}.
129 * It provides access to the EMap view.
130 */
131 interface InternalMapView<K, V> extends Map<K, V>
132 {
133 /**
134 * Returns the EMap view of the map.
135 * @return the EMap view of the map.
136 */
137 EMap<K, V> eMap();
138 }
139 }