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:12:52 +02:00 committed by Christian Beikov
parent 1e0fd15d13
commit 59b6f702e5
5 changed files with 38 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -236,10 +236,10 @@ The properties you really do need to get started are these three:
|=== |===
[IMPORTANT] [IMPORTANT]
.You don't need `hibernate.dialect` anymore! // .You don't need `hibernate.dialect` anymore!
==== ====
In Hibernate 6, you don't need to specify `hibernate.dialect`. In Hibernate 6, you don't need to specify `hibernate.dialect`.
The correct Hibernate SQL `Dialect` will be determined for you. The correct Hibernate SQL `Dialect` will be determined for you automatically.
The only reason to specify this property is if you're using a custom user-written `Dialect` class. The only reason to specify this property is if you're using a custom user-written `Dialect` class.
==== ====
@ -256,7 +256,7 @@ You can set the size of Hibernate's built-in connection pool using this property
|=== |===
[CAUTION] [CAUTION]
.The default connection pool is not meant for production use // .The default connection pool is not meant for production use
==== ====
By default, Hibernate uses a simplistic built-in connection pool. By default, Hibernate uses a simplistic built-in connection pool.
This pool is not meant for use in production, and later, when we discuss performance, we'll see how to <<connection-pool,select a more robust implementation>>. This pool is not meant for use in production, and later, when we discuss performance, we'll see how to <<connection-pool,select a more robust implementation>>.

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

@ -87,14 +87,15 @@ Back when Hibernate was just a baby, property access was quite popular in the Hi
Today, however, field access is _much_ more common. Today, however, field access is _much_ more common.
[NOTE] [NOTE]
.Explicit access type // .Explicit access type
==== ====
The default access type may be specified explicitly using the `@Access` annotation, but we strongly discourage this, since it's ugly and never necessary. The default access type may be specified explicitly using the `@Access` annotation, but we strongly discourage this, since it's ugly and never necessary.
==== ====
[IMPORTANT] [IMPORTANT]
.Mapping annotations should be placed consistently // .Mapping annotations should be placed consistently
==== ====
Mapping annotations should be placed consistently.
If the `@Id` annotation occurs on a field, the other mapping annotations should also be applied to field; or, if the `@Id` annotation occurs on a getter, the other mapping annotations should be applied to getters. If the `@Id` annotation occurs on a field, the other mapping annotations should also be applied to field; or, if the `@Id` annotation occurs on a getter, the other mapping annotations should be applied to getters.
It is in principle possible to mix field and property access using explicit `@Access` annotations at the attribute level. It is in principle possible to mix field and property access using explicit `@Access` annotations at the attribute level.
@ -243,10 +244,10 @@ create sequence seq_book start with 5 increment by 10
---- ----
[IMPORTANT] [IMPORTANT]
.Check the `initialValue` and `allocationSize` // .Check the `initialValue` and `allocationSize`
==== ====
If you let Hibernate export your database schema, the sequence definition will have the right `start with` and `increment` values. If you let Hibernate export your database schema, the sequence definition will have the right `start with` and `increment` values.
But if you're working with a database schema managed outside of Hibernate, make sure the `initialValue` and `allocationSize` members of `@SequenceGenerator` match the `start with` and `increment` specified in the DDL. But if you're working with a database schema managed outside Hibernate, make sure the `initialValue` and `allocationSize` members of `@SequenceGenerator` match the `start with` and `increment` specified in the DDL.
==== ====
Any identifier attribute may now make use of the generator named `bookSeq`: Any identifier attribute may now make use of the generator named `bookSeq`:
@ -268,8 +269,9 @@ Long id;
---- ----
[NOTE] [NOTE]
.JPA id generators may be shared between entities // .JPA id generators may be shared between entities
==== ====
JPA id generators may be shared between entities.
A `@SequenceGenerator` or `@TableGenerator` must have a name, and may be shared between multiple id attributes. A `@SequenceGenerator` or `@TableGenerator` must have a name, and may be shared between multiple id attributes.
This fits somewhat uncomfortably with the common practice of annotating the `@Id` attribute which makes use of the generator! This fits somewhat uncomfortably with the common practice of annotating the `@Id` attribute which makes use of the generator!
==== ====
@ -290,7 +292,7 @@ JPA doesn't define a standard way to extend the set of id generation strategies,
Furthermore, the `@ValueGenerationType` meta-annotation lets you write an annotation which associates a `Generator` type with a non-`@Id` attribute. Furthermore, the `@ValueGenerationType` meta-annotation lets you write an annotation which associates a `Generator` type with a non-`@Id` attribute.
[NOTE] [NOTE]
.The older APIs are still available in Hibernate 6 // .The older APIs are still available in Hibernate 6
==== ====
These APIs are new in Hibernate 6, and supersede the classic `IdentifierGenerator` interface and `@GenericGenerator` annotation from older versions of Hibernate. These APIs are new in Hibernate 6, and supersede the classic `IdentifierGenerator` interface and `@GenericGenerator` annotation from older versions of Hibernate.
However, the older APIs are still available and custom ``IdentifierGenerator``s written for older versions of Hibernate continue to work in Hibernate 6. However, the older APIs are still available and custom ``IdentifierGenerator``s written for older versions of Hibernate continue to work in Hibernate 6.
@ -454,7 +456,7 @@ Even when an entity has a surrogate key, it should still be possible to write do
We call this combination of fields a _natural key_. We call this combination of fields a _natural key_.
[IMPORTANT] [IMPORTANT]
.What if my entity has no natural key? // .What if my entity has no natural key?
==== ====
If you can't identify a natural key, it might be a sign that you need to think more carefully about some aspect of your data model. If you can't identify a natural key, it might be a sign that you need to think more carefully about some aspect of your data model.
If an entity doesn't have a meaningful unique key, then it's impossible to say what event or object it represents in the "real world" outside your program. If an entity doesn't have a meaningful unique key, then it's impossible to say what event or object it represents in the "real world" outside your program.
@ -518,13 +520,13 @@ The JPA specification defines a quite limited set of basic types:
|==== |====
[IMPORTANT] [IMPORTANT]
.Please don't use `Date`! // .Please don't use `Date`!
==== ====
We're begging you to use types from the `java.time` package instead of anything which inherits `java.util.Date`. We're begging you to use types from the `java.time` package instead of anything which inherits `java.util.Date`.
==== ====
[CAUTION] [CAUTION]
.Serialization is usually a bad idea // .Serialization is usually a bad idea
==== ====
Serializing a Java object and storing its binary representation in the database is usually wrong. Serializing a Java object and storing its binary representation in the database is usually wrong.
As we'll soon see in <<embeddable-objects>>, Hibernate has much better ways to handle complex Java objects. As we'll soon see in <<embeddable-objects>>, Hibernate has much better ways to handle complex Java objects.
@ -943,8 +945,10 @@ class Publisher {
The `Publisher.books` field is called the _unowned_ side of the association. The `Publisher.books` field is called the _unowned_ side of the association.
[WARNING] [WARNING]
.To modify a bidirectional association, you must change the _owning side_! // .To modify a bidirectional association, you must change the _owning side_!
==== ====
To modify a bidirectional association, you must change the _owning side_!
Changes made to the unowned side of an association are never synchronized to the database. Changes made to the unowned side of an association are never synchronized to the database.
If we desire to change an association in the database, we must change it from the owning side. If we desire to change an association in the database, we must change it from the owning side.
Here, we must set `Book.publisher`. Here, we must set `Book.publisher`.
@ -1136,7 +1140,7 @@ We've again used ``Set``s to represent the association.
As before, we have the option to `Collection` or `List`, but in this case it _does_ make a difference to the semantics of the association. As before, we have the option to `Collection` or `List`, but in this case it _does_ make a difference to the semantics of the association.
[NOTE] [NOTE]
.Sets and bags // .Sets and bags
==== ====
A many-to-many association represented as a `Collection` or `List` may contain duplicate elements. A many-to-many association represented as a `Collection` or `List` may contain duplicate elements.
However, as before, the order of the elements is not persistent. However, as before, the order of the elements is not persistent.
@ -1182,8 +1186,10 @@ So we may expand our taxonomy with:
|=== |===
[CAUTION] [CAUTION]
.These sorts of mappings are overused // .These sorts of mappings are overused
==== ====
These sorts of mappings are overused.
There _are_ situations where we think it's appropriate to use a collection of basic-typed values in our entity class. There _are_ situations where we think it's appropriate to use a collection of basic-typed values in our entity class.
But such situations are rare. But such situations are rare.
Almost every many-valued relationship should map to a foreign key association between separate tables. Almost every many-valued relationship should map to a foreign key association between separate tables.
@ -1227,7 +1233,7 @@ class Event {
The `@Array` annotation is optional, but it's important to limit the amount of storage space the database allocates to the `ARRAY` column. The `@Array` annotation is optional, but it's important to limit the amount of storage space the database allocates to the `ARRAY` column.
[WARNING] [WARNING]
.Not every database has an `ARRAY` type // .Not every database has an `ARRAY` type
==== ====
Now for the gotcha: not every database has a SQL `ARRAY` type, and some that _do_ have an `ARRAY` type don't allow it to be used as a column type. Now for the gotcha: not every database has a SQL `ARRAY` type, and some that _do_ have an `ARRAY` type don't allow it to be used as a column type.
@ -1259,7 +1265,7 @@ class Event {
---- ----
[WARNING] [WARNING]
.This is not what we would do // .This is not what we would do
==== ====
`@ElementCollection` is one of our least-favorite features of JPA. `@ElementCollection` is one of our least-favorite features of JPA.
Even the name of the annotation is bad. Even the name of the annotation is bad.

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

@ -72,7 +72,7 @@ Furthermore, a persistence context holds a hard references to all its entities,
Thus, the session must be discarded once a unit of work is complete. Thus, the session must be discarded once a unit of work is complete.
[IMPORTANT] [IMPORTANT]
.This is important // .This is important
==== ====
If you don't completely understand the previous passage, go back and re-read it until you do. If you don't completely understand the previous passage, go back and re-read it until you do.
A great deal of human suffering has resulted from users mismanaging the lifecycle of the Hibernate `Session` or JPA `EntityManager`. A great deal of human suffering has resulted from users mismanaging the lifecycle of the Hibernate `Session` or JPA `EntityManager`.
@ -253,8 +253,9 @@ Now, if an exception occurs while interacting with the database, there's no good
Therefore, a session is considered to be unusable after any of its methods throws an exception. Therefore, a session is considered to be unusable after any of its methods throws an exception.
[IMPORTANT] [IMPORTANT]
.The persistence context is fragile // .The persistence context is fragile
==== ====
The persistence context is fragile.
If you receive an exception from Hibernate, you should immediately close and discard the current session. Open a new session if you need to, but throw the bad one away first. If you receive an exception from Hibernate, you should immediately close and discard the current session. Open a new session if you need to, but throw the bad one away first.
==== ====
@ -334,7 +335,7 @@ By default, a flush is triggered when:
- when the program directly calls `flush()`. - when the program directly calls `flush()`.
[NOTE] [NOTE]
.SQL execution happens asynchronously // .SQL execution happens asynchronously
==== ====
Notice that SQL statements are not usually executed synchronously by methods of the `Session` interface like `persist()` and `remove()`. If synchronous execution of SQL is desired, the `StatelessSession` allows this. Notice that SQL statements are not usually executed synchronously by methods of the `Session` interface like `persist()` and `remove()`. If synchronous execution of SQL is desired, the `StatelessSession` allows this.
==== ====
@ -429,7 +430,7 @@ List<Book> matchingBooks =
When a query has multiple parameters, named parameters tend to be easier to read, even if slightly more verbose. When a query has multiple parameters, named parameters tend to be easier to read, even if slightly more verbose.
[IMPORTANT] [IMPORTANT]
.Using parameters to avoid injection attacks // .Using parameters to avoid injection attacks
==== ====
_Never_ concatenate user input with HQL and pass the concatenated string to `createSelectionQuery()`. _Never_ concatenate user input with HQL and pass the concatenated string to `createSelectionQuery()`.
This would open up the possibility for an attacker to execute arbitrary code on your database server. This would open up the possibility for an attacker to execute arbitrary code on your database server.
@ -459,7 +460,7 @@ Occasionally we need to build a query at runtime, from a set of optional conditi
For this, JPA offers an API which allows programmatic construction of a query. For this, JPA offers an API which allows programmatic construction of a query.
[NOTE] [NOTE]
.HQL is implemented in terms of criteria queries // .HQL is implemented in terms of criteria queries
==== ====
Actually, in Hibernate 6, every HQL query is compiled to a criteria query before being translated to SQL. Actually, in Hibernate 6, every HQL query is compiled to a criteria query before being translated to SQL.
This ensures that the semantics of HQL and criteria queries are identical. This ensures that the semantics of HQL and criteria queries are identical.
@ -532,7 +533,7 @@ query.select(book).where(where)
Here, the classes `Book_` and `Author_` are classes generated by Hibernate's {generator}[JPA Metamodel Generator], which is documented in the {generator-guide}[User Guide]. Here, the classes `Book_` and `Author_` are classes generated by Hibernate's {generator}[JPA Metamodel Generator], which is documented in the {generator-guide}[User Guide].
[NOTE] [NOTE]
.Injection attacks and criteria queries // .Injection attacks and criteria queries
==== ====
Notice that we did not bother treating `titlePattern` and `namePattern` as parameters. Notice that we did not bother treating `titlePattern` and `namePattern` as parameters.
That's safe because, _by default_, Hibernate automatically and transparently handles any literal string passed to the `CriteriaBuilder` as a JDBC parameter. That's safe because, _by default_, Hibernate automatically and transparently handles any literal string passed to the `CriteriaBuilder` as a JDBC parameter.

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

@ -130,7 +130,7 @@ class Author { ... }
---- ----
[NOTE] [NOTE]
.Discriminator columns for `TABLE_PER_CLASS` inheritance // .Discriminator columns for `TABLE_PER_CLASS` inheritance
==== ====
Hibernate doesn't allow discriminator columns for `TABLE_PER_CLASS` inheritance mappings, since they would make no sense, and offer no advantage. Hibernate doesn't allow discriminator columns for `TABLE_PER_CLASS` inheritance mappings, since they would make no sense, and offer no advantage.
==== ====
@ -545,7 +545,7 @@ So unless you specifically need to use these JDBC LOB APIs, you _don't_ need the
Instead, as we just saw in <<column-lengths>>, all you need is to specify a large enough column `length` to accommodate the data you plan to write to that column. Instead, as we just saw in <<column-lengths>>, all you need is to specify a large enough column `length` to accommodate the data you plan to write to that column.
[WARNING] [WARNING]
.PostgreSQL `BYTEA` and `TEXT` // .PostgreSQL `BYTEA` and `TEXT`
==== ====
Unfortunately, the driver for PostgreSQL doesn't allow `BYTEA` or `TEXT` columns to be read via the JDBC LOB APIs. Unfortunately, the driver for PostgreSQL doesn't allow `BYTEA` or `TEXT` columns to be read via the JDBC LOB APIs.

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

@ -115,7 +115,7 @@ associated instances of a related entity are fetched using N subsequent
queries. queries.
[IMPORTANT] [IMPORTANT]
.This problem is your responsibility // .This problem is your responsibility
==== ====
This isn't a bug or limitation of Hibernate; this problem even affects typical handwritten JDBC code behind DAOs. This isn't a bug or limitation of Hibernate; this problem even affects typical handwritten JDBC code behind DAOs.
Only you, the developer, can solve this problem, because only you know ahead of time what data you're going to need in a given unit of work. Only you, the developer, can solve this problem, because only you know ahead of time what data you're going to need in a given unit of work.
@ -176,8 +176,9 @@ But that's still not enough.
Hibernate does not itself contain an implementation of a second-level cache, so it's necessary to configure an external _cache provider_. Hibernate does not itself contain an implementation of a second-level cache, so it's necessary to configure an external _cache provider_.
[IMPORTANT] [IMPORTANT]
.Caching is disabled by default // .Caching is disabled by default
==== ====
Caching is disabled by default.
To minimize the risk of data loss, we force you to stop and think before any entity goes into the cache. To minimize the risk of data loss, we force you to stop and think before any entity goes into the cache.
==== ====
@ -245,7 +246,7 @@ This strategy uses "soft" locks to prevent concurrent transactions from retrievi
Which policies make sense may also depend on the underlying second-level cache implementation. Which policies make sense may also depend on the underlying second-level cache implementation.
[NOTE] [NOTE]
.The JPA-defined `@Cacheable` annotation // .The JPA-defined `@Cacheable` annotation
==== ====
JPA has a similar annotation, named `@Cacheable`. JPA has a similar annotation, named `@Cacheable`.
Unfortunately, it's almost useless to us, since: Unfortunately, it's almost useless to us, since:
@ -370,8 +371,9 @@ sf.getCache().evictEntityData(Book.class, bookId);
---- ----
[NOTE] [NOTE]
.Second-level cache management is not transaction-aware // .Second-level cache management is not transaction-aware
==== ====
Second-level cache management is not transaction-aware.
None of the operations of the `Cache` interface respect any isolation or transactional semantics associated with the underlying caches. In particular, eviction via the methods of this interface causes an immediate "hard" removal outside any current transaction and/or locking scheme. None of the operations of the `Cache` interface respect any isolation or transactional semantics associated with the underlying caches. In particular, eviction via the methods of this interface causes an immediate "hard" removal outside any current transaction and/or locking scheme.
==== ====