- * A {@link MergedReftable} merge-joins multiple {@link ReftableReader} on the - * fly. Tables higher/later in the stack shadow lower/earlier tables, hiding + * A {@link org.eclipse.jgit.internal.storage.reftable.MergedReftable} + * merge-joins multiple + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableReader} on the fly. + * Tables higher/later in the stack shadow lower/earlier tables, hiding * references that been updated/replaced. *
* By default deleted references are skipped and not returned to the caller. @@ -89,6 +91,7 @@ public class MergedReftable extends Reftable { } } + /** {@inheritDoc} */ @Override public RefCursor allRefs() throws IOException { MergedRefCursor m = new MergedRefCursor(); @@ -98,6 +101,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public RefCursor seekRef(String name) throws IOException { MergedRefCursor m = new MergedRefCursor(); @@ -107,6 +111,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public RefCursor byObjectId(AnyObjectId name) throws IOException { MergedRefCursor m = new MergedRefCursor(); @@ -116,6 +121,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public LogCursor allLogs() throws IOException { MergedLogCursor m = new MergedLogCursor(); @@ -125,6 +131,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public LogCursor seekLog(String refName, long updateIdx) throws IOException { @@ -135,6 +142,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public void close() throws IOException { for (Reftable t : tables) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java index d8e9c609f..5d4af30a9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java @@ -47,29 +47,45 @@ import java.io.IOException; import org.eclipse.jgit.lib.Ref; -/** Iterator over references inside a {@link Reftable}. */ +/** + * Iterator over references inside a + * {@link org.eclipse.jgit.internal.storage.reftable.Reftable}. + */ public abstract class RefCursor implements AutoCloseable { /** * Check if another reference is available. * * @return {@code true} if there is another result. - * @throws IOException + * @throws java.io.IOException * references cannot be read. */ public abstract boolean next() throws IOException; - /** @return reference at the current position. */ + /** + * Get reference at the current position. + * + * @return reference at the current position. + */ public abstract Ref getRef(); - /** @return updateIndex that last modified the current reference, */ + /** + * Get updateIndex that last modified the current reference. + * + * @return updateIndex that last modified the current reference. + */ public abstract long getUpdateIndex(); - /** @return {@code true} if the current reference was deleted. */ + /** + * Whether the current reference was deleted. + * + * @return {@code true} if the current reference was deleted. + */ public boolean wasDeleted() { Ref r = getRef(); return r.getStorage() == Ref.Storage.NEW && r.getObjectId() == null; } + /** {@inheritDoc} */ @Override public abstract void close(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java index 1189ed3b9..510c1a14e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java @@ -55,9 +55,13 @@ import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.Ref; import org.eclipse.jgit.lib.SymbolicRef; -/** Abstract table of references. */ +/** + * Abstract table of references. + */ public abstract class Reftable implements AutoCloseable { /** + * References to convert into a reftable + * * @param refs * references to convert into a reftable; may be empty. * @return a reader for the supplied references. @@ -83,6 +87,8 @@ public abstract class Reftable implements AutoCloseable { protected boolean includeDeletes; /** + * Whether deleted references will be returned. + * * @param deletes * if {@code true} deleted references will be returned. If * {@code false} (default behavior), deleted references will be @@ -96,7 +102,7 @@ public abstract class Reftable implements AutoCloseable { * Seek to the first reference, to iterate in order. * * @return cursor to iterate. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public abstract RefCursor allRefs() throws IOException; @@ -115,7 +121,7 @@ public abstract class Reftable implements AutoCloseable { * @param refName * reference name or subtree to find. * @return cursor to iterate; empty cursor if no references match. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public abstract RefCursor seekRef(String refName) throws IOException; @@ -126,7 +132,7 @@ public abstract class Reftable implements AutoCloseable { * @param id * object to find. * @return cursor to iterate; empty cursor if no references match. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public abstract RefCursor byObjectId(AnyObjectId id) throws IOException; @@ -135,7 +141,7 @@ public abstract class Reftable implements AutoCloseable { * Seek reader to read log records. * * @return cursor to iterate; empty cursor if no logs are present. - * @throws IOException + * @throws java.io.IOException * if logs cannot be read. */ public abstract LogCursor allLogs() throws IOException; @@ -146,7 +152,7 @@ public abstract class Reftable implements AutoCloseable { * @param refName * exact name of the reference whose log to read. * @return cursor to iterate; empty cursor if no logs match. - * @throws IOException + * @throws java.io.IOException * if logs cannot be read. */ public LogCursor seekLog(String refName) throws IOException { @@ -162,7 +168,7 @@ public abstract class Reftable implements AutoCloseable { * most recent index to return first in the log cursor. Log * records at or before {@code updateIndex} will be returned. * @return cursor to iterate; empty cursor if no logs match. - * @throws IOException + * @throws java.io.IOException * if logs cannot be read. */ public abstract LogCursor seekLog(String refName, long updateIndex) @@ -174,7 +180,7 @@ public abstract class Reftable implements AutoCloseable { * @param refName * reference name to find. * @return the reference, or {@code null} if not found. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ @Nullable @@ -196,7 +202,7 @@ public abstract class Reftable implements AutoCloseable { * reference name or subtree to find. * @return {@code true} if the reference exists, or at least one reference * exists in the subtree. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public boolean hasRef(String refName) throws IOException { @@ -212,7 +218,7 @@ public abstract class Reftable implements AutoCloseable { * ObjectId to find. * @return {@code true} if any reference exists directly referencing * {@code id}, or a annotated tag that peels to {@code id}. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public boolean hasId(AnyObjectId id) throws IOException { @@ -227,7 +233,7 @@ public abstract class Reftable implements AutoCloseable { * @param symref * reference to resolve. * @return resolved {@code symref}, or {@code null}. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ @Nullable @@ -257,6 +263,7 @@ public abstract class Reftable implements AutoCloseable { return new SymbolicRef(ref.getName(), dst); } + /** {@inheritDoc} */ @Override public abstract void close() throws IOException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java index 6b53d4176..ed73a9efb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java @@ -80,6 +80,8 @@ public class ReftableCompactor { private Stats stats; /** + * Set configuration for the reftable. + * * @param cfg * configuration for the reftable. * @return {@code this} @@ -90,6 +92,8 @@ public class ReftableCompactor { } /** + * Set limit on number of bytes from source tables to compact. + * * @param bytes * limit on number of bytes from source tables to compact. * @return {@code this} @@ -100,6 +104,9 @@ public class ReftableCompactor { } /** + * Whether to include deletions in the output, which may be necessary for + * partial compaction. + * * @param deletes * {@code true} to include deletions in the output, which may be * necessary for partial compaction. @@ -111,6 +118,9 @@ public class ReftableCompactor { } /** + * Set the minimum update index for log entries that appear in the compacted + * reftable. + * * @param min * the minimum update index for log entries that appear in the * compacted reftable. This should be 1 higher than the prior @@ -124,6 +134,9 @@ public class ReftableCompactor { } /** + * Set the maximum update index for log entries that appear in the compacted + * reftable. + * * @param max * the maximum update index for log entries that appear in the * compacted reftable. This should be at least 1 higher than the @@ -137,6 +150,8 @@ public class ReftableCompactor { } /** + * Set oldest reflog time to preserve. + * * @param timeMillis * oldest log time to preserve. Entries whose timestamps are * {@code >= timeMillis} will be copied into the output file. Log @@ -159,7 +174,7 @@ public class ReftableCompactor { * tables to compact. Tables should be ordered oldest first/most * recent last so that the more recent tables can shadow the * older results. Caller is responsible for closing the readers. - * @throws IOException + * @throws java.io.IOException * update indexes of a reader cannot be accessed. */ public void addAll(List readers) throws IOException { @@ -184,7 +199,7 @@ public class ReftableCompactor { * responsible for closing the reader. * @return {@code true} if the compactor accepted this table; {@code false} * if the compactor has reached its limit. - * @throws IOException + * @throws java.io.IOException * if size of {@code reader}, or its update indexes cannot be read. */ public boolean tryAddFirst(ReftableReader reader) throws IOException { @@ -213,7 +228,7 @@ public class ReftableCompactor { * @param out * stream to write the compacted tables to. Caller is responsible * for closing {@code out}. - * @throws IOException + * @throws java.io.IOException * if tables cannot be read, or cannot be written. */ public void compact(OutputStream out) throws IOException { @@ -229,7 +244,11 @@ public class ReftableCompactor { stats = writer.getStats(); } - /** @return statistics of the last written reftable. */ + /** + * Get statistics of the last written reftable. + * + * @return statistics of the last written reftable. + */ public Stats getStats() { return stats; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java index f7a1fbe2a..66c113d1e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java @@ -48,7 +48,9 @@ import static org.eclipse.jgit.internal.storage.reftable.ReftableConstants.MAX_B import org.eclipse.jgit.lib.Config; import org.eclipse.jgit.lib.Repository; -/** Configuration used by a reftable writer when constructing the stream. */ +/** + * Configuration used by a reftable writer when constructing the stream. + */ public class ReftableConfig { private int refBlockSize = 4 << 10; private int logBlockSize; @@ -57,7 +59,9 @@ public class ReftableConfig { private boolean alignBlocks = true; private boolean indexObjects = true; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public ReftableConfig() { } @@ -74,7 +78,8 @@ public class ReftableConfig { } /** - * Create a configuration honoring settings in a {@link Config}. + * Create a configuration honoring settings in a + * {@link org.eclipse.jgit.lib.Config}. * * @param cfg * the source to read settings from. The source is not retained @@ -100,12 +105,18 @@ public class ReftableConfig { this.indexObjects = cfg.indexObjects; } - /** @return desired output block size for references, in bytes */ + /** + * Get desired output block size for references, in bytes. + * + * @return desired output block size for references, in bytes. + */ public int getRefBlockSize() { return refBlockSize; } /** + * Set desired output block size for references, in bytes. + * * @param szBytes * desired output block size for references, in bytes. */ @@ -117,6 +128,8 @@ public class ReftableConfig { } /** + * Get desired output block size for log entries, in bytes. + * * @return desired output block size for log entries, in bytes. If 0 the * writer will default to {@code 2 * getRefBlockSize()}. */ @@ -125,6 +138,8 @@ public class ReftableConfig { } /** + * Set desired output block size for log entries, in bytes. + * * @param szBytes * desired output block size for log entries, in bytes. If 0 will * default to {@code 2 * getRefBlockSize()}. @@ -136,12 +151,18 @@ public class ReftableConfig { logBlockSize = Math.max(0, szBytes); } - /** @return number of references between binary search markers. */ + /** + * Get number of references between binary search markers. + * + * @return number of references between binary search markers. + */ public int getRestartInterval() { return restartInterval; } /** + *
Setter for the field restartInterval.
* A reftable can be written in a streaming fashion, provided the caller sorts - * all references. A {@link ReftableWriter} is single-use, and not thread-safe. + * all references. A + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableWriter} is + * single-use, and not thread-safe. */ public class ReftableWriter { private ReftableConfig config; @@ -113,7 +115,9 @@ public class ReftableWriter { private int objIdLen; private Stats stats; - /** Initialize a writer with a default configuration. */ + /** + * Initialize a writer with a default configuration. + */ public ReftableWriter() { this(new ReftableConfig()); } @@ -129,6 +133,8 @@ public class ReftableWriter { } /** + * Set configuration for the writer. + * * @param cfg * configuration for the writer. * @return {@code this} @@ -139,6 +145,9 @@ public class ReftableWriter { } /** + * Set the minimum update index for log entries that appear in this + * reftable. + * * @param min * the minimum update index for log entries that appear in this * reftable. This should be 1 higher than the prior reftable's @@ -151,6 +160,9 @@ public class ReftableWriter { } /** + * Set the maximum update index for log entries that appear in this + * reftable. + * * @param max * the maximum update index for log entries that appear in this * reftable. This should be at least 1 higher than the prior @@ -170,7 +182,7 @@ public class ReftableWriter { * stream to write the table to. Caller is responsible for * closing the stream after invoking {@link #finish()}. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * if reftable header cannot be written. */ public ReftableWriter begin(OutputStream os) throws IOException { @@ -208,7 +220,7 @@ public class ReftableWriter { * @param refsToPack * references to sort and write. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public ReftableWriter sortAndWriteRefs(Collection refsToPack) @@ -232,7 +244,7 @@ public class ReftableWriter { * * @param ref * the reference to store. - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void writeRef(Ref ref) throws IOException { @@ -249,7 +261,7 @@ public class ReftableWriter { * @param updateIndex * the updateIndex that modified this reference. Must be * {@code >= minUpdateIndex} for this file. - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void writeRef(Ref ref, long updateIndex) throws IOException { @@ -295,12 +307,14 @@ public class ReftableWriter { * @param who * committer of the reflog entry. * @param oldId - * prior id; pass {@link ObjectId#zeroId()} for creations. + * prior id; pass {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * for creations. * @param newId - * new id; pass {@link ObjectId#zeroId()} for deletions. + * new id; pass {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * for deletions. * @param message * optional message (may be null). - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void writeLog(String ref, long updateIndex, PersonIdent who, @@ -327,7 +341,7 @@ public class ReftableWriter { * the ref to delete (hide) a reflog entry from. * @param updateIndex * the update index that must be hidden. - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void deleteLog(String ref, long updateIndex) throws IOException { @@ -345,10 +359,14 @@ public class ReftableWriter { } /** + * Get an estimate of the current size in bytes of the reftable + * * @return an estimate of the current size in bytes of the reftable, if it * was finished right now. Estimate is only accurate if - * {@link ReftableConfig#setIndexObjects(boolean)} is {@code false} - * and {@link ReftableConfig#setMaxIndexLevels(int)} is {@code 1}. + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableConfig#setIndexObjects(boolean)} + * is {@code false} and + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableConfig#setMaxIndexLevels(int)} + * is {@code 1}. */ public long estimateTotalBytes() { long bytes = out.size(); @@ -381,7 +399,7 @@ public class ReftableWriter { * Finish writing the reftable by writing its trailer. * * @return {@code this} - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public ReftableWriter finish() throws IOException { @@ -480,7 +498,11 @@ public class ReftableWriter { return s != null && s.idx != null ? s.idx.rootPosition : 0; } - /** @return statistics of the last written reftable. */ + /** + * Get statistics of the last written reftable. + * + * @return statistics of the last written reftable. + */ public Stats getStats() { return stats; }