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 and Description
    --- | ---
    `static BHSDCodec` | `BCI5` BCI5 = (5,4): Used for storing branching information in bytecode.
    `static BHSDCodec` | `BRANCH5` BRANCH5 = (5,4,2): Used for storing branching information in bytecode.
    `static BHSDCodec` | `BYTE1` BYTE1 = (1,256): Used for storing plain bytes.
    `static BHSDCodec` | `CHAR3` CHAR3 = (3,128): Used for storing text (UTF-8) strings.
    `static 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 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 BHSDCodec` | `SIGNED5` SIGNED5 = (5,64,1): Used for small signed values.
    `static BHSDCodec` | `UDELTA5` UDELTA5 = (5,64,0,1): Used for the majority of numerical codings where there is a correlated sequence of unsigned values.
    `static BHSDCodec` | `UNSIGNED5` UNSIGNED5 = (5,64): Used for small unsigned values.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Codec()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract int` | `decode(InputStream in)` Decode a sequence of bytes from the given input stream, returning the value as a long.
    `abstract int` | `decode(InputStream in, long last)` Decode 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)` Encode a single value into a sequence of bytes.
    `byte[]` | `encode(int[] ints)` Encode a sequence of integers into a byte array
    `abstract byte[]` | `encode(int value, int last)` Encode 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 Detail

    - #### 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. NB 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 Detail

    - #### Codec

          public Codec()

  - ### Method Detail

    - #### decode

          public abstract int decode(InputStream in)
                              throws IOException,
                                     Pack200Exception

      Decode 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

    - #### encode

          public abstract byte[] encode(int value,
                                        int last)
                                 throws Pack200Exception

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

    - #### encode

          public abstract byte[] encode(int value)
                                 throws Pack200Exception

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

    - #### decode

          public abstract int decode(InputStream in,
                                     long last)
                              throws IOException,
                                     Pack200Exception

      Decode 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 byte[] encode(int[] ints)
                        throws Pack200Exception

      Encode 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

Copyright © 2002–2020 The Apache Software Foundation. All rights reserved.