org.apache.commons.collections.map

This package contains implementations of the {@link java.util.Map Map}, {@link org.apache.commons.collections.IterableMap IterableMap}, {@link org.apache.commons.collections.OrderedMap OrderedMap} and {@link java.util.SortedMap SortedMap} interfaces. A Map provides a lookup from a key to a value. A number of implementations also support the new MapIterator interface that enables simple iteration of map keys and values.

The following implementations are provided:

• CaseInsensitiveMap - map that compares keys in a case insensitive way
• CompositeMap - map that combines multiple maps into a single view
• HashedMap - general purpose HashMap replacement supporting MapIterator
• IdentityMap - map that uses == for comparison instead of equals()
• Flat3Map - designed for good performance at size 3 or less
• LinkedMap - a hash map that maintains insertion order, supporting OrderedMapIterator
• MultiKeyMap - map that provides special methods for using more than one key to access the value
• ReferenceMap - allows the garbage collector to collect keys and values using equals() for comparison
• ReferenceIdentityMap - allows the garbage collector to collect keys and values using == for comparison
• SingletonMap - a fully featured map to hold one key-value pair
• StaticBucketMap - internally synchronized and designed for thread-contentious environments

The following decorators are provided:

• Unmodifiable - ensures the collection cannot be altered
• Predicated - ensures that only elements that are valid according to a predicate can be added
• Typed - ensures that only elements that are of a specific type can be added
• Transformed - transforms each element added
• FixedSize - ensures that the size of the map cannot change
• Lazy - creates objects in the map on demand
• ListOrdered - ensures that insertion order is retained

This class implements all the features necessary for a subclass hash-based map. Key-value entries are stored in instances of the HashEntry class, which can be overridden and replaced.

The Map API is very difficult to decorate correctly, and involves implementing lots of different classes.

This class implements all the features necessary for a subclass linked hash-based map.

Methods are forwarded directly to the decorated map.

This implementation does not perform any special processing with AbstractMapDecorator.entrySet() , AbstractMapDecorator.keySet() or AbstractMapDecorator.values() .

Methods are forwarded directly to the decorated map.

This implementation does not perform any special processing with the map views. Instead it simply returns the set/collection from the wrapped map.

This class implements all the features necessary for a subclass reference hash-based map.

Methods are forwarded directly to the decorated map.

This implementation does not perform any special processing with the map views. Instead it simply returns the set/collection from the wrapped map.

The forces at work here are similar to those in AbstractTestCollection . If your class implements the full Map interface, including optional operations, simply extend this class, and implement the AbstractTestMap.makeEmptyMap() method.

On the other hand, if your map implementation is weird, you may have to override one or more of the other protected methods.

As entries are added to the map, keys are converted to all lowercase.

Changes made to this map will actually be made on the decorated map. Add and remove operations require the use of a pluggable strategy.

When the DefaultedMap.get(Object) method is called with a key that does not exist in the map, this map will return the default value specified in the constructor/factory.

Any action that would change the size of the map is disallowed. The put method is allowed to change the value associated with an existing key however.

If trying to remove or clear the map, an UnsupportedOperationException is thrown.

Any action that would change the size of the map is disallowed. The put method is allowed to change the value associated with an existing key however.

If trying to remove or clear the map, an UnsupportedOperationException is thrown.

This map is designed for performance and can outstrip HashMap. It also has good garbage collection characteristics.

• Optimised for operation at size 3 or less.
• Still works well once size 3 exceeded.
• Gets at size 3 or less are about 0-10% faster than HashMap,
• Puts at size 3 or less are over 4 times faster than HashMap.
• Performance 5% slower than HashMap once size 3 exceeded once.

This implementation improves on the JDK1.4 HashMap by adding the org.apache.commons.collections.MapIterator MapIterator functionality and many methods for subclassing.

Note that HashedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

This map will violate the detail of various Map and map view contracts. As a general rule, don't compare this map to other maps.

Note that IdentityMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

When the LazyMap.get(Object) method is called with a key that does not exist in the map, the factory is used to create the object.

When the LazySortedMap.get(Object) method is called with a key that does not exist in the map, the factory is used to create the object.

This implementation improves on the JDK1.4 LinkedHashMap by adding the org.apache.commons.collections.MapIterator MapIterator functionality, additional convenience methods and allowing bidirectional iteration.

The order will be used via the iterators and toArray methods on the views. The order is also returned by the MapIterator. The orderedMapIterator() method accesses an iterator that can iterate both forwards and backwards through the map. In addition, non-interface methods are provided to access the map by index.

If an object is added to the Map for a second time, it will remain in the original position in the iteration.

Note that ListOrderedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

The least recently used algorithm works on the get and put operations only. Iteration of any kind, including setting the value by iteration, does not change the order.

This class is the most efficient way to uses multiple keys to map to a value. The best way to use this class is via the additional map-style methods. These provide get, containsKey, put and remove for individual keys which operate without extra object creation.

The additional methods are the main interface of this map. As such, you will not normally hold this map in a variable of type Map.

The normal map methods take in and return a MultiKey . If you try to use put() with any other object type a ClassCastException is thrown.

A MultiMap is a Map with slightly different semantics. Putting a value into the map will add the value to a Collection at that key. Getting a value will return a Collection, holding all the values put to that key.

This implementation is a decorator, allowing any Map implementation to be used as the base.

In addition, this implementation allows the type of collection used for the values to be controlled.

This map exists to provide validation for the decorated map. It is normally created to decorate an empty map. If an object cannot be added to the map, an IllegalArgumentException is thrown.

One usage would be to ensure that no null keys are added to the map.

Map map = PredicatedSet.decorate(new HashMap(), NotNullPredicate.INSTANCE, null);

Note that PredicatedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

This map exists to provide validation for the decorated map. It is normally created to decorate an empty map. If an object cannot be added to the map, an IllegalArgumentException is thrown.

One usage would be to ensure that no null keys are added to the map.

SortedMap map = PredicatedSortedSet.decorate(new TreeMap(), NotNullPredicate.INSTANCE, null);

Note that PredicatedSortedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

When you construct a ReferenceIdentityMap, you can specify what kind of references are used to store the map's keys and values. If non-hard references are used, then the garbage collector can remove mappings if a key or value becomes unreachable, or if the JVM's memory is running low.

When you construct a ReferenceMap, you can specify what kind of references are used to store the map's keys and values. If non-hard references are used, then the garbage collector can remove mappings if a key or value becomes unreachable, or if the JVM's memory is running low.

The Map put methods and Map.Entry setValue method are affected by this class. Thus objects must be removed or searched for using their transformed form. For example, if the transformation converts Strings to Integers, you must use the Integer form to remove objects.

Note that TransformedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

The Map put methods and Map.Entry setValue method are affected by this class. Thus objects must be removed or searched for using their transformed form. For example, if the transformation converts Strings to Integers, you must use the Integer form to remove objects.

Note that TransformedSortedMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization.

The validation of additions is performed via an instanceof test against a specified Class.

The validation of additions is performed via an instanceof test against a specified Class.