HHH-7667 docs

documentation/src/main/docbook/devguide/en-US/appendix-Configuration_Properties.xml

@@ -373,13 +373,6 @@
             created. With <command>create-drop</command>, the database schema is dropped when the
             <classname>SessionFactory</classname> is closed explicitly.</entry>
           </row>
-          <row>          
-            <entry>cglib.use_reflection_optimizer</entry>
-            <entry><para><literal>true</literal> or <literal>false</literal></para></entry>
-            <entry>If enabled, Hibernate uses CGLIB instead of runtime reflection. This is a system-level
-            property. Reflection is useful for troubleshooting. Hibernate always requires CGLIB even if you disable the
-            optimizer. You cannot set this property in hibernate.cfg.xml.</entry>
-          </row>
         </tbody>
       </tgroup>
     </table>

documentation/src/main/docbook/devguide/en-US/chapters/query_native/Native_SQL.xml

@@ -800,7 +800,7 @@ public class SpaceShip {</programlisting>
     <section xml:id="sp_query" >
       <title>Using stored procedures for querying</title>
 
-      <para>Hibernate3 provides support for queries via stored procedures and
+      <para>Hibernate provides support for queries via stored procedures and
       functions. Most of the following documentation is equivalent for both.
       The stored procedure/function must return a resultset as the first
       out-parameter to be able to work with Hibernate. An example of such a
@@ -898,7 +898,7 @@ BEGIN
   <section xml:id="querysql-cud">
     <title>Custom SQL for create, update and delete</title>
 
-    <para>Hibernate3 can use custom SQL for create, update, and delete
+    <para>Hibernate can use custom SQL for create, update, and delete
     operations. The SQL can be overridden at the statement level or
     inidividual column level. This section describes statement overrides. For
     columns, see <xref linkend="mapping-column-read-and-write" />. <xref

documentation/src/main/docbook/manual/en-US/content/basic_mapping.xml

@@ -357,7 +357,7 @@ public class Flight implements Serializable {
       recommended). You can also specify an interface to use for lazy
       initializing proxies (defaults to the class itself): use
       <literal>proxyClass</literal> on <classname>@Proxy</classname>.
-      Hibernate will initially return proxies (Javassist or CGLIB) that
+      Hibernate will initially return proxies ( using bytecode provider defined by <literal>hibernate.bytecode.provider</literal>) that
       implement the named interface. The persistent object will load when a
       method of the proxy is invoked. See "Initializing collections and
       proxies" below.</para>
@@ -580,7 +580,7 @@ public class Summary {
 
           <callout arearefs="class17">
             <para><literal>entity-name</literal> (optional - defaults to the
-            class name): Hibernate3 allows a class to be mapped multiple
+            class name): Hibernate allows a class to be mapped multiple
             times, potentially to different tables. It also allows entity
             mappings that are represented by Maps or XML at the Java level. In
             these cases, you should provide an explicit arbitrary name for the
@@ -723,7 +723,7 @@ public class Person {
       that the class has no identifier property.</para>
 
       <para>The <literal>unsaved-value</literal> attribute is almost never
-      needed in Hibernate3 and indeed has no corresponding element in
+      needed in Hibernate and indeed has no corresponding element in
       annotations.</para>
 
       <para>You can also declare the identifier as a composite identifier.

documentation/src/main/docbook/manual/en-US/content/component_mapping.xml

@@ -272,7 +272,7 @@
 	<note>
 	<title>Note</title>
         <para>
-            In Hibernate3, although the second requirement is not an absolutely hard
+            In Hibernate, although the second requirement is not an absolutely hard
             requirement of Hibernate, it is recommended.
         </para>
 	</note>

documentation/src/main/docbook/manual/en-US/content/configuration.xml

@@ -670,7 +670,7 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
 
             <entry>Optimizes second-level cache operation to minimize writes,
             at the cost of more frequent reads. This setting is most useful
-            for clustered caches and, in Hibernate3, is enabled by default for
+            for clustered caches and, in Hibernate, is enabled by default for
             clustered cache implementations. <para> <emphasis
             role="strong">e.g.</emphasis> <literal>true|false</literal>
             </para></entry>
@@ -911,7 +911,7 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
             runtime reflection. This is a System-level property and cannot be
             set in <literal>hibernate.cfg.xml</literal>. Reflection can
             sometimes be useful when troubleshooting. Hibernate always
-            requires either CGLIB or javassist even if you turn off the
+            requires javassist even if you turn off the
             optimizer.</para><para> <emphasis role="strong">e.g.</emphasis>
             <literal>true</literal> | <literal>false</literal> </para></entry>
           </row>
@@ -919,11 +919,8 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
           <row>
             <entry><literal>hibernate.bytecode.provider</literal></entry>
 
-            <entry><para>Both javassist or cglib can be used as byte
+            <entry><para>At the moment, <literal>javassist</literal> is the only supported bytecode provider.</para><para> <emphasis
-            manipulation engines; the default is
+            role="strong">e.g.</emphasis> <literal>javassist</literal></para></entry>
-            <literal>javassist</literal>.</para><para> <emphasis
-            role="strong">e.g.</emphasis> <literal>javassist</literal> |
-            <literal>cglib</literal> </para></entry>
           </row>
         </tbody>
       </tgroup>

documentation/src/main/docbook/manual/en-US/content/example_parentchild.xml

@@ -256,7 +256,7 @@ session.flush();]]></programlisting>
              database. We will also assume that both <literal>Parent</literal> and <literal>Child</literal> have generated
              identifier properties of type <literal>Long</literal>. Hibernate will use the identifier and 
              version/timestamp property value to determine which of the children are new. (See
-             <xref linkend="objectstate-saveorupdate"/>.) <emphasis>In Hibernate3, it is no longer necessary to specify
+             <xref linkend="objectstate-saveorupdate"/>.) <emphasis>In Hibernate, it is no longer necessary to specify
              an <literal>unsaved-value</literal> explicitly.</emphasis>
          </para>
 

documentation/src/main/docbook/manual/en-US/content/filters.xml

@@ -3,7 +3,7 @@
 <chapter xml:id="filters" xmlns="http://docbook.org/ns/docbook" >
   <title>Filtering data</title>
 
-  <para>Hibernate3 provides an innovative new approach to handling data with
+  <para>Hibernate provides an innovative new approach to handling data with
   "visibility" rules. A <emphasis>Hibernate filter</emphasis> is a global,
   named, parameterized filter that can be enabled or disabled for a particular
   Hibernate session.</para>
@@ -11,7 +11,7 @@
   <section xml:id="objectstate-filters" revision="1">
     <title>Hibernate filters</title>
 
-    <para>Hibernate3 has the ability to pre-define filter criteria and attach
+    <para>Hibernate has the ability to pre-define filter criteria and attach
     those filters at both a class level and a collection level. A filter
     criteria allows you to define a restriction clause similar to the existing
     "where" attribute available on the class and various collection elements.

documentation/src/main/docbook/manual/en-US/content/inheritance_mapping.xml

@@ -61,7 +61,7 @@
              <literal>hibernate-mapping</literal>. This allows you to extend a class hierarchy by adding
              a new mapping file. You must specify an <literal>extends</literal> attribute in the subclass mapping,
              naming a previously mapped superclass. Previously this feature made the ordering of the mapping
-             documents important. Since Hibernate3, the ordering of mapping files is irrelevant when using the
+             documents important. Since Hibernate, the ordering of mapping files is irrelevant when using the
              extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses
              before subclasses.
          </para>

documentation/src/main/docbook/manual/en-US/content/performance.xml

@@ -12,7 +12,7 @@
     over-ridden by a particular HQL or <literal>Criteria</literal>
     query.</para>
 
-    <para>Hibernate3 defines the following fetching strategies:</para>
+    <para>Hibernate defines the following fetching strategies:</para>
 
     <itemizedlist>
       <listitem>
@@ -104,7 +104,7 @@
     <section xml:id="performance-fetching-lazy">
       <title>Working with lazy associations</title>
 
-      <para>By default, Hibernate3 uses lazy select fetching for collections
+      <para>By default, Hibernate uses lazy select fetching for collections
       and lazy proxy fetching for single-valued associations. These defaults
       make sense for most associations in the majority of applications.</para>
 
@@ -144,7 +144,7 @@ Integer accessLevel = (Integer) permissions.get("accounts");  // Error!</program
 
       <para>On the other hand, you can use join fetching, which is non-lazy by
       nature, instead of select fetching in a particular transaction. We will
-      now explain how to customize the fetching strategy. In Hibernate3, the
+      now explain how to customize the fetching strategy. In Hibernate, the
       mechanisms for choosing a fetch strategy are identical for single-valued
       associations and collections.</para>
     </section>
@@ -224,9 +224,9 @@ Integer accessLevel = (Integer) permissions.get("accounts");  // Error!</program
       is needed for lazy behavior in single-ended associations. The target
       entity of the association must be proxied. Hibernate implements lazy
       initializing proxies for persistent objects using runtime bytecode
-      enhancement which is accessed via the CGLIB library.</para>
+      enhancement which is accessed via the bytecode provider.</para>
 
-      <para>At startup, Hibernate3 generates proxies by default for all
+      <para>At startup, Hibernate generates proxies by default for all
       persistent classes and uses them to enable lazy fetching of
       <literal>many-to-one</literal> and <literal>one-to-one</literal>
       associations.</para>
@@ -273,7 +273,7 @@ System.out.println(cat==dc);                            // false</programlisting
       <programlisting role="JAVA">cat.setWeight(11.0);  // hit the db to initialize the proxy
 System.out.println( dc.getWeight() );  // 11.0</programlisting>
 
-      <para>Third, you cannot use a CGLIB proxy for a <literal>final</literal>
+      <para>Third, you cannot use a bytecode provider generated proxy for a <literal>final</literal>
       class or a class with any <literal>final</literal> methods.</para>
 
       <para>Finally, if your persistent object acquires any resources upon
@@ -670,7 +670,7 @@ Customer customer = (Customer) session.get( Customer.class, customerId );
     <section xml:id="performance-fetching-lazyproperties">
       <title>Using lazy property fetching</title>
 
-      <para>Hibernate3 supports the lazy fetching of individual properties.
+      <para>Hibernate supports the lazy fetching of individual properties.
       This optimization technique is also known as <emphasis>fetch
       groups</emphasis>. Please note that this is mostly a marketing feature;
       optimizing row reads is much more important than optimization of column
@@ -1329,7 +1329,52 @@ hibernate.cache.use_structured_entries true</programlisting>
       <literal>org.hibernate.SessionFactory.evictQueries()</literal>.</para>
     </section>
   </section>
+  <section xml:id="bytecode-enhancement" revision="1">
+      <title>Bytecode Enhancement</title>
+      <para>Hibernate internally needs an entry ( <classname>org.hibernate.engine.spi.EntityEntry</classname> ) to tell
+          the current state of an object with respect to its persistent state, when the object is associated with a
+          <classname>Session</classname>. However, maintaining this association was kind of heavy operation due to lots of
+          other rules must by applied, since 4.2.0, there is a new improvement designed for this purpose, which will reduce
+          session-related memory and CPU overloads.
+      </para>
+      <para>Basically, the idea is, instead of having a customized ( kind of heavy and which was usually identified as hotspot )
+          map to do the look up, we change it to </para>
+      <programlisting role="JAVA"><![CDATA[EntityEntry entry = (ManagedEntity)entity.$$_hibernate_getEntityEntry();
+]]></programlisting>
 
+      <para>There are three ways to get benefits from this new improvement:</para>
+
+      <section xml:id="entityentry-lookup-impl-interface">
+         <title>Implementing <classname>org.hibernate.engine.spi.ManagedEntity</classname> interface</title>
+         <para>An entity can choose to implement this interface by itself, then it is the entity's responsibility to maintain
+         the bi-association that essentially provides access to information about an instance's association to a
+         Session/EntityManager.
+         More info about <classname>org.hibernate.engine.spi.ManagedEntity</classname> please find from its javadoc.
+         </para>
+      </section>
+
+      <section xml:id="entityentry-lookup-impl-interface-by-wrapper">
+          <title>Runtime instrument</title>
+          <para>Sometimes, you probably don't want to implement an intrusive interface, maybe due to portable concern,
+          which is fine and Hibernate will take care of this internally with a wrapper class which implements that interface,
+          and also an internal cache that maps this entity instance and the wrapper together.</para>
+
+          <para>Obviously, this is the easiest way to choose, since it doesn't require any change of the project source code,
+          but it also cost more memory and CUP usage, comparing to the first one.</para>
+      </section>
+
+      <section xml:id="entityentry-lookup-buildtime-instrument">
+          <title>Buildtime instrument</title>
+          <para>Besides above two approaches, Hibernate also provides you the third choice, which is an ANT task (
+          <classname>org.hibernate.tool.enhance.EnhancementTask</classname>) that can be used at build time to
+          instrument your entity classes with the required interfaces and methods.
+
+          Meanwhile, the maven and gradle plugin are still under development and will be available soon.
+          </para>
+
+      </section>
+
+  </section>
   <section xml:id="performance-collections">
     <title>Understanding Collection performance</title>
 

documentation/src/main/docbook/manual/en-US/content/query_hql.xml

@@ -768,7 +768,7 @@ where p.name = some elements(list.names)]]></programlisting>
             Note that these constructs - <literal>size</literal>, <literal>elements</literal>,
             <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>,
             <literal>minelement</literal>, <literal>maxelement</literal> - can only be used in
-            the where clause in Hibernate3.
+            the where clause in Hibernate.
         </para>
 
         <para>

documentation/src/main/docbook/manual/en-US/content/query_sql.xml

@@ -9,7 +9,7 @@
   also provides a clean migration path from a direct SQL/JDBC based
   application to Hibernate.</para>
 
-  <para>Hibernate3 allows you to specify handwritten SQL, including stored
+  <para>Hibernate allows you to specify handwritten SQL, including stored
   procedures, for all create, update, delete, and load operations.</para>
 
   <section xml:id="querysql-creating" revision="4">
@@ -800,7 +800,7 @@ public class SpaceShip {</programlisting>
     <section xml:id="sp_query" revision="1">
       <title>Using stored procedures for querying</title>
 
-      <para>Hibernate3 provides support for queries via stored procedures and
+      <para>Hibernate provides support for queries via stored procedures and
       functions. Most of the following documentation is equivalent for both.
       The stored procedure/function must return a resultset as the first
       out-parameter to be able to work with Hibernate. An example of such a
@@ -898,7 +898,7 @@ BEGIN
   <section xml:id="querysql-cud">
     <title>Custom SQL for create, update and delete</title>
 
-    <para>Hibernate3 can use custom SQL for create, update, and delete
+    <para>Hibernate can use custom SQL for create, update, and delete
     operations. The SQL can be overridden at the statement level or
     inidividual column level. This section describes statement overrides. For
     columns, see <xref linkend="mapping-column-read-and-write" />. <xref

documentation/src/main/docbook/manual/en-US/content/tutorial.xml

@@ -100,7 +100,6 @@
             <artifactId>slf4j-simple</artifactId>
         </dependency>
 
-        <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
         <dependency>
             <groupId>javassist</groupId>
             <artifactId>javassist</artifactId>