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

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