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 java.lang.String ASYNCHRONOUS_MODE
      Property value used to indicate that the service should be booted in asynchronous replication mode.
      static java.lang.String MODULE
      The name of the Master Factory, used to boot the service.
      static java.lang.String REPLICATION_MODE
      Property key to specify replication mode
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      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 startFailover()
      Will perform all work needed to failover
      void startMaster​(RawStoreFactory rawStore, DataFactory dataFac, LogFactory logFac, java.lang.String slavehost, int slaveport, java.lang.String dbname)
      Will perform all the work that is needed to set up replication
      void stopMaster()
      Will perform all work that is needed to shut down replication.
      void workToDo()
      Used to notify the log shipper that a log buffer element is full.
    • Field Detail

      • MODULE

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

        static final java.lang.String REPLICATION_MODE
        Property key to specify replication mode
        See Also:
        Constant Field Values
      • ASYNCHRONOUS_MODE

        static final java.lang.String ASYNCHRONOUS_MODE
        Property value used to indicate that the service should be booted in asynchronous replication mode.
        See Also:
        Constant Field Values
    • Method Detail

      • startMaster

        void startMaster​(RawStoreFactory rawStore,
                         DataFactory dataFac,
                         LogFactory logFac,
                         java.lang.String slavehost,
                         int slaveport,
                         java.lang.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:
        LogFactory.flush(org.apache.derby.iapi.store.raw.log.LogInstant)
      • workToDo

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