File Source: MapList.java
/*
P/P * Method: com.dmdirc.util.MapList__static_init
*/
1 /*
2 * Copyright (c) 2006-2009 Chris Smith, Shane Mc Cormack, Gregory Holmes
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to deal
6 * in the Software without restriction, including without limitation the rights
7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 * copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 * SOFTWARE.
21 */
22
23 package com.dmdirc.util;
24
25 import java.util.ArrayList;
26 import java.util.Collection;
27 import java.util.HashMap;
28 import java.util.List;
29 import java.util.Map;
30 import java.util.Set;
31
32 /**
33 * Wraps a Map<S, List<T>> with various convenience methods for
34 * accessing the data. Implements a Map-like interface for easier transition.
35 *
36 * @param <S> the type of keys maintained by this map
37 * @param <T> the type of mapped values
38 * @author chris
39 */
40 public class MapList<S,T> {
41
42 /** Our internal map. */
43 protected final Map<S, List<T>> map;
44
45 /**
46 * Creates a new, empty MapList.
47 */
/*
P/P * Method: void com.dmdirc.util.MapList()
*
* Postconditions:
* this.map == &new HashMap(MapList#1)
* new HashMap(MapList#1) num objects == 1
*/
48 public MapList() {
49 map = new HashMap<S, List<T>>();
50 }
51
52 /**
53 * Creates a new MapList with the values from the specified list.
54 *
55 * @param list The MapList whose values should be used
56 */
/*
P/P * Method: void com.dmdirc.util.MapList(MapList)
*
* Preconditions:
* list != null
*
* Postconditions:
* this.map == &new HashMap(getMap#1)
* new HashMap(getMap#1) num objects == 1
*/
57 public MapList(final MapList<S,T> list) {
58 map = list.getMap();
59 }
60
61 /**
62 * Determines if this MapList is empty. An empty MapList is one that either
63 * contains no keys, or contains only keys which have no associated values.
64 *
65 * @return True if this MapList is empty, false otherwise
66 */
67 public boolean isEmpty() {
/*
P/P * Method: bool isEmpty()
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Iterator:next(...)@68 != null
* java.util.Map:values(...)@68 != null
*
* Postconditions:
* init'ed(return_value)
*
* Test Vectors:
* java.util.Iterator:hasNext(...)@68: {0}, {1}
* java.util.List:isEmpty(...)@69: {1}, {0}
*/
68 for (List<T> list : map.values()) {
69 if (!list.isEmpty()) {
70 return false;
71 }
72 }
73
74 return true;
75 }
76
77 /**
78 * Determines if this MapList contains the specified key.
79 *
80 * @param key The key to look for
81 * @return True if this MapList contains the specified key, false otherwise
82 */
83 public boolean containsKey(final S key) {
/*
P/P * Method: bool containsKey(Object)
*
* Preconditions:
* this.map != null
*
* Postconditions:
* init'ed(return_value)
*/
84 return map.containsKey(key);
85 }
86
87 /**
88 * Determines if this MapList contains the specified value as a child of
89 * the specified key.
90 *
91 * @param key The key to search under
92 * @param value The value to look for
93 * @return True if this MapList contains the specified key/value pair,
94 * false otherwise
95 */
96 public boolean containsValue(final S key, final T value) {
/*
P/P * Method: bool containsValue(Object, Object)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Map:get(...)@97 != null
*
* Postconditions:
* init'ed(return_value)
*/
97 return map.containsKey(key) && map.get(key).contains(value);
98 }
99
100 /**
101 * Retrieves the list of values associated with the specified key.
102 *
103 * @param key The key whose values are being retrieved
104 * @return The values belonging to the specified key
105 */
106 public List<T> get(final S key) {
/*
P/P * Method: List get(Object)
*
* Preconditions:
* this.map != null
*
* Postconditions:
* init'ed(return_value)
*/
107 return map.get(key);
108 }
109
110 /**
111 * Retrieves the value at the specified offset of the specified key.
112 *
113 * @param key The key whose values are being retrieved
114 * @param index The index of the value to retrieve
115 * @return The specified value of the key
116 */
117 public T get(final S key, final int index) {
/*
P/P * Method: Object get(Object, int)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Map:get(...)@118 != null
*
* Postconditions:
* init'ed(return_value)
*/
118 return map.get(key).get(index);
119 }
120
121 /**
122 * Retrieves the list of values associated with the specified key, creating
123 * the key if neccessary.
124 *
125 * @param key The key to retrieve
126 * @return A list of the specified key's values
127 */
128 public List<T> safeGet(final S key) {
/*
P/P * Method: List safeGet(Object)
*
* Preconditions:
* this.map != null
*
* Postconditions:
* init'ed(return_value)
*
* Test Vectors:
* java.util.Map:containsKey(...)@129: {1}, {0}
*/
129 if (!map.containsKey(key)) {
130 map.put(key, new ArrayList<T>());
131 }
132
133 return map.get(key);
134 }
135
136 /**
137 * Adds the specified key to the MapList.
138 *
139 * @param key The key to be added
140 */
141 public void add(final S key) {
/*
P/P * Method: void add(Object)
*
* Preconditions:
* this.map != null
*/
142 safeGet(key);
143 }
144
145 /**
146 * Adds the specified value as a child of the specified key. If the key
147 * didn't previous exist, it is created.
148 *
149 * @param key The key to which the value is being added
150 * @param value The value to be added
151 */
152 public void add(final S key, final T value) {
/*
P/P * Method: void add(Object, Object)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Map:get(...)@133 != null
* java.util.Map:get(...)@52 != null
*/
153 safeGet(key).add(value);
154 }
155
156 /**
157 * Adds the specified set of values to the specified key. If the key
158 * didn't previous exist, it is created.
159 *
160 * @param key The key to which the value is being added
161 * @param values The values to be added
162 */
163 public void add(final S key, final Collection<T> values) {
/*
P/P * Method: void add(Object, Collection)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Map:get(...)@133 != null
* java.util.Map:get(...)@52 != null
*/
164 safeGet(key).addAll(values);
165 }
166
167 /**
168 * Removes the specified key and all of its values.
169 *
170 * @param key The key to remove
171 */
172 public void remove(final S key) {
/*
P/P * Method: void remove(Object)
*
* Preconditions:
* this.map != null
*/
173 map.remove(key);
174 }
175
176 /**
177 * Removes the specified value from all keys.
178 *
179 * @param value The value to remove
180 */
181 public void removeFromAll(final T value) {
/*
P/P * Method: void removeFromAll(Object)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Iterator:next(...)@182 != null
* java.util.Map:values(...)@182 != null
*
* Test Vectors:
* java.util.Iterator:hasNext(...)@182: {0}, {1}
*/
182 for (List<T> list : map.values()) {
183 list.remove(value);
184 }
185 }
186
187 /**
188 * Removes the specified value from the specified key.
189 *
190 * @param key The key whose value is being removed
191 * @param value The value to be removed
192 */
193 public void remove(final S key, final T value) {
/*
P/P * Method: void remove(Object, Object)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Map:get(...)@195 != null
*
* Test Vectors:
* java.util.Map:containsKey(...)@194: {0}, {1}
*/
194 if (map.containsKey(key)) {
195 map.get(key).remove(value);
196 }
197 }
198
199 /**
200 * Entirely clears this MapList.
201 */
202 public void clear() {
/*
P/P * Method: void clear()
*
* Preconditions:
* this.map != null
*/
203 map.clear();
204 }
205
206 /**
207 * Clears all values of the specified key.
208 *
209 * @param key The key to be cleared
210 */
211 public void clear(final S key) {
/*
P/P * Method: void clear(Object)
*
* Preconditions:
* this.map != null
*
* Presumptions:
* java.util.Map:get(...)@133 != null
* java.util.Map:get(...)@52 != null
*/
212 safeGet(key).clear();
213 }
214
215 /**
216 * Returns the set of all keys belonging to this MapList.
217 *
218 * @return This MapList's keyset
219 */
220 public Set<S> keySet() {
/*
P/P * Method: Set keySet()
*
* Preconditions:
* this.map != null
*
* Postconditions:
* init'ed(return_value)
*/
221 return map.keySet();
222 }
223
224 /**
225 * Returns a collection of all values belonging to the specified key.
226 *
227 * @param key The key whose values are being sought
228 * @return A collection of values belonging to the key
229 */
230 public Collection<T> values(final S key) {
/*
P/P * Method: Collection values(Object)
*
* Preconditions:
* this.map != null
*
* Postconditions:
* init'ed(return_value)
*/
231 return map.get(key);
232 }
233
234 /**
235 * Retrieves the entry set for this MapList.
236 *
237 * @return This MapList's entry set
238 */
239 public Set<Map.Entry<S, List<T>>> entrySet() {
/*
P/P * Method: Set entrySet()
*
* Preconditions:
* this.map != null
*
* Postconditions:
* init'ed(return_value)
*/
240 return map.entrySet();
241 }
242
243 /**
244 * Retrieves the map behind this maplist.
245 *
246 * @return This MapList's map.
247 */
248 public Map<S, List<T>> getMap() {
/*
P/P * Method: Map getMap()
*
* Postconditions:
* return_value == &new HashMap(getMap#1)
* new HashMap(getMap#1) num objects == 1
*/
249 return new HashMap<S, List<T>>(map);
250 }
251
252 }
SofCheck Inspector Build Version : 2.17854
| MapList.java |
2009-Jun-25 01:54:24 |
| MapList.class |
2009-Sep-02 17:04:11 |