Merge pull request #118 from jakewins/1.0-single

single and first return record

Author: jakewins

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

@@ -28,7 +28,7 @@
 import org.neo4j.driver.v1.ResultSummary;
 import org.neo4j.driver.v1.Value;
 import org.neo4j.driver.v1.exceptions.ClientException;
-import org.neo4j.driver.v1.exceptions.NoRecordException;
+import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
 import static java.lang.String.format;
 import static java.util.Collections.emptyList;
@@ -100,7 +100,7 @@ public Record record()
         }
         else
         {
-            throw new NoRecordException(
+            throw new NoSuchRecordException(
                 "In order to access the fields of a record in a result, " +
                 "you must first call next() to point the result to the next record in the result stream."
             );
@@ -176,16 +176,38 @@ else if ( records == 0) {
     }
 
     @Override
-    public boolean first()
+    public Record first()
     {
-        long pos = position();
-        return pos < 0 ? next() : pos == 0;
+        if( position() > 0 )
+        {
+            throw new NoSuchRecordException( "Cannot retrieve the first record, because this result cursor has been moved already. " +
+                                             "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( position == 0 )
+        {
+            return record();
+        }
+
+        if( !next() )
+        {
+            throw new NoSuchRecordException( "Cannot retrieve the first record, because this result is empty." );
+        }
+        return record();
     }
 
     @Override
-    public boolean single()
+    public Record single()
     {
-        return first() && atEnd();
+        Record first = first();
+        if( !iter.hasNext() )
+        {
+            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;
     }
 
     @Override
@@ -208,7 +230,7 @@ public <T> List<T> list( Function<RecordAccessor, T> mapFunction )
             assertOpen();
             return emptyList();
         }
-        else if ( first() )
+        else if ( position == 0 || ( position == -1 && next() ) )
         {
             List<T> result = new ArrayList<>();
             do

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

@@ -21,7 +21,7 @@
 import java.util.List;
 
 import org.neo4j.driver.internal.value.NullValue;
-import org.neo4j.driver.v1.exceptions.NoRecordException;
+import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
 /**
  * Access an underlying record (which is an ordered map of fields)
@@ -62,7 +62,7 @@ public interface RecordAccessor extends ListAccessor
      *
      * @param key the key of the property
      * @return the property's value or a {@link NullValue} if no such key exists
-     * @throws NoRecordException if the associated underlying record is not available
+     * @throws NoSuchRecordException if the associated underlying record is not available
      */
     Value get( String key );
 
@@ -78,12 +78,12 @@ public interface RecordAccessor extends ListAccessor
      * Retrieve all record fields
      *
      * @return all fields in key order
-     * @throws NoRecordException if the associated underlying record is not available
+     * @throws NoSuchRecordException if the associated underlying record is not available
      */
     List<Pair<String, Value>> fields();
 
     /**
-     * @throws NoRecordException if the associated underlying record is not available
+     * @throws NoSuchRecordException if the associated underlying record is not available
      * @return an immutable copy of the currently associated underlying record
      */
     Record record();

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

@@ -21,6 +21,7 @@
 import java.util.List;
 
 import org.neo4j.driver.v1.exceptions.ClientException;
+import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
 
 /**
@@ -41,10 +42,10 @@ public interface ResultCursor extends RecordAccessor, Resource
 {
     /**
      * @return an immutable copy of the currently viewed record
-     * @throws ClientException if no calls has been made to {@link #next()}, {@link #first()}, nor {@link #skip(long)}
+     * @throws NoSuchRecordException if no calls has been made to {@link #next()}, {@link #first()}, nor {@link #skip(long)}
      */
     @Override
-    Record record();
+    Record record() throws NoSuchRecordException;
 
     /**
      * Retrieve the zero based position of the cursor in the stream of records.
@@ -90,26 +91,28 @@ public interface ResultCursor extends RecordAccessor, Resource
     long limit( long records );
 
     /**
-     * Move to the first record if possible, otherwise do nothing.
+     * Return the first record in the stream. Fail with an exception if the stream is empty
+     * or if this cursor has already been used to move "into" the stream.
+     *
+     * @return the first record in the stream
+     * @throws NoSuchRecordException if there is no first record or the cursor has been used already
      *
-     * @return <tt>true</tt> if the cursor is placed on the first record
      */
-    boolean first();
+    Record first() throws NoSuchRecordException;
 
     /**
-     * Move to the first record if possible and verify that it is the only record.
+     * Move to the first record and return an immutable copy of it, failing if there is not exactly
+     * one record in the stream, or if this cursor has already been used to move "into" the stream.
      *
-     * @return <tt>true</tt> if the cursor was successfully placed at the single first and only record
+     * @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
      */
-    boolean single();
+    Record single() throws NoSuchRecordException;
 
     /**
-     * Investigate the next upcoming record.
-     *
-     * The returned {@link RecordAccessor} is updated consistently whenever this associated cursor
-     * is moved.
+     * Investigate the next upcoming record without changing the position of this cursor.
      *
-     * @return a view on the next record, or null if there is no next record
+     * @return an immutable copy of the next record, or null if there is no next record
      */
     Record peek();
 
@@ -118,7 +121,8 @@ public interface ResultCursor extends RecordAccessor, Resource
      * This can be used if you want to iterate over the stream multiple times or to store the
      * whole result for later use.
      *
-     * Calling this method exhausts the result cursor and moves it to the last record
+     * Calling this method exhausts the result cursor and moves it to the last record.
+     *
      * @throws ClientException if the cursor can't be positioned at the first record
      * @return list of all immutable records
      */
@@ -129,7 +133,8 @@ public interface ResultCursor extends RecordAccessor, Resource
      * This can be used if you want to iterate over the stream multiple times or to store the
      * whole result for later use.
      *
-     * Calling this method exhausts the result cursor and moves it to the last record
+     * Calling this method exhausts the result cursor and moves it to the last record.
+     *
      * @throws ClientException if the cursor can't be positioned at the first record
      * @param mapFunction a function to map from Value to T. See {@link Values} for some predefined functions, such
      * as {@link Values#valueAsBoolean()}, {@link Values#valueAsList(Function)}.

driver/src/main/java/org/neo4j/driver/v1/exceptions/NoRecordException.java renamed to driver/src/main/java/org/neo4j/driver/v1/exceptions/NoSuchRecordException.java

@@ -18,17 +18,12 @@
  */
 package org.neo4j.driver.v1.exceptions;
 
-public class NoRecordException extends ClientException
+public class NoSuchRecordException extends ClientException
 {
     private static final long serialVersionUID = 9091962868264042491L;
 
-    public NoRecordException( String message )
+    public NoSuchRecordException( String message )
     {
         super( message );
     }
-
-    public NoRecordException( String message, Throwable cause )
-    {
-        super( message, cause );
-    }
 }

driver/src/main/java/org/neo4j/driver/v1/exceptions/value/Unrepresentable.java

@@ -36,10 +36,12 @@
 import org.neo4j.driver.v1.ResultCursor;
 import org.neo4j.driver.v1.Value;
 import org.neo4j.driver.v1.exceptions.ClientException;
+import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.collection.IsCollectionWithSize.hasSize;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
@@ -59,13 +61,12 @@ public void iterationShouldWorksAsExpected()
         // WHEN
         assertThat( result.position(), equalTo( -1L ) );
         assertTrue( result.next() ); //-1 -> 0
-        assertTrue( result.first() );
+        assertNotNull( result.first() );
         assertFalse( result.atEnd() );
         assertThat( values( result.record() ), equalTo(Arrays.asList(value("v1-1"), value( "v2-1" ))));
 
         assertThat( result.position(), equalTo( 0L ) );
         assertTrue( result.next() ); //0 -> 1
-        assertFalse( result.first() );
         assertFalse( result.atEnd() );
         assertThat( values( result.record() ), equalTo(Arrays.asList(value("v1-2"), value( "v2-2" ))));
 
@@ -75,15 +76,18 @@ public void iterationShouldWorksAsExpected()
         // THEN
         assertThat( result.position(), equalTo( 2L ) );
         assertTrue( result.atEnd() );
-        assertFalse( result.first() );
         assertThat( values( result.record() ), equalTo(Arrays.asList(value("v1-3"), value( "v2-3" ))));
         assertFalse( result.next() );
     }
 
     @Test
-    public void firstFalseOnEmptyStream()
+    public void firstThrowsOnEmptyStream()
     {
-        assertFalse( createResult( 0 ).first() );
+        // Expect
+        expectedException.expect( NoSuchRecordException.class );
+
+        // When
+        createResult( 0 ).first();
     }
 
     @Test
@@ -94,18 +98,36 @@ public void firstMovesCursorOnce()
 
         // WHEN
         assertThat( result.position(), equalTo( -1L ) );
-        assertTrue( result.first() );
+        assertNotNull( result.first() );
         assertThat( result.position(), equalTo( 0L ) );
-        assertTrue( result.first() );
+        assertNotNull( result.first() );
         assertThat( result.position(), equalTo( 0L ) );
     }
 
     @Test
     public void singleShouldWorkAsExpected()
     {
-        assertFalse( createResult( 42 ).single() );
-        assertFalse( createResult( 0 ).single() );
-        assertTrue( createResult( 1 ).single() );
+        assertNotNull( createResult( 1 ).single() );
+    }
+
+    @Test
+    public void singleShouldThrowOnBigResult()
+    {
+        // Expect
+        expectedException.expect( NoSuchRecordException.class );
+
+        // When
+        createResult( 42 ).single();
+    }
+
+    @Test
+    public void singleShouldThrowOnEmptyResult()
+    {
+        // Expect
+        expectedException.expect( NoSuchRecordException.class );
+
+        // When
+        createResult( 0 ).single();
     }
 
     @Test

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

@@ -31,7 +31,6 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.containsInAnyOrder;
 import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertTrue;
 
 @RunWith( DocTestRunner.class )
 public class DriverDocIT
@@ -53,8 +52,7 @@ public void exampleUsage( DocSnippet snippet )
 
         // then it should've created a bunch of data
         ResultCursor result = session.run( "MATCH (n) RETURN count(n)" );
-        assertTrue( result.single() );
-        assertEquals( 3, result.get( 0 ).asInt() );
+        assertEquals( 3, result.single().get( 0 ).asInt() );
         assertThat( (List<String>)snippet.get( "names" ), containsInAnyOrder( "Bob", "Alice", "Tina" ) );
     }
 }

driver/src/test/java/org/neo4j/driver/v1/DriverDocIT.java

@@ -26,7 +26,6 @@
 import org.neo4j.driver.v1.util.TestNeo4jSession;
 
 import static org.junit.Assert.assertEquals;
-import static org.junit.Assert.assertTrue;
 
 @RunWith( DocTestRunner.class )
 public class TransactionDocIT
@@ -45,8 +44,7 @@ public void classDoc( DocSnippet snippet )
 
         // Then a node should've been created
         ResultCursor cursor = session.run( "MATCH (n) RETURN count(n)" );
-        assertTrue( cursor.single() );
-        assertEquals( 1, cursor.get( "count(n)" ).asInt() );
+        assertEquals( 1,  cursor.single().get( "count(n)" ).asInt() );
     }
 
     /** @see Transaction#failure()  */
@@ -60,7 +58,6 @@ public void failure( DocSnippet snippet )
 
         // Then a node should've been created
         ResultCursor cursor = session.run( "MATCH (n) RETURN count(n)" );
-        assertTrue( cursor.single() );
-        assertEquals( 0, cursor.get( "count(n)" ).asInt() );
+        assertEquals( 0, cursor.single().get( "count(n)" ).asInt() );
     }
 }