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