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

  • Field Details

    • CODEC_MAGIC

      public static final int CODEC_MAGIC
      Constant to identify the start of a codec header.
      See Also:

  • Method Details

    • 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:

    • 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:

    • 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