Update bookmarks

neo4j · May 1, 2022 · 7761d3c · 7761d3c
1 parent b1bf3fa
commit 7761d3c
Show file tree

Hide file tree

Showing 90 changed files with 1,075 additions and 844 deletions.
diff --git a/driver/clirr-ignored-differences.xml b/driver/clirr-ignored-differences.xml
@@ -304,4 +304,28 @@
         <method>org.neo4j.driver.Value parameters(java.util.Map)</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/Bookmark</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.Bookmark from(java.lang.String)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Bookmark</className>
+        <differenceType>7012</differenceType>
+        <method>java.lang.String value()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Session</className>
+        <differenceType>7012</differenceType>
+        <method>java.util.Set lastBookmarks()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/async/AsyncSession</className>
+        <differenceType>7012</differenceType>
+        <method>java.util.Set lastBookmarks()</method>
+    </difference>
+
 </differences>
diff --git a/driver/src/main/java/org/neo4j/driver/Bookmark.java b/driver/src/main/java/org/neo4j/driver/Bookmark.java
@@ -18,6 +18,7 @@
  */
 package org.neo4j.driver;
 
+import java.util.Collections;
 import java.util.Set;
 
 import org.neo4j.driver.internal.InternalBookmark;
@@ -35,17 +36,39 @@
  */
 public interface Bookmark
 {
+    /**
+     * Returns a string that this bookmark instance identifies.
+     *
+     * @return a string that this bookmark instance identifies.
+     */
+    String value();
+
     /**
      * Returns a read-only set of bookmark strings that this bookmark instance identifies.
+     *
      * @return a read-only set of bookmark strings that this bookmark instance identifies.
      */
+    @Deprecated
     Set<String> values();
 
     /**
-     * Reconstruct bookmark from \bookmarks string values.
+     * Reconstruct bookmark from bookmark string value.
+     *
+     * @param value value obtained from a previous bookmark.
+     * @return A bookmark.
+     */
+    static Bookmark from( String value )
+    {
+        return InternalBookmark.parse( Collections.singleton( value ) );
+    }
+
+    /**
+     * Reconstruct bookmark from bookmarks string values.
+     *
      * @param values values obtained from a previous bookmark.
      * @return A bookmark.
      */
+    @Deprecated
     static Bookmark from( Set<String> values )
     {
         return InternalBookmark.parse( values );
@@ -55,5 +78,6 @@ static Bookmark from( Set<String> values )
      * Return true if the bookmark is empty.
      * @return true if the bookmark is empty.
      */
+    @Deprecated
     boolean isEmpty();
 }
diff --git a/driver/src/main/java/org/neo4j/driver/Session.java b/driver/src/main/java/org/neo4j/driver/Session.java
@@ -19,6 +19,7 @@
 package org.neo4j.driver;
 
 import java.util.Map;
+import java.util.Set;
 import java.util.function.Consumer;
 
 import org.neo4j.driver.async.AsyncSession;
@@ -317,18 +318,23 @@ default void executeWriteWithoutResult( Consumer<TransactionContext> contextCons
     Result run(Query query, TransactionConfig config );
 
     /**
-     * Return the bookmark received following the last completed
-     * {@linkplain Transaction transaction}. If no bookmark was received
-     * or if this transaction was rolled back, the bookmark value will
-     * be null.
+     * Return the bookmark received following the last completed {@linkplain Transaction transaction}. If no bookmark was received or if this transaction was
+     * rolled back, the bookmark value will be null.
      *
      * @return a reference to a previous transaction
      */
+    @Deprecated
     Bookmark lastBookmark();
 
     /**
-     * Signal that you are done using this session. In the default driver usage, closing and accessing sessions is
-     * very low cost.
+     * Return a set of bookmarks known by this session.
+     *
+     * @return a set of bookmarks.
+     */
+    Set<Bookmark> lastBookmarks();
+
+    /**
+     * Signal that you are done using this session. In the default driver usage, closing and accessing sessions is very low cost.
      */
     @Override
     void close();

diff --git a/driver/src/main/java/org/neo4j/driver/async/AsyncSession.java b/driver/src/main/java/org/neo4j/driver/async/AsyncSession.java
@@ -19,6 +19,7 @@
 package org.neo4j.driver.async;
 
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.Executor;
@@ -389,8 +390,16 @@ default <T> CompletionStage<T> executeWriteAsync( AsyncTransactionCallback<Compl
      *
      * @return a reference to a previous transaction
      */
+    @Deprecated
     Bookmark lastBookmark();
 
+    /**
+     * Return a set of bookmarks known by this session.
+     *
+     * @return a set of bookmarks.
+     */
+    Set<Bookmark> lastBookmarks();
+
     /**
      * Signal that you are done using this session. In the default driver usage, closing and accessing sessions is
      * very low cost.

diff --git a/...neo4j/driver/internal/BookmarkHolder.java → ...eo4j/driver/internal/BookmarksHolder.java b/...neo4j/driver/internal/BookmarkHolder.java → ...eo4j/driver/internal/BookmarksHolder.java
@@ -18,20 +18,23 @@
  */
 package org.neo4j.driver.internal;
 
+import java.util.Collections;
+import java.util.Set;
+
 import org.neo4j.driver.Bookmark;
 
-public interface BookmarkHolder
+public interface BookmarksHolder
 {
-    Bookmark getBookmark();
+    Set<Bookmark> getBookmarks();
 
     void setBookmark( Bookmark bookmark );
 
-    BookmarkHolder NO_OP = new BookmarkHolder()
+    BookmarksHolder NO_OP = new BookmarksHolder()
     {
         @Override
-        public Bookmark getBookmark()
+        public Set<Bookmark> getBookmarks()
         {
-            return InternalBookmark.empty();
+            return Collections.emptySet();
         }
 
         @Override

diff --git a/...river/internal/DefaultBookmarkHolder.java → ...iver/internal/DefaultBookmarksHolder.java b/...river/internal/DefaultBookmarkHolder.java → ...iver/internal/DefaultBookmarksHolder.java
@@ -18,37 +18,41 @@
  */
 package org.neo4j.driver.internal;
 
+import java.util.Collections;
+import java.util.Set;
+
 import org.neo4j.driver.Bookmark;
 
 /**
  * @since 2.0
  */
-public class DefaultBookmarkHolder implements BookmarkHolder
+public class DefaultBookmarksHolder implements BookmarksHolder
 {
-    private volatile Bookmark bookmark;
+    private volatile Set<Bookmark> bookmarks;
 
-    public DefaultBookmarkHolder()
+    // for testing only
+    public DefaultBookmarksHolder()
     {
-        this( InternalBookmark.empty() );
+        this( Collections.emptySet() );
     }
 
-    public DefaultBookmarkHolder( Bookmark bookmark )
+    public DefaultBookmarksHolder( Set<Bookmark> bookmarks )
     {
-        this.bookmark = bookmark;
+        this.bookmarks = bookmarks;
     }
 
     @Override
-    public Bookmark getBookmark()
+    public Set<Bookmark> getBookmarks()
     {
-        return bookmark;
+        return bookmarks;
     }
 
     @Override
     public void setBookmark( Bookmark bookmark )
     {
         if ( bookmark != null && !bookmark.isEmpty() )
         {
-            this.bookmark = bookmark;
+            bookmarks = Collections.singleton( bookmark );
         }
     }
 }
diff --git a/driver/src/main/java/org/neo4j/driver/internal/InternalBookmark.java b/driver/src/main/java/org/neo4j/driver/internal/InternalBookmark.java
@@ -117,6 +117,12 @@ public boolean isEmpty()
         return values.isEmpty();
     }
 
+    @Override
+    public String value()
+    {
+        return values.isEmpty() ? null : values.iterator().next();
+    }
+
     @Override
     public Set<String> values()
     {

diff --git a/driver/src/main/java/org/neo4j/driver/internal/InternalSession.java b/driver/src/main/java/org/neo4j/driver/internal/InternalSession.java
@@ -18,7 +18,9 @@
  */
 package org.neo4j.driver.internal;
 
+import java.util.HashSet;
 import java.util.Map;
+import java.util.Set;
 
 import org.neo4j.driver.AccessMode;
 import org.neo4j.driver.Bookmark;
@@ -140,7 +142,13 @@ public <T> T executeWrite( TransactionCallback<T> callback, TransactionConfig co
     @Override
     public Bookmark lastBookmark()
     {
-        return session.lastBookmark();
+        return InternalBookmark.from( session.lastBookmarks() );
+    }
+
+    @Override
+    public Set<Bookmark> lastBookmarks()
+    {
+        return new HashSet<>( session.lastBookmarks() );
     }
 
     private <T> T transaction( AccessMode mode, TransactionWork<T> work, TransactionConfig config )
@@ -149,19 +157,21 @@ private <T> T transaction( AccessMode mode, TransactionWork<T> work, Transaction
         // caller thread will also be the one who sleeps between retries;
         // it is unsafe to execute retries in the event loop threads because this can cause a deadlock
         // event loop thread will bock and wait for itself to read some data
-        return session.retryLogic().retry( () -> {
-            try ( Transaction tx = beginTransaction( mode, config ) )
-            {
-
-                T result = work.execute( tx );
-                if ( tx.isOpen() )
+        return session.retryLogic().retry(
+                () ->
                 {
-                    // commit tx if a user has not explicitly committed or rolled back the transaction
-                    tx.commit();
-                }
-                return result;
-            }
-        } );
+                    try ( Transaction tx = beginTransaction( mode, config ) )
+                    {
+
+                        T result = work.execute( tx );
+                        if ( tx.isOpen() )
+                        {
+                            // commit tx if a user has not explicitly committed or rolled back the transaction
+                            tx.commit();
+                        }
+                        return result;
+                    }
+                } );
     }
 
     private Transaction beginTransaction( AccessMode mode, TransactionConfig config )

diff --git a/...iver/internal/ReadOnlyBookmarkHolder.java → ...ver/internal/ReadOnlyBookmarksHolder.java b/...iver/internal/ReadOnlyBookmarkHolder.java → ...ver/internal/ReadOnlyBookmarksHolder.java
@@ -18,24 +18,26 @@
  */
 package org.neo4j.driver.internal;
 
+import java.util.Set;
+
 import org.neo4j.driver.Bookmark;
 
 /**
  * @since 2.0
  */
-public class ReadOnlyBookmarkHolder implements BookmarkHolder
+public class ReadOnlyBookmarksHolder implements BookmarksHolder
 {
-    private final Bookmark bookmark;
+    private final Set<Bookmark> bookmarks;
 
-    public ReadOnlyBookmarkHolder( Bookmark bookmark )
+    public ReadOnlyBookmarksHolder( Set<Bookmark> bookmarks )
     {
-        this.bookmark = bookmark;
+        this.bookmarks = bookmarks;
     }
 
     @Override
-    public Bookmark getBookmark()
+    public Set<Bookmark> getBookmarks()
     {
-        return bookmark;
+        return bookmarks;
     }
 
     @Override