Package org.opends.server.replication.server.changelog.api

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 Detail

      • 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

        MultiDomainDBCursor getCursorFrom​(MultiDomainServerState startState,
                                  DBCursor.CursorOptions options)
                           throws ChangelogException
        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(Dn, ServerState, CursorOptions)

      • 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:
        getCursorFrom(Dn, ServerState, CursorOptions)

      • 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(DomainReplicaId, CSN, CursorOptions)

      • 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