org.apache.lucene.codecs
Class CodecUtil

java.lang.Object
  extended by 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
static int CODEC_MAGIC
          Constant to identify the start of a codec header.
 
Method Summary
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 int headerLength(String codec)
          Computes the length of a codec header.
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
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

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


Copyright © 2000-2014 Apache Software Foundation. All Rights Reserved.