net.sf.mmm.util.io.api
Interface StreamUtil

All Known Implementing Classes:

StreamUtilImpl

@ComponentSpecification
public interface StreamUtil

This is the interface for a collection of utility functions that help to deal with InputStreams, OutputStreams, Readers and Writers.
Information:
Whenever the javadoc of a method specifies that an object (stream, reader or writer) is closed, then this means that it will be closed on successful return of the method as well as in an exceptional state. If it says that an object is NOT closed then the caller is responsible to ensure that it will be closed properly.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

StreamUtilImpl

Method Summary

void	close(Channel channel) This method closes the given channel without throwing an Exception.
void	close(InputStream inputStream) This method closes the given inputStream without throwing an Exception.
void	close(OutputStream outputStream) This method closes the given outputStream without throwing an IOException.
void	close(Reader reader) This method closes the given reader without throwing an Exception.
void	close(Writer writer) This method closes the given writer without throwing an IOException.
Properties	loadProperties(InputStream inStream) This method loads the Properties from the given inStream and closes it.
Properties	loadProperties(Reader reader) This method loads the Properties from the given reader and closes it.
String	read(Reader reader) This method reads the contents of the given reader into a string.
PrintWriter	toPrintWriter(Appendable appendable) This method converts the given Appendable to a PrintWriter.
Writer	toWriter(Appendable appendable) This method converts the given Appendable to a Writer.
long	transfer(FileInputStream inStream, OutputStream outStream, boolean keepOutStreamOpen) This method transfers the contents of the given inStream to the given outStream using NIO-Channels.
long	transfer(InputStream inStream, FileOutputStream outStream, boolean keepOutStreamOpen, long size) This method transfers the contents of the given inStream to the given outStream using NIO-Channels.
long	transfer(InputStream inStream, OutputStream outStream, boolean keepOutStreamOpen) This method transfers the contents of the given inStream to the given outStream.
long	transfer(Reader reader, Writer writer, boolean keepWriterOpen) This method transfers the contents of the given reader to the given writer.
AsyncTransferrer	transferAsync(InputStream inStream, OutputStream outStream, boolean keepOutStreamOpen) This method transfers the contents of the given inStream to the given outStream.
AsyncTransferrer	transferAsync(InputStream inStream, OutputStream outStream, boolean keepOutStreamOpen, TransferCallback callback) This method transfers the contents of the given inStream to the given outStream.
AsyncTransferrer	transferAsync(Reader reader, Writer writer, boolean keepWriterOpen) This method transfers the contents of the given reader to the given writer.
AsyncTransferrer	transferAsync(Reader reader, Writer writer, boolean keepWriterOpen, TransferCallback callback) This method transfers the contents of the given reader to the given writer.

Method Detail

read

String read(Reader reader)
            throws IOException

This method reads the contents of the given reader into a string.
ATTENTION:
Only use this method if you know what you are doing. This method will cause that the complete content of the given reader is read into memory.

Parameters:

reader - is where to read the content from. It will be closed at the end.

Returns:

the content of the given reader.

Throws:

IOException - if an error occurred with an I/O error.

transfer

long transfer(Reader reader,
              Writer writer,
              boolean keepWriterOpen)
              throws IOException

This method transfers the contents of the given reader to the given writer.

Parameters:

reader - is where to read the content from. Will be closed at the end.

writer - is where to write the content to. Will be closed at the end if keepWriterOpen is false.

keepWriterOpen - if true the given writer will remain open so that additional content can be appended. Else if false, the writer will be closed.

Returns:

the number of bytes that have been transferred.

Throws:

IOException - if the operation failed. Closing is guaranteed even in exception state.

transfer

long transfer(FileInputStream inStream,
              OutputStream outStream,
              boolean keepOutStreamOpen)
              throws IOException

This method transfers the contents of the given inStream to the given outStream using NIO-Channels.

Parameters:

inStream - is where to read the content from. Will be closed at the end.

outStream - is where to write the content to. Will be closed at the end if keepOutStreamOpen is false.

keepOutStreamOpen - if true the given outStream will remain open so that additional content can be appended. Else if false, the outStream will be closed.

Returns:

the number of bytes that have been transferred.

Throws:

IOException - if the operation failed. Closing is guaranteed even in exception state.

transfer

long transfer(InputStream inStream,
              FileOutputStream outStream,
              boolean keepOutStreamOpen,
              long size)
              throws IOException

This method transfers the contents of the given inStream to the given outStream using NIO-Channels.

Parameters:

inStream - is where to read the content from. Will be closed at the end.

outStream - is where to write the content to. Will be closed at the end if keepOutStreamOpen is false.

keepOutStreamOpen - if true the given outStream will remain open so that additional content can be appended. Else if false, the outStream will be closed.

size - is the number of bytes to transfer.

Returns:

the number of bytes that have been transferred.

Throws:

IOException - if the operation failed. Closing is guaranteed even in exception state.

transfer

long transfer(InputStream inStream,
              OutputStream outStream,
              boolean keepOutStreamOpen)
              throws IOException

This method transfers the contents of the given inStream to the given outStream.

Parameters:

inStream - is where to read the content from. Will be closed at the end.

outStream - is where to write the content to. Will be closed at the end if keepOutStreamOpen is false.

keepOutStreamOpen - if true the given outStream will remain open so that additional content can be appended. Else if false, the outStream will be closed.

Returns:

the number of bytes that have been transferred.

Throws:

IOException - if the operation failed. Closing is guaranteed even in exception state.

transferAsync

AsyncTransferrer transferAsync(InputStream inStream,
                               OutputStream outStream,
                               boolean keepOutStreamOpen)

This method transfers the contents of the given inStream to the given outStream.

Parameters:

inStream - is where to read the content from. Will be closed at the end.

outStream - is where to write the content to. Will be closed at the end if keepOutStreamOpen is false.

keepOutStreamOpen - if true the given outStream will remain open so that additional content can be appended. Else if false, the outStream will be closed.

Returns:

the number of bytes that have been transferred.

transferAsync

AsyncTransferrer transferAsync(InputStream inStream,
                               OutputStream outStream,
                               boolean keepOutStreamOpen,
                               TransferCallback callback)

This method transfers the contents of the given inStream to the given outStream.

Parameters:

inStream - is where to read the content from. Will be closed at the end.

outStream - is where to write the content to. Will be closed at the end if keepOutStreamOpen is false.

keepOutStreamOpen - if true the given outStream will remain open so that additional content can be appended. Else if false, the outStream will be closed.

callback - is the callback that is invoked if the transfer is done.

Returns:

the number of bytes that have been transferred.

transferAsync

AsyncTransferrer transferAsync(Reader reader,
                               Writer writer,
                               boolean keepWriterOpen)

This method transfers the contents of the given reader to the given writer.

Parameters:

reader - is where to read the content from. Will be closed at the end.

writer - is where to write the content to. Will be closed at the end if keepWriterOpen is false.

keepWriterOpen - if true the given writer will remain open so that additional content can be appended. Else if false, the writer will be closed.

Returns:

the number of bytes that have been transferred.

transferAsync

AsyncTransferrer transferAsync(Reader reader,
                               Writer writer,
                               boolean keepWriterOpen,
                               TransferCallback callback)

This method transfers the contents of the given reader to the given writer.

Parameters:

reader - is where to read the content from. Will be closed at the end.

writer - is where to write the content to. Will be closed at the end if keepWriterOpen is false.

keepWriterOpen - if true the given writer will remain open so that additional content can be appended. Else if false, the writer will be closed.

callback - is the callback that is invoked if the transfer is done.

Returns:

the number of bytes that have been transferred.

loadProperties

Properties loadProperties(InputStream inStream)
                          throws IOException

This method loads the Properties from the given inStream and closes it.
ATTENTION:
This method loads the properties using the encoding ISO-8859-1 . Use loadProperties(Reader) instead to use an explicit encoding (e.g. UTF-8).

Parameters:

inStream - is the InputStream to the properties data.

Returns:

the properties read from the given inStream.

Throws:

IOException - if the operation failed. Closing is guaranteed even in exception state.

See Also:

Properties.load(InputStream)

loadProperties

Properties loadProperties(Reader reader)
                          throws IOException

This method loads the Properties from the given reader and closes it.

Parameters:

reader - is the Reader to the properties data.

Returns:

the properties read from the given reader.

Throws:

IOException - if the operation failed. Closing is guaranteed even in exception state.

See Also:

Properties.load(Reader)

toWriter

Writer toWriter(Appendable appendable)

This method converts the given Appendable to a Writer.

Parameters:

appendable - is the Appendable to wrap.

Returns:

the adapting Writer.

Since:

2.0.0

toPrintWriter

PrintWriter toPrintWriter(Appendable appendable)

This method converts the given Appendable to a PrintWriter.

Parameters:

appendable - is the Appendable to wrap.

Returns:

the adapting PrintWriter.

Since:

2.0.0

close

void close(InputStream inputStream)

This method closes the given inputStream without throwing an Exception. If an exception occurs, it will only be logged.

Parameters:

inputStream - is the input-stream to close.

close

void close(OutputStream outputStream)
           throws RuntimeIoException

This method closes the given outputStream without throwing an IOException.

Parameters:

outputStream - is the output-stream to close.

Throws:

RuntimeIoException - if the closing failed.

close

void close(Writer writer)
           throws RuntimeIoException

This method closes the given writer without throwing an IOException.

Parameters:

writer - is the writer to close.

Throws:

RuntimeIoException - if the closing failed.

close

void close(Reader reader)

This method closes the given reader without throwing an Exception. If an exception occurs, it will only be logged.

Parameters:

reader - is the reader to close.

close

void close(Channel channel)

This method closes the given channel without throwing an Exception.

Parameters:

channel - is the channel to close.