Class Codec

  • Direct Known Subclasses:
    BHSDCodec, PopulationCodec, RunCodec

    public abstract class Codec
    extends java.lang.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 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 Description
      Codec()  
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract int decode​(java.io.InputStream in)
      Decode a sequence of bytes from the given input stream, returning the value as a long.
      abstract int decode​(java.io.InputStream in, long last)
      Decode a sequence of bytes from the given input stream, returning the value as a long.
      int[] decodeInts​(int n, java.io.InputStream in)
      Decodes a sequence of n values from in.
      int[] decodeInts​(int n, java.io.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.
    • Constructor Detail

    • Method Detail

      • decode

        public abstract int decode​(java.io.InputStream in)
                            throws java.io.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:
        java.io.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​(java.io.InputStream in,
                                   long last)
                            throws java.io.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:
        java.io.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,
                                java.io.InputStream in)
                         throws java.io.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:
        java.io.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,
                                java.io.InputStream in,
                                int firstValue)
                         throws java.io.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:
        java.io.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