Design, implement and document how an application can configure the product (#31)

Author: stIncMale

README.md

@@ -1,23 +1,26 @@
-# A MongoDB Dialect for the Hibernate ORM
+# MongoDB extension of Hibernate ORM
 
-This project aims to provide a library to seamlessly integrate MongoDB with Hibernate ORM. Hibernate _ORM_ is a powerful **O**bject-**r**elational **m**apping tool. Due to the SQL and JDBC standards, Hibernate ORM could centralize each SQL vendor's idiosyncrasies in the so-called _Hibernate Dialect_. This project will include a document database member in the Hibernate's Dialect family.
+This product enables applications to use databases managed by the [MongoDB](https://www.mongodb.com/) DBMS
+via [Hibernate ORM](https://hibernate.org/orm/).
 
 ## Overview
 
-MongoDB speaks _MQL_ (**M**ongoDB **Q**uery **L**anguage in JSON format) instead of SQL. This project creates a MongoDB Hibernate Dialect by:
+MongoDB speaks MQL (**M**ongoDB **Q**uery **L**anguage) instead of SQL. This product works by:
 
-- Creating a JDBC adapter using [MongoDB Java Driver](https://www.mongodb.com/docs/drivers/java-drivers/)
-- Translating Hibernate's internal SQL AST into MQL
+- Creating a JDBC adapter using [MongoDB Java Driver](https://www.mongodb.com/docs/drivers/java-drivers/),
+  which has to be plugged into Hibernate ORM via a custom [`ConnectionProvider`](https://docs.jboss.org/hibernate/orm/6.6/javadocs/org/hibernate/engine/jdbc/connections/spi/ConnectionProvider.html).
+- Translating Hibernate's internal SQL AST into MQL by means of a custom [`Dialect`](https://docs.jboss.org/hibernate/orm/6.6/javadocs/org/hibernate/dialect/Dialect.html),
+  which has to be plugged into Hibernate ORM.
 
-<img src="mongodb_dialect.png" alt="MongoDB Dialect" />
+<img src="mongodb_dialect.png" alt="MongoDB extension" />
 
 ## Development
 
 Java 17 is the JDK version for development.
 
 Initially Hibernate ORM v6.6 is the dependency version.
 
-MongoDB v6 is the minimal version this dialect supports.
+MongoDB v6.0 is the minimal version this product supports.
 
 > [Standalone instance](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-standalone) is not supported. It is recommended to [convert it to a replica set](https://www.mongodb.com/docs/manual/tutorial/convert-standalone-to-replica-set/).
 

build.gradle.kts

@@ -173,11 +173,13 @@ buildConfig {
 
 dependencies {
     testImplementation(libs.junit.jupiter)
+    testImplementation(libs.assertj)
     testImplementation(libs.logback.classic)
     testImplementation(libs.mockito.junit.jupiter)
     testRuntimeOnly(libs.junit.platform.launcher)
 
     integrationTestImplementation(libs.junit.jupiter)
+    integrationTestImplementation(libs.assertj)
     integrationTestImplementation(libs.logback.classic)
 
     @Suppress("UnstableApiUsage")

gradle/libs.versions.toml

@@ -3,6 +3,7 @@
 
 [versions]
 junit-jupiter = "5.11.4"
+assertj = "3.27.3"
 spotless = "7.0.2"
 palantir = "2.50.0"
 ktfmt = "0.54"
@@ -20,6 +21,7 @@ buildconfig = "5.5.1"
 [libraries]
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }
 junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher" }
+assertj = { module = "org.assertj:assertj-core", version.ref = "assertj" }
 nullaway = { module = "com.uber.nullaway:nullaway", version.ref = "nullaway" }
 jspecify = { module = "org.jspecify:jspecify", version.ref = "jspecify" }
 google-errorprone-core = { module = "com.google.errorprone:error_prone_core", version.ref = "google-errorprone-core" }

src/integrationTest/java/com/mongodb/hibernate/BasicInsertionIntegrationTests.java

@@ -17,12 +17,12 @@
 package com.mongodb.hibernate;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.hibernate.cfg.JdbcSettings.JAKARTA_JDBC_URL;
+import static org.assertj.core.api.InstanceOfAssertFactories.LIST;
 
-import com.mongodb.ConnectionString;
-import com.mongodb.MongoClientSettings;
 import com.mongodb.client.MongoClients;
 import com.mongodb.client.MongoCollection;
+import com.mongodb.hibernate.internal.cfg.MongoConfiguration;
+import com.mongodb.hibernate.internal.cfg.MongoConfigurationBuilder;
 import jakarta.persistence.Column;
 import jakarta.persistence.Embeddable;
 import jakarta.persistence.Entity;
@@ -32,7 +32,6 @@
 import java.util.List;
 import java.util.function.Consumer;
 import org.bson.BsonDocument;
-import org.hibernate.cfg.Configuration;
 import org.hibernate.testing.orm.junit.DomainModel;
 import org.hibernate.testing.orm.junit.SessionFactory;
 import org.hibernate.testing.orm.junit.SessionFactoryScope;
@@ -46,9 +45,11 @@
             BasicInsertionIntegrationTests.BookWithEmbeddedField.class
         })
 class BasicInsertionIntegrationTests {
+    private static MongoConfiguration config;
 
     @BeforeEach
-    void setUp() {
+    void setUp(SessionFactoryScope scope) {
+        config = new MongoConfigurationBuilder(scope.getSessionFactory().getProperties()).build();
         onMongoCollection(MongoCollection::drop);
     }
 
@@ -119,12 +120,8 @@ void testEntityWithEmbeddedFieldInsertion(SessionFactoryScope scope) {
     }
 
     private void onMongoCollection(Consumer<MongoCollection<BsonDocument>> collectionConsumer) {
-        var connectionString = new ConnectionString(new Configuration().getProperty(JAKARTA_JDBC_URL));
-        try (var mongoClient = MongoClients.create(MongoClientSettings.builder()
-                .applyConnectionString(connectionString)
-                .build())) {
-            var collection =
-                    mongoClient.getDatabase(connectionString.getDatabase()).getCollection("books", BsonDocument.class);
+        try (var mongoClient = MongoClients.create(config.mongoClientSettings())) {
+            var collection = mongoClient.getDatabase(config.databaseName()).getCollection("books", BsonDocument.class);
             collectionConsumer.accept(collection);
         }
     }
@@ -136,7 +133,7 @@ private List<BsonDocument> getCollectionDocuments() {
     }
 
     private void assertCollectionContainsOnly(BsonDocument expectedDoc) {
-        assertThat(getCollectionDocuments()).asList().singleElement().isEqualTo(expectedDoc);
+        assertThat(getCollectionDocuments()).asInstanceOf(LIST).singleElement().isEqualTo(expectedDoc);
     }
 
     @Entity(name = "Book")

src/integrationTest/java/com/mongodb/hibernate/JakartaPersistenceBootstrappingIntegrationTests.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2025-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.
+ */
+
+package com.mongodb.hibernate;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.hibernate.internal.cfg.MongoConfiguration;
+import com.mongodb.hibernate.internal.cfg.MongoConfigurationBuilder;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EntityManagerFactory;
+import jakarta.persistence.Id;
+import jakarta.persistence.Persistence;
+import jakarta.persistence.Table;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class JakartaPersistenceBootstrappingIntegrationTests {
+    private static EntityManagerFactory entityManagerFactory;
+    private static MongoConfiguration config;
+    private static MongoClient mongoClient;
+
+    @BeforeAll
+    static void beforeAll() {
+        entityManagerFactory = Persistence.createEntityManagerFactory("test-persistence-unit");
+        config = new MongoConfigurationBuilder(entityManagerFactory.getProperties()).build();
+        mongoClient = MongoClients.create(config.mongoClientSettings());
+    }
+
+    @BeforeAll
+    static void beforeEach() {
+        mongoClient.getDatabase(config.databaseName()).drop();
+    }
+
+    @AfterAll
+    @SuppressWarnings("try")
+    static void afterAll() {
+        try (var closed1 = entityManagerFactory;
+                var closed2 = mongoClient) {}
+    }
+
+    @Test
+    void smoke() {
+        try (var entityManager = entityManagerFactory.createEntityManager()) {
+            var transaction = entityManager.getTransaction();
+            try {
+                transaction.begin();
+                var item = new Item();
+                item.id = 1;
+                entityManager.persist(item);
+            } finally {
+                transaction.commit();
+            }
+            assertEquals(
+                    1,
+                    mongoClient
+                            .getDatabase(config.databaseName())
+                            .getCollection("items")
+                            .countDocuments());
+        }
+    }
+
+    @Entity(name = "Item")
+    @Table(name = "items")
+    static class Item {
+        @Id
+        @Column(name = "_id")
+        int id;
+    }
+}

src/integrationTest/java/com/mongodb/hibernate/SessionFactoryIntegrationTests.java

@@ -16,13 +16,11 @@
 
 package com.mongodb.hibernate;
 
-import static org.hibernate.cfg.JdbcSettings.JAKARTA_JDBC_URL;
+import static org.hibernate.cfg.AvailableSettings.JAKARTA_JDBC_URL;
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
-import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.util.Map;
-import org.hibernate.HibernateException;
 import org.hibernate.SessionFactory;
 import org.hibernate.boot.MetadataSources;
 import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
@@ -38,10 +36,9 @@ void testSuccess() {
 
     @Test
     void testInvalidConnectionString() {
-        var exception = assertThrows(ServiceException.class, () -> buildSessionFactory(
+        assertThrows(ServiceException.class, () -> buildSessionFactory(
                         Map.of(JAKARTA_JDBC_URL, "jdbc:postgresql://localhost/test"))
                 .close());
-        assertInstanceOf(HibernateException.class, exception.getCause());
     }
 
     @Test

src/integrationTest/resources/META-INF/persistence.xml

@@ -0,0 +1,11 @@
+<persistence
+        xmlns="http://xmlns.jcp.org/xml/ns/persistence"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
+        version="2.1">
+    <persistence-unit name="test-persistence-unit">
+        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
+        <class>com.mongodb.hibernate.JakartaPersistenceBootstrappingIntegrationTests$Item</class>
+        <properties><!-- rely on `hibernate.properties` --></properties>
+    </persistence-unit>
+</persistence>

src/integrationTest/resources/hibernate.properties

@@ -1,3 +1,3 @@
-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
+jakarta.persistence.jdbc.url=mongodb://localhost/mongo-hibernate-test?directConnection=false

src/main/java/com/mongodb/hibernate/cfg/MongoConfigurator.java

@@ -0,0 +1,99 @@
+/*
+ * 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.
+ */
+
+package com.mongodb.hibernate.cfg;
+
+import com.mongodb.ConnectionString;
+import com.mongodb.MongoClientSettings;
+import com.mongodb.hibernate.internal.Sealed;
+import com.mongodb.hibernate.service.spi.MongoConfigurationContributor;
+import java.util.Map;
+import java.util.function.Consumer;
+import org.hibernate.cfg.AvailableSettings;
+import org.hibernate.service.spi.Configurable;
+
+/**
+ * The configurator of the MongoDB extension of Hibernate ORM.
+ *
+ * <table>
+ *     <caption>Supported configuration properties</caption>
+ *     <thead>
+ *         <tr>
+ *             <th>Method</th>
+ *             <th>Has default</th>
+ *             <th>Related {@linkplain Configurable#configure(Map) configuration property} name</th>
+ *             <th>Supported value types of the configuration property</th>
+ *             <th>Value, unless overridden via {@link MongoConfigurator}</th>
+ *         </tr>
+ *     </thead>
+ *     <tbody>
+ *         <tr>
+ *             <td>{@link #applyToMongoClientSettings(Consumer)}</td>
+ *             <td>✓</td>
+ *             <td>{@value AvailableSettings#JAKARTA_JDBC_URL}</td>
+ *             <td>
+ *                 <ul>
+ *                     <li>{@link String}</li>
+ *                     <li>{@link ConnectionString}</li>
+ *                 </ul>
+ *             </td>
+ *             <td>Is {@linkplain MongoClientSettings.Builder#applyConnectionString(ConnectionString) based} on
+ *             the {@link ConnectionString} {@linkplain ConnectionString#ConnectionString(String) constructed} from
+ *             {@value AvailableSettings#JAKARTA_JDBC_URL}, if the latter is configured; otherwise a {@link MongoClientSettings}
+ *             instance with its defaults.</td>
+ *         </tr>
+ *         <tr>
+ *             <td>{@link #databaseName(String)}</td>
+ *             <td>✗</td>
+ *             <td>{@value AvailableSettings#JAKARTA_JDBC_URL}</td>
+ *             <td>
+ *                 <ul>
+ *                     <li>{@link String}</li>
+ *                     <li>{@link ConnectionString}</li>
+ *                 </ul>
+ *             </td>
+ *             <td>The MongoDB database name from {@value AvailableSettings#JAKARTA_JDBC_URL},
+ *             if {@linkplain ConnectionString#getDatabase() configured};
+ *             otherwise a value must be configured via {@link MongoConfigurator#databaseName(String)}.</td>
+ *         </tr>
+ *     </tbody>
+ * </table>
+ *
+ * @see MongoConfigurationContributor
+ */
+@Sealed
+public interface MongoConfigurator {
+    /**
+     * Configures {@link MongoClientSettings}.
+     *
+     * <p>Note that if you {@linkplain MongoClientSettings.Builder#applyConnectionString(ConnectionString) apply} a
+     * {@link ConnectionString} with the {@linkplain ConnectionString#getDatabase() database name} configured, you still
+     * must configure the database name via {@link MongoConfigurator#databaseName(String)}, as there is no way for that
+     * to happen automatically.
+     *
+     * @param configurator The {@link Consumer} of the {@link MongoClientSettings.Builder}.
+     * @return {@code this}.
+     */
+    MongoConfigurator applyToMongoClientSettings(Consumer<MongoClientSettings.Builder> configurator);
+
+    /**
+     * Sets the name of a MongoDB database to use.
+     *
+     * @param databaseName The name of a MongoDB database to use.
+     * @return {@code this}.
+     */
+    MongoConfigurator databaseName(String databaseName);
+}

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

@@ -0,0 +1,21 @@
+/*
+ * 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.
+ */
+
+/** Program elements related to configuring the MongoDB extension of Hibernate ORM. */
+@NullMarked
+package com.mongodb.hibernate.cfg;
+
+import org.jspecify.annotations.NullMarked;