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

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

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

FOOTER_MAGIC

Constant to identify the start of a codec footer.

Declaration

public static readonly int FOOTER_MAGIC

Field Value

Type	Description
System.Int32

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
System.Int64	Actual checksum value.

Exceptions

Type	Condition
System.IO.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, 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.
System.IO.IOException	If there is an I/O error reading from the underlying medium.

See Also

WriteHeader(DataOutput, String, Int32)

CheckHeaderNoMagic(DataInput, String, Int32, Int32)

Like CheckHeader(DataInput, String, Int32, Int32) except this version assumes the first System.Int32 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

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

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

WriteFooter(IndexOutput)

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

WriteHeader(DataOutput, String, Int32)

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

Exceptions

Type	Condition
System.IO.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(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

Exceptions

Type	Condition
System.IO.IOException	If there is an I/O error writing to the underlying medium.

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

• Magic --> Uint32 (WriteInt32(Int32)). this identifies the start of the header. It is always CODEC_MAGIC.
• CodecName --> String (WriteString(String)). this is a string to identify this file.
• Version --> Uint32 (WriteInt32(Int32)). Records the version of the file.

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

Exceptions

Type	Condition
System.IO.IOException	If there is an I/O error writing to the underlying medium.