com.kabira.platform.highavailability

Class PartitionManager

java.lang.Object

com.kabira.platform.highavailability.PartitionManager

public final class PartitionManager
extends java.lang.Object

The PartitionManager class. This is the main interface for managing partitions.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PartitionManager.DisableAction An enumeration of the possible actions that can be taken when disabling high availability for a node.
static class	PartitionManager.EnableAction An enumeration of the possible actions that can be taken when enabling high availability for a node.

Method Summary

Modifier and Type	Method and Description
static void	clearMapper(java.lang.Class<?> managedClass) Clear a mapper for a given managed class.
static void	clearMapper(java.lang.String typeName) Clear a mapper for a given type.
static void	definePartition(java.lang.String partitionName, Partition.Properties partitionProperties, java.lang.String activeNode, ReplicaNode[] replicas) Define a partition.
static void	definePartition(java.lang.String partitionName, java.lang.String[] nodes) Deprecated.
static void	definePartition(java.lang.String partitionName, java.lang.String restoreFromNode, java.lang.String[] nodes) Deprecated.
static void	disablePartitions(PartitionManager.DisableAction disableAction) Disable high availability for the all partitions defined on the node.
static void	enablePartitions(PartitionManager.EnableAction enableAction) Enable high availability for the all partitions defined on the node.
static Partition	getObjectPartition(java.lang.Object obj) Get the partition an object is in.
static Partition	getPartition(java.lang.String partitionName) Find a partition by name.
static Partition[]	getPartitions() Find all partitions on the local node.
static void	getRemotePartitions(java.lang.String remoteNode) Create local copies of all partition defined by the remote node.
static boolean	isPartitioned(java.lang.Class<?> managedClass) Deprecated.
static void	repartitionInstance(java.lang.Object obj) Move the instance from the current partition (if any) to the partition defined by the installed mapper for the object class.
static void	setMapper(java.lang.Class<?> managedClass, PartitionMapper partitionMapper) Associate a mapper to a given managed class.
static PartitionMapper	setMapper(java.lang.Class<?> managedClass, PartitionMapper partitionMapper, PartitionMapper.Properties mapperProperties) Associate a mapper to a given managed class.
static PartitionMapper	setMapper(java.lang.String typeName, PartitionMapper partitionMapper, PartitionMapper.Properties mapperProperties) Associate a mapper to a given shared memory type.
static void	waitForNode(java.lang.String remoteNode) Wait for a remote node to become available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getPartitions

public static final Partition[] getPartitions()

Find all partitions on the local node.

Returns:

Array of Partition instances.

getPartition

public static final Partition getPartition(java.lang.String partitionName)
                                    throws java.lang.IllegalArgumentException,
                                           PartitionNotFound

Find a partition by name.

Parameters:

partitionName - Name of partition to find.

Returns:

Partition instance.

Throws:

PartitionNotFound - The given partition doesn't exist.

java.lang.IllegalArgumentException - The partitionName was empty.

getObjectPartition

public static final Partition getObjectPartition(java.lang.Object obj)
                                          throws ManagedClassError,
                                                 PartitionNotFound

Get the partition an object is in.

Parameters:

obj - Object to examine.

Returns:

Partition instance.

Throws:

ManagedClassError - The object is not a Managed object.

PartitionNotFound - The given object isn't in a partition. This can happen if object instances were created before a PartitionMapper was installed for a managed class, or no mapper was ever defined.

repartitionInstance

public static final void repartitionInstance(java.lang.Object obj)
                                      throws ManagedClassError

Move the instance from the current partition (if any) to the partition defined by the installed mapper for the object class. The interactions between installed mappers and partitions when an object is repartitioned is enumerated below:

• If the object was not associated with a partition, and a mapper maps it to a new partition, the instance is replicated to all nodes defined for the new partition.
• If the object was mapped to a pre-existing partition, and a mapper maps it to a new partition, the instance is replicated to all nodes defined for the new partition. The instance is removed from all nodes that were defined in the old partition but are not defined with the new partition.
• If the object was associated with a partition, and a mapper no longer exists, the instance is removed from all nodes that that were defined in the old partition, and the instance is left in shared memory on the local node as un-partitioned.
• If the object was not associated with a partition, and a mapper does not exist, this operation does nothing.

Parameters:

obj - Object to repartition.

Throws:

ManagedClassError - The object is not a Managed object.

ResourceUnavailableException - An illegal partition name was returned from the mapper, or the partition that is returned in not in the ACTIVE state.

definePartition

@Deprecated
public static final void definePartition(java.lang.String partitionName,
                                                     java.lang.String[] nodes)
                                              throws java.lang.IllegalArgumentException

Deprecated.

Use definePartition(String, Partition.Properties, String, ReplicaNode [])

Parameters:

partitionName - Name of partition to create.

nodes - An ordered list of nodes for the partition.

Throws:

java.lang.IllegalArgumentException

definePartition

@Deprecated
public static final void definePartition(java.lang.String partitionName,
                                                     java.lang.String restoreFromNode,
                                                     java.lang.String[] nodes)
                                              throws java.lang.IllegalArgumentException,
                                                     NotActiveNode

Deprecated.

Use definePartition(String, Partition.Properties, String, ReplicaNode []) instead.

Parameters:

partitionName - Name of partition to create.

restoreFromNode - The remote node to use when restoring the partition's objects.

nodes - An ordered list of nodes for the partition.

Throws:

java.lang.IllegalArgumentException

NotActiveNode

definePartition

public static final void definePartition(java.lang.String partitionName,
                                         Partition.Properties partitionProperties,
                                         java.lang.String activeNode,
                                         ReplicaNode[] replicas)
                                  throws java.lang.IllegalArgumentException,
                                         NotActiveNode,
                                         ResourceUnavailableException

Define a partition.

This method defines a partition. This method can be called on any node in the cluster to define a new partition, or change the definition of a pre-existing partition. Once all partitions have been defined for a node, the enablePartitions() method should be called to move the partitions to the active state. It is a runtime error to attempt to create or modify instances in a newly defined partition until the enablePartitions() method is called.

The activeNode is the node that will be the active node for the partition after it is enabled.

Optional partition properties can be used by passing in an instance of the Partition.Properties class. User defined properties such as forceReplication are saved and subsequently used during failover processing.

The replicas array contains an ordered list of replica nodes for the partition. A failure of the active node results in the partition automatically migrating to the the next entry in the replicas array. Objects are sent to each replica node based on the configuration in the ReplicaNode entry.

Parameters:

partitionName - Name of partition to create.

partitionProperties - Optional properties for the partition. If null, the default property values are used.

activeNode - The active node for the partition

replicas - An ordered list of replica nodes for the partition. Should be passed in as a null instance or a zero length array if no replicas are desired.

Throws:

java.lang.IllegalArgumentException - The partitionName or activeNode was empty, or the replicas array was invalid.

NotActiveNode - The current node is not the active node for the partition and restoreFromNode was defined in partitionProperties.

ResourceUnavailableException - The operation timed out waiting for the active node to become available.

setMapper

public static final void setMapper(java.lang.Class<?> managedClass,
                                   PartitionMapper partitionMapper)
                            throws ManagedClassError

Associate a mapper to a given managed class. This method uses PartitionMapper.Properties.Audit.IGNORE_PARTITIONING for audit.

Parameters:

managedClass - Name of a Managed object.

partitionMapper - User defined PartitionMapper instance.

Throws:

ManagedClassError - The managedClass is not a Managed object, or has a non-abstract parent class with a key defined but no mapper installed.

See Also:

setMapper(Class, PartitionMapper, PartitionMapper.Properties)

setMapper

public static final PartitionMapper setMapper(java.lang.Class<?> managedClass,
                                              PartitionMapper partitionMapper,
                                              PartitionMapper.Properties mapperProperties)
                                       throws ManagedClassError

Associate a mapper to a given managed class.

This method is used to associate a user defined PartitionMapper instance with a managed class. All managed types that are replicated must have a PartitionMapper associated with the class. This method must be called on all nodes that has the partition definition.

The same PartitionMapper instance can be associated with multiple classes. If a PartitionMapper is already associated with a class, the new value overwrites the previous one.

Applications should only delete a PartitionMapper instance after a new instance is installed. If a PartitionMapper instance is deleted, any subsequent object creates for the class will throw a runtime exception.

Mapper instances are inherited by all classes that extend the managed class. If the managed class extends another class, that class must not have any keys defined.

If auditing is enabled in the mapperProperties instance, this routine will verify that no unpartitioned instances of the given class already exist in shared memory. This can happen if instances are created before a mapper is installed.

Parameters:

managedClass - Managed class.

partitionMapper - User defined PartitionMapper instance.

mapperProperties - Optional mapper properties. If null, PartitionMapper.Properties.Audit.IGNORE_PARTITIONING is used.

Returns:

Old mapper instance associated with managedClass, or null if no mapper was set.

Throws:

ManagedClassError - The managedClass is not a Managed object, or has a non-abstract parent class with a key defined but no mapper installed.

setMapper

public static final PartitionMapper setMapper(java.lang.String typeName,
                                              PartitionMapper partitionMapper,
                                              PartitionMapper.Properties mapperProperties)
                                       throws ResourceUnavailableException

Associate a mapper to a given shared memory type.

This method is used to associate a user defined PartitionMapper instance with shared memory type. All types that are replicated must have a PartitionMapper associated with the class. This method must be called on all nodes that has the partition definition.

The same PartitionMapper instance can be associated with multiple type. If a PartitionMapper is already associated with a type, the new value overwrites the previous one.

Applications should only delete a PartitionMapper instance after a new instance is installed. If a PartitionMapper instance is deleted, any subsequent object creates for the type will throw a runtime exception.

Mapper instances are inherited by all subtypes. If the type extends another type, that class must not have any keys defined.

If auditing is enabled in the mapperProperties instance, this routine will verify that no unpartitioned instances of the given type already exist in shared memory. This can happen if instances are created before a mapper is installed.

Parameters:

typeName - Name of a shared memory type.

partitionMapper - User defined PartitionMapper instance.

mapperProperties - Optional mapper properties. If null, PartitionMapper.Properties.Audit.IGNORE_PARTITIONING is used.

Returns:

Old mapper instance associated with managedClass, or null if no mapper was set.

Throws:

ResourceUnavailableException - The typeName is not a shared memory type, or has a non-abstract parent class with a key defined but no mapper installed.

clearMapper

public static final void clearMapper(java.lang.Class<?> managedClass)
                              throws ManagedClassError

Clear a mapper for a given managed class.

This method is used to remove a user defined PartitionMapper instance for a managed class. This method must be called on all nodes where the mapper was previously defined.

If no PartitionMapper is associated with a class, this operation is a noop.

Parameters:

managedClass - Managed class.

Throws:

ManagedClassError - The managedClass is not a Managed object.

See Also:

setMapper(Class, PartitionMapper, PartitionMapper.Properties)

clearMapper

public static final void clearMapper(java.lang.String typeName)
                              throws ResourceUnavailableException

Clear a mapper for a given type.

This method is used to remove a user defined PartitionMapper instance for a shared memory type. This method must be called on all nodes where the mapper was previously defined.

If no PartitionMapper is associated with a class, this operation is a noop.

Parameters:

typeName - Name of a Managed object.

Throws:

ResourceUnavailableException - The typeName does not exist in shared memory.

See Also:

setMapper(String, PartitionMapper, PartitionMapper.Properties)

isPartitioned

@Deprecated
public static final boolean isPartitioned(java.lang.Class<?> managedClass)

Deprecated.

Use ManagedObject.isPartitioned(java.lang.Class<?>)

Parameters:

managedClass - Class to check.

Returns:

true if class is partitioned.

enablePartitions

public static final void enablePartitions(PartitionManager.EnableAction enableAction)
                                   throws NodeMismatch,
                                          ResourceUnavailableException

Enable high availability for the all partitions defined on the node.

This method is used to enable all partitions that have been defined for this node. This method should be called each time new partitions are defined. This method blocks until all required object migration is complete.

Parameters:

enableAction - The action to take when enabling partitions.

Throws:

NodeMismatch - The partition does not have the local node in the node list, and the active node for the partition has a different node list.

ResourceUnavailableException - The minimum number of nodes needed to establish a quorum has not been seen.

disablePartitions

public static final void disablePartitions(PartitionManager.DisableAction disableAction)
                                    throws ResourceUnavailableException

Disable high availability for the all partitions defined on the node.

This method is used to remove the local node from the node list of all partitions that have been defined for this node. If called multiple times, the additional calls have no effect.

Parameters:

disableAction - The action to take when disabling partitions.

Throws:

ResourceUnavailableException - One or more partitions would be in the UNAVAILABLE state after the disable executes, not thrown if LEAVE_CLUSTER_FORCE is used.

waitForNode

public static final void waitForNode(java.lang.String remoteNode)
                              throws ResourceUnavailableException

Wait for a remote node to become available.

Parameters:

remoteNode - name of remote node to wait for.

Throws:

ResourceUnavailableException - The operation timed out waiting for the remote node to become available.

getRemotePartitions

public static final void getRemotePartitions(java.lang.String remoteNode)
                                      throws ResourceUnavailableException

Create local copies of all partition defined by the remote node.

After execution of this method completes, all partitions defined on the remote node will exist on the local node, and will be accessible using the getPartition(String) method.

Parameters:

remoteNode - name of remote node to access.

Throws:

ResourceUnavailableException - The operation timed out waiting for the remote node to become available.