Interface MasterFactory

All Known Implementing Classes:
MasterController

public interface MasterFactory

This is the interface for the replication master controller service. The master controller service is booted when this instance of Derby will have the replication master role for this database.

The replication master service is responsible for managing all replication related functionality on the master side of replication. This includes connecting to the slave, setting up a log buffer to temporarily store log records from the LogFactory, and to ship these log records to the slave.

The master controller currently only supports asynchronous replication. This means that there are no guarantees that transactions that have committed here (the master side) are also reflected on the slave side. However, the slave version of the database IS guaranteed to be transaction consistent. This implies that:

  • A transaction t that is committed on the master will either be fully reflected or not be reflected at all on the slave when the slave database is turned into a non-replicated database (that is, at failover time)
  • Slave execution of operations is in the same serial order as on the master because replication is based on redoing log records to the slave. By definition, log records are in serial order. This implies that if transaction t1 commits before t2 on the master, and t2 has been committed on the slave, t1 is also guaranteed to have committed on the slave.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    Property value used to indicate that the service should be booted in asynchronous replication mode.
    static final String
    The name of the Master Factory, used to boot the service.
    static final String
    Property key to specify replication mode
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    appendLog(long greatestInstant, byte[] log, int logOffset, int logLength)
    Append a chunk of log records to the log buffer.
    void
    flushedTo(long instant)
    Used by the LogFactory to notify the replication master controller that the log records up to this instant have been flushed to disk.
    void
    Will perform all work needed to failover
    void
    startMaster(RawStoreFactory rawStore, DataFactory dataFac, LogFactory logFac, String slavehost, int slaveport, String dbname)
    Will perform all the work that is needed to set up replication
    void
    Will perform all work that is needed to shut down replication.
    void
    Used to notify the log shipper that a log buffer element is full.
  • Field Details

    • MODULE

      static final String MODULE
      The name of the Master Factory, used to boot the service.
      See Also:
    • REPLICATION_MODE

      static final String REPLICATION_MODE
      Property key to specify replication mode
      See Also:
    • ASYNCHRONOUS_MODE

      static final String ASYNCHRONOUS_MODE
      Property value used to indicate that the service should be booted in asynchronous replication mode.
      See Also:
  • Method Details

    • startMaster

      void startMaster(RawStoreFactory rawStore, DataFactory dataFac, LogFactory logFac, String slavehost, int slaveport, String dbname) throws StandardException
      Will perform all the work that is needed to set up replication
      Parameters:
      rawStore - The RawStoreFactory for the database
      dataFac - The DataFactory for this database
      logFac - The LogFactory ensuring recoverability for this database
      slavehost - The hostname for the slave
      slaveport - The port the slave is listening on
      dbname - The master database that is being replicated.
      Throws:
      StandardException - Standard Derby exception policy, thrown on replication startup error.
    • stopMaster

      void stopMaster() throws StandardException
      Will perform all work that is needed to shut down replication.
      Throws:
      StandardException - If the replication master has been stopped already.
    • startFailover

      void startFailover() throws StandardException
      Will perform all work needed to failover
      Throws:
      StandardException - 1) If the failover succeeds, an exception is thrown to indicate that the master database was shutdown after a successful failover 2) If a failure occurs during network communication with slave.
    • appendLog

      void appendLog(long greatestInstant, byte[] log, int logOffset, int logLength)
      Append a chunk of log records to the log buffer.
      Parameters:
      greatestInstant - the instant of the log record that was added last to this chunk of log
      log - the chunk of log records
      logOffset - offset in log to start copy from
      logLength - number of bytes to copy, starting from logOffset
    • flushedTo

      void flushedTo(long instant)
      Used by the LogFactory to notify the replication master controller that the log records up to this instant have been flushed to disk. The master controller takes action according to the current replication strategy when this method is called. When the asynchronous replication strategy is used, the method does not force log shipping to the slave; the log records may be shipped now or later at the MasterFactory's discretion. However, if another strategy like 2-safe replication is implemented in the future, a call to this method may force log shipment before returning control to the caller. Currently, only asynchronous replication is supported.
      Parameters:
      instant - The highest log instant that has been flushed to disk
      See Also:
    • workToDo

      void workToDo()
      Used to notify the log shipper that a log buffer element is full.