Writes a codec header for an index file, which records both a string to
identify the format of the file, a version number, and data to identify
the file instance (ID and auxiliary suffix such as generation).

writeIndexHeader

Writes a codec header for an index file, which records both a string to
identify the format of the file, a version number, and data to identify
the file instance (ID and auxiliary suffix such as generation).

Note that the length of an index header depends only upon the
name of the codec and suffix, so this length can be computed at any time
with indexHeaderLength(String,String).

Parameters:

out - Output stream

codec - String to identify the format of this file. It should be simple ASCII,
less than 128 characters in length.

id - Unique identifier for this particular file instance.

suffix - auxiliary suffix information for the file. It should be simple ASCII,
less than 256 characters in length.

version - Version number

Throws:

IOException - If there is an I/O error writing to the underlying medium.

IllegalArgumentException - If the codec name is not simple ASCII, or
is more than 127 characters in length, or if id is invalid,
or if the suffix is not simple ASCII, or more than 255 characters
in length.

When reading a file, supply the expected codec,
expected version range (minVersion to maxVersion),
and object ID and suffix.

Parameters:

in - Input stream, positioned at the point where the
header was previously written. Typically this is located
at the beginning of the file.

codec - The expected codec name.

minVersion - The minimum supported expected version number.

maxVersion - The maximum supported expected version number.

expectedID - The expected object identifier for this file.

expectedSuffix - The expected auxiliary suffix for this file.

Returns:

The actual version found, when a valid header is found
that matches codec, with an actual version
where minVersion <= actual <= maxVersion,
and matching expectedID and expectedSuffix
Otherwise an exception is thrown.

Throws:

CorruptIndexException - If the first four bytes are not
CODEC_MAGIC, or if the actual codec found is
not codec, or if the expectedID
or expectedSuffix do not match.

verifyAndCopyIndexHeader

Expert: verifies the incoming IndexInput has an index header
and that its segment ID matches the expected one, and then copies
that index header into the provided DataOutput. This is
useful when building compound files.

Parameters:

in - Input stream, positioned at the point where the
index header was previously written. Typically this is located
at the beginning of the file.

When a priorException is provided, this method will add a suppressed exception
indicating whether the checksum for the stream passes, fails, or cannot be computed, and
rethrow it. Otherwise it behaves the same as checkFooter(ChecksumIndexInput).