implement ConnectionProvider

src/main/java/com/mongodb/hibernate/exception/NotYetImplementedException.java → src/main/java/com/mongodb/hibernate/NotYetImplementedException.java

@@ -14,12 +14,32 @@
  * limitations under the License.
  */
 
-package com.mongodb.hibernate.exception;
+package com.mongodb.hibernate;
 
+/**
+ * A temporary marker exception to denote that the feature in question is in the scope of MongoDB dialect but has not
+ * been implemented yet.
+ *
+ * <p>Ultimately all of its references should be eliminated sooner or later, and then this class is supposed to be
+ * deleted prior to product release.
+ *
+ * <p>It is recommended to provide some message to explain when it will be implemented (e.g. JIRA ticket id is a good
+ * idea), but that is optional.
+ */
 public class NotYetImplementedException extends RuntimeException {
 
+    /**
+     * Default constructor.
+     *
+     * @deprecated use {@link NotYetImplementedException(String)} instead.
+     */
     public NotYetImplementedException() {}
 
+    /**
+     * Constructor with message parameter.
+     *
+     * @param message explanation on when the feature is to be implemented
+     */
     public NotYetImplementedException(String message) {
         super(message);
     }

src/main/java/com/mongodb/hibernate/dialect/MongoDialect.java

@@ -20,11 +20,28 @@
 import org.hibernate.dialect.Dialect;
 import org.hibernate.engine.jdbc.dialect.spi.DialectResolutionInfo;
 
+/**
+ * A MongoDB {@linkplain Dialect dialect}.
+ *
+ * <p>Usually Hibernate dialect represents some SQL RDBMS and speaks SQL with vendor-specific difference. MongoDB is a
+ * document DB and speaks <i>MQL</i> (MongoDB Query Language) in JSON format, but it is still possible to integrate with
+ * Hibernate seamlessly by creating a JDBC adaptor on top of MongoDB's Java client library.
+ *
+ * <p>Some MongoDB-specific customization examples include:
+ *
+ * <ul>
+ *   <li>MQL translation extension point
+ *   <li>SQL {@linkplain java.sql.Types#ARRAY ARRAY} and {@linkplain java.sql.Types#STRUCT STRUCT} extension points to
+ *       support MongoDB's embedding array and document
+ *   <li>MQL parameterization customization
+ * </ul>
+ */
 public class MongoDialect extends Dialect {
     public static final int MINIMUM_MONGODB_MAJOR_VERSION_SUPPORTED = 6;
+    public static final int MINIMUM_MONGODB_MINOR_VERSION_SUPPORTED = 0;
 
     private static final DatabaseVersion MINIMUM_VERSION =
-            DatabaseVersion.make(MINIMUM_MONGODB_MAJOR_VERSION_SUPPORTED);
+            DatabaseVersion.make(MINIMUM_MONGODB_MAJOR_VERSION_SUPPORTED, MINIMUM_MONGODB_MINOR_VERSION_SUPPORTED);
 
     public MongoDialect() {
         this(MINIMUM_VERSION);

src/main/java/com/mongodb/hibernate/jdbc/MongoConnectionProvider.java

@@ -16,125 +16,100 @@
 
 package com.mongodb.hibernate.jdbc;
 
-import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
 import static org.hibernate.cfg.JdbcSettings.*;
-import static org.hibernate.internal.util.NullnessUtil.castNonNull;
 
 import com.mongodb.ConnectionString;
 import com.mongodb.MongoClientSettings;
-import com.mongodb.MongoCredential;
 import com.mongodb.client.MongoClient;
 import com.mongodb.client.MongoClients;
-import com.mongodb.hibernate.cfg.ConfigurationHelper;
-import com.mongodb.hibernate.exception.ConfigurationException;
-import com.mongodb.hibernate.exception.NotYetImplementedException;
+import com.mongodb.hibernate.NotYetImplementedException;
 import java.sql.Connection;
 import java.util.Map;
+import org.hibernate.HibernateException;
+import org.hibernate.cfg.JdbcSettings;
 import org.hibernate.engine.jdbc.connections.spi.ConnectionProvider;
 import org.hibernate.service.UnknownUnwrapTypeException;
 import org.hibernate.service.spi.Configurable;
-import org.hibernate.service.spi.Startable;
 import org.hibernate.service.spi.Stoppable;
 import org.jspecify.annotations.Nullable;
 
 /**
- * MongoDB dialect's customized JDBC {@link ConnectionProvider} spi implementation, whose class name is supposed to be
- * provided as the following Hibernate property to kick off MongoDB dialect's JDBC flow:
+ * MongoDB dialect's customized JDBC {@link ConnectionProvider} SPI implementation, whose class name could be provided
+ * using configuration property {@value org.hibernate.cfg.JdbcSettings#CONNECTION_PROVIDER}.
  *
- * <ul>
- *   <li>hibernate.connection.provider_class
- * </ul>
- *
- * <p>The following Hibernate JDBC properties will be relied upon by Hibernate's {@link Configurable} spi mechanism:
+ * <p>The following Hibernate JDBC properties will be relied upon by Hibernate's {@link Configurable} SPI mechanism:
  *
  * <ul>
- *   <li>jakarta.persistence.jdbc.url
- *   <li>jakarta.persistence.jdbc.user
- *   <li>jakarta.persistence.jdbc.password
+ *   <li>{@linkplain org.hibernate.cfg.JdbcSettings#JAKARTA_JDBC_URL jakarta.persistence.jdbc.url}
+ *   <li>{@linkplain org.hibernate.cfg.JdbcSettings#JAKARTA_JDBC_USER jakarta.persistence.jdbc.user}
+ *   <li>{@linkplain org.hibernate.cfg.JdbcSettings#JAKARTA_JDBC_PASSWORD jakarta.persistence.jdbc.password}
  * </ul>
  *
- * <p><code>jakarta.persistence.jdbc.url</code> property is mandatory and it maps to MongoDB's {@link ConnectionString},
- * in which database name must be provided to align with JDBC URL's convention. The other two JDBC properties are
- * optional.
+ * <p>{@value org.hibernate.cfg.JdbcSettings#JAKARTA_JDBC_URL} property is mandatory and it maps to MongoDB's <a
+ * href="https://www.mongodb.com/docs/manual/reference/connection-string/">connection string</a>, in which database name
+ * must be provided to align with JDBC URL's convention. The other two JDBC properties are optional.
  *
  * @see ConnectionProvider
  * @see Configurable
+ * @see JdbcSettings#JAKARTA_JDBC_URL
+ * @see JdbcSettings#JAKARTA_JDBC_USER
+ * @see JdbcSettings#JAKARTA_JDBC_PASSWORD
  */
-public class MongoConnectionProvider implements ConnectionProvider, Configurable, Startable, Stoppable {
-
-    // non-null after configure(Map<String, Object>) method is invoked successfully
-    private @Nullable ConnectionString connectionString;
-    private @Nullable String database;
+public class MongoConnectionProvider implements ConnectionProvider, Configurable, Stoppable {
 
-    // non-null after start() method is invoked successfully
     private @Nullable MongoClient mongoClient;
 
-    private @Nullable String user;
-    private @Nullable String password;
-
     @Override
     public Connection getConnection() {
-        throw new NotYetImplementedException();
+        throw new NotYetImplementedException("to be implemented at https://jira.mongodb.org/browse/HIBERNATE-29");
     }
 
     @Override
     public void closeConnection(Connection connection) {
-        throw new NotYetImplementedException();
+        throw new NotYetImplementedException("to be implemented at https://jira.mongodb.org/browse/HIBERNATE-29");
     }
 
     @Override
     public boolean supportsAggressiveRelease() {
-        return false; // won't be used in container
+        return false;
     }
 
     @Override
     public boolean isUnwrappableAs(Class<?> unwrapType) {
-        return ConnectionProvider.class.equals(unwrapType)
-                || MongoConnectionProvider.class.isAssignableFrom(unwrapType);
+        return false;
     }
 
     @Override
     public <T> T unwrap(Class<T> unwrapType) {
-        if (isUnwrappableAs(unwrapType)) {
-            return unwrapType.cast(this);
-        } else {
-            throw new UnknownUnwrapTypeException(unwrapType);
-        }
+        throw new UnknownUnwrapTypeException(unwrapType);
     }
 
     @Override
-    public void configure(Map<String, Object> configurationValues) {
-        var jdbcUrl = ConfigurationHelper.getRequiredConfiguration(configurationValues, JAKARTA_JDBC_URL);
+    public void configure(Map<String, Object> configValues) {
+        var jdbcUrl = configValues.get(JAKARTA_JDBC_URL);
+        if (jdbcUrl == null) {
+            throw new HibernateException("property is required: " + JAKARTA_JDBC_URL);
+        }
+        if (!(jdbcUrl instanceof String)) {
+            throw new HibernateException(
+                    String.format("property ('%s') value ('%s') not of string type", JAKARTA_JDBC_URL, jdbcUrl));
+        }
+        ConnectionString connectionString;
         try {
-            this.connectionString = new ConnectionString(jdbcUrl);
+            connectionString = new ConnectionString((String) jdbcUrl);
         } catch (IllegalArgumentException iae) {
-            throw new ConfigurationException(JAKARTA_JDBC_URL, "invalid MongoDB connection string", iae);
+            throw new HibernateException("invalid MongoDB connection string: " + jdbcUrl, iae);
         }
-        var database = this.connectionString.getDatabase();
+        var database = connectionString.getDatabase();
         if (database == null) {
-            throw new ConfigurationException(JAKARTA_JDBC_URL, "database must be provided");
+            throw new HibernateException("database must be provided in connection string: " + jdbcUrl);
         }
-        this.database = database;
-        this.user = ConfigurationHelper.getOptionalConfiguration(configurationValues, JAKARTA_JDBC_USER);
-        this.password = ConfigurationHelper.getOptionalConfiguration(configurationValues, JAKARTA_JDBC_PASSWORD);
-    }
-
-    @Override
-    public void start() {
-        // connectionString and database are set as mandatory values in the above configure method
-        // if either is unset, exception would have been thrown and this method invocation would have be skipped
-        castNonNull(this.connectionString);
-        castNonNull(this.database);
 
         var clientSettingsBuilder = MongoClientSettings.builder().applyConnectionString(connectionString);
-        if (this.user != null) {
-            var password = this.password == null ? null : this.password.toCharArray();
-            var credential = MongoCredential.createCredential(this.user, this.database, password);
-            clientSettingsBuilder.credential(credential);
-        }
 
-        var codecRegistry = fromRegistries(MongoClientSettings.getDefaultCodecRegistry());
-        clientSettingsBuilder.codecRegistry(codecRegistry);
+        if (configValues.get(JAKARTA_JDBC_USER) != null || configValues.get(JAKARTA_JDBC_PASSWORD) != null) {
+            throw new NotYetImplementedException("to be implemented after auth could be tested in CI");
+        }
 
         var clientSettings = clientSettingsBuilder.build();
         this.mongoClient = MongoClients.create(clientSettings);

src/main/java/com/mongodb/hibernate/package-info.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2024-present MongoDB, Inc.
+ *
+ * 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.
+ */
+
 @NullMarked
 package com.mongodb.hibernate;
 

src/test/java/com/mongodb/hibernate/jdbc/SessionFactoryTests.java

@@ -19,8 +19,8 @@
 import static org.hibernate.cfg.JdbcSettings.JAKARTA_JDBC_URL;
 import static org.junit.jupiter.api.Assertions.*;
 
-import com.mongodb.hibernate.exception.ConfigurationException;
 import java.util.Map;
+import org.hibernate.HibernateException;
 import org.hibernate.SessionFactory;
 import org.hibernate.cfg.Configuration;
 import org.hibernate.service.spi.ServiceException;
@@ -38,14 +38,14 @@ void test_invalid_connection_String() {
         var exception = assertThrows(
                 ServiceException.class,
                 () -> buildSessionFactory(Map.of(JAKARTA_JDBC_URL, "jdbc:postgresql://localhost/test")));
-        assertInstanceOf(ConfigurationException.class, exception.getCause());
+        assertInstanceOf(HibernateException.class, exception.getCause());
     }
 
     @Test
     void test_when_database_absent() {
         var exception = assertThrows(
                 ServiceException.class, () -> buildSessionFactory(Map.of(JAKARTA_JDBC_URL, "mongodb://localhost")));
-        assertInstanceOf(ConfigurationException.class, exception.getCause());
+        assertInstanceOf(HibernateException.class, exception.getCause());
     }
 
     private void buildSessionFactory(Map<String, String> configurationValues) throws ServiceException {

src/test/resources/hibernate.properties

@@ -1,3 +1,3 @@
-jakarta.persistence.jdbc.url=mongodb://localhost/test
+jakarta.persistence.jdbc.url=mongodb://localhost/mongo-hibernate-test?directConnection=false
 hibernate.dialect=com.mongodb.hibernate.dialect.MongoDialect
 hibernate.connection.provider_class=com.mongodb.hibernate.jdbc.MongoConnectionProvider