com.google.common.io

Class ByteStreams

java.lang.Object

com.google.common.io.ByteStreams

@Beta
public final class ByteStreams
extends Object

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

Since:

1.0

Author:

Chris Nokleberg, Colin Decker

Method Summary

Methods

Modifier and Type	Method and Description
static ByteSink	asByteSink(OutputSupplier<? extends OutputStream> supplier) Deprecated. Convert all OutputSupplier<? extends OutputStream> implementations to extend ByteSink or provide a method for viewing the object as a ByteSink. This method is scheduled for removal in Guava 18.0.
static ByteSource	asByteSource(InputSupplier<? extends InputStream> supplier) Deprecated. Convert all InputSupplier<? extends InputStream> implementations to extend ByteSource or provide a method for viewing the object as a ByteSource. This method is scheduled for removal in Guava 18.0.
static long	copy(InputStream from, OutputStream to) Copies all bytes from the input stream to the output stream.
static long	copy(InputStream from, OutputSupplier<? extends OutputStream> to) Deprecated. Use ByteSink.writeFrom(InputStream) instead. This method is scheduled for removal in Guava 18.0.
static long	copy(InputSupplier<? extends InputStream> from, OutputStream to) Deprecated. Use ByteSource.copyTo(OutputStream) instead. This method is scheduled for removal in Guava 18.0.
static long	copy(InputSupplier<? extends InputStream> from, OutputSupplier<? extends OutputStream> to) Deprecated. Use ByteSource.copyTo(ByteSink) instead. This method is scheduled for removal in Guava 18.0.
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) Deprecated. Use ByteSource.contentEquals(ByteSource) instead. This method is scheduled for removal in Guava 18.0.
static HashCode	hash(InputSupplier<? extends InputStream> supplier, HashFunction hashFunction) Deprecated. Use ByteSource.hash(HashFunction) instead. This method is scheduled for removal in Guava 18.0.
static InputSupplier<InputStream>	join(InputSupplier<? extends InputStream>... suppliers) Deprecated. Use ByteSource.concat(ByteSource[]) instead. This method is scheduled for removal in Guava 18.0.
static InputSupplier<InputStream>	join(Iterable<? extends InputSupplier<? extends InputStream>> suppliers) Deprecated. Use ByteSource.concat(Iterable) instead. This method is scheduled for removal in Guava 18.0.
static long	length(InputSupplier<? extends InputStream> supplier) Deprecated. Use ByteSource.size() instead. This method is scheduled for removal in Guava 18.0.
static InputStream	limit(InputStream in, long limit) Wraps a InputStream, limiting the number of bytes which can be read.
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 ByteArrayDataInput	newDataInput(ByteArrayInputStream byteArrayInputStream) Returns a new ByteArrayDataInput instance to read from the given ByteArrayInputStream.
static ByteArrayDataOutput	newDataOutput() Returns a new ByteArrayDataOutput instance with a default size.
static ByteArrayDataOutput	newDataOutput(ByteArrayOutputStream byteArrayOutputSteam) Returns a new ByteArrayDataOutput instance which writes to the given ByteArrayOutputStream.
static ByteArrayDataOutput	newDataOutput(int size) Returns a new ByteArrayDataOutput instance sized to hold size bytes before resizing.
static InputSupplier<ByteArrayInputStream>	newInputStreamSupplier(byte[] b) Deprecated. Use ByteSource.wrap(byte[]) instead. This method is scheduled for removal in Guava 18.0.
static InputSupplier<ByteArrayInputStream>	newInputStreamSupplier(byte[] b, int off, int len) Deprecated. Use ByteSource.wrap(b).slice(off, len) instead. This method is scheduled for removal in Guava 18.0.
static OutputStream	nullOutputStream() Returns an OutputStream that simply discards written bytes.
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(InputStream input, ByteProcessor<T> processor) Process the bytes of the given input stream using the given processor.
static <T> T	readBytes(InputSupplier<? extends InputStream> supplier, ByteProcessor<T> processor) Deprecated. Use ByteSource.read(ByteProcessor) instead. This method is scheduled for removal in Guava 18.0.
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) Deprecated. Use ByteSource#slice(int, int) instead. This method is scheduled for removal in Guava 18.0.
static byte[]	toByteArray(InputStream in) Reads all bytes from an input stream into a byte array.
static byte[]	toByteArray(InputSupplier<? extends InputStream> supplier) Deprecated. Use ByteSource.read() instead. This method is scheduled for removal in Guava 18.0.
static void	write(byte[] from, OutputSupplier<? extends OutputStream> to) Deprecated. Use ByteSink.write(byte[]) instead. This method is scheduled for removal in Guava 18.0.

Methods inherited from class java.lang.Object

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

Method Detail

newInputStreamSupplier

@Deprecated
public static InputSupplier<ByteArrayInputStream> newInputStreamSupplier(byte[] b)

Deprecated. Use ByteSource.wrap(byte[]) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static InputSupplier<ByteArrayInputStream> newInputStreamSupplier(byte[] b,
                                                                    int off,
                                                                    int len)

Deprecated. Use ByteSource.wrap(b).slice(off, len) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static void write(byte[] from,
                    OutputSupplier<? extends OutputStream> to)
                  throws IOException

Deprecated. Use ByteSink.write(byte[]) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static long copy(InputSupplier<? extends InputStream> from,
                   OutputSupplier<? extends OutputStream> to)
                 throws IOException

Deprecated. Use ByteSource.copyTo(ByteSink) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static long copy(InputSupplier<? extends InputStream> from,
                   OutputStream to)
                 throws IOException

Deprecated. Use ByteSource.copyTo(OutputStream) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static long copy(InputStream from,
                   OutputSupplier<? extends OutputStream> to)
                 throws IOException

Deprecated. Use ByteSink.writeFrom(InputStream) instead. This method is scheduled for removal in Guava 18.0.

Opens an output stream from the supplier, copies all bytes from the input to the output, and closes the output stream. Does not close or flush the input stream.

Parameters:

from - the input stream to read from

to - the output factory

Returns:

the number of bytes copied

Throws:

IOException - if an I/O error occurs

Since:

10.0

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

@Deprecated
public static byte[] toByteArray(InputSupplier<? extends InputStream> supplier)
                          throws IOException

Deprecated. Use ByteSource.read() instead. This method is scheduled for removal in Guava 18.0.

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

newDataInput

public static ByteArrayDataInput newDataInput(ByteArrayInputStream byteArrayInputStream)

Returns a new ByteArrayDataInput instance to read from the given ByteArrayInputStream. The given input stream is not reset before being read from by the returned ByteArrayDataInput.

Since:

17.0

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

newDataOutput

public static ByteArrayDataOutput newDataOutput(ByteArrayOutputStream byteArrayOutputSteam)

Returns a new ByteArrayDataOutput instance which writes to the given ByteArrayOutputStream. The given output stream is not reset before being written to by the returned ByteArrayDataOutput and new data will be appended to any existing content.

Note that if the given output stream was not empty or is modified after the ByteArrayDataOutput is created, the contract for ByteArrayDataOutput.toByteArray() will not be honored (the bytes returned in the byte array may not be exactly what was written via calls to ByteArrayDataOutput).

Since:

17.0

nullOutputStream

public static OutputStream nullOutputStream()

Returns an OutputStream that simply discards written bytes.

Since:

14.0 (since 1.0 as com.google.common.io.NullOutputStream)

limit

public static InputStream limit(InputStream in,
                long limit)

Wraps a InputStream, limiting the number of bytes which can be read.

Parameters:

in - the input stream to be wrapped

limit - the maximum number of bytes to be read

Returns:

a length-limited InputStream

Since:

14.0 (since 1.0 as com.google.common.io.LimitInputStream)

length

@Deprecated
public static long length(InputSupplier<? extends InputStream> supplier)
                   throws IOException

Deprecated. Use ByteSource.size() instead. This method is scheduled for removal in Guava 18.0.

Returns the length of a supplied input stream, in bytes.

Throws:

IOException

equal

@Deprecated
public static boolean equal(InputSupplier<? extends InputStream> supplier1,
                       InputSupplier<? extends InputStream> supplier2)
                     throws IOException

Deprecated. Use ByteSource.contentEquals(ByteSource) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static <T> T readBytes(InputSupplier<? extends InputStream> supplier,
                         ByteProcessor<T> processor)
                   throws IOException

Deprecated. Use ByteSource.read(ByteProcessor) instead. This method is scheduled for removal in Guava 18.0.

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

readBytes

public static <T> T readBytes(InputStream input,
              ByteProcessor<T> processor)
                   throws IOException

Process the bytes of the given input stream using the given processor.

Parameters:

input - the input stream to process

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

Since:

14.0

hash

@Deprecated
public static HashCode hash(InputSupplier<? extends InputStream> supplier,
                       HashFunction hashFunction)
                     throws IOException

Deprecated. Use ByteSource.hash(HashFunction) instead. This method is scheduled for removal in Guava 18.0.

Computes the hash code of the data supplied by supplier using hashFunction.

Parameters:

supplier - the input stream factory

hashFunction - the hash function to use to hash the data

Returns:

the HashCode of all of the bytes in the input stream

Throws:

IOException - if an I/O error occurs

Since:

12.0

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

@Deprecated
public static InputSupplier<InputStream> slice(InputSupplier<? extends InputStream> supplier,
                                          long offset,
                                          long length)

Deprecated. Use ByteSource#slice(int, int) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static InputSupplier<InputStream> join(Iterable<? extends InputSupplier<? extends InputStream>> suppliers)

Deprecated. Use ByteSource.concat(Iterable) instead. This method is scheduled for removal in Guava 18.0.

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

@Deprecated
public static InputSupplier<InputStream> join(InputSupplier<? extends InputStream>... suppliers)

Deprecated. Use ByteSource.concat(ByteSource[]) instead. This method is scheduled for removal in Guava 18.0.

Varargs form of join(Iterable).

asByteSource

@Deprecated
public static ByteSource asByteSource(InputSupplier<? extends InputStream> supplier)

Deprecated. Convert all InputSupplier<? extends InputStream> implementations to extend ByteSource or provide a method for viewing the object as a ByteSource. This method is scheduled for removal in Guava 18.0.

Returns a view of the given InputStream supplier as a ByteSource.

This method is a temporary method provided for easing migration from suppliers to sources and sinks.

Since:

15.0

asByteSink

@Deprecated
public static ByteSink asByteSink(OutputSupplier<? extends OutputStream> supplier)

Deprecated. Convert all OutputSupplier<? extends OutputStream> implementations to extend ByteSink or provide a method for viewing the object as a ByteSink. This method is scheduled for removal in Guava 18.0.

Returns a view of the given OutputStream supplier as a ByteSink.

This method is a temporary method provided for easing migration from suppliers to sources and sinks.

Since:

15.0