Class CodecUtil

Utility class for reading and writing versioned headers.

Writing codec headers is useful to ensure that a file is in the format you think it is.

Note

This API is experimental and might change in incompatible ways in the next release.

Inheritance
object
CodecUtil
Inherited Members
Namespace: Lucene.Net.Codecs
Assembly: Lucene.Net.dll
Syntax
public static class CodecUtil

Fields

CODEC_MAGIC

Constant to identify the start of a codec header.

Declaration
public static readonly int CODEC_MAGIC
Field Value
Type Description
int

Constant to identify the start of a codec footer.

Declaration
public static readonly int FOOTER_MAGIC
Field Value
Type Description
int

Methods

CheckEOF(IndexInput)

Checks that the stream is positioned at the end, and throws exception if it is not.

Declaration
[Obsolete("Use CheckFooter(ChecksumIndexInput) instead, this should only used for files without checksums.")]
public static void CheckEOF(IndexInput @in)
Parameters
Type Name Description
IndexInput in

CheckFooter(ChecksumIndexInput)

Validates the codec footer previously written by WriteFooter(IndexOutput).

Declaration
public static long CheckFooter(ChecksumIndexInput @in)
Parameters
Type Name Description
ChecksumIndexInput in
Returns
Type Description
long

Actual checksum value.
Exceptions
Type Condition
IOException

If the footer is invalid, if the checksum does not match, or if in is not properly positioned before the footer at the end of the stream.

CheckHeader(DataInput, string, int, int)

Reads and validates a header previously written with WriteHeader(DataOutput, string, int).

When reading a file, supply the expected codec and an expected version range (minVersion to maxVersion).
Declaration
public static int CheckHeader(DataInput @in, string codec, int minVersion, int maxVersion)
Parameters
Type Name Description
DataInput in

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

The expected codec name.
int minVersion

The minimum supported expected version number.
int maxVersion

The maximum supported expected version number.
Returns
Type Description
int

The actual version found, when a valid header is found that matches codec, with an actual version where minVersion <= actual <= maxVersion. Otherwise an exception is thrown.
Exceptions
Type Condition
CorruptIndexException

If the first four bytes are not CODEC_MAGIC, or if the actual codec found is not codec.
IndexFormatTooOldException

If the actual version is less than minVersion.
IndexFormatTooNewException

If the actual version is greater than maxVersion.
IOException

If there is an I/O error reading from the underlying medium.
See Also

CheckHeaderNoMagic(DataInput, string, int, int)

Like CheckHeader(DataInput, string, int, int) except this version assumes the first int has already been read and validated from the input.

Declaration
public static int CheckHeaderNoMagic(DataInput @in, string codec, int minVersion, int maxVersion)
Parameters
Type Name Description
DataInput in
string codec
int minVersion
int maxVersion
Returns
Type Description
int

ChecksumEntireFile(IndexInput)

Clones the provided input, reads all bytes from the file, and calls CheckFooter(ChecksumIndexInput)

Note that this method may be slow, as it must process the entire file. If you just need to extract the checksum value, call RetrieveChecksum(IndexInput).
Declaration
public static long ChecksumEntireFile(IndexInput input)
Parameters
Type Name Description
IndexInput input
Returns
Type Description
long

FooterLength()

Computes the length of a codec footer.

Declaration
public static int FooterLength()
Returns
Type Description
int

Length of the entire codec footer.
See Also

HeaderLength(string)

Computes the length of a codec header.

Declaration
public static int HeaderLength(string codec)
Parameters
Type Name Description
string codec

Codec name.
Returns
Type Description
int

Length of the entire codec header.
See Also

RetrieveChecksum(IndexInput)

Returns (but does not validate) the checksum previously written by CheckFooter(ChecksumIndexInput).

Declaration
public static long RetrieveChecksum(IndexInput @in)
Parameters
Type Name Description
IndexInput in
Returns
Type Description
long

actual checksum value
Exceptions
Type Condition
IOException

If the footer is invalid.

WriteFooter(IndexOutput)

Writes a codec footer, which records both a checksum algorithm ID and a checksum. This footer can be parsed and validated with CheckFooter(ChecksumIndexInput).

CodecFooter --> Magic,AlgorithmID,Checksum
  • Magic --> Uint32 (WriteInt32(int)). this identifies the start of the footer. It is always FOOTER_MAGIC.
  • AlgorithmID --> Uint32 (WriteInt32(int)). this indicates the checksum algorithm used. Currently this is always 0, for zlib-crc32.
  • Checksum --> Uint32 (WriteInt64(long)). The actual checksum value for all previous bytes in the stream, including the bytes from Magic and AlgorithmID.
Declaration
public static void WriteFooter(IndexOutput @out)
Parameters
Type Name Description
IndexOutput out

Output stream
Exceptions
Type Condition
IOException

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

WriteHeader(DataOutput, string, int)

Writes a codec header, which records both a string to identify the file and a version number. This header can be parsed and validated with CheckHeader(DataInput, string, int, int).

CodecHeader --> Magic,CodecName,Version

Note that the length of a codec header depends only upon the name of the codec, so this length can be computed at any time with HeaderLength(string).
Declaration
public static void WriteHeader(DataOutput @out, string codec, int version)
Parameters
Type Name Description
DataOutput out

Output stream
string codec

String to identify this file. It should be simple ASCII, less than 128 characters in length.
int version

Version number
Exceptions
Type Condition
IOException

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