com.google.cloud.dataflow.sdk.runners.worker

Class OrderedCode

java.lang.Object

com.google.cloud.dataflow.sdk.runners.worker.OrderedCode

public class OrderedCode
extends Object

This module provides routines for encoding a sequence of typed entities into a byte array. The resulting byte arrays can be lexicographically compared to yield the same comparison value that would have been generated if the encoded items had been compared one by one according to their type.

More precisely, suppose:

1. byte array A is generated by encoding the sequence of items [A_1..A_n]
2. byte array B is generated by encoding the sequence of items [B_1..B_n]
3. The types match; i.e., for all i: A_i was encoded using the same routine as B_i

Then: Comparing A vs. B lexicographically is the same as comparing the vectors [A_1..A_n] and [B_1..B_n] lexicographically.

This class is NOT thread safe.

Field Summary

Fields

Modifier and Type	Field and Description
static byte	ESCAPE1
static byte[]	ESCAPE1_SEPARATOR
static byte	ESCAPE2
static byte	FF_CHARACTER
static byte	INFINITY
static byte[]	INFINITY_ENCODED
static byte	NULL_CHARACTER
static byte	SEPARATOR

Constructor Summary

Constructors

Constructor and Description
OrderedCode() Creates OrderedCode from scractch.
OrderedCode(byte[] encodedByteArray) Creates OrderedCode from a given encoded byte array.

Method Summary

Modifier and Type	Method and Description
byte[]	getEncodedBytes() Returns the encoded bytes that represent the current state of the OrderedCode.
boolean	hasRemainingEncodedBytes() Returns true if this has more encoded bytes that haven't been read, false otherwise.
byte[]	readBytes() Returns the next byte array item from its encoded byte array store and removes the item from the store.
byte[]	readBytes(int len) Reads (unencoded) len bytes.
boolean	readInfinity() Removes INFINITY item from its internal encoded byte array store if present.
long	readNumIncreasing() Returns the next long item (encoded in big-endian format via writeNumIncreasing(long)) from its internal encoded byte array store and removes the item from the store.
long	readSignedNumIncreasing() Returns the next long item (encoded via writeSignedNumIncreasing(long)) from its internal encoded byte array store and removes the item from the store.
byte[]	readTrailingBytes() Returns the trailing byte array item from its internal encoded byte array store and removes the item from the store.
void	writeBytes(byte[] value) Adds the given byte array item to the OrderedCode.
void	writeInfinity() Encodes and appends INFINITY item to its internal encoded byte array store.
void	writeNumIncreasing(long value) Encodes the long item, in big-endian format, and appends the result to its internal encoded byte array store.
void	writeSignedNumIncreasing(long val) Encodes the long item, in big-endian format, and appends the result to its internal encoded byte array store.
void	writeTrailingBytes(byte[] value) Appends the byte array item to its internal encoded byte array store.

Methods inherited from class java.lang.Object

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

Field Detail

ESCAPE1

public static final byte ESCAPE1

See Also:

Constant Field Values

NULL_CHARACTER

public static final byte NULL_CHARACTER

See Also:

Constant Field Values

SEPARATOR

public static final byte SEPARATOR

See Also:

Constant Field Values

ESCAPE2

public static final byte ESCAPE2

See Also:

Constant Field Values

INFINITY

public static final byte INFINITY

See Also:

Constant Field Values

FF_CHARACTER

public static final byte FF_CHARACTER

See Also:

Constant Field Values

ESCAPE1_SEPARATOR

public static final byte[] ESCAPE1_SEPARATOR

INFINITY_ENCODED

public static final byte[] INFINITY_ENCODED

Constructor Detail

OrderedCode

public OrderedCode()

Creates OrderedCode from scractch. Typically used at encoding time.

OrderedCode

public OrderedCode(byte[] encodedByteArray)

Creates OrderedCode from a given encoded byte array. Typically used at decoding time.

For better performance, it uses the input array provided (not a copy). Therefore the input array should not be modified.

Method Detail

writeBytes

public void writeBytes(byte[] value)

Adds the given byte array item to the OrderedCode. It encodes the input byte array, followed by a separator and appends the result to its internal encoded byte array store.

It works with the input array, so the input array 'value' should not be modified till the method returns.

Parameters:

value - bytes to be written.

See Also:

readBytes()

writeNumIncreasing

public void writeNumIncreasing(long value)

Encodes the long item, in big-endian format, and appends the result to its internal encoded byte array store.

Note that the specified long is treated like a uint64, e.g. new OrderedCode().writeNumIncreasing(-1L).getEncodedBytes() is greater than new OrderedCode().writeNumIncreasing(Long.MAX_VALUE).getEncodedBytes().

See Also:

readNumIncreasing()

writeSignedNumIncreasing

public void writeSignedNumIncreasing(long val)

Encodes the long item, in big-endian format, and appends the result to its internal encoded byte array store.

Note that the specified long is treated like an int64, i.e. new OrderedCode().writeNumIncreasing(-1L).getEncodedBytes() is less than new OrderedCode().writeNumIncreasing(0L).getEncodedBytes().

See Also:

readSignedNumIncreasing()

writeInfinity

public void writeInfinity()

Encodes and appends INFINITY item to its internal encoded byte array store.

See Also:

readInfinity()

writeTrailingBytes

public void writeTrailingBytes(byte[] value)

Appends the byte array item to its internal encoded byte array store. This is used for the last item and is not encoded. It also can be used to write a fixed number of bytes that will be read back using readBytes(int).

It stores the input array in the store, so the input array 'value' should not be modified.

Parameters:

value - bytes to be written.

See Also:

readTrailingBytes(), readBytes(int)

readBytes

public byte[] readBytes()

Returns the next byte array item from its encoded byte array store and removes the item from the store.

See Also:

writeBytes(byte[])

readNumIncreasing

public long readNumIncreasing()

Returns the next long item (encoded in big-endian format via writeNumIncreasing(long)) from its internal encoded byte array store and removes the item from the store.

See Also:

writeNumIncreasing(long)

readSignedNumIncreasing

public long readSignedNumIncreasing()

Returns the next long item (encoded via writeSignedNumIncreasing(long)) from its internal encoded byte array store and removes the item from the store.

See Also:

writeSignedNumIncreasing(long)

readInfinity

public boolean readInfinity()

Removes INFINITY item from its internal encoded byte array store if present. Returns whether INFINITY was present.

See Also:

writeInfinity()

readTrailingBytes

public byte[] readTrailingBytes()

Returns the trailing byte array item from its internal encoded byte array store and removes the item from the store.

See Also:

writeTrailingBytes(byte[])

readBytes

public byte[] readBytes(int len)

Reads (unencoded) len bytes.

See Also:

writeTrailingBytes(byte[])

getEncodedBytes

public byte[] getEncodedBytes()

Returns the encoded bytes that represent the current state of the OrderedCode.

NOTE: This method returns OrederedCode's internal array (not a copy) for better performance. Therefore the returned array should not be modified.

hasRemainingEncodedBytes

public boolean hasRemainingEncodedBytes()

Returns true if this has more encoded bytes that haven't been read, false otherwise. Return value of true doesn't imply anything about validity of remaining data.

Returns:

true if it has more encoded bytes that haven't been read, false otherwise.