Class ByteStreams
- Since:
- 1.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static classprivate static classprivate static final class -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final intprivate static final intMax array length on JVM.private static final OutputStreamprivate static final intLarge enough to never need to expand, given the geometric progression of buffer sizes.private static final intThere are three methods to implementFileChannel.transferTo(long, long, WritableByteChannel): Use sendfile(2) or equivalent. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static byte[]combineBuffers(Queue<byte[]> bufs, int totalLen) static longcopy(InputStream from, OutputStream to) Copies all bytes from the input stream to the output stream.static longcopy(ReadableByteChannel from, WritableByteChannel to) Copies all bytes from the readable channel to the writable channel.(package private) static byte[]Creates a new byte array for buffering reads or writes.static longexhaust(InputStream in) Reads and discards data from the givenInputStreamuntil the end of the stream is reached.static InputStreamlimit(InputStream in, long limit) Wraps aInputStream, limiting the number of bytes which can be read.static ByteArrayDataInputnewDataInput(byte[] bytes) Returns a newByteArrayDataInputinstance to read from thebytesarray from the beginning.static ByteArrayDataInputnewDataInput(byte[] bytes, int start) Returns a newByteArrayDataInputinstance to read from thebytesarray, starting at the given position.static ByteArrayDataInputnewDataInput(ByteArrayInputStream byteArrayInputStream) Returns a newByteArrayDataInputinstance to read from the givenByteArrayInputStream.static ByteArrayDataOutputReturns a newByteArrayDataOutputinstance with a default size.static ByteArrayDataOutputnewDataOutput(int size) Returns a newByteArrayDataOutputinstance sized to holdsizebytes before resizing.static ByteArrayDataOutputnewDataOutput(ByteArrayOutputStream byteArrayOutputStream) Returns a newByteArrayDataOutputinstance which writes to the givenByteArrayOutputStream.static OutputStreamReturns anOutputStreamthat simply discards written bytes.static intread(InputStream in, byte[] b, int off, int len) Reads some bytes from an input stream and stores them into the buffer arrayb.static <T> TreadBytes(InputStream input, ByteProcessor<T> processor) Process the bytes of the given input stream using the given processor.static voidreadFully(InputStream in, byte[] b) Attempts to read enough bytes from the stream to fill the given byte array, with the same behavior asDataInput.readFully(byte[]).static voidreadFully(InputStream in, byte[] b, int off, int len) Attempts to readlenbytes from the stream into the given array starting atoff, with the same behavior asDataInput.readFully(byte[], int, int).static voidskipFully(InputStream in, long n) Discardsnbytes of data from the input stream.private static longskipSafely(InputStream in, long n) Attempts to skip up tonbytes from the given input stream, but not more thanin.available()bytes.(package private) static longskipUpTo(InputStream in, long n) Discards up tonbytes of data from the input stream.static byte[]Reads all bytes from an input stream into a byte array.(package private) static byte[]toByteArray(InputStream in, long expectedSize) Reads all bytes from an input stream into a byte array.private static byte[]toByteArrayInternal(InputStream in, Queue<byte[]> bufs, int totalLen) Returns a byte array containing the bytes from the buffers already inbufs(which have a total combined length oftotalLenbytes) followed by all bytes remaining in the given input stream.
-
Field Details
-
BUFFER_SIZE
private static final int BUFFER_SIZE- See Also:
-
ZERO_COPY_CHUNK_SIZE
private static final int ZERO_COPY_CHUNK_SIZEThere are three methods to implementFileChannel.transferTo(long, long, WritableByteChannel):- Use sendfile(2) or equivalent. Requires that both the input channel and the output channel have their own file descriptors. Generally this only happens when both channels are files or sockets. This performs zero copies - the bytes never enter userspace.
- Use mmap(2) or equivalent. Requires that either the input channel or the output channel have file descriptors. Bytes are copied from the file into a kernel buffer, then directly into the other buffer (userspace). Note that if the file is very large, a naive implementation will effectively put the whole file in memory. On many systems with paging and virtual memory, this is not a problem - because it is mapped read-only, the kernel can always page it to disk "for free". However, on systems where killing processes happens all the time in normal conditions (i.e., android) the OS must make a tradeoff between paging memory and killing other processes - so allocating a gigantic buffer and then sequentially accessing it could result in other processes dying. This is solvable via madvise(2), but that obviously doesn't exist in java.
- Ordinary copy. Kernel copies bytes into a kernel buffer, from a kernel buffer into a userspace buffer (byte[] or ByteBuffer), then copies them from that buffer into the destination channel.
- See Also:
-
MAX_ARRAY_LEN
private static final int MAX_ARRAY_LENMax array length on JVM.- See Also:
-
TO_BYTE_ARRAY_DEQUE_SIZE
private static final int TO_BYTE_ARRAY_DEQUE_SIZELarge enough to never need to expand, given the geometric progression of buffer sizes.- See Also:
-
NULL_OUTPUT_STREAM
-
-
Constructor Details
-
ByteStreams
private ByteStreams()
-
-
Method Details
-
createBuffer
static byte[] createBuffer()Creates a new byte array for buffering reads or writes. -
copy
Copies all bytes from the input stream to the output stream. Does not close or flush either stream.Java 9 users and later: this method should be treated as deprecated; use the equivalent
InputStream.transferTo(java.io.OutputStream)method instead.- Parameters:
from- the input stream to read fromto- the output stream to write to- Returns:
- the number of bytes copied
- Throws:
IOException- if an I/O error occurs
-
copy
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 fromto- the writable channel to write to- Returns:
- the number of bytes copied
- Throws:
IOException- if an I/O error occurs
-
toByteArrayInternal
private static byte[] toByteArrayInternal(InputStream in, Queue<byte[]> bufs, int totalLen) throws IOException Returns a byte array containing the bytes from the buffers already inbufs(which have a total combined length oftotalLenbytes) followed by all bytes remaining in the given input stream.- Throws:
IOException
-
combineBuffers
-
toByteArray
Reads all bytes from an input stream into a byte array. Does not close the stream.Java 9+ users: use
in#readAllBytes()instead.- 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
Reads all bytes from an input stream into a byte array. The given expected size is used to create an initial byte array, but if the actual number of bytes read from the stream differs, the correct result will be returned anyway.- Throws:
IOException
-
exhaust
Reads and discards data from the givenInputStreamuntil the end of the stream is reached. Returns the total number of bytes read. Does not close the stream.- Throws:
IOException- Since:
- 20.0
-
newDataInput
Returns a newByteArrayDataInputinstance to read from thebytesarray from the beginning. -
newDataInput
Returns a newByteArrayDataInputinstance to read from thebytesarray, starting at the given position.- Throws:
IndexOutOfBoundsException- ifstartis negative or greater than the length of the array
-
newDataInput
Returns a newByteArrayDataInputinstance to read from the givenByteArrayInputStream. The given input stream is not reset before being read from by the returnedByteArrayDataInput.- Since:
- 17.0
-
newDataOutput
Returns a newByteArrayDataOutputinstance with a default size. -
newDataOutput
Returns a newByteArrayDataOutputinstance sized to holdsizebytes before resizing.- Throws:
IllegalArgumentException- ifsizeis negative
-
newDataOutput
Returns a newByteArrayDataOutputinstance which writes to the givenByteArrayOutputStream. The given output stream is not reset before being written to by the returnedByteArrayDataOutputand new data will be appended to any existing content.Note that if the given output stream was not empty or is modified after the
ByteArrayDataOutputis created, the contract forByteArrayDataOutput.toByteArray()will not be honored (the bytes returned in the byte array may not be exactly what was written via calls toByteArrayDataOutput).- Since:
- 17.0
-
nullOutputStream
Returns anOutputStreamthat simply discards written bytes.- Since:
- 14.0 (since 1.0 as com.google.common.io.NullOutputStream)
-
limit
Wraps aInputStream, limiting the number of bytes which can be read.- Parameters:
in- the input stream to be wrappedlimit- 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)
-
readFully
Attempts to read enough bytes from the stream to fill the given byte array, with the same behavior asDataInput.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
Attempts to readlenbytes from the stream into the given array starting atoff, with the same behavior asDataInput.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
Discardsnbytes 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 fromn- the number of bytes to skip- Throws:
EOFException- if this stream reaches the end before skipping all the bytesIOException- if an I/O error occurs, or the stream does not support skipping
-
skipUpTo
Discards up tonbytes of data from the input stream. This method will block until either the full amount has been skipped or until the end of the stream is reached, whichever happens first. Returns the total number of bytes skipped.- Throws:
IOException
-
skipSafely
Attempts to skip up tonbytes from the given input stream, but not more thanin.available()bytes. This preventsFileInputStreamfrom skipping more bytes than actually remain in the file, something that it specifies it can do in its Javadoc despite the fact that it is violating the contract ofInputStream.skip().- Throws:
IOException
-
readBytes
Process the bytes of the given input stream using the given processor.- Parameters:
input- the input stream to processprocessor- 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
-
read
Reads some bytes from an input stream and stores them into the buffer arrayb. This method blocks untillenbytes 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
bis null, aNullPointerExceptionis thrown. Ifoffis negative, orlenis negative, oroff+lenis greater than the length of the arrayb, then anIndexOutOfBoundsExceptionis thrown. Iflenis zero, then no bytes are read. Otherwise, the first byte read is stored into elementb[off], the next one intob[off+1], and so on. The number of bytes read is, at most, equal tolen.- Parameters:
in- the input stream to read fromb- the buffer into which the data is readoff- an int specifying the offset into the datalen- an int specifying the number of bytes to read- Returns:
- the number of bytes read
- Throws:
IOException- if an I/O error occursIndexOutOfBoundsException- ifoffis negative, iflenis negative, or ifoff + lenis greater thanb.length
-