Introduce managed query execution on Driver level

This is a new basic high-level API for executing idempotent queries.

Author: injectives

driver/clirr-ignored-differences.xml

@@ -409,4 +409,16 @@
         <method>org.neo4j.driver.BaseSession session(java.lang.Class, org.neo4j.driver.SessionConfig)</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.QueryTask queryTask(java.lang.String)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.BookmarkManager queryBookmarkManager()</method>
+    </difference>
+
 </differences>

driver/src/main/java/module-info.java

@@ -27,6 +27,7 @@
     exports org.neo4j.driver.net;
     exports org.neo4j.driver.util;
     exports org.neo4j.driver.exceptions;
+    exports org.neo4j.driver.querytask;
 
     requires reactor.core;
     requires io.netty.common;

driver/src/main/java/org/neo4j/driver/Config.java

@@ -75,6 +75,8 @@ public final class Config implements Serializable {
 
     private static final Config EMPTY = builder().build();
 
+    private final BookmarkManager queryBookmarkManager;
+
     /**
      * User defined logging
      */
@@ -102,6 +104,7 @@ public final class Config implements Serializable {
     private final MetricsAdapter metricsAdapter;
 
     private Config(ConfigBuilder builder) {
+        this.queryBookmarkManager = builder.queryBookmarkManager;
         this.logging = builder.logging;
         this.logLeakedSessions = builder.logLeakedSessions;
 
@@ -123,6 +126,19 @@ private Config(ConfigBuilder builder) {
         this.metricsAdapter = builder.metricsAdapter;
     }
 
+    /**
+     * A {@link BookmarkManager} implementation for the driver to use on
+     * {@link Driver#queryTask(String)} method and its variants by default.
+     * <p>
+     * Please note that sessions will not use this automatically, but it is possible to enable it explicitly
+     * using {@link SessionConfig.Builder#withBookmarkManager(BookmarkManager)}.
+     *
+     * @return bookmark manager, must not be {@code null}
+     */
+    public BookmarkManager queryBookmarkManager() {
+        return queryBookmarkManager;
+    }
+
     /**
      * Logging provider
      *
@@ -262,6 +278,8 @@ public String userAgent() {
      * Used to build new config instances
      */
     public static final class ConfigBuilder {
+        private BookmarkManager queryBookmarkManager =
+                BookmarkManagers.defaultManager(BookmarkManagerConfig.builder().build());
         private Logging logging = DEV_NULL_LOGGING;
         private boolean logLeakedSessions;
         private int maxConnectionPoolSize = PoolSettings.DEFAULT_MAX_CONNECTION_POOL_SIZE;
@@ -281,6 +299,22 @@ public static final class ConfigBuilder {
 
         private ConfigBuilder() {}
 
+        /**
+         * Sets a {@link BookmarkManager} implementation for the driver to use on
+         * {@link Driver#queryTask(String)} method and its variants by default.
+         * <p>
+         * Please note that sessions will not use this automatically, but it is possible to enable it explicitly
+         * using {@link SessionConfig.Builder#withBookmarkManager(BookmarkManager)}.
+         *
+         * @param queryBookmarkManager bookmark manager, must not be {@code null}
+         * @return this builder
+         */
+        public ConfigBuilder withQueryBookmarkManager(BookmarkManager queryBookmarkManager) {
+            Objects.requireNonNull(queryBookmarkManager, "queryBookmarkManager must not be null");
+            this.queryBookmarkManager = queryBookmarkManager;
+            return this;
+        }
+
         /**
          * Provide a logging implementation for the driver to use. Java logging framework {@link java.util.logging} with {@link Level#INFO} is used by default.
          * Callers are expected to either implement {@link Logging} interface or provide one of the existing implementations available from static factory

driver/src/main/java/org/neo4j/driver/Driver.java

@@ -63,6 +63,24 @@
  * @since 1.0 (Modified and Added {@link AsyncSession} and {@link RxSession} since 2.0)
  */
 public interface Driver extends AutoCloseable {
+    /**
+     * Creates a new {@link QueryTask} instance that executes an idempotent query in a managed transaction with
+     * automatic retries on retryable errors.
+     *
+     * @param query query string
+     * @return new query task instance
+     * @since 5.5
+     */
+    @Experimental
+    QueryTask queryTask(String query);
+
+    /**
+     * Returns an instance of {@link BookmarkManager} used by {@link QueryTask} instances by default.
+     *
+     * @return bookmark manager, must not be {@code null}
+     */
+    BookmarkManager queryBookmarkManager();
+
     /**
      * Return a flag to indicate whether or not encryption is used for this driver.
      *
@@ -84,6 +102,7 @@ default Session session() {
     /**
      * Instantiate a new {@link Session} with a specified {@link SessionConfig session configuration}.
      * Use {@link SessionConfig#forDatabase(String)} to obtain a general purpose session configuration for the specified database.
+     *
      * @param sessionConfig specifies session configurations for this session.
      * @return a new {@link Session} object.
      * @see SessionConfig
@@ -257,6 +276,7 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
     /**
      * Returns the driver metrics if metrics reporting is enabled via {@link Config.ConfigBuilder#withDriverMetrics()}.
      * Otherwise, a {@link ClientException} will be thrown.
+     *
      * @return the driver metrics if enabled.
      * @throws ClientException if the driver metrics reporting is not enabled.
      */
@@ -281,7 +301,7 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
     /**
      * This verifies if the driver can connect to a remote server or a cluster
      * by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.
-     *
+     * <p>
      * It throws exception if fails to connect. Use the exception to further understand the cause of the connectivity problem.
      * Note: Even if this method throws an exception, the driver still need to be closed via {@link #close()} to free up all resources.
      */
@@ -290,7 +310,7 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
     /**
      * This verifies if the driver can connect to a remote server or cluster
      * by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.
-     *
+     * <p>
      * This operation is asynchronous and returns a {@link CompletionStage}. This stage is completed with
      * {@code null} when the driver connects to the remote server or cluster successfully.
      * It is completed exceptionally if the driver failed to connect the remote server or cluster.
@@ -303,12 +323,14 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
 
     /**
      * Returns true if the server or cluster the driver connects to supports multi-databases, otherwise false.
+     *
      * @return true if the server or cluster the driver connects to supports multi-databases, otherwise false.
      */
     boolean supportsMultiDb();
 
     /**
      * Asynchronous check if the server or cluster the driver connects to supports multi-databases.
+     *
      * @return a {@link CompletionStage completion stage} that returns true if the server or cluster
      * the driver connects to supports multi-databases, otherwise false.
      */

driver/src/main/java/org/neo4j/driver/EagerResult.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.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;
+
+import java.util.List;
+import org.neo4j.driver.summary.ResultSummary;
+import org.neo4j.driver.util.Experimental;
+
+/**
+ * An in-memory result of executing a Cypher query that has been consumed in full.
+ * @since 5.5
+ */
+@Experimental
+public interface EagerResult {
+    /**
+     * Returns the keys of the records this result contains.
+     *
+     * @return list of keys
+     */
+    List<String> keys();
+
+    /**
+     * Returns the list of records this result contains.
+     *
+     * @return list of records
+     */
+    List<Record> records();
+
+    /**
+     * Returns the result summary.
+     *
+     * @return result summary
+     */
+    ResultSummary summary();
+}