Add ResultCursor.peek() and ResultCursor.hasRecord()

o Also ensure inner iterator is set to null as soon as possible to free resources early

Author: boggle

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

@@ -48,18 +48,6 @@ public InternalRecord( List<String> keys, Map<String, Integer> keyIndexLookup, V
         this.values = values;
     }
 
-    @Override
-    public Value value( int index )
-    {
-        return index >= 0 && index < values.length ? values[index] : Values.NULL;
-    }
-
-    @Override
-    public int size()
-    {
-        return values.length;
-    }
-
     @Override
     public List<String> keys()
     {
@@ -101,6 +89,24 @@ public Value value( String key )
         }
     }
 
+    @Override
+    public Value value( int index )
+    {
+        return index >= 0 && index < values.length ? values[index] : Values.NULL;
+    }
+
+    @Override
+    public int size()
+    {
+        return values.length;
+    }
+
+    @Override
+    public boolean hasRecord()
+    {
+        return true;
+    }
+
     @Override
     public Record record()
     {

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

@@ -19,25 +19,27 @@
 package org.neo4j.driver.internal;
 
 import java.util.ArrayList;
-import java.util.Iterator;
 import java.util.List;
 
+import org.neo4j.driver.v1.Entry;
 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.exceptions.ClientException;
+import org.neo4j.driver.v1.exceptions.NoRecordException;
 
+import static java.lang.String.format;
 import static java.util.Collections.emptyList;
 
 import static org.neo4j.driver.v1.Records.recordAsIs;
 
 public class InternalResultCursor extends InternalRecordAccessor implements ResultCursor
 {
     private final List<String> keys;
-    private final Iterator<Record> iter;
+    private final PeekingIterator<Record> iter;
     private final ResultSummary summary;
 
     private boolean open = true;
@@ -47,7 +49,7 @@ public class InternalResultCursor extends InternalRecordAccessor implements Resu
     public InternalResultCursor( List<String> keys, List<Record> body, ResultSummary summary )
     {
         this.keys = keys;
-        this.iter = body.iterator();
+        this.iter = new PeekingIterator<>( body.iterator() );
         this.summary = summary;
     }
 
@@ -90,23 +92,27 @@ public int size()
         return keys.size();
     }
 
-    private Value throwNoRecord()
+    @Override
+    public boolean hasRecord()
     {
-        throw new ClientException(
-            "In order to access fields of a record in a result, " +
-            "you must first call next() to point the result to the next record in the result stream."
-        );
+        assertOpen();
+        return current != null && current.hasRecord();
     }
 
     @Override
     public Record record()
     {
-        assertOpen();
-        if ( current == null )
+        if ( hasRecord() )
         {
-            throwNoRecord();
+            return current;
+        }
+        else
+        {
+            throw new NoRecordException(
+                "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."
+            );
         }
-        return current;
     }
 
     @Override
@@ -144,7 +150,7 @@ public long skip( long elements )
     {
         if ( elements < 0 )
         {
-            throw new IllegalArgumentException( "Cannot skip negative number of elements" );
+            throw new ClientException( "Cannot skip negative number of elements" );
         }
         else
         {
@@ -170,6 +176,12 @@ public boolean single()
         return first() && atEnd();
     }
 
+    @Override
+    public RecordAccessor peek()
+    {
+        return new PeekingRecordAccessor();
+    }
+
     @Override
     public List<Record> retain()
     {
@@ -192,14 +204,14 @@ else if ( first() )
                 result.add( mapFunction.apply( this ) );
             }
             while ( next() );
+            discard();
             return result;
         }
         else
         {
-            throw new
-                ClientException( String.format(
-                "Can't retain records when cursor is not pointing at the first record (currently at position %d)",
-                position ) );
+            throw new ClientException(
+                format( "Can't retain records when cursor is not pointing at the first record (currently at position %d)", position )
+            );
         }
     }
 
@@ -208,6 +220,7 @@ else if ( first() )
     public ResultSummary summarize()
     {
         while ( next() ) ;
+        discard();
         return summary;
     }
 
@@ -216,11 +229,20 @@ public void close()
     {
         if ( open )
         {
+            discard();
             open = false;
         }
         else
         {
-            throw new IllegalStateException( "Already closed" );
+            throw new ClientException( "Already closed" );
+        }
+    }
+
+    private void assertOpen()
+    {
+        if ( !open )
+        {
+            throw new ClientException( "Cursor already closed" );
         }
     }
 
@@ -229,11 +251,73 @@ private boolean isEmpty()
         return position == -1 && !iter.hasNext();
     }
 
-    private void assertOpen()
+    private void discard()
     {
-        if ( !open )
+        iter.discard();
+    }
+
+    private class PeekingRecordAccessor implements RecordAccessor
+    {
+        @Override
+        public List<String> keys()
+        {
+            return InternalResultCursor.this.keys();
+        }
+
+        @Override
+        public boolean containsKey( String key )
+        {
+            return InternalResultCursor.this.containsKey( key );
+        }
+
+        @Override
+        public int index( String key )
+        {
+            return InternalResultCursor.this.index( key );
+        }
+
+        @Override
+        public Value value( String key )
+        {
+            return record().value( key );
+        }
+
+        @Override
+        public int size()
+        {
+            return InternalResultCursor.this.size();
+        }
+
+        @Override
+        public List<Entry<Value>> fields()
+        {
+            return record().fields();
+        }
+
+        @Override
+        public boolean hasRecord()
+        {
+            return iter.hasNext();
+        }
+
+        @Override
+        public Record record()
+        {
+            Record record = iter.peek();
+            if ( record == null )
+            {
+                throw new NoRecordException( "Cannot peek past last record" );
+            }
+            else
+            {
+                return record;
+            }
+        }
+
+        @Override
+        public Value value( int index )
         {
-            throw new IllegalStateException( "Cursor already closed" );
+            return record().value( index );
         }
     }
 }

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

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2002-2015 "Neo Technology,"
+ * Network Engine for Objects in Lund AB [http://neotechnology.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.neo4j.driver.internal;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+public class PeekingIterator<T> implements Iterator<T>
+{
+    private Iterator<T> iterator;
+    private T cached;
+
+    public PeekingIterator( Iterator<T> iterator )
+    {
+        this.iterator = iterator.hasNext() ? iterator : null;
+
+    }
+
+    public T peek()
+    {
+        return cacheNext() ? cached : null;
+    }
+
+    public boolean hasNext()
+    {
+        return cacheNext();
+    }
+
+    public T next()
+    {
+        if ( cacheNext() )
+        {
+            T result = cached;
+            cached = null;
+            return result;
+        }
+        else
+        {
+            throw new NoSuchElementException();
+        }
+    }
+
+    private boolean cacheNext()
+    {
+        if ( cached == null  )
+        {
+            if ( iterator == null )
+            {
+                return false;
+            }
+            else
+            {
+                cached = iterator.next();
+                if (! iterator.hasNext()) {
+                    this.iterator = null;
+                }
+                return true;
+            }
+        }
+        else
+        {
+            return true;
+        }
+    }
+
+    public void discard()
+    {
+        this.cached = null;
+        this.iterator = null;
+    }
+}