Package io.pravega.common.io.serialization

Interface RevisionDataOutput

  • All Superinterfaces:
    java.io.DataOutput, DirectDataOutput
    public interface RevisionDataOutput
extends java.io.DataOutput, DirectDataOutput
    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.

    • Method Detail

      • requiresExplicitLength

        boolean requiresExplicitLength()
        Gets a value indicating whether this instance of a RevisionDataOutput requires length(int) 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 DataOutput.writeUTF(java.lang.String). Invoking this method will not actually write the String.
        Parameters:
        s - The string to measure.
        Returns:
        The DataOutput.writeUTF(java.lang.String) 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(long). Invoking this method will not actually write the value.
        Parameters:
        value - The value to measure.
        Returns:
        The writeCompactLong(long) length of the value. This is a value between 1 and Long.BYTES (inclusive).
        Throws:
        java.lang.IllegalArgumentException - If value is not in the interval [0, 2^62).

      • 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(long). 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() or using RevisionDataInput.readCompactSignedLong().
        Parameters:
        value - The value to serialize.
        Throws:
        java.io.IOException - If an IO Exception occurred.
        java.lang.IllegalArgumentException - If value is not in the interval [0, 2^62).

      • getCompactSignedLongLength

        int getCompactSignedLongLength​(long value)
        Calculates the length, in bytes, of the given signed Long as serialized by using writeCompactSignedLong(long). Invoking this method will not actually write the value.
        Parameters:
        value - The value to measure.
        Returns:
        The writeCompactSignedLong(long) length of the value. This is a value between 1 and Long.BYTES (inclusive).
        Throws:
        java.lang.IllegalArgumentException - If value is not in the interval [-2^61, 2^61).

      • writeCompactSignedLong

        void writeCompactSignedLong​(long value)
                     throws java.io.IOException
        Encodes the given signed Long into a compact serialization of 1, 2, 4 or 8 bytes. The actual number of bytes can be calculated using getCompactSignedLongLength(long). The first three bits of the given value are ignored and will be reserved for serialization, hence this can only serialize values in the interval [-2^61, 2^61).

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

        Parameters:
        value - The value to serialize.
        Throws:
        java.io.IOException - If an IO Exception occurred.
        java.lang.IllegalArgumentException - If value is not in the interval [-2^61, 2^61).

      • getCompactIntLength

        int getCompactIntLength​(int value)
        Calculates the length, in bytes, of the given Integer as serialized by using writeCompactInt(int). Invoking this method will not actually write the value.
        Parameters:
        value - The value to measure.
        Returns:
        The writeCompactInt(int) length of the value. This is a value between 1 and Integer.BYTES (inclusive).
        Throws:
        java.lang.IllegalArgumentException - If value is not in the interval [0, 2^30).

      • 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(int). The first two bits of the given value are ignored and will be reserved or serialization, hence this can only serialize values in the interval [0, 2^30). 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 not in the interval [0, 2^30).

      • 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

        <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(java.util.Collection<T>, io.pravega.common.io.serialization.RevisionDataOutput.ElementSerializer<T>).
        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(T[], io.pravega.common.io.serialization.RevisionDataOutput.ElementSerializer<T>).
        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.

      • 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(io.pravega.common.io.serialization.RevisionDataInput.ElementDeserializer<T>, java.util.function.IntFunction<T[]>))).
        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.