Package io.pravega.common.util

Interface BufferView

  • All Known Subinterfaces:
    ArrayView, CompositeArrayView, StructuredReadableBuffer, StructuredWritableBuffer
    All Known Implementing Classes:
    AbstractBufferView, ByteArraySegment, CompositeByteArraySegment
    public interface BufferView
    Defines a generic read-only view of a readable memory buffer with a known length. For array-backed Buffers, see ArrayView. For any implementations that wrap direct memory (a ByteBuffer or Netty ByteBuf and thus support reference counting, consider using retain() release() to ensure the underlying buffer is correctly managed. Invoke retain() if this BufferView instance is to be needed for more than the buffer creator anticipates (i.e., a background async task) and invoke release() to notify that it is no longer needed. The behavior of these two methods are dependent on the actual buffer implementation; for example, Netty ByteBufs only release the memory once the internal reference count reaches 0 (refer to Netty ByteBuf documentation for more details).

    • Method Detail

      • getLength

        int getLength()
        Gets a value representing the length of this BufferView.
        Returns:
        The length.

      • getReader

        java.io.InputStream getReader()
        Creates an InputStream that can be used to read the contents of this BufferView. The InputStream returned spans the entire BufferView.
        Returns:
        The InputStream.

      • getReader

        java.io.InputStream getReader​(int offset,
                              int length)
        Creates an InputStream that can be used to read the contents of this BufferView.
        Parameters:
        offset - The starting offset of the section to read.
        length - The length of the section to read.
        Returns:
        The InputStream.

      • slice

        default BufferView slice()
        Equivalent to invoking slice(int, int) with offset 0 and getLength(). Depending on the implementation, this may return this instance or a new instance that is a duplicate of this one but pointing to the same backing buffer. No data copies are being made as part of invoking this method.
        Returns:
        A BufferView.

      • slice

        BufferView slice​(int offset,
                 int length)
        Creates a new BufferView that represents a sub-range of this BufferView instance. The new instance will share the same backing buffer as this one, so a change to one will be reflected in the other.
        Parameters:
        offset - The starting offset to begin the slice at.
        length - The sliced length.
        Returns:
        A new BufferView.

      • getCopy

        byte[] getCopy()
        Returns a copy of the contents of this BufferView.
        Returns:
        A byte array with the same length as this ArrayView, containing a copy of the data within it.

      • copyTo

        void copyTo​(java.io.OutputStream target)
     throws java.io.IOException
        Copies the contents of this BufferView to the given OutputStream.
        Parameters:
        target - The OutputStream to write to.
        Throws:
        java.io.IOException - If an exception occurred while writing to the target OutputStream.

      • copyTo

        int copyTo​(java.nio.ByteBuffer byteBuffer)
        Copies the contents of this BufferView to the given ByteBuffer.
        Parameters:
        byteBuffer - The ByteBuffer to copy to. This buffer must have sufficient capacity to allow the entire contents of the BufferView to be written. If less needs to be copied, consider using slice() to select a sub-range of this BufferView.
        Returns:
        The number of bytes copied.

      • retain

        default void retain()
        When implemented in a derived class, notifies any wrapped buffer that this BufferView has a need for it. Use release() to do the opposite. See the main documentation on this interface for recommendations on how to use these to methods. Also refer to the implementing class' documentation for any additional details.

      • release

        default void release()
        When implemented in a derived class, notifies any wrapped buffer that this BufferView no longer has a need for it. After invoking this method, this object should no longer be considered safe to access as the underlying buffer may have been deallocated (the actual behavior may vary based on the wrapped buffer, please refer to the implementing class' documentation for any additional details).

      • collect

        <ExceptionT extends java.lang.Exception> void collect​(BufferView.Collector<ExceptionT> bufferCollector)
                                               throws ExceptionT extends java.lang.Exception
        Iterates through each of the buffers that make up this BufferView, in order, and invokes the given BufferView.Collector on each.
        Type Parameters:
        ExceptionT - Type of exception that the BufferView.Collector function throws, if any.
        Parameters:
        bufferCollector - A BufferView.Collector function that will be invoked for each component. Each ByteBuffer passed as an argument to this function is a direct pointer to the data contained within the BufferView (i.e., they are not copies of the data).
        Throws:
        ExceptionT - If the BufferView.Collector function throws an exception of this type, the iteration will end and the exception will be bubbled up.
        ExceptionT extends java.lang.Exception

      • iterateBuffers

        java.util.Iterator<java.nio.ByteBuffer> iterateBuffers()
        Gets an Iterator through each of the ByteBuffers that make up this BufferView, in order.
        Returns:
        A Iterator.

      • wrap

        static BufferView wrap​(java.util.List<BufferView> components)
        Wraps the given BufferView into a single instance.
        Parameters:
        components - The components to wrap. These components will be added by reference, without making any data copies. Any modifications made to these components will be reflected in the returned BufferView and vice-versa.
        Returns:
        An empty BufferView (if the component list is empty), the first item in the list (if the component list has 1 element) or a CompositeBufferView wrapping all the given instances otherwise.

      • builder

        static BufferViewBuilder builder​(int expectedComponentCount)
        Creates a new BufferViewBuilder that can be used to construct composite BufferView instances.
        Parameters:
        expectedComponentCount - The initial component count. Knowing this value beforehand will avoid any list copies that are done as the builder component list grows.
        Returns:
        A new BufferViewBuilder with specified initial component count.