From 43e26de7ecd3b0b6304f0d518de01c423e21234d Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 15:56:57 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit storage/reftable package Change-Id: I14764c5d5b2309d82fe2ccc0593120b51328bf41 Signed-off-by: Matthias Sohn --- .../reftable/BlockSizeTooSmallException.java | 11 +++- .../storage/reftable/EmptyLogCursor.java | 5 ++ .../internal/storage/reftable/LogCursor.java | 26 +++++++-- .../storage/reftable/MergedReftable.java | 12 +++- .../internal/storage/reftable/RefCursor.java | 26 +++++++-- .../internal/storage/reftable/Reftable.java | 29 ++++++---- .../storage/reftable/ReftableCompactor.java | 27 +++++++-- .../storage/reftable/ReftableConfig.java | 57 ++++++++++++++++--- .../reftable/ReftableOutputStream.java | 2 + .../storage/reftable/ReftableReader.java | 27 +++++++-- .../storage/reftable/ReftableWriter.java | 50 +++++++++++----- 11 files changed, 215 insertions(+), 57 deletions(-) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java index cb0f988b23..991306e0a6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java @@ -45,7 +45,10 @@ package org.eclipse.jgit.internal.storage.reftable; import java.io.IOException; -/** Thrown if {@link ReftableWriter} cannot fit a reference. */ +/** + * Thrown if {@link org.eclipse.jgit.internal.storage.reftable.ReftableWriter} + * cannot fit a reference. + */ public class BlockSizeTooSmallException extends IOException { private static final long serialVersionUID = 1L; @@ -55,7 +58,11 @@ public class BlockSizeTooSmallException extends IOException { minBlockSize = b; } - /** @return minimum block size in bytes reftable requires to write a ref. */ + /** + * Get minimum block size in bytes reftable requires to write a ref. + * + * @return minimum block size in bytes reftable requires to write a ref. + */ public int getMinimumBlockSize() { return minBlockSize; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java index d7745891a5..de5baa1c18 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java @@ -49,26 +49,31 @@ import org.eclipse.jgit.lib.ReflogEntry; /** Empty {@link LogCursor} with no results. */ class EmptyLogCursor extends LogCursor { + /** {@inheritDoc} */ @Override public boolean next() throws IOException { return false; } + /** {@inheritDoc} */ @Override public String getRefName() { return null; } + /** {@inheritDoc} */ @Override public long getUpdateIndex() { return 0; } + /** {@inheritDoc} */ @Override public ReflogEntry getReflogEntry() { return null; } + /** {@inheritDoc} */ @Override public void close() { // Do nothing. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java index c19968c098..486fd28984 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java @@ -47,26 +47,42 @@ import java.io.IOException; import org.eclipse.jgit.lib.ReflogEntry; -/** Iterator over logs inside a {@link Reftable}. */ +/** + * Iterator over logs inside a + * {@link org.eclipse.jgit.internal.storage.reftable.Reftable}. + */ public abstract class LogCursor implements AutoCloseable { /** * Check if another log record is available. * * @return {@code true} if there is another result. - * @throws IOException + * @throws java.io.IOException * logs cannot be read. */ public abstract boolean next() throws IOException; - /** @return name of the current reference. */ + /** + * Get name of the current reference. + * + * @return name of the current reference. + */ public abstract String getRefName(); - /** @return identifier of the transaction that created the log record. */ + /** + * Get identifier of the transaction that created the log record. + * + * @return identifier of the transaction that created the log record. + */ public abstract long getUpdateIndex(); - /** @return current log entry. */ + /** + * Get current log entry. + * + * @return current log entry. + */ public abstract ReflogEntry getReflogEntry(); + /** {@inheritDoc} */ @Override public abstract void close(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java index 9fc6ae2bb4..baebde2b48 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java @@ -54,8 +54,10 @@ import org.eclipse.jgit.lib.ReflogEntry; /** * Merges multiple reference tables together. *

- * 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 d8e9c609f0..5d4af30a91 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 1189ed3b96..510c1a14e0 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 6b53d41763..ed73a9efbd 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 f7a1fbe2af..66c113d1ec 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.

+ * * @param interval * number of references between binary search markers. If * {@code interval} is 0 (default), the writer will select a @@ -151,12 +172,18 @@ public class ReftableConfig { restartInterval = Math.max(0, interval); } - /** @return maximum depth of the index; 0 for unlimited. */ + /** + * Get maximum depth of the index; 0 for unlimited. + * + * @return maximum depth of the index; 0 for unlimited. + */ public int getMaxIndexLevels() { return maxIndexLevels; } /** + * Set maximum number of levels to use in indexes. + * * @param levels * maximum number of levels to use in indexes. Lower levels of * the index respect {@link #getRefBlockSize()}, and the highest @@ -166,12 +193,19 @@ public class ReftableConfig { maxIndexLevels = Math.max(0, levels); } - /** @return {@code true} if the writer should align blocks. */ + /** + * Whether the writer should align blocks. + * + * @return {@code true} if the writer should align blocks. + */ public boolean isAlignBlocks() { return alignBlocks; } /** + * Whether blocks are written aligned to multiples of + * {@link #getRefBlockSize()}. + * * @param align * if {@code true} blocks are written aligned to multiples of * {@link #getRefBlockSize()}. May increase file size due to NUL @@ -181,12 +215,19 @@ public class ReftableConfig { alignBlocks = align; } - /** @return {@code true} if the writer should index object to ref. */ + /** + * Whether the writer should index object to ref. + * + * @return {@code true} if the writer should index object to ref. + */ public boolean isIndexObjects() { return indexObjects; } /** + * Whether the reftable may include additional storage to efficiently map + * from {@code ObjectId} to reference names. + * * @param index * if {@code true} the reftable may include additional storage to * efficiently map from {@code ObjectId} to reference names. By diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java index a24619b2c5..1fc43c9fac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java @@ -92,12 +92,14 @@ class ReftableOutputStream extends OutputStream { blockSize = bs; } + /** {@inheritDoc} */ @Override public void write(int b) { ensureBytesAvailableInBlockBuf(1); blockBuf[cur++] = (byte) b; } + /** {@inheritDoc} */ @Override public void write(byte[] b, int off, int cnt) { ensureBytesAvailableInBlockBuf(cnt); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java index 407a77c7d3..74877192f6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java @@ -112,10 +112,13 @@ public class ReftableReader extends Reftable { } /** + * Get the block size in bytes chosen for this file by the writer. + * * @return the block size in bytes chosen for this file by the writer. Most - * reads from the {@link BlockSource} will be aligned to the block - * size. - * @throws IOException + * reads from the + * {@link org.eclipse.jgit.internal.storage.io.BlockSource} will be + * aligned to the block size. + * @throws java.io.IOException * file cannot be read. */ public int blockSize() throws IOException { @@ -126,10 +129,13 @@ public class ReftableReader extends Reftable { } /** + * Get the minimum update index for log entries that appear in this + * reftable. + * * @return the minimum update index for log entries that appear in this * reftable. This should be 1 higher than the prior reftable's * {@code maxUpdateIndex} if this table is used in a stack. - * @throws IOException + * @throws java.io.IOException * file cannot be read. */ public long minUpdateIndex() throws IOException { @@ -140,10 +146,13 @@ public class ReftableReader extends Reftable { } /** + * Get the maximum update index for log entries that appear in this + * reftable. + * * @return the maximum update index for log entries that appear in this * reftable. This should be 1 higher than the prior reftable's * {@code maxUpdateIndex} if this table is used in a stack. - * @throws IOException + * @throws java.io.IOException * file cannot be read. */ public long maxUpdateIndex() throws IOException { @@ -153,6 +162,7 @@ public class ReftableReader extends Reftable { return maxUpdateIndex; } + /** {@inheritDoc} */ @Override public RefCursor allRefs() throws IOException { if (blockSize == -1) { @@ -167,6 +177,7 @@ public class ReftableReader extends Reftable { return i; } + /** {@inheritDoc} */ @Override public RefCursor seekRef(String refName) throws IOException { initRefIndex(); @@ -179,6 +190,7 @@ public class ReftableReader extends Reftable { return i; } + /** {@inheritDoc} */ @Override public RefCursor byObjectId(AnyObjectId id) throws IOException { initObjIndex(); @@ -191,6 +203,7 @@ public class ReftableReader extends Reftable { return i; } + /** {@inheritDoc} */ @Override public LogCursor allLogs() throws IOException { initLogIndex(); @@ -203,6 +216,7 @@ public class ReftableReader extends Reftable { return new EmptyLogCursor(); } + /** {@inheritDoc} */ @Override public LogCursor seekLog(String refName, long updateIndex) throws IOException { @@ -437,13 +451,14 @@ public class ReftableReader extends Reftable { * Get size of the reftable, in bytes. * * @return size of the reftable, in bytes. - * @throws IOException + * @throws java.io.IOException * size cannot be obtained. */ public long size() throws IOException { return src.size(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { src.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java index 0ac2445fc0..f8b9ffd176 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java @@ -89,7 +89,9 @@ import org.eclipse.jgit.util.NB; * Writes a reftable formatted file. *

* 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; } -- 2.39.5