Top Description Fields Constructors Methods
org.apache.commons.compress.harmony.pack200

public final Class BHSDCodec

extends Codec
Class Inheritance
Imports
java.io.EOFException, .IOException, .InputStream, java.util.ArrayList, .Arrays, .List, org.apache.commons.compress.utils.ExactMath
A BHSD codec is a means of encoding integer values as a sequence of bytes or vice versa using a specified "BHSD" encoding mechanism. It uses a variable-length encoding and a modified sign representation such that small numbers are represented as a single byte, whilst larger numbers take more bytes to encode. The number may be signed or unsigned; if it is unsigned, it can be weighted towards positive numbers or equally distributed using a one's complement. The Codec also supports delta coding, where a sequence of numbers is represented as a series of first-order differences. So a delta encoding of the integers [1..10] would be represented as a sequence of 10x1s. This allows the absolute value of a coded integer to fall outside of the 'small number' range, whilst still being encoded as a single byte.

A BHSD codec is configured with four parameters:

B
The maximum number of bytes that each value is encoded as. B must be a value between [1..5]. For a pass-through coding (where each byte is encoded as itself, aka BYTE1, B is 1 (each byte takes a maximum of 1 byte).
H
The radix of the integer. Values are defined as a sequence of values, where value n is multiplied by H^<sup>n</sup>. So the number 1234 may be represented as the sequence 4 3 2 1 with a radix (H) of 10. Note that other permutations are also possible; 43 2 1 will also encode 1234. The co-parameter L is defined as 256-H. This is important because only the last value in a sequence may be < L; all prior values must be > L.
S
Whether the codec represents signed values (or not). This may have 3 values; 0 (unsigned), 1 (signed, one's complement) or 2 (signed, two's complement)
D
Whether the codec represents a delta encoding. This may be 0 (no delta) or 1 (delta encoding). A delta encoding of 1 indicates that values are cumulative; a sequence of 1 1 1 1 1 will represent the sequence 1 2 3 4 5. For this reason, the codec supports two variants of decode; one with and one without a last parameter. If the codec is a non-delta encoding, then the value is ignored if passed. If the codec is a delta encoding, it is a run-time error to call the value without the extra parameter, and the previous value should be returned. (It was designed this way to support multi-threaded access without requiring a new instance of the Codec to be cloned for each use.)

Codecs are notated as (B,H,S,D) and either D or S,D may be omitted if zero. Thus BYTE1 is denoted (1,256,0,0) or (1,256). The toString() method prints out the condensed form of the encoding. Often, the last character in the name (BYTE1, UNSIGNED5) gives a clue as to the B value. Those that start with U (UDELTA5, UNSIGNED5) are unsigned; otherwise, in most cases, they are signed. The presence of the word Delta (DELTA5, UDELTA5) indicates a delta encoding is used.

Field Summary

Modifier and TypeField and Description
private final int
b

The maximum number of bytes in each coding word.

private long
cardinality

private final int
d

Whether delta encoding is used (0=false,1=true).

private final int
h

The radix of the encoding.

private final int
l

The co-parameter of h; 256-h.

private final long
largest

private final long[]
powers

radix^i powers

private final int
s

Represents signed numbers or not, 0 (unsigned), 1 (signed, one's complement) or 2 (signed, two's complement).

private final long
smallest

Inherited from org.apache.commons.compress.harmony.pack200.Codec:
BCI5BRANCH5BYTE1CHAR3DELTA5lastBandLengthMDELTA5SIGNED5UDELTA5UNSIGNED5

Constructor Summary

AccessConstructor and Description
public
BHSDCodec(final int
the maximum number of bytes that a value can be encoded as [1..5]
b, final int
the radix of the encoding [1..256]
h)

Constructs an unsigned, non-delta Codec with the given B and H values.

public
BHSDCodec(final int
the maximum number of bytes that a value can be encoded as [1..5]
b, final int
the radix of the encoding [1..256]
h, final int
whether the encoding represents signed numbers (s=0 is unsigned; s=1 is signed with 1s complement; s=2 is signed with ?)
s)

Constructs a non-delta Codec with the given B, H and S values.

public
BHSDCodec(final int
the maximum number of bytes that a value can be encoded as [1..5]
b, final int
the radix of the encoding [1..256]
h, final int
whether the encoding represents signed numbers (s=0 is unsigned; s=1 is signed with 1s complement; s=2 is signed with ?)
s, final int
whether this is a delta encoding (d=0 is non-delta; d=1 is delta)
d)

Constructs a Codec with the given B, H, S and D values.

Method Summary

Modifier and TypeMethod and Description
private long
calculateLargest()

private long
calculateSmallest()

public long

Returns:

the cardinality of this codec
cardinality()

Returns the cardinality of this codec; that is, the number of distinct values that it can contain.

public int
decode(final InputStream
the input stream to read from
in)

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.decode.

Decodes a sequence of bytes from the given input stream, returning the value as a long.
public int
decode(final InputStream
the input stream to read from
in, final long
the previous value read, which must be supplied if the codec is a delta encoding
last)

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.decode.

Decodes a sequence of bytes from the given input stream, returning the value as a long.
public int[]
decodeInts(final int
the number of values to decode
n, final InputStream
the input stream to read from
in)

Overrides org.apache.commons.compress.harmony.pack200.Codec.decodeInts.

Decodes a sequence of n values from in.
public int[]
decodeInts(final int
the number of values to decode
n, final InputStream
the input stream to read from
in, final int
the first value in the band if it has already been read
firstValue)

Overrides org.apache.commons.compress.harmony.pack200.Codec.decodeInts.

Decodes a sequence of n values from in.
public byte[]
encode(final int
the value to encode
value)

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.encode.

Encodes a single value into a sequence of bytes.
public byte[]
encode(final int
the value to encode
value, final int
the previous value encoded (for delta encodings)
last)

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.encode.

Encodes a single value into a sequence of bytes.
public boolean

Returns:

true if the encoding can encode this value
encodes(final long
the value to check
value)

True if this encoding can code the given value

public boolean
equals(final Object
the reference object with which to compare.
o)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.
public int

Returns:

the b
getB()

Gets the B.

public int

Returns:

the h
getH()

Gets the H.

public int

Returns:

the l
getL()

Gets the L.

public int

Returns:

the s
getS()

Gets the S.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for the object.
public boolean

Returns:

true if this codec is a delta codec
isDelta()

Returns true if this codec is a delta codec

public boolean

Returns:

true if this codec is a signed codec
isSigned()

Returns true if this codec is a signed codec

public long

Returns:

the largest value that this codec can represent.
largest()

Returns the largest value that this codec can represent.

public long

Returns:

the smallest value that this codec can represent.
smallest()

Returns the smallest value that this codec can represent.

public String
toString()

Overrides java.lang.Object.toString.

Returns the codec in the form (1,256) or (1,64,1,1).
Inherited from org.apache.commons.compress.harmony.pack200.Codec:
checkencode

Field Detail

bback to summary
private final int b

The maximum number of bytes in each coding word. B must be a value between [1..5]. For a pass-through coding (where each byte is encoded as itself, aka BYTE1, B is 1 (each byte takes a maximum of 1 byte).

cardinalityback to summary
private long cardinality
dback to summary
private final int d

Whether delta encoding is used (0=false,1=true).

hback to summary
private final int h

The radix of the encoding.

lback to summary
private final int l

The co-parameter of h; 256-h.

largestback to summary
private final long largest
powersback to summary
private final long[] powers

radix^i powers

sback to summary
private final int s

Represents signed numbers or not, 0 (unsigned), 1 (signed, one's complement) or 2 (signed, two's complement).

smallestback to summary
private final long smallest

Constructor Detail

BHSDCodecback to summary
public BHSDCodec(final int b, final int h)

Constructs an unsigned, non-delta Codec with the given B and H values.

Parameters
b:int

the maximum number of bytes that a value can be encoded as [1..5]

h:int

the radix of the encoding [1..256]

BHSDCodecback to summary
public BHSDCodec(final int b, final int h, final int s)

Constructs a non-delta Codec with the given B, H and S values.

Parameters
b:int

the maximum number of bytes that a value can be encoded as [1..5]

h:int

the radix of the encoding [1..256]

s:int

whether the encoding represents signed numbers (s=0 is unsigned; s=1 is signed with 1s complement; s=2 is signed with ?)

BHSDCodecback to summary
public BHSDCodec(final int b, final int h, final int s, final int d)

Constructs a Codec with the given B, H, S and D values.

Parameters
b:int

the maximum number of bytes that a value can be encoded as [1..5]

h:int

the radix of the encoding [1..256]

s:int

whether the encoding represents signed numbers (s=0 is unsigned; s=1 is signed with 1s complement; s=2 is signed with ?)

d:int

whether this is a delta encoding (d=0 is non-delta; d=1 is delta)

Method Detail

calculateLargestback to summary
private long calculateLargest()
calculateSmallestback to summary
private long calculateSmallest()
cardinalityback to summary
public long cardinality()

Returns the cardinality of this codec; that is, the number of distinct values that it can contain.

Returns:long

the cardinality of this codec

decodeback to summary
public int decode(final InputStream in) throws IOException, Pack200Exception

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.decode.

Doc from org.apache.commons.compress.harmony.pack200.Codec.decode.

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:InputStream

the input stream to read from

Returns:int

the value as a long

Annotations
@Override
Exceptions
IOException:
if there is a problem reading from the underlying input stream
Pack200Exception:
if the encoding is a delta encoding
decodeback to summary
public int decode(final InputStream in, final long last) throws IOException, Pack200Exception

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.decode.

Doc from org.apache.commons.compress.harmony.pack200.Codec.decode.

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:InputStream

the input stream to read from

last:long

the previous value read, which must be supplied if the codec is a delta encoding

Returns:int

the value as a long

Annotations
@Override
Exceptions
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
decodeIntsback to summary
public int[] decodeInts(final int n, final InputStream in) throws IOException, Pack200Exception

Overrides org.apache.commons.compress.harmony.pack200.Codec.decodeInts.

Doc from org.apache.commons.compress.harmony.pack200.Codec.decodeInts.

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:int

the number of values to decode

in:InputStream

the input stream to read from

Returns:int[]

an array of int values corresponding to values decoded

Annotations
@Override
Exceptions
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
decodeIntsback to summary
public int[] decodeInts(final int n, final InputStream in, final int firstValue) throws IOException, Pack200Exception

Overrides org.apache.commons.compress.harmony.pack200.Codec.decodeInts.

Doc from org.apache.commons.compress.harmony.pack200.Codec.decodeInts.

Decodes a sequence of n values from in.

Parameters
n:int

the number of values to decode

in:InputStream

the input stream to read from

firstValue:int

the first value in the band if it has already been read

Returns:int[]

an array of int values corresponding to values decoded, with firstValue as the first value in the array.

Annotations
@Override
Exceptions
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
encodeback to summary
public byte[] encode(final int value) throws Pack200Exception

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.encode.

Doc from org.apache.commons.compress.harmony.pack200.Codec.encode.

Encodes a single value into a sequence of bytes. Note that this method can only be used for non-delta encodings.

Parameters
value:int

the value to encode

Returns:byte[]

the encoded bytes

Annotations
@Override
Exceptions
Pack200Exception:
TODO
encodeback to summary
public byte[] encode(final int value, final int last) throws Pack200Exception

Implements abstract org.apache.commons.compress.harmony.pack200.Codec.encode.

Doc from org.apache.commons.compress.harmony.pack200.Codec.encode.

Encodes a single value into a sequence of bytes.

Parameters
value:int

the value to encode

last:int

the previous value encoded (for delta encodings)

Returns:byte[]

the encoded bytes

Annotations
@Override
Exceptions
Pack200Exception:
TODO
encodesback to summary
public boolean encodes(final long value)

True if this encoding can code the given value

Parameters
value:long

the value to check

Returns:boolean

true if the encoding can encode this value

equalsback to summary
public boolean equals(final Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getBback to summary
public int getB()

Gets the B.

Returns:int

the b

getHback to summary
public int getH()

Gets the H.

Returns:int

the h

getLback to summary
public int getL()

Gets the L.

Returns:int

the l

getSback to summary
public int getS()

Gets the S.

Returns:int

the s

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object.

Annotations
@Override
isDeltaback to summary
public boolean isDelta()

Returns true if this codec is a delta codec

Returns:boolean

true if this codec is a delta codec

isSignedback to summary
public boolean isSigned()

Returns true if this codec is a signed codec

Returns:boolean

true if this codec is a signed codec

largestback to summary
public long largest()

Returns the largest value that this codec can represent.

Returns:long

the largest value that this codec can represent.

smallestback to summary
public long smallest()

Returns the smallest value that this codec can represent.

Returns:long

the smallest value that this codec can represent.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the codec in the form (1,256) or (1,64,1,1). Note that trailing zero fields are not shown.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations
@Override