Oracle® Coherence Java API Reference
v3.5.3

E15583-01

com.tangosol.net.partition
Class PartitionSplittingBackingMap

java.lang.Object
  extended by com.tangosol.util.Base
      extended by com.tangosol.util.AbstractKeyBasedMap
          extended by com.tangosol.net.partition.PartitionSplittingBackingMap
All Implemented Interfaces:
PartitionAwareBackingMap, java.util.Map

public class PartitionSplittingBackingMap
extends AbstractKeyBasedMap
implements 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
 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.
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.EntrySet, AbstractKeyBasedMap.KeySet, AbstractKeyBasedMap.ValuesCollection
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry
 
Constructor Summary
PartitionSplittingBackingMap(BackingMapManager bmm, java.lang.String sName)
          Create a PartitionSplittingBackingMap that will delegate each partition's data and operations to a separate backing map.
 
Method Summary
 void clear()
          Clear all key/value mappings.
 boolean containsKey(java.lang.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.
 java.lang.Object get(java.lang.Object oKey)
          Returns the value to which this map maps the specified key.
protected  java.util.Map getBackingMap(java.lang.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.
 java.lang.String getName()
          Determine the name of the cache for which this PartitionAwareBackingMap exists.
 java.util.Map getPartitionMap(int nPid)
          Obtain a Map view for the data in a specific partition.
 java.util.Map getPartitionMap(PartitionSet partitions)
          Obtain a Map view for the data in a specific set of partitions.
 boolean isEmpty()
          Returns true if this map contains no key-value mappings.
protected  boolean isEmpty(java.util.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  java.util.Iterator iterateKeys()
          Create an iterator over the keys in this Map.
protected  java.util.Iterator iterateKeys(java.util.Map[] amap)
          Create an iterator over the keys in maps that belong to partitions contained in the specified PartitionSet.
protected  java.lang.String makeName(java.lang.String sName, int nPid)
          Format a synthetic name for a partition-specific backing map.
 java.lang.Object put(java.lang.Object oKey, java.lang.Object oValue)
          Associates the specified value with the specified key in this map.
 void putAll(java.util.Map map)
          Copies all of the mappings from the specified map to this map.
 java.lang.Object remove(java.lang.Object oKey)
          Removes the mapping for this key from this map if present.
protected  void reportMissingPartition(java.lang.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(java.util.Map[] amap)
          Return the number of key-value mappings in a subset of the maps that belong to specified partitions.
 java.lang.String toString()
          Return a human-readable description for this PartitionBackingMap.
 java.lang.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, instantiateKeySet, instantiateValues, keySet, removeBlind, values
 
Methods inherited from interface java.util.Map
containsValue, entrySet, equals, hashCode, keySet, values
 

Constructor Detail

PartitionSplittingBackingMap

public PartitionSplittingBackingMap(BackingMapManager bmm,
                                    java.lang.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 java.util.Map
Overrides:
clear in class AbstractKeyBasedMap

containsKey

public boolean containsKey(java.lang.Object oKey)
Returns true if this map contains a mapping for the specified key.

Specified by:
containsKey in interface java.util.Map
Overrides:
containsKey in class AbstractKeyBasedMap
Returns:
true if this map contains a mapping for the specified key, false otherwise.

get

public java.lang.Object get(java.lang.Object oKey)
Returns the value to which this map maps the specified key.

Specified by:
get in interface java.util.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 java.util.Map
Overrides:
isEmpty in class AbstractKeyBasedMap
Returns:
true if this map contains no key-value mappings

put

public java.lang.Object put(java.lang.Object oKey,
                            java.lang.Object oValue)
Associates the specified value with the specified key in this map.

Specified by:
put in interface java.util.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(java.util.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(java.lang.Object, java.lang.Object) 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 java.util.Map
Overrides:
putAll in class AbstractKeyBasedMap
Parameters:
map - the Map containing the key/value pairings to put into this Map

remove

public java.lang.Object remove(java.lang.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 java.util.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.

size

public int size()
Returns the number of key-value mappings in this map.

Specified by:
size in interface java.util.Map
Overrides:
size in class AbstractKeyBasedMap
Returns:
the number of key-value mappings in this map

iterateKeys

protected java.util.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

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 java.lang.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 java.util.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 java.util.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

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

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(java.util.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(java.util.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 java.util.Iterator iterateKeys(java.util.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 java.util.Map getBackingMap(java.lang.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 java.lang.String makeName(java.lang.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 java.lang.String toString()
Return a human-readable description for this PartitionBackingMap.

Overrides:
toString in class AbstractKeyBasedMap
Returns:
a String description of the PartitionBackingMap

toString

public java.lang.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(java.lang.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

Oracle® Coherence Java API Reference
v3.5.3

E15583-01

Copyright © 2000, 2010, Oracle. All rights reserved.