HHH-12353 - Document that Session.getReference not always returns a T

documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc

@@ -1163,7 +1163,7 @@ See the <<chapters/domain/inheritance.adoc#entity-inheritance-polymorphism, `@Po
 [[annotations-hibernate-proxy]]
 ==== `@Proxy`
 
-The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Proxy.html[`@Proxy`] annotation is used to specify a custom Proxy implementation for the current annotated entity.
+The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Proxy.html[`@Proxy`] annotation is used to specify a custom proxy implementation for the current annotated entity.
 
 See the <<chapters/domain/entity.adoc#entity-proxy, `@Proxy` mapping>> section for more info.
 

documentation/src/main/asciidoc/userguide/appendices/BestPractices.adoc

@@ -40,7 +40,7 @@ log4j.logger.org.hibernate.type.descriptor.sql=trace
 ----
 
 However, there are some other alternatives like using datasource-proxy or p6spy.
-The advantage of using a JDBC `Driver` or `DataSource` Proxy is that you can go beyond simple SQL logging:
+The advantage of using a JDBC `Driver` or `DataSource` proxy is that you can go beyond simple SQL logging:
 
 - statement execution time
 - JDBC batching logging

documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc

@@ -66,10 +66,10 @@ If enabled, Hibernate will operate in the JPA specified way, throwing exceptions
 The JPA spec says that a `javax.persistence.EntityNotFoundException` should be thrown when accessing an entity Proxy
 which does not have an associated table row in the database.
 +
-Traditionally, Hibernate does not initialize an entity Proxy when accessing its identifier since we already know the identifier value,
+Traditionally, Hibernate does not initialize an entity proxy when accessing its identifier since we already know the identifier value,
 hence we can save a database roundtrip.
 +
-If enabled Hibernate will initialize the entity Proxy even when accessing its identifier.
+If enabled Hibernate will initialize the entity proxy even when accessing its identifier.
 
 `*hibernate.jpa.compliance.global_id_generators*` (e.g. `true` or `false` (default value) )::
 The JPA spec says that the scope of TableGenerator and SequenceGenerator names is global to the persistence unit (across all generator types).

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

@@ -361,7 +361,7 @@ By default, when it needs to use a proxy instead of the actual Pojo, Hibernate i
 http://jboss-javassist.github.io/javassist/[Javassist] or
 http://bytebuddy.net/[Byte Buddy].
 
-However, if the entity class is final, Javassist will not create a Proxy and you will get a Pojo even when you only need a Proxy reference.
+However, if the entity class is final, Javassist will not create a proxy and you will get a Pojo even when you only need a proxy reference.
 In this case, you could proxy an interface that this particular entity implements, as illustrated by the following example.
 
 [[entity-proxy-interface-mapping]]
@@ -374,7 +374,7 @@ include::{sourcedir-proxy}/ProxyInterfaceTest.java[tag=entity-proxy-interface-ma
 ====
 
 The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Proxy.html[`@Proxy`]
-annotation is used to specify a custom Proxy implementation for the current annotated entity.
+annotation is used to specify a custom proxy implementation for the current annotated entity.
 
 When loading the `Book` entity proxy, Hibernate is going to proxy the `Identifiable` interface instead as illustrated by the following example:
 
@@ -392,7 +392,7 @@ include::{extrasdir}/entity/entity-proxy-persist-mapping.sql[]
 ----
 ====
 
-As you can see in the associated SQL snippet, Hibernate issues no SQL SELECT query since the Proxy can be
+As you can see in the associated SQL snippet, Hibernate issues no SQL SELECT query since the proxy can be
 constructed without needing to fetch the actual entity Pojo.
 
 [[entity-tuplizer]]

documentation/src/main/asciidoc/userguide/chapters/pc/PersistenceContext.adoc

@@ -121,6 +121,11 @@ include::{sourcedir}/PersistenceContextTest.java[tags=pc-get-reference-native-ex
 The above works on the assumption that the entity is defined to allow lazy loading, generally through use of runtime proxies.
 In both cases an exception will be thrown later if the given entity does not refer to actual database state when the application attempts to use the returned proxy in any way that requires access to its data.
 
+[IMPORTANT]
+====
+Unless the entity class is declared `final`, the proxy extends the entity class. If the entity class is `final`, the Proxy will implement an interface instead. See the <<chapters/domain/entity.adoc#entity-proxy, `@Proxy` mapping>> section for more info.
+====
+
 [[pc-find]]
 === Obtain an entity with its data initialized
 

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

@@ -159,7 +159,7 @@ include::{sourcedir}/SQLTest.java[tags=sql-hibernate-entity-associations-query-m
 ====
 
 This will allow the `Phone#person` to function properly since the `many-to-one` or `one-to-one`
-association is going to use a Proxy that will be initialized when being navigated for the first time.
+association is going to use a proxy that will be initialized when being navigated for the first time.
 
 It is possible to eagerly join the `Phone` and the `Person` entities to avoid the possible extra roundtrip for initializing the `many-to-one` association.
 

documentation/src/test/java/org/hibernate/userguide/proxy/ProxyInterfaceTest.java

@@ -47,11 +47,11 @@ public class ProxyInterfaceTest extends BaseCoreFunctionalTestCase {
 
 			assertTrue(
 				"Loaded entity is not an instance of the proxy interface",
-				Identifiable.class.isInstance( book )
+				book instanceof Identifiable
 			);
 			assertFalse(
 				"Proxy class was not created",
-				Book.class.isInstance( book )
+				book instanceof Book
 			);
 		} );
 		//end::entity-proxy-persist-mapping[]