Merge branch 'main' into HIBERNATE-35-batch-processing

# Conflicts:
#	src/main/java/com/mongodb/hibernate/jdbc/MongoConnectionProvider.java
#	src/main/java/com/mongodb/hibernate/jdbc/MongoPreparedStatement.java
#	src/test/java/com/mongodb/hibernate/jdbc/MongoConnectionTests.java
#	src/test/java/com/mongodb/hibernate/jdbc/MongoPreparedStatementTests.java
#	src/test/resources/hibernate.properties

Author: NathanQingyangXu

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

@@ -18,10 +18,12 @@ import com.diffplug.spotless.FormatterFunc
 import com.diffplug.spotless.FormatterStep
 import java.io.Serializable
 import net.ltgt.gradle.errorprone.errorprone
+import org.gradle.api.tasks.testing.logging.TestLogEvent
 
 version = "1.0.0-SNAPSHOT"
 
 plugins {
+    idea
     `java-library`
     alias(libs.plugins.spotless)
     alias(libs.plugins.errorprone)
@@ -32,10 +34,8 @@ repositories { mavenCentral() }
 
 java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }
 
-tasks.named<Test>("test") { useJUnitPlatform() }
-
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// Integration Tests
+// Integration Test
 
 sourceSets {
     create("integrationTest") {
@@ -44,29 +44,37 @@ sourceSets {
     }
 }
 
-val integrationTestImplementation by configurations.getting { extendsFrom(configurations.implementation.get()) }
-val integrationTestRuntimeOnly: Configuration by configurations.getting
+val integrationTestSourceSet: SourceSet = sourceSets["integrationTest"]
 
-configurations["integrationTestRuntimeOnly"].extendsFrom(configurations.runtimeOnly.get())
+val integrationTestImplementation: Configuration by
+    configurations.getting { extendsFrom(configurations.implementation.get()) }
+val integrationTestRuntimeOnly: Configuration by
+    configurations.getting { extendsFrom(configurations.runtimeOnly.get()) }
 
-val integrationTest =
+val integrationTestTask: Task =
     task<Test>("integrationTest") {
-        description = "Runs integration tests requiring external MongoDB deployment"
-        group = "verification"
+        group = LifecycleBasePlugin.VERIFICATION_GROUP
+        testClassesDirs = integrationTestSourceSet.output.classesDirs
+        classpath = integrationTestSourceSet.runtimeClasspath
+    }
 
-        testClassesDirs = sourceSets["integrationTest"].output.classesDirs
-        classpath = sourceSets["integrationTest"].runtimeClasspath
-        shouldRunAfter("test")
+tasks.check { dependsOn(integrationTestTask) }
 
-        useJUnitPlatform()
+tasks.withType<Test>().configureEach {
+    useJUnitPlatform()
+    testLogging { events(TestLogEvent.PASSED, TestLogEvent.SKIPPED, TestLogEvent.FAILED) }
+}
 
-        testLogging { events("passed") }
+// https://youtrack.jetbrains.com/issue/IDEA-234382/Gradle-integration-tests-are-not-marked-as-test-sources-resources
+idea {
+    module {
+        testSources.from(integrationTestSourceSet.allSource.srcDirs)
+        testResources.from(integrationTestSourceSet.resources.srcDirs)
     }
-
-tasks.check { dependsOn(integrationTest) }
+}
 
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// Static Analysis Tasks
+// Static Analysis
 
 spotless {
     java {
@@ -139,7 +147,7 @@ class MultilineFormatter : Serializable {
 }
 
 tasks.withType<JavaCompile>().configureEach {
-    options.compilerArgs.addAll(listOf("-Xlint:deprecation", "-Werror"))
+    options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror"))
     if (name == "compileJava") {
         options.errorprone {
             disableWarningsInGeneratedCode.set(true)
@@ -165,20 +173,25 @@ 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")
     integrationTestImplementation(libs.hibernate.testing) {
         exclude(group = "org.apache.logging.log4j", module = "log4j-core")
     }
+
     integrationTestRuntimeOnly(libs.junit.platform.launcher)
 
-    errorprone(libs.nullaway)
     api(libs.jspecify)
 
+    errorprone(libs.nullaway)
     errorprone(libs.google.errorprone.core)
 
     implementation(libs.hibernate.core)

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/BasicInsertionTests.java renamed to 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,19 +32,24 @@
 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;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
 @SessionFactory(exportSchema = false)
-@DomainModel(annotatedClasses = {BasicInsertionTests.Book.class, BasicInsertionTests.BookWithEmbeddedField.class})
-class BasicInsertionTests {
+@DomainModel(
+        annotatedClasses = {
+            BasicInsertionIntegrationTests.Book.class,
+            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);
     }
 
@@ -115,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);
         }
     }
@@ -132,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/SessionFactoryTests.java renamed to src/integrationTest/java/com/mongodb/hibernate/SessionFactoryIntegrationTests.java

@@ -16,20 +16,18 @@
 
 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;
 import org.hibernate.service.spi.ServiceException;
 import org.junit.jupiter.api.Test;
 
-class SessionFactoryTests {
+class SessionFactoryIntegrationTests {
 
     @Test
     void testSuccess() {
@@ -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/java/com/mongodb/hibernate/SessionTests.java renamed to src/integrationTest/java/com/mongodb/hibernate/SessionIntegrationTests.java

@@ -27,7 +27,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-class SessionTests {
+class SessionIntegrationTests {
 
     private static SessionFactory sessionFactory;
 

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