RegisterSign In

API Documentation: Interface ConsensusProcessor

Package: com.mckoi.network

ConsensusProcessor defines the characteristics of a database path instance, including how the path instance should be initialized, how proposed changes to the instance are committed, and a way to display some stats about the instance.

A ConsensusProcessor implements a deterministic 'commit' function that either makes a proposed change to a database, or makes no change and generates a commit fault exception. The purpose of this interface is to provide a plug-in architecture for structured data models that can ensure their logical consistency in the face of changes to state made at any time.

Any none trivial data model will almost always need to enforce some sort of consistency rules (such as integrity constraints) that are not allowed to be violated when a change to a database is proposed. This interface allows a developer to define the consistency rules of a data model by providing a function to allow or reject a proposal, and if a proposal is accepted; define the final format of the accepted changes.

For example, a ConsensusProcessor for an SQL database would need to reject a proposal in which a row in a table is inserted with a primary key value that is already present in the table, or a single row that is deleted by concurrent clients. Another example is a ConsensusProcessor for a distributed file system would need to reject concurrent proposals to create a file object with the same name.

The ConsensusProcessor interface provides a way to enforce the consistency of a data model. Keep in mind that the 'commit' function, by definition, must be performed in a serial process because to accept or reject a proposal the current state of a database must be known and deterministic. No consensus would be able to be determined if it is unknown if the current state might change. For this reason, the consensus functions 'commit' method must be as efficient as possible.

Methods Summary

String getName()
String getDescription()
void initialize(ConsensusDDBConnection connection)
DataAddress commit(ConsensusDDBConnection connection, DataAddress proposal) throws CommitFaultException
String getStats(ConsensusDDBConnection connection, DataAddress snapshot)

Method Details

String getName()

The name of this processor, displayed in the adminsitration user interface.

String getDescription()

A description of this processor appropriate for display in the help section of the user interface.

void initialize(ConsensusDDBConnection connection)

This function creates an initial data model state on a completely blank database. This is only ever called once during the lifespan of a particular state, and the given connection will always be a blank untouched database.

This function is intended to setup the state of a database to a beginning state.

DataAddress commit(ConsensusDDBConnection connection, DataAddress proposal)

Attempts to commit a proposed change and create an updated database state. The given ConsensusDDBConnection object provides access to the latest version of the database as well as historical information about previous states. The proposal is represented as a DataAddress object which is the root node of a data tree that will contain the details of the changes proposed.

If a proposed commit is rejected, this function throws a CommitFaultException and no change is made. If the proposal is accepted, the returned DataAddress is the new root node of this path instance.

Note that this method should be efficiently implemented because it is not possible to perform this function on a single path instance in multiple processes. The reason for this is because the current database state must be deterministic.

String getStats(ConsensusDDBConnection connection, DataAddress snapshot)

Returns a String that briefly describes basic stats about the data model of the given snapshot. This function can return null if there are no stat functions implemented.

This string is intended to be displayed in a user interface to give some status feedback about a path instance to an administrator.

The text on this page is licensed under the Creative Commons Attribution 3.0 License. Java is a registered trademark of Oracle and/or its affiliates.
Mckoi is Copyright © 2000 - 2020 Diehl and Associates, Inc. All rights reserved.