com.persistit

Class PersistitMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

com.persistit.PersistitMap<K,V>

All Implemented Interfaces:

Map<K,V>, SortedMap<K,V>

public class PersistitMap<K,V>
extends AbstractMap<K,V>
implements SortedMap<K,V>

A persistent java.util.SortedMap over a Persistit database. Keys and values inserted into this map are serialized and stored within Persistit using the encoding methods of Key and Value.

To construct a PersistitMap you supply an Exchange. The keys inserted into this map are appended to the key within the Tree originally supplied by the Exchange. For example, the code

 
 Exchange ex = new Exchange("demo", "composers", true);
 ex.append("My Favorite Johns");
 Map<String, String> map = new PersistitMap<String, String>(ex);
 map.put("Brahms", "Johannes");
 map.put("Bach", "Johann");
 
 

is equivalent to

 
 Exchange ex = new Exchange("demo", "composers", true);
 ex.getValue().put("Johannes");
 ex.clear().append("My Favorite Johns", "Brahms").store();
 ex.getValue().put("Johann");
 ex.clear().append("My Favorite Johns", "Bach").store();
 
 

By default any Iterators created by PersistitMap's collection views implement fail-fast behavior, meaning that methods of the the Iterator will throw a ConcurrentModificationException if the backing store has changed after the Iterator was created. However, in a large persistent database designed for concurrent access, it may be preferable to allow the Iterator to function continuously even when the underlying database is changing. The setAllowConcurrentModification(boolean) method provides control over this behavior.

PersistitMap departs from the general contract for SortedMap with respect to the Comparable interface. The ordering of items within the map is determined by the encoding of key values into their underlying serialized byte array representation (see Key Ordering ). Generally this ordering corresponds to the default Comparable implementation for each supported type. However, PersistitMap permits storage of key values that may not permit comparison under their compareTo implementations, does not require key values to implement Comparable, and ignores the ordering implemented by Comparable. Similarly, PersistitMap does not allow installation of a custom Comparator. To customize the ordering of key values in a PersistitMap, implement and register a custom KeyCoder.

Unlike other Map implementations, the methods of this class are thread-safe. Each of the Map methods is synchronized on this PersistitMap instance, and each of the methods of any collection view Iterator created by this Map is synchronized on that iterator. Thus this class enforces serialized access to its internal memory structures. However, for maximum concurrency an application that shares data among multiple threads should create a separate instance of PersistitMap for each thread backed by the same tree rather than sharing a single PersistitMap object. These PersistitMap instances can concurrently modify and query the same collection of data.

Unlike an in-memory implementation of SortedMap, this implementation serializes and deserializes object values into and from byte arrays stored as Persistit key/value pairs. Thus the put(K, V) and remove(java.lang.Object) methods not only read the former value from the database, but also incur the overhead of deserializing it. In many cases applications do not use the former value, and therefore this computation is often unnecessary. For maximum performance an application can use the putFast(java.lang.Object, java.lang.Object) and removeFast(java.lang.Object) methods. These methods are analogous to put(K, V) and remove(java.lang.Object) but do not deserialize or return the former object value.

The Iterator implementations returned by the keySet(), values() and entrySet() provide methods to set and access a KeyFilter for the iterator's traversal of keys in the map. With a filter in place, the iterator only returns keys, values or entries for records whose keys are selected by the filter.

Note on generic types: compile-time type verification cannot check the contents of the data stored in the backing B-Tree. Therefore the types of Key and Value objects stored in the B-Tree are not guaranteed to match the expected types. For example, the following will compile correctly but throw a ClassCastException at runtime:

 
 Exchange ex = new Exchange("demo", "composers", true);
 PersistitMap<String, Integer> map1 = new PersistitMap<String, Integer>();
 map1.put("Adams", Integer.valueOf(1));
 PersistitMap<String, String> map2 = new PersistitMap<String, String>();
 String lastName = map2.get("Adams");
 
 

Note that any PersistitException that may occur during execution of one of the SortedMap methods is thrown within the unchecked wrapper class PersistitMap.PersistitMapException. Applications using PersistitMap should catch and handled PersistitMapException.

Version:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PersistitMap.ExchangeEntry<K,V> Implement java.util.Map.Entry using a backing Persistit tree.
class	PersistitMap.ExchangeIterator<E> Implements java.util.Iterator using an underlying Persistit tree as the source of keys and values to be traversed.
static class	PersistitMap.PersistitMapException Unchecked wrapper for PersistitExceptions that may be thrown by methods of SortedMap.

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
PersistitMap(Exchange ex) Construct a PersistitMap over a particular Exchange.

Method Summary

Modifier and Type	Method and Description
void	clear() Removes all mappings from this map.
protected Object	clone() Returns a shallow copy of this AbstractMap instance: the keys and values themselves are not cloned.
Comparator<K>	comparator() Returns null because PersistitMap always uses Persistit's natural ordering and no other Comparator is possible.
boolean	containsKey(Object key) Determine whether this map contains a mapping for the specified key.
boolean	containsValue(Object value) Determine whether this map maps one or more keys to this value.
Set<Map.Entry<K,V>>	entrySet() Returns a Set of Map.Entry values corresponding with key-value pairs in the backing B-Tree.
boolean	equals(Object o) If the supplied object is also a Map, then this method determines whether the supplied map and this map contain the same entries.
K	firstKey() Returns the first (lowest) key currently in this PersistitMap determined by the key ordering specification.
V	get(Object key) Return the value to which this map maps the specified key.
int	hashCode() Returns the hash code value for this map.
SortedMap<K,V>	headMap(Object toKey) Returns a view of the portion of this PersistitMap whose keys are strictly less than toKey.
boolean	isAllowConcurrentModification() Indicate whether a new Iterators should throw a ConcurrentModificationException in the event the Persistit Tree backing this Map changes.
boolean	isEmpty() Return true if this map contains no key-value mappings.
Set<K>	keySet() Returns a Set view of the keys contained in this map.
K	lastKey() Returns the last (highest) key currently in this PersistitMap as determined by the key ordering specification.
V	put(K key, V value) Stores the specified value with the specified key in this map.
void	putAll(Map t) Copies all of the mappings from the specified map to this map.
void	putFast(Object key, Object value) Associates the specified value with the specified key in this map.
V	remove(Object key) Removes the mapping for this key from this map if present, and returns the former value.
void	removeFast(Object key) Removes the mapping for this key from this map if present.
void	setAllowConcurrentModification(boolean allow) Control whether iterators of the collection views of this Map will throw ConcurrentModificationException in the event the underlying physical database changes.
int	size() Return the number of key-value mappings in this map.
SortedMap<K,V>	subMap(Object fromKey, Object toKey) Returns a view of the portion of this PersistitMap whose keys range from fromKey, inclusive, to toKey, exclusive.
SortedMap<K,V>	tailMap(Object fromKey) Returns a view of the portion of this PersistitMap whose keys are greater than or equal to than fromKey.
String	toString() Returns a string representation of this map.
Collection<V>	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

PersistitMap

public PersistitMap(Exchange ex)

Construct a PersistitMap over a particular Exchange.

Parameters:

ex - A Exchange that serves as the parent of the Map's keys. This constructor makes a copy of the Exchange. The original Exchange is unchanged, and may be reused by the caller.

Method Detail

isAllowConcurrentModification

public boolean isAllowConcurrentModification()

Indicate whether a new Iterators should throw a ConcurrentModificationException in the event the Persistit Tree backing this Map changes.

Returns:

true if concurrent modifications are currently allowed, otherwise false.

setAllowConcurrentModification

public void setAllowConcurrentModification(boolean allow)

Control whether iterators of the collection views of this Map will throw ConcurrentModificationException in the event the underlying physical database changes. This property is used in constructing an new Iterator on a collection view. Changing this property after an Iterator has been constructed does not change that Iterator's behavior.

Parameters:

allow - Specify true to allow changes in the backing Tree. Specify false to cause newly constructed Iterators to throw a ConcurrentModificationException if the Persistit Tree backing this Map changes.

size

public int size()

Return the number of key-value mappings in this map. In the unlikely event the map contains more than Integer.MAX_VALUE elements, the value returned is Integer.MAX_VALUE.

This implementation enumerates all the members of the Map, which for a large database could be time-consuming.

Specified by:

size in interface Map<K,V>

Overrides:

size in class AbstractMap<K,V>

Returns:

the number of key-value mappings in this map.

isEmpty

public boolean isEmpty()

Return true if this map contains no key-value mappings.

This implementation is relatively efficient because it enumerates at most one child node of the Exchange to determine whether there are any children.

Specified by:

isEmpty in interface Map<K,V>

Overrides:

isEmpty in class AbstractMap<K,V>

Returns:

true if this map contains no key-value mappings.

containsValue

public boolean containsValue(Object value)

Determine whether this map maps one or more keys to this value. More formally, returns true if and only if this map contains at least one mapping to a value v such that

 (value==null ? v==null : value.equals(v))
 

This implementation implements a linear search across the child nodes of the Exchange, and can therefore be extremely time-consuming and resource-intensive for large databases.

Specified by:

containsValue in interface Map<K,V>

Overrides:

containsValue in class AbstractMap<K,V>

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to this value.

containsKey

public boolean containsKey(Object key)

Determine whether this map contains a mapping for the specified key. This implementation performs a direct B-Tree lookup and is designed to be fast.

Specified by:

containsKey in interface Map<K,V>

Overrides:

containsKey in class AbstractMap<K,V>

Parameters:

key - key whose presence in this map is to be tested.

Returns:

true if this map contains a mapping for the specified key.

Throws:

NullPointerException - key is null and this map does not not permit null keys.

get

public V get(Object key)

Return the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

This implementation iterates over entrySet() searching for an entry with the specified key. If such an entry is found, the entry's value is returned. If the iteration terminates without finding such an entry, null is returned. Note that this implementation requires linear time in the size of the map; many implementations will override this method.

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractMap<K,V>

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key.

Throws:

NullPointerException - if the key is null and this map does not not permit null keys.

See Also:

containsKey(Object)

put

public V put(K key,
             V value)

Stores the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced. This method returns the old value, if present, or null if there was no former value. An application that does not require the former value can use putFast(java.lang.Object, java.lang.Object) to avoid incurring the cost of deserializing that value.

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMap<K,V>

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. (A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.)

Throws:

ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

IllegalArgumentException - if some aspect of this key or value * prevents it from being stored in this map.

putFast

public void putFast(Object key,
                    Object value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced.

This method differs from put(K, V) by not returning the previous value. In order to return the previous value, put must deserialize it, which can be costly. Applications that don't need that value can benefit from calling putFast instead of put.

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Throws:

ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

IllegalArgumentException - if some aspect of this key or value * prevents it from being stored in this map.

remove

public V remove(Object key)

Removes the mapping for this key from this map if present, and returns the former value. Applications that do not require the former value can use removeFast(java.lang.Object) to improve performance.

Specified by:

remove in interface Map<K,V>

Overrides:

remove in class AbstractMap<K,V>

Parameters:

key - key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no entry for key. (A null return can also indicate that the map previously associated null with the specified key.)

removeFast

public void removeFast(Object key)

Removes the mapping for this key from this map if present. Unlike remove(java.lang.Object), this method does not return the former value, and therefore does not incur the cost of deserializing it.

Parameters:

key - key whose mapping is to be removed from the map.

putAll

public void putAll(Map t)

Copies all of the mappings from the specified map to this map. These mappings will replace any mappings that this map had for any of the keys currently in the specified map.

This implementation iterates over the specified map's entrySet() collection, and calls this map's put operation once for each entry returned by the iteration.

Specified by:

putAll in interface Map<K,V>

Overrides:

putAll in class AbstractMap<K,V>

Parameters:

t - mappings to be stored in this map.

Throws:

ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map.

IllegalArgumentException - if some aspect of a key or value in the specified map prevents it from being stored in this map.

NullPointerException - the specified map is null.

clear

public void clear()

Removes all mappings from this map.

This implementation calls entrySet().clear().

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractMap<K,V>

keySet

public Set<K> keySet()

Returns a Set view of the keys contained in this map. The Set is backed by the map, so changes to the map are reflected in the Set, and vice-versa. (If the map is modified while an iteration over the Set is in progress, the results of the iteration are undefined.) The Set supports element removal, which removes the corresponding entry from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

This implementation returns a Set that subclasses AbstractSet. The subclass's iterator method returns a "wrapper object" over this map's entrySet() iterator. The size method delegates to this map's size method and the contains method delegates to this map's containsKey method.

The Set is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same Set.

Specified by:

keySet in interface Map<K,V>

Specified by:

keySet in interface SortedMap<K,V>

Overrides:

keySet in class AbstractMap<K,V>

Returns:

a Set view of the keys contained in this map.

values

public Collection<V> values()

Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. (If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined.) The collection supports element removal, which removes the corresponding entry from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

This implementation returns a collection that subclasses abstract collection. The subclass's iterator method returns a "wrapper object" over this map's entrySet() iterator. The size method delegates to this map's size method and the contains method delegates to this map's containsValue method.

The collection is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same Collection.

Specified by:

values in interface Map<K,V>

Specified by:

values in interface SortedMap<K,V>

Overrides:

values in class AbstractMap<K,V>

Returns:

a collection view of the values contained in this map.

entrySet

public Set<Map.Entry<K,V>> entrySet()

Returns a Set of Map.Entry values corresponding with key-value pairs in the backing B-Tree.

Specified by:

entrySet in interface Map<K,V>

Specified by:

entrySet in interface SortedMap<K,V>

Specified by:

entrySet in class AbstractMap<K,V>

Returns:

a set view of the mappings contained in this map.

comparator

public Comparator<K> comparator()

Returns null because PersistitMap always uses Persistit's natural ordering and no other Comparator is possible.

Specified by:

comparator in interface SortedMap<K,V>

Returns:

null

subMap

public SortedMap<K,V> subMap(Object fromKey,
                             Object toKey)

Returns a view of the portion of this PersistitMap whose keys range from fromKey, inclusive, to toKey, exclusive. The view is another PersistitMap instance backed by this one; any change to the collection made by either by either instance is reflected in the other.

Specified by:

subMap in interface SortedMap<K,V>

Parameters:

fromKey - low endpoint (inclusive) of the subMap.

toKey - high endpoint (exclusive) of the subMap.

Returns:

a view of the specified range within this sorted map.

headMap

public SortedMap<K,V> headMap(Object toKey)

Returns a view of the portion of this PersistitMap whose keys are strictly less than toKey. The view is another PersistitMap instance backed by this one; any change to the collection made by either by either instance is reflected in the other.

Specified by:

headMap in interface SortedMap<K,V>

Parameters:

toKey - high endpoint (exclusive) of the subMap.

Returns:

a view of the specified range within this sorted map.

tailMap

public SortedMap<K,V> tailMap(Object fromKey)

Returns a view of the portion of this PersistitMap whose keys are greater than or equal to than fromKey. The view is another PersistitMap instance backed by this one; any change to the collection made by either by either instance is reflected in the other.

Specified by:

tailMap in interface SortedMap<K,V>

Parameters:

fromKey - low endpoint (inclusive) of the subMap.

Returns:

a view of the specified range within this sorted map.

firstKey

public K firstKey()

Returns the first (lowest) key currently in this PersistitMap determined by the key ordering specification.

Specified by:

firstKey in interface SortedMap<K,V>

Returns:

the first (lowest) key currently in the backing store for this PersistitMap.

Throws:

NoSuchElementException - if this map is empty.

lastKey

public K lastKey()

Returns the last (highest) key currently in this PersistitMap as determined by the key ordering specification.

Specified by:

lastKey in interface SortedMap<K,V>

Returns:

the last (highest) key currently in the backing store for this PersistitMap.

Throws:

NoSuchElementException - if this map is empty.

equals

public boolean equals(Object o)

If the supplied object is also a Map, then this method determines whether the supplied map and this map contain the same entries. This is implemented by testing set equality between the entrySets of the two maps. Generally this operation is not useful on a backing database that is large and/or changing is discouraged in most cases.

Specified by:

equals in interface Map<K,V>

Overrides:

equals in class AbstractMap<K,V>

Parameters:

o - object to be compared for equality with this map.

Returns:

true if the specified object is equal to this map.

hashCode

public int hashCode()

Returns the hash code value for this map. The hash code is the sum of the hash codes of each Map.Entry value in the entry set. The hash code value is generally not useful on a backing database that is large and/or changing, and therefore use of this method is discouraged in most cases.

Specified by:

hashCode in interface Map<K,V>

Overrides:

hashCode in class AbstractMap<K,V>

Returns:

the hash code value for this map.

See Also:

Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), Set.equals(Object)

toString

public String toString()

Returns a string representation of this map. The string representation consists of a list of key-value mappings in the order returned by the map's entrySet view's iterator, enclosed in braces ( "{}"). Adjacent mappings are separated by the characters ", " (comma and space). Each key-value mapping is rendered as the key followed by an equals sign ("=") followed by the associated value. Keys and values are converted to strings as by String.valueOf(Object).

Overrides:

toString in class AbstractMap<K,V>

Returns:

a String representation of this map.

clone

protected Object clone()
                throws CloneNotSupportedException

Returns a shallow copy of this AbstractMap instance: the keys and values themselves are not cloned.

Overrides:

clone in class AbstractMap<K,V>

Returns:

a shallow copy of this map.

Throws:

CloneNotSupportedException