java.lang.Readable ------------------ /** * Reads all characters from this source and appends them to a destination * in the order in which they are read. On return, the source of characters * will be at its end. *
* This method may block indefinitely while reading from the source or * writing to the destination. If the source or destination is * {@link AutoCloseable closeable}, then the behavior when either is * asynchronously closed, or the thread is interrupted during the * transfer, is highly implementation-dependent and hence unspecified. *
* If an I/O error occurs during the operation, then not all characters * might have been transferred and the source or destination could be * left in an inconsistent state. The caller of this method should therefore * ensure in such a case that measures are taken to release any resources * held by the source and destination. * * @implSpec * The default implementation invokes the read method to read all characters * from this source and invokes the {@link Appendable#append(CharSequence, int, int)} * method to write all characters to the appendable. * The total amount will be added up by after the write method has been * completed. * * The default implementation behaves as if: *
{@code * long transferred = 0; * CharBuffer buffer = CharBuffer.allocate(8192); * int read; * while ((read = this.read(buffer)) >= 0) { * buffer.rewind(); * out.append(buffer, 0, read); * transferred += read; * } * return transferred; * }* * @implNote * The default implementation should usually be overridden in cases where * the implementer is already a {@link CharSequence} or its data is already * available in the internal representation in order not having the extra * overhead creating a buffer in order to transfer its data to the * destination. * * @param out the appendable, non-null * @return the number of characters transferred * @throws IOException if an I/O error occurs when reading or writing * @throws NullPointerException if {@code out} is {@code null} * * @since 10 */ default long transferTo(Appendable out) throws IOException { .... } java.nio.CharBuffer ------------------- /** * {@inheritDoc} * * @implSpec * The implementation is using two strategies of transferring data form the * actual source to the given destination. If the given {@link Appendable} * is a {@link CharBuffer} the transfer uses the {@code put(CharBuffer)} * method to transfer it's data if possible. For the other cases source * is passed into the {@link Appendable#append(CharSequence, int, int)} * method along with the current position and data length. * * @param out the appendable, non-null * @return the number of characters transferred * @throws IOException if an I/O error occurs when reading or writing * @throws NullPointerException if {@code out} is {@code null} * @throws BufferOverflowException if there is insufficient space in this * buffer for the remaining chars in the source buffer * @throws IllegalArgumentException if out is this buffer * @throws ReadOnlyBufferException if out is a read-only buffer * * @since 10 */ @Override public long transferTo(Appendable out) throws IOException { int start = position(); int length = remaining(); if (out instanceof CharBuffer) { ((CharBuffer)out).put(this); } else { out.append(this, start, length); } return length; }