Introduce new session instantiation methods (#1326)

These new methods provide a consistent API for creating different types of session APIs.

Sample usage:
```
var synchronousSession = driver.session(Session.class);
var asynchronousSession = driver.session(AsyncSession.class);
var reactiveSession1 = driver.session(org.neo4j.driver.reactive.ReactiveSession.class);
var reactiveSession2 = driver.session(org.neo4j.driver.reactivestreams.ReactiveSession.class);
var reactiveSession3 = driver.session(org.neo4j.driver.reactive.RxSession.class);
```

The following methods have been deprecated:
- `asyncSession`
- `reactiveSession`

Author: injectives

driver/clirr-ignored-differences.xml

@@ -400,13 +400,13 @@
     <difference>
         <className>org/neo4j/driver/Driver</className>
         <differenceType>7012</differenceType>
-        <method>org.neo4j.driver.BaseReactiveSession reactiveSession(java.lang.Class)</method>
+        <method>org.neo4j.driver.BaseSession session(java.lang.Class)</method>
     </difference>
 
     <difference>
         <className>org/neo4j/driver/Driver</className>
         <differenceType>7012</differenceType>
-        <method>org.neo4j.driver.BaseReactiveSession reactiveSession(java.lang.Class, org.neo4j.driver.SessionConfig)</method>
+        <method>org.neo4j.driver.BaseSession session(java.lang.Class, org.neo4j.driver.SessionConfig)</method>
     </difference>
 
 </differences>

…rg/neo4j/driver/BaseReactiveSession.java …n/java/org/neo4j/driver/BaseSession.javadriver/src/main/java/org/neo4j/driver/BaseReactiveSession.java renamed to driver/src/main/java/org/neo4j/driver/BaseSession.java driver/src/main/java/org/neo4j/driver/BaseReactiveSession.java renamed to driver/src/main/java/org/neo4j/driver/BaseSession.java

@@ -19,6 +19,6 @@
 package org.neo4j.driver;
 
 /**
- * A base interface for reactive sessions, used by {@link Driver#reactiveSession(Class)} and {@link Driver#reactiveSession(Class, SessionConfig)}.
+ * A base interface for sessions, used by {@link Driver#session(Class)} and {@link Driver#session(Class, SessionConfig)}.
  */
-public interface BaseReactiveSession {}
+public interface BaseSession {}

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

@@ -78,17 +78,80 @@ public interface Driver extends AutoCloseable {
      * @return a new {@link Session} object.
      */
     default Session session() {
-        return session(SessionConfig.defaultConfig());
+        return session(Session.class);
     }
 
     /**
-     * Create a new {@link Session} with a specified {@link SessionConfig session configuration}.
+     * 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
      */
-    Session session(SessionConfig sessionConfig);
+    default Session session(SessionConfig sessionConfig) {
+        return session(Session.class, sessionConfig);
+    }
+
+    /**
+     * Instantiate a new session of supported type with default {@link SessionConfig session configuration}.
+     * <p>
+     * Supported types are:
+     * <ul>
+     *     <li>{@link org.neo4j.driver.Session} - synchronous session</li>
+     *     <li>{@link org.neo4j.driver.async.AsyncSession} - asynchronous session</li>
+     *     <li>{@link org.neo4j.driver.reactive.ReactiveSession} - reactive session using Flow API</li>
+     *     <li>{@link org.neo4j.driver.reactivestreams.ReactiveSession} - reactive session using Reactive Streams
+     * API</li>
+     *     <li>{@link org.neo4j.driver.reactive.RxSession} - deprecated reactive session using Reactive Streams
+     * API, superseded by {@link org.neo4j.driver.reactivestreams.ReactiveSession}</li>
+     * </ul>
+     * <p>
+     * Sample usage:
+     * <pre>
+     * {@code
+     * var session = driver.session(AsyncSession.class);
+     * }
+     * </pre>
+     *
+     * @param sessionClass session type class, must not be null
+     * @return session instance
+     * @param <T> session type
+     * @throws IllegalArgumentException for unsupported session types
+     * @since 5.2
+     */
+    default <T extends BaseSession> T session(Class<T> sessionClass) {
+        return session(sessionClass, SessionConfig.defaultConfig());
+    }
+
+    /**
+     * Create a new session of supported type with a specified {@link SessionConfig session configuration}.
+     * <p>
+     * Supported types are:
+     * <ul>
+     *     <li>{@link org.neo4j.driver.Session} - synchronous session</li>
+     *     <li>{@link org.neo4j.driver.async.AsyncSession} - asynchronous session</li>
+     *     <li>{@link org.neo4j.driver.reactive.ReactiveSession} - reactive session using Flow API</li>
+     *     <li>{@link org.neo4j.driver.reactivestreams.ReactiveSession} - reactive session using Reactive Streams
+     * API</li>
+     *     <li>{@link org.neo4j.driver.reactive.RxSession} - deprecated reactive session using Reactive Streams
+     * API, superseded by {@link org.neo4j.driver.reactivestreams.ReactiveSession}</li>
+     * </ul>
+     * <p>
+     * Sample usage:
+     * <pre>
+     * {@code
+     * var session = driver.session(AsyncSession.class);
+     * }
+     * </pre>
+     *
+     * @param sessionClass session type class, must not be null
+     * @param sessionConfig session config, must not be null
+     * @return session instance
+     * @param <T> session type
+     * @throws IllegalArgumentException for unsupported session types
+     * @since 5.2
+     */
+    <T extends BaseSession> T session(Class<T> sessionClass, SessionConfig sessionConfig);
 
     /**
      * Create a new general purpose {@link RxSession} with default {@link SessionConfig session configuration}. The {@link RxSession} provides a reactive way to
@@ -97,11 +160,11 @@ default Session session() {
      * Alias to {@link #rxSession(SessionConfig)}}.
      *
      * @return a new {@link RxSession} object.
-     * @deprecated superseded by {@link #reactiveSession()}.
+     * @deprecated superseded by {@link #session(Class)}
      */
     @Deprecated
     default RxSession rxSession() {
-        return rxSession(SessionConfig.defaultConfig());
+        return session(RxSession.class);
     }
 
     /**
@@ -110,10 +173,12 @@ default RxSession rxSession() {
      *
      * @param sessionConfig used to customize the session.
      * @return a new {@link RxSession} object.
-     * @deprecated superseded by {@link #reactiveSession(SessionConfig)}.
+     * @deprecated superseded by {@link #session(Class, SessionConfig)}
      */
     @Deprecated
-    RxSession rxSession(SessionConfig sessionConfig);
+    default RxSession rxSession(SessionConfig sessionConfig) {
+        return session(RxSession.class, sessionConfig);
+    }
 
     /**
      * Create a new general purpose {@link ReactiveSession} with default {@link SessionConfig session configuration}. The {@link ReactiveSession} provides a
@@ -122,9 +187,11 @@ default RxSession rxSession() {
      * Alias to {@link #rxSession(SessionConfig)}}.
      *
      * @return a new {@link ReactiveSession} object.
+     * @deprecated superseded by {@link #session(Class)}
      */
+    @Deprecated
     default ReactiveSession reactiveSession() {
-        return reactiveSession(SessionConfig.defaultConfig());
+        return session(ReactiveSession.class);
     }
 
     /**
@@ -134,53 +201,25 @@ default ReactiveSession reactiveSession() {
      *
      * @param sessionConfig used to customize the session.
      * @return a new {@link ReactiveSession} object.
+     * @deprecated superseded by {@link #session(Class, SessionConfig)}
      */
+    @Deprecated
     default ReactiveSession reactiveSession(SessionConfig sessionConfig) {
-        return reactiveSession(ReactiveSession.class, sessionConfig);
-    }
-
-    /**
-     * Create a new reactive session of supported type with default {@link SessionConfig session configuration}.
-     * <p>
-     * Supported types are:
-     * <ul>
-     *     <li>{@link org.neo4j.driver.reactive.ReactiveSession} - reactive session using Flow API</li>
-     *     <li>{@link org.neo4j.driver.reactivestreams.ReactiveSession} - reactive session using Reactive Streams API</li>
-     * </ul>
-     *
-     * @param sessionClass session type class
-     * @return session instance
-     * @param <T> session type
-     */
-    default <T extends BaseReactiveSession> T reactiveSession(Class<T> sessionClass) {
-        return reactiveSession(sessionClass, SessionConfig.defaultConfig());
+        return session(ReactiveSession.class, sessionConfig);
     }
 
-    /**
-     * Create a new reactive session of supported type with a specified {@link SessionConfig session configuration}.
-     * <p>
-     * Supported types are:
-     * <ul>
-     *     <li>{@link org.neo4j.driver.reactive.ReactiveSession} - reactive session using Flow API</li>
-     *     <li>{@link org.neo4j.driver.reactivestreams.ReactiveSession} - reactive session using Reactive Streams API</li>
-     * </ul>
-     *
-     * @param sessionClass session type class
-     * @return session instance
-     * @param <T> session type
-     */
-    <T extends BaseReactiveSession> T reactiveSession(Class<T> sessionClass, SessionConfig sessionConfig);
-
     /**
      * Create a new general purpose {@link AsyncSession} with default {@link SessionConfig session configuration}. The {@link AsyncSession} provides an
      * asynchronous way to run queries and process results.
      * <p>
      * Alias to {@link #asyncSession(SessionConfig)}}.
      *
      * @return a new {@link AsyncSession} object.
+     * @deprecated superseded by {@link #session(Class)}
      */
+    @Deprecated
     default AsyncSession asyncSession() {
-        return asyncSession(SessionConfig.defaultConfig());
+        return session(AsyncSession.class);
     }
 
     /**
@@ -190,8 +229,12 @@ default AsyncSession asyncSession() {
      *
      * @param sessionConfig used to customize the session.
      * @return a new {@link AsyncSession} object.
+     * @deprecated superseded by {@link #session(Class, SessionConfig)}
      */
-    AsyncSession asyncSession(SessionConfig sessionConfig);
+    @Deprecated
+    default AsyncSession asyncSession(SessionConfig sessionConfig) {
+        return session(AsyncSession.class, sessionConfig);
+    }
 
     /**
      * Close all the resources assigned to this driver, including open connections and IO threads.

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

@@ -53,7 +53,7 @@
  *
  * @since 1.0 (Removed async API to {@link AsyncSession} in 4.0)
  */
-public interface Session extends Resource, QueryRunner {
+public interface Session extends BaseSession, Resource, QueryRunner {
     /**
      * Begin a new <em>unmanaged {@linkplain Transaction transaction}</em>. At
      * most one transaction may exist in a session at any point in time. To

driver/src/main/java/org/neo4j/driver/async/AsyncSession.java

@@ -25,6 +25,7 @@
 import java.util.concurrent.Executor;
 import java.util.function.Function;
 import org.neo4j.driver.AccessMode;
+import org.neo4j.driver.BaseSession;
 import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.Query;
 import org.neo4j.driver.Result;
@@ -70,7 +71,7 @@
  *
  * @since 4.0
  */
-public interface AsyncSession extends AsyncQueryRunner {
+public interface AsyncSession extends BaseSession, AsyncQueryRunner {
     /**
      * Begin a new <em>unmanaged {@linkplain Transaction transaction}</em>. At
      * most one transaction may exist in a session at any point in time. To

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

@@ -23,7 +23,7 @@
 
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.atomic.AtomicBoolean;
-import org.neo4j.driver.BaseReactiveSession;
+import org.neo4j.driver.BaseSession;
 import org.neo4j.driver.Driver;
 import org.neo4j.driver.Logger;
 import org.neo4j.driver.Logging;
@@ -61,35 +61,28 @@ public class InternalDriver implements Driver {
         this.log = logging.getLog(getClass());
     }
 
+    @SuppressWarnings({"unchecked", "deprecation"})
     @Override
-    public Session session(SessionConfig sessionConfig) {
-        return new InternalSession(newSession(sessionConfig));
-    }
-
-    @Override
-    @Deprecated
-    public RxSession rxSession(SessionConfig sessionConfig) {
-        return new InternalRxSession(newSession(sessionConfig));
-    }
-
-    @SuppressWarnings({"deprecation", "unchecked"})
-    @Override
-    public <T extends BaseReactiveSession> T reactiveSession(Class<T> sessionClass, SessionConfig sessionConfig) {
+    public <T extends BaseSession> T session(Class<T> sessionClass, SessionConfig sessionConfig) {
         requireNonNull(sessionClass, "sessionClass must not be null");
         requireNonNull(sessionClass, "sessionConfig must not be null");
-        if (org.neo4j.driver.reactive.ReactiveSession.class.isAssignableFrom(sessionClass)) {
-            return (T) new org.neo4j.driver.internal.reactive.InternalReactiveSession(newSession(sessionConfig));
+        T session;
+        if (Session.class.isAssignableFrom(sessionClass)) {
+            session = (T) new InternalSession(newSession(sessionConfig));
+        } else if (AsyncSession.class.isAssignableFrom(sessionClass)) {
+            session = (T) new InternalAsyncSession(newSession(sessionConfig));
+        } else if (org.neo4j.driver.reactive.ReactiveSession.class.isAssignableFrom(sessionClass)) {
+            session = (T) new org.neo4j.driver.internal.reactive.InternalReactiveSession(newSession(sessionConfig));
         } else if (org.neo4j.driver.reactivestreams.ReactiveSession.class.isAssignableFrom(sessionClass)) {
-            return (T) new org.neo4j.driver.internal.reactivestreams.InternalReactiveSession(newSession(sessionConfig));
+            session = (T)
+                    new org.neo4j.driver.internal.reactivestreams.InternalReactiveSession(newSession(sessionConfig));
+        } else if (RxSession.class.isAssignableFrom(sessionClass)) {
+            session = (T) new InternalRxSession(newSession(sessionConfig));
         } else {
             throw new IllegalArgumentException(
                     String.format("Unsupported session type '%s'", sessionClass.getCanonicalName()));
         }
-    }
-
-    @Override
-    public AsyncSession asyncSession(SessionConfig sessionConfig) {
-        return new InternalAsyncSession(newSession(sessionConfig));
+        return session;
     }
 
     @Override

driver/src/main/java/org/neo4j/driver/reactive/ReactiveSession.java

@@ -23,7 +23,7 @@
 import java.util.concurrent.CompletionStage;
 import java.util.concurrent.Flow.Publisher;
 import org.neo4j.driver.AccessMode;
-import org.neo4j.driver.BaseReactiveSession;
+import org.neo4j.driver.BaseSession;
 import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.Query;
 import org.neo4j.driver.Result;
@@ -40,7 +40,7 @@
  * @see Publisher
  * @since 5.0
  */
-public interface ReactiveSession extends BaseReactiveSession, ReactiveQueryRunner {
+public interface ReactiveSession extends BaseSession, ReactiveQueryRunner {
     /**
      * Begin a new <em>unmanaged {@linkplain ReactiveTransaction transaction}</em>. At most one transaction may exist in a session at any point in time. To
      * maintain multiple concurrent transactions, use multiple concurrent sessions.

driver/src/main/java/org/neo4j/driver/reactive/RxSession.java

@@ -21,6 +21,7 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import org.neo4j.driver.AccessMode;
+import org.neo4j.driver.BaseSession;
 import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.Query;
 import org.neo4j.driver.Session;
@@ -38,7 +39,7 @@
  * @deprecated superseded by {@link org.neo4j.driver.reactive.ReactiveSession} and {@link org.neo4j.driver.reactivestreams.ReactiveSession}
  */
 @Deprecated
-public interface RxSession extends RxQueryRunner {
+public interface RxSession extends BaseSession, RxQueryRunner {
     /**
      * Begin a new <em>unmanaged {@linkplain RxTransaction transaction}</em>. At most one transaction may exist in a session at any point in time. To maintain
      * multiple concurrent transactions, use multiple concurrent sessions.

driver/src/main/java/org/neo4j/driver/reactivestreams/ReactiveSession.java

@@ -22,7 +22,7 @@
 import java.util.Set;
 import java.util.concurrent.CompletionStage;
 import org.neo4j.driver.AccessMode;
-import org.neo4j.driver.BaseReactiveSession;
+import org.neo4j.driver.BaseSession;
 import org.neo4j.driver.Bookmark;
 import org.neo4j.driver.Query;
 import org.neo4j.driver.Result;
@@ -40,7 +40,7 @@
  * @see Publisher
  * @since 5.2
  */
-public interface ReactiveSession extends BaseReactiveSession, ReactiveQueryRunner {
+public interface ReactiveSession extends BaseSession, ReactiveQueryRunner {
     /**
      * Begin a new <em>unmanaged {@linkplain ReactiveTransaction transaction}</em>. At most one transaction may exist in a session at any point in time. To
      * maintain multiple concurrent transactions, use multiple concurrent sessions.

driver/src/test/java/org/neo4j/driver/integration/QueryRunnerCloseIT.java

@@ -133,7 +133,7 @@ void shouldAllowSummaryAndKeysAfterClose() {
     @Test
     void shouldErrorToAccessRecordsAfterConsumeAsync() {
         // Given
-        AsyncSession session = neo4j.driver().asyncSession();
+        AsyncSession session = neo4j.driver().session(AsyncSession.class);
         ResultCursor result = await(session.runAsync("UNWIND [1,2] AS a RETURN a"));
 
         // When
@@ -151,7 +151,7 @@ void shouldErrorToAccessRecordsAfterConsumeAsync() {
     @Test
     void shouldErrorToAccessRecordsAfterCloseAsync() {
         // Given
-        AsyncSession session = neo4j.driver().asyncSession();
+        AsyncSession session = neo4j.driver().session(AsyncSession.class);
         ResultCursor result = await(session.runAsync("UNWIND [1,2] AS a RETURN a"));
 
         // When
@@ -169,7 +169,7 @@ void shouldErrorToAccessRecordsAfterCloseAsync() {
     @Test
     void shouldAllowConsumeAndKeysAfterConsumeAsync() {
         // Given
-        AsyncSession session = neo4j.driver().asyncSession();
+        AsyncSession session = neo4j.driver().session(AsyncSession.class);
         ResultCursor result = await(session.runAsync("UNWIND [1,2] AS a RETURN a"));
 
         List<String> keys = result.keys();
@@ -188,7 +188,7 @@ void shouldAllowConsumeAndKeysAfterConsumeAsync() {
     @Test
     void shouldAllowConsumeAndKeysAfterCloseAsync() {
         // Given
-        AsyncSession session = neo4j.driver().asyncSession();
+        AsyncSession session = neo4j.driver().session(AsyncSession.class);
         ResultCursor result = await(session.runAsync("UNWIND [1,2] AS a RETURN a"));
         List<String> keys = result.keys();
         ResultSummary summary = await(result.consumeAsync());