Add and use RandomAccessFileMode.

Author: Gary Gregory

src/changes/changes.xml

@@ -191,20 +191,23 @@ The <action> type attribute can be add,update,fix,remove.
         Add and use FileUtils.isNewer(File, FileTime) for more precision.
       </action>
       <action dev="ggregory" type="add" due-to="Gary Gregory">
-        Add and use PathUtils.isOlder(Path, FileTime, LinkOption...)
-        Add and use PathUtils.isOlder(Path, Instant, LinkOption...)
-        Add and use PathUtils.isOlder(Path, long, LinkOption...)
-        Add and use PathUtils.isOlder(Path, Path)
+        Add and use PathUtils.isOlder(Path, FileTime, LinkOption...).
+        Add and use PathUtils.isOlder(Path, Instant, LinkOption...).
+        Add and use PathUtils.isOlder(Path, long, LinkOption...).
+        Add and use PathUtils.isOlder(Path, Path).
       </action>
       <action dev="ggregory" type="add" due-to="Gary Gregory">
-        Add and use PathUtils.sizeOf(Path)
-        Add and use PathUtils.sizeOfAsBigInteger(Path)
-        Add and use PathUtils.sizeOfDirectory(Path)
-        Add and use PathUtils.sizeOfDirectoryAsBigInteger(Path)
+        Add and use PathUtils.sizeOf(Path).
+        Add and use PathUtils.sizeOfAsBigInteger(Path).
+        Add and use PathUtils.sizeOfDirectory(Path).
+        Add and use PathUtils.sizeOfDirectoryAsBigInteger(Path).
       </action>
       <action dev="jonfreedman" type="add" due-to="Jon Freedman, Gary Gregory">
         Add Tailer.Tailable interface to allow tailing of remote files for example using jCIFS.
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add and use RandomAccessFileMode.
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Update FileEntry to use FileTime instead of long for file time stamps.

src/main/java/org/apache/commons/io/RandomAccessFileMode.java

@@ -0,0 +1,100 @@
+/*
+ * 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;
+
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.io.RandomAccessFile;
+import java.nio.file.Path;
+
+/**
+ * Modes and factory for {@link RandomAccessFile}.
+ *
+ * @since 2.12.0
+ */
+public enum RandomAccessFileMode {
+
+    /**
+     * Mode "r" opens for reading only.
+     */
+    READ_ONLY("r"),
+
+    /**
+     * Mode "rw" opens for reading and writing.
+     */
+    READ_WRITE("rw"),
+
+    /**
+     * Mode "rws" opens for reading and writing, as with "rw", and also require that every update to the file's content or
+     * metadata be written synchronously to the underlying storage device.
+     */
+    READ_WRITE_SYNC_ALL("rws"),
+
+    /**
+     * Mode "rwd" open for reading and writing, as with "rw", and also require that every update to the file's content be
+     * written synchronously to the underlying storage device.
+     */
+    READ_WRITE_SYNC_CONTENT("rwd");
+
+    private final String mode;
+
+    RandomAccessFileMode(final String mode) {
+        this.mode = mode;
+    }
+
+    /**
+     * Creates a random access file stream to read from, and optionally to write to, the file specified by the {@link File}
+     * argument.
+     *
+     * @param file the file object
+     * @return a random access file stream
+     * @throws FileNotFoundException See {@link RandomAccessFile#RandomAccessFile(File, String)}.
+     */
+    public RandomAccessFile create(final File file) throws FileNotFoundException {
+        return new RandomAccessFile(file, mode);
+    }
+
+    /**
+     * Creates a random access file stream to read from, and optionally to write to, the file specified by the {@link File}
+     * argument.
+     *
+     * @param file the file object
+     * @return a random access file stream
+     * @throws FileNotFoundException See {@link RandomAccessFile#RandomAccessFile(File, String)}.
+     */
+    public RandomAccessFile create(final Path file) throws FileNotFoundException {
+        return create(file.toFile());
+    }
+
+    /**
+     * Creates a random access file stream to read from, and optionally to write to, the file specified by the {@link File}
+     * argument.
+     *
+     * @param file the file object
+     * @return a random access file stream
+     * @throws FileNotFoundException See {@link RandomAccessFile#RandomAccessFile(File, String)}.
+     */
+    public RandomAccessFile create(final String file) throws FileNotFoundException {
+        return new RandomAccessFile(file, mode);
+    }
+
+    @Override
+    public String toString() {
+        return mode;
+    }
+
+}

src/main/java/org/apache/commons/io/filefilter/MagicNumberFileFilter.java

@@ -30,6 +30,7 @@
 import java.util.Arrays;
 
 import org.apache.commons.io.IOUtils;
+import org.apache.commons.io.RandomAccessFileMode;
 
 /**
  * <p>
@@ -259,7 +260,7 @@ public MagicNumberFileFilter(final String magicNumber, final long offset) {
     public boolean accept(final File file) {
         if (file != null && file.isFile() && file.canRead()) {
             try {
-                try (RandomAccessFile randomAccessFile = new RandomAccessFile(file, "r")) {
+                try (RandomAccessFile randomAccessFile = RandomAccessFileMode.READ_ONLY.create(file)) {
                     final byte[] fileBytes = IOUtils.byteArray(this.magicNumbers.length);
                     randomAccessFile.seek(byteOffset);
                     final int read = randomAccessFile.read(fileBytes);

src/test/java/org/apache/commons/io/FileCleaningTrackerTestCase.java

@@ -53,7 +53,7 @@ public class FileCleaningTrackerTestCase {
     private FileCleaningTracker theInstance;
 
     RandomAccessFile createRandomAccessFile() throws FileNotFoundException {
-        return new RandomAccessFile(testFile, "rw");
+        return RandomAccessFileMode.READ_WRITE.create(testFile);
     }
 
     protected FileCleaningTracker newInstance() {

src/test/java/org/apache/commons/io/input/RandomAccessFileInputStreamTest.java

@@ -28,6 +28,7 @@
 import java.io.RandomAccessFile;
 import java.nio.charset.StandardCharsets;
 
+import org.apache.commons.io.RandomAccessFileMode;
 import org.junit.jupiter.api.Test;
 
 public class RandomAccessFileInputStreamTest {
@@ -36,7 +37,7 @@ public class RandomAccessFileInputStreamTest {
     private static final int DATA_FILE_LEN = 1430;
 
     private RandomAccessFile createRandomAccessFile() throws FileNotFoundException {
-        return new RandomAccessFile(DATA_FILE, "r");
+        return RandomAccessFileMode.READ_ONLY.create(DATA_FILE);
     }
 
     @Test

src/test/java/org/apache/commons/io/input/TailerTest.java

@@ -47,6 +47,7 @@
 
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;
+import org.apache.commons.io.RandomAccessFileMode;
 import org.apache.commons.io.TestResources;
 import org.apache.commons.io.test.TestUtils;
 import org.junit.jupiter.api.AfterEach;
@@ -72,26 +73,26 @@ public NonStandardTailable(final File file) {
         public Tailer.RandomAccessResourceBridge getRandomAccess(final String mode) throws FileNotFoundException {
             return new Tailer.RandomAccessResourceBridge() {
 
-                private final RandomAccessFile reader = new RandomAccessFile(file, mode);
+                private final RandomAccessFile randomAccessFile = new RandomAccessFile(file, mode);
 
                 @Override
                 public void close() throws IOException {
-                    reader.close();
+                    randomAccessFile.close();
                 }
 
                 @Override
                 public long getPointer() throws IOException {
-                    return reader.getFilePointer();
+                    return randomAccessFile.getFilePointer();
                 }
 
                 @Override
                 public int read(final byte[] b) throws IOException {
-                    return reader.read(b);
+                    return randomAccessFile.read(b);
                 }
 
                 @Override
                 public void seek(final long position) throws IOException {
-                    reader.seek(position);
+                    randomAccessFile.seek(position);
                 }
             };
         }
@@ -203,7 +204,7 @@ protected void createFile(final File file, final long size) throws IOException {
         try {
             while (reader == null) {
                 try {
-                    reader = new RandomAccessFile(file.getPath(), "r");
+                    reader = RandomAccessFileMode.READ_ONLY.create(file);
                 } catch (final FileNotFoundException ignore) {
                     // ignore
                 }