GH-2515 - Add a Noop bookmark manager.

Closes #2515.

Author: michael-simons

src/main/asciidoc/appendix/migrating.adoc

@@ -141,6 +141,8 @@ interface and its only implementation `org.springframework.data.neo4j.bookmark.C
 SDN uses bookmarks for all transactions, without configuration.
 You can remove the bean declaration of `CaffeineBookmarkManager` as well as the dependency to `com.github.ben-manes.caffeine:caffeine`.
 
+If you absolutely must, you can disable the automatic bookmark management by following <<faq.bookmarks.noop, these instructions>>.
+
 [[migrating.autoindex]]
 === Automatic creation of constraints and indexes
 

src/main/asciidoc/faq/faq.adoc

@@ -458,7 +458,7 @@ No, you don't.
 SDN uses Neo4j Causal Cluster bookmarks internally without any configuration on your side required.
 Transactions in the same thread or the same reactive stream following each other will be able to read their previously changed values as you would expect.
 
-[[faq.bookmarks]]
+[[faq.bookmarks.seeding]]
 == Can I retrieve the latest Bookmarks or seed the transaction manager?
 
 As mentioned briefly in <<migrating.bookmarks>>, there is no need to configure anything with regard to bookmarks.
@@ -498,6 +498,8 @@ import org.neo4j.driver.Driver;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.data.neo4j.core.DatabaseSelectionProvider;
+import org.springframework.data.neo4j.core.transaction.Neo4jBookmarkManager;
+import org.springframework.data.neo4j.core.transaction.Neo4jTransactionManager;
 import org.springframework.transaction.PlatformTransactionManager;
 
 @Configuration
@@ -528,6 +530,46 @@ public class BookmarkSeedingConfig {
 WARNING: There is *no* need to do any of these things above, unless your application has the need to access or provide
          this data. If in doubt, don't do either.
 
+[[faq.bookmarks.noop]]
+== Can I disable bookmark management?
+
+We provide a Noop bookmark manager that effectively disables bookmark management.
+
+WARNING: Use this bookmark manager at your own risk, it will effectively disable any bookmark management by dropping all
+         bookmarks and never  supplying any. In a cluster you will be at a high risk of experiencing stale reads. In a single
+         instance it will most likely not make any difference.
+         +
+         In a cluster this can be a sensible approach only and if only you can tolerate stale reads and are not in danger of
+         overwriting old data.
+
+You need to provide the following configuration in your system and make sure that SDN uses the transaction manager:
+
+[source,java,indent=0,tabsize=4]
+.BookmarksDisabledConfig.java
+----
+import org.neo4j.driver.Driver;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.data.neo4j.core.DatabaseSelectionProvider;
+import org.springframework.data.neo4j.core.transaction.Neo4jBookmarkManager;
+import org.springframework.data.neo4j.core.transaction.Neo4jTransactionManager;
+import org.springframework.transaction.PlatformTransactionManager;
+
+@Configuration
+public class BookmarksDisabledConfig {
+
+	@Bean
+	public PlatformTransactionManager transactionManager(
+			Driver driver, DatabaseSelectionProvider databaseNameProvider) {
+
+		Neo4jBookmarkManager bookmarkManager = Neo4jBookmarkManager.noop(); // <.>
+		return new Neo4jTransactionManager(
+			driver, databaseNameProvider, bookmarkManager);
+	}
+}
+----
+<.> Get an instance of the Noop bookmark manager
+
 [[faq.annotations.specific]]
 == Do I need to use Neo4j specific annotations?
 

src/main/java/org/springframework/data/neo4j/core/transaction/AbstractBookmarkManager.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2011-2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.springframework.data.neo4j.core.transaction;
+
+/**
+ * A loophole for test implementations.
+ *
+ * @author Michael J. Simons
+ */
+non-sealed abstract class AbstractBookmarkManager implements Neo4jBookmarkManager {
+}

src/main/java/org/springframework/data/neo4j/core/transaction/DefaultBookmarkManager.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2011-2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.springframework.data.neo4j.core.transaction;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+import java.util.function.Supplier;
+
+import org.neo4j.driver.Bookmark;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.lang.Nullable;
+
+/**
+ * Default bookmark manager.
+ *
+ * @author Michael J. Simons
+ * @soundtrack Helge Schneider - The Last Jazz
+ * @since 7.0
+ */
+final class DefaultBookmarkManager extends AbstractBookmarkManager {
+
+	private final Set<Bookmark> bookmarks = new HashSet<>();
+
+	private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
+	private final Lock read = lock.readLock();
+	private final Lock write = lock.writeLock();
+
+	private final Supplier<Set<Bookmark>> bookmarksSupplier;
+
+	@Nullable
+	private ApplicationEventPublisher applicationEventPublisher;
+
+	DefaultBookmarkManager(@Nullable Supplier<Set<Bookmark>> bookmarksSupplier) {
+		this.bookmarksSupplier = bookmarksSupplier == null ? Collections::emptySet : bookmarksSupplier;
+	}
+
+	@Override
+	public Collection<Bookmark> getBookmarks() {
+
+		try {
+			read.lock();
+			HashSet<Bookmark> bookmarksToUse = new HashSet<>(this.bookmarks);
+			bookmarksToUse.addAll(bookmarksSupplier.get());
+			return Collections.unmodifiableSet(bookmarksToUse);
+		} finally {
+			read.unlock();
+		}
+	}
+
+	@Override
+	public void updateBookmarks(Collection<Bookmark> usedBookmarks, Bookmark lastBookmark) {
+
+		try {
+			write.lock();
+			bookmarks.removeAll(usedBookmarks);
+			bookmarks.add(lastBookmark);
+			if (applicationEventPublisher != null) {
+				applicationEventPublisher.publishEvent(new Neo4jBookmarksUpdatedEvent(new HashSet<>(bookmarks)));
+			}
+		} finally {
+			write.unlock();
+		}
+	}
+
+	@Override
+	public void setApplicationEventPublisher(@Nullable ApplicationEventPublisher applicationEventPublisher) {
+		this.applicationEventPublisher = applicationEventPublisher;
+	}
+}

src/main/java/org/springframework/data/neo4j/core/transaction/Neo4jBookmarkManager.java

@@ -16,11 +16,7 @@
 package org.springframework.data.neo4j.core.transaction;
 
 import java.util.Collection;
-import java.util.Collections;
-import java.util.HashSet;
 import java.util.Set;
-import java.util.concurrent.locks.Lock;
-import java.util.concurrent.locks.ReentrantReadWriteLock;
 import java.util.function.Supplier;
 
 import org.apiguardian.api.API;
@@ -36,13 +32,13 @@
  * @since 6.0
  */
 @API(status = API.Status.STABLE, since = "6.1.1")
-public final class Neo4jBookmarkManager {
+public sealed interface Neo4jBookmarkManager permits AbstractBookmarkManager, NoopBookmarkManager {
 
 	/**
-	 * @return A default bookmark manager
+	 * {@return the default bookmark manager}
 	 */
-	public static Neo4jBookmarkManager create() {
-		return new Neo4jBookmarkManager(null);
+	static Neo4jBookmarkManager create() {
+		return new DefaultBookmarkManager(null);
 	}
 
 	/**
@@ -51,55 +47,52 @@ public static Neo4jBookmarkManager create() {
 	 * While this class will make sure that the supplier will be accessed in a thread-safe manner,
 	 * it is the caller's duty to provide a thread safe supplier (not changing the seed during a call, etc.).
 	 *
-	 * @param bookmarksSupplier        A supplier for seeding bookmarks, can be null. The supplier is free to provide different
-	 *                                 bookmarks on each call.
+	 * @param bookmarksSupplier A supplier for seeding bookmarks, can be null. The supplier is free to provide different
+	 *                          bookmarks on each call.
 	 * @return A bookmark manager
 	 */
-	public static Neo4jBookmarkManager create(@Nullable Supplier<Set<Bookmark>> bookmarksSupplier) {
-		return new Neo4jBookmarkManager(bookmarksSupplier);
+	static Neo4jBookmarkManager create(@Nullable Supplier<Set<Bookmark>> bookmarksSupplier) {
+		return new DefaultBookmarkManager(bookmarksSupplier);
 	}
 
-	private final Set<Bookmark> bookmarks = new HashSet<>();
-
-	private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
-	private final Lock read = lock.readLock();
-	private final Lock write = lock.writeLock();
-
-	private final Supplier<Set<Bookmark>> bookmarksSupplier;
-
-	@Nullable
-	private ApplicationEventPublisher applicationEventPublisher;
-
-	private Neo4jBookmarkManager(@Nullable Supplier<Set<Bookmark>> bookmarksSupplier) {
-		this.bookmarksSupplier = bookmarksSupplier == null ? () -> Collections.emptySet() : bookmarksSupplier;
+	/**
+	 * Use this bookmark manager at your own risk, it will effectively disable any bookmark management by dropping all
+	 * bookmarks and never  supplying any. In a cluster you will be at a high risk of experiencing stale reads. In a single
+	 * instance it will most likely not make any difference.
+	 * <p>
+	 * In a cluster this can be a sensible approach only and if only you can tolerate stale reads and are not in danger of
+	 * overwriting old data.
+	 *
+	 * @return A noop bookmark manager, dropping new bookmarks immediately, never supplying bookmarks.
+	 * @since 6.1.11
+	 */
+	@API(status = API.Status.STABLE, since = "6.1.11")
+	static Neo4jBookmarkManager noop() {
+		return NoopBookmarkManager.INSTANCE;
 	}
 
-	Collection<Bookmark> getBookmarks() {
-
-		try {
-			read.lock();
-			HashSet<Bookmark> bookmarksToUse = new HashSet<>(this.bookmarks);
-			bookmarksToUse.addAll(bookmarksSupplier.get());
-			return Collections.unmodifiableSet(bookmarksToUse);
-		} finally {
-			read.unlock();
-		}
-	}
+	/**
+	 * No need to introspect this collection ever. The Neo4j driver will together with the cluster figure out which of
+	 * the bookmarks is the most recent one.
+	 *
+	 * @return a collection of currently known bookmarks
+	 */
+	Collection<Bookmark> getBookmarks();
 
-	void updateBookmarks(Collection<Bookmark> usedBookmarks, Bookmark lastBookmark) {
-		try {
-			write.lock();
-			bookmarks.removeAll(usedBookmarks);
-			bookmarks.add(lastBookmark);
-			if (applicationEventPublisher != null) {
-				applicationEventPublisher.publishEvent(new Neo4jBookmarksUpdatedEvent(new HashSet<>(bookmarks)));
-			}
-		} finally {
-			write.unlock();
-		}
-	}
+	/**
+	 * Refreshes the bookmark manager with the {@code lastBookmark} received after the last transaction committed. The
+	 * collection of {@code usedBookmarks} should be removed from the list of known bookmarks.
+	 *
+	 * @param usedBookmarks The collection of bookmarks known prior to the end of a transaction
+	 * @param lastBookmark  The bookmark received after the end of a transaction
+	 */
+	void updateBookmarks(Collection<Bookmark> usedBookmarks, Bookmark lastBookmark);
 
-	void setApplicationEventPublisher(@Nullable ApplicationEventPublisher applicationEventPublisher) {
-		this.applicationEventPublisher = applicationEventPublisher;
+	/**
+	 * A hook for bookmark managers supporting events.
+	 *
+	 * @param applicationEventPublisher An event publisher. If null, no events will be published.
+	 */
+	default void setApplicationEventPublisher(@Nullable ApplicationEventPublisher applicationEventPublisher) {
 	}
 }

src/main/java/org/springframework/data/neo4j/core/transaction/NoopBookmarkManager.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2011-2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.springframework.data.neo4j.core.transaction;
+
+import java.util.Collection;
+import java.util.Collections;
+
+import org.neo4j.driver.Bookmark;
+
+/**
+ * A bookmark manager that drops all bookmarks and never provides any bookmarks.
+ *
+ * @author Michael J. Simons
+ * @soundtrack Helge Schneider - The Last Jazz
+ * @since 7.0
+ */
+enum NoopBookmarkManager implements Neo4jBookmarkManager {
+
+	INSTANCE;
+
+	@Override
+	public Collection<Bookmark> getBookmarks() {
+		return Collections.emptyList();
+	}
+
+	@Override
+	public void updateBookmarks(Collection<Bookmark> usedBookmarks, Bookmark lastBookmark) {
+	}
+}

src/test/java/org/springframework/data/neo4j/core/transaction/AssertableBookmarkManager.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2011-2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.springframework.data.neo4j.core.transaction;
+
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.neo4j.driver.Bookmark;
+
+/**
+ * Avoids mocking / spying the thing.
+ *
+ * @author Michael J. Simons
+ */
+final class AssertableBookmarkManager extends AbstractBookmarkManager {
+
+	boolean getBookmarksCalled = false;
+	final Map<Bookmark, Boolean> updateBookmarksCalled = new HashMap<>();
+
+	@Override
+	public Collection<Bookmark> getBookmarks() {
+		getBookmarksCalled = true;
+		return Collections.emptyList();
+	}
+
+	@Override
+	public void updateBookmarks(Collection<Bookmark> usedBookmarks, Bookmark lastBookmark) {
+		updateBookmarksCalled.put(lastBookmark, true);
+	}
+}