net.markenwerk.utils.data.fetcher

Interface DataFetcher

All Known Implementing Classes:

AbstractBufferedDataFetcher, AbstractDataFetcher, BufferedDataFetcher

public interface DataFetcher

A DataFetcher can fetch the entire content of a given InputStream into a fresh byte[] or copy it into a given OutputStream.

It is, among other things, intended as a replacement for IOUtils.toByteArray() to perform the everyday and menial task of reading an entire InputStream.

Since the class sun.misc.IOUtils, which provides this functionality, is not a part of the official Java specification, usages of this class will usually yield a compiler warning like "The type 'IOUtils' is not API" and might break at runtime, if a runtime environment other than the Oracle JRE is used.

All methods take optional parameters to specify the buffer size and to specify, whether the provided streams should be closed afterwards. This allows to write compact code like

 {
        foo.setContent(fetcher.fetch(new FileInputStream(file), true));
 }
 

instead of unnecessarily verbose code like

 {
        InputStream in = new FileInputStream(file);
        foo.setContent(fetcher.fetch(in));
        in.close();
 }
 

Since:

4.0.0

Author:

Torsten Krause (tk at markenwerk dot net)

Method Summary

Modifier and Type	Method and Description
void	copy(InputStream in, OutputStream out) Copies the content of a given InputStream into a given OutputStream.
void	copy(InputStream in, OutputStream out, boolean closeIn, boolean closeOut) Copies the content of a given InputStream into a given OutputStream.
void	copy(InputStream in, OutputStream out, DataFetchProgressListener listener) Copies the content of a given InputStream into a given OutputStream.
void	copy(InputStream in, OutputStream out, DataFetchProgressListener listener, boolean closeIn, boolean closeOut) Copies the content of a given InputStream into a given OutputStream.
byte[]	fetch(InputStream in) Fetches the content of a given InputStream into a fresh byte[].
byte[]	fetch(InputStream in, boolean close) Fetches the content of a given InputStream into a fresh byte[].
byte[]	fetch(InputStream in, DataFetchProgressListener listener) Fetches the content of a given InputStream into a fresh byte[].
byte[]	fetch(InputStream in, DataFetchProgressListener listener, boolean close) Fetches the content of a given InputStream into a fresh byte[].

Method Detail

fetch

byte[] fetch(InputStream in)
      throws DataFetchException

Fetches the content of a given InputStream into a fresh byte[].

See copy(InputStream, OutputStream, boolean, boolean) for the handling of missing or invalid arguments.

Parameters:

in - The InputStream to read from.

Returns:

A new byte[], containing the content of the given InputStream.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream.

fetch

byte[] fetch(InputStream in,
             boolean close)
      throws DataFetchException

Fetches the content of a given InputStream into a fresh byte[].

See copy(InputStream, OutputStream, boolean, boolean) for the handling of missing or invalid arguments.

Parameters:

in - The InputStream to read from.

close - Whether to close the given InputStream, after reading from it.

Returns:

A new byte[], containing the content of the given InputStream.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream. FetchExceptions thrown while trying to close the given InputStream, if requested, are ignored.

fetch

byte[] fetch(InputStream in,
             DataFetchProgressListener listener,
             boolean close)
      throws DataFetchException

Fetches the content of a given InputStream into a fresh byte[].

See copy(InputStream, OutputStream, boolean, boolean) for the handling of missing or invalid arguments.

Parameters:

in - The InputStream to read from.

listener - The DataFetchProgressListener to report to.

close - Whether to close the given InputStream, after reading from it.

Returns:

A new byte[], containing the content of the given InputStream.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream. FetchExceptions thrown while trying to close the given InputStream, if requested, are ignored.

fetch

byte[] fetch(InputStream in,
             DataFetchProgressListener listener)
      throws DataFetchException

Fetches the content of a given InputStream into a fresh byte[].

See copy(InputStream, OutputStream, boolean, boolean) for the handling of missing or invalid arguments.

Parameters:

in - The InputStream to read from.

listener - The DataFetchProgressListener to report to.

Returns:

A new byte[], containing the content of the given InputStream.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream.

copy

void copy(InputStream in,
          OutputStream out)
   throws DataFetchException

Copies the content of a given InputStream into a given OutputStream.

See copy(InputStream, OutputStream, boolean, boolean) for the handling of missing or invalid arguments.

Parameters:

in - The InputStream to read from.

out - The OutputStream to write to.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream or writing to the given OutputStream.

copy

void copy(InputStream in,
          OutputStream out,
          boolean closeIn,
          boolean closeOut)
   throws DataFetchException

Copies the content of a given InputStream into a given OutputStream.

Missing or invalid arguments are handled gracefully with the following behaviour.

A null is given as an InputStream, it is simply ignored and handled as if there was nothing to read. If closeOut is true, the given OutputStream will be closed anyway

A null is given as an OutputStream, it is simply ignored, but the content of given InputStream is fetched anyway. If closeIn is true, the given InputStream will be closed anyway

Parameters:

in - The InputStream to read from.

out - The OutputStream to write to.

closeIn - Whether to close the given InputStream, after reading from it.

closeOut - Whether to close the given OutputStream, after writing to it.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream or writing to the given OutputStream. FetchExceptions thrown while trying to close one of the given streams, if requested, are ignored.

copy

void copy(InputStream in,
          OutputStream out,
          DataFetchProgressListener listener)
   throws DataFetchException

Copies the content of a given InputStream into a given OutputStream.

See copy(InputStream, OutputStream, boolean, boolean) for the handling of missing or invalid arguments.

Parameters:

in - The InputStream to read from.

out - The OutputStream to write to.

listener - The DataFetchProgressListener to report to.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream or writing to the given OutputStream.

copy

void copy(InputStream in,
          OutputStream out,
          DataFetchProgressListener listener,
          boolean closeIn,
          boolean closeOut)
   throws DataFetchException

Copies the content of a given InputStream into a given OutputStream.

Missing or invalid arguments are handled gracefully with the following behaviour.

A null is given as an InputStream, it is simply ignored and handled as if there was nothing to read. If closeOut is true, the given OutputStream will be closed anyway

A null is given as an OutputStream, it is simply ignored, but the content of given InputStream is fetched anyway. If closeIn is true, the given InputStream will be closed anyway

Parameters:

in - The InputStream to read from.

out - The OutputStream to write to.

listener - The DataFetchProgressListener to report to.

closeIn - Whether to close the given InputStream, after reading from it.

closeOut - Whether to close the given OutputStream, after writing to it.

Throws:

DataFetchException - If anything went wrong while reading from the given InputStream or writing to the given OutputStream. FetchExceptions thrown while trying to close one of the given streams, if requested, are ignored.