diff --git a/documentation/documentation.gradle b/documentation/documentation.gradle index b31ee1505a..11b8d6fcd8 100644 --- a/documentation/documentation.gradle +++ b/documentation/documentation.gradle @@ -248,7 +248,10 @@ asciidoctorj { experimental: true, 'source-highlighter': 'rouge', majorMinorVersion: rootProject.ormVersion.family, - fullVersion: rootProject.ormVersion.fullName + fullVersion: rootProject.ormVersion.fullName, + javaCompatibleVersions: jdks.versions.compatible.get(), + jakartaJpaVersion: rootProject.jakartaJpaVersion, + jdbcVersion: jdks.versions.jdbc.get() options logDocuments: true } @@ -581,7 +584,7 @@ def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', Asciidoctor inputs.property "hibernate-version", project.ormVersion inputs.file( generateSettingsDocTask.get().outputFile ) - dependsOn generateSettingsDocTask + dependsOn generateSettingsDocTask, generateDialectTableReport sourceDir = file( 'src/main/asciidoc/userguide' ) sources { @@ -592,7 +595,8 @@ def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', Asciidoctor attributes linkcss: true, stylesheet: "css/hibernate.css", docinfo: 'private', - jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/" + jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/", + 'generated-report-dir': layout.buildDirectory.dir( 'orm/generated' ) resources { from( 'src/main/asciidoc/userguide/' ) { diff --git a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc index 63dae70c76..628dcc8bb9 100644 --- a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc +++ b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc @@ -14,6 +14,7 @@ include::Preface.adoc[] :numbered: +include::chapters/compatibility/Compatibility.adoc[] include::chapters/architecture/Architecture.adoc[] include::chapters/domain/DomainModel.adoc[] include::chapters/bootstrap/Bootstrap.adoc[] diff --git a/documentation/src/main/asciidoc/userguide/chapters/compatibility/Compatibility.adoc b/documentation/src/main/asciidoc/userguide/chapters/compatibility/Compatibility.adoc new file mode 100644 index 0000000000..72ee8fcd27 --- /dev/null +++ b/documentation/src/main/asciidoc/userguide/chapters/compatibility/Compatibility.adoc @@ -0,0 +1,76 @@ +[[compatibility]] +== Compatibility + +[[compatibility-dependencies]] +=== [[system-requirements]] Dependencies + +Hibernate {fullVersion} requires the following dependencies (among others): + +.Compatible versions of dependencies +[cols="h,^1", stripes=none] +|=============== +| h|Version +|Java Runtime +|{javaCompatibleVersions} +|https://jakarta.ee/specifications/persistence/[Jakarta Persistence] +|{jakartaJpaVersion} +|JDBC (bundled with the Java Runtime) +|{jdbcVersion} +|=============== + +[TIP] +==== +Find more information for all versions of Hibernate on our +https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix]. + +The https://hibernate.org/community/compatibility-policy/[compatibility policy] may also be of interest. +==== + +If you get Hibernate from Maven Central, it is recommended to import Hibernate Platform +as part of your dependency management to keep all its artifact versions aligned. + +Gradle:: +[source, groovy, subs="+attributes"] +---- +dependencies { + implementation platform "org.hibernate.orm:hibernate-platform:{fullVersion}" + + // use the versions from the platform + implementation "org.hibernate.orm:hibernate-core" + implementation "jakarta.transaction:jakarta.transaction-api" +} +---- +Maven:: +[source, XML, subs="+attributes"] +---- +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.hibernate.search</groupId> + <artifactId>hibernate-platform</artifactId> + <version>{fullVersion}</version> + <type>pom</type> + <scope>import</scope> + </dependency> + </dependencies> +</dependencyManagement> +<!-- use the versions from the platform --> +<dependencies> + <dependency> + <groupId>org.hibernate.orm</groupId> + <artifactId>hibernate-core</artifactId> + </dependency> + <dependency> + <groupId>jakarta.transaction</groupId> + <artifactId>jakarta.transaction-api</artifactId> + </dependency> +</dependencies> +---- + +[[compatibility-database]] +=== Database + +Hibernate {fullVersion} is compatible with the following database versions, +provided you use the corresponding <<database-dialect,dialects>>: + +include::{generated-report-dir}/dialect/dialect-table.adoc[] diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/post/DialectReportTask.java b/local-build-plugins/src/main/java/org/hibernate/orm/post/DialectReportTask.java index 16de169f60..ba751f5a68 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/post/DialectReportTask.java +++ b/local-build-plugins/src/main/java/org/hibernate/orm/post/DialectReportTask.java @@ -22,6 +22,8 @@ import org.gradle.api.Project; import org.gradle.api.file.RegularFile; import org.gradle.api.provider.Property; import org.gradle.api.provider.Provider; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.OutputFile; import org.gradle.api.tasks.SourceSet; import org.gradle.api.tasks.SourceSetContainer; import org.gradle.api.tasks.TaskAction; @@ -31,8 +33,6 @@ import org.hibernate.orm.env.HibernateVersion; import org.jboss.jandex.ClassInfo; import org.jboss.jandex.Index; -import static org.hibernate.orm.post.ReportGenerationPlugin.TASK_GROUP_NAME; - /** * Generates a report on Dialect information * @@ -40,11 +40,23 @@ import static org.hibernate.orm.post.ReportGenerationPlugin.TASK_GROUP_NAME; */ public abstract class DialectReportTask extends AbstractJandexAwareTask { private final Property<RegularFile> reportFile; + private final Property<Boolean> generateHeading; public DialectReportTask() { setDescription( "Generates a report of the supported Dialects" ); reportFile = getProject().getObjects().fileProperty(); reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect.adoc" ) ); + generateHeading = getProject().getObjects().property( Boolean.class ).convention( true ); + } + + @OutputFile + public Property<RegularFile> getReportFile() { + return reportFile; + } + + @Input + public Property<Boolean> getGenerateHeading() { + return generateHeading; } @Override @@ -116,11 +128,14 @@ public abstract class DialectReportTask extends AbstractJandexAwareTask { private void writeDialectReportHeader(OutputStreamWriter fileWriter) { try { - fileWriter.write( "= Supported Dialects\n\n" ); - fileWriter.write( "Supported Dialects along with the minimum supported version of the underlying database.\n\n\n" ); + if ( this.generateHeading.get() ) { + fileWriter.write( "= Supported Dialects\n\n" ); + fileWriter.write( + "Supported Dialects along with the minimum supported version of the underlying database.\n\n\n" ); - HibernateVersion ormVersion = (HibernateVersion) getProject().getRootProject().getExtensions().getByName( "ormVersion" ); - fileWriter.write( "NOTE: Hibernate version " + ormVersion.getFamily() + "\n\n" ); + HibernateVersion ormVersion = (HibernateVersion) getProject().getRootProject().getExtensions().getByName( "ormVersion" ); + fileWriter.write( "NOTE: Hibernate version " + ormVersion.getFamily() + "\n\n" ); + } fileWriter.write( "[cols=\"a,a\", options=\"header\"]\n" ); fileWriter.write( "|===\n" ); diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/post/ReportGenerationPlugin.java b/local-build-plugins/src/main/java/org/hibernate/orm/post/ReportGenerationPlugin.java index aa987dd82c..66bd42a20b 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/post/ReportGenerationPlugin.java +++ b/local-build-plugins/src/main/java/org/hibernate/orm/post/ReportGenerationPlugin.java @@ -63,6 +63,16 @@ public class ReportGenerationPlugin implements Plugin<Project> { (task) -> task.dependsOn( indexerTask ) ); + final TaskProvider<DialectReportTask> dialectTableTask = project.getTasks().register( + "generateDialectTableReport", + DialectReportTask.class, + (task) -> { + task.dependsOn( indexerTask ); + task.setProperty( "generateHeading", false ); + task.setProperty( "reportFile", project.getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect-table.adoc" ) ); + } + ); + final Task groupingTask = project.getTasks().maybeCreate( "generateReports" ); groupingTask.setGroup( TASK_GROUP_NAME ); groupingTask.dependsOn( indexerTask ); @@ -71,5 +81,6 @@ public class ReportGenerationPlugin implements Plugin<Project> { groupingTask.dependsOn( internalsTask ); groupingTask.dependsOn( loggingTask ); groupingTask.dependsOn( dialectTask ); + groupingTask.dependsOn( dialectTableTask ); } } diff --git a/settings.gradle b/settings.gradle index 5f4f07642e..61c0488a11 100644 --- a/settings.gradle +++ b/settings.gradle @@ -53,6 +53,8 @@ dependencyResolutionManagement { versionCatalogs { jdks { version "baseline", "11" + version "compatible", "11, 17 or 21" + version "jdbc", "4.2" // Bundled with JDK 11 // Gradle does bytecode transformation on tests. // You can't use bytecode higher than what Gradle supports, even with toolchains.