2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
8 package org.opendaylight.controller.cluster.raft;
10 import java.util.List;
11 import java.util.function.Consumer;
12 import org.eclipse.jdt.annotation.NonNull;
13 import org.eclipse.jdt.annotation.Nullable;
16 * Represents the ReplicatedLog that needs to be kept in sync by the RaftActor.
18 public interface ReplicatedLog {
19 long NO_MAX_SIZE = -1;
22 * Return the replicated log entry at the specified index.
24 * @param index the index of the log entry
25 * @return the ReplicatedLogEntry if found, otherwise null if the adjusted index less than 0 or
26 * greater than the size of the in-memory journal
28 @Nullable ReplicatedLogEntry get(long index);
31 * Return the last replicated log entry in the log or null of not found.
33 * @return the last replicated log entry in the log or null of not found.
35 @Nullable ReplicatedLogEntry last();
38 * Return the index of the last entry in the log or -1 if the log is empty.
40 * @return the index of the last entry in the log or -1 if the log is empty.
45 * Return the term of the last entry in the log or -1 if the log is empty.
47 * @return the term of the last entry in the log or -1 if the log is empty.
52 * Removes entries from the in-memory log starting at the given index.
54 * @param index the index of the first log entry to remove
55 * @return the adjusted index of the first log entry removed or -1 if the log entry is not found.
57 long removeFrom(long index);
60 * Removes entries from the in-memory log and the persisted log starting at the given index.
63 * The persisted information would then be used during recovery to properly
64 * reconstruct the state of the in-memory replicated log
66 * @param index the index of the first log entry to remove
67 * @return true if entries were removed, false otherwise
69 boolean removeFromAndPersist(long index);
72 * Appends an entry to the log.
74 * @param replicatedLogEntry the entry to append
75 * @return true if the entry was successfully appended, false otherwise. An entry can fail to append if
76 * the index is already included in the log.
78 boolean append(ReplicatedLogEntry replicatedLogEntry);
81 * Optimization method to increase the capacity of the journal log prior to appending entries.
83 * @param amount the amount to increase by
85 void increaseJournalLogCapacity(int amount);
88 * Appends an entry to the in-memory log and persists it as well.
90 * @param replicatedLogEntry the entry to append
91 * @param callback the callback to be notified when persistence is complete (optional).
92 * @param doAsync if true, the persistent actor can receive subsequent messages to process in between the persist
93 * call and the execution of the associated callback. If false, subsequent messages are stashed and get
94 * delivered after persistence is complete and the associated callback is executed. In either case the
95 * callback is guaranteed to execute in the context of the actor associated with this log.
96 * @return true if the entry was successfully appended, false otherwise.
98 boolean appendAndPersist(@NonNull ReplicatedLogEntry replicatedLogEntry,
99 @Nullable Consumer<ReplicatedLogEntry> callback, boolean doAsync);
102 * Returns a list of log entries starting from the given index to the end of the log.
104 * @param index the index of the first log entry to get.
105 * @return the List of entries
107 @NonNull List<ReplicatedLogEntry> getFrom(long index);
110 * Returns a list of log entries starting from the given index up to the given maximum of entries or
111 * the given maximum accumulated size, whichever comes first.
113 * @param index the index of the first log entry to get
114 * @param maxEntries the maximum number of entries to get
115 * @param maxDataSize the maximum accumulated size of the log entries to get
116 * @return the List of entries meeting the criteria.
118 @NonNull List<ReplicatedLogEntry> getFrom(long index, int maxEntries, long maxDataSize);
121 * Returns the number of entries in the journal.
123 * @return the number of entries
128 * Checks if the entry at the specified index is present or not.
130 * @param index the index of the log entry
131 * @return true if the entry is present in the in-memory journal
133 boolean isPresent(long index);
136 * Checks if the entry is present in a snapshot.
138 * @param index the index of the log entry
139 * @return true if the entry is in the snapshot. false if the entry is not in the snapshot even if the entry may
140 * be present in the replicated log
142 boolean isInSnapshot(long index);
145 * Returns the index of the snapshot.
147 * @return the index from which the snapshot was created. -1 otherwise.
149 long getSnapshotIndex();
152 * Returns the term of the snapshot.
154 * @return the term of the index from which the snapshot was created. -1 otherwise
156 long getSnapshotTerm();
159 * Sets the snapshot index in the replicated log.
161 * @param snapshotIndex the index to set
163 void setSnapshotIndex(long snapshotIndex);
166 * Sets snapshot term.
168 * @param snapshotTerm the term to set
170 void setSnapshotTerm(long snapshotTerm);
173 * Clears the journal entries with startIndex (inclusive) and endIndex (exclusive).
175 * @param startIndex the start index (inclusive)
176 * @param endIndex the end index (exclusive)
178 void clear(int startIndex, int endIndex);
181 * Handles all the bookkeeping in order to perform a rollback in the event of SaveSnapshotFailure.
183 * @param snapshotCapturedIndex the new snapshot index
184 * @param snapshotCapturedTerm the new snapshot term
186 void snapshotPreCommit(long snapshotCapturedIndex, long snapshotCapturedTerm);
189 * Sets the Replicated log to state after snapshot success.
191 void snapshotCommit();
194 * Restores the replicated log to a state in the event of a save snapshot failure.
196 void snapshotRollback();
199 * Returns the size of the data in the log (in bytes).
201 * @return the size of the data in the log (in bytes)
206 * Determines if a snapshot needs to be captured based on the count/memory consumed and initiates the capture.
208 * @param replicatedLogEntry the last log entry.
210 void captureSnapshotIfReady(ReplicatedLogEntry replicatedLogEntry);
213 * Determines if a snapshot should be captured based on the count/memory consumed.
215 * @param logIndex the log index to use to determine if the log count has exceeded the threshold
216 * @return true if a snapshot should be captured, false otherwise
218 boolean shouldCaptureSnapshot(long logIndex);