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;
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;
}
/** 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.
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();
}
/**
* Merges multiple reference tables together.
* <p>
- * 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.
* <p>
* By default deleted references are skipped and not returned to the caller.
}
}
+ /** {@inheritDoc} */
@Override
public RefCursor allRefs() throws IOException {
MergedRefCursor m = new MergedRefCursor();
return m;
}
+ /** {@inheritDoc} */
@Override
public RefCursor seekRef(String name) throws IOException {
MergedRefCursor m = new MergedRefCursor();
return m;
}
+ /** {@inheritDoc} */
@Override
public RefCursor byObjectId(AnyObjectId name) throws IOException {
MergedRefCursor m = new MergedRefCursor();
return m;
}
+ /** {@inheritDoc} */
@Override
public LogCursor allLogs() throws IOException {
MergedLogCursor m = new MergedLogCursor();
return m;
}
+ /** {@inheritDoc} */
@Override
public LogCursor seekLog(String refName, long updateIdx)
throws IOException {
return m;
}
+ /** {@inheritDoc} */
@Override
public void close() throws IOException {
for (Reftable t : tables) {
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();
}
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.
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
* 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;
* @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;
* @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;
* 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;
* @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 {
* 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)
* @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
* 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 {
* 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 {
* @param symref
* reference to resolve.
* @return resolved {@code symref}, or {@code null}.
- * @throws IOException
+ * @throws java.io.IOException
* if references cannot be read.
*/
@Nullable
return new SymbolicRef(ref.getName(), dst);
}
+ /** {@inheritDoc} */
@Override
public abstract void close() throws IOException;
}
private Stats stats;
/**
+ * Set configuration for the reftable.
+ *
* @param cfg
* configuration for the reftable.
* @return {@code this}
}
/**
+ * 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}
}
/**
+ * 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.
}
/**
+ * 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
}
/**
+ * 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
}
/**
+ * 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
* 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<? extends Reftable> readers) throws IOException {
* 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 {
* @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 {
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;
}
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;
private boolean alignBlocks = true;
private boolean indexObjects = true;
- /** Create a default configuration. */
+ /**
+ * Create a default configuration.
+ */
public 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
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.
*/
}
/**
+ * 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()}.
*/
}
/**
+ * 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()}.
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;
}
/**
+ * <p>Setter for the field <code>restartInterval</code>.</p>
+ *
* @param interval
* number of references between binary search markers. If
* {@code interval} is 0 (default), the writer will select a
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
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
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
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);
}
/**
+ * 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 {
}
/**
+ * 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 {
}
/**
+ * 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 {
return maxUpdateIndex;
}
+ /** {@inheritDoc} */
@Override
public RefCursor allRefs() throws IOException {
if (blockSize == -1) {
return i;
}
+ /** {@inheritDoc} */
@Override
public RefCursor seekRef(String refName) throws IOException {
initRefIndex();
return i;
}
+ /** {@inheritDoc} */
@Override
public RefCursor byObjectId(AnyObjectId id) throws IOException {
initObjIndex();
return i;
}
+ /** {@inheritDoc} */
@Override
public LogCursor allLogs() throws IOException {
initLogIndex();
return new EmptyLogCursor();
}
+ /** {@inheritDoc} */
@Override
public LogCursor seekLog(String refName, long updateIndex)
throws IOException {
* 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();
* Writes a reftable formatted file.
* <p>
* 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;
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());
}
}
/**
+ * Set configuration for the writer.
+ *
* @param cfg
* configuration for the writer.
* @return {@code this}
}
/**
+ * 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
}
/**
+ * 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
* 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 {
* @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<Ref> refsToPack)
*
* @param ref
* the reference to store.
- * @throws IOException
+ * @throws java.io.IOException
* if reftable cannot be written.
*/
public void writeRef(Ref ref) throws IOException {
* @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 {
* @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,
* 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 {
}
/**
+ * 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();
* 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 {
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;
}
projects / jgit.git / commitdiff