From 208e30e25c3f29b7fc2860a473d8e04fd39b3c7e Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Mon, 25 Apr 2005 22:59:25 +0000
Subject: [PATCH] caveat to aggressive connection closing

git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@6511 1b8cb986-b30d-0410-93ca-fae66ebed9b2
---
 reference/en/modules/transactions.xml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/reference/en/modules/transactions.xml b/reference/en/modules/transactions.xml
index 801a506782..d186e69ff6 100644
--- a/reference/en/modules/transactions.xml
+++ b/reference/en/modules/transactions.xml
@@ -512,6 +512,17 @@ Session sess = factory.getCurrentSession();
                 descriptors of your session bean. The lifecycle of the session is completely managed by
                 Hibernate.
             </para>
+            
+            <para>
+                There is one caveat to the use of <literal>auto_close_session</literal>. Due to a limitation 
+                of the JTA spec, it is not possible for Hibernate to automatically clean up any unclosed 
+                <literal>ScrollableResults</literal> or <literal>Iterator</literal> instances returned by 
+                <literal>scroll()</literal> or <literal>iterate()</literal>. You <emphasis>must</emphasis>
+                release the underlying database cursor by calling <literal>ScrollableResults.close()</literal>
+                or <literal>Hibernate.close(Iterator)</literal> explicity from a <literal>finally</literal> 
+                block. (Of course, most applications can easily avoid using <literal>scroll()</literal> or 
+                <literal>iterate()</literal> at all from the CMT code.)
+            </para>
 
         </sect2>