Skip to content

Apache Lucene open-source search software

Specify and test that IOContext is immutable (#14686)

Chris Hegarty922db5044945
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
+ }
+}