com.sleepycat.je.rep.elections
Class Elections

java.lang.Object
  extended by com.sleepycat.je.rep.elections.Elections

public class Elections
extends Object

Represents the environment in which elections are run on behalf of a node. There is exactly one instance of an Elections for each node. Elections are initiated via this class. One of the primary goals of this interface is to keep Elections as free standing as possible, so that we can change how elections are held, or aspects of the election infrastructure with minimal impact on replication. For example, elections currently used tcp for communication of election messages but may want to switch over to udp. Such a change should be confined to just the Elections module. Other changes might include changes to the strategy used to suggest Values and the weight associated with a suggested Value. The following are the principal points of interaction between Elections and Replication: 1) The initiation of elections via the initiateElections() method. 2) The suggestion of nodes as masters and the ranking of the suggestion. This is done via the Acceptor.SuggestionGenerator interface. An instance of this interface is supplied when the Elections class is instantiated. Note that the implementation must also initiate a freeze of VLSNs to ensure that the ranking does not change as the election progresses. The VLSN can make progress when the node is informed via its Listener that an election with a higher Proposal number (than the one in the Propose request) has finished. 3) Obtaining the result of an election initiated in step 1. This is done via the Learner.Listener interface. An instance of this class is supplied when the Election class is first instantiated.


Nested Class Summary
(package private) static class Elections.ElectionListener
          Used to short-circuit Proposal retries if a new election has completed since the time this election was initiated.
(package private) static class Elections.RetryPredicate
          Implements the retry policy
 
Constructor Summary
Elections(RepNode repNode, Learner.Listener listener, Acceptor.SuggestionGenerator suggestionGenerator)
          Creates an instance of Elections.
 
Method Summary
 void asyncInformMonitors(Proposer.Proposal proposal, Protocol.Value value)
          Used to propagate the results of an election to any monitors.
 boolean electionInProgress()
          Predicate to determine whether an election is currently in progress.
 Acceptor getAcceptor()
          Returns the Acceptor associated with this node.
 Set<InetSocketAddress> getAcceptorSockets()
          Returns a current set of acceptor sockets.
 int getElectionCount()
          The number of elections that have been held.
 Learner getLearner()
          Returns the Learner associated with this node
 Logger getLogger()
           
 Protocol getProtocol()
           
 RepImpl getRepImpl()
           
 RepNode getRepNode()
           
 ServiceDispatcher getServiceDispatcher()
           
 StatGroup getStats()
          Statistics used during testing.
 ExecutorService getThreadPool()
           
 void initiateElection(RepGroupImpl newGroup, QuorumPolicy quorumPolicy)
          The standard method for requesting and election, we normally want to run elections until we hear of an election result.
 void initiateElection(RepGroupImpl newGroup, QuorumPolicy quorumPolicy, int maxRetries)
          Initiates an election.
 void participate()
          Permits the Election agent to start participating in elections held by the replication group, or initiate elections on behalf of this node.
 void shutdown()
          Shuts down just the election support at this node.
 void shutdownAcceptorsLearners(Set<InetSocketAddress> acceptorSockets, Set<InetSocketAddress> learnerSockets)
          Shutdown all acceptor and learner agents by broadcasting a Shutdown message.
 void startLearner()
          Starts a Learner agent.
 void updateRepGroup(RepGroupImpl newRepGroup)
          Updates elections notion of the rep group, so that acceptors are aware of the current state of the group, even in the absence of an election conducted by the node itself.
 void waitForElection()
          For INTERNAL TESTING ONLY.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Elections

public Elections(RepNode repNode,
                 Learner.Listener listener,
                 Acceptor.SuggestionGenerator suggestionGenerator)
Creates an instance of Elections. There should be just one instance per node. Note that the creation does not result in the election threads being started, that is, the instance does not participate in elections. This call is typically followed up with a call to startLearner that lets it learn about elections results and, if applicable, by a subsequent call to participate to let it vote in elections.

Parameters:
listener - the Listener invoked when results are available
repNode - is the owning replicated node, the associated repImpl may be null, if it's being run in a test environment.
suggestionGenerator - used by the Acceptor
Method Detail

getThreadPool

public ExecutorService getThreadPool()

getServiceDispatcher

public ServiceDispatcher getServiceDispatcher()

getRepNode

public RepNode getRepNode()

getLogger

public Logger getLogger()

getRepImpl

public RepImpl getRepImpl()

startLearner

public void startLearner()
                  throws IOException
Starts a Learner agent. Note that the underlying Protocol instance it uses must have a current picture of the replication group otherwise it will reject messages from nodes that it does not think are currently part of the replication group.

Throws:
IOException

participate

public void participate()
                 throws IOException
Permits the Election agent to start participating in elections held by the replication group, or initiate elections on behalf of this node. Participation in elections is initiated only after a node has current information about group membership.

Throws:
IOException

getAcceptor

public Acceptor getAcceptor()
Returns the Acceptor associated with this node.

Returns:
the Acceptor

getAcceptorSockets

public Set<InetSocketAddress> getAcceptorSockets()
Returns a current set of acceptor sockets.


getProtocol

public Protocol getProtocol()

getLearner

public Learner getLearner()
Returns the Learner associated with this node

Returns:
the Learner

getElectionCount

public int getElectionCount()
The number of elections that have been held. Used for testing.

Returns:
total elections initiated by this node.

initiateElection

public void initiateElection(RepGroupImpl newGroup,
                             QuorumPolicy quorumPolicy,
                             int maxRetries)
                      throws InterruptedException
Initiates an election. Note that this may just be one of many possible elections that are in progress in a replication group. The method does not wait for this election to complete, but instead returns as soon as any election result (including one initiated by some other Proposer) becomes available via the Learner. A proposal submitted as part of this election may lose out to other concurrent elections, or there may not be a sufficient number of Acceptor agents active or reachable to reach a quorum. In such cases, the election will not produce a result. That is, there will be no notification to the Learners. Note that only one election can be initiated at a time at a node If a new election is initiated while one is already in progress, then the method will wait until it completes before starting a new one. The results of this and any other elections that may have been initiated concurrently by other nodes are made known to the Learner agents. Note that this method does not return a result, since the concurrent arrival of results could invalidate the result even before its returned.

Parameters:
newGroup - the definition of the group to be used for this election
quorumPolicy - the policy to be used to reach a quorum.
maxRetries - the max number of times a proposal may be retried
Throws:
InterruptedException

initiateElection

public void initiateElection(RepGroupImpl newGroup,
                             QuorumPolicy quorumPolicy)
                      throws InterruptedException
The standard method for requesting and election, we normally want to run elections until we hear of an election result. Once initiated, elections run until there is a successful conclusion, that is, a new master has been elected. Since a successful conclusion requires the participation of at least a simple majority, this may take a while if a sufficient number of nodes are not available. The above method is used mainly for testing.

Throws:
InterruptedException
See Also:
initiateElection(com.sleepycat.je.rep.impl.RepGroupImpl, com.sleepycat.je.rep.QuorumPolicy, int)

updateRepGroup

public void updateRepGroup(RepGroupImpl newRepGroup)
Updates elections notion of the rep group, so that acceptors are aware of the current state of the group, even in the absence of an election conducted by the node itself. This method should be invoked each time a node becomes aware of a group membership change.

Parameters:
newRepGroup - defines the new group

electionInProgress

public boolean electionInProgress()
Predicate to determine whether an election is currently in progress.


getStats

public StatGroup getStats()
Statistics used during testing.


waitForElection

public void waitForElection()
                     throws InterruptedException
For INTERNAL TESTING ONLY. Ensures that the initiated election has reached a conclusion that can be tested.

Throws:
InterruptedException

shutdownAcceptorsLearners

public void shutdownAcceptorsLearners(Set<InetSocketAddress> acceptorSockets,
                                      Set<InetSocketAddress> learnerSockets)
                               throws InterruptedException
Shutdown all acceptor and learner agents by broadcasting a Shutdown message. It waits until reachable agents have acknowledged the message and the local learner and acceptor threads have exited. This is method is intended for use during testing only.

Throws:
InterruptedException

shutdown

public void shutdown()
              throws InterruptedException
Shuts down just the election support at this node. That is the Acceptor, and Learner associated with this Elections as well as any pending election running in its thread is terminated.

Throws:
InterruptedException

asyncInformMonitors

public void asyncInformMonitors(Proposer.Proposal proposal,
                                Protocol.Value value)
Used to propagate the results of an election to any monitors. Note that monitors are informed of results redundantly, both from the node that concludes the election and via this re-propagation. The use of multiple network paths increases the likelihood that the result will reach the monitor via some functioning network path. The method returns immediately after queuing the operation in the thread pool.



Copyright (c) 2004-2012 Oracle. All rights reserved.