Added variants of single and first for simplified access

boggle · boggle · commit b281ef1752bf · 2016-02-04T16:15:38.000+01:00
Rationale: @jakewins and @boggle observed that sometimes using single and first leads to rather long expressions and felt adding this sugar might help with that
diff --git a/driver/src/main/java/org/neo4j/driver/internal/InternalResultCursor.java b/driver/src/main/java/org/neo4j/driver/internal/InternalResultCursor.java
@@ -18,18 +18,13 @@
  */
 package org.neo4j.driver.internal;
 
-import java.util.ArrayList;
-import java.util.List;
-
-import org.neo4j.driver.v1.Function;
-import org.neo4j.driver.v1.Record;
-import org.neo4j.driver.v1.RecordAccessor;
-import org.neo4j.driver.v1.ResultCursor;
-import org.neo4j.driver.v1.ResultSummary;
-import org.neo4j.driver.v1.Value;
+import org.neo4j.driver.v1.*;
 import org.neo4j.driver.v1.exceptions.ClientException;
 import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
+import java.util.ArrayList;
+import java.util.List;
+
 import static java.lang.String.format;
 import static java.util.Collections.emptyList;
 import static org.neo4j.driver.v1.Records.recordAsIs;
@@ -197,6 +192,19 @@ public Record first()
         return record();
     }
 
+
+    @Override
+    public Value first(String fieldName) throws NoSuchRecordException
+    {
+        return first().get( fieldName );
+    }
+
+    @Override
+    public Value first(int index) throws NoSuchRecordException
+    {
+        return first().get( index );
+    }
+
     @Override
     public Record single()
     {
@@ -210,6 +218,18 @@ public Record single()
         return first;
     }
 
+    @Override
+    public Value single( String fieldName ) throws NoSuchRecordException
+    {
+        return single().get( fieldName );
+    }
+
+    @Override
+    public Value single( int index ) throws NoSuchRecordException
+    {
+        return single().get( index );
+    }
+
     @Override
     public Record peek()
     {
diff --git a/driver/src/main/java/org/neo4j/driver/v1/ResultCursor.java b/driver/src/main/java/org/neo4j/driver/v1/ResultCursor.java
@@ -18,11 +18,11 @@
  */
 package org.neo4j.driver.v1;
 
-import java.util.List;
-
 import org.neo4j.driver.v1.exceptions.ClientException;
 import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
+import java.util.List;
+
 
 /**
  * The result of running a statement, a stream of records represented as a cursor.
@@ -100,6 +100,28 @@ public interface ResultCursor extends RecordAccessor, Resource
      */
     Record first() throws NoSuchRecordException;
 
+    /**
+     * Return a field value from 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.
+     *
+     * @param fieldName the name of the field to return from the first record in the stream
+     * @return the specified field from the first record in the stream
+     * @throws NoSuchRecordException if there is no first record or the cursor has been used already
+     *
+     */
+    Value first( String fieldName ) throws NoSuchRecordException;
+
+    /**
+     * Return a field value from 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.
+     *
+     * @param index the index of the field to return from the first record in the stream
+     * @return the specified field from the first record in the stream
+     * @throws NoSuchRecordException if there is no first record or the cursor has been used already
+     *
+     */
+    Value first( int index ) throws NoSuchRecordException;
+
     /**
      * 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.
@@ -109,6 +131,26 @@ public interface ResultCursor extends RecordAccessor, Resource
      */
     Record single() throws NoSuchRecordException;
 
+    /**
+     * Move to the first record and return a field value from 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.
+     *
+     * @param fieldName the name of the field to return from the first and only record in the stream
+     * @return the value of the specified field of 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
+     */
+    Value single( String fieldName ) throws NoSuchRecordException;
+
+    /**
+     * Move to the first record and return a field value from 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.
+     *
+     * @param index the index of the field to return from the first and only record in the stream
+     * @return the value of the specified field of 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
+     */
+    Value single( int index ) throws NoSuchRecordException;
+
     /**
      * Investigate the next upcoming record without changing the position of this cursor.
      *
@@ -157,4 +199,4 @@ public interface ResultCursor extends RecordAccessor, Resource
      * @return a summary for the whole query
      */
     ResultSummary summarize();
-}
+}
diff --git a/driver/src/test/java/org/neo4j/driver/internal/InternalResultCursorTest.java b/driver/src/test/java/org/neo4j/driver/internal/InternalResultCursorTest.java
@@ -22,29 +22,19 @@
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
-
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
-
 import org.neo4j.driver.internal.summary.ResultBuilder;
 import org.neo4j.driver.internal.value.NullValue;
-import org.neo4j.driver.v1.Pair;
-import org.neo4j.driver.v1.Record;
-import org.neo4j.driver.v1.RecordAccessor;
-import org.neo4j.driver.v1.Records;
-import org.neo4j.driver.v1.ResultCursor;
-import org.neo4j.driver.v1.Value;
+import org.neo4j.driver.v1.*;
 import org.neo4j.driver.v1.exceptions.ClientException;
 import org.neo4j.driver.v1.exceptions.NoSuchRecordException;
 
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
 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;
+import static org.junit.Assert.*;
 import static org.neo4j.driver.v1.Values.value;
 
 public class InternalResultCursorTest
@@ -80,6 +70,50 @@ public void iterationShouldWorksAsExpected()
         assertFalse( result.next() );
     }
 
+    @Test
+    public void firstOfFieldNameShouldWorkAsExpected()
+    {
+        // GIVEN
+        ResultCursor result = createResult( 3 );
+
+        // THEN
+        assertThat( result.first( "k1" ), equalTo( value("v1-1") ) );
+        assertFalse( result.atEnd() );
+    }
+
+    @Test
+    public void firstOfFieldIndexShouldWorkAsExpected()
+    {
+        // GIVEN
+        ResultCursor result = createResult( 3 );
+
+        // THEN
+        assertThat( result.first( 0 ), equalTo( value("v1-1") ) );
+        assertFalse( result.atEnd() );
+    }
+
+    @Test
+    public void singleOfFieldNameShouldWorkAsExpected()
+    {
+        // GIVEN
+        ResultCursor result = createResult( 1 );
+
+        // THEN
+        assertThat( result.single( "k1" ), equalTo( value("v1-1") ) );
+        assertTrue( result.atEnd() );
+    }
+
+    @Test
+    public void singleOfFieldIndexShouldWorkAsExpected()
+    {
+        // GIVEN
+        ResultCursor result = createResult( 1 );
+
+        // THEN
+        assertThat( result.single( 0 ), equalTo( value("v1-1") ) );
+        assertTrue( result.atEnd() );
+    }
+
     @Test
     public void firstThrowsOnEmptyStream()
     {
