org.terracotta.collections
Interface ClusteredMap<K,V>

All Superinterfaces:

ConcurrentMap<K,V>, LockableMap<K>, Map<K,V>

All Known Implementing Classes:

ConcurrentDistributedMap, ConcurrentDistributedServerMap, EnterpriseConcurrentDistributedMap

public interface ClusteredMap<K,V>
extends ConcurrentMap<K,V>, LockableMap<K>

Nested Class Summary

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

Map.Entry<K,V>

Method Summary

ClusteredLock	createFinegrainedLock(K key) Create a lock for the given key.
boolean	flush(Object key, Object value) Attempt to recover any local memory resources used by this mapping.
Collection<Map.Entry<K,V>>	getAllEntriesSnapshot() A collection of all entries within this map.
Collection<Map.Entry<K,V>>	getAllLocalEntriesSnapshot() A collection of all in-heap entries within this map.
List<Map<K,V>>	getConstituentMaps() Get a list of the constituent maps that comprise this map.
Map.Entry<K,V>	getRandomEntry() Get a randomly selected entry from this map.
Map.Entry<K,V>	getRandomLocalEntry() Get a randomly selected in-heap entry from this map.
int	localSize() Return the count of local in-heap entries.
void	putNoReturn(K key, V value) Behaves the same as the standard Map.put(Object, Object)�method except that the previous value is not returned.
MapSizeListener	registerMapSizeListener(MapSizeListener newListener) Register a map-size listener on this map.
void	removeNoReturn(K key) Behaves the same as the standard Map.remove(Object) method except that the previous value is not returned.
boolean	tryRemove(Object key, long time, TimeUnit unit) Attempts to remove the mapping for the given key.
V	unlockedGet(Object key) Perform an unlocked read for the given key.
void	unlockedPutNoReturn(K key, V value) Performs an unlocked putNoReturn(Object, Object)
void	unlockedRemoveNoReturn(K key) Performs an unlocked removeNoReturn(Object)
V	unsafeGet(K key) Perform a local unlocked read for the given key.

Methods inherited from interface java.util.concurrent.ConcurrentMap

putIfAbsent, remove, replace, replace

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from interface org.terracotta.locking.LockableMap

lockEntry, unlockEntry

Method Detail

removeNoReturn

void removeNoReturn(K key)

Behaves the same as the standard Map.remove(Object) method except that the previous value is not returned. This can provide significant performance improvements when used in a Terracotta DSO cluster.

Parameters:

key - the key of the entry to remove

unsafeGet

V unsafeGet(K key)

Perform a local unlocked read for the given key.

This method performs no locking and thus provides absolutely no visibility guarantees. If the value is not local it will NOT be faulted and null is returned instead - thus one cannot distinguish between a non-existent mapping from an un-faulted value. USE WITH CAUTION

Parameters:

key - The key to lookup

Returns:

value mapped to the given key (but not necessarily the current mapping)

putNoReturn

void putNoReturn(K key,
                 V value)

Behaves the same as the standard Map.put(Object, Object)�method except that the previous value is not returned. This can provide significant performance improvements when used in a Terracotta DSO cluster.

Parameters:

key - the key of the entry to put

value - the value of the entry to put

unlockedGet

V unlockedGet(Object key)

Perform an unlocked read for the given key.

This method performs no locking and thus provides no visibility guarantees.

Parameters:

key - the key to lookup

Returns:

a value mapped to the given key (but not necessarily the current mapping)

tryRemove

boolean tryRemove(Object key,
                  long time,
                  TimeUnit unit)

Attempts to remove the mapping for the given key.

If the mapping is succesfully removed inside the specified time then true is returned.

Parameters:

key - key for the mapping to be removed

time - time to spend attempting removal

unit - time unit for the timeout

Returns:

true if the mapping was removed

registerMapSizeListener

MapSizeListener registerMapSizeListener(MapSizeListener newListener)

Register a map-size listener on this map.

This method returns the listener previously associated with this map. This allows for simple listener chaining or composition when multiple listeners are required. If no listener was previously registered then null is returned.

Parameters:

newListener - listener to register

Returns:

the previous listener

unlockedPutNoReturn

void unlockedPutNoReturn(K key,
                         V value)

Performs an unlocked putNoReturn(Object, Object)

unlockedRemoveNoReturn

void unlockedRemoveNoReturn(K key)

Performs an unlocked removeNoReturn(Object)

localSize

int localSize()

Return the count of local in-heap entries.

Returns:

count of local entries

flush

boolean flush(Object key,
              Object value)

Attempt to recover any local memory resources used by this mapping.

Parameters:

key - key for the mapping

value - value for the mapping

Returns:

true if memory was recovered

getAllLocalEntriesSnapshot

Collection<Map.Entry<K,V>> getAllLocalEntriesSnapshot()

A collection of all in-heap entries within this map.

Returns:

all in-heap map entries

getAllEntriesSnapshot

Collection<Map.Entry<K,V>> getAllEntriesSnapshot()

A collection of all entries within this map.

Returns:

all map entries

createFinegrainedLock

ClusteredLock createFinegrainedLock(K key)

Create a lock for the given key.

This methods returns as finegrained a lock that still provides exclusion against modification of the mapping for this key.

Specified by:

createFinegrainedLock in interface LockableMap<K>

Parameters:

key - the key for which a fine-grained lock has to be constructed

Returns:

an instance of fine-grained lock that can be used to perform primitive locking operations on a key

getConstituentMaps

List<Map<K,V>> getConstituentMaps()

Get a list of the constituent maps that comprise this map.

This list will be a singleton list whose element is this if this map is not a composite map.

Returns:

the constituent maps

getRandomEntry

Map.Entry<K,V> getRandomEntry()

Get a randomly selected entry from this map.

Returns:

a random map entry

getRandomLocalEntry

Map.Entry<K,V> getRandomLocalEntry()

Get a randomly selected in-heap entry from this map.

Returns:

a random in-heap entry