Add ChunkedOutputStream.Builder and refactor

garydgregory · garydgregory · commit 8acfd4c594eb · 2023-05-20T12:08:29.000-04:00
- Javadoc
- In builders, a negative or zero size buffer should reset the buffer
size to it default buffer size value
- In builders, AbstractOriginSupplier.checkOrigin() now throws
IllegalStateException instead of NullPointerException
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -55,10 +55,16 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="fix" due-to="Gary Gregory">
         ByteArrayOrigin should be able convert a byte[] to a ByteArrayInputStream.
       </action>
+      <action dev="ggregory" type="fix" due-to="Gary Gregory">
+        AbstractOriginSupplier.checkOrigin() now throws IllegalStateException instead of NullPointerException.
+      </action>
       <!-- ADD -->
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add CharSequenceInputStream.Builder.
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add ChunkedOutputStream.Builder.
+      </action>
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add AbstractStreamBuilder.setOpenOptions(OpenOption...).
       </action>
diff --git a/src/main/java/org/apache/commons/io/build/AbstractOriginSupplier.java b/src/main/java/org/apache/commons/io/build/AbstractOriginSupplier.java
@@ -166,10 +166,13 @@ protected static WriterOrigin newWriterOrigin(final Writer origin) {
      * Checks whether the origin is null.
      *
      * @return the origin.
-     * @throws NullPointerException if the {@code origin} is {@code null}
+     * @throws IllegalStateException if the {@code origin} is {@code null}.
      */
     protected AbstractOrigin<?, ?> checkOrigin() {
-        return Objects.requireNonNull(origin, "origin");
+        if (origin == null) {
+            throw new IllegalStateException("origin == null");
+        }
+        return origin;
     }
 
     /**
diff --git a/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java b/src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java
@@ -23,6 +23,7 @@
 import java.io.Writer;
 import java.nio.charset.Charset;
 import java.nio.file.OpenOption;
+import java.nio.file.Path;
 
 import org.apache.commons.io.Charsets;
 import org.apache.commons.io.IOUtils;
@@ -85,11 +86,12 @@ protected int getBufferSizeDefault() {
      * @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}.
      * @see AbstractOrigin#getCharSequence(Charset)
      * @since 2.13.0
      */
     protected CharSequence getCharSequence() throws IOException {
-        return getOrigin().getCharSequence(getCharset());
+        return checkOrigin().getCharSequence(getCharset());
     }
 
     /**
@@ -117,27 +119,42 @@ protected Charset getCharsetDefault() {
      * @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 {
-        return getOrigin().getInputStream(getOpenOptions());
+        return checkOrigin().getInputStream(getOpenOptions());
     }
 
     protected OpenOption[] getOpenOptions() {
         return openOptions;
     }
 
     /**
-     * Gets an output stream from the origin with open options.
+     * Gets an OutputStream from the origin with open options.
      *
-     * @return An input stream
+     * @return An OutputStream
      * @throws IOException                   if an I/O error occurs.
      * @throws UnsupportedOperationException if the origin cannot be converted to an OututStream.
+     * @throws IllegalStateException if the {@code origin} is {@code null}.
      * @see AbstractOrigin#getOutputStream(OpenOption...)
      * @since 2.13.0
      */
     protected OutputStream getOutputStream() throws IOException {
-        return getOrigin().getOutputStream(getOpenOptions());
+        return checkOrigin().getOutputStream(getOpenOptions());
+    }
+
+    /**
+     * 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}.
+     * @see AbstractOrigin#getPath()
+     * @since 2.13.0
+     */
+    protected Path getPath() {
+        return checkOrigin().getPath();
     }
 
     /**
@@ -146,15 +163,16 @@ protected OutputStream getOutputStream() throws IOException {
      * @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}.
      * @see AbstractOrigin#getOutputStream(OpenOption...)
      * @since 2.13.0
      */
     protected Writer getWriter() throws IOException {
-        return getOrigin().getWriter(getCharset(), getOpenOptions());
+        return checkOrigin().getWriter(getCharset(), getOpenOptions());
     }
 
     /**
-     * Sets the buffer size.
+     * Sets the buffer size. Invalid input (bufferSize &lt;= 0) resets the value to its default.
      * <p>
      * Subclasses may ignore this setting.
      * </p>
@@ -163,7 +181,7 @@ protected Writer getWriter() throws IOException {
      * @return this.
      */
     public B setBufferSize(final int bufferSize) {
-        this.bufferSize = bufferSize >= 0 ? bufferSize : bufferSizeDefault;
+        this.bufferSize = bufferSize > 0 ? bufferSize : bufferSizeDefault;
         return asThis();
     }
 
diff --git a/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java b/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
@@ -86,7 +86,7 @@ public static class Builder extends AbstractStreamBuilder<BufferedFileChannelInp
          */
         @Override
         public BufferedFileChannelInputStream get() throws IOException {
-            return new BufferedFileChannelInputStream(getOrigin().getPath(), getBufferSize());
+            return new BufferedFileChannelInputStream(getPath(), getBufferSize());
         }
 
     }
diff --git a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
@@ -108,7 +108,7 @@ public Builder() {
          */
         @Override
         public MemoryMappedFileInputStream get() throws IOException {
-            return new MemoryMappedFileInputStream(getOrigin().getPath(), getBufferSize());
+            return new MemoryMappedFileInputStream(getPath(), getBufferSize());
         }
     }
 
diff --git a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
@@ -114,12 +114,13 @@ public static class Builder extends AbstractStreamBuilder<ReaderInputStream, Bui
          *
          * @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)
          */
         @SuppressWarnings("resource")
         @Override
         public ReaderInputStream get() throws IOException {
-            return new ReaderInputStream(getOrigin().getReader(getCharset()), charsetEncoder, getBufferSize());
+            return new ReaderInputStream(checkOrigin().getReader(getCharset()), charsetEncoder, getBufferSize());
         }
 
         @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
@@ -87,7 +87,7 @@ public Builder() {
          */
         @Override
         public ReversedLinesFileReader get() throws IOException {
-            return new ReversedLinesFileReader(getOrigin().getPath(), getBufferSize(), getCharset());
+            return new ReversedLinesFileReader(getPath(), getBufferSize(), getCharset());
         }
 
     }
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java b/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
@@ -78,12 +78,13 @@ public static class Builder extends AbstractStreamBuilder<UncheckedBufferedReade
          *
          * @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)
          */
         @Override
         public UncheckedBufferedReader get() {
             // This an unchecked class, so this method is as well.
-            return Uncheck.get(() -> new UncheckedBufferedReader(getOrigin().getReader(getCharset()), getBufferSize()));
+            return Uncheck.get(() -> new UncheckedBufferedReader(checkOrigin().getReader(getCharset()), getBufferSize()));
         }
 
     }
diff --git a/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java b/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
@@ -74,12 +74,13 @@ public static class Builder extends AbstractStreamBuilder<UncheckedFilterReader,
          *
          * @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)
          */
         @Override
         public UncheckedFilterReader get() {
             // This an unchecked class, so this method is as well.
-            return Uncheck.get(() -> new UncheckedFilterReader(getOrigin().getReader(getCharset())));
+            return Uncheck.get(() -> new UncheckedFilterReader(checkOrigin().getReader(getCharset())));
         }
 
     }
diff --git a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
@@ -92,11 +92,12 @@ public static class Builder extends AbstractStreamBuilder<UnsynchronizedByteArra
          *
          * @return a new instance.
          * @throws UnsupportedOperationException if the origin cannot provide a byte[].
+         * @throws IllegalStateException if the {@code origin} is {@code null}.
          * @see AbstractOrigin#getByteArray()
          */
         @Override
         public UnsynchronizedByteArrayInputStream get() throws IOException {
-            return new UnsynchronizedByteArrayInputStream(getOrigin().getByteArray(), offset, length);
+            return new UnsynchronizedByteArrayInputStream(checkOrigin().getByteArray(), offset, length);
         }
 
         @Override
diff --git a/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java b/src/main/java/org/apache/commons/io/output/ChunkedOutputStream.java
@@ -21,16 +21,73 @@
 import java.io.OutputStream;
 
 import org.apache.commons.io.IOUtils;
+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.
+ * 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.
  *
  * @since 2.5
  */
 public class ChunkedOutputStream extends FilterOutputStream {
 
+    // @formatter:off
+    /**
+     * Builds a new {@link UnsynchronizedByteArrayOutputStream} instance.
+     * <p>
+     * Using File IO:
+     * </p>
+     *
+     * <pre>{@code
+     * UnsynchronizedByteArrayOutputStream s = UnsynchronizedByteArrayOutputStream.builder()
+     *   .setBufferSize(8192)
+     *   .get();
+     * }
+     * </pre>
+     * <p>
+     * Using NIO Path:
+     * </p>
+     *
+     * <pre>{@code
+     * UnsynchronizedByteArrayOutputStream s = UnsynchronizedByteArrayOutputStream.builder()
+     *   .setBufferSize(8192)
+     *   .get();
+     * }
+     * </pre>
+     *
+     * @since 2.13.0
+     */
+    // @formatter:on
+    public static class Builder extends AbstractStreamBuilder<ChunkedOutputStream, Builder> {
+
+        /**
+         * Constructs a new instance.
+         * <p>
+         * This builder use the aspects OutputStream and buffer size (chunk size).
+         * </p>
+         *
+         * @return a new instance.
+         * @throws IOException                   if an I/O error occurs.
+         * @throws UnsupportedOperationException if the origin cannot be converted to an OututStream.
+         * @see #getOutputStream()
+         */
+        @Override
+        public ChunkedOutputStream get() throws IOException {
+            return new ChunkedOutputStream(getOutputStream(), getBufferSize());
+        }
+
+    }
+
+    /**
+     * Constructs a new {@link Builder}.
+     *
+     * @return a new {@link Builder}.
+     * @since 2.13.0
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * The maximum chunk size to us when writing data arrays
      */
@@ -40,32 +97,40 @@ public class ChunkedOutputStream extends FilterOutputStream {
      * Creates a new stream that uses a chunk size of {@link IOUtils#DEFAULT_BUFFER_SIZE}.
      *
      * @param stream the stream to wrap
+     * @deprecated Use {@link #builder()} and {@link Builder#get()}
      */
+    @Deprecated
     public ChunkedOutputStream(final OutputStream stream) {
         this(stream, IOUtils.DEFAULT_BUFFER_SIZE);
     }
 
     /**
      * Creates a new stream that uses the specified chunk size.
      *
-     * @param stream the stream to wrap
+     * @param stream    the stream to wrap
      * @param chunkSize the chunk size to use; must be a positive number.
      * @throws IllegalArgumentException if the chunk size is &lt;= 0
+     * @deprecated Use {@link #builder()} and {@link Builder#get()}
      */
+    @Deprecated
     public ChunkedOutputStream(final OutputStream stream, final int chunkSize) {
-       super(stream);
-       if (chunkSize <= 0) {
-           throw new IllegalArgumentException();
-       }
-       this.chunkSize = chunkSize;
+        super(stream);
+        if (chunkSize <= 0) {
+            throw new IllegalArgumentException("chunkSize <= 0");
+        }
+        this.chunkSize = chunkSize;
+    }
+
+    int getChunkSize() {
+        return chunkSize;
     }
 
     /**
      * Writes the data buffer in chunks to the underlying stream
      *
-     * @param data the data to write
+     * @param data      the data to write
      * @param srcOffset the offset
-     * @param length the length of data to write
+     * @param length    the length of data to write
      *
      * @throws IOException if an I/O error occurs.
      */
diff --git a/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java b/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
@@ -94,6 +94,7 @@ public static class Builder extends AbstractStreamBuilder<FileWriterWithEncoding
          *
          * @return a new instance.
          * @throws UnsupportedOperationException if the origin cannot provide a File.
+         * @throws IllegalStateException if the {@code origin} is {@code null}.
          * @see AbstractOrigin#getFile()
          */
         @SuppressWarnings("resource")
@@ -103,7 +104,7 @@ public FileWriterWithEncoding get() throws IOException {
                 throw new IllegalStateException(String.format("Mismatched Charset(%s) and CharsetEncoder(%s)", getCharset(), charsetEncoder.charset()));
             }
             final Object encoder = charsetEncoder != null ? charsetEncoder : getCharset();
-            return new FileWriterWithEncoding(FileWriterWithEncoding.initWriter(getOrigin().getFile(), encoder, append));
+            return new FileWriterWithEncoding(FileWriterWithEncoding.initWriter(checkOrigin().getFile(), encoder, append));
         }
 
         /**
diff --git a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
@@ -87,11 +87,12 @@ public Builder() {
          *
          * @return a new instance.
          * @throws UnsupportedOperationException if the origin cannot provide a File.
+         * @throws IllegalStateException if the {@code origin} is {@code null}.
          * @see AbstractOrigin#getFile()
          */
         @Override
         public LockableFileWriter get() throws IOException {
-            return new LockableFileWriter(getOrigin().getFile(), getCharset(), append, lockDirectory.getFile().toString());
+            return new LockableFileWriter(checkOrigin().getFile(), getCharset(), append, lockDirectory.getFile().toString());
         }
 
         /**
diff --git a/src/test/java/org/apache/commons/io/output/ChunkedOutputStreamTest.java b/src/test/java/org/apache/commons/io/output/ChunkedOutputStreamTest.java
diff --git a/src/test/java/org/apache/commons/io/output/LockableFileWriterTest.java b/src/test/java/org/apache/commons/io/output/LockableFileWriterTest.java

Original file line number	Diff line number	Diff line change
`@@ -86,7 +86,7 @@ public static class Builder extends AbstractStreamBuilder<BufferedFileChannelInp`
`86`	`86`	`*/`
`87`	`87`	`@Override`
`88`	`88`	`public BufferedFileChannelInputStream get() throws IOException {`
`89`		`- return new BufferedFileChannelInputStream(getOrigin().getPath(), getBufferSize());`
	`89`	`+ return new BufferedFileChannelInputStream(getPath(), getBufferSize());`
`90`	`90`	`}`
`91`	`91`
`92`	`92`	`}`
Original file line number	Diff line number	Diff line change
`@@ -108,7 +108,7 @@ public Builder() {`
`108`	`108`	`*/`
`109`	`109`	`@Override`
`110`	`110`	`public MemoryMappedFileInputStream get() throws IOException {`
`111`		`- return new MemoryMappedFileInputStream(getOrigin().getPath(), getBufferSize());`
	`111`	`+ return new MemoryMappedFileInputStream(getPath(), getBufferSize());`
`112`	`112`	`}`
`113`	`113`	`}`
`114`	`114`
Original file line number	Diff line number	Diff line change
`@@ -114,12 +114,13 @@ public static class Builder extends AbstractStreamBuilder<ReaderInputStream, Bui`
`114`	`114`	`*`
`115`	`115`	`* @return a new instance.`
`116`	`116`	`* @throws UnsupportedOperationException if the origin cannot provide a Reader.`
	`117`	`+ * @throws IllegalStateException if the {@code origin} is {@code null}.`
`117`	`118`	`* @see AbstractOrigin#getReader(Charset)`
`118`	`119`	`*/`
`119`	`120`	`@SuppressWarnings("resource")`
`120`	`121`	`@Override`
`121`	`122`	`public ReaderInputStream get() throws IOException {`
`122`		`- return new ReaderInputStream(getOrigin().getReader(getCharset()), charsetEncoder, getBufferSize());`
	`123`	`+ return new ReaderInputStream(checkOrigin().getReader(getCharset()), charsetEncoder, getBufferSize());`
`123`	`124`	`}`
`124`	`125`
`125`	`126`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@ public Builder() {`
`87`	`87`	`*/`
`88`	`88`	`@Override`
`89`	`89`	`public ReversedLinesFileReader get() throws IOException {`
`90`		`- return new ReversedLinesFileReader(getOrigin().getPath(), getBufferSize(), getCharset());`
	`90`	`+ return new ReversedLinesFileReader(getPath(), getBufferSize(), getCharset());`
`91`	`91`	`}`
`92`	`92`
`93`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -78,12 +78,13 @@ public static class Builder extends AbstractStreamBuilder<UncheckedBufferedReade`
`78`	`78`	`*`
`79`	`79`	`* @return a new instance.`
`80`	`80`	`* @throws UnsupportedOperationException if the origin cannot provide a Reader.`
	`81`	`+ * @throws IllegalStateException if the {@code origin} is {@code null}.`
`81`	`82`	`* @see AbstractOrigin#getReader(Charset)`
`82`	`83`	`*/`
`83`	`84`	`@Override`
`84`	`85`	`public UncheckedBufferedReader get() {`
`85`	`86`	`// This an unchecked class, so this method is as well.`
`86`		`- return Uncheck.get(() -> new UncheckedBufferedReader(getOrigin().getReader(getCharset()), getBufferSize()));`
	`87`	`+ return Uncheck.get(() -> new UncheckedBufferedReader(checkOrigin().getReader(getCharset()), getBufferSize()));`
`87`	`88`	`}`
`88`	`89`
`89`	`90`	`}`
Original file line number	Diff line number	Diff line change
`@@ -74,12 +74,13 @@ public static class Builder extends AbstractStreamBuilder<UncheckedFilterReader,`
`74`	`74`	`*`
`75`	`75`	`* @return a new instance.`
`76`	`76`	`* @throws UnsupportedOperationException if the origin cannot provide a Reader.`
	`77`	`+ * @throws IllegalStateException if the {@code origin} is {@code null}.`
`77`	`78`	`* @see AbstractOrigin#getReader(Charset)`
`78`	`79`	`*/`
`79`	`80`	`@Override`
`80`	`81`	`public UncheckedFilterReader get() {`
`81`	`82`	`// This an unchecked class, so this method is as well.`
`82`		`- return Uncheck.get(() -> new UncheckedFilterReader(getOrigin().getReader(getCharset())));`
	`83`	`+ return Uncheck.get(() -> new UncheckedFilterReader(checkOrigin().getReader(getCharset())));`
`83`	`84`	`}`
`84`	`85`
`85`	`86`	`}`
Original file line number	Diff line number	Diff line change
`@@ -92,11 +92,12 @@ public static class Builder extends AbstractStreamBuilder<UnsynchronizedByteArra`
`92`	`92`	`*`
`93`	`93`	`* @return a new instance.`
`94`	`94`	`* @throws UnsupportedOperationException if the origin cannot provide a byte[].`
	`95`	`+ * @throws IllegalStateException if the {@code origin} is {@code null}.`
`95`	`96`	`* @see AbstractOrigin#getByteArray()`
`96`	`97`	`*/`
`97`	`98`	`@Override`
`98`	`99`	`public UnsynchronizedByteArrayInputStream get() throws IOException {`
`99`		`- return new UnsynchronizedByteArrayInputStream(getOrigin().getByteArray(), offset, length);`
	`100`	`+ return new UnsynchronizedByteArrayInputStream(checkOrigin().getByteArray(), offset, length);`
`100`	`101`	`}`
`101`	`102`
`102`	`103`	`@Override`