Define API interfaces for mmap-dictionary

build.gradle

@@ -347,6 +347,64 @@ project(':mmap-queue') {
     }
 }
 
+project(':mmap-dictionary') {
+    dependencies {
+        api "org.agrona:agrona:${agronaVersion}"
+        api "org.slf4j:slf4j-api:${slf4jVersion}"
+        api project(':mmap-region')
+
+        testImplementation "org.hdrhistogram:HdrHistogram:${hdrHistogramVersion}"
+        testRuntimeOnly "org.slf4j:slf4j-simple:${slf4jVersion}"
+    }
+
+    jar {
+        bundle {
+            // workaround for https://github.com/bndtools/bnd/issues/6346
+            properties.put("project.group", provider({project.group}))
+            bnd """
+                Automatic-Module-Name:  org.tools4j.mmap-dictionary
+                Bundle-Name:            org.tools4j.mmap-dictionary
+                Bundle-SymbolicName:    org.tools4j.mmap-dictionary
+                Implementation-Title:   mmap
+                Implementation-Vendor:  tools4j.org
+                Implementation-Version: ${projVersion}
+                -exportcontents: org.tools4j.mmap, org.tools4j.mmap.*
+                # Suppress headers that reduce reproducibility.
+                -reproducible: true
+                -noextraheaders: true
+            """
+        }
+    }
+
+    java {
+        withSourcesJar()
+        withJavadocJar()
+    }
+
+    publishing {
+        publications {
+            mmapQueue(MavenPublication) {
+                from components.java
+                pom(projectPom)
+            }
+        }
+
+        repositories {
+            maven {
+                url = !isReleaseVersion ? snapshotsRepoUrl : releasesRepoUrl
+                credentials {
+                    username = ossrhUsername
+                    password = ossrhPassword
+                }
+            }
+        }
+    }
+
+    signing {
+        sign publishing.publications.mmapQueue
+    }
+}
+
 
 tasks.register('testReport', TestReport) {
     destinationDirectory = file("${rootDir}/reports/allTests")

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/DeletePredicate.java

@@ -0,0 +1,29 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+@FunctionalInterface
+public interface DeletePredicate {
+    boolean test(KeyValuePair keyValue);
+}

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/DeletingContext.java

@@ -0,0 +1,65 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+import org.agrona.MutableDirectBuffer;
+
+public interface DeletingContext extends AutoCloseable {
+    /**
+     * Aborts deleting the key/value pair
+     */
+    void abort();
+
+    /**
+     * @return true if the context is closed.
+     */
+    boolean isClosed();
+
+    /**
+     * Aborts deleting if not closed or committed yet.
+     */
+    @Override
+    default void close() {
+        if (!isClosed()) {
+            abort();
+        }
+    }
+
+    interface Key extends DeletingContext {
+        MutableDirectBuffer keyBuffer();
+
+        Result delete(int keyLength);
+        Result deleteIfMatching(int keyLength, DeletePredicate condition);
+    }
+
+    interface Result extends KeyValueResult {
+        /**
+         * @return true if the key/value pair was present in the dictionary when performing or attempting
+         * the delete operation
+         */
+        @Override
+        boolean isPresent();
+        boolean isDeleted();
+    }
+}

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/Dictionary.java

@@ -0,0 +1,58 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+import org.tools4j.mmap.dictionary.config.DictionaryConfig;
+import org.tools4j.mmap.dictionary.config.ReaderConfig;
+import org.tools4j.mmap.dictionary.config.UpdaterConfig;
+import org.tools4j.mmap.dictionary.impl.DictionaryImpl;
+
+import java.io.File;
+
+public interface Dictionary extends AutoCloseable {
+    Updater createUpdater();
+    Updater createUpdater(UpdaterConfig config);
+
+    Lookup createLookup();
+    Lookup createLookup(ReaderConfig config);
+
+    DictionaryIterator createIterator();
+    DictionaryIterator createIterator(ReaderConfig config);
+
+    boolean isClosed();
+
+    /**
+     * Closes the dictionary and all updaters, lookups and iterators created via this dictionary.
+     */
+    @Override
+    void close();
+
+    static Dictionary create(final File file) {
+        return new DictionaryImpl(file);
+    }
+
+    static Dictionary create(final File file, final DictionaryConfig config) {
+        return new DictionaryImpl(file, config);
+    }
+}

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/DictionaryIterator.java

@@ -0,0 +1,41 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+public interface DictionaryIterator extends AutoCloseable {
+    IteratingContext.KeyValuePairs iteratingKeyValuePairs();
+    IteratingContext.Keys iteratingKeys();
+    IteratingContext.Values iteratingValues();
+
+    long size();
+    boolean isEmpty();
+
+    boolean isClosed();
+
+    /**
+     * Closes this reader.
+     */
+    @Override
+    void close();
+}

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/IteratingContext.java

@@ -0,0 +1,39 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+import org.agrona.DirectBuffer;
+
+public interface IteratingContext<E> extends Iterable<E> {
+    boolean isClosed();
+
+    /**
+     * Closes this context.
+     */
+    void close();
+
+    interface KeyValuePairs extends IteratingContext<KeyValuePair>, AutoCloseable {}
+    interface Keys extends IteratingContext<DirectBuffer>, AutoCloseable {}
+    interface Values extends IteratingContext<DirectBuffer>, AutoCloseable {}
+}

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/KeyValueIterable.java

@@ -0,0 +1,47 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+import org.agrona.DirectBuffer;
+
+import java.util.Iterator;
+
+public interface KeyValueIterable extends Iterable<KeyValuePair>, AutoCloseable {
+    @Override
+    Iterator<KeyValuePair> iterator();
+
+    Iterable<DirectBuffer> keys();
+    Iterable<DirectBuffer> values();
+
+    long size();
+    boolean isEmpty();
+
+    boolean isClosed();
+
+    /**
+     * Closes this reader.
+     */
+    @Override
+    void close();
+}

mmap-dictionary/src/main/java/org/tools4j/mmap/dictionary/api/KeyValuePair.java

@@ -0,0 +1,34 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016-2025 tools4j.org (Marco Terzer, Anton Anufriev)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.tools4j.mmap.dictionary.api;
+
+import org.agrona.DirectBuffer;
+
+/**
+ * Representation of a key/value pair, with key and value data accessible through {@link #key()} and {@link #value()}.
+ */
+public interface KeyValuePair {
+    DirectBuffer key();
+    DirectBuffer value();
+}