001: /*
002: * Copyright 2002-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.collections.map;
017:
018: import java.io.IOException;
019: import java.io.ObjectInputStream;
020: import java.io.ObjectOutputStream;
021: import java.io.Serializable;
022:
023: /**
024: * A <code>Map</code> implementation that allows mappings to be
025: * removed by the garbage collector.
026: * <p>
027: * When you construct a <code>ReferenceMap</code>, you can specify what kind
028: * of references are used to store the map's keys and values.
029: * If non-hard references are used, then the garbage collector can remove
030: * mappings if a key or value becomes unreachable, or if the JVM's memory is
031: * running low. For information on how the different reference types behave,
032: * see {@link java.lang.ref.Reference Reference}.
033: * <p>
034: * Different types of references can be specified for keys and values.
035: * The keys can be configured to be weak but the values hard,
036: * in which case this class will behave like a
037: * <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">
038: * <code>WeakHashMap</code></a>. However, you can also specify hard keys and
039: * weak values, or any other combination. The default constructor uses
040: * hard keys and soft values, providing a memory-sensitive cache.
041: * <p>
042: * This map is similar to
043: * {@link org.apache.commons.collections.map.ReferenceIdentityMap ReferenceIdentityMap}.
044: * It differs in that keys and values in this class are compared using <code>equals()</code>.
045: * <p>
046: * This {@link java.util.Map Map} implementation does <i>not</i> allow null elements.
047: * Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.
048: * <p>
049: * This implementation is not synchronized.
050: * You can use {@link java.util.Collections#synchronizedMap} to
051: * provide synchronized access to a <code>ReferenceMap</code>.
052: * Remember that synchronization will not stop the garbage collecter removing entries.
053: * <p>
054: * All the available iterators can be reset back to the start by casting to
055: * <code>ResettableIterator</code> and calling <code>reset()</code>.
056: * <p>
057: * <strong>Note that ReferenceMap is not synchronized and is not thread-safe.</strong>
058: * If you wish to use this map from multiple threads concurrently, you must use
059: * appropriate synchronization. The simplest approach is to wrap this map
060: * using {@link java.util.Collections#synchronizedMap}. This class may throw
061: * exceptions when accessed by concurrent threads without synchronization.
062: * <p>
063: * NOTE: As from Commons Collections 3.1 this map extends <code>AbstractReferenceMap</code>
064: * (previously it extended AbstractMap). As a result, the implementation is now
065: * extensible and provides a <code>MapIterator</code>.
066: *
067: * @see java.lang.ref.Reference
068: *
069: * @since Commons Collections 3.0 (previously in main package v2.1)
070: * @version $Revision: 348007 $ $Date: 2005-11-21 22:52:57 +0000 (Mon, 21 Nov 2005) $
071: *
072: * @author Paul Jack
073: * @author Stephen Colebourne
074: */
075: public class ReferenceMap extends AbstractReferenceMap implements
076: Serializable {
077:
078: /** Serialization version */
079: private static final long serialVersionUID = 1555089888138299607L;
080:
081: /**
082: * Constructs a new <code>ReferenceMap</code> that will
083: * use hard references to keys and soft references to values.
084: */
085: public ReferenceMap() {
086: super (HARD, SOFT, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
087: }
088:
089: /**
090: * Constructs a new <code>ReferenceMap</code> that will
091: * use the specified types of references.
092: *
093: * @param keyType the type of reference to use for keys;
094: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
095: * @param valueType the type of reference to use for values;
096: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
097: */
098: public ReferenceMap(int keyType, int valueType) {
099: super (keyType, valueType, DEFAULT_CAPACITY,
100: DEFAULT_LOAD_FACTOR, false);
101: }
102:
103: /**
104: * Constructs a new <code>ReferenceMap</code> that will
105: * use the specified types of references.
106: *
107: * @param keyType the type of reference to use for keys;
108: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
109: * @param valueType the type of reference to use for values;
110: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
111: * @param purgeValues should the value be automatically purged when the
112: * key is garbage collected
113: */
114: public ReferenceMap(int keyType, int valueType, boolean purgeValues) {
115: super (keyType, valueType, DEFAULT_CAPACITY,
116: DEFAULT_LOAD_FACTOR, purgeValues);
117: }
118:
119: /**
120: * Constructs a new <code>ReferenceMap</code> with the
121: * specified reference types, load factor and initial
122: * capacity.
123: *
124: * @param keyType the type of reference to use for keys;
125: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
126: * @param valueType the type of reference to use for values;
127: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
128: * @param capacity the initial capacity for the map
129: * @param loadFactor the load factor for the map
130: */
131: public ReferenceMap(int keyType, int valueType, int capacity,
132: float loadFactor) {
133: super (keyType, valueType, capacity, loadFactor, false);
134: }
135:
136: /**
137: * Constructs a new <code>ReferenceMap</code> with the
138: * specified reference types, load factor and initial
139: * capacity.
140: *
141: * @param keyType the type of reference to use for keys;
142: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
143: * @param valueType the type of reference to use for values;
144: * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
145: * @param capacity the initial capacity for the map
146: * @param loadFactor the load factor for the map
147: * @param purgeValues should the value be automatically purged when the
148: * key is garbage collected
149: */
150: public ReferenceMap(int keyType, int valueType, int capacity,
151: float loadFactor, boolean purgeValues) {
152: super (keyType, valueType, capacity, loadFactor, purgeValues);
153: }
154:
155: //-----------------------------------------------------------------------
156: /**
157: * Write the map out using a custom routine.
158: */
159: private void writeObject(ObjectOutputStream out) throws IOException {
160: out.defaultWriteObject();
161: doWriteObject(out);
162: }
163:
164: /**
165: * Read the map in using a custom routine.
166: */
167: private void readObject(ObjectInputStream in) throws IOException,
168: ClassNotFoundException {
169: in.defaultReadObject();
170: doReadObject(in);
171: }
172:
173: }
|