Javadoc
diff --git a/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java b/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
index 4262c69..7b11323 100644
--- a/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
+++ b/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
@@ -141,13 +141,14 @@
}
/**
- * Gets an input stream from the origin with open options.
+ * Gets an InputStream from the origin with OpenOption[].
*
* @return An input stream
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to an {@link InputStream}.
* @throws IOException if an I/O error occurs.
* @see AbstractOrigin#getInputStream(OpenOption...)
+ * @see #getOpenOptions()
* @since 2.13.0
*/
protected InputStream getInputStream() throws IOException {
@@ -155,22 +156,23 @@
}
/**
- * Gets the OpenOption.
+ * Gets the OpenOption array.
*
- * @return the OpenOption.
+ * @return the OpenOption array.
*/
protected OpenOption[] getOpenOptions() {
return openOptions;
}
/**
- * Gets an OutputStream from the origin with open options.
+ * Gets an OutputStream from the origin with OpenOption[].
*
* @return An OutputStream
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
* @throws IOException if an I/O error occurs.
* @see AbstractOrigin#getOutputStream(OpenOption...)
+ * @see #getOpenOptions()
* @since 2.13.0
*/
protected OutputStream getOutputStream() throws IOException {
@@ -191,13 +193,14 @@
}
/**
- * Gets an writer from the origin with open options.
+ * Gets a Writer from the origin with OpenOption[].
*
* @return An writer.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws UnsupportedOperationException if the origin cannot be converted to a {@link Writer}.
* @throws IOException if an I/O error occurs.
* @see AbstractOrigin#getOutputStream(OpenOption...)
+ * @see #getOpenOptions()
* @since 2.13.0
*/
protected Writer getWriter() throws IOException {
diff --git a/src/main/java/org/apache/commons/io/filefilter/WildcardFileFilter.java b/src/main/java/org/apache/commons/io/filefilter/WildcardFileFilter.java
index 639feff..f5bad2e 100644
--- a/src/main/java/org/apache/commons/io/filefilter/WildcardFileFilter.java
+++ b/src/main/java/org/apache/commons/io/filefilter/WildcardFileFilter.java
@@ -40,7 +40,7 @@
* command lines. The check is case-sensitive by default. See {@link FilenameUtils#wildcardMatchOnSystem(String,String)} for more information.
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* For example:
diff --git a/src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java b/src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java
index 816bbf3..d7c705f 100644
--- a/src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java
@@ -24,52 +24,57 @@
import org.apache.commons.io.build.AbstractStreamBuilder;
/**
- * Proxy stream that closes and discards the underlying stream as soon as the
- * end of input has been reached or when the stream is explicitly closed.
- * Not even a reference to the underlying stream is kept after it has been
- * closed, so any allocated in-memory buffers can be freed even if the
- * client application still keeps a reference to the proxy stream.
+ * Proxy stream that closes and discards the underlying stream as soon as the end of input has been reached or when the stream is explicitly closed. Not even a
+ * reference to the underlying stream is kept after it has been closed, so any allocated in-memory buffers can be freed even if the client application still
+ * keeps a reference to the proxy stream.
* <p>
- * This class is typically used to release any resources related to an open
- * stream as soon as possible even if the client application (by not explicitly
- * closing the stream when no longer needed) or the underlying stream (by not
- * releasing resources once the last byte has been read) do not do that.
+ * This class is typically used to release any resources related to an open stream as soon as possible even if the client application (by not explicitly closing
+ * the stream when no longer needed) or the underlying stream (by not releasing resources once the last byte has been read) do not do that.
+ * </p>
+ * <p>
+ * To build an instance, use {@link Builder}.
* </p>
*
* @since 1.4
+ * @see Builder
*/
public class AutoCloseInputStream extends ProxyInputStream {
+ // @formatter:off
/**
* Builds a new {@link AutoCloseInputStream} instance.
+ *
* <p>
* For example:
* </p>
- *
* <pre>{@code
* AutoCloseInputStream s = AutoCloseInputStream.builder()
* .setPath(path)
* .get();}
* </pre>
- *
* <pre>{@code
* AutoCloseInputStream s = AutoCloseInputStream.builder()
* .setInputStream(inputStream)
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.13.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<AutoCloseInputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link AutoCloseInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
* <p>
- * This builder use the aspects InputStream, OpenOption[], include, and ByteOrderMark[].
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
@@ -121,15 +126,14 @@
}
/**
- * Closes the underlying input stream and replaces the reference to it
- * with a {@link ClosedInputStream} instance.
+ * Closes the underlying input stream and replaces the reference to it with a {@link ClosedInputStream} instance.
* <p>
- * This method is automatically called by the read methods when the end
- * of input has been reached.
+ * This method is automatically called by the read methods when the end of input has been reached.
+ * </p>
* <p>
- * Note that it is safe to call this method any number of times. The original
- * underlying input stream is closed and discarded only once when this
- * method is first called.
+ * Note that it is safe to call this method any number of times. The original underlying input stream is closed and discarded only once when this method is
+ * first called.
+ * </p>
*
* @throws IOException if the underlying input stream can not be closed
*/
@@ -140,9 +144,9 @@
}
/**
- * Ensures that the stream is closed before it gets garbage-collected.
- * As mentioned in {@link #close()}, this is a no-op if the stream has
- * already been closed.
+ * Ensures that the stream is closed before it gets garbage-collected. As mentioned in {@link #close()}, this is a no-op if the stream has already been
+ * closed.
+ *
* @throws Throwable if an error occurs
*/
@Override
diff --git a/src/main/java/org/apache/commons/io/input/BOMInputStream.java b/src/main/java/org/apache/commons/io/input/BOMInputStream.java
index ad723f7..130c7a4 100644
--- a/src/main/java/org/apache/commons/io/input/BOMInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BOMInputStream.java
@@ -46,7 +46,7 @@
* <li>UTF-32LE - {@link ByteOrderMark#UTF_32BE}</li>
* </ul>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <h2>Example 1 - Detecting and excluding a UTF-8 BOM</h2>
*
@@ -89,15 +89,20 @@
* // has a UTF-32BE BOM
* }
* </pre>
+ * <p>
+ * To build an instance, use {@link Builder}.
+ * </p>
*
+ * @see Builder
* @see org.apache.commons.io.ByteOrderMark
* @see <a href="https://en.wikipedia.org/wiki/Byte_order_mark">Wikipedia - Byte Order Mark</a>
* @since 2.0
*/
public class BOMInputStream extends ProxyInputStream {
+ // @formatter:off
/**
- * Builds a new {@link BOMInputStream} instance.
+ * Builds a new {@link BOMInputStream}.
*
* <h2>Using NIO</h2>
* <pre>{@code
@@ -116,8 +121,10 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<BOMInputStream, Builder> {
private static final ByteOrderMark[] DEFAULT = { ByteOrderMark.UTF_8 };
@@ -136,13 +143,21 @@
private boolean include;
/**
- * Constructs a new instance.
+ * Builds a new {@link BOMInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
* <p>
- * This builder use the aspects InputStream, OpenOption[], include, and ByteOrderMark[].
+ * This builder use the following aspects: InputStream, OpenOption[], include, and ByteOrderMark[].
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>include}</li>
+ * <li>byteOrderMarks</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/BoundedInputStream.java b/src/main/java/org/apache/commons/io/input/BoundedInputStream.java
index f6f4373..7175dac 100644
--- a/src/main/java/org/apache/commons/io/input/BoundedInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BoundedInputStream.java
@@ -31,32 +31,44 @@
* doesn't know whether the content hasn't arrived yet or whether the content has finished. So, one of these, initialized with the {@code Content-Length} sent
* in the {@code ServletInputStream}'s header, will stop it blocking, providing it's been sent with a correct content length.
* </p>
+ * <p>
+ * To build an instance, use {@link Builder}.
+ * </p>
*
+ * @see Builder
* @since 2.0
*/
public class BoundedInputStream extends ProxyInputStream {
// TODO For 3.0, extend CountingInputStream. Or, add a max feature to CountingInputStream.
+ //@formatter:off
/**
- * Builds a new {@link BoundedInputStream} instance.
+ * Builds a new {@link BoundedInputStream}.
*
* <h2>Using NIO</h2>
- *
* <pre>{@code
- * BoundedInputStream s = BoundedInputStream.builder().setPath(Paths.get("MyFile.xml")).setMaxCount(1024).setPropagateClose(false).get();
+ * BoundedInputStream s = BoundedInputStream.builder()
+ * .setPath(Paths.get("MyFile.xml"))
+ * .setMaxCount(1024)
+ * .setPropagateClose(false)
+ * .get();
* }
* </pre>
- *
* <h2>Using IO</h2>
- *
* <pre>{@code
- * BoundedInputStream s = BoundedInputStream.builder().setFile(new File("MyFile.xml")).setMaxCount(1024).setPropagateClose(false).get();
+ * BoundedInputStream s = BoundedInputStream.builder()
+ * .setFile(new File("MyFile.xml"))
+ * .setMaxCount(1024)
+ * .setPropagateClose(false)
+ * .get();
* }
* </pre>
*
+ * @see #get()
* @since 2.16.0
*/
+ //@formatter:on
public static class Builder extends AbstractStreamBuilder<BoundedInputStream, Builder> {
/** The max count of bytes to read. */
@@ -66,10 +78,18 @@
private boolean propagateClose = true;
/**
- * Constructs a new instance.
+ * Builds a new {@link BoundedInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>maxCount</li>
+ * <li>propagateClose</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java b/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
index 045ab06..870c1e4 100644
--- a/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
@@ -32,22 +32,24 @@
* using {@link java.io.BufferedInputStream}. Unfortunately, this is not something already available in JDK, {@code sun.nio.ch.ChannelInputStream} supports
* reading a file using NIO, but does not support buffering.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* This class was ported and adapted from Apache Spark commit 933dc6cb7b3de1d8ccaf73d124d6eb95b947ed19 where it was called {@code NioBufferedFileInputStream}.
* </p>
*
+ * @see Builder
* @since 2.9.0
*/
public final class BufferedFileChannelInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link BufferedFileChannelInputStream} instance.
+ * Builds a new {@link BufferedFileChannelInputStream}.
+ *
* <p>
* Using File IO:
* </p>
- *
* <pre>{@code
* BufferedFileChannelInputStream s = BufferedFileChannelInputStream.builder()
* .setFile(file)
@@ -57,7 +59,6 @@
* <p>
* Using NIO Path:
* </p>
- *
* <pre>{@code
* BufferedFileChannelInputStream s = BufferedFileChannelInputStream.builder()
* .setPath(path)
@@ -65,16 +66,24 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<BufferedFileChannelInputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link BufferedFileChannelInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getPath()} and {@link #getBufferSize()} on this builder, otherwise, this method throws an
- * exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/CharSequenceInputStream.java b/src/main/java/org/apache/commons/io/input/CharSequenceInputStream.java
index aa472c2..2f25d14 100644
--- a/src/main/java/org/apache/commons/io/input/CharSequenceInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/CharSequenceInputStream.java
@@ -42,13 +42,19 @@
* <p>
* <strong>Note:</strong> Supports {@link #mark(int)} and {@link #reset()}.
* </p>
+ * <p>
+ * To build an instance, use {@link Builder}.
+ * </p>
*
+ * @see Builder
* @since 2.2
*/
public class CharSequenceInputStream extends InputStream {
+ //@formatter:off
/**
- * Builds a new {@link CharSequenceInputStream} instance.
+ * Builds a new {@link CharSequenceInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -71,17 +77,27 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.13.0
*/
+ //@formatter:on
public static class Builder extends AbstractStreamBuilder<CharSequenceInputStream, Builder> {
private CharsetEncoder charsetEncoder = newEncoder(getCharset());
/**
- * Constructs a new instance.
+ * Builds a new {@link CharSequenceInputStream}.
* <p>
- * This builder use the aspects the CharSequence, buffer size, and Charset.
+ * You must set input that supports {@link #getCharSequence()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getCharSequence()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>{@link CharsetEncoder}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalArgumentException if the buffer is not large enough to hold a complete character.
diff --git a/src/main/java/org/apache/commons/io/input/ChecksumInputStream.java b/src/main/java/org/apache/commons/io/input/ChecksumInputStream.java
index b3a052e..edbe2c3 100644
--- a/src/main/java/org/apache/commons/io/input/ChecksumInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ChecksumInputStream.java
@@ -34,19 +34,23 @@
* <p>
* If you do not need the verification or threshold feature, then use a plain {@link CheckedInputStream}.
* </p>
+ * <p>
+ * To build an instance, use {@link Builder}.
+ * </p>
*
+ * @see Builder
* @since 2.16.0
*/
public final class ChecksumInputStream extends CountingInputStream {
// @formatter:off
/**
- * Builds a new {@link ChecksumInputStream} instance.
+ * Builds a new {@link ChecksumInputStream}.
+ *
* <p>
* There is no default {@link Checksum}; you MUST provide one.
* </p>
* <h2>Using NIO</h2>
- *
* <pre>{@code
* ChecksumInputStream s = ChecksumInputStream.builder()
* .setPath(Paths.get("MyFile.xml"))
@@ -54,9 +58,7 @@
* .setExpectedChecksumValue(12345)
* .get();
* }</pre>
- *
* <h2>Using IO</h2>
- *
* <pre>{@code
* ChecksumInputStream s = ChecksumInputStream.builder()
* .setFile(new File("MyFile.xml"))
@@ -64,7 +66,6 @@
* .setExpectedChecksumValue(12345)
* .get();
* }</pre>
- *
* <h2>Validating only part of an InputStream</h2>
* <p>
* The following validates the first 100 bytes of the given input.
@@ -91,6 +92,8 @@
* .setCountThreshold(100)
* .get();
* }</pre>
+ *
+ * @see #get()
*/
// @formatter:on
public static class Builder extends AbstractStreamBuilder<ChecksumInputStream, Builder> {
@@ -116,10 +119,19 @@
private long expectedChecksumValue;
/**
- * Constructs a new instance.
+ * Builds a new {@link ChecksumInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link Checksum}</li>
+ * <li>expectedChecksumValue</li>
+ * <li>countThreshold</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
index c60af53..04c385f 100644
--- a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
@@ -43,7 +43,7 @@
* use case, the use of buffering may still further improve performance. For example:
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <pre>{@code
* BufferedInputStream s = new BufferedInputStream(new GzipInputStream(
@@ -66,12 +66,15 @@
* .get());}
* </pre>
*
+ * @see Builder
* @since 2.12.0
*/
public final class MemoryMappedFileInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link MemoryMappedFileInputStream} instance.
+ * Builds a new {@link MemoryMappedFileInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -82,12 +85,14 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<MemoryMappedFileInputStream, Builder> {
/**
- * Constructs a new Builder.
+ * Constructs a new {@link Builder}.
*/
public Builder() {
setBufferSizeDefault(DEFAULT_BUFFER_SIZE);
@@ -95,11 +100,17 @@
}
/**
- * Constructs a new instance.
+ * Builds a new {@link MemoryMappedFileInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getPath()} and {@link #getBufferSize()} this builder, otherwise, this method throws an
- * exception.
+ * You must set input that supports {@link #getPath()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getPath()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
index c3ffc1b..d4a01b2 100644
--- a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
@@ -29,7 +29,7 @@
* This class is an example for using an {@link ObservableInputStream}. It creates its own {@link org.apache.commons.io.input.ObservableInputStream.Observer},
* which calculates a checksum using a {@link MessageDigest}, for example, a SHA-512 sum.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* See the MessageDigest section in the <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java
@@ -38,13 +38,17 @@
* <p>
* <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe, so is {@link MessageDigestCalculatingInputStream}.
* </p>
+ *
+ * @see Builder
* @deprecated Use {@link MessageDigestInputStream}.
*/
@Deprecated
public class MessageDigestCalculatingInputStream extends ObservableInputStream {
+ // @formatter:off
/**
- * Builds a new {@link MessageDigestCalculatingInputStream} instance.
+ * Builds a new {@link MessageDigestCalculatingInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -55,14 +59,16 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<MessageDigestCalculatingInputStream, Builder> {
private MessageDigest messageDigest;
/**
- * Constructs a new Builder.
+ * Constructs a new {@link Builder}.
*/
public Builder() {
try {
@@ -74,10 +80,17 @@
}
/**
- * Constructs a new instance.
+ * Builds a new {@link MessageDigestCalculatingInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getPath()}</li>
+ * <li>{@link MessageDigest}</li>
+ * </ul>
*
* @return a new instance.
* @throws NullPointerException if messageDigest is null.
diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
index a465ad7..d789dc4 100644
--- a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
@@ -28,7 +28,7 @@
* This class is an example for using an {@link ObservableInputStream}. It creates its own {@link org.apache.commons.io.input.ObservableInputStream.Observer},
* which calculates a checksum using a {@link MessageDigest}, for example, a SHA-512 sum.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* See the MessageDigest section in the <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java
@@ -41,12 +41,15 @@
* <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe, so is {@link MessageDigestInputStream}.
* </p>
*
+ * @see Builder
* @since 2.15.0
*/
public final class MessageDigestInputStream extends ObservableInputStream {
+ // @formatter:off
/**
- * Builds new {@link MessageDigestInputStream} instances.
+ * Builds new {@link MessageDigestInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -59,23 +62,33 @@
* <p>
* You must specify a message digest algorithm name or instance.
* </p>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<MessageDigestInputStream, Builder> {
private MessageDigest messageDigest;
/**
- * Constructs a new Builder.
+ * Constructs a new {@link Builder}.
*/
public Builder() {
// empty
}
/**
- * Constructs a new instance.
+ * Builds new {@link MessageDigestInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getPath()}</li>
+ * <li>{@link MessageDigest}</li>
+ * </ul>
*
* @return a new instance.
* @throws NullPointerException if messageDigest is null.
diff --git a/src/main/java/org/apache/commons/io/input/QueueInputStream.java b/src/main/java/org/apache/commons/io/input/QueueInputStream.java
index 1ed2e84..d6d9529 100644
--- a/src/main/java/org/apache/commons/io/input/QueueInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/QueueInputStream.java
@@ -34,12 +34,11 @@
/**
* Simple alternative to JDK {@link java.io.PipedInputStream}; queue input stream provides what's written in queue output stream.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* Example usage:
* </p>
- *
* <pre>
* QueueInputStream inputStream = new QueueInputStream();
* QueueOutputStream outputStream = inputStream.newQueueOutputStream();
@@ -56,17 +55,19 @@
* {@link IOException}.
* </p>
*
+ * @see Builder
* @see QueueOutputStream
* @since 2.9.0
*/
public class QueueInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link QueueInputStream} instance.
+ * Builds a new {@link QueueInputStream}.
+ *
* <p>
* For example:
* </p>
- *
* <pre>{@code
* QueueInputStream s = QueueInputStream.builder()
* .setBlockingQueue(new LinkedBlockingQueue<>())
@@ -74,18 +75,24 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<QueueInputStream, Builder> {
private BlockingQueue<Integer> blockingQueue = new LinkedBlockingQueue<>();
private Duration timeout = Duration.ZERO;
/**
- * Constructs a new instance.
+ * Builds a new {@link QueueInputStream}.
* <p>
- * This builder use the aspects BlockingQueue and timeout.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #setBlockingQueue(BlockingQueue)}</li>
+ * <li>timeout</li>
+ * </ul>
*
* @return a new instance.
*/
diff --git a/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java b/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
index 25e20c2..4a80ff5 100644
--- a/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
@@ -30,14 +30,18 @@
/**
* Streams data from a {@link RandomAccessFile} starting at its current position.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
+ *
+ * @see Builder
* @since 2.8.0
*/
public class RandomAccessFileInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link RandomAccessFileInputStream} instance.
+ * Builds a new {@link RandomAccessFileInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -48,27 +52,33 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<RandomAccessFileInputStream, Builder> {
private RandomAccessFile randomAccessFile;
private boolean closeOnClose;
/**
- * Constructs a new instance.
+ * Builds a new {@link RandomAccessFileInputStream}.
* <p>
- * This builder use the aspects RandomAccessFile or File, and closeOnClose. Only set one of RandomAccessFile or an origin that can be converted to a
- * File.
+ * You must set input that supports {@link RandomAccessFile} or {@link File}, otherwise, this method throws an exception. Only set one of
+ * RandomAccessFile or an origin that can be converted to a File.
* </p>
* <p>
- * If RandomAccessFile is not set, then you must provide an origin that can be converted to a File by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link RandomAccessFile}</li>
+ * <li>{@link File}</li>
+ * <li>closeOnClose</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
- * @throws IllegalStateException if both RandomAccessFile and origin are set.
+ * @throws IllegalStateException if both RandomAccessFile and origin are set.
* @throws UnsupportedOperationException if the origin cannot be converted to a {@link File}.
* @see AbstractOrigin#getFile()
*/
diff --git a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
index efafbb1..3f3ae68 100644
--- a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
@@ -38,18 +38,21 @@
* read() call is issued. The read ahead buffer is used to asynchronously read from the underlying input stream. When the current active buffer is exhausted, we
* flip the two buffers so that we can start reading from the read ahead buffer without being blocked by disk I/O.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* This class was ported and adapted from Apache Spark commit 933dc6cb7b3de1d8ccaf73d124d6eb95b947ed19.
* </p>
*
+ * @see Builder
* @since 2.9.0
*/
public class ReadAheadInputStream extends FilterInputStream {
+ // @formatter:off
/**
- * Builds a new {@link ReadAheadInputStream} instance.
+ * Builds a new {@link ReadAheadInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -60,20 +63,27 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<ReadAheadInputStream, Builder> {
private ExecutorService executorService;
/**
- * Constructs a new instance.
+ * Builds a new {@link ReadAheadInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
* <p>
- * This builder use the aspects InputStream, OpenOption[], buffer size, ExecutorService.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>{@link ExecutorService}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
index cfe79fc..c4e44ee 100644
--- a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
@@ -50,7 +50,7 @@
* would return the same byte sequence as reading from {@code in} (provided that the initial byte sequence is legal with respect to the charset encoding):
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <pre>
* InputStream inputStream = ...
@@ -79,13 +79,16 @@
* Instances of {@link ReaderInputStream} are not thread safe.
* </p>
*
+ * @see Builder
* @see org.apache.commons.io.output.WriterOutputStream
* @since 2.0
*/
public class ReaderInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link ReaderInputStream} instance.
+ * Builds a new {@link ReaderInputStream}.
+ *
* <p>
* For example:
* </p>
@@ -96,26 +99,36 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<ReaderInputStream, Builder> {
private CharsetEncoder charsetEncoder = newEncoder(getCharset());
/**
- * Constructs a new instance.
+ * Builds a new {@link ReaderInputStream}.
+ *
* <p>
- * This builder use the aspects Reader, Charset, CharsetEncoder, buffer size.
+ * You must set input that supports {@link Reader}, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a Reader by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link Reader}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>{@link #getCharset()}</li>
+ * <li>{@link CharsetEncoder}</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a Reader.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @see AbstractOrigin#getReader(Charset)
+ * @see CharsetEncoder
+ * @see #getBufferSize()
*/
@SuppressWarnings("resource")
@Override
diff --git a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
index 0e11811..8fb7ca9 100644
--- a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
+++ b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
@@ -41,15 +41,18 @@
/**
* Reads lines in a file reversely (similar to a BufferedReader, but starting at the last line). Useful for e.g. searching in log files.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @since 2.2
*/
public class ReversedLinesFileReader implements Closeable {
+ // @formatter:off
/**
- * Builds a new {@link ReversedLinesFileReader} instance.
+ * Builds a new {@link ReversedLinesFileReader}.
+ *
* <p>
* For example:
* </p>
@@ -61,12 +64,14 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<ReversedLinesFileReader, Builder> {
/**
- * Constructs a new Builder.
+ * Constructs a new {@link Builder}.
*/
public Builder() {
setBufferSizeDefault(DEFAULT_BLOCK_SIZE);
@@ -74,11 +79,18 @@
}
/**
- * Constructs a new instance.
+ * Builds a new {@link ReversedLinesFileReader}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()}, {@link #getBufferSize()}, and {@link #getCharset()} on this builder,
- * otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>{@link #getCharset()}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/Tailer.java b/src/main/java/org/apache/commons/io/input/Tailer.java
index 70ba0f2..19c9977 100644
--- a/src/main/java/org/apache/commons/io/input/Tailer.java
+++ b/src/main/java/org/apache/commons/io/input/Tailer.java
@@ -47,18 +47,16 @@
/**
* Simple implementation of the UNIX "tail -f" functionality.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <h2>1. Create a TailerListener implementation</h2>
* <p>
* First you need to create a {@link TailerListener} implementation; ({@link TailerListenerAdapter} is provided for
* convenience so that you don't have to implement every method).
* </p>
- *
* <p>
* For example:
* </p>
- *
* <pre>
* public class MyTailerListener extends TailerListenerAdapter {
* public void handle(String line) {
@@ -66,9 +64,7 @@
* }
* }
* </pre>
- *
* <h2>2. Using a Tailer</h2>
- *
* <p>
* You can create and use a Tailer in one of three ways:
* </p>
@@ -77,13 +73,10 @@
* <li>Using an {@link java.util.concurrent.Executor}</li>
* <li>Using a {@link Thread}</li>
* </ul>
- *
* <p>
* An example of each is shown below.
* </p>
- *
* <h3>2.1 Using a Builder</h3>
- *
* <pre>
* TailerListener listener = new MyTailerListener();
* Tailer tailer = Tailer.builder()
@@ -92,9 +85,7 @@
* .setDelayDuration(delay)
* .get();
* </pre>
- *
* <h3>2.2 Using an Executor</h3>
- *
* <pre>
* TailerListener listener = new MyTailerListener();
* Tailer tailer = new Tailer(file, listener, delay);
@@ -108,10 +99,7 @@
*
* executor.execute(tailer);
* </pre>
- *
- *
* <h3>2.3 Using a Thread</h3>
- *
* <pre>
* TailerListener listener = new MyTailerListener();
* Tailer tailer = new Tailer(file, listener, delay);
@@ -119,21 +107,17 @@
* thread.setDaemon(true); // optional
* thread.start();
* </pre>
- *
* <h2>3. Stopping a Tailer</h2>
* <p>
* Remember to stop the tailer when you have done with it:
* </p>
- *
* <pre>
* tailer.stop();
* </pre>
- *
* <h2>4. Interrupting a Tailer</h2>
* <p>
* You can interrupt the thread a tailer is running on by calling {@link Thread#interrupt()}.
* </p>
- *
* <pre>
* thread.interrupt();
* </pre>
@@ -144,6 +128,7 @@
* The file is read using the default Charset; this can be overridden if necessary.
* </p>
*
+ * @see Builder
* @see TailerListener
* @see TailerListenerAdapter
* @since 2.0
@@ -154,8 +139,10 @@
*/
public class Tailer implements Runnable, AutoCloseable {
+ // @formatter:off
/**
- * Builds a {@link Tailer} with default values.
+ * Builds a new {@link Tailer}.
+ *
* <p>
* For example:
* </p>
@@ -173,8 +160,10 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<Tailer, Builder> {
private static final Duration DEFAULT_DELAY_DURATION = Duration.ofMillis(DEFAULT_DELAY_MILLIS);
@@ -194,22 +183,32 @@
private Tailable tailable;
private TailerListener tailerListener;
private Duration delayDuration = DEFAULT_DELAY_DURATION;
- private boolean end;
+ private boolean tailFromEnd;
private boolean reOpen;
private boolean startThread = true;
private ExecutorService executorService = Executors.newSingleThreadExecutor(Builder::newDaemonThread);
/**
- * Constructs a new instance.
+ * Builds a new {@link Tailer}.
+ *
* <p>
- * This builder use the aspects tailable, Charset, TailerListener, delayDuration, end, reOpen, buffer size.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>{@link #getCharset()}</li>
+ * <li>{@link Tailable}</li>
+ * <li>{@link TailerListener}</li>
+ * <li>delayDuration</li>
+ * <li>tailFromEnd</li>
+ * <li>reOpen</li>
+ * </ul>
*
* @return a new instance.
*/
@Override
public Tailer get() {
- final Tailer tailer = new Tailer(tailable, getCharset(), tailerListener, delayDuration, end, reOpen, getBufferSize());
+ final Tailer tailer = new Tailer(tailable, getCharset(), tailerListener, delayDuration, tailFromEnd, reOpen, getBufferSize());
if (startThread) {
executorService.submit(tailer);
}
@@ -300,7 +299,7 @@
* @return this
*/
public Builder setTailFromEnd(final boolean end) {
- this.end = end;
+ this.tailFromEnd = end;
return this;
}
}
diff --git a/src/main/java/org/apache/commons/io/input/ThrottledInputStream.java b/src/main/java/org/apache/commons/io/input/ThrottledInputStream.java
index ec5c37c..c1826aa 100644
--- a/src/main/java/org/apache/commons/io/input/ThrottledInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ThrottledInputStream.java
@@ -32,34 +32,48 @@
* exceed the specified tolerable maximum. (Thus, while the read-rate might exceed the maximum for a short interval, the average tends towards the
* specified maximum, overall.)
* <p>
+ * To build an instance, see {@link Builder}
+ * </p>
+ * <p>
* Inspired by Apache HBase's class of the same name.
* </p>
*
+ * @see Builder
* @since 2.16.0
*/
public final class ThrottledInputStream extends CountingInputStream {
+ // @formatter:off
/**
- * Builds a new {@link ThrottledInputStream} instance.
+ * Builds a new {@link ThrottledInputStream}.
+ *
* <h2>Using NIO</h2>
- *
* <pre>{@code
- * ThrottledInputStream in = ThrottledInputStream.builder().setPath(Paths.get("MyFile.xml")).setMaxBytesPerSecond(100_000).get();
+ * ThrottledInputStream in = ThrottledInputStream.builder()
+ * .setPath(Paths.get("MyFile.xml"))
+ * .setMaxBytesPerSecond(100_000)
+ * .get();
* }
* </pre>
- *
* <h2>Using IO</h2>
- *
* <pre>{@code
- * ThrottledInputStream in = ThrottledInputStream.builder().setFile(new File("MyFile.xml")).setMaxBytesPerSecond(100_000).get();
+ * ThrottledInputStream in = ThrottledInputStream.builder()
+ * .setFile(new File("MyFile.xml"))
+ * .setMaxBytesPerSecond(100_000)
+ * .get();
+ * }
+ * </pre>
+ * <pre>{@code
+ * ThrottledInputStream in = ThrottledInputStream.builder()
+ * .setInputStream(inputStream)
+ * .setMaxBytesPerSecond(100_000)
+ * .get();
* }
* </pre>
*
- * <pre>{@code
- * ThrottledInputStream in = ThrottledInputStream.builder().setInputStream(inputStream).setMaxBytesPerSecond(100_000).get();
- * }
- * </pre>
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<ThrottledInputStream, Builder> {
/**
@@ -68,10 +82,17 @@
private long maxBytesPerSecond = Long.MAX_VALUE;
/**
- * Constructs a new instance.
+ * Builds a new {@link ThrottledInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
+ * <p>
+ * This builder use the following aspects:
+ * </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>maxBytesPerSecond</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java b/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
index c0cd7c5..30f52d8 100644
--- a/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
+++ b/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
@@ -31,9 +31,10 @@
/**
* A {@link BufferedReader} that throws {@link UncheckedIOException} instead of {@link IOException}.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see BufferedReader
* @see IOException
* @see UncheckedIOException
@@ -41,8 +42,10 @@
*/
public final class UncheckedBufferedReader extends BufferedReader {
+ // @formatter:off
/**
- * Builds a new {@link UncheckedBufferedReader} instance.
+ * Builds a new {@link UncheckedBufferedReader}.
+ *
* <p>
* Using File IO:
* </p>
@@ -63,14 +66,22 @@
* .setCharset(Charset.defaultCharset())
* .get();}
* </pre>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<UncheckedBufferedReader, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UncheckedBufferedReader}.
+ *
* <p>
- * This builder use the aspects Reader, Charset, buffer size.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link Reader}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * </ul>
* <p>
* You must provide an origin that can be converted to a Reader by this builder, otherwise, this call will throw an
* {@link UnsupportedOperationException}.
@@ -80,6 +91,7 @@
* @throws UnsupportedOperationException if the origin cannot provide a Reader.
* @throws IllegalStateException if the {@code origin} is {@code null}.
* @see AbstractOrigin#getReader(Charset)
+ * @see #getBufferSize()
*/
@Override
public UncheckedBufferedReader get() {
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java b/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java
index d1b00c2..3fa0498 100644
--- a/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/UncheckedFilterInputStream.java
@@ -29,9 +29,10 @@
/**
* A {@link BufferedReader} that throws {@link UncheckedIOException} instead of {@link IOException}.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see BufferedReader
* @see IOException
* @see UncheckedIOException
@@ -39,8 +40,10 @@
*/
public final class UncheckedFilterInputStream extends FilterInputStream {
+ // @formatter:off
/**
- * Builds a new {@link UncheckedFilterInputStream} instance.
+ * Builds a new {@link UncheckedFilterInputStream}.
+ *
* <p>
* Using File IO:
* </p>
@@ -57,18 +60,23 @@
* .setPath(path)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<UncheckedFilterInputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UncheckedFilterInputStream}.
* <p>
- * This builder use the aspect InputStream and OpenOption[].
+ * You must set input that supports {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to an InputStream by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide an InputStream.
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java b/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
index 4b9fe8e..e366461 100644
--- a/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
+++ b/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
@@ -31,9 +31,10 @@
/**
* A {@link FilterReader} that throws {@link UncheckedIOException} instead of {@link IOException}.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see FilterReader
* @see IOException
* @see UncheckedIOException
@@ -41,8 +42,10 @@
*/
public final class UncheckedFilterReader extends FilterReader {
+ // @formatter:off
/**
- * Builds a new {@link UncheckedFilterReader} instance.
+ * Builds a new {@link UncheckedFilterReader}.
+ *
* <p>
* Using File IO:
* </p>
@@ -59,18 +62,24 @@
* .setPath(path)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<UncheckedFilterReader, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UncheckedFilterReader}.
* <p>
- * This builder use the aspects Reader and Charset.
+ * You must set input that supports {@link Reader} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a Reader by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link Reader}</li>
+ * <li>{@link #getCharset()}</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a Reader.
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
index 3cf17d3..c715dae 100644
--- a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
@@ -32,7 +32,7 @@
* takes place when filling that buffer, but this is usually outweighed by the performance benefits.
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* A typical application pattern for the class looks like this:
@@ -48,14 +48,17 @@
* Provenance: Apache Harmony and modified.
* </p>
*
+ * @see Builder
* @see BufferedInputStream
* @since 2.12.0
*/
//@NotThreadSafe
public final class UnsynchronizedBufferedInputStream extends UnsynchronizedFilterInputStream {
+ // @formatter:off
/**
- * Builds a new {@link UnsynchronizedBufferedInputStream} instance.
+ * Builds a new {@link UnsynchronizedBufferedInputStream}.
+ *
* <p>
* Using File IO:
* </p>
@@ -74,18 +77,24 @@
* .setBufferSize(8192)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<UnsynchronizedBufferedInputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UnsynchronizedBufferedInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} and {@link #getBufferSize()} on this builder, otherwise, this method
- * throws an exception.
+ * You must set input that supports {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * This builder use the aspects InputStream, OpenOption[] and buffer size.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
index fdaafc7..f9d4c12 100644
--- a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
@@ -28,57 +28,75 @@
* This is an alternative to {@link java.io.ByteArrayInputStream} which removes the synchronization overhead for non-concurrent access; as such this class is
* not thread-safe.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see ByteArrayInputStream
* @since 2.7
*/
//@NotThreadSafe
public class UnsynchronizedByteArrayInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link UnsynchronizedByteArrayInputStream} instance.
+ * Builds a new {@link UnsynchronizedByteArrayInputStream}.
+ *
* <p>
* Using a Byte Array:
* </p>
- *
* <pre>{@code
- * UnsynchronizedByteArrayInputStream s = UnsynchronizedByteArrayInputStream.builder().setByteArray(byteArray).setOffset(0).setLength(byteArray.length)
- * .get();
+ * UnsynchronizedByteArrayInputStream s = UnsynchronizedByteArrayInputStream.builder()
+ * .setByteArray(byteArray)
+ * .setOffset(0)
+ * .setLength(byteArray.length)
+ * .get();
* }
* </pre>
* <p>
* Using File IO:
* </p>
- *
* <pre>{@code
- * UnsynchronizedByteArrayInputStream s = UnsynchronizedByteArrayInputStream.builder().setFile(file).setOffset(0).setLength(byteArray.length).get();
+ * UnsynchronizedByteArrayInputStream s = UnsynchronizedByteArrayInputStream.builder()
+ * .setFile(file)
+ * .setOffset(0)
+ * .setLength(byteArray.length)
+ * .get();
* }
* </pre>
* <p>
* Using NIO Path:
* </p>
- *
* <pre>{@code
- * UnsynchronizedByteArrayInputStream s = UnsynchronizedByteArrayInputStream.builder().setPath(path).setOffset(0).setLength(byteArray.length).get();
+ * UnsynchronizedByteArrayInputStream s = UnsynchronizedByteArrayInputStream.builder()
+ * .setPath(path)
+ * .setOffset(0)
+ * .setLength(byteArray.length)
+ * .get();
* }
* </pre>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<UnsynchronizedByteArrayInputStream, Builder> {
private int offset;
private int length;
/**
- * Constructs a new instance.
+ * Builds a new {@link UnsynchronizedByteArrayInputStream}.
* <p>
- * This builder use the aspects byte[], offset and length.
+ * You must set input that supports {@code byte[]} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a byte[] by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@code byte[]}</li>
+ * <li>offset</li>
+ * <li>length</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a byte[].
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
index f2f0294..fd199ce 100644
--- a/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
@@ -31,20 +31,23 @@
* and provide some additional functionality on top of it usually inherit from this class.
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* Provenance: Apache Harmony and modified.
* </p>
*
+ * @see Builder
* @see FilterInputStream
* @since 2.12.0
*/
//@NotThreadSafe
public class UnsynchronizedFilterInputStream extends InputStream {
+ // @formatter:off
/**
- * Builds a new {@link UnsynchronizedFilterInputStream} instance.
+ * Builds a new {@link UnsynchronizedFilterInputStream}.
+ *
* <p>
* Using File IO:
* </p>
@@ -61,17 +64,23 @@
* .setPath(path)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<UnsynchronizedFilterInputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UnsynchronizedFilterInputStream}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
* <p>
- * This builder use the aspects InputStream, OpenOption[] and buffer size.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
index b470779..9ae9dcd 100644
--- a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
+++ b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
@@ -62,19 +62,21 @@
* Determining the character encoding of a feed</a>.
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* Originally developed for <a href="https://rome.dev.java.net">ROME</a> under Apache License 2.0.
* </p>
*
+ * @see Builder
* @see org.apache.commons.io.output.XmlStreamWriter
* @since 2.0
*/
public class XmlStreamReader extends Reader {
+ // @formatter:off
/**
- * Builds a new {@link XmlStreamWriter} instance.
+ * Builds a new {@link XmlStreamWriter}.
*
* Constructs a Reader using an InputStream and the associated content-type header. This constructor is lenient regarding the encoding detection.
* <p>
@@ -104,12 +106,17 @@
* </p>
*
* <pre>{@code
- * XmlStreamReader r = XmlStreamReader.builder().setPath(path).setCharset(StandardCharsets.UTF_8).get();
+ * XmlStreamReader r = XmlStreamReader.builder()
+ * .setPath(path)
+ * .setCharset(StandardCharsets.UTF_8)
+ * .get();
* }
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
+ // @formatter:on
public static class Builder extends AbstractStreamBuilder<XmlStreamReader, Builder> {
private boolean nullCharset = true;
@@ -117,13 +124,19 @@
private String httpContentType;
/**
- * Constructs a new instance.
+ * Builds a new {@link XmlStreamWriter}.
* <p>
- * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * You must set input that supports {@link #getInputStream()}, otherwise, this method throws an exception.
* </p>
* <p>
- * This builder use the aspect InputStream, OpenOption[], httpContentType, lenient, and defaultEncoding.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link #getCharset()}</li>
+ * <li>lenient</li>
+ * <li>httpContentType</li>
+ * </ul>
*
* @return a new instance.
* @throws IllegalStateException if the {@code origin} is {@code null}.
diff --git a/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java b/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java
index b8e2abe..43de792 100644
--- a/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java
@@ -26,18 +26,22 @@
/**
* OutputStream which breaks larger output blocks into chunks. Native code may need to copy the input array; if the write buffer is very large this can cause
* OOME.
+ * <p>
+ * To build an instance, see {@link Builder}
+ * </p>
*
+ * @see Builder
* @since 2.5
*/
public class ChunkedOutputStream extends FilterOutputStream {
// @formatter:off
/**
- * Builds a new {@link UnsynchronizedByteArrayOutputStream} instance.
+ * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
+ *
* <p>
* Using File IO:
* </p>
- *
* <pre>{@code
* UnsynchronizedByteArrayOutputStream s = UnsynchronizedByteArrayOutputStream.builder()
* .setBufferSize(8192)
@@ -47,7 +51,6 @@
* <p>
* Using NIO Path:
* </p>
- *
* <pre>{@code
* UnsynchronizedByteArrayOutputStream s = UnsynchronizedByteArrayOutputStream.builder()
* .setBufferSize(8192)
@@ -55,21 +58,28 @@
* }
* </pre>
*
+ * @see #get()
* @since 2.13.0
*/
// @formatter:on
public static class Builder extends AbstractStreamBuilder<ChunkedOutputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
* <p>
- * This builder use the aspects OutputStream and buffer size (chunk size).
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getInputStream()}</li>
+ * <li>{@link #getBufferSize()} (chunk size)</li>
+ * </ul>
*
* @return a new instance.
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
* @throws IOException if an I/O error occurs.
- * @throws UnsupportedOperationException if the origin cannot be converted to an OutputStream.
* @see #getOutputStream()
+ * @see #getBufferSize()
*/
@Override
public ChunkedOutputStream get() throws IOException {
diff --git a/src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java b/src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java
index 045eae4..bd69e0e 100644
--- a/src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/DeferredFileOutputStream.java
@@ -32,18 +32,21 @@
* An output stream which will retain data in memory until a specified threshold is reached, and only then commit it to disk. If the stream is closed before the
* threshold is reached, the data will not be written to disk at all.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <p>
* This class originated in FileUpload processing. In this use case, you do not know in advance the size of the file being uploaded. If the file is small you
* want to store it in memory (for speed), but if the file is large you want to store it to file (to avoid memory issues).
* </p>
+ *
+ * @see Builder
*/
public class DeferredFileOutputStream extends ThresholdingOutputStream {
// @formatter:off
/**
- * Builds a new {@link DeferredFileOutputStream} instance.
+ * Builds a new {@link DeferredFileOutputStream}.
+ *
* <p>
* For example:
* </p>
@@ -61,6 +64,7 @@
* The only super's aspect used us buffer size.
* </p>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -81,10 +85,18 @@
}
/**
- * Constructs a new instance.
+ * Builds a new {@link DeferredFileOutputStream}.
* <p>
- * This builder use the aspects threshold, outputFile, prefix, suffix, directory, buffer size.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>threshold</li>
+ * <li>outputFile</li>
+ * <li>prefix</li>
+ * <li>suffix</li>
+ * <li>directory</li>
+ * </ul>
*
* @return a new instance.
*/
diff --git a/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java b/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
index d583b23..fc98fd5 100644
--- a/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
+++ b/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
@@ -44,16 +44,18 @@
* required then use the {@link java.io.FileWriter} directly, rather than this implementation.
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @since 1.4
*/
public class FileWriterWithEncoding extends ProxyWriter {
// @formatter:off
/**
- * Builds a new {@link FileWriterWithEncoding} instance.
+ * Builds a new {@link FileWriterWithEncoding}.
+ *
* <p>
* Using a CharsetEncoder:
* </p>
@@ -75,6 +77,7 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -85,14 +88,18 @@
private CharsetEncoder charsetEncoder = super.getCharset().newEncoder();
/**
- * Constructs a new instance.
+ * Builds a new {@link FileWriterWithEncoding}.
* <p>
- * This builder use the aspects File, CharsetEncoder, and append.
+ * You must set input that supports {@link File} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a File by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link File}</li>
+ * <li>{@link CharsetEncoder}</li>
+ * <li>append</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a File.
diff --git a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
index d197270..b57dc2c 100644
--- a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
+++ b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
@@ -45,14 +45,17 @@
* {@code java.io.tmpdir}. The encoding may also be specified, and defaults to the platform default.
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
+ *
+ * @see Builder
*/
public class LockableFileWriter extends Writer {
// @formatter:off
/**
- * Builds a new {@link LockableFileWriter} instance.
+ * Builds a new {@link LockableFileWriter}.
+ *
* <p>
* Using a CharsetEncoder:
* </p>
@@ -64,6 +67,7 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -73,7 +77,7 @@
private AbstractOrigin<?, ?> lockDirectory = AbstractOriginSupplier.newFileOrigin(FileUtils.getTempDirectoryPath());
/**
- * Constructs a new Builder.
+ * Builds a new {@link LockableFileWriter}.
*/
public Builder() {
setBufferSizeDefault(AbstractByteArrayOutputStream.DEFAULT_SIZE);
@@ -83,12 +87,17 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects File, Charset, append, and lockDirectory.
+ * You must set input that supports {@link File} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a File by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link File}</li>
+ * <li>{@link #getCharset()}</li>
+ * <li>append</li>
+ * <li>lockDirectory</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a File.
diff --git a/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java b/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
index aadc624..cfcceb0 100644
--- a/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
@@ -28,19 +28,20 @@
/**
* A {@link FilterOutputStream} that throws {@link UncheckedIOException} instead of {@link UncheckedIOException}.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see FilterOutputStream
* @see UncheckedIOException
- * @see UncheckedIOException
* @since 2.12.0
*/
public final class UncheckedFilterOutputStream extends FilterOutputStream {
// @formatter:off
/**
- * Builds a new {@link UncheckedFilterOutputStream} instance.
+ * Builds a new {@link UncheckedFilterOutputStream}.
+ *
* <p>
* Using File IO:
* </p>
@@ -57,22 +58,28 @@
* .setPath(path)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
// @formatter:on
public static class Builder extends AbstractStreamBuilder<UncheckedFilterOutputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UncheckedFilterOutputStream}.
* <p>
- * This builder use the aspect OutputStream and OpenOption[].
+ * You must set input that supports {@link #getOutputStream()} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to an OutputStream by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getOutputStream()}</li>
+ * </ul>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an OutputStream.
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
+ * @throws IOException if an I/O error occurs.
* @see #getOutputStream()
*/
@SuppressWarnings("resource")
diff --git a/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java b/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
index f126917..b9e2589 100644
--- a/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
+++ b/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
@@ -28,9 +28,10 @@
/**
* A {@link FilterWriter} that throws {@link UncheckedIOException} instead of {@link IOException}.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see FilterWriter
* @see IOException
* @see UncheckedIOException
@@ -40,7 +41,8 @@
// @formatter:off
/**
- * Builds a new {@link UncheckedFilterWriter} instance.
+ * Builds a new {@link UncheckedFilterWriter}.
+ *
* <p>
* Using File IO:
* </p>
@@ -57,19 +59,23 @@
* .setPath(path)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
// @formatter:on
public static class Builder extends AbstractStreamBuilder<UncheckedFilterWriter, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UncheckedFilterWriter}.
* <p>
- * This builder use the aspects Writer, OpenOption[], and Charset.
+ * You must set input that supports {@link #getWriter()} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a Writer by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getWriter()}</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a Writer.
diff --git a/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java b/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
index d68978c..31e14aa 100644
--- a/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
@@ -29,9 +29,10 @@
/**
* Implements a version of {@link AbstractByteArrayOutputStream} <b>without</b> any concurrent thread safety.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @since 2.7
*/
//@NotThreadSafe
@@ -39,7 +40,8 @@
// @formatter:off
/**
- * Builds a new {@link UnsynchronizedByteArrayOutputStream} instance.
+ * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
+ *
* <p>
* Using File IO:
* </p>
@@ -56,15 +58,21 @@
* .setBufferSize(8192)
* .get();}
* </pre>
+ *
+ * @see #get()
*/
// @formatter:on
public static class Builder extends AbstractStreamBuilder<UnsynchronizedByteArrayOutputStream, Builder> {
/**
- * Constructs a new instance.
+ * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
+ *
* <p>
- * This builder use the aspect buffer size.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getBufferSize()}</li>
+ * </ul>
*
* @return a new instance.
* @see AbstractOrigin#getByteArray()
diff --git a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
index e562187..b61c3ce 100644
--- a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
@@ -48,7 +48,7 @@
* would have the same result as writing to {@code out} directly (provided that the byte sequence is legal with respect to the charset encoding):
* </p>
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
* <pre>
* OutputStream out = ...
@@ -73,6 +73,7 @@
* Instances of {@link WriterOutputStream} are not thread safe.
* </p>
*
+ * @see Builder
* @see org.apache.commons.io.input.ReaderInputStream
* @since 2.0
*/
@@ -80,7 +81,8 @@
// @formatter:off
/**
- * Builds a new {@link WriterOutputStream} instance.
+ * Builds a new {@link WriterOutputStream}.
+ *
* <p>
* For example:
* </p>
@@ -93,6 +95,7 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -109,14 +112,19 @@
}
/**
- * Constructs a new instance.
+ * Builds a new {@link WriterOutputStream}.
* <p>
- * This builder use the aspect Writer, OpenOption[], Charset, CharsetDecoder, buffer size and writeImmediately.
+ * You must set input that supports {@link #getWriter()} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to a Writer by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getWriter()}</li>
+ * <li>{@link #getBufferSize()}</li>
+ * <li>charsetDecoder</li>
+ * <li>writeImmediately</li>
+ * </ul>
*
* @return a new instance.
* @throws UnsupportedOperationException if the origin cannot provide a Writer.
diff --git a/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java b/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
index 858a008..a8ccc24 100644
--- a/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
+++ b/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
@@ -38,9 +38,10 @@
/**
* Character stream that handles all the necessary work to figure out the charset encoding of the XML document written to the stream.
* <p>
- * To build an instance, see {@link Builder}.
+ * To build an instance, use {@link Builder}.
* </p>
*
+ * @see Builder
* @see XmlStreamReader
* @since 2.0
*/
@@ -48,7 +49,8 @@
// @formatter:off
/**
- * Builds a new {@link XmlStreamWriter} instance.
+ * Builds a new {@link XmlStreamWriter}.
+ *
* <p>
* For example:
* </p>
@@ -59,13 +61,14 @@
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:off
public static class Builder extends AbstractStreamBuilder<XmlStreamWriter, Builder> {
/**
- * Constructs a new Builder.
+ * Constructs a new {@link Builder}.
*/
public Builder() {
setCharsetDefault(StandardCharsets.UTF_8);
@@ -73,17 +76,21 @@
}
/**
- * Constructs a new instance.
+ * Builds a new {@link XmlStreamWriter}.
* <p>
- * This builder use the aspect OutputStream, OpenOption[], and Charset.
+ * You must set input that supports {@link #getOutputStream()} on this builder, otherwise, this method throws an exception.
* </p>
* <p>
- * You must provide an origin that can be converted to an OutputStream by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * This builder use the following aspects:
* </p>
+ * <ul>
+ * <li>{@link #getOutputStream()}</li>
+ * <li>{@link #getCharset()}</li>
+ * </ul>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an OutputStream.
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to an {@link OutputStream}.
* @throws IOException if an I/O error occurs.
* @see #getOutputStream()
*/
