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.

This is a Lucene.NET EXPERIMENTAL API, use at your own risk
Inheritance
System.Object
CodecUtil
Namespace: Lucene.Net.Codecs
Assembly: Lucene.Net.dll
Syntax
public sealed class CodecUtil : object

Fields

| Improve this Doc View Source

CODEC_MAGIC

Constant to identify the start of a codec header.

Declaration
public static readonly int CODEC_MAGIC
Field Value
Type Description
System.Int32
| Improve this Doc View Source

Constant to identify the start of a codec footer.

Declaration
public static readonly int FOOTER_MAGIC
Field Value
Type Description
System.Int32

Methods

| Improve this Doc View Source

CheckEOF(IndexInput)

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

Declaration
public static void CheckEOF(IndexInput in)
Parameters
Type Name Description
IndexInput in
| Improve this Doc View Source

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
System.Int64

Actual checksum value.

| Improve this Doc View Source

CheckHeader(DataInput, String, Int32, Int32)

Reads and validates a header previously written with WriteHeader(DataOutput, String, Int32).

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.

System.String codec

The expected codec name.

System.Int32 minVersion

The minimum supported expected version number.

System.Int32 maxVersion

The maximum supported expected version number.

Returns
Type Description
System.Int32

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.

See Also
| Improve this Doc View Source

CheckHeaderNoMagic(DataInput, String, Int32, Int32)

Like CheckHeader(DataInput, String, Int32, Int32) except this version assumes the first 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
System.String codec
System.Int32 minVersion
System.Int32 maxVersion
Returns
Type Description
System.Int32
| Improve this Doc View Source

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
System.Int64
| Improve this Doc View Source

FooterLength()

Computes the length of a codec footer.

Declaration
public static int FooterLength()
Returns
Type Description
System.Int32

Length of the entire codec footer.

See Also
| Improve this Doc View Source

HeaderLength(String)

Computes the length of a codec header.

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

Codec name.

Returns
Type Description
System.Int32

Length of the entire codec header.

See Also
| Improve this Doc View Source

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
System.Int64

actual checksum value

| Improve this Doc View Source

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(Int32)). this identifies the start of the footer. It is always FOOTER_MAGIC.
  • AlgorithmID --> Uint32 (WriteInt32(Int32)). this indicates the checksum algorithm used. Currently this is always 0, for zlib-crc32.
  • Checksum --> Uint32 (WriteInt64(Int64)). 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

| Improve this Doc View Source

WriteHeader(DataOutput, String, Int32)

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, Int32, Int32).

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

System.String codec

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

System.Int32 version

Version number