io.pravega.common.io.serialization

Interface RevisionDataOutput

All Superinterfaces:

java.io.DataOutput

public interface RevisionDataOutput
extends java.io.DataOutput

Extension to DataOutput that adds support for a few new constructs and supports formatting a Serialization Revision. An instance of a RevisionDataOutput is created for each Serialization Revision and closed when that Revision's serialization is done - it is not shared between multiple revisions. This interface is designed to serialize data that can be consumed using RevisionDataInput.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	RevisionDataOutput.ElementSerializer<T> Defines a Function signature that can serialize an element to a RevisionDataOutput.

Field Summary

Fields

Modifier and Type	Field and Description
static int	COMPACT_INT_MAX Maximum value that can be encoded using writeCompactInt().
static int	COMPACT_INT_MIN Minimum value that can be encoded using writeCompactInt().
static long	COMPACT_LONG_MAX Maximum value that can be encoded using writeCompactLong().
static long	COMPACT_LONG_MIN Minimum value that can be encoded using writeCompactLong().
static int	UUID_BYTES The number of bytes required to encode a UUID.

Method Summary

Modifier and Type	Method and Description
java.io.OutputStream	getBaseStream() Gets a pointer to the OutputStream that this RevisionDataOutput writes to.
<T> int	getCollectionLength(java.util.Collection<T> collection, java.util.function.ToIntFunction<T> elementLengthProvider) Calculates the number of bytes required to serialize a Collection.
int	getCollectionLength(int elementCount, int elementLength) Calculates the number of bytes required to serialize a Collection or array.
<T> int	getCollectionLength(T[] array, java.util.function.ToIntFunction<T> elementLengthProvider) Calculates the number of bytes required to serialize an array.
int	getCompactIntLength(int value) Calculates the length, in bytes, of the given Integer as serialized by using writeCompactInt().
int	getCompactLongLength(long value) Calculates the length, in bytes, of the given Long as serialized by using writeCompactLong().
int	getMapLength(int elementCount, int keyLength, int valueLength) Calculates the number of bytes required to serialize a Map.
<K,V> int	getMapLength(java.util.Map<K,V> map, java.util.function.ToIntFunction<K> keyLengthProvider, java.util.function.ToIntFunction<V> valueLengthProvider) Calculates the number of bytes required to serialize a Map.
int	getUTFLength(java.lang.String s) Calculates the length, in bytes, of the given String as serialized by using writeUTF().
void	length(int length) If requiresExplicitLength() == true, this method will write 4 bytes at the current position representing the expected serialization length (via the argument).
boolean	requiresExplicitLength() Gets a value indicating whether this instance of a RevisionDataOutput requires length() to be called prior to writing anything to it.
default void	writeArray(byte[] array) Serializes the given byte array.
void	writeArray(byte[] array, int offset, int length) Serializes the given byte array.
default void	writeArray(ByteArraySegment segment) Serializes the given byte array segment.
<T> void	writeArray(T[] array, RevisionDataOutput.ElementSerializer<T> elementSerializer) Serializes the given array using the given ElementSerializer.
<T> void	writeCollection(java.util.Collection<T> collection, RevisionDataOutput.ElementSerializer<T> elementSerializer) Serializes the given Collection using the given ElementSerializer.
void	writeCompactInt(int value) Encodes the given Integer into a compact serialization of 1, 2, 3 or 4 bytes.
void	writeCompactLong(long value) Encodes the given Long into a compact serialization of 1, 2, 4 or 8 bytes.
<K,V> void	writeMap(java.util.Map<K,V> map, RevisionDataOutput.ElementSerializer<K> keySerializer, RevisionDataOutput.ElementSerializer<V> valueSerializer) Serializes the given Map using the given ElementSerializers (one for Key and one for Value).
void	writeUUID(java.util.UUID uuid) Serializes the given UUID as two consecutive Long values.

Methods inherited from interface java.io.DataOutput

write, write, write, writeBoolean, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF

Field Detail

COMPACT_LONG_MAX

static final long COMPACT_LONG_MAX

Maximum value that can be encoded using writeCompactLong().

See Also:

Constant Field Values

COMPACT_LONG_MIN

static final long COMPACT_LONG_MIN

Minimum value that can be encoded using writeCompactLong().

See Also:

Constant Field Values

COMPACT_INT_MAX

static final int COMPACT_INT_MAX

Maximum value that can be encoded using writeCompactInt().

See Also:

Constant Field Values

COMPACT_INT_MIN

static final int COMPACT_INT_MIN

Minimum value that can be encoded using writeCompactInt().

See Also:

Constant Field Values

UUID_BYTES

static final int UUID_BYTES

The number of bytes required to encode a UUID.

See Also:

Constant Field Values

Method Detail

requiresExplicitLength

boolean requiresExplicitLength()

Gets a value indicating whether this instance of a RevisionDataOutput requires length() to be called prior to writing anything to it.

Returns:

True if Length must be declared beforehand (by invoking length()) or not.

length

void length(int length)
     throws java.io.IOException

If requiresExplicitLength() == true, this method will write 4 bytes at the current position representing the expected serialization length (via the argument). In this case, this method must be called prior to invoking any write method on this object. If requiresExplicitLength() == false, this method will have no effect, since the length can be auto-calculated when the RevisionDataOutput is closed.

Parameters:

length - The length to declare.

Throws:

java.io.IOException - If an IO Exception occurred.

getBaseStream

java.io.OutputStream getBaseStream()

Gets a pointer to the OutputStream that this RevisionDataOutput writes to.

Returns:

The OutputStream.

getUTFLength

int getUTFLength(java.lang.String s)

Calculates the length, in bytes, of the given String as serialized by using writeUTF(). Invoking this method will not actually write the String.

Parameters:

s - The string to measure.

Returns:

The writeUTF() length of the String. Note that this may be different from s.length().

getCompactLongLength

int getCompactLongLength(long value)

Calculates the length, in bytes, of the given Long as serialized by using writeCompactLong(). Invoking this method will not actually write the value.

Parameters:

value - The value to measure.

Returns:

The writeCompactLong() length of the value. This is a value between 1 and Long.BYTES (inclusive).

Throws:

java.lang.IllegalArgumentException - If value is negative or greater than 2^62-1.

writeCompactLong

void writeCompactLong(long value)
               throws java.io.IOException

Encodes the given Long into a compact serialization of 1, 2, 4 or 8 bytes. The actual number of bytes can be calculated using getCompactLongLength(). The first two bits of the given value are ignored and will be reserved for serialization, hence this can only serialize values in the interval [0, 2^62).

This value must be read using RevisionDataInput.readCompactLong(). It cannot be read using DataInput.readLong().

Parameters:

value - The value to serialize.

Throws:

java.io.IOException - If an IO Exception occurred.

java.lang.IllegalArgumentException - If value is negative or greater than 2^62-1.

getCompactIntLength

int getCompactIntLength(int value)

Calculates the length, in bytes, of the given Integer as serialized by using writeCompactInt(). Invoking this method will not actually write the value. The first two bits of the given value are ignored and will be reserved for serialization, hence this can only serialize values in the interval [0, 2^30).

Parameters:

value - The value to measure.

Returns:

The writeCompactInt() length of the value. This is a value between 1 and Integer.BYTES (inclusive).

Throws:

java.lang.IllegalArgumentException - If value is negative or greater than 2^30-1.

writeCompactInt

void writeCompactInt(int value)
              throws java.io.IOException

Encodes the given Integer into a compact serialization of 1, 2, 3 or 4 bytes. The actual number of bytes can be calculated using getCompactIntLength().

This value must be read using RevisionDataInput.readCompactInt(). It cannot be read using DataInput.readInt().

Parameters:

value - The value to serialize.

Throws:

java.io.IOException - If an IO Exception occurred.

java.lang.IllegalArgumentException - If value is negative or greater than 2^60-1.

writeUUID

void writeUUID(java.util.UUID uuid)
        throws java.io.IOException

Serializes the given UUID as two consecutive Long values.

This value must be read using RevisionDataInput.readUUID().

Parameters:

uuid - The UUID to serialize.

Throws:

java.io.IOException - If an IO Exception occurred.

getCollectionLength

int getCollectionLength(int elementCount,
                        int elementLength)

Calculates the number of bytes required to serialize a Collection or array. This method can be used to estimate the serialization length of both writeCollection() and writeArray().

Parameters:

elementCount - The size of the collection.

elementLength - The size (in bytes) of each element's serialization.

Returns:

The number of bytes.

getCollectionLength

<T> int getCollectionLength(java.util.Collection<T> collection,
                            java.util.function.ToIntFunction<T> elementLengthProvider)

Calculates the number of bytes required to serialize a Collection. This method can be used to estimate the serialization length of writeCollection().

Type Parameters:

T - Type of the Collection's Elements.

Parameters:

collection - The Collection to measure.

elementLengthProvider - A Function that, given an Element of type T, will return its serialization length.

Returns:

The number of bytes.

getCollectionLength

<T> int getCollectionLength(T[] array,
                            java.util.function.ToIntFunction<T> elementLengthProvider)

Calculates the number of bytes required to serialize an array. This method can be used to estimate the serialization length of writeArray().

Type Parameters:

T - Type of the Array's Elements

Parameters:

array - The array to measure.

elementLengthProvider - A Function that, given an Element of type T, will return its serialization length.

Returns:

The number of bytes.

writeCollection

<T> void writeCollection(java.util.Collection<T> collection,
                         RevisionDataOutput.ElementSerializer<T> elementSerializer)
                  throws java.io.IOException

Serializes the given Collection using the given ElementSerializer. It first writes a Compact Integer representing the number of elements in the collection, followed by each element's serialization, in the same order as returned by the Collection's iterator.

Type Parameters:

T - Type of the elements in the Collection.

Parameters:

collection - The Collection to serialize. Can be null (in which case an Empty Collection will be deserialized by RevisionDataInput.readCollection()).

elementSerializer - A Function that serializes a single element of the collection to a RevisionDataOutput.

Throws:

java.io.IOException - If an IO Exception occurred.

writeArray

<T> void writeArray(T[] array,
                    RevisionDataOutput.ElementSerializer<T> elementSerializer)
             throws java.io.IOException

Serializes the given array using the given ElementSerializer. It first writes a Compact Integer representing the number of elements in the array, followed by each element's serialization, in the order in which they appear in the array.

Type Parameters:

T - Type of the elements in the array.

Parameters:

array - The array to serialize. Can be null (in which case an Empty array will be deserialized by RevisionDataInput.readArray()).

elementSerializer - A Function that serializes a single element of the array to a RevisionDataOutput.

Throws:

java.io.IOException - If an IO Exception occurred.

writeArray

default void writeArray(byte[] array)
                 throws java.io.IOException

Serializes the given byte array. Equivalent to calling writeArray(array, 0, array.length).

Parameters:

array - The array to serialize. Can be null (in which case an Empty array will be deserialized by RevisionDataInput.readArray()).

Throws:

java.io.IOException - If an IO Exception occurred.

writeArray

default void writeArray(ByteArraySegment segment)
                 throws java.io.IOException

Serializes the given byte array segment. Equivalent to calling writeArray(segment, segment.arrayOffset(), segment.getLength()).

Parameters:

segment - The byte array segment to serialize. Can be null (in which case an Empty array will be deserialized by RevisionDataInput.readArray()).

Throws:

java.io.IOException - If an IO Exception occurred.

writeArray

void writeArray(byte[] array,
                int offset,
                int length)
         throws java.io.IOException

Serializes the given byte array. It first writes a Compact Integer representing the length to serialize, followed by the actual array elements being written.

Parameters:

array - The array to serialize. Can be null (in which case an Empty array will be deserialized by RevisionDataInput.readArray()).

offset - The offset within the array to begin serializing at. This is ignored if array == null.

length - The number of elements to serialize. This is ignored if array == null.

Throws:

java.io.IOException - If an IO Exception occurred.

getMapLength

int getMapLength(int elementCount,
                 int keyLength,
                 int valueLength)

Calculates the number of bytes required to serialize a Map.

Parameters:

elementCount - The size of the Map.

keyLength - The size (in bytes) of each key's serialization.

valueLength - The size (in bytes) of each value's serialization.

Returns:

The number of bytes.

getMapLength

<K,V> int getMapLength(java.util.Map<K,V> map,
                       java.util.function.ToIntFunction<K> keyLengthProvider,
                       java.util.function.ToIntFunction<V> valueLengthProvider)

Calculates the number of bytes required to serialize a Map.

Type Parameters:

K - Type of the Map's Keys.

V - Type of the Map's Values.

Parameters:

map - The Map to measure.

keyLengthProvider - A Function that, given a Key of type K, will return its serialization length.

valueLengthProvider - A Function that, given a Value of type V, will return its serialization length.

Returns:

The number of bytes.

writeMap

<K,V> void writeMap(java.util.Map<K,V> map,
                    RevisionDataOutput.ElementSerializer<K> keySerializer,
                    RevisionDataOutput.ElementSerializer<V> valueSerializer)
             throws java.io.IOException

Serializes the given Map using the given ElementSerializers (one for Key and one for Value). It first writes a Compact Integer representing the number of elements in the Map, followed by each pair's serialization (first the key, then the value), in the same order as returned by the Map's iterator.

Type Parameters:

K - Type of the Map's Keys.

V - Type of the Map's Values.

Parameters:

map - The Map to serialize. Can be null (in which case an Empty Map will be deserialized by RevisionDataInput.readMap()).

keySerializer - A Function that serializes a single Key of the Map to a RevisionDataOutput.

valueSerializer - A Function that serializes a single Value of the Map to a RevisionDataOutput.

Throws:

java.io.IOException - If an IO Exception occurred.