Make mongo-hibernate.jar a Java module

.evergreen/java-config.sh

@@ -3,7 +3,6 @@
 # Java configurations for evergreen
 
 export JDK17="/opt/java/jdk17"
-export JDK21="/opt/java/jdk21"
 
 if [ -d "$JDK17" ]; then
   export JAVA_HOME=$JDK17

.evergreen/run-integration-tests.sh

@@ -16,3 +16,7 @@ echo "MongoDB version: ${MONGODB_VERSION}; topology: ${TOPOLOGY}"
 ./gradlew -version
 
 ./gradlew -PjavaVersion=${JAVA_VERSION} --stacktrace --info --continue clean integrationTest
+
+echo "mongo-hibernate: running examples ..."
+./gradlew -PjavaVersion=${JAVA_VERSION} publishToMavenLocal \
+  && ./example/mvnw clean verify -f ./example/pom.xml -DjavaVersion="${JAVA_VERSION}" -DprojectVersion="$(./gradlew -q printProjectVersion)"

.gitattributes

@@ -6,7 +6,7 @@
 
 # These are Windows script files and should use crlf
 *.bat           text eol=crlf
+*.cmd           text eol=crlf
 
 # Binary files should be left untouched
 *.jar           binary
-

.gitignore

@@ -24,7 +24,7 @@
 /bin/
 
 # Intellij IDEA
-/.idea/
+.idea/
 /*.ipr
 /*.iws
 /*.iml
@@ -34,4 +34,5 @@
 # Gradle
 .gradle/
 .kotlin/
-build/
+build/
+target/

README.md

@@ -35,7 +35,7 @@ instead of SQL. This product works by:
 - [Manual](https://www.mongodb.com/docs/languages/java/mongodb-hibernate/current)
 - [API](https://javadoc.io/doc/org.mongodb/mongodb-hibernate/latest/index.html)
 
-[Standalone deployments](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-standalone) are not supported,
+MongoDB [standalone deployments](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-standalone) are not supported,
 because they [do not support transactions](https://www.mongodb.com/docs/manual/core/transactions-production-consideration/).
 If you use one, you may [convert it to a replica set](https://www.mongodb.com/docs/manual/tutorial/convert-standalone-to-replica-set/).
 
@@ -54,6 +54,23 @@ Use ["Extension for Hibernate ORM" at jira.mongodb.org](https://jira.mongodb.org
 
 Use ["Drivers & Frameworks"/"Frameworks (e.g. Django, Hibernate, EFCore)" at feedback.mongodb.com" at feedback.mongodb.com](https://feedback.mongodb.com/?category=7548141831345841376).
 
+### Examples
+
+[Maven](https://maven.apache.org/) is used as a build tool.
+
+The example applications are located in [`./example`](example).
+They require a MongoDB deployment accessible at `localhost:27017`.
+
+#### Build and Run from Source
+
+```console
+source ./.evergreen/java-config.sh \
+  && ./gradlew -PjavaVersion=${JAVA_VERSION} clean publishToMavenLocal \
+  && ./example/mvnw clean verify -f ./example/pom.xml \
+    -DjavaVersion="${JAVA_VERSION}" \
+    -DprojectVersion="$(./gradlew -q printProjectVersion)"
+```
+
 ## Contributor Documentation
 
 [Gradle](https://gradle.org/) is used as a build tool.
@@ -102,7 +119,7 @@ This project uses separate directories for unit and integration tests:
 - [`./src/test`](src/test)
 - [`./src/integrationTest`](src/integrationTest)
 
-Integration tests require a MongoDB deployment with test commands enabled,  which may be achieved with the
+Integration tests require a MongoDB deployment with test commands enabled, which may be achieved with the
 [`--setParameter enableTestCommands=1`](https://www.mongodb.com/docs/manual/reference/parameters/)
 command-line arguments.
 

build.gradle.kts

@@ -39,20 +39,28 @@ java {
 }
 
 tasks.withType<Javadoc> {
-    exclude("/com/mongodb/hibernate/internal/**")
-    exclude("com/mongodb/hibernate/dialect/**")
-    exclude("com/mongodb/hibernate/jdbc/**")
-
     val standardDocletOptions = options as StandardJavadocDocletOptions
     standardDocletOptions.apply {
+        addBooleanOption("Werror", false)
+        // TODO-HIBERNATE-129 addStringOption("-link-modularity-mismatch", "info")
+        addBooleanOption("serialwarn", true)
+        addBooleanOption("Xdoclint:all", true)
+        addBooleanOption(
+            "Xdoclint/package:-" +
+                "com.mongodb.hibernate.internal.*" +
+                ",com.mongodb.hibernate.dialect.*" +
+                ",com.mongodb.hibernate.jdbc.*",
+            true)
+        addStringOption("-show-module-contents", "api")
+        addStringOption("-show-packages", "exported")
+        addStringOption("-show-types", "protected")
         author(true)
         version(true)
-        encoding = "UTF-8"
+        encoding("UTF-8")
         charSet("UTF-8")
         docEncoding("UTF-8")
         addBooleanOption("html5", true)
         addBooleanOption("-allow-script-in-comments", true)
-        // TODO-HIBERNATE-129 addStringOption("-link-modularity-mismatch", "info")
         links =
             listOf(
                 "https://docs.oracle.com/en/java/javase/17/docs/api/",
@@ -141,11 +149,15 @@ spotless {
 tasks.check { dependsOn(tasks.spotlessApply) }
 
 tasks.withType<JavaCompile>().configureEach {
-    options.compilerArgs.addAll(listOf("-Xlint:all", "-Werror"))
+    options.compilerArgs.addAll(
+        listOf("-Xlint:all", "-Xlint:-requires-automatic", "-Xlint:-requires-transitive-automatic", "-Werror"))
     when (this) {
         tasks.compileJava.get() ->
             options.errorprone {
                 disableWarningsInGeneratedCode = true
+                // Error Prone does not understand the `@hidden` standard tag
+                disable("InvalidBlockTag")
+                disable("AssignmentExpression")
                 option("NullAway:AnnotatedPackages", "com.mongodb.hibernate")
                 error("NullAway")
             }
@@ -159,6 +171,8 @@ tasks.withType<JavaCompile>().configureEach {
 buildConfig {
     useJavaOutput()
     packageName("com.mongodb.hibernate.internal")
+    documentation.set(
+        "Generated by the <a href=\"https://github.com/gmazzo/gradle-buildconfig-plugin\">BuildConfig</a> plugin.\n\n@hidden")
     buildConfigField("NAME", provider { project.name })
     buildConfigField("VERSION", provider { "${project.version}" })
 }
@@ -205,6 +219,9 @@ publishing {
     repositories {
         // publish to local build dir for testing
         // `./gradlew publishMavenPublicationToLocalBuildRepository`
+        //
+        // publish to the local Maven cache
+        // `./gradlew publishToMavenLocal`
         maven {
             url = uri(localBuildRepo.get())
             name = "LocalBuild"
@@ -222,8 +239,8 @@ publishing {
                 url = "https://www.mongodb.com/"
                 licenses {
                     license {
-                        name = "The Apache License, Version 2.0"
-                        url = "http://www.apache.org/licenses/LICENSE-2.0.txt"
+                        name = "Apache License, Version 2.0"
+                        url = "https://www.apache.org/licenses/LICENSE-2.0"
                     }
                 }
                 developers {
@@ -234,8 +251,8 @@ publishing {
                 }
                 scm {
                     url.set("https://github.com/mongodb/mongo-hibernate")
-                    connection.set("scm:https://github.com/mongodb/mongo-hibernate.git")
-                    developerConnection.set("scm:https://github.com/mongodb/mongo-hibernate.git")
+                    connection.set("scm:git:https://github.com/mongodb/mongo-hibernate.git")
+                    developerConnection.set("scm:git:https://github.com/mongodb/mongo-hibernate.git")
                 }
             }
         }
@@ -337,3 +354,6 @@ tasks.register("publishArchives") {
         dependsOn(tasks.named("publishToSonatype"))
     }
 }
+
+// `./gradlew -q printProjectVersion`
+tasks.register("printProjectVersion") { doLast { logger.quiet(project.version.toString()) } }

example/.mvn/maven.config

@@ -0,0 +1,13 @@
+# 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.

example/.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/4.0.0-rc-5/apache-maven-4.0.0-rc-5-bin.zip