HHH-7667 docs

This commit is contained in:
Strong Liu 2013-03-16 16:45:58 +08:00
parent 06e3313f23
commit 1b05455d1e
12 changed files with 70 additions and 36 deletions

View File

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

View File

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

View File

@ -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.

View File

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

View File

@ -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
manipulation engines; the default is
<literal>javassist</literal>.</para><para> <emphasis
role="strong">e.g.</emphasis> <literal>javassist</literal> |
<literal>cglib</literal> </para></entry>
<entry><para>At the moment, <literal>javassist</literal> is the only supported bytecode provider.</para><para> <emphasis
role="strong">e.g.</emphasis> <literal>javassist</literal></para></entry>
</row>
</tbody>
</tgroup>

View File

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

View File

@ -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.

View File

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

View File

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

View File

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

View File

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

View File

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