de.unkrig.commons.io.pipe

Class PipeFactory

java.lang.Object

de.unkrig.commons.io.pipe.PipeFactory

public final class PipeFactory
extends Object

The methods of this class create the various Pipe implementations:

byteArrayRingBuffer(int)

A pipe which is backed by an (internal) byte array

byteBufferRingBuffer(ByteBuffer)

A pipe which is backed by a ByteBuffer

elasticPipe()

A Pipe that implements infinite capacity and good performance by first allocating a small in-memory ring buffer, then, if that fills up, a larger one that uses a memory-mapped file, and eventually one based on a random access file with practically unlimited size

elasticPipe(de.unkrig.commons.lang.protocol.ProducerWhichThrows)

A Pipe that implements infinite capacity by allocating delegate pipes as needed (and closing them when they are no longer needed)

mappedFileRingBuffer(java.io.File, int, boolean)

A pipe which is backed by a memory-mapped file, which will be unmapped and (optionally) deleted when the pipe is closed

mappedTempFileRingBuffer(int)

A pipe which is backed by a memory-mapped temporary file, which will be unmapped and deleted when the pipe is closed

randomAccessFileRingBuffer(java.io.File, long, boolean)

A pipe which is backed by a RandomAccessFile, which will (optionally) be deleted when the pipe is closed

randomAccessTempFileRingBuffer(long)

A pipe which is backed by a temporary RandomAccessFile, which is deleted when the pipe is closed

The characteristics of these implementations are as follows:

	Performance	Resource usage	Size limits
byteArrayRingBuffer(int)	Fast	Heap memory	2 GB
byteBufferRingBuffer(ByteBuffer.allocate(int))	Fast	Heap memory	2 GB
byteBufferRingBuffer(ByteBuffer.allocateDirect(int))	Fast	Off-heap memory	2 GB
mappedFileRingBuffer(File, int, boolean)	Medium	Low	2 GB, Address space, disk space
randomAccessFileRingBuffer(File, long, boolean)	Low	Low	Disk space

Method Summary

Modifier and Type	Method and Description
static Pipe	byteArrayRingBuffer(int capacity)
static Pipe	byteBufferRingBuffer(ByteBuffer delegate)
static Pipe	elasticPipe()
static Pipe	elasticPipe(ProducerWhichThrows<? extends Pipe,? extends IOException> pipes)
static Pipe	mappedFileRingBuffer(File file, int capacity, boolean deleteFileOnClose)
static Pipe	mappedTempFileRingBuffer(int capacity)
static Pipe	randomAccessFileRingBuffer(File file, long capacity, boolean deleteFileOnClose)
static Pipe	randomAccessTempFileRingBuffer(long capacity)

Methods inherited from class java.lang.Object

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

Method Detail

byteArrayRingBuffer

public static Pipe byteArrayRingBuffer(int capacity)

Returns:

A pipe which is backed by an (internal) byte array of size capacity

randomAccessTempFileRingBuffer

public static Pipe randomAccessTempFileRingBuffer(long capacity)
                                           throws IOException

Returns:

A pipe which is backed by a temporary RandomAccessFile, which is deleted when the pipe is closed

Throws:

IOException

randomAccessFileRingBuffer

public static Pipe randomAccessFileRingBuffer(File file,
                                              long capacity,
                                              boolean deleteFileOnClose)
                                       throws IOException

Parameters:

file - Will be created if it does not exist; any existing contents will progressively be overwritten by Pipe.write(byte[], int, int)

deleteFileOnClose - Whether to delete the file when the pipe is closed

Returns:

A pipe which is backed by the file

Throws:

RuntimeException - capacity is less than one

IOException

byteBufferRingBuffer

public static Pipe byteBufferRingBuffer(ByteBuffer delegate)

Returns:

A pipe which is backed by the delegate ByteBuffer and has the same size

See Also:

ByteBuffer.allocate(int), ByteBuffer.allocateDirect(int)

mappedTempFileRingBuffer

public static Pipe mappedTempFileRingBuffer(int capacity)
                                     throws IOException

Returns:

A pipe which is backed by a memory-mapped temporary file, which will be unmapped and deleted when the pipe is closed

Throws:

IOException

mappedFileRingBuffer

public static Pipe mappedFileRingBuffer(File file,
                                        int capacity,
                                        boolean deleteFileOnClose)
                                 throws IOException

Parameters:

capacity - The number of bytes in the file to use for buffering

deleteFileOnClose - Whether the file should be deleted when the pipe is closed

Returns:

A pipe which is backed by the memory-mapped file, which will be unmapped and (optionally) deleted when the pipe is closed

Throws:

IOException

elasticPipe

public static Pipe elasticPipe()

Returns:

A Pipe that implements infinite capacity and good performance by first allocating a small in-memory ring buffer, then, if that fills up, a larger one that uses a memory-mapped temporary file, and eventually one that is backed by a random access file with practically unlimited size

elasticPipe

public static Pipe elasticPipe(ProducerWhichThrows<? extends Pipe,? extends IOException> pipes)

Parameters:

pipes - Is invoked when another pipe is needed; the produced pipes are closed when they are no longer needed, or when the returned pipe is closed

Returns:

A Pipe that implements infinite capacity by allocating delegate pipes as needed (and closing them when they are no longer needed)