Interface ReplicationDomainDB

All Known Implementing Classes:
FileChangelogDB

public interface ReplicationDomainDB
This interface allows to query or control the replication domain database(s) (composed of one or more ReplicaDBs) and query/update each ReplicaDB.

In particular, the getCursorFom() methods allow to obtain a cursor at any level:

  • Across all the domains, provided a MultiDomainServerState
  • Across all replicaDBs of a domain, provided a ServerState
  • On one replica DB for a domain and replica id, provided a CSN
The cursor starting point is specified by providing a key, and a DBCursor.PositionStrategy.
  • Method Details

    • getDomainOldestCSNs

      ServerState getDomainOldestCSNs(Dn baseDN)
      Returns the oldest CSNs from the replicaDBs for each replica id in the specified replication domain.
      Parameters:
      baseDN - the replication domain baseDN
      Returns:
      a new ServerState object holding the {replicaId to oldest CSN} mapping. If a replica DB is empty or closed, the oldest CSN will be null for that replica. The caller owns the generated ServerState.
    • getDomainNewestCSNs

      ServerState getDomainNewestCSNs(Dn baseDN)
      Returns the newest CSNs from the replicaDBs for each replica id in the specified replication domain.
      Parameters:
      baseDN - the replication domain baseDN
      Returns:
      a new ServerState object holding the {replicaId to newest CSN} Map. If a replica DB is empty or closed, the newest CSN will be null for that replica. The caller owns the generated ServerState.
    • getNewestMessage

      UpdateMsg getNewestMessage(DomainReplicaId replica)
      Returns the newest message from the replica DB for the provided replica.
      Parameters:
      replica - the base dn and replica id of the replica
      Returns:
      the newest message from the replica DB
    • removeDomain

      void removeDomain(Dn baseDN) throws ChangelogException
      Removes all the data relating to the specified replication domain and shutdown all its replica databases. In particular, it will:
      1. remove all the changes from the replica databases
      2. remove all knowledge of the replicaIds in this domain
      3. remove any knowledge of the current generationId for this domain
      Parameters:
      baseDN - the replication domain baseDN
      Throws:
      ChangelogException - If a database problem happened
    • getCursorFrom

      Generates a DBCursor across all the domains starting before, at or after the provided MultiDomainServerState for each domain, depending on the provided matching and positioning strategies.

      When the cursor is not used anymore, client code MUST call the DBCursor.close() method to free the resources and locks used by the cursor.

      If the positioning strategy defined in options is GREATER_THAN_KEY or GREATER_THAN_OR_EQUAL_TO_KEY, positioning may happen at a change from a replica added after the matching point, otherwise it will position at a change from one of the known replicas.

      Parameters:
      startState - Starting point for each domain cursor. If any ServerState for a domain is null, then start from the oldest CSN for each replicaDBs
      options - The cursor options
      Returns:
      a non null DBCursor
      Throws:
      ChangelogException - If a database problem happened
      See Also:
    • getCursorFrom

      MultiDomainDBCursor getCursorFrom(MultiDomainServerState startState, DBCursor.CursorOptions options, Set<Dn> excludedDomainDns) throws ChangelogException
      Generates a DBCursor across all the domains starting before, at or after the provided MultiDomainServerState for each domain, excluding a provided set of domain DNs.

      When the cursor is not used anymore, client code MUST call the DBCursor.close() method to free the resources and locks used by the cursor.

      If the positioning strategy defined in options is GREATER_THAN_KEY or GREATER_THAN_OR_EQUAL_TO_KEY, positioning may happen at a change from a replica added after the matching point, otherwise it will position at a change from one of the known replicas.

      Parameters:
      startState - Starting point for each domain cursor. If any ServerState for a domain is null, then start from the oldest CSN for each replicaDBs
      options - The cursor options
      excludedDomainDns - Every domain appearing in this set is excluded from the cursor
      Returns:
      a non null DBCursor
      Throws:
      ChangelogException - If a database problem happened
      See Also:
    • getPublisherFromCookie

      Flowable<UpdateRecord> getPublisherFromCookie(String name, MultiDomainServerState cookie, Set<Dn> excludedDomains)
      Returns a publisher of all changes starting from the provided cookie, excluding the changes from the provided set of excluded domains.

      More precisely, it publishes all records with a CSN which is greater than the corresponding CSN in the cookie or are from a domain or replica that is not present in the cookie, except those that are present in the set of excluded domains.

      The subscription to this publisher must be cancelled when it is not used anymore.

      The publisher is automatically updated if some base DN or replica is either added or removed to/from the changelog database, except those that are present in the set of excluded domains.

      Reading will start only when the returned Flowable has been subscribed to.

      Parameters:
      name - The name of this publisher
      cookie - Provides the starting point for each replica. If a replica is not present in the cookie, then the starting point is the oldest record of the replica.
      excludedDomains - The domains which are excluded from the publisher. All replicas belonging to these domains are excluded even if they are present in the cookie.
      Returns:
      a publisher of all changes starting from the provided cookie, excluding the changes from the provided set of excluded domains.
    • getPublisherForDomain

      Flowable<UpdateRecord> getPublisherForDomain(String name, Dn domain, ServerState startState, ServerState endState)
      Returns a publisher of changes from the provided domain, using the provided states to determine the starting and ending points of each replica of the domain.

      More precisely, it publishes all records with a CSN which is greater than the corresponding CSN in the startState or are from a replica that is not present in the startState, and with a CSN that is lower or equal than the corresponding CSN in the endState.

      Thus, provided a couple (startCsn, endCns), there are four possibilities for a given replica of the domain:

      • (null, null): publishes ]-infinite, +infinite[
      • (startCsn, null): publishes ]startCsn, +infinite[
      • (startCsn, endCsn) where startCsn <= endCsn: publishes ]startCsn, endCsn]. Automatically removes the replica from the publisher once the endState is reached.
      • (startCsn, endCsn) where startCsn > endCsn: : publishes no record In other words, excludes this replica from the publisher.
      The publisher is automatically updated if some replica is either added or removed to/from the domain, applying theses rules to determine the start and end states for this replica.

      The publisher returns an error immediately after subscription if there is a change with a CSN greater than the start CSN in a replica changelog and no change with the start CSN (which indicates that the corresponding change has been purged). If the most recent change in a replica changelog is older than the start CSN, then it is not an error and the changes will be eventually published just after the start CSN is reached.

      The publisher must be cancelled at the end of use.

      Reading will start only when the returned Flowable has been subscribed to.

      Parameters:
      name - The name of this publisher
      domain - The base DN of the domain to be published.
      startState - Provides the starting point for each replica. If a replica is not present in this state, then the starting point is the oldest record of the replica.
      endState - Provides the ending point for each replica. If a replica is not present in this state, then it has no ending point and its records will be published until the publisher is stopped or cancelled.
      Returns:
      a publisher of changes from the provided domain, using the provided states to determine the starting and ending points of each replica of the domain.
    • getCursorFrom

      DBCursor<UpdateMsg> getCursorFrom(Dn baseDN, ServerState startState, DBCursor.CursorOptions options) throws ChangelogException
      Generates a DBCursor across all the replicaDBs for the specified replication domain starting before, at or after the provided ServerState for each replicaDB, depending on the provided matching and positioning strategies.

      When the cursor is not used anymore, client code MUST call the DBCursor.close() method to free the resources and locks used by the cursor.

      If the positioning strategy defined in options is GREATER_THAN_KEY or GREATER_THAN_OR_EQUAL_TO_KEY, positioning may happen at a change from a replica added after the matching point, otherwise it will position at a change from one of the known replicas.

      Parameters:
      baseDN - the replication domain baseDN
      startState - Starting point for each ReplicaDB cursor. If any CSN for a replicaDB is null, then start from the oldest CSN for this replicaDB
      options - The cursor options
      Returns:
      a non null DBCursor
      Throws:
      ChangelogException - If a database problem happened
      See Also:
    • getCursorFrom

      DBCursor<UpdateMsg> getCursorFrom(DomainReplicaId replica, CSN startCSN, DBCursor.CursorOptions options) throws ChangelogException
      Generates a DBCursor for one replicaDB for the specified replication domain and replica id starting before, at or after the provided CSN, depending on the provided matching and positioning strategies.

      When the cursor is not used anymore, client code MUST call the DBCursor.close() method to free the resources and locks used by the cursor.

      Parameters:
      replica - the domain replicaId of the replicaDB
      startCSN - Starting point for the ReplicaDB cursor. If the CSN is null, then start from the oldest CSN for this replicaDB
      options - The cursor options
      Returns:
      a non null DBCursor
      Throws:
      ChangelogException - If a database problem happened
    • unregisterCursor

      void unregisterCursor(DBCursor<?> cursor)
      Unregisters the provided cursor from this replication domain.
      Parameters:
      cursor - the cursor to unregister.
    • publishUpdateMsg

      boolean publishUpdateMsg(Dn baseDN, UpdateMsg updateMsg) throws ChangelogException
      Publishes the provided change to the changelog DB for the specified replica id and replication domain. After a change has been successfully published, it becomes available to be returned by the External ChangeLog.
      Parameters:
      baseDN - the replication domain baseDN
      updateMsg - the update message to publish to the replicaDB
      Returns:
      true if a db had to be created to publish this message
      Throws:
      ChangelogException - If a database problem happened
    • replicaHeartbeat

      void replicaHeartbeat(Dn baseDN, CSN heartbeatCSN) throws ChangelogException
      Let the DB know this replica is alive.

      This method allows the medium consistency point to move forward in case this replica did not publish new changes.

      Parameters:
      baseDN - the replication domain baseDN
      heartbeatCSN - The CSN heartbeat sent by this replica (contains the replica id and timestamp of the heartbeat)
      Throws:
      ChangelogException - If a database problem happened
    • getRemovedReplicasCsns

      RemovedReplicasStates getRemovedReplicasCsns(Dn baseDn)
      Returns the latest known CSNs for removed replicas.

      A removed replica needs to remember both the CSN of the last sent message, which can be a ReplicaOffline or an LDAPUpdateMsg depending on the version it was running, and the last LDAPUpdateMsg message to support old servers talking to it.

      Parameters:
      baseDn - the baseDn of the replicated domain
      Returns:
      the latest known CSN for removed replicas
    • getReplicaDbDescription

      Returns a textual description of the contents of the changelog of the provided replica and domain.
      Parameters:
      replica - the DomainReplicaId to describe
      Returns:
      a textual description of the contents of the changelog of the provided replica and domain.
      Throws:
      ChangelogException - if an error occurs while accessing the changelog
    • hasReplicaDb

      boolean hasReplicaDb(DomainReplicaId replica)
      Returns true if a changelog already exists for the replica in the domain.
      Parameters:
      replica - the DomainReplicaId to describe
      Returns:
      true if a changelog already exists for the replica in the domain