org.apache.lucene.codecs

Class CodecUtil

java.lang.Object

org.apache.lucene.codecs.CodecUtil

public final class CodecUtil
extends Object

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.

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	CODEC_MAGIC Constant to identify the start of a codec header.
static int	FOOTER_MAGIC Constant to identify the start of a codec footer.

Method Summary

Methods

Modifier and Type	Method and Description
static void	checkEOF(IndexInput in) Deprecated. Use checkFooter(org.apache.lucene.store.ChecksumIndexInput) instead, this should only used for files without checksums
static long	checkFooter(ChecksumIndexInput in) Validates the codec footer previously written by writeFooter(org.apache.lucene.store.IndexOutput).
static int	checkHeader(DataInput in, String codec, int minVersion, int maxVersion) Reads and validates a header previously written with writeHeader(DataOutput, String, int).
static int	checkHeaderNoMagic(DataInput in, String codec, int minVersion, int maxVersion) Like checkHeader(DataInput,String,int,int) except this version assumes the first int has already been read and validated from the input.
static long	checksumEntireFile(IndexInput input) Clones the provided input, reads all bytes from the file, and calls checkFooter(org.apache.lucene.store.ChecksumIndexInput)
static int	footerLength() Computes the length of a codec footer.
static int	headerLength(String codec) Computes the length of a codec header.
static long	retrieveChecksum(IndexInput in) Returns (but does not validate) the checksum previously written by checkFooter(org.apache.lucene.store.ChecksumIndexInput).
static void	writeFooter(IndexOutput out) Writes a codec footer, which records both a checksum algorithm ID and a checksum.
static void	writeHeader(DataOutput out, String codec, int version) Writes a codec header, which records both a string to identify the file and a version number.

Methods inherited from class java.lang.Object

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

Field Detail

CODEC_MAGIC

public static final int CODEC_MAGIC

Constant to identify the start of a codec header.

See Also:

Constant Field Values

FOOTER_MAGIC

public static final int FOOTER_MAGIC

Constant to identify the start of a codec footer.

See Also:

Constant Field Values

Method Detail

writeHeader

public static void writeHeader(DataOutput out,
               String codec,
               int version)
                        throws IOException

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().

CodecHeader --> Magic,CodecName,Version

• Magic --> Uint32. This identifies the start of the header. It is always 1071082519.
• CodecName --> String. This is a string to identify this file.
• Version --> Uint32. 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).

Parameters:

out - Output stream

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

version - Version number

Throws:

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

headerLength

public static int headerLength(String codec)

Computes the length of a codec header.

Parameters:

codec - Codec name.

Returns:

length of the entire codec header.

See Also:

writeHeader(DataOutput, String, int)

checkHeader

public static int checkHeader(DataInput in,
              String codec,
              int minVersion,
              int maxVersion)
                       throws IOException

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

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.

Returns:

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.

Throws:

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:

writeHeader(DataOutput, String, int)

checkHeaderNoMagic

public static int checkHeaderNoMagic(DataInput in,
                     String codec,
                     int minVersion,
                     int maxVersion)
                              throws IOException

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

Throws:

IOException

writeFooter

public static void writeFooter(IndexOutput out)
                        throws IOException

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

CodecFooter --> Magic,AlgorithmID,Checksum

• Magic --> Uint32. This identifies the start of the footer. It is always -1071082520.
• AlgorithmID --> Uint32. This indicates the checksum algorithm used. Currently this is always 0, for zlib-crc32.
• Checksum --> Uint32. The actual checksum value for all previous bytes in the stream, including the bytes from Magic and AlgorithmID.

Parameters:

out - Output stream

Throws:

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

footerLength

public static int footerLength()

Computes the length of a codec footer.

Returns:

length of the entire codec footer.

See Also:

writeFooter(IndexOutput)

checkFooter

public static long checkFooter(ChecksumIndexInput in)
                        throws IOException

Validates the codec footer previously written by writeFooter(org.apache.lucene.store.IndexOutput).

Returns:

actual checksum value

Throws:

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.

retrieveChecksum

public static long retrieveChecksum(IndexInput in)
                             throws IOException

Returns (but does not validate) the checksum previously written by checkFooter(org.apache.lucene.store.ChecksumIndexInput).

Returns:

actual checksum value

Throws:

IOException - if the footer is invalid

checkEOF

@Deprecated
public static void checkEOF(IndexInput in)
                     throws IOException

Deprecated. Use checkFooter(org.apache.lucene.store.ChecksumIndexInput) instead, this should only used for files without checksums

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

Throws:

IOException

checksumEntireFile

public static long checksumEntireFile(IndexInput input)
                               throws IOException

Clones the provided input, reads all bytes from the file, and calls checkFooter(org.apache.lucene.store.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(org.apache.lucene.store.IndexInput).

Throws:

IOException