com.bigdata.btree

Class BigdataMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

com.bigdata.btree.BigdataMap<K,V>

All Implemented Interfaces:

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

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

A flyweight SortedMap wrapping an IIndex.

Note: The BigdataMap has the same concurrency constraints as the BTree - it is single-threaded for writes and allows concurrent readers. When wrapping a scale-out index, the ConcurrencyManager will automatically provide appropriate concurrency controls. When wrapping a local index, you can use an UnisolatedReadWriteIndex to impose Map operation level concurrency control if your application does not otherwise handle this constraint. Also, note that point tests for the scale-out indices are VERY expensive when compared to ordered reads and writes.

Note: The total order of the BigdataMap is completely determined by ITupleSerializer.serializeKey(Object). There is NO concept of a Comparator. The ITupleSerializer is responsible for coercing application keys into variable length unsigned byte[]s which are the keys for the underlying B+Tree. The order for the B+Tree is the natural order for the unsigned byte[]s. KeyBuilder supports the generation of unsigned byte[]s from various kinds of Java primitives and Unicode Strings and is typically used to write the ITupleSerializer.serializeKey(Object) method.

Note: The coercion of the application keys into unsigned byte[]s is not type safe unless you either consistently use a strongly typed instance of this class or specify an ITupleSerializer for the backing B+Tree that only allows application keys that are instances of acceptable classes. This issue is more critical for keys than for values since the keys define the total index order and the default coercion rules for keys are provided by KeyBuilder.append(Object) which does not attempt to partition the key space by the application key type (keys are not safely polymorphic by default).

Note: When storing Java objects in the tuple value, the value MUST be treated as if it is immutable since it will be serialized on insert or update and deserialized on read. In particular, the pattern of updating the value stored in the map without put(Object, Object)ting the value back into the map WILL NOT cause the value associated with the tuple to be updated.

Note: Both Map.equals(Object) and Map.hashCode() are VERY expensive, but that is how they are defined.

Version:

$Id$

Author:

Bryan Thompson

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	BigdataMap.Entry Note: Since the same ITuple instance is returned for each tuple by many ITupleIterators there is a side-effect that invalidates the last visited Map.Entry object.
protected class	BigdataMap.EntrySet Implementation supporting entrySet().
protected class	BigdataMap.EntrySetIterator Iterator visiting Map.Entry objects in support of BigdataMap.EntrySet.

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

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

Constructor Summary

Constructors

Constructor and Description
BigdataMap(IIndex ndx) Wrap an index as a SortedMap.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear()
Comparator<? super K>	comparator() There is no means available to specify a Comparator for the SortedMap.
boolean	containsKey(Object key)
boolean	containsValue(Object value) Note: This performs an index scan (since the values of the map are unordered) but stops as soon as a match is found.
Set<Map.Entry<K,V>>	entrySet() Note: AbstractMap.keySet() and AbstractMap.values() both depend on this method.
K	firstKey()
V	get(Object key)
IIndex	getIndex() The backing index.
SortedMap<K,V>	headMap(K toKey) A SortedMap view onto the backing B+Tree which imposes the specified key-range restriction.
boolean	isEmpty()
K	lastKey()
V	put(K key, V val)
void	putAll(Map<? extends K,? extends V> t)
long	rangeCount(boolean exactCount) The #of non-deleted entries in the map.
V	remove(Object key)
int	size() The #of index entries.
SortedMap<K,V>	subMap(K fromKey, K toKey) A SortedMap view onto the backing B+Tree which imposes the specified key-range restriction.
SortedMap<K,V>	tailMap(K fromKey) A SortedMap view onto the backing B+Tree which imposes the specified key-range restriction.

Methods inherited from class java.util.AbstractMap

clone, equals, hashCode, keySet, toString, values

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.SortedMap

keySet, values

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

BigdataMap

public BigdataMap(IIndex ndx)

Wrap an index as a SortedMap.

Parameters:

ndx - The index.

Method Detail

getIndex

public IIndex getIndex()

The backing index.

clear

public void clear()

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class AbstractMap<K,V>

putAll

public void putAll(Map<? extends K,? extends V> t)

Specified by:

putAll in interface Map<K,V>

Overrides:

putAll in class AbstractMap<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

Overrides:

get in class AbstractMap<K,V>

put

public V put(K key,
    V val)

Specified by:

put in interface Map<K,V>

Overrides:

put in class AbstractMap<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

Overrides:

remove in class AbstractMap<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

Overrides:

containsKey in class AbstractMap<K,V>

containsValue

public boolean containsValue(Object value)

Note: This performs an index scan (since the values of the map are unordered) but stops as soon as a match is found.

Specified by:

containsValue in interface Map<K,V>

Overrides:

containsValue in class AbstractMap<K,V>

size

public int size()

The #of index entries. When there are more than Integer.MAX_VALUE entries then this method will report Integer.MAX_VALUE entries. If the backing index supports delete markers then an index scan will be performed in order to count the #of non-deleted index entries.

Specified by:

size in interface Map<K,V>

Overrides:

size in class AbstractMap<K,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

Overrides:

isEmpty in class AbstractMap<K,V>

rangeCount

public long rangeCount(boolean exactCount)

The #of non-deleted entries in the map.

Parameters:

exactCount - When true the result will be an exact count, which will require a full key-range scan if delete markers are enabled for the index.

Returns:

The #of entries in the map. When exactCount is false and delete markers are being used, then this will be an upper bound.

See Also:

IRangeQuery.rangeCount(byte[], byte[])

comparator

public final Comparator<? super K> comparator()

There is no means available to specify a Comparator for the SortedMap. Application keys are first converted into unsigned byte[] keys using the configured ITupleSerializer for the backing B+Tree. The index order is directly determined by those keys.

Specified by:

comparator in interface SortedMap<K,V>

Returns:

Always returns null.

firstKey

public K firstKey()

Specified by:

firstKey in interface SortedMap<K,V>

Throws:

UnsupportedOperationException - if the ITupleSerializer does not implement the optional ITupleSerializer.deserializeKey(ITuple) method.

lastKey

public K lastKey()

Specified by:

lastKey in interface SortedMap<K,V>

Throws:

UnsupportedOperationException - if the ITupleSerializer does not implement the optional ITupleSerializer.deserializeKey(ITuple) method.

headMap

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

A SortedMap view onto the backing B+Tree which imposes the specified key-range restriction.

Specified by:

headMap in interface SortedMap<K,V>

subMap

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

A SortedMap view onto the backing B+Tree which imposes the specified key-range restriction.

Specified by:

subMap in interface SortedMap<K,V>

tailMap

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

A SortedMap view onto the backing B+Tree which imposes the specified key-range restriction.

Specified by:

tailMap in interface SortedMap<K,V>

entrySet

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

Note: AbstractMap.keySet() and AbstractMap.values() both depend on this method.

Specified by:

entrySet in interface Map<K,V>

Specified by:

entrySet in interface SortedMap<K,V>

Specified by:

entrySet in class AbstractMap<K,V>