diff --git a/documentation/src/main/asciidoc/integrationguide/Hibernate_Integration_Guide.adoc b/documentation/src/main/asciidoc/integrationguide/Hibernate_Integration_Guide.adoc index 7450ba37ad..1336a737f9 100644 --- a/documentation/src/main/asciidoc/integrationguide/Hibernate_Integration_Guide.adoc +++ b/documentation/src/main/asciidoc/integrationguide/Hibernate_Integration_Guide.adoc @@ -1,11 +1,12 @@ -= Hibernate ORM {majorMinorVersion} Integration Guide -Steve Ebersole, Vlad Mihalcea += Hibernate ORM Integration Guide :toc: :toclevels: 3 -include::Preface.adoc[] +include::preface.adoc[] :numbered: include::chapters/services/Services.adoc[] +include::credits.adoc[] + diff --git a/documentation/src/main/asciidoc/integrationguide/Preface.adoc b/documentation/src/main/asciidoc/integrationguide/Preface.adoc deleted file mode 100644 index d348dc231a..0000000000 --- a/documentation/src/main/asciidoc/integrationguide/Preface.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[[preface]] -== Preface - -Hibernate is an https://en.wikipedia.org/wiki/Object-relational_mapping[Object/Relational Mapping] solution for Java environments. - -Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to SQL data types), but also provides data query and retrieval facilities. -It can significantly reduce development time otherwise spent with manual data handling in SQL and JDBC. -Hibernate’s design goal is to relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for manual, hand-crafted data processing using SQL and JDBC. -However, unlike many other persistence solutions, Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology and knowledge is as valid as always. - -=== Audience - -This guide is for software developers and architects who will be integrating Hibernate with Java EE application servers, Spring framework, caching solutions (e.g. Infinispan, Ehcache, Hazelcast). diff --git a/documentation/src/main/asciidoc/integrationguide/credits.adoc b/documentation/src/main/asciidoc/integrationguide/credits.adoc new file mode 100644 index 0000000000..60f1fd6b8f --- /dev/null +++ b/documentation/src/main/asciidoc/integrationguide/credits.adoc @@ -0,0 +1,10 @@ +[[credits]] +== Credits + +The full list of contributors to Hibernate ORM can be found on the +https://github.com/hibernate/hibernate-orm/graphs/contributors[GitHub repository]. + +The following contributors were involved in this documentation: + +* Steve Ebersole +* Vlad Mihalcea \ No newline at end of file diff --git a/documentation/src/main/asciidoc/integrationguide/preface.adoc b/documentation/src/main/asciidoc/integrationguide/preface.adoc new file mode 100644 index 0000000000..924423496e --- /dev/null +++ b/documentation/src/main/asciidoc/integrationguide/preface.adoc @@ -0,0 +1,8 @@ +[[preface]] +== Preface + +Hibernate provides many integration points that allow integration new capabilities or supplying custom behavior for standard capabilities. This guide covers these integration points and is intended for software developers and architects who will be + +- integrating Hibernate with Java EE application servers, Spring framework, caching solutions (e.g. Infinispan, Ehcache, Hazelcast). +- supplying custom integrations +- want to override standard capabilities \ No newline at end of file diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index 03c8990911..3ab9f3c331 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -119,7 +119,7 @@ This is completely by design and is not in any way a bug. More than one filter may be enabled in a given session. :envers: https://hibernate.org/orm/envers/ -:envers-doc: {userGuideBase}#envers +:envers-doc: {doc-user-guide-url}#envers We've mentioned that a filter can be used to implement versioning, and to provide _historical_ views of the data. Being such a general-purpose construct, filters provide a lot of flexibility here. @@ -592,7 +592,7 @@ Point event = .getSingleResult(); ---- -:matrix: {userGuideBase}#spatial-configuration-dialect-features +:matrix: {doc-user-guide-url}#spatial-configuration-dialect-features Here, `within()` is one of the functions for testing spatial relations defined by the OpenGIS specification. Other such functions include `touches()`, `intersects()`, `distance()`, `boundary()`, etc. @@ -806,7 +806,7 @@ Check constraints and foreign key constraints can help ensure that a row never c [[bytecode-enhancer]] === Using the bytecode enhancer -:enhancer: {userGuideBase}#BytecodeEnhancement +:enhancer: {doc-user-guide-url}#BytecodeEnhancement Hibernate's {enhancer}[bytecode enhancer] enables the following features: diff --git a/documentation/src/main/asciidoc/introduction/Configuration.adoc b/documentation/src/main/asciidoc/introduction/Configuration.adoc index a8c40d5fbf..bb320043d8 100644 --- a/documentation/src/main/asciidoc/introduction/Configuration.adoc +++ b/documentation/src/main/asciidoc/introduction/Configuration.adoc @@ -77,7 +77,7 @@ Where `{version}` is the latest version of the JDBC driver for your databse. === Optional dependencies :slf4j: http://www.slf4j.org/ -:enhancer: {userGuideBase}#tooling-gradle +:enhancer: {doc-user-guide-url}#tooling-gradle :agroal: https://agroal.github.io :jackson: https://github.com/FasterXML/jackson :yasson: https://projects.eclipse.org/projects/ee4j.yasson @@ -231,7 +231,7 @@ SessionFactory sessionFactory = The `Configuration` class has survived almost unchanged since the very earliest (pre-1.0) versions of Hibernate, and so it doesn't look particularly modern. On the other hand, it's very easy to use, and exposes some options that `persistence.xml` doesn't support. -:native-bootstrap: {userGuideBase}#bootstrap-native +:native-bootstrap: {doc-user-guide-url}#bootstrap-native :boot: {versionDocBase}/javadocs/org/hibernate/boot/package-summary.html .Advanced configuration options diff --git a/documentation/src/main/asciidoc/introduction/Entities.adoc b/documentation/src/main/asciidoc/introduction/Entities.adoc index dc9b4d8140..32e67474d6 100644 --- a/documentation/src/main/asciidoc/introduction/Entities.adoc +++ b/documentation/src/main/asciidoc/introduction/Entities.adoc @@ -75,7 +75,7 @@ We won't have much more to say about XML-based mappings in this Introduction, si ."Dynamic" models **** -:maps: {userGuideBase}#dynamic-model +:maps: {doc-user-guide-url}#dynamic-model :envers: https://hibernate.org/orm/envers/ We love representing entities as classes because the classes give us a _type-safe_ model of our data. But Hibernate also has the ability to represent entities as detyped instances of `java.util.Map`. diff --git a/documentation/src/main/asciidoc/introduction/Generator.adoc b/documentation/src/main/asciidoc/introduction/Generator.adoc index e92b31d357..3ae8319812 100644 --- a/documentation/src/main/asciidoc/introduction/Generator.adoc +++ b/documentation/src/main/asciidoc/introduction/Generator.adoc @@ -10,7 +10,7 @@ We've actually already seen its handiwork in the code examples < - org.hibernate.org + org.hibernate.orm hibernate-core 6.3.0.Final ---- [[modules]] -=== Modules belonging to Hibernate ORM +=== Hibernate ORM modules -Hibernate ORM is an umbrella project containing the following modules: +As mentioned earlier, Hibernate ORM is broken into a number of modules with the intent of isolating +transitive dependencies based on the features being used or not. [cols="40m,~"] .API-oriented modules |=== |hibernate-core| The core object/relational mapping engine |hibernate-envers| Entity versioning and auditing -|hibernate-spatial| Support for spatial/GIS data types -|hibernate-jpamodelgen| An annotation processor that generates a JPA-compliant metamodel +|hibernate-spatial| Support for spatial/GIS data types using https://github.com/GeoLatte/geolatte-geom[GeoLatte] +|hibernate-jpamodelgen| An annotation processor that generates a JPA-compliant metamodel, plus optional Hibernate extras |=== [cols="40m,~"] @@ -90,20 +54,57 @@ Hibernate ORM is an umbrella project containing the following modules: |hibernate-vibur| Support for https://www.vibur.org/[Vibur DBCP] connection pooling |hibernate-proxool| Support for https://proxool.sourceforge.net/[Proxool] connection pooling |hibernate-jcache| Integration with https://jcp.org/en/jsr/detail?id=107$$[JCache], allowing any compliant implementation as a second-level cache provider -|hibernate-community-dialects| Additional community-supported SQL dialects |hibernate-graalvm| Experimental extension to make it easier to compile applications as a https://www.graalvm.org/[GraalVM] native image |hibernate-micrometer| Integration with https://micrometer.io[Micrometer] metrics +|hibernate-community-dialects| Additional community-supported SQL dialects |=== [cols="40m,~"] .Testing-oriented modules |=== -|hibernate-testing| A framework for testing Hibernate ORM functionality -|hibernate-integrationtest-java-modules| Integration tests for running Hibernate ORM in the Java module path +|hibernate-testing| A series of JUnit extensions for testing Hibernate ORM functionality |=== -These artifacts are published under the Maven group id `org.hibernate.orm`. +[[platform]] +=== Platform / BOM -[NOTE] -There's more to Hibernate than the modules belonging to the ORM project: Hibernate Search, Hibernate Reactive, Hibernate Validator, and more. +Hibernate also provides a platform (BOM in Maven terminology) module which can be used to align versions of the Hibernate modules along with the versions of its libraries. The platform artifact is named `hibernate-platform`. +To apply the platform in Gradle + +[source,groovy] +---- +dependencies { + implementation platform "org.hibernate.orm:hibernate-platform:6.3.0.Final" + + // use the versions from the platform + implementation "org.hibernate.orm:hibernate-core" + implementation "jakarta.transaction:jakarta.transaction-api" +} +---- + +See the https://docs.gradle.org/current/userguide/java_platform_plugin.html#sec:java_platform_consumption[Gradle documentation] for capabilities of applying a platform. + +To apply the platform (BOM) in Maven + +[source,xml] +---- + + org.hibernate.orm + hibernate-core + + + jakarta.transaction + jakarta.transaction-api + + + + + org.hibernate.orm + hibernate-platform + 6.3.0.Final + pom + import + + +---- diff --git a/documentation/src/main/asciidoc/quickstart/guides/preface.adoc b/documentation/src/main/asciidoc/quickstart/guides/preface.adoc new file mode 100644 index 0000000000..b44b21b353 --- /dev/null +++ b/documentation/src/main/asciidoc/quickstart/guides/preface.adoc @@ -0,0 +1,12 @@ +:shared-attributes-dir: ../../shared/ + +include::{shared-attributes-dir}/url-attributes.adoc[] +include::{shared-attributes-dir}/filesystem-attributes.adoc[] + +[[preface]] +== Preface + +Hibernate is an _Object/Relational Mapping_ (ORM) solution for programs written in Java and other JVM +languages. + +include::{shared-attributes-dir}/background.adoc[] diff --git a/documentation/src/main/asciidoc/quickstart/guides/tutorial_annotations.adoc b/documentation/src/main/asciidoc/quickstart/guides/tutorial_annotations.adoc index 57d95d0ce1..f91f2f3951 100644 --- a/documentation/src/main/asciidoc/quickstart/guides/tutorial_annotations.adoc +++ b/documentation/src/main/asciidoc/quickstart/guides/tutorial_annotations.adoc @@ -1,9 +1,12 @@ +:bootstrap-native-url: {doc-user-guide-url}#bootstrap-native +:entity-model-url: {doc-user-guide-url}#entity + [[tutorial_annotations]] == Tutorial using native Hibernate APIs .Objectives - [*] Configure Hibernate using `hibernate.properties` -- [*] Create a `SessionFactory` using `org.hibernate.boot` +- [*] Create a `SessionFactory` using link:{bootstrap-native-url}[native bootstrapping] - [*] Use annotations to provide mapping information - [*] Use `Session` to persist and query data @@ -74,6 +77,9 @@ Observe that: Hibernate needs to instantiate objects for you, using Java Reflection. The constructor should have package-private or `public` visibility, to allow Hibernate to generate proxies and optimized code for field access. +[NOTE] +The link:{entity-model-url}[Entity types] section of the User Guide covers the complete set of requirements for the entity class. + We use annotations to identify the class as an entity, and to map it to the relational schema. [[hibernate-gsg-tutorial-annotations-entity-entity]] @@ -205,4 +211,5 @@ sessionFactory.inTransaction(session -> { - [ ] Actually run this example to see the SQL executed by Hibernate displayed in the console. - [ ] Reconfigure the examples to connect to your own persistent relational database. - [ ] Add an association to the `Event` entity to model a message thread. - See the _Introduction to Hibernate 6_ for details. + +// force the break diff --git a/documentation/src/main/asciidoc/quickstart/guides/tutorial_envers.adoc b/documentation/src/main/asciidoc/quickstart/guides/tutorial_envers.adoc index 9a2e8f5210..b0506b5fdb 100644 --- a/documentation/src/main/asciidoc/quickstart/guides/tutorial_envers.adoc +++ b/documentation/src/main/asciidoc/quickstart/guides/tutorial_envers.adoc @@ -54,4 +54,6 @@ public void testBasicUsage() { - [*] Write a query to retrieve only historical data which meets some criteria. Use the _User Guide_ to see how Envers queries are constructed. - [*] Experiment with auditing entities which have various forms of relationships (many-to-one, many-to-many, etc). Try -retrieving historical versions (revisions) of such entities and navigating the object tree. \ No newline at end of file +retrieving historical versions (revisions) of such entities and navigating the object tree. + +// force the break \ No newline at end of file diff --git a/documentation/src/main/asciidoc/quickstart/guides/tutorial_jpa.adoc b/documentation/src/main/asciidoc/quickstart/guides/tutorial_jpa.adoc index 3b494a7d19..b4538e7e77 100644 --- a/documentation/src/main/asciidoc/quickstart/guides/tutorial_jpa.adoc +++ b/documentation/src/main/asciidoc/quickstart/guides/tutorial_jpa.adoc @@ -55,15 +55,16 @@ In Java(TM) SE environments the persistence provider (Hibernate) is required to ---- <1> A `persistence.xml` file should provide a unique name for each _persistence unit_ it declares. -Applications use this name to reference the configuration when obtaining an `EntityManagerFactory`. +Applications use this name to reference the configuration when obtaining an `EntityManagerFactory` as we will see shortly. <2> The `` element registers our annotated entity class. <3> The settings specified as `` elements were already discussed in <>. Here JPA-standard property names are used where possible. [NOTE] +==== Configuration properties prefixed with the legacy Java EE namespace `javax.persistence` are still -recognized, but the Jakarta EE namespace `jakarta.persistence` is now preferred. - +recognized, but the Jakarta EE namespace `jakarta.persistence` should be preferred. +==== [[hibernate-gsg-tutorial-jpa-entity]] === The annotated entity Java class @@ -77,14 +78,14 @@ The previous tutorials used Hibernate native APIs. This tutorial uses the standard Jakarta Persistence APIs. [[hibernate-gsg-tutorial-jpa-test-setUp]] -.Obtaining the jakarta.persistence.EntityManagerFactory +.Obtaining the JPA EntityManagerFactory [source, java] ---- protected void setUp() { - sessionFactory = Persistence.createEntityManagerFactory("org.hibernate.tutorial.jpa"); <1> + entityManagerFactory = Persistence.createEntityManagerFactory("org.hibernate.tutorial.jpa"); <1> } ---- -<1> Notice again that the persistence unit name is `org.hibernate.tutorial.jpa`, which matches <>. +<1> Notice again that the persistence unit name is `org.hibernate.tutorial.jpa`, which matches the name from our <>. The code to persist and query entities is almost identical to <>. @@ -114,11 +115,13 @@ void inTransaction(Consumer work) { ---- [TIP] -If you use JPA in Java SE, you'll need to copy/paste this function into your project. +If you use JPA in Java SE, you'll need to copy/paste this function into your project. Alternatively you could unwrap the `EntityManagerFactory` as a `SessionFactory`. [[hibernate-gsg-tutorial-jpa-further]] === Take it further! .Practice Exercises - [ ] Learn how to use CDI to inject a container-managed `EntityManager` in Quarkus. - See https://quarkus.io/guides/hibernate-orm[the Quarkus website] for instructions. \ No newline at end of file + See https://quarkus.io/guides/hibernate-orm[the Quarkus website] for instructions. + +// force the break \ No newline at end of file diff --git a/documentation/src/main/asciidoc/shared/background.adoc b/documentation/src/main/asciidoc/shared/background.adoc new file mode 100644 index 0000000000..03430d9364 --- /dev/null +++ b/documentation/src/main/asciidoc/shared/background.adoc @@ -0,0 +1,12 @@ + +While a strong background in SQL is not required to use Hibernate, a basic understanding of its concepts is useful - especially the principles of _data modeling_. +Understanding the basics of transactions and design patterns such as _Unit of Work_ are important as well. + +[[useful-resources]] +.Useful background resources +**** +- https://en.wikipedia.org/wiki/Data_modeling[Data Modeling (Wikipedia)]. +- https://www.agiledata.org/essays/dataModeling101.html[Data Modeling 101] +- https://www.marcobehler.com/guides/a-guide-to-accessing-databases-in-java[Java & Databases: An Overview of Libraries & APIs] +- https://martinfowler.com/eaaCatalog/unitOfWork.html[Unit of Work] +**** diff --git a/documentation/src/main/asciidoc/shared/common-attributes.adoc b/documentation/src/main/asciidoc/shared/common-attributes.adoc new file mode 100644 index 0000000000..70066a8507 --- /dev/null +++ b/documentation/src/main/asciidoc/shared/common-attributes.adoc @@ -0,0 +1,3 @@ + +// NOTE : majorMinorVersion is injected by the build and will override this value +:majorMinorVersion: 6.3 \ No newline at end of file diff --git a/documentation/src/main/asciidoc/shared/filesystem-attributes.adoc b/documentation/src/main/asciidoc/shared/filesystem-attributes.adoc new file mode 100644 index 0000000000..4b0c59edba --- /dev/null +++ b/documentation/src/main/asciidoc/shared/filesystem-attributes.adoc @@ -0,0 +1,15 @@ +// **************************************************************************** +// Centralized definition of Asciidoc attributes for local filesystem paths +// **************************************************************************** + +:doc-main-dir: ../.. +:doc-main-asciidoc-dir: {doc-main-dir}/asciidoc +:doc-main-style-dir: {doc-main-dir}/style +:pdf-theme: {doc-main-style-dir}/pdf/theme.yml +:pdf-fontsdir: {doc-main-style-dir}/pdf/fonts +//:title-logo-image: {doc-main-style-dir}/asciidoctor/images/org/hibernate/logo.png[] + +:root-project-dir: ../../../../.. +:core-project-dir: {root-project-dir}/hibernate-core +:documentation-project-dir: {root-project-dir}/documentation +:testing-project-dir: {root-project-dir}/hibernate-testing diff --git a/documentation/src/main/asciidoc/shared/renderer-attributes.adoc b/documentation/src/main/asciidoc/shared/renderer-attributes.adoc new file mode 100644 index 0000000000..0aa3837684 --- /dev/null +++ b/documentation/src/main/asciidoc/shared/renderer-attributes.adoc @@ -0,0 +1,3 @@ +:source-highlighter: rouge +:icons: font +:doctype: book \ No newline at end of file diff --git a/documentation/src/main/asciidoc/shared/url-attributes.adoc b/documentation/src/main/asciidoc/shared/url-attributes.adoc new file mode 100644 index 0000000000..12c29a944d --- /dev/null +++ b/documentation/src/main/asciidoc/shared/url-attributes.adoc @@ -0,0 +1,23 @@ +// **************************************************************************** +// Centralized definition of Asciidoc attributes for documentation urls +// **************************************************************************** + +include::./common-attributes.adoc[] + +:doc-base-url: https://docs.jboss.org/hibernate/orm +:doc-version-base-url: {doc-base-url}/{majorMinorVersion} +:doc-migration-guide-url: {doc-version-base-url}/migration-guide/migration-guide.html +:doc-quick-start-url: {doc-version-base-url}/quickstart/html_single/ +:doc-query-language-url: {doc-version-base-url}/querylanguage/html_single/Hibernate_Query_Language.html +:doc-introduction-url: {doc-version-base-url}/introduction/html_single/Hibernate_Introduction.html +:doc-user-guide-url: {doc-version-base-url}/userguide/html_single/Hibernate_User_Guide.html +:doc-javadoc-url: {doc-version-base-url}/javadocs/ +:doc-topical-url: {doc-version-base-url}/topical/html_single/ +:doc-registries-url: {doc-topical-url}/registries/ServiceRegistries.html +:doc-logging-url: {doc-topical-url}/logging/Logging.html + +:report-deprecation-url: {doc-version-base-url}/deprecated/deprecating.txt +:report-dialect-url: {doc-version-base-url}/dialect/dialect.html +:report-incubating-url: {doc-version-base-url}/incubating/incubating.txt +:report-internals-url: {doc-version-base-url}/internals/internal.txt +:report-logging-url: {doc-version-base-url}/logging/logging.html diff --git a/documentation/src/main/asciidoc/topical/index.adoc b/documentation/src/main/asciidoc/topical/index.adoc index d6798303c5..628562548d 100644 --- a/documentation/src/main/asciidoc/topical/index.adoc +++ b/documentation/src/main/asciidoc/topical/index.adoc @@ -1,36 +1,52 @@ +:shared-attributes-dir: ../shared/ + +include::{shared-attributes-dir}/common-attributes.adoc[] +include::{shared-attributes-dir}/url-attributes.adoc[] +include::{shared-attributes-dir}/filesystem-attributes.adoc[] +include::{shared-attributes-dir}/renderer-attributes.adoc[] + = Topical Guides -:userguide_rel_link: ../../userguide/html_single/Hibernate_User_Guide.html -:integrationguid_rel_link: ../../integrationguide/html_single/Hibernate_Integration_Guide.html -:migrationguide_rel_link: ../../migration-guide/migration-guide.html -:logging_rel_link: ../../logging/logging.html -:incubating_rel_link: ../../incubating/incubating.txt -:internal_rel_link: ../../internals/internal.txt :toc: Hibernate documentation is organized into several guides that cover specific topics. This guide provides links to -all the guides to give some direction on where to look for information. +all the documentation to give some direction on where to look for information. -NOTE: This is still very much a work in progress. <> is definitely welcome! - -== User Guides -* For information on bootstrapping Hibernate -** For bootstrapping a SessionFactory, see the link:{userguide_rel_link}#bootstrap-native[Native Bootstrapping Guide] -** For bootstrapping an EntityManagerFactory (Jakarta Persistence) using Hibernate, see the link:{userguide_rel_link}#bootstrap-jpa[Jakarta Persistence Bootstrap Guide] -** For (semi-deprecated) bootstrapping of a SessionFactory using the legacy Configuration approach, see the link:{userguide_rel_link}#appendix-legacy-bootstrap[Legacy Bootstrap Guide] -* For information on generated (non-identifier) values, see the <> -* Others coming soon +[TIP] +==== +See the link:{doc-migration-guide-url}[Migration Guide] for details about migration to Hibernate {majorMinorVersion}. +==== -== Migration -* For information on how to migrate to the current Hibernate 6 version check out the link:{migrationguide_rel_link}[Migration Guide] +[[usage-guides]] +== Usage Guides + +Hibernate publishes multiple usage guides - + +link:{doc-quick-start-url}[Quick Start]:: + Tutorial style guide for quickly getting started with Hibernate. +link:{doc-introduction-url}[Introduction to Hibernate]:: + High-level look at the most used Hibernate features. +link:{doc-query-language-url}[Guide to the Hibernate Query Language]:: + Discussion of the Hibernate Query Language. +link:{doc-user-guide-url}[User Guide]:: + Detailed discussion of all features of Hibernate. More of a reference manual. +[[logging]] +== Logging + +The link:{doc-logging-url}[Logging Guide] discusses logging in Hibernate. + + +[[tooling]] == Tooling -* See the link:{userguide_rel_link}#tooling[Tooling Guide] for information on: -** Bytecode enhancement -** Static Metamodel Generation -** Gradle, Maven, and Ant plugins -** Schema management (coming soon) + +See the link:{doc-user-guide-url}#tooling[Tooling Guide] for information on: + +* Bytecode enhancement +* Static Metamodel Generation +* Gradle, Maven, and Ant plugins +* Schema management == Integrator Guides @@ -38,18 +54,45 @@ NOTE: This is still very much a work in progress. <> is definitely * Others coming soon -== Logging -Check out the link:{logging_rel_link}[Logging Guide] for a list of available Hibernate loggers +[[support]] +== Compatibility and Support + +Compatibility is defined as ... + +Support is defined as ... + +By default, all parts of Hibernate are considered supported and follow the general backwards compatibility https://hibernate.org/community/compatibility-policy/[policy]. +Various things influence the levels of support and backwards compatibility to expect in regard to parts of Hibernate. + +[[support-internal]] +=== Internal + +Internal parts of Hibernate are simply that - internal implementation details that are not supported for use by applications. +Use of internal contracts should be avoided as they are not supported and could be removed or changed at any time. + +Contracts considered internal are defined in one of 2 ways: + +1. The Java class (interface, etc.) is defined under a package named `internal`, either directly or as a sub-package +2. Through the use of the `@Internal` annotation. + +See the definitive set of link:{report-internals-url}[internals]. -== Miscellaneous -* For a list of `@Incubating` source elements, see the link:{incubating_rel_link}[incubating] list. -* For a list of `@Internal` source elements, see the link:{internal_rel_link}[internal] list. +[[support-incubating]] +=== Incubating + +Incubating contracts are generally new contracts which are still being actively designed, similar to +"tech preview" features. +Such contracts are subject to change and should be used with that understanding. + +See the definitive set of link:{report-incubating-url}[incubations]. + +[[support-deprecation]] +=== Deprecations + +1. `@Deprecated` +2. `@Remove` + +See the definitive set of link:{report-deprecation-url}[deprecations]. -[[helping]] -== Helping - -* Reporting/fixing problems. Report any typos or inaccurate information to the -https://hibernate.atlassian.net/browse/HHH[Hibernate ORM Jira] using the +documentation+ component. Follow the same -guidelines for contributing fixes and improvements as for contributing source code. \ No newline at end of file diff --git a/documentation/src/main/asciidoc/topical/logging/Logging.adoc b/documentation/src/main/asciidoc/topical/logging/Logging.adoc new file mode 100644 index 0000000000..4422ff99f0 --- /dev/null +++ b/documentation/src/main/asciidoc/topical/logging/Logging.adoc @@ -0,0 +1,19 @@ +:shared-attributes-dir: ../../shared/ + +include::{shared-attributes-dir}/common-attributes.adoc[] +include::{shared-attributes-dir}/url-attributes.adoc[] +include::{shared-attributes-dir}/filesystem-attributes.adoc[] +include::{shared-attributes-dir}/renderer-attributes.adoc[] + +:jboss-logging-url: + +[[root]] += Logging + +Hibernate uses the link:{jboss-logging-url}[JBoss Logging] library for its logging API. + +JBoss Logging is a logging facade, similar to SLF4J. + +[[logger-names]] +== Logger Names + diff --git a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc index a23f027470..6e0b5d539e 100644 --- a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc +++ b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc @@ -1,10 +1,14 @@ +:shared-attributes-dir: ../shared/ + +include::{shared-attributes-dir}/common-attributes.adoc[] +include::{shared-attributes-dir}/url-attributes.adoc[] +include::{shared-attributes-dir}/filesystem-attributes.adoc[] +include::{shared-attributes-dir}/renderer-attributes.adoc[] + = Hibernate ORM User Guide :toc2: :toclevels: 3 :sectanchors: -:documentation-project-dir: ../../../.. -:root-project-dir: {documentation-project-dir}/.. - include::Preface.adoc[] diff --git a/documentation/src/main/asciidoc/userguide/Preface.adoc b/documentation/src/main/asciidoc/userguide/Preface.adoc index 4e307c1afd..5c2de61d00 100644 --- a/documentation/src/main/asciidoc/userguide/Preface.adoc +++ b/documentation/src/main/asciidoc/userguide/Preface.adoc @@ -1,3 +1,6 @@ +:shared-attributes-dir: ../shared/ +include::{shared-attributes-dir}/url-attributes.adoc[] + [[preface]] == Preface @@ -14,32 +17,31 @@ However, unlike many other persistence solutions, Hibernate does not hide the po Hibernate may not be the best solution for data-centric applications that only use stored-procedures to implement the business logic in the database, it is most useful with object-oriented domain models and business logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate vendor-specific SQL code and will help with the common task of result set translation from a tabular representation to a graph of objects. +[[system-requirements]] +=== System Requirements + +Hibernate {majorMinorVersion} requires at least Java 11 and JDBC 4.2. + +[[getting-started]] +=== Getting Started + +include::{shared-attributes-dir}/background.adoc[] + +[TIP] +==== +New users may want to first look at the tutorial-style link:{doc-quick-start-url}[Quick Start] guide. + +This User Guide is really more of a reference guide. +For a more high-level discussion of the most used features of Hibernate, see the link:{doc-introduction-url}[Introduction to Hibernate] guide. + +There is also a series of link:{doc-topical-url}[topical guides] providing deep dives into various topics such as logging, compatibility and support, etc. +==== + + === Get Involved * Use Hibernate and report any bugs or issues you find. See https://hibernate.org/issuetracker[Issue Tracker] for details. * Try your hand at fixing some bugs or implementing enhancements. Again, see https://hibernate.org/issuetracker[Issue Tracker]. -* Engage with the community using mailing lists, forums, IRC, or other ways listed in the https://hibernate.org/community[Community section]. -* Help improve or translate this documentation. Contact us on the developer mailing list if you have interest. +* Engage with the community using the methods listed in the https://hibernate.org/community[Community section]. +* Help improve this documentation. Contact us on the developer mailing list or Zulip if you have interest. * Spread the word. Let the rest of your organization know about the benefits of Hibernate. - -== System Requirements - -Hibernate 6.0 and later versions require at least Java 11 and JDBC 4.2. - -=== Getting Started Guide - -New users may want to first look through the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/quickstart/html_single/[Hibernate Getting Started Guide] for basic information as well as tutorials. -There is also a series of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/topical/html_single/[topical guides] providing deep dives into various topics. - -[NOTE] -==== -While having a strong background in SQL is not required to use Hibernate, it certainly helps a lot because it all boils down to SQL statements. -Probably even more important is an understanding of data modeling principles. -You might want to consider these resources as a good starting point: - -* https://en.wikipedia.org/wiki/Data_modeling[Data modeling Wikipedia definition] -* https://www.agiledata.org/essays/dataModeling101.html[Data Modeling 101] - -Understanding the basics of transactions and design patterns such as _Unit of Work_ (<>) or _Application Transaction_ are important as well. -These topics will be discussed in the documentation, but a prior understanding will certainly help. -==== diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/associations.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/associations.adoc index 7cc0aea762..991646853b 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/associations.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/associations.adoc @@ -540,7 +540,7 @@ Neither result includes a match for "John Doe" because the inner-join filters ou Hibernate does support a means to refer specifically to the key column (`Person.cityName`) in a query using the special `fk(..)` function. E.g. -[[associations-not-found-implicit-join-example]] +[[associations-not-found-fk-function-example]] .Implicit join example ==== [source,java] diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc index 39f2bd84b9..7827c8c1f7 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc @@ -38,7 +38,7 @@ The semantics of a collection describes how to handle the collection, including * the collection subtype to use - `java.util.List`, `java.util.Set`, `java.util.SortedSet`, etc. * how to access elements of the collection -* how to create instances of the collection - both "raw" and "wrapper" forms. See <> +* how to create instances of the collection - both "raw" and "<>" forms. Hibernate supports the following semantics: diff --git a/documentation/src/main/asciidoc/userguide/chapters/multitenancy/MultiTenancy.adoc b/documentation/src/main/asciidoc/userguide/chapters/multitenancy/MultiTenancy.adoc index f5e04adfd7..b30f83d1d1 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/multitenancy/MultiTenancy.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/multitenancy/MultiTenancy.adoc @@ -81,7 +81,7 @@ include::{example-dir-multitenancy}/AbstractMultiTenancyTest.java[tags=multitena For the partitioned data approach, each entity representing partitioned data must declare a field annotated `@TenantId`. -[[multitenacy-hibernate-MultiTenantConnectionProvider-example]] +[[multitenacy-hibernate-TenantId-example]] .A `@TenantId` usage example ==== [source, JAVA, indent=0] diff --git a/documentation/src/main/asciidoc/pdf/fonts/Inconsolata-Light.ttf b/documentation/src/main/style/pdf/fonts/Inconsolata-Light.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/Inconsolata-Light.ttf rename to documentation/src/main/style/pdf/fonts/Inconsolata-Light.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/NotoEmoji.ttf b/documentation/src/main/style/pdf/fonts/NotoEmoji.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/NotoEmoji.ttf rename to documentation/src/main/style/pdf/fonts/NotoEmoji.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/OpenSansEmoji.ttf b/documentation/src/main/style/pdf/fonts/OpenSansEmoji.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/OpenSansEmoji.ttf rename to documentation/src/main/style/pdf/fonts/OpenSansEmoji.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Black.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-Black.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Black.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-Black.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-BlackItalic.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-BlackItalic.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-BlackItalic.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-BlackItalic.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Bold.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-Bold.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Bold.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-Bold.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-BoldItalic.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-BoldItalic.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-BoldItalic.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-BoldItalic.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-ExtraLight.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-ExtraLight.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-ExtraLight.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-ExtraLight.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-ExtraLightItalic.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-ExtraLightItalic.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-ExtraLightItalic.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-ExtraLightItalic.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Italic.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-Italic.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Italic.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-Italic.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Light.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-Light.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Light.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-Light.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-LightItalic.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-LightItalic.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-LightItalic.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-LightItalic.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Regular.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-Regular.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-Regular.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-Regular.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-SemiBold.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-SemiBold.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-SemiBold.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-SemiBold.ttf diff --git a/documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-SemiBoldItalic.ttf b/documentation/src/main/style/pdf/fonts/SourceSansPro-SemiBoldItalic.ttf similarity index 100% rename from documentation/src/main/asciidoc/pdf/fonts/SourceSansPro-SemiBoldItalic.ttf rename to documentation/src/main/style/pdf/fonts/SourceSansPro-SemiBoldItalic.ttf diff --git a/documentation/src/main/asciidoc/pdf/theme.yml b/documentation/src/main/style/pdf/theme.yml similarity index 100% rename from documentation/src/main/asciidoc/pdf/theme.yml rename to documentation/src/main/style/pdf/theme.yml