Class BufferAllocator

java.lang.Object
org.simpleframework.common.buffer.FilterAllocator
org.simpleframework.common.buffer.BufferAllocator
All Implemented Interfaces:
Allocator, Buffer

public class BufferAllocator extends FilterAllocator implements Buffer
The BufferAllocator object is used to provide a means to allocate buffers using a single underlying buffer. This uses a buffer from a existing allocator to create the region of memory to use to allocate all other buffers. As a result this allows a single buffer to acquire the bytes in a number of associated buffers. This has the advantage of allowing bytes to be read in sequence without joining data from other buffers or allocating multiple regions.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private Buffer
    This is the underlying buffer all other buffers are within.

    Fields inherited from class org.simpleframework.common.buffer.FilterAllocator

    capacity, limit, source
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructor for the BufferAllocator object.
    BufferAllocator(Allocator source, long capacity)
    Constructor for the BufferAllocator object.
    BufferAllocator(Allocator source, long capacity, long limit)
    Constructor for the BufferAllocator object.
  • Method Summary

    Modifier and Type
    Method
    Description
    This method is used to allocate a default buffer.
    allocate(long size)
    This method is used to allocate a default buffer.
    append(byte[] array)
    This method is used to append bytes to the end of the buffer.
    append(byte[] array, int off, int size)
    This method is used to append bytes to the end of the buffer.
    void
    This will clear all data from the buffer.
    void
    This method is used to ensure the buffer can be closed.
    This method is used to acquire the buffered bytes as a string.
    encode(String charset)
    This method is used to acquire the buffered bytes as a string.
    long
    This is used to provide the number of bytes that have been written to the buffer.
    This method is used so that a buffer can be represented as a stream of bytes.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • buffer

      private Buffer buffer
      This is the underlying buffer all other buffers are within.
  • Constructor Details

    • BufferAllocator

      public BufferAllocator(Allocator source)
      Constructor for the BufferAllocator object. This is used to instantiate the allocator with a default buffer size of half a kilobyte. This ensures that it can be used for general purpose byte storage and for minor I/O tasks.
      Parameters:
      source - this is where the underlying buffer is allocated
    • BufferAllocator

      public BufferAllocator(Allocator source, long capacity)
      Constructor for the BufferAllocator object. This is used to instantiate the allocator with a specified buffer size. This is typically used when a very specific buffer capacity is required, for example a request body with a known length.
      Parameters:
      source - this is where the underlying buffer is allocated
      capacity - the initial capacity of the allocated buffers
    • BufferAllocator

      public BufferAllocator(Allocator source, long capacity, long limit)
      Constructor for the BufferAllocator object. This is used to instantiate the allocator with a specified buffer size. This is typically used when a very specific buffer capacity is required, for example a request body with a known length.
      Parameters:
      source - this is where the underlying buffer is allocated
      capacity - the initial capacity of the allocated buffers
      limit - this is the maximum buffer size created by this
  • Method Details

    • open

      public InputStream open() throws IOException
      This method is used so that a buffer can be represented as a stream of bytes. This provides a quick means to access the data that has been written to the buffer. It wraps the buffer within an input stream so that it can be read directly.
      Specified by:
      open in interface Buffer
      Returns:
      a stream that can be used to read the buffered bytes
      Throws:
      IOException
    • encode

      public String encode() throws IOException
      This method is used to acquire the buffered bytes as a string. This is useful if the contents need to be manipulated as a string or transferred into another encoding. If the UTF-8 content encoding is not supported the platform default is used, however this is unlikely as UTF-8 should be supported.
      Specified by:
      encode in interface Buffer
      Returns:
      this returns a UTF-8 encoding of the buffer contents
      Throws:
      IOException
    • encode

      public String encode(String charset) throws IOException
      This method is used to acquire the buffered bytes as a string. This is useful if the contents need to be manipulated as a string or transferred into another encoding. This will convert the bytes using the specified character encoding format.
      Specified by:
      encode in interface Buffer
      Parameters:
      charset - this is the charset to encode the data with
      Returns:
      this returns the encoding of the buffer contents
      Throws:
      IOException
    • append

      public Buffer append(byte[] array) throws IOException
      This method is used to append bytes to the end of the buffer. This will expand the capacity of the buffer if there is not enough space to accommodate the extra bytes.
      Specified by:
      append in interface Buffer
      Parameters:
      array - this is the byte array to append to this buffer
      Returns:
      this returns this buffer for another operation
      Throws:
      IOException
    • append

      public Buffer append(byte[] array, int off, int size) throws IOException
      This method is used to append bytes to the end of the buffer. This will expand the capacity of the buffer if there is not enough space to accommodate the extra bytes.
      Specified by:
      append in interface Buffer
      Parameters:
      array - this is the byte array to append to this buffer
      off - this is the offset to begin reading the bytes from
      size - the number of bytes to be read from the array
      Returns:
      this returns this buffer for another operation
      Throws:
      IOException
    • clear

      public void clear() throws IOException
      This will clear all data from the buffer. This simply sets the count to be zero, it will not clear the memory occupied by the instance as the internal buffer will remain. This allows the memory occupied to be reused as many times as is required.
      Specified by:
      clear in interface Buffer
      Throws:
      IOException
    • close

      public void close() throws IOException
      This method is used to ensure the buffer can be closed. Once the buffer is closed it is an immutable collection of bytes and can not longer be modified. This ensures that it can be passed by value without the risk of modification of the bytes.
      Specified by:
      close in interface Buffer
      Throws:
      IOException
    • allocate

      public Buffer allocate() throws IOException
      This method is used to allocate a default buffer. This will allocate a buffer of predetermined size, allowing it to grow to an upper limit to accommodate extra data. If the buffer requested is larger than the limit an exception is thrown.
      Specified by:
      allocate in interface Allocator
      Specified by:
      allocate in interface Buffer
      Overrides:
      allocate in class FilterAllocator
      Returns:
      this returns an allocated buffer with a default size
      Throws:
      IOException
    • allocate

      public Buffer allocate(long size) throws IOException
      This method is used to allocate a default buffer. This will allocate a buffer of predetermined size, allowing it to grow to an upper limit to accommodate extra data. If the buffer requested is larger than the limit an exception is thrown.
      Specified by:
      allocate in interface Allocator
      Overrides:
      allocate in class FilterAllocator
      Parameters:
      size - the initial capacity of the allocated buffer
      Returns:
      this returns an allocated buffer with a default size
      Throws:
      IOException
    • length

      public long length()
      This is used to provide the number of bytes that have been written to the buffer. This increases as bytes are appended to the buffer. if the buffer is cleared this resets to zero.
      Specified by:
      length in interface Buffer
      Returns:
      this returns the number of bytes within the buffer