1 /* 2 * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang; 27 28 import java.io.IOException; 29 import java.nio.CharBuffer; 30 import java.util.Objects; 31 32 /** 33 * A {@code Readable} is a source of characters. Characters from 34 * a {@code Readable} are made available to callers of the read 35 * method via a {@link java.nio.CharBuffer CharBuffer}. 36 * 37 * @since 1.5 38 */ 39 public interface Readable { 40 41 /** 42 * Attempts to read characters into the specified character buffer. 43 * The buffer is used as a repository of characters as-is: the only 44 * changes made are the results of a put operation. No flipping or 45 * rewinding of the buffer is performed. 46 * 47 * @param cb the buffer to read characters into 48 * @return The number of {@code char} values added to the buffer, 49 * or -1 if this source of characters is at its end 50 * @throws IOException if an I/O error occurs 51 * @throws NullPointerException if cb is null 52 * @throws java.nio.ReadOnlyBufferException if cb is a read only buffer 53 */ 54 public int read(java.nio.CharBuffer cb) throws IOException; 55 56 /** 57 * Reads all characters from this source and appends them to a destination 58 * in the order in which they are read. On return, the source of characters 59 * will be at its end. 60 * <p> 61 * This method may block indefinitely while reading from the source or 62 * writing to the destination. If the source or destination is 63 * {@link AutoCloseable closeable}, then the behavior when either is 64 * <i>asynchronously closed</i>, or the thread is interrupted during the 65 * transfer, is highly implementation-dependent and therefore unspecified. 66 * <p> 67 * If an I/O error occurs during the operation, then not all characters 68 * might have been transferred and the source or destination could be 69 * left in an inconsistent state. The caller of this method should therefore 70 * ensure in such a case that measures are taken to release any resources 71 * held by the source and destination. 72 * <p> 73 * If the destination is capacity bounded and has insufficient capacity to 74 * append all characters read from the source then the exception may be 75 * thrown after transferring some characters to the destination. 76 * 77 * @implSpec 78 * The default implementation invokes the read method to read all characters 79 * from this source and invokes the {@link Appendable#append(CharSequence, int, int)} 80 * method to write all characters to the appendable. 81 * 82 * The default implementation behaves as if: 83 * <pre>{@code 84 * long transferred = 0; 85 * CharBuffer buffer = CharBuffer.allocate(8192); 86 * int read; 87 * while ((read = this.read(buffer)) >= 0) { 88 * buffer.rewind(); 89 * out.append(buffer, 0, read); 90 * transferred += read; 91 * } 92 * return transferred; 93 * }</pre> 94 * 95 * @implNote 96 * The default implementation should usually be overridden in cases where 97 * the implementer is already a {@link CharSequence} or its data is already 98 * available in the internal representation to avoid the extra overhead of 99 * a buffer in order to transfer its data to the destination. 100 * 101 * @param out the appendable, non-null 102 * @return the number of characters transferred 103 * @throws IOException if an I/O error occurs when reading or writing 104 * @throws NullPointerException if {@code out} is {@code null} 105 * 106 * @since 10 107 */ 108 public default long transferTo(Appendable out) throws IOException { 109 Objects.requireNonNull(out, "out"); 110 long transferred = 0; 111 CharBuffer buffer = CharBuffer.allocate(8192); 112 int read; 113 while ((read = this.read(buffer)) >= 0) { 114 buffer.rewind(); 115 out.append(buffer, 0, read); 116 transferred += read; 117 } 118 return transferred; 119 } 120 }