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 e0f9ba6..4262c69 100644
--- a/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
+++ b/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
@@ -112,9 +112,9 @@
* Gets a CharSequence from the origin with a Charset.
*
* @return An input stream
- * @throws IOException if an I/O error occurs.
- * @throws UnsupportedOperationException if the origin cannot be converted to a CharSequence.
* @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to a CharSequence.
+ * @throws IOException if an I/O error occurs.
* @see AbstractOrigin#getCharSequence(Charset)
* @since 2.13.0
*/
@@ -144,10 +144,10 @@
* Gets an input stream from the origin with open options.
*
* @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.
- * @throws UnsupportedOperationException if the origin cannot be converted to an InputStream.
* @see AbstractOrigin#getInputStream(OpenOption...)
- * @throws IllegalStateException if the {@code origin} is {@code null}.
* @since 2.13.0
*/
protected InputStream getInputStream() throws IOException {
@@ -167,9 +167,9 @@
* Gets an OutputStream from the origin with open options.
*
* @return An OutputStream
- * @throws IOException if an I/O error occurs.
- * @throws UnsupportedOperationException if the origin cannot be converted to 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...)
* @since 2.13.0
*/
@@ -181,8 +181,8 @@
* Gets a Path from the origin.
*
* @return A Path
- * @throws UnsupportedOperationException if the origin cannot be converted to a Path.
* @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
* @see AbstractOrigin#getPath()
* @since 2.13.0
*/
@@ -194,9 +194,9 @@
* Gets an writer from the origin with open options.
*
* @return An writer.
- * @throws IOException if an I/O error occurs.
- * @throws UnsupportedOperationException if the origin cannot be converted to a 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...)
* @since 2.13.0
*/
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 7a6089d..816bbf3 100644
--- a/src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/AutoCloseInputStream.java
@@ -65,12 +65,17 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspect InputStream.
+ * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * </p>
+ * <p>
+ * This builder use the aspects InputStream, OpenOption[], include, and ByteOrderMark[].
* </p>
*
* @return a new instance.
- * @throws IOException if an I/O error occurs.
- * @throws IllegalArgumentException if the buffer is not large enough to hold a complete character.
+ * @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 #getInputStream()
*/
@SuppressWarnings("resource") // Caller closes
@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 3a2aed5..ad723f7 100644
--- a/src/main/java/org/apache/commons/io/input/BOMInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BOMInputStream.java
@@ -138,15 +138,16 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects InputStream, OpenOption[], include, and ByteOrderMark[].
+ * You must provide an origin that supports calling {@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 aspects InputStream, OpenOption[], include, and ByteOrderMark[].
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @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 #getInputStream()
*/
@SuppressWarnings("resource")
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 f3d7e6f..f6f4373 100644
--- a/src/main/java/org/apache/commons/io/input/BoundedInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BoundedInputStream.java
@@ -65,6 +65,18 @@
/** Flag if close should be propagated. */
private boolean propagateClose = true;
+ /**
+ * Constructs a new instance.
+ * <p>
+ * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * </p>
+ *
+ * @return a new instance.
+ * @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 #getInputStream()
+ */
@SuppressWarnings("resource")
@Override
public BoundedInputStream get() throws IOException {
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 182090d..045ab06 100644
--- a/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
@@ -25,7 +25,6 @@
import java.util.Objects;
import org.apache.commons.io.IOUtils;
-import org.apache.commons.io.build.AbstractOrigin;
import org.apache.commons.io.build.AbstractStreamBuilder;
/**
@@ -73,16 +72,16 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects Path and buffer size.
- * </p>
- * <p>
- * You must provide an origin that can be converted to a Path by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * You must provide an origin that supports calling {@link #getPath()} and {@link #getBufferSize()} on this builder, otherwise, this method throws an
+ * exception.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide a Path.
- * @see AbstractOrigin#getPath()
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
+ * @throws IOException If an I/O error occurs
+ * @see #getPath()
+ * @see #getBufferSize()
*/
@Override
public BufferedFileChannelInputStream get() throws IOException {
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 f1a2551..b3a052e 100644
--- a/src/main/java/org/apache/commons/io/input/ChecksumInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ChecksumInputStream.java
@@ -118,15 +118,13 @@
/**
* Constructs a new instance.
* <p>
- * This builder requires an input convertible by {@link #getInputStream()}.
- * </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}.
+ * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @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 #getInputStream()
*/
@SuppressWarnings("resource")
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 3d03f8c..c60af53 100644
--- a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
@@ -27,7 +27,6 @@
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
-import org.apache.commons.io.build.AbstractOrigin;
import org.apache.commons.io.build.AbstractStreamBuilder;
/**
@@ -98,16 +97,16 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects Path and buffer size.
- * </p>
- * <p>
- * You must provide an origin that can be converted to a Path by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * You must provide an origin that supports calling {@link #getPath()} and {@link #getBufferSize()} this builder, otherwise, this method throws an
+ * exception.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide a Path.
- * @see AbstractOrigin#getPath()
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
+ * @throws IOException if an I/O error occurs.
+ * @see #getPath()
+ * @see #getBufferSize()
*/
@Override
public MemoryMappedFileInputStream get() throws IOException {
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 97d7ff5..c3ffc1b 100644
--- a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
@@ -76,15 +76,14 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects InputStream, OpenOption[], and MessageDigest.
- * </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}.
+ * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @throws NullPointerException if messageDigest is null.
+ * @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 #getInputStream()
*/
@SuppressWarnings("resource")
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 d822256..a465ad7 100644
--- a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
@@ -74,15 +74,14 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects InputStream, OpenOption[], and MessageDigest.
- * </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}.
+ * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @throws NullPointerException if messageDigest is null.
+ * @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 #getInputStream()
*/
@SuppressWarnings("resource")
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 07a8a97..25e20c2 100644
--- a/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
@@ -17,6 +17,7 @@
package org.apache.commons.io.input;
+import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.RandomAccessFile;
@@ -66,8 +67,9 @@
* </p>
*
* @return a new instance.
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
* @throws IllegalStateException if both RandomAccessFile and origin are set.
- * @throws UnsupportedOperationException if the origin cannot provide a File.
+ * @throws UnsupportedOperationException if the origin cannot be converted to a {@link File}.
* @see AbstractOrigin#getFile()
*/
@SuppressWarnings("resource") // Caller closes depending on settings
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 dc4fc08..efafbb1 100644
--- a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
@@ -69,16 +69,18 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects InputStream, OpenOption[], buffer size, ExecutorService.
+ * You must provide an origin that supports calling {@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 aspects InputStream, OpenOption[], buffer size, ExecutorService.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @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 #getInputStream()
+ * @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 f805690..0e11811 100644
--- a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
+++ b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
@@ -36,7 +36,6 @@
import org.apache.commons.io.Charsets;
import org.apache.commons.io.FileSystem;
import org.apache.commons.io.StandardLineSeparator;
-import org.apache.commons.io.build.AbstractOrigin;
import org.apache.commons.io.build.AbstractStreamBuilder;
/**
@@ -77,16 +76,17 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects Path, Charset, buffer size.
- * </p>
- * <p>
- * You must provide an origin that can be converted to a Path by this builder, otherwise, this call will throw an
- * {@link UnsupportedOperationException}.
+ * You must provide an origin that supports calling {@link #getInputStream()}, {@link #getBufferSize()}, and {@link #getCharset()} on this builder,
+ * otherwise, this method throws an exception.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide a Path.
- * @see AbstractOrigin#getPath()
+ * @throws IllegalStateException if the {@code origin} is {@code null}.
+ * @throws UnsupportedOperationException if the origin cannot be converted to a {@link Path}.
+ * @throws IOException if an I/O error occurs.
+ * @see #getPath()
+ * @see #getBufferSize()
+ * @see #getCharset()
*/
@Override
public ReversedLinesFileReader get() throws IOException {
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 b6b464e..ec5c37c 100644
--- a/src/main/java/org/apache/commons/io/input/ThrottledInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ThrottledInputStream.java
@@ -67,6 +67,18 @@
*/
private long maxBytesPerSecond = Long.MAX_VALUE;
+ /**
+ * Constructs a new instance.
+ * <p>
+ * You must provide an origin that supports calling {@link #getInputStream()} on this builder, otherwise, this method throws an exception.
+ * </p>
+ *
+ * @return a new instance.
+ * @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 #getInputStream()
+ */
@SuppressWarnings("resource")
@Override
public ThrottledInputStream get() throws IOException {
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 f3e0dc0..3cf17d3 100644
--- a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
@@ -80,16 +80,19 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspects InputStream, OpenOption[] and buffer size.
+ * You must provide an origin that supports calling {@link #getInputStream()} and {@link #getBufferSize()} 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 aspects InputStream, OpenOption[] and buffer size.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @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 #getInputStream()
+ * @see #getBufferSize()
*/
@SuppressWarnings("resource") // Caller closes.
@Override
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 d5ae16a..f2f0294 100644
--- a/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
@@ -67,15 +67,16 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspect InputStream and OpenOption[].
+ * You must provide an origin that supports calling {@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 aspects InputStream, OpenOption[] and buffer size.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+ * @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 #getInputStream()
*/
@SuppressWarnings("resource") // Caller closes.
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 e206789..b470779 100644
--- a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
+++ b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
@@ -119,17 +119,17 @@
/**
* Constructs a new instance.
* <p>
- * This builder use the aspect InputStream, OpenOption[], httpContentType, lenient, and defaultEncoding.
+ * You must provide an origin that supports calling {@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 aspect InputStream, OpenOption[], httpContentType, lenient, and defaultEncoding.
* </p>
*
* @return a new instance.
- * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
- * @throws IOException thrown if there is a problem reading the stream.
- * @throws XmlStreamReaderException thrown if the charset encoding could not be determined according to the specification.
+ * @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.
+ * @throws XmlStreamReaderException thrown if the Charset encoding could not be determined according to the specification.
* @see #getInputStream()
*/
@SuppressWarnings("resource")
