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