From 81236f34ad88ffcb71c8d7cdb15b82bad2e50251 Mon Sep 17 00:00:00 2001 From: Moiz Raja Date: Tue, 21 Jul 2015 17:23:19 -0700 Subject: [PATCH] CLEANUP : Fix javadoc warnings in sal-akka-raft code Change-Id: Id26cdcac3c4bc7f998483e4078cd1891d0783e8d Signed-off-by: Moiz Raja (cherry picked from commit a6db8d8fcb55e6b9a7a2102c9ec0b7e8ba752b50) --- .../cluster/raft/ClientRequestTracker.java | 9 ++- .../cluster/raft/FollowerLogInformation.java | 31 +++++----- .../cluster/raft/RaftActorContext.java | 62 ++++++++++++------- .../cluster/raft/ReplicatedLog.java | 4 +- .../cluster/raft/ReplicatedLogEntry.java | 14 ++--- .../cluster/raft/SnapshotState.java | 3 +- .../behaviors/AbstractRaftActorBehavior.java | 45 +++++--------- .../raft/behaviors/RaftActorBehavior.java | 10 ++- 8 files changed, 85 insertions(+), 93 deletions(-) diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ClientRequestTracker.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ClientRequestTracker.java index 4972b348ff..af6f1d453a 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ClientRequestTracker.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ClientRequestTracker.java @@ -12,22 +12,21 @@ import akka.actor.ActorRef; public interface ClientRequestTracker { /** - * The client actor who is waiting for a response * - * @return + * @return the client actor that should be sent a response when consensus is achieved */ ActorRef getClientActor(); /** * - * @return + * @return the identifier of the object that is to be replicated. For example a transaction identifier in the case + * of a transaction */ String getIdentifier(); /** - * The index of the log entry which needs to be replicated * - * @return + * @return the index of the log entry that is to be replicated */ long getIndex(); diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/FollowerLogInformation.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/FollowerLogInformation.java index c5524bc167..6618a97f21 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/FollowerLogInformation.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/FollowerLogInformation.java @@ -14,13 +14,15 @@ public interface FollowerLogInformation { /** * Increment the value of the nextIndex - * @return + * + * @return the new value of nextIndex */ long incrNextIndex(); /** * Decrement the value of the nextIndex - * @return + * + * @return the new value of nextIndex */ long decrNextIndex(); @@ -35,7 +37,8 @@ public interface FollowerLogInformation { /** * Increment the value of the matchIndex - * @return + * + * @return the new value of matchIndex */ long incrMatchIndex(); @@ -49,28 +52,25 @@ public interface FollowerLogInformation { boolean setMatchIndex(long matchIndex); /** - * The identifier of the follower - * This could simply be the url of the remote actor + * + * @return the identifier of the follower. This could simply be the url of the remote actor. */ String getId(); /** - * for each server, index of the next log entry - * to send to that server (initialized to leader - * last log index + 1) + * @return index of the next log entry to send to that server (initialized to leader last log index + 1) */ long getNextIndex(); /** - * for each server, index of highest log entry - * known to be replicated on server - * (initialized to 0, increases monotonically) + * @return index of highest log entry known to be replicated on server (initialized to 0, increases monotonically) */ long getMatchIndex(); /** * Checks if the follower is active by comparing the last updated with the duration - * @return boolean + * + * @return true if follower is active, false otherwise */ boolean isFollowerActive(); @@ -87,19 +87,20 @@ public interface FollowerLogInformation { /** * This will return the active time of follower, since it was last reset - * @return time in milliseconds + * + * @return time in milliseconds since the last activity from the follower */ long timeSinceLastActivity(); /** * This method checks if it is ok to replicate * - * @return true if it is ok to replicate + * @return true if it is ok to replicate, false otherwise */ boolean okToReplicate(); /** - * Returns the payload data version of the follower. + * @return the payload data version of the follower. */ short getPayloadVersion(); diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/RaftActorContext.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/RaftActorContext.java index bdb1cd93c6..175654a6c3 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/RaftActorContext.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/RaftActorContext.java @@ -26,15 +26,15 @@ import org.slf4j.Logger; public interface RaftActorContext { /** * Create a new local actor - * @param props - * @return + * @param props + * @return a reference to the newly created actor */ ActorRef actorOf(Props props); /** * Create a actor selection * @param path - * @return + * @return an actor selection for the given actor path */ ActorSelection actorSelection(String path); @@ -42,54 +42,47 @@ public interface RaftActorContext { * Get the identifier for the RaftActor. This identifier represents the * name of the actor whose common state is being shared. For example the * id could be 'inventory' + * * @return the identifier */ String getId(); /** - * A reference to the RaftActor itself. This could be used to send messages + * @return A reference to the RaftActor itself. This could be used to send messages * to the RaftActor - * @return */ ActorRef getActor(); /** - * Get the ElectionTerm information - * @return + * @return the ElectionTerm information */ ElectionTerm getTermInformation(); /** - * index of highest log entry known to be - * committed (initialized to 0, increases - * monotonically) - * @return + * @return index of highest log entry known to be committed (initialized to 0, increases monotonically) */ long getCommitIndex(); /** - * + * @param commitIndex new commit index */ void setCommitIndex(long commitIndex); /** - * index of highest log entry applied to state - * machine (initialized to 0, increases - * monotonically) - * @return + * @return index of highest log entry applied to state machine (initialized to 0, increases monotonically) */ long getLastApplied(); /** - * + * @param lastApplied the index of the last log entry that was applied to the state */ void setLastApplied(long lastApplied); /** * - * @param replicatedLog + * @param replicatedLog the replicated log of the current RaftActor */ void setReplicatedLog(ReplicatedLog replicatedLog); @@ -104,16 +97,12 @@ public interface RaftActorContext { ActorSystem getActorSystem(); /** - * Get the logger to be used for logging messages - * - * @return + * @return the logger to be used for logging messages to a log file */ Logger getLogger(); /** - * Get a mapping of peerId's to their addresses - * - * @return + * @return a mapping of peerId's to their addresses * */ Map getPeerAddresses(); @@ -130,6 +119,7 @@ public interface RaftActorContext { /** * Add to actor peers + * * @param name * @param address */ @@ -169,16 +159,40 @@ public interface RaftActorContext { */ ConfigParams getConfigParams(); + /** + * + * @return the SnapshotManager for this RaftActor + */ SnapshotManager getSnapshotManager(); + /** + * + * @return the DataPersistenceProvider for this RaftActor + */ DataPersistenceProvider getPersistenceProvider(); + /** + * + * @return true if the RaftActor has followers else false + */ boolean hasFollowers(); + /** + * + * @return the total memory used by the ReplicatedLog + */ long getTotalMemory(); + /** + * + * @param retriever a supplier of the total memory metric + */ @VisibleForTesting void setTotalMemoryRetriever(Supplier retriever); + /** + * + * @return the payload version to be used when replicating data + */ short getPayloadVersion(); } diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.java index 9e99be1184..ffa4cb1172 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.java @@ -57,7 +57,7 @@ public interface ReplicatedLog { * The persisted information would then be used during recovery to properly * reconstruct the state of the in-memory replicated log * - * @param the index of the first log entry to remove + * @param index the index of the first log entry to remove */ void removeFromAndPersist(long index); @@ -105,7 +105,7 @@ public interface ReplicatedLog { /** * - * @return + * @return the number of entries in the journal */ long size(); diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLogEntry.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLogEntry.java index 1979609736..1bced2404d 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLogEntry.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLogEntry.java @@ -15,32 +15,26 @@ import org.opendaylight.controller.cluster.raft.protobuff.client.messages.Payloa */ public interface ReplicatedLogEntry { /** - * The data stored in that entry * - * @return + * @return The payload/data to be replicated */ Payload getData(); /** - * The term stored in that entry * - * @return + * @return The term of the entry */ long getTerm(); /** - * The index of the entry * - * @return + * @return The index of the entry */ long getIndex(); /** - * The size of the entry in bytes. * - * An approximate number may be good enough. - * - * @return + * @return The size of the entry in bytes. An approximate number may be good enough. */ int size(); } diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/SnapshotState.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/SnapshotState.java index 3167596cc3..46e0c87fc2 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/SnapshotState.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/SnapshotState.java @@ -12,8 +12,7 @@ import org.opendaylight.controller.cluster.raft.behaviors.RaftActorBehavior; public interface SnapshotState { /** - * Should return true when a snapshot is being captured - * @return + * @return true when a snapshot is being captured */ boolean isCapturing(); diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/AbstractRaftActorBehavior.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/AbstractRaftActorBehavior.java index fc2f137e88..a1bc3eea65 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/AbstractRaftActorBehavior.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/AbstractRaftActorBehavior.java @@ -106,7 +106,7 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { * * @param sender The actor that sent this message * @param appendEntries The AppendEntries message - * @return + * @return a new behavior if it was changed or the current behavior */ protected abstract RaftActorBehavior handleAppendEntries(ActorRef sender, AppendEntries appendEntries); @@ -118,7 +118,7 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { * * @param sender * @param appendEntries - * @return + * @return a new behavior if it was changed or the current behavior */ protected RaftActorBehavior appendEntries(ActorRef sender, AppendEntries appendEntries) { @@ -151,7 +151,7 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { * * @param sender The actor that sent this message * @param appendEntriesReply The AppendEntriesReply message - * @return + * @return a new behavior if it was changed or the current behavior */ protected abstract RaftActorBehavior handleAppendEntriesReply(ActorRef sender, AppendEntriesReply appendEntriesReply); @@ -162,7 +162,7 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { * * @param sender * @param requestVote - * @return + * @return a new behavior if it was changed or the current behavior */ protected RaftActorBehavior requestVote(ActorRef sender, RequestVote requestVote) { @@ -221,15 +221,14 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { * * @param sender The actor that sent this message * @param requestVoteReply The RequestVoteReply message - * @return + * @return a new behavior if it was changed or the current behavior */ protected abstract RaftActorBehavior handleRequestVoteReply(ActorRef sender, RequestVoteReply requestVoteReply); /** - * Creates a random election duration * - * @return + * @return a random election duration */ protected FiniteDuration electionDuration() { long variance = new Random().nextInt(context.getConfigParams().getElectionTimeVariance()); @@ -249,7 +248,7 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { /** * schedule a new election * - * @param interval + * @param interval the duration after which we should trigger a new election */ protected void scheduleElection(FiniteDuration interval) { stopElection(); @@ -263,62 +262,52 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { } /** - * Get the current term - * @return + * @return the current term */ protected long currentTerm() { return context.getTermInformation().getCurrentTerm(); } /** - * Get the candidate for whom we voted in the current term - * @return + * @return the candidate for whom we voted in the current term */ protected String votedFor() { return context.getTermInformation().getVotedFor(); } /** - * Get the actor associated with this behavior - * @return + * @return the actor associated with this behavior */ protected ActorRef actor() { return context.getActor(); } /** - * Get the term from the last entry in the log * - * @return + * @return the term from the last entry in the log */ protected long lastTerm() { return context.getReplicatedLog().lastTerm(); } /** - * Get the index from the last entry in the log - * - * @return + * @return the index from the last entry in the log */ protected long lastIndex() { return context.getReplicatedLog().lastIndex(); } /** - * Find the client request tracker for a specific logIndex - * * @param logIndex - * @return + * @return the client request tracker for the specified logIndex */ protected ClientRequestTracker findClientRequestTracker(long logIndex) { return null; } /** - * Find the client request tracker for a specific logIndex - * * @param logIndex - * @return + * @return the client request tracker for the specified logIndex */ protected ClientRequestTracker removeClientRequestTracker(long logIndex) { return null; @@ -326,9 +315,8 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { /** - * Find the log index from the previous to last entry in the log * - * @return + * @return log index from the previous to last entry in the log */ protected long prevLogIndex(long index){ ReplicatedLogEntry prevEntry = @@ -340,8 +328,7 @@ public abstract class AbstractRaftActorBehavior implements RaftActorBehavior { } /** - * Find the log term from the previous to last entry in the log - * @return + * @return log term from the previous to last entry in the log */ protected long prevLogTerm(long index){ ReplicatedLogEntry prevEntry = diff --git a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/RaftActorBehavior.java b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/RaftActorBehavior.java index a4f7a42640..d04dec030b 100644 --- a/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/RaftActorBehavior.java +++ b/opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/RaftActorBehavior.java @@ -39,15 +39,14 @@ public interface RaftActorBehavior extends AutoCloseable{ RaftActorBehavior handleMessage(ActorRef sender, Object message); /** - * The state associated with a given behavior * - * @return + * @return The state associated with a given behavior */ RaftState state(); /** * - * @return + * @return The Id of the Leader if known else null */ String getLeaderId(); @@ -58,13 +57,12 @@ public interface RaftActorBehavior extends AutoCloseable{ void setReplicatedToAllIndex(long replicatedToAllIndex); /** - * getting the index of the log entry which is replicated to all nodes - * @return + * @return the index of the log entry which is replicated to all nodes */ long getReplicatedToAllIndex(); /** - * Returns the leader's payload data version. + * @return the leader's payload data version. */ short getLeaderPayloadVersion(); } -- 2.36.6