Package com.tangosol.io

Class MultiBufferWriteBuffer

  • All Implemented Interfaces:
    Disposable, WriteBuffer, AutoCloseable
    public final class MultiBufferWriteBuffer
extends AbstractWriteBuffer
implements Disposable
    The MultiBufferWriteBuffer is used to present a single WriteBuffer that collects together a sequence of underlying WriteBuffer objects, and which grows by allocating additional WriteBuffer objects as necessary.
    Author:
    cp 2006.04.10

    • Constructor Detail

      • MultiBufferWriteBuffer

        public MultiBufferWriteBuffer​(MultiBufferWriteBuffer.WriteBufferPool bufferpool,
                              int cbEstimate)
        Construct a MultiBufferWriteBuffer that will use the passed WriteBufferPool to allocate WriteBuffer objects from.
        Parameters:
        bufferpool - a MultiBufferWriteBuffer.WriteBufferPool from which the MultiBufferWriteBuffer will allocate WriteBuffer objects
        cbEstimate - an estimate as to the final size

    • Method Detail

      • write

        public void write​(int ofDest,
                  byte b)
        Store the specified byte at the specified offset within the buffer.

        For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code: 

        
 byte[] abSrc = new byte[1];
 abSrc[0] = b;
 write(ofDest, abSrc, 0, abSrc.length);

        Specified by:
        write in interface WriteBuffer
        Specified by:
        write in class AbstractWriteBuffer
        Parameters:
        ofDest - the offset within this buffer to store the passed data
        b - the byte to store in this buffer

      • write

        public void write​(int ofDest,
                  ReadBuffer bufSrc,
                  int ofSrc,
                  int cbSrc)
        Store the specified portion of the contents of the specified ReadBuffer at the specified offset within this buffer.

        For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code: 

        
 byte[] abSrc = bufSrc.toByteArray(ofSrc, cbSrc);
 write(ofDest, abSrc, 0, abSrc.length);

        Specified by:
        write in interface WriteBuffer
        Overrides:
        write in class AbstractWriteBuffer
        Parameters:
        ofDest - the offset within this buffer to store the passed data
        bufSrc - the array of bytes to store in this buffer
        ofSrc - the offset within the passed ReadBuffer to copy from
        cbSrc - the number of bytes to copy from the passed ReadBuffer

      • length

        public int length()
        Determine the length of the data that is in the buffer. This is the actual number of bytes of data that have been written to the buffer, not the capacity of the buffer.
        Specified by:
        length in interface WriteBuffer
        Specified by:
        length in class AbstractWriteBuffer
        Returns:
        the number of bytes of data represented by this WriteBuffer

      • retain

        public void retain​(int of,
                   int cb)
        Starting with the byte at offset of, retain cb bytes in this WriteBuffer, such that the byte at offset of is shifted to offset 0, the byte at offset of + 1 is shifted to offset 1, and so on up to the byte at offset of + cb - 1, which is shifted to offset cb - 1. After this method, the length of the buffer as indicated by the WriteBuffer.length() method will be equal to cb.

        Legal values for the offset of the first byte to retain of are (of >= 0 && of <= WriteBuffer.length()). Legal values for the number of bytes to retain cb are (cb >= 0 && cb <= WriteBuffer.length()), such that (of + cb <= WriteBuffer.length()).

        If cb is zero, then this method will have the same effect as clear. If of is zero, then this method will have the effect of truncating the data in the buffer, but no bytes will be shifted within the buffer.

        The effect on the capacity of the buffer is implementation-specific; some implementations are expected to retain the same capacity while others are expected to shrink accordingly.

        Specified by:
        retain in interface WriteBuffer
        Specified by:
        retain in class AbstractWriteBuffer
        Parameters:
        of - the offset of the first byte within the WriteBuffer that will be retained
        cb - the number of bytes to retain

      • getCapacity

        public int getCapacity()
        Determine the number of bytes that the buffer can hold without resizing itself. In other words, a WriteBuffer has getCapacity() - WriteBuffer.length() bytes that can be written to it without overflowing the current underlying buffer allocation. Since the buffer is an abstract concept, the actual mechanism for the underlying buffer is not known, but it could be a Java NIO buffer, or a byte array, etc.

        Note that if the maximum size returned by WriteBuffer.getMaximumCapacity() is greater than the current size returned by this method, then the WriteBuffer will automatically resize itself to allocate more space when the amount of data written to it passes the current size.

        Specified by:
        getCapacity in interface WriteBuffer
        Specified by:
        getCapacity in class AbstractWriteBuffer
        Returns:
        the number of bytes of data that this WriteBuffer can hold without resizing its underlying buffer

      • getMaximumCapacity

        public int getMaximumCapacity()
        Determine the maximum number of bytes that the buffer can hold. If the maximum size is greater than the current size, then the buffer is expected to resize itself as necessary up to the maximum size in order to contain the data given to it.
        Specified by:
        getMaximumCapacity in interface WriteBuffer
        Overrides:
        getMaximumCapacity in class AbstractWriteBuffer
        Returns:
        the maximum number of bytes of data that the WriteBuffer can hold

      • getReadBuffer

        public ReadBuffer getReadBuffer()
        Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.

        This method is functionally equivalent to the following code: 

        
 ReadBuffer buf = getUnsafeReadBuffer();
 byte[] ab = buf.toByteArray();
 return new ByteArrayReadBuffer(ab);

        Specified by:
        getReadBuffer in interface WriteBuffer
        Overrides:
        getReadBuffer in class AbstractWriteBuffer
        Returns:
        a ReadBuffer that reflects the point-in-time contents of this WriteBuffer

      • getUnsafeReadBuffer

        public ReadBuffer getUnsafeReadBuffer()
        Get a ReadBuffer object to read data from this buffer. This method is not guaranteed to return a snapshot of this buffer's data, nor is it guaranteed to return a live view of this buffer, which means that subsequent changes to this WriteBuffer may or may not affect the contents and / or the length of the returned ReadBuffer.

        To get a snapshot, use the WriteBuffer.getReadBuffer() method.

        Specified by:
        getUnsafeReadBuffer in interface WriteBuffer
        Specified by:
        getUnsafeReadBuffer in class AbstractWriteBuffer
        Returns:
        a ReadBuffer that reflects the contents of this WriteBuffer but whose behavior is undefined if the WriteBuffer is modified

      • toByteArray

        public byte[] toByteArray()
        Returns a new byte array that holds the complete contents of this WriteBuffer.

        This method is functionally equivalent to the following code: 

        
 return getUnsafeReadBuffer().toByteArray();

        Specified by:
        toByteArray in interface WriteBuffer
        Overrides:
        toByteArray in class AbstractWriteBuffer
        Returns:
        the contents of this WriteBuffer as a byte[]

      • toBinary

        public Binary toBinary()
        Returns a new Binary object that holds the complete contents of this WriteBuffer.

        This method is functionally equivalent to the following code: 

        
 return getUnsafeReadBuffer().toBinary();

        Specified by:
        toBinary in interface WriteBuffer
        Overrides:
        toBinary in class AbstractWriteBuffer
        Returns:
        the contents of this WriteBuffer as a Binary object

      • getBufferOutput

        public WriteBuffer.BufferOutput getBufferOutput​(int of)
        Get a BufferOutput object to write data to this buffer starting at a particular offset.

        Note that each call to this method will return a new BufferOutput object, with the possible exception being that a zero-length non-resizing WriteBuffer could always return the same instance (since it is not writable).

        This is functionally equivalent to: 

        
 BufferOutput bufout = getBufferOutput();
 bufout.setOffset(of);
 return bufout;

        Specified by:
        getBufferOutput in interface WriteBuffer
        Overrides:
        getBufferOutput in class AbstractWriteBuffer
        Parameters:
        of - the offset of the first byte of this buffer that the BufferOutput will write to
        Returns:
        a BufferOutput that will write to this buffer

      • clone

        public Object clone()
        Create a clone of this WriteBuffer object. Changes to the clone will not affect the original, and vice-versa.
        Specified by:
        clone in interface WriteBuffer
        Overrides:
        clone in class AbstractWriteBuffer
        Returns:
        a WriteBuffer object with the same contents as this WriteBuffer object

      • dispose

        public void dispose()
        Invoked when all resources owned by the implementer can safely be released.

        Once disposed of the object should no longer be considered to be usable.

        Note the Disposable interface is compatible with try-with-resources which will automatically invoke this method.

        Specified by:
        dispose in interface Disposable

      • getBufferPool

        public MultiBufferWriteBuffer.WriteBufferPool getBufferPool()
        Obtain the factory used to create WriteBuffer objects.
        Returns:
        the WriteBufferPool used by this MultiBufferWriteBuffer

      • getBufferCount

        public int getBufferCount()
        Determine the number of WriteBuffer objects allocated by this MultiBufferWriteBuffer from the WriteBufferPool.
        Returns:
        the count of WriteBuffer objects allocated

      • getBufferOffset

        public int getBufferOffset​(int iBuffer)
        Determine the offset of the specified buffer. The offset of a buffer is the absolute offset of the first byte stored in the buffer.
        Parameters:
        iBuffer - an index 0 <= iBuffer < getBufferCount()
        Returns:
        the absolute offset of the first byte of the specified WriteBuffer

      • getBuffer

        public WriteBuffer getBuffer​(int iBuffer)
        Obtain the specified buffer.
        Parameters:
        iBuffer - an index 0 <= iBuffer < getBufferCount()
        Returns:
        the specified WriteBuffer

      • getBufferIndexByOffset

        protected int getBufferIndexByOffset​(int of)
        Determine which underlying WriteBuffer contains the specified offset.
        Parameters:
        of - an offset into the MultiBufferWriteBuffer, 0 <= of <= length()
        Returns:
        the index of the WriteBuffer containing the specified offset

      • addBuffer

        protected WriteBuffer addBuffer()
        Once the current buffer is full, allocate a new one and make it the current buffer.
        Returns:
        the new WriteBuffer object

      • getCurrentBuffer

        protected WriteBuffer getCurrentBuffer()
        Obtain the current buffer.
        Returns:
        the current underlying WriteBuffer

      • getCurrentBufferAbsoluteOffset

        protected int getCurrentBufferAbsoluteOffset()
        Determine the offset of the first byte of the current buffer.
        Returns:
        the offset of the first byte written to the current underlying WriteBuffer

      • getCurrentBufferRemaining

        protected int getCurrentBufferRemaining()
        Determine the maximum number of bytes that can still be written to the current underlying WriteBuffer.
        Returns:
        the number of bytes of capacity that remain on the current underlying WriteBuffer object

      • ensureBufferOutput

        protected MultiBufferWriteBuffer.MultiBufferOutput ensureBufferOutput​(int of)
        Obtain the internal MultiBufferOutput, creating it if necessary.
        Parameters:
        of - the desired offset of the MultiBufferOutput
        Returns:
        a MultiBufferOutput set to the specified offest