com.google.common.io
Class ByteStreams

java.lang.Object
  extended by com.google.common.io.ByteStreams

public final class ByteStreams
extends Object

Provides utility methods for working with byte arrays and I/O streams.

All method parameters must be non-null unless documented otherwise.

Since:
2009.09.15 tentative
Author:
Chris Nokleberg

Method Summary
static long copy(InputStream from, OutputStream to)
          Copies all bytes from the input stream to the output stream.
static long copy(InputSupplier<? extends InputStream> from, OutputStream to)
          Opens an input stream from the supplier, copies all bytes from the input to the output, and closes the input stream.
static long copy(InputSupplier<? extends InputStream> from, OutputSupplier<? extends OutputStream> to)
          Opens input and output streams from the given suppliers, copies all bytes from the input to the output, and closes the streams.
static long copy(ReadableByteChannel from, WritableByteChannel to)
          Copies all bytes from the readable channel to the writable channel.
static boolean equal(InputSupplier<? extends InputStream> supplier1, InputSupplier<? extends InputStream> supplier2)
          Returns true if the supplied input streams contain the same bytes.
static long getChecksum(InputSupplier<? extends InputStream> supplier, Checksum checksum)
          Computes and returns the checksum value for a supplied input stream.
static byte[] getDigest(InputSupplier<? extends InputStream> supplier, MessageDigest md)
          Computes and returns the digest value for a supplied input stream.
static InputSupplier<InputStream> join(InputSupplier<? extends InputStream>... suppliers)
          Varargs form of join(Iterable).
static InputSupplier<InputStream> join(Iterable<? extends InputSupplier<? extends InputStream>> suppliers)
          Joins multiple InputStream suppliers into a single supplier.
static long length(InputSupplier<? extends InputStream> supplier)
          Returns the length of a supplied input stream, in bytes.
static ByteArrayDataInput newDataInput(byte[] bytes)
          Returns a new ByteArrayDataInput instance to read from the bytes array from the beginning.
static ByteArrayDataInput newDataInput(byte[] bytes, int start)
          Returns a new ByteArrayDataInput instance to read from the bytes array, starting at the given position.
static ByteArrayDataOutput newDataOutput()
          Returns a new ByteArrayDataOutput instance with a default size.
static ByteArrayDataOutput newDataOutput(int size)
          Returns a new ByteArrayDataOutput instance sized to hold size bytes before resizing.
static InputSupplier<ByteArrayInputStream> newInputStreamSupplier(byte[] b)
          Returns a factory that will supply instances of ByteArrayInputStream that read from the given byte array.
static InputSupplier<ByteArrayInputStream> newInputStreamSupplier(byte[] b, int off, int len)
          Returns a factory that will supply instances of ByteArrayInputStream that read from the given byte array.
static int read(InputStream in, byte[] b, int off, int len)
          Reads some bytes from an input stream and stores them into the buffer array b.
static
<T> T
readBytes(InputSupplier<? extends InputStream> supplier, ByteProcessor<T> processor)
          Process the bytes of a supplied stream
static void readFully(InputStream in, byte[] b)
          Attempts to read enough bytes from the stream to fill the given byte array, with the same behavior as DataInput.readFully(byte[]).
static void readFully(InputStream in, byte[] b, int off, int len)
          Attempts to read len bytes from the stream into the given array starting at off, with the same behavior as DataInput.readFully(byte[], int, int).
static void skipFully(InputStream in, long n)
          Discards n bytes of data from the input stream.
static InputSupplier<InputStream> slice(InputSupplier<? extends InputStream> supplier, long offset, long length)
          Returns an InputSupplier that returns input streams from the an underlying supplier, where each stream starts at the given offset and is limited to the specified number of bytes.
static byte[] toByteArray(InputStream in)
          Reads all bytes from an input stream into a byte array.
static byte[] toByteArray(InputSupplier<? extends InputStream> supplier)
          Returns the data from a InputStream factory as a byte array.
static void write(byte[] from, OutputSupplier<? extends OutputStream> to)
          Writes a byte array to an output stream from the given supplier.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

newInputStreamSupplier

public static InputSupplier<ByteArrayInputStream> newInputStreamSupplier(byte[] b)
Returns a factory that will supply instances of ByteArrayInputStream that read from the given byte array.

Parameters:
b - the input buffer
Returns:
the factory

newInputStreamSupplier

public static InputSupplier<ByteArrayInputStream> newInputStreamSupplier(byte[] b,
                                                                         int off,
                                                                         int len)
Returns a factory that will supply instances of ByteArrayInputStream that read from the given byte array.

Parameters:
b - the input buffer
off - the offset in the buffer of the first byte to read
len - the maximum number of bytes to read from the buffer
Returns:
the factory

write

public static void write(byte[] from,
                         OutputSupplier<? extends OutputStream> to)
                  throws IOException
Writes a byte array to an output stream from the given supplier.

Parameters:
from - the bytes to write
to - the output supplier
Throws:
IOException - if an I/O error occurs

copy

public static long copy(InputSupplier<? extends InputStream> from,
                        OutputSupplier<? extends OutputStream> to)
                 throws IOException
Opens input and output streams from the given suppliers, copies all bytes from the input to the output, and closes the streams.

Parameters:
from - the input factory
to - the output factory
Returns:
the number of bytes copied
Throws:
IOException - if an I/O error occurs

copy

public static long copy(InputSupplier<? extends InputStream> from,
                        OutputStream to)
                 throws IOException
Opens an input stream from the supplier, copies all bytes from the input to the output, and closes the input stream. Does not close or flush the output stream.

Parameters:
from - the input factory
to - the output stream to write to
Returns:
the number of bytes copied
Throws:
IOException - if an I/O error occurs

copy

public static long copy(InputStream from,
                        OutputStream to)
                 throws IOException
Copies all bytes from the input stream to the output stream. Does not close or flush either stream.

Parameters:
from - the input stream to read from
to - the output stream to write to
Returns:
the number of bytes copied
Throws:
IOException - if an I/O error occurs

copy

public static long copy(ReadableByteChannel from,
                        WritableByteChannel to)
                 throws IOException
Copies all bytes from the readable channel to the writable channel. Does not close or flush either channel.

Parameters:
from - the readable channel to read from
to - the writable channel to write to
Returns:
the number of bytes copied
Throws:
IOException - if an I/O error occurs

toByteArray

public static byte[] toByteArray(InputStream in)
                          throws IOException
Reads all bytes from an input stream into a byte array. Does not close the stream.

Parameters:
in - the input stream to read from
Returns:
a byte array containing all the bytes from the stream
Throws:
IOException - if an I/O error occurs

toByteArray

public static byte[] toByteArray(InputSupplier<? extends InputStream> supplier)
                          throws IOException
Returns the data from a InputStream factory as a byte array.

Parameters:
supplier - the factory
Throws:
IOException - if an I/O error occurs

newDataInput

public static ByteArrayDataInput newDataInput(byte[] bytes)
Returns a new ByteArrayDataInput instance to read from the bytes array from the beginning.


newDataInput

public static ByteArrayDataInput newDataInput(byte[] bytes,
                                              int start)
Returns a new ByteArrayDataInput instance to read from the bytes array, starting at the given position.

Throws:
IndexOutOfBoundsException - if start is negative or greater than the length of the array

newDataOutput

public static ByteArrayDataOutput newDataOutput()
Returns a new ByteArrayDataOutput instance with a default size.


newDataOutput

public static ByteArrayDataOutput newDataOutput(int size)
Returns a new ByteArrayDataOutput instance sized to hold size bytes before resizing.

Throws:
IllegalArgumentException - if size is negative

length

public static long length(InputSupplier<? extends InputStream> supplier)
                   throws IOException
Returns the length of a supplied input stream, in bytes.

Throws:
IOException

equal

public static boolean equal(InputSupplier<? extends InputStream> supplier1,
                            InputSupplier<? extends InputStream> supplier2)
                     throws IOException
Returns true if the supplied input streams contain the same bytes.

Throws:
IOException - if an I/O error occurs

readFully

public static void readFully(InputStream in,
                             byte[] b)
                      throws IOException
Attempts to read enough bytes from the stream to fill the given byte array, with the same behavior as DataInput.readFully(byte[]). Does not close the stream.

Parameters:
in - the input stream to read from.
b - the buffer into which the data is read.
Throws:
EOFException - if this stream reaches the end before reading all the bytes.
IOException - if an I/O error occurs.

readFully

public static void readFully(InputStream in,
                             byte[] b,
                             int off,
                             int len)
                      throws IOException
Attempts to read len bytes from the stream into the given array starting at off, with the same behavior as DataInput.readFully(byte[], int, int). Does not close the stream.

Parameters:
in - the input stream to read from.
b - the buffer into which the data is read.
off - an int specifying the offset into the data.
len - an int specifying the number of bytes to read.
Throws:
EOFException - if this stream reaches the end before reading all the bytes.
IOException - if an I/O error occurs.

skipFully

public static void skipFully(InputStream in,
                             long n)
                      throws IOException
Discards n bytes of data from the input stream. This method will block until the full amount has been skipped. Does not close the stream.

Parameters:
in - the input stream to read from
n - the number of bytes to skip
Throws:
EOFException - if this stream reaches the end before skipping all the bytes
IOException - if an I/O error occurs, or the stream does not support skipping

readBytes

public static <T> T readBytes(InputSupplier<? extends InputStream> supplier,
                              ByteProcessor<T> processor)
                   throws IOException
Process the bytes of a supplied stream

Parameters:
supplier - the input stream factory
processor - the object to which to pass the bytes of the stream
Returns:
the result of the byte processor
Throws:
IOException - if an I/O error occurs

getChecksum

public static long getChecksum(InputSupplier<? extends InputStream> supplier,
                               Checksum checksum)
                        throws IOException
Computes and returns the checksum value for a supplied input stream. The checksum object is reset when this method returns successfully.

Parameters:
supplier - the input stream factory
checksum - the checksum object
Returns:
the result of Checksum.getValue() after updating the checksum object with all of the bytes in the stream
Throws:
IOException - if an I/O error occurs

getDigest

public static byte[] getDigest(InputSupplier<? extends InputStream> supplier,
                               MessageDigest md)
                        throws IOException
Computes and returns the digest value for a supplied input stream. The digest object is reset when this method returns successfully.

Parameters:
supplier - the input stream factory
md - the digest object
Returns:
the result of MessageDigest.digest() after updating the digest object with all of the bytes in the stream
Throws:
IOException - if an I/O error occurs

read

public static int read(InputStream in,
                       byte[] b,
                       int off,
                       int len)
                throws IOException
Reads some bytes from an input stream and stores them into the buffer array b. This method blocks until len bytes of input data have been read into the array, or end of file is detected. The number of bytes read is returned, possibly zero. Does not close the stream.

A caller can detect EOF if the number of bytes read is less than len. All subsequent calls on the same stream will return zero.

If b is null, a NullPointerException is thrown. If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. If len is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len.

Parameters:
in - the input stream to read from
b - the buffer into which the data is read
off - an int specifying the offset into the data
len - an int specifying the number of bytes to read
Returns:
the number of bytes read
Throws:
IOException - if an I/O error occurs

slice

public static InputSupplier<InputStream> slice(InputSupplier<? extends InputStream> supplier,
                                               long offset,
                                               long length)
Returns an InputSupplier that returns input streams from the an underlying supplier, where each stream starts at the given offset and is limited to the specified number of bytes.

Parameters:
supplier - the supplier from which to get the raw streams
offset - the offset in bytes into the underlying stream where the returned streams will start
length - the maximum length of the returned streams
Throws:
IllegalArgumentException - if offset or length are negative

join

public static InputSupplier<InputStream> join(Iterable<? extends InputSupplier<? extends InputStream>> suppliers)
Joins multiple InputStream suppliers into a single supplier. Streams returned from the supplier will contain the concatenated data from the streams of the underlying suppliers.

Only one underlying input stream will be open at a time. Closing the joined stream will close the open underlying stream.

Reading from the joined stream will throw a NullPointerException if any of the suppliers are null or return null.

Parameters:
suppliers - the suppliers to concatenate
Returns:
a supplier that will return a stream containing the concatenated stream data

join

public static InputSupplier<InputStream> join(InputSupplier<? extends InputStream>... suppliers)
Varargs form of join(Iterable).