Merge remote-tracking branch 'upstream/master'

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");
         }