Formalize contract for run

Author: jakewins

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

@@ -203,7 +203,8 @@ public RecordAccessor peek()
         return new PeekingRecordAccessor();
     }
 
-    public List<Record> recordsAsList()
+    @Override
+    public List<Record> list()
     {
         return list( recordAsIs() );
     }

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

@@ -36,6 +36,41 @@ public interface StatementRunner
      * dangerous cypher injection attacks and improves database performance as
      * Neo4j can re-use query plans more often.
      *
+     * <h2>Important notes about guarantees</h2>
+     * When you invoke this method, there are no guarantees that your statement will be
+     * immediately ran. This allows highly efficient execution when you run multiple
+     * statements in a row.
+     *
+     * There are two ways to ensure a statement has been ran:
+     *
+     * <h3>Observe the result</h3>
+     *
+     * Once you start reading the result, the statement must execute. If you do not care about
+     * the contents of the result and only want to ensure it is ran, you may simply
+     * {@link ResultCursor#close() close} it.
+     *
+     * <h3>Observe the result of a later statement</h3>
+     *
+     * Every statement you run is logically ordered to happen after every statement you've ran
+     * before it. This means that if you read the result of one statement, every statement
+     * ran before is forced to execute.
+     *
+     * Thus, both statements are guaranteed to have executed successfully if this code
+     * exits without error, because we close the result of the second statement.
+     *
+     * <pre class="doctest:StatementRunnerDocIT#orderedObserveResult">
+     * {@code
+     * session.run( "CREATE (:FirstNode)" );
+     * session.run( "CREATE (:SecondNode)" ).close();
+     * }
+     * </pre>
+     *
+     * <h3>Closing resources</h3>
+     *
+     * Finally, all statements ran in a {@link StatementRunner} are guaranteed to have executed
+     * when you close a {@link Transaction} associated with the {@link StatementRunner}, likewise
+     * when you close the {@link Session} or the {@link Driver}.
+     *
      * <h2>Example</h2>
      * <pre class="doctest:StatementRunnerDocIT#parameterTest">
      * {@code

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

@@ -27,6 +27,7 @@
 
 import static org.hamcrest.CoreMatchers.notNullValue;
 import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.Assert.assertTrue;
 
 @RunWith( DocTestRunner.class )
 public class StatementRunnerDocIT
@@ -46,6 +47,20 @@ public void parameterTest( DocSnippet snippet )
         assertThat( snippet.get( "cursor" ), notNullValue() );
     }
 
+    public void orderedObserveResult( DocSnippet snippet )
+    {
+        // given
+        snippet.set( "session", session );
+
+        // when
+        snippet.run();
+
+        // then
+        assertTrue( session.run( "OPTIONAL MATCH (a:FirstNode)" +
+                     "OPTIONAL MATCH (b:SecondNode)" +
+                     "RETURN a is not null and b is not null" ).peek().get( 0 ).isTrue() );
+    }
+
     public void statementObjectTest( DocSnippet snippet )
     {
         // given

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

@@ -0,0 +1,24 @@
+package org.neo4j.driver.v1;
+
+import org.junit.Test;
+
+public class TypePlayTest
+{
+    @Test
+    public void asd() throws Throwable
+    {
+        Driver driver = GraphDatabase.driver( ".." );
+
+        Session session = driver.session();
+
+        session.run( "CREATE (n)" ).close();
+
+    }
+
+    static class StaticTypeSystem
+    {
+        public static Type FLOAT() {
+            return null;
+        }
+    }
+}