CLEANUP : Fix javadoc warnings in sal-akka-raft code 53/24453/1
authorMoiz Raja <moraja@cisco.com>
Wed, 22 Jul 2015 00:23:19 +0000 (17:23 -0700)
committerTom Pantelis <tpanteli@brocade.com>
Thu, 23 Jul 2015 02:02:08 +0000 (02:02 +0000)
Change-Id: Id26cdcac3c4bc7f998483e4078cd1891d0783e8d
Signed-off-by: Moiz Raja <moraja@cisco.com>
(cherry picked from commit a6db8d8fcb55e6b9a7a2102c9ec0b7e8ba752b50)

opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ClientRequestTracker.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/FollowerLogInformation.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/RaftActorContext.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLog.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/ReplicatedLogEntry.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/SnapshotState.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/AbstractRaftActorBehavior.java
opendaylight/md-sal/sal-akka-raft/src/main/java/org/opendaylight/controller/cluster/raft/behaviors/RaftActorBehavior.java

index 4972b34..af6f1d4 100644 (file)
@@ -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();
 
index c5524bc..6618a97 100644 (file)
@@ -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();
 
index bdb1cd9..175654a 100644 (file)
@@ -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<String, String> 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<Long> retriever);
 
+    /**
+     *
+     * @return the payload version to be used when replicating data
+     */
     short getPayloadVersion();
 }
index 9e99be1..ffa4cb1 100644 (file)
@@ -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();
 
index 1979609..1bced24 100644 (file)
@@ -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();
 }
index 3167596..46e0c87 100644 (file)
@@ -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();
 
index fc2f137..a1bc3ee 100644 (file)
@@ -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 =
index a4f7a42..d04dec0 100644 (file)
@@ -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();
 }