motiejus
/
jgit
1
Fork 0
Code Releases Activity

Fix javadoc in org.eclipse.jgit storage/pack package 

Change-Id: Id1b7d392e1bb36079edaf16450e73a044a318e7e
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
This commit is contained in:
Matthias Sohn 2017-12-18 15:33:32 +01:00
parent c6d17443ad
commit 783dbf1b03
10 changed files with 258 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java
View File

@ -45,13 +45,17 @@
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 long getDeltaCount() throws IOException {
* 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,

23
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java
View File

@ -48,7 +48,10 @@
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 DeltaEncoder(OutputStream out, long baseSize, long resultSize)
* 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 @@ private void writeVarint(long sz) throws IOException {
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 int getSize() {
* 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 boolean insert(String text) throws IOException {
* 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 boolean insert(byte[] text) throws IOException {
* 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 boolean insert(byte[] text, int off, int cnt)
* 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 {

16
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java
View File

@ -51,8 +51,9 @@
* <p>
* 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.
* <p>
* 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 @@ private void copyEntries(DeltaIndexScanner scan) {
}
}
/** @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 @@ private static int sizeOfArray(int entSize, int len) {
* 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 void encode(OutputStream out, byte[] res) throws IOException {
* @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 @@ private static int negmatch(byte[] res, int resPtr, byte[] src, int srcPtr,
return start - resPtr;
}
/** {@inheritDoc} */
@Override
@SuppressWarnings("nls")
public String toString() {

1
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java
View File

@ -292,6 +292,7 @@ void add(Slice s) {
slices.add(s);
}
/** {@inheritDoc} */
@Override
public Object call() throws Exception {
or = block.templateReader.newReader();

56
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java
View File

@ -51,26 +51,27 @@
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.
* <p>
* {@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.
* <p>
* {@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 {
* <p>
* 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.
* <p>
* 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.
* <p>
* 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 void selectObjectRepresentation(PackWriter packer,
* 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 void selectObjectRepresentation(PackWriter packer,
* 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 void writeObjects(PackOutputStream out, List<ObjectToPack> list)
* 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 void copyObjectAsIs(PackOutputStream out, ObjectToPack otp,
* 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 abstract void copyPackAsIs(PackOutputStream out, CachedPack pack)
* @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.

43
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java
View File

@ -50,7 +50,8 @@
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}.
* <p>
* {@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 ObjectToPack(AnyObjectId src, final int type) {
}
/**
* 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 @@ final void clearDeltaBase() {
}
/**
* @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 final boolean isWritten() {
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 @@ final void markWantWrite() {
}
/**
* 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 @@ final void setDeltaAttempted(boolean deltaAttempted) {
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 @@ final void setCachedSize(int sz) {
* Remember a specific representation for reuse at a later time.
* <p>
* 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 void select(StoredObjectRepresentation ref) {
// Empty by default.
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

29
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java
View File

@ -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 @@ private PackExt(String ext, int pos) {
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$

27
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java
View File

@ -57,7 +57,10 @@
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 {
* <p>
* 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 PackOutputStream(final ProgressMonitor writeMonitor,
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 void write(final int b) throws IOException {
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 void write(final byte[] b, int off, int len)
}
}
/** {@inheritDoc} */
@Override
public void flush() throws IOException {
out.flush();
@ -154,7 +161,7 @@ final void writeFileHeader(int version, long objectCount)
*
* @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 void writeObject(ObjectToPack otp) throws IOException {
* 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 @@ private static final int ofsDeltaVarIntLength(long v) {
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 @@ void endObject() {
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;
}

157
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java
View File

@ -135,8 +135,8 @@
* <li>(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</li>
* <li>by providing iterator of {@link RevObject} specifying exact list and
* order of objects in pack</li>
* <li>by providing iterator of {@link org.eclipse.jgit.revwalk.RevObject}
* specifying exact list and order of objects in pack</li>
* </ul>
* <p>
* Typical usage consists of creating an instance, configuring options,
@ -149,10 +149,11 @@
* followed by {@link #writeBitmapIndex(OutputStream)}.
* </p>
* <p>
* Class provide set of configurable options and {@link ProgressMonitor}
* support, as operations may take a long time for big repositories. Deltas
* searching algorithm is <b>NOT IMPLEMENTED</b> 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 <b>NOT
* IMPLEMENTED</b> yet - this implementation relies only on deltas and objects
* reuse.
* </p>
* <p>
* This class is not thread safe. It is intended to be used in one thread as a
@ -210,7 +211,11 @@ public void remove() {
}
};
/** @return all allocated, non-released PackWriters instances. */
/**
* Get all allocated, non-released PackWriters instances.
*
* @return all allocated, non-released PackWriters instances.
*/
public static Iterable<PackWriter> getInstances() {
return instancesIterable;
}
@ -374,7 +379,6 @@ public PackWriter(final PackConfig config, final ObjectReader reader) {
*
* @param callback
* the callback to set
*
* @return this object for chaining.
*/
public PackWriter setObjectCountCallback(ObjectCountCallback callback) {
@ -466,12 +470,19 @@ public void setReuseValidatingObjects(boolean validate) {
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 void setThin(final boolean packthin) {
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 void setUseCachedPacks(boolean useCached) {
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 void setUseBitmaps(boolean useBitmaps) {
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 boolean isIgnoreMissingUninteresting() {
}
/**
* 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 void setShallowPack(int depth,
* 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 long getObjectCount() throws IOException {
* 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<ObjectIdOwnerMap.Entry> getObjectSet()
@ -672,12 +708,14 @@ public void excludeObjects(ObjectIdSet idx) {
* @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<RevObject> objectsSource)
@ -693,10 +731,10 @@ public void preparePack(@NonNull Iterator<RevObject> objectsSource)
* 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.
* </p>
*
* @param countingMonitor
@ -709,7 +747,7 @@ public void preparePack(@NonNull Iterator<RevObject> objectsSource)
* 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 void preparePack(ProgressMonitor countingMonitor,
* {@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 void preparePack(ProgressMonitor countingMonitor,
* @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 @@ private ObjectWalk getObjectWalk() {
* 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.
* </p>
*
* @param countingMonitor
@ -829,7 +867,7 @@ private ObjectWalk getObjectWalk() {
* @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 void preparePack(ProgressMonitor countingMonitor,
* @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 int getIndexVersion() {
* @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 void writeIndex(final OutputStream indexStream) throws IOException {
* @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 @@ private void endPhase(ProgressMonitor monitor) {
* @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 void writePack(ProgressMonitor compressMonitor,
}
/**
* 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 PackStatistics getStatistics() {
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}
* <p>
* Release all resources used by this writer.
*/
@Override
@ -1972,7 +2019,7 @@ private static void pruneEdgesFromObjectList(List<ObjectToPack> list) {
*
* @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 @@ private boolean exclude(AnyObjectId objectId) {
/**
* Select an object representation for this writer.
* <p>
* 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 @@ private final boolean have(ObjectToPack ptr, AnyObjectId objectId) {
* @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 {

14
org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java
View File

@ -46,7 +46,9 @@
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 int getWeight() {
}
/**
* 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 int getFormat() {
}
/**
* 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 ObjectId getDeltaBase() {
}
/**
* 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.
*/