Introduce executeQuery on Driver level (#1321)

* Introduce executeQuery on Driver level

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

* Delete DriverQueryBookmarkManagerPlaceholder

* Update documentation

* Update documentation

Author: injectives

driver/clirr-ignored-differences.xml

@@ -391,4 +391,40 @@
         <differenceType>3003</differenceType>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.EagerResult executeQuery(org.neo4j.driver.Query)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>java.lang.Object executeQuery(org.neo4j.driver.Query, org.neo4j.driver.QueryConfig)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.EagerResult executeQuery(java.lang.String)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>org.neo4j.driver.EagerResult executeQuery(java.lang.String, java.util.Map)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7012</differenceType>
+        <method>java.lang.Object executeQuery(java.lang.String, java.util.Map, org.neo4j.driver.QueryConfig)</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/org/neo4j/driver/Config.java

@@ -75,7 +75,11 @@ public final class Config implements Serializable {
 
     private static final Config EMPTY = builder().build();
 
-    /** User defined logging */
+    private final BookmarkManager queryBookmarkManager;
+
+    /**
+     * User defined logging
+     */
     private final Logging logging;
 
     private final boolean logLeakedSessions;
@@ -100,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;
 
@@ -121,8 +126,22 @@ private Config(ConfigBuilder builder) {
         this.metricsAdapter = builder.metricsAdapter;
     }
 
+    /**
+     * A {@link BookmarkManager} implementation for the driver to use on
+     * {@link Driver#executeQuery(Query, QueryConfig)} 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
+     *
      * @return the Logging provider to use
      */
     public Logging logging() {
@@ -256,6 +275,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;
@@ -275,6 +296,22 @@ public static final class ConfigBuilder {
 
         private ConfigBuilder() {}
 
+        /**
+         * Sets a {@link BookmarkManager} implementation for the driver to use on
+         * {@link Driver#executeQuery(Query, QueryConfig)} 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
@@ -331,7 +368,7 @@ public ConfigBuilder withLeakedSessionsLogging() {
          * validity and negative values mean connections will never be tested.
          *
          * @param value the minimum idle time
-         * @param unit the unit in which the duration is given
+         * @param unit  the unit in which the duration is given
          * @return this builder
          */
         public ConfigBuilder withConnectionLivenessCheckTimeout(long value, TimeUnit unit) {
@@ -356,7 +393,7 @@ public ConfigBuilder withConnectionLivenessCheckTimeout(long value, TimeUnit uni
          * checked.
          *
          * @param value the maximum connection lifetime
-         * @param unit the unit in which the duration is given
+         * @param unit  the unit in which the duration is given
          * @return this builder
          */
         public ConfigBuilder withMaxConnectionLifetime(long value, TimeUnit unit) {
@@ -402,7 +439,7 @@ public ConfigBuilder withMaxConnectionPoolSize(int value) {
          * of {@code 0} is allowed and results in no timeout and immediate failure when connection is unavailable.
          *
          * @param value the acquisition timeout
-         * @param unit the unit in which the duration is given
+         * @param unit  the unit in which the duration is given
          * @return this builder
          * @see #withMaxConnectionPoolSize(int)
          */
@@ -418,6 +455,7 @@ public ConfigBuilder withConnectionAcquisitionTimeout(long value, TimeUnit unit)
 
         /**
          * Set to use encrypted traffic.
+         *
          * @return this builder
          */
         public ConfigBuilder withEncryption() {
@@ -427,6 +465,7 @@ public ConfigBuilder withEncryption() {
 
         /**
          * Set to use unencrypted traffic.
+         *
          * @return this builder
          */
         public ConfigBuilder withoutEncryption() {
@@ -461,13 +500,12 @@ public ConfigBuilder withTrustStrategy(TrustStrategy trustStrategy) {
          * The routing table of a database get refreshed if the database is used frequently.
          * If the database is not used for a long time,
          * the driver use the timeout specified here to purge the stale routing table.
-         *
+         * <p>
          * After a routing table is removed, next time when using the database of the purged routing table,
          * the driver will fall back to use seed URI for a new routing table.
-         * @param delay
-         *         the amount of time to wait before purging routing tables
-         * @param unit
-         *         the unit in which the duration is given
+         *
+         * @param delay the amount of time to wait before purging routing tables
+         * @param unit  the unit in which the duration is given
          * @return this builder
          */
         public ConfigBuilder withRoutingTablePurgeDelay(long delay, TimeUnit unit) {
@@ -483,15 +521,16 @@ public ConfigBuilder withRoutingTablePurgeDelay(long delay, TimeUnit unit) {
         /**
          * Specify how many records to fetch in each batch.
          * This config is only valid when the driver is used with servers that support Bolt V4 (Server version 4.0 and later).
-         *
+         * <p>
          * Bolt V4 enables pulling records in batches to allow client to take control of data population and apply back pressure to server.
          * This config specifies the default fetch size for all query runs using {@link Session} and {@link org.neo4j.driver.async.AsyncSession}.
          * By default, the value is set to {@code 1000}.
          * Use {@code -1} to disables back pressure and config client to pull all records at once after each run.
-         *
+         * <p>
          * This config only applies to run result obtained via {@link Session} and {@link org.neo4j.driver.async.AsyncSession}.
          * As with {@link org.neo4j.driver.reactive.RxSession}, the batch size is provided via
          * {@link org.reactivestreams.Subscription#request(long)} instead.
+         *
          * @param size the default record fetch size when pulling records in batches using Bolt V4.
          * @return this builder
          */
@@ -512,10 +551,10 @@ public ConfigBuilder withFetchSize(long size) {
          * The default value of this parameter is {@code 30 SECONDS}.
          *
          * @param value the timeout duration
-         * @param unit the unit in which duration is given
+         * @param unit  the unit in which duration is given
          * @return this builder
          * @throws IllegalArgumentException when given value is negative or does not fit in {@code int} when
-         * converted to milliseconds.
+         *                                  converted to milliseconds.
          */
         public ConfigBuilder withConnectionTimeout(long value, TimeUnit unit) {
             long connectionTimeoutMillis = unit.toMillis(value);
@@ -543,7 +582,7 @@ public ConfigBuilder withConnectionTimeout(long value, TimeUnit unit) {
          * Default value is 30 seconds.
          *
          * @param value the timeout duration
-         * @param unit the unit in which duration is given
+         * @param unit  the unit in which duration is given
          * @return this builder
          * @throws IllegalArgumentException when given value is negative
          */
@@ -586,6 +625,7 @@ public ConfigBuilder withDriverMetrics() {
 
         /**
          * Disable driver metrics. When disabled, driver metrics cannot be accessed via {@link Driver#metrics()}.
+         *
          * @return this builder.
          */
         public ConfigBuilder withoutDriverMetrics() {
@@ -619,6 +659,7 @@ public ConfigBuilder withMetricsAdapter(MetricsAdapter metricsAdapter) {
         /**
          * Configure the event loop thread count. This specifies how many threads the driver can use to handle network I/O events
          * and user's events in driver's I/O threads. By default, 2 * NumberOfProcessors amount of threads will be used instead.
+         *
          * @param size the thread count.
          * @return this builder.
          * @throws IllegalArgumentException if the value of the size is set to a number that is less than 1.
@@ -634,6 +675,7 @@ public ConfigBuilder withEventLoopThreads(int size) {
 
         /**
          * Configure the user_agent field sent to the server to identify the connected client.
+         *
          * @param userAgent the string to configure user_agent.
          * @return this builder.
          */
@@ -802,6 +844,7 @@ public static TrustStrategy trustAllCertificates() {
 
         /**
          * The revocation strategy used for verifying certificates.
+         *
          * @return this {@link TrustStrategy}'s revocation strategy
          */
         public RevocationCheckingStrategy revocationCheckingStrategy() {
@@ -811,6 +854,7 @@ public RevocationCheckingStrategy revocationCheckingStrategy() {
         /**
          * Configures the {@link TrustStrategy} to not carry out OCSP revocation checks on certificates. This is the
          * option that is configured by default.
+         *
          * @return the current trust strategy
          */
         public TrustStrategy withoutCertificateRevocationChecks() {
@@ -823,6 +867,7 @@ public TrustStrategy withoutCertificateRevocationChecks() {
          * stapled to the certificate. If no stapled response is found, then certificate verification continues
          * (and does not fail verification). This setting also requires the server to be configured to enable
          * OCSP stapling.
+         *
          * @return the current trust strategy
          */
         public TrustStrategy withVerifyIfPresentRevocationChecks() {
@@ -834,9 +879,10 @@ public TrustStrategy withVerifyIfPresentRevocationChecks() {
          * Configures the {@link TrustStrategy} to carry out strict OCSP revocation checks for revocation status that
          * are stapled to the certificate. If no stapled response is found, then the driver will fail certificate verification
          * and not connect to the server. This setting also requires the server to be configured to enable OCSP stapling.
-         *
+         * <p>
          * Note: enabling this setting will prevent the driver connecting to the server when the server is unable to reach
          * the certificate's configured OCSP responder URL.
+         *
          * @return the current trust strategy
          */
         public TrustStrategy withStrictRevocationChecks() {