001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.io; 016 017import static com.google.common.base.Preconditions.checkArgument; 018import static com.google.common.base.Preconditions.checkNotNull; 019import static com.google.common.base.Preconditions.checkPositionIndex; 020import static com.google.common.base.Preconditions.checkPositionIndexes; 021import static java.lang.Math.max; 022import static java.lang.Math.min; 023 024import com.google.common.annotations.Beta; 025import com.google.common.annotations.GwtIncompatible; 026import com.google.common.math.IntMath; 027import com.google.errorprone.annotations.CanIgnoreReturnValue; 028import java.io.ByteArrayInputStream; 029import java.io.ByteArrayOutputStream; 030import java.io.DataInput; 031import java.io.DataInputStream; 032import java.io.DataOutput; 033import java.io.DataOutputStream; 034import java.io.EOFException; 035import java.io.FilterInputStream; 036import java.io.IOException; 037import java.io.InputStream; 038import java.io.OutputStream; 039import java.nio.ByteBuffer; 040import java.nio.channels.FileChannel; 041import java.nio.channels.ReadableByteChannel; 042import java.nio.channels.WritableByteChannel; 043import java.util.ArrayDeque; 044import java.util.Arrays; 045import java.util.Queue; 046import javax.annotation.CheckForNull; 047import org.checkerframework.checker.nullness.qual.Nullable; 048 049/** 050 * Provides utility methods for working with byte arrays and I/O streams. 051 * 052 * @author Chris Nokleberg 053 * @author Colin Decker 054 * @since 1.0 055 */ 056@GwtIncompatible 057@ElementTypesAreNonnullByDefault 058public final class ByteStreams { 059 060 private static final int BUFFER_SIZE = 8192; 061 062 /** Creates a new byte array for buffering reads or writes. */ 063 static byte[] createBuffer() { 064 return new byte[BUFFER_SIZE]; 065 } 066 067 /** 068 * There are three methods to implement {@link FileChannel#transferTo(long, long, 069 * WritableByteChannel)}: 070 * 071 * <ol> 072 * <li>Use sendfile(2) or equivalent. Requires that both the input channel and the output 073 * channel have their own file descriptors. Generally this only happens when both channels 074 * are files or sockets. This performs zero copies - the bytes never enter userspace. 075 * <li>Use mmap(2) or equivalent. Requires that either the input channel or the output channel 076 * have file descriptors. Bytes are copied from the file into a kernel buffer, then directly 077 * into the other buffer (userspace). Note that if the file is very large, a naive 078 * implementation will effectively put the whole file in memory. On many systems with paging 079 * and virtual memory, this is not a problem - because it is mapped read-only, the kernel 080 * can always page it to disk "for free". However, on systems where killing processes 081 * happens all the time in normal conditions (i.e., android) the OS must make a tradeoff 082 * between paging memory and killing other processes - so allocating a gigantic buffer and 083 * then sequentially accessing it could result in other processes dying. This is solvable 084 * via madvise(2), but that obviously doesn't exist in java. 085 * <li>Ordinary copy. Kernel copies bytes into a kernel buffer, from a kernel buffer into a 086 * userspace buffer (byte[] or ByteBuffer), then copies them from that buffer into the 087 * destination channel. 088 * </ol> 089 * 090 * This value is intended to be large enough to make the overhead of system calls negligible, 091 * without being so large that it causes problems for systems with atypical memory management if 092 * approaches 2 or 3 are used. 093 */ 094 private static final int ZERO_COPY_CHUNK_SIZE = 512 * 1024; 095 096 private ByteStreams() {} 097 098 /** 099 * Copies all bytes from the input stream to the output stream. Does not close or flush either 100 * stream. 101 * 102 * @param from the input stream to read from 103 * @param to the output stream to write to 104 * @return the number of bytes copied 105 * @throws IOException if an I/O error occurs 106 */ 107 @CanIgnoreReturnValue 108 public static long copy(InputStream from, OutputStream to) throws IOException { 109 checkNotNull(from); 110 checkNotNull(to); 111 byte[] buf = createBuffer(); 112 long total = 0; 113 while (true) { 114 int r = from.read(buf); 115 if (r == -1) { 116 break; 117 } 118 to.write(buf, 0, r); 119 total += r; 120 } 121 return total; 122 } 123 124 /** 125 * Copies all bytes from the readable channel to the writable channel. Does not close or flush 126 * either channel. 127 * 128 * @param from the readable channel to read from 129 * @param to the writable channel to write to 130 * @return the number of bytes copied 131 * @throws IOException if an I/O error occurs 132 */ 133 @CanIgnoreReturnValue 134 public static long copy(ReadableByteChannel from, WritableByteChannel to) throws IOException { 135 checkNotNull(from); 136 checkNotNull(to); 137 if (from instanceof FileChannel) { 138 FileChannel sourceChannel = (FileChannel) from; 139 long oldPosition = sourceChannel.position(); 140 long position = oldPosition; 141 long copied; 142 do { 143 copied = sourceChannel.transferTo(position, ZERO_COPY_CHUNK_SIZE, to); 144 position += copied; 145 sourceChannel.position(position); 146 } while (copied > 0 || position < sourceChannel.size()); 147 return position - oldPosition; 148 } 149 150 ByteBuffer buf = ByteBuffer.wrap(createBuffer()); 151 long total = 0; 152 while (from.read(buf) != -1) { 153 Java8Compatibility.flip(buf); 154 while (buf.hasRemaining()) { 155 total += to.write(buf); 156 } 157 Java8Compatibility.clear(buf); 158 } 159 return total; 160 } 161 162 /** Max array length on JVM. */ 163 private static final int MAX_ARRAY_LEN = Integer.MAX_VALUE - 8; 164 165 /** Large enough to never need to expand, given the geometric progression of buffer sizes. */ 166 private static final int TO_BYTE_ARRAY_DEQUE_SIZE = 20; 167 168 /** 169 * Returns a byte array containing the bytes from the buffers already in {@code bufs} (which have 170 * a total combined length of {@code totalLen} bytes) followed by all bytes remaining in the given 171 * input stream. 172 */ 173 private static byte[] toByteArrayInternal(InputStream in, Queue<byte[]> bufs, int totalLen) 174 throws IOException { 175 // Roughly size to match what has been read already. Some file systems, such as procfs, return 0 176 // as their length. These files are very small, so it's wasteful to allocate an 8KB buffer. 177 int initialBufferSize = min(BUFFER_SIZE, max(128, Integer.highestOneBit(totalLen) * 2)); 178 // Starting with an 8k buffer, double the size of each successive buffer. Smaller buffers 179 // quadruple in size until they reach 8k, to minimize the number of small reads for longer 180 // streams. Buffers are retained in a deque so that there's no copying between buffers while 181 // reading and so all of the bytes in each new allocated buffer are available for reading from 182 // the stream. 183 for (int bufSize = initialBufferSize; 184 totalLen < MAX_ARRAY_LEN; 185 bufSize = IntMath.saturatedMultiply(bufSize, bufSize < 4096 ? 4 : 2)) { 186 byte[] buf = new byte[min(bufSize, MAX_ARRAY_LEN - totalLen)]; 187 bufs.add(buf); 188 int off = 0; 189 while (off < buf.length) { 190 // always OK to fill buf; its size plus the rest of bufs is never more than MAX_ARRAY_LEN 191 int r = in.read(buf, off, buf.length - off); 192 if (r == -1) { 193 return combineBuffers(bufs, totalLen); 194 } 195 off += r; 196 totalLen += r; 197 } 198 } 199 200 // read MAX_ARRAY_LEN bytes without seeing end of stream 201 if (in.read() == -1) { 202 // oh, there's the end of the stream 203 return combineBuffers(bufs, MAX_ARRAY_LEN); 204 } else { 205 throw new OutOfMemoryError("input is too large to fit in a byte array"); 206 } 207 } 208 209 private static byte[] combineBuffers(Queue<byte[]> bufs, int totalLen) { 210 if (bufs.isEmpty()) { 211 return new byte[0]; 212 } 213 byte[] result = bufs.remove(); 214 if (result.length == totalLen) { 215 return result; 216 } 217 int remaining = totalLen - result.length; 218 result = Arrays.copyOf(result, totalLen); 219 while (remaining > 0) { 220 byte[] buf = bufs.remove(); 221 int bytesToCopy = min(remaining, buf.length); 222 int resultOffset = totalLen - remaining; 223 System.arraycopy(buf, 0, result, resultOffset, bytesToCopy); 224 remaining -= bytesToCopy; 225 } 226 return result; 227 } 228 229 /** 230 * Reads all bytes from an input stream into a byte array. Does not close the stream. 231 * 232 * @param in the input stream to read from 233 * @return a byte array containing all the bytes from the stream 234 * @throws IOException if an I/O error occurs 235 */ 236 public static byte[] toByteArray(InputStream in) throws IOException { 237 checkNotNull(in); 238 return toByteArrayInternal(in, new ArrayDeque<byte[]>(TO_BYTE_ARRAY_DEQUE_SIZE), 0); 239 } 240 241 /** 242 * Reads all bytes from an input stream into a byte array. The given expected size is used to 243 * create an initial byte array, but if the actual number of bytes read from the stream differs, 244 * the correct result will be returned anyway. 245 */ 246 static byte[] toByteArray(InputStream in, long expectedSize) throws IOException { 247 checkArgument(expectedSize >= 0, "expectedSize (%s) must be non-negative", expectedSize); 248 if (expectedSize > MAX_ARRAY_LEN) { 249 throw new OutOfMemoryError(expectedSize + " bytes is too large to fit in a byte array"); 250 } 251 252 byte[] bytes = new byte[(int) expectedSize]; 253 int remaining = (int) expectedSize; 254 255 while (remaining > 0) { 256 int off = (int) expectedSize - remaining; 257 int read = in.read(bytes, off, remaining); 258 if (read == -1) { 259 // end of stream before reading expectedSize bytes 260 // just return the bytes read so far 261 return Arrays.copyOf(bytes, off); 262 } 263 remaining -= read; 264 } 265 266 // bytes is now full 267 int b = in.read(); 268 if (b == -1) { 269 return bytes; 270 } 271 272 // the stream was longer, so read the rest normally 273 Queue<byte[]> bufs = new ArrayDeque<>(TO_BYTE_ARRAY_DEQUE_SIZE + 2); 274 bufs.add(bytes); 275 bufs.add(new byte[] {(byte) b}); 276 return toByteArrayInternal(in, bufs, bytes.length + 1); 277 } 278 279 /** 280 * Reads and discards data from the given {@code InputStream} until the end of the stream is 281 * reached. Returns the total number of bytes read. Does not close the stream. 282 * 283 * @since 20.0 284 */ 285 @CanIgnoreReturnValue 286 @Beta 287 public static long exhaust(InputStream in) throws IOException { 288 long total = 0; 289 long read; 290 byte[] buf = createBuffer(); 291 while ((read = in.read(buf)) != -1) { 292 total += read; 293 } 294 return total; 295 } 296 297 /** 298 * Returns a new {@link ByteArrayDataInput} instance to read from the {@code bytes} array from the 299 * beginning. 300 */ 301 @Beta 302 public static ByteArrayDataInput newDataInput(byte[] bytes) { 303 return newDataInput(new ByteArrayInputStream(bytes)); 304 } 305 306 /** 307 * Returns a new {@link ByteArrayDataInput} instance to read from the {@code bytes} array, 308 * starting at the given position. 309 * 310 * @throws IndexOutOfBoundsException if {@code start} is negative or greater than the length of 311 * the array 312 */ 313 @Beta 314 public static ByteArrayDataInput newDataInput(byte[] bytes, int start) { 315 checkPositionIndex(start, bytes.length); 316 return newDataInput(new ByteArrayInputStream(bytes, start, bytes.length - start)); 317 } 318 319 /** 320 * Returns a new {@link ByteArrayDataInput} instance to read from the given {@code 321 * ByteArrayInputStream}. The given input stream is not reset before being read from by the 322 * returned {@code ByteArrayDataInput}. 323 * 324 * @since 17.0 325 */ 326 @Beta 327 public static ByteArrayDataInput newDataInput(ByteArrayInputStream byteArrayInputStream) { 328 return new ByteArrayDataInputStream(checkNotNull(byteArrayInputStream)); 329 } 330 331 private static class ByteArrayDataInputStream implements ByteArrayDataInput { 332 final DataInput input; 333 334 ByteArrayDataInputStream(ByteArrayInputStream byteArrayInputStream) { 335 this.input = new DataInputStream(byteArrayInputStream); 336 } 337 338 @Override 339 public void readFully(byte b[]) { 340 try { 341 input.readFully(b); 342 } catch (IOException e) { 343 throw new IllegalStateException(e); 344 } 345 } 346 347 @Override 348 public void readFully(byte b[], int off, int len) { 349 try { 350 input.readFully(b, off, len); 351 } catch (IOException e) { 352 throw new IllegalStateException(e); 353 } 354 } 355 356 @Override 357 public int skipBytes(int n) { 358 try { 359 return input.skipBytes(n); 360 } catch (IOException e) { 361 throw new IllegalStateException(e); 362 } 363 } 364 365 @Override 366 public boolean readBoolean() { 367 try { 368 return input.readBoolean(); 369 } catch (IOException e) { 370 throw new IllegalStateException(e); 371 } 372 } 373 374 @Override 375 public byte readByte() { 376 try { 377 return input.readByte(); 378 } catch (EOFException e) { 379 throw new IllegalStateException(e); 380 } catch (IOException impossible) { 381 throw new AssertionError(impossible); 382 } 383 } 384 385 @Override 386 public int readUnsignedByte() { 387 try { 388 return input.readUnsignedByte(); 389 } catch (IOException e) { 390 throw new IllegalStateException(e); 391 } 392 } 393 394 @Override 395 public short readShort() { 396 try { 397 return input.readShort(); 398 } catch (IOException e) { 399 throw new IllegalStateException(e); 400 } 401 } 402 403 @Override 404 public int readUnsignedShort() { 405 try { 406 return input.readUnsignedShort(); 407 } catch (IOException e) { 408 throw new IllegalStateException(e); 409 } 410 } 411 412 @Override 413 public char readChar() { 414 try { 415 return input.readChar(); 416 } catch (IOException e) { 417 throw new IllegalStateException(e); 418 } 419 } 420 421 @Override 422 public int readInt() { 423 try { 424 return input.readInt(); 425 } catch (IOException e) { 426 throw new IllegalStateException(e); 427 } 428 } 429 430 @Override 431 public long readLong() { 432 try { 433 return input.readLong(); 434 } catch (IOException e) { 435 throw new IllegalStateException(e); 436 } 437 } 438 439 @Override 440 public float readFloat() { 441 try { 442 return input.readFloat(); 443 } catch (IOException e) { 444 throw new IllegalStateException(e); 445 } 446 } 447 448 @Override 449 public double readDouble() { 450 try { 451 return input.readDouble(); 452 } catch (IOException e) { 453 throw new IllegalStateException(e); 454 } 455 } 456 457 @Override 458 @CheckForNull 459 public String readLine() { 460 try { 461 return input.readLine(); 462 } catch (IOException e) { 463 throw new IllegalStateException(e); 464 } 465 } 466 467 @Override 468 public String readUTF() { 469 try { 470 return input.readUTF(); 471 } catch (IOException e) { 472 throw new IllegalStateException(e); 473 } 474 } 475 } 476 477 /** Returns a new {@link ByteArrayDataOutput} instance with a default size. */ 478 @Beta 479 public static ByteArrayDataOutput newDataOutput() { 480 return newDataOutput(new ByteArrayOutputStream()); 481 } 482 483 /** 484 * Returns a new {@link ByteArrayDataOutput} instance sized to hold {@code size} bytes before 485 * resizing. 486 * 487 * @throws IllegalArgumentException if {@code size} is negative 488 */ 489 @Beta 490 public static ByteArrayDataOutput newDataOutput(int size) { 491 // When called at high frequency, boxing size generates too much garbage, 492 // so avoid doing that if we can. 493 if (size < 0) { 494 throw new IllegalArgumentException(String.format("Invalid size: %s", size)); 495 } 496 return newDataOutput(new ByteArrayOutputStream(size)); 497 } 498 499 /** 500 * Returns a new {@link ByteArrayDataOutput} instance which writes to the given {@code 501 * ByteArrayOutputStream}. The given output stream is not reset before being written to by the 502 * returned {@code ByteArrayDataOutput} and new data will be appended to any existing content. 503 * 504 * <p>Note that if the given output stream was not empty or is modified after the {@code 505 * ByteArrayDataOutput} is created, the contract for {@link ByteArrayDataOutput#toByteArray} will 506 * not be honored (the bytes returned in the byte array may not be exactly what was written via 507 * calls to {@code ByteArrayDataOutput}). 508 * 509 * @since 17.0 510 */ 511 @Beta 512 public static ByteArrayDataOutput newDataOutput(ByteArrayOutputStream byteArrayOutputStream) { 513 return new ByteArrayDataOutputStream(checkNotNull(byteArrayOutputStream)); 514 } 515 516 private static class ByteArrayDataOutputStream implements ByteArrayDataOutput { 517 518 final DataOutput output; 519 final ByteArrayOutputStream byteArrayOutputStream; 520 521 ByteArrayDataOutputStream(ByteArrayOutputStream byteArrayOutputStream) { 522 this.byteArrayOutputStream = byteArrayOutputStream; 523 output = new DataOutputStream(byteArrayOutputStream); 524 } 525 526 @Override 527 public void write(int b) { 528 try { 529 output.write(b); 530 } catch (IOException impossible) { 531 throw new AssertionError(impossible); 532 } 533 } 534 535 @Override 536 public void write(byte[] b) { 537 try { 538 output.write(b); 539 } catch (IOException impossible) { 540 throw new AssertionError(impossible); 541 } 542 } 543 544 @Override 545 public void write(byte[] b, int off, int len) { 546 try { 547 output.write(b, off, len); 548 } catch (IOException impossible) { 549 throw new AssertionError(impossible); 550 } 551 } 552 553 @Override 554 public void writeBoolean(boolean v) { 555 try { 556 output.writeBoolean(v); 557 } catch (IOException impossible) { 558 throw new AssertionError(impossible); 559 } 560 } 561 562 @Override 563 public void writeByte(int v) { 564 try { 565 output.writeByte(v); 566 } catch (IOException impossible) { 567 throw new AssertionError(impossible); 568 } 569 } 570 571 @Override 572 public void writeBytes(String s) { 573 try { 574 output.writeBytes(s); 575 } catch (IOException impossible) { 576 throw new AssertionError(impossible); 577 } 578 } 579 580 @Override 581 public void writeChar(int v) { 582 try { 583 output.writeChar(v); 584 } catch (IOException impossible) { 585 throw new AssertionError(impossible); 586 } 587 } 588 589 @Override 590 public void writeChars(String s) { 591 try { 592 output.writeChars(s); 593 } catch (IOException impossible) { 594 throw new AssertionError(impossible); 595 } 596 } 597 598 @Override 599 public void writeDouble(double v) { 600 try { 601 output.writeDouble(v); 602 } catch (IOException impossible) { 603 throw new AssertionError(impossible); 604 } 605 } 606 607 @Override 608 public void writeFloat(float v) { 609 try { 610 output.writeFloat(v); 611 } catch (IOException impossible) { 612 throw new AssertionError(impossible); 613 } 614 } 615 616 @Override 617 public void writeInt(int v) { 618 try { 619 output.writeInt(v); 620 } catch (IOException impossible) { 621 throw new AssertionError(impossible); 622 } 623 } 624 625 @Override 626 public void writeLong(long v) { 627 try { 628 output.writeLong(v); 629 } catch (IOException impossible) { 630 throw new AssertionError(impossible); 631 } 632 } 633 634 @Override 635 public void writeShort(int v) { 636 try { 637 output.writeShort(v); 638 } catch (IOException impossible) { 639 throw new AssertionError(impossible); 640 } 641 } 642 643 @Override 644 public void writeUTF(String s) { 645 try { 646 output.writeUTF(s); 647 } catch (IOException impossible) { 648 throw new AssertionError(impossible); 649 } 650 } 651 652 @Override 653 public byte[] toByteArray() { 654 return byteArrayOutputStream.toByteArray(); 655 } 656 } 657 658 private static final OutputStream NULL_OUTPUT_STREAM = 659 new OutputStream() { 660 /** Discards the specified byte. */ 661 @Override 662 public void write(int b) {} 663 664 /** Discards the specified byte array. */ 665 @Override 666 public void write(byte[] b) { 667 checkNotNull(b); 668 } 669 670 /** Discards the specified byte array. */ 671 @Override 672 public void write(byte[] b, int off, int len) { 673 checkNotNull(b); 674 checkPositionIndexes(off, off + len, b.length); 675 } 676 677 @Override 678 public String toString() { 679 return "ByteStreams.nullOutputStream()"; 680 } 681 }; 682 683 /** 684 * Returns an {@link OutputStream} that simply discards written bytes. 685 * 686 * @since 14.0 (since 1.0 as com.google.common.io.NullOutputStream) 687 */ 688 @Beta 689 public static OutputStream nullOutputStream() { 690 return NULL_OUTPUT_STREAM; 691 } 692 693 /** 694 * Wraps a {@link InputStream}, limiting the number of bytes which can be read. 695 * 696 * @param in the input stream to be wrapped 697 * @param limit the maximum number of bytes to be read 698 * @return a length-limited {@link InputStream} 699 * @since 14.0 (since 1.0 as com.google.common.io.LimitInputStream) 700 */ 701 @Beta 702 public static InputStream limit(InputStream in, long limit) { 703 return new LimitedInputStream(in, limit); 704 } 705 706 private static final class LimitedInputStream extends FilterInputStream { 707 708 private long left; 709 private long mark = -1; 710 711 LimitedInputStream(InputStream in, long limit) { 712 super(in); 713 checkNotNull(in); 714 checkArgument(limit >= 0, "limit must be non-negative"); 715 left = limit; 716 } 717 718 @Override 719 public int available() throws IOException { 720 return (int) Math.min(in.available(), left); 721 } 722 723 // it's okay to mark even if mark isn't supported, as reset won't work 724 @Override 725 public synchronized void mark(int readLimit) { 726 in.mark(readLimit); 727 mark = left; 728 } 729 730 @Override 731 public int read() throws IOException { 732 if (left == 0) { 733 return -1; 734 } 735 736 int result = in.read(); 737 if (result != -1) { 738 --left; 739 } 740 return result; 741 } 742 743 @Override 744 public int read(byte[] b, int off, int len) throws IOException { 745 if (left == 0) { 746 return -1; 747 } 748 749 len = (int) Math.min(len, left); 750 int result = in.read(b, off, len); 751 if (result != -1) { 752 left -= result; 753 } 754 return result; 755 } 756 757 @Override 758 public synchronized void reset() throws IOException { 759 if (!in.markSupported()) { 760 throw new IOException("Mark not supported"); 761 } 762 if (mark == -1) { 763 throw new IOException("Mark not set"); 764 } 765 766 in.reset(); 767 left = mark; 768 } 769 770 @Override 771 public long skip(long n) throws IOException { 772 n = Math.min(n, left); 773 long skipped = in.skip(n); 774 left -= skipped; 775 return skipped; 776 } 777 } 778 779 /** 780 * Attempts to read enough bytes from the stream to fill the given byte array, with the same 781 * behavior as {@link DataInput#readFully(byte[])}. Does not close the stream. 782 * 783 * @param in the input stream to read from. 784 * @param b the buffer into which the data is read. 785 * @throws EOFException if this stream reaches the end before reading all the bytes. 786 * @throws IOException if an I/O error occurs. 787 */ 788 @Beta 789 public static void readFully(InputStream in, byte[] b) throws IOException { 790 readFully(in, b, 0, b.length); 791 } 792 793 /** 794 * Attempts to read {@code len} bytes from the stream into the given array starting at {@code 795 * off}, with the same behavior as {@link DataInput#readFully(byte[], int, int)}. Does not close 796 * the stream. 797 * 798 * @param in the input stream to read from. 799 * @param b the buffer into which the data is read. 800 * @param off an int specifying the offset into the data. 801 * @param len an int specifying the number of bytes to read. 802 * @throws EOFException if this stream reaches the end before reading all the bytes. 803 * @throws IOException if an I/O error occurs. 804 */ 805 @Beta 806 public static void readFully(InputStream in, byte[] b, int off, int len) throws IOException { 807 int read = read(in, b, off, len); 808 if (read != len) { 809 throw new EOFException( 810 "reached end of stream after reading " + read + " bytes; " + len + " bytes expected"); 811 } 812 } 813 814 /** 815 * Discards {@code n} bytes of data from the input stream. This method will block until the full 816 * amount has been skipped. Does not close the stream. 817 * 818 * @param in the input stream to read from 819 * @param n the number of bytes to skip 820 * @throws EOFException if this stream reaches the end before skipping all the bytes 821 * @throws IOException if an I/O error occurs, or the stream does not support skipping 822 */ 823 @Beta 824 public static void skipFully(InputStream in, long n) throws IOException { 825 long skipped = skipUpTo(in, n); 826 if (skipped < n) { 827 throw new EOFException( 828 "reached end of stream after skipping " + skipped + " bytes; " + n + " bytes expected"); 829 } 830 } 831 832 /** 833 * Discards up to {@code n} bytes of data from the input stream. This method will block until 834 * either the full amount has been skipped or until the end of the stream is reached, whichever 835 * happens first. Returns the total number of bytes skipped. 836 */ 837 static long skipUpTo(InputStream in, long n) throws IOException { 838 long totalSkipped = 0; 839 // A buffer is allocated if skipSafely does not skip any bytes. 840 byte[] buf = null; 841 842 while (totalSkipped < n) { 843 long remaining = n - totalSkipped; 844 long skipped = skipSafely(in, remaining); 845 846 if (skipped == 0) { 847 // Do a buffered read since skipSafely could return 0 repeatedly, for example if 848 // in.available() always returns 0 (the default). 849 int skip = (int) Math.min(remaining, BUFFER_SIZE); 850 if (buf == null) { 851 // Allocate a buffer bounded by the maximum size that can be requested, for 852 // example an array of BUFFER_SIZE is unnecessary when the value of remaining 853 // is smaller. 854 buf = new byte[skip]; 855 } 856 if ((skipped = in.read(buf, 0, skip)) == -1) { 857 // Reached EOF 858 break; 859 } 860 } 861 862 totalSkipped += skipped; 863 } 864 865 return totalSkipped; 866 } 867 868 /** 869 * Attempts to skip up to {@code n} bytes from the given input stream, but not more than {@code 870 * in.available()} bytes. This prevents {@code FileInputStream} from skipping more bytes than 871 * actually remain in the file, something that it {@linkplain java.io.FileInputStream#skip(long) 872 * specifies} it can do in its Javadoc despite the fact that it is violating the contract of 873 * {@code InputStream.skip()}. 874 */ 875 private static long skipSafely(InputStream in, long n) throws IOException { 876 int available = in.available(); 877 return available == 0 ? 0 : in.skip(Math.min(available, n)); 878 } 879 880 /** 881 * Process the bytes of the given input stream using the given processor. 882 * 883 * @param input the input stream to process 884 * @param processor the object to which to pass the bytes of the stream 885 * @return the result of the byte processor 886 * @throws IOException if an I/O error occurs 887 * @since 14.0 888 */ 889 @Beta 890 @CanIgnoreReturnValue // some processors won't return a useful result 891 @ParametricNullness 892 public static <T extends @Nullable Object> T readBytes( 893 InputStream input, ByteProcessor<T> processor) throws IOException { 894 checkNotNull(input); 895 checkNotNull(processor); 896 897 byte[] buf = createBuffer(); 898 int read; 899 do { 900 read = input.read(buf); 901 } while (read != -1 && processor.processBytes(buf, 0, read)); 902 return processor.getResult(); 903 } 904 905 /** 906 * Reads some bytes from an input stream and stores them into the buffer array {@code b}. This 907 * method blocks until {@code len} bytes of input data have been read into the array, or end of 908 * file is detected. The number of bytes read is returned, possibly zero. Does not close the 909 * stream. 910 * 911 * <p>A caller can detect EOF if the number of bytes read is less than {@code len}. All subsequent 912 * calls on the same stream will return zero. 913 * 914 * <p>If {@code b} is null, a {@code NullPointerException} is thrown. If {@code off} is negative, 915 * or {@code len} is negative, or {@code off+len} is greater than the length of the array {@code 916 * b}, then an {@code IndexOutOfBoundsException} is thrown. If {@code len} is zero, then no bytes 917 * are read. Otherwise, the first byte read is stored into element {@code b[off]}, the next one 918 * into {@code b[off+1]}, and so on. The number of bytes read is, at most, equal to {@code len}. 919 * 920 * @param in the input stream to read from 921 * @param b the buffer into which the data is read 922 * @param off an int specifying the offset into the data 923 * @param len an int specifying the number of bytes to read 924 * @return the number of bytes read 925 * @throws IOException if an I/O error occurs 926 * @throws IndexOutOfBoundsException if {@code off} is negative, if {@code len} is negative, or if 927 * {@code off + len} is greater than {@code b.length} 928 */ 929 @Beta 930 @CanIgnoreReturnValue 931 // Sometimes you don't care how many bytes you actually read, I guess. 932 // (You know that it's either going to read len bytes or stop at EOF.) 933 public static int read(InputStream in, byte[] b, int off, int len) throws IOException { 934 checkNotNull(in); 935 checkNotNull(b); 936 if (len < 0) { 937 throw new IndexOutOfBoundsException(String.format("len (%s) cannot be negative", len)); 938 } 939 checkPositionIndexes(off, off + len, b.length); 940 int total = 0; 941 while (total < len) { 942 int result = in.read(b, off + total, len - total); 943 if (result == -1) { 944 break; 945 } 946 total += result; 947 } 948 return total; 949 } 950}