Renamed result#summary to result#consume

Author: Zhen Li

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

@@ -36,7 +36,7 @@
  * @see Session
  * @see Transaction
  * @see StatementResult
- * @see StatementResult#summary()
+ * @see StatementResult#consume()
  * @see ResultSummary
  * @since 1.0
  */

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

@@ -147,5 +147,5 @@ public interface StatementResult extends Iterator<Record>
      *
      * @return a summary for the whole query result.
      */
-    ResultSummary summary();
+    ResultSummary consume();
 }

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

@@ -42,7 +42,7 @@
  *
  * <ul>
  * <li>Read from or discard a result, for instance via
- * {@link StatementResult#next()} or {@link StatementResult#summary()} </li>
+ * {@link StatementResult#next()} or {@link StatementResult#consume()} </li>
  * <li>Explicitly commit/rollback a transaction using blocking {@link Transaction#close()} </li>
  * <li>Close a session using blocking {@link Session#close()}</li>
  * </ul>

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

@@ -51,7 +51,7 @@
  *
  * <ul>
  * <li>Read from or discard a result, for instance via
- * {@link StatementResultCursor#nextAsync()}, {@link StatementResultCursor#summaryAsync()}</li>
+ * {@link StatementResultCursor#nextAsync()}, {@link StatementResultCursor#consumeAsync()}</li>
  * <li>Explicitly commit/rollback a transaction using {@link AsyncTransaction#commitAsync()}, {@link AsyncTransaction#rollbackAsync()}</li>
  * <li>Close a session using {@link AsyncSession#closeAsync()}</li>
  * </ul>

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

@@ -80,7 +80,7 @@ public interface StatementResultCursor
      * @return a {@link CompletionStage} completed with a summary for the whole query result. Stage can also be
      * completed exceptionally if query execution fails.
      */
-    CompletionStage<ResultSummary> summaryAsync();
+    CompletionStage<ResultSummary> consumeAsync();
 
     /**
      * Asynchronously navigate to and retrieve the next {@link Record} in this result. Returned stage can contain

driver/src/main/java/org/neo4j/driver/exceptions/TransactionNestingException.java

@@ -27,4 +27,9 @@ public TransactionNestingException( String message )
     {
         super( message );
     }
+
+    public TransactionNestingException()
+    {
+        this( "You cannot run another query or begin a new transaction in the same session before you've fully consumed the previous run result." );
+    }
 }

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

@@ -23,12 +23,12 @@
 public interface FailableCursor
 {
     /**
-     * Dispose this cursor by discarding all unconsumed records and returning failure if there is any to run and/or pulls.
+     * Discarding all unconsumed records and returning failure if there is any to run and/or pulls.
      */
-    CompletionStage<Throwable> consumeAsync();
+    CompletionStage<Throwable> discardAllFailureAsync();
 
     /**
      * Pulling all unconsumed records into memory and returning failure if there is any to run and/or pulls.
      */
-    CompletionStage<Throwable> failureAsync();
+    CompletionStage<Throwable> pullAllFailureAsync();
 }

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

@@ -112,9 +112,9 @@ public <T> List<T> list( Function<Record, T> mapFunction )
     }
 
     @Override
-    public ResultSummary summary()
+    public ResultSummary consume()
     {
-        return blockingGet( cursor.summaryAsync() );
+        return blockingGet( cursor.consumeAsync() );
     }
 
     @Override

driver/src/main/java/org/neo4j/driver/internal/async/NetworkSession.java

@@ -197,7 +197,7 @@ public CompletionStage<Void> closeAsync()
                 if ( cursor != null )
                 {
                     // there exists a cursor with potentially unconsumed error, try to extract and propagate it
-                    return cursor.consumeAsync();
+                    return cursor.discardAllFailureAsync();
                 }
                 // no result cursor exists so no error exists
                 return completedWithNull();
@@ -255,7 +255,7 @@ private CompletionStage<Connection> acquireConnection( AccessMode mode )
                 return completedWithNull();
             }
             // make sure previous result is fully consumed and connection is released back to the pool
-            return cursor.failureAsync();
+            return cursor.pullAllFailureAsync();
         } ).thenCompose( error ->
         {
             if ( error == null )

driver/src/main/java/org/neo4j/driver/internal/async/ResultCursorsHolder.java

@@ -74,6 +74,6 @@ private static CompletionStage<Throwable> retrieveFailure( CompletionStage<? ext
     {
         return cursorStage
                 .exceptionally( cursor -> null )
-                .thenCompose( cursor -> cursor == null ? completedWithNull() : cursor.consumeAsync() );
+                .thenCompose( cursor -> cursor == null ? completedWithNull() : cursor.discardAllFailureAsync() );
     }
 }

driver/src/main/java/org/neo4j/driver/internal/cursor/AsyncStatementResultCursorImpl.java

@@ -49,9 +49,9 @@ public List<String> keys()
     }
 
     @Override
-    public CompletionStage<ResultSummary> summaryAsync()
+    public CompletionStage<ResultSummary> consumeAsync()
     {
-        return pullAllHandler.summaryAsync();
+        return pullAllHandler.consumeAsync();
     }
 
     @Override
@@ -95,7 +95,7 @@ public CompletionStage<ResultSummary> forEachAsync( Consumer<Record> action )
     {
         CompletableFuture<Void> resultFuture = new CompletableFuture<>();
         internalForEachAsync( action, resultFuture );
-        return resultFuture.thenCompose( ignore -> summaryAsync() );
+        return resultFuture.thenCompose( ignore -> consumeAsync() );
     }
 
     @Override
@@ -111,18 +111,17 @@ public <T> CompletionStage<List<T>> listAsync( Function<Record,T> mapFunction )
     }
 
     @Override
-    public CompletionStage<Throwable> consumeAsync()
+    public CompletionStage<Throwable> discardAllFailureAsync()
     {
-        return summaryAsync().handle( ( summary, error ) -> error );
+        return consumeAsync().handle( ( summary, error ) -> error );
     }
 
     @Override
-    public CompletionStage<Throwable> failureAsync()
+    public CompletionStage<Throwable> pullAllFailureAsync()
     {
-        return pullAllHandler.failureAsync();
+        return pullAllHandler.pullAllFailureAsync();
     }
 
-
     private void internalForEachAsync( Consumer<Record> action, CompletableFuture<Void> resultFuture )
     {
         CompletionStage<Record> recordFuture = nextAsync();

driver/src/main/java/org/neo4j/driver/internal/cursor/DisposableAsyncStatementResultCursor.java

@@ -48,10 +48,10 @@ public List<String> keys()
     }
 
     @Override
-    public CompletionStage<ResultSummary> summaryAsync()
+    public CompletionStage<ResultSummary> consumeAsync()
     {
         isDisposed = true;
-        return delegate.summaryAsync();
+        return delegate.consumeAsync();
     }
 
     @Override
@@ -91,18 +91,18 @@ public <T> CompletionStage<List<T>> listAsync( Function<Record,T> mapFunction )
     }
 
     @Override
-    public CompletionStage<Throwable> consumeAsync()
+    public CompletionStage<Throwable> discardAllFailureAsync()
     {
         isDisposed = true;
-        return delegate.consumeAsync();
+        return delegate.discardAllFailureAsync();
     }
 
     @Override
-    public CompletionStage<Throwable> failureAsync()
+    public CompletionStage<Throwable> pullAllFailureAsync()
     {
         // This one does not dispose the result so that a user could still visit the buffered result after this method call.
         // This also does not assert not disposed so that this method can be called after summary.
-        return delegate.failureAsync();
+        return delegate.pullAllFailureAsync();
     }
 
     private <T> CompletableFuture<T> assertNotDisposed()

driver/src/main/java/org/neo4j/driver/internal/cursor/RxStatementResultCursorImpl.java

@@ -98,22 +98,21 @@ public void cancel()
     }
 
     @Override
-    public CompletionStage<Throwable> consumeAsync()
+    public CompletionStage<Throwable> discardAllFailureAsync()
     {
         // calling this method will enforce discarding record stream and finish running cypher query
         return summaryAsync().thenApply( summary -> (Throwable) null ).exceptionally( error -> error );
     }
 
     @Override
-    public CompletionStage<Throwable> failureAsync()
+    public CompletionStage<Throwable> pullAllFailureAsync()
     {
         if ( isRecordConsumerInstalled() && !isDone() )
         {
-            throw new TransactionNestingException(
-                    "You cannot run another query or begin a new transaction in the same session before you've fully consumed the previous run result." );
+            return CompletableFuture.completedFuture( new TransactionNestingException() );
         }
         // It is safe to discard records as either the streaming has not started at all, or the streaming is fully finished.
-        return consumeAsync();
+        return discardAllFailureAsync();
     }
 
     @Override

driver/src/main/java/org/neo4j/driver/internal/handlers/LegacyPullAllResponseHandler.java

@@ -178,11 +178,11 @@ public synchronized CompletionStage<Record> nextAsync()
         return peekAsync().thenApply( ignore -> dequeueRecord() );
     }
 
-    public synchronized CompletionStage<ResultSummary> summaryAsync()
+    public synchronized CompletionStage<ResultSummary> consumeAsync()
     {
         ignoreRecords = true;
         records.clear();
-        return failureAsync().thenApply( error ->
+        return pullAllFailureAsync().thenApply( error ->
         {
             if ( error != null )
             {
@@ -194,7 +194,7 @@ public synchronized CompletionStage<ResultSummary> summaryAsync()
 
     public synchronized <T> CompletionStage<List<T>> listAsync( Function<Record,T> mapFunction )
     {
-        return failureAsync().thenApply( error ->
+        return pullAllFailureAsync().thenApply( error ->
         {
             if ( error != null )
             {
@@ -210,7 +210,7 @@ public void prePopulateRecords()
         connection.writeAndFlush( PullAllMessage.PULL_ALL, this );
     }
 
-    public synchronized CompletionStage<Throwable> failureAsync()
+    public synchronized CompletionStage<Throwable> pullAllFailureAsync()
     {
         if ( failure != null )
         {

driver/src/main/java/org/neo4j/driver/internal/handlers/PullAllResponseHandler.java

@@ -28,15 +28,15 @@
 
 public interface PullAllResponseHandler extends ResponseHandler
 {
-    CompletionStage<ResultSummary> summaryAsync();
+    CompletionStage<ResultSummary> consumeAsync();
 
     CompletionStage<Record> nextAsync();
 
     CompletionStage<Record> peekAsync();
 
     <T> CompletionStage<List<T>> listAsync( Function<Record, T> mapFunction );
 
-    CompletionStage<Throwable> failureAsync();
+    CompletionStage<Throwable> pullAllFailureAsync();
 
     void prePopulateRecords();
 }

driver/src/main/java/org/neo4j/driver/internal/handlers/pulln/AutoPullResponseHandler.java

@@ -137,7 +137,7 @@ public synchronized CompletionStage<Record> nextAsync()
         return peekAsync().thenApply( ignore -> dequeueRecord() );
     }
 
-    public synchronized CompletionStage<ResultSummary> summaryAsync()
+    public synchronized CompletionStage<ResultSummary> consumeAsync()
     {
         records.clear();
         if ( isDone() )
@@ -162,7 +162,7 @@ public synchronized <T> CompletionStage<List<T>> listAsync( Function<Record,T> m
     }
 
     @Override
-    public synchronized CompletionStage<Throwable> failureAsync()
+    public synchronized CompletionStage<Throwable> pullAllFailureAsync()
     {
         return pullAllAsync().handle( ( ignore, error ) -> error );
     }

driver/src/main/java/org/neo4j/driver/internal/reactive/InternalRxStatementResult.java

@@ -112,7 +112,7 @@ synchronized CompletionStage<RxStatementResultCursor> initCursorFuture()
     }
 
     @Override
-    public Publisher<ResultSummary> summary()
+    public Publisher<ResultSummary> consume()
     {
         return Mono.create( sink -> getCursorFuture().whenComplete( ( cursor, completionError ) -> {
             if ( cursor != null )

driver/src/main/java/org/neo4j/driver/internal/util/ServerVersion.java

@@ -64,7 +64,7 @@ public static ServerVersion version( Driver driver )
     {
         try ( Session session = driver.session() )
         {
-            String versionString = session.readTransaction( tx -> tx.run( "RETURN 1" ).summary().server().version() );
+            String versionString = session.readTransaction( tx -> tx.run( "RETURN 1" ).consume().server().version() );
             return version( versionString );
         }
     }

driver/src/main/java/org/neo4j/driver/reactive/RxStatementResult.java

@@ -45,17 +45,17 @@ public interface RxStatementResult
      * <p>
      * When this publisher is {@linkplain Publisher#subscribe(Subscriber) subscribed}, the query statement is sent to the server and executed.
      * This method does not start the record streaming nor publish query execution error.
-     * To retrieve the execution result, either {@link #records()} or {@link #summary()} can be used.
+     * To retrieve the execution result, either {@link #records()} or {@link #consume()} can be used.
      * {@link #records()} starts record streaming and reports query execution error.
-     * {@link #summary()} skips record streaming and directly reports query execution error.
+     * {@link #consume()} skips record streaming and directly reports query execution error.
      * <p>
      * Consuming of execution result ensures the resources (such as network connections) used by this result is freed correctly.
      * Consuming the keys without consuming the execution result will result in resource leak.
      * To avoid the resource leak, {@link RxSession#close()} (and/or {@link RxTransaction#commit()} and {@link RxTransaction#rollback()}) shall be invoked
      * and subscribed to enforce the result resources created in the {@link RxSession} (and/or {@link RxTransaction}) to be freed correctly.
      * <p>
      * This publisher can be subscribed many times. The keys published stays the same as the keys are buffered.
-     * If this publisher is subscribed after the publisher of {@link #records()} or {@link #summary()},
+     * If this publisher is subscribed after the publisher of {@link #records()} or {@link #consume()},
      * then the buffered keys will be returned.
      * @return a cold publisher of keys.
      */
@@ -83,7 +83,7 @@ public interface RxStatementResult
      * This publisher can only be subscribed by one {@link Subscriber} once.
      * <p>
      * If this publisher is subscribed after {@link #keys()}, then the publish of records is carried out after the arrival of keys.
-     * If this publisher is subscribed after {@link #summary()}, then the publish of records is already cancelled
+     * If this publisher is subscribed after {@link #consume()}, then the publish of records is already cancelled
      * and an empty publisher of zero record will be return.
      * @return a cold unicast publisher of records.
      */
@@ -104,5 +104,5 @@ public interface RxStatementResult
      * This method can be subscribed multiple times. When the {@linkplain ResultSummary summary} arrives, it will be buffered locally for all subsequent calls.
      * @return a cold publisher of result summary which only arrives after all records.
      */
-    Publisher<ResultSummary> summary();
+    Publisher<ResultSummary> consume();
 }

driver/src/test/java/org/neo4j/driver/integration/BookmarkIT.java

@@ -166,7 +166,7 @@ void bookmarkRemainsAfterSuccessfulSessionRun()
         Bookmark bookmark = session.lastBookmark();
         assertBookmarkContainsSingleValue( bookmark );
 
-        session.run( "RETURN 1" ).summary();
+        session.run( "RETURN 1" ).consume();
 
         assertEquals( bookmark, session.lastBookmark() );
     }
@@ -181,7 +181,7 @@ void bookmarkRemainsAfterFailedSessionRun()
         Bookmark bookmark = session.lastBookmark();
         assertBookmarkContainsSingleValue( bookmark );
 
-        assertThrows( ClientException.class, () -> session.run( "RETURN" ).summary() );
+        assertThrows( ClientException.class, () -> session.run( "RETURN" ).consume() );
         assertEquals( bookmark, session.lastBookmark() );
     }
 

driver/src/test/java/org/neo4j/driver/integration/ConnectionHandlingIT.java

@@ -116,7 +116,7 @@ void connectionUsedForSessionRunReturnedToThePoolWhenResultConsumed()
         Connection connection1 = connectionPool.lastAcquiredConnectionSpy;
         verify( connection1, never() ).release();
 
-        result.summary();
+        result.consume();
 
         Connection connection2 = connectionPool.lastAcquiredConnectionSpy;
         assertSame( connection1, connection2 );
@@ -131,7 +131,7 @@ void connectionUsedForSessionRunReturnedToThePoolWhenResultSummaryObtained()
         Connection connection1 = connectionPool.lastAcquiredConnectionSpy;
         verify( connection1, never() ).release();
 
-        ResultSummary summary = result.summary();
+        ResultSummary summary = result.consume();
 
         assertEquals( 5, summary.counters().nodesCreated() );
         Connection connection2 = connectionPool.lastAcquiredConnectionSpy;
@@ -201,7 +201,7 @@ void connectionUsedForSessionRunReturnedToThePoolWhenServerErrorDuringResultFetc
         Connection connection1 = connectionPool.lastAcquiredConnectionSpy;
         verify( connection1, never() ).release();
 
-        assertThrows( ClientException.class, result::summary );
+        assertThrows( ClientException.class, result::consume );
 
         Connection connection2 = connectionPool.lastAcquiredConnectionSpy;
         assertSame( connection1, connection2 );
@@ -355,7 +355,7 @@ void resultSummaryShouldReleaseConnectionUsedBySessionRun() throws Throwable
         Connection connection1 = connectionPool.lastAcquiredConnectionSpy;
         assertNull( connection1 );
 
-        StepVerifier.create( Mono.from( res.summary() ) ).expectNextCount( 1 ).verifyComplete();
+        StepVerifier.create( Mono.from( res.consume() ) ).expectNextCount( 1 ).verifyComplete();
 
         Connection connection2 = connectionPool.lastAcquiredConnectionSpy;
         assertNotSame( connection1, connection2 );

driver/src/test/java/org/neo4j/driver/integration/ConnectionPoolIT.java

@@ -173,7 +173,7 @@ private static void startAndCloseTransactions( Driver driver, int txCount )
         {
             for ( StatementResult result : results )
             {
-                result.summary();
+                result.consume();
             }
             for ( Transaction tx : transactions )
             {