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

HHH-13165 - Don't use confusing "this" in the User Guide admonition blocks

This commit is contained in:
Vlad Mihalcea 2019-01-10 10:45:53 +02:00
parent a78c56c01f
commit 070c14e149
33 changed files with 214 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
documentation/src/main/asciidoc/userguide/appendices/Legacy_Bootstrap.adoc
View File

@ -7,7 +7,8 @@ I like to think of `Configuration` as a big pot to which we add a bunch of stuff
[NOTE]
====
There are some significant draw backs to this approach which led to its deprecation and the development of the new approach, which is discussed in <<chapters/bootstrap/Bootstrap.adoc#bootstrap-native,Native Bootstrapping>>.
There are some significant drawbacks to the legacy bootstrapping mechanism which led to its deprecation and the development of the new approach, which is discussed in <<chapters/bootstrap/Bootstrap.adoc#bootstrap-native,Native Bootstrapping>>.
`Configuration` is semi-deprecated but still available for use, in a limited form that eliminates these drawbacks.
"Under the covers", `Configuration` uses the new bootstrapping code, so the things available there as also available here in terms of auto-discovery.
====

2
documentation/src/main/asciidoc/userguide/appendices/Legacy_Native_Queries.adoc
View File

@ -267,7 +267,7 @@ The following example shows how to define custom SQL operations using annotation
[NOTE]
====
If you expect to call a store procedure, be sure to set the `callable` attribute to `true`, in annotations as well as in xml.
If you expect to call a stored procedure, be sure to set the `callable` attribute to `true` in both annotation and XML-based mappings.
====
To check that the execution happens correctly, Hibernate allows you to define one of those three strategies:

19
documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc
View File

@ -38,7 +38,7 @@ The following settings control this behavior.
[NOTE]
====
Since version 5.2, Hibernate allows overriding the global JDBC batch size given by the `hibernate.jdbc.batch_size` configuration property for a given `Session`.
Since version 5.2, Hibernate allows overriding the global JDBC batch size given by the `hibernate.jdbc.batch_size` configuration property on a per `Session` basis.
====
[[batch-session-jdbc-batch-size-example]]
@ -73,7 +73,7 @@ There are several problems associated with this example:
. JDBC batching is not enabled by default, so every insert statement requires a database roundtrip.
To enable JDBC batching, set the `hibernate.jdbc.batch_size` property to an integer between 10 and 50.
[NOTE]
[IMPORTANT]
====
Hibernate disables insert batching at the JDBC level transparently if you use an identity identifier generator.
====
@ -175,7 +175,7 @@ DELETE FROM EntityName e WHERE e.name = ?
[NOTE]
====
The `FROM` and `WHERE` clauses are each optional, but it's good practice to use them.
Although the `FROM` and `WHERE` clauses are optional, it is good practice to declare them explicitly.
====
The `FROM` clause can only refer to a single entity, which can be aliased.
@ -220,7 +220,7 @@ include::{sourcedir}/BatchTest.java[tags=batch-bulk-hql-update-version-example]
[NOTE]
====
If you use the `VERSIONED` statement, you cannot use custom version types, which use class `org.hibernate.usertype.UserVersionType`.
If you use the `VERSIONED` statement, you cannot use custom version types that implement the `org.hibernate.usertype.UserVersionType`.
This feature is only available in HQL since it's not standardized by JPA.
====
@ -394,7 +394,7 @@ So, the entity identifiers are selected first and used for each particular updat
[TIP]
====
The IN clause row value expression has long been supported by Oracle, PostgreSQL, and nowadays by MySQL 5.7.
However, SQL Server 2014 does not support this syntax, so you'll have to use a different strategy.
However, SQL Server 2014 does not support it, so you'll have to use a different strategy.
====
[[batch-bulk-hql-strategies-InlineIdsSubSelectValueListBulkIdStrategy]]
@ -422,8 +422,8 @@ include::{extrasdir}/batch-bulk-hql-InlineIdsSubSelectValueListBulkIdStrategy-de
[TIP]
====
The underlying database must support the VALUES list clause, like PostgreSQL or SQL Server 2008.
However, this strategy requires the IN-clause row value expression for composite identifiers so you can use this strategy only with PostgreSQL.
The underlying database must support the `VALUES` list clause, like PostgreSQL or SQL Server 2008.
However, this strategy requires the IN-clause row value expression for composite identifiers, and for this reason, you can only use the `InlineIdsSubSelectValueListBulkIdStrategy` strategy with PostgreSQL.
====
[[batch-bulk-hql-strategies-InlineIdsOrClauseBulkIdStrategy]]
@ -451,7 +451,7 @@ include::{extrasdir}/batch-bulk-hql-InlineIdsOrClauseBulkIdStrategy-delete-query
[TIP]
====
This strategy has the advantage of being supported by all the major relational database systems (e.g. Oracle, SQL Server, MySQL, and PostgreSQL).
The `InlineIdsOrClauseBulkIdStrategy` strategy has the advantage of being supported by all the major relational database systems (e.g. Oracle, SQL Server, MySQL, and PostgreSQL).
====
[[batch-bulk-hql-strategies-CteValuesListBulkIdStrategy]]
@ -479,7 +479,8 @@ include::{extrasdir}/batch-bulk-hql-CteValuesListBulkIdStrategy-delete-query-exa
[TIP]
====
The underlying database must support the CTE (Common Table Expressions) that can be referenced from non-query statements as well, like PostgreSQL since 9.1 or SQL Server since 2005.
The underlying database must support CTE (Common Table Expressions) that can be referenced from non-query statements as well. For instance, PostgreSQL supports this feature since version 9.1 and SQL Server offers support for it since version 2005.
The underlying database must also support the VALUES list clause, like PostgreSQL or SQL Server 2008.
However, this strategy requires the IN-clause row value expression for composite identifiers, so you can only use this strategy only with PostgreSQL.

9
documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc
View File

@ -10,13 +10,6 @@ The term bootstrapping refers to initializing and starting a software component.
In Hibernate, we are specifically talking about the process of building a fully functional `SessionFactory` instance or `EntityManagerFactory` instance, for JPA.
The process is very different for each.
[NOTE]
====
This chapter will not focus on all the possibilities of bootstrapping.
Those will be covered in each specific more-relevant chapters later on.
Instead, we focus here on the API calls needed to perform the bootstrapping.
====
[TIP]
====
During the bootstrap process, you might want to customize Hibernate behavior so make sure you check the <<appendices/Configurations.adoc#configurations,Configurations>> section as well.
@ -47,7 +40,7 @@ This is a very powerful service, but a full discussion of it is beyond the scope
[NOTE]
====
If you are ok with the default behavior of Hibernate in regards to these `BootstrapServiceRegistry` services
(which is quite often the case, especially in stand-alone environments), then building the `BootstrapServiceRegistry` can be skipped.
(which is quite often the case, especially in stand-alone environments), then you don't need to explicitly build the `BootstrapServiceRegistry`.
====
If you wish to alter how the `BootstrapServiceRegistry` is built, that is controlled through the `org.hibernate.boot.registry.BootstrapServiceRegistryBuilder:`

50
documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc
View File

@ -10,8 +10,9 @@ It is possible to configure a JVM-level (`SessionFactory`-level) or even a clust
[NOTE]
====
Be aware that caches are not aware of changes made to the persistent store by other applications.
They can, however, be configured to regularly expire cached data.
Be aware that Hibernate caches are not aware of changes made to the persistent store by other applications.
To address this limitation, you can configure a TTL (Time To Live) retention policy at the second-level cache region level so that the underlying cache entries expire regularly.
====
[[caching-config]]
@ -115,8 +116,9 @@ transactional::
[NOTE]
====
Rather than using a global cache concurrency strategy, it is recommended to define this setting on a per entity basis.
Use the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Cache.html[`@org.hibernate.annotations.Cache`] annotation for that.
Rather than using a global setting, it is recommended to define the cache concurrency strategy on a per entity basis.
Use the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Cache.html[`@org.hibernate.annotations.Cache`] annotation for this purpose.
====
The `@Cache` annotation define three attributes:
@ -147,10 +149,9 @@ ____
[NOTE]
====
As of Hibernate ORM 5.3, it's now possible to possible to override a base class `@Cacheable` or `@Cache` definition in subclasses.
As of Hibernate ORM 5.3, you can now override a base class `@Cacheable` or `@Cache` definition at subclass level.
However, the Hibernate cache concurrency strategy (e.g. read-only, nonstrict-read-write, read-write, transactional) is still defined at the root entity level
and cannot be overridden.
However, the Hibernate cache concurrency strategy (e.g. read-only, nonstrict-read-write, read-write, transactional) is still defined at the root entity level and cannot be overridden.
====
Nevertheless, the reasons why we advise you to have all entities belonging to an inheritance tree share the same caching definition can be summed as follows:
@ -306,10 +307,13 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-native-example
[NOTE]
====
The query cache does not cache the state of the actual entities in the cache;
it caches only identifier values and results of value type.
For entity queries, the query cache does not cache the state of the actual entities. Instead, it stores the entity identifiers, and when the query result is fetched from the cache, the entity state is going to be loaded from the second-level cache entity regions.
Just as with collection caching, the query cache should always be used in conjunction with the second-level cache for those entities expected to be cached as part of a query result cache.
For projection queries, the query cache stores the dehydrated entity state (e.g. `Object[]`) associated with the underlying JDBC `ResultSet`.
====
[[caching-query-region]]
@ -327,7 +331,7 @@ This setting creates two new cache regions:
====
If you configure your underlying cache implementation to use expiration, it's very important
that the timeout of the underlying cache region for the `default-update-timestamps-region`
is set to a higher value than the timeouts of any of the query caches.
is set to a higher value than the timeout setting of any of the query caches.
In fact, we recommend that the `default-update-timestamps-region` region is not configured for expiration (time-based) or eviction (size/memory-based) at all.
Note that an LRU (Least Recently Used) cache eviction policy is never appropriate for this particular cache region.
@ -380,7 +384,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-m
When using https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CacheStoreMode.html#REFRESH[`CacheStoreMode.REFRESH`] or https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/CacheMode.html#REFRESH[`CacheMode.REFRESH`] in conjunction with the region you have defined for the given query,
Hibernate will selectively force the results cached in that particular region to be refreshed.
This is particularly useful in cases where underlying data may have been updated via a separate process
This behavior is particularly useful in cases when the underlying data may have been updated via a separate process
and is a far more efficient alternative to the bulk eviction of the region via `SessionFactory` eviction which looks as follows:
[source, JAVA, indent=0]
@ -508,8 +512,9 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-statistics-example]
[NOTE]
====
Use of the built-in integration for https://jcp.org/en/jsr/detail?id=107[JCache] requires that the `hibernate-jcache` module jar (and all of its dependencies) are on the classpath.
In addition a JCache implementation needs to be added as well.
To use the built-in integration for https://jcp.org/en/jsr/detail?id=107[JCache], you need the `hibernate-jcache` module jar (and all of its dependencies) to be on the classpath.
In addition, a JCache implementation needs to be added as well.
A list of compatible implementations can be found https://jcp.org/aboutJava/communityprocess/implementations/jsr107/index.html[on the JCP website].
An alternative source of compatible implementations can be found through https://github.com/cruftex/jsr107-test-zoo[the JSR-107 test zoo].
====
@ -565,23 +570,21 @@ Only by specifying the second property `hibernate.javax.cache.uri` will you be a
If you don't want to use the default `CacheManager`, you need to set the `hibernate.javax.cache.cache_manager` configuration property
to one of the following values:
Object reference:: If the value is an Object instance implementing the `CacheManager` interface,
Object reference:: If the value is an `Object` instance implementing the `CacheManager` interface,
the provided `CacheManager` instance will be used.
`Class`:: If the value is a Java `Class` object that implements the `CacheManager` interface,
Hibernate will create a new instance for that `Class` and use it instead of the default one.
+
[NOTE]
====
The default no-arg constructor is going to be used, so make sure that the `CacheManager`
implementation class provides it.
When passing a Java `Class` that implements the `CacheManager` interface, you must make sure that the `CacheManager` implementation class provides a default no-arg constructor because that's going to be used to instantiate a `CacheManager` implementation `Object`.
====
`String`:: If the value is a Java `String`, Hibernate expects it to be the fully-qualified `Class` name
of the `CacheManager` implementation which will be used to instantiate the non-default `CacheManager`.
+
[NOTE]
====
The default no-arg constructor is going to be used, so make sure that the `CacheManager`
implementation class provides it.
When passing the fully-qualified class name, you must make sure that the associated `Class` type provides a default no-arg constructor because that's going to be used to instantiate a `CacheManager` implementation `Object`.
====
[[caching-provider-jcache-missing-cache-strategy]]
@ -607,11 +610,9 @@ and also log a warning about the missing cache.
[WARNING]
====
Note that caches created this way may be very badly configured (unlimited size and no eviction in particular)
unless the cache provider was explicitly configured to use a specific configuration for default caches.
Note that caches created this way may not be suitable for production usage (unlimited size and no eviction in particular) unless the cache provider explicitly provides a specific configuration for default caches.
Ehcache, in particular, allows to set such default configuration using cache templates,
see http://www.ehcache.org/documentation/3.0/107.html#supplement-jsr-107-configurations
Ehcache, in particular, allows to set such default configuration using cache templates. See the http://www.ehcache.org/documentation/3.0/107.html#supplement-jsr-107-configurations[Ehcache documentation] for more details.
====
[[caching-provider-ehcache]]
@ -669,7 +670,7 @@ shared among multiple `SessionFactory` instances in the same JVM.
[NOTE]
====
http://www.ehcache.org/documentation/2.8/integrations/hibernate#optional[Ehcache documentation] recommends using multiple non-singleton `CacheManager(s)` when there are multiple Hibernate `SessionFactory` instances running in the same JVM.
The http://www.ehcache.org/documentation/2.8/integrations/hibernate#optional[Ehcache documentation] recommends using multiple non-singleton `CacheManager(s)` when there are multiple Hibernate `SessionFactory` instances running in the same JVM.
====
[[caching-provider-ehcache-missing-cache-strategy]]
@ -695,8 +696,7 @@ and also log a warning about the missing cache.
[WARNING]
====
Note that caches created this way may be very badly configured (large size in particular)
unless an appropriate `<defaultCache>` entry is added to the Ehcache configuration.
Note that caches created this way may be very badly configured (large size in particular) unless an appropriate `<defaultCache>` entry is added to the Ehcache configuration.
====
[[caching-provider-infinispan]]

7
documentation/src/main/asciidoc/userguide/chapters/domain/access.adoc
View File

@ -10,8 +10,9 @@ When placed on the identifier getter, Hibernate will use property-based access.
[IMPORTANT]
====
You should pay attention to https://docs.oracle.com/javase/8/docs/api/java/beans/Introspector.html#decapitalize(java.lang.String)[Java Beans specification] in regard to naming properties to avoid
issues such as https://hibernate.atlassian.net/browse/HCANN-63[Property name beginning with at least two uppercase characters has odd functionality in HQL]!
To avoid issues such as
https://hibernate.atlassian.net/browse/HCANN-63[HCANN-63 - Property name beginning with at least two uppercase characters has odd functionality in HQL], you should pay attention to
https://docs.oracle.com/javase/8/docs/api/java/beans/Introspector.html#decapitalize(java.lang.String)[Java Bean specification] in regard to naming properties.
====
Embeddable types inherit the access strategy from their parent entities.
@ -34,7 +35,9 @@ To exclude a field from being part of the entity persistent state, the field mus
[NOTE]
====
Another advantage of using field-based access is that some entity attributes can be hidden from outside the entity.
An example of such attribute is the entity `@Version` field, which, usually, does not need to be manipulated by the data access layer.
With field-based access, we can simply omit the getter and the setter for this version field, and Hibernate can still leverage the optimistic concurrency control mechanism.
====

15
documentation/src/main/asciidoc/userguide/chapters/domain/associations.adoc
View File

@ -93,7 +93,7 @@ Upon removing a `Phone` from the phones collection, the association row is delet
[NOTE]
====
The unidirectional associations are not very efficient when it comes to removing child entities.
In this particular example, upon flushing the persistence context, Hibernate deletes all database child entries and reinserts the ones that are still found in the in-memory persistence context.
In the example above, upon flushing the persistence context, Hibernate deletes all database rows from the link table (e.g. `Person_Phone`) that are associated with the parent `Person` entity and reinserts the ones that are still found in the `@OneToMany` collection.
On the other hand, a bidirectional `@OneToMany` association is much more efficient because the child entity controls the association.
====
@ -123,6 +123,7 @@ include::{extrasdir}/associations-one-to-many-bidirectional-example.sql[]
[IMPORTANT]
====
Whenever a bidirectional association is formed, the application developer must make sure both sides are in-sync at all times.
The `addPhone()` and `removePhone()` are utility methods that synchronize both ends whenever a child element is added or removed.
====
@ -392,8 +393,9 @@ Because this mapping is formed out of two bidirectional associations, the helper
[NOTE]
====
The aforementioned example uses a Hibernate specific mapping for the link entity since JPA doesn't allow building a composite identifier out of multiple `@ManyToOne` associations.
For more details, see the <<chapters/domain/identifiers.adoc#identifiers-composite-associations,Composite identifiers - associations>> section.
The aforementioned example uses a Hibernate-specific mapping for the link entity since JPA doesn't allow building a composite identifier out of multiple `@ManyToOne` associations.
For more details, see the <<chapters/domain/identifiers.adoc#identifiers-composite-associations,composite identifiers with associations>> section.
====
The entity state transitions are better managed than in the previous bidirectional `@ManyToMany` case.
@ -427,8 +429,7 @@ To ignore non-existing parent entity references, even though not really recommen
[NOTE]
====
`@ManyToOne` and `@OneToOne` associations annotated with `@NotFound(action = NotFoundAction.IGNORE)` are always fetched eagerly
even if you set the `fetch` attribute to `FetchType.LAZY`.
The `@ManyToOne` and `@OneToOne` associations that are annotated with `@NotFound(action = NotFoundAction.IGNORE)` are always fetched eagerly even if the `fetch` strategy is set to `FetchType.LAZY`.
====
Considering the following `City` and `Person` entity mappings:
@ -497,7 +498,6 @@ a metadata information for the associated entity type.
[NOTE]
====
It is impossible to specify a foreign key constraint for this kind of association.
This is not the usual way of mapping polymorphic associations and you should use this only in special cases (e.g. audit logs, user session data, etc).
====
@ -556,8 +556,7 @@ include::{sourcedir}/any/package-info.java[tags=associations-any-meta-def-exampl
[NOTE]
====
Although the `@AnyMetaDef` mapping could be set right next to the `@Any` annotation,
if you need to reuse it, it's good practice to configure it at the class or package level.
Although the `@AnyMetaDef` mapping could be set right next to the `@Any` annotation, it is good practice to configure it at the class or package level, especially if you need to reuse it for multiple `@Any` mappings.
====
To see the `@Any` annotation in action, consider the next examples.

59
documentation/src/main/asciidoc/userguide/chapters/domain/basic_types.adoc
View File

@ -90,8 +90,9 @@ Internally Hibernate uses a registry of basic types when it needs to resolve a s
[NOTE]
====
To use these hibernate-spatial types, you must add the `hibernate-spatial` dependency to your classpath _and_ use a `org.hibernate.spatial.SpatialDialect` implementation.
See <<spatial>> for more details about spatial types.
To use the Hibernate Spatial types, you must add the `hibernate-spatial` dependency to your classpath _and_ use a `org.hibernate.spatial.SpatialDialect` implementation.
See the <<chapters/query/spatial/Spatial.adoc#spatial,Spatial>> chapter for more details.
====
These mappings are managed by a service inside Hibernate called the `org.hibernate.type.BasicTypeRegistry`, which essentially maintains a map of `org.hibernate.type.BasicType` (a `org.hibernate.type.Type` specialization) instances keyed by a name.
@ -142,7 +143,8 @@ The JPA specification strictly limits the Java types that can be marked as basic
* any other type that implements `Serializable` (JPA's "support" for `Serializable` types is to directly serialize their state to the database).
If provider portability is a concern, you should stick to just these basic types.
Note that JPA 2.1 did add the notion of a `javax.persistence.AttributeConverter` to help alleviate some of these concerns; see <<basic-jpa-convert>> for more on this topic.
Note that JPA 2.1 introduced the `javax.persistence.AttributeConverter` contract to help alleviate some of these concerns. See <<basic-jpa-convert>> for more on this topic.
====
The `@Basic` annotation defines 2 attributes.
@ -192,8 +194,9 @@ But first, let's explore how implicit resolution works and how applications can
[NOTE]
====
A thorough discussion of the `BasicTypeRegistry` and all the different ways to contribute types to it is beyond the scope of this documentation.
Please see Integrations Guide for complete details.
A thorough discussion of `BasicTypeRegistry` and all the different ways to contribute types is beyond the scope of this documentation.
Please see the http://docs.jboss.org/hibernate/orm/{majorMinorVersion}/integrationguide/html_single/Hibernate_Integration_Guide.html[Integration Guide] for complete details.
====
As an example, take a String attribute such as we saw before with Product#sku.
@ -256,8 +259,7 @@ The first approach is to directly implement the `BasicType` interface.
[NOTE]
====
Because the `BasicType` interface has a lot of methods to implement, it's much more convenient to extend the `AbstractStandardBasicType`,
or the `AbstractSingleColumnStandardBasicType` if the value is stored in a single database column.
Because the `BasicType` interface has a lot of methods to implement, if the value is stored in a single database column, it's much more convenient to extend the `AbstractStandardBasicType` or the `AbstractSingleColumnStandardBasicType` Hibernate classes.
====
First, we need to extend the `AbstractSingleColumnStandardBasicType` like this:
@ -397,7 +399,7 @@ include::{sourcedir}/../bootstrap/BootstrapTest.java[tags=basic-custom-type-regi
====
Like `BasicType`, you can also register the `UserType` using a simple name.
Without registration, the `UserType` mapping requires the fully-classified name:
Without registering a name, the `UserType` mapping requires the fully-classified name:
[source, JAVA, indent=0]
----
@ -533,8 +535,9 @@ For additional details on using AttributeConverters, see <<basic-jpa-convert>> s
[NOTE]
====
JPA explicitly disallows the use of an AttributeConverter with an attribute marked as `@Enumerated`.
So if using the AttributeConverter approach, be sure not to mark the attribute as `@Enumerated`.
JPA explicitly disallows the use of an `AttributeConverter` with an attribute marked as `@Enumerated`.
So, when using the `AttributeConverter` approach, be sure not to mark the attribute as `@Enumerated`.
====
[[basic-attribute-converter-query-parameter]]
@ -764,8 +767,7 @@ include::{sourcedir}/basic/ClobStringTest.java[tags=basic-clob-string-example]
====
How JDBC deals with `LOB` data varies from driver to driver, and Hibernate tries to handle all these variances on your behalf.
However, some drivers are trickier (e.g. PostgreSQL), and, in such cases, you may have to do some extra to get LOBs working.
Such discussions are beyond the scope of this guide.
However, some drivers are trickier (e.g. PostgreSQL), and, in such cases, you may have to do some extra steps to get LOBs working. Such discussions are beyond the scope of this guide.
====
We might even want the materialized data as a char array (although this might not be a very good idea).
@ -940,7 +942,8 @@ include::{sourcedir}/basic/NClobCharArrayTest.java[tags=basic-nclob-char-array-e
[NOTE]
====
If you application and database are entirely nationalized you may instead want to enable nationalized character data as the default.
If your application and database use nationalization, you may instead want to enable nationalized character data as the default.
You can do this via the `hibernate.use_nationalized_character_data` setting or by calling `MetadataBuilder#enableGlobalNationalizedCharacterDataSupport` during bootstrap.
====
@ -951,8 +954,9 @@ Hibernate also allows you to map UUID values, again in a number of ways.
[NOTE]
====
The default UUID mapping is as binary because it represents more efficient storage.
However, many applications prefer the readability of character storage.
The default UUID mapping is the binary one because it uses a more efficient column storage.
However, many applications prefer the readability of the character-based column storage.
To switch the default mapping, simply call `MetadataBuilder.applyBasicType( UUIDCharType.INSTANCE, UUID.class.getName() )`.
====
@ -971,10 +975,10 @@ Maps the UUID to a String using `java.util.UUID#toString` and `java.util.UUID#fr
[IMPORTANT]
====
When using one of the PostgreSQL Dialects, this becomes the default UUID mapping.
When using one of the PostgreSQL Dialects, the PostgreSQL-specific UUID Hibernate type becomes the default UUID mapping.
====
Maps the UUID using PostgreSQL's specific UUID data type.
Maps the UUID using the PostgreSQL-specific UUID data type.
The PostgreSQL JDBC driver chooses to map its UUID type to the `OTHER` code.
Note that this can cause difficulty as the driver chooses to map many different data types to `OTHER`.
@ -995,7 +999,7 @@ TIMESTAMP:: It stores both a DATE and a TIME plus nanoseconds. The JDBC equivale
[NOTE]
====
To avoid dependencies on the `java.sql` package, it's common to use the `java.util` or `java.time` Date/Time classes instead.
To avoid dependencies on the `java.sql` package, it's common to use the `java.util` or `java.time` Date/Time classes instead of the `java.sql.Timestamp` and `java.sql.Time` ones.
====
While the `java.sql` classes define a direct association to the SQL Date/Time data types,
@ -1077,7 +1081,8 @@ include::{extrasdir}/basic/basic-datetime-temporal-timestamp-persist-example.sql
[NOTE]
====
Just like the `java.util.Date`, the `java.util.Calendar` requires the `@Temporal` annotation in order to know what JDBC data type to be chosen: DATE, TIME or TIMESTAMP.
Just like the `java.util.Date`, the `java.util.Calendar` requires the `@Temporal` annotation in order to know what JDBC data type to be chosen: `DATE`, `TIME` or `TIMESTAMP`.
If the `java.util.Date` marks a point in time, the `java.util.Calendar` takes into consideration the default Time Zone.
====
@ -1094,7 +1099,8 @@ TIMESTAMP:: `java.time.Instant`, `java.time.LocalDateTime`, `java.time.OffsetDat
[IMPORTANT]
====
Because the mapping between Java 8 Date/Time classes and the SQL types is implicit, there is not need to specify the `@Temporal` annotation.
Because the mapping between the Java 8 Date/Time classes and the SQL types is implicit, there is not need to specify the `@Temporal` annotation.
Setting it on the `java.time` classes throws the following exception:
----
@ -1258,7 +1264,7 @@ include::{sourcedir}/converter/MoneyConverterTest.java[tags=basic-jpa-convert-mo
[TIP]
====
Although the `AttributeConverter` types can be mutable so that dirty checking, deep copying and second-level caching work properly,
Although the `AttributeConverter` types can be mutable so that dirty checking, deep copying, and second-level caching work properly,
treating these as immutable (when they really are) is more efficient.
For this reason, prefer immutable types over mutable ones whenever possible.
@ -1640,12 +1646,7 @@ include::{sourcedir}/../fetching/FetchingTest.java[tags=mapping-column-read-and-
----
====
[NOTE]
====
You can use the plural form `@ColumnTransformers` if more than one columns need to define either of these rules.
====
If a property uses more than one column, you must use the `forColumn` attribute to specify which column, the expressions are targeting.
If a property uses more than one column, you must use the `forColumn` attribute to specify which column, the `@ColumnTransformer` read and write expressions are targeting.
[[mapping-column-read-and-write-composite-type-example]]
.`@ColumnTransformer` `forColumn` attribute usage
@ -1686,7 +1687,7 @@ You can use a SQL fragment (aka formula) instead of mapping a property into a co
[NOTE]
====
You should be aware that the `@Formula` annotation takes a native SQL clause which can affect database portability.
You should be aware that the `@Formula` annotation takes a native SQL clause which may affect database portability.
====
[[mapping-column-formula-example]]
@ -1716,5 +1717,5 @@ include::{extrasdir}/basic/mapping-column-formula-persistence-example.sql[]
[NOTE]
====
The SQL fragment can be as complex as you want and even include subselects.
The SQL fragment defined by the `@Formula` annotation can be as complex as you want, and it can even include subselects.
====

13
documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc
View File

@ -37,6 +37,7 @@ include::{sourcedir}/BasicTypeElementCollectionTest.java[tags=collections-collec
[NOTE]
====
It is important that collections be defined using the appropriate Java Collections Framework interface rather than a specific implementation.
From a theoretical perspective, this just follows good design principles.
From a practical perspective, Hibernate (like other persistence providers) will use their own collection implementations which conform to the Java Collections Framework interfaces.
====
@ -195,7 +196,8 @@ include::{extrasdir}/collections-unidirectional-bag-example.sql[]
[NOTE]
====
Because both the parent and the child sides are entities, the persistence context manages each entity separately.
Cascades can propagate an entity state transition from a parent entity to its children.
The cascading mechanism allows you to propagate an entity state transition from a parent entity to its children.
====
By marking the parent side with the `CascadeType.ALL` attribute, the unidirectional association lifecycle becomes very similar to that of a value type collection.
@ -219,7 +221,8 @@ In the example above, once the parent entity is persisted, the child entities ar
[NOTE]
====
Just like value type collections, unidirectional bags are not as efficient when it comes to modifying the collection structure (removing or reshuffling elements).
Because the parent-side cannot uniquely identify each individual child, Hibernate might delete all child table rows associated with the parent entity and re-add them according to the current collection state.
Because the parent-side cannot uniquely identify each individual child, Hibernate deletes all link table rows associated with the parent entity and re-adds the remaining ones that are found in the current collection state.
====
[[collections-bidirectional-bag]]
@ -470,7 +473,8 @@ The only difference is that `Set` doesn't allow duplicates, but this constraint
[NOTE]
====
When using sets, it's very important to supply proper equals/hashCode implementations for child entities.
When using Sets, it's very important to supply proper equals/hashCode implementations for child entities.
In the absence of a custom equals/hashCode implementation logic, Hibernate will use the default Java reference-based object equality which might render unexpected results when mixing detached and managed object instances.
====
@ -605,8 +609,7 @@ The `call_timestamp_epoch` column stores the phone call timestamp as a Unix time
[NOTE]
====
The `@MapKeyColumn` annotation is used to define the table column holding the key
while the `@Column` mapping gives the value of the `java.util.Map` in question.
The `@MapKeyColumn` annotation is used to define the table column holding the key while the `@Column` mapping gives the value of the `java.util.Map` in question.
====
Since we want to map all the calls by their associated `java.util.Date`, not by their timestamp since epoch which is a number, the entity mapping looks as follows:

2
documentation/src/main/asciidoc/userguide/chapters/domain/dynamic_model.adoc
View File

@ -7,7 +7,7 @@
[IMPORTANT]
====
JPA only acknowledges the entity model mapping so, if you are concerned about JPA provider portability, it's best to stick to the strict POJO model.
On the other hand, Hibernate can work with both POJO entities as well as with dynamic entity models.
On the other hand, Hibernate can work with both POJO entities and dynamic entity models.
====
[[mapping-model-dynamic]]

4
documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc
View File

@ -55,7 +55,7 @@ JPA defines two terms for working with an embeddable type: `@Embeddable` and `@E
`@Embeddable` is used to describe the mapping type itself (e.g. `Publisher`).
`@Embedded` is for referencing a given embeddable type (e.g. `book#publisher`).
`@Embedded` is for referencing a given embeddable type (e.g. `book.publisher`).
====
So, the embeddable type is represented by the `Publisher` class and
@ -140,7 +140,7 @@ include::{extrasdir}/embeddable/embeddable-type-override-mapping-example.sql[]
[IMPORTANT]
====
This is a Hibernate specific feature.
The `ImplicitNamingStrategyComponentPathImpl` is a Hibernate-specific feature.
Users concerned with JPA provider portability should instead prefer explicit column naming with `@AttributeOverride`.
====

9
documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc
View File

@ -54,7 +54,7 @@ For the very same reason, you should also avoid declaring persistent attribute g
[NOTE]
====
Starting in 5.0 Hibernate offers a more robust version of bytecode enhancement as another means for handling lazy loading.
Starting with 5.0, Hibernate offers a more robust version of bytecode enhancement as another means for handling lazy loading.
Hibernate had some bytecode re-writing capabilities prior to 5.0 but they were very rudimentary.
See the <<chapters/pc/BytecodeEnhancement.adoc#BytecodeEnhancement,BytecodeEnhancement>> for additional information on fetching and on bytecode enhancement.
====
@ -85,8 +85,9 @@ Again, if wanting to use runtime proxy generation for lazy loading, the getter/s
[IMPORTANT]
====
Historically this was considered optional.
However, not defining identifier attribute(s) on the entity should be considered a deprecated feature that will be removed in an upcoming release.
Historically, providing identifier attributes was considered optional.
However, not defining identifier attributes on the entity should be considered a deprecated feature that will be removed in an upcoming release.
====
The identifier attribute does not necessarily need to be mapped to the column(s) that physically define the primary key.
@ -94,7 +95,7 @@ However, it should map to column(s) that can uniquely identify each row.
[NOTE]
====
We recommend that you declare consistently-named identifier attributes on persistent classes and that you use a nullable (i.e., non-primitive) type.
We recommend that you declare consistently-named identifier attributes on persistent classes and that you use a wrapper (i.e., non-primitive) type (e.g. `Long` or `Integer`).
====
The placement of the `@Id` annotation marks the <<chapters/domain/access.adoc#access,persistence state access strategy>>.

35
documentation/src/main/asciidoc/userguide/chapters/domain/identifiers.adoc
View File

@ -95,8 +95,9 @@ or defined using the `javax.persistence.IdClass` annotation (see <<identifiers-c
[NOTE]
====
The restriction that a composite identifier has to be represented by a "primary key class" is only JPA specific.
Hibernate does allow composite identifiers to be defined without a "primary key class", although that modeling technique is deprecated and therefore omitted from this discussion.
The restriction that a composite identifier has to be represented by a "primary key class" (e.g. `@EmbeddedId` or `@IdClass`) is only JPA-specific.
Hibernate does allow composite identifiers to be defined without a "primary key class" via multiple `@Id` attributes.
====
The attributes making up the composition can be either basic, composite, `@ManyToOne`.
@ -130,10 +131,10 @@ include::{sourcedir}/EmbeddedIdManyToOneTest.java[tag=identifiers-basic-embedded
[NOTE]
====
Hibernate supports directly modeling the ManyToOne in the PK class, whether `@EmbeddedId` or `@IdClass`.
Hibernate supports directly modeling `@ManyToOne` associations in the Primary Key class, whether `@EmbeddedId` or `@IdClass`.
However, that is not portably supported by the JPA specification.
In JPA terms one would use "derived identifiers"; for details, see <<identifiers-derived>>.
In JPA terms, one would use "derived identifiers". For more details, see <<identifiers-derived>>.
====
[[identifiers-composite-nonaggregated]]
@ -175,7 +176,7 @@ include::{sourcedir}/IdClassGeneratedValueTest.java[tag=identifiers-basic-idclas
[NOTE]
====
This feature exists because of a highly questionable interpretation of the JPA specification made by the SpecJ committee.
This feature which allows auto-generated values in composite identifiers exists because of a highly questionable interpretation of the JPA specification made by the SpecJ committee.
Hibernate does not feel that JPA defines support for this, but added the feature simply to be usable in SpecJ benchmarks.
Use of this feature may or may not be portable from a JPA perspective.
@ -276,7 +277,7 @@ and we assigned it to the composite identifier prior to persisting the `Event` e
[NOTE]
====
For discussion of generated values for non-identifier attributes, see <<chapters/domain/basic_types.adoc#mapping-generated,Generated properties>>.
You can also auto-generate values for non-identifier attributes. For more details, see the <<chapters/domain/basic_types.adoc#mapping-generated,Generated properties>> section.
====
Hibernate supports identifier value generation across a number of different types.
@ -289,9 +290,10 @@ The most important piece of information here is the specified `javax.persistence
====
The discussions below assume that the application is using Hibernate's "new generator mappings" as indicated by the `hibernate.id.new_generator_mappings` setting or
`MetadataBuilder.enableNewIdentifierGeneratorSupport` method during bootstrap.
Starting with Hibernate 5, this is set to true by default.
If applications set this to false the resolutions discussed here will be very different.
The rest of the discussion here assumes this setting is enabled (true).
Starting with Hibernate 5, this is set to `true` by default.
In applications where the `hibernate.id.new_generator_mappings` configuration is set to `false` the resolutions discussed here will be very different.
The rest of the discussion here assumes this setting is enabled (`true`).
====
[IMPORTANT]
@ -394,16 +396,18 @@ IdentityGenerator understands 3 different ways that the INSERT-generated value m
[IMPORTANT]
====
It is important to realize that this imposes a runtime behavior where the entity row *must* be physically inserted prior to the identifier value being known.
This can mess up extended persistence contexts (conversations).
Because of the runtime imposition/inconsistency, Hibernate suggests other forms of identifier value generation be used.
It is important to realize that using IDENTITY columns imposes a runtime behavior where the entity row *must* be physically inserted prior to the identifier value being known.
This can mess up extended persistence contexts (long conversations).
Because of the runtime imposition/inconsistency, Hibernate suggests other forms of identifier value generation be used (e.g. SEQUENCE).
====
[NOTE]
====
There is yet another important runtime impact of choosing IDENTITY generation: Hibernate will not be able to JDBC batching for inserts of the entities that use IDENTITY generation.
There is yet another important runtime impact of choosing IDENTITY generation: Hibernate will not be able to batch INSERT statements for the entities using the IDENTITY generation.
The importance of this depends on the application-specific use cases.
If the application is not usually creating many new instances of a given type of entity that uses IDENTITY generation, then this is not an important impact since batching would not have been helpful anyway.
If the application is not usually creating many new instances of a given entity type using the IDENTITY generator, then this limitation will be less important since batching would not have been very helpful anyway.
====
[[identifiers-generators-table]]
@ -609,8 +613,7 @@ include::{sourcedir-associations}/OneToOnePrimaryKeyJoinColumnTest.java[tag=iden
[NOTE]
====
Unlike `@MapsId`, the application developer is responsible for ensuring that the identifier and the many-to-one (or one-to-one) association are in sync
as you can see in the `PersonDetails#setPerson` method.
Unlike `@MapsId`, the application developer is responsible for ensuring that the entity identifier and the many-to-one (or one-to-one) association are in sync, as you can see in the `PersonDetails#setPerson` method.
====
[[identifiers-rowid]]

2
documentation/src/main/asciidoc/userguide/chapters/domain/immutability.adoc
View File

@ -107,5 +107,5 @@ include::{extrasdir}/collection-immutability-update-example.log.txt[]
[TIP]
====
While immutable entity changes are simply discarded, modifying an immutable collection end up in a `HibernateException` being thrown.
While immutable entity changes are simply discarded, modifying an immutable collection will end up in a `HibernateException` being thrown.
====

16
documentation/src/main/asciidoc/userguide/chapters/domain/inheritance.adoc
View File

@ -36,7 +36,7 @@ include::{extrasdir}/entity-inheritance-mapped-superclass-example.sql[]
[NOTE]
====
Because the `@MappedSuperclass` inheritance model is not mirrored at the database level,
it's not possible to use polymorphic queries (fetching subclasses by their base class).
it's not possible to use polymorphic queries referencing the `@MappedSuperclass` when fetching persistent objects by their base class.
====
[[entity-inheritance-single-table]]
@ -119,20 +119,20 @@ You can also use `@DiscriminatorFormula` to express in SQL a virtual discriminat
This is particularly useful when the discriminator value can be extracted from one or more columns of the table.
Both `@DiscriminatorColumn` and `@DiscriminatorFormula` are to be set on the root entity (once per persisted hierarchy).
`@org.hibernate.annotations.DiscriminatorOptions` allows to optionally specify Hibernate specific discriminator options which are not standardized in JPA.
`@org.hibernate.annotations.DiscriminatorOptions` allows to optionally specify Hibernate-specific discriminator options which are not standardized in JPA.
The available options are `force` and `insert`.
The `force` attribute is useful if the table contains rows with _extra_ discriminator values that are not mapped to a persistent class.
This could, for example, occur when working with a legacy database.
If `force` is set to true Hibernate will specify the allowed discriminator values in the SELECT query, even when retrieving all instances of the root class.
If `force` is set to `true`, Hibernate will specify the allowed discriminator values in the SELECT query even when retrieving all instances of the root class.
The second option, `insert`, tells Hibernate whether or not to include the discriminator column in SQL INSERTs.
Usually, the column should be part of the INSERT statement, but if your discriminator column is also part of a mapped composite identifier you have to set this option to false.
Usually, the column should be part of the INSERT statement, but if your discriminator column is also part of a mapped composite identifier you have to set this option to `false`.
====
[IMPORTANT]
====
There used to be `@org.hibernate.annotations.ForceDiscriminator` annotation which was deprecated in version 3.6 and later removed. Use `@DiscriminatorOptions` instead.
There used to be a `@org.hibernate.annotations.ForceDiscriminator` annotation which was deprecated in version 3.6 and later removed. Use `@DiscriminatorOptions` instead.
====
[[entity-inheritance-discriminator-formula]]
@ -226,7 +226,7 @@ include::{extrasdir}/entity-inheritance-joined-table-example.sql[]
[NOTE]
====
The primary key of this table is also a foreign key to the superclass table and described by the `@PrimaryKeyJoinColumns`.
The primary keys of the `CreditAccount` and `DebitAccount` tables are also foreign keys to the superclass table primary key and described by the `@PrimaryKeyJoinColumns`.
The table name still defaults to the non-qualified class name.
Also, if `@PrimaryKeyJoinColumn` is not set, the primary key / foreign key columns are assumed to have the same names as the primary key columns of the primary table of the superclass.
@ -311,7 +311,9 @@ include::{extrasdir}/entity-inheritance-table-per-class-query-example.sql[]
====
Polymorphic queries require multiple UNION queries, so be aware of the performance implications of a large class hierarchy.
Unfortunatelly, not all database systems support UNION ALL, so if your current Hibernate dialect does not extend any of these dialects, then UNION is going to be used instead of UNION ALL.
Unfortunately, not all database systems support UNION ALL, in which case, UNION is going to be used instead of UNION ALL.
The following Hibernate dialects support UNION ALL:
- `AbstractHANADialect`
- `AbstractTransactSQLDialect`

7
documentation/src/main/asciidoc/userguide/chapters/domain/naming.adoc
View File

@ -93,10 +93,11 @@ would be, for example, to say that the physical column name should instead be ab
[NOTE]
====
It is true that the resolution to `acct_num` could have been handled in an ImplicitNamingStrategy in this case.
But the point is separation of concerns. The PhysicalNamingStrategy will be applied regardless of whether
It is true that the resolution to `acct_num` could have been handled using an `ImplicitNamingStrategy` in this case.
But the point here is the separation of concerns. The `PhysicalNamingStrategy` will be applied regardless of whether
the attribute explicitly specified the column name or whether we determined that implicitly. The
ImplicitNamingStrategy would only be applied if an explicit name was not given. So it depends on needs
`ImplicitNamingStrategy` would only be applied if an explicit name was not given. So, it all depends on needs
and intent.
====

2
documentation/src/main/asciidoc/userguide/chapters/domain/natural_id.adoc
View File

@ -135,7 +135,7 @@ To be clear: this is only pertinent for mutable natural ids.
[IMPORTANT]
====
This _discovery and adjustment_ have a performance impact.
If an application is certain that none of its mutable natural ids already associated with the Session have changed, it can disable that checking by calling `setSynchronizationEnabled(false)` (the default is true).
If you are certain that none of the mutable natural ids already associated with the current `Session` have changed, you can disable this checking by calling `setSynchronizationEnabled(false)` (the default is `true`).
This will force Hibernate to circumvent the checking of mutable natural ids.
====

4
documentation/src/main/asciidoc/userguide/chapters/domain/types.adoc
View File

@ -12,9 +12,9 @@ This Hibernate type also describes various behavioral aspects of the Java type s
[NOTE]
====
The Hibernate type is neither a Java type nor a SQL data type.
It provides information about both of these as well as understanding marshalling between.
It provides information about mapping a Java type to an SQL type as well as how to persist and fetch a given Java type to and from a relational database.
When you encounter the term type in discussions of Hibernate, it may refer to the Java type, the JDBC type, or the Hibernate type, depending on context.
When you encounter the term type in discussions of Hibernate, it may refer to the Java type, the JDBC type, or the Hibernate type, depending on the context.
====
To help understand the type categorizations, let's look at a simple table and domain model that we wish to map.

21
documentation/src/main/asciidoc/userguide/chapters/envers/Envers.adoc
View File

@ -23,8 +23,8 @@ You can create, modify and delete the entities as always.
[IMPORTANT]
====
The use of JPA's `CriteriaUpdate` and `CriteriaDelete` bulk operations are not currently supported by Envers
due to how an entity's lifecycle events are dispatched. Such operations should be avoided as they're not
captured by Envers and leads to incomplete audit history.
due to how an entity's lifecycle events are dispatched. Such operations should be avoided as they're not
captured by Envers and lead to incomplete audit history.
====
If you look at the generated schema for your entities, or at the data persisted by Hibernate, you will notice that there are no changes.
@ -300,8 +300,7 @@ Specifies the composite-id key property name used by the audit table mappings.
[IMPORTANT]
====
The following configuration options have been added recently and should
be regarded as experimental:
The following configuration options have been added recently and should be regarded as experimental:
. `org.hibernate.envers.track_entities_changed_in_revision`
. `org.hibernate.envers.using_modified_flag`
@ -336,7 +335,7 @@ you can set the `@AuditOverride( forClass = SomeEntity.class, isAudited = true/f
[NOTE]
====
The `@Audited` annotation also features an `auditParents` attribute but it's now deprecated in favor of `@AuditOverride`,
The `@Audited` annotation also features an `auditParents` attribute but it's now deprecated in favor of `@AuditOverride`.
====
[[envers-audit-strategy]]
@ -419,7 +418,7 @@ include::{extrasdir}/envers-audited-validity-rev1-example.sql[]
[NOTE]
====
Compared to the default strategy, the `ValidityAuditStrategy` generates simpler queries that can render better execution plans.
Compared to the default strategy, the `ValidityAuditStrategy` generates simpler queries that can render better SQL execution plans.
====
[[envers-revisionlog]]
@ -527,7 +526,7 @@ As demonstrated by the example above, the username is properly set and propagate
[WARNING]
====
**This strategy is deprecated since version 5.2. The alternative is to use dependency injection offered as of version 5.3.**
**This strategy is deprecated since version 5.2. The alternative is to use dependency injection offered as of version 5.3.**
An alternative method to using the `org.hibernate.envers.RevisionListener` is to instead call the
[line-through]#https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/envers/AuditReader.html#getCurrentRevision-java.lang.Class-boolean-[`getCurrentRevision( Class<T> revisionEntityClass, boolean persist )`]#
@ -545,7 +544,7 @@ The method accepts a `persist` parameter indicating whether the revision entity
As of Hibernate Envers 5.3, dependency injection is now supported for a `RevisionListener`.
This feature is up to the various dependency frameworks, such as CDI and Spring, to supply the
necessary implementation during Hibernate ORM bootstrap to support injection. If no qualifying
necessary implementation during Hibernate ORM bootstrap to support injection. If no qualifying
implementation is supplied, the `RevisionListener` will be constructed without injection.
====
@ -732,7 +731,7 @@ The queries on the audited data will be in many cases much slower than correspon
as, especially for the default audit strategy, they involve correlated subselects.
Queries are improved both in terms of speed and possibilities when using the validity audit strategy,
which stores both start and end revisions for entities. See <<envers-audit-ValidityAuditStrategy>>.
which stores both start and end revisions for entities. See <<envers-audit-ValidityAuditStrategy>> for a more detailed discussion.
====
[[entities-at-revision]]
@ -1248,7 +1247,7 @@ To use customized Envers event listeners, the following steps are needed:
[NOTE]
====
The use of `hibernate.listeners.envers.autoRegister` has been deprecated.
A new configuration setting `hibernate.envers.autoRegisterListeners` should be used instead.
The new `hibernate.envers.autoRegisterListeners` configuration setting should be used instead.
====
[[envers-schema]]
@ -1285,7 +1284,7 @@ The name of this table can be configured, the name of its columns as well as add
[NOTE]
====
While global revisions are a good way to provide correct auditing of relations, some people have pointed out that this may be a bottleneck in systems, where data is very often modified.
While global revisions are a good way to provide correct auditing of relations, some people have pointed out that this may be a bottleneck in systems where data is very often modified.
One viable solution is to introduce an option to have an entity "locally revisioned", that is revisions would be created for it independently.
This would not enable correct versioning of relations, but it would work without the `REVINFO` table.

4
documentation/src/main/asciidoc/userguide/chapters/events/Events.adoc
View File

@ -25,7 +25,7 @@ include::{sourcedir}/InterceptorTest.java[tags=events-interceptors-example]
[NOTE]
====
You can either implement `Interceptor` directly or extend `org.hibernate.EmptyInterceptor`.
You can either implement `Interceptor` directly or extend the `org.hibernate.EmptyInterceptor` base class.
====
An Interceptor can be either `Session`-scoped or `SessionFactory`-scoped.
@ -68,7 +68,7 @@ be responsible for processing the `load()` requests made of the `Session`.
[NOTE]
====
The listeners should be considered stateless; they are shared between requests, and should not save any state as instance variables.
The listeners should be considered stateless. They are shared between requests, and should not save any state as instance variables.
====
A custom listener implements the appropriate interface for the event it wants to process and/or extend one of the convenience base classes

14
documentation/src/main/asciidoc/userguide/chapters/fetching/Fetching.adoc
View File

@ -20,7 +20,7 @@ The concept of fetching breaks down into two different questions.
[NOTE]
====
"now" is generally termed eager or immediate. "later" is generally termed lazy or delayed.
"Now" is generally termed eager or immediate while "later" is generally termed lazy or delayed.
====
There are a number of scopes for defining fetching:
@ -122,8 +122,10 @@ include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-domain-model-exa
[IMPORTANT]
====
The Hibernate recommendation is to statically mark all associations lazy and to use dynamic fetching strategies for eagerness.
This is unfortunately at odds with the JPA specification which defines that all one-to-one and many-to-one associations should be eagerly fetched by default.
The Hibernate recommendation is to statically mark all associations lazy and to use dynamic fetching strategies for eagerness.
This is unfortunately at odds with the JPA specification which defines that all one-to-one and many-to-one associations should be eagerly fetched by default.
Hibernate, as a JPA provider, honors that default.
====
@ -281,8 +283,8 @@ list of attribute names, optionally including any sub-graph specifications.
[NOTE]
====
Parsing a textual representation of a graph is not (yet) a part of the JPA specification. So the
syntax described here is specific to Hibernate. We do hope to eventually make this syntax part of
Parsing a textual representation of a graph is not (yet) a part of the JPA specification. So the
syntax described here is specific to Hibernate. We do hope to eventually make this syntax part of
the JPA specification proper.
====
@ -645,5 +647,5 @@ include::{extrasdir}/fetching-LazyCollection-select-example.sql[]
====
Therefore, the child entities were fetched one after the other without triggering a full collection initialization.
For this reason, caution is advised because `LazyCollectionOption.EXTRA` lazy collections are prone to N+1 query issues.
For this reason, caution is advised since accessing all elements using `LazyCollectionOption.EXTRA` can lead to N+1 query issues.
====

4
documentation/src/main/asciidoc/userguide/chapters/flushing/Flushing.adoc
View File

@ -58,7 +58,7 @@ Hibernate logs the message prior to inserting the entity because the flush only
====
This is valid for the `SEQUENCE` and `TABLE` identifier generators.
The `IDENTITY` generator must execute the insert right after calling `persist()`.
For details, see the discussion of generators in <<chapters/domain/identifiers.adoc#identifiers,_Identifier generators_>>.
For more details, see the discussion of generators in <<chapters/domain/identifiers.adoc#identifiers,_Identifier generators_>>.
====
==== `AUTO` flush on JPQL/HQL query
@ -234,7 +234,7 @@ The `INSERT` statement was not executed because the persistence context because
[NOTE]
====
This mode is useful when using multi-request logical transactions, and only the last request should flush the persistence context.
The `MANUAL` flush mode is useful when using multi-request logical transactions, and only the last request should flush the persistence context.
====
[[flushing-order]]

12
documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc
View File

@ -44,7 +44,7 @@ Otherwise, the no-arg form is used.
[IMPORTANT]
====
To use this integration, the application must include the hibernate-c3p0 module jar (as well as its dependencies) on the classpath.
To use the c3p0 integration, the application must include the `hibernate-c3p0` module jar (as well as its dependencies) on the classpath.
====
Hibernate also provides support for applications to use http://www.mchange.com/projects/c3p0/[c3p0] connection pooling.
@ -70,7 +70,7 @@ Any other settings prefixed with `c3p0.`:: Get passed to c3p0 as is. See http://
[IMPORTANT]
====
To use this integration, the application must include the hibernate-proxool module jar (as well as its dependencies) on the classpath.
To use the Proxool integration, the application must include the `hibernate-proxool` module jar (as well as its dependencies) on the classpath.
====
Hibernate also provides support for applications to use http://proxool.sourceforge.net/[Proxool] connection pooling.
@ -102,7 +102,7 @@ See http://proxool.sourceforge.net/configure.html[proxool configuration].
[IMPORTANT]
====
To use this integration, the application must include the hibernate-hikari module jar (as well as its dependencies) on the classpath.
To use the HikariCP this integration, the application must include the `hibernate-hikari` module jar (as well as its dependencies) on the classpath.
====
Hibernate also provides support for applications to use http://brettwooldridge.github.io/HikariCP/[Hikari] connection pool.
@ -123,7 +123,7 @@ Note that Hikari only supports JDBC standard isolation levels (apparently).
[IMPORTANT]
====
To use this integration, the application must include the hibernate-vibur module jar (as well as its dependencies) on the classpath.
To use the Vibur DBCP integration, the application must include the `hibernate-vibur` module jar (as well as its dependencies) on the classpath.
====
Hibernate also provides support for applications to use http://www.vibur.org/[Vibur DBCP] connection pool.
@ -143,7 +143,7 @@ Additionally, this `ConnectionProvider` will pick up the following Hibernate-spe
[IMPORTANT]
====
To use this integration, the application must include the hibernate-agroal module jar (as well as its dependencies) on the classpath.
To use the Agroal integration, the application must include the `hibernate-agroal` module jar (as well as its dependencies) on the classpath.
====
Hibernate also provides support for applications to use http://agroal.github.io/[Agroal] connection pool.
@ -218,7 +218,7 @@ when starting a new transaction, the `Connection` is acquired and the autocommit
[NOTE]
====
If you are using a connection pool `DataSource` that already disabled the autocommit mode for every pooled `Connection`, you can set the `hibernate.connection.provider_disables_autocommit` to `true` and the database connection acquisition will be, indeed, delayed until Hibernate needs to execute an SQL statement.
If you are using a connection pool `DataSource` that already disabled the autocommit mode for every pooled `Connection`, you should set the `hibernate.connection.provider_disables_autocommit` to `true` and the database connection acquisition will be, indeed, delayed until Hibernate needs to execute the first SQL statement.
====
===== JTA transaction connection handling

6
documentation/src/main/asciidoc/userguide/chapters/multitenancy/MultiTenancy.adoc
View File

@ -19,9 +19,9 @@ There are three main approaches to isolating information in these multitenant sy
[NOTE]
====
Each approach has pros and cons as well as specific techniques and considerations.
Each multitenancy strategy has pros and cons as well as specific techniques and considerations.
Such topics are beyond the scope of this documentation.
Many resources exist which delve into these other topics, like http://msdn.microsoft.com/en-us/library/aa479086.aspx[this one] which does a great job of covering these topics.
Many resources exist which delve into these other topics, like http://msdn.microsoft.com/en-us/library/aa479086.aspx[this one] which does a great job of covering this subject.
====
[[multitenacy-separate-database]]
@ -177,7 +177,7 @@ The key used to cache data encodes the tenant identifier.
[NOTE]
====
Currently, schema export will not really work with multitenancy. That may not change.
Currently, schema export will not really work with multitenancy.
The JPA expert group is in the process of defining multitenancy support for an upcoming version of the specification.
====

2
documentation/src/main/asciidoc/userguide/chapters/pc/BytecodeEnhancement.adoc
View File

@ -122,7 +122,7 @@ Enable association management feature in runtime bytecode enhancement which auto
[NOTE]
====
Also, at the moment, only annotated classes are supported for runtime enhancement.
Also, at the moment, only annotated classes support runtime enhancement.
====
[[BytecodeEnhancement-enhancement-gradle]]

11
documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc
View File

@ -88,8 +88,9 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-remove-native-example]
[NOTE]
====
Hibernate itself can handle deleting detached state.
JPA, however, disallows it.
Hibernate itself can handle deleting entities in detached state.
JPA, however, disallows this behavior.
The implication here is that the entity instance passed to the `org.hibernate.Session` delete method can be either in managed or detached state,
while the entity instance passed to remove on `javax.persistence.EntityManager` must be in the managed state.
====
@ -848,11 +849,11 @@ See the discussion of non-identifier <<chapters/domain/basic_types.adoc#mapping-
[IMPORTANT]
====
Traditionally, Hibernate has been allowing detached entities to be refreshed.
Traditionally, Hibernate allowed detached entities to be refreshed.
Unfortunately, JPA prohibits this practice and specifies that an `IllegalArgumentException` should be thrown instead.
For this reason, when bootstrapping the Hibernate `SessionFactory` using the native API, the legacy detached entity refresh behavior is going to be preserved.
On the other hand, when bootstrapping Hibernate through JPA `EntityManagerFactory` building process, detached entities are not allowed to be refreshed by default.
On the other hand, when bootstrapping Hibernate through the JPA `EntityManagerFactory` building process, detached entities are not allowed to be refreshed by default.
However, this default behavior can be overwritten through the `hibernate.allow_refresh_detached_entity` configuration property.
If this property is explicitly set to `true`, then you can refresh detached entities even when using the JPA bootstraps mechanism, therefore bypassing the JPA specification restriction.
@ -903,7 +904,7 @@ Reattachment is the process of taking an incoming entity instance that is in the
[IMPORTANT]
====
JPA does not provide for this model. This is only available through Hibernate `org.hibernate.Session`.
JPA does not support reattaching detached data. This is only available through Hibernate `org.hibernate.Session`.
====
[[pc-detach-reattach-lock-example]]

9
documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc
View File

@ -70,7 +70,7 @@ Starting with version 3.2.3, Hibernate comes with a set of http://in.relation.to
[NOTE]
====
There are specifically 2 bundled __enhanced__generators:
There are specifically 2 bundled __enhanced__ generators:
* `org.hibernate.id.enhanced.SequenceStyleGenerator`
* `org.hibernate.id.enhanced.TableGenerator`
@ -84,8 +84,9 @@ For example, the `org.hibernate.id.enhanced.SequenceStyleGenerator` mimics the b
[WARNING]
====
This is an area in Hibernate in need of improvement.
In terms of portability concerns, this function handling currently works pretty well in HQL, however, it is quite lacking in all other aspects.
When it comes to database functions, Hibernate could benefit from an improvement.
In terms of portability concerns, the function handling currently works pretty well in HQL, however, it is quite lacking in all other aspects.
====
SQL functions can be referenced in many ways by users.
@ -94,7 +95,7 @@ Hibernate, provides a means of mapping a _logical_ function name to a delegate w
[IMPORTANT]
====
Technically this function registration is handled through the `org.hibernate.dialect.function.SQLFunctionRegistry` class which is intended to allow users to provide custom function definitions without having to provide a custom dialect.
Technically the SQL function registration is handled through the `org.hibernate.dialect.function.SQLFunctionRegistry` class which is intended to allow users to provide custom function definitions without having to provide a custom dialect.
This specific behavior is not fully completed as of yet.
It is sort of implemented such that users can programmatically register functions with the `org.hibernate.cfg.Configuration` and those functions will be recognized for HQL.

7
documentation/src/main/asciidoc/userguide/chapters/query/criteria/Criteria.adoc
View File

@ -7,7 +7,8 @@ Criteria queries offer a type-safe alternative to HQL, JPQL and native SQL queri
[IMPORTANT]
====
Hibernate offers an older, legacy `org.hibernate.Criteria` API which should be considered deprecated.
No feature development will target those APIs. Eventually, Hibernate-specific criteria features will be ported as extensions to the JPA `javax.persistence.criteria.CriteriaQuery`.
No feature development will target those APIs. Eventually, Hibernate-specific Criteria features will be ported as extensions to the JPA `javax.persistence.criteria.CriteriaQuery`.
For details on the `org.hibernate.Criteria` API, see <<appendices/Legacy_Criteria.adoc#appendix-legacy-criteria, Legacy Hibernate Criteria Queries>>.
This chapter will focus on the JPA APIs for declaring type-safe criteria queries.
@ -35,7 +36,7 @@ Each serves a different purpose depending on the expected type of the query resu
[NOTE]
====
Chapter 6 Criteria API of the JPA Specification already contains a decent amount of reference material pertaining to the various parts of a criteria query.
The chapter 6 (e.g. Criteria API) of the JPA Specification already contains a decent amount of reference material pertaining to the various parts of a criteria query.
So rather than duplicate all that content here, let's instead look at some of the more widely anticipated usages of the API.
====
@ -281,7 +282,7 @@ However, in order to define the fetching of _Phone#addresses_ we needed a `javax
[NOTE]
====
Roots, joins and fetches are themselves paths as well.
Roots, joins and fetches are themselves path expressions as well.
====
[[criteria-param]]

41
documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc
View File

@ -9,7 +9,7 @@ JPQL is a heavily-inspired-by subset of HQL.
A JPQL query is always a valid HQL query, the reverse is not true, however.
Both HQL and JPQL are non-type-safe ways to perform query operations.
Criteria queries offer a type-safe approach to querying. See <<chapters/query/criteria/Criteria.adoc#criteria,Criteria>> for more information.
Criteria queries offer a type-safe approach to querying. See <<chapters/query/criteria/Criteria.adoc#criteria,Criteria>> for more information.
[[hql-examples-domain-model]]
=== Example domain model
@ -162,7 +162,7 @@ include::{sourcedir}/HQLTest.java[tags=jpql-api-positional-parameter-example]
[NOTE]
====
It's good practice not to mix forms in a given query.
It's good practice not to mix parameter binding forms in a given query.
====
In terms of execution, JPA `Query` offers 2 different methods for retrieving a result set.
@ -285,24 +285,18 @@ include::{sourcedir}/HQLTest.java[tags=hql-api-parameter-short-form-example]
----
====
HQL-style positional parameters follow JDBC positional parameter syntax.
They are declared using `?` without a following ordinal.
There is no way to relate two such positional parameters as being "the same" aside from binding the same value to each.
[[hql-api-positional-parameter-example]]
.Hibernate positional parameter binding
[IMPORTANT]
====
Traditionally, Hibernate used to support a JDBC positional parameter syntax form via a `?` symbol without a following ordinal.
There was no way to relate two such positional parameters as being "the same" aside from binding the same value to each and, for this reason, this form is no longer supported.
[source, JAVA, indent=0]
----
include::{sourcedir}/HQLTest.java[tags=hql-api-positional-parameter-example]
----
====
[IMPORTANT]
====
This form should be considered deprecated and may be removed in the near future.
====
In terms of execution, Hibernate offers 4 different methods. The 2 most commonly used are
* `Query#list` - executes the select query and returns back the list of results.
@ -428,7 +422,7 @@ So `SeLeCT` is the same as `sELEct` is the same as `SELECT`, but `org.hibernate.
[NOTE]
====
This documentation uses lowercase keywords as a convention in examples.
This documentation uses lowercase keywords as a convention in query examples.
====
[[hql-statement-types]]
@ -510,7 +504,7 @@ This is achieved by adding the `VERSIONED` keyword after the `UPDATE` keyword.
[NOTE]
====
This is a Hibernate specific feature and will not work in a portable manner.
Versioned updates is a Hibernate-specific feature and will not work in a portable manner.
Custom version types, `org.hibernate.usertype.UserVersionType`, are not allowed in conjunction with an `update versioned` statement.
====
@ -564,7 +558,7 @@ HQL adds the ability to define `INSERT` statements as well.
[NOTE]
====
There is no JPQL equivalent to this.
There is no JPQL equivalent to HQL-style INSERT statements.
====
The BNF for an HQL `INSERT` statement is:
@ -709,7 +703,7 @@ HQL also defines a `WITH` clause to qualify the join conditions.
[NOTE]
====
This is specific to HQL. JPQL defines the `ON` clause for this feature.
The HQL-style WITH keyword is specific to Hibernate. JPQL defines the `ON` clause for this feature.
====
[[hql-explicit-join-with-example]]
@ -1504,9 +1498,9 @@ include::{sourcedir}/HQLTest.java[tags=hql-entity-type-exp-example]
[NOTE]
====
HQL also has a legacy form of referring to an entity type, though that legacy form is considered deprecated in favor of `TYPE`.
The legacy form would have used `p.class` in the examples rather than `type(p)`.
It is mentioned only for completeness.
HQL also has a legacy form of referring to an entity type using the `class` keyword, though that legacy form is considered deprecated in favor of `TYPE`.
The legacy form would have used `p.class` in the examples rather than `type(p)`. It is mentioned only for completeness.
====
[[hql-case-expressions]]
@ -1619,12 +1613,13 @@ include::{sourcedir}/HQLTest.java[tags=hql-select-clause-dynamic-instantiation-e
[NOTE]
====
The class reference must be fully qualified and it must have a matching constructor.
The projection class must be fully qualified in the entity query, and it must define a matching constructor.
====
[IMPORTANT]
====
The class here need not be mapped.
The class here need not be mapped. It can be a DTO class.
If it does represent an entity, the resulting instances are returned in the NEW state (not managed!).
====
@ -1847,7 +1842,7 @@ If that following predicate is true, the NOT resolves to false.
[NOTE]
====
If the predicate is true, NOT resolves to false. If the predicate is unknown (e.g. `NULL`), the NOT resolves to unknown as well.
If the predicate is true, NOT resolves to false. If the predicate is unknown (e.g. `NULL`), then NOT resolves to unknown as well.
====
[[hql-and-predicate]]

14
documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc
View File

@ -196,7 +196,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-m
[NOTE]
====
Because of the `ROOT_ENTITY` `ResultTransformer`, this query will return the parent-side as root entities.
Because of the `ROOT_ENTITY` `ResultTransformer`, the query above will return the parent-side as root entities.
====
Notice that you added an alias name _pr_ to be able to specify the target property path of the join.
@ -277,7 +277,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-hibernate-multi-entity-query-alias-ex
[NOTE]
====
There's no such equivalent in JPA because the `Query` interface doesn't define an `addEntity` method equivalent.
There's no such equivalent in JPA because the `javax.persistence.Query` interface does not define an `addEntity` method equivalent.
====
The `{pr.*}` and `{pt.*}` notation used above is shorthand for "all properties".
@ -342,7 +342,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-hibernate-dto-query-example, indent=0
[NOTE]
====
There's no such equivalent in JPA because the `Query` interface doesn't define a `setResultTransformer` method equivalent.
There's no such equivalent in JPA because the `javax.persistence.Query` interface does not define a `setResultTransformer` method equivalent.
====
The above query will return a list of `PersonSummaryDTO` which has been instantiated and injected the values of `id` and `name` into its corresponding properties or fields.
@ -363,7 +363,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-hibernate-inheritance-query-example]
[NOTE]
====
There's no such equivalent in JPA because the `Query` interface doesn't define an `addEntity` method equivalent.
There's no such equivalent in JPA because the `javax.persistence.Query` interface does not define an `addEntity` method equivalent.
====
[[sql-query-parameters]]
@ -775,7 +775,7 @@ include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-sp-ref-cursor-oracl
[IMPORTANT]
====
`REF_CURSOR` result sets are only supported by Oracle and PostgreSQL because other database systems JDBC drivers don't support this feature.
`REF_CURSOR` result sets are only supported by some relational databases (e.g. Oracle and PostgreSQL), and other database systems JDBC drivers might not support this feature.
====
This function can be called using the standard Java Persistence API:
@ -909,9 +909,9 @@ To define the result check style, use the `check` parameter.
[TIP]
====
The parameter order is important and is defined by the order Hibernate handles properties.
You can see the expected order by enabling debug logging, so Hibernate can print out the static SQL that is used to create, update, delete etc. entities.
You can see the expected order by enabling debug logging, so Hibernate can print out the static SQL that is used to create, update, delete entities.
To see the expected sequence, remember to not include your custom SQL through annotations or mapping files as that will override the Hibernate generated static sql.
To see the expected sequence, remember to not include your custom SQL through annotations or mapping files as that will override the Hibernate generated static SQL.
====
Overriding SQL statements for secondary tables is also possible using `@org.hibernate.annotations.Table` and the `sqlInsert`, `sqlUpdate`, `sqlDelete` attributes.

2
documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc
View File

@ -140,7 +140,7 @@ In the mapping above, both the `name` and `clientId` table columns are going to
[NOTE]
====
The entity is annotated with the `@DynamicInsert` annotation so that the `INSERT` statement does not include the entity attribute that have not been set.
The `Person` entity above is annotated with the `@DynamicInsert` annotation so that the `INSERT` statement does not include any entity attribute that does not contain a value.
====
This way, when omitting the `name` and the `clientId` attribute, the database is going to set them according to their default values.

6
documentation/src/main/asciidoc/userguide/chapters/transactions/Transactions.adoc
View File

@ -39,7 +39,8 @@ or provide a custom `org.hibernate.resource.transaction.TransactionCoordinatorBu
[NOTE]
====
For details on implementing a custom `TransactionCoordinatorBuilder`, or simply better understanding how it works, see the Integrations Guide.
For details on implementing a custom `TransactionCoordinatorBuilder`, or simply better understanding how it works, see the
http://docs.jboss.org/hibernate/orm/{majorMinorVersion}/integrationguide/html_single/Hibernate_Integration_Guide.html[Integration Guide] .
====
Hibernate uses JDBC connections and JTA resources directly, without adding any additional locking behavior.
@ -50,8 +51,10 @@ The Hibernate `Session` acts as a transaction-scoped cache providing repeatable
[IMPORTANT]
====
To reduce lock contention in the database, the physical database transaction needs to be as short as possible.
Long-running database transactions prevent your application from scaling to a highly-concurrent load.
Do not hold a database transaction open during end-user-level work, but open it after the end-user-level work is finished.
This concept is referred to as `transactional write-behind`.
====
@ -202,6 +205,7 @@ Avoid auto-commit behavior for reading data because many small transactions are
[NOTE]
====
Using auto-commit does not circumvent database transactions.
Instead, when in auto-commit mode, JDBC drivers simply perform each call in an implicit transaction call.
It is as if your application called commit after each and every JDBC call.
====

5
documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java
View File

@ -43,6 +43,7 @@ import org.hibernate.userguide.model.PhoneType;
import org.hibernate.userguide.model.WireTransferPayment;
import org.hibernate.testing.DialectChecks;
import org.hibernate.testing.FailureExpected;
import org.hibernate.testing.RequiresDialect;
import org.hibernate.testing.RequiresDialectFeature;
import org.hibernate.testing.SkipForDialect;
@ -776,7 +777,7 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
});
}
@Test
@Test(expected = IllegalArgumentException.class)
public void test_hql_api_positional_parameter_example() {
doInJPA( this::entityManagerFactory, entityManager -> {
Date timestamp = new Date( );
@ -785,7 +786,7 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
org.hibernate.query.Query query = session.createQuery(
"select p " +
"from Person p " +
"where p.name like ?1" )
"where p.name like ?" )
.setParameter( 1, "J%" );
//end::hql-api-positional-parameter-example[]
});