< prev index next >
src/java.base/share/classes/java/lang/Readable.java
Print this page
@@ -1,7 +1,7 @@
/*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
@@ -24,10 +24,12 @@
*/
package java.lang;
import java.io.IOException;
+import java.nio.CharBuffer;
+import java.util.Objects;
/**
* A {@code Readable} is a source of characters. Characters from
* a {@code Readable} are made available to callers of the read
* method via a {@link java.nio.CharBuffer CharBuffer}.
@@ -48,6 +50,71 @@
* @throws IOException if an I/O error occurs
* @throws NullPointerException if cb is null
* @throws java.nio.ReadOnlyBufferException if cb is a read only buffer
*/
public int read(java.nio.CharBuffer cb) throws IOException;
+
+ /**
+ * 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.
+ * <p>
+ * 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
+ * <i>asynchronously closed</i>, or the thread is interrupted during the
+ * transfer, is highly implementation-dependent and therefore unspecified.
+ * <p>
+ * 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.
+ * <p>
+ * If the destination is capacity bounded and has insufficient capacity to
+ * append all characters read from the source then the exception may be
+ * thrown after transferring some characters to the 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 default implementation behaves as if:
+ * <pre>{@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;
+ * }</pre>
+ *
+ * @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 to avoid the extra overhead of
+ * 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
+ */
+ public default long transferTo(Appendable out) throws IOException {
+ Objects.requireNonNull(out, "out");
+ 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;
+ }
}
< prev index next >