YieldingRunnable

src/main/java/com/mongodb/hibernate/internal/MongoAssertions.java

@@ -41,4 +41,30 @@ public static <T> T assertNotNull(@Nullable T value) throws AssertionError {
         }
         return value;
     }
+
+    /**
+     * @param value A value to check.
+     * @param <T> The type of {@code value}.
+     * @return {@code null}.
+     * @throws AssertionError If {@code value} is not {@code null}.
+     */
+    @Nullable
+    public static <T> T assertNull(@Nullable final T value) throws AssertionError {
+        if (value != null) {
+            throw new AssertionError(value.toString());
+        }
+        return null;
+    }
+
+    /**
+     * @param value A value to check.
+     * @return {@code true}.
+     * @throws AssertionError If {@code value} is {@code false}.
+     */
+    public static boolean assertTrue(final boolean value) throws AssertionError {
+        if (!value) {
+            throw new AssertionError();
+        }
+        return true;
+    }
 }

src/main/java/com/mongodb/hibernate/translate/attachment/YieldingRunnable.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2024-present MongoDB, Inc.
+ *
+ * Licensed 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 com.mongodb.hibernate.translate.attachment;
+
+import org.jspecify.annotations.Nullable;
+
+import com.mongodb.hibernate.translate.attachment.YieldingRunnable.ValueDescriptors.ValueDescriptor;
+
+import static com.mongodb.hibernate.internal.MongoAssertions.assertNotNull;
+import static com.mongodb.hibernate.internal.MongoAssertions.assertNull;
+import static com.mongodb.hibernate.internal.MongoAssertions.assertTrue;
+
+@FunctionalInterface
+public interface YieldingRunnable<T, D extends ValueDescriptor<? super T>> {
+    static <T, D extends ValueDescriptor<? super T>> T run(D valueDescriptor, YieldingRunnable<T, D> runnable) {
+        YieldableValue<T, D> yieldableValue = new YieldableValue<>(valueDescriptor);
+        runnable.run(yieldableValue);
+        return yieldableValue.get();
+    }
+
+    void run(YieldableValue<T, D> yieldableValue);
+
+    final class ValueDescriptors {
+        public static final ColumnName COLUMN_NAME = new ColumnName();
+        public static final CollectionName COLLECTION_NAME = new CollectionName();
+        public static final MyNumber MY_NUMBER = new MyNumber();
+
+        private ValueDescriptors() {
+        }
+
+        public static abstract class ValueDescriptor<T> {
+            private ValueDescriptor() {
+            }
+
+            @Override
+            public String toString() {
+                return getClass().getSimpleName();
+            }
+        }
+
+        public static final class ColumnName extends ValueDescriptor<String> {
+            private ColumnName() {
+            }
+        }
+
+        public static final class CollectionName extends ValueDescriptor<String> {
+            private CollectionName() {
+            }
+        }
+
+        public static final class MyNumber extends ValueDescriptor<Number> {
+            private MyNumber() {
+            }
+        }
+    }
+
+    final class YieldableValue<T, D extends ValueDescriptor<? super T>> {
+        private final D descriptor;
+        @Nullable
+        private T value;
+
+        private YieldableValue(final D descriptor) {
+            this.descriptor = descriptor;
+        }
+
+        public void yield(D descriptor, T value) {
+            assertTrue(descriptor.equals(this.descriptor));
+            assertNull(this.value);
+            this.value = assertNotNull(value);
+        }
+
+        private T get() {
+            return assertNotNull(value);
+        }
+    }
+}

src/test/java/com/mongodb/hibernate/translate/attachment/YieldingRunnableTests.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2024-present MongoDB, Inc.
+ *
+ * Licensed 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 com.mongodb.hibernate.translate.attachment;
+
+import com.mongodb.hibernate.translate.attachment.YieldingRunnable.ValueDescriptors;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class YieldingRunnableTests {
+    @Test
+    void example() {
+        assertEquals(
+                "my string",
+                YieldingRunnable.run(ValueDescriptors.COLLECTION_NAME, yieldableValue -> {
+                    voidMethod();
+                    yieldableValue.yield(ValueDescriptors.COLLECTION_NAME, "my string");
+                }));
+    }
+
+    private static void voidMethod() {
+    }
+
+    @Test
+    void features() {
+        String string = YieldingRunnable.run(ValueDescriptors.COLUMN_NAME, yieldableValue ->
+                // Note how the compiler does not allow you to use `COLLECTION_NAME`,
+                // despite it also being of the `ValueDescriptor<String>` type.
+                // The compiler forces you to specify `COLUMN_NAME` here, and nothing else.
+                //
+                // We still require `COLUMN_NAME` to be passed here,
+                // because this way we can check that the passed `ValueDescriptor` matches the required one,
+                // regardless of whether the calling code uses raw types, or unchecked conversions.
+                yieldableValue.yield(ValueDescriptors.COLUMN_NAME, "my string"));
+
+        // Note how we can return `Integer` despite `MY_NUMBER` being of the `ValueDescriptor<Number>` type.
+        // Such versatility is good. At the same time, we cannot return `Object` or `String`, i.e., we are type-safe.
+        Integer integer = YieldingRunnable.run(ValueDescriptors.MY_NUMBER, todo ->
+                todo.yield(ValueDescriptors.MY_NUMBER, Integer.parseInt("1")));
+    }
+}