Unified the input and output value of database name.

The database name default to `null` if the server does not support multi-databases when the database name is returned in result summary.
However `null` is a forbidden value for database in session parameters. Then for user who want to connect to default db but do not want ot omit invoke `withDatabase` method on session parameter, they have to use empty string to work aroud our API design.

This PR allows `null` as a valid database name for session parameters, while disallows empty string as it is an invalid database name to users.

Author: Zhen Li

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

@@ -58,8 +58,9 @@ public interface SessionParametersTemplate
 
     /**
      * Set the database that the newly created session is going to connect to.
-     * The given database name cannot be <code>null</code>.
-     * If the database name is not set, then the default database configured on the server configuration will be connected when the session established.
+     * If the database name is not set or the database name is set to <code>null</code>,
+     * then the default database configured in the server configuration will be connected when the session is established.
+     * For servers that do not support multi-databases, this database value should not be set or could only be set to <code>null</code>.
      *
      * @param database the database the session going to connect to.
      * @return this builder.

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

@@ -28,6 +28,8 @@
 import org.neo4j.driver.internal.retry.RetryLogic;
 import org.neo4j.driver.internal.spi.ConnectionProvider;
 
+import static org.neo4j.driver.internal.messaging.request.MultiDatabaseUtil.ABSENT_DB_NAME;
+
 public class SessionFactoryImpl implements SessionFactory
 {
     private final ConnectionProvider connectionProvider;
@@ -47,7 +49,7 @@ public class SessionFactoryImpl implements SessionFactory
     public NetworkSession newInstance( SessionParameters parameters )
     {
         BookmarksHolder bookmarksHolder = new DefaultBookmarksHolder( Bookmarks.from( parameters.bookmarks() ) );
-        return createSession( connectionProvider, retryLogic, parameters.database(), parameters.defaultAccessMode(), bookmarksHolder, logging );
+        return createSession( connectionProvider, retryLogic, parameters.database().orElse( ABSENT_DB_NAME ), parameters.defaultAccessMode(), bookmarksHolder, logging );
     }
 
     @Override

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

@@ -21,6 +21,7 @@
 import java.util.Arrays;
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 
 import org.neo4j.driver.AccessMode;
 import org.neo4j.driver.SessionParametersTemplate;
@@ -87,11 +88,11 @@ public AccessMode defaultAccessMode()
 
     /**
      * The database where the session is going to connect to.
-     * @return the database name where the session is going to connect to.
+     * @return the nullable database name where the session is going to connect to.
      */
-    public String database()
+    public Optional<String> database()
     {
-        return database;
+        return Optional.ofNullable( database );
     }
 
     @Override
@@ -125,7 +126,7 @@ public static class Template implements SessionParametersTemplate
     {
         private List<String> bookmarks = null;
         private AccessMode defaultAccessMode = AccessMode.WRITE;
-        private String database = ABSENT_DB_NAME;
+        private String database = null;
 
         private Template()
         {
@@ -162,7 +163,11 @@ public Template withDefaultAccessMode( AccessMode mode )
         @Override
         public Template withDatabase( String database )
         {
-            Objects.requireNonNull( database, "Database cannot be null." );
+            if ( ABSENT_DB_NAME.equals( database ) )
+            {
+                // Disallow users to use bolt internal value directly. To users, this is totally an illegal database name.
+                throw new IllegalArgumentException( String.format( "Illegal database name '%s'.", database ) );
+            }
             this.database = database;
             return this;
         }

driver/src/test/java/org/neo4j/driver/internal/SessionParametersTest.java

@@ -34,7 +34,9 @@
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.neo4j.driver.internal.SessionParameters.empty;
 import static org.neo4j.driver.internal.SessionParameters.template;
 import static org.neo4j.driver.internal.messaging.request.MultiDatabaseUtil.ABSENT_DB_NAME;
@@ -47,7 +49,7 @@ void shouldReturnDefaultValues() throws Throwable
         SessionParameters parameters = empty();
 
         Assert.assertEquals( AccessMode.WRITE, parameters.defaultAccessMode() );
-        assertEquals( ABSENT_DB_NAME, parameters.database() );
+        assertFalse( parameters.database().isPresent() );
         assertNull( parameters.bookmarks() );
     }
 
@@ -60,18 +62,28 @@ void shouldChangeAccessMode( AccessMode mode ) throws Throwable
     }
 
     @ParameterizedTest
-    @ValueSource( strings = {"", "foo", "data", ABSENT_DB_NAME} )
+    @ValueSource( strings = {"foo", "data", "my awesome database", " "} )
     void shouldChangeDatabaseName( String databaseName )
     {
         SessionParameters parameters = template().withDatabase( databaseName ).build();
-        assertEquals( databaseName, parameters.database() );
+        assertTrue( parameters.database().isPresent() );
+        assertEquals( databaseName, parameters.database().get() );
     }
 
     @Test
-    void shouldForbiddenNullDatabaseName() throws Throwable
+    void shouldAllowNullDatabaseName() throws Throwable
     {
-        NullPointerException error = assertThrows( NullPointerException.class, () -> template().withDatabase( null ).build());
-        assertThat( error.getMessage(), equalTo( "Database cannot be null." ) );
+        SessionParameters parameters = template().withDatabase( null ).build();
+        assertFalse( parameters.database().isPresent() );
+        assertEquals( "", parameters.database().orElse( ABSENT_DB_NAME ) );
+    }
+
+    @ParameterizedTest
+    @ValueSource( strings = {"", ABSENT_DB_NAME} )
+    void shouldForbiddenEmptyStringDatabaseName( String databaseName ) throws Throwable
+    {
+        IllegalArgumentException error = assertThrows( IllegalArgumentException.class, () -> template().withDatabase( databaseName ).build());
+        assertThat( error.getMessage(), equalTo( "Illegal database name ''." ) );
     }
 
     @Test