Introduce BookmarkManager (#1285)

Bookmark manager is a new opt-in feature that is enabled via driver `Config`.

It is responsible for providing an up-to-date set of bookmarks to driver on session creation and database data access.

Driver provides a default implementation via `BookmarkManagers.defaultManager`. The default implementation keeps track of a single local driver instance bookmarks only. However, it supports 2 extension points:
- `updateListener` - a listener for new bookmarks
- `bookmarkSupplier` - a supplier of additional bookmarks

It is possible to turn off bookmark manager on session level using `SessionConfig` even when it is enabled on the driver level.

Please note that this feature might have an impact on setups that do not manage the driver directly since there is a chance of getting a driver with bookmarks manager enabled.

Javadoc includes more general details.

Author: injectives

driver/src/main/java/org/neo4j/driver/BookmarkManager.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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 org.neo4j.driver;
+
+import java.io.Serializable;
+import java.util.Set;
+
+/**
+ * Keeps track of database bookmarks and is used by the driver to ensure causal consistency between sessions and query executions.
+ * <p>
+ * Please note that implementations of this interface MUST NOT block for extended periods of time.
+ * <p>
+ * Implementations must avoid calling driver.
+ *
+ * @see org.neo4j.driver.Config.ConfigBuilder#withBookmarkManager(BookmarkManager)
+ */
+public interface BookmarkManager extends Serializable {
+    /**
+     * Updates database bookmarks by deleting the given previous bookmarks and adding the new bookmarks.
+     *
+     * @param database          the database name, this might be an empty string when session has no database name configured and database discovery is unavailable
+     * @param previousBookmarks the previous bookmarks
+     * @param newBookmarks      the new bookmarks
+     */
+    void updateBookmarks(String database, Set<Bookmark> previousBookmarks, Set<Bookmark> newBookmarks);
+
+    /**
+     * Gets an immutable set of bookmarks for a given database.
+     *
+     * @param database the database name
+     * @return the set of bookmarks or an empty set if the database name is unknown to the bookmark manager
+     */
+    Set<Bookmark> getBookmarks(String database);
+
+    /**
+     * Gets an immutable set of bookmarks for all databases.
+     *
+     * @return the set of bookmarks or an empty set
+     */
+    Set<Bookmark> getAllBookmarks();
+
+    /**
+     * Deletes bookmarks for the given databases.
+     * <p>
+     * This method should be called by driver users if data deletion is desired when bookmarks for the given databases are no longer needed.
+     *
+     * @param databases the set of database names
+     */
+    void forget(Set<String> databases);
+}

driver/src/main/java/org/neo4j/driver/BookmarkManagerConfig.java

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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 org.neo4j.driver;
+
+import java.util.Collections;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.function.BiConsumer;
+
+/**
+ * Bookmark configuration used to configure bookmark manager supplied by {@link BookmarkManagers#defaultManager(BookmarkManagerConfig)}.
+ */
+public final class BookmarkManagerConfig {
+    private final Map<String, Set<Bookmark>> initialBookmarks;
+    private final BiConsumer<String, Set<Bookmark>> updateListener;
+    private final BookmarkSupplier bookmarkSupplier;
+
+    private BookmarkManagerConfig(BookmarkManagerConfigBuilder builder) {
+        this.initialBookmarks = builder.initialBookmarks;
+        this.updateListener = builder.updateListener;
+        this.bookmarkSupplier = builder.bookmarkSupplier;
+    }
+
+    /**
+     * Creates a new {@link BookmarkManagerConfigBuilder} used to construct a configuration object.
+     *
+     * @return a bookmark manager configuration builder.
+     */
+    public static BookmarkManagerConfigBuilder builder() {
+        return new BookmarkManagerConfigBuilder();
+    }
+
+    /**
+     * Returns the map of bookmarks used to initialise the bookmark manager.
+     *
+     * @return the map of bookmarks
+     */
+    public Map<String, Set<Bookmark>> initialBookmarks() {
+        return initialBookmarks;
+    }
+
+    /**
+     * Returns a bookmark update listener that will be notified when database bookmarks are updated.
+     *
+     * @return the update listener or {@code null}
+     */
+    public BiConsumer<String, Set<Bookmark>> updateListener() {
+        return updateListener;
+    }
+
+    /**
+     * Returns bookmark supplier that will be used by the bookmark manager when getting bookmarks.
+     *
+     * @return the bookmark supplier or {@code null}
+     */
+    public BookmarkSupplier bookmarkSupplier() {
+        return bookmarkSupplier;
+    }
+
+    /**
+     * Builder used to configure {@link BookmarkManagerConfig} which will be used to create a bookmark manager.
+     */
+    public static class BookmarkManagerConfigBuilder {
+        private Map<String, Set<Bookmark>> initialBookmarks = Collections.emptyMap();
+        private BiConsumer<String, Set<Bookmark>> updateListener;
+        private BookmarkSupplier bookmarkSupplier;
+
+        private BookmarkManagerConfigBuilder() {}
+
+        /**
+         * Provide a map of initial bookmarks to initialise the bookmark manager.
+         *
+         * @param databaseToBookmarks database to bookmarks map
+         * @return this builder
+         */
+        public BookmarkManagerConfigBuilder withInitialBookmarks(Map<String, Set<Bookmark>> databaseToBookmarks) {
+            Objects.requireNonNull(databaseToBookmarks, "databaseToBookmarks must not be null");
+            this.initialBookmarks = databaseToBookmarks;
+            return this;
+        }
+
+        /**
+         * Provide a bookmarks update listener.
+         * <p>
+         * The listener will be called outside bookmark manager's synchronisation lock.
+         *
+         * @param updateListener update listener
+         * @return this builder
+         */
+        public BookmarkManagerConfigBuilder withUpdateListener(BiConsumer<String, Set<Bookmark>> updateListener) {
+            this.updateListener = updateListener;
+            return this;
+        }
+
+        /**
+         * Provide a bookmark supplier.
+         * <p>
+         * The supplied bookmarks will be served alongside the bookmarks served by the bookmark manager. The supplied bookmarks will not be stored nor managed by the bookmark manager.
+         * <p>
+         * The supplier will be called outside bookmark manager's synchronisation lock.
+         *
+         * @param bookmarkSupplier the bookmarks supplier
+         * @return this builder
+         */
+        public BookmarkManagerConfigBuilder withBookmarksSupplier(BookmarkSupplier bookmarkSupplier) {
+            this.bookmarkSupplier = bookmarkSupplier;
+            return this;
+        }
+
+        public BookmarkManagerConfig build() {
+            return new BookmarkManagerConfig(this);
+        }
+    }
+}

driver/src/main/java/org/neo4j/driver/BookmarkManagers.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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 org.neo4j.driver;
+
+import org.neo4j.driver.internal.Neo4jBookmarkManager;
+
+/**
+ * Setups new instances of {@link BookmarkManager}.
+ */
+public interface BookmarkManagers {
+    /**
+     * Setups a new instance of bookmark manager that can be used in {@link org.neo4j.driver.Config.ConfigBuilder#withBookmarkManager(BookmarkManager)}.
+     *
+     * @param config the bookmark manager configuration
+     * @return the bookmark manager
+     */
+    static BookmarkManager defaultManager(BookmarkManagerConfig config) {
+        return new Neo4jBookmarkManager(config.initialBookmarks(), config.updateListener(), config.bookmarkSupplier());
+    }
+}

driver/src/main/java/org/neo4j/driver/BookmarkSupplier.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * 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 org.neo4j.driver;
+
+import java.util.Set;
+
+/**
+ * Supplies additional bookmarks to {@link BookmarkManager} implementation provided by {@link BookmarkManagers#defaultManager(BookmarkManagerConfig)}.
+ * <p>
+ * Implementations must avoid calling driver.
+ */
+public interface BookmarkSupplier {
+    /**
+     * Supplies a set of bookmarks for a given database.
+     *
+     * @param database the database name
+     * @return the set of bookmarks, must not be {@code null}
+     */
+    Set<Bookmark> getBookmarks(String database);
+
+    /**
+     * Supplies a set of bookmarks for all databases.
+     *
+     * @return the set of bookmarks, must not be {@code null}
+     */
+    Set<Bookmark> getAllBookmarks();
+}

driver/src/main/java/org/neo4j/driver/Config.java

@@ -98,6 +98,7 @@ public class Config implements Serializable {
     private final int eventLoopThreads;
     private final String userAgent;
     private final MetricsAdapter metricsAdapter;
+    private final BookmarkManager bookmarkManager;
 
     private Config(ConfigBuilder builder) {
         this.logging = builder.logging;
@@ -119,6 +120,8 @@ private Config(ConfigBuilder builder) {
 
         this.eventLoopThreads = builder.eventLoopThreads;
         this.metricsAdapter = builder.metricsAdapter;
+
+        this.bookmarkManager = builder.bookmarkManager;
     }
 
     /**
@@ -252,6 +255,15 @@ public String userAgent() {
         return userAgent;
     }
 
+    /**
+     * A {@link BookmarkManager} implementation for the driver to use.
+     *
+     * @return bookmark implementation or {@code null}.
+     */
+    public BookmarkManager bookmarkManager() {
+        return bookmarkManager;
+    }
+
     /**
      * Used to build new config instances
      */
@@ -272,6 +284,7 @@ public static class ConfigBuilder {
         private MetricsAdapter metricsAdapter = MetricsAdapter.DEV_NULL;
         private long fetchSize = FetchSizeUtil.DEFAULT_FETCH_SIZE;
         private int eventLoopThreads = 0;
+        private BookmarkManager bookmarkManager;
 
         private ConfigBuilder() {}
 
@@ -645,6 +658,19 @@ public ConfigBuilder withUserAgent(String userAgent) {
             return this;
         }
 
+        /**
+         * Sets a {@link BookmarkManager} implementation for the driver to use.
+         * <p>
+         * By default, bookmark manager is effectively disabled.
+         *
+         * @param bookmarkManager bookmark manager implementation. Providing {@code null} effectively disables bookmark manager.
+         * @return this builder.
+         */
+        public ConfigBuilder withBookmarkManager(BookmarkManager bookmarkManager) {
+            this.bookmarkManager = bookmarkManager;
+            return this;
+        }
+
         /**
          * Extracts the driver version from the driver jar MANIFEST.MF file.
          */