From 783dbf1b03cdabc5a8db63c9ac10fae164e6cf41 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 15:33:32 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit storage/pack package Change-Id: Id1b7d392e1bb36079edaf16450e73a044a318e7e Signed-off-by: Matthias Sohn --- .../internal/storage/pack/CachedPack.java | 17 +- .../internal/storage/pack/DeltaEncoder.java | 23 ++- .../internal/storage/pack/DeltaIndex.java | 16 +- .../jgit/internal/storage/pack/DeltaTask.java | 1 + .../storage/pack/ObjectReuseAsIs.java | 56 ++++--- .../internal/storage/pack/ObjectToPack.java | 43 +++-- .../jgit/internal/storage/pack/PackExt.java | 29 +++- .../storage/pack/PackOutputStream.java | 27 ++- .../internal/storage/pack/PackWriter.java | 157 ++++++++++++------ .../pack/StoredObjectRepresentation.java | 14 +- 10 files changed, 258 insertions(+), 125 deletions(-) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java index 6498ea35d0..81f40558ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java @@ -45,13 +45,17 @@ package org.eclipse.jgit.internal.storage.pack; import java.io.IOException; -/** Describes a pack file {@link ObjectReuseAsIs} can append onto a stream. */ +/** + * Describes a pack file + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs} can append + * onto a stream. + */ public abstract class CachedPack { /** * Get the number of objects in this pack. * * @return the total object count for the pack. - * @throws IOException + * @throws java.io.IOException * if the object count cannot be read. */ public abstract long getObjectCount() throws IOException; @@ -70,7 +74,7 @@ public abstract class CachedPack { * * @return the number of deltas; 0 if the number is not known or there are * no deltas. - * @throws IOException + * @throws java.io.IOException * if the delta count cannot be read. */ public long getDeltaCount() throws IOException { @@ -88,15 +92,16 @@ public abstract class CachedPack { * only and using its internal state to decide if this object is within this * pack. Implementors should ensure a representation from this cached pack * is tested as part of - * {@link ObjectReuseAsIs#selectObjectRepresentation(PackWriter, org.eclipse.jgit.lib.ProgressMonitor, Iterable)} + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs#selectObjectRepresentation(PackWriter, org.eclipse.jgit.lib.ProgressMonitor, Iterable)} * , ensuring this method would eventually return true if the object would * be included by this cached pack. * * @param obj * the object being packed. Can be used as an ObjectId. * @param rep - * representation from the {@link ObjectReuseAsIs} instance that - * originally supplied this CachedPack. + * representation from the + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs} + * instance that originally supplied this CachedPack. * @return true if this pack contains this object. */ public abstract boolean hasObject(ObjectToPack obj, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java index cccbc5903e..343faf4df4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java @@ -48,7 +48,10 @@ import java.io.OutputStream; import org.eclipse.jgit.lib.Constants; -/** Encodes an instruction stream for {@link BinaryDelta}. */ +/** + * Encodes an instruction stream for + * {@link org.eclipse.jgit.internal.storage.pack.BinaryDelta}. + */ public class DeltaEncoder { /** * Maximum number of bytes to be copied in pack v2 format. @@ -91,7 +94,7 @@ public class DeltaEncoder { * @param resultSize * size of the resulting object, after applying this instruction * stream to the base object, in bytes. - * @throws IOException + * @throws java.io.IOException * the output buffer cannot store the instruction stream's * header with the size fields. */ @@ -114,7 +117,7 @@ public class DeltaEncoder { * maximum number of bytes to write to the out buffer declaring * the stream is over limit and should be discarded. May be 0 to * specify an infinite limit. - * @throws IOException + * @throws java.io.IOException * the output buffer cannot store the instruction stream's * header with the size fields. */ @@ -138,7 +141,11 @@ public class DeltaEncoder { out.write(buf, 0, p); } - /** @return current size of the delta stream, in bytes. */ + /** + * Get current size of the delta stream, in bytes. + * + * @return current size of the delta stream, in bytes. + */ public int getSize() { return size; } @@ -150,7 +157,7 @@ public class DeltaEncoder { * the string to insert. * @return true if the insert fits within the limit; false if the insert * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer can't store the instructions. */ public boolean insert(String text) throws IOException { @@ -164,7 +171,7 @@ public class DeltaEncoder { * the binary to insert. * @return true if the insert fits within the limit; false if the insert * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer can't store the instructions. */ public boolean insert(byte[] text) throws IOException { @@ -182,7 +189,7 @@ public class DeltaEncoder { * number of bytes to insert. * @return true if the insert fits within the limit; false if the insert * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer can't store the instructions. */ public boolean insert(byte[] text, int off, int cnt) @@ -217,7 +224,7 @@ public class DeltaEncoder { * number of bytes to copy. * @return true if the copy fits within the limit; false if the copy * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer cannot store the instructions. */ public boolean copy(long offset, int cnt) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java index 0f22de08e0..6f3e2accad 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java @@ -51,8 +51,9 @@ import java.io.OutputStream; *

* The index can be passed a result buffer, and output an instruction sequence * that transforms the source buffer used by the index into the result buffer. - * The instruction sequence can be executed by {@link BinaryDelta} to recreate - * the result buffer. + * The instruction sequence can be executed by + * {@link org.eclipse.jgit.internal.storage.pack.BinaryDelta} to recreate the + * result buffer. *

* An index stores the entire contents of the source buffer, but also a table of * block identities mapped to locations where the block appears in the source @@ -191,7 +192,11 @@ public class DeltaIndex { } } - /** @return size of the source buffer this index has scanned. */ + /** + * Get size of the source buffer this index has scanned. + * + * @return size of the source buffer this index has scanned. + */ public long getSourceSize() { return src.length; } @@ -244,7 +249,7 @@ public class DeltaIndex { * the desired result buffer. The generated instructions will * recreate this buffer when applied to the source buffer stored * within this index. - * @throws IOException + * @throws java.io.IOException * the output stream refused to write the instructions. */ public void encode(OutputStream out, byte[] res) throws IOException { @@ -274,7 +279,7 @@ public class DeltaIndex { * @return true if the delta is smaller than deltaSizeLimit; false if the * encoder aborted because the encoded delta instructions would be * longer than deltaSizeLimit bytes. - * @throws IOException + * @throws java.io.IOException * the output stream refused to write the instructions. */ public boolean encode(OutputStream out, byte[] res, int deltaSizeLimit) @@ -421,6 +426,7 @@ public class DeltaIndex { return start - resPtr; } + /** {@inheritDoc} */ @Override @SuppressWarnings("nls") public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java index 0c4e4448d8..0347644324 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java @@ -292,6 +292,7 @@ final class DeltaTask implements Callable { slices.add(s); } + /** {@inheritDoc} */ @Override public Object call() throws Exception { or = block.templateReader.newReader(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java index 2e5d59960e..f759e23ef4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java @@ -51,26 +51,27 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; -import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ProgressMonitor; /** - * Extension of {@link ObjectReader} that supports reusing objects in packs. + * Extension of {@link org.eclipse.jgit.lib.ObjectReader} that supports reusing + * objects in packs. *

* {@code ObjectReader} implementations may also optionally implement this - * interface to support {@link PackWriter} with a means of copying an object - * that is already in pack encoding format directly into the output stream, - * without incurring decompression and recompression overheads. + * interface to support + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} with a means of + * copying an object that is already in pack encoding format directly into the + * output stream, without incurring decompression and recompression overheads. */ public interface ObjectReuseAsIs { /** * Allocate a new {@code PackWriter} state structure for an object. *

- * {@link PackWriter} allocates these objects to keep track of the - * per-object state, and how to load the objects efficiently into the - * generated stream. Implementers may subclass this type with additional - * object state, such as to remember what file and offset contains the - * object's pack encoded data. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} allocates these + * objects to keep track of the per-object state, and how to load the + * objects efficiently into the generated stream. Implementers may subclass + * this type with additional object state, such as to remember what file and + * offset contains the object's pack encoded data. * * @param objectId * the id of the object that will be packed. @@ -85,15 +86,16 @@ public interface ObjectReuseAsIs { *

* Implementations should iterate through all available representations of * an object, and pass them in turn to the PackWriter though - * {@link PackWriter#select(ObjectToPack, StoredObjectRepresentation)} so - * the writer can select the most suitable representation to reuse into the - * output stream. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter#select(ObjectToPack, StoredObjectRepresentation)} + * so the writer can select the most suitable representation to reuse into + * the output stream. *

- * If the implementation returns CachedPack from {@link #getCachedPacksAndUpdate(BitmapBuilder)} - * it must consider the representation of any object that is stored in any - * of the offered CachedPacks. PackWriter relies on this behavior to prune - * duplicate objects out of the pack stream when it selects a CachedPack and - * the object was also reached through the thin-pack enumeration. + * If the implementation returns CachedPack from + * {@link #getCachedPacksAndUpdate(BitmapBuilder)} it must consider the + * representation of any object that is stored in any of the offered + * CachedPacks. PackWriter relies on this behavior to prune duplicate + * objects out of the pack stream when it selects a CachedPack and the + * object was also reached through the thin-pack enumeration. *

* The implementation may choose to consider multiple objects at once on * concurrent threads, but must evaluate all representations of an object @@ -106,10 +108,10 @@ public interface ObjectReuseAsIs { * once for each item in the iteration when selection is done. * @param objects * the objects that are being packed. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * there is no representation available for the object, as it is * no longer in the repository. Packing will abort. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed. Packing will abort. */ public void selectObjectRepresentation(PackWriter packer, @@ -136,7 +138,9 @@ public interface ObjectReuseAsIs { * format to reach a delta base that is later in the stream. It may also * reduce data locality for the reader, slowing down data access. * - * Invoking {@link PackOutputStream#writeObject(ObjectToPack)} will cause + * Invoking + * {@link org.eclipse.jgit.internal.storage.pack.PackOutputStream#writeObject(ObjectToPack)} + * will cause * {@link #copyObjectAsIs(PackOutputStream, ObjectToPack, boolean)} to be * invoked recursively on {@code this} if the current object is scheduled * for reuse. @@ -147,7 +151,7 @@ public interface ObjectReuseAsIs { * the list of objects to write. Objects should be written in * approximately this order. Implementors may resort the list * elements in-place during writing if desired. - * @throws IOException + * @throws java.io.IOException * the stream cannot be written to, or one or more required * objects cannot be accessed from the object database. */ @@ -186,13 +190,13 @@ public interface ObjectReuseAsIs { * corrupt before being reused. If false, validation may be * skipped as it will be performed elsewhere in the processing * pipeline. - * @throws StoredObjectRepresentationNotAvailableException + * @throws org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException * the previously selected representation is no longer * available. If thrown before {@code out.writeHeader} the pack * writer will try to find another representation, and write * that one instead. If throw after {@code out.writeHeader}, * packing will abort. - * @throws IOException + * @throws java.io.IOException * the stream's write method threw an exception. Packing will * abort. */ @@ -209,7 +213,7 @@ public interface ObjectReuseAsIs { * stream to append the pack onto. * @param pack * the cached pack to send. - * @throws IOException + * @throws java.io.IOException * the pack cannot be read, or stream did not accept a write. */ public abstract void copyPackAsIs(PackOutputStream out, CachedPack pack) @@ -225,7 +229,7 @@ public interface ObjectReuseAsIs { * @param needBitmap * the bitmap that contains all of the objects the client wants. * @return the available cached packs. - * @throws IOException + * @throws java.io.IOException * the cached packs cannot be listed from the repository. * Callers may choose to ignore this and continue as-if there * were no cached packs. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java index bc7a603c4a..e8c75107b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java @@ -50,7 +50,8 @@ import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.transport.PackedObjectInfo; /** - * Per-object state used by {@link PackWriter}. + * Per-object state used by + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter}. *

* {@code PackWriter} uses this class to track the things it needs to include in * the newly generated pack file, and how to efficiently obtain the raw data for @@ -108,19 +109,25 @@ public class ObjectToPack extends PackedObjectInfo { } /** + * Get delta base object id if object is going to be packed in delta + * representation + * * @return delta base object id if object is going to be packed in delta - * representation; null otherwise - if going to be packed as a - * whole object. + * representation; null otherwise - if going to be packed as a whole + * object. */ public final ObjectId getDeltaBaseId() { return deltaBase; } /** + * Get delta base object to pack if object is going to be packed in delta + * representation and delta is specified as object to pack + * * @return delta base object to pack if object is going to be packed in - * delta representation and delta is specified as object to - * pack; null otherwise - if going to be packed as a whole - * object or delta base is specified only as id. + * delta representation and delta is specified as object to pack; + * null otherwise - if going to be packed as a whole object or delta + * base is specified only as id. */ public final ObjectToPack getDeltaBase() { if (deltaBase instanceof ObjectToPack) @@ -164,8 +171,9 @@ public class ObjectToPack extends PackedObjectInfo { } /** - * @return true if object is going to be written as delta; false - * otherwise. + * Whether object is going to be written as delta + * + * @return true if object is going to be written as delta; false otherwise. */ public final boolean isDeltaRepresentation() { return deltaBase != null; @@ -181,7 +189,7 @@ public class ObjectToPack extends PackedObjectInfo { return 1 < getOffset(); // markWantWrite sets 1. } - /** @return the type of this object. */ + /** {@inheritDoc} */ @Override public final int getType() { return (flags >> TYPE_SHIFT) & 0x7; @@ -216,6 +224,9 @@ public class ObjectToPack extends PackedObjectInfo { } /** + * Whether an existing representation was selected to be reused as-is into + * the pack stream. + * * @return true if an existing representation was selected to be reused * as-is into the pack stream. */ @@ -266,7 +277,11 @@ public class ObjectToPack extends PackedObjectInfo { flags &= ~DELTA_ATTEMPTED; } - /** @return the extended flags on this object, in the range [0x0, 0xf]. */ + /** + * Get the extended flags on this object, in the range [0x0, 0xf]. + * + * @return the extended flags on this object, in the range [0x0, 0xf]. + */ protected final int getExtendedFlags() { return (flags >>> EXT_SHIFT) & EXT_MASK; } @@ -363,9 +378,10 @@ public class ObjectToPack extends PackedObjectInfo { * Remember a specific representation for reuse at a later time. *

* Implementers should remember the representation chosen, so it can be - * reused at a later time. {@link PackWriter} may invoke this method - * multiple times for the same object, each time saving the current best - * representation found. + * reused at a later time. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} may invoke this + * method multiple times for the same object, each time saving the current + * best representation found. * * @param ref * the object representation. @@ -374,6 +390,7 @@ public class ObjectToPack extends PackedObjectInfo { // Empty by default. } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java index e8bbf78a15..292fd368cd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.internal.storage.pack; -/** A pack file extension. */ +/** + * A pack file extension. + */ public class PackExt { private static volatile PackExt[] VALUES = new PackExt[] {}; @@ -62,7 +64,11 @@ public class PackExt { /** A reftable file. */ public static final PackExt REFTABLE = newPackExt("ref"); //$NON-NLS-1$ - /** @return all of the PackExt values. */ + /** + * Get all of the PackExt values. + * + * @return all of the PackExt values. + */ public static PackExt[] values() { return VALUES; } @@ -102,21 +108,34 @@ public class PackExt { this.pos = pos; } - /** @return the file extension. */ + /** + * Get the file extension. + * + * @return the file extension. + */ public String getExtension() { return ext; } - /** @return the position of the extension in the values array. */ + /** + * Get the position of the extension in the values array. + * + * @return the position of the extension in the values array. + */ public int getPosition() { return pos; } - /** @return the bit mask of the extension e.g {@code 1 << getPosition()}. */ + /** + * Get the bit mask of the extension e.g {@code 1 << getPosition()}. + * + * @return the bit mask of the extension e.g {@code 1 << getPosition()}. + */ public int getBit() { return 1 << getPosition(); } + /** {@inheritDoc} */ @Override public String toString() { return String.format("PackExt[%s, bit=0x%s]", getExtension(), //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java index 59166e6206..fd9c1a00d3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java @@ -57,7 +57,10 @@ import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.util.NB; -/** Custom output stream to support {@link PackWriter}. */ +/** + * Custom output stream to support + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter}. + */ public final class PackOutputStream extends OutputStream { private static final int BYTES_TO_WRITE_BEFORE_CANCEL_CHECK = 128 * 1024; @@ -84,7 +87,8 @@ public final class PackOutputStream extends OutputStream { *

* This constructor is exposed to support debugging the JGit library only. * Application or storage level code should not create a PackOutputStream, - * instead use {@link PackWriter}, and let the writer create the stream. + * instead use {@link org.eclipse.jgit.internal.storage.pack.PackWriter}, + * and let the writer create the stream. * * @param writeMonitor * monitor to update on object output progress. @@ -101,6 +105,7 @@ public final class PackOutputStream extends OutputStream { this.checkCancelAt = BYTES_TO_WRITE_BEFORE_CANCEL_CHECK; } + /** {@inheritDoc} */ @Override public final void write(final int b) throws IOException { count++; @@ -108,6 +113,7 @@ public final class PackOutputStream extends OutputStream { md.update((byte) b); } + /** {@inheritDoc} */ @Override public final void write(final byte[] b, int off, int len) throws IOException { @@ -131,6 +137,7 @@ public final class PackOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void flush() throws IOException { out.flush(); @@ -154,7 +161,7 @@ public final class PackOutputStream extends OutputStream { * * @param otp * the object to write. - * @throws IOException + * @throws java.io.IOException * the object cannot be read from the object reader, or the * output stream is no longer accepting output. Caller must * examine the type of exception and possibly its message to @@ -177,7 +184,7 @@ public final class PackOutputStream extends OutputStream { * in whole object format, this is the same as the object size. * For an object that is in a delta format, this is the size of * the inflated delta instruction stream. - * @throws IOException + * @throws java.io.IOException * the underlying stream refused to accept the header. */ public final void writeHeader(ObjectToPack otp, long rawLength) @@ -224,7 +231,11 @@ public final class PackOutputStream extends OutputStream { return n; } - /** @return a temporary buffer writers can use to copy data with. */ + /** + * Get a temporary buffer writers can use to copy data with. + * + * @return a temporary buffer writers can use to copy data with. + */ public final byte[] getCopyBuffer() { return copyBuffer; } @@ -233,7 +244,11 @@ public final class PackOutputStream extends OutputStream { writeMonitor.update(1); } - /** @return total number of bytes written since stream start. */ + /** + * Get total number of bytes written since stream start. + * + * @return total number of bytes written since stream start. + */ public final long length() { return count; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java index 2c1d475aea..2cf4d4b559 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java @@ -135,8 +135,8 @@ import org.eclipse.jgit.util.TemporaryBuffer; *

  • (usually) by providing sets of interesting and uninteresting objects in * repository - all interesting objects and their ancestors except uninteresting * objects and their ancestors will be included in pack, or
    • - *
  • by providing iterator of {@link RevObject} specifying exact list and - * order of objects in pack
    • + *
  • by providing iterator of {@link org.eclipse.jgit.revwalk.RevObject} + * specifying exact list and order of objects in pack
    • * *

    * Typical usage consists of creating an instance, configuring options, @@ -149,10 +149,11 @@ import org.eclipse.jgit.util.TemporaryBuffer; * followed by {@link #writeBitmapIndex(OutputStream)}. *

    *

    - * Class provide set of configurable options and {@link ProgressMonitor} - * support, as operations may take a long time for big repositories. Deltas - * searching algorithm is NOT IMPLEMENTED yet - this implementation - * relies only on deltas and objects reuse. + * Class provide set of configurable options and + * {@link org.eclipse.jgit.lib.ProgressMonitor} support, as operations may take + * a long time for big repositories. Deltas searching algorithm is NOT + * IMPLEMENTED yet - this implementation relies only on deltas and objects + * reuse. *

    *

    * This class is not thread safe. It is intended to be used in one thread as a @@ -210,7 +211,11 @@ public class PackWriter implements AutoCloseable { } }; - /** @return all allocated, non-released PackWriters instances. */ + /** + * Get all allocated, non-released PackWriters instances. + * + * @return all allocated, non-released PackWriters instances. + */ public static Iterable getInstances() { return instancesIterable; } @@ -374,7 +379,6 @@ public class PackWriter implements AutoCloseable { * * @param callback * the callback to set - * * @return this object for chaining. */ public PackWriter setObjectCountCallback(ObjectCountCallback callback) { @@ -466,12 +470,19 @@ public class PackWriter implements AutoCloseable { reuseValidate = validate; } - /** @return true if this writer is producing a thin pack. */ + /** + * Whether this writer is producing a thin pack. + * + * @return true if this writer is producing a thin pack. + */ public boolean isThin() { return thin; } /** + * Whether writer may pack objects with delta base object not within set of + * objects to pack + * * @param packthin * a boolean indicating whether writer may pack objects with * delta base object not within set of objects to pack, but @@ -483,16 +494,23 @@ public class PackWriter implements AutoCloseable { thin = packthin; } - /** @return true to reuse cached packs. If true index creation isn't available. */ + /** + * Whether to reuse cached packs. + * + * @return {@code true} to reuse cached packs. If true index creation isn't + * available. + */ public boolean isUseCachedPacks() { return useCachedPacks; } /** + * Whether to use cached packs + * * @param useCached - * if set to true and a cached pack is present, it will be - * appended onto the end of a thin-pack, reducing the amount of - * working set space and CPU used by PackWriter. Enabling this + * if set to {@code true} and a cached pack is present, it will + * be appended onto the end of a thin-pack, reducing the amount + * of working set space and CPU used by PackWriter. Enabling this * feature prevents PackWriter from creating an index for the * newly created pack, so its only suitable for writing to a * network client, where the client will make the index. @@ -501,12 +519,18 @@ public class PackWriter implements AutoCloseable { useCachedPacks = useCached; } - /** @return true to use bitmaps for ObjectWalks, if available. */ + /** + * Whether to use bitmaps + * + * @return {@code true} to use bitmaps for ObjectWalks, if available. + */ public boolean isUseBitmaps() { return useBitmaps; } /** + * Whether to use bitmaps + * * @param useBitmaps * if set to true, bitmaps will be used when preparing a pack. */ @@ -514,23 +538,33 @@ public class PackWriter implements AutoCloseable { this.useBitmaps = useBitmaps; } - /** @return true if the index file cannot be created by this PackWriter. */ + /** + * Whether the index file cannot be created by this PackWriter. + * + * @return {@code true} if the index file cannot be created by this + * PackWriter. + */ public boolean isIndexDisabled() { return indexDisabled || !cachedPacks.isEmpty(); } /** + * Whether to disable creation of the index file. + * * @param noIndex - * true to disable creation of the index file. + * {@code true} to disable creation of the index file. */ public void setIndexDisabled(boolean noIndex) { this.indexDisabled = noIndex; } /** - * @return true to ignore objects that are uninteresting and also not found - * on local disk; false to throw a {@link MissingObjectException} - * out of {@link #preparePack(ProgressMonitor, Set, Set)} if an + * Whether to ignore missing uninteresting objects + * + * @return {@code true} to ignore objects that are uninteresting and also + * not found on local disk; false to throw a + * {@link org.eclipse.jgit.errors.MissingObjectException} out of + * {@link #preparePack(ProgressMonitor, Set, Set)} if an * uninteresting object is not in the source repository. By default, * true, permitting gracefully ignoring of uninteresting objects. */ @@ -539,11 +573,13 @@ public class PackWriter implements AutoCloseable { } /** + * Whether writer should ignore non existing uninteresting objects + * * @param ignore - * true if writer should ignore non existing uninteresting - * objects during construction set of objects to pack; false - * otherwise - non existing uninteresting objects may cause - * {@link MissingObjectException} + * {@code true} if writer should ignore non existing + * uninteresting objects during construction set of objects to + * pack; false otherwise - non existing uninteresting objects may + * cause {@link org.eclipse.jgit.errors.MissingObjectException} */ public void setIgnoreMissingUninteresting(final boolean ignore) { ignoreMissingUninteresting = ignore; @@ -586,7 +622,7 @@ public class PackWriter implements AutoCloseable { * Returns objects number in a pack file that was created by this writer. * * @return number of objects in pack. - * @throws IOException + * @throws java.io.IOException * a cached pack cannot supply its object count. */ public long getObjectCount() throws IOException { @@ -613,7 +649,7 @@ public class PackWriter implements AutoCloseable { * been invoked and completed successfully. * * @return set of objects in pack. - * @throws IOException + * @throws java.io.IOException * a cached pack cannot supply its object ids. */ public ObjectIdOwnerMap getObjectSet() @@ -672,12 +708,14 @@ public class PackWriter implements AutoCloseable { * @param objectsSource * iterator of object to store in a pack; order of objects within * each type is important, ordering by type is not needed; - * allowed types for objects are {@link Constants#OBJ_COMMIT}, - * {@link Constants#OBJ_TREE}, {@link Constants#OBJ_BLOB} and - * {@link Constants#OBJ_TAG}; objects returned by iterator may be - * later reused by caller as object id and type are internally - * copied in each iteration. - * @throws IOException + * allowed types for objects are + * {@link org.eclipse.jgit.lib.Constants#OBJ_COMMIT}, + * {@link org.eclipse.jgit.lib.Constants#OBJ_TREE}, + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB} and + * {@link org.eclipse.jgit.lib.Constants#OBJ_TAG}; objects + * returned by iterator may be later reused by caller as object + * id and type are internally copied in each iteration. + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public void preparePack(@NonNull Iterator objectsSource) @@ -693,10 +731,10 @@ public class PackWriter implements AutoCloseable { * Basing on these 2 sets, another set of objects to put in a pack file is * created: this set consists of all objects reachable (ancestors) from * interesting objects, except uninteresting objects and their ancestors. - * This method uses class {@link ObjectWalk} extensively to find out that - * appropriate set of output objects and their optimal order in output pack. - * Order is consistent with general git in-pack rules: sort by object type, - * recency, path and delta-base first. + * This method uses class {@link org.eclipse.jgit.revwalk.ObjectWalk} + * extensively to find out that appropriate set of output objects and their + * optimal order in output pack. Order is consistent with general git + * in-pack rules: sort by object type, recency, path and delta-base first. *

    * * @param countingMonitor @@ -709,7 +747,7 @@ public class PackWriter implements AutoCloseable { * points of graph traversal). Pass {@link #NONE} if all objects * reachable from {@code want} are desired, such as when serving * a clone. - * @throws IOException + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -744,7 +782,7 @@ public class PackWriter implements AutoCloseable { * {@code shallow} commits and earlier generations will be * included in the pack if requested by {@code want}. Must not be * {@code null}. - * @throws IOException + * @throws java.io.IOException * an I/O problem occurred while reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -783,7 +821,7 @@ public class PackWriter implements AutoCloseable { * @param noBitmaps * collection of objects to be excluded from bitmap commit * selection. - * @throws IOException + * @throws java.io.IOException * an I/O problem occurred while reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -808,10 +846,10 @@ public class PackWriter implements AutoCloseable { * Basing on these 2 sets, another set of objects to put in a pack file is * created: this set consists of all objects reachable (ancestors) from * interesting objects, except uninteresting objects and their ancestors. - * This method uses class {@link ObjectWalk} extensively to find out that - * appropriate set of output objects and their optimal order in output pack. - * Order is consistent with general git in-pack rules: sort by object type, - * recency, path and delta-base first. + * This method uses class {@link org.eclipse.jgit.revwalk.ObjectWalk} + * extensively to find out that appropriate set of output objects and their + * optimal order in output pack. Order is consistent with general git + * in-pack rules: sort by object type, recency, path and delta-base first. *

    * * @param countingMonitor @@ -829,7 +867,7 @@ public class PackWriter implements AutoCloseable { * @param noBitmaps * collection of objects to be excluded from bitmap commit * selection. - * @throws IOException + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -853,7 +891,7 @@ public class PackWriter implements AutoCloseable { * @param id * the object to test the existence of. * @return true if the object will appear in the output pack file. - * @throws IOException + * @throws java.io.IOException * a cached pack cannot be examined. */ public boolean willInclude(final AnyObjectId id) throws IOException { @@ -920,7 +958,7 @@ public class PackWriter implements AutoCloseable { * @param indexStream * output for the index data. Caller is responsible for closing * this stream. - * @throws IOException + * @throws java.io.IOException * the index data could not be written to the supplied stream. */ public void writeIndex(final OutputStream indexStream) throws IOException { @@ -942,7 +980,7 @@ public class PackWriter implements AutoCloseable { * @param bitmapIndexStream * output for the bitmap index data. Caller is responsible for * closing this stream. - * @throws IOException + * @throws java.io.IOException * the index data could not be written to the supplied stream. */ public void writeBitmapIndex(final OutputStream bitmapIndexStream) @@ -1027,13 +1065,13 @@ public class PackWriter implements AutoCloseable { * @param packStream * output stream of pack data. The stream should be buffered by * the caller. The caller is responsible for closing the stream. - * @throws IOException + * @throws java.io.IOException * an error occurred reading a local object's data to include in * the pack, or writing compressed object data to the output * stream. * @throws WriteAbortedException - * the write operation is aborted by {@link ObjectCountCallback} - * . + * the write operation is aborted by + * {@link org.eclipse.jgit.transport.ObjectCountCallback} . */ public void writePack(ProgressMonitor compressMonitor, ProgressMonitor writeMonitor, OutputStream packStream) @@ -1122,6 +1160,9 @@ public class PackWriter implements AutoCloseable { } /** + * Get statistics of what this PackWriter did in order to create the final + * pack stream. + * * @return description of what this PackWriter did in order to create the * final pack stream. This should only be invoked after the calls to * create the pack/index/bitmap have completed. @@ -1130,12 +1171,18 @@ public class PackWriter implements AutoCloseable { return new PackStatistics(stats); } - /** @return snapshot of the current state of this PackWriter. */ + /** + * Get snapshot of the current state of this PackWriter. + * + * @return snapshot of the current state of this PackWriter. + */ public State getState() { return state.snapshot(); } /** + * {@inheritDoc} + *

    * Release all resources used by this writer. */ @Override @@ -1972,7 +2019,7 @@ public class PackWriter implements AutoCloseable { * * @param object * the object to add. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object is an unsupported type. */ public void addObject(final RevObject object) @@ -2014,9 +2061,9 @@ public class PackWriter implements AutoCloseable { /** * Select an object representation for this writer. *

    - * An {@link ObjectReader} implementation should invoke this method once for - * each representation available for an object, to allow the writer to find - * the most suitable one for the output. + * An {@link org.eclipse.jgit.lib.ObjectReader} implementation should invoke + * this method once for each representation available for an object, to + * allow the writer to find the most suitable one for the output. * * @param otp * the object being packed. @@ -2097,7 +2144,7 @@ public class PackWriter implements AutoCloseable { * @param pm * progress monitor to report bitmap building work. * @return whether a bitmap index may be written. - * @throws IOException + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public boolean prepareBitmapIndex(ProgressMonitor pm) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java index c48b1bbff0..23778201cf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.internal.storage.pack; import org.eclipse.jgit.lib.ObjectId; /** - * An object representation {@link PackWriter} can consider for packing. + * An object representation + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} can consider for + * packing. */ public class StoredObjectRepresentation { /** Special unknown value for {@link #getWeight()}. */ @@ -62,6 +64,8 @@ public class StoredObjectRepresentation { public static final int FORMAT_OTHER = 2; /** + * Get relative size of this object's packed form. + * * @return relative size of this object's packed form. The special value * {@link #WEIGHT_UNKNOWN} can be returned to indicate the * implementation doesn't know, or cannot supply the weight up @@ -72,6 +76,8 @@ public class StoredObjectRepresentation { } /** + * Get the storage format type + * * @return the storage format type, which must be one of * {@link #PACK_DELTA}, {@link #PACK_WHOLE}, or * {@link #FORMAT_OTHER}. @@ -81,6 +87,9 @@ public class StoredObjectRepresentation { } /** + * Get identity of the object this delta applies to in order to recover the + * original object content. + * * @return identity of the object this delta applies to in order to recover * the original object content. This method should only be called if * {@link #getFormat()} returned {@link #PACK_DELTA}. @@ -90,6 +99,9 @@ public class StoredObjectRepresentation { } /** + * Whether the current representation of the object has had delta + * compression attempted on it. + * * @return whether the current representation of the object has had delta * compression attempted on it. */ -- 2.39.5