Align driver with latest revision of ExecuteQuery ADR (#1377)

* Align driver with latest revision of `ExecuteQuery` ADR

Rename `QueryTask` occurrences with `ExecuteQuery`

Rename default `ExecuteQuery`'s default `BookmarkManager` getter

Make default `ExecuteQuery`'s default `BookmarkManager` unchangeable

* Fix Javadoc error

* s/Builder/Template/

* Update naming

* Update clirr

* Update variable names

* Update Javadoc

* Update test name

* Update default ExecutableQuery BookmarkManager accessor

* Update Bookmark Manager accessor

* Update clirr config to align with the naming update

---------

Co-authored-by: Dmitriy Tverdiakov <[email protected]>

Author: fbiville

driver/clirr-ignored-differences.xml

@@ -457,4 +457,50 @@
         <method>java.util.Optional rawCategory()</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.QueryTask queryTask(java.lang.String)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.BookmarkManager queryTaskBookmarkManager()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Config</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.BookmarkManager queryTaskBookmarkManager()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Config$ConfigBuilder</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.Config$ConfigBuilder withQueryTaskBookmarkManager(org.neo4j.driver.BookmarkManager)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/QueryTask</className>
+        <differenceType>8001</differenceType>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/QueryTask$ResultFinisher</className>
+        <differenceType>8001</differenceType>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.ExecutableQuery executableQuery(java.lang.String)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.BookmarkManager executableQueryBookmarkManager()</method>
+    </difference>
+
 </differences>

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

@@ -41,7 +41,6 @@
 import org.neo4j.driver.net.ServerAddressResolver;
 import org.neo4j.driver.util.Experimental;
 import org.neo4j.driver.util.Immutable;
-import org.neo4j.driver.util.Preview;
 
 /**
  * A configuration class to config driver properties.
@@ -77,11 +76,6 @@ public final class Config implements Serializable {
 
     private static final Config EMPTY = builder().build();
 
-    /**
-     * The {@link QueryTask} {@link BookmarkManager}.
-     */
-    private final BookmarkManager queryBookmarkManager;
-
     /**
      * User defined logging
      */
@@ -155,7 +149,6 @@ 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;
 
@@ -178,21 +171,6 @@ 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}
-     * @since 5.5
-     */
-    @Preview(name = "Driver Level Queries")
-    public BookmarkManager queryTaskBookmarkManager() {
-        return queryBookmarkManager;
-    }
-
     /**
      * Logging provider
      *
@@ -361,8 +339,6 @@ 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;
@@ -383,24 +359,6 @@ 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 bookmarkManager bookmark manager, must not be {@code null}
-         * @return this builder
-         * @since 5.5
-         */
-        @Preview(name = "Driver Level Queries")
-        public ConfigBuilder withQueryTaskBookmarkManager(BookmarkManager bookmarkManager) {
-            Objects.requireNonNull(bookmarkManager, "bookmarkManager must not be null");
-            this.queryBookmarkManager = bookmarkManager;
-            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

@@ -65,24 +65,24 @@
  */
 public interface Driver extends AutoCloseable {
     /**
-     * Creates a new {@link QueryTask} instance that executes a query in a managed transaction with automatic retries on
+     * Creates a new {@link ExecutableQuery} instance that executes a query in a managed transaction with automatic retries on
      * retryable errors.
      *
      * @param query query string
-     * @return new query task instance
-     * @since 5.5
+     * @return new executable query instance
+     * @since 5.7
      */
     @Preview(name = "Driver Level Queries")
-    QueryTask queryTask(String query);
+    ExecutableQuery executableQuery(String query);
 
     /**
-     * Returns an instance of {@link BookmarkManager} used by {@link QueryTask} instances by default.
+     * Returns an instance of {@link BookmarkManager} used by {@link ExecutableQuery} instances by default.
      *
      * @return bookmark manager, must not be {@code null}
-     * @since 5.6
+     * @since 5.7
      */
     @Preview(name = "Driver Level Queries")
-    BookmarkManager queryTaskBookmarkManager();
+    BookmarkManager executableQueryBookmarkManager();
 
     /**
      * Return a flag to indicate whether or not encryption is used for this driver.

driver/src/main/java/org/neo4j/driver/QueryTask.java renamed to driver/src/main/java/org/neo4j/driver/ExecutableQuery.java

@@ -29,22 +29,21 @@
 import org.neo4j.driver.util.Preview;
 
 /**
- * A task that executes a query in a managed transaction with automatic retries on retryable errors.
+ * An executable query that executes a query in a managed transaction with automatic retries on retryable errors.
  * <p>
  * This is a high-level API for executing a query. There are more advanced APIs available.
  * For instance, {@link Session}, {@link Transaction} and transaction functions that are accessible via
  * methods like {@link Session#executeWrite(TransactionCallback)}, {@link Session#executeWriteWithoutResult(Consumer)}
  * and {@link Session#executeRead(TransactionCallback)} (there are also overloaded options available).
  * <p>
- * Causal consistency is managed via driver's {@link BookmarkManager} that is enabled by default and may
- * be replaced using {@link Config.ConfigBuilder#withQueryTaskBookmarkManager(BookmarkManager)}. It is also possible
+ * Causal consistency is managed via driver's {@link BookmarkManager} that is enabled by default. It is possible
  * to use a different {@link BookmarkManager} or disable it via
  * {@link QueryConfig.Builder#withBookmarkManager(BookmarkManager)} on individual basis.
  * <p>
  * Sample usage:
  * <pre>
  * {@code
- * var eagerResult = driver.queryTask("CREATE (n{field: $value}) RETURN n")
+ * var eagerResult = driver.executableQuery("CREATE (n{field: $value}) RETURN n")
  *         .withParameters(Map.of("value", "5"))
  *         .execute();
  * }
@@ -72,13 +71,13 @@
  * {@code
  * import static java.util.stream.Collectors.*;
  *
- * var averagingLong = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
+ * var averagingLong = driver.executableQuery("UNWIND range(0, 5) as N RETURN N")
  *         .execute(averagingLong(record -> record.get("N").asLong()));
  *
- * var filteredValues = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
+ * var filteredValues = driver.executableQuery("UNWIND range(0, 5) as N RETURN N")
  *         .execute(mapping(record -> record.get("N").asLong(), filtering(value -> value > 2, toList())));
  *
- * var maxValue = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
+ * var maxValue = driver.executableQuery("UNWIND range(0, 5) as N RETURN N")
  *         .execute(mapping(record -> record.get("N").asLong(), maxBy(Long::compare)));
  * }
  * </pre>
@@ -90,32 +89,32 @@
  *
  * private record ResultValue(List<String> keys, Set<Long> values, ResultSummary summary) {}
  *
- * var result = driver.queryTask("UNWIND range(0, 5) as N RETURN N")
+ * var result = driver.executableQuery("UNWIND range(0, 5) as N RETURN N")
  *                     .execute(Collectors.mapping(record -> record.get("N").asLong(), toSet()), ResultValue::new);
  * }
  * </pre>
  *
- * @since 5.5
+ * @since 5.7
  */
 @Preview(name = "Driver Level Queries")
-public interface QueryTask {
+public interface ExecutableQuery {
     /**
      * Sets query parameters.
      *
      * @param parameters parameters map, must not be {@code null}
-     * @return a new query task
+     * @return a new executable query
      */
-    QueryTask withParameters(Map<String, Object> parameters);
+    ExecutableQuery withParameters(Map<String, Object> parameters);
 
     /**
      * Sets {@link QueryConfig}.
      * <p>
-     * By default, {@link QueryTask} has {@link QueryConfig#defaultConfig()} value.
+     * By default, {@link ExecutableQuery} has {@link QueryConfig#defaultConfig()} value.
      *
      * @param config query config, must not be {@code null}
-     * @return a new query task
+     * @return a new executable query
      */
-    QueryTask withConfig(QueryConfig config);
+    ExecutableQuery withConfig(QueryConfig config);
 
     /**
      * Executes query, collects all results eagerly and returns a result.

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

@@ -27,7 +27,7 @@
 import org.neo4j.driver.util.Preview;
 
 /**
- * Query configuration used by {@link Driver#queryTask(String)} and its variants.
+ * Query configuration used by {@link Driver#executableQuery(String)} and its variants.
  * @since 5.5
  */
 @Preview(name = "Driver Level Queries")
@@ -116,7 +116,6 @@ public Optional<String> impersonatedUser() {
      * Returns bookmark manager for the query.
      *
      * @param defaultBookmarkManager default bookmark manager to use when none has been configured explicitly,
-     * {@link Config#queryTaskBookmarkManager()} as a default value by the driver
      * @return bookmark manager
      */
     public Optional<BookmarkManager> bookmarkManager(BookmarkManager defaultBookmarkManager) {

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

@@ -275,8 +275,7 @@ protected InternalDriver createRoutingDriver(
      */
     protected InternalDriver createDriver(
             SecurityPlan securityPlan, SessionFactory sessionFactory, MetricsProvider metricsProvider, Config config) {
-        return new InternalDriver(
-                config.queryTaskBookmarkManager(), securityPlan, sessionFactory, metricsProvider, config.logging());
+        return new InternalDriver(securityPlan, sessionFactory, metricsProvider, config.logging());
     }
 
     /**

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

@@ -25,13 +25,15 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 import org.neo4j.driver.BaseSession;
 import org.neo4j.driver.BookmarkManager;
+import org.neo4j.driver.BookmarkManagerConfig;
+import org.neo4j.driver.BookmarkManagers;
 import org.neo4j.driver.Driver;
+import org.neo4j.driver.ExecutableQuery;
 import org.neo4j.driver.Logger;
 import org.neo4j.driver.Logging;
 import org.neo4j.driver.Metrics;
 import org.neo4j.driver.Query;
 import org.neo4j.driver.QueryConfig;
-import org.neo4j.driver.QueryTask;
 import org.neo4j.driver.Session;
 import org.neo4j.driver.SessionConfig;
 import org.neo4j.driver.async.AsyncSession;
@@ -47,7 +49,8 @@
 import org.neo4j.driver.types.TypeSystem;
 
 public class InternalDriver implements Driver {
-    private final BookmarkManager queryBookmarkManager;
+    private final BookmarkManager queryBookmarkManager =
+            BookmarkManagers.defaultManager(BookmarkManagerConfig.builder().build());
     private final SecurityPlan securityPlan;
     private final SessionFactory sessionFactory;
     private final Logger log;
@@ -56,25 +59,23 @@ public class InternalDriver implements Driver {
     private final MetricsProvider metricsProvider;
 
     InternalDriver(
-            BookmarkManager queryBookmarkManager,
             SecurityPlan securityPlan,
             SessionFactory sessionFactory,
             MetricsProvider metricsProvider,
             Logging logging) {
-        this.queryBookmarkManager = queryBookmarkManager;
         this.securityPlan = securityPlan;
         this.sessionFactory = sessionFactory;
         this.metricsProvider = metricsProvider;
         this.log = logging.getLog(getClass());
     }
 
     @Override
-    public QueryTask queryTask(String query) {
-        return new InternalQueryTask(this, new Query(query), QueryConfig.defaultConfig());
+    public ExecutableQuery executableQuery(String query) {
+        return new InternalExecutableQuery(this, new Query(query), QueryConfig.defaultConfig());
     }
 
     @Override
-    public BookmarkManager queryTaskBookmarkManager() {
+    public BookmarkManager executableQueryBookmarkManager() {
         return queryBookmarkManager;
     }
 

driver/src/main/java/org/neo4j/driver/internal/InternalQueryTask.java renamed to driver/src/main/java/org/neo4j/driver/internal/InternalExecutableQuery.java

@@ -23,19 +23,19 @@
 import java.util.Map;
 import java.util.stream.Collector;
 import org.neo4j.driver.Driver;
+import org.neo4j.driver.ExecutableQuery;
 import org.neo4j.driver.Query;
 import org.neo4j.driver.QueryConfig;
-import org.neo4j.driver.QueryTask;
 import org.neo4j.driver.Record;
 import org.neo4j.driver.SessionConfig;
 import org.neo4j.driver.TransactionCallback;
 
-public class InternalQueryTask implements QueryTask {
+public class InternalExecutableQuery implements ExecutableQuery {
     private final Driver driver;
     private final Query query;
     private final QueryConfig config;
 
-    public InternalQueryTask(Driver driver, Query query, QueryConfig config) {
+    public InternalExecutableQuery(Driver driver, Query query, QueryConfig config) {
         requireNonNull(driver, "driver must not be null");
         requireNonNull(query, "query must not be null");
         requireNonNull(config, "config must not be null");
@@ -45,23 +45,24 @@ public InternalQueryTask(Driver driver, Query query, QueryConfig config) {
     }
 
     @Override
-    public QueryTask withParameters(Map<String, Object> parameters) {
+    public ExecutableQuery withParameters(Map<String, Object> parameters) {
         requireNonNull(parameters, "parameters must not be null");
-        return new InternalQueryTask(driver, query.withParameters(parameters), config);
+        return new InternalExecutableQuery(driver, query.withParameters(parameters), config);
     }
 
     @Override
-    public QueryTask withConfig(QueryConfig config) {
+    public ExecutableQuery withConfig(QueryConfig config) {
         requireNonNull(config, "config must not be null");
-        return new InternalQueryTask(driver, query, config);
+        return new InternalExecutableQuery(driver, query, config);
     }
 
     @Override
     public <A, R, T> T execute(Collector<Record, A, R> recordCollector, ResultFinisher<R, T> resultFinisher) {
         var sessionConfigBuilder = SessionConfig.builder();
         config.database().ifPresent(sessionConfigBuilder::withDatabase);
         config.impersonatedUser().ifPresent(sessionConfigBuilder::withImpersonatedUser);
-        config.bookmarkManager(driver.queryTaskBookmarkManager()).ifPresent(sessionConfigBuilder::withBookmarkManager);
+        config.bookmarkManager(driver.executableQueryBookmarkManager())
+                .ifPresent(sessionConfigBuilder::withBookmarkManager);
         var supplier = recordCollector.supplier();
         var accumulator = recordCollector.accumulator();
         var finisher = recordCollector.finisher();