Use a hint to specify READONCE IOContext

lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene50/Lucene50CompoundReader.java

@@ -153,6 +153,7 @@ public void close() throws IOException {
 
   @Override
   public IndexInput openInput(String name, IOContext context) throws IOException {
+    validateIOContext(context);
     ensureOpen();
     final String id = IndexFileNames.stripSegmentName(name);
     final FileEntry entry = entries.get(id);
@@ -170,7 +171,7 @@ public IndexInput openInput(String name, IOContext context) throws IOException {
               + entries.keySet()
               + ")");
     }
-    return handle.slice(name, entry.offset, entry.length, context.readAdvice());
+    return handle.slice(name, entry.offset, entry.length, toReadAdvice(context));
   }
 
   /** Returns an array of strings, one for each file in the directory. */

lucene/codecs/src/java/org/apache/lucene/codecs/simpletext/SimpleTextCompoundFormat.java

@@ -140,7 +140,7 @@ public IndexInput openInput(String name, IOContext context) throws IOException {
             name,
             startOffsets[index],
             endOffsets[index] - startOffsets[index],
-            context.readAdvice());
+            toReadAdvice(context));
       }
 
       @Override

lucene/core/src/java/org/apache/lucene/codecs/lucene90/Lucene90CompoundReader.java

@@ -169,7 +169,7 @@ public IndexInput openInput(String name, IOContext context) throws IOException {
               + entries.keySet()
               + ")");
     }
-    return handle.slice(name, entry.offset, entry.length, context.readAdvice());
+    return handle.slice(name, entry.offset, entry.length, toReadAdvice(context));
   }
 
   /** Returns an array of strings, one for each file in the directory. */

lucene/core/src/java/org/apache/lucene/index/ConcurrentMergeScheduler.java

@@ -299,6 +299,7 @@ public Directory wrapForMerge(OneMerge merge, Directory in) {
     return new FilterDirectory(in) {
       @Override
       public IndexOutput createOutput(String name, IOContext context) throws IOException {
+        validateIOContext(context);
         ensureOpen();
 
         // This Directory is only supposed to be used during merging,

lucene/core/src/java/org/apache/lucene/index/DocumentsWriterPerThread.java

@@ -415,7 +415,7 @@ FlushedSegment flush(DocumentsWriter.FlushNotifications flushNotifications) thro
             segmentInfo,
             fieldInfos.finish(),
             pendingUpdates,
-            new IOContext(new FlushInfo(numDocsInRAM, lastCommittedBytesUsed)));
+            IOContext.flush(new FlushInfo(numDocsInRAM, lastCommittedBytesUsed)));
     final double startMBUsed = lastCommittedBytesUsed / 1024. / 1024.;
 
     // Apply delete-by-docID now (delete-byDocID only
@@ -599,7 +599,7 @@ void sealFlushedSegment(
     IndexWriter.setDiagnostics(newSegment.info, IndexWriter.SOURCE_FLUSH);
 
     IOContext context =
-        new IOContext(new FlushInfo(newSegment.info.maxDoc(), newSegment.sizeInBytes()));
+        IOContext.flush(new FlushInfo(newSegment.info.maxDoc(), newSegment.sizeInBytes()));
 
     boolean success = false;
     try {

lucene/core/src/java/org/apache/lucene/index/IndexWriter.java

@@ -3058,7 +3058,7 @@ public long addIndexes(Directory... dirs) throws IOException {
             }
 
             IOContext context =
-                new IOContext(new FlushInfo(info.info.maxDoc(), info.sizeInBytes()));
+                IOContext.flush(new FlushInfo(info.info.maxDoc(), info.sizeInBytes()));
 
             FieldInfos fis = readFieldInfos(info);
             for (FieldInfo fi : fis) {
@@ -3400,7 +3400,7 @@ public void addIndexesReaderMerge(MergePolicy.OneMerge merge) throws IOException
     testReserveDocs(numDocs);
 
     final IOContext context =
-        new IOContext(
+        IOContext.merge(
             new MergeInfo(Math.toIntExact(numDocs), -1, false, UNBOUNDED_MAX_MERGE_SEGMENTS));
 
     TrackingDirectoryWrapper trackingDir = new TrackingDirectoryWrapper(mergeDirectory);
@@ -3950,7 +3950,7 @@ public void setMergeInfo(SegmentCommitInfo info) {
       boolean closeReaders = true;
       try {
         for (MergePolicy.OneMerge merge : pointInTimeMerges.merges) {
-          IOContext context = new IOContext(merge.getStoreMergeInfo());
+          IOContext context = IOContext.merge(merge.getStoreMergeInfo());
           merge.initMergeReaders(
               sci -> {
                 final ReadersAndUpdates rld = getPooledInstance(sci, true);
@@ -5139,7 +5139,7 @@ private int mergeMiddle(MergePolicy.OneMerge merge, MergePolicy mergePolicy) thr
     merge.checkAborted();
 
     Directory mergeDirectory = mergeScheduler.wrapForMerge(merge, directory);
-    IOContext context = new IOContext(merge.getStoreMergeInfo());
+    IOContext context = IOContext.merge(merge.getStoreMergeInfo());
 
     final TrackingDirectoryWrapper dirWrapper = new TrackingDirectoryWrapper(mergeDirectory);
 

lucene/core/src/java/org/apache/lucene/index/ReadersAndUpdates.java

@@ -321,7 +321,7 @@ private synchronized void handleDVUpdates(
       }
       final long nextDocValuesGen = info.getNextDocValuesGen();
       final String segmentSuffix = Long.toString(nextDocValuesGen, Character.MAX_RADIX);
-      final IOContext updatesContext = new IOContext(new FlushInfo(info.info.maxDoc(), bytes));
+      final IOContext updatesContext = IOContext.flush(new FlushInfo(info.info.maxDoc(), bytes));
       final FieldInfo fieldInfo = infos.fieldInfo(field);
       assert fieldInfo != null;
       fieldInfo.setDocValuesGen(nextDocValuesGen);
@@ -536,7 +536,7 @@ private synchronized Set<String> writeFieldInfosGen(
     // HEADER + FOOTER: 40
     // 90 bytes per-field (over estimating long name and attributes map)
     final long estInfosSize = 40 + 90L * fieldInfos.size();
-    final IOContext infosContext = new IOContext(new FlushInfo(info.info.maxDoc(), estInfosSize));
+    final IOContext infosContext = IOContext.flush(new FlushInfo(info.info.maxDoc(), estInfosSize));
     // separately also track which files were created for this gen
     final TrackingDirectoryWrapper trackingDir = new TrackingDirectoryWrapper(dir);
     infosFormat.write(trackingDir, info.info, segmentSuffix, fieldInfos, infosContext);

lucene/core/src/java/org/apache/lucene/index/SortingTermVectorsConsumer.java

@@ -86,7 +86,7 @@ void flush(
   @Override
   void initTermVectorsWriter() throws IOException {
     if (writer == null) {
-      IOContext context = new IOContext(new FlushInfo(lastDocID, bytesUsed.get()));
+      IOContext context = IOContext.flush(new FlushInfo(lastDocID, bytesUsed.get()));
       tmpDirectory = new TrackingTmpOutputDirectoryWrapper(directory);
       writer = TEMP_TERM_VECTORS_FORMAT.vectorsWriter(tmpDirectory, info, context);
       lastDocID = 0;

lucene/core/src/java/org/apache/lucene/index/TermVectorsConsumer.java

@@ -102,7 +102,7 @@ void fill(int docID) throws IOException {
 
   void initTermVectorsWriter() throws IOException {
     if (writer == null) {
-      IOContext context = new IOContext(new FlushInfo(lastDocID, bytesUsed.get()));
+      IOContext context = IOContext.flush(new FlushInfo(lastDocID, bytesUsed.get()));
       writer = codec.termVectorsFormat().vectorsWriter(directory, info, context);
       lastDocID = 0;
       accountable = writer;

lucene/core/src/java/org/apache/lucene/store/ByteBuffersDirectory.java

@@ -153,6 +153,7 @@ public boolean fileExists(String name) {
 
   @Override
   public IndexOutput createOutput(String name, IOContext context) throws IOException {
+    validateIOContext(context);
     ensureOpen();
     FileEntry e = new FileEntry(name);
     if (files.putIfAbsent(name, e) != null) {
@@ -164,6 +165,7 @@ public IndexOutput createOutput(String name, IOContext context) throws IOExcepti
   @Override
   public IndexOutput createTempOutput(String prefix, String suffix, IOContext context)
       throws IOException {
+    validateIOContext(context);
     ensureOpen();
     while (true) {
       String name = IndexFileNames.segmentFileName(prefix, tempFileName.apply(suffix), "tmp");
@@ -203,6 +205,7 @@ public void syncMetaData() throws IOException {
 
   @Override
   public IndexInput openInput(String name, IOContext context) throws IOException {
+    validateIOContext(context);
     ensureOpen();
     FileEntry e = files.get(name);
     if (e == null) {

lucene/core/src/java/org/apache/lucene/store/DataAccessHint.java

@@ -0,0 +1,23 @@
+/*
+ * 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.lucene.store;
+
+/** Hint on the data access pattern likely to be used */
+public enum DataAccessHint implements IOContext.FileOpenHint {
+  RANDOM,
+  SEQUENTIAL
+}

lucene/core/src/java/org/apache/lucene/store/DefaultIOContext.java

@@ -0,0 +1,71 @@
+/*
+ * 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.lucene.store;
+
+import java.util.Arrays;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+
+record DefaultIOContext(Optional<ReadAdvice> readAdvice, Set<FileOpenHint> hints)
+    implements IOContext {
+
+  public DefaultIOContext {
+    Objects.requireNonNull(readAdvice);
+    Objects.requireNonNull(hints);
+    if (readAdvice.isPresent() && !hints.isEmpty())
+      throw new IllegalArgumentException("Either ReadAdvice or hints can be specified, not both");
+  }
+
+  public DefaultIOContext(Optional<ReadAdvice> readAdvice, FileOpenHint... hints) {
+    this(readAdvice, Set.of(hints));
+  }
+
+  @Override
+  public Context context() {
+    return Context.DEFAULT;
+  }
+
+  @Override
+  public MergeInfo mergeInfo() {
+    return null;
+  }
+
+  @Override
+  public FlushInfo flushInfo() {
+    return null;
+  }
+
+  @Override
+  public IOContext withHints(FileOpenHint... hints) {
+    if (readAdvice().isPresent())
+      throw new IllegalArgumentException("ReadAdvice has been specified directly");
+    // TODO: see if this is needed or not
+    if (!hints().isEmpty()) throw new IllegalArgumentException("Hints have already been specified");
+    return new DefaultIOContext(Optional.empty(), hints);
+  }
+
+  private static final DefaultIOContext[] READADVICE_TO_IOCONTEXT =
+      Arrays.stream(ReadAdvice.values())
+          .map(r -> new DefaultIOContext(Optional.of(r)))
+          .toArray(DefaultIOContext[]::new);
+
+  @Override
+  public DefaultIOContext withReadAdvice(ReadAdvice advice) {
+    return READADVICE_TO_IOCONTEXT[advice.ordinal()];
+  }
+}

lucene/core/src/java/org/apache/lucene/store/Directory.java

@@ -21,8 +21,12 @@
 import java.io.IOException;
 import java.nio.file.NoSuchFileException;
 import java.util.Collection; // for javadocs
+import java.util.List;
+import java.util.Map;
 import java.util.Set;
+import java.util.stream.Collectors;
 import org.apache.lucene.index.IndexFileNames;
+import org.apache.lucene.util.Constants;
 import org.apache.lucene.util.IOUtils;
 
 /**
@@ -79,6 +83,32 @@ public abstract class Directory implements Closeable {
    */
   public abstract long fileLength(String name) throws IOException;
 
+  protected void validateIOContext(IOContext context) {
+    Map<Class<? extends IOContext.FileOpenHint>, List<IOContext.FileOpenHint>> hintClasses =
+        context.hints().stream().collect(Collectors.groupingBy(IOContext.FileOpenHint::getClass));
+
+    // there should only be one of FileType, FileData, DataAccess
+    List<IOContext.FileOpenHint> fileTypes =
+        hintClasses.getOrDefault(FileTypeHint.class, List.of());
+    if (fileTypes.size() > 1) {
+      throw new IllegalArgumentException("Multiple file type hints specified: " + fileTypes);
+    }
+    List<IOContext.FileOpenHint> fileData = hintClasses.getOrDefault(FileDataHint.class, List.of());
+    if (fileData.size() > 1) {
+      throw new IllegalArgumentException("Multiple file data hints specified: " + fileData);
+    }
+    List<IOContext.FileOpenHint> dataAccess =
+        hintClasses.getOrDefault(DataAccessHint.class, List.of());
+    if (dataAccess.size() > 1) {
+      throw new IllegalArgumentException("Multiple data access hints specified: " + dataAccess);
+    }
+  }
+
+  protected ReadAdvice toReadAdvice(IOContext context) {
+    if (ReadOnceHint.isReadOnce(context)) return ReadAdvice.SEQUENTIAL;
+    return context.readAdvice().orElse(Constants.DEFAULT_READADVICE);
+  }
+
   /**
    * Creates a new, empty file in the directory and returns an {@link IndexOutput} instance for
    * appending data to this file.

lucene/core/src/java/org/apache/lucene/store/FSDirectory.java

@@ -205,6 +205,7 @@ public long fileLength(String name) throws IOException {
 
   @Override
   public IndexOutput createOutput(String name, IOContext context) throws IOException {
+    validateIOContext(context);
     ensureOpen();
     maybeDeletePendingFiles();
     // If this file was pending delete, we are now bringing it back to life:
@@ -218,6 +219,7 @@ public IndexOutput createOutput(String name, IOContext context) throws IOExcepti
   @Override
   public IndexOutput createTempOutput(String prefix, String suffix, IOContext context)
       throws IOException {
+    validateIOContext(context);
     ensureOpen();
     maybeDeletePendingFiles();
     while (true) {

lucene/core/src/java/org/apache/lucene/store/FileDataHint.java

@@ -0,0 +1,24 @@
+/*
+ * 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.lucene.store;
+
+/** Hints on the type of data stored in the file */
+public enum FileDataHint implements IOContext.FileOpenHint {
+  POSTINGS,
+  STORED_FIELDS,
+  VECTORS
+}

lucene/core/src/java/org/apache/lucene/store/FileTypeHint.java

@@ -0,0 +1,24 @@
+/*
+ * 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.lucene.store;
+
+/** Hints on the type of file being opened */
+public enum FileTypeHint implements IOContext.FileOpenHint {
+  METADATA,
+  DATA,
+  INDEX
+}

lucene/core/src/java/org/apache/lucene/store/FilterDirectory.java

@@ -70,6 +70,11 @@ public long fileLength(String name) throws IOException {
     return in.fileLength(name);
   }
 
+  @Override
+  protected void validateIOContext(IOContext context) {
+    in.validateIOContext(context);
+  }
+
   @Override
   public IndexOutput createOutput(String name, IOContext context) throws IOException {
     return in.createOutput(name, context);