org.simpleframework.util.buffer
Class BufferAllocator

java.lang.Object
  org.simpleframework.util.buffer.FilterAllocator
      org.simpleframework.util.buffer.BufferAllocator

All Implemented Interfaces:

Closeable, 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.

Author:

Niall Gallagher

Field Summary

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

capacity, limit, source

Constructor Summary

BufferAllocator(Allocator source)
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

Buffer	allocate() This method is used to allocate a default buffer.
Buffer	allocate(long size) This method is used to allocate a default buffer.
Buffer	append(byte[] array) This method is used to append bytes to the end of the buffer.
Buffer	append(byte[] array, int off, int size) This method is used to append bytes to the end of the buffer.
void	clear() This will clear all data from the buffer.
void	close() This method is used to ensure the buffer can be closed.
String	encode() This method is used to acquire the buffered bytes as a string.
String	encode(String charset) This method is used to acquire the buffered bytes as a string.
long	length() This is used to provide the number of bytes that have been written to the buffer.
InputStream	open() 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

Constructor Detail

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 Detail

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

size - the number of bytes to be read from the array

off - this is the offset to begin reading the bytes from

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 Closeable

Specified by:

close in interface Allocator

Specified by:

close in interface Buffer

Overrides:

close in class FilterAllocator

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