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
`static int` `CODEC_MAGIC` Constant to identify the start of a codec header.

### Method Summary

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