org.simpleframework.util.buffer
Class ArrayBuffer

java.lang.Object
  extended by org.simpleframework.util.buffer.ArrayBuffer
All Implemented Interfaces:
Buffer, Stream

public class ArrayBuffer
extends java.lang.Object
implements Buffer

The ArrayBuffer is intended to be a general purpose byte buffer that stores bytes in an single internal byte array. The intended use of this buffer is to provide a simple buffer object to read and write bytes with. In particular this provides a high performance buffer that can be used to read and write bytes fast.

This provides several convenience methods which make the use of the buffer easy and useful. This buffer allows an initial capacity to be specified however if there is a need for extra space to be added to buffer then the append methods will expand the capacity of the buffer as needed.

Author:
Niall Gallagher
See Also:
ArrayAllocator

Constructor Summary
ArrayBuffer()
          Constructor for the ArrayBuffer object.
ArrayBuffer(int size)
          Constructor for the ArrayBuffer object.
ArrayBuffer(int size, int limit)
          Constructor for the ArrayBuffer object.
 
Method Summary
 Buffer allocate()
          This method is used to allocate a segment of this buffer as a separate buffer object.
 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.
 java.lang.String encode()
          This method is used to acquire the buffered bytes as a string.
 java.lang.String encode(java.lang.String charset)
          This method is used to acquire the buffered bytes as a string.
 java.io.InputStream getInputStream()
          This method is used so that the 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

ArrayBuffer

public ArrayBuffer()
Constructor for the ArrayBuffer object. The initial capacity of the default buffer object is set to 16, the capacity will be expanded when the append methods are used and there is not enough space to accommodate the extra bytes.


ArrayBuffer

public ArrayBuffer(int size)
Constructor for the ArrayBuffer object. The initial capacity of the buffer object is set to given size, the capacity will be expanded when the append methods are used and there is not enough space to accommodate the extra bytes.

Parameters:
size - the initial capacity of this buffer instance

ArrayBuffer

public ArrayBuffer(int size,
                   int limit)
Constructor for the ArrayBuffer object. The initial capacity of the buffer object is set to given size, the capacity will be expanded when the append methods are used and there is not enough space to accommodate the extra bytes.

Parameters:
size - the initial capacity of this buffer instance
limit - this is the maximum allowable buffer capacity
Method Detail

getInputStream

public java.io.InputStream getInputStream()
This method is used so that the 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:
getInputStream in interface Stream
Returns:
a stream that can be used to read the buffered bytes

allocate

public Buffer allocate()
                throws java.io.IOException
This method is used to allocate a segment of this buffer as a separate buffer object. This allows the buffer to be sliced in to several smaller independent buffers, while still allowing the parent buffer to manage a single buffer. This is useful if the parent is split in to logically smaller segments.

Specified by:
allocate in interface Buffer
Returns:
this returns a buffer which is a segment of this buffer
Throws:
java.io.IOException

encode

public java.lang.String encode()
                        throws java.io.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:
java.io.IOException

encode

public java.lang.String encode(java.lang.String charset)
                        throws java.io.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:
java.io.IOException

append

public Buffer append(byte[] array)
              throws java.io.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:
java.io.IOException

append

public Buffer append(byte[] array,
                     int off,
                     int size)
              throws java.io.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:
java.io.IOException

clear

public void clear()
           throws java.io.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:
java.io.IOException

close

public void close()
           throws java.io.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:
java.io.IOException