Collections Data Structure Java

/* 
 * JCommon : a free general purpose class library for the Java(tm) platform
 * 
 *
 * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
 * 
 * Project Info:  http://www.jfree.org/jcommon/index.html
 *
 * This library is free software; you can redistribute it and/or modify it 
 * under the terms of the GNU Lesser General Public License as published by 
 * the Free Software Foundation; either version 2.1 of the License, or 
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but 
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
 * License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
 * USA.  
 *
 * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
 * in the United States and other countries.]
 *
 * -------------
 * HashNMap.java
 * -------------
 * (C)opyright 2002-2005, by Thomas Morgner and Contributors.
 *
 * Original Author:  Thomas Morgner;
 * Contributor(s):   David Gilbert (for Object Refinery Limited);
 *
 * $Id: HashNMap.java,v 1.7 2005/10/18 13:24:19 mungady Exp $
 *
 * Changes
 * -------
 * 20-May-2002 : Initial version
 * 10-Dec-2002 : Minor Javadoc updates (DG);
 * 29-Jul-2004 : Replaced 'enum' variable name (reserved word in JDK 1.5) (DG);
 * 12-Mar-2005 : Some performance improvements, this implementation is no 
 *               longer forced to use ArrayLists, add/put behaviour changed to 
 *               fit the common behaviour of collections.
 *
 */
import java.io.Serializable;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.Set;
/**
 * The HashNMap can be used to store multiple values by a single key value. The
 * values stored can be retrieved using a direct query or by creating an
 * enumeration over the stored elements.
 * 
 * @author Thomas Morgner
 */
public class HashNMap implements Serializable, Cloneable {
  /** Serialization support. */
  private static final long serialVersionUID = -670924844536074826L;
  /**
   * An helper class to implement an empty iterator. This iterator will always
   * return false when hasNext is called.
   */
  private static final class EmptyIterator implements Iterator {
    /**
     * DefaultConstructor.
     */
    private EmptyIterator() {
      super();
    }
    /**
     * Returns true if the iteration has more elements. (In other
     * words, returns true if next would return an element
     * rather than throwing an exception.)
     * 
     * @return true if the iterator has more elements.
     */
    public boolean hasNext() {
      return false;
    }
    /**
     * Returns the next element in the iteration.
     * 
     * @return the next element in the iteration.
     * @throws NoSuchElementException
     *           iteration has no more elements.
     */
    public Object next() {
      throw new NoSuchElementException("This iterator is empty.");
    }
    /**
     * Removes from the underlying collection the last element returned by the
     * iterator (optional operation). This method can be called only once per
     * call to next. The behavior of an iterator is unspecified if
     * the underlying collection is modified while the iteration is in progress
     * in any way other than by calling this method.
     * 
     * @throws UnsupportedOperationException
     *           if the remove operation is not supported by this
     *           Iterator.
     * @throws IllegalStateException
     *           if the next method has not yet been called, or the
     *           remove method has already been called after the last
     *           call to the next method.
     */
    public void remove() {
      throw new UnsupportedOperationException("This iterator is empty, no remove supported.");
    }
  }
  /**
   * A singleton instance of the empty iterator. This object can be safely
   * shared.
   */
  private static final Iterator EMPTY_ITERATOR = new EmptyIterator();
  /**
   * The underlying storage.
   */
  private HashMap table;
  /**
   * An empty array.
   */
  private static final Object[] EMPTY_ARRAY = new Object[0];
  /**
   * Default constructor.
   */
  public HashNMap() {
    this.table = new HashMap();
  }
  /**
   * Returns a new empty list.
   * 
   * @return A new empty list.
   */
  protected List createList() {
    return new ArrayList();
  }
  /**
   * Inserts a new key/value pair into the map. If such a pair already exists,
   * it gets replaced with the given values.
   * 
   * @param key
   *          the key.
   * @param val
   *          the value.
   * @return A boolean.
   */
  public boolean put(final Object key, final Object val) {
    final List v = (List) this.table.get(key);
    if (v == null) {
      final List newList = createList();
      newList.add(val);
      this.table.put(key, newList);
      return true;
    } else {
      v.clear();
      return v.add(val);
    }
  }
  /**
   * Adds a new key/value pair into this map. If the key is not yet in the map,
   * it gets added to the map and the call is equal to put(Object,Object).
   * 
   * @param key
   *          the key.
   * @param val
   *          the value.
   * @return true, if the value has been added, false otherwise
   */
  public boolean add(final Object key, final Object val) {
    final List v = (List) this.table.get(key);
    if (v == null) {
      put(key, val);
      return true;
    } else {
      return v.add(val);
    }
  }
  /**
   * Retrieves the first value registered for an key or null if there was no
   * such key in the list.
   * 
   * @param key
   *          the key.
   * @return the value.
   */
  public Object getFirst(final Object key) {
    return get(key, 0);
  }
  /**
   * Retrieves the n-th value registered for an key or null if there was no such
   * key in the list. An index out of bounds exception is thrown if there are
   * less than n elements registered to this key.
   * 
   * @param key
   *          the key.
   * @param n
   *          the index.
   * @return the object.
   */
  public Object get(final Object key, final int n) {
    final List v = (List) this.table.get(key);
    if (v == null) {
      return null;
    }
    return v.get(n);
  }
  /**
   * Returns an iterator over all elements registered to the given key.
   * 
   * @param key
   *          the key.
   * @return an iterator.
   */
  public Iterator getAll(final Object key) {
    final List v = (List) this.table.get(key);
    if (v == null) {
      return EMPTY_ITERATOR;
    }
    return v.iterator();
  }
  /**
   * Returns all registered keys as an enumeration.
   * 
   * @return an enumeration of the keys.
   */
  public Iterator keys() {
    return this.table.keySet().iterator();
  }
  /**
   * Returns all registered keys as set.
   * 
   * @return a set of keys.
   */
  public Set keySet() {
    return this.table.keySet();
  }
  /**
   * Removes the key/value pair from the map. If the removed entry was the last
   * entry for this key, the key gets also removed.
   * 
   * @param key
   *          the key.
   * @param value
   *          the value.
   * @return true, if removing the element was successfull, false otherwise.
   */
  public boolean remove(final Object key, final Object value) {
    final List v = (List) this.table.get(key);
    if (v == null) {
      return false;
    }
    if (!v.remove(value)) {
      return false;
    }
    if (v.size() == 0) {
      this.table.remove(key);
    }
    return true;
  }
  /**
   * Removes all elements for the given key.
   * 
   * @param key
   *          the key.
   */
  public void removeAll(final Object key) {
    this.table.remove(key);
  }
  /**
   * Clears all keys and values of this map.
   */
  public void clear() {
    this.table.clear();
  }
  /**
   * Tests whether this map contains the given key.
   * 
   * @param key
   *          the key.
   * @return true if the key is contained in the map
   */
  public boolean containsKey(final Object key) {
    return this.table.containsKey(key);
  }
  /**
   * Tests whether this map contains the given value.
   * 
   * @param value
   *          the value.
   * @return true if the value is registered in the map for an key.
   */
  public boolean containsValue(final Object value) {
    final Iterator e = this.table.values().iterator();
    boolean found = false;
    while (e.hasNext() && !found) {
      final List v = (List) e.next();
      found = v.contains(value);
    }
    return found;
  }
  /**
   * Tests whether this map contains the given value.
   * 
   * @param value
   *          the value.
   * @param key
   *          the key under which to find the value
   * @return true if the value is registered in the map for an key.
   */
  public boolean containsValue(final Object key, final Object value) {
    final List v = (List) this.table.get(key);
    if (v == null) {
      return false;
    }
    return v.contains(value);
  }
  /**
   * Tests whether this map contains the given key or value.
   * 
   * @param value
   *          the value.
   * @return true if the key or value is contained in the map
   */
  public boolean contains(final Object value) {
    if (containsKey(value)) {
      return true;
    }
    return containsValue(value);
  }
  /**
   * Returns a clone of the specified object, if it can be cloned, otherwise
   * throws a CloneNotSupportedException.
   * 
   * @param object
   *          the object to clone (null not permitted).
   * @return A clone of the specified object.
   * @throws CloneNotSupportedException
   *           if the object cannot be cloned.
   */
  public static Object clone(final Object object) throws CloneNotSupportedException {
    if (object == null) {
      throw new IllegalArgumentException("Null 'object' argument.");
    }
    else {
      try {
        final Method method = object.getClass().getMethod("clone", (Class[]) null);
        if (Modifier.isPublic(method.getModifiers())) {
          return method.invoke(object, (Object[]) null);
        }
      } catch (Exception e) {
      }
    }
    throw new CloneNotSupportedException("Failed to clone.");
  }
  /**
   * Creates a deep copy of this HashNMap.
   * 
   * @return a clone.
   * @throws CloneNotSupportedException
   *           this should never happen.
   */
  public Object clone() throws CloneNotSupportedException {
    final HashNMap map = (HashNMap) super.clone();
    map.table = new HashMap();
    final Iterator iterator = keys();
    while (iterator.hasNext()) {
      final Object key = iterator.next();
      final List list = (List) map.table.get(key);
      if (list != null) {
        map.table.put(key,clone(list));
      }
    }
    return map;
  }
  /**
   * Returns the contents for the given key as object array. If there were no
   * objects registered with that key, an empty object array is returned.
   * 
   * @param key
   *          the key.
   * @param data
   *          the object array to receive the contents.
   * @return the contents.
   */
  public Object[] toArray(final Object key, final Object[] data) {
    if (key == null) {
      throw new NullPointerException("Key must not be null.");
    }
    final List list = (List) this.table.get(key);
    if (list != null) {
      return list.toArray(data);
    }
    if (data.length > 0) {
      data[0] = null;
    }
    return data;
  }
  /**
   * Returns the contents for the given key as object array. If there were no
   * objects registered with that key, an empty object array is returned.
   * 
   * @param key
   *          the key.
   * @return the contents.
   */
  public Object[] toArray(final Object key) {
    if (key == null) {
      throw new NullPointerException("Key must not be null.");
    }
    final List list = (List) this.table.get(key);
    if (list != null) {
      return list.toArray();
    }
    return EMPTY_ARRAY;
  }
  /**
   * Returns the number of elements registered with the given key.
   * 
   * @param key
   *          the key.
   * @return the number of element for this key, or 0 if there are no elements
   *         registered.
   */
  public int getValueCount(final Object key) {
    if (key == null) {
      throw new NullPointerException("Key must not be null.");
    }
    final List list = (List) this.table.get(key);
    if (list != null) {
      return list.size();
    }
    return 0;
  }
}