From 0069aa7be9437192e1580fad3f0972f91e62be33 Mon Sep 17 00:00:00 2001 From: Sanne Grinovero Date: Tue, 14 Apr 2020 12:23:38 +0100 Subject: [PATCH 1/9] Switching version to 5.5.0-SNAPSHOT --- gradle/base-information.gradle | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gradle/base-information.gradle b/gradle/base-information.gradle index 4cbe0e1bcb1a..d07aa5702c30 100644 --- a/gradle/base-information.gradle +++ b/gradle/base-information.gradle @@ -8,7 +8,7 @@ apply plugin: 'base' ext { - ormVersion = new HibernateVersion( '5.4.15-SNAPSHOT', project ) + ormVersion = new HibernateVersion( '5.5.0-SNAPSHOT', project ) baselineJavaVersion = '1.8' jpaVersion = new JpaVersion('2.2') } From c906989989ca35e87fad19e0b4154e3cf936428f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Fri, 3 Apr 2020 10:20:45 +0200 Subject: [PATCH 2/9] HHH-13682 Remove unnecessary checks around Java 8 compatibility The build requires JDK8+, so we're alwways Java 8 compatible. --- documentation/documentation.gradle | 4 +--- gradle/published-java-module.gradle | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/documentation/documentation.gradle b/documentation/documentation.gradle index 09e3b86689f1..4fed8c7da665 100644 --- a/documentation/documentation.gradle +++ b/documentation/documentation.gradle @@ -140,9 +140,7 @@ task aggregateJavadocs(type: Javadoc) { options.source = project.baselineJavaVersion } - if ( JavaVersion.current().isJava8Compatible() ) { - options.addStringOption( 'Xdoclint:none', '-quiet' ) - } + options.addStringOption( 'Xdoclint:none', '-quiet' ) } // process each project, building up: diff --git a/gradle/published-java-module.gradle b/gradle/published-java-module.gradle index f98f7a4494bc..ab90619a3f0b 100644 --- a/gradle/published-java-module.gradle +++ b/gradle/published-java-module.gradle @@ -131,9 +131,7 @@ javadoc { options.source = project.baselineJavaVersion } - if ( JavaVersion.current().isJava8Compatible() ) { - options.addStringOption( 'Xdoclint:none', '-quiet' ) - } + options.addStringOption( 'Xdoclint:none', '-quiet' ) doFirst { // ordering problems if we try to do this during config phase :( From 0cdf4c19e3d2f64b0538639211a1295904930b6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Mon, 21 Oct 2019 11:02:11 +0200 Subject: [PATCH 3/9] HHH-13682 Generate Java 13/14 bytecode for tests when building with JDK13/14 --- gradle/base-information.gradle | 15 +++++++++++++++ gradle/java-module.gradle | 18 +++++++++++++----- ...bernate-integrationtest-java-modules.gradle | 10 ++++++---- 3 files changed, 34 insertions(+), 9 deletions(-) diff --git a/gradle/base-information.gradle b/gradle/base-information.gradle index d07aa5702c30..6972f7e189ad 100644 --- a/gradle/base-information.gradle +++ b/gradle/base-information.gradle @@ -13,6 +13,21 @@ ext { jpaVersion = new JpaVersion('2.2') } +if ( JavaVersion.current() == JavaVersion.VERSION_HIGHER ) { + // This JDK is not supported by Gradle. + // Use a hack to retrieve the major as a string. + + // This only works for Java 9+ (we're at least on Java 13 here). + def major = System.getProperty( 'java.specification.version' ) + logger.warn( "[WARN] The Java version '$major' is not supported by gradle." ) + + ext.testedJavaVersion = major +} +else { + // This JDK is supported by Gradle. + ext.testedJavaVersion = JavaVersion.current() +} + group = 'org.hibernate' version = project.ormVersion.fullName diff --git a/gradle/java-module.gradle b/gradle/java-module.gradle index 1928f00d42fb..f015fa48a558 100644 --- a/gradle/java-module.gradle +++ b/gradle/java-module.gradle @@ -38,10 +38,6 @@ ext { forbiddenAPITargetJDKCompatibility = '11' } - -sourceCompatibility = project.baselineJavaVersion -targetCompatibility = project.baselineJavaVersion - if ( !project.description ) { project.description = "The Hibernate ORM $project.name module" } @@ -115,8 +111,20 @@ dependencies { // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // Compilation -tasks.withType(JavaCompile) { +tasks.withType( JavaCompile ) { options.encoding = 'UTF-8' + sourceCompatibility = project.baselineJavaVersion + targetCompatibility = project.baselineJavaVersion +} + +if ( project.baselineJavaVersion != project.testedJavaVersion ) { + logger.info( "Forcing the target bytecode version for test classes to '$project.testedJavaVersion'" ) + + tasks.compileTestJava { + // For *tests only*, generate bytecode matching the Java version currently in use. + // This allows testing bytecode enhancement on the latest Java versions (13, 14, ...). + targetCompatibility = project.testedJavaVersion + } } task compile(dependsOn: [compileJava, processResources, compileTestJava, processTestResources] ) diff --git a/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle b/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle index 233ce94e946a..bcd9bfac9a7f 100644 --- a/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle +++ b/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle @@ -24,10 +24,12 @@ apply from: rootProject.file( 'gradle/java-module.gradle' ) // so we have to use https://github.com/java9-modularity/gradle-modules-plugin apply plugin: "org.javamodularity.moduleplugin" -// Override -source and -target -ext.baselineJavaVersion = 11 -sourceCompatibility = project.baselineJavaVersion -targetCompatibility = project.baselineJavaVersion +// Override -source and -target to the version being tested (11+, since this module is enabled) +ext.baselineJavaVersion = project.testedJavaVersion +tasks.withType( JavaCompile ) { + sourceCompatibility = project.baselineJavaVersion + targetCompatibility = project.baselineJavaVersion +} // Checkstyle fails for module-info checkstyleMain.exclude '**/module-info.java' From 96f7870528cfcfeaf28f090b059f069ad253a485 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Mon, 21 Oct 2019 14:57:54 +0200 Subject: [PATCH 4/9] HHH-13682 Do not set net.bytebuddy.experimental=true in tests anymore It's no longer necessary since we upgraded to byte-buddy 1.10.2, and it causes bytecode to be converted from Java 14 to Java 12 in some cases (I don't know why). --- gradle/java-module.gradle | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/gradle/java-module.gradle b/gradle/java-module.gradle index f015fa48a558..913b1327db06 100644 --- a/gradle/java-module.gradle +++ b/gradle/java-module.gradle @@ -208,18 +208,6 @@ processTestResources { } } -// Enable the experimental features of ByteBuddy with JDK 12+ -test { - //Only safe to attempt to parse the version as an integer since JDK11 - if ( JavaVersion.current().isJava11Compatible() ) { - int majorJVMVersionInt = Integer.valueOf(JavaVersion.current().toString()); - //Set the -Dnet.bytebuddy.experimental=true property only when we need it: - if (majorJVMVersionInt >= 12) { - systemProperty 'net.bytebuddy.experimental', true - } - } -} - test { if ( project.findProperty( 'log-test-progress' )?.toString()?.toBoolean() ) { // Log a statement for each test. From 1060baf74b3d480d026a3d88e9c4b2d4aae118a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Thu, 2 Apr 2020 11:33:22 +0200 Subject: [PATCH 5/9] HHH-13682 Enable extended bytecode enhancement in NaturalIdInUninitializedAssociationTest This test accesses a field of an entity directly and expects it to be automatically initialized; this cannot work without extended bytecode enhancement. This used to work with Java 8 bytecode, but only by chance. It seems that Java 8 bytecode relies on "synthetic", static access methods inserted by the compiler to access the fields of entities in this test: any access to the field is done through this access method instead of through a direct field access. Since we apply bytecode enhancement to all methods of entities, this means that access to fields triggers initialization, without any bytecode enhancement in the caller class. I believe this is specific to nested classes, but couldn't find a source. For reference, the bytecode of access methods looks like this: static int access$002(org.hibernate.test.bytecode.enhancement.lazy.NaturalIdInUninitializedAssociationTest$AnEntity, int); Code: 0: aload_0 1: iload_1 2: dup_x1 3: putfield #3 // Field id:I 6: ireturn static org.hibernate.test.bytecode.enhancement.lazy.NaturalIdInUninitializedAssociationTest$EntityImmutableNaturalId access$102(org.hibernate.test.bytecode.enhancement.lazy.NaturalIdInUninitializedAssociationTest$AnEntity, org.hibernate.test.bytecode.enhancement.lazy.NaturalIdInUninitializedAssociationTest$EntityImmutableNaturalId); Code: 0: aload_0 1: aload_1 2: dup_x1 3: putfield #2 // Field entityImmutableNaturalId:Lorg/hibernate/test/bytecode/enhancement/lazy/NaturalIdInUninitializedAssociationTest$EntityImmutableNaturalId; 6: areturn With Java 11, however, access to fields of entities is done directly, even for nested classes. So the access methods no longer exist, and we don't get automatic initialization upon field access. We need extended bytecode enhancement, like we would in any other case of field access (in particular accessing fields of non-nested classes). --- .../lazy/NaturalIdInUninitializedAssociationTest.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hibernate-core/src/test/java/org/hibernate/test/bytecode/enhancement/lazy/NaturalIdInUninitializedAssociationTest.java b/hibernate-core/src/test/java/org/hibernate/test/bytecode/enhancement/lazy/NaturalIdInUninitializedAssociationTest.java index 1f86b4aa83b3..3e9ede028f0a 100644 --- a/hibernate-core/src/test/java/org/hibernate/test/bytecode/enhancement/lazy/NaturalIdInUninitializedAssociationTest.java +++ b/hibernate-core/src/test/java/org/hibernate/test/bytecode/enhancement/lazy/NaturalIdInUninitializedAssociationTest.java @@ -39,7 +39,7 @@ @SuppressWarnings({"unused", "WeakerAccess","ResultOfMethodCallIgnored"}) @TestForIssue( jiraKey = "HHH-13607" ) @RunWith( BytecodeEnhancerRunner.class ) -@EnhancementOptions( lazyLoading = true ) +@EnhancementOptions( lazyLoading = true, extendedEnhancement = true ) public class NaturalIdInUninitializedAssociationTest extends BaseNonConfigCoreFunctionalTestCase { @Test From b32ff5cd9c8da14fc2b756ccca2fdc860403b113 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Wed, 23 Oct 2019 08:45:47 +0200 Subject: [PATCH 6/9] HHH-13682 Allow forcing the tested Java version in the Gradle build ... just in case we need that for some cutting-edge JDK, for example 15, that would not be supported by Gradle yet. --- build.gradle | 2 +- gradle/base-information.gradle | 15 --------- gradle/java-module.gradle | 6 ++-- ...ernate-integrationtest-java-modules.gradle | 2 +- settings.gradle | 31 ++++++++++++++++++- 5 files changed, 35 insertions(+), 21 deletions(-) diff --git a/build.gradle b/build.gradle index 6e7f479bb198..a67fae0768e2 100644 --- a/build.gradle +++ b/build.gradle @@ -58,7 +58,7 @@ task release { // Force to release with JDK 8. Releasing with JDK 11 is not supported yet: // - the hibernate-orm-modules tests do not run due to an issue with the ASM version currently used by Gradle doFirst { - if ( !JavaVersion.current().isJava8() ) { + if ( !JavaVersion.current().isJava8() || !gradle.ext.testedJavaVersionAsEnum.isJava8() ) { throw new IllegalStateException( "Please use JDK 8 to perform the release." ) } } diff --git a/gradle/base-information.gradle b/gradle/base-information.gradle index 6972f7e189ad..d07aa5702c30 100644 --- a/gradle/base-information.gradle +++ b/gradle/base-information.gradle @@ -13,21 +13,6 @@ ext { jpaVersion = new JpaVersion('2.2') } -if ( JavaVersion.current() == JavaVersion.VERSION_HIGHER ) { - // This JDK is not supported by Gradle. - // Use a hack to retrieve the major as a string. - - // This only works for Java 9+ (we're at least on Java 13 here). - def major = System.getProperty( 'java.specification.version' ) - logger.warn( "[WARN] The Java version '$major' is not supported by gradle." ) - - ext.testedJavaVersion = major -} -else { - // This JDK is supported by Gradle. - ext.testedJavaVersion = JavaVersion.current() -} - group = 'org.hibernate' version = project.ormVersion.fullName diff --git a/gradle/java-module.gradle b/gradle/java-module.gradle index 913b1327db06..b3fc25c29ab2 100644 --- a/gradle/java-module.gradle +++ b/gradle/java-module.gradle @@ -117,13 +117,13 @@ tasks.withType( JavaCompile ) { targetCompatibility = project.baselineJavaVersion } -if ( project.baselineJavaVersion != project.testedJavaVersion ) { - logger.info( "Forcing the target bytecode version for test classes to '$project.testedJavaVersion'" ) +if ( project.baselineJavaVersion != gradle.ext.testedJavaVersion ) { + logger.info( "Forcing the target bytecode version for test classes to '$gradle.ext.testedJavaVersion'" ) tasks.compileTestJava { // For *tests only*, generate bytecode matching the Java version currently in use. // This allows testing bytecode enhancement on the latest Java versions (13, 14, ...). - targetCompatibility = project.testedJavaVersion + targetCompatibility = gradle.ext.testedJavaVersion } } diff --git a/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle b/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle index bcd9bfac9a7f..663e585f4454 100644 --- a/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle +++ b/hibernate-integrationtest-java-modules/hibernate-integrationtest-java-modules.gradle @@ -25,7 +25,7 @@ apply from: rootProject.file( 'gradle/java-module.gradle' ) apply plugin: "org.javamodularity.moduleplugin" // Override -source and -target to the version being tested (11+, since this module is enabled) -ext.baselineJavaVersion = project.testedJavaVersion +ext.baselineJavaVersion = gradle.ext.testedJavaVersion tasks.withType( JavaCompile ) { sourceCompatibility = project.baselineJavaVersion targetCompatibility = project.baselineJavaVersion diff --git a/settings.gradle b/settings.gradle index 1abab8f11e60..aa16052c5220 100644 --- a/settings.gradle +++ b/settings.gradle @@ -10,7 +10,36 @@ plugins { } if ( !JavaVersion.current().java8Compatible ) { - throw new GradleException( "Gradle must be run with Java 8" ) + throw new GradleException( "Gradle must be run with Java 8 or later" ) +} + +// Consume the property 'testedJavaVersion' here and +// set it on gradle.ext so that we can inspect the result in build.gradle. +// We wouldn't be able to do that if we consumed +// the property in base-information.gradle and set it on project.ext. + +if ( hasProperty( 'testedJavaVersion' ) ) { + logger.warn( "[WARN] Targeting Java version '$testedJavaVersion' in tests." ) + gradle.ext.testedJavaVersion = testedJavaVersion + gradle.ext.testedJavaVersionAsEnum = JavaVersion.toVersion( testedJavaVersion ) +} +else { + // We will simply use Gradle's JDK for compilation, tests and javadoc generation. + def major + if ( JavaVersion.current() == JavaVersion.VERSION_HIGHER) { + logger.warn( "Gradle does not support this JDK, because it is too recent; build is likely to fail." + + " To avoid failures, you should specify an older Java version in the 'testedJavaVersion' parameter." + + " Just append the following to your gradle command:" + + " '-PtestedJavaVersion='" ) + // Use a hack to retrieve the major as a string. + // This only works for Java 9+ (we're at least on Java 18 here). + gradle.ext.testedJavaVersion = System.getProperty( 'java.specification.version' ) + } + else { + gradle.ext.testedJavaVersion = JavaVersion.current().getMajorVersion() + } + + gradle.ext.testedJavaVersionAsEnum = JavaVersion.current() } include 'hibernate-core' From 5fab58bf767951ff1bebc74c06866237cb01c347 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Fri, 3 Apr 2020 11:01:07 +0200 Subject: [PATCH 7/9] HHH-13682 Upgrade to forbiddenapis 2.7 So that we can feed it Java 13/14 bytecode --- gradle/java-module.gradle | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gradle/java-module.gradle b/gradle/java-module.gradle index b3fc25c29ab2..5934e8d64cdf 100644 --- a/gradle/java-module.gradle +++ b/gradle/java-module.gradle @@ -10,7 +10,7 @@ buildscript { mavenCentral() } dependencies { - classpath 'de.thetaphi:forbiddenapis:2.6' + classpath 'de.thetaphi:forbiddenapis:2.7' } } From 0b4bcce3fa2589f25b28d1393a57fe1e10a5cbce Mon Sep 17 00:00:00 2001 From: Sanne Grinovero Date: Tue, 14 Apr 2020 15:58:41 +0100 Subject: [PATCH 8/9] HHH-13947 Switch the JPA Javadoc prefix URL to a build parameter Applying the following script, and setting the current value as a documentation parameter: find . -type f -name '*.java' -o -name '*.adoc' -o -name '.xml' | xargs sed -i 's/https:\/\/javaee\.github\.io\/javaee-spec\/javadocs\/javax\/persistence\//\{jpaJavadocUrlPrefix\}/g' Having the script might help re-migrating existing documentation patches, or forward porting subsequent improvements from previous branches. The javadocs for JPA 3.0 have not been published yet at this point; having a parameter will make it easier to leave this single task for a later point in time. --- documentation/documentation.gradle | 3 +- .../userguide/appendices/Annotations.adoc | 186 +++++++++--------- .../chapters/bootstrap/Bootstrap.adoc | 8 +- .../userguide/chapters/caching/Caching.adoc | 10 +- .../chapters/domain/collections.adoc | 4 +- .../chapters/domain/embeddables.adoc | 16 +- .../userguide/chapters/domain/entity.adoc | 8 +- .../chapters/domain/identifiers.adoc | 2 +- .../userguide/chapters/events/Events.adoc | 4 +- .../userguide/chapters/fetching/Fetching.adoc | 4 +- .../userguide/chapters/flushing/Flushing.adoc | 2 +- .../userguide/chapters/locking/Locking.adoc | 4 +- .../chapters/pc/PersistenceContext.adoc | 4 +- .../userguide/chapters/query/hql/HQL.adoc | 4 +- .../chapters/query/native/Native.adoc | 2 +- .../userguide/chapters/schema/Schema.adoc | 4 +- 16 files changed, 133 insertions(+), 132 deletions(-) diff --git a/documentation/documentation.gradle b/documentation/documentation.gradle index 4fed8c7da665..9d4537fe0ad7 100644 --- a/documentation/documentation.gradle +++ b/documentation/documentation.gradle @@ -232,7 +232,8 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') { stylesheet: "css/hibernate.css", majorMinorVersion: rootProject.ormVersion.family, fullVersion: rootProject.ormVersion.fullName, - docinfo: 'private' + docinfo: 'private', + jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/" resources { from('src/main/asciidoc/userguide/') { diff --git a/documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc b/documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc index cbd2db63a35e..bcc352d8e288 100644 --- a/documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc +++ b/documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc @@ -7,45 +7,45 @@ [[annotations-jpa-access]] ==== `@Access` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Access.html[`@Access`] annotation is used to specify the access type of the associated entity class, mapped superclass, or embeddable class, or entity attribute. +The {jpaJavadocUrlPrefix}Access.html[`@Access`] annotation is used to specify the access type of the associated entity class, mapped superclass, or embeddable class, or entity attribute. See the <> section for more info. [[annotations-jpa-associationoverride]] ==== `@AssociationOverride` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AssociationOverride.html[`@AssociationOverride`] annotation is used to override an association mapping (e.g. `@ManyToOne`, `@OneToOne`, `@OneToMany`, `@ManyToMany`) inherited from a mapped superclass or an embeddable. +The {jpaJavadocUrlPrefix}AssociationOverride.html[`@AssociationOverride`] annotation is used to override an association mapping (e.g. `@ManyToOne`, `@OneToOne`, `@OneToMany`, `@ManyToMany`) inherited from a mapped superclass or an embeddable. See the <> section for more info. [[annotations-jpa-associationoverrides]] ==== `@AssociationOverrides` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AssociationOverrides.html[`@AssociationOverrides`] is used to group several <> annotations. +The {jpaJavadocUrlPrefix}AssociationOverrides.html[`@AssociationOverrides`] is used to group several <> annotations. [[annotations-jpa-attributeoverride]] ==== `@AttributeOverride` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AttributeOverride.html[`@AttributeOverride`] annotation is used to override an attribute mapping inherited from a mapped superclass or an embeddable. +The {jpaJavadocUrlPrefix}AttributeOverride.html[`@AttributeOverride`] annotation is used to override an attribute mapping inherited from a mapped superclass or an embeddable. See the <> section for more info. [[annotations-jpa-attributeoverrides]] ==== `@AttributeOverrides` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AttributeOverrides.html[`@AttributeOverrides`] is used to group several <> annotations. +The {jpaJavadocUrlPrefix}AttributeOverrides.html[`@AttributeOverrides`] is used to group several <> annotations. [[annotations-jpa-basic]] ==== `@Basic` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Basic.html[`@Basic`] annotation is used to map a basic attribute type to a database column. +The {jpaJavadocUrlPrefix}Basic.html[`@Basic`] annotation is used to map a basic attribute type to a database column. See the <> chapter for more info. [[annotations-jpa-cacheable]] ==== `@Cacheable` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Cacheable.html[`@Cacheable`] annotation is used to specify whether an entity should be stored in the second-level cache. +The {jpaJavadocUrlPrefix}Cacheable.html[`@Cacheable`] annotation is used to specify whether an entity should be stored in the second-level cache. If the `persistence.xml` `shared-cache-mode` XML attribute is set to `ENABLE_SELECTIVE`, then only the entities annotated with the `@Cacheable` are going to be stored in the second-level cache. @@ -56,102 +56,102 @@ See the <> chapter for more info. [[annotations-jpa-collectiontable]] ==== `@CollectionTable` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CollectionTable.html[`@CollectionTable`] annotation is used to specify the database table that stores the values of a basic or an embeddable type collection. +The {jpaJavadocUrlPrefix}CollectionTable.html[`@CollectionTable`] annotation is used to specify the database table that stores the values of a basic or an embeddable type collection. See the <> section for more info. [[annotations-jpa-column]] ==== `@Column` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Column.html[`@Column`] annotation is used to specify the mapping between a basic entity attribute and the database table column. +The {jpaJavadocUrlPrefix}Column.html[`@Column`] annotation is used to specify the mapping between a basic entity attribute and the database table column. See the <> section for more info. [[annotations-jpa-columnresult]] ==== `@ColumnResult` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ColumnResult.html[`@ColumnResult`] annotation is used in conjunction with the <> or <> annotations to map a SQL column for a given SELECT query. +The {jpaJavadocUrlPrefix}ColumnResult.html[`@ColumnResult`] annotation is used in conjunction with the <> or <> annotations to map a SQL column for a given SELECT query. See the <> section for more info. [[annotations-jpa-constructorresult]] ==== `@ConstructorResult` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ConstructorResult.html[`@ConstructorResult`] annotation is used in conjunction with the <> annotations to map columns of a given SELECT query to a certain object constructor. +The {jpaJavadocUrlPrefix}ConstructorResult.html[`@ConstructorResult`] annotation is used in conjunction with the <> annotations to map columns of a given SELECT query to a certain object constructor. See the <> section for more info. [[annotations-jpa-convert]] ==== `@Convert` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Convert.html[`@Convert`] annotation is used to specify the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AttributeConverter.html[`AttributeConverter`] implementation used to convert the currently annotated basic attribute. +The {jpaJavadocUrlPrefix}Convert.html[`@Convert`] annotation is used to specify the {jpaJavadocUrlPrefix}AttributeConverter.html[`AttributeConverter`] implementation used to convert the currently annotated basic attribute. -If the `AttributeConverter` uses https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Converter.html#autoApply--[`autoApply`], then all entity attributes with the same target type are going to be converted automatically. +If the `AttributeConverter` uses {jpaJavadocUrlPrefix}Converter.html#autoApply--[`autoApply`], then all entity attributes with the same target type are going to be converted automatically. See the <> section for more info. [[annotations-jpa-converter]] ==== `@Converter` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Converter.html[`@Converter`] annotation is used to specify that the currently annotated https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AttributeConverter.html[`AttributeConverter`] implementation can be used as a JPA basic attribute converter. +The {jpaJavadocUrlPrefix}Converter.html[`@Converter`] annotation is used to specify that the currently annotated {jpaJavadocUrlPrefix}AttributeConverter.html[`AttributeConverter`] implementation can be used as a JPA basic attribute converter. -If the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Converter.html#autoApply--[`autoApply`] attribute is set to `true`, then the JPA provider will automatically convert all basic attributes with the same Java type as defined by the current converter. +If the {jpaJavadocUrlPrefix}Converter.html#autoApply--[`autoApply`] attribute is set to `true`, then the JPA provider will automatically convert all basic attributes with the same Java type as defined by the current converter. See the <> section for more info. [[annotations-jpa-converts]] ==== `@Converts` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Converts.html[`@Converts`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}Converts.html[`@Converts`] annotation is used to group multiple <> annotations. See the <> section for more info. [[annotations-jpa-discriminatorcolumn]] ==== `@DiscriminatorColumn` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/DiscriminatorColumn.html[`@DiscriminatorColumn`] annotation is used to specify the discriminator column name and the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/DiscriminatorColumn.html#discriminatorType--[discriminator type] for the `SINGLE_TABLE` and `JOINED` inheritance strategies. +The {jpaJavadocUrlPrefix}DiscriminatorColumn.html[`@DiscriminatorColumn`] annotation is used to specify the discriminator column name and the {jpaJavadocUrlPrefix}DiscriminatorColumn.html#discriminatorType--[discriminator type] for the `SINGLE_TABLE` and `JOINED` inheritance strategies. See the <> section for more info. [[annotations-jpa-discriminatorvalue]] ==== `@DiscriminatorValue` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/DiscriminatorValue.html[`@DiscriminatorValue`] annotation is used to specify what value of the discriminator column is used for mapping the currently annotated entity. +The {jpaJavadocUrlPrefix}DiscriminatorValue.html[`@DiscriminatorValue`] annotation is used to specify what value of the discriminator column is used for mapping the currently annotated entity. See the <> section for more info. [[annotations-jpa-elementcollection]] ==== `@ElementCollection` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ElementCollection.html[`@ElementCollection`] annotation is used to specify a collection of a basic or embeddable types. +The {jpaJavadocUrlPrefix}ElementCollection.html[`@ElementCollection`] annotation is used to specify a collection of a basic or embeddable types. See the <> section for more info. [[annotations-jpa-embeddable]] ==== `@Embeddable` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Embeddable.html[`@Embeddable`] annotation is used to specify embeddable types. Like basic types, embeddable types do not have any identity, being managed by their owning entity. +The {jpaJavadocUrlPrefix}Embeddable.html[`@Embeddable`] annotation is used to specify embeddable types. Like basic types, embeddable types do not have any identity, being managed by their owning entity. See the <> section for more info. [[annotations-jpa-embedded]] ==== `@Embedded` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Embedded.html[`@Embedded`] annotation is used to specify that a given entity attribute represents an embeddable type. +The {jpaJavadocUrlPrefix}Embedded.html[`@Embedded`] annotation is used to specify that a given entity attribute represents an embeddable type. See the <> section for more info. [[annotations-jpa-embeddedid]] ==== `@EmbeddedId` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/EmbeddedId.html[`@EmbeddedId`] annotation is used to specify the entity identifier is an embeddable type. +The {jpaJavadocUrlPrefix}EmbeddedId.html[`@EmbeddedId`] annotation is used to specify the entity identifier is an embeddable type. See the <> section for more info. [[annotations-jpa-entity]] ==== `@Entity` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Entity.html[`@Entity`] annotation is used to specify that the currently annotated class represents an entity type. +The {jpaJavadocUrlPrefix}Entity.html[`@Entity`] annotation is used to specify that the currently annotated class represents an entity type. Unlike basic and embeddable types, entity types have an identity and their state is managed by the underlying Persistence Context. See the <> section for more info. @@ -159,49 +159,49 @@ See the <> section for more info. [[annotations-jpa-entitylisteners]] ==== `@EntityListeners` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/EntityListeners.html[`@EntityListeners`] annotation is used to specify an array of callback listener classes that are used by the currently annotated entity. +The {jpaJavadocUrlPrefix}EntityListeners.html[`@EntityListeners`] annotation is used to specify an array of callback listener classes that are used by the currently annotated entity. See the <> section for more info. [[annotations-jpa-entityresult]] ==== `@EntityResult` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/EntityResult.html[`@EntityResult`] annotation is used with the <> annotation to map the selected columns to an entity. +The {jpaJavadocUrlPrefix}EntityResult.html[`@EntityResult`] annotation is used with the <> annotation to map the selected columns to an entity. See the <> section for more info. [[annotations-jpa-enumerated]] ==== `@Enumerated` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Enumerated.html[`@Enumerated`] annotation is used to specify that an entity attribute represents an enumerated type. +The {jpaJavadocUrlPrefix}Enumerated.html[`@Enumerated`] annotation is used to specify that an entity attribute represents an enumerated type. See the <> section for more info. [[annotations-jpa-excludedefaultlisteners]] ==== `@ExcludeDefaultListeners` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ExcludeDefaultListeners.html[`@ExcludeDefaultListeners`] annotation is used to specify that the currently annotated entity skips the invocation of any default listener. +The {jpaJavadocUrlPrefix}ExcludeDefaultListeners.html[`@ExcludeDefaultListeners`] annotation is used to specify that the currently annotated entity skips the invocation of any default listener. See the <> section for more info. [[annotations-jpa-excludesuperclasslisteners]] ==== `@ExcludeSuperclassListeners` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ExcludeSuperclassListeners.html[`@ExcludeSuperclassListeners`] annotation is used to specify that the currently annotated entity skips the invocation of listeners declared by its superclass. +The {jpaJavadocUrlPrefix}ExcludeSuperclassListeners.html[`@ExcludeSuperclassListeners`] annotation is used to specify that the currently annotated entity skips the invocation of listeners declared by its superclass. See the <> section for more info. [[annotations-jpa-fieldresult]] ==== `@FieldResult` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/FieldResult.html[`@FieldResult`] annotation is used with the <> annotation to map the selected columns to the fields of some specific entity. +The {jpaJavadocUrlPrefix}FieldResult.html[`@FieldResult`] annotation is used with the <> annotation to map the selected columns to the fields of some specific entity. See the <> section for more info. [[annotations-jpa-foreignkey]] ==== `@ForeignKey` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ForeignKey.html[`@ForeignKey`] annotation is used to specify the associated foreign key of a <> mapping. +The {jpaJavadocUrlPrefix}ForeignKey.html[`@ForeignKey`] annotation is used to specify the associated foreign key of a <> mapping. The `@ForeignKey` annotation is only used if the automated schema generation tool is enabled, in which case, it allows you to customize the underlying foreign key definition. See the <> section for more info. @@ -209,7 +209,7 @@ See the <> section for more info. @@ -217,7 +217,7 @@ See the <> section for more info. @@ -225,7 +225,7 @@ See the <> section for [[annotations-jpa-idclass]] ==== `@IdClass` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/IdClass.html[`@IdClass`] annotation is used if the current entity defined a composite identifier. +The {jpaJavadocUrlPrefix}IdClass.html[`@IdClass`] annotation is used if the current entity defined a composite identifier. A separate class encapsulates all the identifier attributes, which are mirrored by the current entity mapping. See the <> section for more info. @@ -233,89 +233,89 @@ See the <> chapter for more info. [[annotations-jpa-inheritance]] ==== `@Inheritance` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Inheritance.html[`@Inheritance`] annotation is used to specify the inheritance strategy of a given entity class hierarchy. +The {jpaJavadocUrlPrefix}Inheritance.html[`@Inheritance`] annotation is used to specify the inheritance strategy of a given entity class hierarchy. See the <> section for more info. [[annotations-jpa-joincolumn]] ==== `@JoinColumn` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/JoinColumn.html[`@JoinColumn`] annotation is used to specify the FOREIGN KEY column used when joining an entity association or an embeddable collection. +The {jpaJavadocUrlPrefix}JoinColumn.html[`@JoinColumn`] annotation is used to specify the FOREIGN KEY column used when joining an entity association or an embeddable collection. See the <> section for more info. [[annotations-jpa-joincolumns]] ==== `@JoinColumns` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/JoinColumns.html[`@JoinColumns`] annotation is used to group multiple <> annotations, which are used when mapping entity association or an embeddable collection using a composite identifier. +The {jpaJavadocUrlPrefix}JoinColumns.html[`@JoinColumns`] annotation is used to group multiple <> annotations, which are used when mapping entity association or an embeddable collection using a composite identifier. [[annotations-jpa-jointable]] ==== `@JoinTable` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/JoinTable.html[`@JoinTable`] annotation is used to specify the link table between two other database tables. +The {jpaJavadocUrlPrefix}JoinTable.html[`@JoinTable`] annotation is used to specify the link table between two other database tables. See the <> section for more info. [[annotations-jpa-lob]] ==== `@Lob` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Lob.html[`@Lob`] annotation is used to specify that the currently annotated entity attribute represents a large object type. +The {jpaJavadocUrlPrefix}Lob.html[`@Lob`] annotation is used to specify that the currently annotated entity attribute represents a large object type. See the <> section for more info. [[annotations-jpa-manytomany]] ==== `@ManyToMany` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ManyToMany.html[`@ManyToMany`] annotation is used to specify a many-to-many database relationship. +The {jpaJavadocUrlPrefix}ManyToMany.html[`@ManyToMany`] annotation is used to specify a many-to-many database relationship. See the <> section for more info. [[annotations-jpa-manytoone]] ==== `@ManyToOne` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ManyToOne.html[`@ManyToOne`] annotation is used to specify a many-to-one database relationship. +The {jpaJavadocUrlPrefix}ManyToOne.html[`@ManyToOne`] annotation is used to specify a many-to-one database relationship. See the <> section for more info. [[annotations-jpa-mapkey]] ==== `@MapKey` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKey.html[`@MapKey`] annotation is used to specify the key of a `java.util.Map` association for which the key type is either the primary key or an attribute of the entity which represents the value of the map. +The {jpaJavadocUrlPrefix}MapKey.html[`@MapKey`] annotation is used to specify the key of a `java.util.Map` association for which the key type is either the primary key or an attribute of the entity which represents the value of the map. See the <> section for more info. [[annotations-jpa-mapkeyclass]] ==== `@MapKeyClass` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKeyClass.html[`@MapKeyClass`] annotation is used to specify the type of the map key of a `java.util.Map` associations. +The {jpaJavadocUrlPrefix}MapKeyClass.html[`@MapKeyClass`] annotation is used to specify the type of the map key of a `java.util.Map` associations. See the <> section for more info. [[annotations-jpa-mapkeycolumn]] ==== `@MapKeyColumn` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKeyColumn.html[`@MapKeyColumn`] annotation is used to specify the database column which stores the key of a `java.util.Map` association for which the map key is a basic type. +The {jpaJavadocUrlPrefix}MapKeyColumn.html[`@MapKeyColumn`] annotation is used to specify the database column which stores the key of a `java.util.Map` association for which the map key is a basic type. See the <> for an example of `@MapKeyColumn` annotation usage. [[annotations-jpa-mapkeyenumerated]] ==== `@MapKeyEnumerated` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKeyEnumerated.html[`@MapKeyEnumerated`] annotation is used to specify that the key of `java.util.Map` association is a Java Enum. +The {jpaJavadocUrlPrefix}MapKeyEnumerated.html[`@MapKeyEnumerated`] annotation is used to specify that the key of `java.util.Map` association is a Java Enum. See the <> section for more info. [[annotations-jpa-mapkeyjoincolumn]] ==== `@MapKeyJoinColumn` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKeyJoinColumn.html[`@MapKeyJoinColumn`] annotation is used to specify that the key of `java.util.Map` association is an entity association. +The {jpaJavadocUrlPrefix}MapKeyJoinColumn.html[`@MapKeyJoinColumn`] annotation is used to specify that the key of `java.util.Map` association is an entity association. The map key column is a FOREIGN KEY in a link table that also joins the `Map` owner's table with the table where the `Map` value resides. See the <> section for more info. @@ -323,205 +323,205 @@ See the <> mappings when the `java.util.Map` association key uses a composite identifier. +The {jpaJavadocUrlPrefix}MapKeyJoinColumns.html[`@MapKeyJoinColumns`] annotation is used to group several <> mappings when the `java.util.Map` association key uses a composite identifier. [[annotations-jpa-mapkeytemporal]] ==== `@MapKeyTemporal` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKeyTemporal.html[`@MapKeyTemporal`] annotation is used to specify that the key of `java.util.Map` association is a https://javaee.github.io/javaee-spec/javadocs/javax/persistence/TemporalType.html[`@TemporalType`] (e.g. `DATE`, `TIME`, `TIMESTAMP`). +The {jpaJavadocUrlPrefix}MapKeyTemporal.html[`@MapKeyTemporal`] annotation is used to specify that the key of `java.util.Map` association is a {jpaJavadocUrlPrefix}TemporalType.html[`@TemporalType`] (e.g. `DATE`, `TIME`, `TIMESTAMP`). See the <> section for more info. [[annotations-jpa-mappedsuperclass]] ==== `@MappedSuperclass` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MappedSuperclass.html[`@MappedSuperclass`] annotation is used to specify that the currently annotated type attributes are inherited by any subclass entity. +The {jpaJavadocUrlPrefix}MappedSuperclass.html[`@MappedSuperclass`] annotation is used to specify that the currently annotated type attributes are inherited by any subclass entity. See the <> section for more info. [[annotations-jpa-mapsid]] ==== `@MapsId` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapsId.html[`@MapsId`] annotation is used to specify that the entity identifier is mapped by the currently annotated `@ManyToOne` or `@OneToOne` association. +The {jpaJavadocUrlPrefix}MapsId.html[`@MapsId`] annotation is used to specify that the entity identifier is mapped by the currently annotated `@ManyToOne` or `@OneToOne` association. See the <> section for more info. [[annotations-jpa-namedattributenode]] ==== `@NamedAttributeNode` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedAttributeNode.html[`@NamedAttributeNode`] annotation is used to specify each individual attribute node that needs to be fetched by an Entity Graph. +The {jpaJavadocUrlPrefix}NamedAttributeNode.html[`@NamedAttributeNode`] annotation is used to specify each individual attribute node that needs to be fetched by an Entity Graph. See the <> section for more info. [[annotations-jpa-namedentitygraph]] ==== `@NamedEntityGraph` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedEntityGraph.html[`@NamedEntityGraph`] annotation is used to specify an Entity Graph that can be used by an entity query to override the default fetch plan. +The {jpaJavadocUrlPrefix}NamedEntityGraph.html[`@NamedEntityGraph`] annotation is used to specify an Entity Graph that can be used by an entity query to override the default fetch plan. See the <> section for more info. [[annotations-jpa-namedentitygraphs]] ==== `@NamedEntityGraphs` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedEntityGraphs.html[`@NamedEntityGraphs`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}NamedEntityGraphs.html[`@NamedEntityGraphs`] annotation is used to group multiple <> annotations. [[annotations-jpa-namednativequeries]] ==== `@NamedNativeQueries` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedNativeQueries.html[`@NamedNativeQueries`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}NamedNativeQueries.html[`@NamedNativeQueries`] annotation is used to group multiple <> annotations. See the <> section for more info. [[annotations-jpa-namednativequery]] ==== `@NamedNativeQuery` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedNativeQuery.html[`@NamedNativeQuery`] annotation is used to specify a native SQL query that can be retrieved later by its name. +The {jpaJavadocUrlPrefix}NamedNativeQuery.html[`@NamedNativeQuery`] annotation is used to specify a native SQL query that can be retrieved later by its name. See the <> section for more info. [[annotations-jpa-namedqueries]] ==== `@NamedQueries` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedQueries.html[`@NamedQueries`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}NamedQueries.html[`@NamedQueries`] annotation is used to group multiple <> annotations. [[annotations-jpa-namedquery]] ==== `@NamedQuery` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedQuery.html[`@NamedQuery`] annotation is used to specify a JPQL query that can be retrieved later by its name. +The {jpaJavadocUrlPrefix}NamedQuery.html[`@NamedQuery`] annotation is used to specify a JPQL query that can be retrieved later by its name. See the <> section for more info. [[annotations-jpa-namedstoredprocedurequeries]] ==== `@NamedStoredProcedureQueries` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedStoredProcedureQueries.html[`@NamedStoredProcedureQueries`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}NamedStoredProcedureQueries.html[`@NamedStoredProcedureQueries`] annotation is used to group multiple <> annotations. [[annotations-jpa-namedstoredprocedurequery]] ==== `@NamedStoredProcedureQuery` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedStoredProcedureQuery.html[`@NamedStoredProcedureQuery`] annotation is used to specify a stored procedure query that can be retrieved later by its name. +The {jpaJavadocUrlPrefix}NamedStoredProcedureQuery.html[`@NamedStoredProcedureQuery`] annotation is used to specify a stored procedure query that can be retrieved later by its name. See the <> section for more info. [[annotations-jpa-namedsubgraph]] ==== `@NamedSubgraph` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedSubgraph.html[`@NamedSubgraph`] annotation used to specify a subgraph in an Entity Graph. +The {jpaJavadocUrlPrefix}NamedSubgraph.html[`@NamedSubgraph`] annotation used to specify a subgraph in an Entity Graph. See the <> section for more info. [[annotations-jpa-onetomany]] ==== `@OneToMany` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OneToMany.html[`@OneToMany`] annotation is used to specify a one-to-many database relationship. +The {jpaJavadocUrlPrefix}OneToMany.html[`@OneToMany`] annotation is used to specify a one-to-many database relationship. See the <> section for more info. [[annotations-jpa-onetoone]] ==== `@OneToOne` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OneToOne.html[`@OneToOne`] annotation is used to specify a one-to-one database relationship. +The {jpaJavadocUrlPrefix}OneToOne.html[`@OneToOne`] annotation is used to specify a one-to-one database relationship. See the <> section for more info. [[annotations-jpa-orderby]] ==== `@OrderBy` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OrderBy.html[`@OrderBy`] annotation is used to specify the entity attributes used for sorting when fetching the currently annotated collection. +The {jpaJavadocUrlPrefix}OrderBy.html[`@OrderBy`] annotation is used to specify the entity attributes used for sorting when fetching the currently annotated collection. See the <> section for more info. [[annotations-jpa-ordercolumn]] ==== `@OrderColumn` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OrderColumn.html[`@OrderColumn`] annotation is used to specify that the current annotation collection order should be materialized in the database. +The {jpaJavadocUrlPrefix}OrderColumn.html[`@OrderColumn`] annotation is used to specify that the current annotation collection order should be materialized in the database. See the <> section for more info. [[annotations-jpa-persistencecontext]] ==== `@PersistenceContext` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceContext.html[`@PersistenceContext`] annotation is used to specify the `EntityManager` that needs to be injected as a dependency. +The {jpaJavadocUrlPrefix}PersistenceContext.html[`@PersistenceContext`] annotation is used to specify the `EntityManager` that needs to be injected as a dependency. See the <> section for more info. [[annotations-jpa-persistencecontexts]] ==== `@PersistenceContexts` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceContexts.html[`@PersistenceContexts`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}PersistenceContexts.html[`@PersistenceContexts`] annotation is used to group multiple <> annotations. [[annotations-jpa-persistenceproperty]] ==== `@PersistenceProperty` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceProperty.html[`@PersistenceProperty`] annotation is used by the <> annotation to declare JPA provider properties that are passed to the underlying container when the `EntityManager` instance is created. +The {jpaJavadocUrlPrefix}PersistenceProperty.html[`@PersistenceProperty`] annotation is used by the <> annotation to declare JPA provider properties that are passed to the underlying container when the `EntityManager` instance is created. See the <> section for more info. [[annotations-jpa-persistenceunit]] ==== `@PersistenceUnit` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceUnit.html[`@PersistenceUnit`] annotation is used to specify the `EntityManagerFactory` that needs to be injected as a dependency. +The {jpaJavadocUrlPrefix}PersistenceUnit.html[`@PersistenceUnit`] annotation is used to specify the `EntityManagerFactory` that needs to be injected as a dependency. See the <> section for more info. [[annotations-jpa-persistenceunits]] ==== `@PersistenceUnits` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceUnits.html[`@PersistenceUnits`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}PersistenceUnits.html[`@PersistenceUnits`] annotation is used to group multiple <> annotations. [[annotations-jpa-postload]] ==== `@PostLoad` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PostLoad.html[`@PostLoad`] annotation is used to specify a callback method that fires after an entity is loaded. +The {jpaJavadocUrlPrefix}PostLoad.html[`@PostLoad`] annotation is used to specify a callback method that fires after an entity is loaded. See the <> section for more info. [[annotations-jpa-postpersist]] ==== `@PostPersist` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PostPersist.html[`@PostPersist`] annotation is used to specify a callback method that fires after an entity is persisted. +The {jpaJavadocUrlPrefix}PostPersist.html[`@PostPersist`] annotation is used to specify a callback method that fires after an entity is persisted. See the <> section for more info. [[annotations-jpa-postremove]] ==== `@PostRemove` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PostRemove.html[`@PostRemove`] annotation is used to specify a callback method that fires after an entity is removed. +The {jpaJavadocUrlPrefix}PostRemove.html[`@PostRemove`] annotation is used to specify a callback method that fires after an entity is removed. See the <> section for more info. [[annotations-jpa-postupdate]] ==== `@PostUpdate` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PostUpdate.html[`@PostUpdate`] annotation is used to specify a callback method that fires after an entity is updated. +The {jpaJavadocUrlPrefix}PostUpdate.html[`@PostUpdate`] annotation is used to specify a callback method that fires after an entity is updated. See the <> section for more info. [[annotations-jpa-prepersist]] ==== `@PrePersist` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PrePersist.html[`@PrePersist`] annotation is used to specify a callback method that fires before an entity is persisted. +The {jpaJavadocUrlPrefix}PrePersist.html[`@PrePersist`] annotation is used to specify a callback method that fires before an entity is persisted. See the <> section for more info. [[annotations-jpa-preremove]] ==== `@PreRemove` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PreRemove.html[`@PreRemove`] annotation is used to specify a callback method that fires before an entity is removed. +The {jpaJavadocUrlPrefix}PreRemove.html[`@PreRemove`] annotation is used to specify a callback method that fires before an entity is removed. See the <> section for more info. [[annotations-jpa-preupdate]] ==== `@PreUpdate` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PreUpdate.html[`@PreUpdate`] annotation is used to specify a callback method that fires before an entity is updated. +The {jpaJavadocUrlPrefix}PreUpdate.html[`@PreUpdate`] annotation is used to specify a callback method that fires before an entity is updated. See the <> section for more info. [[annotations-jpa-primarykeyjoincolumn]] ==== `@PrimaryKeyJoinColumn` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PrimaryKeyJoinColumn.html[`@PrimaryKeyJoinColumn`] annotation is used to specify that the primary key column of the currently annotated entity is also a foreign key to some other entity +The {jpaJavadocUrlPrefix}PrimaryKeyJoinColumn.html[`@PrimaryKeyJoinColumn`] annotation is used to specify that the primary key column of the currently annotated entity is also a foreign key to some other entity (e.g. a base class table in a `JOINED` inheritance strategy, the primary table in a secondary table mapping, or the parent table in a `@OneToOne` relationship). See the <> section for more info. @@ -529,92 +529,92 @@ See the <> annotations. +The {jpaJavadocUrlPrefix}PrimaryKeyJoinColumns.html[`@PrimaryKeyJoinColumns`] annotation is used to group multiple <> annotations. [[annotations-jpa-queryhint]] ==== `@QueryHint` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/QueryHint.html[`@QueryHint`] annotation is used to specify a JPA provider hint used by a `@NamedQuery` or a `@NamedNativeQuery` annotation. +The {jpaJavadocUrlPrefix}QueryHint.html[`@QueryHint`] annotation is used to specify a JPA provider hint used by a `@NamedQuery` or a `@NamedNativeQuery` annotation. See the <> section for more info. [[annotations-jpa-secondarytable]] ==== `@SecondaryTable` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/SecondaryTable.html[`@SecondaryTable`] annotation is used to specify a secondary table for the currently annotated entity. +The {jpaJavadocUrlPrefix}SecondaryTable.html[`@SecondaryTable`] annotation is used to specify a secondary table for the currently annotated entity. See the <> section for more info. [[annotations-jpa-secondarytables]] ==== `@SecondaryTables` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/SecondaryTables.html[`@SecondaryTables`] annotation is used to group multiple <> annotations. +The {jpaJavadocUrlPrefix}SecondaryTables.html[`@SecondaryTables`] annotation is used to group multiple <> annotations. [[annotations-jpa-sequencegenerator]] ==== `@SequenceGenerator` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/SequenceGenerator.html[`@SequenceGenerator`] annotation is used to specify the database sequence used by the identifier generator of the currently annotated entity. +The {jpaJavadocUrlPrefix}SequenceGenerator.html[`@SequenceGenerator`] annotation is used to specify the database sequence used by the identifier generator of the currently annotated entity. See the <> section for more info. [[annotations-jpa-sqlresultsetmapping]] ==== `@SqlResultSetMapping` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/SqlResultSetMapping.html[`@SqlResultSetMapping`] annotation is used to specify the `ResultSet` mapping of a native SQL query or stored procedure. +The {jpaJavadocUrlPrefix}SqlResultSetMapping.html[`@SqlResultSetMapping`] annotation is used to specify the `ResultSet` mapping of a native SQL query or stored procedure. See the <> section for more info. [[annotations-jpa-sqlresultsetmappings]] ==== `@SqlResultSetMappings` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/SqlResultSetMappings.html[`@SqlResultSetMappings`] annotation is group multiple <> annotations. +The {jpaJavadocUrlPrefix}SqlResultSetMappings.html[`@SqlResultSetMappings`] annotation is group multiple <> annotations. [[annotations-jpa-storedprocedureparameter]] ==== `@StoredProcedureParameter` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/StoredProcedureParameter.html[`@StoredProcedureParameter`] annotation is used to specify a parameter of a <>. +The {jpaJavadocUrlPrefix}StoredProcedureParameter.html[`@StoredProcedureParameter`] annotation is used to specify a parameter of a <>. See the <> section for more info. [[annotations-jpa-table]] ==== `@Table` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Table.html[`@Table`] annotation is used to specify the primary table of the currently annotated entity. +The {jpaJavadocUrlPrefix}Table.html[`@Table`] annotation is used to specify the primary table of the currently annotated entity. See the <> section for more info. [[annotations-jpa-tablegenerator]] ==== `@TableGenerator` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/TableGenerator.html[`@TableGenerator`] annotation is used to specify the database table used by the identity generator of the currently annotated entity. +The {jpaJavadocUrlPrefix}TableGenerator.html[`@TableGenerator`] annotation is used to specify the database table used by the identity generator of the currently annotated entity. See the <> section for more info. [[annotations-jpa-temporal]] ==== `@Temporal` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Temporal.html[`@Temporal`] annotation is used to specify the `TemporalType` of the currently annotated `java.util.Date` or `java.util.Calendar` entity attribute. +The {jpaJavadocUrlPrefix}Temporal.html[`@Temporal`] annotation is used to specify the `TemporalType` of the currently annotated `java.util.Date` or `java.util.Calendar` entity attribute. See the <> chapter for more info. [[annotations-jpa-transient]] ==== `@Transient` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Transient.html[`@Transient`] annotation is used to specify that a given entity attribute should not be persisted. +The {jpaJavadocUrlPrefix}Transient.html[`@Transient`] annotation is used to specify that a given entity attribute should not be persisted. See the <> section for more info. [[annotations-jpa-uniqueconstraint]] ==== `@UniqueConstraint` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/UniqueConstraint.html[`@UniqueConstraint`] annotation is used to specify a unique constraint to be included by the automated schema generator for the primary or secondary table associated with the currently annotated entity. +The {jpaJavadocUrlPrefix}UniqueConstraint.html[`@UniqueConstraint`] annotation is used to specify a unique constraint to be included by the automated schema generator for the primary or secondary table associated with the currently annotated entity. See the <> chapter for more info. [[annotations-jpa-version]] ==== `@Version` -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Version.html[`@Version`] annotation is used to specify the version attribute used for optimistic locking. +The {jpaJavadocUrlPrefix}Version.html[`@Version`] annotation is used to specify the version attribute used for optimistic locking. See the <> section for more info. @@ -676,7 +676,7 @@ See the <> chapter for more info. The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Cascade.html[`@Cascade`] annotation is used to apply the Hibernate specific http://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/CascadeType.html[`CascadeType`] strategies (e.g. `CascadeType.LOCK`, `CascadeType.SAVE_UPDATE`, `CascadeType.REPLICATE`) on a given association. -For JPA cascading, prefer using the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CascadeType.html[`javax.persistence.CascadeType`] instead. +For JPA cascading, prefer using the {jpaJavadocUrlPrefix}CascadeType.html[`javax.persistence.CascadeType`] instead. When combining both JPA and Hibernate `CascadeType` strategies, Hibernate will merge both sets of cascades. @@ -930,7 +930,7 @@ The possible values are given by the `https://docs.jboss.org/hibernate/orm/{majo `FALSE`:: Eagerly load it. `EXTRA`:: Prefer extra queries over full collection loading. -The `TRUE` and `FALSE` values are deprecated since you should be using the JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/FetchType.html[`FetchType`] attribute of the <>, <>, or <> collection. +The `TRUE` and `FALSE` values are deprecated since you should be using the JPA {jpaJavadocUrlPrefix}FetchType.html[`FetchType`] attribute of the <>, <>, or <> collection. The `EXTRA` value has no equivalent in the JPA specification, and it's used to avoid loading the entire collection even when the collection is accessed for the first time. Each element is fetched individually using a secondary query. diff --git a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc index 81dc32a3b2a2..fb4c994fc2eb 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc @@ -239,11 +239,11 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-EntityManag [NOTE] ==== If you don't want to provide a `persistence.xml` configuration file, JPA allows you to provide all the configuration options in a -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/spi/PersistenceUnitInfo.html[`PersistenceUnitInfo`] implementation and call +{jpaJavadocUrlPrefix}spi/PersistenceUnitInfo.html[`PersistenceUnitInfo`] implementation and call https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/HibernatePersistenceProvider.html#createContainerEntityManagerFactory-javax.persistence.spi.PersistenceUnitInfo-java.util.Map-[`HibernatePersistenceProvider.html#createContainerEntityManagerFactory`]. ==== -To inject the default Persistence Context, you can use the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceContext.html[`@PersistenceContext`] annotation. +To inject the default Persistence Context, you can use the {jpaJavadocUrlPrefix}PersistenceContext.html[`@PersistenceContext`] annotation. [[bootstrap-jpa-compliant-PersistenceContext-example]] .Inject the default `EntityManager` @@ -255,9 +255,9 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-Persistence ==== To inject a specific Persistence Context, -you can use the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceContext.html[`@PersistenceContext`] annotation, +you can use the {jpaJavadocUrlPrefix}PersistenceContext.html[`@PersistenceContext`] annotation, and you can even pass `EntityManager`-specific properties using the -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceProperty.html[`@PersistenceProperty`] annotation. +{jpaJavadocUrlPrefix}PersistenceProperty.html[`@PersistenceProperty`] annotation. [[bootstrap-jpa-compliant-PersistenceContext-configurable-example]] diff --git a/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc b/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc index fde8ac92b526..98474ba4ccb4 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc @@ -89,7 +89,7 @@ or by using the `javax.persistence.sharedCache.mode` property in your configurat The following values are possible: `ENABLE_SELECTIVE` (Default and recommended value):: - Entities are not cached unless explicitly marked as cacheable (with the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Cacheable.html[`@Cacheable`] annotation). + Entities are not cached unless explicitly marked as cacheable (with the {jpaJavadocUrlPrefix}Cacheable.html[`@Cacheable`] annotation). `DISABLE_SELECTIVE`:: Entities are cached unless explicitly marked as non-cacheable. `ALL`:: @@ -381,7 +381,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-m [NOTE] ==== -When using https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CacheStoreMode.html#REFRESH[`CacheStoreMode.REFRESH`] or https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/CacheMode.html#REFRESH[`CacheMode.REFRESH`] in conjunction with the region you have defined for the given query, +When using {jpaJavadocUrlPrefix}CacheStoreMode.html#REFRESH[`CacheStoreMode.REFRESH`] or https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/CacheMode.html#REFRESH[`CacheMode.REFRESH`] in conjunction with the region you have defined for the given query, Hibernate will selectively force the results cached in that particular region to be refreshed. This behavior is particularly useful in cases when the underlying data may have been updated via a separate process @@ -398,8 +398,8 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-native- Traditionally, Hibernate defined the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/CacheMode.html[`CacheMode`] enumeration to describe the ways of interactions with the cached data. -JPA split cache modes by storage (https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CacheStoreMode.html[`CacheStoreMode`]) -and retrieval (https://javaee.github.io/javaee-spec/javadocs/javax/persistence/CacheRetrieveMode.html[`CacheRetrieveMode`]). +JPA split cache modes by storage ({jpaJavadocUrlPrefix}CacheStoreMode.html[`CacheStoreMode`]) +and retrieval ({jpaJavadocUrlPrefix}CacheRetrieveMode.html[`CacheRetrieveMode`]). The relationship between Hibernate and JPA cache modes can be seen in the following table: @@ -460,7 +460,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-cache-mod Because the second level cache is bound to the `EntityManagerFactory` or the `SessionFactory`, cache eviction must be done through these two interfaces. -JPA only supports entity eviction through the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Cache.html[`javax.persistence.Cache`] interface: +JPA only supports entity eviction through the {jpaJavadocUrlPrefix}Cache.html[`javax.persistence.Cache`] interface: [[caching-management-evict-jpa-example]] .Evicting entities with JPA diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc index 8205d7d2098a..c92d557ad267 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc @@ -417,7 +417,7 @@ include::{extrasdir}/collections-customizing-ordered-list-ordinal-persist-exampl ===== Customizing ORDER BY SQL clause While the JPA -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OrderBy.html[`@OrderBy`] annotation allows you to specify the entity attributes used for sorting +{jpaJavadocUrlPrefix}OrderBy.html[`@OrderBy`] annotation allows you to specify the entity attributes used for sorting when fetching the current annotated collection, the Hibernate specific https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/OrderBy.html[`@OrderBy`] annotation is used to specify a *SQL* clause instead. @@ -647,7 +647,7 @@ include::{sourcedir}/MapKeyClassTest.java[tags=collections-map-key-class-type-ma ==== If you want to use the `PhoneNumber` interface as a `java.util.Map` key, then you need to supply the -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapKeyClass.html[`@MapKeyClass`] annotation as well. +{jpaJavadocUrlPrefix}MapKeyClass.html[`@MapKeyClass`] annotation as well. [[collections-map-key-class-mapping-example]] .`@MapKeyClass` mapping example diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc index 1694aa3c5f0b..8bac23663653 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/embeddables.adoc @@ -95,8 +95,8 @@ JPA defines the `@AttributeOverride` annotation to handle this scenario. This way, the mapping conflict is resolved by setting up explicit name-based property-column type mappings. If an Embeddable type is used multiple times in some entity, you need to use the -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AttributeOverride.html[`@AttributeOverride`] and -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/AssociationOverride.html[`@AssociationOverride`] annotations +{jpaJavadocUrlPrefix}AttributeOverride.html[`@AttributeOverride`] and +{jpaJavadocUrlPrefix}AssociationOverride.html[`@AssociationOverride`] annotations to override the default column names defined by the Embeddable. Considering you have the following `Publisher` embeddable type @@ -204,13 +204,13 @@ Embeddable types that are used as collection entries, map keys or entity type id The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Target.html[`@Target`] annotation is used to specify the implementation class of a given association that is mapped via an interface. The -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ManyToOne.html[`@ManyToOne`], -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OneToOne.html[`@OneToOne`], -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/OneToMany.html[`@OneToMany`], and -https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ManyToMany.html[`@ManyToMany`] -feature a https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ManyToOne.html#targetEntity--[`targetEntity`] attribute to specify the actual class of the entity association when an interface is used for the mapping. +{jpaJavadocUrlPrefix}ManyToOne.html[`@ManyToOne`], +{jpaJavadocUrlPrefix}OneToOne.html[`@OneToOne`], +{jpaJavadocUrlPrefix}OneToMany.html[`@OneToMany`], and +{jpaJavadocUrlPrefix}ManyToMany.html[`@ManyToMany`] +feature a {jpaJavadocUrlPrefix}ManyToOne.html#targetEntity--[`targetEntity`] attribute to specify the actual class of the entity association when an interface is used for the mapping. -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ElementCollection.html[`@ElementCollection`] association has a https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ElementCollection.html#targetClass--[`targetClass`] attribute for the same purpose. +The {jpaJavadocUrlPrefix}ElementCollection.html[`@ElementCollection`] association has a {jpaJavadocUrlPrefix}ElementCollection.html#targetClass--[`targetClass`] attribute for the same purpose. However, for simple embeddable types, there is no such construct and so you need to use the Hibernate-specific `@Target` annotation instead. diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc index ac6f40564c0e..42d154f1dee4 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc @@ -114,9 +114,9 @@ Hibernate offers multiple identifier generation strategies, see the <>, <>, or <> collection. +The `TRUE` and `FALSE` values are deprecated since you should be using the JPA {jpaJavadocUrlPrefix}FetchType.html[`FetchType`] attribute of the <>, <>, or <> collection. The `EXTRA` value has no equivalent in the JPA specification, and it's used to avoid loading the entire collection even when the collection is accessed for the first time. Each element is fetched individually using a secondary query. diff --git a/documentation/src/main/asciidoc/userguide/chapters/flushing/Flushing.adoc b/documentation/src/main/asciidoc/userguide/chapters/flushing/Flushing.adoc index 0a92cb6508bb..f03b7f220297 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/flushing/Flushing.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/flushing/Flushing.adoc @@ -17,7 +17,7 @@ See the <> for more informa ==== The flushing strategy is given by the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Session.html#getFlushMode--[`flushMode`] of the current running Hibernate `Session`. -Although JPA defines only two flushing strategies (https://javaee.github.io/javaee-spec/javadocs/javax/persistence/FlushModeType.html#AUTO[`AUTO`] and https://javaee.github.io/javaee-spec/javadocs/javax/persistence/FlushModeType.html#COMMIT[`COMMIT`]), +Although JPA defines only two flushing strategies ({jpaJavadocUrlPrefix}FlushModeType.html#AUTO[`AUTO`] and {jpaJavadocUrlPrefix}FlushModeType.html#COMMIT[`COMMIT`]), Hibernate has a much broader spectrum of flush types: ALWAYS:: Flushes the `Session` before every query. diff --git a/documentation/src/main/asciidoc/userguide/chapters/locking/Locking.adoc b/documentation/src/main/asciidoc/userguide/chapters/locking/Locking.adoc index 8dbe4fbf83ce..7784ce31c653 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/locking/Locking.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/locking/Locking.adoc @@ -312,7 +312,7 @@ Hibernate always uses the locking mechanism of the database, and never lock obje === `LockMode` and `LockModeType` Long before JPA 1.0, Hibernate already defined various explicit locking strategies through its `LockMode` enumeration. -JPA comes with its own https://javaee.github.io/javaee-spec/javadocs/javax/persistence/LockModeType.html[`LockModeType`] enumeration which defines similar strategies as the Hibernate-native `LockMode`. +JPA comes with its own {jpaJavadocUrlPrefix}LockModeType.html[`LockModeType`] enumeration which defines similar strategies as the Hibernate-native `LockMode`. [cols=",,",, options="header"] |======================================================================= @@ -351,7 +351,7 @@ This ensures that applications are portable. JPA 2.0 introduced two query hints: javax.persistence.lock.timeout:: it gives the number of milliseconds a lock acquisition request will wait before throwing an exception -javax.persistence.lock.scope:: defines the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PessimisticLockScope.html[_scope_] of the lock acquisition request. +javax.persistence.lock.scope:: defines the {jpaJavadocUrlPrefix}PessimisticLockScope.html[_scope_] of the lock acquisition request. The scope can either be `NORMAL` (default value) or `EXTENDED`. The `EXTENDED` scope will cause a lock acquisition request to be passed to other owned table structured (e.g. `@Inheritance(strategy=InheritanceType.JOINED)`, `@ElementCollection`) [[locking-jpa-query-hints-timeout-example]] diff --git a/documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc b/documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc index becc39ea0db6..1d4d5a4dc84f 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc @@ -1388,7 +1388,7 @@ Certain methods of the JPA `EntityManager` or the Hibernate `Session` will not l Rolling back the database transaction does not put your business objects back into the state they were at the start of the transaction. This means that the database state and the business objects will be out of sync. Usually, this is not a problem because exceptions are not recoverable and you will have to start over after rollback anyway. -The JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceException.html[`PersistenceException`] or the +The JPA {jpaJavadocUrlPrefix}PersistenceException.html[`PersistenceException`] or the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/HibernateException.html[`HibernateException`] wraps most of the errors that can occur in a Hibernate persistence layer. Both the `PersistenceException` and the `HibernateException` are runtime exceptions because, in our opinion, we should not force the application developer to catch an unrecoverable exception at a low layer. In most systems, unchecked and fatal exceptions are handled in one of the first frames of the method call stack (i.e., in higher layers) and either an error message is presented to the application user or some other appropriate action is taken. Note that Hibernate might also throw other unchecked exceptions that are not a `HibernateException`. These are not recoverable either, and appropriate action should be taken. @@ -1431,7 +1431,7 @@ SQLGrammarException:: [NOTE] ==== Starting with Hibernate 5.2, the Hibernate `Session` extends the JPA `EntityManager`. For this reason, when a `SessionFactory` is built via Hibernate's native bootstrapping, -the `HibernateException` or `SQLException` can be wrapped in a JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/PersistenceException.html[`PersistenceException`] when thrown +the `HibernateException` or `SQLException` can be wrapped in a JPA {jpaJavadocUrlPrefix}PersistenceException.html[`PersistenceException`] when thrown by `Session` methods that implement `EntityManager` methods (e.g., https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Session.html#merge-java.lang.Object-[Session.merge(Object object)], https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Session.html#flush--[Session.flush()]). diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc index 17902a1f960e..2e8fc345e43f 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc @@ -104,7 +104,7 @@ include::{sourcedir}/HQLTest.java[tags=jpql-api-basic-usage-example] ---- ==== -For complete details, see the `Query` https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Query.html[Javadocs]. +For complete details, see the `Query` {jpaJavadocUrlPrefix}Query.html[Javadocs]. Many of the settings controlling the execution of the query are defined as hints. JPA defines some standard hints (like timeout in the example), but most are provider specific. Relying on provider specific hints limits your applications portability to some degree. @@ -1984,7 +1984,7 @@ include::{extrasdir}/hql-read-only-entities-example.sql[] As you can see, there is no SQL `UPDATE` being executed. -You can also pass the read-only hint to named queries using the JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/QueryHint.html[`@QueryHint`] annotation. +You can also pass the read-only hint to named queries using the JPA {jpaJavadocUrlPrefix}QueryHint.html[`@QueryHint`] annotation. [[jpa-read-only-entities-native-example]] .Fetching read-only entities using a named query and the read-only hint diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc index dc827ce7caef..657f7e6cd029 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc @@ -840,7 +840,7 @@ For SQL Server, if you can enable `SET NOCOUNT ON` in your procedure it will pro === Using named queries to call stored procedures Just like with SQL statements, you can also use named queries to call stored procedures. -For this purpose, JPA defines the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedStoredProcedureQuery.html[`@NamedStoredProcedureQuery`] annotation. +For this purpose, JPA defines the {jpaJavadocUrlPrefix}NamedStoredProcedureQuery.html[`@NamedStoredProcedureQuery`] annotation. [[sql-sp-ref-cursor-oracle-named-query-example]] .Oracle `REF_CURSOR` named query stored procedure diff --git a/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc b/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc index 399f8203a8f8..13d496e3bc33 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc @@ -162,7 +162,7 @@ include::{extrasdir}/schema-generation-column-default-value-persist-example.sql[ [[schema-generation-columns-unique-constraint]] === Columns unique constraint -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/UniqueConstraint.html[`@UniqueConstraint`] annotation is used to specify a unique constraint to be included by the automated schema generator for the primary or secondary table associated with the current annotated entity. +The {jpaJavadocUrlPrefix}UniqueConstraint.html[`@UniqueConstraint`] annotation is used to specify a unique constraint to be included by the automated schema generator for the primary or secondary table associated with the current annotated entity. Considering the following entity mapping, Hibernate generates the unique constraint DDL when creating the database schema: @@ -202,7 +202,7 @@ The second INSERT statement fails because of the unique constraint violation. [[schema-generation-columns-index]] === Columns index -The https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Index.html[`@Index`] annotation is used by the automated schema generation tool to create a database index. +The {jpaJavadocUrlPrefix}Index.html[`@Index`] annotation is used by the automated schema generation tool to create a database index. Considering the following entity mapping. Hibernate generates the index when creating the database schema: From 588115bb0a055573a85a8fa01c50490390870ca2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yoann=20Rodi=C3=A8re?= Date: Tue, 14 Apr 2020 15:21:33 +0200 Subject: [PATCH 9/9] HHH-13682 Restore the system property net.bytebuddy.experimental=true in tests on JDK15+ Turns out it's necessary for JDKs with experimental support. --- gradle/java-module.gradle | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/gradle/java-module.gradle b/gradle/java-module.gradle index 5934e8d64cdf..0b7b1b14b125 100644 --- a/gradle/java-module.gradle +++ b/gradle/java-module.gradle @@ -208,6 +208,15 @@ processTestResources { } } +// Enable the experimental features of ByteBuddy with JDK 15+ +test { + if ( Integer.valueOf( gradle.ext.testedJavaVersionAsEnum.getMajorVersion() ) >= 15 ) { + logger.warn( "The version of java that will be tested is not supported by Bytebuddy by default. " + + " Setting 'net.bytebuddy.experimental=true'." ) + systemProperty 'net.bytebuddy.experimental', true + } +} + test { if ( project.findProperty( 'log-test-progress' )?.toString()?.toBoolean() ) { // Log a statement for each test.