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

@@ -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/') {

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]]

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

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

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.
 

documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc

@@ -114,9 +114,9 @@ Hibernate offers multiple identifier generation strategies, see the <<chapters/d
 [[entity-pojo-mapping]]
 ==== Mapping the entity
 
-The main piece in mapping the entity is the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Entity.html[`javax.persistence.Entity`] annotation.
+The main piece in mapping the entity is the {jpaJavadocUrlPrefix}Entity.html[`javax.persistence.Entity`] annotation.
 
-The `@Entity` annotation defines just the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Entity.html#name--[`name`] attribute which is used to give a specific entity name for use in JPQL queries.
+The `@Entity` annotation defines just the {jpaJavadocUrlPrefix}Entity.html#name--[`name`] attribute which is used to give a specific entity name for use in JPQL queries.
 
 By default, if the name attribute of the `@Entity` annotation is missing, the unqualified name of the entity class itself will be used as the entity name.
 
@@ -168,7 +168,7 @@ include::{sourcedir-mapping}/identifier/SimpleEntityTableTest.java[tag=entity-po
 
 Without specifying the catalog of the associated database table a given entity is mapped to, Hibernate will use the default catalog associated with the current database connection.
 
-However, if your database hosts multiple catalogs, you can specify the catalog where a given table is located using the `catalog` attribute of the JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Table.html[`@Table`] annotation.
+However, if your database hosts multiple catalogs, you can specify the catalog where a given table is located using the `catalog` attribute of the JPA {jpaJavadocUrlPrefix}Table.html[`@Table`] annotation.
 
 Let's assume we are using MySQL and want to map a `Book` entity to the `book` table located in the `public` catalog
 which looks as follows.
@@ -198,7 +198,7 @@ include::{sourcedir-mapping}/identifier/EntityTableCatalogTest.java[tag=mapping-
 
 Without specifying the schema of the associated database table a given entity is mapped to, Hibernate will use the default schema associated with the current database connection.
 
-However, if your database supports schemas, you can specify the schema where a given table is located using the `schema` attribute of the JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Table.html[`@Table`] annotation.
+However, if your database supports schemas, you can specify the schema where a given table is located using the `schema` attribute of the JPA {jpaJavadocUrlPrefix}Table.html[`@Table`] annotation.
 
 Let's assume we are using PostgreSQL and want to map a `Book` entity to the `book` table located in the `library` schema
 which looks as follows.

documentation/src/main/asciidoc/userguide/chapters/domain/identifiers.adoc

@@ -437,7 +437,7 @@ If no table name is given Hibernate assumes an implicit name of `hibernate_seque
 Additionally, because no `javax.persistence.TableGenerator#pkColumnValue` is specified,
 Hibernate will use the default segment (`sequence_name='default'`) from the hibernate_sequences table.
 
-However, you can configure the table identifier generator using the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/TableGenerator.html[`@TableGenerator`] annotation.
+However, you can configure the table identifier generator using the {jpaJavadocUrlPrefix}TableGenerator.html[`@TableGenerator`] annotation.
 
 [[identifiers-generators-table-configured-mapping-example]]
 .Configured table generator

documentation/src/main/asciidoc/userguide/chapters/events/Events.adoc

@@ -247,8 +247,8 @@ include::{extrasdir}/events-default-listener-update-example.sql[]
 
 If you already registered a default entity listener, but you don't want to apply it to a particular entity,
 you can use the
-https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ExcludeDefaultListeners.html[`@ExcludeDefaultListeners`] and
-https://javaee.github.io/javaee-spec/javadocs/javax/persistence/ExcludeSuperclassListeners.html[`@ExcludeSuperclassListeners`] JPA annotations.
+{jpaJavadocUrlPrefix}ExcludeDefaultListeners.html[`@ExcludeDefaultListeners`] and
+{jpaJavadocUrlPrefix}ExcludeSuperclassListeners.html[`@ExcludeSuperclassListeners`] JPA annotations.
 
 `@ExcludeDefaultListeners` instructs the current class to ignore the default entity listeners for the current entity
 while `@ExcludeSuperclassListeners` is used to ignore the default entity listeners propagated to the `BaseEntity` super-class.

documentation/src/main/asciidoc/userguide/chapters/fetching/Fetching.adoc

@@ -219,7 +219,7 @@ An EntityGraph is the root of a "load plan" and must correspond to an EntityType
 ==== JPA (key) subgraphs
 
 A sub-graph is used to control the fetching of sub-attributes of the AttributeNode it is applied to.
-It is generally defined via the https://javaee.github.io/javaee-spec/javadocs/javax/persistence/NamedSubgraph.html[`@NamedSubgraph`] annotation.
+It is generally defined via the {jpaJavadocUrlPrefix}NamedSubgraph.html[`@NamedSubgraph`] annotation.
 
 If we have a `Project` parent entity which has an `employees` child associations,
 and we'd like to fetch the `department` for the `Employee` child association.
@@ -587,7 +587,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 <<annotations-jpa-elementcollection>>, <<annotations-jpa-onetomany>>, or <<annotations-jpa-manytomany>> collection.
+The `TRUE` and `FALSE` values are deprecated since you should be using the JPA {jpaJavadocUrlPrefix}FetchType.html[`FetchType`] attribute of the <<annotations-jpa-elementcollection>>, <<annotations-jpa-onetomany>>, or <<annotations-jpa-manytomany>> 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.

documentation/src/main/asciidoc/userguide/chapters/flushing/Flushing.adoc

@@ -17,7 +17,7 @@ See the <<chapters/batch/Batching.adoc#batch,Batching chapter>> 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.

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]]

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()]).