Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

get rid of useless titles on admonitions 

failed experiment
This commit is contained in:
Gavin 2023-05-12 22:05:20 +02:00 committed by Christian Beikov
parent ab688d3016
commit 1e0fd15d13
6 changed files with 35 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
documentation/src/main/asciidoc/introduction/Configuration.adoc
View File

@ -150,7 +150,7 @@ The `<persistence-unit>` element defines a named _persistence unit_, that is:
Each `<class>` element specifies the fully-qualified name of an entity class. Each `<class>` element specifies the fully-qualified name of an entity class.
[TIP] [TIP]
.Scanning for entity classes // .Scanning for entity classes
==== ====
In some container environments, for example, in any EE container, the `<class>` elements are unnecessary, since the container will scan the archive for annotated classes, and automatically recognize any class annotated `@Entity`. In some container environments, for example, in any EE container, the `<class>` elements are unnecessary, since the container will scan the archive for annotated classes, and automatically recognize any class annotated `@Entity`.
==== ====
@ -201,13 +201,12 @@ SessionFactory sf = new Configuration()
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. 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. On the other hand, it's very easy to use, and exposes some options that `persistence.xml` doesn't support.
[TIP]
.Advanced configuration options .Advanced configuration options
==== ****
Actually, the `Configuration` class is just a very simple facade for the more modern, much more powerful—but more complex—API defined in the package `org.hibernate.boot`. Actually, the `Configuration` class is just a very simple facade for the more modern, much more powerful—but more complex—API defined in the package `org.hibernate.boot`.
This API is useful if you have very advanced requirements, for example, if you're writing a framework or implementing a container. This API is useful if you have very advanced requirements, for example, if you're writing a framework or implementing a container.
You'll find more information in the Hibernate ORM Integration Guide, and in the package-level documentation of `org.hibernate.boot`. You'll find more information in the Hibernate ORM Integration Guide, and in the package-level documentation of `org.hibernate.boot`.
==== ****
[[basic-configuration-settings]] [[basic-configuration-settings]]
=== Basic configuration settings === Basic configuration settings
@ -218,7 +217,7 @@ Of course, we're not going to cover every useful configuration setting in this c
Instead, we'll mention the ones you need to get started, and come back to some other important settings later, especially when we talk about performance tuning. Instead, we'll mention the ones you need to get started, and come back to some other important settings later, especially when we talk about performance tuning.
[TIP] [TIP]
.Ya ain't gunna need 'em // .Ya ain't gunna need 'em
==== ====
Hibernate has many—too many—switches and toggles. Hibernate has many—too many—switches and toggles.
Please don't go crazy messing about with these settings; most of them are rarely needed, and many only exist to provide backward compatibility with older versions of Hibernate. Please don't go crazy messing about with these settings; most of them are rarely needed, and many only exist to provide backward compatibility with older versions of Hibernate.
@ -314,7 +313,7 @@ Additionally, drop the schema on `SessionFactory` shutdown.
This feature is extremely useful for testing. This feature is extremely useful for testing.
[TIP] [TIP]
.Importing test or reference data // .Importing test or reference data
==== ====
The easiest way to pre-initialize a database with test or "reference" data is to place a list of SQL `insert` statements in a file named, for example, `import.sql`, and specify the path to this file using the property `jakarta.persistence.schema-generation.create-script-source`. The easiest way to pre-initialize a database with test or "reference" data is to place a list of SQL `insert` statements in a file named, for example, `import.sql`, and specify the path to this file using the property `jakarta.persistence.schema-generation.create-script-source`.
@ -322,7 +321,7 @@ This approach is cleaner than writing Java code to instantiate entity instances
==== ====
[TIP] [TIP]
.Programmatic schema export // .Programmatic schema export
==== ====
The `SchemaManager` API allow you to control schema export programmatically. The `SchemaManager` API allow you to control schema export programmatically.
@ -379,9 +378,9 @@ The following properties are very useful for minimizing the amount of informatio
|=== |===
[TIP] [TIP]
.Implement your naming standards as a `PhysicalNamingStrategy` // .Implement your naming standards as a `PhysicalNamingStrategy`
==== ====
Writing your own `PhysicalNamingStrategy` and/or `ImplicitNamingStrategy` is an especially good way to reduce the clutter of annotations on your entity classes, and we think you should do it for any nontrivial data model. Writing your own `PhysicalNamingStrategy` and/or `ImplicitNamingStrategy` is an especially good way to reduce the clutter of annotations on your entity classes, and to implement your database naming conventions, and so we think you should do it for any nontrivial data model.
Please refer to the Javadoc for these interfaces for more information about the division of responsibility between them. Please refer to the Javadoc for these interfaces for more information about the division of responsibility between them.
==== ====
@ -399,7 +398,7 @@ _By default,_ SQL Server's `char` and `varchar` types don't accommodate Unicode
|=== |===
[TIP] [TIP]
.Configuring SQL Server to use UTF-8 by default // .Configuring SQL Server to use UTF-8 by default
==== ====
Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`. Alternatively, you can configure SQL Server to use the UTF-8 enabled collation `_UTF8`.
==== ====

23
documentation/src/main/asciidoc/introduction/Entities.adoc
View File

@ -34,7 +34,7 @@ An entity must:
On the other hand, the entity class may be either concrete or `abstract`, and it may have any number of additional constructors. On the other hand, the entity class may be either concrete or `abstract`, and it may have any number of additional constructors.
[TIP] [TIP]
.Inner entity classes // .Inner entity classes
==== ====
An entity class may be a `static` inner class. An entity class may be a `static` inner class.
==== ====
@ -196,7 +196,7 @@ Long id;
---- ----
[TIP] [TIP]
.Using surrogate keys // .Using surrogate keys
==== ====
System-generated identifiers, or _surrogate keys_ make it easier to evolve or refactor the relational data model. System-generated identifiers, or _surrogate keys_ make it easier to evolve or refactor the relational data model.
If you have the freedom to define the relational schema, we recommend the use of surrogate keys. If you have the freedom to define the relational schema, we recommend the use of surrogate keys.
@ -440,7 +440,7 @@ LocalDateTime lastUpdated;
The `@Id` and `@Version` attributes we've already seen are just specialized examples of _basic attributes_. The `@Id` and `@Version` attributes we've already seen are just specialized examples of _basic attributes_.
[TIP] [TIP]
.Optimistic locking in Hibernate // .Optimistic locking in Hibernate
==== ====
If an entity doesn't have a version number, which often happens when mapping legacy data, we can still do optimistic locking. If an entity doesn't have a version number, which often happens when mapping legacy data, we can still do optimistic locking.
The `@OptimisticLocking` annotation lets us specify that optimistic locks should be checked by validating the values of `ALL` fields, or only the `DIRTY` fields of the entity. The `@OptimisticLocking` annotation lets us specify that optimistic locks should be checked by validating the values of `ALL` fields, or only the `DIRTY` fields of the entity.
@ -609,7 +609,7 @@ In Hibernate 6, an `enum` annotated `@Enumerated(STRING)` is mapped to:
Any other ``enum`` is mapped to a `TINYINT` column with a `CHECK` constraint. Any other ``enum`` is mapped to a `TINYINT` column with a `CHECK` constraint.
[TIP] [TIP]
.It's usually better to persist `enum` values by their names // .It's usually better to persist `enum` values by their names
==== ====
JPA picks the wrong default here. JPA picks the wrong default here.
In most cases, storing an integer encoding of the `enum` value makes the relational data harder to interpret. In most cases, storing an integer encoding of the `enum` value makes the relational data harder to interpret.
@ -845,7 +845,7 @@ class Author {
---- ----
[TIP] [TIP]
.The `@Embedded` annotation is not required // .The `@Embedded` annotation is not required
==== ====
JPA provides an `@Embedded` annotation to identify an attribute of an entity that refers to an embeddable type. JPA provides an `@Embedded` annotation to identify an attribute of an entity that refers to an embeddable type.
This annotation is completely optional, and so we don't usually use it. This annotation is completely optional, and so we don't usually use it.
@ -879,7 +879,7 @@ In this diagram, we can see the sorts of associations which are possible.
image::images/associations.png[] image::images/associations.png[]
[TIP] [TIP]
.One-to-one associations and subtyping // .One-to-one associations and subtyping
==== ====
An astute observer of the diagram above might notice that the relationships we've represented as unidirectional one-to-one associations could reasonably be represented in Java using subtyping. An astute observer of the diagram above might notice that the relationships we've represented as unidirectional one-to-one associations could reasonably be represented in Java using subtyping.
This is quite normal. This is quite normal.
@ -895,7 +895,7 @@ A many-to-one association is the most basic sort of association we can imagine.
It maps completely naturally to a foreign key in the database. It maps completely naturally to a foreign key in the database.
[TIP] [TIP]
.One-to-many join table mappings // .One-to-many join table mappings
==== ====
Later, we'll see how to map a many-to-one association to an <<join-table-mappings,association table>>. Later, we'll see how to map a many-to-one association to an <<join-table-mappings,association table>>.
==== ====
@ -917,10 +917,11 @@ class Book {
Here, the `Book` table has a foreign key column holding the identifier of the associated `Publisher`. Here, the `Book` table has a foreign key column holding the identifier of the associated `Publisher`.
[TIP] [TIP]
.Almost all associations should be lazy // .Almost all associations should be lazy
==== ====
A very unfortunate misfeature of JPA is that `@ManyToOne` associations are fetched eagerly by default. A very unfortunate misfeature of JPA is that `@ManyToOne` associations are fetched eagerly by default.
This is almost never what we want. This is almost never what we want.
Almost all associations should be lazy.
The only scenario in which `fetch=EAGER` makes sense is if we think there's always a _very_ high probability that the associated object will be found in the second-level cache. The only scenario in which `fetch=EAGER` makes sense is if we think there's always a _very_ high probability that the associated object will be found in the second-level cache.
Whenever this isn't the case, remember to explicitly specify `fetch=LAZY`. Whenever this isn't the case, remember to explicitly specify `fetch=LAZY`.
==== ====
@ -955,7 +956,7 @@ That said, it's not a hard requirement to update the unowned side, at least if y
==== ====
[TIP] [TIP]
.Unidirectional `@OneToMany`? // .Unidirectional `@OneToMany`?
==== ====
In principle Hibernate _does_ allow you to have a unidirectional one to many, that is, a `@OneToMany` with no matching `@ManyToOne` on the other side. In principle Hibernate _does_ allow you to have a unidirectional one to many, that is, a `@OneToMany` with no matching `@ManyToOne` on the other side.
In practice, this mapping is unnatural, and just doesn't work very well. In practice, this mapping is unnatural, and just doesn't work very well.
@ -994,7 +995,7 @@ In hindsight, we could have done more to make clear that this was always a viabl
The simplest sort of one-to-one association is almost exactly line a `@ManyToOne` association, except that it maps to a foreign key column with a `UNIQUE` constraint. The simplest sort of one-to-one association is almost exactly line a `@ManyToOne` association, except that it maps to a foreign key column with a `UNIQUE` constraint.
[TIP] [TIP]
.One-to-many join table mappings // .One-to-many join table mappings
==== ====
Later, we'll see how to map a many-to-one association to an <<join-table-mappings,association table>>. Later, we'll see how to map a many-to-one association to an <<join-table-mappings,association table>>.
==== ====
@ -1018,7 +1019,7 @@ class Author {
Here, the `Author` table has a foreign key column holding the identifier of the associated `Publisher`. Here, the `Author` table has a foreign key column holding the identifier of the associated `Publisher`.
[TIP] [TIP]
.One-to-one associations are a way to represent subtyping // .One-to-one associations are a way to represent subtyping
==== ====
A one-to-one association often models a "type of" relationship. A one-to-one association often models a "type of" relationship.
In our example, an `Author` is a type of `Person`. In our example, an `Author` is a type of `Person`.

4
documentation/src/main/asciidoc/introduction/Hibernate_Introduction.adoc
View File

@ -29,7 +29,7 @@ ORM takes the pain out of persistence by relieving the developer of the need to
Even better, ORM makes it much easier to tune performance later, after the basic persistence logic has already been written. Even better, ORM makes it much easier to tune performance later, after the basic persistence logic has already been written.
[TIP] [TIP]
.ORM or SQL? // .ORM or SQL?
==== ====
A perennial question is: should I use ORM, or plain SQL? A perennial question is: should I use ORM, or plain SQL?
The answer is usually: _use both_. The answer is usually: _use both_.
@ -74,7 +74,7 @@ As an application developer, you must decide whether to:
Whichever path you take, you will use the JPA-defined mapping annotations most of the time, and the Hibernate-defined annotations for more advanced mapping problems. Whichever path you take, you will use the JPA-defined mapping annotations most of the time, and the Hibernate-defined annotations for more advanced mapping problems.
[TIP] [TIP]
.Developing with "pure" JPA // .Developing with "pure" JPA
==== ====
You might wonder if it's possible to develop an application using _only_ JPA-defined APIs, and, indeed, that's possible in principle. You might wonder if it's possible to develop an application using _only_ JPA-defined APIs, and, indeed, that's possible in principle.
JPA is a great baseline that really nails the basics of the object/relational mapping problem. JPA is a great baseline that really nails the basics of the object/relational mapping problem.

10
documentation/src/main/asciidoc/introduction/Interacting.adoc
View File

@ -10,7 +10,7 @@ To interact with the database, that is, to execute queries, or to insert, update
The `Session` interface extends `EntityManager`, and so the only difference between the two interfaces is that `Session` offers a few more operations. The `Session` interface extends `EntityManager`, and so the only difference between the two interfaces is that `Session` offers a few more operations.
[TIP] [TIP]
.The `Session` hiding inside an `EntityManager` // .The `Session` hiding inside an `EntityManager`
==== ====
Actually, in Hibernate, every `EntityManager` is a `Session`, and you can narrow it like this: Actually, in Hibernate, every `EntityManager` is a `Session`, and you can narrow it like this:
@ -28,7 +28,7 @@ We'll come back to <<stateless-sessions,this very useful API>> when we talk abou
What you need to know for now is that a stateless session doesn't have a persistence context. What you need to know for now is that a stateless session doesn't have a persistence context.
[TIP] [TIP]
.Some people prefer `StatelessSession` // .Some people prefer `StatelessSession`
==== ====
Still, we should let you know that some people prefer to use `StatelessSession` everywhere. Still, we should let you know that some people prefer to use `StatelessSession` everywhere.
It's a simpler programming model, and lets the developer interact with the database more _directly_. It's a simpler programming model, and lets the developer interact with the database more _directly_.
@ -312,13 +312,13 @@ Now for the gotchas:
It almost inevitably leads to the infamous _N+1 selects_ problem we'll discuss later when we talk about how to <<association-fetching,optimize association fetching>>. It almost inevitably leads to the infamous _N+1 selects_ problem we'll discuss later when we talk about how to <<association-fetching,optimize association fetching>>.
[TIP] [TIP]
.Strive to avoid triggering lazy fetching // .Strive to avoid triggering lazy fetching
==== ====
We're getting a bit ahead of ourselves here, but let's quickly mention the general strategy we recommend to navigate past these gotchas: We're getting a bit ahead of ourselves here, but let's quickly mention the general strategy we recommend to navigate past these gotchas:
- All associations should be set `fetch=LAZY` to avoid fetching extra data when it's not needed. - All associations should be set `fetch=LAZY` to avoid fetching extra data when it's not needed.
As we mentioned in <<many-to-one>>, this setting is not the default for `@ManyToOne` associations, and must be specified explicitly. As we mentioned in <<many-to-one>>, this setting is not the default for `@ManyToOne` associations, and must be specified explicitly.
- However, avoid writing code which triggers lazy fetching. - But strive to avoid writing code which triggers lazy fetching.
Instead, fetch all the data you'll need upfront at the beginning of a unit of work, using one of the techniques described in <<association-fetching>>, usually, using _join fetch_ in HQL. Instead, fetch all the data you'll need upfront at the beginning of a unit of work, using one of the techniques described in <<association-fetching>>, usually, using _join fetch_ in HQL.
==== ====
@ -490,7 +490,7 @@ HibernateCriteriaBuilder cb = sf.getCriteriaBuilder();
The `HibernateCriteriaBuilder` extends `CriteriaBuilder` and adds many operations that JPQL doesn't have. The `HibernateCriteriaBuilder` extends `CriteriaBuilder` and adds many operations that JPQL doesn't have.
[TIP] [TIP]
.Getting a `HibernateCriteriaBuilder` in JPA // .Getting a `HibernateCriteriaBuilder` in JPA
==== ====
If you're using `EntityManagerFactory`, don't despair, you have two perfectly good ways to obtain the `HibernateCriteriaBuilder` associated with that factory. If you're using `EntityManagerFactory`, don't despair, you have two perfectly good ways to obtain the `HibernateCriteriaBuilder` associated with that factory.
Either: Either:

12
documentation/src/main/asciidoc/introduction/Mapping.adoc
View File

@ -12,7 +12,7 @@ Usually, _we already have a relational schema_, and we're constructing our domai
This is called _bottom up_ mapping. This is called _bottom up_ mapping.
[TIP] [TIP]
."Legacy" data // ."Legacy" data
==== ====
Developers often refer to a pre-existing relational database as "legacy" data. Developers often refer to a pre-existing relational database as "legacy" data.
That's perhaps a bad word to use, conjuring images of bad old "legacy apps" written in COBOL or something. That's perhaps a bad word to use, conjuring images of bad old "legacy apps" written in COBOL or something.
@ -112,7 +112,7 @@ class Author { ... }
---- ----
[TIP] [TIP]
.Discriminator columns for `JOINED` inheritance // .Discriminator columns for `JOINED` inheritance
==== ====
However, we can add a discriminator column if we like, and in that case the generated SQL for polymorphic queries will be slightly simpler. However, we can add a discriminator column if we like, and in that case the generated SQL for polymorphic queries will be slightly simpler.
==== ====
@ -205,7 +205,7 @@ The `@Table` annotation can do more than just specify a name:
|=== |===
[TIP] [TIP]
.If you don't need to, don't hardcode the schema and catalog // .If you don't need to, don't hardcode the schema and catalog
==== ====
It only makes sense to explicitly specify the `schema` in annotations if the domain model is spread across multiple schemas. It only makes sense to explicitly specify the `schema` in annotations if the domain model is spread across multiple schemas.
@ -340,9 +340,9 @@ The `@Column` annotation is not only useful for specifying the column name.
|=== |===
[TIP] [TIP]
.Use of `columnDefinition` results in unportable DDL // .Use of `columnDefinition` results in unportable DDL
==== ====
We no longer recommend the use of `columnDefinition`. We no longer recommend the use of `columnDefinition` since it results in unportable DDL.
Hibernate has much better ways to customize the generated DDL using techniques that result in portable behavior across different databases. Hibernate has much better ways to customize the generated DDL using techniques that result in portable behavior across different databases.
==== ====
@ -409,7 +409,7 @@ class Item {
---- ----
[TIP] [TIP]
.Foreign key constraint names // .Foreign key constraint names
==== ====
Notice the use of `@ForeignKey` to customize the name of the foreign key constraint. Notice the use of `@ForeignKey` to customize the name of the foreign key constraint.
If you don't supply a name explicitly, Hibernate will generate a quite ugly name. If you don't supply a name explicitly, Hibernate will generate a quite ugly name.

2
documentation/src/main/asciidoc/introduction/Tuning.adoc
View File

@ -349,7 +349,7 @@ The JPA-defined cache modes are:
|=== |===
[TIP] [TIP]
.A good time to `BYPASS` the cache // .A good time to `BYPASS` the cache
==== ====
It's a good idea to set the `CacheStoreMode` to `BYPASS` just before running a query which returns a large result set full of data that we don't expect to need again soon. It's a good idea to set the `CacheStoreMode` to `BYPASS` just before running a query which returns a large result set full of data that we don't expect to need again soon.
This saves work, and prevents the newly-read data from pushing out the previously cached data. This saves work, and prevents the newly-read data from pushing out the previously cached data.