Class ByteStreamWriter

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

    public abstract class ByteStreamWriter
    extends java.io.OutputStream
    Allows for writing raw bytes directly to a segment. This is intended as low level building block for creating higher level components. As such it can break things. This class does not frame, attach headers, or otherwise modify the bytes written to it in any way. So unlike EventStreamWriter or RevisionedStreamClient the data written cannot be split apart when read. As such, any bytes written by this API can ONLY be read using ByteStreamReader. Similarly, unless some sort of framing is added it is probably an error to have multiple ByteStreamWriters write to the same segment as this will result in interleaved data. The methods on this class are non-blocking unless otherwise specified. As such data passed to a OutputStream.write(byte[]) call cannot be assumed to be persisted until a flush has been called. It is safe to invoke methods on this class from multiple threads but doing so will not result in an increase in performance.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      abstract void close()
      Flushes the buffer and closes the writer.
      abstract void closeAndSeal()
      Closes the writer similar to close() but also seals it so that no future writes can ever be made.
      abstract long fetchHeadOffset()
      This makes a synchronous RPC call to the server to obtain the current head of the stream.
      abstract long fetchTailOffset()
      This makes a synchronous RPC call to the server to obtain the total number of bytes written to the segment in its history.
      abstract void flush()
      Blocks until all data written has been durably persisted.
      abstract java.util.concurrent.CompletableFuture<java.lang.Void> flushAsync()
      The future will complete successfully when all data which was passed to the write prior to calling this method has been persisted, and will complete exceptionally if that is not possible such as for example if the segment is sealed.
      abstract void truncateDataBefore​(long offset)
      This makes a synchronous RPC call to the server to truncate the segment at the provided offset.
      abstract void write​(byte[] b, int off, int len)
      Writes the provided data to the segment.
      abstract void write​(java.nio.ByteBuffer src)
      Similar to write(byte[], int, int) Writes the provided data to the segment.
      • Methods inherited from class java.io.OutputStream

        nullOutputStream, write, write
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ByteStreamWriter

        public ByteStreamWriter()
    • Method Detail

      • write

        public abstract void write​(java.nio.ByteBuffer src)
                            throws java.io.IOException
        Similar to write(byte[], int, int) Writes the provided data to the segment. The data is buffered internally to avoid blocking. As such it cannot be assumed to be durably stored until a flush completes. It is intended that this method not block, but it may in the event that the server becomes disconnected for sufficiently long or is sufficiently slow that that backlog of data to be written becomes a memory issue.
        Parameters:
        src - The bytes to write.
        Throws:
        java.io.IOException - If for any reason an error occurs writing the data, including if the stream is sealed.
      • write

        public abstract void write​(byte[] b,
                                   int off,
                                   int len)
                            throws java.io.IOException
        Writes the provided data to the segment. The data is buffered internally to avoid blocking. As such it cannot be assumed to be durably stored until a flush completes. It is intended that this method not block, but it may in the event that the server becomes disconnected for sufficiently long or is sufficiently slow that that backlog of data to be written becomes a memory issue.
        Overrides:
        write in class java.io.OutputStream
        Throws:
        java.io.IOException
        See Also:
        OutputStream.write(byte[], int, int)
      • close

        public abstract void close()
                            throws java.io.IOException
        Flushes the buffer and closes the writer. If there is data to flush, this is a blocking method.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        java.io.IOException
        See Also:
        OutputStream.close()
      • flush

        public abstract void flush()
                            throws java.io.IOException
        Blocks until all data written has been durably persisted.
        Specified by:
        flush in interface java.io.Flushable
        Overrides:
        flush in class java.io.OutputStream
        Throws:
        java.io.IOException - If for any reason the flush fails including if the stream is sealed.
        See Also:
        OutputStream.flush()
      • flushAsync

        public abstract java.util.concurrent.CompletableFuture<java.lang.Void> flushAsync()
                                                                                   throws java.io.IOException
        The future will complete successfully when all data which was passed to the write prior to calling this method has been persisted, and will complete exceptionally if that is not possible such as for example if the segment is sealed.
        Returns:
        The future related to last write
        Throws:
        java.io.IOException - If for any reason the flush fails including if the stream is sealed.
        See Also:
        OutputStream.flush()
      • closeAndSeal

        public abstract void closeAndSeal()
                                   throws java.io.IOException
        Closes the writer similar to close() but also seals it so that no future writes can ever be made.
        Throws:
        java.io.IOException - If for any reason the flush fails including if the stream is sealed.
      • fetchHeadOffset

        public abstract long fetchHeadOffset()
        This makes a synchronous RPC call to the server to obtain the current head of the stream.
        Returns:
        The current head offset
      • fetchTailOffset

        public abstract long fetchTailOffset()
        This makes a synchronous RPC call to the server to obtain the total number of bytes written to the segment in its history. This is the sum total of the bytes written in all calls to OutputStream.write(byte[]) that have been flushed. It does not include data that was passed to OutputStream.write(byte[]) but which has not yet been persisted.
        Returns:
        The tail offset
      • truncateDataBefore

        public abstract void truncateDataBefore​(long offset)
        This makes a synchronous RPC call to the server to truncate the segment at the provided offset.
        Parameters:
        offset - The truncation offset.