com.tangosol.net.partition

Class PartitionSplittingBackingMap

java.lang.Object

com.tangosol.util.Base

com.tangosol.util.AbstractKeyBasedMap

com.tangosol.net.partition.PartitionSplittingBackingMap

All Implemented Interfaces:

com.oracle.coherence.common.base.Disposable, PartitionAwareBackingMap, AutoCloseable, Map

Direct Known Subclasses:

ObservableSplittingBackingCache.CapacityAwareMap

public class PartitionSplittingBackingMap
extends AbstractKeyBasedMap
implements com.oracle.coherence.common.base.Disposable, PartitionAwareBackingMap

In a partitioned configuration, the PartitionSplittingBackingMap is a "map multi-plexer" that enables multiple backing maps to be used in place of a single backing map. The data and operations related to each partition are routed by the PartitionSplittingBackingMap to a partition-specific backing map. The two primary benefits are:

1. Less data are stored in each backing map, potentially enabling much more total data to be managed, and
2. each partition is managed by a separate data structure, potentially increasing concurrency by spreading concurrent operations over multiple data structures.

Also, as with all usage of BinaryMap, if the data are stored off-heap, the proper use of the MaxDirectMemorySize JVM switch will be crucial.

Since:

Coherence 3.5

Author:

cp 2008-11-20

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PartitionSplittingBackingMap.AggregatingCacheStatistics An implementation of the CacheStatics interface that aggregates across the CacheStatics objects provided by each of the backing maps corresponding to the partitions managed by this PartitionSplittingBackingMap.
protected class	PartitionSplittingBackingMap.KeySet A KeySet implementation optimized for PartitionSplittingBackingMap.
static class	PartitionSplittingBackingMap.MapArray The MapArray is a data structure that provides a mapping between partition IDs and backing maps.
class	PartitionSplittingBackingMap.MaskedPartitionMap A read-only view into a subset of backing maps managed by the underlying PartitionSplittingBackingMap.
class	PartitionSplittingBackingMap.PartitionedIterator An Iterator designed to ensure that a stable copy of each partition's keys is available for the duration of the iteration over its keys.

Nested classes/interfaces inherited from class com.tangosol.util.AbstractKeyBasedMap

AbstractKeyBasedMap.DeferredCacheEvent<K,V>, AbstractKeyBasedMap.EntrySet, AbstractKeyBasedMap.ValuesCollection

Nested classes/interfaces inherited from class com.tangosol.util.Base

Base.LoggingWriter, Base.StackFrame

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

Map.Entry<K,V>

Field Summary

Fields inherited from class com.tangosol.util.Base

LOG_ALWAYS, LOG_DEBUG, LOG_ERR, LOG_INFO, LOG_MAX, LOG_MIN, LOG_QUIET, LOG_WARN, POWER_0, POWER_G, POWER_K, POWER_M, POWER_T, UNIT_D, UNIT_H, UNIT_M, UNIT_MS, UNIT_NS, UNIT_S, UNIT_US

Constructor Summary

Constructors

Constructor and Description
PartitionSplittingBackingMap(BackingMapManager bmm, String sName) Create a PartitionSplittingBackingMap that will delegate each partition's data and operations to a separate backing map.

Method Summary

Modifier and Type	Method and Description
void	clear() Clear all key/value mappings.
boolean	containsKey(Object oKey) Returns true if this map contains a mapping for the specified key.
void	createPartition(int nPid) Add a partition to the PartitionAwareBackingMap.
void	destroyPartition(int nPid) Remove a partition from the PartitionAwareBackingMap.
void	dispose() Invoked when all resources owned by the implementer can safely be released.
Object	get(Object oKey) Returns the value to which this map maps the specified key.
protected Map	getBackingMap(Object oKey) Obtain a backing map for the specified key.
BackingMapManager	getBackingMapManager() Obtain the BackingMapManager that this PartitionAwareBackingMap uses to instantiate and release backing maps.
CacheStatistics	getCacheStatistics() Returns the CacheStatistics for this cache.
protected BackingMapManagerContext	getContext() Obtain the BackingMapManagerContext that provides the partition information for keys that are stored in the backing map.
protected PartitionSplittingBackingMap.MapArray	getMapArray() Get the mapping between partition IDs and backing maps.
String	getName() Determine the name of the cache for which this PartitionAwareBackingMap exists.
Map	getPartitionMap(int nPid) Obtain a Map view for the data in a specific partition.
Map	getPartitionMap(PartitionSet partitions) Obtain a Map view for the data in a specific set of partitions.
protected Set	instantiateKeySet() Factory pattern: Create a Set that represents the keys in the Map
boolean	isEmpty() Returns true if this map contains no key-value mappings.
protected boolean	isEmpty(Map[] amap) Return true iff a subset of the maps that belong to specified partitions contains no entries.
boolean	isStrict() Determine if any access to data in missing partitions is being treated as an error.
protected Iterator	iterateKeys() Create an iterator over the keys in this Map.
protected Iterator	iterateKeys(Map[] amap) Create an iterator over the keys in maps that belong to partitions contained in the specified PartitionSet.
protected String	makeName(String sName, int nPid) Format a synthetic name for a partition-specific backing map.
Object	put(Object oKey, Object oValue) Associates the specified value with the specified key in this map.
void	putAll(Map map) Copies all of the mappings from the specified map to this map.
protected void	putAllInternal(Map mapPart, Map mapUpdate) Put all entries in mapUpdate into the provided map.
protected Object	putInternal(Map mapPart, Object oKey, Object oValue) Put the key and value into a map representing a given partition.
Object	remove(Object oKey) Removes the mapping for this key from this map if present.
protected boolean	removeBlind(Object oKey) Removes the mapping for this key from this map if present.
protected void	reportMissingPartition(Object oKey, int nPid) Report a missing partition according to the "strict" flag rules.
void	setStrict(boolean fStrict) Specify whether any access to data in missing partitions should be treated as an error.
int	size() Returns the number of key-value mappings in this map.
protected int	size(Map[] amap) Return the number of key-value mappings in a subset of the maps that belong to specified partitions.
String	toString() Return a human-readable description for this PartitionBackingMap.
String	toString(boolean fVerbose) Return a human-readable description for this PartitionBackingMap.

Methods inherited from class com.tangosol.util.AbstractKeyBasedMap

clone, containsValue, entrySet, equals, getAll, hashCode, instantiateEntrySet, instantiateValues, keySet, values

Methods inherited from class com.tangosol.util.Base

azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureBigDecimal, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getProcessRandom, getRandom, getRandomBinary, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, mod, mod, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parsePercentage, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, truncateString, wait

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.oracle.coherence.common.base.Disposable

close

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, containsValue, entrySet, equals, forEach, getOrDefault, hashCode, keySet, merge, putIfAbsent, remove, replace, replace, replaceAll, values

Constructor Detail

PartitionSplittingBackingMap

public PartitionSplittingBackingMap(BackingMapManager bmm,
                                    String sName)

Create a PartitionSplittingBackingMap that will delegate each partition's data and operations to a separate backing map.

Parameters:

bmm - a BackingMapManager that knows how to create and release the backing maps that this PartitionSplittingBackingMap is responsible for

sName - the cache name for which this backing map exists

Method Detail

clear

public void clear()

Clear all key/value mappings.

Specified by:

clear in interface Map

Overrides:

clear in class AbstractKeyBasedMap

containsKey

public boolean containsKey(Object oKey)

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

Specified by:

containsKey in interface Map

Overrides:

containsKey in class AbstractKeyBasedMap

Returns:

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

get

public Object get(Object oKey)

Returns the value to which this map maps the specified key.

Specified by:

get in interface Map

Specified by:

get in class AbstractKeyBasedMap

Parameters:

oKey - the key object

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key

isEmpty

public boolean isEmpty()

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

Specified by:

isEmpty in interface Map

Overrides:

isEmpty in class AbstractKeyBasedMap

Returns:

true if this map contains no key-value mappings

put

public Object put(Object oKey,
                  Object oValue)

Associates the specified value with the specified key in this map.

Specified by:

put in interface Map

Overrides:

put in class AbstractKeyBasedMap

Parameters:

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

oValue - value to be associated with the specified key

Returns:

previous value associated with specified key, or null if there was no mapping for key

putAll

public void putAll(Map map)

Copies all of the mappings from the specified map to this map. The effect of this call is equivalent to that of calling AbstractKeyBasedMap.put(K, V) on this map once for each mapping in the passed map. The behavior of this operation is unspecified if the passed map is modified while the operation is in progress.

Specified by:

putAll in interface Map

Overrides:

putAll in class AbstractKeyBasedMap

Parameters:

map - the Map containing the key/value pairings to put into this Map

remove

public Object remove(Object oKey)

Removes the mapping for this key from this map if present. Expensive: updates both the underlying cache and the local cache.

Specified by:

remove in interface Map

Overrides:

remove in class AbstractKeyBasedMap

Parameters:

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

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.

removeBlind

protected boolean removeBlind(Object oKey)

Removes the mapping for this key from this map if present. This method exists to allow sub-classes to optimize remove functionality for situations in which the original value is not required.

Overrides:

removeBlind in class AbstractKeyBasedMap

Parameters:

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

Returns:

true iff the Map changed as the result of this operation

size

public int size()

Returns the number of key-value mappings in this map.

Specified by:

size in interface Map

Overrides:

size in class AbstractKeyBasedMap

Returns:

the number of key-value mappings in this map

iterateKeys

protected Iterator iterateKeys()

Create an iterator over the keys in this Map. The Iterator must support remove() if the Map supports removal.

Specified by:

iterateKeys in class AbstractKeyBasedMap

Returns:

a new instance of an Iterator over the keys in this Map

instantiateKeySet

protected Set instantiateKeySet()

Factory pattern: Create a Set that represents the keys in the Map

Overrides:

instantiateKeySet in class AbstractKeyBasedMap

Returns:

a new instance of Set that represents the keys in the Map

getCacheStatistics

public CacheStatistics getCacheStatistics()

Returns the CacheStatistics for this cache.

Returns:

a CacheStatistics object

getBackingMapManager

public BackingMapManager getBackingMapManager()

Obtain the BackingMapManager that this PartitionAwareBackingMap uses to instantiate and release backing maps.

Specified by:

getBackingMapManager in interface PartitionAwareBackingMap

Returns:

the BackingMapManager

getName

public String getName()

Determine the name of the cache for which this PartitionAwareBackingMap exists.

Specified by:

getName in interface PartitionAwareBackingMap

Returns:

the cache name

createPartition

public void createPartition(int nPid)

Add a partition to the PartitionAwareBackingMap.

Specified by:

createPartition in interface PartitionAwareBackingMap

Parameters:

nPid - the partition id that the PartitionAwareBackingMap will be responsible for, starting at this instant

destroyPartition

public void destroyPartition(int nPid)

Remove a partition from the PartitionAwareBackingMap.

Specified by:

destroyPartition in interface PartitionAwareBackingMap

Parameters:

nPid - the partition id that the PartitionAwareBackingMap will no longer be responsible for, starting at this instant

getPartitionMap

public Map getPartitionMap(int nPid)

Obtain a Map view for the data in a specific partition.

Specified by:

getPartitionMap in interface PartitionAwareBackingMap

Parameters:

nPid - the partition ID

Returns:

the backing map (or null if that partition is not owned)

getPartitionMap

public Map getPartitionMap(PartitionSet partitions)

Obtain a Map view for the data in a specific set of partitions.

Specified by:

getPartitionMap in interface PartitionAwareBackingMap

Parameters:

partitions - the masking PartitionSet

Returns:

a read-only view into a subset of backing maps

dispose

public void dispose()

Invoked when all resources owned by the implementer can safely be released.

Once disposed of the object should no longer be considered to be usable.

Note the Disposable interface is compatible with try-with-resources which will automatically invoke this method.

Specified by:

dispose in interface com.oracle.coherence.common.base.Disposable

isStrict

public boolean isStrict()

Determine if any access to data in missing partitions is being treated as an error.

Returns:

true if access to missing partitions is being treated as error

setStrict

public void setStrict(boolean fStrict)

Specify whether any access to data in missing partitions should be treated as an error. If set to true, any read operation against a missing partition will log an error and any write operation will generate an exception. Otherwise, read operations against missing partitions will just return natural default values and write operations will log warnings.

Parameters:

fStrict - if true, any access to missing partitions should being treated as error

putInternal

protected Object putInternal(Map mapPart,
                             Object oKey,
                             Object oValue)

Put the key and value into a map representing a given partition.

Parameters:

mapPart - a partition map

oKey - oKey with which the specified value is to be associated

oValue - oValue to be associated with the specified oKey

Returns:

previous value associated with specified key, or null if there was no mapping for the key

putAllInternal

protected void putAllInternal(Map mapPart,
                              Map mapUpdate)

Put all entries in mapUpdate into the provided map.

Parameters:

mapPart - a partition map

mapUpdate - the Map containing the key/value pairings to put into mapPart

getContext

protected BackingMapManagerContext getContext()

Obtain the BackingMapManagerContext that provides the partition information for keys that are stored in the backing map.

Returns:

the BackingMapManagerContext for the underlying service

size

protected int size(Map[] amap)

Return the number of key-value mappings in a subset of the maps that belong to specified partitions.

Parameters:

amap - the array of maps to process

Returns:

the number of entries in a subset of the maps

isEmpty

protected boolean isEmpty(Map[] amap)

Return true iff a subset of the maps that belong to specified partitions contains no entries.

Parameters:

amap - the array of maps to process

Returns:

true iff the subset of the maps contains no entries

iterateKeys

protected Iterator iterateKeys(Map[] amap)

Create an iterator over the keys in maps that belong to partitions contained in the specified PartitionSet.

Parameters:

amap - the array of maps to process

Returns:

the key iterator

getMapArray

protected PartitionSplittingBackingMap.MapArray getMapArray()

Get the mapping between partition IDs and backing maps.

Returns:

the current MapArray data

getBackingMap

protected Map getBackingMap(Object oKey)

Obtain a backing map for the specified key.

Parameters:

oKey - the key

Returns:

the backing map for the specified key or null if the partition is missing

makeName

protected String makeName(String sName,
                          int nPid)

Format a synthetic name for a partition-specific backing map.

Parameters:

sName - the name of the cache

nPid - the partition number

Returns:

a name that a backing map for a specific partition will be known by, for example as it should appear in JMX

toString

public String toString()

Return a human-readable description for this PartitionBackingMap.

Overrides:

toString in class AbstractKeyBasedMap

Returns:

a String description of the PartitionBackingMap

toString

public String toString(boolean fVerbose)

Return a human-readable description for this PartitionBackingMap.

Parameters:

fVerbose - if true, generate a verbose descrition

Returns:

a String description of the PartitionBackingMap

reportMissingPartition

protected void reportMissingPartition(Object oKey,
                                      int nPid)

Report a missing partition according to the "strict" flag rules.

Parameters:

oKey - the key for which an operation failed (optional)

nPid - the missing partition; meaningful only if oKey is null