001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2013-2016 ForgeRock AS.
015 */
016package org.opends.server.replication.server.changelog.api;
017
018import org.opends.server.replication.common.CSN;
019import org.forgerock.opendj.ldap.DN;
020
021/**
022 * This class stores an index of all the changes seen by this server in the form
023 * of {@link ChangeNumberIndexRecord}s. The records are sorted by a global
024 * ordering as defined in the CSN class. The index links a
025 * <code>changeNumber</code> to the corresponding CSN. The CSN then links to a
026 * corresponding change in one of the ReplicaDBs.
027 *
028 * @see <a href=
029 * "https://wikis.forgerock.org/confluence/display/OPENDJ/OpenDJ+Domain+Names"
030 * >OpenDJ Domain Names</a> for more information about the changelog.
031 * @see <a href= "http://tools.ietf.org/html/draft-good-ldap-changelog-04"
032 * >OpenDJ Domain Names</a> for more information about the changeNumber.
033 */
034public interface ChangeNumberIndexDB
035{
036
037  /**
038   * Returns the last generated change number.
039   *
040   * @return the last generated change number
041   */
042  long getLastGeneratedChangeNumber();
043
044  /**
045   * Get the oldest record stored in this DB.
046   *
047   * @return Returns the oldest {@link ChangeNumberIndexRecord} in this DB, null
048   *         when the DB is empty or closed
049   * @throws ChangelogException
050   *           if a database problem occurs.
051   */
052  ChangeNumberIndexRecord getOldestRecord() throws ChangelogException;
053
054  /**
055   * Get the newest record stored in this DB.
056   *
057   * @return Returns the newest {@link ChangeNumberIndexRecord} in this DB, null
058   *         when the DB is empty or closed
059   * @throws ChangelogException
060   *           if a database problem occurs.
061   */
062  ChangeNumberIndexRecord getNewestRecord() throws ChangelogException;
063
064  /**
065   * Add an update to the list of messages that must be saved to this DB managed
066   * by this DB and return the changeNumber associated to this record.
067   * <p>
068   * Note: this method disregards the changeNumber in the provided record.
069   *
070   * @param record
071   *          The {@link ChangeNumberIndexRecord} to add to this DB.
072   * @return the change number associated to this record on adding to this DB
073   * @throws ChangelogException
074   *           if a database problem occurs.
075   */
076  long addRecord(ChangeNumberIndexRecord record) throws ChangelogException;
077
078  /**
079   * Generate a new {@link DBCursor} that allows to browse the db managed by
080   * this object and starting at the position defined by a given changeNumber.
081   *
082   * @param startChangeNumber
083   *          The position where the iterator must start.
084   * @return a new DBCursor that allows to browse this DB managed by
085   *         this object and starting at the position defined by a given
086   *         changeNumber.
087   * @throws ChangelogException
088   *           if a database problem occurs.
089   */
090  DBCursor<ChangeNumberIndexRecord> getCursorFrom(long startChangeNumber)
091      throws ChangelogException;
092
093  /**
094   * Resets ChangeNumber index to the given number and CSN.
095   * @param newFirstCN
096   *          the new change number to appear as first change in the external changelog
097   * @param baseDN
098   *          the new record for the first change
099   * @param newFirstCSN
100   *          the CSN of the new first change
101   * @throws ChangelogException
102   *          if an error occurs during reset
103   */
104  void resetChangeNumberTo(long newFirstCN, DN baseDN, CSN newFirstCSN) throws ChangelogException;
105}