From e3a04b6c413143e02af919a1eca7d99f0cb4b99f Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 14:04:41 +0100 Subject: [PATCH 1/2] Fix javadoc in org.eclipse.jgit ketch package Change-Id: I72be0a0d5ac7d3e957597803bd103dbbec141ba4 --- .../jgit/internal/ketch/KetchConstants.java | 4 +- .../jgit/internal/ketch/KetchLeader.java | 76 +++++++++++------- .../jgit/internal/ketch/KetchLeaderCache.java | 2 +- .../jgit/internal/ketch/KetchPreReceive.java | 11 ++- .../jgit/internal/ketch/KetchReplica.java | 78 ++++++++++++++----- .../jgit/internal/ketch/KetchSystem.java | 61 ++++++++++++--- .../jgit/internal/ketch/KetchText.java | 10 ++- .../eclipse/jgit/internal/ketch/LagCheck.java | 1 + .../jgit/internal/ketch/LeaderSnapshot.java | 30 ++++++- .../jgit/internal/ketch/LocalReplica.java | 8 +- .../eclipse/jgit/internal/ketch/LogIndex.java | 31 +++++--- .../eclipse/jgit/internal/ketch/Proposal.java | 63 +++++++++++---- .../jgit/internal/ketch/RemoteGitReplica.java | 18 ++++- .../jgit/internal/ketch/ReplicaConfig.java | 22 +++++- .../internal/ketch/ReplicaFetchRequest.java | 24 +++++- .../internal/ketch/ReplicaPushRequest.java | 24 ++++-- .../jgit/internal/ketch/ReplicaSnapshot.java | 34 ++++++-- .../jgit/internal/ketch/StageBuilder.java | 13 ++-- 18 files changed, 380 insertions(+), 130 deletions(-) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java index 171c059db..168ab8c26 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.internal.ketch; import org.eclipse.jgit.revwalk.FooterKey; -/** Frequently used constants in a Ketch system. */ +/** + * Frequently used constants in a Ketch system. + */ public class KetchConstants { /** * Default reference namespace holding {@link #ACCEPTED} and diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java index 3bcd6bcb2..bc5ba3926 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java @@ -69,11 +69,15 @@ import org.slf4j.LoggerFactory; /** * A leader managing consensus across remote followers. *

- * A leader instance starts up in {@link State#CANDIDATE} and tries to begin a - * new term by sending an {@link ElectionRound} to all replicas. Its term starts - * if a majority of replicas have accepted this leader instance for the term. + * A leader instance starts up in + * {@link org.eclipse.jgit.internal.ketch.KetchLeader.State#CANDIDATE} and tries + * to begin a new term by sending an + * {@link org.eclipse.jgit.internal.ketch.ElectionRound} to all replicas. Its + * term starts if a majority of replicas have accepted this leader instance for + * the term. *

- * Once elected by a majority the instance enters {@link State#LEADER} and runs + * Once elected by a majority the instance enters + * {@link org.eclipse.jgit.internal.ketch.KetchLeader.State#LEADER} and runs * proposals offered to {@link #queueProposal(Proposal)}. This continues until * the leader is timed out for inactivity, or is deposed by a competing leader * gaining its own majority. @@ -81,36 +85,42 @@ import org.slf4j.LoggerFactory; * Once timed out or deposed this {@code KetchLeader} instance should be * discarded, and a new instance takes over. *

- * Each leader instance coordinates a group of {@link KetchReplica}s. Replica - * instances are owned by the leader instance and must be discarded when the - * leader is discarded. + * Each leader instance coordinates a group of + * {@link org.eclipse.jgit.internal.ketch.KetchReplica}s. Replica instances are + * owned by the leader instance and must be discarded when the leader is + * discarded. *

* In Ketch all push requests are issued through the leader. The steps are as - * follows (see {@link KetchPreReceive} for an example): + * follows (see {@link org.eclipse.jgit.internal.ketch.KetchPreReceive} for an + * example): *

*

* The leader gains consensus by first pushing the needed objects and a - * {@link RefTree} representing the desired target repository state to the - * {@code refs/txn/accepted} branch on each of the replicas. Once a majority has - * succeeded, the leader commits the state by either pushing the - * {@code refs/txn/accepted} value to {@code refs/txn/committed} (for - * Ketch-aware replicas) or by pushing updates to {@code refs/heads/master}, - * etc. for stock Git replicas. + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree} representing the + * desired target repository state to the {@code refs/txn/accepted} branch on + * each of the replicas. Once a majority has succeeded, the leader commits the + * state by either pushing the {@code refs/txn/accepted} value to + * {@code refs/txn/committed} (for Ketch-aware replicas) or by pushing updates + * to {@code refs/heads/master}, etc. for stock Git replicas. *

* Internally, the actual transport to replicas is performed on background - * threads via the {@link KetchSystem}'s executor service. For performance, the - * {@link KetchLeader}, {@link KetchReplica} and {@link Proposal} objects share - * some state, and may invoke each other's methods on different threads. This - * access is protected by the leader's {@link #lock} object. Care must be taken - * to prevent concurrent access by correctly obtaining the leader's lock. + * threads via the {@link org.eclipse.jgit.internal.ketch.KetchSystem}'s + * executor service. For performance, the + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}, + * {@link org.eclipse.jgit.internal.ketch.KetchReplica} and + * {@link org.eclipse.jgit.internal.ketch.Proposal} objects share some state, + * and may invoke each other's methods on different threads. This access is + * protected by the leader's {@link #lock} object. Care must be taken to prevent + * concurrent access by correctly obtaining the leader's lock. */ public abstract class KetchLeader { private static final Logger log = LoggerFactory.getLogger(KetchLeader.class); @@ -295,7 +305,7 @@ public abstract class KetchLeader { * The caller will close the repository. * * @return opened repository for use by the leader thread. - * @throws IOException + * @throws java.io.IOException * cannot reopen the repository for the leader. */ protected abstract Repository openRepository() throws IOException; @@ -307,16 +317,17 @@ public abstract class KetchLeader { * checked to look for risks of conflicts, and then submitted into the queue * for distribution as soon as possible. *

- * Callers must use {@link Proposal#await()} to see if the proposal is done. + * Callers must use {@link org.eclipse.jgit.internal.ketch.Proposal#await()} + * to see if the proposal is done. * * @param proposal * the proposed reference updates to queue for consideration. * Once execution is complete the individual reference result * fields will be populated with the outcome. - * @throws InterruptedException + * @throws java.lang.InterruptedException * current thread was interrupted. The proposal may have been * aborted if it was not yet queued for execution. - * @throws IOException + * @throws java.io.IOException * unrecoverable error preventing proposals from being attempted * by this leader. */ @@ -577,7 +588,11 @@ public abstract class KetchLeader { } } - /** @return snapshot this leader. */ + /** + * Snapshot this leader + * + * @return snapshot of this leader + */ public LeaderSnapshot snapshot() { lock.lock(); try { @@ -599,7 +614,9 @@ public abstract class KetchLeader { } } - /** Gracefully shutdown this leader and cancel outstanding operations. */ + /** + * Gracefully shutdown this leader and cancel outstanding operations. + */ public void shutdown() { lock.lock(); try { @@ -617,6 +634,7 @@ public abstract class KetchLeader { } } + /** {@inheritDoc} */ @Override public String toString() { return snapshot().toString(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java index ba033c1a4..de0da4f32 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java @@ -82,7 +82,7 @@ public class KetchLeaderCache { * @param repo * repository to get the leader for. * @return the leader instance for the repository. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * remote configuration contains an invalid URL. */ public KetchLeader get(Repository repo) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java index 1b4307f3f..53d286539 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java @@ -64,9 +64,10 @@ import org.slf4j.LoggerFactory; /** * PreReceiveHook for handling push traffic in a Ketch system. *

- * Install an instance on {@link ReceivePack} to capture the commands and other - * connection state and relay them through the {@link KetchLeader}, allowing the - * leader to gain consensus about the new reference state. + * Install an instance on {@link org.eclipse.jgit.transport.ReceivePack} to + * capture the commands and other connection state and relay them through the + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}, allowing the leader to + * gain consensus about the new reference state. */ public class KetchPreReceive implements PreReceiveHook { private static final Logger log = LoggerFactory.getLogger(KetchPreReceive.class); @@ -74,7 +75,8 @@ public class KetchPreReceive implements PreReceiveHook { private final KetchLeader leader; /** - * Construct a hook executing updates through a {@link KetchLeader}. + * Construct a hook executing updates through a + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}. * * @param leader * leader for this repository. @@ -83,6 +85,7 @@ public class KetchPreReceive implements PreReceiveHook { this.leader = leader; } + /** {@inheritDoc} */ @Override public void onPreReceive(ReceivePack rp, Collection cmds) { cmds = ReceiveCommand.filter(cmds, NOT_ATTEMPTED); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java index a30bbb260..a0176d7d2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java @@ -82,26 +82,32 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * A Ketch replica, either {@link LocalReplica} or {@link RemoteGitReplica}. + * A Ketch replica, either {@link org.eclipse.jgit.internal.ketch.LocalReplica} + * or {@link org.eclipse.jgit.internal.ketch.RemoteGitReplica}. *

* Replicas can be either a stock Git replica, or a Ketch-aware replica. *

* A stock Git replica has no special knowledge of Ketch and simply stores * objects and references. Ketch communicates with the stock Git replica using - * the Git push wire protocol. The {@link KetchLeader} commits an agreed upon + * the Git push wire protocol. The + * {@link org.eclipse.jgit.internal.ketch.KetchLeader} commits an agreed upon * state by pushing all references to the Git replica, for example * {@code "refs/heads/master"} is pushed during commit. Stock Git replicas use - * {@link CommitMethod#ALL_REFS} to record the final state. + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.CommitMethod#ALL_REFS} to + * record the final state. *

* Ketch-aware replicas understand the {@code RefTree} sent during the proposal * and during commit are able to update their own reference space to match the * state represented by the {@code RefTree}. Ketch-aware replicas typically use * a {@link org.eclipse.jgit.internal.storage.reftree.RefTreeDatabase} and - * {@link CommitMethod#TXN_COMMITTED} to record the final state. + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.CommitMethod#TXN_COMMITTED} + * to record the final state. *

- * KetchReplica instances are tightly coupled with a single {@link KetchLeader}. - * Some state may be accessed by the leader thread and uses the leader's own - * {@link KetchLeader#lock} to protect shared data. + * KetchReplica instances are tightly coupled with a single + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}. Some state may be + * accessed by the leader thread and uses the leader's own + * {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock} to protect shared + * data. */ public abstract class KetchReplica { static final Logger log = LoggerFactory.getLogger(KetchReplica.class); @@ -223,37 +229,65 @@ public abstract class KetchReplica { this.queued = new ArrayList<>(4); } - /** @return system configuration. */ + /** + * Get system configuration. + * + * @return system configuration. + */ public KetchSystem getSystem() { return getLeader().getSystem(); } - /** @return leader instance this replica follows. */ + /** + * Get leader instance this replica follows. + * + * @return leader instance this replica follows. + */ public KetchLeader getLeader() { return leader; } - /** @return unique-ish name for debugging. */ + /** + * Get unique-ish name for debugging. + * + * @return unique-ish name for debugging. + */ public String getName() { return replicaName; } - /** @return description of this replica for error/debug logging purposes. */ + /** + * Get description of this replica for error/debug logging purposes. + * + * @return description of this replica for error/debug logging purposes. + */ protected String describeForLog() { return getName(); } - /** @return how the replica participates in this Ketch system. */ + /** + * Get how the replica participates in this Ketch system. + * + * @return how the replica participates in this Ketch system. + */ public Participation getParticipation() { return participation; } - /** @return how Ketch will commit to the repository. */ + /** + * Get how Ketch will commit to the repository. + * + * @return how Ketch will commit to the repository. + */ public CommitMethod getCommitMethod() { return commitMethod; } - /** @return when Ketch will commit to the repository. */ + /** + * Get when Ketch will commit to the repository. + * + * @return when Ketch will commit to the repository. + */ public CommitSpeed getCommitSpeed() { return commitSpeed; } @@ -264,7 +298,8 @@ public abstract class KetchReplica { * Default implementation cancels any scheduled retry. Subclasses may add * additional logic before or after calling {@code super.shutdown()}. *

- * Called with {@link KetchLeader#lock} held by caller. + * Called with {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock} held + * by caller. */ protected void shutdown() { Future f = retryFuture; @@ -541,8 +576,8 @@ public abstract class KetchReplica { /** * Begin executing a single push. *

- * This method must move processing onto another thread. - * Called with {@link KetchLeader#lock} held by caller. + * This method must move processing onto another thread. Called with + * {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock} held by caller. * * @param req * the request to send to the replica. @@ -666,20 +701,21 @@ public abstract class KetchReplica { /** * Fetch objects from the remote using the calling thread. *

- * Called without {@link KetchLeader#lock}. + * Called without {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock}. * * @param repo * local repository to fetch objects into. * @param req * the request to fetch from a replica. - * @throws IOException + * @throws java.io.IOException * communication with the replica was not possible. */ protected abstract void blockingFetch(Repository repo, ReplicaFetchRequest req) throws IOException; /** - * Build a list of commands to commit {@link CommitMethod#ALL_REFS}. + * Build a list of commands to commit + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.CommitMethod#ALL_REFS}. * * @param git * local leader repository to read committed state from. @@ -689,7 +725,7 @@ public abstract class KetchReplica { * @param committed * state being pushed to {@code refs/txn/committed}. * @return commands to update during commit. - * @throws IOException + * @throws java.io.IOException * cannot read the committed state. */ protected Collection prepareCommit(Repository git, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java index 33f526e52..1908d6c98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java @@ -81,12 +81,17 @@ import org.slf4j.LoggerFactory; * Full scale installations are expected to subclass and override methods to * provide consistent configuration across all managed repositories. *

- * Servers should configure their own {@link ScheduledExecutorService}. + * Servers should configure their own + * {@link java.util.concurrent.ScheduledExecutorService}. */ public class KetchSystem { private static final Random RNG = new Random(); - /** @return default executor, one thread per available processor. */ + /** + * Get default executor, one thread per available processor. + * + * @return default executor, one thread per available processor. + */ public static ScheduledExecutorService defaultExecutor() { return DefaultExecutorHolder.I; } @@ -98,7 +103,9 @@ public class KetchSystem { private final String txnCommitted; private final String txnStage; - /** Create a default system with a thread pool of 1 thread per CPU. */ + /** + * Create a default system with a thread pool of 1 thread per CPU. + */ public KetchSystem() { this(defaultExecutor(), new MonotonicSystemClock(), DEFAULT_TXN_NAMESPACE); } @@ -125,17 +132,29 @@ public class KetchSystem { this.txnStage = txnNamespace + STAGE; } - /** @return executor to perform background operations. */ + /** + * Get executor to perform background operations. + * + * @return executor to perform background operations. + */ public ScheduledExecutorService getExecutor() { return executor; } - /** @return clock to obtain timestamps from. */ + /** + * Get clock to obtain timestamps from. + * + * @return clock to obtain timestamps from. + */ public MonotonicClock getClock() { return clock; } /** + * Get how long the leader will wait for the {@link #getClock()}'s + * {@code ProposedTimestamp} used in commits proposed to the RefTree graph + * ({@link #getTxnAccepted()}) + * * @return how long the leader will wait for the {@link #getClock()}'s * {@code ProposedTimestamp} used in commits proposed to the RefTree * graph ({@link #getTxnAccepted()}). Defaults to 5 seconds. @@ -145,8 +164,12 @@ public class KetchSystem { } /** - * @return true if elections should require monotonically increasing commit - * timestamps. This requires a very good {@link MonotonicClock}. + * Whether elections should require monotonically increasing commit + * timestamps + * + * @return {@code true} if elections should require monotonically increasing + * commit timestamps. This requires a very good + * {@link org.eclipse.jgit.util.time.MonotonicClock}. */ public boolean requireMonotonicLeaderElections() { return false; @@ -161,22 +184,36 @@ public class KetchSystem { return txnNamespace; } - /** @return name of the accepted RefTree graph. */ + /** + * Get name of the accepted RefTree graph. + * + * @return name of the accepted RefTree graph. + */ public String getTxnAccepted() { return txnAccepted; } - /** @return name of the committed RefTree graph. */ + /** + * Get name of the committed RefTree graph. + * + * @return name of the committed RefTree graph. + */ public String getTxnCommitted() { return txnCommitted; } - /** @return prefix for staged objects, e.g. {@code "refs/txn/stage/"}. */ + /** + * Get prefix for staged objects, e.g. {@code "refs/txn/stage/"}. + * + * @return prefix for staged objects, e.g. {@code "refs/txn/stage/"}. + */ public String getTxnStage() { return txnStage; } /** + * Create new committer {@code PersonIdent} for ketch system + * * @param time * timestamp for the committer. * @return identity line for the committer header of a RefTreeGraph. @@ -220,7 +257,7 @@ public class KetchSystem { * @param repo * local repository stored by the leader. * @return leader instance. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * a follower configuration contains an unsupported URI. */ public KetchLeader createLeader(final Repository repo) @@ -246,7 +283,7 @@ public class KetchSystem { * @param repo * repository to get the replicas of. * @return collection of replicas for the specified repository. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * a configured URI is invalid. */ protected List createReplicas(KetchLeader leader, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java index b6c3bc92c..fa34a88cf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java @@ -46,9 +46,15 @@ package org.eclipse.jgit.internal.ketch; import org.eclipse.jgit.nls.NLS; import org.eclipse.jgit.nls.TranslationBundle; -/** Translation bundle for the Ketch implementation. */ +/** + * Translation bundle for the Ketch implementation. + */ public class KetchText extends TranslationBundle { - /** @return instance of this translation bundle. */ + /** + * Get an instance of this translation bundle. + * + * @return instance of this translation bundle. + */ public static KetchText get() { return NLS.getBundleFor(KetchText.class); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java index 757c19ac9..c09d872f0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java @@ -86,6 +86,7 @@ class LagCheck implements AutoCloseable { rw.setRetainBody(false); } + /** {@inheritDoc} */ @Override public void close() { if (rw != null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java index 28a49df97..4c8bd0600 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java @@ -53,7 +53,9 @@ import java.util.List; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.lib.ObjectId; -/** A snapshot of a leader and its view of the world. */ +/** + * A snapshot of a leader and its view of the world. + */ public class LeaderSnapshot { final List replicas = new ArrayList<>(); KetchLeader.State state; @@ -65,17 +67,28 @@ public class LeaderSnapshot { LeaderSnapshot() { } - /** @return unmodifiable view of configured replicas. */ + /** + * Get unmodifiable view of configured replicas. + * + * @return unmodifiable view of configured replicas. + */ public Collection getReplicas() { return Collections.unmodifiableList(replicas); } - /** @return current state of the leader. */ + /** + * Get current state of the leader. + * + * @return current state of the leader. + */ public KetchLeader.State getState() { return state; } /** + * Whether the leader is not running a round to reach consensus, and has no + * rounds queued. + * * @return {@code true} if the leader is not running a round to reach * consensus, and has no rounds queued. */ @@ -84,14 +97,19 @@ public class LeaderSnapshot { } /** + * Get term of this leader + * * @return term of this leader. Valid only if {@link #getState()} is - * currently {@link KetchLeader.State#LEADER}. + * currently + * {@link org.eclipse.jgit.internal.ketch.KetchLeader.State#LEADER}. */ public long getTerm() { return term; } /** + * Get end of the leader's log + * * @return end of the leader's log; null if leader hasn't started up enough * to begin its own election. */ @@ -101,6 +119,9 @@ public class LeaderSnapshot { } /** + * Get state the leader knows is committed on a majority of participant + * replicas + * * @return state the leader knows is committed on a majority of participant * replicas. Null until the leader instance has committed a log * index within its own term. @@ -110,6 +131,7 @@ public class LeaderSnapshot { return committedIndex; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java index 907eecbef..9c37a90ce 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java @@ -67,7 +67,10 @@ import org.eclipse.jgit.transport.ReceiveCommand; import org.eclipse.jgit.util.time.MonotonicClock; import org.eclipse.jgit.util.time.ProposedTimestamp; -/** Ketch replica running on the same system as the {@link KetchLeader}. */ +/** + * Ketch replica running on the same system as the + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}. + */ public class LocalReplica extends KetchReplica { /** * Configure a local replica. @@ -83,6 +86,7 @@ public class LocalReplica extends KetchReplica { super(leader, name, cfg); } + /** {@inheritDoc} */ @Override protected String describeForLog() { return String.format("%s (leader)", getName()); //$NON-NLS-1$ @@ -116,6 +120,7 @@ public class LocalReplica extends KetchReplica { getSystem().getTxnCommitted())); } + /** {@inheritDoc} */ @Override protected void startPush(final ReplicaPushRequest req) { getSystem().getExecutor().execute(new Runnable() { @@ -137,6 +142,7 @@ public class LocalReplica extends KetchReplica { }); } + /** {@inheritDoc} */ @Override protected void blockingFetch(Repository repo, ReplicaFetchRequest req) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java index 350c8ed62..eb600bb41 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java @@ -54,17 +54,18 @@ import org.eclipse.jgit.lib.ObjectId; * LogIndex provides a performance optimization for Ketch, the same information * can be obtained from {@link org.eclipse.jgit.revwalk.RevWalk}. *

- * Index values are only valid within a single {@link KetchLeader} instance - * after it has won an election. By restricting scope to a single leader new - * leaders do not need to traverse the entire history to determine the next - * {@code index} for new proposals. This differs from Raft, where leader - * election uses the log index and the term number to determine which replica - * holds a sufficiently up-to-date log. Since Ketch uses Git objects for storage - * of its replicated log, it keeps the term number as Raft does but uses - * standard Git operations to imply the log index. + * Index values are only valid within a single + * {@link org.eclipse.jgit.internal.ketch.KetchLeader} instance after it has won + * an election. By restricting scope to a single leader new leaders do not need + * to traverse the entire history to determine the next {@code index} for new + * proposals. This differs from Raft, where leader election uses the log index + * and the term number to determine which replica holds a sufficiently + * up-to-date log. Since Ketch uses Git objects for storage of its replicated + * log, it keeps the term number as Raft does but uses standard Git operations + * to imply the log index. *

- * {@link Round#runAsync(AnyObjectId)} bumps the index as each new round is - * constructed. + * {@link org.eclipse.jgit.internal.ketch.Round#runAsync(AnyObjectId)} bumps the + * index as each new round is constructed. */ public class LogIndex extends ObjectId { static LogIndex unknown(AnyObjectId id) { @@ -82,7 +83,11 @@ public class LogIndex extends ObjectId { return new LogIndex(id, index + 1); } - /** @return index provided by the current leader instance. */ + /** + * Get index provided by the current leader instance. + * + * @return index provided by the current leader instance. + */ public long getIndex() { return index; } @@ -103,6 +108,9 @@ public class LogIndex extends ObjectId { } /** + * Create string suitable for debug logging containing the log index and + * abbreviated ObjectId. + * * @return string suitable for debug logging containing the log index and * abbreviated ObjectId. */ @@ -111,6 +119,7 @@ public class LogIndex extends ObjectId { return String.format("%5d/%s", index, abbreviate(6).name()); //$NON-NLS-1$ } + /** {@inheritDoc} */ @SuppressWarnings("boxing") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java index 12d3f4c9c..db2ad2301 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java @@ -78,10 +78,11 @@ import org.eclipse.jgit.util.time.ProposedTimestamp; * area under the {@code refs/txn/stage/} namespace. If the proposal succeeds * then the changes are durable and the leader can commit the proposal. *

- * Proposals are executed by {@link KetchLeader#queueProposal(Proposal)}, which - * runs them asynchronously in the background. Proposals are thread-safe futures - * allowing callers to {@link #await()} for results or be notified by callback - * using {@link #addListener(Runnable)}. + * Proposals are executed by + * {@link org.eclipse.jgit.internal.ketch.KetchLeader#queueProposal(Proposal)}, + * which runs them asynchronously in the background. Proposals are thread-safe + * futures allowing callers to {@link #await()} for results or be notified by + * callback using {@link #addListener(Runnable)}. */ public class Proposal { /** Current state of the proposal. */ @@ -146,9 +147,9 @@ public class Proposal { * walker to assist in preparing commands. * @param cmds * list of pending commands. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * newId of a command is not found locally. - * @throws IOException + * @throws java.io.IOException * local objects cannot be accessed. */ public Proposal(RevWalk rw, Collection cmds) @@ -166,12 +167,20 @@ public class Proposal { return Collections.unmodifiableList(commands); } - /** @return commands from this proposal. */ + /** + * Get commands from this proposal. + * + * @return commands from this proposal. + */ public Collection getCommands() { return commands; } - /** @return optional author of the proposal. */ + /** + * Get optional author of the proposal. + * + * @return optional author of the proposal. + */ @Nullable public PersonIdent getAuthor() { return author; @@ -189,7 +198,11 @@ public class Proposal { return this; } - /** @return optional message for the commit log of the RefTree. */ + /** + * Get optional message for the commit log of the RefTree. + * + * @return optional message for the commit log of the RefTree. + */ @Nullable public String getMessage() { return message; @@ -207,7 +220,11 @@ public class Proposal { return this; } - /** @return optional certificate signing the references. */ + /** + * Get optional certificate signing the references. + * + * @return optional certificate signing the references. + */ @Nullable public PushCertificate getPushCertificate() { return pushCert; @@ -226,6 +243,8 @@ public class Proposal { } /** + * Get timestamps that Ketch must block for. + * * @return timestamps that Ketch must block for. These may have been used as * commit times inside the objects involved in the proposal. */ @@ -240,6 +259,7 @@ public class Proposal { * Request the proposal to wait for the affected timestamps to resolve. * * @param ts + * a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. * @return {@code this}. */ public Proposal addProposedTimestamp(ProposedTimestamp ts) { @@ -253,9 +273,11 @@ public class Proposal { /** * Add a callback to be invoked when the proposal is done. *

- * A proposal is done when it has entered either {@link State#EXECUTED} or - * {@link State#ABORTED} state. If the proposal is already done - * {@code callback.run()} is immediately invoked on the caller's thread. + * A proposal is done when it has entered either + * {@link org.eclipse.jgit.internal.ketch.Proposal.State#EXECUTED} or + * {@link org.eclipse.jgit.internal.ketch.Proposal.State#ABORTED} state. If + * the proposal is already done {@code callback.run()} is immediately + * invoked on the caller's thread. * * @param callback * method to run after the proposal is done. The callback may be @@ -291,12 +313,18 @@ public class Proposal { notifyState(ABORTED); } - /** @return read the current state of the proposal. */ + /** + * Read the current state of the proposal. + * + * @return read the current state of the proposal. + */ public State getState() { return state.get(); } /** + * Whether the proposal was attempted + * * @return {@code true} if the proposal was attempted. A true value does not * mean consensus was reached, only that the proposal was considered * and will not be making any more progress beyond its current @@ -309,7 +337,7 @@ public class Proposal { /** * Wait for the proposal to be attempted and {@link #isDone()} to be true. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * caller was interrupted before proposal executed. */ public void await() throws InterruptedException { @@ -328,7 +356,7 @@ public class Proposal { * @param unit * unit describing the wait time. * @return true if the proposal is done; false if the method timed out. - * @throws InterruptedException + * @throws java.lang.InterruptedException * caller was interrupted before proposal executed. */ public boolean await(long wait, TimeUnit unit) throws InterruptedException { @@ -351,7 +379,7 @@ public class Proposal { * @param unit * unit describing the wait time. * @return true if the proposal exited the state; false on time out. - * @throws InterruptedException + * @throws java.lang.InterruptedException * caller was interrupted before proposal executed. */ public boolean awaitStateChange(State notIn, long wait, TimeUnit unit) @@ -378,6 +406,7 @@ public class Proposal { } } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java index a0ac60809..674da1fc6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java @@ -80,7 +80,8 @@ import org.eclipse.jgit.transport.URIish; /** * Representation of a Git repository on a remote replica system. *

- * {@link KetchLeader} will contact the replica using the Git wire protocol. + * {@link org.eclipse.jgit.internal.ketch.KetchLeader} will contact the replica + * using the Git wire protocol. *

* The remote replica may be fully Ketch-aware, or a standard Git server. */ @@ -110,22 +111,32 @@ public class RemoteGitReplica extends KetchReplica { this.remoteConfig = rc; } - /** @return URI to contact the remote peer repository. */ + /** + * Get URI to contact the remote peer repository. + * + * @return URI to contact the remote peer repository. + */ public URIish getURI() { return uri; } - /** @return optional configuration describing how to contact the peer. */ + /** + * Get optional configuration describing how to contact the peer. + * + * @return optional configuration describing how to contact the peer. + */ @Nullable protected RemoteConfig getRemoteConfig() { return remoteConfig; } + /** {@inheritDoc} */ @Override protected String describeForLog() { return String.format("%s @ %s", getName(), getURI()); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override protected void startPush(final ReplicaPushRequest req) { getSystem().getExecutor().execute(new Runnable() { @@ -240,6 +251,7 @@ public class RemoteGitReplica extends KetchReplica { ReceiveCommand.abort(tmp); } + /** {@inheritDoc} */ @Override protected void blockingFetch(Repository repo, ReplicaFetchRequest req) throws NotSupportedException, TransportException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java index e16e63aa7..84261f1ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java @@ -65,7 +65,9 @@ import org.eclipse.jgit.internal.ketch.KetchReplica.CommitSpeed; import org.eclipse.jgit.internal.ketch.KetchReplica.Participation; import org.eclipse.jgit.lib.Config; -/** Configures a {@link KetchReplica}. */ +/** + * Configures a {@link org.eclipse.jgit.internal.ketch.KetchReplica}. + */ public class ReplicaConfig { /** * Read a configuration from a config block. @@ -86,17 +88,29 @@ public class ReplicaConfig { private long minRetry = SECONDS.toMillis(5); private long maxRetry = MINUTES.toMillis(1); - /** @return participation of the replica in the system. */ + /** + * Get participation of the replica in the system. + * + * @return participation of the replica in the system. + */ public Participation getParticipation() { return participation; } - /** @return how Ketch should apply committed changes. */ + /** + * Get how Ketch should apply committed changes. + * + * @return how Ketch should apply committed changes. + */ public CommitMethod getCommitMethod() { return commitMethod; } - /** @return how quickly should Ketch commit. */ + /** + * Get how quickly should Ketch commit. + * + * @return how quickly should Ketch commit. + */ public CommitSpeed getCommitSpeed() { return commitSpeed; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java index 201d9e974..11c5b618d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.Ref; -/** A fetch request to obtain objects from a replica, and its result. */ +/** + * A fetch request to obtain objects from a replica, and its result. + */ public class ReplicaFetchRequest { private final Set wantRefs; private final Set wantObjects; @@ -70,23 +72,37 @@ public class ReplicaFetchRequest { this.wantObjects = wantObjects; } - /** @return references to be fetched. */ + /** + * Get references to be fetched. + * + * @return references to be fetched. + */ public Set getWantRefs() { return wantRefs; } - /** @return objects to be fetched. */ + /** + * Get objects to be fetched. + * + * @return objects to be fetched. + */ public Set getWantObjects() { return wantObjects; } - /** @return remote references, usually from the advertisement. */ + /** + * Get remote references, usually from the advertisement. + * + * @return remote references, usually from the advertisement. + */ @Nullable public Map getRefs() { return refs; } /** + * Set references observed from the replica. + * * @param refs * references observed from the replica. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java index 691b1424f..603288ebc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java @@ -54,8 +54,8 @@ import org.eclipse.jgit.transport.ReceiveCommand; /** * A push request sending objects to a replica, and its result. *

- * Implementors of {@link KetchReplica} must populate the command result fields, - * {@link #setRefs(Map)}, and call one of + * Implementors of {@link org.eclipse.jgit.internal.ketch.KetchReplica} must + * populate the command result fields, {@link #setRefs(Map)}, and call one of * {@link #setException(Repository, Throwable)} or {@link #done(Repository)} to * finish processing. */ @@ -80,18 +80,28 @@ public class ReplicaPushRequest { this.commands = commands; } - /** @return commands to be executed, and their results. */ + /** + * Get commands to be executed, and their results. + * + * @return commands to be executed, and their results. + */ public Collection getCommands() { return commands; } - /** @return remote references, usually from the advertisement. */ + /** + * Get remote references, usually from the advertisement. + * + * @return remote references, usually from the advertisement. + */ @Nullable public Map getRefs() { return refs; } /** + * Set references observed from the replica. + * * @param refs * references observed from the replica. */ @@ -99,7 +109,11 @@ public class ReplicaPushRequest { this.refs = refs; } - /** @return exception thrown, if any. */ + /** + * Get exception thrown, if any. + * + * @return exception thrown, if any. + */ @Nullable public Throwable getException() { return exception; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java index 8c3de027d..263be77bf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java @@ -65,31 +65,50 @@ public class ReplicaSnapshot { this.replica = replica; } - /** @return the replica this snapshot describes the state of. */ + /** + * Get the replica this snapshot describes the state of + * + * @return the replica this snapshot describes the state of + */ public KetchReplica getReplica() { return replica; } - /** @return current state of the replica. */ + /** + * Get current state of the replica + * + * @return current state of the replica + */ public KetchReplica.State getState() { return state; } - /** @return last known Git commit at {@code refs/txn/accepted}. */ + /** + * Get last known Git commit at {@code refs/txn/accepted} + * + * @return last known Git commit at {@code refs/txn/accepted} + */ @Nullable public ObjectId getAccepted() { return accepted; } - /** @return last known Git commit at {@code refs/txn/committed}. */ + /** + * Get last known Git commit at {@code refs/txn/committed} + * + * @return last known Git commit at {@code refs/txn/committed} + */ @Nullable public ObjectId getCommitted() { return committed; } /** - * @return if {@link #getState()} == {@link KetchReplica.State#OFFLINE} an - * optional human-readable message from the transport system + * Get error message + * + * @return if {@link #getState()} == + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.State#OFFLINE} + * an optional human-readable message from the transport system * explaining the failure. */ @Nullable @@ -98,6 +117,9 @@ public class ReplicaSnapshot { } /** + * Get when the leader will retry communication with the offline or lagging + * replica + * * @return time (usually in the future) when the leader will retry * communication with the offline or lagging replica; null if no * retry is scheduled or necessary. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java index 61871a494..ae82dced2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java @@ -66,7 +66,9 @@ import org.eclipse.jgit.treewalk.EmptyTreeIterator; import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.filter.TreeFilter; -/** Constructs a set of commands to stage content during a proposal. */ +/** + * Constructs a set of commands to stage content during a proposal. + */ public class StageBuilder { /** * Acceptable number of references to send in a single stage transaction. @@ -119,14 +121,15 @@ public class StageBuilder { * from. * @param oldTree * accepted RefTree on the replica ({@code refs/txn/accepted}). - * Use {@link ObjectId#zeroId()} if the remote does not have any - * ref tree, e.g. a new replica catching up. + * Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} if the + * remote does not have any ref tree, e.g. a new replica catching + * up. * @param newTree * RefTree being sent to the replica. The trees will be compared. * @return list of commands to create {@code "refs/txn/stage/..."} * references on replicas anchoring new objects into the repository * while a transaction gains consensus. - * @throws IOException + * @throws java.io.IOException * {@code git} cannot be accessed to compare {@code oldTree} and * {@code newTree} to build the object set. */ @@ -172,7 +175,7 @@ public class StageBuilder { * @return list of commands to create {@code "refs/txn/stage/..."} * references on replicas anchoring {@code newObjs} into the * repository while a transaction gains consensus. - * @throws IOException + * @throws java.io.IOException * {@code git} cannot be accessed to perform minification of * {@code newObjs}. */ From 5bd3e75094a1149a0a63a5600a147bd369b5f9d0 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 14:05:44 +0100 Subject: [PATCH 2/2] Fix javadoc in org.eclipse.jgit rewalk package Change-Id: Ifc34e96a56df30e3b73bef812eea943623af7906 Signed-off-by: Matthias Sohn --- .../org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java | 3 +++ .../eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java | 3 +++ 2 files changed, 6 insertions(+) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java index 3145de184..468d93046 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java @@ -73,6 +73,7 @@ public class AddToBitmapFilter extends RevFilter { this.bitmap = bitmap; } + /** {@inheritDoc} */ @Override public final boolean include(RevWalk walker, RevCommit cmit) { Bitmap visitedBitmap; @@ -93,11 +94,13 @@ public class AddToBitmapFilter extends RevFilter { return false; } + /** {@inheritDoc} */ @Override public final RevFilter clone() { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public final boolean requiresCommitBody() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java index 6cb19ba00..a52c6a26a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java @@ -81,6 +81,7 @@ public class AddUnseenToBitmapFilter extends RevFilter { this.bitmap = bitmap; } + /** {@inheritDoc} */ @Override public final boolean include(RevWalk walker, RevCommit cmit) { Bitmap visitedBitmap; @@ -101,11 +102,13 @@ public class AddUnseenToBitmapFilter extends RevFilter { return false; } + /** {@inheritDoc} */ @Override public final RevFilter clone() { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public final boolean requiresCommitBody() { return false;