HHH-10566 - linking to specific 'stable' doc urls from versioned docs

documentation/documentation.gradle

@@ -289,6 +289,9 @@ task renderMappingGuide(type: AsciidoctorTask, group: 'Documentation') {
 
 // User Guides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+final String[] versionComponents = version.split( '\\.' );
+final String majorMinorVersion = versionComponents[0] + '.' + versionComponents[1];
+
 task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {
     description = 'Renders the User Guides in HTML format using Asciidoctor.'
     sourceDir = file( 'src/main/asciidoc/userguide' )
@@ -297,7 +300,7 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {
     separateOutputDirs false
     options logDocuments: true
     //attributes  icons: 'font', experimental: true, 'source-highlighter': 'prettify', linkcss: true, stylesheet: "css/hibernate.css"
-    attributes  icons: 'font', experimental: true, 'source-highlighter': 'prettify', linkcss: true
+    attributes  icons: 'font', experimental: true, 'source-highlighter': 'prettify', linkcss: true, majorMinorVersion: majorMinorVersion
     resources {
         from('src/main/asciidoc/') {
             include 'images/**'

documentation/src/main/asciidoc/userguide/chapters/bootstrap/Bootstrap.adoc

@@ -70,7 +70,7 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-bootstrap-native-registry
 ====
 
 A `StandardServiceRegistry` is also highly configurable via the StandardServiceRegistryBuilder API.
-See the `StandardServiceRegistryBuilder` https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/registry/StandardServiceRegistryBuilder.html[Javadocs] for more details.
+See the `StandardServiceRegistryBuilder` https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/registry/StandardServiceRegistryBuilder.html[Javadocs] for more details.
 
 Some specific methods of interest:
 
@@ -105,7 +105,7 @@ The second step in native bootstrapping is the building of a `org.hibernate.boot
 The first thing we obviously need to build a parsed representation is the source information to be parsed (annotated classes, `hbm.xml` files, `orm.xml` files).
 This is the purpose of `org.hibernate.boot.MetadataSources`:
 
-`MetadataSources` has many other methods as well, explore its API and https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/MetadataSources.html[Javadocs] for more information.
+`MetadataSources` has many other methods as well, explore its API and https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/MetadataSources.html[Javadocs] for more information.
 Also, all methods on `MetadataSources` offer fluent-style call chaining::
 
 [[bootstrap-native-metadata-source-example]]
@@ -118,7 +118,7 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-metadata-source-ex
 ====
 
 Once we have the sources of mapping information defined, we need to build the `Metadata` object.
-If you are ok with the default behavior in building the Metadata then you can simply call the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/MetadataSources.html#buildMetadata--[1buildMetadata`] method of the `MetadataSources`.
+If you are ok with the default behavior in building the Metadata then you can simply call the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/MetadataSources.html#buildMetadata--[`buildMetadata`] method of the `MetadataSources`.
 
 [NOTE]
 ====
@@ -130,7 +130,7 @@ From there, `MetadataBuilder`, `Metadata`, `SessionFactoryBuilder` and `SessionF
 However, if you wish to adjust the process of building `Metadata` from `MetadataSources`,
 you will need to use the `MetadataBuilder` as obtained via `MetadataSources#getMetadataBuilder`.
 `MetadataBuilder` allows a lot of control over the `Metadata` building process.
-See its https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/MetadataBuilder.html[Javadocs] for full details.
+See its https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/MetadataBuilder.html[Javadocs] for full details.
 
 [[bootstrap-native-metadata-builder-example]]
 .Building Metadata via `MetadataBuilder`
@@ -145,9 +145,9 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-native-metadata-builder-e
 ==== Building the SessionFactory
 
 The final step in native bootstrapping is to build the `SessionFactory` itself.
-Much like discussed above, if you are ok with the default behavior of building a `SessionFactory` from a `Metadata` reference, you can simply call the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/Metadata.html#buildSessionFactory--[`buildSessionFactory`] method on the `Metadata` object.
+Much like discussed above, if you are ok with the default behavior of building a `SessionFactory` from a `Metadata` reference, you can simply call the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/Metadata.html#buildSessionFactory--[`buildSessionFactory`] method on the `Metadata` object.
 
-However, if you would like to adjust that building process you will need to use `SessionFactoryBuilder` as obtained via [`Metadata#getSessionFactoryBuilder`. Again, see its https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/boot/Metadata.html#getSessionFactoryBuilder--[Javadocs] for more details.
+However, if you would like to adjust that building process you will need to use `SessionFactoryBuilder` as obtained via [`Metadata#getSessionFactoryBuilder`. Again, see its https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/boot/Metadata.html#getSessionFactoryBuilder--[Javadocs] for more details.
 
 [[bootstrap-native-SessionFactory-example]]
 .Native Bootstrapping - Putting it all together
@@ -217,7 +217,7 @@ include::{sourcedir}/BootstrapTest.java[tags=bootstrap-jpa-compliant-EntityManag
 [[bootstrap-jpa-hibernate]]
 ==== Proprietary JPA bootstrapping
 
-Hibernate defines a proprietary https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.html[`EntityManagerFactoryBuilderImpl`]
+Hibernate defines a proprietary https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.html[`EntityManagerFactoryBuilderImpl`]
 utility, which allows bootstrapping the JPA environment without even in the absence of the `persistence.xml` configuration file.
 To substitute the `persistence.xml` file, Hibernate offers the `PersistenceUnitInfoDescriptor` utility, which can take configuration that's available in the standard XML configuration file.
 

documentation/src/main/asciidoc/userguide/chapters/caching/Caching.adoc

@@ -104,7 +104,7 @@ transactional::
 [NOTE]
 ====
 Rather than using a global cache concurrency strategy, it is recommended to define this setting on a per entity basis.
-Use the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/annotations/Cache.html[`@org.hibernate.annotations.Cache`] annotation for that.
+Use the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Cache.html[`@org.hibernate.annotations.Cache`] annotation for that.
 ====
 
 The `@Cache` annotation define three attributes:
@@ -335,7 +335,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-store-m
 
 [NOTE]
 ====
-When using http://docs.oracle.com/javaee/7/api/javax/persistence/CacheStoreMode.html#REFRESH[`CacheStoreMode.REFRESH`] or https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/CacheMode.html#REFRESH[`CacheMode.REFRESH`] in conjunction with the region you have defined for the given query,
+When using http://docs.oracle.com/javaee/7/api/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,
 Hibernate will selectively force the results cached in that particular region to be refreshed.
 
 This is particularly useful in cases where underlying data may have been updated via a separate process
@@ -351,7 +351,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-query-region-native-
 [[caching-management]]
 === Managing the cached data
 
-Traditionally, Hibernate defined the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/CacheMode.html[`CacheMode`] enumeration to describe
+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 (http://docs.oracle.com/javaee/7/api/javax/persistence/CacheStoreMode.html[`CacheStoreMode`])
 and retrieval (http://docs.oracle.com/javaee/7/api/javax/persistence/CacheRetrieveMode.html[`CacheRetrieveMode`]).
@@ -427,7 +427,7 @@ include::{sourcedir}/SecondLevelCacheTest.java[tags=caching-management-evict-jpa
 ====
 
 Hibernate is much more flexible in this regard as it offers a fine-grained control over what needs to be evicted.
-The https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/Cache.html[`org.hibernate.Cache`] interface defines various evicting strategies:
+The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Cache.html[`org.hibernate.Cache`] interface defines various evicting strategies:
 
 - entities (by their class or region)
 - entities stored using the natural-id (by their class or region)
@@ -450,7 +450,7 @@ If you enable the `hibernate.generate_statistics` configuration property,
 Hibernate will expose a number of metrics via `SessionFactory.getStatistics()`.
 Hibernate can even be configured to expose these statistics via JMX.
 
-This way, you can get access to the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/stat/Statistics.html[`Statistics`] class which comprises all sort of
+This way, you can get access to the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/stat/Statistics.html[`Statistics`] class which comprises all sort of
 second-level cache metrics.
 
 [[caching-statistics-example]]

documentation/src/main/asciidoc/userguide/chapters/envers/Envers.adoc

@@ -32,7 +32,7 @@ Instead of annotating the whole class and auditing all properties, you can annot
 This will cause only these properties to be audited.
 
 The audit (history) of an entity can be accessed using the `AuditReader` interface, which can be obtained having an open `EntityManager` or `Session` via the `AuditReaderFactory`.
-See the [Javadocs](https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/envers/AuditReaderFactory.html) for these classes for details on the functionality offered.
+See the [Javadocs](https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/envers/AuditReaderFactory.html) for these classes for details on the functionality offered.
 
 [[envers-configuration]]
 === Configuration
@@ -196,7 +196,7 @@ There are two things you need to make this work:
 +
 NOTE: It is an error for there to be multiple entities marked as `@org.hibernate.envers.RevisionEntity`
 
-. Second, you need to tell Envers how to create instances of your revision entity which is handled by the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/envers/RevisionListener.html#newRevision-java.lang.Object-[`newRevision( Object revisionEntity )`] method of the `org.hibernate.envers.RevisionListener` interface.
+. Second, you need to tell Envers how to create instances of your revision entity which is handled by the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/envers/RevisionListener.html#newRevision-java.lang.Object-[`newRevision( Object revisionEntity )`] method of the `org.hibernate.envers.RevisionListener` interface.
 +
   You tell Envers your custom `org.hibernate.envers.RevisionListener` implementation to use by specifying it on the `@org.hibernate.envers.RevisionEntity` annotation, using the value attribute.
   If your `RevisionListener` class is inaccessible from `@RevisionEntity` (e.g. it exists in a different module), set `org.hibernate.envers.revision_listener` property to its fully qualified class name.
@@ -263,7 +263,7 @@ public class ExampleListener implements RevisionListener {
 
 [NOTE]
 ====
-An alternative method to using the `org.hibernate.envers.RevisionListener` is to instead call the https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/envers/AuditReader.html#getCurrentRevision-java.lang.Class-boolean-[`getCurrentRevision( Class<T> revisionEntityClass, boolean persist )`] method of the `org.hibernate.envers.AuditReader` interface to obtain the current revision, and fill it with desired information.
+An alternative method to using the `org.hibernate.envers.RevisionListener` is to instead call the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/envers/AuditReader.html#getCurrentRevision-java.lang.Class-boolean-[`getCurrentRevision( Class<T> revisionEntityClass, boolean persist )`] method of the `org.hibernate.envers.AuditReader` interface to obtain the current revision, and fill it with desired information.
 The method accepts a `persist` parameter indicating whether the revision entity should be persisted prior to returning from this method:
 
 `true`:: ensures that the returned entity has access to its identifier value (revision number), but the revision entity will be persisted regardless of whether there are any audited entities changed.

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

@@ -16,7 +16,7 @@ Because DML statements are grouped together, Hibernate can apply batching transp
 See the <<chapters/batch/Batching.adoc#batch,Batching chapter>> for more information.
 ====
 
-The flushing strategy is given by the http://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/Session.html#getFlushMode--[`flushMode`] of the current running Hibernate `Session`.
+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://docs.oracle.com/javaee/7/api/javax/persistence/FlushModeType.html#AUTO[`AUTO`] and https://docs.oracle.com/javaee/7/api/javax/persistence/FlushModeType.html#COMMIT[`COMMIT`]),
 Hibernate has a much broader spectrum of flush types:
 

documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc

@@ -8,7 +8,7 @@ As an ORM tool, probably the single most important thing you need to tell Hibern
 This is ultimately the function of the `org.hibernate.engine.jdbc.connections.spi.ConnectionProvider` interface.
 Hibernate provides some out of the box implementations of this interface.
 `ConnectionProvider` is also an extension point, so you can also use custom implementations from third parties or written yourself.
-The ConnectionProvider to use is defined by the `hibernate.connection.provider_class` setting. See the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/cfg/AvailableSettings.html#CONNECTION_PROVIDER`[org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER`]
+The `ConnectionProvider` to use is defined by the `hibernate.connection.provider_class` setting. See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/cfg/AvailableSettings.html#CONNECTION_PROVIDER[`org.hibernate.cfg.AvailableSettings#CONNECTION_PROVIDER`]
 
 Generally speaking applications should not have to configure a `ConnectionProvider` explicitly if using one of the Hibernate-provided implementations.
 Hibernate will internally determine which `ConnectionProvider` to use based on the following algorithm:

documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc

@@ -209,7 +209,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-api-basic-usage-example]
 ----
 ====
 
-For complete details, see the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/Query.html[Query] Javadocs.
+For complete details, see the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Query.html[Query] Javadocs.
 
 [IMPORTANT]
 ====
@@ -225,7 +225,7 @@ Locking is covered in detail in <<chapters/locking/Locking.adoc#locking,Locking>
 The concept of read-only state is covered in <<chapters/pc/PersistenceContext.adoc#pc,Persistence Contexts>>.
 
 Hibernate also allows an application to hook into the process of building the query results via the `org.hibernate.transform.ResultTransformer` contract.
-See its http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/transform/ResultTransformer.html[Javadocs] as well as the Hibernate-provided implementations for additional details.
+See its https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/transform/ResultTransformer.html[Javadocs] as well as the Hibernate-provided implementations for additional details.
 
 The last thing that needs to happen before we can execute the query is to bind the values for any parameters defined in the query.
 Query defines many overloaded methods for this purpose.
@@ -315,7 +315,7 @@ Hibernate offers 2 additional, specialized methods for performing the query and
 The `scroll` method is overloaded.
 
 * Then main form accepts a single argument of type `org.hibernate.ScrollMode` which indicates the type of scrolling to be used.
-See the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/ScrollMode.html[Javadocs] for the details on each.
+See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/ScrollMode.html[Javadocs] for the details on each.
 * The second form takes no argument and will use the `ScrollMode` indicated by `Dialect#defaultScrollMode`.
 `Query#scroll` returns a `org.hibernate.ScrollableResults` which wraps the underlying JDBC (scrollable) `ResultSet` and provides access to the results.
 Since this form holds the JDBC `ResultSet` open, the application should indicate when it is done with the `ScrollableResults` by calling its `close()` method (as inherited from `java.io.Closeable`, so that `ScrollableResults` will work with try-with-resources blocks!).
@@ -339,7 +339,7 @@ In cases where many of the entities do not exist in the second-level cache, this
 
 The `Iterator` returned from `Query#iterate` is actually a specially typed Iterator: `org.hibernate.engine.HibernateIterator`.
 It is specialized to expose a `close()` method (again, inherited from `java.io.Closeable`).
-When you are done with this `Iterator` you should close it, either by casting to `HibernateIterator` or `Closeable`, or by calling http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/Hibernate.html#close%28java.util.Iterator%29[`Hibernate.html#close(java.util.Iterator)`].
+When you are done with this `Iterator` you should close it, either by casting to `HibernateIterator` or `Closeable`, or by calling https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/Hibernate.html#close-java.util.Iterator-[`Hibernate#close(java.util.Iterator)`].
 
 [[hql-case-sensitivity]]
 === Case Sensitivity

documentation/src/main/asciidoc/userguide/chapters/transactions/Transactions.adoc

@@ -147,15 +147,15 @@ However, as of version 3.1, the processing behind `SessionFactory.getCurrentSess
 To that end, a new extension interface, `org.hibernate.context.spi.CurrentSessionContext`,
 and a new configuration parameter, `hibernate.current_session_context_class`, have been added to allow pluggability of the scope and context of defining current sessions.
 
-See the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/context/spi/CurrentSessionContext.html[Javadocs] for the `org.hibernate.context.spi.CurrentSessionContext` interface for a detailed discussion of its contract.
+See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/spi/CurrentSessionContext.html[Javadocs] for the `org.hibernate.context.spi.CurrentSessionContext` interface for a detailed discussion of its contract.
 It defines a single method, `currentSession()`, by which the implementation is responsible for tracking the current contextual session.
 Out-of-the-box, Hibernate comes with three implementations of this interface:
 
 `org.hibernate.context.internal.JTASessionContext`:: current sessions are tracked and scoped by a `JTA` transaction.
-The processing here is exactly the same as in the older JTA-only approach. See the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/context/internal/JTASessionContext.html[Javadocs] for more details.
-* `org.hibernate.context.internal.ThreadLocalSessionContext`:current sessions are tracked by thread of execution. See the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/context/internal/ThreadLocalSessionContext.html[Javadocs] for more details.
+The processing here is exactly the same as in the older JTA-only approach. See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/internal/JTASessionContext.html[Javadocs] for more details.
+* `org.hibernate.context.internal.ThreadLocalSessionContext`:current sessions are tracked by thread of execution. See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/internal/ThreadLocalSessionContext.html[Javadocs] for more details.
 * `org.hibernate.context.internal.ManagedSessionContext`: current sessions are tracked by thread of execution.
-However, you are responsible to bind and unbind a `Session` instance with static methods on this class: it does not open, flush, or close a `Session`. See the http://docs.jboss.org/hibernate/stable/core/javadocs/org/hibernate/context/internal/ManagedSessionContext.html[Javadocs] for details.
+However, you are responsible to bind and unbind a `Session` instance with static methods on this class: it does not open, flush, or close a `Session`. See the https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/context/internal/ManagedSessionContext.html[Javadocs] for details.
 
 Typically, the value of this parameter would just name the implementation class to use.
 For the three out-of-the-box implementations, however, there are three corresponding short names: _jta_, _thread_, and _managed_.