edu.umass.cs.reconfiguration

Class AbstractReplicaCoordinator<NodeIDType>

java.lang.Object

edu.umass.cs.reconfiguration.AbstractReplicaCoordinator<NodeIDType>

Type Parameters:

NodeIDType -

This abstract class should be inherited by replica coordination protocols. The only abstract method the inheritor needs to implement is coordinateRequest(.). For example, this method could lazily propagate the request to all replicas; or it could ensure reliable receipt from a threshold number of replicas for durability, and so on. Notes: In general, coordinateRequest(.) is app-specific logic. But most common cases, e.g., linearizability, sequential, causal, eventual, etc. can be implemented agnostic to app-specific details with supporting libraries that we can provide. A request is not an entity that definitively does or does not need coordination. A request, e.g., a read request, may or may not need coordination depending on the replica coordination protocol, which is why it is here.

All Implemented Interfaces:

Application, AppRequestParser, AppRequestParserBytes, Replicable, Reconfigurable, ReplicaCoordinator<NodeIDType>, Repliconfigurable

Direct Known Subclasses:

AbstractReplicaCoordinatorPersistent, AbstractTransactor, DynamoReplicaCoordinator, PaxosReplicaCoordinator

public abstract class AbstractReplicaCoordinator<NodeIDType>
extends java.lang.Object
implements Repliconfigurable, ReplicaCoordinator<NodeIDType>, AppRequestParserBytes

Author:

V. Arun

Field Summary

Fields

Modifier and Type	Field and Description
protected Repliconfigurable	app
protected Messenger<NodeIDType,?>	messenger

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractReplicaCoordinator(Replicable app)
	AbstractReplicaCoordinator(Replicable app, Messenger<NodeIDType,?> messenger)

Method Summary

Modifier and Type	Method and Description
protected void	callCallback(Request request, boolean handled, ExecutedCallback requestCallback)
java.lang.String	checkpoint(java.lang.String name) Checkpoints the current application state and returns it.
abstract boolean	coordinateRequest(Request request, ExecutedCallback callback) Start of abstract methods
boolean	createReplicaGroup(java.util.Map<java.lang.String,java.lang.String> nameStates, java.util.Set<NodeIDType> nodes) Default implementation that can be overridden for more batching optimization.
abstract boolean	createReplicaGroup(java.lang.String serviceName, int epoch, java.lang.String state, java.util.Set<NodeIDType> nodes) This method should return true if the replica group is successfully created or one already exists with the same set of nodes.
boolean	deleteFinalState(java.lang.String name, int epoch) Garbage-collects the final state for name, epoch.
abstract boolean	deleteReplicaGroup(java.lang.String serviceName, int epoch) This method should result in all state corresponding to serviceName being deleted
boolean	execute(Request request)
boolean	execute(Request request, boolean noReplyToClient) This method must handle the request atomically and return true if successful or throw an exception or return false.
boolean	execute(Request request, boolean noReplyToClient, ExecutedCallback requestCallback) This method is a wrapper for Application.handleRequest and meant to be invoked by the class that implements this AbstractReplicaCoordinator or its helper classes.
java.util.Set<IntegerPacketType>	getAppRequestTypes() Need to return just app's request types.
protected java.lang.String	getARARNodesAsString()
protected java.lang.String	getARRCNodesAsString()
protected ReconfiguratorCallback	getCallback()
java.util.Set<IntegerPacketType>	getCoordinatorRequestTypes()
java.lang.Integer	getEpoch(java.lang.String name) Returns the current (unique) epoch for name.
java.lang.String	getFinalState(java.lang.String name, int epoch) Return the final checkpointed state for name, epoch.
protected Messenger<NodeIDType,?>	getMessenger()
protected java.util.Set<IntegerPacketType>	getMutualAuthAppRequestTypes()
NodeIDType	getMyID()
abstract java.util.Set<NodeIDType>	getReplicaGroup(java.lang.String serviceName) This method must return the replica group that was most recently successfully created for the serviceName using createReplicaGroup.
Request	getRequest(byte[] bytes, NIOHeader header) The implementation of this method is tied to and must be the inverse of Request.toBytes(), , i.e., invoking getRequest(request.toBytes(), header).equals(request).
protected Request	getRequest(ReplicableClientRequest rcr, NIOHeader header)
Request	getRequest(java.lang.String stringified) An application must support string-to-Request conversion and back.
ReconfigurableRequest	getStopRequest(java.lang.String name, int epoch) Returns a stop request that when executed by the app ensures that no subsequent request after the stop is executed in that epoch.
protected boolean	handleIncoming(Request request, ExecutedCallback callback) Coordinate if needed, else hand over to app.
boolean	hasLargeCheckpoints()
void	putInitialState(java.lang.String name, int epoch, java.lang.String state) Inserts the specified state as the initial state for name, epoch.
protected void	registerCoordination(IntegerPacketType... types)
boolean	restore(java.lang.String name, java.lang.String state) Resets the current application state for name to state.
protected void	sendAllLazy(Request request) Request propagation helper methods
protected AbstractReplicaCoordinator<NodeIDType>	setCallback(ReconfiguratorCallback callback) This "default" callback will be called after every request execution.
void	setLargeCheckpoints() Enables large checkpoints.
protected void	setMessenger(Messenger<NodeIDType,?> messenger)
protected AbstractReplicaCoordinator<NodeIDType>	setStopCallback(ReconfiguratorCallback callback) Used only at active replicas.
void	stop() End of private helper methods

Methods inherited from class java.lang.Object

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

Methods inherited from interface edu.umass.cs.gigapaxos.interfaces.AppRequestParser

getMutualAuthRequestTypes, getRequestTypes, getServerAuthRequestTypes

Field Detail

app

protected final Repliconfigurable app

messenger

protected Messenger<NodeIDType,?> messenger

Constructor Detail

AbstractReplicaCoordinator

protected AbstractReplicaCoordinator(Replicable app)

AbstractReplicaCoordinator

public AbstractReplicaCoordinator(Replicable app,
                                  Messenger<NodeIDType,?> messenger)

Parameters:

app -

messenger -

Method Detail

coordinateRequest

public abstract boolean coordinateRequest(Request request,
                                          ExecutedCallback callback)
                                   throws java.io.IOException,
                                          RequestParseException

Start of abstract methods

Specified by:

coordinateRequest in interface ReplicaCoordinator<NodeIDType>

Parameters:

request -

callback -

Returns:

Success of coordination.

Throws:

java.io.IOException

RequestParseException

createReplicaGroup

public abstract boolean createReplicaGroup(java.lang.String serviceName,
                                           int epoch,
                                           java.lang.String state,
                                           java.util.Set<NodeIDType> nodes)

Description copied from interface: ReplicaCoordinator

This method should return true if the replica group is successfully created or one already exists with the same set of nodes. It should return false otherwise.

Specified by:

createReplicaGroup in interface ReplicaCoordinator<NodeIDType>

Returns:

True if created successfully.

deleteReplicaGroup

public abstract boolean deleteReplicaGroup(java.lang.String serviceName,
                                           int epoch)

Description copied from interface: ReplicaCoordinator

This method should result in all state corresponding to serviceName being deleted

Specified by:

deleteReplicaGroup in interface ReplicaCoordinator<NodeIDType>

Returns:

True if deleted without errors.

getReplicaGroup

public abstract java.util.Set<NodeIDType> getReplicaGroup(java.lang.String serviceName)

Description copied from interface: ReplicaCoordinator

This method must return the replica group that was most recently successfully created for the serviceName using createReplicaGroup.

Specified by:

getReplicaGroup in interface ReplicaCoordinator<NodeIDType>

Returns:

Set of nodes in the replica group for serviceName.

getCoordinatorRequestTypes

public java.util.Set<IntegerPacketType> getCoordinatorRequestTypes()

Returns:

Request types for coordination requests. By default, it is the AppRequestParser.getRequestTypes() - getAppRequestTypes(). This method must be overridden for non-default behavior.

setMessenger

protected void setMessenger(Messenger<NodeIDType,?> messenger)

getMessenger

protected Messenger<NodeIDType,?> getMessenger()

registerCoordination

protected void registerCoordination(IntegerPacketType... types)

setCallback

protected final AbstractReplicaCoordinator<NodeIDType> setCallback(ReconfiguratorCallback callback)

This "default" callback will be called after every request execution. If there is a request-specific callback also specified, this callback will be called before the request-specific callback.

Parameters:

callback -

Returns:

this

getCallback

protected final ReconfiguratorCallback getCallback()

setStopCallback

protected final AbstractReplicaCoordinator<NodeIDType> setStopCallback(ReconfiguratorCallback callback)

Used only at active replicas.

Parameters:

callback -

Returns:

this

handleIncoming

protected boolean handleIncoming(Request request,
                                 ExecutedCallback callback)

Coordinate if needed, else hand over to app.

Parameters:

request -

Returns:

True if coordinated successfully or handled successfully (locally), false otherwise.

execute

public boolean execute(Request request)

Specified by:

execute in interface Application

Returns:

True if the request is executed successfully.

execute

public boolean execute(Request request,
                       boolean noReplyToClient)

Description copied from interface: Replicable

This method must handle the request atomically and return true if successful or throw an exception or return false. It is the application's responsibility to ensure atomicity, i.e., it should return true iff the request was successfully executed; if it returns false or throws an exception, the application should ensure that the state of the application rolls back any partial execution of this request. If it returns false or throws an exception, the replica coordination protocol may try to re-attempt executing the request.

Specified by:

execute in interface Replicable

noReplyToClient - If true, the application is expected to not send a response back to the originating client (say, because this request is part of a post-crash roll-forward or only the "entry replica" that received the request from the client is expected to respond back. If false, the application is expected to either send a response (if any) back to the client via the ClientMessenger interface or delegate response messaging to paxos via the ClientRequest.getResponse() interface.

Returns:

Must return true if and only if the application handled the request successfully. For safety, executing a request must have a deterministic effect on the safety-critical state. If the request is bad and is to be discarded, the application must still return true (after "successfully" discarding it). If the application returns false, the replica coordination protocol (e.g., paxos) might try to repeatedly re-execute it until successful or kill this replica group ( request.getServiceName()) altogether after a limited number of retries, so the replica group may get stuck unless it returns true after a limited number of retries. Thus, with paxos as the replica coordination protocol, returning false is not really an option as paxos has no way to "roll back" a request whose global order has already been agreed upon.

With replica coordination protocols other than paxos, the boolean return value could be used in protocol-specific ways, e.g., a primary-backup protocol might normally execute a request at just one replica but relay the request to one or more backups if the return value of Application.execute(Request) is false.

execute

public boolean execute(Request request,
                       boolean noReplyToClient,
                       ExecutedCallback requestCallback)

This method is a wrapper for Application.handleRequest and meant to be invoked by the class that implements this AbstractReplicaCoordinator or its helper classes. We need control over this method in order to call the callback after the app's handleRequest method has been executed. An alternative would have been to enforce the callback as part of the Reconfigurable interface. However, this is a less preferred design because it depends more on the app's support for stop requests even though a stop request is really meaningless to an app. Should we add support for response messaging here using the ClientMessgenser and ClientRequest interfaces similar to that in gigapaxos? No, because response messaging details are specific to the coordination protocol.

Parameters:

request -

noReplyToClient -

requestCallback -

Returns:

True

getRequest

public final Request getRequest(java.lang.String stringified)
                         throws RequestParseException

Description copied from interface: AppRequestParser

An application must support string-to-Request conversion and back. Furthermore, the conversion to a string and back must preserve the return values of all Request methods, i.e., Application.getRequest (request.toString())).equals(request) must be true.

Specified by:

getRequest in interface AppRequestParser

Returns:

Request corresponding to stringified.

Throws:

RequestParseException

getRequest

public final Request getRequest(byte[] bytes,
                                NIOHeader header)
                         throws RequestParseException

Description copied from interface: AppRequestParser

The implementation of this method is tied to and must be the inverse of Request.toBytes(), , i.e., invoking getRequest(request.toBytes(), header).equals(request).

Specified by:

getRequest in interface AppRequestParser

Specified by:

getRequest in interface AppRequestParserBytes

Returns:

Request parsed from message.

Throws:

RequestParseException

getRequest

protected final Request getRequest(ReplicableClientRequest rcr,
                                   NIOHeader header)
                            throws RequestParseException

Throws:

RequestParseException

getAppRequestTypes

public java.util.Set<IntegerPacketType> getAppRequestTypes()

Need to return just app's request types. Coordination packets can go directly to the coordination module and don't have to be known to ActiveReplica.

Returns:

Set of request types that the app is designed to handle.

getStopRequest

public ReconfigurableRequest getStopRequest(java.lang.String name,
                                            int epoch)

Description copied from interface: Reconfigurable

Returns a stop request that when executed by the app ensures that no subsequent request after the stop is executed in that epoch. We need the app to return a stop request as opposed to just exposing a stop() method because, in general, the stop may need to be coordinated across app replicas. If nothing special has to be done by the app upon an epoch stop, it is okay for this method to just return null or a no-op request. If an app is using PaxosReplicaCoordinator, nothing special needs to be done by the app upon an epoch stop, so it can return either null or a no-op request.

Specified by:

getStopRequest in interface Reconfigurable

Returns:

InterfaceReconfigurableRequest corresponding to the stop request for the replica group name:epoch.

getFinalState

public java.lang.String getFinalState(java.lang.String name,
                                      int epoch)

Description copied from interface: Reconfigurable

Return the final checkpointed state for name, epoch. If a checkpoint does not yet exist, it has to be created. This method should return null if the app has moved on, i.e., its current epoch number is higher than epoch and it has no final state for the requested epoch (possibly because it has been garbage-collected). This method will typically get called right after a stop request has been supplied for execution to the app, so it is a good idea for the application to create the checkpoint immediately after executing an epoch stop request.

Specified by:

getFinalState in interface Reconfigurable

Returns:

The final state, or a concise handle thereof, as a String.

putInitialState

public void putInitialState(java.lang.String name,
                            int epoch,
                            java.lang.String state)

Description copied from interface: Reconfigurable

Inserts the specified state as the initial state for name, epoch. This method marks the creation of an epoch. All lower epoch numbers must be marked as inactive at this point. After this method has been called, the app can only accept requests for "name" in the epoch "epoch".

Specified by:

putInitialState in interface Reconfigurable

deleteFinalState

public boolean deleteFinalState(java.lang.String name,
                                int epoch)

Description copied from interface: Reconfigurable

Garbage-collects the final state for name, epoch.

Specified by:

deleteFinalState in interface Reconfigurable

Returns:

True if final state for name:epoch was deleted or did not exist to begin with.

getEpoch

public java.lang.Integer getEpoch(java.lang.String name)

Description copied from interface: Reconfigurable

Returns the current (unique) epoch for name. At most a single epoch can actively exist at any time at a replica. The app replica may maintain the final state for lower (inactive) epochs, but may not accept requests in any epoch other than the currently active epoch if one exists. This method should return null if no active replica for the name exists at this node.

Specified by:

getEpoch in interface Reconfigurable

Returns:

The current epoch number for name.

checkpoint

public java.lang.String checkpoint(java.lang.String name)

Description copied from interface: Replicable

Checkpoints the current application state and returns it.

Specified by:

checkpoint in interface Replicable

Returns:

Returns the checkpoint state. If the application encounters an error while creating the checkpoint, it must retry until successful or throw a RuntimeException. Returning a null value will be interpreted to mean that the application state is indeed null.

Note that state may simply be an app-specific handle, e.g., a file name, representing the state as opposed to the actual state. The application is responsible for interpreting the state returned by Replicable.checkpoint(String) and that supplied in Replicable.restore(String, String) in a consistent manner.

restore

public boolean restore(java.lang.String name,
                       java.lang.String state)

Description copied from interface: Replicable

Resets the current application state for name to state.

Note that state may simply be an app-specific handle, e.g., a file name, representing the state as opposed to the actual state. The application is responsible for interpreting the state returned by Replicable.checkpoint(String) and that supplied in Replicable.restore(String, String) in a consistent manner.

Specified by:

restore in interface Replicable

Returns:

True if the app atomically updated the state successfully. Else, it must throw an exception. If it returns false, the replica coordination protocol may try to repeat the operation until successful causing the application to get stuck.

callCallback

protected final void callCallback(Request request,
                                  boolean handled,
                                  ExecutedCallback requestCallback)

getMyID

public NodeIDType getMyID()

Returns:

My node ID.

hasLargeCheckpoints

public boolean hasLargeCheckpoints()

Returns:

True if large checkpoints are enabled.

setLargeCheckpoints

public void setLargeCheckpoints()

Enables large checkpoints. Large checkpoints means that the file system will be used to store or retrieve remote checkpoints. This is the only way to do checkpointing if the checkpoint state size exceeds the amount of available memory.

createReplicaGroup

public boolean createReplicaGroup(java.util.Map<java.lang.String,java.lang.String> nameStates,
                                  java.util.Set<NodeIDType> nodes)

Default implementation that can be overridden for more batching optimization.

Parameters:

nameStates -

nodes -

Returns:

True if all groups successfully created.

stop

public void stop()

End of private helper methods

sendAllLazy

protected void sendAllLazy(Request request)
                    throws java.io.IOException,
                           RequestParseException,
                           org.json.JSONException

Request propagation helper methods

Throws:

java.io.IOException

RequestParseException

org.json.JSONException

getMutualAuthAppRequestTypes

protected java.util.Set<IntegerPacketType> getMutualAuthAppRequestTypes()

Returns:

Refer AppRequestParser.getMutualAuthRequestTypes()

getARARNodesAsString

protected java.lang.String getARARNodesAsString()

getARRCNodesAsString

protected java.lang.String getARRCNodesAsString()