Merge pull request #619 from zhenlineo/2.0-sys-bookmark

System database bookmarks.

Author: zhenlineo

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

@@ -21,6 +21,7 @@
 import java.util.Map;
 
 import org.neo4j.driver.async.AsyncSession;
+import org.neo4j.driver.internal.Bookmark;
 import org.neo4j.driver.util.Resource;
 
 /**
@@ -212,7 +213,7 @@ public interface Session extends Resource, StatementRunner
      *
      * @return a reference to a previous transaction
      */
-    String lastBookmark();
+    Bookmark lastBookmark();
 
     /**
      * Reset the current session. This sends an immediate RESET signal to the server which both interrupts

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

@@ -19,11 +19,11 @@
 package org.neo4j.driver;
 
 import java.util.Arrays;
-import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
 
 import org.neo4j.driver.async.AsyncSession;
+import org.neo4j.driver.internal.Bookmark;
 import org.neo4j.driver.reactive.RxSession;
 
 import static java.util.Objects.requireNonNull;
@@ -36,7 +36,7 @@ public class SessionConfig
 {
     private static final SessionConfig EMPTY = builder().build();
 
-    private final List<String> bookmarks;
+    private final Iterable<Bookmark> bookmarks;
     private final AccessMode defaultAccessMode;
     private final String database;
 
@@ -85,7 +85,7 @@ public static SessionConfig forDatabase( String database )
      *
      * @return the initial bookmarks.
      */
-    public List<String> bookmarks()
+    public Iterable<Bookmark> bookmarks()
     {
         return bookmarks;
     }
@@ -143,7 +143,7 @@ public String toString()
      */
     public static class Builder
     {
-        private List<String> bookmarks = null;
+        private Iterable<Bookmark> bookmarks = null;
         private AccessMode defaultAccessMode = AccessMode.WRITE;
         private String database = null;
 
@@ -164,11 +164,10 @@ private Builder()
          * are permitted, and indicate that the bookmarks do not exist or are unknown.
          * @return this builder.
          */
-        public Builder withBookmarks( String... bookmarks )
+        public Builder withBookmarks( Bookmark... bookmarks )
         {
             if ( bookmarks == null )
             {
-                // TODO bookmarks should not be null
                 this.bookmarks = null;
             }
             else
@@ -189,7 +188,7 @@ public Builder withBookmarks( String... bookmarks )
          * are permitted, and indicate that the bookmarks do not exist or are unknown.
          * @return this builder
          */
-        public Builder withBookmarks( List<String> bookmarks )
+        public Builder withBookmarks( Iterable<Bookmark> bookmarks )
         {
             this.bookmarks = bookmarks;
             return this;
@@ -229,7 +228,11 @@ public Builder withDatabase( String database )
                 // Disallow users to use bolt internal value directly. To users, this is totally an illegal database name.
                 throw new IllegalArgumentException( String.format( "Illegal database name '%s'.", database ) );
             }
-            this.database = database;
+            // The database name is normalized to lowercase on the server side.
+            // The client in theory shall not perform any normalization at all.
+            // However as this name is also used in routing table registry as the map's key to find the routing table for the given database,
+            // to avoid multiple routing tables for the same database, we perform a client side normalization.
+            this.database = database.toLowerCase();
             return this;
         }
 

driver/src/main/java/org/neo4j/driver/async/AsyncSession.java

@@ -29,6 +29,7 @@
 import org.neo4j.driver.Transaction;
 import org.neo4j.driver.TransactionConfig;
 import org.neo4j.driver.Values;
+import org.neo4j.driver.internal.Bookmark;
 
 /**
  * Provides a context of work for database interactions.
@@ -301,7 +302,7 @@ public interface AsyncSession extends AsyncStatementRunner
      *
      * @return a reference to a previous transaction
      */
-    String lastBookmark();
+    Bookmark lastBookmark();
 
     /**
      * Signal that you are done using this session. In the default driver usage, closing and accessing sessions is

driver/src/main/java/org/neo4j/driver/internal/Bookmark.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2002-2019 "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.internal;
+
+import java.io.Serializable;
+
+/**
+ * Causal chaining is carried out by passing bookmarks between transactions.
+ *
+ * When starting a session with initial bookmarks, the first transaction will be ensured to run at least after
+ * the database is as up-to-date as the latest transaction referenced by the supplied bookmarks.
+ *
+ * Within a session, bookmark propagation is carried out automatically.
+ * Thus all transactions in a session including explicit and implicit transactions are ensured to be carried out one after another.
+ *
+ * To opt out of this mechanism for unrelated units of work, applications can use multiple sessions.
+ */
+public interface Bookmark extends Serializable
+{
+}

driver/src/main/java/org/neo4j/driver/internal/BookmarksHolder.java renamed to driver/src/main/java/org/neo4j/driver/internal/BookmarkHolder.java

@@ -18,31 +18,23 @@
  */
 package org.neo4j.driver.internal;
 
-public interface BookmarksHolder
+public interface BookmarkHolder
 {
-    Bookmarks getBookmarks();
+    InternalBookmark getBookmark();
 
-    void setBookmarks( Bookmarks bookmarks );
+    void setBookmark( InternalBookmark bookmark );
 
-    String lastBookmark();
-
-    BookmarksHolder NO_OP = new BookmarksHolder()
+    BookmarkHolder NO_OP = new BookmarkHolder()
     {
         @Override
-        public Bookmarks getBookmarks()
-        {
-            return Bookmarks.empty();
-        }
-
-        @Override
-        public void setBookmarks( Bookmarks bookmarks )
+        public InternalBookmark getBookmark()
         {
+            return InternalBookmark.empty();
         }
 
         @Override
-        public String lastBookmark()
+        public void setBookmark( InternalBookmark bookmark )
         {
-            return null;
         }
     };
 }