/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.collections.map;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
A Map implementation that allows mappings to be
removed by the garbage collector.
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. For information on how the different reference types behave, see Reference.
Different types of references can be specified for keys and values.
The keys can be configured to be weak but the values hard,
in which case this class will behave like a
WeakHashMap. However, you can also specify hard keys and
weak values, or any other combination. The default constructor uses
hard keys and soft values, providing a memory-sensitive cache.
This map is similar to ReferenceIdentityMap. It differs in that keys and values in this class are compared using equals().
This Map implementation does not allow null elements.
Attempting to add a null key or value to the map will raise a NullPointerException.
This implementation is not synchronized. You can use Collections.synchronizedMap to provide synchronized access to a ReferenceMap.
Remember that synchronization will not stop the garbage collecter removing entries.
All the available iterators can be reset back to the start by casting to
ResettableIterator and calling reset().
Note that ReferenceMap 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 simplest approach is to wrap this map using Collections.synchronizedMap. This class may throw exceptions when accessed by concurrent threads without synchronization.
NOTE: As from Commons Collections 3.1 this map extends AbstractReferenceMap
(previously it extended AbstractMap). As a result, the implementation is now
extensible and provides a MapIterator.
Author: Paul Jack, Stephen Colebourne See Also: Since: Commons Collections 3.0 (previously in main package v2.1) Version: $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
/**
* A <code>Map</code> implementation that allows mappings to be
* removed by the garbage collector.
* <p>
* When you construct a <code>ReferenceMap</code>, 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. For information on how the different reference types behave,
* see {@link java.lang.ref.Reference Reference}.
* <p>
* Different types of references can be specified for keys and values.
* The keys can be configured to be weak but the values hard,
* in which case this class will behave like a
* <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">
* <code>WeakHashMap</code></a>. However, you can also specify hard keys and
* weak values, or any other combination. The default constructor uses
* hard keys and soft values, providing a memory-sensitive cache.
* <p>
* This map is similar to
* {@link org.apache.commons.collections.map.ReferenceIdentityMap ReferenceIdentityMap}.
* It differs in that keys and values in this class are compared using <code>equals()</code>.
* <p>
* This {@link java.util.Map Map} implementation does <i>not</i> allow null elements.
* Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.
* <p>
* This implementation is not synchronized.
* You can use {@link java.util.Collections#synchronizedMap} to
* provide synchronized access to a <code>ReferenceMap</code>.
* Remember that synchronization will not stop the garbage collecter removing entries.
* <p>
* All the available iterators can be reset back to the start by casting to
* <code>ResettableIterator</code> and calling <code>reset()</code>.
* <p>
* <strong>Note that ReferenceMap is not synchronized and is not thread-safe.</strong>
* If you wish to use this map from multiple threads concurrently, you must use
* appropriate synchronization. The simplest approach is to wrap this map
* using {@link java.util.Collections#synchronizedMap}. This class may throw
* exceptions when accessed by concurrent threads without synchronization.
* <p>
* NOTE: As from Commons Collections 3.1 this map extends <code>AbstractReferenceMap</code>
* (previously it extended AbstractMap). As a result, the implementation is now
* extensible and provides a <code>MapIterator</code>.
*
* @see java.lang.ref.Reference
*
* @since Commons Collections 3.0 (previously in main package v2.1)
* @version $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
*
* @author Paul Jack
* @author Stephen Colebourne
*/
public class ReferenceMap extends AbstractReferenceMap implements Serializable {
Serialization version /** Serialization version */
private static final long serialVersionUID = 1555089888138299607L;
Constructs a new ReferenceMap that will
use hard references to keys and soft references to values.
/**
* Constructs a new <code>ReferenceMap</code> that will
* use hard references to keys and soft references to values.
*/
public ReferenceMap() {
super(HARD, SOFT, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
}
Constructs a new ReferenceMap that will
use the specified types of references.
Params: - keyType – the type of reference to use for keys; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - valueType – the type of reference to use for values; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK
/**
* Constructs a new <code>ReferenceMap</code> that will
* use the specified types of references.
*
* @param keyType the type of reference to use for keys;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param valueType the type of reference to use for values;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
*/
public ReferenceMap(int keyType, int valueType) {
super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
}
Constructs a new ReferenceMap that will
use the specified types of references.
Params: - keyType – the type of reference to use for keys; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - valueType – the type of reference to use for values; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - purgeValues – should the value be automatically purged when the
key is garbage collected
/**
* Constructs a new <code>ReferenceMap</code> that will
* use the specified types of references.
*
* @param keyType the type of reference to use for keys;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param valueType the type of reference to use for values;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param purgeValues should the value be automatically purged when the
* key is garbage collected
*/
public ReferenceMap(int keyType, int valueType, boolean purgeValues) {
super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues);
}
Constructs a new ReferenceMap with the
specified reference types, load factor and initial
capacity.
Params: - keyType – the type of reference to use for keys; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - valueType – the type of reference to use for values; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - capacity – the initial capacity for the map
- loadFactor – the load factor for the map
/**
* Constructs a new <code>ReferenceMap</code> with the
* specified reference types, load factor and initial
* capacity.
*
* @param keyType the type of reference to use for keys;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param valueType the type of reference to use for values;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param capacity the initial capacity for the map
* @param loadFactor the load factor for the map
*/
public ReferenceMap(int keyType, int valueType, int capacity, float loadFactor) {
super(keyType, valueType, capacity, loadFactor, false);
}
Constructs a new ReferenceMap with the
specified reference types, load factor and initial
capacity.
Params: - keyType – the type of reference to use for keys; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - valueType – the type of reference to use for values; must be
AbstractReferenceMap.HARD, AbstractReferenceMap.SOFT, AbstractReferenceMap.WEAK - capacity – the initial capacity for the map
- loadFactor – the load factor for the map
- purgeValues – should the value be automatically purged when the
key is garbage collected
/**
* Constructs a new <code>ReferenceMap</code> with the
* specified reference types, load factor and initial
* capacity.
*
* @param keyType the type of reference to use for keys;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param valueType the type of reference to use for values;
* must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
* @param capacity the initial capacity for the map
* @param loadFactor the load factor for the map
* @param purgeValues should the value be automatically purged when the
* key is garbage collected
*/
public ReferenceMap(int keyType, int valueType, int capacity,
float loadFactor, boolean purgeValues) {
super(keyType, valueType, capacity, loadFactor, purgeValues);
}
//-----------------------------------------------------------------------
Write the map out using a custom routine.
/**
* Write the map out using a custom routine.
*/
private void writeObject(ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
doWriteObject(out);
}
Read the map in using a custom routine.
/**
* Read the map in using a custom routine.
*/
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();
doReadObject(in);
}
}