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.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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

      - 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`

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