Clarify semantics of peek

Author: boggle

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

@@ -246,19 +246,22 @@ public Record single()
     public Record peek()
     {
         assertOpen();
-        Record nextRecord = recordBuffer.peek();
-        if ( nextRecord != null )
-        {
-            return nextRecord;
-        }
-        else if ( done )
-        {
-            return null;
-        }
-        else
+
+        while ( true )
         {
             tryFetching();
-            return peek();
+            Record nextRecord = recordBuffer.peek();
+            if ( nextRecord == null )
+            {
+                if ( done )
+                {
+                    throw new NoSuchRecordException( "Cannot peek past the last record" );
+                }
+            }
+            else
+            {
+                return nextRecord;
+            }
         }
     }
 

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

@@ -70,6 +70,8 @@ public interface StatementResult extends Iterator<Record>
 
     /**
      * Navigate to and retrieve the next {@link Record} in this result.
+     *
+     * @throws NoSuchRecordException if there is no record left in the stream
      * @return the next record
      */
     @Override Record next();
@@ -78,7 +80,7 @@ public interface StatementResult extends Iterator<Record>
      * Return the first record in the result, failing if there is not exactly
      * one record left in the stream
      *
-     * Calling this method exhausts the result, even when failing.
+     * Calling this method always exhausts the result, even when failing.
      *
      * @return the first and only record in the stream
      * @throws NoSuchRecordException if there is not exactly one record left in the stream
@@ -88,7 +90,8 @@ public interface StatementResult extends Iterator<Record>
     /**
      * Investigate the next upcoming record without moving forward in the result.
      *
-     * @return the next record, or null if there is no next record
+     * @throws NoSuchRecordException if there is no record left in the stream
+     * @return the next record
      */
     Record peek();
 

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

@@ -334,18 +334,23 @@ public void shouldPeekIntoTheFuture()
         result.next();
 
         // THEN
-        assertNull( result.peek() );
+        expectedException.expect( NoSuchRecordException.class );
+
+        // WHEN
+        result.peek();
     }
 
     @Test
     public void shouldNotPeekIntoTheFutureWhenResultIsEmpty()
     {
         // GIVEN
         StatementResult result = createResult( 0 );
-        Record future = result.peek();
+
+        // THEN
+        expectedException.expect( NoSuchRecordException.class );
 
         // WHEN
-        assertNull( future );
+        Record future = result.peek();
     }
 
     private StatementResult createResult( int numberOfRecords )