diff --git a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc index a781d8199f..41158ceb78 100644 --- a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc +++ b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc @@ -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[] diff --git a/documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc b/documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc index 9a65d6e19f..d6c80a513e 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc @@ -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] diff --git a/documentation/src/main/asciidoc/userguide/chapters/beans/Beans.adoc b/documentation/src/main/asciidoc/userguide/chapters/beans/Beans.adoc index 411b86910a..8574ce72f0 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/beans/Beans.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/beans/Beans.adoc @@ -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 <>] 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 <> or <> +CDI access, resolving these Hibernate integrations as managed beans is disabled. [[beans-cdi]] @@ -94,4 +92,4 @@ NOTE: When used in WildFly, this is all automatically set up by the server === Custom BeanContainer Other containers (Spring, e.g.) can also be used and integrated by implementing `BeanContainer` and -declaring it using `hibernate.resource.beans.container`. \ No newline at end of file +declaring it using `hibernate.resource.beans.container`. diff --git a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc index df84daa08d..2bb2152299 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc @@ -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 diff --git a/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc b/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc index 4904cb220e..cc3504d992 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc @@ -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 <> section. +<> 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 <> 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 <> 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 <> 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 <> 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 <> 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 <> with two differences: +This functionality is similar to a derived-property <> 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] diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc index 325010be2b..597d3933bf 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc @@ -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 <> 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 <>. ==== [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] ---- ==== diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/customizing.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/customizing.adoc index fd55cba316..438815a065 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/customizing.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/customizing.adoc @@ -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] ---- ==== @@ -32,4 +32,4 @@ it has the `@AttributeBinderType` meta-annotation and knows how to apply that th Notice also that `@AttributeBinderType` provides a type-safe way to perform configuration because the `AttributeBinder` (`YesNoBinder`) is handed the custom annotation (`@YesNo`) to grab its configured attributes. `@YesNo` does not provide any attributes, but it easily could. Whatever `YesNoBinder` -supports. \ No newline at end of file +supports. diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/dynamic_model.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/dynamic_model.adoc index 26e914897a..b456d4f95e 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/dynamic_model.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/dynamic_model.adoc @@ -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] @@ -66,4 +68,4 @@ However, as a result of the Hibernate mapping, the database schema can easily be It is also interesting to note that dynamic models are great for certain integration use cases as well. Envers, for example, makes extensive use of dynamic models to represent the historical data. -==== \ No newline at end of file +==== diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc index 098dc1d649..2c5b1f1e70 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc @@ -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 <>. ==== [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] ---- ==== @@ -439,4 +441,4 @@ Now the "path" to attributes are used in the implicit column naming: include::{extrasdir}/embeddable/embeddable-multiple-namingstrategy-entity-mapping.sql[] ---- -You could even develop your own naming strategy to do other types of implicit naming strategies. \ No newline at end of file +You could even develop your own naming strategy to do other types of implicit naming strategies. diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc index 1481ae5227..fe5ae7670e 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc @@ -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 <> 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 <> 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] ---- ==== diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc index 4dda3dcc32..f990607b15 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/Query.adoc @@ -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`, 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] ---- ==== diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc index 9a2aafbd2d..13c81154ae 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc @@ -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`—writing `update versioned`—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 <> 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 <