[hibernate-commits] Hibernate SVN: r10495 - branches/Branch_3_2/Hibernate3/doc/reference/en/modules trunk/Hibernate3/doc/reference/en/modules
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Sep 20 02:59:14 EDT 2006
Author: christian.bauer at jboss.com
Date: 2006-09-20 02:59:09 -0400 (Wed, 20 Sep 2006)
New Revision: 10495
Modified:
branches/Branch_3_2/Hibernate3/doc/reference/en/modules/tutorial.xml
trunk/Hibernate3/doc/reference/en/modules/tutorial.xml
Log:
Added warnings about session-per-operation anti-pattern
Modified: branches/Branch_3_2/Hibernate3/doc/reference/en/modules/tutorial.xml
===================================================================
--- branches/Branch_3_2/Hibernate3/doc/reference/en/modules/tutorial.xml 2006-09-19 16:59:36 UTC (rev 10494)
+++ branches/Branch_3_2/Hibernate3/doc/reference/en/modules/tutorial.xml 2006-09-20 06:59:09 UTC (rev 10495)
@@ -588,7 +588,7 @@
</sect2>
- <sect2 id="tutorial-firstapp-workingpersistence" revision="4">
+ <sect2 id="tutorial-firstapp-workingpersistence" revision="5">
<title>Loading and storing objects</title>
<para>
@@ -652,19 +652,35 @@
as many times and anywhere you like, once you get hold of your <literal>SessionFactory</literal>
(easy thanks to <literal>HibernateUtil</literal>). The <literal>getCurrentSession()</literal>
method always returns the "current" unit of work. Remember that we switched the configuration
- option for this mechanism to "thread" in <literal>hibernate.cfg.xml</literal>? Hence, the scope
- of the current unit of work is the current Java thread that executes our application. However, this
- is not the full truth. A <literal>Session</literal> begins when it is
- first needed, when the first call to <literal>getCurrentSession()</literal> is made.
- It is then bound by Hibernate to the current thread. When the transaction ends,
- either committed or rolled back, Hibernate also unbinds the <literal>Session</literal>
- from the thread and closes it for you. If you call <literal>getCurrentSession()</literal>
- again, you get a new <literal>Session</literal> and can start a new unit of work. This
- <emphasis>thread-bound</emphasis> programming model is the most popular way of using
- Hibernate.
+ option for this mechanism to "thread" in <literal>hibernate.cfg.xml</literal>? Hence,
+ the current unit of work is bound to the current Java thread that executes our application.
+ However, this is not the full picture, you also have to consider scope, when a unit of work
+ begins and when it ends.
</para>
<para>
+ A <literal>Session</literal> begins when it is first needed, when the first call to
+ <literal>getCurrentSession()</literal> is made. It is then bound by Hibernate to the current
+ thread. When the transaction ends, either through commit or rollback, Hibernate automatically
+ unbinds the <literal>Session</literal> from the thread and closes it for you. If you call
+ <literal>getCurrentSession()</literal> again, you get a new <literal>Session</literal> and can
+ start a new unit of work. This <emphasis>thread-bound</emphasis> programming model is the most
+ popular way of using Hibernate, as it allows flexible layering of your code (transaction
+ demarcation code can be separated from data access code, we'll do this later in this tutorial).
+ </para>
+
+ <para>
+ Related to the unit of work scope, should the Hibernate <literal>Session</literal> be used to
+ execute one or several database operations? The above example uses one <literal>Session</literal>
+ for one operation. This is pure coincidence, the example is just not complex enough to show any
+ other approach. The scope of a Hibernate <literal>Session</literal> is flexible but you should
+ never design your application to use a new Hibernate <literal>Session</literal> for
+ <emphasis>every</emphasis> database operation. So even if you see it a few more times in
+ the following (very trivial) examples, consider <emphasis>session-per-operation</emphasis>
+ an anti-pattern. A real (web) application is shown later in this tutorial.
+ </para>
+
+ <para>
Have a look at <xref linkend="transactions"/> for more information
about transaction handling and demarcation. We also skipped any error handling and
rollback in the previous example.
@@ -1254,7 +1270,7 @@
database, and it provides an HTML form to enter new events.
</para>
- <sect2 id="tutorial-webapp-servlet" revision="1">
+ <sect2 id="tutorial-webapp-servlet" revision="2">
<title>Writing the basic servlet</title>
<para>
@@ -1311,6 +1327,13 @@
</para>
<para>
+ Do <emphasis>not</emphasis> use a new Hibernate <literal>Session</literal> for
+ every database operation. Use one Hibernate <literal>Session</literal> that is
+ scoped to the whole request. Use <literal>getCurrentSession()</literal>, so that
+ it is automatically bound to the current Java thread.
+ </para>
+
+ <para>
Next, the possible actions of the request are processed and the response HTML
is rendered. We'll get to that part soon.
</para>
Modified: trunk/Hibernate3/doc/reference/en/modules/tutorial.xml
===================================================================
--- trunk/Hibernate3/doc/reference/en/modules/tutorial.xml 2006-09-19 16:59:36 UTC (rev 10494)
+++ trunk/Hibernate3/doc/reference/en/modules/tutorial.xml 2006-09-20 06:59:09 UTC (rev 10495)
@@ -588,7 +588,7 @@
</sect2>
- <sect2 id="tutorial-firstapp-workingpersistence" revision="4">
+ <sect2 id="tutorial-firstapp-workingpersistence" revision="5">
<title>Loading and storing objects</title>
<para>
@@ -652,19 +652,35 @@
as many times and anywhere you like, once you get hold of your <literal>SessionFactory</literal>
(easy thanks to <literal>HibernateUtil</literal>). The <literal>getCurrentSession()</literal>
method always returns the "current" unit of work. Remember that we switched the configuration
- option for this mechanism to "thread" in <literal>hibernate.cfg.xml</literal>? Hence, the scope
- of the current unit of work is the current Java thread that executes our application. However, this
- is not the full truth. A <literal>Session</literal> begins when it is
- first needed, when the first call to <literal>getCurrentSession()</literal> is made.
- It is then bound by Hibernate to the current thread. When the transaction ends,
- either committed or rolled back, Hibernate also unbinds the <literal>Session</literal>
- from the thread and closes it for you. If you call <literal>getCurrentSession()</literal>
- again, you get a new <literal>Session</literal> and can start a new unit of work. This
- <emphasis>thread-bound</emphasis> programming model is the most popular way of using
- Hibernate.
+ option for this mechanism to "thread" in <literal>hibernate.cfg.xml</literal>? Hence,
+ the current unit of work is bound to the current Java thread that executes our application.
+ However, this is not the full picture, you also have to consider scope, when a unit of work
+ begins and when it ends.
</para>
<para>
+ A <literal>Session</literal> begins when it is first needed, when the first call to
+ <literal>getCurrentSession()</literal> is made. It is then bound by Hibernate to the current
+ thread. When the transaction ends, either through commit or rollback, Hibernate automatically
+ unbinds the <literal>Session</literal> from the thread and closes it for you. If you call
+ <literal>getCurrentSession()</literal> again, you get a new <literal>Session</literal> and can
+ start a new unit of work. This <emphasis>thread-bound</emphasis> programming model is the most
+ popular way of using Hibernate, as it allows flexible layering of your code (transaction
+ demarcation code can be separated from data access code, we'll do this later in this tutorial).
+ </para>
+
+ <para>
+ Related to the unit of work scope, should the Hibernate <literal>Session</literal> be used to
+ execute one or several database operations? The above example uses one <literal>Session</literal>
+ for one operation. This is pure coincidence, the example is just not complex enough to show any
+ other approach. The scope of a Hibernate <literal>Session</literal> is flexible but you should
+ never design your application to use a new Hibernate <literal>Session</literal> for
+ <emphasis>every</emphasis> database operation. So even if you see it a few more times in
+ the following (very trivial) examples, consider <emphasis>session-per-operation</emphasis>
+ an anti-pattern. A real (web) application is shown later in this tutorial.
+ </para>
+
+ <para>
Have a look at <xref linkend="transactions"/> for more information
about transaction handling and demarcation. We also skipped any error handling and
rollback in the previous example.
@@ -1255,7 +1271,7 @@
database, and it provides an HTML form to enter new events.
</para>
- <sect2 id="tutorial-webapp-servlet" revision="1">
+ <sect2 id="tutorial-webapp-servlet" revision="2">
<title>Writing the basic servlet</title>
<para>
@@ -1312,6 +1328,13 @@
</para>
<para>
+ Do <emphasis>not</emphasis> use a new Hibernate <literal>Session</literal> for
+ every database operation. Use one Hibernate <literal>Session</literal> that is
+ scoped to the whole request. Use <literal>getCurrentSession()</literal>, so that
+ it is automatically bound to the current Java thread.
+ </para>
+
+ <para>
Next, the possible actions of the request are processed and the response HTML
is rendered. We'll get to that part soon.
</para>
More information about the hibernate-commits
mailing list