Add AbstractStreamBuilder.setBufferSizeMax(int).

Add IntToIntFunction
Add AbstractStreamBuilder.setBufferSizeChecker(IntToIntFunction)

Author: garydgregory

src/changes/changes.xml

@@ -107,6 +107,15 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add DeferredFileOutputStream.Builder.setDirectory(Path).
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add IntToIntFunction.
+      </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add AbstractStreamBuilder.setBufferSizeChecker(IntToIntFunction).
+      </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add AbstractStreamBuilder.setBufferSizeMax(int).
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Dependabot">
         Bump jimfs from 1.2 to 1.3.0 #465 (tests).

src/main/java/org/apache/commons/io/build/AbstractStreamBuilder.java

@@ -24,10 +24,10 @@
 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;
 import org.apache.commons.io.file.PathUtils;
+import org.apache.commons.io.function.IntToIntFunction;
 
 /**
  * Abstracts building a typed instance of {@code T}.
@@ -38,6 +38,8 @@
  */
 public abstract class AbstractStreamBuilder<T, B extends AbstractStreamBuilder<T, B>> extends AbstractOriginSupplier<T, B> {
 
+    private static final int DEFAULT_MAX_VALUE = Integer.MAX_VALUE;
+
     private static final OpenOption[] DEFAULT_OPEN_OPTIONS = PathUtils.EMPTY_OPEN_OPTION_ARRAY;
 
     /**
@@ -50,6 +52,11 @@ public abstract class AbstractStreamBuilder<T, B extends AbstractStreamBuilder<T
      */
     private int bufferSizeDefault = IOUtils.DEFAULT_BUFFER_SIZE;
 
+    /**
+     * The maximum buffer size.
+     */
+    private int bufferSizeMax = DEFAULT_MAX_VALUE;
+
     /**
      * The Charset, defaults to {@link Charset#defaultCharset()}.
      */
@@ -62,6 +69,26 @@ public abstract class AbstractStreamBuilder<T, B extends AbstractStreamBuilder<T
 
     private OpenOption[] openOptions = DEFAULT_OPEN_OPTIONS;
 
+    /**
+     * The default checking behavior for a buffer size request. Throws a {@link IllegalArgumentException} by default.
+     */
+    private final IntToIntFunction defaultSizeChecker = size -> size > bufferSizeMax ? throwIae(size, bufferSizeMax) : size;
+
+    /**
+     * The checking behavior for a buffer size request.
+     */
+    private IntToIntFunction bufferSizeChecker = defaultSizeChecker;
+
+    /**
+     * Applies the buffer size request.
+     *
+     * @param size the size request.
+     * @return the size to use, usually the input, or can throw an unchecked exception, like {@link IllegalArgumentException}.
+     */
+    private int checkBufferSize(final int size) {
+        return bufferSizeChecker.applyAsInt(size);
+    }
+
     /**
      * Gets the buffer size, defaults to {@link IOUtils#DEFAULT_BUFFER_SIZE} ({@value IOUtils#DEFAULT_BUFFER_SIZE}).
      *
@@ -86,7 +113,7 @@ 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}.
+     * @throws IllegalStateException         if the {@code origin} is {@code null}.
      * @see AbstractOrigin#getCharSequence(Charset)
      * @since 2.13.0
      */
@@ -136,7 +163,7 @@ protected OpenOption[] getOpenOptions() {
      * @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}.
+     * @throws IllegalStateException         if the {@code origin} is {@code null}.
      * @see AbstractOrigin#getOutputStream(OpenOption...)
      * @since 2.13.0
      */
@@ -149,7 +176,7 @@ protected OutputStream getOutputStream() throws IOException {
      *
      * @return A Path
      * @throws UnsupportedOperationException if the origin cannot be converted to a Path.
-     * @throws IllegalStateException if the {@code origin} is {@code null}.
+     * @throws IllegalStateException         if the {@code origin} is {@code null}.
      * @see AbstractOrigin#getPath()
      * @since 2.13.0
      */
@@ -163,7 +190,7 @@ protected Path getPath() {
      * @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 IllegalStateException         if the {@code origin} is {@code null}.
      * @see AbstractOrigin#getOutputStream(OpenOption...)
      * @since 2.13.0
      */
@@ -181,7 +208,7 @@ protected Writer getWriter() throws IOException {
      * @return this.
      */
     public B setBufferSize(final int bufferSize) {
-        this.bufferSize = bufferSize > 0 ? bufferSize : bufferSizeDefault;
+        this.bufferSize = checkBufferSize(bufferSize > 0 ? bufferSize : bufferSizeDefault);
         return asThis();
     }
 
@@ -199,6 +226,18 @@ public B setBufferSize(final Integer bufferSize) {
         return asThis();
     }
 
+    /**
+     * Sets the buffer size checker function. Throws a {@link IllegalArgumentException} by default.
+     *
+     * @param bufferSizeChecker the buffer size checker function. null resets to the default behavior.
+     * @return this
+     * @since 2.14.0
+     */
+    public B setBufferSizeChecker(final IntToIntFunction bufferSizeChecker) {
+        this.bufferSizeChecker = bufferSizeChecker != null ? bufferSizeChecker : defaultSizeChecker;
+        return asThis();
+    }
+
     /**
      * Sets the buffer size for subclasses to initialize.
      * <p>
@@ -213,6 +252,19 @@ protected B setBufferSizeDefault(final int bufferSizeDefault) {
         return asThis();
     }
 
+    /**
+     * The maximum buffer size checked by the buffer size checker. Values less or equal to 0, resets to the int max value. By default, if this value is
+     * exceeded, this methods throws an {@link IllegalArgumentException}.
+     *
+     * @param bufferSizeMax maximum buffer size checked by the buffer size checker.
+     * @return this.
+     * @since 2.14.0
+     */
+    public B setBufferSizeMax(final int bufferSizeMax) {
+        this.bufferSizeMax = bufferSizeMax > 0 ? bufferSizeMax : DEFAULT_MAX_VALUE;
+        return asThis();
+    }
+
     /**
      * Sets the Charset.
      * <p>
@@ -274,4 +326,8 @@ public B setOpenOptions(final OpenOption... openOptions) {
         this.openOptions = openOptions != null ? openOptions : DEFAULT_OPEN_OPTIONS;
         return asThis();
     }
+
+    private int throwIae(final int size, final int max) {
+        throw new IllegalArgumentException(String.format("Request %,d exceeds maximum %,d", size, max));
+    }
 }

src/main/java/org/apache/commons/io/function/IntToIntFunction.java

@@ -0,0 +1,52 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.io.function;
+
+import java.util.function.Function;
+
+/**
+ * Represents a function that accepts an int-valued argument and produces an int-valued result. This is the {@code int}-to-{@code int} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>
+ * This is a <a href="package-summary.html">functional interface</a> whose functional method is {@link #applyAsInt(int)}.
+ * </p>
+ *
+ * @see Function
+ * @since 2.14.0
+ */
+@FunctionalInterface
+public interface IntToIntFunction {
+
+    /**
+     * Returns a function that always returns its input argument.
+     *
+     * @return a function that always returns its input argument
+     */
+    static IntToIntFunction identity() {
+        return i -> i;
+    }
+
+    /**
+     * Applies this function to the given argument.
+     *
+     * @param value the function argument
+     * @return the function result
+     */
+    int applyAsInt(int value);
+}

src/test/java/org/apache/commons/io/build/AbstractStreamBuilderTest.java

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.io.build;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.Arrays;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests {@link AbstractStreamBuilder}.
+ */
+public class AbstractStreamBuilderTest {
+
+    public static class Builder extends AbstractStreamBuilder<char[], Builder> {
+
+        @Override
+        public char[] get() {
+            final char[] arr = new char[getBufferSize()];
+            Arrays.fill(arr, 'a');
+            return arr;
+        }
+
+    }
+
+    private void assertResult(final char[] arr, final int size) {
+        assertNotNull(arr);
+        assertEquals(size, arr.length);
+        for (final char c : arr) {
+            assertEquals('a', c);
+        }
+    }
+
+    protected Builder builder() {
+        return new Builder();
+    }
+
+    @Test
+    public void testBufferSizeChecker() {
+        // sanity
+        final Builder builder = builder();
+        assertResult(builder.get(), builder.getBufferSize());
+        // basic failure
+        assertThrows(IllegalArgumentException.class, () -> builder().setBufferSizeMax(2).setBufferSize(3));
+        // reset
+        assertResult(builder.setBufferSizeMax(2).setBufferSizeMax(0).setBufferSize(3).get(), 3);
+        // resize
+        assertResult(builder().setBufferSizeMax(2).setBufferSizeChecker(i -> 100).setBufferSize(3).get(), 100);
+    }
+}