Bookmark in BEGIN

Author: technige

driver/src/main/java/org/neo4j/driver/internal/InternalTransaction.java renamed to driver/src/main/java/org/neo4j/driver/internal/ExplicitTransaction.java

@@ -34,10 +34,13 @@
 import org.neo4j.driver.v1.exceptions.Neo4jException;
 import org.neo4j.driver.v1.types.TypeSystem;
 
+import static java.util.Collections.emptyMap;
+import static java.util.Collections.singletonMap;
+
 import static org.neo4j.driver.v1.Values.ofValue;
 import static org.neo4j.driver.v1.Values.value;
 
-public class InternalTransaction implements Transaction
+class ExplicitTransaction implements Transaction
 {
     private enum State
     {
@@ -68,13 +71,26 @@ private enum State
 
     private State state = State.ACTIVE;
 
-    public InternalTransaction( Connection conn, Runnable cleanup )
+    ExplicitTransaction( Connection conn, Runnable cleanup )
+    {
+        this( conn, cleanup, null );
+    }
+
+    ExplicitTransaction( Connection conn, Runnable cleanup, String bookmark )
     {
         this.conn = conn;
         this.cleanup = cleanup;
 
-        // Note there is no sync here, so this will just value queued locally
-        conn.run( "BEGIN", Collections.<String, Value>emptyMap(), StreamCollector.NO_OP );
+        final Map<String, Value> parameters;
+        if ( bookmark == null )
+        {
+            parameters = emptyMap();
+        }
+        else
+        {
+            parameters = singletonMap( "bookmark", value( bookmark ) );
+        }
+        conn.run( "BEGIN", parameters, StreamCollector.NO_OP );
         conn.discardAll();
     }
 

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

@@ -52,7 +52,7 @@ public void run()
         }
     };
 
-    private InternalTransaction currentTransaction;
+    private ExplicitTransaction currentTransaction;
     private AtomicBoolean isOpen = new AtomicBoolean( true );
 
     public InternalSession( Connection connection, Logger logger )
@@ -152,17 +152,24 @@ public String server()
 
     @Override
     public Transaction beginTransaction()
+    {
+        return beginTransaction( null );
+    }
+
+    @Override
+    public Transaction beginTransaction( String bookmark )
     {
         ensureConnectionIsValidBeforeOpeningTransaction();
-        currentTransaction = new InternalTransaction( connection, txCleanup );
-        connection.onError( new Runnable() {
+        currentTransaction = new ExplicitTransaction( connection, txCleanup, bookmark );
+        connection.onError( new Runnable()
+        {
             @Override
             public void run()
             {
-                //must check if transaction has been closed
-                if (currentTransaction != null)
+                // must check if transaction has been closed
+                if ( currentTransaction != null )
                 {
-                    if( connection.hasUnrecoverableErrors() )
+                    if ( connection.hasUnrecoverableErrors() )
                     {
                         currentTransaction.markToClose();
                     }
@@ -172,7 +179,7 @@ public void run()
                     }
                 }
             }
-        });
+        } );
         return currentTransaction;
     }
 

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

@@ -1,41 +1,57 @@
 /**
  * Copyright (c) 2002-2016 "Neo Technology,"
  * Network Engine for Objects in Lund AB [http://neotechnology.com]
- *
+ * <p>
  * This file is part of Neo4j.
- *
+ * <p>
  * 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
- *
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
  * 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.v1;
 
 import org.neo4j.driver.v1.util.Resource;
 
 /**
- * A live session with a Neo4j instance.
+ * A <em>Session</em> hosts a series of {@linkplain Transaction transactions}
+ * carried out against a database. Within the database, all statements are
+ * carried out within a transaction. Within application code, however, it is
+ * not always necessary to explicitly {@link #beginTransaction() begin a
+ * transaction}. If a statement is {@link #run} directly against a {@link
+ * Session}, the server will automatically <code>BEGIN</code> and
+ * <code>COMMIT</code> that statement within its own transaction. This type
+ * of transaction is known as an <em>autocommit transaction</em>.
  * <p>
- * Sessions serve two purposes. For one, they are an optimization. By keeping state on the database side, we can
- * avoid re-transmitting certain metadata over and over.
+ * Explicit transactions allow multiple statements to be committed as part of
+ * a single atomic operation and can be rolled back if necessary. They can also
+ * be used to ensure <em>causal consistency</em>, meaning that an application
+ * can run a series of queries on different members of a cluster, while
+ * ensuring that each query sees the state of graph at least as up-to-date as
+ * the graph seen by the previous query. For more on causal consistency, see
+ * the Neo4j clustering manual.
  * <p>
- * Sessions also serve a role in transaction isolation and ordering semantics. Neo4j requires
- * "sticky sessions", meaning all requests within one session must always go to the same Neo4j instance.
+ * Typically, a session will wrap a TCP connection. Such a connection will be
+ * acquired from a connection pool and released back there when the session is
+ * destroyed. One connection can therefore be adopted by many sessions,
+ * although by only one at a time. Application code should never need to deal
+ * directly with connection management.
  * <p>
- * Session objects are not thread safe, if you want to run concurrent operations against the database,
- * simply create multiple sessions objects.
- *
- * <h2>Important note on semantics</h2>
- *
- * Please see the section under {@link StatementRunner} for an important overview of the guarantees
- * the session gives you around when statements are executed.
+ * A session inherits its destination address and permissions from its
+ * underlying connection. This means that one session may only ever target one
+ * machine within a cluster and does not support re-authentication. To achieve
+ * otherwise requires creation of a separate session.
+ * <p>
+ * Similarly, multiple sessions should be used when working with concurrency;
+ * session implementations are generally not thread safe.
  *
  * @since 1.0
  */
@@ -44,20 +60,25 @@ public interface Session extends Resource, StatementRunner
     String LOG_NAME = "session";
 
     /**
-     * Begin a new transaction in this session. A session can have at most one transaction running at a time, if you
-     * want to run multiple concurrent transactions, you should use multiple concurrent sessions.
-     * <p>
-     * All data operations in Neo4j are transactional. However, for convenience we provide a {@link #run(String)}
-     * method directly on this session interface as well. When you use that method, your statement automatically gets
-     * wrapped in a transaction.
-     * <p>
-     * If you want to run multiple statements in the same transaction, you should wrap them in a transaction using this
-     * method.
+     * Begin a new <em>explicit {@linkplain Transaction transaction}</em>. At
+     * most one transaction may exist in a session at any point in time. To
+     * maintain multiple concurrent transactions, use multiple concurrent
+     * sessions.
      *
-     * @return a new transaction
+     * @return a new {@link Transaction}
      */
     Transaction beginTransaction();
 
+    /**
+     * Begin a new <em>explicit {@linkplain Transaction transaction}</em>,
+     * requiring that the server hosting is at least as up-to-date as the
+     * transaction referenced by the supplied <em>bookmark</em>.
+     *
+     * @param bookmark a reference to a previous transaction
+     * @return a new {@link Transaction}
+     */
+    Transaction beginTransaction( String bookmark );
+
     /**
      * Reset the current session. This sends an immediate RESET signal to the server which both interrupts
      * any statement that is currently executing and ignores any subsequently queued statements. Following

driver/src/test/java/org/neo4j/driver/internal/InternalTransactionTest.java renamed to driver/src/test/java/org/neo4j/driver/internal/ExplicitTransactionTest.java

@@ -33,7 +33,7 @@
 import static org.mockito.Mockito.verifyNoMoreInteractions;
 import static org.mockito.Mockito.when;
 
-public class InternalTransactionTest
+public class ExplicitTransactionTest
 {
     @Test
     public void shouldRollbackOnImplicitFailure() throws Throwable
@@ -42,7 +42,7 @@ public void shouldRollbackOnImplicitFailure() throws Throwable
         Connection conn = mock( Connection.class );
         when( conn.isOpen() ).thenReturn( true );
         Runnable cleanup = mock( Runnable.class );
-        InternalTransaction tx = new InternalTransaction( conn, cleanup );
+        ExplicitTransaction tx = new ExplicitTransaction( conn, cleanup );
 
         // When
         tx.close();
@@ -66,7 +66,7 @@ public void shouldRollbackOnExplicitFailure() throws Throwable
         Connection conn = mock( Connection.class );
         when( conn.isOpen() ).thenReturn( true );
         Runnable cleanup = mock( Runnable.class );
-        InternalTransaction tx = new InternalTransaction( conn, cleanup );
+        ExplicitTransaction tx = new ExplicitTransaction( conn, cleanup );
 
         // When
         tx.failure();
@@ -92,7 +92,7 @@ public void shouldCommitOnSuccess() throws Throwable
         Connection conn = mock( Connection.class );
         when( conn.isOpen() ).thenReturn( true );
         Runnable cleanup = mock( Runnable.class );
-        InternalTransaction tx = new InternalTransaction( conn, cleanup );
+        ExplicitTransaction tx = new ExplicitTransaction( conn, cleanup );
 
         // When
         tx.success();

driver/src/test/java/org/neo4j/driver/v1/util/TestNeo4jSession.java

@@ -106,6 +106,12 @@ public Transaction beginTransaction()
         return realSession.beginTransaction();
     }
 
+    @Override
+    public Transaction beginTransaction( String bookmark )
+    {
+        return realSession.beginTransaction( bookmark );
+    }
+
     @Override
     public void reset()
     {