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 16ca1a0595
commit fd3670bbeb
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:
:toclevels: 3
:sectanchors:
:root-project-dir: ../../../../../../..
include::Preface.adoc[]

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

@ -1,7 +1,10 @@
[[batch]]
== Batching
:sourcedir: ../../../../../test/java/org/hibernate/userguide/batch
:bulkid-sourcedir: ../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/bulkid
:root-project-dir: ../../../../../../..
: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
[[batch-jdbcbatch]]
@ -46,7 +49,7 @@ Since version 5.2, Hibernate allows overriding the global JDBC batch size given
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]

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

@ -1,12 +1,6 @@
[[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
: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
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]]
=== 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.java.BasicJavaType`
* `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.metamodel.EmbeddableInstantiator`
* `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]]

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

@ -1,7 +1,10 @@
[[bootstrap]]
== Bootstrap
:sourcedir: ../../../../../test/java/org/hibernate/userguide/bootstrap
:boot-spi-sourcedir: ../../../../../../../hibernate-core/src/test/java/org/hibernate/orm/test/bootstrap/spi
:root-project-dir: ../../../../../../..
: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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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

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

@ -1,6 +1,8 @@
[[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.
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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 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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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
: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
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]
----
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]
@ -32,7 +34,7 @@ Each entity has a lifecycle of its own. Once the `@ManyToOne` association is set
====
[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]
@ -58,7 +60,7 @@ When using a unidirectional `@OneToMany` association, Hibernate resorts to using
====
[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]
@ -78,7 +80,7 @@ Only the parent side of an association makes sense to cascade its entity state t
====
[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]
@ -111,7 +113,7 @@ Every bidirectional association must have one owning side only (the child side),
====
[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]
@ -135,7 +137,7 @@ the `equals()` and the `hashCode()` can make use of this property, and so the `r
====
[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]
@ -164,7 +166,7 @@ A bidirectional association features a `mappedBy` `@OneToOne` parent side too.
====
[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]
@ -188,7 +190,7 @@ This mapping requires a bidirectional `@OneToOne` association as you can see in
====
[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]
@ -204,7 +206,7 @@ This time, the `PhoneDetails` owns the association, and, like any bidirectional
====
[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]
@ -222,7 +224,7 @@ Continuing the previous example, when adding another `PhoneDetails`, Hibernate v
====
[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]
----
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]
----
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]
@ -283,7 +285,7 @@ Unfortunately, this operation requires removing all entries associated with a gi
====
[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]
@ -318,7 +320,7 @@ By simply removing the parent-side, Hibernate can safely remove the associated l
====
[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]
@ -338,7 +340,7 @@ To preserve synchronicity between both sides, it's good practice to provide help
====
[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]
@ -354,7 +356,7 @@ With the helper methods in place, the synchronicity management can be simplified
====
[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]
@ -378,7 +380,7 @@ and the link table has an associated entity which controls the relationship for
====
[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]
@ -404,7 +406,7 @@ The entity state transitions are better managed than in the previous bidirection
====
[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]
@ -456,7 +458,7 @@ Considering the following `City` and `Person` entity mappings:
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/any/PropertyHolder.java[tags=associations-any-example]
include::{example-dir-association}/any/PropertyHolder.java[tags=associations-any-example]
----
[source, SQL, indent=0]
@ -657,7 +659,7 @@ Hibernate will generate the following SQL queries:
====
[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]
@ -674,7 +676,7 @@ Hibernate will fetch the associated `StringProperty` entity like this:
====
[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]
@ -700,7 +702,7 @@ into a single annotation that we can apply in each usage.
====
[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]
----
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]
@ -751,7 +753,7 @@ Hibernate will generate the following SQL queries:
====
[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]
@ -768,7 +770,7 @@ Hibernate will fetch the associated `IntegerProperty` and `StringProperty` entit
====
[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]
@ -789,7 +791,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
====
[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]
@ -807,7 +809,7 @@ Considering we have the following entities:
====
[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]
----
include::{sourcedir}/JoinFormulaTest.java[tags=associations-JoinFormula-fetching-example]
include::{example-dir-association}/JoinFormulaTest.java[tags=associations-JoinFormula-fetching-example]
----
[source, SQL, indent=0]
@ -839,7 +841,7 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
====
[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]
@ -857,7 +859,7 @@ Considering we have the following entities:
====
[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]
----
include::{sourcedir}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-fetching-example]
include::{example-dir-association}/JoinColumnOrFormulaTest.java[tags=associations-JoinColumnOrFormula-fetching-example]
----
[source, SQL, indent=0]

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

@ -1,13 +1,15 @@
[[basic]]
=== Basic values
:rootProjectDir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation
:coreProjectDir: {rootProjectDir}/hibernate-core
:core-generated-test-dir: {coreProjectDir}/src/test/java/org/hibernate/orm/test/mapping/generated
:modeldir: {documentationProjectDir}/src/main/java/org/hibernate/userguide/model
:sourcedir: {documentationProjectDir}/src/test/java/org/hibernate/userguide/mapping
:resourcedir: {documentationProjectDir}/src/test/resources/org/hibernate/userguide/
:converter-sourcedir: {coreProjectDir}/src/test/java/org/hibernate/orm/test/mapping/converted/converter
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:documentation-example-base: {documentation-project-dir}/src/test/
:example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:example-dir-basic-mapping: {documentation-example-base}/java/org/hibernate/userguide/mapping
:example-dir-resources: {documentation-example-base}/resources/org/hibernate/userguide/
:core-project-dir: {root-project-dir}/hibernate-core
: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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -255,7 +257,7 @@ Assuming the following enumeration:
====
[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]
----
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]
----
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]
@ -301,7 +303,7 @@ In the STRING example, the `phone_type` column is defined as a (nullable) VARCHA
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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
<<basic-mapping-explicit>> section.
<<basic-mapping-composition-jdbc>> section.
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
@ -566,7 +568,7 @@ By default, Hibernate maps values of `Float` to the `FLOAT`, `REAL` or
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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:
[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
@ -2052,14 +2054,14 @@ On the other hand, consider the following example where the `Money` type is a mu
[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:
[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]
@ -2082,7 +2084,7 @@ Assuming you have the following entity:
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -2402,7 +2404,7 @@ This way, we don't need to manually quote any identifier:
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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.
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 read-write, not read-only.
@ -2641,7 +2643,7 @@ The `write` expression, if specified, must contain exactly one '?' placeholder f
====
[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]

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

@ -1,16 +1,16 @@
[[collections]]
=== Collections
:rootProjectDir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation
:docTestsDir: ../../../../../test/java/org/hibernate/userguide/collections
:coreProjectDir: {rootProjectDir}/hibernate-core
:coreTestsDir: {coreProjectDir}/src/test/java
:coreCollectionTestsDir: {coreTestsDir}/org/hibernate/orm/test/mapping/collections
:classificationTestsDir: {coreCollectionTestsDir}/classification
:extrasdir: extras/collections
:docs-base: https://docs.jboss.org/hibernate/orm/6.0
:majorMinorVersion: 6.2
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-collection-doc: {documentation-project-dir}/src/test/java/org/hibernate/userguide/collections
:core-project-dir: {root-project-dir}/hibernate-core
:core-test-base: {core-project-dir}/src/test/java
:example-dir-collection: {core-test-base}/org/hibernate/orm/test/mapping/collections
:docs-base: https://docs.jboss.org/hibernate/orm/{majorMinorVersion}
:javadoc-base: {docs-base}/javadoc
: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)
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -382,7 +382,7 @@ cross between the ordered-ness of a `List` and the uniqueness of a `Set`. First
====
[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]
----
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]
----
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]
----
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]
----
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]
@ -507,7 +507,7 @@ By marking the parent side with the `CascadeType.ALL` attribute, the unidirectio
====
[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]
@ -536,7 +536,7 @@ The `@ManyToOne` side is the owning side of the bidirectional bag association, w
====
[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]
@ -550,7 +550,7 @@ include::{extrasdir}/collections-bidirectional-bag-example.sql[]
====
[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]
@ -564,7 +564,7 @@ include::{extrasdir}/collections-bidirectional-bag-lifecycle-example.sql[]
====
[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]
@ -594,7 +594,7 @@ When using the `@OrderBy` annotation, the mapping looks as follows:
====
[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]
----
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]
@ -659,7 +659,7 @@ The mapping is similar with the <<collections-bidirectional-bag>> example, just
====
[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]
----
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]
@ -693,7 +693,7 @@ You can customize the ordinal of the underlying ordered list by using the https:
====
[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]
----
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]
@ -729,7 +729,7 @@ by the number of characters of the `name` attribute.
====
[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]
----
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]
@ -764,7 +764,7 @@ The unidirectional set uses a link table to hold the parent-child associations a
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -887,7 +887,7 @@ Adding entries to the map generates the following SQL statements:
====
[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]
@ -925,7 +925,7 @@ Since we want to map all the calls by their associated `java.util.Date`, not by
====
[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]
----
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]
----
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]
@ -969,7 +969,7 @@ Hibernate generates the following SQL statements:
====
[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]
@ -986,7 +986,7 @@ Hibernate generates the following SQL statements:
====
[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]
@ -1013,7 +1013,7 @@ The `@MapKey` annotation is used to define the entity attribute used as a key of
====
[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]
@ -1034,7 +1034,7 @@ In the following example, you can see that `@MapKeyEnumerated` was used so that
====
[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]
@ -1065,7 +1065,7 @@ By default, Hibernate will choose a BINARY type, as supported by the current `Di
====
[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]
@ -1100,9 +1100,9 @@ is using an <<basic-jpa-convert,AttributeConverter>>.
====
[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]
----
====

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

@ -1,8 +1,8 @@
[[domain-customizing]]
=== Customizing the domain model
:rootProjectDir: ../../../../../../..
:coreProjectDir: {rootProjectDir}/hibernate-core
:attributeBinderTestDir: {coreProjectDir}/src/test/java/org/hibernate/orm/test/mapping/attributebinder
:root-project-dir: ../../../../../../..
:core-project-dir: {root-project-dir}/hibernate-core
:example-dir-attributebinder: {core-project-dir}/src/test/java/org/hibernate/orm/test/mapping/attributebinder
:extrasdir: extras
For cases where Hibernate does not provide a built-in way to configure the domain
@ -18,9 +18,9 @@ An example:
====
[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]
----
====

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

@ -1,7 +1,9 @@
[[dynamic-model]]
=== Dynamic Model
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/dynamic
:mappingdir: ../../../../../test/resources/org/hibernate/userguide/mapping/dynamic
:root-project-dir: ../../../../../../..
: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
[IMPORTANT]
@ -26,7 +28,7 @@ Entity modes can now be mixed within a domain model; a dynamic entity might refe
====
[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]
----
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]
----
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]

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

@ -1,11 +1,13 @@
[[embeddables]]
=== Embeddable values
:rootProjectDir: ../../../../../../..
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/embeddable
:coreProjectDir: {rootProjectDir}/hibernate-core
:coreTestSrcDir: {rootProjectDir}/hibernate-core/src/test/java
:instantiatorTestDir: {coreTestSrcDir}/org/hibernate/orm/test/mapping/embeddable/strategy/instantiator
:usertypeTestDir: {coreTestSrcDir}/org/hibernate/orm/test/mapping/embeddable/strategy/usertype
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:documentation-example-base: {documentation-project-dir}/src/test/java
:example-dir-emeddable: {documentation-example-base}/org/hibernate/userguide/mapping/embeddable
:core-project-dir: {root-project-dir}/hibernate-core
: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
Historically Hibernate called these components.
@ -28,7 +30,7 @@ Throughout this chapter and thereafter, for brevity sake, embeddable types may a
====
[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]
----
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]
@ -75,7 +77,7 @@ In fact, that table could also be mapped by the following entity type instead.
====
[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]
----
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]
@ -125,7 +127,7 @@ Therefore, the `Book` entity needs to override the embeddable type mappings for
====
[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]
@ -178,7 +180,7 @@ However, for simple embeddable types, there is no such construct and so you need
====
[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]
----
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]
----
include::{sourcedir}/TargetTest.java[tags=embeddable-Target-fetching-example]
include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-fetching-example]
----
[source, SQL, indent=0]
@ -225,7 +227,7 @@ The Hibernate-specific `@Parent` annotation allows you to reference the owner en
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/EmbeddableImplicitOverrideTest.java[tag=embeddable-multiple-ImplicitNamingStrategyComponentPathImpl, indent=0]
include::{example-dir-emeddable}/EmbeddableImplicitOverrideTest.java[tag=embeddable-multiple-ImplicitNamingStrategyComponentPathImpl, indent=0]
----
====

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

@ -1,9 +1,11 @@
[[entity]]
=== Entity types
:sourcedir-locking: ../../../../../test/java/org/hibernate/userguide/locking
:sourcedir-mapping: ../../../../../test/java/org/hibernate/userguide/mapping
:sourcedir-proxy: ../../../../../test/java/org/hibernate/userguide/proxy
:sourcedir-persister: ../../../../../test/java/org/hibernate/userguide/persister
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-locking: {documentation-project-dir}/src/test/java/org/hibernate/userguide/locking
: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
.Usage of the word _entity_
@ -105,7 +107,7 @@ The placement of the `@Id` annotation marks the <<chapters/domain/access.adoc#ac
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -510,12 +512,12 @@ of 6.2 `@Persister` has been formally deprecated.
====
[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]
----
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
:projectRootDir: ../../../../../../..
:sourcedir: ../../../../../test/java/org/hibernate/userguide/mapping/identifier
:sourcedir-associations: ../../../../../test/java/org/hibernate/userguide/associations
:coreTestsDir: {projectRootDir}/hibernate-core/src/test/java
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-identifier: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping/identifier
: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
:extrasdir: extras
@ -58,7 +59,7 @@ assign the value to the identifier attribute prior to persisting the entity.
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -471,7 +472,7 @@ However, you can configure the table identifier generator using the {jpaJavadocU
====
[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]
@ -487,7 +488,7 @@ Now, when inserting 3 `Product` entities, Hibernate generates the following stat
====
[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]
@ -515,7 +516,7 @@ Hibernate does ship with an alternative strategy which is a RFC 4122 version 1 (
====
[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]
----
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]
----
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]
----
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]
----
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]
@ -646,7 +647,7 @@ Java Persistence 2.0 added support for derived identifiers which allow an entity
====
[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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/RowIdTest.java[tag=identifiers-rowid-example]
include::{example-dir-identifier}/RowIdTest.java[tag=identifiers-rowid-example]
----
[source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[entity-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
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]
----
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]
----
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]
----
include::{sourcedir}/EntityImmutabilityTest.java[tags=entity-immutability-update-example]
include::{example-dir-immutability}/EntityImmutabilityTest.java[tags=entity-immutability-update-example]
----
[source, SQL, indent=0]
@ -58,7 +60,7 @@ Considering the following entity mappings:
====
[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]
----
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]
----
include::{sourcedir}/CollectionImmutabilityTest.java[tags=collection-entity-update-example]
include::{example-dir-immutability}/CollectionImmutabilityTest.java[tags=collection-entity-update-example]
----
[source, SQL, indent=0]
@ -96,7 +98,7 @@ However, when trying to modify the `events` collection:
====
[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]

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

@ -1,6 +1,8 @@
[[entity-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
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]
----
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]
@ -56,7 +58,7 @@ When omitting an explicit inheritance strategy (e.g. `@Inheritance`), Jakarta Pe
====
[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]
@ -73,7 +75,7 @@ If this is not specified, the `DTYPE` column is used as a discriminator, storing
====
[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]
@ -89,7 +91,7 @@ When using polymorphic queries, only a single table is required to be scanned to
====
[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]
@ -146,7 +148,7 @@ we can take advantage of the Hibernate specific `@DiscriminatorFormula` annotati
====
[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]
@ -173,7 +175,7 @@ To understand how these two values work, consider the following entity mapping:
====
[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]
----
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]
@ -215,7 +217,7 @@ Each subclass must, however, declare a table column holding the object identifie
====
[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]
@ -237,7 +239,7 @@ Also, if `@PrimaryKeyJoinColumn` is not set, the primary key / foreign key colum
====
[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]
@ -253,7 +255,7 @@ When using polymorphic queries, the base class table must be joined with all sub
====
[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]
@ -283,7 +285,7 @@ However, if you wish to use polymorphic associations (e.g. an association to the
====
[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]
@ -298,7 +300,7 @@ When using polymorphic queries, a UNION is required to fetch the base class tabl
====
[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]
@ -345,7 +347,7 @@ For instance, considering the following `DomainModelEntity` interface:
====
[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]
----
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]
----
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,7 +386,7 @@ or they are not annotated at all with the `@Polymorphism` annotation (implying t
====
[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]
----
====

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

@ -1,6 +1,8 @@
[[naming]]
=== 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
mapping names from the object model to the corresponding database names.
@ -113,7 +115,7 @@ whose naming standards are to:
====
[source,java]
----
include::{sourcedir}/AcmeCorpPhysicalNamingStrategy.java[]
include::{example-dir-naming}/AcmeCorpPhysicalNamingStrategy.java[]
----
====

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

@ -1,6 +1,8 @@
[[naturalid]]
=== 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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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
: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
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]
----
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
: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
[[envers-basics]]
@ -44,7 +46,7 @@ Hibernate is going to generate the following tables using the `hibernate.hbm2ddl
====
[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]
@ -64,7 +66,7 @@ let's see how Envers auditing works when inserting, updating, and deleting the e
====
[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]
@ -78,7 +80,7 @@ include::{extrasdir}/envers-audited-insert-example.sql[]
====
[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]
@ -92,7 +94,7 @@ include::{extrasdir}/envers-audited-update-example.sql[]
====
[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]
@ -120,7 +122,7 @@ The audit (history) of an entity can be accessed using the `AuditReader` interfa
====
[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]
@ -136,7 +138,7 @@ Using the previously fetched revisions, we can now inspect the state of the `Cus
====
[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]
@ -159,7 +161,7 @@ The same goes for the second revision associated with the `UPDATE` statement.
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -612,7 +614,7 @@ Tracking of modified entity names can be enabled in three different ways:
+
[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.
@ -620,7 +622,7 @@ include::{sourcedir}/EntityTypeChangeAuditDefaultTrackingTest.java[tags=envers-t
+
[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:
@ -630,7 +632,7 @@ Considering we have a `Customer` entity illustrated by the following example:
====
[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]
----
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]
@ -666,7 +668,7 @@ added, modified or removed within current revision boundaries.
====
[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]
----
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]
----
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]
----
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]
----
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]
@ -748,7 +750,7 @@ As you can see, every property features a `_MOD` column (e.g. `createdOn_MOD`) i
====
[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]
@ -863,7 +865,7 @@ The entry point for this type of queries is:
====
[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]
----
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]
----
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]
@ -908,7 +910,7 @@ The same SQL is generated even if we provide the identifier instead of the targe
====
[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]
----
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]
@ -938,7 +940,7 @@ A full query, can look for example like this:
====
[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]
@ -955,7 +957,7 @@ The entry point for this type of queries is:
[[revisions-of-entity-query-example]]
[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.
@ -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]]
[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.
@ -987,7 +989,7 @@ you can run the following query:
[[revisions-of-entity-query-minimize-example]]
[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,
@ -1018,7 +1020,7 @@ maximum revision number, you would use the following query:
[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
@ -1039,7 +1041,7 @@ First, you must make sure that your entity can track _modification flags_:
====
[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]
----
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]
@ -1071,7 +1073,7 @@ Of course, nothing prevents users from combining `hasChanged` condition with som
====
[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]
@ -1088,7 +1090,7 @@ we have to use the `forEntitiesModifiedAtRevision` query:
====
[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]
@ -1146,12 +1148,12 @@ This basic query allows retrieving entity names and corresponding Java classes c
====
[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]
----
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]
----
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]
----
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]
----
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]
@ -1234,7 +1236,7 @@ with the country attribute of the address property being `România`:
====
[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]
@ -1253,7 +1255,7 @@ having the `address` in `Cluj-Napoca` or the `address` does _not_ have any count
====
[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]
@ -1277,7 +1279,7 @@ where the country name is `România` or that the `Customer` lives in `Cluj-Napoc
====
[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]
@ -1295,7 +1297,7 @@ Assuming the `Customer` and the `Address` were previously changed as follows:
====
[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]
----
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]
@ -1431,7 +1433,7 @@ For the following entities, Hibernate is going to generate the following databas
====
[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]

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

@ -1,6 +1,8 @@
[[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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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`.
@ -200,7 +202,7 @@ When persisting a `Person` or `Book` entity, the `createdOn` is going to be set
====
[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]
@ -216,7 +218,7 @@ When updating a `Person` or `Book` entity, the `updatedOn` is going to be set by
====
[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]
@ -241,7 +243,7 @@ while `@ExcludeSuperclassListeners` is used to ignore the default entity listene
====
[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]
----
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]

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

@ -1,6 +1,8 @@
[[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
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]
----
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]
----
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]
@ -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]
----
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]
@ -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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -302,7 +304,7 @@ the Jakarta Persistence specification proper.
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/BatchFetchingTest.java[tags=fetching-batch-fetching-example]
include::{example-dir-fetching}/BatchFetchingTest.java[tags=fetching-batch-fetching-example]
----
[source, SQL, indent=0]
@ -480,7 +482,7 @@ To demonstrate how `FetchMode.SELECT` works, consider the following entity mappi
====
[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]
----
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]
@ -516,7 +518,7 @@ To demonstrate how `FetchMode.SUBSELECT` works, we are going to modify the <<fet
====
[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]
----
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]
@ -552,7 +554,7 @@ To demonstrate how `FetchMode.JOIN` works, we are going to modify the <<fetching
====
[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]
----
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]
@ -609,7 +611,7 @@ Each element is fetched individually using a secondary query.
====
[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]
----
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]
----
include::{sourcedir}/LazyCollectionTest.java[tags=fetching-LazyCollection-select-example]
include::{example-dir-fetching}/LazyCollectionTest.java[tags=fetching-LazyCollection-select-example]
----
[source, SQL, indent=0]

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

@ -1,6 +1,8 @@
[[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
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]
----
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]
@ -70,7 +72,7 @@ A flush may also be triggered when executing an entity query.
====
[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]
@ -86,7 +88,7 @@ The reason why the `Advertisement` entity query didn't trigger a flush is that t
====
[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]
----
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]
@ -117,7 +119,7 @@ When executing a native SQL query, a flush is always triggered when using the `E
====
[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]
----
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]
----
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]
----
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]
@ -177,7 +179,7 @@ Because the Jakarta Persistence doesn't impose a strict rule on delaying flushin
====
[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]
@ -201,7 +203,7 @@ The `ALWAYS` flush mode triggers a persistence context flush even when executing
====
[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]
@ -221,7 +223,7 @@ Hibernate also provides a `MANUAL` flush mode so the persistence context can onl
====
[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]
@ -256,7 +258,7 @@ To visualize how this works, consider the following example:
====
[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]

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

@ -1,6 +1,8 @@
[[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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -152,7 +154,7 @@ as illustrated in the following example.
====
[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]
----
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]
@ -218,7 +220,7 @@ There are 4 available OptimisticLockTypes:
====
[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]
----
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]
@ -259,7 +261,7 @@ since the entity was loaded in the currently running Persistence Context.
====
[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]
----
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]
@ -354,7 +356,7 @@ The scope can either be `NORMAL` (default value) or `EXTENDED`. The `EXTENDED` s
====
[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]
@ -384,7 +386,7 @@ The following example shows how to obtain a shared database lock.
====
[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]
@ -410,7 +412,7 @@ For this reason, Hibernate uses secondary selects to lock the previously fetched
====
[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]
@ -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]
----
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]
@ -450,7 +452,7 @@ Even more important is that you can overrule the default follow-on-locking detec
====
[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]

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

@ -1,6 +1,8 @@
[[multitenacy]]
== 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
[[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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,
@ -226,7 +228,7 @@ we could also configure the `Session` to use the tenant-specific time zone.
====
[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]
----
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]
----
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]

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

@ -1,6 +1,8 @@
[[BytecodeEnhancement]]
=== 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.
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]
----
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]
----
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]
----
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]
----
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]]
== Persistence Context
:sourcedir: ../../../../../test/java/org/hibernate/userguide/pc
:sourcedir-caching: ../../../../../test/java/org/hibernate/userguide/caching
:root-project-dir: ../../../../../../..
: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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -262,7 +264,7 @@ https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/WhereTest.java[tags=pc-where-persistence-example]
include::{example-dir-pc}/WhereTest.java[tags=pc-where-persistence-example]
----
[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]
----
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]
@ -400,7 +402,7 @@ When fetching the `debitAccounts` or the `creditAccounts` collections, Hibernate
====
[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]
@ -419,7 +421,7 @@ Just like `@Where` annotation, `@WhereJoinTable` is used to filter out collectio
====
[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]
@ -438,7 +440,7 @@ Considering that the following two `Book_Reader` entries are added into our syst
====
[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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/FilterTest.java[tags=pc-filter-persistence-example]
include::{example-dir-pc}/FilterTest.java[tags=pc-filter-persistence-example]
----
[source, SQL, indent=0]
@ -512,7 +514,7 @@ By default, without explicitly enabling the filter, Hibernate is going to fetch
====
[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]
@ -529,7 +531,7 @@ then Hibernate is going to apply the filtering criteria to the associated `Accou
====
[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]
@ -548,7 +550,7 @@ Therefore, even in the following example, the filter is taken into consideration
.Fetching entities mapped with `@Filter`
[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]
@ -566,7 +568,7 @@ Just like with entity queries, collections can be filtered as well, but only if
====
[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]
@ -582,7 +584,7 @@ When activating the `@Filter` and fetching the `accounts` collections, Hibernate
====
[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]
@ -620,7 +622,7 @@ if the `@Filter` defines a condition that uses predicates across multiple tables
====
[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]
----
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]
@ -654,7 +656,7 @@ The `@FilterJoinTable` annotation can be, therefore, applied to a unidirectional
====
[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]
----
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]
@ -685,7 +687,7 @@ The collections can be filtered only if the associated filter is enabled on the
====
[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]
@ -702,7 +704,7 @@ If we enable the filter and set the `maxOrderId` to `1` when fetching the `accou
====
[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]
@ -722,7 +724,7 @@ There is no need to call a particular method to make your modifications persiste
====
[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]
----
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]
----
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]
----
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]
----
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]
@ -795,7 +797,7 @@ To enable dynamic updates, you need to annotate the entity with the `@DynamicUpd
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]]
@ -1164,7 +1166,7 @@ The `CascadeType.PERSIST` allows us to persist a child entity along with the par
====
[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]
@ -1185,7 +1187,7 @@ The `CascadeType.MERGE` allows us to merge a child entity along with the parent
====
[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]
@ -1209,7 +1211,7 @@ However, `CascadeType.REMOVE` and `org.hibernate.annotations.CascadeType.DELETE`
====
[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]
@ -1228,7 +1230,7 @@ include::{extrasdir}/pc-cascade-remove-example.sql[]
====
[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]
----
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]
----
include::{sourcedir}/CascadeRefreshTest.java[tags=pc-cascade-refresh-example]
include::{example-dir-pc}/CascadeRefreshTest.java[tags=pc-cascade-refresh-example]
----
[source, SQL, indent=0]
@ -1282,7 +1284,7 @@ The replicate operation allows you to synchronize entities coming from different
====
[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]
@ -1308,12 +1310,12 @@ as illustrated by the following example.
====
[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]
----
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]
@ -1329,7 +1331,7 @@ Now, you can just remove the `Person` entity, and the associated `Phone` entitie
====
[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]
@ -1346,12 +1348,12 @@ illustrated in the following example.
====
[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]
----
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]
----
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]

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

@ -1,6 +1,8 @@
[[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.
@ -49,7 +51,7 @@ The application wants to select entity instances.
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]]
== Java API for HQL and JPQL
:modeldir: ../../../../../../main/java/org/hibernate/userguide/model
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/hql
:root-project-dir: ../../../../../../../..
: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
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]
----
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]
----
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]
----
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]
====
@ -126,7 +128,7 @@ That way, you'll obtain a `TypedQuery<T>`, and avoid some later typecasting.
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -488,7 +490,7 @@ The method `Query#setReadOnly()` is an alternative to using a Jakarta Persistenc
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
====

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

@ -1,7 +1,9 @@
[[query-language]]
== Hibernate Query Language
:modeldir: ../../../../../../main/java/org/hibernate/userguide/model
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/hql
:root-project-dir: ../../../../../../../..
: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
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]
----
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]
----
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:
[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.
@ -140,7 +142,7 @@ An alternative "simplest" query has _only_ a `select` list:
====
[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]
----
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.
@ -182,7 +184,7 @@ For example:
====
[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]
----
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]
----
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]
----
include::{sourcedir}/HQLTest.java[tags=hql-insert-example]
include::{example-dir-hql}/HQLTest.java[tags=hql-insert-example]
----
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/HQLTest.java[tags=hql-abs-function-example]
include::{example-dir-hql}/HQLTest.java[tags=hql-abs-function-example]
----
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
====

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

@ -1,7 +1,9 @@
[[sql]]
== Native SQL Queries
:modeldir: ../../../../../../main/java/org/hibernate/userguide/model
:sourcedir: ../../../../../../test/java/org/hibernate/userguide/sql
:root-project-dir: ../../../../../../../..
: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
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
@ -190,7 +192,7 @@ Joined entities will only be present for their respective association.
====
[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]
----
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]
@ -216,7 +218,7 @@ include::{extrasdir}/sql-jpa-entity-associations-query-one-to-many-join-example.
====
[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]
@ -241,7 +243,7 @@ Column alias injection is needed in the following query which otherwise throws `
====
[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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
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]
----
include::{sourcedir}/OracleCustomSQLWithStoredProcedureTest.java[tags=sql-sp-soft-delete-example]
include::{doc-emeddable-example-dir}/OracleCustomSQLWithStoredProcedureTest.java[tags=sql-sp-soft-delete-example]
----
====
@ -946,7 +948,7 @@ The entity can use this stored procedure to soft-delete the entity in question:
====
[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]
----
====

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

@ -1,6 +1,8 @@
[[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
[[spatial-overview]]
@ -213,7 +215,7 @@ Here is an example using JTS:
====
[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]
----
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]
----
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
: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
:resourcesdir: ../../../../../test/resources
Hibernate allows you to generate the database from the entity mappings.
@ -22,7 +24,7 @@ Considering the following Domain Model:
====
[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]
----
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]
----
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]
----
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]
----
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]
@ -127,7 +129,7 @@ With Hibernate, you can specify a default value for a given database column usin
====
[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]
@ -150,7 +152,7 @@ This way, when the `name` and or `clientId` attribute is null, the database will
====
[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]
@ -176,7 +178,7 @@ Considering the following entity mapping, Hibernate generates the unique constra
====
[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]
@ -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]
----
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]
@ -216,7 +218,7 @@ Considering the following entity mapping. Hibernate generates the index when cre
====
[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]

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

@ -1,6 +1,5 @@
[[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.

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

@ -1,8 +1,8 @@
[[tooling]]
== Build Tool Integration
:rootProjectDir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation
:documentationModel: {documentationProjectDir}/src/main/java/org/hibernate/userguide/model
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
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]]
=== Static Metamodel Generator
:rootProjectDir: ../../../../../../..
:documentationProjectDir: {rootProjectDir}/documentation
:documentationModel: {documentationProjectDir}/src/main/java/org/hibernate/userguide/model
:documentationMetamodel: {documentationProjectDir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/userguide/model
:toolingTestsDir: {documentationProjectDir}/src/test/java/org/hibernate/userguide/tooling
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-model: {documentation-project-dir}/src/main/java/org/hibernate/userguide/model
:example-dir-metamodelgen-generated: {documentation-project-dir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/userguide/model
: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
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]
----
include::{documentationModel}/tooling/Customer.java[tags=tooling-modelgen-model]
include::{documentationModel}/tooling/Order.java[tags=tooling-modelgen-model]
include::{documentationModel}/tooling/Item.java[tags=tooling-modelgen-model]
include::{example-dir-model}/tooling/Customer.java[tags=tooling-modelgen-model]
include::{example-dir-model}/tooling/Order.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]
----
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 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.
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]
----
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]
----
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]
----
include::{sourcedir}/TransactionsTest.java[tags=transactions-api-bmt-example]
include::{example-dir-transaction}/TransactionsTest.java[tags=transactions-api-bmt-example]
----
====