You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ch...@apache.org on 2025/05/21 08:41:07 UTC

(lucene) branch main updated: Specify and test that IOContext is immutable (#14686)

This is an automated email from the ASF dual-hosted git repository.

chegar pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/lucene.git


The following commit(s) were added to refs/heads/main by this push:
     new 922db504494 Specify and test that IOContext is immutable (#14686)
922db504494 is described below

commit 922db5044945b5df8a5dbbe29d30140fff9f0791
Author: Chris Hegarty <62...@users.noreply.github.com>
AuthorDate: Wed May 21 01:41:03 2025 -0700

    Specify and test that IOContext is immutable (#14686)
    
    Specify and test that IOContext is immutable.
---
 .../java/org/apache/lucene/store/IOContext.java    | 12 +++-
 .../org/apache/lucene/store/TestIOContext.java     | 75 ++++++++++++++++++++++
 2 files changed, 86 insertions(+), 1 deletion(-)

diff --git a/lucene/core/src/java/org/apache/lucene/store/IOContext.java b/lucene/core/src/java/org/apache/lucene/store/IOContext.java
index c097b238554..049659d45f1 100644
--- a/lucene/core/src/java/org/apache/lucene/store/IOContext.java
+++ b/lucene/core/src/java/org/apache/lucene/store/IOContext.java
@@ -25,6 +25,8 @@ import java.util.stream.Stream;
  * passed as a {@code null} parameter to either {@link
  * org.apache.lucene.store.Directory#openInput(String, IOContext)} or {@link
  * org.apache.lucene.store.Directory#createOutput(String, IOContext)}
+ *
+ * <p>Implementations of IOContext are immutable and thread-safe.
  */
 public interface IOContext {
 
@@ -137,6 +139,14 @@ public interface IOContext {
     return hints().stream().filter(cls::isInstance).map(cls::cast);
   }
 
-  /** Sets the hints on this IOContext, if it makes sense to do so for this specific context */
+  /**
+   * Returns an IOContext with the given hints, if it makes sense to do so for this specific
+   * context. Otherwise, returns this context.
+   *
+   * <p>The returned context has the same {@link #context()}, {@link #mergeInfo()}, and {@link
+   * #flushInfo()} as this context.
+   *
+   * <p>This instance is immutable and unaffected by this method call.
+   */
   IOContext withHints(FileOpenHint... hints);
 }
diff --git a/lucene/core/src/test/org/apache/lucene/store/TestIOContext.java b/lucene/core/src/test/org/apache/lucene/store/TestIOContext.java
new file mode 100644
index 00000000000..19460d6c583
--- /dev/null
+++ b/lucene/core/src/test/org/apache/lucene/store/TestIOContext.java
@@ -0,0 +1,75 @@
+/*
+ * 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.List;
+import java.util.Set;
+import org.apache.lucene.store.IOContext.FileOpenHint;
+import org.apache.lucene.tests.util.LuceneTestCase;
+
+public class TestIOContext extends LuceneTestCase {
+
+  static final Class<UnsupportedOperationException> UOE = UnsupportedOperationException.class;
+
+  public void testUnmodifiable() {
+    for (var context : getContexts()) {
+      expectThrows(UOE, () -> context.hints().remove(randomHint()));
+      expectThrows(UOE, () -> context.hints().removeAll(List.of(randomHint())));
+      expectThrows(UOE, () -> context.hints().add(randomHint()));
+
+      var prevHints = context.hints();
+      var newHint = randomHint();
+      var newContext = context.withHints(newHint);
+      assertEquals(prevHints, context.hints());
+      assertEquals(context.context(), newContext.context());
+      assertEquals(context.mergeInfo(), newContext.mergeInfo());
+      assertEquals(context.flushInfo(), newContext.flushInfo());
+      if (context != newContext) {
+        assertTrue(context.mergeInfo() == null && context.flushInfo() == null);
+        assertEquals(Set.of(newHint), newContext.hints());
+      } else {
+        assertTrue(context.mergeInfo() != null || context.flushInfo() != null);
+      }
+    }
+  }
+
+  protected List<IOContext> getContexts() {
+    return List.of(
+        IOContext.DEFAULT,
+        IOContext.READONCE,
+        IOContext.flush(new FlushInfo(1, 2)),
+        IOContext.merge(new MergeInfo(1, 2, true, 4)));
+  }
+
+  static FileOpenHint randomHint() {
+    var values =
+        switch (random().nextInt(5)) {
+          case 0 -> DataAccessHint.values();
+          case 1 -> FileDataHint.values();
+          case 2 -> FileTypeHint.values();
+          case 3 -> PreloadHint.values();
+          case 4 -> CustomTestHint.values();
+          default -> throw new IllegalStateException("Unexpected value");
+        };
+    return values[random().nextInt(values.length)];
+  }
+
+  enum CustomTestHint implements FileOpenHint {
+    CUSTOM_TEST_HINT1,
+    CUSTOM_TEST_HINT2
+  }
+}