KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > map > ReferenceMap


1 /*
2  * Copyright 2002-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.map;
17
18 import java.io.IOException JavaDoc;
19 import java.io.ObjectInputStream JavaDoc;
20 import java.io.ObjectOutputStream JavaDoc;
21 import java.io.Serializable JavaDoc;
22
23 /**
24  * A <code>Map</code> implementation that allows mappings to be
25  * removed by the garbage collector.
26  * <p>
27  * When you construct a <code>ReferenceMap</code>, you can specify what kind
28  * of references are used to store the map's keys and values.
29  * If non-hard references are used, then the garbage collector can remove
30  * mappings if a key or value becomes unreachable, or if the JVM's memory is
31  * running low. For information on how the different reference types behave,
32  * see {@link Reference}.
33  * <p>
34  * Different types of references can be specified for keys and values.
35  * The keys can be configured to be weak but the values hard,
36  * in which case this class will behave like a
37  * <a HREF="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">
38  * <code>WeakHashMap</code></a>. However, you can also specify hard keys and
39  * weak values, or any other combination. The default constructor uses
40  * hard keys and soft values, providing a memory-sensitive cache.
41  * <p>
42  * This map is similar to
43  * {@link org.apache.commons.collections.map.ReferenceIdentityMap ReferenceIdentityMap}.
44  * It differs in that keys and values in this class are compared using <code>equals()</code>.
45  * <p>
46  * This {@link Map} implementation does <i>not</i> allow null elements.
47  * Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.
48  * <p>
49  * This implementation is not synchronized.
50  * You can use {@link java.util.Collections#synchronizedMap} to
51  * provide synchronized access to a <code>ReferenceMap</code>.
52  * Remember that synchronization will not stop the garbage collecter removing entries.
53  * <p>
54  * All the available iterators can be reset back to the start by casting to
55  * <code>ResettableIterator</code> and calling <code>reset()</code>.
56  * <p>
57  * NOTE: As from Commons Collections 3.1 this map extends <code>AbstractReferenceMap</code>
58  * (previously it extended AbstractMap). As a result, the implementation is now
59  * extensible and provides a <code>MapIterator</code>.
60  *
61  * @see java.lang.ref.Reference
62  *
63  * @since Commons Collections 3.0 (previously in main package v2.1)
64  * @version $Revision: 1.13 $ $Date: 2004/04/27 21:35:23 $
65  *
66  * @author Paul Jack
67  * @author Stephen Colebourne
68  */
69 public class ReferenceMap extends AbstractReferenceMap implements Serializable JavaDoc {
70
71     /** Serialization version */
72     private static final long serialVersionUID = 1555089888138299607L;
73
74     /**
75      * Constructs a new <code>ReferenceMap</code> that will
76      * use hard references to keys and soft references to values.
77      */
78     public ReferenceMap() {
79         super(HARD, SOFT, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
80     }
81
82     /**
83      * Constructs a new <code>ReferenceMap</code> that will
84      * use the specified types of references.
85      *
86      * @param keyType the type of reference to use for keys;
87      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
88      * @param valueType the type of reference to use for values;
89      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
90      */
91     public ReferenceMap(int keyType, int valueType) {
92         super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
93     }
94
95     /**
96      * Constructs a new <code>ReferenceMap</code> that will
97      * use the specified types of references.
98      *
99      * @param keyType the type of reference to use for keys;
100      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
101      * @param valueType the type of reference to use for values;
102      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
103      * @param purgeValues should the value be automatically purged when the
104      * key is garbage collected
105      */
106     public ReferenceMap(int keyType, int valueType, boolean purgeValues) {
107         super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues);
108     }
109
110     /**
111      * Constructs a new <code>ReferenceMap</code> with the
112      * specified reference types, load factor and initial
113      * capacity.
114      *
115      * @param keyType the type of reference to use for keys;
116      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
117      * @param valueType the type of reference to use for values;
118      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
119      * @param capacity the initial capacity for the map
120      * @param loadFactor the load factor for the map
121      */
122     public ReferenceMap(int keyType, int valueType, int capacity, float loadFactor) {
123         super(keyType, valueType, capacity, loadFactor, false);
124     }
125
126     /**
127      * Constructs a new <code>ReferenceMap</code> with the
128      * specified reference types, load factor and initial
129      * capacity.
130      *
131      * @param keyType the type of reference to use for keys;
132      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
133      * @param valueType the type of reference to use for values;
134      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
135      * @param capacity the initial capacity for the map
136      * @param loadFactor the load factor for the map
137      * @param purgeValues should the value be automatically purged when the
138      * key is garbage collected
139      */
140     public ReferenceMap(int keyType, int valueType, int capacity,
141                         float loadFactor, boolean purgeValues) {
142         super(keyType, valueType, capacity, loadFactor, purgeValues);
143     }
144
145     //-----------------------------------------------------------------------
146 /**
147      * Write the map out using a custom routine.
148      */
149     private void writeObject(ObjectOutputStream JavaDoc out) throws IOException JavaDoc {
150         out.defaultWriteObject();
151         doWriteObject(out);
152     }
153
154     /**
155      * Read the map in using a custom routine.
156      */
157     private void readObject(ObjectInputStream JavaDoc in) throws IOException JavaDoc, ClassNotFoundException JavaDoc {
158         in.defaultReadObject();
159         doReadObject(in);
160     }
161
162 }
163
Popular Tags