2
* See the file LICENSE for redistribution information.
4
* Copyright (c) 2000-2004
5
* Sleepycat Software. All rights reserved.
7
* $Id: StoredMap.java,v 1.4 2004/09/22 18:01:03 bostic Exp $
10
package com.sleepycat.collections;
12
import java.util.Collection;
13
import java.util.Collections;
14
import java.util.Iterator;
18
import com.sleepycat.bind.EntityBinding;
19
import com.sleepycat.bind.EntryBinding;
20
import com.sleepycat.db.Database;
23
* A Map view of a {@link Database}.
25
* <p><em>Note that this class does not conform to the standard Java
26
* collections interface in the following ways:</em></p>
28
* <li>The {@link #size} method always throws
29
* <code>UnsupportedOperationException</code> because, for performance reasons,
30
* databases do not maintain their total record count.</li>
31
* <li>All iterators must be explicitly closed using {@link
32
* StoredIterator#close()} or {@link StoredIterator#close(java.util.Iterator)}
33
* to release the underlying database cursor resources.</li>
36
* <p>In addition to the standard Map methods, this class provides the
37
* following methods for stored maps only. Note that the use of these methods
38
* is not compatible with the standard Java collections interface.</p>
40
* <li>{@link #duplicates(Object)}</li>
41
* <li>{@link #append(Object)}</li>
46
public class StoredMap extends StoredContainer implements Map {
48
private StoredKeySet keySet;
49
private boolean keySetInitialized = false;
50
private StoredEntrySet entrySet;
51
private boolean entrySetInitialized = false;
52
private StoredValueSet valueSet;
53
private boolean valueSetInitialized = false;
56
* Creates a map view of a {@link Database}.
58
* @param database is the Database underlying the new collection.
60
* @param keyBinding is the binding used to translate between key buffers
63
* @param valueBinding is the binding used to translate between value
64
* buffers and value objects.
66
* @param writeAllowed is true to create a read-write collection or false
67
* to create a read-only collection.
69
* @throws IllegalArgumentException if formats are not consistently
70
* defined or a parameter is invalid.
72
* @throws RuntimeExceptionWrapper if a {@link
73
* com.sleepycat.db.DatabaseException} is thrown.
75
public StoredMap(Database database, EntryBinding keyBinding,
76
EntryBinding valueBinding, boolean writeAllowed) {
78
super(new DataView(database, keyBinding, valueBinding, null,
83
* Creates a map view of a {@link Database} with a {@link
84
* PrimaryKeyAssigner}. Writing is allowed for the created map.
86
* @param database is the Database underlying the new collection.
88
* @param keyBinding is the binding used to translate between key buffers
91
* @param valueBinding is the binding used to translate between value
92
* buffers and value objects.
94
* @param keyAssigner is used by the {@link #append} method to assign
97
* @throws IllegalArgumentException if formats are not consistently
98
* defined or a parameter is invalid.
100
* @throws RuntimeExceptionWrapper if a {@link
101
* com.sleepycat.db.DatabaseException} is thrown.
103
public StoredMap(Database database, EntryBinding keyBinding,
104
EntryBinding valueBinding,
105
PrimaryKeyAssigner keyAssigner) {
107
super(new DataView(database, keyBinding, valueBinding, null,
111
protected Object clone()
112
throws CloneNotSupportedException {
114
// cached collections must be cleared and recreated with the new view
115
// of the map to inherit the new view's properties
116
StoredMap other = (StoredMap) super.clone();
118
other.keySetInitialized = false;
119
other.entrySet = null;
120
other.entrySetInitialized = false;
121
other.valueSet = null;
122
other.valueSetInitialized = false;
127
* Creates a map entity view of a {@link Database}.
129
* @param database is the Database underlying the new collection.
131
* @param keyBinding is the binding used to translate between key buffers
134
* @param valueEntityBinding is the binding used to translate between
135
* key/value buffers and entity value objects.
137
* @param writeAllowed is true to create a read-write collection or false
138
* to create a read-only collection.
140
* @throws IllegalArgumentException if formats are not consistently
141
* defined or a parameter is invalid.
143
* @throws RuntimeExceptionWrapper if a {@link
144
* com.sleepycat.db.DatabaseException} is thrown.
146
public StoredMap(Database database, EntryBinding keyBinding,
147
EntityBinding valueEntityBinding, boolean writeAllowed) {
149
super(new DataView(database, keyBinding, null, valueEntityBinding,
150
writeAllowed, null));
154
* Creates a map entity view of a {@link Database} with a {@link
155
* PrimaryKeyAssigner}. Writing is allowed for the created map.
157
* @param database is the Database underlying the new collection.
159
* @param keyBinding is the binding used to translate between key buffers
162
* @param valueEntityBinding is the binding used to translate between
163
* key/value buffers and entity value objects.
165
* @param keyAssigner is used by the {@link #append} method to assign
168
* @throws IllegalArgumentException if formats are not consistently
169
* defined or a parameter is invalid.
171
* @throws RuntimeExceptionWrapper if a {@link
172
* com.sleepycat.db.DatabaseException} is thrown.
174
public StoredMap(Database database, EntryBinding keyBinding,
175
EntityBinding valueEntityBinding,
176
PrimaryKeyAssigner keyAssigner) {
178
super(new DataView(database, keyBinding, null, valueEntityBinding,
182
StoredMap(DataView view) {
188
* Returns the value to which this map maps the specified key. If
189
* duplicates are allowed, this method returns the first duplicate, in the
190
* order in which duplicates are configured, that maps to the specified
193
* This method conforms to the {@link Map#get} interface.
195
* @throws RuntimeExceptionWrapper if a {@link
196
* com.sleepycat.db.DatabaseException} is thrown.
198
public Object get(Object key) {
200
return super.get(key);
204
* Associates the specified value with the specified key in this map
205
* (optional operation). If duplicates are allowed and the specified key
206
* is already mapped to a value, this method appends the new duplicate
207
* after the existing duplicates. This method conforms to the {@link
208
* Map#put} interface.
210
* <p>The key parameter may be null if an entity binding is used and the
211
* key will be derived from the value (entity) parameter. If an entity
212
* binding is used and the key parameter is non-null, then the key
213
* parameter must be equal to the key derived from the value parameter.</p>
215
* @return the previous value associated with specified key, or null if
216
* there was no mapping for the key or if duplicates are allowed.
218
* @throws UnsupportedOperationException if the collection is indexed, or
219
* if the collection is read-only.
221
* @throws IllegalArgumentException if an entity value binding is used and
222
* the primary key of the value given is different than the existing stored
225
* @throws RuntimeExceptionWrapper if a {@link
226
* com.sleepycat.db.DatabaseException} is thrown.
228
public Object put(Object key, Object value) {
230
return super.put(key, value);
234
* Appends a given value returning the newly assigned key. If a {@link
235
* PrimaryKeyAssigner} is associated with Store for this map, it will be
236
* used to assigned the returned key. Otherwise the Store must be a QUEUE
237
* or RECNO database and the next available record number is assigned as
238
* the key. This method does not exist in the standard {@link Map}
241
* @param value the value to be appended.
243
* @return the assigned key.
245
* @throws UnsupportedOperationException if the collection is indexed, or
246
* if the collection is read-only, or if the Store has no {@link
247
* PrimaryKeyAssigner} and is not a QUEUE or RECNO database.
249
* @throws RuntimeExceptionWrapper if a {@link
250
* com.sleepycat.db.DatabaseException} is thrown.
252
public Object append(Object value) {
254
boolean doAutoCommit = beginAutoCommit();
256
Object[] key = new Object[1];
257
view.append(value, key, null);
258
commitAutoCommit(doAutoCommit);
260
} catch (Exception e) {
261
throw handleException(e, doAutoCommit);
266
* Removes the mapping for this key from this map if present (optional
267
* operation). If duplicates are allowed, this method removes all
268
* duplicates for the given key. This method conforms to the {@link
269
* Map#remove} interface.
271
* @throws UnsupportedOperationException if the collection is read-only.
273
* @throws RuntimeExceptionWrapper if a {@link
274
* com.sleepycat.db.DatabaseException} is thrown.
276
public Object remove(Object key) {
278
Object[] oldVal = new Object[1];
279
removeKey(key, oldVal);
284
* Returns true if this map contains the specified key. This method
285
* conforms to the {@link Map#containsKey} interface.
287
* @throws RuntimeExceptionWrapper if a {@link
288
* com.sleepycat.db.DatabaseException} is thrown.
290
public boolean containsKey(Object key) {
292
return super.containsKey(key);
296
* Returns true if this map contains the specified value. When an entity
297
* binding is used, this method returns whether the map contains the
298
* primary key and value mapping of the entity. This method conforms to
299
* the {@link Map#containsValue} interface.
301
* @throws RuntimeExceptionWrapper if a {@link
302
* com.sleepycat.db.DatabaseException} is thrown.
304
public boolean containsValue(Object value) {
306
return super.containsValue(value);
310
* Copies all of the mappings from the specified map to this map (optional
311
* operation). When duplicates are allowed, the mappings in the specified
312
* map are effectively appended to the existing mappings in this map, that
313
* is no previously existing mappings in this map are replaced. This
314
* method conforms to the {@link Map#putAll} interface.
316
* @throws UnsupportedOperationException if the collection is read-only, or
317
* if the collection is indexed.
319
* @throws RuntimeExceptionWrapper if a {@link
320
* com.sleepycat.db.DatabaseException} is thrown.
322
public void putAll(Map map) {
324
boolean doAutoCommit = beginAutoCommit();
325
Iterator entries = null;
327
entries = map.entrySet().iterator();
328
while (entries.hasNext()) {
329
Map.Entry entry = (Map.Entry) entries.next();
330
put(entry.getKey(), entry.getValue());
332
StoredIterator.close(entries);
333
commitAutoCommit(doAutoCommit);
334
} catch (Exception e) {
335
StoredIterator.close(entries);
336
throw handleException(e, doAutoCommit);
341
* Returns a set view of the keys contained in this map. A {@link
342
* java.util.SortedSet} is returned if the map is ordered. The returned
343
* collection will be read-only if the map is read-only. This method
344
* conforms to the {@link Map#keySet()} interface.
346
* @return a {@link StoredKeySet} or a {@link StoredSortedKeySet} for this
349
* @throws RuntimeExceptionWrapper if a {@link
350
* com.sleepycat.db.DatabaseException} is thrown.
353
* @see #isWriteAllowed
355
public Set keySet() {
357
if (!keySetInitialized) {
358
synchronized (this) {
359
if (!keySetInitialized) {
360
DataView newView = view.keySetView();
362
keySet = new StoredSortedKeySet(newView);
364
keySet = new StoredKeySet(newView);
366
keySetInitialized = true;
374
* Returns a set view of the mappings contained in this map. A {@link
375
* java.util.SortedSet} is returned if the map is ordered. The returned
376
* collection will be read-only if the map is read-only. This method
377
* conforms to the {@link Map#entrySet()} interface.
379
* @return a {@link StoredEntrySet} or a {@link StoredSortedEntrySet} for
382
* @throws RuntimeExceptionWrapper if a {@link
383
* com.sleepycat.db.DatabaseException} is thrown.
386
* @see #isWriteAllowed
388
public Set entrySet() {
390
if (!entrySetInitialized) {
391
synchronized (this) {
392
if (!entrySetInitialized) {
394
entrySet = new StoredSortedEntrySet(view);
396
entrySet = new StoredEntrySet(view);
398
entrySetInitialized = true;
406
* Returns a collection view of the values contained in this map. A {@link
407
* java.util.SortedSet} is returned if the map is ordered and the
408
* value/entity binding can be used to derive the map's key from its
409
* value/entity object. The returned collection will be read-only if the
410
* map is read-only. This method conforms to the {@link Map#entrySet()}
413
* @return a {@link StoredValueSet} or a {@link StoredSortedValueSet} for
416
* @throws RuntimeExceptionWrapper if a {@link
417
* com.sleepycat.db.DatabaseException} is thrown.
420
* @see #isWriteAllowed
422
public Collection values() {
424
if (!valueSetInitialized) {
425
synchronized (this) {
426
if (!valueSetInitialized) {
427
DataView newView = view.valueSetView();
428
if (isOrdered() && newView.canDeriveKeyFromValue()) {
429
valueSet = new StoredSortedValueSet(newView);
431
valueSet = new StoredValueSet(newView);
433
valueSetInitialized = true;
441
* Returns a new collection containing the values mapped to the given key
442
* in this map. This collection's iterator() method is particularly useful
443
* for iterating over the duplicates for a given key, since this is not
444
* supported by the standard Map interface. This method does not exist in
445
* the standard {@link Map} interface.
447
* <p>If no mapping for the given key is present, an empty collection is
448
* returned. If duplicates are not allowed, at most a single value will be
449
* in the collection returned. If duplicates are allowed, the returned
450
* collection's add() method may be used to add values for the given
453
* @param key is the key for which values are to be returned.
455
* @throws RuntimeExceptionWrapper if a {@link
456
* com.sleepycat.db.DatabaseException} is thrown.
458
public Collection duplicates(Object key) {
461
DataView newView = view.valueSetView(key);
462
return new StoredValueSet(newView, true);
463
} catch (KeyRangeException e) {
464
return Collections.EMPTY_SET;
465
} catch (Exception e) {
466
throw StoredContainer.convertException(e);
471
* Compares the specified object with this map for equality. A value
472
* comparison is performed by this method and the stored values are
473
* compared rather than calling the equals() method of each element. This
474
* method conforms to the {@link Map#equals} interface.
476
* @throws RuntimeExceptionWrapper if a {@link
477
* com.sleepycat.db.DatabaseException} is thrown.
479
public boolean equals(Object other) {
481
if (other instanceof Map) {
482
return entrySet().equals(((Map) other).entrySet());
489
* Add this in to keep FindBugs from whining at us about implementing
490
* equals(), but not hashCode().
492
public int hashCode() {
493
return super.hashCode();
497
* Converts the map to a string representation for debugging. WARNING: All
498
* mappings will be converted to strings and returned and therefore the
499
* returned string may be very large.
501
* @return the string representation.
503
* @throws RuntimeExceptionWrapper if a {@link
504
* com.sleepycat.db.DatabaseException} is thrown.
506
public String toString() {
508
return entrySet().toString();
added
removed
db/java/src/com/sleepycat/collections/StoredMap.java
