content: /* ========================================================================
   * 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.
   *
   */
  
  package org.jfree.util;
  
  import java.io.Serializable;
  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 <code>hasNext</code> is called.
       */
      private static final class EmptyIterator implements Iterator {
  
          /**
           * DefaultConstructor.
           */
          private EmptyIterator() {
              super();
          }
  
          /**
           * Returns <tt>true</tt> if the iteration has more elements. (In other
           * words, returns <tt>true</tt> if <tt>next</tt> would return an element
           * rather than throwing an exception.)
           *
           * @return <tt>true</tt> 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 <tt>next</tt>.  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 <tt>remove</tt>
           *                                       operation is not supported by this Iterator.
           * @throws IllegalStateException         if the <tt>next</tt> method has not
           *                                       yet been called, or the <tt>remove</tt> method has already
           *                                       been called after the last call to the <tt>next</tt>
           *                                       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);
      }
  
      /**
       * 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, ObjectUtilities.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;
      }
  }
  