org.apache.commons.collections
Class BufferUtils

java.lang.Object
  org.apache.commons.collections.BufferUtils

public class BufferUtils
extends Object

Provides utility methods and decorators for Buffer instances.

Since:

Commons Collections 2.1

Version:

$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:32:42 $

Author:

Matt Hall, John Watkinson, Paul Jack, Stephen Colebourne

Field Summary

static Buffer

EMPTY_BUFFER An empty unmodifiable buffer.

Constructor Summary

BufferUtils()
BufferUtils should not normally be instantiated.

Method Summary

static <E> Buffer<E>	blockingBuffer(Buffer<E> buffer) Returns a synchronized buffer backed by the given buffer that will block on Buffer.get() and Buffer.remove() operations.
static <E> Buffer<E>	predicatedBuffer(Buffer<E> buffer, Predicate<E> predicate) Returns a predicated (validating) buffer backed by the given buffer.
static <E> Buffer<E>	synchronizedBuffer(Buffer<E> buffer) Returns a synchronized buffer backed by the given buffer.
static <I,O> Buffer<O>	transformedBuffer(Buffer<I> buffer, Transformer<I,O> transformer) Returns a transformed buffer backed by the given buffer.
static <E> Buffer<E>	typedBuffer(Buffer<E> buffer, Class<E> type) Deprecated. No longer required with Java 1.5 Generics.
static <E> Buffer<E>	unmodifiableBuffer(Buffer<E> buffer) Returns an unmodifiable buffer backed by the given buffer.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_BUFFER

public static final Buffer EMPTY_BUFFER

An empty unmodifiable buffer.

Constructor Detail

BufferUtils

public BufferUtils()

BufferUtils should not normally be instantiated.

Method Detail

synchronizedBuffer

public static <E> Buffer<E> synchronizedBuffer(Buffer<E> buffer)

Returns a synchronized buffer backed by the given buffer. Much like the synchronized collections returned by Collections, you must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Buffer b = BufferUtils.synchronizedBuffer(myBuffer);
 synchronized (b) {
     Iterator i = b.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
 

Parameters:

buffer - the buffer to synchronize, must not be null

Returns:

a synchronized buffer backed by that buffer

Throws:

IllegalArgumentException - if the Buffer is null

blockingBuffer

public static <E> Buffer<E> blockingBuffer(Buffer<E> buffer)

Returns a synchronized buffer backed by the given buffer that will block on Buffer.get() and Buffer.remove() operations. If the buffer is empty, then the Buffer.get() and Buffer.remove() operations will block until new elements are added to the buffer, rather than immediately throwing a BufferUnderflowException.

Parameters:

buffer - the buffer to synchronize, must not be null

Returns:

a blocking buffer backed by that buffer

Throws:

IllegalArgumentException - if the Buffer is null

unmodifiableBuffer

public static <E> Buffer<E> unmodifiableBuffer(Buffer<E> buffer)

Returns an unmodifiable buffer backed by the given buffer.

Parameters:

buffer - the buffer to make unmodifiable, must not be null

Returns:

an unmodifiable buffer backed by that buffer

Throws:

IllegalArgumentException - if the Buffer is null

predicatedBuffer

public static <E> Buffer<E> predicatedBuffer(Buffer<E> buffer,
                                             Predicate<E> predicate)

Returns a predicated (validating) buffer backed by the given buffer.

Only objects that pass the test in the given predicate can be added to the buffer. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original buffer after invoking this method, as it is a backdoor for adding invalid objects.

Parameters:

buffer - the buffer to predicate, must not be null

predicate - the predicate used to evaluate new elements, must not be null

Returns:

a predicated buffer

Throws:

IllegalArgumentException - if the Buffer or Predicate is null

typedBuffer

public static <E> Buffer<E> typedBuffer(Buffer<E> buffer,
                                        Class<E> type)

Deprecated. No longer required with Java 1.5 Generics.

Returns a typed buffer backed by the given buffer.

Only elements of the specified type can be added to the buffer.

Parameters:

buffer - the buffer to predicate, must not be null

type - the type to allow into the buffer, must not be null

Returns:

a typed buffer

Throws:

IllegalArgumentException - if the buffer or type is null

transformedBuffer

public static <I,O> Buffer<O> transformedBuffer(Buffer<I> buffer,
                                                Transformer<I,O> transformer)

Returns a transformed buffer backed by the given buffer.

Each object is passed through the transformer as it is added to the Buffer. It is important not to use the original buffer after invoking this method, as it is a backdoor for adding untransformed objects.

Parameters:

buffer - the buffer to predicate, must not be null

transformer - the transformer for the buffer, must not be null

Returns:

a transformed buffer backed by the given buffer

Throws:

IllegalArgumentException - if the Buffer or Transformer is null