Merge pull request #11666 from fickludd/3.4-javadocs-for-statement

Improve javadocs and method names around Transaction and Statement

community/kernel-api/src/main/java/org/neo4j/internal/kernel/api/Transaction.java

@@ -27,6 +27,37 @@
 
 /**
  * A transaction with the graph database.
+ *
+ * Access to the graph is performed via sub-interfaces like {@link org.neo4j.internal.kernel.api.Read}.
+ * Changes made within a transaction are immediately visible to all operations within it, but are only
+ * visible to other transactions after the successful commit of the transaction.
+ *
+ * Typical usage:
+ * <pre>
+ * try ( Transaction transaction = session.beginTransaction() )
+ * {
+ *      ...
+ *      transaction.success();
+ * }
+ * catch ( SomeException e )
+ * {
+ *      ...
+ * }
+ * </pre>
+ *
+ * Typical usage of failure if failure isn't controlled with exceptions:
+ * <pre>
+ * try ( Transaction transaction = session.beginTransaction() )
+ * {
+ *      ...
+ *      if ( ... some condition )
+ *      {
+ *          transaction.failure();
+ *      }
+ *
+ *      transaction.success();
+ * }
+ * </pre>
  */
 public interface Transaction extends AutoCloseable
 {

community/kernel/src/main/java/org/neo4j/kernel/api/KernelTransaction.java

@@ -19,65 +19,19 @@
  */
 package org.neo4j.kernel.api;
 
+import org.neo4j.graphdb.NotInTransactionException;
 import org.neo4j.internal.kernel.api.NodeCursor;
 import org.neo4j.internal.kernel.api.PropertyCursor;
 import org.neo4j.internal.kernel.api.RelationshipScanCursor;
 import org.neo4j.internal.kernel.api.Transaction;
 import org.neo4j.internal.kernel.api.security.AuthSubject;
-import org.neo4j.internal.kernel.api.security.LoginContext;
 import org.neo4j.internal.kernel.api.security.SecurityContext;
 import org.neo4j.kernel.impl.api.ClockContext;
-import org.neo4j.kernel.impl.api.KernelImpl;
 
 /**
- * Represents a transaction of changes to the underlying graph.
- * Actual changes are made in the {@linkplain #acquireStatement() statements} acquired from this transaction.
- * Changes made within a transaction are visible to all operations within it.
- *
- * The reason for the separation between transactions and statements is isolation levels. While Neo4j is read-committed
- * isolation, a read can potentially involve multiple operations (think of a cypher statement). Within that read, or
- * statement if you will, the isolation level should be repeatable read, not read committed.
- *
- * Clearly separating between the concept of a transaction and the concept of a statement allows us to cater to this
- * type of isolation requirements.
- *
- * This class has a 1-1 relationship with{@link org.neo4j.kernel.impl.transaction.state.TransactionRecordState}, please see its'
- * javadoc for details.
- *
- * Typical usage:
- * <pre>
- * try ( KernelTransaction transaction = kernel.newTransaction() )
- * {
- *      try ( Statement statement = transaction.acquireStatement() )
- *      {
- *          ...
- *      }
- *      ...
- *      transaction.success();
- * }
- * catch ( SomeException e )
- * {
- *      ...
- * }
- * catch ( SomeOtherExceptionException e )
- * {
- *      ...
- * }
- * </pre>
- *
- * Typical usage of failure if failure isn't controlled with exceptions:
- * <pre>
- * try ( KernelTransaction transaction = kernel.newTransaction() )
- * {
- *      ...
- *      if ( ... some condition )
- *      {
- *          transaction.failure();
- *      }
- *
- *      transaction.success();
- * }
- * </pre>
+ * Extends the outwards-facing {@link org.neo4j.internal.kernel.api.Transaction} with additional functionality
+ * that is used inside the kernel (and in some other places, ahum). Please do not rely on this class unless you
+ * have to.
  */
 public interface KernelTransaction extends Transaction, AssertOpen
 {
@@ -94,19 +48,21 @@ interface CloseListener
      * Acquires a new {@link Statement} for this transaction which allows for reading and writing data from and
      * to the underlying database. After the group of reads and writes have been performed the statement
      * must be {@link Statement#close() released}.
+     *
      * @return a {@link Statement} with access to underlying database.
      */
     Statement acquireStatement();
 
     /**
      * @return the security context this transaction is currently executing in.
+     * @throws NotInTransactionException if the transaction is closed.
      */
     SecurityContext securityContext();
 
     /**
-     * @return the subject executing this transaction.
+     * @return the subject executing this transaction, or {@link AuthSubject#ANONYMOUS} if the transaction is closed.
      */
-    AuthSubject subject();
+    AuthSubject subjectOrAnonymous();
 
     /**
      * @return The timestamp of the last transaction that was committed to the store when this transaction started.
@@ -163,15 +119,40 @@ interface CloseListener
      */
     long getCommitTime();
 
+    /**
+     * Temporarily override this transaction's SecurityContext. The override should be reverted using
+     * the returned {@link Revertable}.
+     *
+     * @param context the temporary SecurityContext.
+     * @return {@link Revertable} which reverts to the original SecurityContext.
+     */
     Revertable overrideWith( SecurityContext context );
 
+    /**
+     * Clocks associated with this transaction.
+     */
     ClockContext clocks();
 
-    NodeCursor nodeCursor();
+    /**
+     * USE WITH CAUTION:
+     * The internal node cursor instance used to serve kernel API calls. If some kernel API call
+     * is made while this cursor is used, it might get corrupted and return wrong results.
+     */
+    NodeCursor ambientNodeCursor();
 
-    RelationshipScanCursor relationshipCursor();
+    /**
+     * USE WITH CAUTION:
+     * The internal relationship scan cursor instance used to serve kernel API calls. If some kernel
+     * API call is made while this cursor is used, it might get corrupted and return wrong results.
+     */
+    RelationshipScanCursor ambientRelationshipCursor();
 
-    PropertyCursor propertyCursor();
+    /**
+     * USE WITH CAUTION:
+     * The internal property cursor instance used to serve kernel API calls. If some kernel
+     * API call is made while this cursor is used, it might get corrupted and return wrong results.
+     */
+    PropertyCursor ambientPropertyCursor();
 
     @FunctionalInterface
     interface Revertable extends AutoCloseable

community/kernel/src/main/java/org/neo4j/kernel/api/Statement.java

@@ -23,8 +23,13 @@
 
 /**
  * A statement which is a smaller coherent unit of work inside a {@link KernelTransaction}.
- * There are accessors for different types of operations. The operations are divided into
- * read and write operations.
+ *
+ * The main purpose of the statement is to keep resources open for the duration of the statement, and
+ * then close all resources at statement close.
+ *
+ * Note that Statement used to be the access-point for all kernel reads and writes before 3.4. For
+ * accessing the graph now, see {@link org.neo4j.internal.kernel.api.Transaction}. The only remainder
+ * the QueryRegistryOperations, which will eventually also move from here.
  */
 public interface Statement extends Resource, ResourceManager
 {

community/kernel/src/main/java/org/neo4j/kernel/impl/api/KernelTransactionImplementation.java

@@ -374,7 +374,7 @@ public SecurityContext securityContext()
         return securityContext;
     }
 
-    public AuthSubject subject()
+    public AuthSubject subjectOrAnonymous()
     {
         return securityContext == null ? AuthSubject.ANONYMOUS : securityContext.subject();
     }
@@ -1172,19 +1172,19 @@ public ClockContext clocks()
     }
 
     @Override
-    public NodeCursor nodeCursor()
+    public NodeCursor ambientNodeCursor()
     {
         return operations.nodeCursor();
     }
 
     @Override
-    public RelationshipScanCursor relationshipCursor()
+    public RelationshipScanCursor ambientRelationshipCursor()
     {
         return operations.relationshipCursor();
     }
 
     @Override
-    public PropertyCursor propertyCursor()
+    public PropertyCursor ambientPropertyCursor()
     {
         return operations.propertyCursor();
     }

community/kernel/src/main/java/org/neo4j/kernel/impl/api/KernelTransactionImplementationHandle.java

@@ -24,7 +24,6 @@
 import java.util.stream.Stream;
 
 import org.neo4j.internal.kernel.api.security.AuthSubject;
-import org.neo4j.internal.kernel.api.security.SecurityContext;
 import org.neo4j.kernel.api.KernelTransaction;
 import org.neo4j.kernel.api.KernelTransactionHandle;
 import org.neo4j.kernel.api.exceptions.Status;
@@ -62,7 +61,7 @@ class KernelTransactionImplementationHandle implements KernelTransactionHandle
         this.lastTransactionTimestampWhenStarted = tx.lastTransactionTimestampWhenStarted();
         this.startTime = tx.startTime();
         this.timeoutMillis = tx.timeout();
-        this.subject = tx.subject();
+        this.subject = tx.subjectOrAnonymous();
         this.terminationReason = tx.getReasonIfTerminated();
         this.executingQueries = tx.executingQueries();
         this.metaData = tx.getMetaData();

community/kernel/src/main/java/org/neo4j/kernel/impl/core/GraphPropertiesProxy.java

@@ -73,7 +73,7 @@ public boolean hasProperty( String key )
             return false;
         }
 
-        PropertyCursor properties = transaction.propertyCursor();
+        PropertyCursor properties = transaction.ambientPropertyCursor();
         transaction.dataRead().graphProperties( properties );
         while ( properties.next() )
         {
@@ -99,7 +99,7 @@ public Object getProperty( String key )
             throw new NotFoundException( format( "No such property, '%s'.", key ) );
         }
 
-        PropertyCursor properties = transaction.propertyCursor();
+        PropertyCursor properties = transaction.ambientPropertyCursor();
         transaction.dataRead().graphProperties( properties );
 
         while ( properties.next() )
@@ -125,7 +125,7 @@ public Object getProperty( String key, Object defaultValue )
             throw new IllegalArgumentException( "(null) property key is not allowed" );
         }
         KernelTransaction transaction = safeAcquireTransaction();
-        PropertyCursor properties = transaction.propertyCursor();
+        PropertyCursor properties = transaction.ambientPropertyCursor();
         int propertyKey = transaction.tokenRead().propertyKey( key );
         if ( propertyKey == TokenRead.NO_TOKEN )
         {
@@ -197,7 +197,7 @@ public Iterable<String> getPropertyKeys()
         List<String> keys = new ArrayList<>();
         try
         {
-            PropertyCursor properties = transaction.propertyCursor();
+            PropertyCursor properties = transaction.ambientPropertyCursor();
             TokenRead token = transaction.tokenRead();
             transaction.dataRead().graphProperties( properties );
             while ( properties.next() )
@@ -241,7 +241,7 @@ public Map<String,Object> getProperties( String... names )
             propertyIds[i] = token.propertyKey( key );
         }
 
-        PropertyCursor propertyCursor = transaction.propertyCursor();
+        PropertyCursor propertyCursor = transaction.ambientPropertyCursor();
         transaction.dataRead().graphProperties( propertyCursor );
         int propertiesToFind = itemsToReturn;
         while ( propertiesToFind > 0 && propertyCursor.next() )
@@ -270,7 +270,7 @@ public Map<String, Object> getAllProperties()
 
         try
         {
-            PropertyCursor propertyCursor = transaction.propertyCursor();
+            PropertyCursor propertyCursor = transaction.ambientPropertyCursor();
             TokenRead token = transaction.tokenRead();
             transaction.dataRead().graphProperties( propertyCursor );
             while ( propertyCursor.next() )