com.amazon.carbonado.raw
Class KeyEncoder

java.lang.Object
  com.amazon.carbonado.raw.KeyEncoder

public class KeyEncoder
extends Object

A very low-level class that supports encoding of primitive data into unique, sortable byte array keys. If the data to encode is of a variable size, then it is written in base-32768, using only byte values 32..223. This allows special values such as nulls and terminators to be unambiguously encoded. Terminators for variable data can be encoded using 1 for ascending order and 254 for descending order. Nulls can be encoded as 255 for high ordering and 0 for low ordering.

Author:

Brian S O'Neill

See Also:

KeyDecoder, DataEncoder

Constructor Summary

KeyEncoder()

Method Summary

static int	calculateEncodedLength(BigDecimal value) Returns the amount of bytes required to encode a BigDecimal.
static int	calculateEncodedLength(BigInteger value) Returns the amount of bytes required to encode a BigInteger.
static int	calculateEncodedLength(byte[] value) Returns the amount of bytes required to encode a byte array of the given length.
static int	calculateEncodedLength(byte[] value, int valueOffset, int valueLength) Returns the amount of bytes required to encode the given byte array.
static int	calculateEncodedStringLength(String value) Returns the amount of bytes required to encode the given String.
static int	encode(BigDecimal value, byte[] dst, int dstOffset) Encodes the given optional BigDecimal into a variable amount of bytes.
static int	encode(BigInteger value, byte[] dst, int dstOffset) Encodes the given optional BigInteger into a variable amount of bytes.
static int	encode(byte[] value, byte[] dst, int dstOffset) Encodes the given optional unsigned byte array into a variable amount of bytes.
static int	encode(byte[] value, int valueOffset, int valueLength, byte[] dst, int dstOffset) Encodes the given optional unsigned byte array into a variable amount of bytes.
static int	encode(String value, byte[] dst, int dstOffset) Encodes the given optional String into a variable amount of bytes.
static int	encodeDesc(BigDecimal value, byte[] dst, int dstOffset) Encodes the given optional BigDecimal into a variable amount of bytes for descending order.
static int	encodeDesc(BigInteger value, byte[] dst, int dstOffset) Encodes the given optional BigInteger into a variable amount of bytes for descending order.
static void	encodeDesc(boolean value, byte[] dst, int dstOffset) Encodes the given boolean into exactly 1 byte for descending order.
static void	encodeDesc(Boolean value, byte[] dst, int dstOffset) Encodes the given Boolean object into exactly 1 byte for descending order.
static int	encodeDesc(byte[] value, byte[] dst, int dstOffset) Encodes the given optional unsigned byte array into a variable amount of bytes for descending order.
static int	encodeDesc(byte[] value, int valueOffset, int valueLength, byte[] dst, int dstOffset) Encodes the given optional unsigned byte array into a variable amount of bytes for descending order.
static void	encodeDesc(byte value, byte[] dst, int dstOffset) Encodes the given signed byte into exactly 1 byte for descending order.
static int	encodeDesc(Byte value, byte[] dst, int dstOffset) Encodes the given signed Byte object into exactly 1 or 2 bytes for descending order.
static int	encodeDesc(Character value, byte[] dst, int dstOffset) Encodes the given Character object into exactly 1 or 3 bytes for descending order.
static void	encodeDesc(char value, byte[] dst, int dstOffset) Encodes the given character into exactly 2 bytes for descending order.
static void	encodeDesc(double value, byte[] dst, int dstOffset) Encodes the given double into exactly 8 bytes for descending order.
static void	encodeDesc(Double value, byte[] dst, int dstOffset) Encodes the given Double object into exactly 8 bytes for descending order.
static void	encodeDesc(float value, byte[] dst, int dstOffset) Encodes the given float into exactly 4 bytes for descending order.
static void	encodeDesc(Float value, byte[] dst, int dstOffset) Encodes the given Float object into exactly 4 bytes for descending order.
static void	encodeDesc(int value, byte[] dst, int dstOffset) Encodes the given signed integer into exactly 4 bytes for descending order.
static int	encodeDesc(Integer value, byte[] dst, int dstOffset) Encodes the given signed Integer object into exactly 1 or 5 bytes for descending order.
static void	encodeDesc(long value, byte[] dst, int dstOffset) Encodes the given signed long into exactly 8 bytes for descending order.
static int	encodeDesc(Long value, byte[] dst, int dstOffset) Encodes the given signed Long object into exactly 1 or 9 bytes for descending order.
static void	encodeDesc(short value, byte[] dst, int dstOffset) Encodes the given signed short into exactly 2 bytes for descending order.
static int	encodeDesc(Short value, byte[] dst, int dstOffset) Encodes the given signed Short object into exactly 1 or 3 bytes for descending order.
static int	encodeDesc(String value, byte[] dst, int dstOffset) Encodes the given optional String into a variable amount of bytes for descending order.
static byte[]	encodeSingleDesc(byte[] value) Encodes the given byte array for use when there is only a single required property, descending order, whose type is a byte array.
static byte[]	encodeSingleDesc(byte[] value, int prefixPadding, int suffixPadding) Encodes the given byte array for use when there is only a single required property, descending order, whose type is a byte array.
static byte[]	encodeSingleNullableDesc(byte[] value) Encodes the given byte array for use when there is only a single nullable property, descending order, whose type is a byte array.
static byte[]	encodeSingleNullableDesc(byte[] value, int prefixPadding, int suffixPadding) Encodes the given byte array for use when there is only a single nullable property, descending order, whose type is a byte array.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyEncoder

public KeyEncoder()

Method Detail

encodeDesc

public static void encodeDesc(int value,
                              byte[] dst,
                              int dstOffset)

Encodes the given signed integer into exactly 4 bytes for descending order.

Parameters:

value - signed integer value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static int encodeDesc(Integer value,
                             byte[] dst,
                             int dstOffset)

Encodes the given signed Integer object into exactly 1 or 5 bytes for descending order. If the Integer object is never expected to be null, consider encoding as an int primitive.

Parameters:

value - optional signed Integer value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static void encodeDesc(long value,
                              byte[] dst,
                              int dstOffset)

Encodes the given signed long into exactly 8 bytes for descending order.

Parameters:

value - signed long value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static int encodeDesc(Long value,
                             byte[] dst,
                             int dstOffset)

Encodes the given signed Long object into exactly 1 or 9 bytes for descending order. If the Long object is never expected to be null, consider encoding as a long primitive.

Parameters:

value - optional signed Long value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static void encodeDesc(byte value,
                              byte[] dst,
                              int dstOffset)

Encodes the given signed byte into exactly 1 byte for descending order.

Parameters:

value - signed byte value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static int encodeDesc(Byte value,
                             byte[] dst,
                             int dstOffset)

Encodes the given signed Byte object into exactly 1 or 2 bytes for descending order. If the Byte object is never expected to be null, consider encoding as a byte primitive.

Parameters:

value - optional signed Byte value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static void encodeDesc(short value,
                              byte[] dst,
                              int dstOffset)

Encodes the given signed short into exactly 2 bytes for descending order.

Parameters:

value - signed short value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static int encodeDesc(Short value,
                             byte[] dst,
                             int dstOffset)

Encodes the given signed Short object into exactly 1 or 3 bytes for descending order. If the Short object is never expected to be null, consider encoding as a short primitive.

Parameters:

value - optional signed Short value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static void encodeDesc(char value,
                              byte[] dst,
                              int dstOffset)

Encodes the given character into exactly 2 bytes for descending order.

Parameters:

value - character value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static int encodeDesc(Character value,
                             byte[] dst,
                             int dstOffset)

Encodes the given Character object into exactly 1 or 3 bytes for descending order. If the Character object is never expected to be null, consider encoding as a char primitive.

Parameters:

value - optional Character value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static void encodeDesc(boolean value,
                              byte[] dst,
                              int dstOffset)

Encodes the given boolean into exactly 1 byte for descending order.

Parameters:

value - boolean value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static void encodeDesc(Boolean value,
                              byte[] dst,
                              int dstOffset)

Encodes the given Boolean object into exactly 1 byte for descending order.

Parameters:

value - optional Boolean value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static void encodeDesc(float value,
                              byte[] dst,
                              int dstOffset)

Encodes the given float into exactly 4 bytes for descending order.

Parameters:

value - float value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static void encodeDesc(Float value,
                              byte[] dst,
                              int dstOffset)

Encodes the given Float object into exactly 4 bytes for descending order. A non-canonical NaN value is used to represent null.

Parameters:

value - optional Float value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static void encodeDesc(double value,
                              byte[] dst,
                              int dstOffset)

Encodes the given double into exactly 8 bytes for descending order.

Parameters:

value - double value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encodeDesc

public static void encodeDesc(Double value,
                              byte[] dst,
                              int dstOffset)

Encodes the given Double object into exactly 8 bytes for descending order. A non-canonical NaN value is used to represent null.

Parameters:

value - optional Double value to encode

dst - destination for encoded bytes

dstOffset - offset into destination array

encode

public static int encode(BigInteger value,
                         byte[] dst,
                         int dstOffset)

Encodes the given optional BigInteger into a variable amount of bytes. If the BigInteger is null, exactly 1 byte is written. Otherwise, the amount written can be determined by calling calculateEncodedLength.

Parameters:

value - BigInteger value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

Since:

1.2

encodeDesc

public static int encodeDesc(BigInteger value,
                             byte[] dst,
                             int dstOffset)

Encodes the given optional BigInteger into a variable amount of bytes for descending order. If the BigInteger is null, exactly 1 byte is written. Otherwise, the amount written can be determined by calling calculateEncodedLength.

Parameters:

value - BigInteger value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

Since:

1.2

calculateEncodedLength

public static int calculateEncodedLength(BigInteger value)

Returns the amount of bytes required to encode a BigInteger.

Parameters:

value - BigInteger value to encode, may be null

Returns:

amount of bytes needed to encode

Since:

1.2

encode

public static int encode(BigDecimal value,
                         byte[] dst,
                         int dstOffset)

Encodes the given optional BigDecimal into a variable amount of bytes. If the BigDecimal is null, exactly 1 byte is written. Otherwise, the amount written can be determined by calling calculateEncodedLength.

Note: It is recommended that value be normalized by stripping trailing zeros. This makes searching by value much simpler.

Parameters:

value - BigDecimal value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

Since:

1.2

encodeDesc

public static int encodeDesc(BigDecimal value,
                             byte[] dst,
                             int dstOffset)

Encodes the given optional BigDecimal into a variable amount of bytes for descending order. If the BigDecimal is null, exactly 1 byte is written. Otherwise, the amount written can be determined by calling calculateEncodedLength.

Note: It is recommended that value be normalized by stripping trailing zeros. This makes searching by value much simpler.

Parameters:

value - BigDecimal value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

Since:

1.2

calculateEncodedLength

public static int calculateEncodedLength(BigDecimal value)

Returns the amount of bytes required to encode a BigDecimal.

Note: It is recommended that value be normalized by stripping trailing zeros. This makes searching by value much simpler.

Parameters:

value - BigDecimal value to encode, may be null

Returns:

amount of bytes needed to encode

Since:

1.2

encode

public static int encode(byte[] value,
                         byte[] dst,
                         int dstOffset)

Encodes the given optional unsigned byte array into a variable amount of bytes. If the byte array is null, exactly 1 byte is written. Otherwise, the amount written can be determined by calling calculateEncodedLength.

Parameters:

value - byte array value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encode

public static int encode(byte[] value,
                         int valueOffset,
                         int valueLength,
                         byte[] dst,
                         int dstOffset)

Encodes the given optional unsigned byte array into a variable amount of bytes. If the byte array is null, exactly 1 byte is written. Otherwise, the amount written can be determined by calling calculateEncodedLength.

Parameters:

value - byte array value to encode, may be null

valueOffset - offset into byte array

valueLength - length of data in byte array

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static int encodeDesc(byte[] value,
                             byte[] dst,
                             int dstOffset)

Encodes the given optional unsigned byte array into a variable amount of bytes for descending order. If the byte array is null, exactly 1 byte is written. Otherwise, the amount written is determined by calling calculateEncodedLength.

Parameters:

value - byte array value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static int encodeDesc(byte[] value,
                             int valueOffset,
                             int valueLength,
                             byte[] dst,
                             int dstOffset)

Encodes the given optional unsigned byte array into a variable amount of bytes for descending order. If the byte array is null, exactly 1 byte is written. Otherwise, the amount written is determined by calling calculateEncodedLength.

Parameters:

value - byte array value to encode, may be null

valueOffset - offset into byte array

valueLength - length of data in byte array

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

calculateEncodedLength

public static int calculateEncodedLength(byte[] value)

Returns the amount of bytes required to encode a byte array of the given length.

Parameters:

value - byte array value to encode, may be null

Returns:

amount of bytes needed to encode

calculateEncodedLength

public static int calculateEncodedLength(byte[] value,
                                         int valueOffset,
                                         int valueLength)

Returns the amount of bytes required to encode the given byte array.

Parameters:

value - byte array value to encode, may be null

valueOffset - offset into byte array

valueLength - length of data in byte array

Returns:

amount of bytes needed to encode

encode

public static int encode(String value,
                         byte[] dst,
                         int dstOffset)

Encodes the given optional String into a variable amount of bytes. The amount written can be determined by calling calculateEncodedStringLength.

Strings are encoded in a fashion similar to UTF-8, in that ASCII characters are usually written in one byte. This encoding is more efficient than UTF-8, but it isn't compatible with UTF-8.

Parameters:

value - String value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

encodeDesc

public static int encodeDesc(String value,
                             byte[] dst,
                             int dstOffset)

Encodes the given optional String into a variable amount of bytes for descending order. The amount written can be determined by calling calculateEncodedStringLength.

Strings are encoded in a fashion similar to UTF-8, in that ASCII characters are usually written in one byte. This encoding is more efficient than UTF-8, but it isn't compatible with UTF-8.

Parameters:

value - String value to encode, may be null

dst - destination for encoded bytes

dstOffset - offset into destination array

Returns:

amount of bytes written

calculateEncodedStringLength

public static int calculateEncodedStringLength(String value)

Returns the amount of bytes required to encode the given String.

Parameters:

value - String to encode, may be null

encodeSingleDesc

public static byte[] encodeSingleDesc(byte[] value)

Encodes the given byte array for use when there is only a single required property, descending order, whose type is a byte array. The original byte array is returned if the length is zero.

encodeSingleDesc

public static byte[] encodeSingleDesc(byte[] value,
                                      int prefixPadding,
                                      int suffixPadding)

Encodes the given byte array for use when there is only a single required property, descending order, whose type is a byte array. The original byte array is returned if the length and padding lengths are zero.

Parameters:

prefixPadding - amount of extra bytes to allocate at start of encoded byte array

suffixPadding - amount of extra bytes to allocate at end of encoded byte array

encodeSingleNullableDesc

public static byte[] encodeSingleNullableDesc(byte[] value)

Encodes the given byte array for use when there is only a single nullable property, descending order, whose type is a byte array.

encodeSingleNullableDesc

public static byte[] encodeSingleNullableDesc(byte[] value,
                                              int prefixPadding,
                                              int suffixPadding)

Encodes the given byte array for use when there is only a single nullable property, descending order, whose type is a byte array.

Parameters:

prefixPadding - amount of extra bytes to allocate at start of encoded byte array

suffixPadding - amount of extra bytes to allocate at end of encoded byte array