This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new 5e3c7e8f Javadoc
5e3c7e8f is described below
commit 5e3c7e8ff7ebf048f2555028a86732a81d2ae7e1
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Sun Jan 28 08:49:53 2024 -0500
Javadoc
---
.../commons/io/build/AbstractStreamBuilder.java | 13 +++---
.../commons/io/filefilter/WildcardFileFilter.java | 2 +-
.../commons/io/input/AutoCloseInputStream.java | 52 ++++++++++++----------
.../apache/commons/io/input/BOMInputStream.java | 25 ++++++++---
.../commons/io/input/BoundedInputStream.java | 36 +++++++++++----
.../io/input/BufferedFileChannelInputStream.java | 23 +++++++---
.../commons/io/input/CharSequenceInputStream.java | 22 +++++++--
.../commons/io/input/ChecksumInputStream.java | 26 ++++++++---
.../io/input/MemoryMappedFileInputStream.java | 23 +++++++---
.../input/MessageDigestCalculatingInputStream.java | 23 +++++++---
.../commons/io/input/MessageDigestInputStream.java | 23 +++++++---
.../apache/commons/io/input/QueueInputStream.java | 19 +++++---
.../io/input/RandomAccessFileInputStream.java | 26 +++++++----
.../commons/io/input/ReadAheadInputStream.java | 20 ++++++---
.../apache/commons/io/input/ReaderInputStream.java | 25 ++++++++---
.../commons/io/input/ReversedLinesFileReader.java | 24 +++++++---
.../java/org/apache/commons/io/input/Tailer.java | 45 +++++++++----------
.../commons/io/input/ThrottledInputStream.java | 41 ++++++++++++-----
.../commons/io/input/UncheckedBufferedReader.java | 20 +++++++--
.../io/input/UncheckedFilterInputStream.java | 20 ++++++---
.../commons/io/input/UncheckedFilterReader.java | 21 ++++++---
.../input/UnsynchronizedBufferedInputStream.java | 21 ++++++---
.../input/UnsynchronizedByteArrayInputStream.java | 44 ++++++++++++------
.../io/input/UnsynchronizedFilterInputStream.java | 19 +++++---
.../apache/commons/io/input/XmlStreamReader.java | 25 ++++++++---
.../commons/io/output/ChunkedOutputStream.java | 22 ++++++---
.../io/output/DeferredFileOutputStream.java | 20 +++++++--
.../commons/io/output/FileWriterWithEncoding.java | 19 +++++---
.../commons/io/output/LockableFileWriter.java | 21 ++++++---
.../io/output/UncheckedFilterOutputStream.java | 23 ++++++----
.../commons/io/output/UncheckedFilterWriter.java | 18 +++++---
.../UnsynchronizedByteArrayOutputStream.java | 16 +++++--
.../commons/io/output/WriterOutputStream.java | 20 ++++++---
.../apache/commons/io/output/XmlStreamWriter.java | 23 ++++++----
34 files changed, 580 insertions(+), 240 deletions(-)
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 4262c690..7b113237 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 @@ public abstract class AbstractStreamBuilder<T, B extends
AbstractStreamBuilder<T
}
/**
- * 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 @@ public abstract class AbstractStreamBuilder<T, B extends
AbstractStreamBuilder<T
}
/**
- * 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 @@ public abstract class AbstractStreamBuilder<T, B extends
AbstractStreamBuilder<T
}
/**
- * 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 639feffb..f5bad2e3 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 @@ import org.apache.commons.io.file.PathUtils;
* 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 816bbf3a..d7c705f4 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 java.io.InputStream;
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 @@ public class AutoCloseInputStream extends
ProxyInputStream {
}
/**
- * 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 @@ public class AutoCloseInputStream extends ProxyInputStream {
}
/**
- * 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 ad723f7b..130c7a4a 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* <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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* // 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 @@ public class BOMInputStream extends ProxyInputStream {
* .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 @@ public class BOMInputStream extends ProxyInputStream {
private boolean include;
/**
- * Constructs a new instance.
+ * Builds a new {@link BOMInputStream}.
+ * <p>
+ * You must set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link
#getInputStream()} on this builder, otherwise, this method throws an exception.
+ * This builder use the following aspects: InputStream, OpenOption[],
include, and ByteOrderMark[].
* </p>
* <p>
- * This builder use the aspects InputStream, OpenOption[], include,
and ByteOrderMark[].
+ * 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 f6f4373f..7175dac8 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ public class BoundedInputStream extends ProxyInputStream {
private boolean propagateClose = true;
/**
- * Constructs a new instance.
+ * Builds a new {@link BoundedInputStream}.
+ * <p>
+ * You must set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link
#getInputStream()} on this builder, otherwise, this method throws an exception.
+ * 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 045ab068..870c1e44 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ public final class BufferedFileChannelInputStream extends
InputStream {
* <p>
* Using NIO Path:
* </p>
- *
* <pre>{@code
* BufferedFileChannelInputStream s =
BufferedFileChannelInputStream.builder()
* .setPath(path)
@@ -65,16 +66,24 @@ public final class BufferedFileChannelInputStream extends
InputStream {
* .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 set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link #getPath()}
and {@link #getBufferSize()} on this builder, otherwise, this method throws an
- * exception.
+ * 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 aa472c2d..2f25d146 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 @@ import org.apache.commons.io.function.Uncheck;
* <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 @@ public class CharSequenceInputStream extends InputStream {
* .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>
+ * You must set input that supports {@link #getCharSequence()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * This builder use the aspects the CharSequence, buffer size, and
Charset.
+ * 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 b3a052e6..edbe2c39 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* <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 @@ public final class ChecksumInputStream extends
CountingInputStream {
* .setExpectedChecksumValue(12345)
* .get();
* }</pre>
- *
* <h2>Using IO</h2>
- *
* <pre>{@code
* ChecksumInputStream s = ChecksumInputStream.builder()
* .setFile(new File("MyFile.xml"))
@@ -64,7 +66,6 @@ public final class ChecksumInputStream extends
CountingInputStream {
* .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 @@ public final class ChecksumInputStream extends
CountingInputStream {
* .setCountThreshold(100)
* .get();
* }</pre>
+ *
+ * @see #get()
*/
// @formatter:on
public static class Builder extends
AbstractStreamBuilder<ChecksumInputStream, Builder> {
@@ -116,10 +119,19 @@ public final class ChecksumInputStream extends
CountingInputStream {
private long expectedChecksumValue;
/**
- * Constructs a new instance.
+ * Builds a new {@link ChecksumInputStream}.
+ * <p>
+ * You must set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link
#getInputStream()} on this builder, otherwise, this method throws an exception.
+ * 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 c60af531..04c385ff 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* .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 @@ public final class MemoryMappedFileInputStream extends
InputStream {
* .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 @@ public final class MemoryMappedFileInputStream extends
InputStream {
}
/**
- * Constructs a new instance.
+ * Builds a new {@link MemoryMappedFileInputStream}.
+ * <p>
+ * You must set input that supports {@link #getPath()}, otherwise,
this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link #getPath()}
and {@link #getBufferSize()} this builder, otherwise, this method throws an
- * exception.
+ * 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 c3ffc1b4..d4a01b26 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* <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 @@ public class MessageDigestCalculatingInputStream extends
ObservableInputStream {
* .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 @@ public class MessageDigestCalculatingInputStream extends
ObservableInputStream {
}
/**
- * Constructs a new instance.
+ * Builds a new {@link MessageDigestCalculatingInputStream}.
+ * <p>
+ * You must set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link
#getInputStream()} on this builder, otherwise, this method throws an exception.
+ * 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 a465ad72..d789dc41 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* <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 @@ public final class MessageDigestInputStream extends
ObservableInputStream {
* <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 set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link
#getInputStream()} on this builder, otherwise, this method throws an exception.
+ * 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 1ed2e84a..d6d9529a 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 @@ import org.apache.commons.io.output.QueueOutputStream;
/**
* 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 @@ import org.apache.commons.io.output.QueueOutputStream;
* {@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 @@ public class QueueInputStream extends InputStream {
* .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 25e20c23..4a80ff58 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
/**
* 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 @@ public class RandomAccessFileInputStream extends
InputStream {
* .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 efafbb16..3f3ae68d 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ public class ReadAheadInputStream extends FilterInputStream
{
* .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 cfe79fc1..c4e44eea 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 @@ import org.apache.commons.io.charset.CharsetEncoders;
* 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 @@ import org.apache.commons.io.charset.CharsetEncoders;
* 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 @@ public class ReaderInputStream extends InputStream {
* .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 0e118115..8fb7ca91 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
/**
* 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 @@ public class ReversedLinesFileReader implements Closeable {
* .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 @@ public class ReversedLinesFileReader implements Closeable {
}
/**
- * Constructs a new instance.
+ * Builds a new {@link ReversedLinesFileReader}.
+ * <p>
+ * 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 supports calling {@link
#getInputStream()}, {@link #getBufferSize()}, and {@link #getCharset()} on this
builder,
- * otherwise, this method throws an exception.
+ * 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 70ba0f2c..19c99775 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 @@ import org.apache.commons.io.file.attribute.FileTimes;
/**
* 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 @@ import org.apache.commons.io.file.attribute.FileTimes;
* }
* }
* </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 @@ import org.apache.commons.io.file.attribute.FileTimes;
* <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 @@ import org.apache.commons.io.file.attribute.FileTimes;
* .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 @@ import org.apache.commons.io.file.attribute.FileTimes;
*
* 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 @@ import org.apache.commons.io.file.attribute.FileTimes;
* 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 @@ import org.apache.commons.io.file.attribute.FileTimes;
* 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 @@ import org.apache.commons.io.file.attribute.FileTimes;
*/
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 @@ public class Tailer implements Runnable, AutoCloseable {
* .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 @@ public class Tailer implements Runnable, AutoCloseable {
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 @@ public class Tailer implements Runnable, AutoCloseable {
* @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 ec5c37c0..c1826aa9 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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.
- * <h2>Using NIO</h2>
+ * 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();
+ * 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 @@ public final class ThrottledInputStream extends
CountingInputStream {
private long maxBytesPerSecond = Long.MAX_VALUE;
/**
- * Constructs a new instance.
+ * Builds a new {@link ThrottledInputStream}.
+ * <p>
+ * You must set input that supports {@link #getInputStream()},
otherwise, this method throws an exception.
+ * </p>
* <p>
- * You must provide an origin that supports calling {@link
#getInputStream()} on this builder, otherwise, this method throws an exception.
+ * 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 c0cd7c5a..30f52d88 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 @@ import org.apache.commons.io.function.Uncheck;
/**
* 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 @@ import org.apache.commons.io.function.Uncheck;
*/
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 @@ public final class UncheckedBufferedReader extends
BufferedReader {
* .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 @@ public final class UncheckedBufferedReader extends
BufferedReader {
* @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 d1b00c2b..3fa04986 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 @@ import org.apache.commons.io.function.Uncheck;
/**
* 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 @@ import org.apache.commons.io.function.Uncheck;
*/
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 @@ public final class UncheckedFilterInputStream extends
FilterInputStream {
* .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 4b9fe8e1..e366461c 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 @@ import org.apache.commons.io.function.Uncheck;
/**
* 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 @@ import org.apache.commons.io.function.Uncheck;
*/
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 @@ public final class UncheckedFilterReader extends
FilterReader {
* .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 3cf17d3d..c715daef 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ public final class UnsynchronizedBufferedInputStream
extends UnsynchronizedFilte
* .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 fdaafc74..f9d4c12c 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 f2f02949..fd199ceb 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ public class UnsynchronizedFilterInputStream extends
InputStream {
* .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 b4707795..9ae9dcd6 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 @@ import org.apache.commons.io.output.XmlStreamWriter;
* 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 @@ public class XmlStreamReader extends Reader {
* </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 @@ public class XmlStreamReader extends Reader {
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 b8e2abe2..43de7922 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
/**
* 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 @@ public class ChunkedOutputStream extends FilterOutputStream {
* <p>
* Using NIO Path:
* </p>
- *
* <pre>{@code
* UnsynchronizedByteArrayOutputStream s =
UnsynchronizedByteArrayOutputStream.builder()
* .setBufferSize(8192)
@@ -55,21 +58,28 @@ public class ChunkedOutputStream extends FilterOutputStream
{
* }
* </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 045eae4a..bd69e0e5 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 @@ import org.apache.commons.io.file.PathUtils;
* 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 @@ public class DeferredFileOutputStream extends
ThresholdingOutputStream {
* The only super's aspect used us buffer size.
* </p>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -81,10 +85,18 @@ public class DeferredFileOutputStream extends
ThresholdingOutputStream {
}
/**
- * 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 d583b232..fc98fd5b 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* 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 @@ public class FileWriterWithEncoding extends ProxyWriter {
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -85,14 +88,18 @@ public class FileWriterWithEncoding extends ProxyWriter {
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 d197270f..b57dc2c9 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 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
* {@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 @@ public class LockableFileWriter extends Writer {
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -73,7 +77,7 @@ public class LockableFileWriter extends Writer {
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 @@ public class LockableFileWriter extends Writer {
/**
* 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 aadc6240..cfcceb02 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 @@ import org.apache.commons.io.function.Uncheck;
/**
* 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 @@ public final class UncheckedFilterOutputStream extends
FilterOutputStream {
* .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 f126917c..b9e25897 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 @@ import org.apache.commons.io.function.Uncheck;
/**
* 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 @@ public final class UncheckedFilterWriter extends FilterWriter
{
// @formatter:off
/**
- * Builds a new {@link UncheckedFilterWriter} instance.
+ * Builds a new {@link UncheckedFilterWriter}.
+ *
* <p>
* Using File IO:
* </p>
@@ -57,19 +59,23 @@ public final class UncheckedFilterWriter extends
FilterWriter {
* .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 d68978c6..31e14aab 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 @@ import
org.apache.commons.io.input.UnsynchronizedByteArrayInputStream;
/**
* 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 @@ public final class UnsynchronizedByteArrayOutputStream
extends AbstractByteArray
// @formatter:off
/**
- * Builds a new {@link UnsynchronizedByteArrayOutputStream} instance.
+ * Builds a new {@link UnsynchronizedByteArrayOutputStream}.
+ *
* <p>
* Using File IO:
* </p>
@@ -56,15 +58,21 @@ public final class UnsynchronizedByteArrayOutputStream
extends AbstractByteArray
* .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 e5621875..b61c3cee 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 @@ import org.apache.commons.io.charset.CharsetDecoders;
* 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 @@ import org.apache.commons.io.charset.CharsetDecoders;
* 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 @@ public class WriterOutputStream extends OutputStream {
// @formatter:off
/**
- * Builds a new {@link WriterOutputStream} instance.
+ * Builds a new {@link WriterOutputStream}.
+ *
* <p>
* For example:
* </p>
@@ -93,6 +95,7 @@ public class WriterOutputStream extends OutputStream {
* .get();}
* </pre>
*
+ * @see #get()
* @since 2.12.0
*/
// @formatter:on
@@ -109,14 +112,19 @@ public class WriterOutputStream extends OutputStream {
}
/**
- * 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 858a0087..a8ccc249 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 @@ import org.apache.commons.io.input.XmlStreamReader;
/**
* 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 @@ public class XmlStreamWriter extends Writer {
// @formatter:off
/**
- * Builds a new {@link XmlStreamWriter} instance.
+ * Builds a new {@link XmlStreamWriter}.
+ *
* <p>
* For example:
* </p>
@@ -59,13 +61,14 @@ public class XmlStreamWriter extends Writer {
* .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 @@ public class XmlStreamWriter extends Writer {
}
/**
- * 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()
*/
