Clarify semantics of single

Author: boggle

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

@@ -222,27 +222,24 @@ else if ( done )
     @Override
     public Record single()
     {
-        if( position > 0 )
-        {
-            throw new NoSuchRecordException(
-                    "Cannot retrieve the first record, because other operations have already used the first record. " +
-                    "Please ensure you are not calling `first` multiple times, or are mixing it with calls " +
-                    "to `next`, `single`, `list` or any other method that changes the position of the cursor." );
-        }
-
         if( !hasNext() )
         {
-            throw new NoSuchRecordException( "Cannot retrieve the first record, because this result is empty." );
+            throw new NoSuchRecordException( "Cannot retrieve a single record, because this result is empty." );
         }
 
-        Record first = next();
-        if( hasNext() )
+        Record single = next();
+        boolean hasMany = hasNext();
+
+        consume();
+
+        if( hasMany )
         {
             throw new NoSuchRecordException( "Expected a result with a single record, but this result contains at least one more. " +
                     "Ensure your query returns only one record, or use `first` instead of `single` if " +
                     "you do not care about the number of records in the result." );
         }
-        return first;
+
+        return single;
     }
 
     @Override

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

@@ -76,10 +76,12 @@ public interface StatementResult extends Iterator<Record>
 
     /**
      * Return the first record in the result, failing if there is not exactly
-     * one record, or if this result has already been used to move past the first record.
+     * one record left in the stream
+     *
+     * Calling this method exhausts the result, even when failing.
      *
      * @return the first and only record in the stream
-     * @throws NoSuchRecordException if there is not exactly one record in the stream, or if the cursor has been used already
+     * @throws NoSuchRecordException if there is not exactly one record left in the stream
      */
     Record single() throws NoSuchRecordException;
 
@@ -103,7 +105,7 @@ public interface StatementResult extends Iterator<Record>
      * Calling this method exhausts the result.
      *
      * @throws ClientException if the result has already been used
-     * @return list of all immutable records
+     * @return list of all remaining immutable records
      */
     List<Record> list();
 
@@ -123,7 +125,7 @@ public interface StatementResult extends Iterator<Record>
      * @param mapFunction a function to map from Value to T. See {@link Values} for some predefined functions, such
      * as {@link Values#ofBoolean()}, {@link Values#ofList(Function)}.
      * @param <T> the type of result list elements
-     * @return list of all mapped immutable records
+     * @return list of all mapped remaining immutable records
      */
     <T> List<T> list( Function<Record, T> mapFunction );
 
@@ -141,4 +143,4 @@ public interface StatementResult extends Iterator<Record>
      * @return a summary for the whole query
      */
     ResultSummary consume();
-}
+}

driver/src/test/java/org/neo4j/driver/internal/InternalStatementResultTest.java

@@ -19,27 +19,27 @@
 package org.neo4j.driver.internal;
 
 
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedList;
+import java.util.List;
+
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.mockito.invocation.InvocationOnMock;
 import org.mockito.stubbing.Answer;
 
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.LinkedList;
-import java.util.List;
-
 import org.neo4j.driver.internal.spi.Connection;
 import org.neo4j.driver.internal.value.NullValue;
-import org.neo4j.driver.v1.Statement;
-import org.neo4j.driver.v1.StatementResult;
-import org.neo4j.driver.v1.util.Pair;
 import org.neo4j.driver.v1.Record;
 import org.neo4j.driver.v1.Records;
+import org.neo4j.driver.v1.Statement;
+import org.neo4j.driver.v1.StatementResult;
 import org.neo4j.driver.v1.Value;
 import org.neo4j.driver.v1.exceptions.ClientException;
 import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
+import org.neo4j.driver.v1.util.Pair;
 
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.collection.IsCollectionWithSize.hasSize;
@@ -48,8 +48,10 @@
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
 import static org.mockito.Mockito.doAnswer;
 import static org.mockito.Mockito.mock;
+
 import static org.neo4j.driver.v1.Values.value;
 
 public class InternalStatementResultTest
@@ -192,6 +194,46 @@ public void singleShouldThrowOnEmptyResult()
         createResult( 0 ).single();
     }
 
+    @Test
+    public void singleShouldThrowOnConsumedResult()
+    {
+        // Expect
+        expectedException.expect( NoSuchRecordException.class );
+
+        // When
+        StatementResult result = createResult( 2 );
+        result.consume();
+        result.single();
+    }
+
+    @Test
+    public void singleShouldNotThrowOnPartiallyConsumedResult()
+    {
+        // Given
+        StatementResult result = createResult( 2 );
+        result.next();
+
+        // When + Then
+        assertNotNull( result.single() );
+    }
+
+    @Test
+    public void singleShouldConsumeIfFailing()
+    {
+        // Given
+        StatementResult result = createResult( 2 );
+
+        try
+        {
+            result.single();
+            fail( "Exception expected" );
+        }
+        catch ( NoSuchRecordException e )
+        {
+            assertFalse( result.hasNext() );
+        }
+    }
+
     @Test
     public void retainShouldWorkAsExpected()
     {