java.lang.Object
- org.apache.geode.cache.partition.PartitionRegionHelper

public final class PartitionRegionHelper
extends java.lang.Object

Utility methods for handling partitioned Regions, for example during execution of Functions on a Partitioned Region.

Example of a Function using utility methods:

  public Serializable execute(FunctionContext context) {
     if (context instanceof RegionFunctionContext) {
         RegionFunctionContext rc = (RegionFunctionContext) context;
         if (PartitionRegionHelper.isPartitionedRegion(rc.getDataSet())) {
             Region efficientReader =
              PartitionRegionHelper.getLocalDataForContext(rc);
             efficientReader.get("someKey");
             // ...
         }
      }
  // ...

Since:: GemFire 6.0
See Also:: FunctionService.onRegion(Region)

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static void`	`assignBucketsToPartitions(Region<?,?> region)`	Decide which partitions will host which buckets.
`static <K,V> java.util.Set<DistributedMember>`	`getAllMembersForKey(Region<K,V> r, K key)`	Get all potential owners for a key.
`static java.util.Map<java.lang.String,Region<?,?>>`	`getColocatedRegions(Region<?,?> r)`	Given a partitioned Region, return a map of colocated Regions.
`static java.util.Map<java.lang.String,Region<?,?>>`	`getLocalColocatedRegions(RegionFunctionContext<?> c)`	Given a RegionFunctionContext for a partitioned Region, return a map of colocated Regions with read access limited to the context of the function.
`static <K,V> Region<K,V>`	`getLocalData(Region<K,V> r)`	Given a partitioned Region return a Region providing read access limited to the local heap, writes using this Region have no constraints and behave the same as a partitioned Region.
`static <K,V> Region<K,V>`	`getLocalDataForContext(RegionFunctionContext<?> c)`	Given a RegionFunctionContext for a partitioned Region, return a Region providing read access limited to the function context. Returned Region provides only one copy of the data although `redundantCopies` configured is more than 0.
`static <K,V> Region<K,V>`	`getLocalPrimaryData(Region<K,V> r)`	Given a partitioned Region return a Region providing read access to primary copy of the data which is limited to the local heap, writes using this Region have no constraints and behave the same as a partitioned Region.
`static java.util.Set<PartitionRegionInfo>`	`getPartitionRegionInfo(Cache cache)`	Gathers a set of details about all partitioned regions in the local Cache.
`static PartitionRegionInfo`	`getPartitionRegionInfo(Region<?,?> region)`	Gathers details about the specified partitioned region.
`static <K,V> DistributedMember`	`getPrimaryMemberForKey(Region<K,V> r, K key)`	Get the current primary owner for a key.
`static <K,V> java.util.Set<DistributedMember>`	`getRedundantMembersForKey(Region<K,V> r, K key)`	Get all potential redundant owners for a key.
`static boolean`	`isPartitionedRegion(Region<?,?> r)`	Test a Region to see if it is a partitioned Region
`static <K> void`	`moveBucketByKey(Region<K,?> region, DistributedMember source, DistributedMember destination, K key)`	Moves the bucket which contains the given key from the source member to the destination member.
`static RebalanceResults`	`moveData(Region<?,?> region, DistributedMember source, DistributedMember destination, float percentage)`	Moves data from the source member to the destination member, up to the given percentage of data (measured in bytes).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getColocatedRegions
```
public static java.util.Map<java.lang.String,Region<?,?>> getColocatedRegions(Region<?,?> r)
```
    Given a partitioned Region, return a map of colocated Regions. Given a local data reference to a partitioned region, return a map of local colocated Regions. If there are no colocated regions, return an empty map.
    
    Parameters:
    
    r - a partitioned Region
    
    Returns:
    
    an unmodifiable map of region name to Region
    
    Throws:
    
    java.lang.IllegalStateException - if the Region is not a partitioned Region
    
    Since:
    
    GemFire 6.0
  - isPartitionedRegion
```
public static boolean isPartitionedRegion(Region<?,?> r)
```
    Test a Region to see if it is a partitioned Region
    
    Parameters:
    
    r - the region
    
    Returns:
    
    true if it is a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getPartitionRegionInfo
```
public static java.util.Set<PartitionRegionInfo> getPartitionRegionInfo(Cache cache)
```
    Gathers a set of details about all partitioned regions in the local Cache. If there are no partitioned regions then an empty set will be returned.
    
    Parameters:
    
    cache - the cache which has the regions
    
    Returns:
    
    set of details about all locally defined partitioned regions
    
    Since:
    
    GemFire 6.0
  - getPartitionRegionInfo
```
public static PartitionRegionInfo getPartitionRegionInfo(Region<?,?> region)
```
    Gathers details about the specified partitioned region. Returns null if the partitioned region is not locally defined.
    
    Parameters:
    
    region - the region to get info about
    
    Returns:
    
    details about the specified partitioned region
    
    Since:
    
    GemFire 6.0
  - assignBucketsToPartitions
```
public static void assignBucketsToPartitions(Region<?,?> region)
```
    Decide which partitions will host which buckets. Gemfire normally assigns buckets to partitions as needed when data is added to a partitioned region. This method provides way to assign all of the buckets without putting any data in partition region. This method should not be called until all of the partitions are running because it will divide the buckets between the running partitions. If the buckets are already assigned this method will have no effect. This method will block until all buckets are assigned.
    
    Parameters:
    
    region - The region which should have its buckets assigned.
    
    Throws:
    
    java.lang.IllegalStateException - if the provided region is something other than a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getPrimaryMemberForKey
```
public static <K,V> DistributedMember getPrimaryMemberForKey(Region<K,V> r,
                                                                   K key)
```
    Get the current primary owner for a key. Upon return there is no guarantee that primary owner remains the primary owner, or that the member is still alive.
    This method is not a substitute for Region.containsKey(Object).
    
    Type Parameters:
    
    K - The key type of the region
    
    V - The value type of the region
    
    Parameters:
    
    r - a PartitionedRegion
    
    key - the key to evaluate
    
    Returns:
    
    the primary member for the key, possibly null if a primary is not yet determined
    
    Throws:
    
    java.lang.IllegalStateException - if the provided region is something other than a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getRedundantMembersForKey
```
public static <K,V> java.util.Set<DistributedMember> getRedundantMembersForKey(Region<K,V> r,
                                                                                     K key)
```
    Get all potential redundant owners for a key. If the key exists in the Region, upon return there is no guarantee that key has not been moved or that the members are still alive.
    This method is not a substitute for Region.containsKey(Object).
    This method is equivalent to: DistributedMember primary = getPrimaryMemberForKey(r, key); Set<? extends DistributedMember> allMembers = getAllMembersForKey(r, key); allMembers.remove(primary);
    
    Type Parameters:
    
    K - The key type of the region
    
    V - The value type of the region
    
    Parameters:
    
    r - a PartitionedRegion
    
    key - the key to evaluate
    
    Returns:
    
    an unmodifiable set of members minus the primary
    
    Throws:
    
    java.lang.IllegalStateException - if the provided region is something other than a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getAllMembersForKey
```
public static <K,V> java.util.Set<DistributedMember> getAllMembersForKey(Region<K,V> r,
                                                                               K key)
```
    Get all potential owners for a key. If the key exists in the Region, upon return there is no guarantee that it has not moved nor does it guarantee all members are still alive.
    This method is not a substitute for Region.containsKey(Object).
    
    Type Parameters:
    
    K - The key type of the region
    
    V - The value type of the region
    
    Parameters:
    
    r - PartitionedRegion
    
    key - the key to evaluate
    
    Returns:
    
    an unmodifiable set of all members
    
    Throws:
    
    java.lang.IllegalStateException - if the provided region is something other than a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getLocalColocatedRegions
```
public static java.util.Map<java.lang.String,Region<?,?>> getLocalColocatedRegions(RegionFunctionContext<?> c)
```
    Given a RegionFunctionContext for a partitioned Region, return a map of colocated Regions with read access limited to the context of the function.
    Writes using these regions have no constraints and behave the same as a partitioned Region.
    If there are no colocated regions, return an empty map.
    
    Parameters:
    
    c - the region function context
    
    Returns:
    
    an unmodifiable map of region name to Region
    
    Throws:
    
    java.lang.IllegalStateException - if the Region is not a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getLocalDataForContext
```
public static <K,V> Region<K,V> getLocalDataForContext(RegionFunctionContext<?> c)
```
    Given a RegionFunctionContext for a partitioned Region, return a Region providing read access limited to the function context.
    Returned Region provides only one copy of the data although redundantCopies configured is more than 0. If the invoking Function is configured to have optimizeForWrite as true,the returned Region will only contain primary copy of the data.
    Writes using this Region have no constraints and behave the same as a partitioned Region.
    
    Type Parameters:
    
    K - The key type of the region
    
    V - The value type of the region
    
    Parameters:
    
    c - a functions context
    
    Returns:
    
    a Region for efficient reads
    
    Throws:
    
    java.lang.IllegalStateException - if RegionFunctionContext.getDataSet() returns something other than a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getLocalData
```
public static <K,V> Region<K,V> getLocalData(Region<K,V> r)
```
    Given a partitioned Region return a Region providing read access limited to the local heap, writes using this Region have no constraints and behave the same as a partitioned Region.
    
    Type Parameters:
    
    K - The key type of the region
    
    V - The value type of the region
    
    Parameters:
    
    r - a partitioned region
    
    Returns:
    
    a Region for efficient reads
    
    Throws:
    
    java.lang.IllegalStateException - if the provided region is something other than a partitioned Region
    
    Since:
    
    GemFire 6.0
  - getLocalPrimaryData
```
public static <K,V> Region<K,V> getLocalPrimaryData(Region<K,V> r)
```
    Given a partitioned Region return a Region providing read access to primary copy of the data which is limited to the local heap, writes using this Region have no constraints and behave the same as a partitioned Region.
    
    Type Parameters:
    
    K - The key type of the region
    
    V - The value type of the region
    
    Parameters:
    
    r - a partitioned region
    
    Returns:
    
    a Region for efficient reads
    
    Throws:
    
    java.lang.IllegalStateException - if the provided region is something other than a partitioned Region
    
    Since:
    
    GemFire 6.5
  - moveBucketByKey
```
public static <K> void moveBucketByKey(Region<K,?> region,
                                       DistributedMember source,
                                       DistributedMember destination,
                                       K key)
```
    Moves the bucket which contains the given key from the source member to the destination member. The bucket will be fully transferred once this method is complete, if the method does not throw an exception.
    All keys which exist in the same bucket will also be moved to the new node.
    Any data in colocated regions that are colocated with this key will also be moved.
    This method allows direct control of what data to move. To automatically balance buckets, see ResourceManager.createRebalanceFactory()
    
    Type Parameters:
    
    K - The key type of the region
    
    Parameters:
    
    region - The region in which to move the bucket. Data in regions colocated with this region will also be moved.
    
    source - A member that is currently hosting this bucket. The bucket is moved off of this member.
    
    destination - A member that is not currently hosting this bucket, but has the partitioned region defined. The bucket is moved to this member.
    
    key - A key which maps to the bucket to move. This key does not actually need to exist in the region, but if using a PartitionResolver the resolver should be able to get the routing object from this key to determine the bucket to move.
    
    Throws:
    
    java.lang.IllegalStateException - if the bucket is not present on the source, if the source or destination are not valid members of the system, if the destination already hosts a copy of the bucket, or if the bucket does not exist.
    
    Since:
    
    GemFire 7.1
  - moveData
```
public static RebalanceResults moveData(Region<?,?> region,
                                        DistributedMember source,
                                        DistributedMember destination,
                                        float percentage)
```
    Moves data from the source member to the destination member, up to the given percentage of data (measured in bytes). The data will be fully transferred once this method is complete, if the method does not throw an exception. The percentage is a percentage of the amount of data in bytes on the source member for this region.
    If this region has colocated regions, the colocated data will also be moved. The total amount of data in all colocated regions will be taken into consideration when determining what percentage of data will be moved.
    It may not be possible to move data to the destination member, if the destination member has no available space, no bucket smaller than the given percentage exists, or if moving data would violate redundancy constraints. If data cannot be moved, this method will return a RebalanceResult object with 0 total bucket transfers.
    This method allows direct control of what data to move. To automatically balance buckets, see ResourceManager.createRebalanceFactory()
    
    Parameters:
    
    region - The region in which to move data. Data in regions colocated with this region will also be moved.
    
    source - A member that is currently hosting data. The bucket is moved off of this member.
    
    destination - A member that that has the partitioned region defined. Data is moved to this member.
    
    percentage - the maximum amount of data to move, as a percentage from 0 to 100.
    
    Returns:
    
    A RebalanceResult object that contains information about what data was actually moved.
    
    Throws:
    
    java.lang.IllegalStateException - if the source or destination are not valid members of the system.
    
    java.lang.IllegalArgumentException - if the percentage is not between 0 and 100.
    
    Since:
    
    GemFire 7.1

Gemfire JavaDocs_test

Class PartitionRegionHelper

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getColocatedRegions

isPartitionedRegion

getPartitionRegionInfo

getPartitionRegionInfo

assignBucketsToPartitions

getPrimaryMemberForKey

getRedundantMembersForKey

getAllMembersForKey

getLocalColocatedRegions

getLocalDataForContext

getLocalData

getLocalPrimaryData

moveBucketByKey

moveData