public abstract class PackIndexWriter extends Object
PackFile.
Pack index files (the .idx suffix in a pack file pair)
provides random access to any object in the pack by associating an ObjectId
to the byte offset within the pack where the object's data can be read.
| Modifier and Type | Field and Description |
|---|---|
protected List<? extends PackedObjectInfo> |
entries
The entries this writer must pack.
|
protected DigestOutputStream |
out
The index data stream we are responsible for creating.
|
protected byte[] |
packChecksum
SHA-1 checksum for the entire pack data.
|
protected byte[] |
tmp
A temporary buffer for use during IO to {link #out}.
|
protected static byte[] |
TOC
Magic constant indicating post-version 1 format.
|
| Modifier | Constructor and Description |
|---|---|
protected |
PackIndexWriter(OutputStream dst)
Create a new writer instance.
|
| Modifier and Type | Method and Description |
|---|---|
static PackIndexWriter |
createOldestPossible(OutputStream dst,
List<? extends PackedObjectInfo> objs)
Create a new writer for the oldest (most widely understood) format.
|
static PackIndexWriter |
createVersion(OutputStream dst,
int version)
Create a new writer instance for a specific index format version.
|
static int |
oldestPossibleFormat(List<? extends PackedObjectInfo> objs)
Return the oldest (most widely understood) index format.
|
void |
write(List<? extends PackedObjectInfo> toStore,
byte[] packDataChecksum)
Write all object entries to the index stream.
|
protected void |
writeChecksumFooter()
Output the standard two-checksum index footer.
|
protected void |
writeFanOutTable()
Output the standard 256 entry first-level fan-out table.
|
protected abstract void |
writeImpl()
Writes the index file to
out. |
protected void |
writeTOC(int version)
Output the version 2 (and later) TOC header, with version number.
|
protected static final byte[] TOC
protected final DigestOutputStream out
protected final byte[] tmp
protected List<? extends PackedObjectInfo> entries
protected byte[] packChecksum
protected PackIndexWriter(OutputStream dst)
dst - the stream this instance outputs to. If not already buffered
it will be automatically wrapped in a buffered stream.public static PackIndexWriter createOldestPossible(OutputStream dst, List<? extends PackedObjectInfo> objs)
This method selects an index format that can accurate describe the supplied objects and that will be the most compatible format with older Git implementations.
Index version 1 is widely recognized by all Git implementations, but index version 2 (and later) is not as well recognized as it was introduced more than a year later. Index version 1 can only be used if the resulting pack file is under 4 gigabytes in size; packs larger than that limit must use index version 2.
dst - the stream the index data will be written to. If not already
buffered it will be automatically wrapped in a buffered
stream. Callers are always responsible for closing the stream.objs - the objects the caller needs to store in the index. Entries
will be examined until a format can be conclusively selected.IllegalArgumentException - no recognized pack index version can support the supplied
objects. This is likely a bug in the implementation.oldestPossibleFormat(List)public static int oldestPossibleFormat(List<? extends PackedObjectInfo> objs)
This method selects an index format that can accurate describe the supplied objects and that will be the most compatible format with older Git implementations.
Index version 1 is widely recognized by all Git implementations, but index version 2 (and later) is not as well recognized as it was introduced more than a year later. Index version 1 can only be used if the resulting pack file is under 4 gigabytes in size; packs larger than that limit must use index version 2.
objs - the objects the caller needs to store in the index. Entries
will be examined until a format can be conclusively selected.IllegalArgumentException - no recognized pack index version can support the supplied
objects. This is likely a bug in the implementation.public static PackIndexWriter createVersion(OutputStream dst, int version)
dst - the stream the index data will be written to. If not already
buffered it will be automatically wrapped in a buffered
stream. Callers are always responsible for closing the stream.version - index format version number required by the caller. Exactly
this formatted version will be written.IllegalArgumentException - the version requested is not supported by this
implementation.public void write(List<? extends PackedObjectInfo> toStore, byte[] packDataChecksum) throws IOException
After writing the stream passed to the factory is flushed but remains open. Callers are always responsible for closing the output stream.
toStore - sorted list of objects to store in the index. The caller must
have previously sorted the list using PackedObjectInfo's
native Comparable implementation.packDataChecksum - checksum signature of the entire pack data content. This is
traditionally the last 20 bytes of the pack file's own stream.IOException - an error occurred while writing to the output stream, or this
index format cannot store the object data supplied.protected abstract void writeImpl()
throws IOException
out.
Implementations should go something like:
writeFanOutTable();
for (final PackedObjectInfo po : entries)
writeOneEntry(po);
writeChecksumFooter();
Where the logic for writeOneEntry is specific to the index
format in use. Additional headers/footers may be used if necessary and
the entries collection may be iterated over more than once if
necessary. Implementors therefore have complete control over the data.
IOException - an error occurred while writing to the output stream, or this
index format cannot store the object data supplied.protected void writeTOC(int version)
throws IOException
Post version 1 all index files start with a TOC header that makes the file an invalid version 1 file, and then includes the version number. This header is necessary to recognize a version 1 from a version 2 formatted index.
version - version number of this index format being written.IOException - an error occurred while writing to the output stream.protected void writeFanOutTable()
throws IOException
The fan-out table is 4 KB in size, holding 256 32-bit unsigned integer
counts. Each count represents the number of objects within this index
whose AnyObjectId.getFirstByte() matches the count's position in the
fan-out table.
IOException - an error occurred while writing to the output stream.protected void writeChecksumFooter()
throws IOException
The standard footer contains two checksums (20 byte SHA-1 values):
IOException - an error occurred while writing to the output stream.Copyright © 2014. All rights reserved.