Java tutorial
/* * 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 <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); } /** * Returns a clone of the specified object, if it can be cloned, otherwise * throws a CloneNotSupportedException. * * @param object * the object to clone (<code>null</code> 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; } }