org.forgerock.http.io

Class IO

java.lang.Object

org.forgerock.http.io.IO

public final class IO
extends Object

Utility class that can stream to and from streams.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_TMP_FILE_LIMIT 1 GiB.
static int	DEFAULT_TMP_INIT_LENGTH 8 KiB.
static int	DEFAULT_TMP_MEMORY_LIMIT 64 KiB.

Method Summary

Modifier and Type	Method and Description
static BranchingInputStream	newBranchingInputStream(byte[] bytes) Creates a new branching input stream that wraps a byte array.
static BranchingInputStream	newBranchingInputStream(InputStream in, Factory<Buffer> bufferFactory) Creates a new branching input stream to wrap another input stream.
static Buffer	newFileBuffer(File file, int limit) Creates a new file buffer that uses a local file for data storage.
static Buffer	newMemoryBuffer(int initial, int limit) Creates a new buffer that uses a byte array for data storage.
static Buffer	newTemporaryBuffer(int initialLength, int memoryLimit, int fileLimit, File directory) Creates a new temporary buffer that first uses memory, then a temporary file for data storage.
static Factory<Buffer>	newTemporaryStorage() Creates a new storage using the system dependent default temporary directory and default sizes.
static Factory<Buffer>	newTemporaryStorage(File directory) Builds a storage using the given directory (may be null) and default sizes.
static Factory<Buffer>	newTemporaryStorage(File directory, int initialLength, int memoryLimit, int fileLimit) Builds a storage using the given directory (may be null) and provided sizes.
static InputStream	nullInputStream() Returns an input stream that holds no data.
static OutputStream	nullOutputStream() Returns an output stream that discards all data written to it.
static void	stream(InputStream in, OutputStream out) Streams all data from an input stream to an output stream.
static void	stream(InputStream in, OutputStream out, boolean forceFlush) Streams all data from an input stream to an output stream.
static int	stream(InputStream in, OutputStream out, int len) Streams data from an input stream to an output stream, up to a specified length.
static void	stream(Reader in, Writer out) Streams all characters from a reader to a writer.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TMP_INIT_LENGTH

public static final int DEFAULT_TMP_INIT_LENGTH

8 KiB.

See Also:

Constant Field Values

DEFAULT_TMP_MEMORY_LIMIT

public static final int DEFAULT_TMP_MEMORY_LIMIT

64 KiB.

See Also:

Constant Field Values

DEFAULT_TMP_FILE_LIMIT

public static final int DEFAULT_TMP_FILE_LIMIT

1 GiB.

See Also:

Constant Field Values

Method Detail

newBranchingInputStream

public static BranchingInputStream newBranchingInputStream(byte[] bytes)

Creates a new branching input stream that wraps a byte array.

Parameters:

bytes - byte array to wrap with the branching input stream.

Returns:

The branching input stream.

newBranchingInputStream

public static BranchingInputStream newBranchingInputStream(InputStream in,
                                                           Factory<Buffer> bufferFactory)

Creates a new branching input stream to wrap another input stream. All divergence between branches is maintained in a temporary buffer.

If the stream being wrapped is a branching input stream, this constructor will simply branch off of that existing stream rather than wrapping it with another branching input stream.

Note: This stream and any branches it creates are not safe for use by multiple concurrent threads.

Parameters:

in - the stream to be wrapped.

bufferFactory - an object that can create new temporary buffers (e.g. @link TemporaryStorage}).

Returns:

The branching input stream.

newFileBuffer

public static Buffer newFileBuffer(File file,
                                   int limit)
                            throws FileNotFoundException

Creates a new file buffer that uses a local file for data storage.

Note: The returned buffer is not synchronized. If multiple threads access a buffer concurrently, threads that append to the buffer should synchronize on the instance of this object.

Parameters:

file - the file to use as storage for the buffer.

limit - the buffer length limit, after which an OverflowException will be thrown.

Returns:

The file buffer.

Throws:

FileNotFoundException - if the file cannot be created or opened for writing.

SecurityException - if a security manager denies access to the specified file.

newMemoryBuffer

public static Buffer newMemoryBuffer(int initial,
                                     int limit)

Creates a new buffer that uses a byte array for data storage. The byte array starts at a prescribed initial length, and grows exponentially up to the prescribed limit.

Note: The returned buffer is not synchronized. If multiple threads access a buffer concurrently, threads that append to the buffer should synchronize on the instance of this object.

Parameters:

initial - the initial size of the byte array to create.

limit - the buffer length limit, after which an OverflowException will be thrown.

Returns:

The memory buffer.

newTemporaryBuffer

public static Buffer newTemporaryBuffer(int initialLength,
                                        int memoryLimit,
                                        int fileLimit,
                                        File directory)

Creates a new temporary buffer that first uses memory, then a temporary file for data storage. Initially, a memory buffer is used; when the memory buffer limit is exceeded it promotes to the use of a file buffer.

Parameters:

initialLength - the initial length of memory buffer byte array.

memoryLimit - the length limit of the memory buffer.

fileLimit - the length limit of the file buffer.

directory - the directory where temporary files are created, or null to use the system-dependent default temporary directory.

Returns:

The temporary buffer.

newTemporaryStorage

public static Factory<Buffer> newTemporaryStorage()

Creates a new storage using the system dependent default temporary directory and default sizes. Equivalent to call newTemporaryStorage(null).

Returns:

The temporary storage.

newTemporaryStorage

public static Factory<Buffer> newTemporaryStorage(File directory)

Builds a storage using the given directory (may be null) and default sizes. Equivalent to call newTemporaryStorage(directory, HEIGHT_KB, SIXTY_FOUR_KB, ONE_MB) .

Parameters:

directory - The directory where temporary files are created. If null, then the system-dependent default temporary directory will be used.

Returns:

The temporary storage.

newTemporaryStorage

public static Factory<Buffer> newTemporaryStorage(File directory,
                                                  int initialLength,
                                                  int memoryLimit,
                                                  int fileLimit)

Builds a storage using the given directory (may be null) and provided sizes.

Parameters:

directory - The directory where temporary files are created. If null, then the system-dependent default temporary directory will be used.

initialLength - The initial length of memory buffer byte array.

memoryLimit - The length limit of the memory buffer. Attempts to exceed this limit will result in promoting the buffer from a memory to a file buffer.

fileLimit - The length limit of the file buffer. Attempts to exceed this limit will result in an OverflowException being thrown.

Returns:

The temporary storage.

nullInputStream

public static InputStream nullInputStream()

Returns an input stream that holds no data.

Returns:

An input stream that holds no data.

nullOutputStream

public static OutputStream nullOutputStream()

Returns an output stream that discards all data written to it.

Returns:

An output stream that discards all data written to it.

stream

public static void stream(InputStream in,
                          OutputStream out)
                   throws IOException

Streams all data from an input stream to an output stream.

Parameters:

in - the input stream to stream the data from.

out - the output stream to stream the data to.

Throws:

IOException - if an I/O exception occurs.

stream

public static void stream(InputStream in,
                          OutputStream out,
                          boolean forceFlush)
                   throws IOException

Streams all data from an input stream to an output stream.

Parameters:

in - the input stream to stream the data from.

out - the output stream to stream the data to.

forceFlush - flush the output stream after each buffer is written.

Throws:

IOException - if an I/O exception occurs.

stream

public static int stream(InputStream in,
                         OutputStream out,
                         int len)
                  throws IOException

Streams data from an input stream to an output stream, up to a specified length.

Parameters:

in - the input stream to stream the data from.

out - the output stream to stream the data to.

len - the number of bytes to stream.

Returns:

the actual number of bytes streamed.

Throws:

IOException - if an I/O exception occurs.

stream

public static void stream(Reader in,
                          Writer out)
                   throws IOException

Streams all characters from a reader to a writer.

Parameters:

in - reader to stream the characters from.

out - the writer to stream the characters to.

Throws:

IOException - if an I/O exception occurs.