Package org.eclipse.jgit.internal.storage.file

## Class PackIndexWriter

- java.lang.Object
- - org.eclipse.jgit.internal.storage.file.PackIndexWriter

    public abstract class PackIndexWriter
    extends Object

Creates a table of contents to support random access by `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.

### Field Summary

Fields
`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.

### Constructor Summary

Constructors
`protected` `PackIndexWriter​(OutputStream dst)` Create a new writer instance.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`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.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### TOC

    protected static final byte[] TOC

Magic constant indicating post-version 1 format.

#### out

    protected final DigestOutputStream out

The index data stream we are responsible for creating.

#### tmp

    protected final byte[] tmp

A temporary buffer for use during IO to {link #out}.

#### entries

    protected List<? extends PackedObjectInfo> entries

The entries this writer must pack.

#### packChecksum

    protected byte[] packChecksum

SHA-1 checksum for the entire pack data.

### Constructor Detail

#### PackIndexWriter

    protected PackIndexWriter​(OutputStream dst)

Create a new writer instance.

Parameters:
  `dst` - the stream this instance outputs to. If not already buffered it will be automatically wrapped in a buffered stream.

### Method Detail

#### createOldestPossible

    public static PackIndexWriter createOldestPossible​(OutputStream dst,
                                                       List<? extends PackedObjectInfo> objs)

Create a new writer for the oldest (most widely understood) format.

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.

Parameters:
  `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.
Returns:
  a new writer to output an index file of the requested format to the supplied stream.
Throws:
  `IllegalArgumentException` - no recognized pack index version can support the supplied objects. This is likely a bug in the implementation.
See Also:
  `oldestPossibleFormat(List)`

#### oldestPossibleFormat

    public static int oldestPossibleFormat​(List<? extends PackedObjectInfo> objs)

Return the oldest (most widely understood) index format.

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.

Parameters:
  `objs` - the objects the caller needs to store in the index. Entries will be examined until a format can be conclusively selected.
Returns:
  the index format.
Throws:
  `IllegalArgumentException` - no recognized pack index version can support the supplied objects. This is likely a bug in the implementation.

#### createVersion

    public static PackIndexWriter createVersion​(OutputStream dst,
                                                int version)

Create a new writer instance for a specific index format version.

Parameters:
  `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.
Returns:
  a new writer to output an index file of the requested format to the supplied stream.
Throws:
  `IllegalArgumentException` - the version requested is not supported by this implementation.

#### write

    public void write​(List<? extends PackedObjectInfo> toStore,
                      byte[] packDataChecksum)
               throws IOException

Write all object entries to the index stream.

After writing the stream passed to the factory is flushed but remains open. Callers are always responsible for closing the output stream.

Parameters:
  `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.
Throws:
  `IOException` - an error occurred while writing to the output stream, or this index format cannot store the object data supplied.

#### writeImpl

    protected abstract void writeImpl()
                               throws IOException

Writes the index file to `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.

Throws:
  `IOException` - an error occurred while writing to the output stream, or this index format cannot store the object data supplied.

#### writeTOC

    protected void writeTOC​(int version)
                     throws IOException

Output the version 2 (and later) TOC header, with version number.

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.

Parameters:
  `version` - version number of this index format being written.
Throws:
  `IOException` - an error occurred while writing to the output stream.

#### writeFanOutTable

    protected void writeFanOutTable()
                             throws IOException

Output the standard 256 entry first-level fan-out table.

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.

Throws:
  `IOException` - an error occurred while writing to the output stream.

#### writeChecksumFooter

    protected void writeChecksumFooter()
                                throws IOException

Output the standard two-checksum index footer.

The standard footer contains two checksums (20 byte SHA-1 values):

1. Pack data checksum - taken from the last 20 bytes of the pack file.
2. Index data checksum - checksum of all index bytes written, including the pack data checksum above.

Throws:
  `IOException` - an error occurred while writing to the output stream.