com.kabira.platform.highavailability

Class Partition

java.lang.Object

com.kabira.platform.highavailability.Partition

public final class Partition
extends java.lang.Object

The Partition class. This non-managed class contains a snapshot of a shared memory partition. Direct access to the Partition instance in shared memory is not allowed to avoid transaction locking issues.

Note that partitions are only visible on their active and replica nodes, not all nodes in the cluster.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Partition.Properties The Partition properties used when defining a partition
static class	Partition.State The Partition states
static class	Partition.Statistics Partition statistics
static class	Partition.Status The Partition status

Field Summary

Fields

Modifier and Type	Field and Description
static int	ActiveNodeIndex Index to the active node in the nodes array
static long	DefaultNumberOfThreads The default number of threads to use when performing a migrate.
static long	DefaultObjectsLockedPerTransaction The default number of objects locked per transaction when performing a migrate or update.
static Partition.Properties.RemoteEnableAction	DefaultRemoteEnableAction The default action used for remote partition enables.
static Partition.Properties.ReplicaAudit	DefaultReplicaAudit The default audit used for replicas.
static Partition.Properties.SparseAudit	DefaultSparseAudit The default audit used for sparse partitions.

Method Summary

Modifier and Type	Method and Description
long	cardinality() Returns the number of instances in this partition.
void	clearStatistics() Clear the statistics for the partition.
void	disable(PartitionManager.DisableAction disableAction) Disable high availability for this partition.
void	enable(PartitionManager.EnableAction enableAction) Enable high availability for this partition.
java.lang.String	getActiveNode() Get the active node for the partition.
Partition.State	getCurrentState() Get the current state for the partition.
Partition.Status	getCurrentStatus() Get the current status for the partition.
java.util.Date	getLastStateChangeTime() Get the last time the state for the partition was updated
java.lang.String	getName() Get the partition name.
java.lang.String[]	getNodeList() Get the complete node list for the partition.
Partition.Properties	getProperties() Get the properties currently defined for the partition.
ReplicaNode	getReplicaNode(int idx) Get the ReplicaNode instance for the given replica node index.
ReplicaNode	getReplicaNode(java.lang.String nodeName) Get the ReplicaNode instance for the given replica node name.
java.lang.String[]	getReplicaNodes() Get the replica node list for the partition.
Partition.Statistics	getStatistics() Get the statistics for the partition.
void	migrate(Partition.Properties partitionProperties, java.lang.String activeNode, ReplicaNode[] replicas) Migrate the partition.
void	migrate(java.lang.String[] nodes) Deprecated.
void	setNotifier(PartitionNotifier partitionNotifier) Associated a notifier with the partition.
void	update() Deprecated.
void	update(Partition.Properties partitionProperties) Update the partition.

Methods inherited from class java.lang.Object

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

Field Detail

ActiveNodeIndex

public static final int ActiveNodeIndex

Index to the active node in the nodes array

See Also:

Constant Field Values

DefaultObjectsLockedPerTransaction

public static final long DefaultObjectsLockedPerTransaction

The default number of objects locked per transaction when performing a migrate or update.

See Also:

Constant Field Values

DefaultNumberOfThreads

public static final long DefaultNumberOfThreads

The default number of threads to use when performing a migrate.

See Also:

Constant Field Values

DefaultSparseAudit

public static final Partition.Properties.SparseAudit DefaultSparseAudit

The default audit used for sparse partitions. The value is Partition.Properties.SparseAudit.VERIFY_NODE_LIST

DefaultReplicaAudit

public static final Partition.Properties.ReplicaAudit DefaultReplicaAudit

The default audit used for replicas. The value is Partition.Properties.ReplicaAudit.WAIT_ACTIVE

DefaultRemoteEnableAction

public static final Partition.Properties.RemoteEnableAction DefaultRemoteEnableAction

The default action used for remote partition enables. The value is Partition.Properties.RemoteEnableAction.ENABLE_PARTITION

Method Detail

getName

public final java.lang.String getName()

Get the partition name.

Returns:

Partition name.

getActiveNode

public final java.lang.String getActiveNode()

Get the active node for the partition.

Returns:

Active node name.

getReplicaNodes

public final java.lang.String[] getReplicaNodes()

Get the replica node list for the partition.

Returns:

Array of replica node names.

getNodeList

public final java.lang.String[] getNodeList()

Get the complete node list for the partition.

The node list is a String array of node names, with the active node being at ActiveNodeIndex, followed by a prioritized list of replica nodes.

Returns:

Array of node names.

getCurrentState

public final Partition.State getCurrentState()

Get the current state for the partition.

Returns:

Current state of partition.

getCurrentStatus

public final Partition.Status getCurrentStatus()

Get the current status for the partition.

Returns:

Current status of partition.

getReplicaNode

public final ReplicaNode getReplicaNode(int idx)
                                 throws java.lang.IndexOutOfBoundsException

Get the ReplicaNode instance for the given replica node index.

Parameters:

idx - Index into the ReplicaNode array.

Returns:

ReplicaNode instance.

Throws:

java.lang.IndexOutOfBoundsException - The idx isn't valid.

getReplicaNode

public final ReplicaNode getReplicaNode(java.lang.String nodeName)
                                 throws java.lang.IllegalArgumentException

Get the ReplicaNode instance for the given replica node name.

Parameters:

nodeName - Name of replica node.

Returns:

ReplicaNode instance, or null if not found.

Throws:

java.lang.IllegalArgumentException - The nodeName was invalid.

getLastStateChangeTime

public final java.util.Date getLastStateChangeTime()

Get the last time the state for the partition was updated

Returns:

Date of last state change for partition.

getProperties

public final Partition.Properties getProperties()

Get the properties currently defined for the partition.

The restoreFromNode property is not stored in the runtime since it has no meaning outside of the initial definePartition(). So this method will return a Properties instance with a null restoreFromNode value.

Returns:

Properties instance for partition.

getStatistics

public final Partition.Statistics getStatistics()

Get the statistics for the partition.

Returns:

A Statistics instance for the partition.

clearStatistics

public final void clearStatistics()

Clear the statistics for the partition.

update

@Deprecated
public final void update()
                              throws NodeMismatch,
                                     NotActiveNode

Deprecated.

Use update(Properties) instead.

Throws:

NodeMismatch

NotActiveNode

update

public final void update(Partition.Properties partitionProperties)
                  throws NodeMismatch,
                         NotActiveNode

Update the partition.

This method is used to re-partition all instances that exist in a partition. For each instance in the partition, the PartitionMapper defined for that type is accessed, and the instance re-assigned to the partition that the PartitionMapper.getPartition(java.lang.Object) method returns. The update() method must be called on the current active node for the partition.

To split a partition, the applications should create the new partition, install a new PartitionMapper for all types managed by the partition, and call the update() method for the existing partition.

To merge two or more partitions, the applications should install a new PartitionMapper for all types managed by the partition(s), and call the update() method for all the partitions that need to be merged.

It is important that all partitions returned when executing the PartitionMapper's getPartition() call for a type all contain identical node lists. If the partition returned contains a different node list than this partition, a NodeMismatch exception is thrown, and the update() terminates. To fix this, perform a migrate() on all partitions that will be split or merged to insure that they have identical node lists before performing an update().

Parameters:

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

Throws:

NodeMismatch - The re-partitioning of instances was done using partitions that have different node lists.

NotActiveNode - The current node is not the active node for the partition.

migrate

@Deprecated
public final void migrate(java.lang.String[] nodes)
                               throws NotActiveNode,
                                      java.lang.IllegalArgumentException

Deprecated.

Use migrate(Properties, String, ReplicaNode []) instead.

Parameters:

nodes - An ordered list of nodes for the partition.

Throws:

NotActiveNode

java.lang.IllegalArgumentException

migrate

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

Migrate the partition.

This method is used to migrate all instances that exist in a partition. For each instance in the partition, the object is migrated as needed to all nodes in the replicas array, and to the new activeNode if it is different from the current active node. This method must be called on the currently active node for the partition.

Any properties passed in only apply to the current migrate() command, properties passed into definePartition() are saved and used during failover.

Parameters:

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

activeNode - Active node after migrate completes.

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 exists.

Throws:

NotActiveNode - The current node is not the active node for the partition.

java.lang.IllegalArgumentException - The activeNode or replica array was invalid.

enable

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

Enable high availability for this partition.

This method is used to enable this partition. If the partition is already in the ACTIVE state, no action is taken. This method blocks until all required object migration is complete.

Parameters:

enableAction - The action to take when enabling partitions.

Throws:

ResourceUnavailableException - The minimum number of nodes needed to establish a quorum has not been seen, or the partition has not been defined.

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.

See Also:

PartitionManager.enablePartitions(PartitionManager.EnableAction)

disable

public final void disable(PartitionManager.DisableAction disableAction)
                   throws ResourceUnavailableException

Disable high availability for this partition.

This method is used to remove the local node from the node list of this partition, and move the partition state to UNAVAILABLE. If called multiple times, the additional calls have no effect.

If the local node does not exist in the partition, no action is taken.

Parameters:

disableAction - The action to take when disabling partitions.

Throws:

ResourceUnavailableException - The partition would be in the UNAVAILABLE state after the disable executes, not thrown if LEAVE_CLUSTER_FORCE is used.

See Also:

PartitionManager.disablePartitions(PartitionManager.DisableAction)

setNotifier

public final void setNotifier(PartitionNotifier partitionNotifier)

Associated a notifier with the partition.

This method is used to associate a user defined PartitionNotifier instance with a partition.

PartitionNotifier instances are local to a node, this method should be executed on all nodes which need to determine if a partition state change occurs.

The same PartitionNotifier instance can be associated with multiple partitions. Multiple PartitionNotifier instances can be installed for a given Partition. When a state change occurs, all instances are executed, no order is guaranteed when executing the notifiers. To remove a notifier, the PartitionNotifier instance should be deleted.

Parameters:

partitionNotifier - User defined notifier instance.

cardinality

public final long cardinality()

Returns the number of instances in this partition.

This method does not establish transaction locks on the partition or any of the individual objects in the partition. This means the number returned by cardinality() may change even as observed within a single transaction.

Warning: This method requires a scan of all objects for each class in the partition to determine the count, which is computationally expensive.

Returns:

Number of instances found.