/*---------------------------------------------------------------------------*\
$Id: 55099a0f56afdc766564d3b1c3f99281645c3b02 $
---------------------------------------------------------------------------
This software is released under a BSD-style license:
Copyright (c) 2004-2007 Brian M. Clapper. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. The end-user documentation included with the redistribution, if any,
must include the following acknowlegement:
"This product includes software developed by Brian M. Clapper
(bmc@clapper.org, http://www.clapper.org/bmc/). That software is
copyright (c) 2004-2007 Brian M. Clapper."
Alternately, this acknowlegement may appear in the software itself,
if wherever such third-party acknowlegements normally appear.
3. Neither the names "clapper.org", "clapper.org Java Utility Library",
nor any of the names of the project contributors may be used to
endorse or promote products derived from this software without prior
written permission. For written permission, please contact
bmc@clapper.org.
4. Products derived from this software may not be called "clapper.org
Java Utility Library", nor may "clapper.org" appear in their names
without prior written permission of Brian M. Clapper.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL BRIAN M. CLAPPER BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\*---------------------------------------------------------------------------*/
package org.clapper.util.misc;
import java.util.Map;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.ArrayList;
import java.util.Iterator;
import java.io.Serializable;
import java.util.Collection;
/**
* An OrderedHashMap is a java.util.HashMap with one
* additional property: It maintains a list of the map's keys in the order
* they were added to the map. This additional capability imposes a small
* amount of extra overhead on insertion and a larger amount of overhead on
* key removal, but absolutely no additional key lookup overhead. This
* class is conceptually similar to (though less feature-rich than) the
* java.util.LinkedHashMap class added in JDK 1.4.
*
* @version $Revision$
*
* @author Copyright © 2004-2007 Brian M. Clapper
*
* @deprecated Please use java.util.LinkedHashMap, instead
*
* @see #keysInInsertionOrder
* @see #getKeysInInsertionOrder
*/
public class OrderedHashMap
extends HashMap
implements Cloneable, Serializable
{
/*----------------------------------------------------------------------*\
Private Static Variables
\*----------------------------------------------------------------------*/
/**
* See JDK 1.5 version of java.io.Serializable
*/
private static final long serialVersionUID = 1L;
/*----------------------------------------------------------------------*\
Private Variables
\*----------------------------------------------------------------------*/
private LinkedList keysInOrder = new LinkedList();
/*----------------------------------------------------------------------*\
Constructors
\*----------------------------------------------------------------------*/
/**
* Construct a new empty map with a default capacity and load factor.
*/
public OrderedHashMap()
{
super();
}
/**
* Construct a new empty map with the specified initial capacity and
* a default load factor.
*
* @param initialCapacity the initial capacity
*/
public OrderedHashMap (int initialCapacity)
{
super (initialCapacity);
}
/**
* Constructs a new, empty map with the specified initial capacity and
* the specified load factor.
*
* @param initialCapacity the initial capacity
* @param loadFactor the load factor
*/
public OrderedHashMap (int initialCapacity, float loadFactor)
{
super (initialCapacity, loadFactor);
}
/**
* Constructs a new map with the same mappings as the given map. The
* initial capacity and load factor is the same as for the parent
* HashMap class. Since there's no way of knowing in what
* order entries were made in the original map, the order imposed on
* them in this map is the order in which they are returned by the
* keySet() method.
*
* @param map the map whose mappings are to be copied
*
* @see #OrderedHashMap(OrderedHashMap)
*/
public OrderedHashMap (Map map)
{
super (map);
keysInOrder.addAll (map.keySet());
}
/**
* Constructs a new map with the same mappings as the given
* OrderedHashMap. The initial capacity and load factor is the
* same as for the parent HashMap class. The insertion order
* of the keys is preserved.
*
* @param map the map whose mappings are to be copied
*/
public OrderedHashMap (OrderedHashMap map)
{
super (map);
keysInOrder.addAll (map.keysInOrder);
}
/*----------------------------------------------------------------------*\
Public Methods
\*----------------------------------------------------------------------*/
/**
* Get the keys in the order they were added to this map.
*
* @param list the List to receive the keys
*
* @return the number of keys added to the list
*
* @see #keysInInsertionOrder
*/
public int getKeysInInsertionOrder (List list)
{
// Casting to Collection removes a stupid JDK 1.6-beta compiler
// complaint. Doing this:
//
// list.addAll(keysInOrder)
//
// results in this compiler error:
//
// reference to addAll is ambiguous, both method
// addAll(java.util.Collection) in
// java.util.Collection and method
// addAll(java.util.Collection) in
// java.util.List match
//
// This problem is new with 1.6. Casting solves the problem.
((Collection) list).addAll(keysInOrder);
return keysInOrder.size();
}
/**
* Get the keys in the order they were added to this map.
*
* @return a new List containing the keys in insertion order
*
* @see #getKeysInInsertionOrder
*/
public List keysInInsertionOrder()
{
return new ArrayList (keysInOrder);
}
/**
* Returns a shallow copy of this instance. The keys and values themselves
* are not cloned.
*
* @return a shallow copy of this map
*/
public Object clone() // NOPMD
{
return new OrderedHashMap (this);
}
/**
* Remove all mappings from this map.
*/
public void clear()
{
super.clear();
keysInOrder.clear();
}
/**
* Associates the specified value with the specified key in this map.
* If the key already has a value in this map, the existing value is
* replaced by the new value, and the old value is replaced. If the key
* already exists in the map, it is moved to the end of the key
* insertion order list.
*
* @param key the key with which the specified value is to be associated
* @param value the value to associate with the specified key
*
* @return the previous value associated with the key, or null if (a) there
* was no previous value, or (b) the previous value was a null
*/
public V put (K key, V value)
{
V oldValue = super.put (key, value);
keysInOrder.remove (key);
keysInOrder.add (key);
return oldValue;
}
/**
* Copies all of the mappings from a specified map to this one. These
* mappings replace any mappings that this map had for any of the keys
* in this map. Since there's no way of knowing in what order entries
* were made in the original map, they are appended to the key
* insertion order list in the order they are returned by the map's
* keySet() method.
*
* @param map the map whose mappings are to be copied
*
* @see #putAll(OrderedHashMap)
*/
public void putAll (Map map)
{
for (Iterator it = map.keySet().iterator();
it.hasNext(); )
{
K key = it.next();
V value = map.get (key);
this.put (key, value);
}
}
/**
* Copies all of the mappings from a specified map to this one. These
* mappings replace any mappings that this map had for any of the keys
* in this map. The keys are appended to this map's key insertion order
* list in the order they were originally added to map.
*
* @param map the map whose mappings are to be copied
*
* @see #putAll(OrderedHashMap)
* @see #keysInInsertionOrder
*/
public void putAll (OrderedHashMap map)
{
for (Iterator it = map.keysInInsertionOrder().iterator();
it.hasNext(); )
{
K key = it.next();
V value = map.get (key);
this.put (key, value);
}
}
/**
* Removes the mapping for a key, if there is one. The key is also removed
* from the key insertion order list.
*
* @param key the key to remove
*
* @return the previous value associated with the key, or null if (a) there
* was no previous value, or (b) the previous value was a null
*/
public V remove (Object key)
{
V oldValue = super.remove (key);
keysInOrder.remove (key);
return oldValue;
}
}
Ads help maintain this website.