From 70d2e3848b0c96adfb33e8c1a3accb5dfd79cb59 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Tue, 19 Apr 2011 08:48:54 -0500 Subject: [PATCH] HHH-6082 - Incorporate EntityManager documentation into main dev guide --- .../docbook/devguide/en-US/Author_Group.xml | 219 ++------------- .../devguide/en-US/Database_Access.xml | 55 ++-- .../devguide/en-US/Persistence_Context.xml | 4 +- .../docbook/devguide/en-US/Transactions.xml | 253 ++++++++++++++---- .../src/main/docbook/en/master.xml | 2 +- .../modules/{ => migrated}/transactions.xml | 0 6 files changed, 247 insertions(+), 286 deletions(-) rename hibernate-entitymanager/src/main/docbook/en/modules/{ => migrated}/transactions.xml (100%) diff --git a/documentation/src/main/docbook/devguide/en-US/Author_Group.xml b/documentation/src/main/docbook/devguide/en-US/Author_Group.xml index 3be3262c04..a6f9c2f8a6 100644 --- a/documentation/src/main/docbook/devguide/en-US/Author_Group.xml +++ b/documentation/src/main/docbook/devguide/en-US/Author_Group.xml @@ -22,8 +22,7 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> - + Gavin @@ -33,18 +32,18 @@ Christian Bauer - - Max - Rydahl - Andersen + + Steve + Ebersole + + + Max + Rydahl + Andersen - - Emmanuel - Bernard - - - Steve - Ebersole + + Emmanuel + Bernard Hardy @@ -54,6 +53,10 @@ Adam Warski + + Gail + Badner + James @@ -70,191 +73,9 @@ - - - - kreimer@bbs.frc.utn.edu.ar - - Translation - - - - - - Vincent - Ricard - - Translation - - - - Sebastien - Cesbron - - Translation - - - - Michael - Courcy - - Translation - - - - Vincent - Giguère - - Translation - - - - Baptiste - Mathus - - Translation - - - - Emmanuel - Bernard - - Translation - - - - Anthony - Patricio - - Translation - - - - - - Alvaro - Netto - alvaronetto@cetip.com.br - - Translation - - - - Anderson - Braulio - andersonbraulio@gmail.com - - Translation - - - - Daniel Vieira - Costa - danielvc@gmail.com - - Translation - - - - Francisco - gamarra - francisco.gamarra@gmail.com - - Translation - - - - Gamarra - mauricio.gamarra@gmail.com - - Translation - - - - Luiz Carlos - Rodrigues - luizcarlos_rodrigues@yahoo.com.br - - Translation - - - - Marcel - Castelo - marcel.castelo@gmail.com - - Translation - - - - Paulo - César - paulocol@gmail.com - - Translation - - - - Pablo L. - de Miranda - pablolmiranda@gmail.com - - Translation - - - - Renato - Deggau - rdeggau@gmail.com - - Translation - - - - Rogério - Araújo - rgildoaraujo@yahoo.com.br - - Translation - - - - Wanderson - Siqueira - wandersonxs@gmail.com - - Translation - - - - - - Cao - Xiaogang - - RedSaga - - Translation Lead - caoxg@yahoo.com - - Translation - - + + Misty + Stanley-Jones + diff --git a/documentation/src/main/docbook/devguide/en-US/Database_Access.xml b/documentation/src/main/docbook/devguide/en-US/Database_Access.xml index 6f6b8af0cf..6fe3e3837c 100644 --- a/documentation/src/main/docbook/devguide/en-US/Database_Access.xml +++ b/documentation/src/main/docbook/devguide/en-US/Database_Access.xml @@ -4,34 +4,35 @@ %BOOK_ENTITIES; ]> - Database access - -
- Connection - - Hibernate connects to databases on behalf of your applications. It can connect through a variety of different - mechanisms, including: - - - Stand-alone built-in connection pool - javax.sql.DataSource - Two different third-party opensource JDBC connection pools: - - c3p0 - proxool - - - - - - The built-in connection pool is not intended for production environments. - - - + Database access +
- Configuring database connections - - You can configure database connections using a properties file, an XML deployment descriptor, programmatically. + Connecting + + Hibernate connects to databases on behalf of your application. It can connect through a variety of mechanisms, + including: + + + Stand-alone built-in connection pool + javax.sql.DataSource + Two different third-party opensource JDBC connection pools: + + c3p0 + proxool + + + + + + The built-in connection pool is not intended for production environments. + + + + +
+ Configuration + + You can configure database connections using a properties file, an XML deployment descriptor, programmatically. <filename>hibernate.properties</filename> for a c3p0 connection pool diff --git a/documentation/src/main/docbook/devguide/en-US/Persistence_Context.xml b/documentation/src/main/docbook/devguide/en-US/Persistence_Context.xml index 434bd3bb52..5cbd8185e2 100644 --- a/documentation/src/main/docbook/devguide/en-US/Persistence_Context.xml +++ b/documentation/src/main/docbook/devguide/en-US/Persistence_Context.xml @@ -3,8 +3,8 @@ %BOOK_ENTITIES; ]> - - Working with entities + + Persistence Contexts Both the org.hibernate.Session API and diff --git a/documentation/src/main/docbook/devguide/en-US/Transactions.xml b/documentation/src/main/docbook/devguide/en-US/Transactions.xml index 5e268a1124..2700a60191 100644 --- a/documentation/src/main/docbook/devguide/en-US/Transactions.xml +++ b/documentation/src/main/docbook/devguide/en-US/Transactions.xml @@ -4,56 +4,202 @@ %BOOK_ENTITIES; ]> - Transactions and concurrency control -
- Defining a transaction - - 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. - - - 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. - -
-
- How Hibernate uses transactions - - 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. - - - 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 Session, 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. - -
-
- Transaction Scopes - - A SessionFactory is an expensive-to-create, thread-safe object, which all application - threads can share. It is created once, usually on application startup, from a Configuration - instance. - - - A Session 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 Session does - not obtain a JDBC Connection, or a Datasource, unless it is needed. It does not consume any resources until you - use it. - - - 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. - - -
- Session-per-operation - Antipatterns to avoid + Transactions and concurrency control + +
+ Defining Transaction + + 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. + + + + + It might refer to the physical transaction with the database. + + + + + It might refer to the logical notion of a transaction as related to a persistence context. + + + + + It might refer to the application notion of a Unit-of-Work, as defined by the archetypal pattern. + + + + + This documentation largely treats the physical and logic notions of transaction as one-in-the-same. + + + + +
+ +
+ Physical Transactions + + 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. + + + The first concept in understanding Hibernate transaction support is the + org.hibernate.engine.transaction.spi.TransactionFactory interface which + serves 2 main functions: + + + + + 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. + + + + + It acts as a factory for org.hibernate.Transaction instances which + are used to allow applications to manage and check the state of transactions. + org.hibernate.Transaction is Hibernate's notion of a logical + transaction. JPA has a similar notion in the + javax.persistence.EntityTransaction interface. + + + + + org.hibernate.engine.transaction.spi.TransactionFactory is a + standard Hibernate service. The default initiator, + org.hibernate.engine.transaction.internal.TransactionFactoryInitiator, + looks for a hibernate.transaction.factory_class configuration setting to determine + the factory to use. + + + +
+ Physical Transactions - JDBC + + JDBC-based transaction management leverages the JDBC defined methods + java.sql.Connection.commit() and + java.sql.Connection.rollback() (JDBC does not define and explicit + method of beginning a transaction). In Hibernate, this approach is represented by the + org.hibernate.engine.transaction.internal.jdbc.JdbcTransactionFactory class. + +
+ +
+ Physical Transactions - JTA + + JTA-based transaction management leverages the + javax.transaction.TransactionManager interface as obtained from + org.hibernate.service.jta.platform.spi.JtaPlatform API. This approach + is represented by the + org.hibernate.engine.transaction.internal.jta.JtaTransactionFactory class. + + +
+ + +
+ Physical Transactions - CMT + + CMT-based transaction management leverages the + javax.transaction.UserTransaction interface as obtained from + org.hibernate.service.jta.platform.spi.JtaPlatform API. This approach + is represented by the + org.hibernate.engine.transaction.internal.jta.CMTTransactionFactory class. + + +
+ +
+ Physical Transactions - Custom + + Its is also possible to plug in ones own transaction approach by implementing the + org.hibernate.engine.transaction.spi.TransactionFactory contract. + The default service initiator has built-in support for understanding custom transaction approaches + via the hibernate.transaction.factory_class which can name either: + + + + + The instance of org.hibernate.engine.transaction.spi.TransactionFactory + to use. + + + + + The name of a class implementing + org.hibernate.engine.transaction.spi.TransactionFactory + to use. The expectation is that the implementation class have a no-argument constructor. + + + +
+ +
+ Physical Transactions - Legacy + + 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. + + + + + org.hibernate.transaction.JDBCTransactionFactory is mapped to + org.hibernate.engine.transaction.internal.jdbc.JdbcTransactionFactory + + + + + org.hibernate.transaction.JTATransactionFactory is mapped to + org.hibernate.engine.transaction.internal.jta.JtaTransactionFactory + + + + + org.hibernate.transaction.CMTTransactionFactory is mapped to + org.hibernate.engine.transaction.internal.jta.CMTTransactionFactory + + + +
+ +
+ + +
+ Hibernate Transaction Usage + + 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. + + + 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 + org.hibernate.Session acts as a transaction-scoped cache providing + repeatable reads for lookup by identifier and entity queries and not-reporting queries that return scalar + values. + +
+ + + + 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 transactional write-behind. + + + + +
+ Transaction Scopes + +
+ Session-per-operation + Antipatterns to avoid Session-per-operation refers to the antipattern of opening and closing a Session for each database call in a single thread. It is also an antipattern in terms of @@ -322,13 +468,6 @@
-
- Types - - - -
-
Hibernate Transaction API (JTA) diff --git a/hibernate-entitymanager/src/main/docbook/en/master.xml b/hibernate-entitymanager/src/main/docbook/en/master.xml index a9ac97a6d7..dfe0a054f2 100644 --- a/hibernate-entitymanager/src/main/docbook/en/master.xml +++ b/hibernate-entitymanager/src/main/docbook/en/master.xml @@ -111,7 +111,7 @@ -