[IO-883] ByteArraySeekableByteChannel should optionally configure a read-only channel (#834)

* [IO-856] Try test on all OSs for GitHub CI

* [IO-883] ByteArraySeekableByteChannel should optionally configure a
read-only channel

- AbstractStreamBuilder.setOpenOptions(OpenOption...) now makes a
defensive copy of its input array.
- Add ByteArraySeekableByteChannel.Builder and builder().
- Add AbstractStreamBuilder.getByteArray().

Author: garydgregory

src/changes/changes.xml

@@ -63,14 +63,17 @@ The <action> type attribute can be add,update,fix,remove.
       <action type="fix" dev="ggregory" due-to="Martin Wiesner">Fix typos in Javadoc of FileUtils and related test classes #833.</action>
       <action type="fix" dev="ggregory" due-to="Daniel Vega, Gary Gregory" issue="IO-887">WriterOutputStream from a builder fails on malformed or unmappable input bytes.</action>
       <action type="fix" dev="ggregory" due-to="Gary Gregory">BoundedReader now extends ProxyReader.</action>
+      <action type="fix" dev="ggregory" due-to="Gary Gregory">AbstractStreamBuilder.setOpenOptions(OpenOption...) now makes a defensive copy of its input array.</action>
       <action type="fix" dev="ggregory" due-to="Peter De Maeyer, Gary Gregory" issue="IO-885">Path visits follow links #832.</action>
       <!-- ADD -->
       <action type="add" dev="ggregory" due-to="Gary Gregory, Piotr P. Karwasz">Add and use IOUtils.closeQuietlySuppress(Closeable, Throwable) #818.</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add ProxyWriter.setReference(Writer).</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add ProxyWriter.unwrap().</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add ProxyReader.setReference(Reader).</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add ProxyReader.unrwap().</action>
-      <action type="add" dev="ggregory" due-to="Gary Gregory">Make ProxyOutputStream.unrwap() public.</action>
+      <action type="add" dev="ggregory" due-to="Konrad Windszus, Gary Gregory, Makarand Hinge" issue="IO-883">ByteArraySeekableByteChannel should optionally configure a read-only channel.</action>
+      <action type="add" dev="ggregory" due-to="Gary Gregory" issue="IO-883">Add ByteArraySeekableByteChannel.Builder and builder().</action>
+      <action type="add" dev="ggregory" due-to="Gary Gregory" issue="IO-883">Add AbstractStreamBuilder.getByteArray().</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory"             due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 91 to 97 #816.</action>
       <action type="update" dev="ggregory"             due-to="Gary Gregory, Dependabot">Bump commons-codec:commons-codec from 1.19.0 to 1.21.0 #812.</action>

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

@@ -122,6 +122,20 @@ public int getBufferSizeDefault() {
         return bufferSizeDefault;
     }
 
+    /**
+     * Gets a byte array from the origin.
+     *
+     * @return A byte array.
+     * @throws IllegalStateException         if the {@code origin} is {@code null}.
+     * @throws UnsupportedOperationException if the origin cannot be converted to a byte array.
+     * @throws IOException                   if an I/O error occurs.
+     * @see AbstractOrigin#getByteArray()
+     * @since 2.22.0
+     */
+    public byte[] getByteArray() throws IOException {
+        return checkOrigin().getByteArray();
+    }
+
     /**
      * Gets a Channel from the origin with OpenOption[].
      *
@@ -202,7 +216,7 @@ public InputStream getInputStream() throws IOException {
     /**
      * Gets the OpenOption array.
      *
-     * @return the OpenOption array.
+     * @return the OpenOption array, this is not a defensive copy, modify at your own risk.
      */
     public OpenOption[] getOpenOptions() {
         return openOptions;
@@ -388,23 +402,23 @@ protected B setCharsetDefault(final Charset defaultCharset) {
     }
 
     /**
-     * Sets the OpenOption[].
+     * Sets the OpenOption array.
      * <p>
      * Normally used with InputStream, OutputStream, and Writer.
      * </p>
      * <p>
      * Subclasses may ignore this setting.
      * </p>
      *
-     * @param openOptions the OpenOption[] name, null resets to the default.
+     * @param openOptions the OpenOption[] name, null resets to the default, a defensive copy is made.
      * @return {@code this} instance.
      * @since 2.13.0
      * @see #setInputStream(InputStream)
      * @see #setOutputStream(OutputStream)
      * @see #setWriter(Writer)
      */
     public B setOpenOptions(final OpenOption... openOptions) {
-        this.openOptions = openOptions != null ? openOptions : DEFAULT_OPEN_OPTIONS;
+        this.openOptions = openOptions != null ? openOptions.clone() : DEFAULT_OPEN_OPTIONS;
         return asThis();
     }
 

src/main/java/org/apache/commons/io/channels/ByteArraySeekableByteChannel.java

@@ -24,12 +24,16 @@
 import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.nio.channels.ClosedChannelException;
+import java.nio.channels.NonWritableChannelException;
 import java.nio.channels.SeekableByteChannel;
+import java.nio.file.OpenOption;
+import java.nio.file.StandardOpenOption;
 import java.util.Arrays;
 import java.util.Objects;
 import java.util.concurrent.locks.ReentrantLock;
 
 import org.apache.commons.io.IOUtils;
+import org.apache.commons.io.build.AbstractStreamBuilder;
 
 /**
  * A {@link SeekableByteChannel} implementation backed by a byte array.
@@ -38,13 +42,65 @@
  * and it's not possible to {@link #position(long) set the position} or {@link #truncate(long) truncate} to a value bigger than that. The raw internal buffer is
  * accessed via {@link ByteArraySeekableByteChannel#array()}.
  * </p>
+ * <p>
+ * Building a read-only channel from an existing byte array is supported with:
+ * </p>
+ * <pre>{@code
+ * try (ByteArraySeekableByteChannel channel = ByteArraySeekableByteChannel.builder()
+ *               .setByteArray(...)
+ *               .setOpenOptions(StandardOpenOption.READ)
+ *               .get()) {
+ *               // read from channel
+ * }
+ * }</pre>
  *
  * @since 2.21.0
  */
 public class ByteArraySeekableByteChannel implements SeekableByteChannel {
 
+    /**
+     * Builds for {@link ByteArraySeekableByteChannel}.
+     * <p>
+     * Building a read-only channel from an existing byte array is supported with:
+     * </p>
+     * <pre>{@code
+     * try (ByteArraySeekableByteChannel channel = ByteArraySeekableByteChannel.builder()
+     *               .setByteArray(...)
+     *               .setOpenOptions(StandardOpenOption.READ)
+     *               .get()) {
+     *               // read from channel
+     * }
+     * }</pre>
+     *
+     * @since 2.22.0
+     */
+    public static class Builder extends AbstractStreamBuilder<ByteArraySeekableByteChannel, Builder> {
+
+        /**
+         * Constructs a new builder for {@link ByteArraySeekableByteChannel}.
+         */
+        public Builder() {
+            setByteArray(IOUtils.EMPTY_BYTE_ARRAY);
+        }
+
+        @Override
+        public ByteArraySeekableByteChannel get() throws IOException {
+            return new ByteArraySeekableByteChannel(this);
+        }
+    }
+
     private static final int RESIZE_LIMIT = Integer.MAX_VALUE >> 1;
 
+    /**
+     * Constructs a new builder for {@link ByteArraySeekableByteChannel}.
+     *
+     * @return a new builder for {@link ByteArraySeekableByteChannel}.
+     * @since 2.22.0
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
     /**
      * Constructs a new channel backed directly by the given byte array.
      *
@@ -65,11 +121,11 @@ public static ByteArraySeekableByteChannel wrap(final byte[] bytes) {
         Objects.requireNonNull(bytes, "bytes");
         return new ByteArraySeekableByteChannel(bytes);
     }
-
     private byte[] data;
     private volatile boolean closed;
     private long position;
     private int size;
+    private final boolean isWritable;
     private final ReentrantLock lock = new ReentrantLock();
 
     /**
@@ -84,9 +140,19 @@ public ByteArraySeekableByteChannel() {
         this(IOUtils.DEFAULT_BUFFER_SIZE);
     }
 
+    private ByteArraySeekableByteChannel(final Builder builder) throws IOException {
+        this.data = builder.getByteArray();
+        this.size = data.length;
+        final OpenOption[] openOptions = builder.getOpenOptions();
+        Arrays.sort(openOptions);
+        this.isWritable = openOptions.length == 0 || Arrays.binarySearch(openOptions, StandardOpenOption.WRITE) >= 0
+                || Arrays.binarySearch(openOptions, StandardOpenOption.APPEND) >= 0;
+    }
+
     private ByteArraySeekableByteChannel(final byte[] data) {
         this.data = data;
         this.size = data.length;
+        this.isWritable = true;
     }
 
     /**
@@ -103,6 +169,7 @@ public ByteArraySeekableByteChannel(final int size) {
             throw new IllegalArgumentException("Size must be non-negative");
         }
         this.data = new byte[size];
+        this.isWritable = true;
     }
 
     /**
@@ -129,6 +196,12 @@ private void checkRange(final long newSize, final String method) {
         }
     }
 
+    private void checkWritable() {
+        if (!isWritable) {
+            throw new NonWritableChannelException();
+        }
+    }
+
     @Override
     public void close() {
         closed = true;
@@ -237,6 +310,7 @@ public byte[] toByteArray() {
     @Override
     public SeekableByteChannel truncate(final long newSize) throws ClosedChannelException {
         checkOpen();
+        checkWritable();
         checkRange(newSize, "truncate()");
         lock.lock();
         try {
@@ -255,6 +329,8 @@ public SeekableByteChannel truncate(final long newSize) throws ClosedChannelExce
     @Override
     public int write(final ByteBuffer b) throws IOException {
         checkOpen();
+        checkWritable();
+        //
         if (position > Integer.MAX_VALUE) {
             throw new IOException("position > Integer.MAX_VALUE");
         }

src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java

@@ -92,10 +92,6 @@ public Builder() {
             // empty
         }
 
-        private byte[] checkOriginByteArray() throws IOException {
-            return checkOrigin().getByteArray();
-        }
-
         /**
          * Builds a new {@link UnsynchronizedByteArrayInputStream}.
          * <p>
@@ -207,7 +203,7 @@ private static int requireNonNegative(final int value, final String name) {
     private int markedOffset;
 
     private UnsynchronizedByteArrayInputStream(final Builder builder) throws IOException {
-        this(builder.checkOriginByteArray(), builder.offset, builder.length);
+        this(builder.getByteArray(), builder.offset, builder.length);
     }
 
     /**

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

@@ -17,6 +17,7 @@
 
 package org.apache.commons.io.build;
 
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -31,17 +32,21 @@
 import java.nio.channels.ReadableByteChannel;
 import java.nio.channels.SeekableByteChannel;
 import java.nio.file.Files;
+import java.nio.file.OpenOption;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.nio.file.StandardOpenOption;
 import java.util.Arrays;
 import java.util.Objects;
 import java.util.stream.Stream;
 
 import org.apache.commons.io.function.IOConsumer;
 import org.apache.commons.lang3.ArrayUtils;
+import org.apache.commons.lang3.RandomUtils;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.MethodSource;
+import org.junit.jupiter.params.provider.ValueSource;
 
 /**
  * Tests {@link AbstractStreamBuilder}.
@@ -118,16 +123,71 @@ void testBufferSizeChecker() {
         assertResult(builder().setBufferSizeMax(2).setBufferSizeChecker(i -> 100).setBufferSize(3).get(), 100);
     }
 
+    /**
+     * Tests various ways to obtain a byte array.
+     *
+     * @param configurer configures a builder.
+     */
+    @ParameterizedTest
+    @MethodSource("fileBasedConfigurers")
+    void testGetByteArray(final IOConsumer<Builder> configurer) throws Exception {
+        final Builder builder = builder();
+        configurer.accept(builder);
+        assertNotNull(builder.getByteArray());
+    }
+
     /**
      * Tests various ways to obtain a {@link InputStream}.
      *
-     * @param configurer Lambda to configure the builder.
+     * @param configurer configures a builder.
      */
     @ParameterizedTest
     @MethodSource("fileBasedConfigurers")
     void testGetInputStream(final IOConsumer<Builder> configurer) throws Exception {
         final Builder builder = builder();
         configurer.accept(builder);
-        assertNotNull(builder.getInputStream());
+        try (InputStream inputStream = builder.getInputStream()) {
+            assertNotNull(inputStream);
+        }
+    }
+
+    @ParameterizedTest
+    @ValueSource(ints = { 0, 1, 2, 4 })
+    void testSetByteArrayGetByteArray(final int size) throws Exception {
+        final Builder builder = builder();
+        final byte[] randomBytes = RandomUtils.insecure().randomBytes(size);
+        builder.setByteArray(randomBytes);
+        assertArrayEquals(randomBytes, builder.getByteArray());
+    }
+
+    @Test
+    void testSetFileGetByteArray() throws Exception {
+        final Builder builder = builder();
+        final Path path = Paths.get(AbstractOriginTest.FILE_NAME_RO);
+        builder.setFile(path.toFile());
+        assertArrayEquals(Files.readAllBytes(path), builder.getByteArray());
+    }
+
+    @Test
+    void testSetOpenOptions() {
+        final Builder builder = builder();
+        assertEquals(0, builder.setOpenOptions().getOpenOptions().length);
+        assertEquals(0, builder.setOpenOptions((OpenOption[]) null).getOpenOptions().length);
+        assertEquals(1, builder.setOpenOptions(StandardOpenOption.READ).getOpenOptions().length);
+        final OpenOption[] options = { StandardOpenOption.READ, StandardOpenOption.WRITE };
+        assertArrayEquals(options, builder.setOpenOptions(options).getOpenOptions());
+        // Check that the builder makes a defensive copy of the array.
+        options[0] = null;
+        options[1] = null;
+        assertEquals(StandardOpenOption.READ, builder.getOpenOptions()[0]);
+        assertEquals(StandardOpenOption.WRITE, builder.getOpenOptions()[1]);
+    }
+
+    @Test
+    void testSetPathGetByteArray() throws Exception {
+        final Builder builder = builder();
+        final Path path = Paths.get(AbstractOriginTest.FILE_NAME_RO);
+        builder.setPath(path);
+        assertArrayEquals(Files.readAllBytes(path), builder.getByteArray());
     }
 }