Package org.apache.commons.compress.harmony.pack200

# Class Codec

java.lang.Object
org.apache.commons.compress.harmony.pack200.Codec

Direct Known Subclasses:
  `BHSDCodec`, `PopulationCodec`, `RunCodec`

public abstract class Codec extends Object
A Codec allows a sequence of bytes to be decoded into integer values (or vice versa).

There are a number of standard Codecs (`UDELTA5`, `UNSIGNED5`, `BYTE1`, `CHAR3`) that are used in the implementation of many bands; but there are a variety of other ones, and indeed the specification assumes that other combinations of values can result in more specific and efficient formats. There are also a sequence of canonical encodings defined by the Pack200 specification, which allow a Codec to be referred to by canonical number. `CodecEncoding.getCodec(int, InputStream, Codec)`)

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final BHSDCodec`
  `BCI5`
  BCI5 = (5,4): Used for storing branching information in bytecode.
  `static final BHSDCodec`
  `BRANCH5`
  BRANCH5 = (5,4,2): Used for storing branching information in bytecode.
  `static final BHSDCodec`
  `BYTE1`
  BYTE1 = (1,256): Used for storing plain bytes.
  `static final BHSDCodec`
  `CHAR3`
  CHAR3 = (3,128): Used for storing text (UTF-8) strings.
  `static final BHSDCodec`
  `DELTA5`
  DELTA5 = (5,64,1,1): Used for the majority of numerical codings where there is a correlated sequence of signed values.
  `int`
  `lastBandLength`
  `static final BHSDCodec`
  `MDELTA5`
  MDELTA5 = (5,64,2,1): Used for the majority of numerical codings where there is a correlated sequence of signed values, but where most of them are expected to be non-negative.
  `static final BHSDCodec`
  `SIGNED5`
  SIGNED5 = (5,64,1): Used for small signed values.
  `static final BHSDCodec`
  `UDELTA5`
  UDELTA5 = (5,64,0,1): Used for the majority of numerical codings where there is a correlated sequence of unsigned values.
  `static final BHSDCodec`
  `UNSIGNED5`
  UNSIGNED5 = (5,64): Used for small unsigned values.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Codec()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract int`
  `decode(InputStream in)`
  Decodes a sequence of bytes from the given input stream, returning the value as a long.
  `abstract int`
  `decode(InputStream in, long last)`
  Decodes a sequence of bytes from the given input stream, returning the value as a long.
  `int[]`
  `decodeInts(int n, InputStream in)`
  Decodes a sequence of `n` values from `in`.
  `int[]`
  `decodeInts(int n, InputStream in, int firstValue)`
  Decodes a sequence of `n` values from `in`.
  `abstract byte[]`
  `encode(int value)`
  Encodes a single value into a sequence of bytes.
  `byte[]`
  `encode(int[] ints)`
  Encodes a sequence of integers into a byte array.
  `abstract byte[]`
  `encode(int value, int last)`
  Encodes a single value into a sequence of bytes.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### BCI5

    public static final BHSDCodec BCI5
    BCI5 = (5,4): Used for storing branching information in bytecode.

  - ### BRANCH5

    public static final BHSDCodec BRANCH5
    BRANCH5 = (5,4,2): Used for storing branching information in bytecode.

  - ### BYTE1

    public static final BHSDCodec BYTE1
    BYTE1 = (1,256): Used for storing plain bytes.

  - ### CHAR3

    public static final BHSDCodec CHAR3
    CHAR3 = (3,128): Used for storing text (UTF-8) strings. This isn't quite the same as UTF-8, but has similar properties; ASCII characters < 127 are stored in a single byte.

  - ### DELTA5

    public static final BHSDCodec DELTA5
    DELTA5 = (5,64,1,1): Used for the majority of numerical codings where there is a correlated sequence of signed values.

  - ### MDELTA5

    public static final BHSDCodec MDELTA5
    MDELTA5 = (5,64,2,1): Used for the majority of numerical codings where there is a correlated sequence of signed values, but where most of them are expected to be non-negative.

  - ### SIGNED5

    public static final BHSDCodec SIGNED5
    SIGNED5 = (5,64,1): Used for small signed values.

  - ### UDELTA5

    public static final BHSDCodec UDELTA5
    UDELTA5 = (5,64,0,1): Used for the majority of numerical codings where there is a correlated sequence of unsigned values.

  - ### UNSIGNED5

    public static final BHSDCodec UNSIGNED5
    UNSIGNED5 = (5,64): Used for small unsigned values.

  - ### lastBandLength

    public int lastBandLength

- ## Constructor Details

  - ### Codec

    public Codec()

- ## Method Details

  - ### decode

    public abstract int decode(InputStream in) throws IOException, Pack200Exception
    Decodes a sequence of bytes from the given input stream, returning the value as a long. Note that this method can only be applied for non-delta encodings.
    Parameters:
      `in` - the input stream to read from
    Returns:
      the value as a long
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if the encoding is a delta encoding

  - ### decode

    public abstract int decode(InputStream in, long last) throws IOException, Pack200Exception
    Decodes a sequence of bytes from the given input stream, returning the value as a long. If this encoding is a delta encoding (d=1) then the previous value must be passed in as a parameter. If it is a non-delta encoding, then it does not matter what value is passed in, so it makes sense for the value to be passed in by default using code similar to:

         long last = 0;
         while (condition) {
             last = codec.decode(in, last);
             // do something with last
         }

    Parameters:
      `in` - the input stream to read from
      `last` - the previous value read, which must be supplied if the codec is a delta encoding
    Returns:
      the value as a long
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if there is a problem decoding the value or that the value is invalid

  - ### decodeInts

    public int[] decodeInts(int n, InputStream in) throws IOException, Pack200Exception
    Decodes a sequence of `n` values from `in`. This should probably be used in most cases, since some codecs (such as `PopulationCodec`) only work when the number of values to be read is known.
    Parameters:
      `n` - the number of values to decode
      `in` - the input stream to read from
    Returns:
      an array of `int` values corresponding to values decoded
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if there is a problem decoding the value or that the value is invalid

  - ### decodeInts

    public int[] decodeInts(int n, InputStream in, int firstValue) throws IOException, Pack200Exception
    Decodes a sequence of `n` values from `in`.
    Parameters:
      `n` - the number of values to decode
      `in` - the input stream to read from
      `firstValue` - the first value in the band if it has already been read
    Returns:
      an array of `int` values corresponding to values decoded, with firstValue as the first value in the array.
    Throws:
      `IOException` - if there is a problem reading from the underlying input stream
      `Pack200Exception` - if there is a problem decoding the value or that the value is invalid

  - ### encode

    public abstract byte[] encode(int value) throws Pack200Exception
    Encodes a single value into a sequence of bytes. Note that this method can only be used for non-delta encodings.
    Parameters:
      `value` - the value to encode.
    Returns:
      the encoded bytes.
    Throws:
      `Pack200Exception` - If a Pack200 semantic error occurs.

  - ### encode

    public abstract byte[] encode(int value, int last) throws Pack200Exception
    Encodes a single value into a sequence of bytes.
    Parameters:
      `value` - the value to encode.
      `last` - the previous value encoded (for delta encodings).
    Returns:
      the encoded bytes.
    Throws:
      `Pack200Exception` - If a Pack200 semantic error occurs.

  - ### encode

    public byte[] encode(int[] ints) throws Pack200Exception
    Encodes a sequence of integers into a byte array.
    Parameters:
      `ints` - the values to encode.
    Returns:
      byte[] encoded bytes.
    Throws:
      `Pack200Exception` - if there is a problem encoding any of the values.