openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From awh...@apache.org
Subject svn commit: r434517 [20/23] - in /incubator/openjpa/trunk: openjpa-kernel/src/main/java/org/apache/openjpa/meta/ openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/ openjpa-project/src/doc/manual/
Date Thu, 24 Aug 2006 20:41:14 GMT
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml Thu Aug 24 13:41:12 2006
@@ -1,555 +1,434 @@
-
-    <chapter id="ref_guide_pc">
-      <title>Persistent Classes</title>
-      <indexterm zone="ref_guide_pc">
-        <primary>persistent classes</primary>
-      </indexterm>
-      <para>
-  Persistent class basics are covered in 
-  <xref linkend="jpa_overview_pc"/> of the JPA Overview.  
-  This chapter details the persistent class features OpenJPA offers beyond the 
-  core JPA specification.
-  </para>
-      <section id="ref_guide_pc_pcclasses">
-        <title>Persistent Class List</title>
+<chapter id="ref_guide_pc">
+    <title>
+        Persistent Classes
+    </title>
+    <indexterm zone="ref_guide_pc">
+        <primary>
+            persistent classes
+        </primary>
+    </indexterm>
+    <para>
+Persistent class basics are covered in <xref linkend="jpa_overview_pc"></xref>
+of the JPA Overview. This chapter details the persistent class features OpenJPA
+offers beyond the core JPA specification.
+    </para>
+    <section id="ref_guide_pc_pcclasses">
+        <title>
+            Persistent Class List
+        </title>
         <indexterm zone="ref_guide_pc_pcclasses">
-          <primary>persistent classes</primary>
-          <secondary>list</secondary>
+            <primary>
+                persistent classes
+            </primary>
+            <secondary>
+                list
+            </secondary>
         </indexterm>
         <indexterm zone="ref_guide_pc_pcclasses">
-          <primary>PCClasses</primary>
+            <primary>
+                PCClasses
+            </primary>
         </indexterm>
         <para>
-    Unlike many ORM products, OpenJPA does not need to know about all of your
-    persistent classes at startup.  OpenJPA discovers new persistent classes 
-    automatically as they are loaded into the JVM; in fact you can introduce
-    new persistent classes into running applications under OpenJPA.  However,
-    there are certain situations in which providing OpenJPA with a persistent
-    class list is helpful:
-    </para>
-        <itemizedlist>
-          <listitem>
-            <para>
-        OpenJPA must be able to match entity names in JPQL queries to 
-        persistent classes.  OpenJPA automatically knows the entity names
-        of any persistent classes already loaded into the JVM.  To match
-        entity names to classes that have not been loaded, however,
-        you must supply a persistent class list.
-        </para>
-          </listitem>
-          <listitem>
-            <para>
-        When OpenJPA manipulates classes in a persistent inheritance
-        hierarchy, OpenJPA must be aware of all the classes in the
-        hierarchy.  If some of the classes have not been loaded into the
-        JVM yet, OpenJPA may not know about them, and queries may return
-        incorrect results.
-        </para>
-          </listitem>
-          <listitem>
-            <para>
-        If you configure OpenJPA to create the needed database schema
-        on startup (see <xref linkend="ref_guide_mapping_synch"/>),
-        OpenJPA must know all of your persistent classes up-front.
+Unlike many ORM products, OpenJPA does not need to know about all of your
+persistent classes at startup. OpenJPA discovers new persistent classes
+automatically as they are loaded into the JVM; in fact you can introduce new
+persistent classes into running applications under OpenJPA. However, there are
+certain situations in which providing OpenJPA with a persistent class list is
+helpful:
         </para>
-          </listitem>
+        <itemizedlist>
+            <listitem>
+                <para>
+OpenJPA must be able to match entity names in JPQL queries to persistent
+classes. OpenJPA automatically knows the entity names of any persistent classes
+already loaded into the JVM. To match entity names to classes that have not been
+loaded, however, you must supply a persistent class list.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+When OpenJPA manipulates classes in a persistent inheritance hierarchy, OpenJPA
+must be aware of all the classes in the hierarchy. If some of the classes have
+not been loaded into the JVM yet, OpenJPA may not know about them, and queries
+may return incorrect results.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+If you configure OpenJPA to create the needed database schema on startup (see
+<xref linkend="ref_guide_mapping_synch"></xref> ), OpenJPA must know all of your
+persistent classes up-front.
+                </para>
+            </listitem>
         </itemizedlist>
         <para>
-    When any of these conditions are a factor in your JPA 
-    application, use the <literal>class</literal>, <literal>
-    mapping-file</literal>, and <literal>jar-file</literal> elements of 
-    JPA's standard XML format to list your 
-    persistent classes.  See
-    <xref linkend="jpa_overview_persistence_xml"/> for details.
-    </para>
+When any of these conditions are a factor in your JPA application, use the
+<literal>class</literal>, <literal> mapping-file</literal>, and <literal>
+jar-file</literal> elements of JPA's standard XML format to list your persistent
+classes. See <xref linkend="jpa_overview_persistence_xml"></xref> for details.
+        </para>
         <note>
-          <para>
-      Listing persistent classes (or their metadata or jar files) is an 
-      all-or-nothing endeavor.  If your persistent class list is 
-      non-empty, OpenJPA will assume that any unlisted class is not 
-      persistent.
-      </para>
+            <para>
+Listing persistent classes (or their metadata or jar files) is an all-or-nothing
+endeavor. If your persistent class list is non-empty, OpenJPA will assume that
+any unlisted class is not persistent.
+            </para>
         </note>
-      </section>
-      <section id="ref_guide_pc_enhance">
-        <title>Enhancement</title>
+    </section>
+    <section id="ref_guide_pc_enhance">
+        <title>
+            Enhancement
+        </title>
         <indexterm zone="ref_guide_pc_enhance">
-          <primary>enhancer</primary>
+            <primary>
+                enhancer
+            </primary>
         </indexterm>
         <indexterm>
-          <primary>openjpac</primary>
-          <see>enhancer</see>
+            <primary>
+                openjpac
+            </primary>
+            <see>
+                enhancer
+            </see>
         </indexterm>
         <para>
-    In order to provide optimal runtime performance, flexible lazy loading,
-    and efficient, immediate dirty tracking, OpenJPA uses an <emphasis>
-    enhancer</emphasis>.  An enhancer is a tool that automatically adds 
-    code to your persistent classes after you have written them.
-    The enhancer post-processes the bytecode generated by your Java 
-    compiler, adding the necessary fields and methods to implement the 
-    required persistence features.  This bytecode modification perfectly 
-    preserves the line numbers in stack traces and is compatible with Java 
-    debuggers.
-    <phrase>
-    In fact, the only change to debugging is that the persistent setter 
-    and getter methods of entity classes using property access will be
-    prefixed with <literal>pc</literal> in stack traces and 
-    step-throughs.
-    For example, if your entity has a <methodname>getId</methodname> method
-    for persistent property <literal>id</literal>, and that method throws 
-    an exception, the stack trace will report the exception from method 
-    <methodname>pcgetId</methodname>.  The line numbers, however, will
-    correctly correspond to the <methodname>getId</methodname> method 
-    in your source file.
-    </phrase>
-    </para>
+In order to provide optimal runtime performance, flexible lazy loading, and
+efficient, immediate dirty tracking, OpenJPA uses an <emphasis> enhancer
+</emphasis>. An enhancer is a tool that automatically adds code to your
+persistent classes after you have written them. The enhancer post-processes the
+bytecode generated by your Java compiler, adding the necessary fields and
+methods to implement the required persistence features. This bytecode
+modification perfectly preserves the line numbers in stack traces and is
+compatible with Java debuggers. <phrase> In fact, the only change to debugging
+is that the persistent setter and getter methods of entity classes using
+property access will be prefixed with <literal>pc</literal> in stack traces and
+step-throughs. For example, if your entity has a <methodname>getId</methodname>
+method for persistent property <literal>id</literal>, and that method throws an
+exception, the stack trace will report the exception from method <methodname>
+pcgetId</methodname>. The line numbers, however, will correctly correspond to
+the <methodname>getId</methodname> method in your source file.</phrase>
+        </para>
         <mediaobject>
-          <imageobject>
-<!-- PNG image data, 509 x 133 (see README) -->
-            <imagedata fileref="img/enhancement.png" width="339px"/>
-          </imageobject>
+            <imageobject>
+                <!-- PNG image data, 509 x 133 (see README) -->
+                <imagedata fileref="img/enhancement.png" width="339px">
+                </imagedata>
+            </imageobject>
         </mediaobject>
         <para>
-    The diagram above illustrates the compilation of a persistent class.
-    </para>
+The diagram above illustrates the compilation of a persistent class.
+        </para>
         <para>
-    You can add the OpenJPA enhancer to your build process, 
-    or use Java 1.5's new instrumentation features to transparently enhance
-    persistent classes when they are loaded into the JVM.  The following 
-    sections describe each option.
-    </para>
+You can add the OpenJPA enhancer to your build process, or use Java 1.5's new
+instrumentation features to transparently enhance persistent classes when they
+are loaded into the JVM. The following sections describe each option.
+        </para>
         <section id="ref_guide_pc_enhance_build">
-          <title>Enhancing at Build Time</title>
-          <indexterm zone="ref_guide_pc_enhance_build">
-            <primary>enhancer</primary>
-            <secondary>build time</secondary>
-          </indexterm>
-          <para>
-      The enhancer can be invoked at build time via the
-      included <literal>openjpac</literal> script or via its Java class, 
-      <classname>org.apache.openjpa.enhance.PCEnhancer</classname>.
-      </para>
-          <note>
-            <para>
-        You can also enhance via Ant; see
-        <xref linkend="ref_guide_integration_enhance"/>.
-        </para>
-          </note>
-          <example id="ref_guide_pc_enhance_enhancer">
-            <title>Using the OpenJPA Enhancer</title>
-            <programlisting format="linespecific">
+            <title>
+                Enhancing at Build Time
+            </title>
+            <indexterm zone="ref_guide_pc_enhance_build">
+                <primary>
+                    enhancer
+                </primary>
+                <secondary>
+                    build time
+                </secondary>
+            </indexterm>
+            <para>
+The enhancer can be invoked at build time via the included <literal>openjpac
+</literal> script or via its Java class, <classname>
+org.apache.openjpa.enhance.PCEnhancer</classname>.
+            </para>
+            <note>
+                <para>
+You can also enhance via Ant; see <xref linkend="ref_guide_integration_enhance">
+</xref>.
+                </para>
+            </note>
+            <example id="ref_guide_pc_enhance_enhancer">
+                <title>
+                    Using the OpenJPA Enhancer
+                </title>
+<programlisting>
 openjpac Magazine.java
 </programlisting>
-          </example>
-          <para>
-      The enhancer accepts the standard set of command-line arguments 
-      defined by the configuration framework
-      (see <xref linkend="ref_guide_conf_devtools"/>), along with the
-      following flags:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para><literal>-directory/-d &lt;output directory&gt;</literal>: 
-          Path to the output directory.  If the directory does not 
-          match the enhanced class' package, the package structure 
-          will be created beneath the directory.  By default, the 
-          enhancer overwrites the original <filename>.class</filename>
-          file.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-enforcePropertyRestrictions/-epr &lt;true/t | 
-          false/f&gt;</literal>: Whether to throw an exception when
-          it appears that a property access entity is not obeying the
-          restrictions placed on property access.  Defaults to false.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-addDefaultConstructor/-adc &lt;true/t 
-          | false/f&gt;</literal>: The spec requires that all 
-          persistent classes define a no-arg constructor.  This flag 
-          tells the enhancer whether to add a protected no-arg 
-          constructor to any persistent classes that don't already 
-          have one.  Defaults to <literal>true</literal>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-tmpClassLoader/-tcl &lt;true/t 
-          | false/f&gt;</literal>: Whether to load persistent classes
-          with a temporary class loader.  This allows other code to 
-          then load the enhanced version of the class within the same
-          JVM.  Defaults to <literal>true</literal>.  Try setting 
-          this flag to <literal>false</literal> as a debugging step 
-          if you run into class loading problems when running the 
-          enhancer.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para>
-      Each additional argument to the enhancer must be one of the 
-      following:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para>The full name of a class.</para>
-            </listitem>
-            <listitem>
-              <para>The .java file for a class.</para>
-            </listitem>
-            <listitem>
-              <para>
-          The <filename>.class</filename> file of a class.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para>
-      If you do not supply any arguments to the enhancer, it will run on
-      the classes in your persistent class list (see 
-      <xref linkend="ref_guide_pc_pcclasses"/>).
-      </para>
-          <para>
-      You can run the enhancer over classes that have already been 
-      enhanced, in which case it will not further modify the class.  You 
-      can also run it over classes that are not persistence-capable, in 
-      which case it will treat the class as persistence-aware.  
-      Persistence-aware classes can directly manipulate the persistent 
-      fields of persistence-capable classes.
-      </para>
-          <para>
-      Note that the enhancement process for subclasses introduces 
-      dependencies on the persistent parent class being enhanced.  This 
-      is normally not problematic; however, when running the enhancer 
-      multiple times over a subclass whose parent class is not yet 
-      enhanced, class loading errors can occur.  In the event of a class 
-      load error, simply re-compile and re-enhance the offending classes.
-      </para>
+            </example>
+            <para>
+The enhancer accepts the standard set of command-line arguments defined by the
+configuration framework (see <xref linkend="ref_guide_conf_devtools"></xref> ),
+along with the following flags:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+<literal>-directory/-d &lt;output directory&gt;</literal>: Path to the output
+directory. If the directory does not match the enhanced class' package, the
+package structure will be created beneath the directory. By default, the
+enhancer overwrites the original <filename>.class</filename> file.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-enforcePropertyRestrictions/-epr &lt;true/t | false/f&gt;</literal>:
+Whether to throw an exception when it appears that a property access entity is
+not obeying the restrictions placed on property access. Defaults to false.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-addDefaultConstructor/-adc &lt;true/t | false/f&gt;</literal>: The
+spec requires that all persistent classes define a no-arg constructor. This flag
+tells the enhancer whether to add a protected no-arg constructor to any
+persistent classes that don't already have one. Defaults to <literal>true
+</literal>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-tmpClassLoader/-tcl &lt;true/t | false/f&gt;</literal>: Whether to
+load persistent classes with a temporary class loader. This allows other code to
+then load the enhanced version of the class within the same JVM. Defaults to
+<literal>true</literal>. Try setting this flag to <literal>false</literal> as a
+debugging step if you run into class loading problems when running the enhancer.
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <para>
+Each additional argument to the enhancer must be one of the following:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+The full name of a class.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+The .java file for a class.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+The <filename>.class</filename> file of a class.
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <para>
+If you do not supply any arguments to the enhancer, it will run on the classes
+in your persistent class list (see <xref linkend="ref_guide_pc_pcclasses">
+</xref> ).
+            </para>
+            <para>
+You can run the enhancer over classes that have already been enhanced, in which
+case it will not further modify the class. You can also run it over classes that
+are not persistence-capable, in which case it will treat the class as
+persistence-aware. Persistence-aware classes can directly manipulate the
+persistent fields of persistence-capable classes.
+            </para>
+            <para>
+Note that the enhancement process for subclasses introduces dependencies on the
+persistent parent class being enhanced. This is normally not problematic;
+however, when running the enhancer multiple times over a subclass whose parent
+class is not yet enhanced, class loading errors can occur. In the event of a
+class load error, simply re-compile and re-enhance the offending classes.
+            </para>
         </section>
         <section id="ref_guide_pc_enhance_runtime_container">
-          <title>Enhancing JPA Entities on Deployment</title>
-          <indexterm zone="ref_guide_pc_enhance_runtime_container">
-            <primary>enhancer</primary>
-            <secondary>runtime</secondary>
-            <tertiary>in an EJB container</tertiary>
-          </indexterm>
-          <para>
-      The JEE 5 specification includes hooks to automatically enhance
-      JPA entities when they are deployed into a container.  Thus, if you
-      are using a JEE 5-compliant application server, OpenJPA will enhance
-      your entities automatically at runtime.  Note that if you prefer
-      build-time enhancement, OpenJPA's runtime enhancer will correctly 
-      recognize and skip pre-enhanced classes.
-      </para>
-          <para>
-      If your application server does not support the JEE 5 enhancement
-      hooks, consider using the build-time enhancement described above,
-      or the more general runtime enhancement described in the next 
-      section.
-      </para>
+            <title>
+                Enhancing JPA Entities on Deployment
+            </title>
+            <indexterm zone="ref_guide_pc_enhance_runtime_container">
+                <primary>
+                    enhancer
+                </primary>
+                <secondary>
+                    runtime
+                </secondary>
+                <tertiary>
+                    in an EJB container
+                </tertiary>
+            </indexterm>
+            <para>
+The JEE 5 specification includes hooks to automatically enhance JPA entities
+when they are deployed into a container. Thus, if you are using a JEE
+5-compliant application server, OpenJPA will enhance your entities automatically
+at runtime. Note that if you prefer build-time enhancement, OpenJPA's runtime
+enhancer will correctly recognize and skip pre-enhanced classes.
+            </para>
+            <para>
+If your application server does not support the JEE 5 enhancement hooks,
+consider using the build-time enhancement described above, or the more general
+runtime enhancement described in the next section.
+            </para>
         </section>
         <section id="ref_guide_pc_enhance_runtime">
-          <title>Enhancing at Runtime</title>
-          <indexterm zone="ref_guide_pc_enhance_runtime">
-            <primary>enhancer</primary>
-            <secondary>runtime</secondary>
-            <tertiary>outside a container</tertiary>
-          </indexterm>
-          <para>
-      OpenJPA includes a <emphasis>Java agent</emphasis> for automatically
-      enhancing persistent classes as they are loaded into the JVM.  
-      Java agents are classes that are invoked prior to your application's
-      <methodname>main</methodname> method.  OpenJPA's agent uses JVM 
-      hooks to intercept all class loading to enhance classes that
-      have persistence metadata before the JVM loads them.  
-      </para>
-          <note>
-            <para>
-        Java agents are new to Java 5; 
-        if you are using a previous Java version, you must use OpenJPA's
-        <link linkend="ref_guide_pc_enhance_build">build-time 
-        enhancement</link> option.
-        </para>
-          </note>
-          <para>
-      Searching for metadata for every class loaded by the JVM can slow
-      application initialization.  One way to speed things up is to
-      take advantage of the optional persistent class list described in
-      <xref linkend="ref_guide_pc_pcclasses"/>.  If you declare a 
-      persistent class list, OpenJPA will only search for metadata for
-      classes in that list. 
-      </para>
-          <para>
-      To employ the OpenJPA agent, invoke <literal>java</literal> with the
-      <literal>-javaagent</literal> set to the path to your 
-      <filename>org.apache.openjpa.jar</filename> or 
-      <filename>openjpa-runtime.jar</filename> file.
-      </para>
-          <example id="ref_guide_pc_enhance_runtime_ex">
-            <title>Using the OpenJPA Agent for Runtime Enhancement</title>
-            <programlisting format="linespecific">
+            <title>
+                Enhancing at Runtime
+            </title>
+            <indexterm zone="ref_guide_pc_enhance_runtime">
+                <primary>
+                    enhancer
+                </primary>
+                <secondary>
+                    runtime
+                </secondary>
+                <tertiary>
+                    outside a container
+                </tertiary>
+            </indexterm>
+            <para>
+OpenJPA includes a <emphasis>Java agent</emphasis> for automatically enhancing
+persistent classes as they are loaded into the JVM. Java agents are classes that
+are invoked prior to your application's <methodname>main</methodname> method.
+OpenJPA's agent uses JVM hooks to intercept all class loading to enhance classes
+that have persistence metadata before the JVM loads them.
+            </para>
+            <note>
+                <para>
+Java agents are new to Java 5; if you are using a previous Java version, you
+must use OpenJPA's <link linkend="ref_guide_pc_enhance_build">build-time
+enhancement</link> option.
+                </para>
+            </note>
+            <para>
+Searching for metadata for every class loaded by the JVM can slow application
+initialization. One way to speed things up is to take advantage of the optional
+persistent class list described in <xref linkend="ref_guide_pc_pcclasses">
+</xref>. If you declare a persistent class list, OpenJPA will only search for
+metadata for classes in that list.
+            </para>
+            <para>
+To employ the OpenJPA agent, invoke <literal>java</literal> with the <literal>
+-javaagent</literal> set to the path to your <filename>org.apache.openjpa.jar
+</filename> or <filename>openjpa-runtime.jar</filename> file.
+            </para>
+            <example id="ref_guide_pc_enhance_runtime_ex">
+                <title>
+                    Using the OpenJPA Agent for Runtime Enhancement
+                </title>
+<programlisting>
 java -javaagent:/home/dev/openjpa/lib/org.apache.openjpa.jar com.xyz.Main
 </programlisting>
-          </example>
-          <para>
-      You can pass settings to the agent using OpenJPA's plugin syntax
-      (see <xref linkend="ref_guide_conf_plugins"/>).  The agent accepts
-      the long form of any of the standard configuration options
-      (<xref linkend="ref_guide_conf_devtools"/>).  It also accepts the
-      following options, the first three of which correspond exactly to
-      to the same-named options of the enhancer tool described in 
-      <xref linkend="ref_guide_pc_enhance_build"/>:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para>
-                <literal>addDefaultConstructor</literal>
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                <literal>jdoEnhance</literal>
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                <literal>enforcePropertyRestrictions</literal>
-              </para>
-            </listitem>
-            <listitem>
-              <para><literal>scanDevPath</literal>: Boolean indicating whether
-          to scan the classpath for persistent types if none have
-          been configured.  If you do not specify a persistent types
-          list and do not set this option to true, OpenJPA will check
-          whether each class loaded into the JVM is persistent, and
-          enhance it accordingly.  This may slow down class load times
-          significantly. 
-          </para>
-            </listitem>
-          </itemizedlist>
-          <example id="ref_guide_pc_enhance_runtime_opt_ex">
-            <title>Passing Options to the OpenJPA Agent</title>
-            <programlisting format="linespecific">
+            </example>
+            <para>
+You can pass settings to the agent using OpenJPA's plugin syntax (see
+<xref linkend="ref_guide_conf_plugins"></xref> ). The agent accepts the long
+form of any of the standard configuration options (
+<xref linkend="ref_guide_conf_devtools"></xref> ). It also accepts the following
+options, the first three of which correspond exactly to to the same-named
+options of the enhancer tool described in
+<xref linkend="ref_guide_pc_enhance_build"></xref>:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+<literal>addDefaultConstructor</literal>
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>jdoEnhance</literal>
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>enforcePropertyRestrictions</literal>
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>scanDevPath</literal>: Boolean indicating whether to scan the
+classpath for persistent types if none have been configured. If you do not
+specify a persistent types list and do not set this option to true, OpenJPA will
+check whether each class loaded into the JVM is persistent, and enhance it
+accordingly. This may slow down class load times significantly.
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <example id="ref_guide_pc_enhance_runtime_opt_ex">
+                <title>
+                    Passing Options to the OpenJPA Agent
+                </title>
+<programlisting>
 java -javaagent:/home/dev/openjpa/lib/org.apache.openjpa.jar=jdoEnhance=true,addDefaultConstructor=false com.xyz.Main
 </programlisting>
-          </example>
+            </example>
         </section>
         <section id="ref_guide_pc_enhance_sercompat">
-          <title>Serializing Enhanced Types</title>
-          <indexterm zone="ref_guide_pc_enhance_sercompat">
-            <primary>enhancer</primary>
-            <secondary>serialization</secondary>
-            <tertiary>of enhanced types</tertiary>
-          </indexterm>
-          <indexterm zone="ref_guide_pc_enhance_sercompat">
-            <primary>serialization</primary>
-            <secondary>of enhanced types</secondary>
-          </indexterm>
-          <para>
-      By default, OpenJPA maintains serialization compatibility
-      between the enhanced and unenhanced versions of a class.  This 
-      allows you to serialize instances between a server using OpenJPA and
-      a client that does not have access to enhanced classes or OpenJPA 
-      libraries.  In some cases, however, you can make the persist and 
-      attach processes more robust and efficient by allowing breaks in 
-      serialization compatibility.  See 
-      <xref linkend="ref_guide_detach_graph"/> for details.
-      </para>
+            <title>
+                Serializing Enhanced Types
+            </title>
+            <indexterm zone="ref_guide_pc_enhance_sercompat">
+                <primary>
+                    enhancer
+                </primary>
+                <secondary>
+                    serialization
+                </secondary>
+                <tertiary>
+                    of enhanced types
+                </tertiary>
+            </indexterm>
+            <indexterm zone="ref_guide_pc_enhance_sercompat">
+                <primary>
+                    serialization
+                </primary>
+                <secondary>
+                    of enhanced types
+                </secondary>
+            </indexterm>
+            <para>
+By default, OpenJPA maintains serialization compatibility between the enhanced
+and unenhanced versions of a class. This allows you to serialize instances
+between a server using OpenJPA and a client that does not have access to
+enhanced classes or OpenJPA libraries. In some cases, however, you can make the
+persist and attach processes more robust and efficient by allowing breaks in
+serialization compatibility. See <xref linkend="ref_guide_detach_graph"></xref>
+for details.
+            </para>
         </section>
-      </section>
-<!-- ### proxy
-  <section id="ref_guide_pc_prop">
-    <title>Restrictions on Property Access Types</title>
-    <indexterm zone="ref_guide_pc_prop">
-      <primary>persistent classes</primary>
-      <secondary>property access restrictions</secondary>
-    </indexterm>
-    <indexterm zone="ref_guide_pc_prop">
-      <primary>property access</primary>
-      <secondary>restrictions</secondary>
-    </indexterm>
-    <para>
-    The JPA Overview explains the choice between property and 
-    field access for your entities and embeddable types in 
-    <xref linkend="jpa_overview_meta"/>.  As you saw in the previous 
-    section, OpenJPA uses an <emphasis>enhancer</emphasis> to transparently
-    intercept operations on persistent state in field access classes.  For 
-    property access classes, however, OpenJPA uses a different strategy.  OpenJPA 
-    generates dynamic subclasses of your persistent classes at runtime.  
-    These subclasses override your persistent property "getter" and 
-    "setter" methods to control the loading and dirtying of persistent
-    state.
-    </para>
-    <para>
-    Any time you look up an entity by id, merge an entity, or retrieve an
-    entity by query, OpenJPA returns an instance of the entity's 
-    dynamically-generated subclass.  When you persist new entities, 
-    however, you typically create them with the Java <literal>new</literal>
-    operator, then pass them to 
-    <ulink url="&ejb-javadoc-dir;/javax/persistence/EntityManager.html">
-    <methodname>EntityManager.persist</methodname></ulink>.  Obviously,
-    these entities are not subclassed.  We must therefore consider two
-    categories of restrictions on property access entities: general
-    restrictions that allow your class to be dynamically subclassed by OpenJPA,
-    and special restrictions on non-subclassed instances you have created 
-    with the <literal>new</literal> operator.
-    </para>
-    <section id="ref_guide_pc_prop_sub">
-      <title>General Restrictions</title>
-      <para>
-      <xref linkend="jpa_overview_pc"/> of the JPA Overview
-      covers the restrictions imposed on persistent classes by the
-      JPA specification.  In order for dynamic subclassing
-      to work properly, your property access entities and 
-      embeddable types must obey those restrictions, as well as the
-      following additions:
-      </para>
-      <orderedlist>
-        <listitem>
-          <para>
-          <emphasis role="bold">Use <literal>
-          instanceof</literal>.</emphasis>  Because OpenJPA will return
-          instances of dynamically-generated subclasses, comparisons
-          on <classname>Class</classname> objects may fail.  Use
-          the <literal>instanceof</literal> operator instead when
-          testing for specific persistent types.
-          </para>  
-        </listitem>
-        <listitem>
-          <para>
-          <emphasis role="bold">Define <literal>public</literal>
-          or <literal>protected</literal> methods.</emphasis>
-          OpenJPA's subclass must be able to override your persistent
-          property accessor and mutator methods. 
-          </para>  
-        </listitem>
-        <listitem>
-          <para>
-          <emphasis role="bold">Do not access persistent fields
-          directly.</emphasis>  The OpenJPA runtime relies on getter
-          and setter method invocations to detect state access.  
-          Thus, outside of your getter and setter methods themselves,
-          you should not manipulate persistent fields directly.  This 
-          restriction applies not only to access from outside
-          code, but also to access from within the business methods
-          of your entity class.  All manipulation of persistent
-          state must go through your getter and setter methods.  
-          </para>  
-        </listitem>
-      </orderedlist>
-    </section>
-    <section id="ref_guide_pc_prop_new">
-      <title>Restrictions on New Instances</title>
-      <para>
-      Non-subclassed property access objects do not afford OpenJPA any 
-      opportunities to intercept persistent state manipulation or store
-      additional bookkeeping information in the object itself.  This is
-      not normally problematic, but does limit the use of these
-      objects in an extended persistence context (see
-      <xref linkend="jpa_overview_emfactory_perscontext"/>).  
-      </para>
-      <itemizedlist>
-        <listitem>
-          <para>
-          New instances using OpenJPA's datastore identity feature
-          (see <xref linkend="ref_guide_pc_oid"/> below) that become
-          detached cannot be merged.  OpenJPA has no place to store the
-          datastore identity value in the non-subclassed detached 
-          instance, so the object's identity is lost.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-          New instances without a 
-          <link linkend="jpa_overview_meta_version">version field
-          </link> must use a <link linkend="jpa_overview_meta_id">
-          <literal>generate</literal> strategy</link> other than
-          <literal>GeneratorType.NONE</literal> for at least one
-          primary key field to be merged after being detached.
-          Otherwise, OpenJPA has no criteria with which to differentiate
-          a detached object from a new one.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-          OpenJPA typically detects attempts to read an auto-assigned 
-          field in a new instance.   OpenJPA generates the value or 
-          flushes to the database transparently on access.
-          OpenJPA cannot detect state reads in non-subclassed property 
-          access classes, however.  Thus, 
-          reading an auto-assigned property will return its 
-          Java default value until you flush or commit.
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-          If you continue using a property access object created with
-          <literal>new</literal> in subsequent transactions of an
-          extended persistence context, OpenJPA will not be able to
-          lazy-load its state.  On boundaries where OpenJPA would 
-          normally clear state (such as when entering a non-optimistic
-          transaction), OpenJPA will clear, then immediately re-load
-          all data.  Because OpenJPA cannot detect state manipulation
-          on a non-subclassed instance, this is the only way to ensure
-          that all properties have the correct values should you 
-          access them.
-          </para>
-        </listitem>
-      </itemizedlist>
-      <para>
-      If you find yourself running up against these limitations in 
-      practice, consider using field access, or taking advantage of the
-      <ulink url="&javadoc-dir;/openjpa/persistence/OpenJPAEntityManager.html">
-      <classname>OpenJPAEntityManager</classname></ulink>, OpenJPA's 
-      extended <classname>EntityManager</classname> interface:
-      </para>
-<programlisting>
-public &lt;T> T createInstance (Class&lt;T> cls);
-</programlisting>
-      <para>
-      The <classname>OpenJPAEntityManager</classname>'s
-      <literal>createInstance</literal> method acts as a factory for 
-      entity and embeddable types.
-      When the given class uses property access, it returns a generated
-      subclass instance.  This instance is not subject to the
-      limitations of objects created with <literal>new</literal>.
-      </para>
     </section>
-  </section>
-  -->
-      <section id="ref_guide_pc_oid">
-        <title>Object Identity</title>
+    <section id="ref_guide_pc_oid">
+        <title>
+            Object Identity
+        </title>
         <indexterm zone="ref_guide_pc_oid">
-          <primary>identity</primary>
+            <primary>
+                identity
+            </primary>
         </indexterm>
         <para>
-    The JPA specification requires you to declare one or more
-    identity fields in your persistent classes.  OpenJPA fully supports
-    this form of object identity, called <emphasis>application</emphasis>
-    identity.  OpenJPA, however, also supports <emphasis>datastore</emphasis>
-    identity.  In datastore identity, you do not declare any primary key
-    fields.  OpenJPA manages the identity of your persistent objects for
-    you through a surrogate key in the database. 
-    </para>
-        <para>
-    You can control how your JPA datastore identity value is generated
-    through OpenJPA's 
-    <ulink url="../apidocs/org/apache/openjpa/persistence/DataStoreId.html"><classname>org.apache.openjpa.persistence.DataStoreId</classname></ulink> class
-    annotation.  This annotation has <literal>strategy</literal> and
-    <literal>generator</literal> properties that mirror the same-named
-    properties on the standard <classname>javax.persistence.GeneratedValue
-    </classname> annotation described in 
-    <xref linkend="jpa_overview_meta_id"/> of the JPA Overview.
-    
-    </para>
-        <para>
-    To retrieve the identity value of a datastore identity entity, use the
-    <methodname>OpenJPAEntityManager.getObjectId (Object entity)
-    </methodname> method.  See 
-    <xref linkend="ref_guide_runtime_em"/>
-    for more information on the <classname>OpenJPAEntityManager</classname>.
-    </para>
+The JPA specification requires you to declare one or more identity fields in
+your persistent classes. OpenJPA fully supports this form of object identity,
+called <emphasis>application</emphasis> identity. OpenJPA, however, also
+supports <emphasis>datastore</emphasis> identity. In datastore identity, you do
+not declare any primary key fields. OpenJPA manages the identity of your
+persistent objects for you through a surrogate key in the database.
+        </para>
+        <para>
+You can control how your JPA datastore identity value is generated through
+OpenJPA's
+<ulink url="../apidocs/org/apache/openjpa/persistence/DataStoreId.html">
+<classname>org.apache.openjpa.persistence.DataStoreId</classname></ulink> class
+annotation. This annotation has <literal>strategy</literal> and <literal>
+generator</literal> properties that mirror the same-named properties on the
+standard <classname>javax.persistence.GeneratedValue</classname> annotation
+described in <xref linkend="jpa_overview_meta_id"></xref> of the JPA Overview.
+        </para>
+        <para>
+To retrieve the identity value of a datastore identity entity, use the
+<methodname>OpenJPAEntityManager.getObjectId (Object entity)</methodname>
+method. See <xref linkend="ref_guide_runtime_em"></xref> for more information on
+the <classname>OpenJPAEntityManager</classname>.
+        </para>
         <example id="ref_guide_pc_oid_datastoreentityex">
-          <title>JPA Datastore Identity Metadata</title>
-          <programlisting format="linespecific">
+            <title>
+                JPA Datastore Identity Metadata
+            </title>
+<programlisting>
 import org.apache.openjpa.persistence.*;
 
 @Entity
@@ -561,254 +440,281 @@
 </programlisting>
         </example>
         <section id="ref_guide_pc_oid_datastore">
-          <title>Datastore Identity Objects</title>
-          <indexterm zone="ref_guide_pc_oid">
-            <primary>identity</primary>
-            <secondary>datastore</secondary>
-          </indexterm>
-          <para>
-      Internally, OpenJPA uses the public 
-      <ulink url="../apidocs/org/apache/openjpa/util/Id.html"><classname>org.apache.openjpa.util.Id
-      </classname></ulink> class for datastore identity objects.  When
-      writing OpenJPA plugins, you can manipulate datastore identity objects
-      by casting them to this class.  You can also create your own 
-      <classname>Id</classname> instances and pass them to any internal
-      OpenJPA method that expects an identity object.
-      </para>
-          <para>
-      In JPA, you will never see <classname>Id</classname> instances
-      directly.  Instead, calling <classname>OpenJPAEntityManager.getObjectId
-      </classname> on a datastore identity object will return the
-      <classname>Long</classname> surrogate primary key value for that
-      object.  You can then use this value in calls to 
-      <classname>EntityManager.find</classname> for subsequent lookups
-      of the same record.
-      </para>
+            <title>
+                Datastore Identity Objects
+            </title>
+            <indexterm zone="ref_guide_pc_oid">
+                <primary>
+                    identity
+                </primary>
+                <secondary>
+                    datastore
+                </secondary>
+            </indexterm>
+            <para>
+Internally, OpenJPA uses the public
+<ulink url="../apidocs/org/apache/openjpa/util/Id.html"><classname>
+org.apache.openjpa.util.Id</classname></ulink> class for datastore identity
+objects. When writing OpenJPA plugins, you can manipulate datastore identity
+objects by casting them to this class. You can also create your own <classname>
+Id</classname> instances and pass them to any internal OpenJPA method that
+expects an identity object.
+            </para>
+            <para>
+In JPA, you will never see <classname>Id</classname> instances directly.
+Instead, calling <classname>OpenJPAEntityManager.getObjectId</classname> on a
+datastore identity object will return the <classname>Long</classname> surrogate
+primary key value for that object. You can then use this value in calls to
+<classname>EntityManager.find</classname> for subsequent lookups of the same
+record.
+            </para>
         </section>
         <section id="ref_guide_pc_oid_application">
-          <title>Application Identity Tool</title>
-          <indexterm zone="ref_guide_pc_oid_application">
-            <primary>identity</primary>
-            <secondary>application</secondary>
-            <tertiary>application identity tool</tertiary>
-          </indexterm>
-          <indexterm zone="ref_guide_pc_oid_application">
-            <primary>application identity tool</primary>
-          </indexterm>
-          <para>
-      If you choose to use application identity, you may want to take
-      advantage of OpenJPA <phrase>JPA</phrase>'s application identity tool.
-      The application identity tool generates Java code implementing the
-      identity class for any persistent type using application 
-      identity.  The code satisfies all the requirements the specification
-      places on identity classes.  You can use it as-is, or simply use it
-      as a starting point, editing it to meet your needs.
-      </para>
-          <para>
-      Before you can run the application identity tool on a persistent
-      class, the class must be compiled and must have complete  
-      metadata.  All primary key fields must be marked as such in the
-      metadata.
-      </para>
-          <para>
-      In JPA metadata, do not attempt to specify the 
-      <literal>@IdClass</literal> annotation unless you are using the
-      application identity tool to overwrite an existing identity class.
-      Attempting to set the value of the <literal>@IdClass</literal> to 
-      a non-existent class will prevent your persistent class from 
-      compiling.  Instead, use the <literal>-name</literal> or
-      <literal>-suffix</literal> options described below to tell OpenJPA
-      what name to give your generated identity class.  Once the 
-      application identity tool has generated the class code, you can
-      set the <literal>@IdClass</literal> annotation.
-      </para>
-          <para>
-      The application identity tool can be invoked via the included 
-      <literal>appidtool</literal> shell/bat script or via its Java class,
-      <ulink url="../apidocs/org/apache/openjpa/enhance/ApplicationIdTool"><classname>org.apache.openjpa.enhance.ApplicationIdTool</classname></ulink>.  
-      </para>
-          <note>
-            <para><xref linkend="ref_guide_integration_appidtool"/> describes
-        the application identity tool's Ant task.
-        </para>
-          </note>
-          <example id="ref_guide_pc_appid_appidtool">
-            <title>Using the Application Identity Tool</title>
-            <programlisting format="linespecific">
+            <title>
+                Application Identity Tool
+            </title>
+            <indexterm zone="ref_guide_pc_oid_application">
+                <primary>
+                    identity
+                </primary>
+                <secondary>
+                    application
+                </secondary>
+                <tertiary>
+                    application identity tool
+                </tertiary>
+            </indexterm>
+            <indexterm zone="ref_guide_pc_oid_application">
+                <primary>
+                    application identity tool
+                </primary>
+            </indexterm>
+            <para>
+If you choose to use application identity, you may want to take advantage of
+OpenJPA <phrase>JPA</phrase>'s application identity tool. The application
+identity tool generates Java code implementing the identity class for any
+persistent type using application identity. The code satisfies all the
+requirements the specification places on identity classes. You can use it as-is,
+or simply use it as a starting point, editing it to meet your needs.
+            </para>
+            <para>
+Before you can run the application identity tool on a persistent class, the
+class must be compiled and must have complete metadata. All primary key fields
+must be marked as such in the metadata.
+            </para>
+            <para>
+In JPA metadata, do not attempt to specify the <literal>@IdClass</literal>
+annotation unless you are using the application identity tool to overwrite an
+existing identity class. Attempting to set the value of the <literal>@IdClass
+</literal> to a non-existent class will prevent your persistent class from
+compiling. Instead, use the <literal>-name</literal> or <literal>-suffix
+</literal> options described below to tell OpenJPA what name to give your
+generated identity class. Once the application identity tool has generated the
+class code, you can set the <literal>@IdClass</literal> annotation.
+            </para>
+            <para>
+The application identity tool can be invoked via the included <literal>
+appidtool</literal> shell/bat script or via its Java class,
+<ulink url="../apidocs/org/apache/openjpa/enhance/ApplicationIdTool">
+<classname>org.apache.openjpa.enhance.ApplicationIdTool</classname></ulink>.
+            </para>
+            <note>
+                <para>
+<xref linkend="ref_guide_integration_appidtool"></xref> describes the
+application identity tool's Ant task.
+                </para>
+            </note>
+            <example id="ref_guide_pc_appid_appidtool">
+                <title>
+                    Using the Application Identity Tool
+                </title>
+<programlisting>
 appidtool -s Id Magazine.java
 </programlisting>
-          </example>
-          <para>
-      The application identity tool accepts the standard set of 
-      command-line arguments defined by the configuration framework
-      (see <xref linkend="ref_guide_conf_devtools"/>),
-      including code formatting flags described in
-      <xref linkend="ref_guide_conf_devtools_format"/>.
-      It also accepts the following arguments:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para><literal>-directory/-d &lt;output directory&gt;</literal>: 
-          Path to the output directory.  If the directory does not 
-          match the generated oid class' package, the package 
-          structure will be created beneath the directory.  If not 
-          specified, the tool will first try to find the directory of
-          the <filename>.java</filename> file for the 
-          persistence-capable class, and failing that will use the 
-          current directory.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-ignoreErrors/-i &lt;true/t | false/f&gt;
-          </literal>:  If <literal>false</literal>, an exception will
-          be thrown if the tool is run on any class that does not 
-          use application identity, or is not the base class in the 
-          inheritance hierarchy (recall that subclasses never define 
-          the application identity class; they inherit it from their 
-          persistent superclass).
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-token/-t &lt;token&gt;</literal>: The token
-          to use to separate stringified primary key values in the
-          string form of the object id.  This option is only used
-          if you have multiple primary key fields.  It defaults to
-          "::". 
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-name/-n &lt;id class name&gt;</literal>: The name
-          of the identity class to generate.  If this option is 
-          specified, you must run the tool on exactly one class.
-          If the class metadata already names an object id class,
-          this option is ignored.  If the name is not fully qualified,
-          the persistent class' package is prepended to form the
-          qualified name.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>-suffix/-s &lt;id class suffix&gt;</literal>: A
-          string to suffix each persistent class name with to form
-          the identity class name.  This option is overridden by
-          <literal>-name</literal> or by any object id class specified
-          in metadata.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para>
-      Each additional argument to the tool must be one of the following:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para>The full name of a persistent class.</para>
-            </listitem>
-            <listitem>
-              <para>The .java file for a persistent class.</para>
-            </listitem>
-            <listitem>
-              <para>
-          The <filename>.class</filename> file of a persistent class.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para>
-      If you do not supply any arguments to the tool, it will act on the
-      classes in your persistent classes list (see
-      <xref linkend="ref_guide_pc_pcclasses"/>).
-      </para>
+            </example>
+            <para>
+The application identity tool accepts the standard set of command-line arguments
+defined by the configuration framework (see
+<xref linkend="ref_guide_conf_devtools"></xref> ), including code formatting
+flags described in <xref linkend="ref_guide_conf_devtools_format"></xref>. It
+also accepts the following arguments:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+<literal>-directory/-d &lt;output directory&gt;</literal>: Path to the output
+directory. If the directory does not match the generated oid class' package, the
+package structure will be created beneath the directory. If not specified, the
+tool will first try to find the directory of the <filename>.java</filename> file
+for the persistence-capable class, and failing that will use the current
+directory.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-ignoreErrors/-i &lt;true/t | false/f&gt;</literal>: If <literal>false
+</literal>, an exception will be thrown if the tool is run on any class that
+does not use application identity, or is not the base class in the inheritance
+hierarchy (recall that subclasses never define the application identity class;
+they inherit it from their persistent superclass).
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-token/-t &lt;token&gt;</literal>: The token to use to separate
+stringified primary key values in the string form of the object id. This option
+is only used if you have multiple primary key fields. It defaults to "::".
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-name/-n &lt;id class name&gt;</literal>: The name of the identity
+class to generate. If this option is specified, you must run the tool on exactly
+one class. If the class metadata already names an object id class, this option
+is ignored. If the name is not fully qualified, the persistent class' package is
+prepended to form the qualified name.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>-suffix/-s &lt;id class suffix&gt;</literal>: A string to suffix each
+persistent class name with to form the identity class name. This option is
+overridden by <literal>-name</literal> or by any object id class specified in
+metadata.
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <para>
+Each additional argument to the tool must be one of the following:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+The full name of a persistent class.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+The .java file for a persistent class.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+The <filename>.class</filename> file of a persistent class.
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <para>
+If you do not supply any arguments to the tool, it will act on the classes in
+your persistent classes list (see <xref linkend="ref_guide_pc_pcclasses"></xref>
+).
+            </para>
         </section>
         <section id="ref_guide_pc_oid_pkgen_autoinc">
-          <title>Autoassign / Identity Strategy Caveats</title>
-          <indexterm zone="ref_guide_pc_oid_pkgen_autoinc">
-            <primary>datastore identity</primary>
-            <secondary>autoassign strategy</secondary>
-          </indexterm>
-          <indexterm zone="ref_guide_pc_oid_pkgen_autoinc">
-            <primary>datastore identity</primary>
-            <secondary>autoassign strategy</secondary>
-          </indexterm>
-          <indexterm zone="ref_guide_pc_oid_pkgen_autoinc">
-            <primary>persistent fields</primary>
-            <secondary>autoassign strategy</secondary>
-          </indexterm>
-          <para><xref linkend="jpa_overview_meta_gen"/> explains how to use JPA's
-      <literal>IDENTITY</literal> generation type to automatically assign
-      field values. However, here are some additional caveats you
-      should be aware of when using <literal>IDENTITY</literal> 
-      generation:
-      </para>
-          <orderedlist>
-            <listitem>
-              <para>
-          Your database must support auto-increment / identity
-          columns, or some equivalent (see 
-          <xref linkend="ref_guide_dbsetup_dbsupport_oracle"/> for
-          how to configure a combination of triggers and sequences to
-          fake auto-increment support in Oracle).
-          </para>
-            </listitem>
-            <listitem>
-              <para>
-          Auto-increment / identity columns must be an integer or 
-          long integer type.
-          </para>
-            </listitem>
-            <listitem>
-              <para>
-          Databases support auto-increment / identity columns
-          to varying degrees.  Some do not support them at all.
-          Others only allow a single such column per
-          table, and require that it be the primary key column.
-          More lenient databases may allow non-primary key 
-          auto-increment columns, and may allow more than one
-          per table.  See your database documentation for 
-          details.
-          </para>
-            </listitem>
-            <listitem>
-              <para>
-          Statements inserting into tables with auto-increment 
-          / identity columns cannot be batched.  After each insert, 
-          OpenJPA must go back to the database to retrieve the last 
-          inserted auto-increment value to set back in the
-          persistent object.  This can have a negative
-          impact on performance.
-          </para>
-            </listitem>
-          </orderedlist>
+            <title>
+                Autoassign / Identity Strategy Caveats
+            </title>
+            <indexterm zone="ref_guide_pc_oid_pkgen_autoinc">
+                <primary>
+                    datastore identity
+                </primary>
+                <secondary>
+                    autoassign strategy
+                </secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_pc_oid_pkgen_autoinc">
+                <primary>
+                    datastore identity
+                </primary>
+                <secondary>
+                    autoassign strategy
+                </secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_pc_oid_pkgen_autoinc">
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    autoassign strategy
+                </secondary>
+            </indexterm>
+            <para>
+<xref linkend="jpa_overview_meta_gen"></xref> explains how to use JPA's
+<literal>IDENTITY</literal> generation type to automatically assign field
+values. However, here are some additional caveats you should be aware of when
+using <literal>IDENTITY</literal> generation:
+            </para>
+            <orderedlist>
+                <listitem>
+                    <para>
+Your database must support auto-increment / identity columns, or some equivalent
+(see <xref linkend="ref_guide_dbsetup_dbsupport_oracle"></xref> for how to
+configure a combination of triggers and sequences to fake auto-increment support
+in Oracle).
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+Auto-increment / identity columns must be an integer or long integer type.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+Databases support auto-increment / identity columns to varying degrees. Some do
+not support them at all. Others only allow a single such column per table, and
+require that it be the primary key column. More lenient databases may allow
+non-primary key auto-increment columns, and may allow more than one per table.
+See your database documentation for details.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+Statements inserting into tables with auto-increment / identity columns cannot
+be batched. After each insert, OpenJPA must go back to the database to retrieve
+the last inserted auto-increment value to set back in the persistent object.
+This can have a negative impact on performance.
+                    </para>
+                </listitem>
+            </orderedlist>
         </section>
-      </section>
-      <section id="ref_guide_inverses">
-        <title>Managed Inverses</title>
+    </section>
+    <section id="ref_guide_inverses">
+        <title>
+            Managed Inverses
+        </title>
         <indexterm zone="ref_guide_inverses">
-          <primary>bidirectional relations</primary>
-          <secondary>automatic management</secondary>
+            <primary>
+                bidirectional relations
+            </primary>
+            <secondary>
+                automatic management
+            </secondary>
         </indexterm>
         <para>
-    Bidirectional relations are an essential part of data modeling.
-    <xref linkend="jpa_overview_mapping"/> in the JPA Overview
-    explains how to use the <literal>mappedBy</literal> annotation attribute
-    to form bidirectional relations that also share datastore storage 
-    in JPA.  
-    </para>
+Bidirectional relations are an essential part of data modeling.
+<xref linkend="jpa_overview_mapping"></xref> in the JPA Overview explains how to
+use the <literal>mappedBy</literal> annotation attribute to form bidirectional
+relations that also share datastore storage in JPA.
+        </para>
         <para>
-    OpenJPA also allows you to define purely logical bidirectional
-    relations.
-    <phrase>
-    The <ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html"><classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink>
-    annotation names a logical inverse in JPA metadata.
-    </phrase>
-    
-    </para>
+OpenJPA also allows you to define purely logical bidirectional relations.
+<phrase> The
+<ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html">
+<classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink>
+annotation names a logical inverse in JPA metadata.</phrase>
+        </para>
         <example id="ref_guide_inverses_logicalex">
-          <title>Specifying Logical Inverses</title>
-          <para><literal>Magazine.coverPhoto</literal> and <literal>Photograph.mag
-      </literal> are each mapped to different foreign keys in their 
-      respective tables, but form a logical bidirectional relation.  Only
-      one of the fields needs to declare the other as its logical inverse,
-      though it is not an error to set the logical inverse of both fields.
-      </para>
-          <programlisting format="linespecific">
+            <title>
+                Specifying Logical Inverses
+            </title>
+            <para>
+<literal>Magazine.coverPhoto</literal> and <literal>Photograph.mag</literal> are
+each mapped to different foreign keys in their respective tables, but form a
+logical bidirectional relation. Only one of the fields needs to declare the
+other as its logical inverse, though it is not an error to set the logical
+inverse of both fields.
+            </para>
+<programlisting>
 import org.apache.openjpa.persistence.*;
 
 @Entity
@@ -830,7 +736,7 @@
     ...
 }
 </programlisting>
-          <programlisting format="linespecific">
+<programlisting>
 &lt;class name="Magazine"&gt;
     &lt;field name="coverPhoto"/&gt;
     ...
@@ -844,111 +750,135 @@
 </programlisting>
         </example>
         <para>
-    Java does not provide any native facilities to ensure that both sides 
-    of a bidirectional relation remain consistent.  
-    Whenever you set one side of the relation, you must manually set the 
-    other side as well. 
-    </para>
+Java does not provide any native facilities to ensure that both sides of a
+bidirectional relation remain consistent. Whenever you set one side of the
+relation, you must manually set the other side as well.
+        </para>
         <para>
-    By default, OpenJPA behaves the same way.  OpenJPA does not automatically 
-    propagate changes from one field in bidirectional relation to the other 
-    field.  This is in keeping with the philosophy of transparency, and 
-    also provides higher performance, as OpenJPA does not need to analyze 
-    your object graph to correct inconsistent relations.
-    </para>
-        <para><indexterm><primary>InverseManager</primary></indexterm>
-    If convenience is more important to you than strict transparency, 
-    however, you can enable inverse relation management in OpenJPA.
-    Set the <link linkend="openjpa.InverseManager"><classname>openjpa.InverseManager</classname></link> plugin property to 
-    <literal>true</literal> for standard management.  Under this setting,
-    OpenJPA detects changes to either side of a bidirectional relation (logical
-    or physical), and automatically sets the other side appropriately on 
-    flush.
-    </para>
+By default, OpenJPA behaves the same way. OpenJPA does not automatically
+propagate changes from one field in bidirectional relation to the other field.
+This is in keeping with the philosophy of transparency, and also provides higher
+performance, as OpenJPA does not need to analyze your object graph to correct
+inconsistent relations.
+        </para>
+        <para>
+        <indexterm>
+            <primary>
+                InverseManager
+            </primary>
+        </indexterm>
+If convenience is more important to you than strict transparency, however, you
+can enable inverse relation management in OpenJPA. Set the
+<link linkend="openjpa.InverseManager"><classname>openjpa.InverseManager
+</classname></link> plugin property to <literal>true</literal> for standard
+management. Under this setting, OpenJPA detects changes to either side of a
+bidirectional relation (logical or physical), and automatically sets the other
+side appropriately on flush.
+        </para>
         <example id="ref_guide_inversesex">
-          <title>Enabling Managed Inverses</title>
-          <programlisting format="linespecific">
+            <title>
+                Enabling Managed Inverses
+            </title>
+<programlisting>
 &lt;property name="openjpa.InverseManager" value="true"/&gt;
 </programlisting>
         </example>
         <para>
-    The inverse manager has options to log a warning or throw an exception 
-    when it detects an inconsistent bidirectional relation, rather than
-    correcting it.  To use these modes, set the manager's <literal>Action
-    </literal> property to <literal>warn</literal> or 
-    <literal>exception</literal>, respectively.
-    </para>
+The inverse manager has options to log a warning or throw an exception when it
+detects an inconsistent bidirectional relation, rather than correcting it. To
+use these modes, set the manager's <literal>Action</literal> property to
+<literal>warn</literal> or <literal>exception</literal>, respectively.
+        </para>
         <para>
-    By default, OpenJPA excludes <link linkend="ref_guide_pc_scos_proxy_lrs">
-    large result set fields</link> from management.  You can force
-    large result set fields to be included by setting the
-    <literal>ManageLRS</literal> plugin property to <literal>true</literal>.
-    </para>
+By default, OpenJPA excludes <link linkend="ref_guide_pc_scos_proxy_lrs"> large
+result set fields</link> from management. You can force large result set fields
+to be included by setting the <literal>ManageLRS</literal> plugin property to
+<literal>true</literal>.
+        </para>
         <example id="ref_guide_inverses_logex">
-          <title>Log Inconsistencies</title>
-          <programlisting format="linespecific">
+            <title>
+                Log Inconsistencies
+            </title>
+<programlisting>
 &lt;property name="openjpa.InverseManager" value="true(Action=warn)"/&gt;
 </programlisting>
         </example>
-      </section>
-      <section id="ref_guide_pc_scos">
-        <title>Persistent Fields</title>
+    </section>
+    <section id="ref_guide_pc_scos">
+        <title>
+            Persistent Fields
+        </title>
         <indexterm zone="ref_guide_pc_scos">
-          <primary>persistent fields</primary>
+            <primary>
+                persistent fields
+            </primary>
         </indexterm>
         <para>
-    OpenJPA enhances the specification's support for persistent 
-    fields in many ways.  This section documents aspects of OpenJPA's 
-    persistent field handling that may affect the way you design your 
-    persistent classes.  
-    </para>
+OpenJPA enhances the specification's support for persistent fields in many ways.
+This section documents aspects of OpenJPA's persistent field handling that may
+affect the way you design your persistent classes.
+        </para>
         <section id="ref_guide_pc_scos_restore">
-          <title>Restoring State</title>
-          <indexterm zone="ref_guide_pc_scos">
-            <primary>persistent fields</primary>
-            <secondary>field rollback</secondary>
-          </indexterm>
-          <indexterm zone="ref_guide_pc_scos_restore">
-            <primary>RestoreState</primary>
-          </indexterm>
-          <para>
-      While the JPA specification says that you should not use rolled 
-      back objects, such objects are perfectly valid in OpenJPA.  You can
-      control whether the objects' managed state is rolled back to its
-      pre-transaction values with the <link linkend="openjpa.RestoreState"><literal>openjpa.RestoreState</literal></link> configuration property.
-      <literal>none</literal> does not roll back state (the object
-      becomes hollow, and will re-load its state the next time it
-      is accessed), <literal>immutable</literal> restores immutable values
-      (primitives, primitive wrappers, strings) and clears mutable values
-      so that they are reloaded on next access, and <literal>all</literal>
-      restores all managed values to their pre-transaction state.
-      </para>
+            <title>
+                Restoring State
+            </title>
+            <indexterm zone="ref_guide_pc_scos">
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    field rollback
+                </secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_pc_scos_restore">
+                <primary>
+                    RestoreState
+                </primary>
+            </indexterm>
+            <para>
+While the JPA specification says that you should not use rolled back objects,
+such objects are perfectly valid in OpenJPA. You can control whether the
+objects' managed state is rolled back to its pre-transaction values with the
+<link linkend="openjpa.RestoreState"><literal>openjpa.RestoreState</literal>
+</link> configuration property. <literal>none</literal> does not roll back state
+(the object becomes hollow, and will re-load its state the next time it is
+accessed), <literal>immutable</literal> restores immutable values (primitives,
+primitive wrappers, strings) and clears mutable values so that they are reloaded
+on next access, and <literal>all</literal> restores all managed values to their
+pre-transaction state.
+            </para>
         </section>
         <section id="ref_guide_pc_scos_order">
-          <title>Typing and Ordering</title>
-          <indexterm zone="ref_guide_pc_scos_order">
-            <primary>persistent fields</primary>
-            <secondary>comparators</secondary>
-          </indexterm>
-          <para>
-      When loading data into a field, OpenJPA examines the value you assign 
-      the field in your declaration code or in your no-args constructor.
-      If the field value's type is more specific than the field's 
-      declared type, OpenJPA uses the value type to hold the loaded data.  
-      OpenJPA also uses the comparator you've initialized the field with, if
-      any.  Therefore, you can use custom comparators on your persistent 
-      field simply by setting up the comparator and using it in your 
-      field's initial value.
-      </para>
-          <example id="ref_guide_pc_scos_order_initialvals">
-            <title>Using Initial Field Values</title>
-            <para>
-        Though the annotations are left out for simplicity, assume
-        <literal>employeesBySal</literal> and 
-        <literal>departments</literal> are persistent fields in the
-        class below.
-        </para>
-            <programlisting format="linespecific">
+            <title>
+                Typing and Ordering
+            </title>
+            <indexterm zone="ref_guide_pc_scos_order">
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    comparators
+                </secondary>
+            </indexterm>
+            <para>
+When loading data into a field, OpenJPA examines the value you assign the field
+in your declaration code or in your no-args constructor. If the field value's
+type is more specific than the field's declared type, OpenJPA uses the value
+type to hold the loaded data. OpenJPA also uses the comparator you've
+initialized the field with, if any. Therefore, you can use custom comparators on
+your persistent field simply by setting up the comparator and using it in your
+field's initial value.
+            </para>
+            <example id="ref_guide_pc_scos_order_initialvals">
+                <title>
+                    Using Initial Field Values
+                </title>
+                <para>
+Though the annotations are left out for simplicity, assume <literal>
+employeesBySal</literal> and <literal>departments</literal> are persistent
+fields in the class below.
+                </para>
+<programlisting>
 public class Company
 {
     // OpenJPA will detect the custom comparator in the initial field value
@@ -967,123 +897,144 @@
     // rest of class definition...
 }
 </programlisting>
-          </example>
+            </example>
         </section>
         <section id="ref_guide_pc_calendar_timezone">
-          <title>Calendar Fields and TimeZones</title>
-          <indexterm zone="ref_guide_pc_calendar_timezone">
-            <primary>persistent fields</primary>
-            <secondary>calendar</secondary>
-          </indexterm>
-          <para>
-      OpenJPA's support for the <classname>java.util.Calendar</classname>
-      type will store only the <classname>Date</classname> part of the 
-      field, not the <classname>TimeZone</classname> associated with the
-      field. When loading the date into the <classname>Calendar
-      </classname> field, OpenJPA will use the <classname>TimeZone
-      </classname> that was used to initialize the field.
-      </para>
-          <note>
-            <para>
-        OpenJPA will automatically track changes made via modification
-        methods in fields of type
-        <classname>Calendar</classname>, with one exception:
-        when using Java version 1.3, the <methodname>set()</methodname>
-        method cannot be overridden, so when altering the calendar
-        using that method, the field must be explicitly marked
-        as dirty. This limitation does not apply when running with
-        Java version 1.4 and higer.
-        </para>
-          </note>
+            <title>
+                Calendar Fields and TimeZones
+            </title>
+            <indexterm zone="ref_guide_pc_calendar_timezone">
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    calendar
+                </secondary>
+            </indexterm>
+            <para>
+OpenJPA's support for the <classname>java.util.Calendar</classname> type will
+store only the <classname>Date</classname> part of the field, not the
+<classname>TimeZone</classname> associated with the field. When loading the date
+into the <classname>Calendar</classname> field, OpenJPA will use the <classname>
+TimeZone</classname> that was used to initialize the field.
+            </para>
+            <note>
+                <para>
+OpenJPA will automatically track changes made via modification methods in fields
+of type <classname>Calendar</classname>, with one exception: when using Java
+version 1.3, the <methodname>set()</methodname> method cannot be overridden, so
+when altering the calendar using that method, the field must be explicitly
+marked as dirty. This limitation does not apply when running with Java version
+1.4 and higer.
+                </para>
+            </note>
         </section>
         <section id="ref_guide_pc_scos_proxy">
-          <title>Proxies</title>
-          <indexterm zone="ref_guide_pc_scos_proxy">
-            <primary>proxies</primary>
-          </indexterm>
-          <indexterm>
-            <primary>persistent fields</primary>
-            <secondary>proxies</secondary>
-            <see>proxies</see>
-          </indexterm>
-          <para>
-      At runtime, the values of all mutable second class object fields 
-      in persistent and transactional objects are replaced with 
-      implementation-specific proxies.  On modification, these proxies 
-      notify their owning instance that they have been changed, so that 
-      the appropriate updates can be made on the datastore.
-      </para>
-          <section id="ref_guide_pc_scos_proxy_smart">
-            <title>Smart Proxies</title>
-            <indexterm zone="ref_guide_pc_scos_proxy_smart">
-              <primary>proxies</primary>
-              <secondary>smart</secondary>
-            </indexterm>
-            <para>
-        Most proxies only track whether or not they have been modified. 
-        Smart proxies for collection and map fields, however, keep a 
-        record of which elements have been added, removed, and changed.
-        This record enables the OpenJPA runtime to make more efficient
-        database updates on these fields. 
-        </para>
-            <para>
-        When designing your persistent classes, keep in mind that 
-        you can optimize for OpenJPA smart proxies by using fields of type 
-        <classname>java.util.Set</classname>, 
-        <classname>java.util.TreeSet</classname>, and 
-        <classname>java.util.HashSet</classname> for your collections 
-        whenever possible.  Smart proxies for these types are more 
-        efficient than proxies for <classname>List</classname>s.  You 
-        can also design your own smart proxies to further optimize OpenJPA
-        for your usage patterns.  See the section on 
-        <link linkend="ref_guide_pc_scos_proxy_custom">custom proxies
-        </link> for details.  
-        </para>
-          </section>
-          <section id="ref_guide_pc_scos_proxy_lrs">
-            <title>Large Result Set Proxies</title>
-            <indexterm zone="ref_guide_pc_scos_proxy_lrs">
-              <primary>proxies</primary>
-              <secondary>large result set</secondary>
-            </indexterm>
-            <indexterm zone="ref_guide_pc_scos_proxy_lrs">
-              <primary>large result sets</primary>
-              <secondary>fields</secondary>
-            </indexterm>
-            <para>
-        Under standard ORM behavior, traversing a persistent collection
-        or map field brings the entire contents of that field into
-        memory.  Some persistent fields, however, might represent
-        huge amounts of data, to the point that attempting to fully
-        instantiate them can overwhelm the JVM or seriously degrade
-        performance.
-        </para>
-            <para>
-        OpenJPA uses special proxy types to represent these "large result
-        set" fields.  OpenJPA's large result set proxies do not cache
-        any data in memory.  Instead, each operation on the proxy 
-        offloads the work to the database and returns the proper result.
-        For example, the <methodname>contains</methodname> method
-        of a large result set collection will perform a <literal>
-        SELECT COUNT(*)</literal> query with the proper <literal>WHERE
-        </literal> conditions to find out if the given element exists 
-        in the database's
-        record of the collection.  Similarly, each time you obtain
-        an iterator OpenJPA performs the proper query using the current
-        <link linkend="ref_guide_dbsetup_lrs">
-        large result set settings</link>, as discussed in the 
-        <link linkend="ref_guide_dbsetup">JDBC</link> chapter.  As you 
-        invoke <methodname>Iterator.next</methodname>, OpenJPA 
-        instantiates the result objects on-demand.
-        </para>
-            <para>
-        You can free the resources used by a large result set iterator 
-        by passing it to the static 
-        <link linkend="ref_guide_runtime_openjpapersistence"><methodname>OpenJPAPersistence.close</methodname></link> method. 
-        </para>
-            <example id="ref_guide_pc_scos_proxy_lrs_itr">
-              <title>Using a Large Result Set Iterator</title>
-              <programlisting format="linespecific">
+            <title>
+                Proxies
+            </title>
+            <indexterm zone="ref_guide_pc_scos_proxy">
+                <primary>
+                    proxies
+                </primary>
+            </indexterm>
+            <indexterm>
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    proxies
+                </secondary>
+                <see>
+                    proxies
+                </see>
+            </indexterm>
+            <para>
+At runtime, the values of all mutable second class object fields in persistent
+and transactional objects are replaced with implementation-specific proxies. On
+modification, these proxies notify their owning instance that they have been
+changed, so that the appropriate updates can be made on the datastore.
+            </para>
+            <section id="ref_guide_pc_scos_proxy_smart">
+                <title>
+                    Smart Proxies
+                </title>
+                <indexterm zone="ref_guide_pc_scos_proxy_smart">
+                    <primary>
+                        proxies
+                    </primary>
+                    <secondary>
+                        smart
+                    </secondary>
+                </indexterm>
+                <para>
+Most proxies only track whether or not they have been modified. Smart proxies
+for collection and map fields, however, keep a record of which elements have
+been added, removed, and changed. This record enables the OpenJPA runtime to
+make more efficient database updates on these fields.
+                </para>
+                <para>
+When designing your persistent classes, keep in mind that you can optimize for
+OpenJPA smart proxies by using fields of type <classname>java.util.Set
+</classname>, <classname>java.util.TreeSet</classname>, and <classname>
+java.util.HashSet</classname> for your collections whenever possible. Smart
+proxies for these types are more efficient than proxies for <classname>List
+</classname> s. You can also design your own smart proxies to further optimize
+OpenJPA for your usage patterns. See the section on
+<link linkend="ref_guide_pc_scos_proxy_custom">custom proxies</link> for
+details.
+                </para>
+            </section>
+            <section id="ref_guide_pc_scos_proxy_lrs">
+                <title>
+                    Large Result Set Proxies
+                </title>
+                <indexterm zone="ref_guide_pc_scos_proxy_lrs">
+                    <primary>
+                        proxies
+                    </primary>
+                    <secondary>
+                        large result set
+                    </secondary>
+                </indexterm>
+                <indexterm zone="ref_guide_pc_scos_proxy_lrs">
+                    <primary>
+                        large result sets
+                    </primary>
+                    <secondary>
+                        fields
+                    </secondary>
+                </indexterm>
+                <para>
+Under standard ORM behavior, traversing a persistent collection or map field
+brings the entire contents of that field into memory. Some persistent fields,
+however, might represent huge amounts of data, to the point that attempting to
+fully instantiate them can overwhelm the JVM or seriously degrade performance.
+                </para>
+                <para>
+OpenJPA uses special proxy types to represent these "large result set" fields.
+OpenJPA's large result set proxies do not cache any data in memory. Instead,
+each operation on the proxy offloads the work to the database and returns the
+proper result. For example, the <methodname>contains</methodname> method of a
+large result set collection will perform a <literal> SELECT COUNT(*)</literal>
+query with the proper <literal>WHERE</literal> conditions to find out if the
+given element exists in the database's record of the collection. Similarly, each
+time you obtain an iterator OpenJPA performs the proper query using the current
+<link linkend="ref_guide_dbsetup_lrs"> large result set settings</link>, as
+discussed in the <link linkend="ref_guide_dbsetup">JDBC</link> chapter. As you
+invoke <methodname>Iterator.next</methodname>, OpenJPA instantiates the result
+objects on-demand.
+                </para>
+                <para>
+You can free the resources used by a large result set iterator by passing it to
+the static <link linkend="ref_guide_runtime_openjpapersistence"><methodname>
+OpenJPAPersistence.close</methodname></link> method.
+                </para>
+                <example id="ref_guide_pc_scos_proxy_lrs_itr">
+                    <title>
+                        Using a Large Result Set Iterator
+                    </title>
+<programlisting>
 import org.apache.openjpa.persistence.*;
 
 ...
@@ -1094,60 +1045,55 @@

[... 2477 lines stripped ...]


Mime
View raw message