MapList now uses synchronised lists.

Added explicit documentation on synchronisation.
Minor code tidying and typo fixes.

Fixes issue 4344.

Change-Id: I92b691de235cb5da1ca83133cb6eac451c5973bd
Reviewed-on: http://gerrit.dmdirc.com/1452
Automatic-Compile: DMDirc Local Commits <dmdirc@googlemail.com>
Reviewed-by: Gregory Holmes <greg@dmdirc.com>

src/com/dmdirc/util/MapList.java

@@ -24,6 +24,7 @@ package com.dmdirc.util;
 
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -32,13 +33,22 @@ import java.util.Set;
 /**
  * Wraps a Map<S, List<T>> with various convenience methods for
  * accessing the data. Implements a Map-like interface for easier transition.
- * 
+ * <p>
+ * <strong>Note that this implementation is not synchronized.</strong> If
+ * multiple threads access a <code>MapList</code> instance concurrently, and
+ * at least one of the threads modifies the map, it <em>must</em> be
+ * synchronized externally.
+ * <p>
+ * The <code>List</code>s used to back this map are synchronized using the
+ * {@link Collections#synchronizedList(java.util.List)} method, which requires
+ * manual synchronization in any code iterating over the values.
+ *
  * @param <S> the type of keys maintained by this map
  * @param <T> the type of mapped values
  * @author chris
  */
-public class MapList<S,T> {
-    
+public class MapList<S, T> {
+
     /** Our internal map. */
     protected final Map<S, List<T>> map;
 
@@ -51,17 +61,17 @@ public class MapList<S,T> {
 
     /**
      * Creates a new MapList with the values from the specified list.
-     * 
+     *
      * @param list The MapList whose values should be used
      */
-    public MapList(final MapList<S,T> list) {
+    public MapList(final MapList<S, T> list) {
         map = list.getMap();
     }
 
     /**
      * Determines if this MapList is empty. An empty MapList is one that either
      * contains no keys, or contains only keys which have no associated values.
-     * 
+     *
      * @return True if this MapList is empty, false otherwise
      */
     public boolean isEmpty() {
@@ -70,13 +80,13 @@ public class MapList<S,T> {
                 return false;
             }
         }
-        
+
         return true;
     }
 
     /**
      * Determines if this MapList contains the specified key.
-     * 
+     *
      * @param key The key to look for
      * @return True if this MapList contains the specified key, false otherwise
      */
@@ -87,10 +97,10 @@ public class MapList<S,T> {
     /**
      * Determines if this MapList contains the specified value as a child of
      * the specified key.
-     * 
+     *
      * @param key The key to search under
      * @param value The value to look for
-     * @return True if this MapList contains the specified key/value pair, 
+     * @return True if this MapList contains the specified key/value pair,
      * false otherwise
      */
     public boolean containsValue(final S key, final T value) {
@@ -99,53 +109,53 @@ public class MapList<S,T> {
 
     /**
      * Retrieves the list of values associated with the specified key.
-     * 
+     *
      * @param key The key whose values are being retrieved
      * @return The values belonging to the specified key
      */
     public List<T> get(final S key) {
         return map.get(key);
     }
-    
+
     /**
      * Retrieves the value at the specified offset of the specified key.
-     * 
+     *
      * @param key The key whose values are being retrieved
      * @param index The index of the value to retrieve
      * @return The specified value of the key
-     */    
+     */
     public T get(final S key, final int index) {
         return map.get(key).get(index);
-    }    
-    
+    }
+
     /**
      * Retrieves the list of values associated with the specified key, creating
-     * the key if neccessary.
-     * 
+     * the key if necessary.
+     *
      * @param key The key to retrieve
      * @return A list of the specified key's values
      */
     public List<T> safeGet(final S key) {
         if (!map.containsKey(key)) {
-            map.put(key, new ArrayList<T>());
+            map.put(key, Collections.synchronizedList(new ArrayList<T>()));
         }
-        
+
         return map.get(key);
     }
-    
+
     /**
      * Adds the specified key to the MapList.
-     * 
+     *
      * @param key The key to be added
      */
     public void add(final S key) {
         safeGet(key);
-    }    
+    }
 
     /**
      * Adds the specified value as a child of the specified key. If the key
      * didn't previous exist, it is created.
-     * 
+     *
      * @param key The key to which the value is being added
      * @param value The value to be added
      */
@@ -156,26 +166,26 @@ public class MapList<S,T> {
     /**
      * Adds the specified set of values to the specified key. If the key
      * didn't previous exist, it is created.
-     * 
+     *
      * @param key The key to which the value is being added
      * @param values The values to be added
-     */    
+     */
     public void add(final S key, final Collection<T> values) {
         safeGet(key).addAll(values);
-    }    
+    }
 
     /**
      * Removes the specified key and all of its values.
-     * 
+     *
      * @param key The key to remove
-     */    
+     */
     public void remove(final S key) {
         map.remove(key);
     }
-    
+
     /**
      * Removes the specified value from all keys.
-     * 
+     *
      * @param value The value to remove
      */
     public void removeFromAll(final T value) {
@@ -186,7 +196,7 @@ public class MapList<S,T> {
 
     /**
      * Removes the specified value from the specified key.
-     * 
+     *
      * @param key The key whose value is being removed
      * @param value The value to be removed
      */
@@ -194,7 +204,7 @@ public class MapList<S,T> {
         if (map.containsKey(key)) {
             map.get(key).remove(value);
         }
-    }    
+    }
 
     /**
      * Entirely clears this MapList.
@@ -202,19 +212,19 @@ public class MapList<S,T> {
     public void clear() {
         map.clear();
     }
-    
+
     /**
      * Clears all values of the specified key.
-     * 
+     *
      * @param key The key to be cleared
      */
     public void clear(final S key) {
         safeGet(key).clear();
-    }    
+    }
 
     /**
      * Returns the set of all keys belonging to this MapList.
-     * 
+     *
      * @return This MapList's keyset
      */
     public Set<S> keySet() {
@@ -223,26 +233,26 @@ public class MapList<S,T> {
 
     /**
      * Returns a collection of all values belonging to the specified key.
-     * 
+     *
      * @param key The key whose values are being sought
      * @return A collection of values belonging to the key
      */
     public Collection<T> values(final S key) {
         return map.get(key);
     }
-    
+
     /**
      * Retrieves the entry set for this MapList.
-     * 
+     *
      * @return This MapList's entry set
      */
     public Set<Map.Entry<S, List<T>>> entrySet() {
         return map.entrySet();
     }
-    
+
     /**
      * Retrieves the map behind this maplist.
-     * 
+     *
      * @return This MapList's map.
      */
     public Map<S, List<T>> getMap() {