Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-6082 - Incorporate EntityManager documentation into main dev guide

This commit is contained in:
Steve Ebersole 2011-04-19 08:48:54 -05:00
parent 28a3e38f7a
commit 70d2e3848b
6 changed files with 247 additions and 286 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

219
documentation/src/main/docbook/devguide/en-US/Author_Group.xml
View File

@ -22,8 +22,7 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<authorgroup>
<author>
<firstname>Gavin</firstname>
@ -33,18 +32,18 @@
<firstname>Christian</firstname>
<surname>Bauer</surname>
</author>
<author>
<firstname>Max</firstname>
<othername>Rydahl</othername>
<surname>Andersen</surname>
<author>
<firstname>Steve</firstname>
<surname>Ebersole</surname>
</author>
<author>
<firstname>Max</firstname>
<othername>Rydahl</othername>
<surname>Andersen</surname>
</author>
<author>
<firstname>Emmanuel</firstname>
<surname>Bernard</surname>
</author>
<author>
<firstname>Steve</firstname>
<surname>Ebersole</surname>
<author>
<firstname>Emmanuel</firstname>
<surname>Bernard</surname>
</author>
<author>
<firstname>Hardy</firstname>
@ -54,6 +53,10 @@
<firstname>Adam</firstname>
<surname>Warski</surname>
</author>
<author>
<firstname>Gail</firstname>
<surname>Badner</surname>
</author>
<othercredit>
<firstname>James</firstname>
@ -70,191 +73,9 @@
</affiliation>
</othercredit>
<!--
#######################################################################
# Spanish
#######################################################################
-->
<othercredit class="translator" lang="es-ES">
<othername><![CDATA[Bernardo Antonio Buffa Colom&#x00e9]]></othername>
<email>kreimer@bbs.frc.utn.edu.ar</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<!--
#######################################################################
# French
#######################################################################
-->
<othercredit class="translator" lang="fr-FR">
<firstname>Vincent</firstname>
<surname>Ricard</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="fr-FR">
<firstname>Sebastien</firstname>
<surname>Cesbron</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="fr-FR">
<firstname>Michael</firstname>
<surname>Courcy</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="fr-FR">
<firstname>Vincent</firstname>
<surname>Giguère</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="fr-FR">
<firstname>Baptiste</firstname>
<surname>Mathus</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="fr-FR">
<firstname>Emmanuel</firstname>
<surname>Bernard</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="fr-FR">
<firstname>Anthony</firstname>
<surname>Patricio</surname>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<!--
#######################################################################
# Portugese
#######################################################################
-->
<othercredit class="translator" lang="pt-BR">
<firstname>Alvaro</firstname>
<surname>Netto</surname>
<email>alvaronetto@cetip.com.br</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Anderson</firstname>
<surname>Braulio</surname>
<email>andersonbraulio@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Daniel Vieira</firstname>
<surname>Costa</surname>
<email>danielvc@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Francisco</firstname>
<surname>gamarra</surname>
<email>francisco.gamarra@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Gamarra</firstname>
<email>mauricio.gamarra@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Luiz Carlos</firstname>
<surname>Rodrigues</surname>
<email>luizcarlos_rodrigues@yahoo.com.br</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Marcel</firstname>
<surname>Castelo</surname>
<email>marcel.castelo@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Paulo</firstname>
<surname>César</surname>
<email>paulocol@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Pablo L.</firstname>
<surname>de Miranda</surname>
<email>pablolmiranda@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Renato</firstname>
<surname>Deggau</surname>
<email>rdeggau@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Rogério</firstname>
<surname>Araújo</surname>
<email>rgildoaraujo@yahoo.com.br</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<othercredit class="translator" lang="pt-BR">
<firstname>Wanderson</firstname>
<surname>Siqueira</surname>
<email>wandersonxs@gmail.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<!--
#######################################################################
# Chinese
#######################################################################
-->
<othercredit class="translator" lang="zh-CN">
<firstname>Cao</firstname>
<surname>Xiaogang</surname>
<affiliation>
<orgname>RedSaga</orgname>
</affiliation>
<contrib>Translation Lead</contrib>
<email>caoxg@yahoo.com</email>
<affiliation>
<shortaffil>Translation</shortaffil>
</affiliation>
</othercredit>
<editor>
<firstname>Misty</firstname>
<surname>Stanley-Jones</surname>
</editor>
</authorgroup>

55
documentation/src/main/docbook/devguide/en-US/Database_Access.xml
View File

@ -4,34 +4,35 @@
%BOOK_ENTITIES;
]>
<chapter>
<title>Database access</title>
<section>
<title>Connection</title>
<para>
Hibernate connects to databases on behalf of your applications. It can connect through a variety of different
mechanisms, including:
</para>
<itemizedlist>
<listitem><para>Stand-alone built-in connection pool</para></listitem>
<listitem><para><classname>javax.sql.DataSource</classname></para></listitem>
<listitem><para>Two different third-party opensource JDBC connection pools:</para>
<itemizedlist>
<listitem><para>c3p0</para></listitem>
<listitem><para>proxool</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<note>
<para>
The built-in connection pool is not intended for production environments.
</para>
</note>
<title>Database access</title>
<section>
<title>Configuring database connections</title>
<para>
You can configure database connections using a properties file, an XML deployment descriptor, programmatically.
<title>Connecting</title>
<para>
Hibernate connects to databases on behalf of your application. It can connect through a variety of mechanisms,
including:
</para>
<itemizedlist>
<listitem><para>Stand-alone built-in connection pool</para></listitem>
<listitem><para><classname>javax.sql.DataSource</classname></para></listitem>
<listitem><para>Two different third-party opensource JDBC connection pools:</para>
<itemizedlist>
<listitem><para>c3p0</para></listitem>
<listitem><para>proxool</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<note>
<para>The built-in connection pool is not intended for production environments.</para>
</note>
<!-- todo : discuss servies -->
<section>
<title>Configuration</title>
<para>
You can configure database connections using a properties file, an XML deployment descriptor, programmatically.
</para>
<example>
<title><filename>hibernate.properties</filename> for a c3p0 connection pool</title>

4
documentation/src/main/docbook/devguide/en-US/Persistence_Context.xml
View File

@ -3,8 +3,8 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "Hibernate_Development_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="devguide-dataOperations">
<title>Working with entities</title>
<chapter>
<title>Persistence Contexts</title>
<para>
Both the <interfacename>org.hibernate.Session</interfacename> API and

253
documentation/src/main/docbook/devguide/en-US/Transactions.xml
View File

@ -4,56 +4,202 @@
%BOOK_ENTITIES;
]>
<chapter>
<title>Transactions and concurrency control</title>
<section>
<title>Defining a transaction</title>
<para>
A transaction, or unit of work, encompasses a group of potential decisions between your application and the datasources it
uses to store information. The role of a transaction is to ensure data integrity by causing the datasources to all
commit, or all roll back, in agreement with each other and your application.
</para>
<para>
An example of when transactions might be useful is a travel agency, which only charges a customer's credit card if
the plane tickets are available and the credit card has adequate funds to pay for the tickets. If the card is
charged, but the tickets are not available, data integrity is not maintained.
</para>
</section>
<section>
<title>How Hibernate uses transactions</title>
<para>
Hibernate uses JDBC connections and JTA resources directly, without adding any additional locking behavior. It is
important for you to become familiar with the JBDC, ANSI, and transaction isolation specification of your database
management system.
</para>
<para>
Hibernate does not lock objects in memory. The behavior defined by the isolation level of your database transactions
does not change when you use Hibernate. Through <classname>Session</classname>, which is also a transaction-scoped
cache, Hibernate provides repeatable reads for lookup by identifier and entity queries and not-reporting queries
that return scalar values.
</para>
</section>
<section>
<title>Transaction Scopes</title>
<para>
A <classname>SessionFactory</classname> is an expensive-to-create, thread-safe object, which all application
threads can share. It is created once, usually on application startup, from a <classname>Configuration</classname>
instance.
</para>
<para>
A <classname>Session</classname> is an inexpensive, non-thread-safe object. Use it once and then discard it. You
can use it for a single request, a conversation, or a single unit of work. A <classname>Session</classname> does
not obtain a JDBC Connection, or a Datasource, unless it is needed. It does not consume any resources until you
use it.
</para>
<para>
To reduce lock contention in the database, a database transaction needs to be as short as possible. Long database
transactions prevent your application from scaling to a highly-concurrent load. Do not hold a database transaction
open during user-level work, but open it after the user-level work is finished.
</para>
<section id="session-per-operation">
<title>Session-per-operation</title>
<subtitle>Antipatterns to avoid</subtitle>
<title>Transactions and concurrency control</title>
<section>
<title>Defining Transaction</title>
<para>
It is important to understand that the term transaction has many related, yet different meanings in relation
to persistence and Object/Relational Mapping. In most use cases these definitions align, but that is not
always the case.
</para>
<itemizedlist>
<listitem>
<para>
It might refer to the physical transaction with the database.
</para>
</listitem>
<listitem>
<para>
It might refer to the logical notion of a transaction as related to a persistence context.
</para>
</listitem>
<listitem>
<para>
It might refer to the application notion of a Unit-of-Work, as defined by the archetypal pattern.
</para>
</listitem>
<note>
<para>
This documentation largely treats the physical and logic notions of transaction as one-in-the-same.
</para>
</note>
</itemizedlist>
</section>
<section>
<title>Physical Transactions</title>
<para>
Hibernate uses the JDBC API for persistence. In the world of Java there are 2 well defined mechanism
for dealing with transactions in JDBC: JDBC, itself, and JTA. Hibernate supports both mechanisms for
integrating with transactions and allowing applications to manage physical transactions.
</para>
<para>
The first concept in understanding Hibernate transaction support is the
<interfacename>org.hibernate.engine.transaction.spi.TransactionFactory</interfacename> interface which
serves 2 main functions:
</para>
<itemizedlist>
<listitem>
<para>
It allows Hibernate to understand the transaction semantics of the environment. Are we operating
in a JTA environment? Is a physical transaction already currently active? etc.
</para>
</listitem>
<listitem>
<para>
It acts as a factory for <interfacename>org.hibernate.Transaction</interfacename> instances which
are used to allow applications to manage and check the state of transactions.
<interfacename>org.hibernate.Transaction</interfacename> is Hibernate's notion of a logical
transaction. JPA has a similar notion in the
<interfacename>javax.persistence.EntityTransaction</interfacename> interface.
</para>
</listitem>
</itemizedlist>
<para>
<interfacename>org.hibernate.engine.transaction.spi.TransactionFactory</interfacename> is a
standard Hibernate service. The default initiator,
<classname>org.hibernate.engine.transaction.internal.TransactionFactoryInitiator</classname>,
looks for a <literal>hibernate.transaction.factory_class</literal> configuration setting to determine
the factory to use.
<!-- todo : see service registry appendix -->
</para>
<section>
<title>Physical Transactions - JDBC</title>
<para>
JDBC-based transaction management leverages the JDBC defined methods
<methodname>java.sql.Connection.commit()</methodname> and
<methodname>java.sql.Connection.rollback()</methodname> (JDBC does not define and explicit
method of beginning a transaction). In Hibernate, this approach is represented by the
<classname>org.hibernate.engine.transaction.internal.jdbc.JdbcTransactionFactory</classname> class.
</para>
</section>
<section>
<title>Physical Transactions - JTA</title>
<para>
JTA-based transaction management leverages the
<interfacename>javax.transaction.TransactionManager</interfacename> interface as obtained from
<interfacename>org.hibernate.service.jta.platform.spi.JtaPlatform</interfacename> API. This approach
is represented by the
<classname>org.hibernate.engine.transaction.internal.jta.JtaTransactionFactory</classname> class.
<!-- todo : see service registry appendix -->
</para>
</section>
<section>
<title>Physical Transactions - CMT</title>
<para>
CMT-based transaction management leverages the
<interfacename>javax.transaction.UserTransaction</interfacename> interface as obtained from
<interfacename>org.hibernate.service.jta.platform.spi.JtaPlatform</interfacename> API. This approach
is represented by the
<classname>org.hibernate.engine.transaction.internal.jta.CMTTransactionFactory</classname> class.
<!-- todo : see service registry appendix -->
</para>
</section>
<section>
<title>Physical Transactions - Custom</title>
<para>
Its is also possible to plug in ones own transaction approach by implementing the
<interfacename>org.hibernate.engine.transaction.spi.TransactionFactory</interfacename> contract.
The default service initiator has built-in support for understanding custom transaction approaches
via the <literal>hibernate.transaction.factory_class</literal> which can name either:
</para>
<itemizedlist>
<listitem>
<para>
The instance of <interfacename>org.hibernate.engine.transaction.spi.TransactionFactory</interfacename>
to use.
</para>
</listitem>
<listitem>
<para>
The name of a class implementing
<interfacename>org.hibernate.engine.transaction.spi.TransactionFactory</interfacename>
to use. The expectation is that the implementation class have a no-argument constructor.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Physical Transactions - Legacy</title>
<para>
During development of 4.0, most of these classes named here were moved to new packages. To help
facilitate upgrading, Hibernate will also recognize the legacy names here for a short period of time.
</para>
<itemizedlist>
<listitem>
<para>
<literal>org.hibernate.transaction.JDBCTransactionFactory</literal> is mapped to
<classname>org.hibernate.engine.transaction.internal.jdbc.JdbcTransactionFactory</classname>
</para>
</listitem>
<listitem>
<para>
<literal>org.hibernate.transaction.JTATransactionFactory</literal> is mapped to
<classname>org.hibernate.engine.transaction.internal.jta.JtaTransactionFactory</classname>
</para>
</listitem>
<listitem>
<para>
<literal>org.hibernate.transaction.CMTTransactionFactory</literal> is mapped to
<classname>org.hibernate.engine.transaction.internal.jta.CMTTransactionFactory</classname>
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Hibernate Transaction Usage</title>
<para>
Hibernate uses JDBC connections and JTA resources directly, without adding any additional locking behavior.
It is important for you to become familiar with the JBDC, ANSI SQL, and transaction isolation specification
of your database management system.
</para>
<para>
Hibernate does not lock objects in memory. The behavior defined by the isolation level of your database
transactions does not change when you use Hibernate. The Hibernate
<interfacename>org.hibernate.Session</interfacename> acts as a transaction-scoped cache providing
repeatable reads for lookup by identifier and entity queries and not-reporting queries that return scalar
values.
</para>
</section>
<sidebar>
<para>
To reduce lock contention in the database, a database transaction needs to be as short as possible. Long
database transactions prevent your application from scaling to a highly-concurrent load. Do not hold a
database transaction open during end-user-level work, but open it after the end-user-level work is finished.
This is concept is referred to as <literal>transactional write-behind</literal>.
</para>
</sidebar>
<section>
<title>Transaction Scopes</title>
<section id="session-per-operation">
<title>Session-per-operation</title>
<subtitle>Antipatterns to avoid</subtitle>
<para>
<firstterm>Session-per-operation</firstterm> refers to the antipattern of opening and closing a
<classname>Session</classname> for each database call in a single thread. It is also an antipattern in terms of
@ -322,13 +468,6 @@
</section>
</section>
<section>
<title>Types</title>
<para>
</para>
</section>
<section id="hibernate-transaction-api">
<title>Hibernate Transaction API (JTA)</title>

2
hibernate-entitymanager/src/main/docbook/en/master.xml
View File

@ -111,7 +111,7 @@
<xi:include href="modules/metamodel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="modules/transactions.xml"
<xi:include href="modules/migrated/transactions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="modules/listeners.xml"

0
hibernate-entitymanager/src/main/docbook/en/modules/transactions.xml → hibernate-entitymanager/src/main/docbook/en/modules/migrated/transactions.xml
View File