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

Unify example includes in terms of well-defined asciidoc attributes 

preparation step for moving tests out of `documentation` and into the proper projects (core, envers and spatial)
This commit is contained in:
Steve Ebersole 2023-01-27 17:25:22 -06:00
parent 7564551f6e
commit 606ae62499
37 changed files with 967 additions and 907 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc
View File

@ -3,6 +3,8 @@ Vlad Mihalcea, Steve Ebersole, Andrea Boriero, Gunnar Morling, Gail Badner, Chri
:toc2: :toc2:
:toclevels: 3 :toclevels: 3
:sectanchors: :sectanchors:
:root-project-dir: ../../../../../../..
include::Preface.adoc[] include::Preface.adoc[]

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

@ -1,7 +1,10 @@
[[batch]] [[batch]]
== Batching == Batching
:sourcedir: ../../../../../test/java/org/hibernate/userguide/batch :root-project-dir: ../../../../../../..
:bulkid-sourcedir: ../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/bulkid :documentation-project-dir: {root-project-dir}/documentation
:core-project-dir: {root-project-dir}/hibernate-core
:example-dir-doc-batch: {documentation-project-dir}/src/test/java/org/hibernate/userguide/batch
:example-dir-bulkid: {core-project-dir}/src/test/java/org/hibernate/orm/test/bulkid
:extrasdir: extras :extrasdir: extras
[[batch-jdbcbatch]] [[batch-jdbcbatch]]
@ -46,7 +49,7 @@ Since version 5.2, Hibernate allows overriding the global JDBC batch size given
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-session-jdbc-batch-size-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-session-jdbc-batch-size-example]
---- ----
==== ====
@ -60,7 +63,7 @@ The following example shows an anti-pattern for batch inserts.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-session-batch-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-session-batch-example]
---- ----
==== ====
@ -88,7 +91,7 @@ When you make new objects persistent, employ methods `flush()` and `clear()` to
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-session-batch-insert-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-session-batch-insert-example]
---- ----
==== ====
@ -103,7 +106,7 @@ In addition, use method `scroll()` to take advantage of server-side cursors for
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-session-scroll-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-session-scroll-example]
---- ----
==== ====
@ -149,7 +152,7 @@ IMPORTANT: Due to the lack of a first-level cache, stateless sessions are vulner
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-stateless-session-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-stateless-session-example]
---- ----
==== ====
@ -205,7 +208,7 @@ You can use sub-queries in the `WHERE` clause, and the sub-queries themselves ca
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-bulk-jpql-update-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-bulk-jpql-update-example]
---- ----
==== ====
@ -214,7 +217,7 @@ include::{sourcedir}/BatchTest.java[tags=batch-bulk-jpql-update-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-bulk-hql-update-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-bulk-hql-update-example]
---- ----
==== ====
@ -226,7 +229,7 @@ You can use a versioned update to force Hibernate to reset the version or timest
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-bulk-hql-update-version-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-bulk-hql-update-version-example]
---- ----
==== ====
@ -242,7 +245,7 @@ This feature is only available in HQL since it's not standardized by Jakarta Per
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-bulk-jpql-delete-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-bulk-jpql-delete-example]
---- ----
==== ====
@ -251,7 +254,7 @@ include::{sourcedir}/BatchTest.java[tags=batch-bulk-jpql-delete-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-bulk-hql-delete-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-bulk-hql-delete-example]
---- ----
==== ====
@ -309,7 +312,7 @@ in which case the seed value defined by the `org.hibernate.type.descriptor.java.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchTest.java[tags=batch-bulk-hql-insert-example] include::{example-dir-doc-batch}/BatchTest.java[tags=batch-bulk-hql-insert-example]
---- ----
==== ====
@ -344,7 +347,7 @@ The `Person` entity is the base class of this entity inheritance model, and is m
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{bulkid-sourcedir}/AbstractMutationStrategyCompositeIdTest.java[tags=batch-bulk-hql-temp-table-base-class-example] include::{example-dir-bulkid}/AbstractMutationStrategyCompositeIdTest.java[tags=batch-bulk-hql-temp-table-base-class-example]
---- ----
==== ====
@ -355,7 +358,7 @@ Both the `Doctor` and `Engineer` entity classes extend the `Person` base class:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{bulkid-sourcedir}/AbstractMutationStrategyIdTest.java[tags=batch-bulk-hql-temp-table-sub-classes-example] include::{example-dir-bulkid}/AbstractMutationStrategyIdTest.java[tags=batch-bulk-hql-temp-table-sub-classes-example]
---- ----
==== ====
@ -369,7 +372,7 @@ Now, when you try to execute a bulk entity delete query:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{bulkid-sourcedir}/AbstractMutationStrategyCompositeIdTest.java[tags=batch-bulk-hql-temp-table-delete-query-example] include::{example-dir-bulkid}/AbstractMutationStrategyCompositeIdTest.java[tags=batch-bulk-hql-temp-table-delete-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

20
documentation/src/main/asciidoc/userguide/chapters/beans/Beans.adoc
View File

@ -1,12 +1,6 @@
[[beans]] [[beans]]
== Managed Beans == Managed Beans
:rootProjectDir: ../../../../../../..
:sourcedir: ../../../../../test/java/org/hibernate/userguide/beans
:coreProjectDir: {rootProjectDir}/hibernate-core
:coreTestSrcDir: {rootProjectDir}/hibernate-core/src/test/java
:instantiatorTestDir: {coreTestSrcDir}/org/hibernate/orm/test/mapping/embeddable/strategy/instantiator
:extrasdir: extras :extrasdir: extras
:fn-cdi-availability: footnote:disclaimer[With delayed or extended CDI availability, IdentifierGenerators cannot be resolved from CDI due to timing. See <<beans-cdi>>]
Hibernate supports consuming many of its extension points as "managed beans". A bean being Hibernate supports consuming many of its extension points as "managed beans". A bean being
managed simply means that its creation and lifecycle are managed by a container of some sort. managed simply means that its creation and lifecycle are managed by a container of some sort.
@ -25,10 +19,11 @@ the SessionFactory. It supports a number of ways to influence how this process
[[beans-manageable]] [[beans-manageable]]
=== Manageable Beans === Manageable Beans
Hibernate supports using the following integrations as managed beans: Jakarta Persistence defines support for resolving `AttributeConverter` and
"entity listener" classes as managed beans.
Additionally, Hibernate supports resolving the following integrations as managed beans:
* `jakarta.persistence.AttributeConverter`
* Jakarta Persistence "entity listener" classes
* `org.hibernate.type.descriptor.jdbc.JdbcType` * `org.hibernate.type.descriptor.jdbc.JdbcType`
* `org.hibernate.type.descriptor.java.BasicJavaType` * `org.hibernate.type.descriptor.java.BasicJavaType`
* `org.hibernate.type.descriptor.java.MutabilityPlan` * `org.hibernate.type.descriptor.java.MutabilityPlan`
@ -36,7 +31,10 @@ Hibernate supports using the following integrations as managed beans:
* `org.hibernate.usertype.UserCollectionType` * `org.hibernate.usertype.UserCollectionType`
* `org.hibernate.metamodel.EmbeddableInstantiator` * `org.hibernate.metamodel.EmbeddableInstantiator`
* `org.hibernate.envers.RevisionListener` * `org.hibernate.envers.RevisionListener`
* `org.hibernate.id.IdentifierGenerator`{fn-cdi-availability} * `org.hibernate.id.IdentifierGenerator`
NOTE: At the moment, when using either <<beans-cdi-delayed,delayed>> or <<beans-cdi-extended,extended>>
CDI access, resolving these Hibernate integrations as managed beans is disabled.
[[beans-cdi]] [[beans-cdi]]
@ -94,4 +92,4 @@ NOTE: When used in WildFly, this is all automatically set up by the server
=== Custom BeanContainer === Custom BeanContainer
Other containers (Spring, e.g.) can also be used and integrated by implementing `BeanContainer` and Other containers (Spring, e.g.) can also be used and integrated by implementing `BeanContainer` and
declaring it using `hibernate.resource.beans.container`. declaring it using `hibernate.resource.beans.container`.

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

@ -1,7 +1,10 @@
[[bootstrap]] [[bootstrap]]
== Bootstrap == Bootstrap
:sourcedir: ../../../../../test/java/org/hibernate/userguide/bootstrap :root-project-dir: ../../../../../../..
:boot-spi-sourcedir: ../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/bootstrap/spi :documentation-project-dir: {root-project-dir}/documentation
:core-project-dir: {root-project-dir}/hibernate-core
:example-dir-boot: {documentation-project-dir}/src/test/java/org/hibernate/userguide/bootstrap
:example-dir-boot-spi: {core-project-dir}/src/test/java/org/hibernate/orm/test/bootstrap/spi
:extrasdir: extras :extrasdir: extras
The term bootstrapping refers to initializing and starting a software component. The term bootstrapping refers to initializing and starting a software component.
@ -48,7 +51,7 @@ If you wish to alter how the `BootstrapServiceRegistry` is built, that is contro
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry-BootstrapServiceRegistry-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry-BootstrapServiceRegistry-example]
---- ----
==== ====
@ -65,7 +68,7 @@ You will almost always need to configure the `StandardServiceRegistry`, which is
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry-StandardServiceRegistryBuilder-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry-StandardServiceRegistryBuilder-example]
---- ----
==== ====
@ -79,7 +82,7 @@ Some specific methods of interest:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry-MetadataSources-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry-MetadataSources-example]
---- ----
==== ====
@ -93,7 +96,7 @@ The main use cases for an `org.hibernate.integrator.spi.Integrator` right now ar
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-event-listener-registration-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-event-listener-registration-example]
---- ----
==== ====
@ -112,7 +115,7 @@ Also, all methods on `MetadataSources` offer fluent-style call chaining::
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-metadata-source-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-native-metadata-source-example]
---- ----
==== ====
@ -136,7 +139,7 @@ See its https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-metadata-builder-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-native-metadata-builder-example]
---- ----
==== ====
@ -153,7 +156,7 @@ However, if you would like to adjust that building process, you will need to use
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-SessionFactory-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-native-SessionFactory-example]
---- ----
==== ====
@ -168,7 +171,7 @@ The bootstrapping API is quite flexible, but in most cases it makes the most sen
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-SessionFactoryBuilder-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-native-SessionFactoryBuilder-example]
---- ----
==== ====
@ -196,7 +199,7 @@ and make that available to the application for injection via the `jakarta.persis
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-example]
---- ----
==== ====
@ -208,7 +211,7 @@ you can inject a specific `EntityManagerFactory` by Unit name:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-configurable-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceUnit-configurable-example]
---- ----
==== ====
@ -231,7 +234,7 @@ The application creates an `EntityManagerFactory` by calling the `createEntityMa
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-EntityManagerFactory-example] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-jpa-compliant-EntityManagerFactory-example]
---- ----
==== ====
@ -249,7 +252,7 @@ To inject the default Persistence Context, you can use the {jpaJavadocUrlPrefix}
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceContext-example, indent=0] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceContext-example, indent=0]
---- ----
==== ====
@ -264,7 +267,7 @@ and you can even pass `EntityManager`-specific properties using the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceContext-configurable-example, indent=0] include::{example-dir-boot}/BootstrapTest.java[tags=bootstrap-jpa-compliant-PersistenceContext-configurable-example, indent=0]
---- ----
==== ====
@ -324,7 +327,7 @@ https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{boot-spi-sourcedir}/metadatabuildercontributor/SqlFunctionMetadataBuilderContributor.java[tags=bootstrap-jpa-compliant-MetadataBuilderContributor-example] include::{example-dir-boot-spi}/metadatabuildercontributor/SqlFunctionMetadataBuilderContributor.java[tags=bootstrap-jpa-compliant-MetadataBuilderContributor-example]
---- ----
==== ====
org.hibernate.orm.test.bootstrap.spi.metadatabuildercontributor org.hibernate.orm.test.bootstrap.spi.metadatabuildercontributor

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

@ -1,6 +1,8 @@
[[caching]] [[caching]]
== Caching == Caching
:sourcedir: ../../../../../test/java/org/hibernate/userguide/caching :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-caching: {documentation-project-dir}/src/test/java/org/hibernate/userguide/caching
At runtime, Hibernate handles moving data into and out of the second-level cache in response to the operations performed by the `Session`, which acts as a transaction-level cache of persistent data. At runtime, Hibernate handles moving data into and out of the second-level cache in response to the operations performed by the `Session`, which acts as a transaction-level cache of persistent data.
Once an entity becomes managed, that object is added to the internal cache of the current persistence context (`EntityManager` or `Session`). Once an entity becomes managed, that object is added to the internal cache of the current persistence context (`EntityManager` or `Session`).
@ -167,7 +169,7 @@ Nevertheless, the reasons why we advise you to have all entities belonging to an
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/NonStrictReadWriteCacheTest.java[tags=caching-entity-mapping-example] include::{example-dir-caching}/NonStrictReadWriteCacheTest.java[tags=caching-entity-mapping-example]
---- ----
==== ====
@ -182,7 +184,7 @@ Once an entity is stored in the second-level cache, you can avoid a database hit
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-entity-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-entity-jpa-example]
---- ----
==== ====
@ -191,7 +193,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-entity-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-entity-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-entity-native-example]
---- ----
==== ====
@ -202,7 +204,7 @@ The Hibernate second-level cache can also load entities by their <<chapters/doma
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-entity-natural-id-mapping-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-entity-natural-id-mapping-example]
---- ----
==== ====
@ -211,7 +213,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-entity-natural-id-ma
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-entity-natural-id-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-entity-natural-id-example]
---- ----
==== ====
@ -230,7 +232,7 @@ the collection cache entry will store the entity identifiers only.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/NonStrictReadWriteCacheTest.java[tags=caching-collection-mapping-example] include::{example-dir-caching}/NonStrictReadWriteCacheTest.java[tags=caching-collection-mapping-example]
---- ----
==== ====
@ -241,7 +243,7 @@ Collections are read-through, meaning they are cached upon being accessed for th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/NonStrictReadWriteCacheTest.java[tags=caching-collection-example] include::{example-dir-caching}/NonStrictReadWriteCacheTest.java[tags=caching-collection-example]
---- ----
==== ====
@ -292,7 +294,7 @@ This way, the query looks for existing cache results or adds the query results t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-jpa-example]
---- ----
==== ====
@ -301,7 +303,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-native-example]
---- ----
==== ====
@ -345,7 +347,7 @@ you can specify a named cache region for a particular query.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-region-jpa-example]
---- ----
==== ====
@ -354,7 +356,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-jpa-exa
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-region-native-example]
---- ----
==== ====
@ -366,7 +368,7 @@ you can use custom cache modes.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-mode-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-region-store-mode-jpa-example]
---- ----
==== ====
@ -375,7 +377,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-m
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-mode-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-region-store-mode-native-example]
---- ----
==== ====
@ -389,7 +391,7 @@ and is a far more efficient alternative to the bulk eviction of the region via `
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-native-evict-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-query-region-native-evict-example]
---- ----
==== ====
@ -421,7 +423,7 @@ Setting the cache mode can be done either when loading entities directly or when
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-entity-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-entity-jpa-example]
---- ----
==== ====
@ -430,7 +432,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mod
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-entity-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-entity-native-example]
---- ----
==== ====
@ -441,7 +443,7 @@ The custom cache modes can be set for queries as well:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-query-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-query-jpa-example]
---- ----
==== ====
@ -450,7 +452,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mod
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-query-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-management-cache-mode-query-native-example]
---- ----
==== ====
@ -467,7 +469,7 @@ Jakarta Persistence only supports entity eviction through the {jpaJavadocUrlPref
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-evict-jpa-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-management-evict-jpa-example]
---- ----
==== ====
@ -484,7 +486,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-evict-native-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-management-evict-native-example]
---- ----
==== ====
@ -503,7 +505,7 @@ second-level cache metrics.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-statistics-example] include::{example-dir-caching}/SecondLevelCacheTest.java[tags=caching-statistics-example]
---- ----
==== ====

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

@ -1,6 +1,8 @@
[[access]] [[access]]
=== Access strategies === Access strategies
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/access :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-access: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping/access
:extrasdir: extras :extrasdir: extras
As a Jakarta Persistence provider, Hibernate can introspect both the entity attributes (instance fields) or the accessors (instance properties). As a Jakarta Persistence provider, Hibernate can introspect both the entity attributes (instance fields) or the accessors (instance properties).
@ -25,7 +27,7 @@ Embeddable types inherit the access strategy from their parent entities.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/FieldAccessTest.java[tag=access-field-mapping-example, indent=0] include::{example-dir-access}/FieldAccessTest.java[tag=access-field-mapping-example, indent=0]
---- ----
==== ====
@ -49,7 +51,7 @@ With field-based access, we can simply omit the getter and the setter for this v
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/PropertyAccessTest.java[tag=access-property-mapping-example, indent=0] include::{example-dir-access}/PropertyAccessTest.java[tag=access-property-mapping-example, indent=0]
---- ----
==== ====
@ -66,7 +68,7 @@ In the following example, the `@Version` attribute is accessed by its field and
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/PropertyAccessOverrideTest.java[tag=access-property-override-mapping-example, indent=0] include::{example-dir-access}/PropertyAccessOverrideTest.java[tag=access-property-override-mapping-example, indent=0]
---- ----
==== ====
@ -84,7 +86,7 @@ In the following example, the embeddable uses property-based access, no matter w
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddableAccessTest.java[tag=access-embeddable-mapping-example, indent=0] include::{example-dir-access}/EmbeddableAccessTest.java[tag=access-embeddable-mapping-example, indent=0]
---- ----
==== ====
@ -95,7 +97,7 @@ The owning entity can use field-based access while the embeddable uses property-
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddableAccessTest.java[tag=access-embedded-mapping-example, indent=0] include::{example-dir-access}/EmbeddableAccessTest.java[tag=access-embedded-mapping-example, indent=0]
---- ----
==== ====
@ -106,6 +108,6 @@ This works also for collection of embeddable types:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ElementCollectionAccessTest.java[tag=access-element-collection-mapping-example, indent=0] include::{example-dir-access}/ElementCollectionAccessTest.java[tag=access-element-collection-mapping-example, indent=0]
---- ----
==== ====

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

@ -1,6 +1,8 @@
[[associations]] [[associations]]
=== Associations === Associations
:sourcedir: ../../../../../test/java/org/hibernate/userguide/associations :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-association: {documentation-project-dir}/src/test/java/org/hibernate/userguide/associations
:extrasdir: extras/associations :extrasdir: extras/associations
Associations describe how two or more entities form a relationship based on a database joining semantics. Associations describe how two or more entities form a relationship based on a database joining semantics.
@ -16,7 +18,7 @@ and so it establishes a relationship between a child entity and a parent.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToOneTest.java[tags=associations-many-to-one-example,indent=0] include::{example-dir-association}/ManyToOneTest.java[tags=associations-many-to-one-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -32,7 +34,7 @@ Each entity has a lifecycle of its own. Once the `@ManyToOne` association is set
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToOneTest.java[tags=associations-many-to-one-lifecycle-example,indent=0] include::{example-dir-association}/ManyToOneTest.java[tags=associations-many-to-one-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -58,7 +60,7 @@ When using a unidirectional `@OneToMany` association, Hibernate resorts to using
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToManyUnidirectionalTest.java[tags=associations-one-to-many-unidirectional-example,indent=0] include::{example-dir-association}/OneToManyUnidirectionalTest.java[tags=associations-one-to-many-unidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -78,7 +80,7 @@ Only the parent side of an association makes sense to cascade its entity state t
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToManyUnidirectionalTest.java[tags=associations-one-to-many-unidirectional-lifecycle-example,indent=0] include::{example-dir-association}/OneToManyUnidirectionalTest.java[tags=associations-one-to-many-unidirectional-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -111,7 +113,7 @@ Every bidirectional association must have one owning side only (the child side),
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToManyBidirectionalTest.java[tags=associations-one-to-many-bidirectional-example,indent=0] include::{example-dir-association}/OneToManyBidirectionalTest.java[tags=associations-one-to-many-bidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -135,7 +137,7 @@ the `equals()` and the `hashCode()` can make use of this property, and so the `r
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToManyBidirectionalTest.java[tags=associations-one-to-many-bidirectional-lifecycle-example,indent=0] include::{example-dir-association}/OneToManyBidirectionalTest.java[tags=associations-one-to-many-bidirectional-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -164,7 +166,7 @@ A bidirectional association features a `mappedBy` `@OneToOne` parent side too.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToOneUnidirectionalTest.java[tags=associations-one-to-one-unidirectional-example,indent=0] include::{example-dir-association}/OneToOneUnidirectionalTest.java[tags=associations-one-to-one-unidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -188,7 +190,7 @@ This mapping requires a bidirectional `@OneToOne` association as you can see in
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToOneBidirectionalTest.java[tags=associations-one-to-one-bidirectional-example,indent=0] include::{example-dir-association}/OneToOneBidirectionalTest.java[tags=associations-one-to-one-bidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -204,7 +206,7 @@ This time, the `PhoneDetails` owns the association, and, like any bidirectional
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToOneBidirectionalTest.java[tags=associations-one-to-one-bidirectional-lifecycle-example,indent=0] include::{example-dir-association}/OneToOneBidirectionalTest.java[tags=associations-one-to-one-bidirectional-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -222,7 +224,7 @@ Continuing the previous example, when adding another `PhoneDetails`, Hibernate v
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToOneBidirectionalTest.java[tags=associations-one-to-one-bidirectional-constraint-example,indent=0] include::{example-dir-association}/OneToOneBidirectionalTest.java[tags=associations-one-to-one-bidirectional-constraint-example,indent=0]
---- ----
==== ====
@ -243,7 +245,7 @@ then you need to enable lazy state initialization bytecode enhancement.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OneToOneBidirectionalLazyTest.java[tags=associations-one-to-one-bidirectional-lazy-example,indent=0] include::{example-dir-association}/OneToOneBidirectionalLazyTest.java[tags=associations-one-to-one-bidirectional-lazy-example,indent=0]
---- ----
==== ====
@ -264,7 +266,7 @@ Like the `@OneToMany` association, `@ManyToMany` can be either unidirectional or
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyUnidirectionalTest.java[tags=associations-many-to-many-unidirectional-example,indent=0] include::{example-dir-association}/ManyToManyUnidirectionalTest.java[tags=associations-many-to-many-unidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -283,7 +285,7 @@ Unfortunately, this operation requires removing all entries associated with a gi
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyUnidirectionalTest.java[tags=associations-many-to-many-unidirectional-lifecycle-example,indent=0] include::{example-dir-association}/ManyToManyUnidirectionalTest.java[tags=associations-many-to-many-unidirectional-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -318,7 +320,7 @@ By simply removing the parent-side, Hibernate can safely remove the associated l
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyUnidirectionalTest.java[tags=associations-many-to-many-unidirectional-remove-example,indent=0] include::{example-dir-association}/ManyToManyUnidirectionalTest.java[tags=associations-many-to-many-unidirectional-remove-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -338,7 +340,7 @@ To preserve synchronicity between both sides, it's good practice to provide help
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyBidirectionalTest.java[tags=associations-many-to-many-bidirectional-example,indent=0] include::{example-dir-association}/ManyToManyBidirectionalTest.java[tags=associations-many-to-many-bidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -354,7 +356,7 @@ With the helper methods in place, the synchronicity management can be simplified
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyBidirectionalTest.java[tags=associations-many-to-many-bidirectional-lifecycle-example,indent=0] include::{example-dir-association}/ManyToManyBidirectionalTest.java[tags=associations-many-to-many-bidirectional-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -378,7 +380,7 @@ and the link table has an associated entity which controls the relationship for
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyBidirectionalWithLinkEntityTest.java[tags=associations-many-to-many-bidirectional-with-link-entity-example,indent=0] include::{example-dir-association}/ManyToManyBidirectionalWithLinkEntityTest.java[tags=associations-many-to-many-bidirectional-with-link-entity-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -404,7 +406,7 @@ The entity state transitions are better managed than in the previous bidirection
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/ManyToManyBidirectionalWithLinkEntityTest.java[tags=associations-many-to-many-bidirectional-with-link-entity-lifecycle-example,indent=0] include::{example-dir-association}/ManyToManyBidirectionalWithLinkEntityTest.java[tags=associations-many-to-many-bidirectional-with-link-entity-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -456,7 +458,7 @@ Considering the following `City` and `Person` entity mappings:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-domain-model-example,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-domain-model-example,indent=0]
---- ----
==== ====
@ -467,7 +469,7 @@ If we have the following entities in our database:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-persist-example,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-persist-example,indent=0]
---- ----
==== ====
@ -478,7 +480,7 @@ When loading the `Person` entity, Hibernate is able to locate the associated `Ci
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-find-baseline,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-find-baseline,indent=0]
---- ----
==== ====
@ -489,7 +491,7 @@ However, if we break the foreign-key:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-break-fk,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-break-fk,indent=0]
---- ----
==== ====
@ -500,7 +502,7 @@ Hibernate is not going to throw any exception, and it will assign a value of `nu
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-non-existing-find-example,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-non-existing-find-example,indent=0]
---- ----
==== ====
@ -529,7 +531,7 @@ resolve the `city.id` value.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-implicit-join-example,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-implicit-join-example,indent=0]
---- ----
==== ====
@ -543,7 +545,7 @@ using the special `fk(..)` function. E.g.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NotFoundTest.java[tags=associations-not-found-fk-function-example,indent=0] include::{example-dir-association}/NotFoundTest.java[tags=associations-not-found-fk-function-example,indent=0]
---- ----
==== ====
@ -615,11 +617,11 @@ For this example, consider the following `Property` class hierarchy:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/Property.java[tags=associations-any-property-example] include::{example-dir-association}/any/Property.java[tags=associations-any-property-example]
include::{sourcedir}/any/IntegerProperty.java[tags=associations-any-property-example] include::{example-dir-association}/any/IntegerProperty.java[tags=associations-any-property-example]
include::{sourcedir}/any/StringProperty.java[tags=associations-any-property-example] include::{example-dir-association}/any/StringProperty.java[tags=associations-any-property-example]
---- ----
==== ====
@ -630,7 +632,7 @@ A `PropertyHolder` entity defines an attribute of type `Property`:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/PropertyHolder.java[tags=associations-any-example] include::{example-dir-association}/any/PropertyHolder.java[tags=associations-any-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -657,7 +659,7 @@ Hibernate will generate the following SQL queries:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/AnyTest.java[tags=associations-any-persist-example] include::{example-dir-association}/any/AnyTest.java[tags=associations-any-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -674,7 +676,7 @@ Hibernate will fetch the associated `StringProperty` entity like this:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/AnyTest.java[tags=associations-any-query-example] include::{example-dir-association}/any/AnyTest.java[tags=associations-any-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -700,7 +702,7 @@ into a single annotation that we can apply in each usage.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/PropertyHolder2.java[tags=associations-any-def-example] include::{example-dir-association}/any/PropertyHolder2.java[tags=associations-any-def-example]
---- ----
==== ====
@ -731,7 +733,7 @@ The `repository_properties` link table holds the associations between `PropertyR
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/PropertyRepository.java[tags=associations-many-to-any-example] include::{example-dir-association}/any/PropertyRepository.java[tags=associations-many-to-any-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -751,7 +753,7 @@ Hibernate will generate the following SQL queries:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/ManyToAnyTest.java[tags=associations-many-to-any-persist-example] include::{example-dir-association}/any/ManyToAnyTest.java[tags=associations-many-to-any-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -768,7 +770,7 @@ Hibernate will fetch the associated `IntegerProperty` and `StringProperty` entit
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/any/ManyToAnyTest.java[tags=associations-many-to-any-query-example] include::{example-dir-association}/any/ManyToAnyTest.java[tags=associations-many-to-any-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -789,7 +791,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/JoinFormulaTest.java[tags=associations-JoinFormula-example] include::{example-dir-association}/JoinFormulaTest.java[tags=associations-JoinFormula-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -807,7 +809,7 @@ Considering we have the following entities:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/JoinFormulaTest.java[tags=associations-JoinFormula-persistence-example] include::{example-dir-association}/JoinFormulaTest.java[tags=associations-JoinFormula-persistence-example]
---- ----
==== ====
@ -818,7 +820,7 @@ When fetching the `User` entities, the `country` property is mapped by the `@Joi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/JoinFormulaTest.java[tags=associations-JoinFormula-fetching-example] include::{example-dir-association}/JoinFormulaTest.java[tags=associations-JoinFormula-fetching-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -839,7 +841,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-example] include::{example-dir-association}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -857,7 +859,7 @@ Considering we have the following entities:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-persistence-example] include::{example-dir-association}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-persistence-example]
---- ----
==== ====
@ -868,7 +870,7 @@ When fetching the `User` entities, the `country` property is mapped by the `@Joi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-fetching-example] include::{example-dir-association}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-fetching-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,13 +1,15 @@
[[basic]] [[basic]]
=== Basic values === Basic values
:rootProjectDir: ../../../../../../.. :root-project-dir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation :documentation-project-dir: {root-project-dir}/documentation
:coreProjectDir: {rootProjectDir}/hibernate-core :documentation-example-base: {documentation-project-dir}/src/test/
:core-generated-test-dir: {coreProjectDir}/src/test/java/org/hibernate/orm/test/mapping/generated :example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:modeldir: {documentationProjectDir}/src/main/java/org/hibernate/userguide/model :example-dir-basic-mapping: {documentation-example-base}/java/org/hibernate/userguide/mapping
:sourcedir: {documentationProjectDir}/src/test/java/org/hibernate/userguide/mapping :example-dir-resources: {documentation-example-base}/resources/org/hibernate/userguide/
:resourcedir: {documentationProjectDir}/src/test/resources/org/hibernate/userguide/ :core-project-dir: {root-project-dir}/hibernate-core
:converter-sourcedir: {coreProjectDir}/src/test/java/org/hibernate/orm/test/mapping/converted/converter :core-test-base: {core-project-dir}/src/test
:example-dir-generated: {core-test-base}/java/org/hibernate/orm/test/mapping/generated
:example-dir-converter: {core-test-base}/java/org/hibernate/orm/test/mapping/converted/converter
:extrasdir: extras :extrasdir: extras
A basic type is a mapping between a Java type and a single database column. A basic type is a mapping between a Java type and a single database column.
@ -61,7 +63,7 @@ examples are ultimately the same.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ExplicitBasicTypeTest.java[tags=basic-annotation-explicit-example] include::{example-dir-basic-mapping}/basic/ExplicitBasicTypeTest.java[tags=basic-annotation-explicit-example]
---- ----
==== ====
@ -70,7 +72,7 @@ include::{sourcedir}/basic/ExplicitBasicTypeTest.java[tags=basic-annotation-expl
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ImplicitBasicTypeTest.java[tags=basic-annotation-implicit-example] include::{example-dir-basic-mapping}/basic/ImplicitBasicTypeTest.java[tags=basic-annotation-implicit-example]
---- ----
==== ====
@ -106,7 +108,7 @@ If that implicit naming rule does not meet your requirements, you can explicitly
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ExplicitColumnNamingTest.java[tags=basic-annotation-explicit-column-example] include::{example-dir-basic-mapping}/basic/ExplicitColumnNamingTest.java[tags=basic-annotation-explicit-column-example]
---- ----
==== ====
@ -136,7 +138,7 @@ The `@Column` annotation defines other mapping information as well. See its Java
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/FormulaTest.java[tags=mapping-column-formula-example] include::{example-dir-basic-mapping}/basic/FormulaTest.java[tags=mapping-column-formula-example]
---- ----
==== ====
@ -147,7 +149,7 @@ When loading the `Account` entity, Hibernate is going to calculate the `interest
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/FormulaTest.java[tags=mapping-column-formula-persistence-example] include::{example-dir-basic-mapping}/basic/FormulaTest.java[tags=mapping-column-formula-persistence-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -255,7 +257,7 @@ Assuming the following enumeration:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/PhoneType.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/PhoneType.java[tags=hql-examples-domain-model-example]
---- ----
==== ====
@ -270,7 +272,7 @@ In the ORDINAL example, the `phone_type` column is defined as a (nullable) INTEG
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/PhoneTypeEnumeratedOrdinalTest.java[tags=basic-enums-Enumerated-ordinal-example] include::{example-dir-basic-mapping}/basic/PhoneTypeEnumeratedOrdinalTest.java[tags=basic-enums-Enumerated-ordinal-example]
---- ----
==== ====
@ -281,7 +283,7 @@ When persisting this entity, Hibernate generates the following SQL statement:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/PhoneTypeEnumeratedOrdinalTest.java[tags=basic-enums-Enumerated-ordinal-persistence-example] include::{example-dir-basic-mapping}/basic/PhoneTypeEnumeratedOrdinalTest.java[tags=basic-enums-Enumerated-ordinal-persistence-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -301,7 +303,7 @@ In the STRING example, the `phone_type` column is defined as a (nullable) VARCHA
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/PhoneTypeEnumeratedStringTest.java[tags=basic-enums-Enumerated-string-example] include::{example-dir-basic-mapping}/basic/PhoneTypeEnumeratedStringTest.java[tags=basic-enums-Enumerated-string-example]
---- ----
==== ====
@ -326,7 +328,7 @@ Let's consider the following `Gender` enum which stores its values using the `'M
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/Gender.java[tags=basic-enums-converter-example] include::{example-dir-basic-mapping}/basic/Gender.java[tags=basic-enums-converter-example]
---- ----
==== ====
@ -337,7 +339,7 @@ You can map enums in a Jakarta Persistence compliant way using a Jakarta Persist
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/EnumerationConverterTest.java[tags=basic-enums-attribute-converter-example] include::{example-dir-basic-mapping}/basic/EnumerationConverterTest.java[tags=basic-enums-attribute-converter-example]
---- ----
==== ====
@ -369,11 +371,11 @@ Let's again revisit the Gender enum example, this time using a custom Type to st
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/EnumerationCustomTypeTest.java[tags=basic-enums-custom-type-example, indent=0] include::{example-dir-basic-mapping}/basic/EnumerationCustomTypeTest.java[tags=basic-enums-custom-type-example, indent=0]
include::{sourcedir}/basic/GenderType.java[tags=basic-enums-custom-type-example, indent=0] include::{example-dir-basic-mapping}/basic/GenderType.java[tags=basic-enums-custom-type-example, indent=0]
include::{sourcedir}/basic/GenderJavaType.java[tags=basic-enums-custom-type-example, indent=0] include::{example-dir-basic-mapping}/basic/GenderJavaType.java[tags=basic-enums-custom-type-example, indent=0]
---- ----
==== ====
@ -400,7 +402,7 @@ dedicated `BOOLEAN` type. On databases which don't, Hibernate uses whatever else
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BooleanMappingTests.java[tags=basic-boolean-example-implicit] include::{example-dir-basic-mapping}/basic/BooleanMappingTests.java[tags=basic-boolean-example-implicit]
---- ----
==== ====
@ -417,11 +419,11 @@ provides 3 built-in converters for the common boolean mapping cases:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BooleanMappingTests.java[tags=basic-boolean-example-explicit-yes-no] include::{example-dir-basic-mapping}/basic/BooleanMappingTests.java[tags=basic-boolean-example-explicit-yes-no]
include::{sourcedir}/basic/BooleanMappingTests.java[tags=basic-boolean-example-explicit-t-f] include::{example-dir-basic-mapping}/basic/BooleanMappingTests.java[tags=basic-boolean-example-explicit-t-f]
include::{sourcedir}/basic/BooleanMappingTests.java[tags=basic-boolean-example-explicit-numeric] include::{example-dir-basic-mapping}/basic/BooleanMappingTests.java[tags=basic-boolean-example-explicit-numeric]
---- ----
==== ====
@ -443,7 +445,7 @@ By default, Hibernate maps values of `Byte` / `byte` to the `TINYINT` JDBC type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ByteMappingTests.java[tags=basic-byte-example-implicit] include::{example-dir-basic-mapping}/basic/ByteMappingTests.java[tags=basic-byte-example-implicit]
---- ----
==== ====
@ -465,7 +467,7 @@ By default, Hibernate maps values of `Short` / `short` to the `SMALLINT` JDBC ty
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ShortMappingTests.java[tags=basic-short-example-implicit] include::{example-dir-basic-mapping}/basic/ShortMappingTests.java[tags=basic-short-example-implicit]
---- ----
==== ====
@ -484,7 +486,7 @@ By default, Hibernate maps values of `Integer` / `int` to the `INTEGER` JDBC typ
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/IntegerMappingTests.java[tags=basic-integer-example-implicit] include::{example-dir-basic-mapping}/basic/IntegerMappingTests.java[tags=basic-integer-example-implicit]
---- ----
==== ====
@ -502,7 +504,7 @@ By default, Hibernate maps values of `Long` / `long` to the `BIGINT` JDBC type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/LongMappingTests.java[tags=basic-long-example-implicit] include::{example-dir-basic-mapping}/basic/LongMappingTests.java[tags=basic-long-example-implicit]
---- ----
==== ====
@ -521,7 +523,7 @@ By default, Hibernate maps values of `BigInteger` to the `NUMERIC` JDBC type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BigIntegerMappingTests.java[tags=basic-biginteger-example-implicit] include::{example-dir-basic-mapping}/basic/BigIntegerMappingTests.java[tags=basic-biginteger-example-implicit]
---- ----
==== ====
@ -541,12 +543,12 @@ By default, Hibernate maps values of `Double` to the `DOUBLE`, `FLOAT`, `REAL` o
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/DoubleMappingTests.java[tags=basic-double-example-implicit] include::{example-dir-basic-mapping}/basic/DoubleMappingTests.java[tags=basic-double-example-implicit]
---- ----
==== ====
A specific type can be influenced using any of the JDBC type influencers covered in A specific type can be influenced using any of the JDBC type influencers covered in
<<basic-mapping-explicit>> section. <<basic-mapping-composition-jdbc>> section.
If `@JdbcTypeCode` is used, the Dialect is still consulted to make sure the database If `@JdbcTypeCode` is used, the Dialect is still consulted to make sure the database
supports the requested type. If not, an appropriate type is selected supports the requested type. If not, an appropriate type is selected
@ -566,7 +568,7 @@ By default, Hibernate maps values of `Float` to the `FLOAT`, `REAL` or
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/FloatMappingTests.java[tags=basic-float-example-implicit] include::{example-dir-basic-mapping}/basic/FloatMappingTests.java[tags=basic-float-example-implicit]
---- ----
==== ====
@ -590,7 +592,7 @@ By default, Hibernate maps values of `BigDecimal` to the `NUMERIC` JDBC type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BigDecimalMappingTests.java[tags=basic-bigdecimal-example-implicit] include::{example-dir-basic-mapping}/basic/BigDecimalMappingTests.java[tags=basic-bigdecimal-example-implicit]
---- ----
==== ====
@ -608,7 +610,7 @@ By default, Hibernate maps `Character` to the `CHAR` JDBC type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/CharacterMappingTests.java[tags=basic-character-example-implicit] include::{example-dir-basic-mapping}/basic/CharacterMappingTests.java[tags=basic-character-example-implicit]
---- ----
==== ====
@ -626,7 +628,7 @@ By default, Hibernate maps `String` to the `VARCHAR` JDBC type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/StringMappingTests.java[tags=basic-string-example] include::{example-dir-basic-mapping}/basic/StringMappingTests.java[tags=basic-string-example]
---- ----
==== ====
@ -673,7 +675,7 @@ nationalized data.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/StringNationalizedMappingTests.java[tags=basic-nstring-example] include::{example-dir-basic-mapping}/basic/StringNationalizedMappingTests.java[tags=basic-nstring-example]
---- ----
==== ====
@ -694,7 +696,7 @@ By default, Hibernate maps `Character[]` and `char[]` to the `VARCHAR` JDBC type
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/CharacterArrayMappingTests.java[tags=basic-chararray-example] include::{example-dir-basic-mapping}/basic/CharacterArrayMappingTests.java[tags=basic-chararray-example]
---- ----
==== ====
@ -708,7 +710,7 @@ nationalized data.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/CharacterArrayNationalizedMappingTests.java[tags=basic-nchararray-example] include::{example-dir-basic-mapping}/basic/CharacterArrayNationalizedMappingTests.java[tags=basic-nchararray-example]
---- ----
==== ====
@ -747,7 +749,7 @@ Let's first map this using the `@Lob` Jakarta Persistence annotation and the `ja
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ClobTest.java[tags=basic-clob-example] include::{example-dir-basic-mapping}/basic/ClobTest.java[tags=basic-clob-example]
---- ----
==== ====
@ -758,7 +760,7 @@ To persist such an entity, you have to create a `Clob` using the `ClobProxy` Hib
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ClobTest.java[tags=basic-clob-persist-example] include::{example-dir-basic-mapping}/basic/ClobTest.java[tags=basic-clob-persist-example]
---- ----
==== ====
@ -769,7 +771,7 @@ To retrieve the `Clob` content, you need to transform the underlying `java.io.Re
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ClobTest.java[tags=basic-clob-find-example] include::{example-dir-basic-mapping}/basic/ClobTest.java[tags=basic-clob-find-example]
---- ----
==== ====
@ -780,7 +782,7 @@ We could also map the CLOB in a materialized form. This way, we can either use a
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ClobStringTest.java[tags=basic-clob-string-example] include::{example-dir-basic-mapping}/basic/ClobStringTest.java[tags=basic-clob-string-example]
---- ----
==== ====
@ -791,7 +793,7 @@ We might even want the materialized data as a char array.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ClobCharArrayTest.java[tags=basic-clob-char-array-example] include::{example-dir-basic-mapping}/basic/ClobCharArrayTest.java[tags=basic-clob-char-array-example]
---- ----
==== ====
@ -813,7 +815,7 @@ Hibernate can map the `NCLOB` to a `java.sql.NClob`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/NClobTest.java[tags=basic-nclob-example] include::{example-dir-basic-mapping}/basic/NClobTest.java[tags=basic-nclob-example]
---- ----
==== ====
@ -824,7 +826,7 @@ To persist such an entity, you have to create an `NClob` using the `NClobProxy`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/NClobTest.java[tags=basic-nclob-persist-example] include::{example-dir-basic-mapping}/basic/NClobTest.java[tags=basic-nclob-persist-example]
---- ----
==== ====
@ -835,7 +837,7 @@ To retrieve the `NClob` content, you need to transform the underlying `java.io.R
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/NClobTest.java[tags=basic-nclob-find-example] include::{example-dir-basic-mapping}/basic/NClobTest.java[tags=basic-nclob-find-example]
---- ----
==== ====
@ -846,7 +848,7 @@ We could also map the `NCLOB` in a materialized form. This way, we can either us
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/NClobStringTest.java[tags=basic-nclob-string-example] include::{example-dir-basic-mapping}/basic/NClobStringTest.java[tags=basic-nclob-string-example]
---- ----
==== ====
@ -857,7 +859,7 @@ We might even want the materialized data as a char array.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/NClobCharArrayTest.java[tags=basic-nclob-char-array-example] include::{example-dir-basic-mapping}/basic/NClobCharArrayTest.java[tags=basic-nclob-char-array-example]
---- ----
==== ====
@ -878,7 +880,7 @@ By default, Hibernate maps values of type `byte[]` and `Byte[]` to the JDBC type
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ByteArrayMappingTests.java[tags=basic-bytearray-example] include::{example-dir-basic-mapping}/basic/ByteArrayMappingTests.java[tags=basic-bytearray-example]
---- ----
==== ====
@ -936,7 +938,7 @@ Let's first map this using the JDBC `java.sql.Blob` type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BlobTest.java[tags=basic-blob-example] include::{example-dir-basic-mapping}/basic/BlobTest.java[tags=basic-blob-example]
---- ----
==== ====
@ -947,7 +949,7 @@ To persist such an entity, you have to create a `Blob` using the `BlobProxy` Hib
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BlobTest.java[tags=basic-blob-persist-example] include::{example-dir-basic-mapping}/basic/BlobTest.java[tags=basic-blob-persist-example]
---- ----
==== ====
@ -958,7 +960,7 @@ To retrieve the `Blob` content, you need to transform the underlying `java.io.In
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BlobTest.java[tags=basic-blob-find-example] include::{example-dir-basic-mapping}/basic/BlobTest.java[tags=basic-blob-find-example]
---- ----
==== ====
@ -969,7 +971,7 @@ We could also map the BLOB in a materialized form (e.g. `byte[]`).
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BlobByteArrayTest.java[tags=basic-blob-byte-array-example] include::{example-dir-basic-mapping}/basic/BlobByteArrayTest.java[tags=basic-blob-byte-array-example]
---- ----
==== ====
@ -989,7 +991,7 @@ TIP: It's possible to map `Duration` to the `INTERVAL_SECOND` SQL type using `@J
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/DurationMappingTests.java[tags=basic-duration-example] include::{example-dir-basic-mapping}/basic/DurationMappingTests.java[tags=basic-duration-example]
---- ----
==== ====
@ -1007,7 +1009,7 @@ include::{sourcedir}/basic/DurationMappingTests.java[tags=basic-duration-example
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/InstantMappingTests.java[tags=basic-instant-example] include::{example-dir-basic-mapping}/basic/InstantMappingTests.java[tags=basic-instant-example]
---- ----
==== ====
@ -1028,7 +1030,7 @@ See <<basic-temporal>> for basics of temporal mapping
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/LocalDateMappingTests.java[tags=basic-localDate-example] include::{example-dir-basic-mapping}/basic/LocalDateMappingTests.java[tags=basic-localDate-example]
---- ----
==== ====
@ -1049,7 +1051,7 @@ See <<basic-temporal>> for basics of temporal mapping
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/LocalDateTimeMappingTests.java[tags=basic-localDateTime-example] include::{example-dir-basic-mapping}/basic/LocalDateTimeMappingTests.java[tags=basic-localDateTime-example]
---- ----
==== ====
@ -1070,7 +1072,7 @@ See <<basic-temporal>> for basics of temporal mapping
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/LocalTimeMappingTests.java[tags=basic-localTime-example] include::{example-dir-basic-mapping}/basic/LocalTimeMappingTests.java[tags=basic-localTime-example]
---- ----
==== ====
@ -1093,7 +1095,7 @@ depending on the database.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/OffsetDateTimeMappingTests.java[tags=basic-OffsetDateTime-example] include::{example-dir-basic-mapping}/basic/OffsetDateTimeMappingTests.java[tags=basic-OffsetDateTime-example]
---- ----
==== ====
@ -1119,7 +1121,7 @@ depending on the database.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/OffsetTimeMappingTests.java[tags=basic-offsetTime-example] include::{example-dir-basic-mapping}/basic/OffsetTimeMappingTests.java[tags=basic-offsetTime-example]
---- ----
==== ====
@ -1141,7 +1143,7 @@ See <<basic-datetime-time-zone>> for basics of time-zone handling
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/TimeZoneMappingTests.java[tags=basic-timeZone-example] include::{example-dir-basic-mapping}/basic/TimeZoneMappingTests.java[tags=basic-timeZone-example]
---- ----
==== ====
@ -1163,7 +1165,7 @@ depending on the database.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ZonedDateTimeMappingTests.java[tags=basic-ZonedDateTime-example] include::{example-dir-basic-mapping}/basic/ZonedDateTimeMappingTests.java[tags=basic-ZonedDateTime-example]
---- ----
==== ====
@ -1187,7 +1189,7 @@ See <<basic-datetime-time-zone>> for basics of time-zone handling
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ZoneOffsetMappingTests.java[tags=basic-ZoneOffset-example] include::{example-dir-basic-mapping}/basic/ZoneOffsetMappingTests.java[tags=basic-ZoneOffset-example]
---- ----
==== ====
@ -1257,7 +1259,7 @@ Hibernate maps `Class` references to `VARCHAR` JDBC type
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ClassMappingTests.java[tags=basic-Class-example] include::{example-dir-basic-mapping}/basic/ClassMappingTests.java[tags=basic-Class-example]
---- ----
==== ====
@ -1272,7 +1274,7 @@ Hibernate maps `Currency` references to `VARCHAR` JDBC type
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/CurrencyMappingTests.java[tags=basic-Currency-example] include::{example-dir-basic-mapping}/basic/CurrencyMappingTests.java[tags=basic-Currency-example]
---- ----
==== ====
@ -1287,7 +1289,7 @@ Hibernate maps `Locale` references to `VARCHAR` JDBC type
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/LocaleMappingTests.java[tags=basic-Locale-example] include::{example-dir-basic-mapping}/basic/LocaleMappingTests.java[tags=basic-Locale-example]
---- ----
==== ====
@ -1338,7 +1340,7 @@ By default, Hibernate will map `InetAddress` to the `INET` SQL type and fallback
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/InetAddressMappingTests.java[tags=basic-inet-address-example] include::{example-dir-basic-mapping}/basic/InetAddressMappingTests.java[tags=basic-inet-address-example]
---- ----
==== ====
@ -1355,7 +1357,7 @@ as can be read in the <<appendices/Configurations.adoc#misc-options,Configuratio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/JsonMappingTests.java[tags=basic-json-example] include::{example-dir-basic-mapping}/basic/JsonMappingTests.java[tags=basic-json-example]
---- ----
==== ====
@ -1372,7 +1374,7 @@ as can be read in the <<appendices/Configurations.adoc#misc-options,Configuratio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/XmlMappingTests.java[tags=basic-xml-example] include::{example-dir-basic-mapping}/basic/XmlMappingTests.java[tags=basic-xml-example]
---- ----
==== ====
@ -1390,7 +1392,7 @@ depending on the database support as determined via the new method `org.hibernat
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BasicArrayMappingTests.java[tags=basic-array-example] include::{example-dir-basic-mapping}/basic/BasicArrayMappingTests.java[tags=basic-array-example]
---- ----
==== ====
@ -1408,7 +1410,7 @@ depending on the database support as determined via the new method `org.hibernat
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/BasicCollectionMappingTests.java[tags=basic-collection-example] include::{example-dir-basic-mapping}/basic/BasicCollectionMappingTests.java[tags=basic-collection-example]
---- ----
==== ====
@ -1661,7 +1663,7 @@ To map a specific attribute to a nationalized variant data type, Hibernate defin
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/NationalizedTest.java[tags=basic-nationalized-example] include::{example-dir-basic-mapping}/basic/NationalizedTest.java[tags=basic-nationalized-example]
---- ----
==== ====
@ -1772,7 +1774,7 @@ use `@Temporal`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/DatePrecisionTests.java[tags=basic-temporal-example] include::{example-dir-basic-mapping}/basic/DatePrecisionTests.java[tags=basic-temporal-example]
---- ----
==== ====
@ -1873,7 +1875,7 @@ Due to this, storing the offset is only safe for past timestamps, and we advise
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/TimeZoneStorageMappingTests.java[tags=time-zone-column-examples-mapping-example] include::{example-dir-basic-mapping}/basic/TimeZoneStorageMappingTests.java[tags=time-zone-column-examples-mapping-example]
---- ----
==== ====
@ -1893,7 +1895,7 @@ In the following example, the `java.time.Period` is going to be mapped to a `VAR
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/PeriodStringConverter.java[tags=basic-jpa-convert-period-string-converter-example] include::{example-dir-basic-mapping}/converter/PeriodStringConverter.java[tags=basic-jpa-convert-period-string-converter-example]
---- ----
==== ====
@ -1904,7 +1906,7 @@ To make use of this custom converter, the `@Convert` annotation must decorate th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-mapping-example] include::{example-dir-basic-mapping}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-mapping-example]
---- ----
==== ====
@ -1966,7 +1968,7 @@ Let's consider we have an application-specific `Money` type:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/hbm/Money.java[tags=basic-hbm-attribute-converter-mapping-money-example] include::{example-dir-basic-mapping}/converter/hbm/Money.java[tags=basic-hbm-attribute-converter-mapping-money-example]
---- ----
==== ====
@ -1977,7 +1979,7 @@ Now, we want to use the `Money` type when mapping the `Account` entity:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/hbm/Account.java[tags=basic-hbm-attribute-converter-mapping-account-example] include::{example-dir-basic-mapping}/converter/hbm/Account.java[tags=basic-hbm-attribute-converter-mapping-account-example]
---- ----
==== ====
@ -1990,7 +1992,7 @@ to transform the `Money` type as a `Long`. For this purpose, we are going to use
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/hbm/MoneyConverter.java[tags=basic-hbm-attribute-converter-mapping-moneyconverter-example] include::{example-dir-basic-mapping}/converter/hbm/MoneyConverter.java[tags=basic-hbm-attribute-converter-mapping-moneyconverter-example]
---- ----
==== ====
@ -2002,7 +2004,7 @@ attribute of the `property` element.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{resourcedir}/mapping/converter/hbm/MoneyConverterHbmTest.hbm.xml[] include::{example-dir-resources}/mapping/converter/hbm/MoneyConverterHbmTest.hbm.xml[]
---- ----
==== ====
@ -2036,14 +2038,14 @@ Considering we have the same `Period` entity attribute as illustrated in the <<b
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-mapping-example] include::{example-dir-basic-mapping}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-mapping-example]
---- ----
The only way to change the `span` attribute is to reassign it to a different value: The only way to change the `span` attribute is to reassign it to a different value:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-immutability-plan-example] include::{example-dir-basic-mapping}/converter/PeriodStringTest.java[tags=basic-jpa-convert-period-string-converter-immutability-plan-example]
---- ----
====== Mutable types ====== Mutable types
@ -2052,14 +2054,14 @@ On the other hand, consider the following example where the `Money` type is a mu
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/MoneyConverterTest.java[tags=basic-jpa-convert-money-converter-mapping-example] include::{example-dir-basic-mapping}/converter/MoneyConverterTest.java[tags=basic-jpa-convert-money-converter-mapping-example]
---- ----
A mutable `Object` allows you to modify its internal structure, and Hibernate's dirty checking mechanism is going to propagate the change to the database: A mutable `Object` allows you to modify its internal structure, and Hibernate's dirty checking mechanism is going to propagate the change to the database:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/converter/MoneyConverterTest.java[tags=basic-jpa-convert-money-converter-mutability-plan-example] include::{example-dir-basic-mapping}/converter/MoneyConverterTest.java[tags=basic-jpa-convert-money-converter-mutability-plan-example]
---- ----
[TIP] [TIP]
@ -2082,7 +2084,7 @@ Assuming you have the following entity:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{converter-sourcedir}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-entity-example] include::{example-dir-converter}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-entity-example]
---- ----
==== ====
@ -2093,7 +2095,7 @@ And the `Caption` class looks as follows:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{converter-sourcedir}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-object-example] include::{example-dir-converter}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-object-example]
---- ----
==== ====
@ -2104,7 +2106,7 @@ And we have an `AttributeConverter` to handle the `Caption` Java object:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{converter-sourcedir}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-converter-example] include::{example-dir-converter}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-converter-example]
---- ----
==== ====
@ -2115,7 +2117,7 @@ Traditionally, you could only use the DB data `Caption` representation, which in
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{converter-sourcedir}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-converter-dbdata-example] include::{example-dir-converter}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-converter-dbdata-example]
---- ----
==== ====
@ -2126,7 +2128,7 @@ In order to use the Java object `Caption` representation, you have to get the as
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{converter-sourcedir}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-converter-object-example] include::{example-dir-converter}/ConverterTest.java[tags=basic-attribute-converter-query-parameter-converter-object-example]
---- ----
==== ====
@ -2191,7 +2193,7 @@ We've covered many ways to specify basic value mappings so far. This section wi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetImplicitTests.java[tags=basic-bitset-example-implicit] include::{example-dir-basic-mapping}/basic/bitset/BitSetImplicitTests.java[tags=basic-bitset-example-implicit]
---- ----
==== ====
@ -2215,9 +2217,9 @@ This works well in most cases and is portable across Jakarta Persistence provide
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetConverterTests.java[tags=basic-bitset-example-convert] include::{example-dir-basic-mapping}/basic/bitset/BitSetConverterTests.java[tags=basic-bitset-example-convert]
include::{sourcedir}/basic/bitset/BitSetConverterTests.java[tags=basic-bitset-example-converter] include::{example-dir-basic-mapping}/basic/bitset/BitSetConverterTests.java[tags=basic-bitset-example-converter]
---- ----
==== ====
@ -2247,7 +2249,7 @@ for `BitSet` that maps values to `VARCHAR` for storage by default.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetJavaType.java[tags=basic-bitset-example-java-type] include::{example-dir-basic-mapping}/basic/bitset/BitSetJavaType.java[tags=basic-bitset-example-java-type]
---- ----
==== ====
@ -2259,7 +2261,7 @@ We can either apply that type locally using `@JavaType`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetJavaTypeTests.java[tags=basic-bitset-example-java-type-local,indent=0] include::{example-dir-basic-mapping}/basic/bitset/BitSetJavaTypeTests.java[tags=basic-bitset-example-java-type-local,indent=0]
---- ----
==== ====
@ -2271,7 +2273,7 @@ to be used as the default whenever we encounter the `BitSet` type
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetJavaTypeRegistrationTests.java[tags=basic-bitset-example-java-type-global,indent=0] include::{example-dir-basic-mapping}/basic/bitset/BitSetJavaTypeRegistrationTests.java[tags=basic-bitset-example-java-type-global,indent=0]
---- ----
==== ====
@ -2297,7 +2299,7 @@ serialization.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetJdbcTypeCodeTests.java[tags=basic-bitset-example-jdbc-type-code,indent=0] include::{example-dir-basic-mapping}/basic/bitset/BitSetJdbcTypeCodeTests.java[tags=basic-bitset-example-jdbc-type-code,indent=0]
---- ----
==== ====
@ -2310,7 +2312,7 @@ In this example, `@JdbcTypeCode` has been used to indicate that the `JdbcType` r
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetJdbcTypeTests.java[tags=basic-bitset-example-jdbc-type-local,indent=0] include::{example-dir-basic-mapping}/basic/bitset/BitSetJdbcTypeTests.java[tags=basic-bitset-example-jdbc-type-local,indent=0]
---- ----
==== ====
@ -2325,7 +2327,7 @@ We could instead replace how Hibernate deals with all `VARBINARY` handling with
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/bitset/BitSetJdbcTypeRegistrationTests.java[tags=basic-bitset-example-jdbc-type-global,indent=0] include::{example-dir-basic-mapping}/basic/bitset/BitSetJdbcTypeRegistrationTests.java[tags=basic-bitset-example-jdbc-type-global,indent=0]
---- ----
==== ====
@ -2349,7 +2351,7 @@ This is usually double quotes, but SQL Server uses brackets and MySQL uses backt
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/QuotingTest.java[tags=basic-quoting-example] include::{example-dir-basic-mapping}/basic/QuotingTest.java[tags=basic-quoting-example]
---- ----
==== ====
@ -2358,7 +2360,7 @@ include::{sourcedir}/basic/QuotingTest.java[tags=basic-quoting-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/JpaQuotingTest.java[tags=basic-jpa-quoting-example] include::{example-dir-basic-mapping}/basic/JpaQuotingTest.java[tags=basic-jpa-quoting-example]
---- ----
==== ====
@ -2371,7 +2373,7 @@ When saving the following `Product entity`, Hibernate generates the following SQ
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/QuotingTest.java[tags=basic-quoting-persistence-example, indent=0] include::{example-dir-basic-mapping}/basic/QuotingTest.java[tags=basic-quoting-persistence-example, indent=0]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -2402,7 +2404,7 @@ This way, we don't need to manually quote any identifier:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/AutoQuotingTest.java[tags=basic-auto-quoting-example] include::{example-dir-basic-mapping}/basic/AutoQuotingTest.java[tags=basic-auto-quoting-example]
---- ----
==== ====
@ -2489,7 +2491,7 @@ It uses the database's `current_timestamp` function as the generated value
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{core-generated-test-dir}/CurrentTimestampAnnotationTests.java[tags=mapping-generated-CurrentTimestamp-ex1] include::{example-dir-generated}/CurrentTimestampAnnotationTests.java[tags=mapping-generated-CurrentTimestamp-ex1]
---- ----
==== ====
@ -2508,7 +2510,7 @@ Supports most temporal types (`java.time.Instant`, `java.util.Date`, `java.util.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/generated/CreationTimestampTest.java[tags=mapping-generated-provided-creation-ex1] include::{example-dir-basic-mapping}/generated/CreationTimestampTest.java[tags=mapping-generated-provided-creation-ex1]
---- ----
==== ====
@ -2529,7 +2531,7 @@ Supports most temporal types (`java.time.Instant`, `java.util.Date`, `java.util.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/generated/UpdateTimestampTest.java[tags=mapping-generated-provided-update-ex1] include::{example-dir-basic-mapping}/generated/UpdateTimestampTest.java[tags=mapping-generated-provided-update-ex1]
---- ----
==== ====
@ -2548,7 +2550,7 @@ This is the legacy mapping for in-DB generated values.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/generated/GeneratedTest.java[tags=mapping-generated-provided-generated] include::{example-dir-basic-mapping}/generated/GeneratedTest.java[tags=mapping-generated-provided-generated]
---- ----
==== ====
@ -2567,7 +2569,7 @@ Let's look at an example of generating UUID values. First the attribute mapping
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{core-generated-test-dir}/temporals/GeneratedUuidTests.java[tags=mapping-generated-custom-ex1] include::{example-dir-generated}/temporals/GeneratedUuidTests.java[tags=mapping-generated-custom-ex1]
---- ----
==== ====
@ -2579,7 +2581,7 @@ annotations provided by the application.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{core-generated-test-dir}/temporals/GeneratedUuidTests.java[tags=mapping-generated-custom-ex2] include::{example-dir-generated}/temporals/GeneratedUuidTests.java[tags=mapping-generated-custom-ex2]
---- ----
==== ====
@ -2591,7 +2593,7 @@ Hibernate how to generate values for the attribute - here it will use the specif
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{core-generated-test-dir}/temporals/GeneratedUuidTests.java[tags=mapping-generated-custom-ex3] include::{example-dir-generated}/temporals/GeneratedUuidTests.java[tags=mapping-generated-custom-ex3]
---- ----
==== ====
@ -2613,7 +2615,7 @@ For example, if your database provides a set of data encryption functions, you c
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/../fetching/FetchingTest.java[tags=mapping-column-read-and-write-example] include::{example-dir-basic-mapping}/../fetching/FetchingTest.java[tags=mapping-column-read-and-write-example]
---- ----
==== ====
@ -2624,12 +2626,12 @@ If a property uses more than one column, you must use the `forColumn` attribute
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ColumnTransformerTest.java[tags=mapping-column-read-and-write-composite-type-example] include::{example-dir-basic-mapping}/basic/ColumnTransformerTest.java[tags=mapping-column-read-and-write-composite-type-example]
---- ----
==== ====
Hibernate applies the custom expressions automatically whenever the property is referenced in a query. Hibernate applies the custom expressions automatically whenever the property is referenced in a query.
This functionality is similar to a derived-property <<mapping-column-formula>> with two differences: This functionality is similar to a derived-property <<basic-formula-annotation>> with two differences:
* The property is backed by one or more columns that are exported as part of automatic schema generation. * The property is backed by one or more columns that are exported as part of automatic schema generation.
* The property is read-write, not read-only. * The property is read-write, not read-only.
@ -2641,7 +2643,7 @@ The `write` expression, if specified, must contain exactly one '?' placeholder f
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/ColumnTransformerTest.java[tags=mapping-column-read-and-write-composite-type-persistence-example] include::{example-dir-basic-mapping}/basic/ColumnTransformerTest.java[tags=mapping-column-read-and-write-composite-type-persistence-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,16 +1,16 @@
[[collections]] [[collections]]
=== Collections === Collections
:rootProjectDir: ../../../../../../.. :majorMinorVersion: 6.2
:documentationProjectDir: {rootProjectDir}/documentation :root-project-dir: ../../../../../../..
:docTestsDir: ../../../../../test/java/org/hibernate/userguide/collections :documentation-project-dir: {root-project-dir}/documentation
:coreProjectDir: {rootProjectDir}/hibernate-core :example-dir-collection-doc: {documentation-project-dir}/src/test/java/org/hibernate/userguide/collections
:coreTestsDir: {coreProjectDir}/src/test/java :core-project-dir: {root-project-dir}/hibernate-core
:coreCollectionTestsDir: {coreTestsDir}/org/hibernate/orm/test/mapping/collections :core-test-base: {core-project-dir}/src/test/java
:classificationTestsDir: {coreCollectionTestsDir}/classification :example-dir-collection: {core-test-base}/org/hibernate/orm/test/mapping/collections
:extrasdir: extras/collections :docs-base: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}
:docs-base: https://docs.jboss.org/hibernate/orm/6.0
:javadoc-base: {docs-base}/javadoc :javadoc-base: {docs-base}/javadoc
:java-javadoc-base: https://docs.oracle.com/en/java/javase/11/docs/api/java.base :java-javadoc-base: https://docs.oracle.com/en/java/javase/11/docs/api/java.base
:extrasdir: extras/collections
Hibernate supports mapping collections (`java.util.Collection` and `java.util.Map` subtypes) Hibernate supports mapping collections (`java.util.Collection` and `java.util.Map` subtypes)
in a variety of ways. in a variety of ways.
@ -80,7 +80,7 @@ interpretation as to which classification it fits in to, using the following che
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/list/EntityWithList.java[tags=collections-list-ex] include::{example-dir-collection}/classification/list/EntityWithList.java[tags=collections-list-ex]
---- ----
==== ====
@ -108,7 +108,7 @@ The default column name that stores the index is derived from the attribute name
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/list/EntityWithOrderColumnList.java[tags=collections-list-ordercolumn-ex] include::{example-dir-collection}/classification/list/EntityWithOrderColumnList.java[tags=collections-list-ordercolumn-ex]
---- ----
==== ====
@ -125,7 +125,7 @@ cases using its `@ListIndexBase` annotation.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/list/EntityWithIndexBasedList.java[tags=collections-list-indexbase-ex] include::{example-dir-collection}/classification/list/EntityWithIndexBasedList.java[tags=collections-list-indexbase-ex]
---- ----
==== ====
@ -145,7 +145,7 @@ mapping sets according to the requirements of the `java.util.Set`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/set/EntityWithSet.java[tags=collections-set-ex] include::{example-dir-collection}/classification/set/EntityWithSet.java[tags=collections-set-ex]
---- ----
==== ====
@ -172,9 +172,9 @@ this implies that the element type is `Comparable`. E.g.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/Name.java[tags=collections-name-ex] include::{example-dir-collection}/classification/Name.java[tags=collections-name-ex]
include::{classificationTestsDir}/set/EntityWithNaturallySortedSet.java[tags=collections-sortedset-natural-ex] include::{example-dir-collection}/classification/set/EntityWithNaturallySortedSet.java[tags=collections-sortedset-natural-ex]
---- ----
==== ====
@ -189,9 +189,9 @@ the `Names` as sorted by a `NameComparator`:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/NameComparator.java[tags=collections-name-comparator-ex] include::{example-dir-collection}/classification/NameComparator.java[tags=collections-name-comparator-ex]
include::{classificationTestsDir}/set/EntityWithSortedSet.java[tags=collections-sortedset-comparator-ex] include::{example-dir-collection}/classification/set/EntityWithSortedSet.java[tags=collections-sortedset-comparator-ex]
---- ----
==== ====
@ -232,7 +232,7 @@ are handled is largely undefined.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/bag/EntityWithBagAsCollection.java[tags=collections-bag-ex] include::{example-dir-collection}/classification/bag/EntityWithBagAsCollection.java[tags=collections-bag-ex]
---- ----
==== ====
@ -244,7 +244,7 @@ lists as bags. First an explicit annotation
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{classificationTestsDir}/bag/EntityWithBagAsList.java[tags=collections-bag-list-ex] include::{example-dir-collection}/classification/bag/EntityWithBagAsList.java[tags=collections-bag-list-ex]
---- ----
==== ====
@ -302,7 +302,7 @@ The embeddable used in the examples is a `PhoneNumber` -
==== ====
[source,java] [source,java]
---- ----
include::{coreCollectionTestsDir}/nature/elemental/Phone.java[tags=ex-collection-elemental-model,indent=0] include::{example-dir-collection}/nature/elemental/Phone.java[tags=ex-collection-elemental-model,indent=0]
---- ----
==== ====
@ -314,7 +314,7 @@ First, a BAG mapping -
==== ====
[source,java] [source,java]
---- ----
include::{coreCollectionTestsDir}/nature/elemental/ElementalBagTest.java[tags=ex-collection-elemental-model,indent=0] include::{example-dir-collection}/nature/elemental/ElementalBagTest.java[tags=ex-collection-elemental-model,indent=0]
---- ----
==== ====
@ -324,7 +324,7 @@ include::{coreCollectionTestsDir}/nature/elemental/ElementalBagTest.java[tags=ex
==== ====
[source,java] [source,java]
---- ----
include::{coreCollectionTestsDir}/nature/elemental/ElementalBagTest.java[tags=ex-collection-elemental-lifecycle,indent=0] include::{example-dir-collection}/nature/elemental/ElementalBagTest.java[tags=ex-collection-elemental-lifecycle,indent=0]
---- ----
[source,sql] [source,sql]
@ -382,7 +382,7 @@ cross between the ordered-ness of a `List` and the uniqueness of a `Set`. First
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{coreCollectionTestsDir}/semantics/TheEntityWithUniqueList.java[tags=ex-collections-custom-type-model] include::{example-dir-collection}/semantics/TheEntityWithUniqueList.java[tags=ex-collections-custom-type-model]
---- ----
==== ====
@ -393,7 +393,7 @@ The mapping says to use the `UniqueListType` class for the mapping of the plural
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{coreCollectionTestsDir}/semantics/UniqueListType.java[tags=collections-custom-type-ex] include::{example-dir-collection}/semantics/UniqueListType.java[tags=collections-custom-type-ex]
---- ----
==== ====
@ -404,7 +404,7 @@ Most custom `UserCollectionType` implementations will want their own `Persistent
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{coreCollectionTestsDir}/semantics/UniqueListWrapper.java[tags=collections-custom-semantics-ex] include::{example-dir-collection}/semantics/UniqueListWrapper.java[tags=collections-custom-semantics-ex]
---- ----
==== ====
@ -424,7 +424,7 @@ plural attributes of a given classification, Hibernate also provides the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{coreCollectionTestsDir}/semantics/TheEntityWithUniqueListRegistration.java[tags=ex-collections-custom-type-model] include::{example-dir-collection}/semantics/TheEntityWithUniqueListRegistration.java[tags=ex-collections-custom-type-model]
---- ----
==== ====
@ -484,7 +484,7 @@ Behind the scenes, Hibernate requires an association table to manage the parent-
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalBagTest.java[tags=collections-unidirectional-bag-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalBagTest.java[tags=collections-unidirectional-bag-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -507,7 +507,7 @@ By marking the parent side with the `CascadeType.ALL` attribute, the unidirectio
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalBagTest.java[tags=collections-unidirectional-bag-lifecycle-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalBagTest.java[tags=collections-unidirectional-bag-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -536,7 +536,7 @@ The `@ManyToOne` side is the owning side of the bidirectional bag association, w
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalBagTest.java[tags=collections-bidirectional-bag-example,indent=0] include::{example-dir-collection-doc}/BidirectionalBagTest.java[tags=collections-bidirectional-bag-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -550,7 +550,7 @@ include::{extrasdir}/collections-bidirectional-bag-example.sql[]
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalBagTest.java[tags=collections-bidirectional-bag-lifecycle-example,indent=0] include::{example-dir-collection-doc}/BidirectionalBagTest.java[tags=collections-bidirectional-bag-lifecycle-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -564,7 +564,7 @@ include::{extrasdir}/collections-bidirectional-bag-lifecycle-example.sql[]
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalBagOrphanRemovalTest.java[tags=collections-bidirectional-bag-orphan-removal-example,indent=0] include::{example-dir-collection-doc}/BidirectionalBagOrphanRemovalTest.java[tags=collections-bidirectional-bag-orphan-removal-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -594,7 +594,7 @@ When using the `@OrderBy` annotation, the mapping looks as follows:
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalOrderedByListTest.java[tags=collections-unidirectional-ordered-list-order-by-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalOrderedByListTest.java[tags=collections-unidirectional-ordered-list-order-by-example,indent=0]
---- ----
==== ====
@ -626,7 +626,7 @@ Another ordering option is to use the `@OrderColumn` annotation:
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalOrderColumnListTest.java[tags=collections-unidirectional-ordered-list-order-column-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalOrderColumnListTest.java[tags=collections-unidirectional-ordered-list-order-column-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -659,7 +659,7 @@ The mapping is similar with the <<collections-bidirectional-bag>> example, just
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalOrderByListTest.java[tags=collections-bidirectional-ordered-list-order-by-example,indent=0] include::{example-dir-collection-doc}/BidirectionalOrderByListTest.java[tags=collections-bidirectional-ordered-list-order-by-example,indent=0]
---- ----
==== ====
@ -672,7 +672,7 @@ When using the `@OrderColumn` annotation, the `order_id` column is going to be e
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalOrderColumnListTest.java[tags=collections-bidirectional-ordered-list-order-column-example,indent=0] include::{example-dir-collection-doc}/BidirectionalOrderColumnListTest.java[tags=collections-bidirectional-ordered-list-order-column-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -693,7 +693,7 @@ You can customize the ordinal of the underlying ordered list by using the https:
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-mapping-example,indent=0] include::{example-dir-collection-doc}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-mapping-example,indent=0]
---- ----
==== ====
@ -704,7 +704,7 @@ When inserting two `Phone` records, Hibernate is going to start the List index f
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-persist-example,indent=0] include::{example-dir-collection-doc}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-persist-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -729,7 +729,7 @@ by the number of characters of the `name` attribute.
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/OrderedBySQLTest.java[tags=collections-customizing-ordered-by-sql-clause-mapping-example,indent=0] include::{example-dir-collection-doc}/OrderedBySQLTest.java[tags=collections-customizing-ordered-by-sql-clause-mapping-example,indent=0]
---- ----
==== ====
@ -740,7 +740,7 @@ When fetching the `articles` collection, Hibernate uses the ORDER BY SQL clause
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/OrderedBySQLTest.java[tags=collections-customizing-ordered-by-sql-clause-fetching-example,indent=0] include::{example-dir-collection-doc}/OrderedBySQLTest.java[tags=collections-customizing-ordered-by-sql-clause-fetching-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -764,7 +764,7 @@ The unidirectional set uses a link table to hold the parent-child associations a
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalSetTest.java[tags=collections-unidirectional-set-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalSetTest.java[tags=collections-unidirectional-set-example,indent=0]
---- ----
==== ====
@ -789,7 +789,7 @@ The lifecycle is just like with bidirectional bags except for the duplicates whi
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalSetTest.java[tags=collections-bidirectional-set-example,indent=0] include::{example-dir-collection-doc}/BidirectionalSetTest.java[tags=collections-bidirectional-set-example,indent=0]
---- ----
==== ====
@ -809,7 +809,7 @@ A `SortedSet` that relies on the natural sorting order given by the child elemen
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalSortedSetTest.java[tags=collections-unidirectional-sorted-set-natural-comparator-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalSortedSetTest.java[tags=collections-unidirectional-sorted-set-natural-comparator-example,indent=0]
---- ----
==== ====
@ -822,7 +822,7 @@ To provide a custom sorting logic, Hibernate also provides a `@SortComparator` a
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalComparatorSortedSetTest.java[tags=collections-unidirectional-sorted-set-custom-comparator-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalComparatorSortedSetTest.java[tags=collections-unidirectional-sorted-set-custom-comparator-example,indent=0]
---- ----
==== ====
@ -836,9 +836,9 @@ The `@SortNatural` and `@SortComparator` work the same for bidirectional sorted
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalSortedSetTest.java[tags=collections-bidirectional-sorted-set-example,indent=0] include::{example-dir-collection-doc}/BidirectionalSortedSetTest.java[tags=collections-bidirectional-sorted-set-example,indent=0]
include::{docTestsDir}/UnidirectionalComparatorSortedSetTest.java[lines=75..77,indent=0] include::{example-dir-collection-doc}/UnidirectionalComparatorSortedSetTest.java[lines=75..77,indent=0]
---- ----
==== ====
@ -871,7 +871,7 @@ A map of value type must use the `@ElementCollection` annotation, just like valu
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/ElementCollectionMapTest.java[tags=collections-map-value-type-entity-key-example,indent=0] include::{example-dir-collection-doc}/ElementCollectionMapTest.java[tags=collections-map-value-type-entity-key-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -887,7 +887,7 @@ Adding entries to the map generates the following SQL statements:
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/ElementCollectionMapTest.java[tags=collections-map-value-type-entity-key-add-example,indent=0] include::{example-dir-collection-doc}/ElementCollectionMapTest.java[tags=collections-map-value-type-entity-key-add-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -925,7 +925,7 @@ Since we want to map all the calls by their associated `java.util.Date`, not by
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/MapKeyTypeTest.java[tags=collections-map-custom-key-type-mapping-example,indent=0] include::{example-dir-collection-doc}/MapKeyTypeTest.java[tags=collections-map-custom-key-type-mapping-example,indent=0]
---- ----
==== ====
@ -940,7 +940,7 @@ Considering you have the following `PhoneNumber` interface with an implementatio
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/MapKeyClassTest.java[tags=collections-map-key-class-type-mapping-example,indent=0] include::{example-dir-collection-doc}/MapKeyClassTest.java[tags=collections-map-key-class-type-mapping-example,indent=0]
---- ----
==== ====
@ -952,7 +952,7 @@ If you want to use the `PhoneNumber` interface as a `java.util.Map` key, then yo
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/MapKeyClassTest.java[tags=collections-map-key-class-mapping-example,indent=0] include::{example-dir-collection-doc}/MapKeyClassTest.java[tags=collections-map-key-class-mapping-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -969,7 +969,7 @@ Hibernate generates the following SQL statements:
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/MapKeyClassTest.java[tags=collections-map-key-class-persist-example,indent=0] include::{example-dir-collection-doc}/MapKeyClassTest.java[tags=collections-map-key-class-persist-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -986,7 +986,7 @@ Hibernate generates the following SQL statements:
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/MapKeyClassTest.java[tags=collections-map-key-class-fetch-example,indent=0] include::{example-dir-collection-doc}/MapKeyClassTest.java[tags=collections-map-key-class-fetch-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -1013,7 +1013,7 @@ The `@MapKey` annotation is used to define the entity attribute used as a key of
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/UnidirectionalMapTest.java[tags=collections-map-unidirectional-example,indent=0] include::{example-dir-collection-doc}/UnidirectionalMapTest.java[tags=collections-map-unidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -1034,7 +1034,7 @@ In the following example, you can see that `@MapKeyEnumerated` was used so that
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/BidirectionalMapTest.java[tags=collections-map-bidirectional-example,indent=0] include::{example-dir-collection-doc}/BidirectionalMapTest.java[tags=collections-map-bidirectional-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -1065,7 +1065,7 @@ By default, Hibernate will choose a BINARY type, as supported by the current `Di
==== ====
[source,java] [source,java]
---- ----
include::{docTestsDir}/ArrayTest.java[tags=collections-array-binary-example,indent=0] include::{example-dir-collection-doc}/ArrayTest.java[tags=collections-array-binary-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -1100,9 +1100,9 @@ is using an <<basic-jpa-convert,AttributeConverter>>.
==== ====
[source,java] [source,java]
---- ----
include::{coreCollectionTestsDir}/asbasic/CommaDelimitedStringsConverter.java[tags=ex-csv-converter,indent=0] include::{example-dir-collection}/asbasic/CommaDelimitedStringsConverter.java[tags=ex-csv-converter,indent=0]
include::{coreCollectionTestsDir}/asbasic/CommaDelimitedStringsConverterTests.java[tags=ex-csv-converter-model,indent=0] include::{example-dir-collection}/asbasic/CommaDelimitedStringsConverterTests.java[tags=ex-csv-converter-model,indent=0]
---- ----
==== ====

12
documentation/src/main/asciidoc/userguide/chapters/domain/customizing.adoc
View File

@ -1,8 +1,8 @@
[[domain-customizing]] [[domain-customizing]]
=== Customizing the domain model === Customizing the domain model
:rootProjectDir: ../../../../../../.. :root-project-dir: ../../../../../../..
:coreProjectDir: {rootProjectDir}/hibernate-core :core-project-dir: {root-project-dir}/hibernate-core
:attributeBinderTestDir: {coreProjectDir}/src/test/java/org/hibernate/orm/test/mapping/attributebinder :example-dir-attributebinder: {core-project-dir}/src/test/java/org/hibernate/orm/test/mapping/attributebinder
:extrasdir: extras :extrasdir: extras
For cases where Hibernate does not provide a built-in way to configure the domain For cases where Hibernate does not provide a built-in way to configure the domain
@ -18,9 +18,9 @@ An example:
==== ====
[source,java] [source,java]
---- ----
include::{attributeBinderTestDir}/YesNo.java[tag=attribute-binder-example, indent=0] include::{example-dir-attributebinder}/YesNo.java[tag=attribute-binder-example, indent=0]
include::{attributeBinderTestDir}/YesNoBinder.java[tag=attribute-binder-example, indent=0] include::{example-dir-attributebinder}/YesNoBinder.java[tag=attribute-binder-example, indent=0]
---- ----
==== ====
@ -32,4 +32,4 @@ it has the `@AttributeBinderType` meta-annotation and knows how to apply that th
Notice also that `@AttributeBinderType` provides a type-safe way to perform configuration because Notice also that `@AttributeBinderType` provides a type-safe way to perform configuration because
the `AttributeBinder` (`YesNoBinder`) is handed the custom annotation (`@YesNo`) to grab its configured the `AttributeBinder` (`YesNoBinder`) is handed the custom annotation (`@YesNo`) to grab its configured
attributes. `@YesNo` does not provide any attributes, but it easily could. Whatever `YesNoBinder` attributes. `@YesNo` does not provide any attributes, but it easily could. Whatever `YesNoBinder`
supports. supports.

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

@ -1,7 +1,9 @@
[[dynamic-model]] [[dynamic-model]]
=== Dynamic Model === Dynamic Model
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/dynamic :root-project-dir: ../../../../../../..
:mappingdir: ../../../../../test/resources/org/hibernate/userguide/mapping/dynamic :documentation-project-dir: {root-project-dir}/documentation
:example-dir-dynamic: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping/dynamic
:example-dir-resources: {documentation-project-dir}/src/test/resources/org/hibernate/userguide/mapping/dynamic
:extrasdir: extras :extrasdir: extras
[IMPORTANT] [IMPORTANT]
@ -26,7 +28,7 @@ Entity modes can now be mixed within a domain model; a dynamic entity might refe
==== ====
[source,xml] [source,xml]
---- ----
include::{mappingdir}/Book.hbm.xml[tag=mapping-model-dynamic-example, indent=0] include::{example-dir-resources}/Book.hbm.xml[tag=mapping-model-dynamic-example, indent=0]
---- ----
==== ====
@ -37,7 +39,7 @@ After you defined your entity mapping, you need to instruct Hibernate to use the
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/DynamicEntityTest.java[tag=mapping-model-dynamic-setting-example, indent=0] include::{example-dir-dynamic}/DynamicEntityTest.java[tag=mapping-model-dynamic-setting-example, indent=0]
---- ----
==== ====
@ -49,7 +51,7 @@ Hibernate is going to generate the following SQL statement:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/DynamicEntityTest.java[tag=mapping-model-dynamic-example, indent=0] include::{example-dir-dynamic}/DynamicEntityTest.java[tag=mapping-model-dynamic-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -66,4 +68,4 @@ However, as a result of the Hibernate mapping, the database schema can easily be
It is also interesting to note that dynamic models are great for certain integration use cases as well. It is also interesting to note that dynamic models are great for certain integration use cases as well.
Envers, for example, makes extensive use of dynamic models to represent the historical data. Envers, for example, makes extensive use of dynamic models to represent the historical data.
==== ====

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

@ -1,11 +1,13 @@
[[embeddables]] [[embeddables]]
=== Embeddable values === Embeddable values
:rootProjectDir: ../../../../../../.. :root-project-dir: ../../../../../../..
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/embeddable :documentation-project-dir: {root-project-dir}/documentation
:coreProjectDir: {rootProjectDir}/hibernate-core :documentation-example-base: {documentation-project-dir}/src/test/java
:coreTestSrcDir: {rootProjectDir}/hibernate-core/src/test/java :example-dir-emeddable: {documentation-example-base}/org/hibernate/userguide/mapping/embeddable
:instantiatorTestDir: {coreTestSrcDir}/org/hibernate/orm/test/mapping/embeddable/strategy/instantiator :core-project-dir: {root-project-dir}/hibernate-core
:usertypeTestDir: {coreTestSrcDir}/org/hibernate/orm/test/mapping/embeddable/strategy/usertype :core-test-base: {root-project-dir}/hibernate-core/src/test/java
:example-dir-embeddableinstantiator: {core-test-base}/org/hibernate/orm/test/mapping/embeddable/strategy/instantiator
:example-dir-compositeusertype: {core-test-base}/org/hibernate/orm/test/mapping/embeddable/strategy/usertype
:extrasdir: extras :extrasdir: extras
Historically Hibernate called these components. Historically Hibernate called these components.
@ -28,7 +30,7 @@ Throughout this chapter and thereafter, for brevity sake, embeddable types may a
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/NestedEmbeddableTest.java[tag=embeddable-type-mapping-example, indent=0] include::{example-dir-emeddable}/NestedEmbeddableTest.java[tag=embeddable-type-mapping-example, indent=0]
---- ----
==== ====
@ -45,7 +47,7 @@ Most often, embeddable types are used to group multiple basic type mappings and
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SimpleEmbeddableTest.java[tag=embeddable-type-mapping-example, indent=0] include::{example-dir-emeddable}/SimpleEmbeddableTest.java[tag=embeddable-type-mapping-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -75,7 +77,7 @@ In fact, that table could also be mapped by the following entity type instead.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SimpleEmbeddableEquivalentTest.java[tag=embeddable-type-mapping-example, indent=0] include::{example-dir-emeddable}/SimpleEmbeddableEquivalentTest.java[tag=embeddable-type-mapping-example, indent=0]
---- ----
==== ====
@ -106,7 +108,7 @@ which defines a `@ManyToOne` association with the `Country` entity:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddableOverrideTest.java[tag=embeddable-type-association-mapping-example, indent=0] include::{example-dir-emeddable}/EmbeddableOverrideTest.java[tag=embeddable-type-association-mapping-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -125,7 +127,7 @@ Therefore, the `Book` entity needs to override the embeddable type mappings for
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddableOverrideTest.java[tag=embeddable-type-override-mapping-example, indent=0] include::{example-dir-emeddable}/EmbeddableOverrideTest.java[tag=embeddable-type-override-mapping-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -178,7 +180,7 @@ However, for simple embeddable types, there is no such construct and so you need
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/TargetTest.java[tags=embeddable-Target-example] include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-example]
---- ----
==== ====
@ -193,7 +195,7 @@ Assuming we have persisted the following `City` entity:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/TargetTest.java[tags=embeddable-Target-persist-example] include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-persist-example]
---- ----
==== ====
@ -204,7 +206,7 @@ When fetching the `City` entity, the `coordinates` property is mapped by the `@T
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/TargetTest.java[tags=embeddable-Target-fetching-example] include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-fetching-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -225,7 +227,7 @@ The Hibernate-specific `@Parent` annotation allows you to reference the owner en
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ParentTest.java[tags=embeddable-Parent-example] include::{example-dir-emeddable}/ParentTest.java[tags=embeddable-Parent-example]
---- ----
==== ====
@ -236,7 +238,7 @@ Assuming we have persisted the following `City` entity:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ParentTest.java[tags=embeddable-Parent-persist-example] include::{example-dir-emeddable}/ParentTest.java[tags=embeddable-Parent-persist-example]
---- ----
==== ====
@ -247,7 +249,7 @@ When fetching the `City` entity, the `city` property of the embeddable type acts
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ParentTest.java[tags=embeddable-Parent-fetching-example] include::{example-dir-emeddable}/ParentTest.java[tags=embeddable-Parent-fetching-example]
---- ----
==== ====
@ -270,7 +272,7 @@ embeddable:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{instantiatorTestDir}/embedded/Name.java[tags=embeddable-instantiator-embeddable] include::{example-dir-embeddableinstantiator}/embedded/Name.java[tags=embeddable-instantiator-embeddable]
---- ----
==== ====
@ -282,7 +284,7 @@ conventions, in terms of constructor, a custom strategy for instantiation is nee
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{instantiatorTestDir}/embedded/NameInstantiator.java[tags=embeddable-instantiator-impl] include::{example-dir-embeddableinstantiator}/embedded/NameInstantiator.java[tags=embeddable-instantiator-impl]
---- ----
==== ====
@ -294,7 +296,7 @@ annotation can be used on the embedded attribute:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{instantiatorTestDir}/embedded/Person.java[tags=embeddable-instantiator-property] include::{example-dir-embeddableinstantiator}/embedded/Person.java[tags=embeddable-instantiator-property]
---- ----
==== ====
@ -305,9 +307,9 @@ include::{instantiatorTestDir}/embedded/Person.java[tags=embeddable-instantiator
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{instantiatorTestDir}/embeddable/Name.java[tags=embeddable-instantiator-class] include::{example-dir-embeddableinstantiator}/embeddable/Name.java[tags=embeddable-instantiator-class]
include::{instantiatorTestDir}/embeddable/Person.java[tags=embeddable-instantiator-class] include::{example-dir-embeddableinstantiator}/embeddable/Person.java[tags=embeddable-instantiator-class]
---- ----
==== ====
@ -321,7 +323,7 @@ on the <<embeddable-instantiator-class-ex,embeddable>>.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{instantiatorTestDir}/registered/Person.java[tags=embeddable-instantiator-registration] include::{example-dir-embeddableinstantiator}/registered/Person.java[tags=embeddable-instantiator-registration]
---- ----
==== ====
@ -346,7 +348,7 @@ For example, consider the following custom type:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{usertypeTestDir}/embedded/Name.java[tags=embeddable-usertype-domain] include::{example-dir-compositeusertype}/embedded/Name.java[tags=embeddable-usertype-domain]
---- ----
==== ====
@ -358,7 +360,7 @@ conventions, a custom user type for instantiation and state access is needed.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{usertypeTestDir}/embedded/NameCompositeUserType.java[tags=embeddable-usertype-impl] include::{example-dir-compositeusertype}/embedded/NameCompositeUserType.java[tags=embeddable-usertype-impl]
---- ----
==== ====
@ -381,7 +383,7 @@ annotation can be used on the embedded and element collection attributes:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{usertypeTestDir}/embedded/Person.java[tags=embeddable-usertype-property] include::{example-dir-compositeusertype}/embedded/Person.java[tags=embeddable-usertype-property]
---- ----
==== ====
@ -393,7 +395,7 @@ when the application developer wants to apply the composite user type for all do
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{usertypeTestDir}/registered/Person.java[tags=embeddable-usertype-registration] include::{example-dir-compositeusertype}/registered/Person.java[tags=embeddable-usertype-registration]
---- ----
==== ====
@ -417,7 +419,7 @@ However, for the purposes of this discussion, Hibernate has the capability to in
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddableImplicitOverrideTest.java[tag=embeddable-multiple-namingstrategy-entity-mapping, indent=0] include::{example-dir-emeddable}/EmbeddableImplicitOverrideTest.java[tag=embeddable-multiple-namingstrategy-entity-mapping, indent=0]
---- ----
==== ====
@ -428,7 +430,7 @@ To make it work, you need to use the `ImplicitNamingStrategyComponentPathImpl` n
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddableImplicitOverrideTest.java[tag=embeddable-multiple-ImplicitNamingStrategyComponentPathImpl, indent=0] include::{example-dir-emeddable}/EmbeddableImplicitOverrideTest.java[tag=embeddable-multiple-ImplicitNamingStrategyComponentPathImpl, indent=0]
---- ----
==== ====
@ -439,4 +441,4 @@ Now the "path" to attributes are used in the implicit column naming:
include::{extrasdir}/embeddable/embeddable-multiple-namingstrategy-entity-mapping.sql[] include::{extrasdir}/embeddable/embeddable-multiple-namingstrategy-entity-mapping.sql[]
---- ----
You could even develop your own naming strategy to do other types of implicit naming strategies. You could even develop your own naming strategy to do other types of implicit naming strategies.

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

@ -1,9 +1,11 @@
[[entity]] [[entity]]
=== Entity types === Entity types
:sourcedir-locking: ../../../../../test/java/org/hibernate/userguide/locking :root-project-dir: ../../../../../../..
:sourcedir-mapping: ../../../../../test/java/org/hibernate/userguide/mapping :documentation-project-dir: {root-project-dir}/documentation
:sourcedir-proxy: ../../../../../test/java/org/hibernate/userguide/proxy :example-dir-locking: {documentation-project-dir}/src/test/java/org/hibernate/userguide/locking
:sourcedir-persister: ../../../../../test/java/org/hibernate/userguide/persister :example-dir-mapping: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping
:example-dir-proxy: {documentation-project-dir}/src/test/java/org/hibernate/userguide/proxy
:example-dir-persister: {documentation-project-dir}/src/test/java/org/hibernate/userguide/persister
:extrasdir: extras :extrasdir: extras
.Usage of the word _entity_ .Usage of the word _entity_
@ -105,7 +107,7 @@ The placement of the `@Id` annotation marks the <<chapters/domain/access.adoc#ac
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-identifier-mapping-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-identifier-mapping-example, indent=0]
---- ----
==== ====
@ -134,7 +136,7 @@ In the following example, the entity name (e.g. `Book`) is given by the unqualif
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/Book.java[tag=entity-pojo-mapping-implicit-name-example, indent=0] include::{example-dir-mapping}/identifier/Book.java[tag=entity-pojo-mapping-implicit-name-example, indent=0]
---- ----
==== ====
@ -145,7 +147,7 @@ However, the entity name can also be set explicitly as illustrated by the follow
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-mapping-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-mapping-example, indent=0]
---- ----
==== ====
@ -159,7 +161,7 @@ To explicitly give the name of the table or to specify other information about t
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTableTest.java[tag=entity-pojo-table-mapping-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTableTest.java[tag=entity-pojo-table-mapping-example, indent=0]
---- ----
==== ====
@ -189,7 +191,7 @@ Now, to map the `Book` entity to the `book` table in the `public` catalog we can
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/EntityTableCatalogTest.java[tag=mapping-entity-table-catalog-mysql-example, indent=0] include::{example-dir-mapping}/identifier/EntityTableCatalogTest.java[tag=mapping-entity-table-catalog-mysql-example, indent=0]
---- ----
==== ====
@ -219,7 +221,7 @@ Now, to map the `Book` entity to the `book` table in the `library` schema we can
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/EntityTableSchemaTest.java[tag=mapping-entity-table-schema-postgresql-example, indent=0] include::{example-dir-mapping}/identifier/EntityTableSchemaTest.java[tag=mapping-entity-table-schema-postgresql-example, indent=0]
---- ----
==== ====
@ -261,7 +263,7 @@ So if we ask a Hibernate `Session` to load that specific Person multiple times w
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-identity-scope-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-identity-scope-example, indent=0]
---- ----
==== ====
@ -272,7 +274,7 @@ Consider we have a `Library` parent entity which contains a `java.util.Set` of `
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-set-mapping-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-set-mapping-example, indent=0]
---- ----
==== ====
@ -281,7 +283,7 @@ include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-se
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-set-identity-scope-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-set-identity-scope-example, indent=0]
---- ----
==== ====
@ -292,12 +294,12 @@ However, the semantic changes when we mix instances loaded from different Sessio
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-multi-session-identity-scope-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-multi-session-identity-scope-example, indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-multi-session-set-identity-scope-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-multi-session-set-identity-scope-example, indent=0]
---- ----
==== ====
@ -314,7 +316,7 @@ Consider yet another case:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-transient-set-identity-scope-example, indent=0] include::{example-dir-mapping}/identifier/SimpleEntityTest.java[tag=entity-pojo-transient-set-identity-scope-example, indent=0]
---- ----
==== ====
@ -329,7 +331,7 @@ A common initial approach is to use the entity's identifier attribute as the bas
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/NaiveEqualsHashCodeEntityTest.java[tag=entity-pojo-naive-equals-hashcode-example, indent=0] include::{example-dir-mapping}/identifier/NaiveEqualsHashCodeEntityTest.java[tag=entity-pojo-naive-equals-hashcode-example, indent=0]
---- ----
==== ====
@ -340,7 +342,7 @@ It turns out that this still breaks when adding transient instance of `Book` to
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/NaiveEqualsHashCodeEntityTest.java[tag=entity-pojo-naive-equals-hashcode-persist-example, indent=0] include::{example-dir-mapping}/identifier/NaiveEqualsHashCodeEntityTest.java[tag=entity-pojo-naive-equals-hashcode-persist-example, indent=0]
---- ----
==== ====
@ -358,7 +360,7 @@ Another option is to force the identifier to be generated and set prior to addin
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/NaiveEqualsHashCodeEntityTest.java[tag=entity-pojo-naive-equals-hashcode-persist-force-flush-example, indent=0] include::{example-dir-mapping}/identifier/NaiveEqualsHashCodeEntityTest.java[tag=entity-pojo-naive-equals-hashcode-persist-force-flush-example, indent=0]
---- ----
==== ====
@ -371,7 +373,7 @@ The final approach is to use a "better" equals/hashCode implementation, making u
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/NaturalIdEqualsHashCodeEntityTest.java[tag=entity-pojo-natural-id-equals-hashcode-example, indent=0] include::{example-dir-mapping}/identifier/NaturalIdEqualsHashCodeEntityTest.java[tag=entity-pojo-natural-id-equals-hashcode-example, indent=0]
---- ----
==== ====
@ -382,7 +384,7 @@ This time, when adding a `Book` to the `Library` `Set`, you can retrieve the `Bo
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/identifier/NaturalIdEqualsHashCodeEntityTest.java[tag=entity-pojo-natural-id-equals-hashcode-persist-example, indent=0] include::{example-dir-mapping}/identifier/NaturalIdEqualsHashCodeEntityTest.java[tag=entity-pojo-natural-id-equals-hashcode-persist-example, indent=0]
---- ----
==== ====
@ -410,7 +412,7 @@ You can map an entity to a SQL query using the https://docs.jboss.org/hibernate/
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/basic/SubselectTest.java[tag=mapping-Subselect-example,indent=0] include::{example-dir-mapping}/basic/SubselectTest.java[tag=mapping-Subselect-example,indent=0]
---- ----
==== ====
@ -426,7 +428,7 @@ So, if we have the following `AccountTransaction` record, the `AccountSummary` b
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/basic/SubselectTest.java[tag=mapping-Subselect-entity-find-example,indent=0] include::{example-dir-mapping}/basic/SubselectTest.java[tag=mapping-Subselect-entity-find-example,indent=0]
---- ----
==== ====
@ -437,7 +439,7 @@ If we add a new `AccountTransaction` entity and refresh the `AccountSummary` ent
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-mapping}/basic/SubselectTest.java[tag=mapping-Subselect-entity-refresh-example,indent=0] include::{example-dir-mapping}/basic/SubselectTest.java[tag=mapping-Subselect-entity-refresh-example,indent=0]
---- ----
==== ====
@ -465,7 +467,7 @@ In this case, you could proxy an interface that this particular entity implement
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-proxy}/ProxyInterfaceTest.java[tag=entity-proxy-interface-mapping,indent=0] include::{example-dir-proxy}/ProxyInterfaceTest.java[tag=entity-proxy-interface-mapping,indent=0]
---- ----
==== ====
@ -479,7 +481,7 @@ When loading the `Book` entity proxy, Hibernate is going to proxy the `Identifia
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-proxy}/ProxyInterfaceTest.java[tag=entity-proxy-persist-mapping,indent=0] include::{example-dir-proxy}/ProxyInterfaceTest.java[tag=entity-proxy-persist-mapping,indent=0]
---- ----
[source,sql] [source,sql]
@ -510,12 +512,12 @@ of 6.2 `@Persister` has been formally deprecated.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-persister}/Author.java[tag=entity-persister-mapping,indent=0] include::{example-dir-persister}/Author.java[tag=entity-persister-mapping,indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir-persister}/Book.java[tag=entity-persister-mapping,indent=0] include::{example-dir-persister}/Book.java[tag=entity-persister-mapping,indent=0]
---- ----
==== ====

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

@ -1,9 +1,10 @@
[[identifiers]] [[identifiers]]
=== Identifiers === Identifiers
:projectRootDir: ../../../../../../.. :root-project-dir: ../../../../../../..
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/identifier :documentation-project-dir: {root-project-dir}/documentation
:sourcedir-associations: ../../../../../test/java/org/hibernate/userguide/associations :example-dir-identifier: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping/identifier
:coreTestsDir: {projectRootDir}/hibernate-core/src/test/java :example-dir-associations: {documentation-project-dir}/src/test/java/org/hibernate/userguide/associations
:core-test-base: {root-project-dir}/hibernate-core/src/test/java
:jpaJavadocUrl: https://javadoc.io/doc/jakarta.persistence/jakarta.persistence-api/latest/jakarta.persistence :jpaJavadocUrl: https://javadoc.io/doc/jakarta.persistence/jakarta.persistence-api/latest/jakarta.persistence
:extrasdir: extras :extrasdir: extras
@ -58,7 +59,7 @@ assign the value to the identifier attribute prior to persisting the entity.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/AssignedIdentifierTest.java[tag=identifiers-simple-assigned-mapping-example, indent=0] include::{example-dir-identifier}/AssignedIdentifierTest.java[tag=identifiers-simple-assigned-mapping-example, indent=0]
---- ----
==== ====
@ -74,7 +75,7 @@ annotated with `jakarta.persistence.GeneratedValue`
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/GeneratedIdentifierTest.java[tag=identifiers-simple-generated-mapping-example, indent=0] include::{example-dir-identifier}/GeneratedIdentifierTest.java[tag=identifiers-simple-generated-mapping-example, indent=0]
---- ----
==== ====
@ -126,7 +127,7 @@ the identifier, and then exposing an attribute of that embeddable type on the en
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddedIdTest.java[tag=identifiers-basic-embeddedid-mapping-example, indent=0] include::{example-dir-identifier}/EmbeddedIdTest.java[tag=identifiers-basic-embeddedid-mapping-example, indent=0]
---- ----
==== ====
@ -137,7 +138,7 @@ As mentioned before, EmbeddedIds can even contain `@ManyToOne` attributes:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/EmbeddedIdManyToOneTest.java[tag=identifiers-basic-embeddedid-manytoone-mapping-example, indent=0] include::{example-dir-identifier}/EmbeddedIdManyToOneTest.java[tag=identifiers-basic-embeddedid-manytoone-mapping-example, indent=0]
---- ----
==== ====
@ -160,7 +161,7 @@ attribute making up the composition. The IdClass is used as the representation
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/IdClassTest.java[tag=identifiers-basic-idclass-mapping-example, indent=0] include::{example-dir-identifier}/IdClassTest.java[tag=identifiers-basic-idclass-mapping-example, indent=0]
---- ----
==== ====
@ -171,7 +172,7 @@ Non-aggregated composite identifiers can also contain ManyToOne attributes as we
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/IdClassManyToOneTest.java[tag=identifiers-basic-idclass-manytoone-mapping-example, indent=0] include::{example-dir-identifier}/IdClassManyToOneTest.java[tag=identifiers-basic-idclass-manytoone-mapping-example, indent=0]
---- ----
==== ====
@ -182,7 +183,7 @@ With non-aggregated composite identifiers, Hibernate also supports "partial" gen
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/IdClassGeneratedValueTest.java[tag=identifiers-basic-idclass-generatedvalue-mapping-example, indent=0] include::{example-dir-identifier}/IdClassGeneratedValueTest.java[tag=identifiers-basic-idclass-generatedvalue-mapping-example, indent=0]
---- ----
==== ====
@ -206,7 +207,7 @@ In the following example, the `Book` entity identifier is formed of two `@ManyTo
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/IdManyToOneTest.java[tag=identifiers-composite-id-mapping-example, indent=0] include::{example-dir-identifier}/IdManyToOneTest.java[tag=identifiers-composite-id-mapping-example, indent=0]
---- ----
==== ====
@ -218,7 +219,7 @@ To query this entity, an instance of the entity itself must be supplied to the p
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/IdManyToOneTest.java[tag=identifiers-composite-id-fetching-example, indent=0] include::{example-dir-identifier}/IdManyToOneTest.java[tag=identifiers-composite-id-fetching-example, indent=0]
---- ----
==== ====
@ -240,12 +241,12 @@ Assuming we have the following `EventId` composite identifier and an `Event` ent
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/composite/Event.java[tag=identifiers-composite-generated-mapping-example, indent=0] include::{example-dir-identifier}/composite/Event.java[tag=identifiers-composite-generated-mapping-example, indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir}/composite/EventId.java[tag=identifiers-composite-generated-mapping-example, indent=0] include::{example-dir-identifier}/composite/EventId.java[tag=identifiers-composite-generated-mapping-example, indent=0]
---- ----
==== ====
@ -260,7 +261,7 @@ you need to do that as follows:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/composite/EmbeddedIdInMemoryGeneratedValueTest.java[tag=identifiers-composite-generated-in-memory-example, indent=0] include::{example-dir-identifier}/composite/EmbeddedIdInMemoryGeneratedValueTest.java[tag=identifiers-composite-generated-in-memory-example, indent=0]
---- ----
==== ====
@ -278,7 +279,7 @@ you could to do it as illustrated by the following example.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/composite/EmbeddedIdDatabaseGeneratedValueTest.java[tag=identifiers-composite-generated-database-example, indent=0] include::{example-dir-identifier}/composite/EmbeddedIdDatabaseGeneratedValueTest.java[tag=identifiers-composite-generated-database-example, indent=0]
---- ----
==== ====
@ -334,7 +335,7 @@ id generation behavior (versus say choosing between SEQUENCE and IDENTITY).
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SequenceGeneratorUnnamedTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0] include::{example-dir-identifier}/SequenceGeneratorUnnamedTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0]
---- ----
==== ====
@ -357,7 +358,7 @@ To specify the sequence name explicitly, the simplest form is to specify `@Gener
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SequenceGeneratorAnnotationNameTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0] include::{example-dir-identifier}/SequenceGeneratorAnnotationNameTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0]
---- ----
==== ====
@ -370,7 +371,7 @@ For more advanced configuration, Jakarta Persistence defines the `@SequenceGener
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SequenceGeneratorNamedTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0] include::{example-dir-identifier}/SequenceGeneratorNamedTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0]
---- ----
==== ====
@ -383,7 +384,7 @@ configurations as well.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SequenceGeneratorConfiguredTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0] include::{example-dir-identifier}/SequenceGeneratorConfiguredTest.java[tag=identifiers-generators-sequence-mapping-example, indent=0]
---- ----
==== ====
@ -450,7 +451,7 @@ The basic idea is that a given table-generator table (`hibernate_sequences` for
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/TableGeneratorUnnamedTest.java[tag=identifiers-generators-table-mapping-example, indent=0] include::{example-dir-identifier}/TableGeneratorUnnamedTest.java[tag=identifiers-generators-table-mapping-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -471,7 +472,7 @@ However, you can configure the table identifier generator using the {jpaJavadocU
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/TableGeneratorConfiguredTest.java[tag=identifiers-generators-table-mapping-example, indent=0] include::{example-dir-identifier}/TableGeneratorConfiguredTest.java[tag=identifiers-generators-table-mapping-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -487,7 +488,7 @@ Now, when inserting 3 `Product` entities, Hibernate generates the following stat
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/TableGeneratorConfiguredTest.java[tag=identifiers-generators-table-persist-example, indent=0] include::{example-dir-identifier}/TableGeneratorConfiguredTest.java[tag=identifiers-generators-table-persist-example, indent=0]
---- ----
[source,sql] [source,sql]
@ -515,7 +516,7 @@ Hibernate does ship with an alternative strategy which is a RFC 4122 version 1 (
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/UuidGeneratedValueTest.java[tag=identifiers-generators-uuid-mapping-example, indent=0] include::{example-dir-identifier}/UuidGeneratedValueTest.java[tag=identifiers-generators-uuid-mapping-example, indent=0]
---- ----
==== ====
@ -527,7 +528,7 @@ Here we choose the RFC 4122 version 1 compliant strategy named `org.hibernate.id
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/UuidCustomGeneratedValueTest.java[tag=identifiers-generators-custom-uuid-mapping-example, indent=0] include::{example-dir-identifier}/UuidCustomGeneratedValueTest.java[tag=identifiers-generators-custom-uuid-mapping-example, indent=0]
---- ----
==== ====
@ -577,9 +578,9 @@ and type-safe definition and configuration of custom `org.hibernate.id.Identifie
==== ====
[source,java] [source,java]
---- ----
include::{coreTestsDir}/org/hibernate/orm/test/id/custom/CustomSequenceGenerator.java[tag=identifiers-IdGeneratorType-example, indent=0] include::{core-test-base}/org/hibernate/orm/test/id/custom/CustomSequenceGenerator.java[tag=identifiers-IdGeneratorType-example, indent=0]
include::{coreTestsDir}/org/hibernate/orm/test/id/custom/Sequence.java[tag=identifiers-IdGeneratorType-example, indent=0] include::{core-test-base}/org/hibernate/orm/test/id/custom/Sequence.java[tag=identifiers-IdGeneratorType-example, indent=0]
---- ----
==== ====
@ -613,7 +614,7 @@ for identifier generators.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PooledOptimizerTest.java[tag=identifiers-generators-pooled-lo-optimizer-mapping-example] include::{example-dir-identifier}/PooledOptimizerTest.java[tag=identifiers-generators-pooled-lo-optimizer-mapping-example]
---- ----
==== ====
@ -624,7 +625,7 @@ Now, when saving 5 `Person` entities and flushing the Persistence Context after
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PooledOptimizerTest.java[tag=identifiers-generators-pooled-lo-optimizer-persist-example] include::{example-dir-identifier}/PooledOptimizerTest.java[tag=identifiers-generators-pooled-lo-optimizer-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -646,7 +647,7 @@ Java Persistence 2.0 added support for derived identifiers which allow an entity
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-associations}/OneToOneMapsIdTest.java[tag=identifiers-derived-mapsid, indent=0] include::{example-dir-associations}/OneToOneMapsIdTest.java[tag=identifiers-derived-mapsid, indent=0]
---- ----
==== ====
@ -658,7 +659,7 @@ The value of the `PersonDetails` entity identifier is "derived" from the identif
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-associations}/OneToOneMapsIdTest.java[tag=identifiers-derived-mapsid-persist-example, indent=0] include::{example-dir-associations}/OneToOneMapsIdTest.java[tag=identifiers-derived-mapsid-persist-example, indent=0]
---- ----
==== ====
@ -671,7 +672,7 @@ The previous example can also be mapped using `@PrimaryKeyJoinColumn`.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir-associations}/OneToOnePrimaryKeyJoinColumnTest.java[tag=identifiers-derived-primarykeyjoincolumn, indent=0] include::{example-dir-associations}/OneToOnePrimaryKeyJoinColumnTest.java[tag=identifiers-derived-primarykeyjoincolumn, indent=0]
---- ----
==== ====
@ -691,7 +692,7 @@ then Hibernate can use the `ROWID` pseudo-column for CRUD operations.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/RowIdTest.java[tag=identifiers-rowid-mapping] include::{example-dir-identifier}/RowIdTest.java[tag=identifiers-rowid-mapping]
---- ----
==== ====
@ -702,7 +703,7 @@ Now, when fetching an entity and modifying it, Hibernate uses the `ROWID` pseudo
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/RowIdTest.java[tag=identifiers-rowid-example] include::{example-dir-identifier}/RowIdTest.java[tag=identifiers-rowid-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[entity-immutability]] [[entity-immutability]]
=== Immutability === Immutability
:sourcedir: ../../../../../test/java/org/hibernate/userguide/immutability :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-immutability: {documentation-project-dir}/src/test/java/org/hibernate/userguide/immutability
:extrasdir: extras/immutability :extrasdir: extras/immutability
Immutability can be specified for both entities and collections. Immutability can be specified for both entities and collections.
@ -13,7 +15,7 @@ If a specific entity is immutable, it is good practice to mark it with the `@Imm
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityImmutabilityTest.java[tags=entity-immutability-example] include::{example-dir-immutability}/EntityImmutabilityTest.java[tags=entity-immutability-example]
---- ----
==== ====
@ -28,7 +30,7 @@ Considering the following entity is persisted in the database:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityImmutabilityTest.java[tags=entity-immutability-persist-example] include::{example-dir-immutability}/EntityImmutabilityTest.java[tags=entity-immutability-persist-example]
---- ----
==== ====
@ -39,7 +41,7 @@ Hibernate will skip any modification, therefore no SQL `UPDATE` statement is exe
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityImmutabilityTest.java[tags=entity-immutability-update-example] include::{example-dir-immutability}/EntityImmutabilityTest.java[tags=entity-immutability-update-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -58,7 +60,7 @@ Considering the following entity mappings:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CollectionImmutabilityTest.java[tags=collection-immutability-example] include::{example-dir-immutability}/CollectionImmutabilityTest.java[tags=collection-immutability-example]
---- ----
==== ====
@ -69,7 +71,7 @@ Once the immutable collection is created, it can never be modified.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CollectionImmutabilityTest.java[tags=collection-immutability-persist-example] include::{example-dir-immutability}/CollectionImmutabilityTest.java[tags=collection-immutability-persist-example]
---- ----
==== ====
@ -81,7 +83,7 @@ For instance, we can still modify the entity name:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CollectionImmutabilityTest.java[tags=collection-entity-update-example] include::{example-dir-immutability}/CollectionImmutabilityTest.java[tags=collection-entity-update-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -96,7 +98,7 @@ However, when trying to modify the `events` collection:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CollectionImmutabilityTest.java[tags=collection-immutability-update-example] include::{example-dir-immutability}/CollectionImmutabilityTest.java[tags=collection-immutability-update-example]
---- ----
[source, bash, indent=0] [source, bash, indent=0]
@ -108,4 +110,4 @@ include::{extrasdir}/collection-immutability-update-example.log.txt[]
[TIP] [TIP]
==== ====
While immutable entity changes are simply discarded, modifying an immutable collection will 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.
==== ====

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

@ -1,6 +1,8 @@
[[entity-inheritance]] [[entity-inheritance]]
=== Inheritance === Inheritance
:sourcedir: ../../../../../test/java/org/hibernate/userguide/inheritance :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-inheritance: {documentation-project-dir}/src/test/java/org/hibernate/userguide/inheritance
:extrasdir: extras/inheritance :extrasdir: extras/inheritance
Although relational database systems don't provide support for inheritance, Hibernate provides several strategies to leverage this object-oriented trait onto domain model entities: Although relational database systems don't provide support for inheritance, Hibernate provides several strategies to leverage this object-oriented trait onto domain model entities:
@ -24,7 +26,7 @@ When using `MappedSuperclass`, the inheritance is visible in the domain model on
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/MappedSuperclassTest.java[tags=entity-inheritance-mapped-superclass-example,indent=0] include::{example-dir-inheritance}/MappedSuperclassTest.java[tags=entity-inheritance-mapped-superclass-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -56,7 +58,7 @@ When omitting an explicit inheritance strategy (e.g. `@Inheritance`), Jakarta Pe
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SingleTableTest.java[tags=entity-inheritance-single-table-example,indent=0] include::{example-dir-inheritance}/SingleTableTest.java[tags=entity-inheritance-single-table-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -73,7 +75,7 @@ If this is not specified, the `DTYPE` column is used as a discriminator, storing
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SingleTableTest.java[tags=entity-inheritance-single-table-persist-example,indent=0] include::{example-dir-inheritance}/SingleTableTest.java[tags=entity-inheritance-single-table-persist-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -89,7 +91,7 @@ When using polymorphic queries, only a single table is required to be scanned to
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SingleTableTest.java[tags=entity-inheritance-single-table-query-example,indent=0] include::{example-dir-inheritance}/SingleTableTest.java[tags=entity-inheritance-single-table-query-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -146,7 +148,7 @@ we can take advantage of the Hibernate specific `@DiscriminatorFormula` annotati
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SingleTableDiscriminatorFormulaTest.java[tags=entity-inheritance-single-table-discriminator-formula-example,indent=0] include::{example-dir-inheritance}/SingleTableDiscriminatorFormulaTest.java[tags=entity-inheritance-single-table-discriminator-formula-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -173,7 +175,7 @@ To understand how these two values work, consider the following entity mapping:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/DiscriminatorNotNullSingleTableTest.java[tags=entity-inheritance-single-table-discriminator-value-example,indent=0] include::{example-dir-inheritance}/DiscriminatorNotNullSingleTableTest.java[tags=entity-inheritance-single-table-discriminator-value-example,indent=0]
---- ----
==== ====
@ -188,7 +190,7 @@ To visualize how it works, consider the following example:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/DiscriminatorNotNullSingleTableTest.java[tags=entity-inheritance-single-table-discriminator-value-persist-example,indent=0] include::{example-dir-inheritance}/DiscriminatorNotNullSingleTableTest.java[tags=entity-inheritance-single-table-discriminator-value-persist-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -215,7 +217,7 @@ Each subclass must, however, declare a table column holding the object identifie
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/JoinTableTest.java[tags=entity-inheritance-joined-table-example,indent=0] include::{example-dir-inheritance}/JoinTableTest.java[tags=entity-inheritance-joined-table-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -237,7 +239,7 @@ Also, if `@PrimaryKeyJoinColumn` is not set, the primary key / foreign key colum
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/JoinTablePrimaryKeyJoinColumnTest.java[tags=entity-inheritance-joined-table-primary-key-join-column-example,indent=0] include::{example-dir-inheritance}/JoinTablePrimaryKeyJoinColumnTest.java[tags=entity-inheritance-joined-table-primary-key-join-column-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -253,7 +255,7 @@ When using polymorphic queries, the base class table must be joined with all sub
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/JoinTableTest.java[tags=entity-inheritance-joined-table-query-example,indent=0] include::{example-dir-inheritance}/JoinTableTest.java[tags=entity-inheritance-joined-table-query-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -283,7 +285,7 @@ However, if you wish to use polymorphic associations (e.g. an association to the
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/TablePerClassTest.java[tags=entity-inheritance-table-per-class-example,indent=0] include::{example-dir-inheritance}/TablePerClassTest.java[tags=entity-inheritance-table-per-class-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -298,7 +300,7 @@ When using polymorphic queries, a UNION is required to fetch the base class tabl
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/TablePerClassTest.java[tags=entity-inheritance-table-per-class-query-example,indent=0] include::{example-dir-inheritance}/TablePerClassTest.java[tags=entity-inheritance-table-per-class-query-example,indent=0]
---- ----
[source,sql] [source,sql]
@ -345,7 +347,7 @@ For instance, considering the following `DomainModelEntity` interface:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/polymorphism/DomainModelEntity.java[tags=entity-inheritance-polymorphism-interface-example,indent=0] include::{example-dir-inheritance}/polymorphism/DomainModelEntity.java[tags=entity-inheritance-polymorphism-interface-example,indent=0]
---- ----
==== ====
@ -359,7 +361,7 @@ and taking the `PolymorphismType.EXPLICIT` setting:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/polymorphism/ExplicitPolymorphismTest.java[tags=entity-inheritance-polymorphism-mapping-example,indent=0] include::{example-dir-inheritance}/polymorphism/ExplicitPolymorphismTest.java[tags=entity-inheritance-polymorphism-mapping-example,indent=0]
---- ----
==== ====
@ -370,7 +372,7 @@ If we have the following entity objects in our system:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/polymorphism/ExplicitPolymorphismTest.java[tags=entity-inheritance-polymorphism-persist-example,indent=0] include::{example-dir-inheritance}/polymorphism/ExplicitPolymorphismTest.java[tags=entity-inheritance-polymorphism-persist-example,indent=0]
---- ----
==== ====
@ -384,10 +386,10 @@ or they are not annotated at all with the `@Polymorphism` annotation (implying t
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/polymorphism/ExplicitPolymorphismTest.java[tags=entity-inheritance-polymorphism-fetch-example,indent=0] include::{example-dir-inheritance}/polymorphism/ExplicitPolymorphismTest.java[tags=entity-inheritance-polymorphism-fetch-example,indent=0]
---- ----
==== ====
Therefore, only the `Book` was fetched since the `Blog` entity was marked with the Therefore, only the `Book` was fetched since the `Blog` entity was marked with the
`@Polymorphism(type = PolymorphismType.EXPLICIT)` annotation, which instructs Hibernate `@Polymorphism(type = PolymorphismType.EXPLICIT)` annotation, which instructs Hibernate
to skip it when executing a polymorphic query against a non-mapped base class. to skip it when executing a polymorphic query against a non-mapped base class.

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

@ -1,6 +1,8 @@
[[naming]] [[naming]]
=== Naming strategies === Naming strategies
:sourcedir: ../../../../../test/java/org/hibernate/userguide/naming :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-naming: {documentation-project-dir}/src/test/java/org/hibernate/userguide/naming
Part of the mapping of an object model to the relational database is Part of the mapping of an object model to the relational database is
mapping names from the object model to the corresponding database names. mapping names from the object model to the corresponding database names.
@ -113,7 +115,7 @@ whose naming standards are to:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/AcmeCorpPhysicalNamingStrategy.java[] include::{example-dir-naming}/AcmeCorpPhysicalNamingStrategy.java[]
---- ----
==== ====

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

@ -1,6 +1,8 @@
[[naturalid]] [[naturalid]]
=== Natural Ids === Natural Ids
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/identifier :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-naturalid: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping/identifier
:extrasdir: extras :extrasdir: extras
Natural ids represent domain model unique identifiers that have a meaning in the real world too. Natural ids represent domain model unique identifiers that have a meaning in the real world too.
@ -17,7 +19,7 @@ Natural ids are defined in terms of one or more persistent attributes.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SimpleNaturalIdTest.java[tags=naturalid-simple-basic-attribute-mapping-example,indent=0] include::{example-dir-naturalid}/SimpleNaturalIdTest.java[tags=naturalid-simple-basic-attribute-mapping-example,indent=0]
---- ----
==== ====
@ -26,7 +28,7 @@ include::{sourcedir}/SimpleNaturalIdTest.java[tags=naturalid-simple-basic-attrib
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/CompositeNaturalIdTest.java[tags=naturalid-single-embedded-attribute-mapping-example,indent=0] include::{example-dir-naturalid}/CompositeNaturalIdTest.java[tags=naturalid-single-embedded-attribute-mapping-example,indent=0]
---- ----
==== ====
@ -35,7 +37,7 @@ include::{sourcedir}/CompositeNaturalIdTest.java[tags=naturalid-single-embedded-
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/MultipleNaturalIdTest.java[tags=naturalid-multiple-attribute-mapping-example,indent=0] include::{example-dir-naturalid}/MultipleNaturalIdTest.java[tags=naturalid-multiple-attribute-mapping-example,indent=0]
---- ----
==== ====
@ -55,17 +57,17 @@ If the entity does not define a natural id, trying to load an entity by its natu
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SimpleNaturalIdTest.java[tags=naturalid-load-access-example,indent=0] include::{example-dir-naturalid}/SimpleNaturalIdTest.java[tags=naturalid-load-access-example,indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir}/CompositeNaturalIdTest.java[tags=naturalid-load-access-example,indent=0] include::{example-dir-naturalid}/CompositeNaturalIdTest.java[tags=naturalid-load-access-example,indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir}/MultipleNaturalIdTest.java[tags=naturalid-load-access-example,indent=0] include::{example-dir-naturalid}/MultipleNaturalIdTest.java[tags=naturalid-load-access-example,indent=0]
---- ----
==== ====
@ -88,12 +90,12 @@ Because the `Book` entities in the first two examples define "simple" natural id
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/SimpleNaturalIdTest.java[tags=naturalid-simple-load-access-example,indent=0] include::{example-dir-naturalid}/SimpleNaturalIdTest.java[tags=naturalid-simple-load-access-example,indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir}/CompositeNaturalIdTest.java[tags=naturalid-simple-load-access-example,indent=0] include::{example-dir-naturalid}/CompositeNaturalIdTest.java[tags=naturalid-simple-load-access-example,indent=0]
---- ----
==== ====
@ -122,7 +124,7 @@ If the value(s) of the natural id attribute(s) change, `@NaturalId(mutable = tru
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/MutableNaturalIdTest.java[tags=naturalid-mutable-mapping-example,indent=0] include::{example-dir-naturalid}/MutableNaturalIdTest.java[tags=naturalid-mutable-mapping-example,indent=0]
---- ----
==== ====
@ -144,7 +146,7 @@ This will force Hibernate to circumvent the checking of mutable natural ids.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/MutableNaturalIdTest.java[tags=naturalid-mutable-synchronized-example,indent=0] include::{example-dir-naturalid}/MutableNaturalIdTest.java[tags=naturalid-mutable-synchronized-example,indent=0]
---- ----
==== ====
@ -155,6 +157,6 @@ Not only can this NaturalId-to-PK resolution be cached in the Session, but we ca
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/CacheableNaturalIdTest.java[tags=naturalid-cacheable-mapping-example,indent=0] include::{example-dir-naturalid}/CacheableNaturalIdTest.java[tags=naturalid-cacheable-mapping-example,indent=0]
---- ----
==== ====

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

@ -1,6 +1,8 @@
[[mapping-types]] [[mapping-types]]
=== Mapping types === Mapping types
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-mapping: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping
:extrasdir: extras/types :extrasdir: extras/types
Hibernate understands both the Java and JDBC representations of application data. Hibernate understands both the Java and JDBC representations of application data.
@ -29,7 +31,7 @@ include::{extrasdir}/mapping-types-basic-example.sql[]
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/basic/TypeCategoryTest.java[tags=mapping-types-basic-example] include::{example-dir-mapping}/basic/TypeCategoryTest.java[tags=mapping-types-basic-example]
---- ----
==== ====

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

@ -1,6 +1,8 @@
[[envers]] [[envers]]
== Envers == Envers
:sourcedir: ../../../../../test/java/org/hibernate/userguide/envers :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-envers: {documentation-project-dir}/src/test/java/org/hibernate/userguide/envers
:extrasdir: extras :extrasdir: extras
[[envers-basics]] [[envers-basics]]
@ -44,7 +46,7 @@ Hibernate is going to generate the following tables using the `hibernate.hbm2ddl
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-mapping-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-mapping-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -64,7 +66,7 @@ let's see how Envers auditing works when inserting, updating, and deleting the e
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-insert-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-insert-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -78,7 +80,7 @@ include::{extrasdir}/envers-audited-insert-example.sql[]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-update-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-update-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -92,7 +94,7 @@ include::{extrasdir}/envers-audited-update-example.sql[]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-delete-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-delete-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -120,7 +122,7 @@ The audit (history) of an entity can be accessed using the `AuditReader` interfa
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-revisions-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-revisions-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -136,7 +138,7 @@ Using the previously fetched revisions, we can now inspect the state of the `Cus
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-rev1-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-rev1-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -159,7 +161,7 @@ The same goes for the second revision associated with the `UPDATE` statement.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-rev2-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-rev2-example]
---- ----
==== ====
@ -170,7 +172,7 @@ For the deleted entity revision, Envers throws a `NoResultException` since the e
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-rev3-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-rev3-example]
---- ----
==== ====
@ -184,7 +186,7 @@ all attributes, except for the entity identifier, are going to be `null`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultAuditTest.java[tags=envers-audited-rev4-example] include::{example-dir-envers}/DefaultAuditTest.java[tags=envers-audited-rev4-example]
---- ----
==== ====
@ -412,7 +414,7 @@ First, you need to configure the `ValidityAuditStrategy`:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ValidityStrategyAuditTest.java[tags=envers-audited-validity-configuration-example] include::{example-dir-envers}/ValidityStrategyAuditTest.java[tags=envers-audited-validity-configuration-example]
---- ----
==== ====
@ -513,7 +515,7 @@ Considering we have a `CurrentUser` utility which stores the currently logged us
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CustomRevisionEntityTest.java[tags=envers-revisionlog-CurrentUser-example] include::{example-dir-envers}/CustomRevisionEntityTest.java[tags=envers-revisionlog-CurrentUser-example]
---- ----
==== ====
@ -524,7 +526,7 @@ Now, we need to provide a custom `@RevisionEntity` to store the currently logged
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CustomRevisionEntityTest.java[tags=envers-revisionlog-RevisionEntity-example] include::{example-dir-envers}/CustomRevisionEntityTest.java[tags=envers-revisionlog-RevisionEntity-example]
---- ----
==== ====
@ -537,7 +539,7 @@ of `RevisionEntity` instances.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CustomRevisionEntityTest.java[tags=envers-revisionlog-RevisionListener-example] include::{example-dir-envers}/CustomRevisionEntityTest.java[tags=envers-revisionlog-RevisionListener-example]
---- ----
==== ====
@ -561,7 +563,7 @@ Now, when inserting a `Customer` entity, Envers generates the following statemen
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CustomRevisionEntityTest.java[tags=envers-revisionlog-RevisionEntity-persist-example] include::{example-dir-envers}/CustomRevisionEntityTest.java[tags=envers-revisionlog-RevisionEntity-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -612,7 +614,7 @@ Tracking of modified entity names can be enabled in three different ways:
+ +
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditDefaultTrackingTest.java[tags=envers-tracking-modified-entities-revchanges-example] include::{example-dir-envers}/EntityTypeChangeAuditDefaultTrackingTest.java[tags=envers-tracking-modified-entities-revchanges-example]
---- ----
+ +
. Mark an appropriate field of a custom revision entity with `@org.hibernate.envers.ModifiedEntityNames` annotation. . Mark an appropriate field of a custom revision entity with `@org.hibernate.envers.ModifiedEntityNames` annotation.
@ -620,7 +622,7 @@ include::{sourcedir}/EntityTypeChangeAuditDefaultTrackingTest.java[tags=envers-t
+ +
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-revchanges-example] include::{example-dir-envers}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-revchanges-example]
---- ----
Considering we have a `Customer` entity illustrated by the following example: Considering we have a `Customer` entity illustrated by the following example:
@ -630,7 +632,7 @@ Considering we have a `Customer` entity illustrated by the following example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-revchanges-before-rename-example] include::{example-dir-envers}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-revchanges-before-rename-example]
---- ----
==== ====
@ -642,7 +644,7 @@ Envers is going to insert a new record in the `REVCHANGES` table with the previo
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-revchanges-after-rename-example] include::{example-dir-envers}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-revchanges-after-rename-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -666,7 +668,7 @@ added, modified or removed within current revision boundaries.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-EntityTrackingRevisionListener-example] include::{example-dir-envers}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-EntityTrackingRevisionListener-example]
---- ----
==== ====
@ -677,7 +679,7 @@ The `CustomTrackingRevisionListener` adds the fully-qualified class name to the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-RevisionEntity-example] include::{example-dir-envers}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-RevisionEntity-example]
---- ----
==== ====
@ -688,7 +690,7 @@ The `CustomTrackingRevisionEntity` contains a `@OneToMany` list of `ModifiedType
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-EntityType-example] include::{example-dir-envers}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-EntityType-example]
---- ----
==== ====
@ -699,7 +701,7 @@ Now, when fetching the `CustomTrackingRevisionEntity`, you can get access to the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-query-example] include::{example-dir-envers}/EntityTypeChangeAuditTrackingRevisionListenerTest.java[tags=envers-tracking-modified-entities-revchanges-query-example]
---- ----
==== ====
@ -732,7 +734,7 @@ Because of costs mentioned, it is recommended to enable the feature selectively,
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ModifiedFlagsAuditTest.java[tags=envers-tracking-properties-changes-mapping-example] include::{example-dir-envers}/ModifiedFlagsAuditTest.java[tags=envers-tracking-properties-changes-mapping-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -748,7 +750,7 @@ As you can see, every property features a `_MOD` column (e.g. `createdOn_MOD`) i
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ModifiedFlagsAuditTest.java[tags=envers-tracking-properties-changes-example] include::{example-dir-envers}/ModifiedFlagsAuditTest.java[tags=envers-tracking-properties-changes-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -863,7 +865,7 @@ The entry point for this type of queries is:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=entities-at-revision-example] include::{example-dir-envers}/QueryAuditTest.java[tags=entities-at-revision-example]
---- ----
==== ====
@ -880,7 +882,7 @@ For example, to select only entities where the `firstName` property is equal to
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=entities-filtering-example] include::{example-dir-envers}/QueryAuditTest.java[tags=entities-filtering-example]
---- ----
==== ====
@ -892,7 +894,7 @@ you can use either the target entity or its identifier.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=entities-filtering-by-entity-example] include::{example-dir-envers}/QueryAuditTest.java[tags=entities-filtering-by-entity-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -908,7 +910,7 @@ The same SQL is generated even if we provide the identifier instead of the targe
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=entities-filtering-by-entity-identifier-example] include::{example-dir-envers}/QueryAuditTest.java[tags=entities-filtering-by-entity-identifier-example]
---- ----
==== ====
@ -919,7 +921,7 @@ Apart from strict equality matching, you can also use an `IN` clause to provide
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=entities-in-clause-filtering-by-entity-identifier-example] include::{example-dir-envers}/QueryAuditTest.java[tags=entities-in-clause-filtering-by-entity-identifier-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -938,7 +940,7 @@ A full query, can look for example like this:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=entities-filtering-and-pagination] include::{example-dir-envers}/QueryAuditTest.java[tags=entities-filtering-and-pagination]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -955,7 +957,7 @@ The entry point for this type of queries is:
[[revisions-of-entity-query-example]] [[revisions-of-entity-query-example]]
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=revisions-of-entity-query-example] include::{example-dir-envers}/QueryAuditTest.java[tags=revisions-of-entity-query-example]
---- ----
You can add constraints to this query in the same way as to the previous one. You can add constraints to this query in the same way as to the previous one.
@ -975,7 +977,7 @@ For example, the following query will select the smallest revision number, at wh
[[revisions-of-entity-query-by-revision-number-example]] [[revisions-of-entity-query-by-revision-number-example]]
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=revisions-of-entity-query-by-revision-number-example] include::{example-dir-envers}/QueryAuditTest.java[tags=revisions-of-entity-query-by-revision-number-example]
---- ----
The second additional feature you can use in queries for revisions is the ability to _maximize_/_minimize_ a property. The second additional feature you can use in queries for revisions is the ability to _maximize_/_minimize_ a property.
@ -987,7 +989,7 @@ you can run the following query:
[[revisions-of-entity-query-minimize-example]] [[revisions-of-entity-query-minimize-example]]
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=revisions-of-entity-query-minimize-example] include::{example-dir-envers}/QueryAuditTest.java[tags=revisions-of-entity-query-minimize-example]
---- ----
The `minimize()` and `maximize()` methods return a criterion, to which you can add constraints, The `minimize()` and `maximize()` methods return a criterion, to which you can add constraints,
@ -1018,7 +1020,7 @@ maximum revision number, you would use the following query:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=aggregate-max-revision-with-entity-example] include::{example-dir-envers}/QueryAuditTest.java[tags=aggregate-max-revision-with-entity-example]
---- ----
In other words, the result set would contain a list of `Customer` instances, one per primary key. Each instance would In other words, the result set would contain a list of `Customer` instances, one per primary key. Each instance would
@ -1039,7 +1041,7 @@ First, you must make sure that your entity can track _modification flags_:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-entity-example] include::{example-dir-envers}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-entity-example]
---- ----
==== ====
@ -1051,7 +1053,7 @@ for which the `lastName` property has changed.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-hasChanged-example] include::{example-dir-envers}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-hasChanged-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1071,7 +1073,7 @@ Of course, nothing prevents users from combining `hasChanged` condition with som
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-hasChanged-and-hasNotChanged-example] include::{example-dir-envers}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-hasChanged-and-hasNotChanged-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1088,7 +1090,7 @@ we have to use the `forEntitiesModifiedAtRevision` query:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-at-revision-example] include::{example-dir-envers}/QueryAuditWithModifiedFlagTest.java[tags=envers-tracking-properties-changes-queries-at-revision-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1146,12 +1148,12 @@ This basic query allows retrieving entity names and corresponding Java classes c
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-queries-example1] include::{example-dir-envers}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-queries-example1]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-queries-example2] include::{example-dir-envers}/EntityTypeChangeAuditTest.java[tags=envers-tracking-modified-entities-queries-example2]
---- ----
==== ====
@ -1192,7 +1194,7 @@ The basis for creating an entity relation join query is as follows:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=envers-querying-entity-relation-inner-join] include::{example-dir-envers}/QueryAuditTest.java[tags=envers-querying-entity-relation-inner-join]
---- ----
==== ====
@ -1201,7 +1203,7 @@ include::{sourcedir}/QueryAuditTest.java[tags=envers-querying-entity-relation-in
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=envers-querying-entity-relation-left-join] include::{example-dir-envers}/QueryAuditTest.java[tags=envers-querying-entity-relation-left-join]
---- ----
==== ====
@ -1215,7 +1217,7 @@ you can use the following query:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditTest.java[tags=envers-querying-entity-relation-join-restriction] include::{example-dir-envers}/QueryAuditTest.java[tags=envers-querying-entity-relation-join-restriction]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1234,7 +1236,7 @@ with the country attribute of the address property being `România`:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-restriction] include::{example-dir-envers}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-restriction]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1253,7 +1255,7 @@ having the `address` in `Cluj-Napoca` or the `address` does _not_ have any count
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-join-multiple-restrictions] include::{example-dir-envers}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-join-multiple-restrictions]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1277,7 +1279,7 @@ where the country name is `România` or that the `Customer` lives in `Cluj-Napoc
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-multiple-restrictions] include::{example-dir-envers}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-multiple-restrictions]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1295,7 +1297,7 @@ Assuming the `Customer` and the `Address` were previously changed as follows:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-multiple-restrictions-combined-entities] include::{example-dir-envers}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-multiple-restrictions-combined-entities]
---- ----
==== ====
@ -1307,7 +1309,7 @@ where the `city` property of the `address` attribute equals the `name` of the as
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-multiple-restrictions-combined] include::{example-dir-envers}/QueryAuditAdressCountryTest.java[tags=envers-querying-entity-relation-nested-join-multiple-restrictions-combined]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1431,7 +1433,7 @@ For the following entities, Hibernate is going to generate the following databas
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/QueryAuditAdressCountryTest.java[tags=envers-generateschema-example] include::{example-dir-envers}/QueryAuditAdressCountryTest.java[tags=envers-generateschema-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[events]] [[events]]
== Interceptors and events == Interceptors and events
:sourcedir: ../../../../../test/java/org/hibernate/userguide/events :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-event: {documentation-project-dir}/src/test/java/org/hibernate/userguide/events
:extrasdir: extras :extrasdir: extras
It is useful for the application to react to certain events that occur inside Hibernate. It is useful for the application to react to certain events that occur inside Hibernate.
@ -19,7 +21,7 @@ The following example shows an `Interceptor` implementation that automatically l
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/InterceptorTest.java[tags=events-interceptors-example] include::{example-dir-event}/InterceptorTest.java[tags=events-interceptors-example]
---- ----
==== ====
@ -36,7 +38,7 @@ A Session-scoped interceptor is specified when a session is opened.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/InterceptorTest.java[tags=events-interceptors-session-scope-example] include::{example-dir-event}/InterceptorTest.java[tags=events-interceptors-session-scope-example]
---- ----
==== ====
@ -49,7 +51,7 @@ Ensure that you do not store session-specific states since multiple sessions wil
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/InterceptorTest.java[tags=events-interceptors-session-factory-scope-example] include::{example-dir-event}/InterceptorTest.java[tags=events-interceptors-session-factory-scope-example]
---- ----
==== ====
@ -81,12 +83,12 @@ Here is an example of a custom load event listener:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ListenerTest.java[tags=events-interceptors-load-listener-example-part1] include::{example-dir-event}/ListenerTest.java[tags=events-interceptors-load-listener-example-part1]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ListenerTest.java[tags=events-interceptors-load-listener-example-part2] include::{example-dir-event}/ListenerTest.java[tags=events-interceptors-load-listener-example-part2]
---- ----
==== ====
@ -134,7 +136,7 @@ The entity listener class is then associated with the entity using the `jakarta.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ListenerTest.java[tags=events-jpa-callbacks-example] include::{example-dir-event}/ListenerTest.java[tags=events-jpa-callbacks-example]
---- ----
==== ====
@ -172,12 +174,12 @@ Default entity listeners can only be defined in XML mapping files.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListener.java[tags=events-default-listener-mapping-example] include::{example-dir-event}/DefaultEntityListener.java[tags=events-default-listener-mapping-example]
---- ----
[source, XML, indent=0] [source, XML, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListener-orm.xml[tags=events-default-listener-mapping-example] include::{example-dir-event}/DefaultEntityListener-orm.xml[tags=events-default-listener-mapping-example]
---- ----
==== ====
@ -185,12 +187,12 @@ Considering that all entities extend the `BaseEntity` class:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BaseEntity.java[tags=events-default-listener-mapping-example] include::{example-dir-event}/BaseEntity.java[tags=events-default-listener-mapping-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListenerTest.java[tags=events-default-listener-mapping-example] include::{example-dir-event}/DefaultEntityListenerTest.java[tags=events-default-listener-mapping-example]
---- ----
When persisting a `Person` or `Book` entity, the `createdOn` is going to be set by the `onPersist` method of the `DefaultEntityListener`. When persisting a `Person` or `Book` entity, the `createdOn` is going to be set by the `onPersist` method of the `DefaultEntityListener`.
@ -200,7 +202,7 @@ When persisting a `Person` or `Book` entity, the `createdOn` is going to be set
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListenerTest.java[tags=events-default-listener-persist-example] include::{example-dir-event}/DefaultEntityListenerTest.java[tags=events-default-listener-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -216,7 +218,7 @@ When updating a `Person` or `Book` entity, the `updatedOn` is going to be set by
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListenerTest.java[tags=events-default-listener-update-example] include::{example-dir-event}/DefaultEntityListenerTest.java[tags=events-default-listener-update-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -241,7 +243,7 @@ while `@ExcludeSuperclassListeners` is used to ignore the default entity listene
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListenerTest.java[tags=events-exclude-default-listener-mapping-example] include::{example-dir-event}/DefaultEntityListenerTest.java[tags=events-exclude-default-listener-mapping-example]
---- ----
==== ====
@ -254,7 +256,7 @@ because the `Publisher` entity was marked with the `@ExcludeDefaultListeners` an
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DefaultEntityListenerTest.java[tags=events-exclude-default-listener-persist-example] include::{example-dir-event}/DefaultEntityListenerTest.java[tags=events-exclude-default-listener-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[fetching]] [[fetching]]
== Fetching == Fetching
:sourcedir: ../../../../../test/java/org/hibernate/userguide/fetching :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-fetching: {documentation-project-dir}/src/test/java/org/hibernate/userguide/fetching
:extrasdir: extras :extrasdir: extras
Fetching, essentially, is the process of grabbing data from the database and making it available to the application. Fetching, essentially, is the process of grabbing data from the database and making it available to the application.
@ -61,7 +63,7 @@ To see the difference between direct fetching and entity queries in regard to ea
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DirectVsQueryFetchingTest.java[tags=fetching-direct-vs-query-domain-model-example] include::{example-dir-fetching}/DirectVsQueryFetchingTest.java[tags=fetching-direct-vs-query-domain-model-example]
---- ----
==== ====
@ -74,7 +76,7 @@ When issuing a direct entity fetch, Hibernate executed the following SQL query:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DirectVsQueryFetchingTest.java[tags=fetching-direct-vs-query-direct-fetching-example] include::{example-dir-fetching}/DirectVsQueryFetchingTest.java[tags=fetching-direct-vs-query-direct-fetching-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -92,7 +94,7 @@ On the other hand, if you are using an entity query that does not contain a `JOI
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DirectVsQueryFetchingTest.java[tags=fetching-direct-vs-query-entity-query-example] include::{example-dir-fetching}/DirectVsQueryFetchingTest.java[tags=fetching-direct-vs-query-entity-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -122,7 +124,7 @@ Let's consider these topics as it relates to a sample domain model and a few use
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-domain-model-example] include::{example-dir-fetching}/FetchingTest.java[tags=fetching-strategies-domain-model-example]
---- ----
==== ====
@ -146,7 +148,7 @@ Let's assume that login only requires access to the `Employee` information, not
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-no-fetching-example] include::{example-dir-fetching}/FetchingTest.java[tags=fetching-strategies-no-fetching-example]
---- ----
==== ====
@ -160,7 +162,7 @@ If the login process does not need access to the `Employee` information specific
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-no-fetching-scalar-example] include::{example-dir-fetching}/FetchingTest.java[tags=fetching-strategies-no-fetching-scalar-example]
---- ----
==== ====
@ -175,7 +177,7 @@ Certainly access to the `Employee` is needed, as is the collection of `Projects`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-dynamic-fetching-jpql-example] include::{example-dir-fetching}/FetchingTest.java[tags=fetching-strategies-dynamic-fetching-jpql-example]
---- ----
==== ====
@ -184,7 +186,7 @@ include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-dynamic-fetching
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchingTest.java[tags=fetching-strategies-dynamic-fetching-criteria-example] include::{example-dir-fetching}/FetchingTest.java[tags=fetching-strategies-dynamic-fetching-criteria-example]
---- ----
==== ====
@ -208,12 +210,12 @@ Below is a `fetch graph` dynamic fetching example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-mapping-example] include::{example-dir-fetching}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-mapping-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-example] include::{example-dir-fetching}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-example]
---- ----
==== ====
@ -242,7 +244,7 @@ and we'd like to fetch the `department` for the `Employee` child association.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-subgraph-mapping-example] include::{example-dir-fetching}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-subgraph-mapping-example]
---- ----
==== ====
@ -253,7 +255,7 @@ When fetching this entity graph, Hibernate generates the following SQL query:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-subgraph-example] include::{example-dir-fetching}/GraphFetchingTest.java[tags=fetching-strategies-dynamic-fetching-entity-subgraph-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -302,7 +304,7 @@ the Jakarta Persistence specification proper.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-parsing-example-1] include::{example-dir-fetching}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-parsing-example-1]
---- ----
==== ====
@ -317,7 +319,7 @@ to the end of the attribute name.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-parsing-key-example-1] include::{example-dir-fetching}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-parsing-key-example-1]
---- ----
==== ====
@ -325,7 +327,7 @@ include::{sourcedir}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetc
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-parsing-key-example-2] include::{example-dir-fetching}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-parsing-key-example-2]
---- ----
==== ====
@ -376,7 +378,7 @@ the previous example can also be built by combining separate aspect graphs into
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-merging-example] include::{example-dir-fetching}/GraphParsingTest.java[tags=fetching-strategies-dynamic-fetching-entity-graph-merging-example]
---- ----
==== ====
@ -393,12 +395,12 @@ So we would leverage a fetch profile.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ProfileFetchingTest.java[tags=fetching-strategies-dynamic-fetching-profile-mapping-example] include::{example-dir-fetching}/ProfileFetchingTest.java[tags=fetching-strategies-dynamic-fetching-profile-mapping-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ProfileFetchingTest.java[tags=fetching-strategies-dynamic-fetching-profile-example] include::{example-dir-fetching}/ProfileFetchingTest.java[tags=fetching-strategies-dynamic-fetching-profile-example]
---- ----
==== ====
@ -419,7 +421,7 @@ Considering the following entity mapping:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchFetchingTest.java[tags=fetching-batch-mapping-example] include::{example-dir-fetching}/BatchFetchingTest.java[tags=fetching-batch-mapping-example]
---- ----
==== ====
@ -432,7 +434,7 @@ the `@BatchSize` annotations allows us to load multiple `Employee` entities in a
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BatchFetchingTest.java[tags=fetching-batch-fetching-example] include::{example-dir-fetching}/BatchFetchingTest.java[tags=fetching-batch-fetching-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -480,7 +482,7 @@ To demonstrate how `FetchMode.SELECT` works, consider the following entity mappi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchModeSelectTest.java[tags=fetching-strategies-fetch-mode-select-mapping-example] include::{example-dir-fetching}/FetchModeSelectTest.java[tags=fetching-strategies-fetch-mode-select-mapping-example]
---- ----
==== ====
@ -493,7 +495,7 @@ collection using a secondary `SELECT` statement upon accessing the child collect
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchModeSelectTest.java[tags=fetching-strategies-fetch-mode-select-example] include::{example-dir-fetching}/FetchModeSelectTest.java[tags=fetching-strategies-fetch-mode-select-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -516,7 +518,7 @@ To demonstrate how `FetchMode.SUBSELECT` works, we are going to modify the <<fet
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchModeSubselectTest.java[tags=fetching-strategies-fetch-mode-subselect-mapping-example] include::{example-dir-fetching}/FetchModeSubselectTest.java[tags=fetching-strategies-fetch-mode-subselect-mapping-example]
---- ----
==== ====
@ -532,7 +534,7 @@ Instead of passing all entity identifiers, Hibernate simply reruns the previous
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchModeSubselectTest.java[tags=fetching-strategies-fetch-mode-subselect-example] include::{example-dir-fetching}/FetchModeSubselectTest.java[tags=fetching-strategies-fetch-mode-subselect-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -552,7 +554,7 @@ To demonstrate how `FetchMode.JOIN` works, we are going to modify the <<fetching
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchModeJoinTest.java[tags=fetching-strategies-fetch-mode-join-mapping-example] include::{example-dir-fetching}/FetchModeJoinTest.java[tags=fetching-strategies-fetch-mode-join-mapping-example]
---- ----
==== ====
@ -578,7 +580,7 @@ Hibernate is going to avoid the secondary query by issuing an OUTER JOIN for the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FetchModeJoinTest.java[tags=fetching-strategies-fetch-mode-join-example] include::{example-dir-fetching}/FetchModeJoinTest.java[tags=fetching-strategies-fetch-mode-join-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -609,7 +611,7 @@ Each element is fetched individually using a secondary query.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/LazyCollectionTest.java[tags=fetching-LazyCollection-domain-model-example] include::{example-dir-fetching}/LazyCollectionTest.java[tags=fetching-LazyCollection-domain-model-example]
---- ----
==== ====
@ -630,7 +632,7 @@ Now, considering we have the following entities:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/LazyCollectionTest.java[tags=fetching-LazyCollection-persist-example] include::{example-dir-fetching}/LazyCollectionTest.java[tags=fetching-LazyCollection-persist-example]
---- ----
==== ====
@ -642,7 +644,7 @@ Hibernate generates the following SQL statements:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/LazyCollectionTest.java[tags=fetching-LazyCollection-select-example] include::{example-dir-fetching}/LazyCollectionTest.java[tags=fetching-LazyCollection-select-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[flushing]] [[flushing]]
== Flushing == Flushing
:sourcedir: ../../../../../test/java/org/hibernate/userguide/flush :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-flushing: {documentation-project-dir}/src/test/java/org/hibernate/userguide/flush
:extrasdir: extras :extrasdir: extras
Flushing is the process of synchronizing the state of the persistence context with the underlying database. Flushing is the process of synchronizing the state of the persistence context with the underlying database.
@ -43,7 +45,7 @@ In the following example, an entity is persisted, and then the transaction is co
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AutoFlushTest.java[tags=flushing-auto-flush-commit-example] include::{example-dir-flushing}/AutoFlushTest.java[tags=flushing-auto-flush-commit-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -70,7 +72,7 @@ A flush may also be triggered when executing an entity query.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AutoFlushTest.java[tags=flushing-auto-flush-jpql-example] include::{example-dir-flushing}/AutoFlushTest.java[tags=flushing-auto-flush-jpql-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -86,7 +88,7 @@ The reason why the `Advertisement` entity query didn't trigger a flush is that t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AutoFlushTest.java[tags=flushing-auto-flush-jpql-entity-example] include::{example-dir-flushing}/AutoFlushTest.java[tags=flushing-auto-flush-jpql-entity-example]
---- ----
==== ====
@ -97,7 +99,7 @@ When querying for a `Person` entity, the flush is triggered prior to executing t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AutoFlushTest.java[tags=flushing-auto-flush-jpql-overlap-example] include::{example-dir-flushing}/AutoFlushTest.java[tags=flushing-auto-flush-jpql-overlap-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -117,7 +119,7 @@ When executing a native SQL query, a flush is always triggered when using the `E
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AutoFlushTest.java[tags=flushing-auto-flush-sql-example] include::{example-dir-flushing}/AutoFlushTest.java[tags=flushing-auto-flush-sql-example]
---- ----
==== ====
@ -129,7 +131,7 @@ the `Session` API will trigger a flush automatically when executing a native que
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HibernateAutoFlushTest.java[tags=flushing-auto-flush-sql-native-example] include::{example-dir-flushing}/HibernateAutoFlushTest.java[tags=flushing-auto-flush-sql-native-example]
---- ----
==== ====
@ -140,7 +142,7 @@ To flush the `Session`, the query must use a synchronization:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AutoFlushTest.java[tags=flushing-auto-flush-sql-synchronization-example] include::{example-dir-flushing}/AutoFlushTest.java[tags=flushing-auto-flush-sql-synchronization-example]
---- ----
==== ====
@ -161,7 +163,7 @@ When executing a JPQL query, the persistence context is only flushed when the cu
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CommitFlushTest.java[tags=flushing-commit-flush-jpql-example] include::{example-dir-flushing}/CommitFlushTest.java[tags=flushing-commit-flush-jpql-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -177,7 +179,7 @@ Because the Jakarta Persistence doesn't impose a strict rule on delaying flushin
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CommitFlushTest.java[tags=flushing-commit-flush-sql-example] include::{example-dir-flushing}/CommitFlushTest.java[tags=flushing-commit-flush-sql-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -201,7 +203,7 @@ The `ALWAYS` flush mode triggers a persistence context flush even when executing
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AlwaysFlushTest.java[tags=flushing-always-flush-sql-example] include::{example-dir-flushing}/AlwaysFlushTest.java[tags=flushing-always-flush-sql-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -221,7 +223,7 @@ Hibernate also provides a `MANUAL` flush mode so the persistence context can onl
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ManualFlushTest.java[tags=flushing-manual-flush-example] include::{example-dir-flushing}/ManualFlushTest.java[tags=flushing-manual-flush-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -256,7 +258,7 @@ To visualize how this works, consider the following example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FlushOrderTest.java[tags=flushing-order-example] include::{example-dir-flushing}/FlushOrderTest.java[tags=flushing-order-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

40
documentation/src/main/asciidoc/userguide/chapters/locking/Locking.adoc
View File

@ -1,6 +1,8 @@
[[locking]] [[locking]]
== Locking == Locking
:sourcedir: ../../../../../test/java/org/hibernate/userguide/locking :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-locking: {documentation-project-dir}/src/test/java/org/hibernate/userguide/locking
:extrasdir: extras :extrasdir: extras
In a relational database, locking refers to actions taken to prevent data from changing between the time it is read and the time is used. In a relational database, locking refers to actions taken to prevent data from changing between the time it is read and the time is used.
@ -55,17 +57,17 @@ However, Hibernate allows you to use even Java 8 Date/Time types, such as `Insta
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-entity-mapping-example,indent=0] include::{example-dir-locking}/OptimisticLockingTest.java[tags=locking-optimistic-entity-mapping-example,indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockingTimestampTest.java[tags=locking-optimistic-entity-mapping-example,indent=0] include::{example-dir-locking}/OptimisticLockingTimestampTest.java[tags=locking-optimistic-entity-mapping-example,indent=0]
---- ----
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockingInstantTest.java[tags=locking-optimistic-entity-mapping-example,indent=0] include::{example-dir-locking}/OptimisticLockingInstantTest.java[tags=locking-optimistic-entity-mapping-example,indent=0]
---- ----
==== ====
@ -79,7 +81,7 @@ The version number mechanism for optimistic locking is provided through a `@Vers
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-version-number-example,indent=0] include::{example-dir-locking}/OptimisticLockingTest.java[tags=locking-optimistic-version-number-example,indent=0]
---- ----
==== ====
@ -108,7 +110,7 @@ Timestamping is automatically used if you the `@Version` annotation on a `Date`
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/OptimisticLockingTest.java[tags=locking-optimistic-version-timestamp-example,indent=0] include::{example-dir-locking}/OptimisticLockingTest.java[tags=locking-optimistic-version-timestamp-example,indent=0]
---- ----
==== ====
@ -119,7 +121,7 @@ The timestamp can also be generated by the database, instead of by the VM, using
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-mapping-example,indent=0] include::{example-dir-locking}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-mapping-example,indent=0]
---- ----
==== ====
@ -130,7 +132,7 @@ Now, when persisting a `Person` entity, Hibernate calls the database-specific cu
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-persist-example,indent=0] include::{example-dir-locking}/VersionSourceTest.java[tags=locking-optimistic-version-timestamp-source-persist-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]
@ -152,7 +154,7 @@ as illustrated in the following example.
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-mapping-example,indent=0] include::{example-dir-locking}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-mapping-example,indent=0]
---- ----
==== ====
@ -164,7 +166,7 @@ the two concurrent transactions are not going to conflict as illustrated by the
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-example,indent=0] include::{example-dir-locking}/OptimisticLockTest.java[tags=locking-optimistic-exclude-attribute-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]
@ -218,7 +220,7 @@ There are 4 available OptimisticLockTypes:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-example,indent=0] include::{example-dir-locking}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-example,indent=0]
---- ----
==== ====
@ -229,7 +231,7 @@ When you need to modify the `Person` entity above:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-update-example,indent=0] include::{example-dir-locking}/OptimisticLockTypeAllTest.java[tag=locking-optimistic-lock-type-all-update-example,indent=0]
---- ----
[source,SQL] [source,SQL]
@ -259,7 +261,7 @@ since the entity was loaded in the currently running Persistence Context.
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-example,indent=0] include::{example-dir-locking}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-example,indent=0]
---- ----
==== ====
@ -270,7 +272,7 @@ When you need to modify the `Person` entity above:
==== ====
[source,java] [source,java]
---- ----
include::{sourcedir}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-update-example,indent=0] include::{example-dir-locking}/OptimisticLockTypeDirtyTest.java[tag=locking-optimistic-lock-type-dirty-update-example,indent=0]
---- ----
[source,SQL] [source,SQL]
@ -354,7 +356,7 @@ The scope can either be `NORMAL` (default value) or `EXTENDED`. The `EXTENDED` s
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/ExplicitLockingTest.java[tags=locking-jpa-query-hints-timeout-example,indent=0] include::{example-dir-locking}/ExplicitLockingTest.java[tags=locking-jpa-query-hints-timeout-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]
@ -384,7 +386,7 @@ The following example shows how to obtain a shared database lock.
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/ExplicitLockingTest.java[tags=locking-session-lock-example,indent=0] include::{example-dir-locking}/ExplicitLockingTest.java[tags=locking-session-lock-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]
@ -410,7 +412,7 @@ For this reason, Hibernate uses secondary selects to lock the previously fetched
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-example,indent=0] include::{example-dir-locking}/ExplicitLockingTest.java[tags=locking-follow-on-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]
@ -429,7 +431,7 @@ To avoid the N+1 query problem, a separate query can be used to apply the lock u
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-secondary-query-example,indent=0] include::{example-dir-locking}/ExplicitLockingTest.java[tags=locking-follow-on-secondary-query-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]
@ -450,7 +452,7 @@ Even more important is that you can overrule the default follow-on-locking detec
==== ====
[source, JAVA,indent=0] [source, JAVA,indent=0]
---- ----
include::{sourcedir}/ExplicitLockingTest.java[tags=locking-follow-on-explicit-example,indent=0] include::{example-dir-locking}/ExplicitLockingTest.java[tags=locking-follow-on-explicit-example,indent=0]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]

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

@ -1,6 +1,8 @@
[[multitenacy]] [[multitenacy]]
== Multitenancy == Multitenancy
:sourcedir: ../../../../../test/java/org/hibernate/userguide/multitenancy :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-multitenancy: {documentation-project-dir}/src/test/java/org/hibernate/userguide/multitenancy
:extrasdir: extras :extrasdir: extras
[[multitenacy-intro]] [[multitenacy-intro]]
@ -69,7 +71,7 @@ The API is really just defined by passing the tenant identifier as part of openi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AbstractMultiTenancyTest.java[tags=multitenacy-hibernate-session-example] include::{example-dir-multitenancy}/AbstractMultiTenancyTest.java[tags=multitenacy-hibernate-session-example]
---- ----
==== ====
@ -128,7 +130,7 @@ The following example portrays a `MultiTenantConnectionProvider` implementation
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ConfigurableMultiTenantConnectionProvider.java[tags=multitenacy-hibernate-ConfigurableMultiTenantConnectionProvider-example] include::{example-dir-multitenancy}/ConfigurableMultiTenantConnectionProvider.java[tags=multitenacy-hibernate-ConfigurableMultiTenantConnectionProvider-example]
---- ----
==== ====
@ -139,7 +141,7 @@ The `ConfigurableMultiTenantConnectionProvider` can be set up as follows:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AbstractMultiTenancyTest.java[tags=multitenacy-hibernate-MultiTenantConnectionProvider-example] include::{example-dir-multitenancy}/AbstractMultiTenancyTest.java[tags=multitenacy-hibernate-MultiTenantConnectionProvider-example]
---- ----
==== ====
@ -150,7 +152,7 @@ When using multitenancy, it's possible to save an entity with the same identifie
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/AbstractMultiTenancyTest.java[tags=multitenacy-multitenacy-hibernate-same-entity-example] include::{example-dir-multitenancy}/AbstractMultiTenancyTest.java[tags=multitenacy-multitenacy-hibernate-same-entity-example]
---- ----
==== ====
@ -196,7 +198,7 @@ For instance, each tenant could specify a different time zone configuration.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-registerConnectionProvider-call-example] include::{example-dir-multitenancy}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-registerConnectionProvider-call-example]
---- ----
==== ====
@ -207,7 +209,7 @@ The `registerConnectionProvider` method is used to define the tenant-specific co
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-registerConnectionProvider-example] include::{example-dir-multitenancy}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-registerConnectionProvider-example]
---- ----
==== ====
@ -215,7 +217,7 @@ For our example, the tenant-specific context is held in the `connectionProviderM
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-context-example] include::{example-dir-multitenancy}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-context-example]
---- ----
Now, when building the Hibernate `Session`, aside from passing the tenant identifier, Now, when building the Hibernate `Session`, aside from passing the tenant identifier,
@ -226,7 +228,7 @@ we could also configure the `Session` to use the tenant-specific time zone.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-session-example] include::{example-dir-multitenancy}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-timezone-configuration-session-example]
---- ----
==== ====
@ -239,7 +241,7 @@ even if the currently running JVM uses a different time zone.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-applying-timezone-configuration-example] include::{example-dir-multitenancy}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-applying-timezone-configuration-example]
---- ----
==== ====
@ -252,7 +254,7 @@ test output.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-not-applying-timezone-configuration-example] include::{example-dir-multitenancy}/DatabaseTimeZoneMultiTenancyTest.java[tags=multitenacy-hibernate-not-applying-timezone-configuration-example]
---- ----
[source, SQL,indent=0] [source, SQL,indent=0]

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

@ -1,6 +1,8 @@
[[BytecodeEnhancement]] [[BytecodeEnhancement]]
=== Bytecode Enhancement === Bytecode Enhancement
:sourcedir: ../../../../../test/java/org/hibernate/userguide/pc :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-enhancement: {documentation-project-dir}/src/test/java/org/hibernate/userguide/pc
Hibernate "grew up" not supporting bytecode enhancement at all. Hibernate "grew up" not supporting bytecode enhancement at all.
At that time, Hibernate only supported proxy-based alternative for lazy loading and always used diff-based dirty calculation. At that time, Hibernate only supported proxy-based alternative for lazy loading and always used diff-based dirty calculation.
@ -29,7 +31,7 @@ This behavior is explicitly controllable through the `@org.hibernate.annotations
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-lazy-loading-example] include::{example-dir-enhancement}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-lazy-loading-example]
---- ----
==== ====
@ -67,7 +69,7 @@ Consider a domain model with a normal `Person`/`Book` bidirectional association:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty-tracking-bidirectional-example] include::{example-dir-enhancement}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty-tracking-bidirectional-example]
---- ----
==== ====
@ -76,7 +78,7 @@ include::{sourcedir}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty-tracking-bidirectional-incorrect-usage-example] include::{example-dir-enhancement}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty-tracking-bidirectional-incorrect-usage-example]
---- ----
==== ====
@ -87,7 +89,7 @@ This blows up in normal Java usage. The correct normal Java usage is:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty-tracking-bidirectional-correct-usage-example] include::{example-dir-enhancement}/BytecodeEnhancementTest.java[tags=BytecodeEnhancement-dirty-tracking-bidirectional-correct-usage-example]
---- ----
==== ====

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

@ -1,7 +1,9 @@
[[pc]] [[pc]]
== Persistence Context == Persistence Context
:sourcedir: ../../../../../test/java/org/hibernate/userguide/pc :root-project-dir: ../../../../../../..
:sourcedir-caching: ../../../../../test/java/org/hibernate/userguide/caching :documentation-project-dir: {root-project-dir}/documentation
:example-dir-pc: {documentation-project-dir}/src/test/java/org/hibernate/userguide/pc
:example-dir-caching: {documentation-project-dir}/src/test/java/org/hibernate/userguide/caching
:extrasdir: extras :extrasdir: extras
Both the `org.hibernate.Session` API and `jakarta.persistence.EntityManager` API represent a context for dealing with persistent data. Both the `org.hibernate.Session` API and `jakarta.persistence.EntityManager` API represent a context for dealing with persistent data.
@ -27,7 +29,7 @@ Jakarta Persistence defines an incredibly useful method to allow applications ac
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-unwrap-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-unwrap-example]
---- ----
==== ====
@ -44,7 +46,7 @@ You can make it persistent by associating it to either an `org.hibernate.Session
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-persist-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-persist-jpa-example]
---- ----
==== ====
@ -53,7 +55,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-persist-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-persist-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-persist-native-example]
---- ----
==== ====
@ -73,7 +75,7 @@ Entities can also be deleted.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-remove-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-remove-jpa-example]
---- ----
==== ====
@ -82,7 +84,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-remove-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-remove-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-remove-native-example]
---- ----
==== ====
@ -106,7 +108,7 @@ The most common case being the need to create an association between an entity a
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-get-reference-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-get-reference-jpa-example]
---- ----
==== ====
@ -115,7 +117,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-get-reference-jpa-examp
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-get-reference-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-get-reference-native-example]
---- ----
==== ====
@ -137,7 +139,7 @@ It is also quite common to want to obtain an entity along with its data (e.g. li
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-jpa-example]
---- ----
==== ====
@ -147,7 +149,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-jpa-example]
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-native-example]
---- ----
==== ====
@ -157,7 +159,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-native-example]
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-by-id-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-by-id-native-example]
---- ----
==== ====
@ -171,7 +173,7 @@ It's possible to return a Java 8 `Optional` as well:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-optional-by-id-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-optional-by-id-native-example]
---- ----
==== ====
@ -241,7 +243,7 @@ as illustrated by the following example:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MultiLoadIdTest.java[tags=pc-by-multiple-ids-example] include::{example-dir-pc}/MultiLoadIdTest.java[tags=pc-by-multiple-ids-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -262,7 +264,7 @@ https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MultiLoadIdTest.java[tags=pc-by-multiple-ids-second-level-cache-example] include::{example-dir-pc}/MultiLoadIdTest.java[tags=pc-by-multiple-ids-second-level-cache-example]
---- ----
==== ====
@ -289,7 +291,7 @@ In addition to allowing to load the entity by its identifier, Hibernate allows a
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-by-natural-id-entity-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-by-natural-id-entity-example]
---- ----
==== ====
@ -300,7 +302,7 @@ We can also opt to fetch the entity or just retrieve a reference to it when usin
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-by-simple-natural-id-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-by-simple-natural-id-example]
---- ----
==== ====
@ -309,7 +311,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-by-simple-natural-
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-by-natural-id-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-by-natural-id-example]
---- ----
==== ====
@ -320,7 +322,7 @@ We can also use a Java 8 `Optional` to load an entity by its natural id:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-find-optional-by-simple-natural-id-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-find-optional-by-simple-natural-id-example]
---- ----
==== ====
@ -357,7 +359,7 @@ This can be achieved using the `@Where` annotation, which can be applied to enti
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereTest.java[tags=pc-where-example] include::{example-dir-pc}/WhereTest.java[tags=pc-where-example]
---- ----
==== ====
@ -368,7 +370,7 @@ If the database contains the following entities:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereTest.java[tags=pc-where-persistence-example] include::{example-dir-pc}/WhereTest.java[tags=pc-where-persistence-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -384,7 +386,7 @@ When executing an `Account` entity query, Hibernate is going to filter out all r
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereTest.java[tags=pc-where-entity-query-example] include::{example-dir-pc}/WhereTest.java[tags=pc-where-entity-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -400,7 +402,7 @@ When fetching the `debitAccounts` or the `creditAccounts` collections, Hibernate
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereTest.java[tags=pc-where-collection-query-example] include::{example-dir-pc}/WhereTest.java[tags=pc-where-collection-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -419,7 +421,7 @@ Just like `@Where` annotation, `@WhereJoinTable` is used to filter out collectio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereJoinTableTest.java[tags=pc-where-join-table-example] include::{example-dir-pc}/WhereJoinTableTest.java[tags=pc-where-join-table-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -438,7 +440,7 @@ Considering that the following two `Book_Reader` entries are added into our syst
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereJoinTableTest.java[tags=pc-where-join-table-persist-example] include::{example-dir-pc}/WhereJoinTableTest.java[tags=pc-where-join-table-persist-example]
---- ----
==== ====
@ -449,7 +451,7 @@ When fetching the `currentWeekReaders` collection, Hibernate is going to find on
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/WhereJoinTableTest.java[tags=pc-where-join-table-fetch-example] include::{example-dir-pc}/WhereJoinTableTest.java[tags=pc-where-join-table-fetch-example]
---- ----
==== ====
@ -466,7 +468,7 @@ Now, considering we have the following `Account` entity:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-filter-Account-example] include::{example-dir-pc}/FilterTest.java[tags=pc-filter-Account-example]
---- ----
==== ====
@ -484,7 +486,7 @@ As already explained, we can also apply the `@Filter` annotation for collections
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-filter-Client-example] include::{example-dir-pc}/FilterTest.java[tags=pc-filter-Client-example]
---- ----
==== ====
@ -496,7 +498,7 @@ Hibernate will execute the following SQL statements:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-filter-persistence-example] include::{example-dir-pc}/FilterTest.java[tags=pc-filter-persistence-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -512,7 +514,7 @@ By default, without explicitly enabling the filter, Hibernate is going to fetch
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-no-filter-entity-query-example] include::{example-dir-pc}/FilterTest.java[tags=pc-no-filter-entity-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -529,7 +531,7 @@ then Hibernate is going to apply the filtering criteria to the associated `Accou
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-filter-entity-query-example] include::{example-dir-pc}/FilterTest.java[tags=pc-filter-entity-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -548,7 +550,7 @@ Therefore, even in the following example, the filter is taken into consideration
.Fetching entities mapped with `@Filter` .Fetching entities mapped with `@Filter`
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-filter-entity-example] include::{example-dir-pc}/FilterTest.java[tags=pc-filter-entity-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -566,7 +568,7 @@ Just like with entity queries, collections can be filtered as well, but only if
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-no-filter-collection-query-example] include::{example-dir-pc}/FilterTest.java[tags=pc-no-filter-collection-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -582,7 +584,7 @@ When activating the `@Filter` and fetching the `accounts` collections, Hibernate
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterTest.java[tags=pc-filter-collection-query-example] include::{example-dir-pc}/FilterTest.java[tags=pc-filter-collection-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -620,7 +622,7 @@ if the `@Filter` defines a condition that uses predicates across multiple tables
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterSqlFragementAliasTest.java[tags=pc-filter-sql-fragment-alias-example] include::{example-dir-pc}/FilterSqlFragementAliasTest.java[tags=pc-filter-sql-fragment-alias-example]
---- ----
==== ====
@ -632,7 +634,7 @@ Hibernate is going to apply the right table aliases to the filter predicates:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterSqlFragementAliasTest.java[tags=pc-filter-sql-fragment-alias-query-example] include::{example-dir-pc}/FilterSqlFragementAliasTest.java[tags=pc-filter-sql-fragment-alias-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -654,7 +656,7 @@ The `@FilterJoinTable` annotation can be, therefore, applied to a unidirectional
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterJoinTableTest.java[tags=pc-filter-join-table-example] include::{example-dir-pc}/FilterJoinTableTest.java[tags=pc-filter-join-table-example]
---- ----
==== ====
@ -669,7 +671,7 @@ Let's assume our database contains the following entities:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterJoinTableTest.java[tags=pc-filter-join-table-persistence-example] include::{example-dir-pc}/FilterJoinTableTest.java[tags=pc-filter-join-table-persistence-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -685,7 +687,7 @@ The collections can be filtered only if the associated filter is enabled on the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterJoinTableTest.java[tags=pc-no-filter-join-table-collection-query-example] include::{example-dir-pc}/FilterJoinTableTest.java[tags=pc-no-filter-join-table-collection-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -702,7 +704,7 @@ If we enable the filter and set the `maxOrderId` to `1` when fetching the `accou
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/FilterJoinTableTest.java[tags=pc-filter-join-table-collection-query-example] include::{example-dir-pc}/FilterJoinTableTest.java[tags=pc-filter-join-table-collection-query-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -722,7 +724,7 @@ There is no need to call a particular method to make your modifications persiste
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-managed-state-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-managed-state-jpa-example]
---- ----
==== ====
@ -731,7 +733,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-managed-state-jpa-examp
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-managed-state-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-managed-state-native-example]
---- ----
==== ====
@ -744,7 +746,7 @@ Therefore, considering you have the following `Product` entity mapping:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/NoDynamicUpdateTest.java[tags=pc-managed-state-update-mapping-example] include::{example-dir-pc}/NoDynamicUpdateTest.java[tags=pc-managed-state-update-mapping-example]
---- ----
==== ====
@ -755,7 +757,7 @@ If you persist the following `Product` entity:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/NoDynamicUpdateTest.java[tags=pc-managed-state-update-persist-example] include::{example-dir-pc}/NoDynamicUpdateTest.java[tags=pc-managed-state-update-persist-example]
---- ----
==== ====
@ -766,7 +768,7 @@ When you modify the `Product` entity, Hibernate generates the following SQL UPDA
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/NoDynamicUpdateTest.java[tags=pc-managed-state-update-example] include::{example-dir-pc}/NoDynamicUpdateTest.java[tags=pc-managed-state-update-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -795,7 +797,7 @@ To enable dynamic updates, you need to annotate the entity with the `@DynamicUpd
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/DynamicUpdateTest.java[tags=pc-managed-state-dynamic-update-mapping-example] include::{example-dir-pc}/DynamicUpdateTest.java[tags=pc-managed-state-dynamic-update-mapping-example]
---- ----
==== ====
@ -822,7 +824,7 @@ You can reload an entity instance and its collections at any time.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-refresh-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-refresh-jpa-example]
---- ----
==== ====
@ -831,7 +833,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-refresh-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-refresh-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-refresh-native-example]
---- ----
==== ====
@ -876,7 +878,7 @@ For instance, consider the following example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-refresh-child-entity-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-refresh-child-entity-jpa-example]
---- ----
==== ====
@ -912,7 +914,7 @@ Jakarta Persistence does not support reattaching detached data. This is only ava
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-detach-reattach-lock-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-detach-reattach-lock-example]
---- ----
==== ====
@ -921,7 +923,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-detach-reattach-lock-ex
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-detach-reattach-saveOrUpdate-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-detach-reattach-saveOrUpdate-example]
---- ----
==== ====
@ -947,7 +949,7 @@ Although not exactly per se, the following example is a good visualization of th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-merge-visualize-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-merge-visualize-example]
---- ----
==== ====
@ -956,7 +958,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-merge-visualize-example
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-merge-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-merge-jpa-example]
---- ----
==== ====
@ -965,7 +967,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-merge-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-merge-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-merge-native-example]
---- ----
==== ====
@ -1038,7 +1040,7 @@ An application can verify the state of entities and collections in relation to t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-contains-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-contains-jpa-example]
---- ----
==== ====
@ -1047,7 +1049,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-contains-jpa-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-contains-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-contains-native-example]
---- ----
==== ====
@ -1056,7 +1058,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-contains-native-example
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-verify-lazy-jpa-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-verify-lazy-jpa-example]
---- ----
==== ====
@ -1065,7 +1067,7 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-verify-lazy-jpa-example
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-verify-lazy-native-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-verify-lazy-native-example]
---- ----
==== ====
@ -1076,7 +1078,7 @@ In Jakarta Persistence there is an alternative means to check laziness using the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersistenceContextTest.java[tags=pc-verify-lazy-jpa-alternative-example] include::{example-dir-pc}/PersistenceContextTest.java[tags=pc-verify-lazy-jpa-alternative-example]
---- ----
==== ====
@ -1091,7 +1093,7 @@ the `evict()` method can be used to remove the object and its collections from t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir-caching}/FirstLevelCacheTest.java[tags=caching-management-jpa-detach-example] include::{example-dir-caching}/FirstLevelCacheTest.java[tags=caching-management-jpa-detach-example]
---- ----
==== ====
@ -1100,7 +1102,7 @@ include::{sourcedir-caching}/FirstLevelCacheTest.java[tags=caching-management-jp
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir-caching}/FirstLevelCacheTest.java[tags=caching-management-native-evict-example] include::{example-dir-caching}/FirstLevelCacheTest.java[tags=caching-management-native-evict-example]
---- ----
==== ====
@ -1111,7 +1113,7 @@ To detach all entities from the current persistence context, both the `EntityMan
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir-caching}/FirstLevelCacheTest.java[tags=caching-management-clear-example] include::{example-dir-caching}/FirstLevelCacheTest.java[tags=caching-management-clear-example]
---- ----
==== ====
@ -1122,7 +1124,7 @@ To verify if an entity instance is currently attached to the running persistence
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir-caching}/FirstLevelCacheTest.java[tags=caching-management-contains-example] include::{example-dir-caching}/FirstLevelCacheTest.java[tags=caching-management-contains-example]
---- ----
==== ====
@ -1149,9 +1151,9 @@ The following examples will explain some of the aforementioned cascade operation
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/Person.java[tags=pc-cascade-domain-model-example] include::{example-dir-pc}/Person.java[tags=pc-cascade-domain-model-example]
include::{sourcedir}/Phone.java[tags=pc-cascade-domain-model-example] include::{example-dir-pc}/Phone.java[tags=pc-cascade-domain-model-example]
---- ----
[[pc-cascade-persist]] [[pc-cascade-persist]]
@ -1164,7 +1166,7 @@ The `CascadeType.PERSIST` allows us to persist a child entity along with the par
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadePersistTest.java[tags=pc-cascade-persist-example] include::{example-dir-pc}/CascadePersistTest.java[tags=pc-cascade-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1185,7 +1187,7 @@ The `CascadeType.MERGE` allows us to merge a child entity along with the parent
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeMergeTest.java[tags=pc-cascade-merge-example] include::{example-dir-pc}/CascadeMergeTest.java[tags=pc-cascade-merge-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1209,7 +1211,7 @@ However, `CascadeType.REMOVE` and `org.hibernate.annotations.CascadeType.DELETE`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeRemoveTest.java[tags=pc-cascade-remove-example] include::{example-dir-pc}/CascadeRemoveTest.java[tags=pc-cascade-remove-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1228,7 +1230,7 @@ include::{extrasdir}/pc-cascade-remove-example.sql[]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeDetachTest.java[tags=pc-cascade-detach-example] include::{example-dir-pc}/CascadeDetachTest.java[tags=pc-cascade-detach-example]
---- ----
==== ====
@ -1245,7 +1247,7 @@ However, `CascadeType.LOCK` allows us to reattach a parent entity along with its
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeLockTest.java[tags=pc-cascade-lock-example] include::{example-dir-pc}/CascadeLockTest.java[tags=pc-cascade-lock-example]
---- ----
==== ====
@ -1260,7 +1262,7 @@ The refresh operation will discard the current entity state, and it will overrid
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeRefreshTest.java[tags=pc-cascade-refresh-example] include::{example-dir-pc}/CascadeRefreshTest.java[tags=pc-cascade-refresh-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1282,7 +1284,7 @@ The replicate operation allows you to synchronize entities coming from different
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeReplicateTest.java[tags=pc-cascade-replicate-example] include::{example-dir-pc}/CascadeReplicateTest.java[tags=pc-cascade-replicate-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1308,12 +1310,12 @@ as illustrated by the following example.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeOnDeleteTest.java[tags=pc-cascade-on-delete-mapping-Person-example] include::{example-dir-pc}/CascadeOnDeleteTest.java[tags=pc-cascade-on-delete-mapping-Person-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeOnDeleteTest.java[tags=pc-cascade-on-delete-mapping-Phone-example] include::{example-dir-pc}/CascadeOnDeleteTest.java[tags=pc-cascade-on-delete-mapping-Phone-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1329,7 +1331,7 @@ Now, you can just remove the `Person` entity, and the associated `Phone` entitie
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeOnDeleteTest.java[tags=pc-cascade-on-delete-example] include::{example-dir-pc}/CascadeOnDeleteTest.java[tags=pc-cascade-on-delete-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -1346,12 +1348,12 @@ illustrated in the following example.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeOnDeleteCollectionTest.java[tags=pc-cascade-on-delete-collection-mapping-Person-example] include::{example-dir-pc}/CascadeOnDeleteCollectionTest.java[tags=pc-cascade-on-delete-collection-mapping-Person-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeOnDeleteCollectionTest.java[tags=pc-cascade-on-delete-collection-mapping-Phone-example] include::{example-dir-pc}/CascadeOnDeleteCollectionTest.java[tags=pc-cascade-on-delete-collection-mapping-Phone-example]
---- ----
==== ====
@ -1362,7 +1364,7 @@ Now, when removing the `Person` entity, all the associated `Phone` child entitie
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CascadeOnDeleteCollectionTest.java[tags=pc-cascade-on-delete-collection-example] include::{example-dir-pc}/CascadeOnDeleteCollectionTest.java[tags=pc-cascade-on-delete-collection-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[criteria]] [[criteria]]
== Criteria == Criteria
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/criteria :root-project-dir: ../../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-criteria: {documentation-project-dir}/src/test/java/org/hibernate/userguide/criteria
Criteria queries offer a type-safe alternative to HQL, JPQL and native SQL queries. Criteria queries offer a type-safe alternative to HQL, JPQL and native SQL queries.
@ -49,7 +51,7 @@ The application wants to select entity instances.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-typedquery-entity-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-typedquery-entity-example]
---- ----
==== ====
@ -77,7 +79,7 @@ But this expression might also represent an aggregation, a mathematical operatio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-typedquery-expression-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-typedquery-expression-example]
---- ----
==== ====
@ -97,7 +99,7 @@ or consider a wrapper query, see <<criteria-typedquery-wrapper>> for details.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-typedquery-multiselect-array-explicit-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-typedquery-multiselect-array-explicit-example]
---- ----
==== ====
@ -111,7 +113,7 @@ The example then uses the array method of `jakarta.persistence.criteria.Criteria
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-typedquery-multiselect-array-implicit-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-typedquery-multiselect-array-implicit-example]
---- ----
==== ====
@ -131,9 +133,9 @@ Going back to the example query there, rather than returning an array of _[Perso
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersonWrapper.java[tags=criteria-typedquery-wrapper-example, indent=0] include::{example-dir-criteria}/PersonWrapper.java[tags=criteria-typedquery-wrapper-example, indent=0]
include::{sourcedir}/CriteriaTest.java[tags=criteria-typedquery-wrapper-example, indent=0] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-typedquery-wrapper-example, indent=0]
---- ----
==== ====
@ -155,7 +157,7 @@ A better approach to <<criteria-typedquery-multiselect>> is to use either a wrap
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-tuple-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-tuple-example]
---- ----
==== ====
@ -218,7 +220,7 @@ A root is always an entity type. Roots are defined and added to the criteria by
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-from-root-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-from-root-example]
---- ----
==== ====
@ -230,7 +232,7 @@ Here is an example defining a Cartesian Product between `Person` and `Partner` e
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-from-multiple-root-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-from-multiple-root-example]
---- ----
==== ====
@ -245,7 +247,7 @@ Joins are created by the numerous overloaded __join__ methods of the `jakarta.pe
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-from-join-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-from-join-example]
---- ----
==== ====
@ -260,7 +262,7 @@ Fetches are created by the numerous overloaded __fetch__ methods of the `jakarta
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-from-fetch-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-from-fetch-example]
---- ----
==== ====
@ -286,7 +288,7 @@ Roots, joins and fetches are themselves path expressions as well.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-param-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-param-example]
---- ----
==== ====
@ -301,6 +303,6 @@ Then use the parameter reference to bind the parameter value to the `jakarta.per
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CriteriaTest.java[tags=criteria-group-by-example] include::{example-dir-criteria}/CriteriaTest.java[tags=criteria-group-by-example]
---- ----
==== ====

82
documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc
View File

@ -1,7 +1,9 @@
[[hql]] [[hql]]
== Java API for HQL and JPQL == Java API for HQL and JPQL
:modeldir: ../../../../../../main/java/org/hibernate/userguide/model :root-project-dir: ../../../../../../../..
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/hql :documentation-project-dir: {root-project-dir}/documentation
:example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:example-dir-query: {documentation-project-dir}/src/test/java/org/hibernate/userguide/hql
:extrasdir: extras :extrasdir: extras
The Hibernate Query Language (HQL) and the Java Persistence Query Language (JPQL) are object-oriented query languages based on SQL and very similar in flavor to SQL. The Hibernate Query Language (HQL) and the Java Persistence Query Language (JPQL) are object-oriented query languages based on SQL and very similar in flavor to SQL.
@ -37,23 +39,23 @@ The code examples featured in this chapter, and the next, make use of the follow
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/Person.java[tags=hql-examples-domain-model-example]
include::{modeldir}/AddressType.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/AddressType.java[tags=hql-examples-domain-model-example]
include::{modeldir}/Partner.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/Partner.java[tags=hql-examples-domain-model-example]
include::{modeldir}/Phone.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/Phone.java[tags=hql-examples-domain-model-example]
include::{modeldir}/PhoneType.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/PhoneType.java[tags=hql-examples-domain-model-example]
include::{modeldir}/Call.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/Call.java[tags=hql-examples-domain-model-example]
include::{modeldir}/Payment.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/Payment.java[tags=hql-examples-domain-model-example]
include::{modeldir}/CreditCardPayment.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/CreditCardPayment.java[tags=hql-examples-domain-model-example]
include::{modeldir}/WireTransferPayment.java[tags=hql-examples-domain-model-example] include::{example-dir-model}/WireTransferPayment.java[tags=hql-examples-domain-model-example]
---- ----
==== ====
@ -79,7 +81,7 @@ Named queries may be defined using the Jakarta Persistence annotation `@NamedQue
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=jpa-read-only-entities-native-example] include::{example-dir-model}/Person.java[tags=jpa-read-only-entities-native-example]
---- ----
==== ====
@ -92,7 +94,7 @@ which allows the specification of additional properties of the query, including
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Phone.java[tags=jpql-api-hibernate-named-query-example, indent=0] include::{example-dir-model}/Phone.java[tags=jpql-api-hibernate-named-query-example, indent=0]
---- ----
//include::{sourcedir}/HQLTest.java[tags=jpql-api-hibernate-named-query-example, indent=0] //include::{sourcedir}/HQLTest.java[tags=jpql-api-hibernate-named-query-example, indent=0]
==== ====
@ -126,7 +128,7 @@ That way, you'll obtain a `TypedQuery<T>`, and avoid some later typecasting.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-example]
---- ----
==== ====
@ -135,9 +137,9 @@ include::{sourcedir}/HQLTest.java[tags=jpql-api-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=jpql-api-named-query-example, indent=0] include::{example-dir-model}/Person.java[tags=jpql-api-named-query-example, indent=0]
include::{sourcedir}/HQLTest.java[tags=jpql-api-named-query-example, indent=0] include::{example-dir-query}/HQLTest.java[tags=jpql-api-named-query-example, indent=0]
---- ----
==== ====
@ -161,7 +163,7 @@ Hibernate's `Query` interface offers additional operations not available via `Ty
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-api-example] include::{example-dir-query}/HQLTest.java[tags=hql-api-example]
---- ----
==== ====
@ -170,7 +172,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-api-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-api-named-query-example] include::{example-dir-query}/HQLTest.java[tags=hql-api-named-query-example]
---- ----
==== ====
@ -194,7 +196,7 @@ If the query has parameters, arguments must be bound to each parameter before th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-parameter-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-parameter-example]
---- ----
==== ====
@ -206,7 +208,7 @@ Just like with named parameters, a ordinal parameter may appear multiple times i
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-ordinal-parameter-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-ordinal-parameter-example]
---- ----
==== ====
@ -230,7 +232,7 @@ The `Query` interface is used to control the execution of the query.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-list-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-list-example]
---- ----
==== ====
@ -239,7 +241,7 @@ include::{sourcedir}/HQLTest.java[tags=jpql-api-list-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-single-result-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-single-result-example]
---- ----
==== ====
@ -248,7 +250,7 @@ include::{sourcedir}/HQLTest.java[tags=jpql-api-single-result-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-stream-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-stream-example]
---- ----
==== ====
@ -268,7 +270,7 @@ The very important methods `Query#setMaxResults()` and `Query#setFirstResult()`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-basic-usage-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-basic-usage-example]
---- ----
==== ====
@ -283,7 +285,7 @@ For example, we may want to specify an execution timeout or control caching.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-api-hint-usage-example] include::{example-dir-query}/HQLTest.java[tags=jpql-api-hint-usage-example]
---- ----
==== ====
@ -352,7 +354,7 @@ For complete details, see the https://docs.jboss.org/hibernate/orm/{majorMinorVe
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-api-basic-usage-example] include::{example-dir-query}/HQLTest.java[tags=hql-api-basic-usage-example]
---- ----
==== ====
@ -368,7 +370,7 @@ Hibernate provides several some built-in implementations of these interfaces, fo
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SelectDistinctTest.java[tags=hql-distinct-entity-resulttransformer-example] include::{example-dir-query}/SelectDistinctTest.java[tags=hql-distinct-entity-resulttransformer-example]
---- ----
==== ====
@ -470,7 +472,7 @@ Read-only entities are skipped by the dirty checking mechanism as illustrated by
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-read-only-entities-example] include::{example-dir-query}/HQLTest.java[tags=hql-read-only-entities-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -488,7 +490,7 @@ The method `Query#setReadOnly()` is an alternative to using a Jakarta Persistenc
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-read-only-entities-native-example] include::{example-dir-query}/HQLTest.java[tags=hql-read-only-entities-native-example]
---- ----
==== ====
@ -508,7 +510,7 @@ Depending on the specified `ScrollMode`, and on the capabilities of the JDBC dri
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-api-scroll-example] include::{example-dir-query}/HQLTest.java[tags=hql-api-scroll-example]
---- ----
==== ====
@ -541,7 +543,7 @@ For that, use `getResultList().stream()`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-api-stream-projection-example] include::{example-dir-query}/HQLTest.java[tags=hql-api-stream-projection-example]
---- ----
==== ====
@ -550,7 +552,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-api-stream-projection-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-api-stream-example] include::{example-dir-query}/HQLTest.java[tags=hql-api-stream-example]
---- ----
==== ====
@ -593,9 +595,9 @@ it does not expose a `#executeUpdate` method. This allows for earlier validatio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SelectionQueryExampleTests.java[tags=example-hql-selection-query] include::{example-dir-query}/SelectionQueryExampleTests.java[tags=example-hql-selection-query]
include::{sourcedir}/SelectionQueryExampleTests.java[tags=example-hql-selection-query-query] include::{example-dir-query}/SelectionQueryExampleTests.java[tags=example-hql-selection-query-query]
---- ----
==== ====
@ -606,9 +608,9 @@ include::{sourcedir}/SelectionQueryExampleTests.java[tags=example-hql-selection-
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SelectionQueryExampleTests.java[tags=example-hql-named-selection-query] include::{example-dir-query}/SelectionQueryExampleTests.java[tags=example-hql-named-selection-query]
include::{sourcedir}/SelectionQueryExampleTests.java[tags=example-hql-named-selection-query-query] include::{example-dir-query}/SelectionQueryExampleTests.java[tags=example-hql-named-selection-query-query]
---- ----
==== ====
@ -626,9 +628,9 @@ For example, in terms of execution, it only exposes `#executeUpdate` method. Th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MutationQueryExampleTests.java[tags=example-hql-mutation-query] include::{example-dir-query}/MutationQueryExampleTests.java[tags=example-hql-mutation-query]
include::{sourcedir}/MutationQueryExampleTests.java[tags=example-hql-mutation-query-query] include::{example-dir-query}/MutationQueryExampleTests.java[tags=example-hql-mutation-query-query]
---- ----
==== ====
@ -640,9 +642,9 @@ include::{sourcedir}/MutationQueryExampleTests.java[tags=example-hql-mutation-qu
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MutationQueryExampleTests.java[tags=example-hql-named-mutation-query] include::{example-dir-query}/MutationQueryExampleTests.java[tags=example-hql-named-mutation-query]
include::{sourcedir}/MutationQueryExampleTests.java[tags=example-hql-named-mutation-query-query] include::{example-dir-query}/MutationQueryExampleTests.java[tags=example-hql-named-mutation-query-query]
---- ----
==== ====

196
documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc
View File

@ -1,7 +1,9 @@
[[query-language]] [[query-language]]
== Hibernate Query Language == Hibernate Query Language
:modeldir: ../../../../../../main/java/org/hibernate/userguide/model :root-project-dir: ../../../../../../../..
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/hql :documentation-project-dir: {root-project-dir}/documentation
:example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:example-dir-hql: ../../../../../../test/java/org/hibernate/userguide/hql
:extrasdir: extras :extrasdir: extras
This chapter describes Hibernate Query Language (HQL) and Jakarta Persistence Query Language (JPQL). This chapter describes Hibernate Query Language (HQL) and Jakarta Persistence Query Language (JPQL).
@ -107,7 +109,7 @@ For example, the simplest query in HQL has no `select` clause at all:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-simplest-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-simplest-example]
---- ----
==== ====
@ -121,14 +123,14 @@ Naturally, the previous query may be written with a `select` clause:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-simplest-jpql-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-simplest-jpql-example]
---- ----
When there's no explicit `select` clause, the select list is implied by the result type of the query: When there's no explicit `select` clause, the select list is implied by the result type of the query:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-no-from] include::{example-dir-hql}/HQLTest.java[tags=hql-select-no-from]
---- ----
For complicated queries, it's probably best to explicitly specify a `select` list. For complicated queries, it's probably best to explicitly specify a `select` list.
@ -140,7 +142,7 @@ An alternative "simplest" query has _only_ a `select` list:
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-simplest-example-alt] include::{example-dir-hql}/HQLTest.java[tags=hql-select-simplest-example-alt]
---- ----
==== ====
@ -155,7 +157,7 @@ But it's more natural to put it last:
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-last-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-last-example]
---- ----
This form of the query is more readable, because the alias is declared _before_ it's used, just as God and nature intended. This form of the query is more readable, because the alias is declared _before_ it's used, just as God and nature intended.
@ -182,7 +184,7 @@ For example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-update-example] include::{example-dir-hql}/HQLTest.java[tags=hql-update-example]
---- ----
==== ====
@ -194,9 +196,9 @@ A single HQL `update` statement might result in multiple SQL update statements e
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/../batch/BatchTest.java[tags=batch-bulk-jpql-update-example] include::{example-dir-hql}/../batch/BatchTest.java[tags=batch-bulk-jpql-update-example]
include::{sourcedir}/../batch/BatchTest.java[tags=batch-bulk-hql-update-example] include::{example-dir-hql}/../batch/BatchTest.java[tags=batch-bulk-hql-update-example]
---- ----
==== ====
@ -222,7 +224,7 @@ Adding the keyword `versioned`&mdash;writing `update versioned`&mdash;specifies
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/../batch/BatchTest.java[tags=batch-bulk-hql-update-version-example] include::{example-dir-hql}/../batch/BatchTest.java[tags=batch-bulk-hql-update-version-example]
---- ----
==== ====
@ -288,12 +290,12 @@ For example:
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-insert-example] include::{example-dir-hql}/HQLTest.java[tags=hql-insert-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/../batch/BatchTest.java[tags=batch-bulk-hql-insert-example] include::{example-dir-hql}/../batch/BatchTest.java[tags=batch-bulk-hql-insert-example]
---- ----
==== ====
@ -357,7 +359,7 @@ To escape a single quote within a string literal, use a doubled single quote: `'
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-string-literals-example] include::{example-dir-hql}/HQLTest.java[tags=hql-string-literals-example]
---- ----
==== ====
@ -371,7 +373,7 @@ Numeric literals come in several different forms.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-numeric-literals-example] include::{example-dir-hql}/HQLTest.java[tags=hql-numeric-literals-example]
---- ----
==== ====
@ -472,7 +474,7 @@ Literal values of a Java enumerated type may be written without needing to speci
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-enum-example] include::{example-dir-hql}/HQLTest.java[tags=hql-enum-example]
---- ----
==== ====
@ -487,7 +489,7 @@ HQL allows any Java `static` constant to be used in HQL, but it must be referenc
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-java-constant-example] include::{example-dir-hql}/HQLTest.java[tags=hql-java-constant-example]
---- ----
==== ====
@ -516,7 +518,7 @@ See <<hql-functions-string,below>> for details of the `concat()` function.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-concatenation-example] include::{example-dir-hql}/HQLTest.java[tags=hql-concatenation-example]
---- ----
==== ====
@ -532,7 +534,7 @@ The basic SQL arithmetic operators, `+`,`-`,`*`, and `/` are joined by the remai
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-numeric-arithmetic-example] include::{example-dir-hql}/HQLTest.java[tags=hql-numeric-arithmetic-example]
---- ----
==== ====
@ -615,7 +617,7 @@ For example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-simple-case-expressions-example] include::{example-dir-hql}/HQLTest.java[tags=hql-simple-case-expressions-example]
---- ----
==== ====
@ -637,7 +639,7 @@ For example:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-searched-case-expressions-example] include::{example-dir-hql}/HQLTest.java[tags=hql-searched-case-expressions-example]
---- ----
==== ====
@ -648,7 +650,7 @@ A `case` expression may contain complex expression, including operator expressio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-case-arithmetic-expressions-example] include::{example-dir-hql}/HQLTest.java[tags=hql-case-arithmetic-expressions-example]
---- ----
==== ====
@ -703,7 +705,7 @@ This is mainly useful when dealing with entity inheritance hierarchies.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-entity-type-exp-example] include::{example-dir-hql}/HQLTest.java[tags=hql-entity-type-exp-example]
---- ----
==== ====
@ -717,7 +719,7 @@ This is useful when dealing with entity inheritance hierarchies.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-treat-example] include::{example-dir-hql}/HQLTest.java[tags=hql-treat-example]
---- ----
==== ====
@ -738,7 +740,7 @@ The target type is an unqualified Java class name:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-cast-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-cast-function-example]
---- ----
==== ====
@ -750,7 +752,7 @@ The function `str(x)` is a synonym for `cast(x as String)`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-str-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-str-function-example]
---- ----
==== ====
@ -775,7 +777,7 @@ An abbreviated `case` expression that returns the first non-null operand.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-coalesce-example] include::{example-dir-hql}/HQLTest.java[tags=hql-coalesce-example]
---- ----
==== ====
@ -791,7 +793,7 @@ Evaluates to null if its operands are equal, or to its first argument otherwise.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-nullif-example] include::{example-dir-hql}/HQLTest.java[tags=hql-nullif-example]
---- ----
==== ====
@ -818,7 +820,7 @@ For a full list of field types, see the Javadoc for https://docs.jboss.org/hiber
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-extract-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-extract-function-example]
---- ----
==== ====
@ -840,7 +842,7 @@ TIP: These abbreviations aren't part of the JPQL standard, but on the other hand
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-year-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-year-function-example]
---- ----
==== ====
@ -892,7 +894,7 @@ Accepts a variable number of arguments, and produces a string by concatenating t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-concat-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-concat-function-example]
---- ----
==== ====
@ -904,7 +906,7 @@ The JPQL function `locate()` determines the position of a substring within anoth
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-locate-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-locate-function-example]
---- ----
==== ====
@ -915,7 +917,7 @@ The `position()` function has a similar purpose, but follows the ANSI SQL syntax
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-position-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-position-function-example]
---- ----
==== ====
@ -928,7 +930,7 @@ Returns a substring of the given string.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-substring-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-substring-function-example]
---- ----
==== ====
@ -939,7 +941,7 @@ It may be used to trim `leading` characters, `trailing` characters, or both.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-trim-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-trim-function-example]
---- ----
==== ====
@ -1015,15 +1017,15 @@ Of course, we also have a number of functions for working with numeric values.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-abs-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-abs-function-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-mod-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-mod-function-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-sqrt-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-sqrt-function-example]
---- ----
==== ====
@ -1057,7 +1059,7 @@ The number of elements of a collection or to-many association.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-size-example] include::{example-dir-hql}/HQLTest.java[tags=hql-size-example]
---- ----
==== ====
@ -1124,7 +1126,7 @@ Then at startup Hibernate will log a list of type signatures of all registered f
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-native-function-example] include::{example-dir-hql}/HQLTest.java[tags=hql-native-function-example]
---- ----
==== ====
@ -1170,7 +1172,7 @@ The operands should be of the same type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-relational-comparisons-example] include::{example-dir-hql}/HQLTest.java[tags=hql-relational-comparisons-example]
---- ----
==== ====
@ -1186,7 +1188,7 @@ Of course, all three operands must be of compatible type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-between-predicate-example] include::{example-dir-hql}/HQLTest.java[tags=hql-between-predicate-example]
---- ----
==== ====
@ -1207,7 +1209,7 @@ The following operators make it easier to deal with null values.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-null-predicate-example] include::{example-dir-hql}/HQLTest.java[tags=hql-null-predicate-example]
---- ----
==== ====
@ -1236,7 +1238,7 @@ The expression on the right is a pattern, where:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-like-predicate-example] include::{example-dir-hql}/HQLTest.java[tags=hql-like-predicate-example]
---- ----
==== ====
@ -1249,7 +1251,7 @@ For example, to match all stored procedures prefixed with `Dr_`, the like criter
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-like-predicate-escape-example] include::{example-dir-hql}/HQLTest.java[tags=hql-like-predicate-escape-example]
---- ----
==== ====
@ -1317,7 +1319,7 @@ Even embedded attributes are allowed, although that feature depends on the level
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-in-predicate-example] include::{example-dir-hql}/HQLTest.java[tags=hql-in-predicate-example]
---- ----
==== ====
@ -1326,7 +1328,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-in-predicate-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-expressions-in-example] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-expressions-in-example]
---- ----
==== ====
@ -1352,7 +1354,7 @@ The qualifiers are unary prefix operators: `all`, `every`, `any`, and `some`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-all-subquery-comparison-qualifier-example] include::{example-dir-hql}/HQLTest.java[tags=hql-all-subquery-comparison-qualifier-example]
---- ----
==== ====
@ -1361,12 +1363,12 @@ include::{sourcedir}/HQLTest.java[tags=hql-all-subquery-comparison-qualifier-exa
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-expressions-all-example] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-expressions-all-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-expressions-some-example] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-expressions-some-example]
---- ----
==== ====
@ -1387,7 +1389,7 @@ As you can surely guess, `not exists` evaluates to true if the thing to the righ
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-expressions-exists-example] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-expressions-exists-example]
---- ----
==== ====
@ -1408,7 +1410,7 @@ The following operators apply to collection-valued attributes and to-many associ
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-empty-collection-predicate-example] include::{example-dir-hql}/HQLTest.java[tags=hql-empty-collection-predicate-example]
---- ----
==== ====
@ -1417,7 +1419,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-empty-collection-predicate-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-member-of-collection-predicate-example] include::{example-dir-hql}/HQLTest.java[tags=hql-member-of-collection-predicate-example]
---- ----
==== ====
@ -1463,7 +1465,7 @@ Remember, the _entity name_ is the value of the `name` member of the `@Entity` a
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-simplest-jpql-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-simplest-jpql-example]
---- ----
==== ====
@ -1477,7 +1479,7 @@ Then Hibernate will query every entity which inherits the named type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-simplest-jpql-fqn-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-simplest-jpql-fqn-example]
---- ----
==== ====
@ -1488,12 +1490,12 @@ Of course, there may be multiple root entities.
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-multiple-root-reference-jpql-example] include::{example-dir-hql}/HQLTest.java[tags=hql-multiple-root-reference-jpql-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-multiple-same-root-reference-jpql-example] include::{example-dir-hql}/HQLTest.java[tags=hql-multiple-same-root-reference-jpql-example]
---- ----
==== ====
@ -1504,7 +1506,7 @@ The previous queries may even be written using the syntax `cross join` in place
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-cross-join-jpql-example] include::{example-dir-hql}/HQLTest.java[tags=hql-cross-join-jpql-example]
---- ----
==== ====
@ -1518,7 +1520,7 @@ Consider:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-polymorphism-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-polymorphism-example, indent=0]
---- ----
==== ====
@ -1547,7 +1549,7 @@ It must declare an identification variable.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-derived-root-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-derived-root-example, indent=0]
---- ----
==== ====
@ -1597,7 +1599,7 @@ An explicit root join works just like an ANSI-style join in SQL.
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-explicit-root-join-example] include::{example-dir-hql}/HQLTest.java[tags=hql-explicit-root-join-example]
---- ----
==== ====
@ -1627,7 +1629,7 @@ An explicit join may assign an identification variable to the joined entity.
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-explicit-inner-join-example] include::{example-dir-hql}/HQLTest.java[tags=hql-explicit-inner-join-example]
---- ----
==== ====
@ -1636,7 +1638,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-explicit-inner-join-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-explicit-outer-join-example] include::{example-dir-hql}/HQLTest.java[tags=hql-explicit-outer-join-example]
---- ----
==== ====
@ -1663,7 +1665,7 @@ Join conditions occurring in the `with` or `on` clause are added to the `on` cla
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-explicit-join-with-example] include::{example-dir-hql}/HQLTest.java[tags=hql-explicit-join-with-example]
---- ----
==== ====
@ -1674,7 +1676,7 @@ The following query is arguably less clear, but semantically equivalent:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-explicit-join-jpql-on-example] include::{example-dir-hql}/HQLTest.java[tags=hql-explicit-join-jpql-on-example]
---- ----
==== ====
@ -1701,7 +1703,7 @@ For example, if `Person` has a one-to-many association named `phones`, the use o
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-explicit-fetch-join-example] include::{example-dir-hql}/HQLTest.java[tags=hql-explicit-fetch-join-example]
---- ----
==== ====
@ -1738,7 +1740,7 @@ An explicit join may narrow the type of the joined entity using `treat()`.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-join-treat-example] include::{example-dir-hql}/HQLTest.java[tags=hql-join-treat-example]
---- ----
==== ====
@ -1761,7 +1763,7 @@ The `lateral` keyword just distinguishes the two cases.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-derived-join-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-derived-join-example, indent=0]
---- ----
==== ====
@ -1808,7 +1810,7 @@ In the second case, Hibernate with automatically add a join to the generated SQL
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-implicit-join-example] include::{example-dir-hql}/HQLTest.java[tags=hql-implicit-join-example]
---- ----
==== ====
@ -1825,7 +1827,7 @@ Note that:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-implicit-join-alias-example] include::{example-dir-hql}/HQLTest.java[tags=hql-implicit-join-alias-example]
---- ----
==== ====
@ -1843,7 +1845,7 @@ When a join involves a collection or many-valued association, the declared ident
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-valued-associations] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-valued-associations]
---- ----
==== ====
@ -1872,9 +1874,9 @@ In particular, `index()` and `key()` obtain a reference to a list index or map k
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Phone.java[tags=hql-collection-qualification-example, indent=0] include::{example-dir-model}/Phone.java[tags=hql-collection-qualification-example, indent=0]
include::{sourcedir}/HQLTest.java[tags=hql-collection-qualification-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-qualification-example, indent=0]
---- ----
==== ====
@ -1887,7 +1889,7 @@ The functions `element()`, `index()`, `key()`, and `value()` may even be applied
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-implicit-join-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-implicit-join-example, indent=0]
---- ----
==== ====
@ -1898,7 +1900,7 @@ An element of an indexed collection (an array, list, or map) may even be identif
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-index-operator-example] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-index-operator-example]
---- ----
==== ====
@ -1931,7 +1933,7 @@ But if there are multiple expressions in the select list then:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=jpql-projection-example] include::{example-dir-hql}/HQLTest.java[tags=jpql-projection-example]
---- ----
==== ====
@ -1967,9 +1969,9 @@ The `select new` construct packages the query results into a user-written Java c
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CallStatistics.java[tags=hql-select-clause-dynamic-instantiation-example] include::{example-dir-hql}/CallStatistics.java[tags=hql-select-clause-dynamic-instantiation-example]
include::{sourcedir}/HQLTest.java[tags=hql-select-clause-dynamic-instantiation-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-select-clause-dynamic-instantiation-example, indent=0]
---- ----
==== ====
@ -1989,7 +1991,7 @@ Alternatively, using the syntax `select new map`, the query may specify that eac
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-clause-dynamic-map-instantiation-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-clause-dynamic-map-instantiation-example]
---- ----
==== ====
@ -2003,7 +2005,7 @@ Or, using the syntax `select new list`, the query may specify that each result s
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-select-clause-dynamic-list-instantiation-example] include::{example-dir-hql}/HQLTest.java[tags=hql-select-clause-dynamic-list-instantiation-example]
---- ----
==== ====
@ -2025,7 +2027,7 @@ It's only effect is to add `distinct` to the generated SQL.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SelectDistinctTest.java[tags=hql-distinct-projection-query-example] include::{example-dir-hql}/SelectDistinctTest.java[tags=hql-distinct-projection-query-example]
---- ----
==== ====
@ -2072,7 +2074,7 @@ There are also <<hql-aggregate-functions-orderedset,ordered set aggregate functi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-aggregate-functions-example] include::{example-dir-hql}/HQLTest.java[tags=hql-aggregate-functions-example]
---- ----
==== ====
@ -2110,7 +2112,7 @@ The `elements()` and `indices()` functions we met <<hql-elements-indices,earlier
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-collection-expressions-example] include::{example-dir-hql}/HQLTest.java[tags=hql-collection-expressions-example]
---- ----
==== ====
@ -2129,12 +2131,12 @@ All aggregate functions support the inclusion of a _filter clause_, a sort of mi
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-aggregate-functions-simple-filter-example] include::{example-dir-hql}/HQLTest.java[tags=hql-aggregate-functions-simple-filter-example]
---- ----
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-aggregate-functions-filter-example] include::{example-dir-hql}/HQLTest.java[tags=hql-aggregate-functions-filter-example]
---- ----
==== ====
@ -2168,7 +2170,7 @@ This function has different names on different databases, but HQL abstracts thes
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-aggregate-functions-within-group-example] include::{example-dir-hql}/HQLTest.java[tags=hql-aggregate-functions-within-group-example]
---- ----
==== ====
@ -2275,7 +2277,7 @@ Consider the following queries:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-group-by-example] include::{example-dir-hql}/HQLTest.java[tags=hql-group-by-example]
---- ----
==== ====
@ -2307,7 +2309,7 @@ If that ended up being too much data to deal with, we might want to restrict the
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-group-by-having-example] include::{example-dir-hql}/HQLTest.java[tags=hql-group-by-having-example]
---- ----
==== ====
@ -2329,7 +2331,7 @@ Just like in SQL, `all` suppresses the elimination of duplicate results.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-union-example] include::{example-dir-hql}/HQLTest.java[tags=hql-union-example]
---- ----
==== ====
@ -2394,7 +2396,7 @@ Therefore, the sorting of null values may also be explicitly specified:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-order-by-example] include::{example-dir-hql}/HQLTest.java[tags=hql-order-by-example]
---- ----
==== ====
@ -2431,7 +2433,7 @@ These two queries are identical:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-limit-example] include::{example-dir-hql}/HQLTest.java[tags=hql-limit-example]
---- ----
==== ====
@ -2452,7 +2454,7 @@ This next query is accepted by HQL, and no more than 50 results are returned by
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-bad-limit-example] include::{example-dir-hql}/HQLTest.java[tags=hql-bad-limit-example]
---- ----
==== ====
@ -2513,7 +2515,7 @@ whereas `NOT MATERIALIZED` will cause the subquery to be inlined into every use
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-cte-materialized-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-cte-materialized-example, indent=0]
---- ----
==== ====
@ -2532,7 +2534,7 @@ Recursive CTEs must follow a very particular shape, which is
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-cte-recursive-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-cte-recursive-example, indent=0]
---- ----
==== ====
@ -2578,7 +2580,7 @@ A DBMS has two possible orders when executing the recursive query part
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-cte-recursive-search-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-cte-recursive-search-example, indent=0]
---- ----
==== ====
@ -2606,7 +2608,7 @@ cycleClause
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/HQLTest.java[tags=hql-cte-recursive-cycle-example, indent=0] include::{example-dir-hql}/HQLTest.java[tags=hql-cte-recursive-cycle-example, indent=0]
---- ----
==== ====
@ -2617,4 +2619,4 @@ Therefore, this feature will only work if the database supports recursive CTEs.
Hibernate does emulate the `search` and `cycle` clauses though if necessary, so you can safely use that. Hibernate does emulate the `search` and `cycle` clauses though if necessary, so you can safely use that.
Note that most modern database versions support recursive CTEs already. Note that most modern database versions support recursive CTEs already.
==== ====

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

@ -1,7 +1,9 @@
[[sql]] [[sql]]
== Native SQL Queries == Native SQL Queries
:modeldir: ../../../../../../main/java/org/hibernate/userguide/model :root-project-dir: ../../../../../../../..
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/sql :documentation-project-dir: {root-project-dir}/documentation
:example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:doc-emeddable-example-dir: ../../../../../../test/java/org/hibernate/userguide/sql
:extrasdir: extras :extrasdir: extras
You may also express queries in the native SQL dialect of your database. You may also express queries in the native SQL dialect of your database.
@ -25,7 +27,7 @@ The most basic SQL query is to get a list of scalars (column) values.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-all-columns-scalar-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-all-columns-scalar-query-example]
---- ----
==== ====
@ -34,7 +36,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-all-columns-scalar-query-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-custom-column-selection-scalar-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-custom-column-selection-scalar-query-example]
---- ----
==== ====
@ -43,7 +45,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-custom-column-selection-scalar-qu
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-all-columns-scalar-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-all-columns-scalar-query-example]
---- ----
==== ====
@ -52,7 +54,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-hibernate-all-columns-scalar-query-ex
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-custom-column-selection-scalar-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-custom-column-selection-scalar-query-example]
---- ----
==== ====
@ -66,7 +68,7 @@ To avoid the overhead of using `ResultSetMetadata`, or simply to be more explici
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-scalar-query-explicit-result-set-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-scalar-query-explicit-result-set-example]
---- ----
==== ====
@ -80,7 +82,7 @@ It is possible to leave out the type information for all or some of the scalars.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-scalar-query-partial-explicit-result-set-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-scalar-query-partial-explicit-result-set-example]
---- ----
==== ====
@ -99,7 +101,7 @@ The above queries were all about returning scalar values, basically returning th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-entity-query-example]
---- ----
==== ====
@ -108,7 +110,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-query-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-query-example]
---- ----
==== ====
@ -120,7 +122,7 @@ the following query will also return a `List` where each element is a `Person` e
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-query-explicit-result-set-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-entity-query-explicit-result-set-example]
---- ----
==== ====
@ -129,7 +131,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-query-explicit-result-set-
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-query-explicit-result-set-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-query-explicit-result-set-example]
---- ----
==== ====
@ -145,7 +147,7 @@ otherwise, a database-specific _column not found_ error will occur.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-associations-query-many-to-one-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-entity-associations-query-many-to-one-example]
---- ----
==== ====
@ -154,7 +156,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-associations-query-many-to
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-many-to-one-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-many-to-one-example]
---- ----
==== ====
@ -168,7 +170,7 @@ It is possible to eagerly join the `Phone` and the `Person` entities to avoid th
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-many-to-one-join-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-many-to-one-join-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -190,7 +192,7 @@ Joined entities will only be present for their respective association.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-many-to-one-join-tuple-transformer-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-many-to-one-join-tuple-transformer-example]
---- ----
==== ====
@ -202,7 +204,7 @@ It is possible to do the same eager joining for collections (e.g. the `Phone#cal
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-associations-query-one-to-many-join-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-entity-associations-query-one-to-many-join-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -216,7 +218,7 @@ include::{extrasdir}/sql-jpa-entity-associations-query-one-to-many-join-example.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-one-to-many-join-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-one-to-many-join-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -241,7 +243,7 @@ Column alias injection is needed in the following query which otherwise throws `
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-multi-entity-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-multi-entity-query-example]
---- ----
==== ====
@ -250,7 +252,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-multi-entity-query-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-multi-entity-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-multi-entity-query-example]
---- ----
==== ====
@ -266,7 +268,7 @@ The following form is not vulnerable to column name duplication:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-multi-entity-query-alias-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-multi-entity-query-alias-example]
---- ----
==== ====
@ -329,9 +331,9 @@ It is possible to apply a `ResultTransformer` to native SQL queries, allowing it
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/PersonSummaryDTO.java[tags=sql-hibernate-dto-query-example, indent=0] include::{doc-emeddable-example-dir}/PersonSummaryDTO.java[tags=sql-hibernate-dto-query-example, indent=0]
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-dto-query-example, indent=0] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-dto-query-example, indent=0]
---- ----
==== ====
@ -352,7 +354,7 @@ Native SQL queries which query for entities that are mapped as part of an inheri
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-inheritance-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-inheritance-query-example]
---- ----
==== ====
@ -371,7 +373,7 @@ Native SQL queries support ordinal as well as named parameters:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-query-parameters-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-query-parameters-example]
---- ----
==== ====
@ -380,7 +382,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-query-parameters-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-query-parameters-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-query-parameters-example]
---- ----
==== ====
@ -423,7 +425,7 @@ To fetch a single column of given table, the named query looks as follows:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=sql-scalar-NamedNativeQuery-example] include::{example-dir-model}/Person.java[tags=sql-scalar-NamedNativeQuery-example]
---- ----
==== ====
@ -432,7 +434,7 @@ include::{modeldir}/Person.java[tags=sql-scalar-NamedNativeQuery-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-scalar-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-scalar-named-query-example]
---- ----
==== ====
@ -441,7 +443,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-scalar-named-query-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-scalar-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-scalar-named-query-example]
---- ----
==== ====
@ -452,7 +454,7 @@ Selecting multiple scalar values is done like this:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=sql-multiple-scalar-values-NamedNativeQuery-example] include::{example-dir-model}/Person.java[tags=sql-multiple-scalar-values-NamedNativeQuery-example]
---- ----
==== ====
@ -463,7 +465,7 @@ Without specifying an explicit result type, Hibernate will assume an `Object` ar
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-multiple-scalar-values-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-multiple-scalar-values-named-query-example]
---- ----
==== ====
@ -472,7 +474,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-multiple-scalar-values-named-quer
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-multiple-scalar-values-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-multiple-scalar-values-named-query-example]
---- ----
==== ====
@ -483,7 +485,7 @@ It's possible to use a DTO to store the resulting scalar values:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/PersonNames.java[tags=sql-ConstructorResult-dto-example] include::{example-dir-model}/PersonNames.java[tags=sql-ConstructorResult-dto-example]
---- ----
==== ====
@ -501,7 +503,7 @@ include::{modeldir}/Person.java[tags=sql-multiple-scalar-values-dto-NamedNativeQ
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-multiple-scalar-values-dto-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-multiple-scalar-values-dto-named-query-example]
---- ----
==== ====
@ -510,7 +512,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-multiple-scalar-values-dto-named-
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-multiple-scalar-values-dto-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-multiple-scalar-values-dto-named-query-example]
---- ----
==== ====
@ -522,7 +524,7 @@ to customize the named query using various configurations such as fetch mode, ca
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Phone.java[tags=sql-multiple-scalar-values-dto-NamedNativeQuery-hibernate-example] include::{example-dir-model}/Phone.java[tags=sql-multiple-scalar-values-dto-NamedNativeQuery-hibernate-example]
---- ----
==== ====
@ -531,7 +533,7 @@ include::{modeldir}/Phone.java[tags=sql-multiple-scalar-values-dto-NamedNativeQu
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-multiple-scalar-values-dto-hibernate-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-multiple-scalar-values-dto-hibernate-named-query-example]
---- ----
==== ====
@ -545,7 +547,7 @@ Considering the following named query:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=sql-entity-NamedNativeQuery-example] include::{example-dir-model}/Person.java[tags=sql-entity-NamedNativeQuery-example]
---- ----
==== ====
@ -561,7 +563,7 @@ Executing this named native query can be done as follows:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-entity-named-query-example]
---- ----
==== ====
@ -570,7 +572,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-named-query-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-named-query-example]
---- ----
==== ====
@ -581,7 +583,7 @@ To join multiple entities, you need to use a `SqlResultSetMapping` for each enti
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=sql-entity-associations-NamedNativeQuery-example] include::{example-dir-model}/Person.java[tags=sql-entity-associations-NamedNativeQuery-example]
---- ----
==== ====
@ -590,7 +592,7 @@ include::{modeldir}/Person.java[tags=sql-entity-associations-NamedNativeQuery-ex
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-associations_named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-entity-associations_named-query-example]
---- ----
==== ====
@ -599,7 +601,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-entity-associations_named-query-e
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations_named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-entity-associations_named-query-example]
---- ----
==== ====
@ -612,13 +614,13 @@ For this example, the following entities are going to be used:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/Dimensions.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0] include::{doc-emeddable-example-dir}/Dimensions.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0]
include::{sourcedir}/Identity.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0] include::{doc-emeddable-example-dir}/Identity.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0]
include::{sourcedir}/Captain.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0] include::{doc-emeddable-example-dir}/Captain.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0]
include::{sourcedir}/SpaceShip.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0] include::{doc-emeddable-example-dir}/SpaceShip.java[tags=sql-composite-key-entity-associations_named-query-example, indent=0]
---- ----
==== ====
@ -627,7 +629,7 @@ include::{sourcedir}/SpaceShip.java[tags=sql-composite-key-entity-associations_n
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-jpa-composite-key-entity-associations_named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-jpa-composite-key-entity-associations_named-query-example]
---- ----
==== ====
@ -636,7 +638,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-jpa-composite-key-entity-associations
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SQLTest.java[tags=sql-hibernate-composite-key-entity-associations_named-query-example] include::{doc-emeddable-example-dir}/SQLTest.java[tags=sql-hibernate-composite-key-entity-associations_named-query-example]
---- ----
==== ====
@ -702,7 +704,7 @@ parameter type, a `REF_CURSOR` or it could just return the result like a functio
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-sp-out-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-sp-out-mysql-example]
---- ----
==== ====
@ -713,7 +715,7 @@ To use this stored procedure, you can execute the following Jakarta Persistence
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-jpa-call-sp-out-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-jpa-call-sp-out-mysql-example]
---- ----
==== ====
@ -722,7 +724,7 @@ include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-jpa-call-sp-out-mysq
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-hibernate-call-sp-out-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-hibernate-call-sp-out-mysql-example]
---- ----
==== ====
@ -733,7 +735,7 @@ If the stored procedure outputs the result directly without an `OUT` parameter t
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-sp-no-out-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-sp-no-out-mysql-example]
---- ----
==== ====
@ -744,7 +746,7 @@ You can retrieve the results of the aforementioned MySQL stored procedure as fol
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-jpa-call-sp-no-out-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-jpa-call-sp-no-out-mysql-example]
---- ----
==== ====
@ -753,7 +755,7 @@ include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-jpa-call-sp-no-out-m
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-hibernate-call-sp-no-out-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-hibernate-call-sp-no-out-mysql-example]
---- ----
==== ====
@ -764,7 +766,7 @@ For a `REF_CURSOR` result sets, we'll consider the following Oracle stored proce
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-sp-ref-cursor-oracle-example] include::{doc-emeddable-example-dir}/OracleStoredProcedureTest.java[tags=sql-sp-ref-cursor-oracle-example]
---- ----
==== ====
@ -780,7 +782,7 @@ This function can be called using the standard Java Persistence API:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-jpa-call-sp-ref-cursor-oracle-example] include::{doc-emeddable-example-dir}/OracleStoredProcedureTest.java[tags=sql-jpa-call-sp-ref-cursor-oracle-example]
---- ----
==== ====
@ -789,7 +791,7 @@ include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-jpa-call-sp-ref-cur
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-hibernate-call-sp-ref-cursor-oracle-example] include::{doc-emeddable-example-dir}/OracleStoredProcedureTest.java[tags=sql-hibernate-call-sp-ref-cursor-oracle-example]
---- ----
==== ====
@ -800,7 +802,7 @@ If the database defines an SQL function:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-function-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-function-mysql-example]
---- ----
==== ====
@ -817,7 +819,7 @@ This limitation is acknowledged and will be addressed by the https://hibernate.a
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/MySQLStoredProcedureTest.java[tags=sql-call-function-mysql-example] include::{doc-emeddable-example-dir}/MySQLStoredProcedureTest.java[tags=sql-call-function-mysql-example]
---- ----
==== ====
@ -842,7 +844,7 @@ For this purpose, Jakarta Persistence defines the {jpaJavadocUrlPrefix}NamedStor
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{modeldir}/Person.java[tags=sql-sp-ref-cursor-oracle-named-query-example] include::{example-dir-model}/Person.java[tags=sql-sp-ref-cursor-oracle-named-query-example]
---- ----
==== ====
@ -853,7 +855,7 @@ Calling this stored procedure is straightforward, as illustrated by the followin
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-jpa-call-sp-ref-cursor-oracle-named-query-example] include::{doc-emeddable-example-dir}/OracleStoredProcedureTest.java[tags=sql-jpa-call-sp-ref-cursor-oracle-named-query-example]
---- ----
==== ====
@ -877,7 +879,7 @@ To filter collections, the `@Where` annotation allows customizing the underlying
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CustomSQLTest.java[tags=sql-custom-crud-example] include::{doc-emeddable-example-dir}/CustomSQLTest.java[tags=sql-custom-crud-example]
---- ----
==== ====
@ -916,7 +918,7 @@ Overriding SQL statements for secondary tables is also possible.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CustomSQLSecondaryTableTest.java[tags=sql-custom-crud-secondary-table-example] include::{doc-emeddable-example-dir}/CustomSQLSecondaryTableTest.java[tags=sql-custom-crud-secondary-table-example]
---- ----
==== ====
@ -935,7 +937,7 @@ Assuming the following stored procedure:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/OracleCustomSQLWithStoredProcedureTest.java[tags=sql-sp-soft-delete-example] include::{doc-emeddable-example-dir}/OracleCustomSQLWithStoredProcedureTest.java[tags=sql-sp-soft-delete-example]
---- ----
==== ====
@ -946,11 +948,11 @@ The entity can use this stored procedure to soft-delete the entity in question:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/OracleCustomSQLWithStoredProcedureTest.java[tags=sql-sp-custom-crud-example] include::{doc-emeddable-example-dir}/OracleCustomSQLWithStoredProcedureTest.java[tags=sql-sp-custom-crud-example]
---- ----
==== ====
[NOTE] [NOTE]
==== ====
You need to set the `callable` attribute when using a stored procedure instead of an SQL statement. You need to set the `callable` attribute when using a stored procedure instead of an SQL statement.
==== ====

10
documentation/src/main/asciidoc/userguide/chapters/query/spatial/Spatial.adoc
View File

@ -1,6 +1,8 @@
[[spatial]] [[spatial]]
== Spatial == Spatial
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/spatial :root-project-dir: ../../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-spatial: {documentation-project-dir}/src/test/java/org/hibernate/userguide/spatial
:extrasdir: extras :extrasdir: extras
[[spatial-overview]] [[spatial-overview]]
@ -213,7 +215,7 @@ Here is an example using JTS:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SpatialTest.java[tags=spatial-types-mapping-example, indent=0] include::{example-dir-spatial}/SpatialTest.java[tags=spatial-types-mapping-example, indent=0]
---- ----
==== ====
@ -224,7 +226,7 @@ We can now treat spatial geometries like any other type.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SpatialTest.java[tags=spatial-types-point-creation-example] include::{example-dir-spatial}/SpatialTest.java[tags=spatial-types-point-creation-example]
---- ----
==== ====
@ -236,7 +238,7 @@ could use the `within` function to find all objects within a given spatial exten
==== ====
[source, SQL, indent=0] [source, SQL, indent=0]
---- ----
include::{sourcedir}/SpatialTest.java[tags=spatial-types-query-example] include::{example-dir-spatial}/SpatialTest.java[tags=spatial-types-query-example]
---- ----
==== ====

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

@ -1,8 +1,10 @@
[[schema-generation]] [[schema-generation]]
== Schema generation == Schema generation
:sourcedir: ../../../../../test/java/org/hibernate/userguide/schema :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-schemagen: {documentation-project-dir}/src/test/java/org/hibernate/userguide/schema
:example-dir-schemagen-resources: {documentation-project-dir}/src/test/resources
:extrasdir: extras :extrasdir: extras
:resourcesdir: ../../../../../test/resources
Hibernate allows you to generate the database from the entity mappings. Hibernate allows you to generate the database from the entity mappings.
@ -22,7 +24,7 @@ Considering the following Domain Model:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/BaseSchemaGeneratorTest.java[tags=schema-generation-domain-model-example] include::{example-dir-schemagen}/BaseSchemaGeneratorTest.java[tags=schema-generation-domain-model-example]
---- ----
==== ====
@ -49,7 +51,7 @@ For instance, considering the following `schema-generation.sql` import file:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{resourcesdir}/schema-generation.sql[] include::{example-dir-schemagen-resources}/schema-generation.sql[]
---- ----
==== ====
@ -80,7 +82,7 @@ Considering the following HBM mapping:
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/SchemaGenerationTest.hbm.xml[] include::{example-dir-schemagen}/SchemaGenerationTest.hbm.xml[]
---- ----
==== ====
@ -96,7 +98,7 @@ Hibernate offers the `@Check` annotation so that you can specify an arbitrary SQ
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CheckTest.java[tag=schema-generation-database-checks-example] include::{example-dir-schemagen}/CheckTest.java[tag=schema-generation-database-checks-example]
---- ----
==== ====
@ -108,7 +110,7 @@ a `ConstraintViolationException` is going to be thrown.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/CheckTest.java[tag=schema-generation-database-checks-persist-example] include::{example-dir-schemagen}/CheckTest.java[tag=schema-generation-database-checks-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -127,7 +129,7 @@ With Hibernate, you can specify a default value for a given database column usin
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ColumnDefaultTest.java[tag=schema-generation-column-default-value-mapping-example] include::{example-dir-schemagen}/ColumnDefaultTest.java[tag=schema-generation-column-default-value-mapping-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -150,7 +152,7 @@ This way, when the `name` and or `clientId` attribute is null, the database will
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/ColumnDefaultTest.java[tag=schema-generation-column-default-value-persist-example] include::{example-dir-schemagen}/ColumnDefaultTest.java[tag=schema-generation-column-default-value-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -176,7 +178,7 @@ Considering the following entity mapping, Hibernate generates the unique constra
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/UniqueConstraintTest.java[tag=schema-generation-columns-unique-constraint-mapping-example] include::{example-dir-schemagen}/UniqueConstraintTest.java[tag=schema-generation-columns-unique-constraint-mapping-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -193,7 +195,7 @@ it's no longer possible to add two books with the same title and for the same au
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/UniqueConstraintTest.java[tag=schema-generation-columns-unique-constraint-persist-example] include::{example-dir-schemagen}/UniqueConstraintTest.java[tag=schema-generation-columns-unique-constraint-persist-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]
@ -216,7 +218,7 @@ Considering the following entity mapping. Hibernate generates the index when cre
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/IndexTest.java[tag=schema-generation-columns-index-mapping-example] include::{example-dir-schemagen}/IndexTest.java[tag=schema-generation-columns-index-mapping-example]
---- ----
[source, SQL, indent=0] [source, SQL, indent=0]

1
documentation/src/main/asciidoc/userguide/chapters/statistics/Statistics.adoc
View File

@ -1,6 +1,5 @@
[[statistics]] [[statistics]]
== Statistics == Statistics
:stat-sourcedir: ../../../../../../../hibernate-core/src/main/java/org/hibernate/stat
Hibernate can gather all sorts of statistics which can help you get a better insight into what Hibernate does behind the scenes. Hibernate can gather all sorts of statistics which can help you get a better insight into what Hibernate does behind the scenes.

6
documentation/src/main/asciidoc/userguide/chapters/tooling/Tooling.adoc
View File

@ -1,8 +1,8 @@
[[tooling]] [[tooling]]
== Build Tool Integration == Build Tool Integration
:rootProjectDir: ../../../../../../.. :root-project-dir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation :documentation-project-dir: {root-project-dir}/documentation
:documentationModel: {documentationProjectDir}/src/main/java/org/hibernate/userguide/model :example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
Hibernate provides build-time services available as plugins for Hibernate provides build-time services available as plugins for

18
documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc
View File

@ -1,10 +1,10 @@
[[tooling-modelgen]] [[tooling-modelgen]]
=== Static Metamodel Generator === Static Metamodel Generator
:rootProjectDir: ../../../../../../.. :root-project-dir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation :documentation-project-dir: {root-project-dir}/documentation
:documentationModel: {documentationProjectDir}/src/main/java/org/hibernate/userguide/model :example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:documentationMetamodel: {documentationProjectDir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/userguide/model :example-dir-metamodelgen-generated: {documentation-project-dir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/userguide/model
:toolingTestsDir: {documentationProjectDir}/src/test/java/org/hibernate/userguide/tooling :toolingTestsDir: {documentation-project-dir}/src/test/java/org/hibernate/userguide/tooling
Jakarta Persistence defines a typesafe Criteria API which allows `Criteria` queries to be constructed in a Jakarta Persistence defines a typesafe Criteria API which allows `Criteria` queries to be constructed in a
strongly-typed manner, utilizing so-called static metamodel classes. For developers, it is important that strongly-typed manner, utilizing so-called static metamodel classes. For developers, it is important that
@ -78,9 +78,9 @@ As an example, consider the following domain model -
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{documentationModel}/tooling/Customer.java[tags=tooling-modelgen-model] include::{example-dir-model}/tooling/Customer.java[tags=tooling-modelgen-model]
include::{documentationModel}/tooling/Order.java[tags=tooling-modelgen-model] include::{example-dir-model}/tooling/Order.java[tags=tooling-modelgen-model]
include::{documentationModel}/tooling/Item.java[tags=tooling-modelgen-model] include::{example-dir-model}/tooling/Item.java[tags=tooling-modelgen-model]
---- ----
==== ====
@ -91,7 +91,7 @@ Given this model, the generator will produce classes named `Customer_`, `Order_`
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{documentationMetamodel}/tooling/Order_.java[] include::{example-dir-metamodelgen-generated}/tooling/Order_.java[]
---- ----
==== ====

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

@ -1,6 +1,8 @@
[[transactions]] [[transactions]]
== Transactions and concurrency control == Transactions and concurrency control
:sourcedir: ../../../../../test/java/org/hibernate/userguide/transactions :root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-transaction: {documentation-project-dir}/src/test/java/org/hibernate/userguide/transactions
It is important to understand that the term transaction has many different yet related meanings in regards to persistence and Object/Relational Mapping. It is important to understand that the term transaction has many different yet related meanings in regards to persistence and Object/Relational Mapping.
In most use-cases these definitions align, but that is not always the case. In most use-cases these definitions align, but that is not always the case.
@ -116,7 +118,7 @@ Let's take a look at using the Transaction API in the various environments.
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/TransactionsTest.java[tags=transactions-api-jdbc-example] include::{example-dir-transaction}/TransactionsTest.java[tags=transactions-api-jdbc-example]
---- ----
==== ====
@ -125,7 +127,7 @@ include::{sourcedir}/TransactionsTest.java[tags=transactions-api-jdbc-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/TransactionsTest.java[tags=transactions-api-cmt-example] include::{example-dir-transaction}/TransactionsTest.java[tags=transactions-api-cmt-example]
---- ----
==== ====
@ -134,7 +136,7 @@ include::{sourcedir}/TransactionsTest.java[tags=transactions-api-cmt-example]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
---- ----
include::{sourcedir}/TransactionsTest.java[tags=transactions-api-bmt-example] include::{example-dir-transaction}/TransactionsTest.java[tags=transactions-api-bmt-example]
---- ----
==== ====