KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Copyright 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 import java.lang.ref.Reference JavaDoc;
23
24 /**
25  * A <code>Map</code> implementation that allows mappings to be
26  * removed by the garbage collector and matches keys and values based
27  * on <code>==</code> not <code>equals()</code>.
28  * <p>
29  * <p>
30  * When you construct a <code>ReferenceIdentityMap</code>, you can specify what kind
31  * of references are used to store the map's keys and values.
32  * If non-hard references are used, then the garbage collector can remove
33  * mappings if a key or value becomes unreachable, or if the JVM's memory is
34  * running low. For information on how the different reference types behave,
35  * see {@link Reference}.
36  * <p>
37  * Different types of references can be specified for keys and values.
38  * The default constructor uses hard keys and soft values, providing a
39  * memory-sensitive cache.
40  * <p>
41  * This map is similar to
42  * {@link org.apache.commons.collections.map.ReferenceMap ReferenceMap}.
43  * It differs in that keys and values in this class are compared using <code>==</code>.
44  * <p>
45  * This map will violate the detail of various Map and map view contracts.
46  * As a general rule, don't compare this map to other maps.
47  * <p>
48  * This {@link Map} implementation does <i>not</i> allow null elements.
49  * Attempting to add a null key or value to the map will raise a <code>NullPointerException</code>.
50  * <p>
51  * This implementation is not synchronized.
52  * You can use {@link java.util.Collections#synchronizedMap} to
53  * provide synchronized access to a <code>ReferenceIdentityMap</code>.
54  * Remember that synchronization will not stop the garbage collecter removing entries.
55  * <p>
56  * All the available iterators can be reset back to the start by casting to
57  * <code>ResettableIterator</code> and calling <code>reset()</code>.
58  *
59  * @see java.lang.ref.Reference
60  *
61  * @since Commons Collections 3.0 (previously in main package v2.1)
62  * @version $Revision: 1.1 $ $Date: 2004/04/27 21:37:32 $
63  *
64  * @author Stephen Colebourne
65  */
66 public class ReferenceIdentityMap extends AbstractReferenceMap implements Serializable JavaDoc {
67
68     /** Serialization version */
69     private static final long serialVersionUID = -1266190134568365852L;
70
71     /**
72      * Constructs a new <code>ReferenceIdentityMap</code> that will
73      * use hard references to keys and soft references to values.
74      */
75     public ReferenceIdentityMap() {
76         super(HARD, SOFT, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
77     }
78
79     /**
80      * Constructs a new <code>ReferenceIdentityMap</code> that will
81      * use the specified types of references.
82      *
83      * @param keyType the type of reference to use for keys;
84      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
85      * @param valueType the type of reference to use for values;
86      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
87      */
88     public ReferenceIdentityMap(int keyType, int valueType) {
89         super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, false);
90     }
91
92     /**
93      * Constructs a new <code>ReferenceIdentityMap</code> that will
94      * use the specified types of references.
95      *
96      * @param keyType the type of reference to use for keys;
97      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
98      * @param valueType the type of reference to use for values;
99      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
100      * @param purgeValues should the value be automatically purged when the
101      * key is garbage collected
102      */
103     public ReferenceIdentityMap(int keyType, int valueType, boolean purgeValues) {
104         super(keyType, valueType, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, purgeValues);
105     }
106
107     /**
108      * Constructs a new <code>ReferenceIdentityMap</code> with the
109      * specified reference types, load factor and initial capacity.
110      *
111      * @param keyType the type of reference to use for keys;
112      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
113      * @param valueType the type of reference to use for values;
114      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
115      * @param capacity the initial capacity for the map
116      * @param loadFactor the load factor for the map
117      */
118     public ReferenceIdentityMap(int keyType, int valueType, int capacity, float loadFactor) {
119         super(keyType, valueType, capacity, loadFactor, false);
120     }
121
122     /**
123      * Constructs a new <code>ReferenceIdentityMap</code> with the
124      * specified reference types, load factor and initial capacity.
125      *
126      * @param keyType the type of reference to use for keys;
127      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
128      * @param valueType the type of reference to use for values;
129      * must be {@link #HARD}, {@link #SOFT}, {@link #WEAK}
130      * @param capacity the initial capacity for the map
131      * @param loadFactor the load factor for the map
132      * @param purgeValues should the value be automatically purged when the
133      * key is garbage collected
134      */
135     public ReferenceIdentityMap(int keyType, int valueType, int capacity,
136                         float loadFactor, boolean purgeValues) {
137         super(keyType, valueType, capacity, loadFactor, purgeValues);
138     }
139
140     //-----------------------------------------------------------------------
141 /**
142      * Gets the hash code for the key specified.
143      * <p>
144      * This implementation uses the identity hash code.
145      *
146      * @param key the key to get a hash code for
147      * @return the hash code
148      */
149     protected int hash(Object JavaDoc key) {
150         return System.identityHashCode(key);
151     }
152
153     /**
154      * Gets the hash code for a MapEntry.
155      * <p>
156      * This implementation uses the identity hash code.
157      *
158      * @param key the key to get a hash code for, may be null
159      * @param value the value to get a hash code for, may be null
160      * @return the hash code, as per the MapEntry specification
161      */
162     protected int hashEntry(Object JavaDoc key, Object JavaDoc value) {
163         return System.identityHashCode(key) ^
164                System.identityHashCode(value);
165     }
166
167     /**
168      * Compares two keys for equals.
169      * <p>
170      * This implementation converts the key from the entry to a real reference
171      * before comparison and uses <code>==</code>.
172      *
173      * @param key1 the first key to compare passed in from outside
174      * @param key2 the second key extracted from the entry via <code>entry.key</code>
175      * @return true if equal by identity
176      */
177     protected boolean isEqualKey(Object JavaDoc key1, Object JavaDoc key2) {
178         key2 = (keyType > HARD ? ((Reference JavaDoc) key2).get() : key2);
179         return (key1 == key2);
180     }
181
182     /**
183      * Compares two values for equals.
184      * <p>
185      * This implementation uses <code>==</code>.
186      *
187      * @param value1 the first value to compare passed in from outside
188      * @param value2 the second value extracted from the entry via <code>getValue()</code>
189      * @return true if equal by identity
190      */
191     protected boolean isEqualValue(Object JavaDoc value1, Object JavaDoc value2) {
192         return (value1 == value2);
193     }
194
195     //-----------------------------------------------------------------------
196 /**
197      * Write the map out using a custom routine.
198      */
199     private void writeObject(ObjectOutputStream JavaDoc out) throws IOException JavaDoc {
200         out.defaultWriteObject();
201         doWriteObject(out);
202     }
203
204     /**
205      * Read the map in using a custom routine.
206      */
207     private void readObject(ObjectInputStream JavaDoc in) throws IOException JavaDoc, ClassNotFoundException JavaDoc {
208         in.defaultReadObject();
209         doReadObject(in);
210     }
211
212 }
213
Popular Tags