com.mucommander.io
Class BufferPool

java.lang.Object
  com.mucommander.io.BufferPool

public class BufferPool
extends java.lang.Object

This class allows to share and reuse byte buffers to avoid excessive memory allocation and garbage collection. Methods that use byte buffers and that are called repeatedly will benefit from using this class.

This class works with two types of byte buffers indifferently:

• Byte array buffers (byte[])
• java.nio.ByteBuffer

Usage of this class is similar to malloc/free:

• Call #get*Buffer(int) to retrieve a buffer instance of a specified size
• Use the buffer
• When finished using the buffer, call #release*Buffer(byte[]) to make this buffer available for subsequent calls to #get*Buffer(int). Failing to call this method will prevent the buffer from being used again and from being garbage-collected.

Note: this class is thread safe and thus can safely be used by concurrent threads.

Author:

Maxence Bernard

See Also:

StreamUtils

Nested Class Summary

static class	BufferPool.BufferContainer Wraps a buffer instance and provides information about the wrapped buffer.
static class	BufferPool.BufferFactory A BufferFactory is responsible for creating buffer and BufferPool.BufferContainer instances, and for returning the buffer Class.
static class	BufferPool.ByteArrayFactory This class is a BufferPool.BufferFactory implementation for byte array (byte[]) buffers.
static class	BufferPool.ByteBufferFactory This class is a BufferPool.BufferFactory implementation for java.nio.ByteBuffer buffers.
static class	BufferPool.CharArrayFactory This class is a BufferPool.BufferFactory implementation for char array (char[]) buffers.

Field Summary

static int

DEFAULT_BUFFER_SIZE The default buffer size when not specified

Constructor Summary

BufferPool()

Method Summary

static java.lang.Object	getBuffer(int size, BufferPool.BufferFactory factory) Returns a byte array of the specified size.
static byte[]	getByteArray() Convenience method that has the same effect as calling getByteArray(int) with DEFAULT_BUFFER_SIZE.
static byte[]	getByteArray(int size) Returns a byte array of the specified size.
static java.nio.ByteBuffer	getByteBuffer() Convenience method that has the same effect as calling getByteBuffer(int) with DEFAULT_BUFFER_SIZE.
static java.nio.ByteBuffer	getByteBuffer(int capacity) Returns a ByteBuffer of the specified capacity.
static char[]	getCharArray() Convenience method that has the same effect as calling getCharArray(int) with DEFAULT_BUFFER_SIZE.
static char[]	getCharArray(int size) Returns a char array of the specified size.
static void	releaseBuffer(java.lang.Object buffer, BufferPool.BufferFactory factory) Makes the given buffer available for further calls to getBuffer(int, BufferFactory) with the same buffer size and factory.
static void	releaseByteArray(byte[] buffer) Makes the given buffer available for further calls to getByteArray(int) with the same buffer size.
static void	releaseByteBuffer(java.nio.ByteBuffer buffer) Makes the given buffer available for further calls to getByteBuffer(int) with the same buffer size.
static void	releaseCharArray(char[] buffer) Makes the given buffer available for further calls to getCharArray(int) with the same buffer size.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The default buffer size when not specified

See Also:

Constant Field Values

Constructor Detail

BufferPool

public BufferPool()

Method Detail

getByteArray

public static byte[] getByteArray()

Convenience method that has the same effect as calling getByteArray(int) with DEFAULT_BUFFER_SIZE.

Returns:

a byte array with a length of DEFAULT_BUFFER_SIZE

getByteArray

public static byte[] getByteArray(int size)

Returns a byte array of the specified size. This method first checks if a byte array of the specified size exists in the pool. If one is found, it is removed from the pool and returned. If not, a new instance is created and returned.

This method won't return the same buffer instance until it has been released with releaseByteArray(byte[]).

This method is a shorthand for getBuffer(int, com.mucommander.io.BufferPool.BufferFactory) called with a BufferPool.ByteArrayFactory instance.

.

Parameters:

size - size of the byte array

Returns:

a byte array of the specified size

getCharArray

public static char[] getCharArray()

Convenience method that has the same effect as calling getCharArray(int) with DEFAULT_BUFFER_SIZE.

Returns:

a char array with a length of DEFAULT_BUFFER_SIZE

getCharArray

public static char[] getCharArray(int size)

Returns a char array of the specified size. This method first checks if a char array of the specified size exists in the pool. If one is found, it is removed from the pool and returned. If not, a new instance is created and returned.

This method won't return the same buffer instance until it has been released with releaseCharArray(char[]).

This method is a shorthand for getBuffer(int, com.mucommander.io.BufferPool.BufferFactory) called with a BufferPool.CharArrayFactory instance.

.

Parameters:

size - size of the char array

Returns:

a char array of the specified size

getByteBuffer

public static java.nio.ByteBuffer getByteBuffer()

Convenience method that has the same effect as calling getByteBuffer(int) with DEFAULT_BUFFER_SIZE.

Returns:

a ByteBuffer with a capacity of DEFAULT_BUFFER_SIZE bytes

getByteBuffer

public static java.nio.ByteBuffer getByteBuffer(int capacity)

Returns a ByteBuffer of the specified capacity. This method first checks if a ByteBuffer instance of the specified capacity exists in the pool. If one is found, it is removed from the pool and returned. If not, a new instance is created and returned.

This method won't return the same buffer instance until it has been released with releaseByteBuffer(ByteBuffer).

This method is a shorthand for getBuffer(int, com.mucommander.io.BufferPool.BufferFactory) called with a BufferPool.ByteArrayFactory instance.

.

Parameters:

capacity - capacity of the ByteBuffer

Returns:

a ByteBuffer with the specified capacity

getBuffer

public static java.lang.Object getBuffer(int size,
                                         BufferPool.BufferFactory factory)

Returns a byte array of the specified size. This method first checks if a buffer the same size as the specified one and a class compatible with the specified factory exists in the pool. If one is found, it is removed from the pool and returned. If not, a new instance is created and returned using BufferPool.BufferFactory.newBuffer(int).

This method won't return the same buffer instance until it has been released with releaseBuffer(Object, BufferFactory).

Parameters:

size - size of the buffer

factory - BufferFactory used to identify the target buffer class and create a new buffer (if necessary)

Returns:

a buffer of the specified size

releaseByteArray

public static void releaseByteArray(byte[] buffer)

Makes the given buffer available for further calls to getByteArray(int) with the same buffer size. Does nothing if the specified buffer already is in the pool. After calling this method, the given buffer instance must not be used, otherwise it could get corrupted if some other threads use it.

Parameters:

buffer - the buffer instance to make available for further use

Throws:

java.lang.IllegalArgumentException - if specified buffer is null

releaseCharArray

public static void releaseCharArray(char[] buffer)

Makes the given buffer available for further calls to getCharArray(int) with the same buffer size. Does nothing if the specified buffer already is in the pool. After calling this method, the given buffer instance must not be used, otherwise it could get corrupted if some other threads use it.

Parameters:

buffer - the buffer instance to make available for further use

Throws:

java.lang.IllegalArgumentException - if specified buffer is null

releaseByteBuffer

public static void releaseByteBuffer(java.nio.ByteBuffer buffer)

Makes the given buffer available for further calls to getByteBuffer(int) with the same buffer size. Does nothing if the specified buffer already is in the pool. After calling this method, the given buffer instance must not be used, otherwise it could get corrupted if some other threads use it.

Parameters:

buffer - the buffer instance to make available for further use

Throws:

java.lang.IllegalArgumentException - if specified buffer is null

releaseBuffer

public static void releaseBuffer(java.lang.Object buffer,
                                 BufferPool.BufferFactory factory)

Makes the given buffer available for further calls to getBuffer(int, BufferFactory) with the same buffer size and factory. Does nothing if the specified buffer already is in the pool. After calling this method, the given buffer instance must not be used, otherwise it could get corrupted if some other threads use it.

Parameters:

buffer - the buffer instance to make available for further use

factory - BufferFactory used create a buffer container

Throws:

java.lang.IllegalArgumentException - if specified buffer is null