diff --git a/openjpa-jdbc-5/pom.xml b/openjpa-jdbc-5/pom.xml
index 127feccf3..3453871f0 100644
--- a/openjpa-jdbc-5/pom.xml
+++ b/openjpa-jdbc-5/pom.xml
@@ -10,11 +10,9 @@
     <description>JDBC 1.5</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
@@ -22,7 +20,7 @@
 
             <groupId>org.apache.openjpa</groupId>
             <artifactId>openjpa-jdbc</artifactId>
-            <version>0.0.1</version>
+            <version>${pom.version}</version>
             <scope>compile</scope>
 
         </dependency>
diff --git a/openjpa-jdbc/pom.xml b/openjpa-jdbc/pom.xml
index fd25a050b..066c07bd9 100644
--- a/openjpa-jdbc/pom.xml
+++ b/openjpa-jdbc/pom.xml
@@ -10,11 +10,9 @@
     <description>JDBC</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
@@ -22,7 +20,7 @@
 
             <groupId>org.apache.openjpa</groupId>
             <artifactId>openjpa-kernel</artifactId>
-            <version>0.0.1</version>
+            <version>${pom.version}</version>
             <scope>compile</scope>
 
         </dependency>
diff --git a/openjpa-kernel-5/pom.xml b/openjpa-kernel-5/pom.xml
index 99ec5902d..e105ca0fe 100644
--- a/openjpa-kernel-5/pom.xml
+++ b/openjpa-kernel-5/pom.xml
@@ -10,11 +10,9 @@
     <description>Kernel 1.5</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
diff --git a/openjpa-kernel/pom.xml b/openjpa-kernel/pom.xml
index 31df1e426..edbd5bb74 100644
--- a/openjpa-kernel/pom.xml
+++ b/openjpa-kernel/pom.xml
@@ -10,11 +10,9 @@
     <description>Kernel</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
diff --git a/openjpa-lib/pom.xml b/openjpa-lib/pom.xml
index 051d52382..2891b6876 100644
--- a/openjpa-lib/pom.xml
+++ b/openjpa-lib/pom.xml
@@ -10,115 +10,76 @@
     <description>Utilities</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
-
         <dependency>
-
             <groupId>jakarta-regexp</groupId>
             <artifactId>jakarta-regexp</artifactId>
             <version>1.4</version>
             <scope>test</scope>
-
         </dependency>
         <dependency>
-
             <groupId>commons-logging</groupId>
             <artifactId>commons-logging</artifactId>
             <version>1.0.4</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
             <groupId>log4j</groupId>
             <artifactId>log4j</artifactId>
             <version>1.2.13</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
             <groupId>javax.servlet</groupId>
             <artifactId>servlet-api</artifactId>
             <version>2.5</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
             <groupId>commons-lang</groupId>
             <artifactId>commons-lang</artifactId>
             <version>2.1</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
             <groupId>ant</groupId>
             <artifactId>ant</artifactId>
             <version>1.6.5</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
             <groupId>commons-collections</groupId>
             <artifactId>commons-collections</artifactId>
             <version>3.1</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
             <groupId>commons-pool</groupId>
             <artifactId>commons-pool</artifactId>
             <version>1.2</version>
             <scope>compile</scope>
-
         </dependency>
         <dependency>
-
-            <groupId>backport-util-concurrent</groupId>
-            <artifactId>backport-util-concurrent</artifactId>
-            <version>2.1</version>
-            <scope>compile</scope>
-
-        </dependency>
-
-        <dependency>
-
             <groupId>net.sourceforge.serp</groupId>
             <artifactId>serp</artifactId>
             <version>1.11.0</version>
             <scope>compile</scope>
-
         </dependency>
-
     </dependencies>
     <build>
-
         <plugins>
-
             <plugin>
-
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
                 <configuration>
                     <source>1.3</source>
                     <target>1.3</target>
                 </configuration>
-
             </plugin>
-
         </plugins>
-
     </build>
-
-
 </project>
diff --git a/openjpa-persistence-jdbc/pom.xml b/openjpa-persistence-jdbc/pom.xml
index 131da5d8a..f16ba47d3 100644
--- a/openjpa-persistence-jdbc/pom.xml
+++ b/openjpa-persistence-jdbc/pom.xml
@@ -10,11 +10,9 @@
     <description>JPA JDBC</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
@@ -22,7 +20,7 @@
 
             <groupId>org.apache.openjpa</groupId>
             <artifactId>openjpa-jdbc-5</artifactId>
-            <version>0.0.1</version>
+            <version>${pom.version}</version>
             <scope>compile</scope>
 
         </dependency>
@@ -30,7 +28,7 @@
 
             <groupId>org.apache.openjpa</groupId>
             <artifactId>openjpa-persistence</artifactId>
-            <version>0.0.1</version>
+            <version>${pom.version}</version>
             <scope>compile</scope>
 
         </dependency>
@@ -38,7 +36,7 @@
 
             <groupId>org.apache.derby</groupId>
             <artifactId>derby</artifactId>
-            <version>10.1.2.1</version>
+            <version>10.1.3.1</version>
             <scope>test</scope>
 
         </dependency>
diff --git a/openjpa-persistence/pom.xml b/openjpa-persistence/pom.xml
index a1b1df6d3..3a5b3cc3b 100644
--- a/openjpa-persistence/pom.xml
+++ b/openjpa-persistence/pom.xml
@@ -10,11 +10,9 @@
     <description>JPA</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
diff --git a/openjpa-project/LICENSE.txt b/openjpa-project/LICENSE.txt
new file mode 100644
index 000000000..693d6a988
--- /dev/null
+++ b/openjpa-project/LICENSE.txt
@@ -0,0 +1,20 @@
+Permission is hereby granted, free of charge, to any person 
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without 
+restriction, including without limitation the rights to use, 
+copy, modify, merge, publish, distribute, sublicense, and/or 
+sell copies of the Software, and to permit persons to whom the 
+Software is furnished to do so, subject to the following 
+conditions:
+
+The above copyright notice and this permission notice shall be 
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
+OTHER DEALINGS IN THE SOFTWARE.
diff --git a/openjpa-project/README.txt b/openjpa-project/README.txt
new file mode 100644
index 000000000..e88cdf60e
--- /dev/null
+++ b/openjpa-project/README.txt
@@ -0,0 +1,2 @@
+
+Thanks!
diff --git a/openjpa-project/assembly.xml b/openjpa-project/assembly.xml
new file mode 100644
index 000000000..38e6f5e17
--- /dev/null
+++ b/openjpa-project/assembly.xml
@@ -0,0 +1,94 @@
+<assembly>
+    <id></id>
+    <formats>
+        <format>zip</format>
+    </formats>
+    <includeBaseDirectory>true</includeBaseDirectory>
+    <fileSets>
+        <fileSet>
+            <includes>
+                <include>README*</include>
+                <include>LICENSE*</include>
+                <include>NOTICE*</include>
+            </includes>
+        </fileSet>
+        <fileSet>
+            <directory>licenses</directory>
+            <outputDirectory>/lib</outputDirectory>
+            <includes>
+                <include>*</include>
+            </includes>
+        </fileSet>
+        <fileSet>
+            <directory>target/manual/OpenJPA</directory>
+            <outputDirectory>/manual</outputDirectory>
+        </fileSet>
+        <fileSet>
+            <directory>../target/site/apidocs</directory>
+            <outputDirectory>/javadoc</outputDirectory>
+        </fileSet>
+        <fileSet>
+            <directory>target/examples</directory>
+            <outputDirectory>/examples</outputDirectory>
+        </fileSet>
+    </fileSets>
+    <dependencySets>
+        <dependencySet>
+            <outputDirectory>/lib</outputDirectory>
+            <unpack>false</unpack>
+            <scope>runtime</scope>
+            <excludes>
+                <!-- only used for the ant tasks, which will already have it -->
+                <exclude>ant:ant</exclude>
+                <exclude>ant:ant-xalan2</exclude>
+                <exclude>ant:ant-trax</exclude>
+                <exclude>bcel:bcel</exclude>
+
+                <!-- exclude empty distribution jars -->
+                <exclude>openjpa:openjpa-project</exclude>
+
+                <!-- already included in JDK 1.5 -->
+                <exclude>xerces:xerces</exclude>
+                <exclude>xerces:xercesImpl</exclude>
+                <exclude>xalan:xalan</exclude>
+                <exclude>xml-apis:xml-apis</exclude>
+                <exclude>xerces:xmlParserAPIs</exclude>
+
+                <!-- not required for release -->
+                <exclude>hsqldb:hsqldb</exclude>
+
+                <!-- only required for persistence server -->
+                <exclude>javax.servlet:servlet-api</exclude>
+
+                <!-- optional log implementation -->
+                <exclude>log4j:log4j</exclude>
+
+                <!-- optional -->
+                <exclude>junit:junit</exclude>
+            </excludes>
+        </dependencySet>
+
+
+        <!--
+        <dependencySet>
+            <outputDirectory>/optional</outputDirectory>
+            <unpack>false</unpack>
+            <scope>runtime</scope>
+            <includes>
+                <include>org.apache.derby:derby</include>
+            </includes>
+        </dependencySet>
+        -->
+
+        <!--
+         <dependencySet>
+            <outputDirectory>/</outputDirectory>
+            <unpack>false</unpack>
+            <scope>runtime</scope>
+            <includes>
+                <include>org.apache.openjpa:openjpa-all</include>
+            </includes>
+        </dependencySet>
+        -->
+    </dependencySets>
+</assembly>
diff --git a/openjpa-project/pom.xml b/openjpa-project/pom.xml
new file mode 100644
index 000000000..558890fa1
--- /dev/null
+++ b/openjpa-project/pom.xml
@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+        http://maven.apache.org/maven-v4_0_0.xsd">
+
+    <!--
+        To build the distribution files from project root:
+
+        mvn clean compile package -Dtest=false
+    -->
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>openjpa-project</artifactId>
+    <name>OpenJPA Project</name>
+    <parent>
+        <groupId>org.apache.openjpa</groupId>
+        <artifactId>openjpa</artifactId>
+        <version>0.9.0</version>
+    </parent>
+
+    <build>
+        <!-- needed to let maven pass the "compile" phase -->
+        <testSourceDirectory>/none/</testSourceDirectory>
+
+        <!-- filter site resources -->
+        <resources>
+            <resource>
+                <directory>${project.basedir}/src/site</directory>
+                <!-- targetPath is relative to target/classes/ -->
+                <targetPath>../filtered-site</targetPath>
+                <filtering>true</filtering>
+            </resource>
+        </resources>
+
+        <plugins>
+
+            <!-- build the docs when creating the site from docbook source -->
+            <plugin>
+                <artifactId>maven-antrun-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <phase>site</phase>
+                        <configuration>
+                         <!-- destdir="${project.build.directory}/site/manual" -->
+                            <tasks>
+                            <echo>Building docbook manual</echo>
+                            <style includes="**/manual.xml"
+                                basedir="${project.basedir}/src/doc/manual"
+                                destdir="${project.basedir}/target/filtered-site/resources/manual"
+                                style="manual-xhtml.xsl"
+                                classpathref="maven.runtime.classpath"/>
+                            <style includes="**/manual.xml"
+                                basedir="${project.basedir}/src/doc/manual"
+                                destdir="${project.basedir}/target/filtered-site/resources/manual"
+                                style="manual-xhtml-chunk.xsl"
+                                classpathref="maven.runtime.classpath"/>
+                            </tasks>
+                        </configuration>
+                        <goals>
+                            <goal>run</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <plugin>
+                <artifactId>maven-assembly-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>bin</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>assembly</goal>
+                        </goals>
+                        <configuration>
+                            <descriptor>assembly.xml</descriptor>
+                            <finalName>openjpa-${version}</finalName>
+                            <outputDirectory>${project.basedir}/target/filtered-site/resources/downloads</outputDirectory>
+                            <workDirectory>target/work</workDirectory>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>sources</id>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>assembly</goal>
+                        </goals>
+                        <configuration>
+                            <descriptor>source-assembly.xml</descriptor>
+                            <finalName>openjpa-${version}</finalName>
+                            <outputDirectory>${project.basedir}/target/filtered-site/resources/downloads</outputDirectory>
+                            <workDirectory>target/work</workDirectory>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <!--
+                copy over site files from src/site to target/filtered-site
+                so we can filter resources and include other generated
+                content from the openjpa-project module
+            -->
+            <plugin>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>prefilter-site</id>
+                        <phase>site</phase>
+                        <goals>
+                            <goal>resources</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-site-plugin</artifactId>
+                <version>2.0-beta-5</version>
+                <configuration>
+                    <siteDirectory>target/filtered-site</siteDirectory>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+
+    <!-- need to explicitly list dependencies for assembly to work -->
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-lib</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-kernel</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-kernel-5</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-jdbc</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-jdbc-5</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-persistence</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-persistence-jdbc</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.openjpa</groupId>
+            <artifactId>openjpa-xmlstore</artifactId>
+            <version>${pom.version}</version>
+        </dependency>
+
+        <!-- included so we can include it in the distribution -->
+        <dependency>
+            <groupId>org.apache.derby</groupId>
+            <artifactId>derby</artifactId>
+            <version>10.1.3.1</version>
+        </dependency>
+
+
+        <!-- jars needed for for docbook -->
+        <dependency>
+            <groupId>ant</groupId>
+            <artifactId>ant</artifactId>
+            <version>1.6.5</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>ant</groupId>
+            <artifactId>ant-trax</artifactId>
+            <version>1.6.5</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>xalan</groupId>
+            <artifactId>xalan</artifactId>
+            <version>2.7.0</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>bcel</groupId>
+            <artifactId>bcel</artifactId>
+            <version>5.1</version>
+            <scope>runtime</scope>
+        </dependency>
+    </dependencies>
+</project>
diff --git a/openjpa-project/source-assembly.xml b/openjpa-project/source-assembly.xml
new file mode 100644
index 000000000..9031adb20
--- /dev/null
+++ b/openjpa-project/source-assembly.xml
@@ -0,0 +1,16 @@
+<assembly>
+  <id>sources</id>
+  <formats>
+    <format>zip</format>
+  </formats>
+  <includeBaseDirectory>true</includeBaseDirectory>
+  <fileSets>
+    <fileSet>
+      <directory>..</directory>
+      <outputDirectory></outputDirectory>
+      <excludes>
+        <exclude>**/target/**</exclude>
+      </excludes>
+    </fileSet>
+  </fileSets>
+</assembly>
diff --git a/openjpa-project/src/doc/manual/manual-xhtml-chunk.xsl b/openjpa-project/src/doc/manual/manual-xhtml-chunk.xsl
new file mode 100644
index 000000000..3243d28a1
--- /dev/null
+++ b/openjpa-project/src/doc/manual/manual-xhtml-chunk.xsl
@@ -0,0 +1,24 @@
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+    <!-- docbook stylesheet customizations for openjpa manual -->
+	<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.69.1/xhtml/chunk.xsl"/>
+
+    <!--
+	<xsl:param name="html.stylesheet">../css/maven-base.css ../css/maven-theme.css ../css/site.css</xsl:param>
+    -->
+
+	<xsl:param name="html.cleanup" select="1"/>
+	<xsl:param name="label.from.part" select="1"/>
+	<xsl:param name="annotate.toc" select="1"/>
+	<xsl:param name="toc.section.depth">5</xsl:param>
+	<xsl:param name="generate.section.toc.level" select="8"/>
+	<xsl:param name="generate.id.attributes" select="1"/>
+	<xsl:param name="generate.index" select="1"/>
+	<xsl:param name="chapter.autolabel" select="1"/>
+	<xsl:param name="appendix.autolabel" select="1"/>
+	<xsl:param name="part.autolabel" select="1"/>
+	<xsl:param name="preface.autolabel" select="0"/>
+	<xsl:param name="qandadiv.autolabel" select="1"/>
+	<xsl:param name="section.autolabel" select="1"/>
+</xsl:stylesheet>
+
diff --git a/openjpa-project/src/doc/manual/manual-xhtml.xsl b/openjpa-project/src/doc/manual/manual-xhtml.xsl
new file mode 100644
index 000000000..902c618e6
--- /dev/null
+++ b/openjpa-project/src/doc/manual/manual-xhtml.xsl
@@ -0,0 +1,24 @@
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+    <!-- docbook stylesheet customizations for openjpa manual -->
+	<xsl:import href="http://docbook.sourceforge.net/release/xsl/1.69.1/xhtml/docbook.xsl"/>
+
+    <!--
+	<xsl:param name="html.stylesheet">../css/maven-base.css ../css/maven-theme.css ../css/site.css</xsl:param>
+    -->
+
+	<xsl:param name="html.cleanup" select="1"/>
+	<xsl:param name="label.from.part" select="1"/>
+	<xsl:param name="annotate.toc" select="1"/>
+	<xsl:param name="toc.section.depth">5</xsl:param>
+	<xsl:param name="generate.section.toc.level" select="8"/>
+	<xsl:param name="generate.id.attributes" select="1"/>
+	<xsl:param name="generate.index" select="1"/>
+	<xsl:param name="chapter.autolabel" select="1"/>
+	<xsl:param name="appendix.autolabel" select="1"/>
+	<xsl:param name="part.autolabel" select="1"/>
+	<xsl:param name="preface.autolabel" select="0"/>
+	<xsl:param name="qandadiv.autolabel" select="1"/>
+	<xsl:param name="section.autolabel" select="1"/>
+</xsl:stylesheet>
+
diff --git a/openjpa-project/src/doc/manual/manual.xml b/openjpa-project/src/doc/manual/manual.xml
new file mode 100644
index 000000000..67dbffa7d
--- /dev/null
+++ b/openjpa-project/src/doc/manual/manual.xml
@@ -0,0 +1,33806 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY openjpa-version "VERSION"> ]>
+<book id="manual">
+  <bookinfo>
+    <title>OpenJPA Developers Guide</title>
+  </bookinfo>
+  <part id="introduction">
+    <title>Introduction</title>
+    <chapter id="openjpa_intro">
+      <title>OpenJPA <phrase>JPA</phrase></title>
+      <indexterm zone="openjpa_intro">
+        <primary>OpenJPA <phrase>JPA</phrase></primary>
+      </indexterm>
+      <para>
+	OpenJPA <phrase>JPA</phrase> is Apache's implementation of Sun's
+	<phrase>
+	Java Persistence API (JPA) specification</phrase>
+	
+	
+	for the transparent persistence of Java objects.
+	This document provides an overview of
+	<phrase>the JPA standard</phrase>
+	
+	
+	and technical details on the use of OpenJPA <phrase>JPA</phrase>.
+	</para>
+      <para>
+	To quickly get started with JPA, you may want to begin at
+	<xref linkend="jpa_tutorial"/>.
+	If you would prefer to start with an introduction to the concepts of JPA,
+	begin with <xref linkend="jpa_overview_intro"/>.
+	</para>
+      <section id="openjpa_intro_about">
+        <title>About This Document</title>
+        <para>
+		This document is intended for OpenJPA users.  It is divided into several 
+		parts:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+				The <link linkend="jpa_overview_intro">JPA Overview</link> 
+				describes the fundamentals of JPA.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				In the <link linkend="tutorials">OpenJPA <phrase>JPA</phrase> 
+				Tutorials</link> you will develop simple persistent applications
+				using OpenJPA.  Through the tutorials' hands-on approach, you
+				will become comfortable with the core tools and development
+				processes under OpenJPA <phrase>JPA</phrase>.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				The <link linkend="ref_guide_intro">OpenJPA <phrase>JPA</phrase> 
+				Reference Guide</link> contains detailed documentation on all 
+				aspects of OpenJPA <phrase>JPA</phrase>.  Browse through this guide to 
+				familiarize yourself with the many advanced features and 
+				customization opportunities OpenJPA provides.  Later, you can use 
+				the guide when you need details on a specific aspect of OpenJPA 
+				<phrase>JPA</phrase>.
+				</para>
+          </listitem>
+        </itemizedlist>
+      </section>
+    </chapter>
+  </part>
+  <part id="jpa_overview">
+    <title>Java Persistence API</title>
+    <chapter id="jpa_overview_intro">
+      <title>Introduction</title>
+      <para><indexterm><primary>EJB3 Persistence</primary><see>EJB</see></indexterm><indexterm><primary>EJB</primary></indexterm>
+	Enterprise Java Beans 3.0 Persistence (EJB persistence) is a specification 
+	from Sun Microsystems for the persistence of Java objects to any relational
+	datastore.  EJB persistence requires J2SE 1.5 (also referred to as "Java 5")
+	or higher, as it makes heavy use of new Java language features such as
+	annotations and generics.  This document provides an overview of EJB 
+	persistence.  Unless otherwise noted, the information presented
+	applies to all EJB persistence implementations.
+	</para>
+      <note>
+        <para>
+		This document describes the Public Draft of the EJB 3.0
+		persistence specification.
+		</para>
+        <para>
+		For coverage of OpenJPA's many extensions to the EJB persistence 
+		specification, see the <link linkend="ref_guide_intro">Reference
+		Guide</link>.
+		</para>
+      </note>
+      <section id="jpa_overview_intro_audience">
+        <title>Intended Audience</title>
+        <para>
+		This document is intended for developers who want to learn about
+		EJB persistence in order to use it in their applications.
+		It assumes that you have a strong knowledge of object-oriented concepts
+		and Java, including Java 5 annotations and generics.  It also assumes
+		some experience with relational databases and the 
+		Structured Query Language (SQL).
+		</para>
+      </section>
+      <section id="jpa_overview_intro_transpers">
+        <title>Lightweight Persistence</title>
+        <indexterm zone="jpa_overview_intro_transpers">
+          <primary>lightweight persistence</primary>
+        </indexterm>
+        <para><indexterm><primary>persistent data</primary></indexterm><emphasis>Persistent data</emphasis> is information that can
+		outlive the program that creates it.  The majority of complex
+		programs use persistent data: GUI applications need to store user 
+		preferences across program invocations, web applications track 
+		user movements and orders over long periods of time, etc.
+		</para>
+        <para><emphasis>Lightweight persistence</emphasis> is the storage and 
+		retrieval of persistent data with little or no work from you, the 
+		developer.  For example, Java serialization<indexterm><primary>serialization</primary></indexterm> is a form of 
+		lightweight persistence because it can be used to persist Java 
+		objects directly to a file with very little effort.  Serialization's
+		capabilities as a lightweight persistence mechanism pale in 
+		comparison to those provided by EJB, however.  The next
+		chapter compares EJB to serialization and other available
+		persistence mechanisms.
+		</para>
+      </section>
+    </chapter>
+    <chapter id="jpa_overview_why">
+      <title>Why JPA?</title>
+      <indexterm zone="jpa_overview_why">
+        <primary>JPA</primary>
+        <secondary>why</secondary>
+      </indexterm>
+      <para>
+	Java developers who need to store and retrieve persistent 
+	data already have several options available to them:
+	serialization, JDBC, JDO, proprietary object-relational mapping tools, 
+	object databases, and EJB 2 entity beans.  Why introduce yet 	
+	another persistence framework?  The answer to this question is that with
+	the exception of JDO, each of the aforementioned persistence solutions
+	has severe limitations.  JPA attempts to overcome these
+	limitations, as illustrated by the table below.
+	</para>
+      <table tocentry="1">
+        <title>Persistence Mechanisms</title>
+        <tgroup cols="8" align="left" colsep="1" rowsep="1">
+          <colspec colname="sup"/>
+          <colspec colname="ser"/>
+          <colspec colname="jdbc"/>
+          <colspec colname="or"/>
+          <colspec colname="objdb"/>
+          <colspec colname="ejb2"/>
+          <colspec colname="jdo"/>
+          <colspec colname="ejb3"/>
+          <thead>
+            <row>
+              <entry colname="sup">Supports:</entry>
+              <entry colname="ser">Serialization</entry>
+              <entry colname="jdbc">JDBC</entry>
+              <entry colname="or">ORM</entry>
+              <entry colname="objdb">ODB</entry>
+              <entry colname="ejb2">EJB 2</entry>
+              <entry colname="jdo">JDO</entry>
+              <entry colname="ejb3">JPA</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry colname="sup">Java Objects</entry>
+              <entry colname="ser">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdbc">No</entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Advanced OO Concepts</entry>
+              <entry colname="ser">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdbc">No</entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">No</entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Transactional Integrity</entry>
+              <entry colname="ser">No</entry>
+              <entry colname="jdbc">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Concurrency</entry>
+              <entry colname="ser">No</entry>
+              <entry colname="jdbc">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Large Data Sets</entry>
+              <entry colname="ser">No</entry>
+              <entry colname="jdbc">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Existing Schema</entry>
+              <entry colname="ser">No</entry>
+              <entry colname="jdbc">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">No</entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">
+						Relational and Non-Relational Stores
+					</entry>
+              <entry colname="ser">No</entry>
+              <entry colname="jdbc">No</entry>
+              <entry colname="or">No</entry>
+              <entry colname="objdb">No</entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">No</entry>
+            </row>
+            <row>
+              <entry colname="sup">Queries</entry>
+              <entry colname="ser">No</entry>
+              <entry colname="jdbc">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Strict Standards / Portability</entry>
+              <entry colname="ser">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdbc">No</entry>
+              <entry colname="or">No</entry>
+              <entry colname="objdb">No</entry>
+              <entry colname="ejb2">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+            <row>
+              <entry colname="sup">Simplicity</entry>
+              <entry colname="ser">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="jdbc">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="or">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="objdb">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb2">No</entry>
+              <entry colname="jdo">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+              <entry colname="ejb3">
+                <emphasis role="bold">Yes</emphasis>
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      <itemizedlist>
+        <listitem>
+          <para><indexterm><primary>serialization</primary></indexterm><indexterm><primary>JPA</primary><secondary>vs serialization</secondary></indexterm><emphasis>Serialization</emphasis> is Java's 
+			built-in mechanism for transforming an object graph into a
+			series of bytes, which can then be sent over the network or
+			stored in a file.  Serialization is very easy to use, 
+			but it is also very limited.  It must store and retrieve the
+			entire object graph at once, making it unsuitable for
+			dealing with large amounts of data.  It cannot undo changes 
+			that are made to objects if an error occurs while updating
+			information, making it unsuitable for applications that 
+			require strict data integrity.  Multiple threads or programs
+			cannot read and write the same serialized data concurrently
+			without conflicting with each other.  It provides no query
+			capabilities.  All these factors make serialization useless 
+			for all but the most trivial persistence needs.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>Java Database Connectivity</primary><see>JDBC</see></indexterm><indexterm><primary>JDBC</primary></indexterm><indexterm><primary>JPA</primary><secondary>vs JDBC</secondary></indexterm>
+			Many developers use the 
+			<emphasis>Java Database Connectivity</emphasis> (JDBC) APIs to
+			manipulate persistent data in relational databases.  JDBC 
+			overcomes most of the shortcomings of serialization:
+			it can handle large amounts of data, has mechanisms to ensure
+			data integrity, supports concurrent access to information, and 
+			has a sophisticated query language in SQL.  Unfortunately, JDBC
+			does not duplicate serialization's ease of use.  The relational
+			paradigm used by JDBC was not designed for storing objects,
+			and therefore forces you to either abandon
+			object-oriented programming for the portions of your code 
+			that deal with persistent data, or to find a way of mapping 
+			object-oriented concepts like inheritance to relational 
+			databases yourself.  
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>object-relational mapping</primary><see>ORM</see></indexterm><indexterm><primary>ORM</primary></indexterm><indexterm><primary>JPA</primary><secondary>vs ORM products</secondary></indexterm>
+			There are many proprietary software products that can perform the
+			mapping between objects and relational database tables for you.
+			These <emphasis>object-relational mapping</emphasis> (ORM) 
+			frameworks allow you to focus on the object model and not concern
+			yourself with the mismatch between 
+			the object-oriented and relational paradigms.  Unfortunately, 
+			each of these product has its own set of APIs.
+			Your code becomes tied to the proprietary interfaces of a single
+			vendor.  If the vendor raises prices, fails to fix show-stopping 
+			bugs, or falls behind in features, you cannot switch to another 
+			product without rewriting all of your persistence code.   This is 
+			referred to as vendor lock-in.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>object database</primary><see>ODB</see></indexterm><indexterm><primary>ODB</primary></indexterm><indexterm><primary>JPA</primary><secondary>vs ODBs</secondary></indexterm><indexterm><primary>ODBMG</primary></indexterm>
+			Rather than map objects to relational databases, some software
+			companies have developed a form of database designed 
+			specifically to store objects.  These
+			<emphasis>object databases</emphasis> (ODBs) are often much
+			easier to use than object-relational mapping software.
+			The Object Database Management Group (ODMG) was formed to create
+			a standard API for accessing object databases; few object
+			database vendors, however, comply with the ODMG's 
+			recommendations.  Thus, vendor lock-in plagues object databases
+			as well.  Many companies are also hesitant to switch from
+			tried-and-true relational systems to the relatively unknown object
+			database technology.  Fewer data-analysis tools are available
+			for object database systems, and there are vast quantities of
+			data already stored in older relational databases.  For all of
+			these reasons and more, object databases have not caught on
+			as well as their creators hoped.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>Enterprise Java Beans</primary><see>EJB</see></indexterm><indexterm><primary>EJB</primary></indexterm><indexterm><primary>JPA</primary><secondary>vs EJB 2</secondary></indexterm>
+			The Enterprise Edition of the Java platform introduced entity
+			Enterprise Java Beans (EJBs).  EJB 2.x entities are components that
+			represent persistent information in a datastore.  Like 
+			object-relational mapping solutions, EJB 2.x entities provide
+			an object-oriented view of persistent data.  Unlike 
+			object-relational software, however, EJB 2.x entities are not
+			limited to relational databases; the persistent information they
+			represent may come from an Enterprise Information System (EIS) or
+			other storage device.  Also, EJB 2.x entities use a strict standard,
+			making them portable across vendors.  Unfortunately, the EJB 2.x 
+			standard is somewhat limited in the object-oriented concepts it can 
+			represent.  Advanced features like inheritance, polymorphism, and 
+			complex relations are absent.  Additionally, EBJ 2.x entities are
+			difficult to code, and they require heavyweight and often expensive
+			application servers to run.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>JDO</primary></indexterm><indexterm><primary>JPA</primary><secondary>vs JDO</secondary></indexterm>
+			The JDO specification uses an API that is strikingly similar to
+			JPA.  JDO, however, supports non-relational databases, 
+			a feature that some argue dilutes the specification.
+			</para>
+        </listitem>
+      </itemizedlist>
+      <para><indexterm><primary>JPA</primary></indexterm>
+	JPA combines the best features from each of the persistence 
+	mechanisms listed above.  Creating entities under JPA
+	is as simple as creating serializable classes.  JPA supports the
+	large data sets, data consistency, concurrent use, and query capabilities of
+	JDBC.  Like object-relational software and object databases, JPA
+	allows the use of advanced object-oriented concepts such as inheritance. 
+	JPA avoids vendor lock-in by relying on a strict specification
+	like JDO and EJB 2.x entities.  JPA focuses on relational 
+	databases.  And like JDO, JPA is extremely easy to use.
+	</para>
+      <note>
+        <para>
+		OpenJPA typically stores data in relational databases, but can be 
+		customized for use with non-relational datastores as well.
+		</para>
+      </note>
+      <para>
+	JPA is not ideal for every application.  For many applications,
+	though, it provides an exciting alternative to other persistence mechanisms.
+	</para>
+    </chapter>
+    <chapter id="jpa_overview_arch">
+      <title>EJB Persistence Architecture</title>
+      <indexterm zone="jpa_overview_arch">
+        <primary>EJB</primary>
+        <secondary>architecture</secondary>
+      </indexterm>
+      <para>
+	The diagram below illustrates the relationships between the primary
+	components of the EJB architecture.
+	</para>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data 400 x 256 (see README) -->
+          <imagedata fileref="img/ejb3-arch.png" width="267px"/>
+        </imageobject>
+        <textobject>
+          <phrase>EJB architecture</phrase>
+        </textobject>
+      </mediaobject>
+      <note>
+        <para>
+		A number of the depicted interfaces are only required outside of
+		an EJB3-compliant application server.  In an application server,
+		<classname>EntityManager</classname> instances are typically injected, 
+		rendering the <classname>EntityManagerFactory</classname> unnecessary.
+		Also, transactions within an application server
+		are handled using standard application server transaction controls.
+		Thus, the <classname>EntityTransaction</classname> also goes unused.
+		</para>
+      </note>
+      <itemizedlist>
+        <listitem>
+          <para><indexterm><primary>Persistence</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_persistence"><classname>Persistence</classname></link></emphasis>:
+			The <classname>javax.persistence.Persistence</classname> class
+			contains static helper methods to obtain 
+			<classname>EntityManagerFactory</classname> instances in a 
+			vendor-neutral fashion.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>EntityManagerFactory</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_emfactory"><classname>EntityManagerFactory</classname></link></emphasis>:  The <classname>javax.persistence.EntityManagerFactory
+			</classname> class is a factory for <classname>
+			EntityManager</classname>s.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>EntityManager</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_em"><classname>EntityManager</classname></link></emphasis>:
+			The <classname>javax.persistence.EntityManager</classname> is the
+			primary EJB persistence interface used by applications.
+			Each <classname>EntityManager</classname> manages a set of 
+			persistent objects, and has APIs to insert new objects and delete
+			existing ones.  When used outside the container, there is a 
+			one-to-one relationship between an 
+			<classname>EntityManager</classname> and an <classname>
+			EntityTransaction</classname>.  <classname>
+			EntityManager</classname>s also act as factories for
+			<classname>Query</classname> instances.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>entity</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_pc"><classname>Entity</classname></link></emphasis>:
+			Entites are persistent objects that represent datastore records.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>EntityTransaction</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_trans"><classname>EntityTransaction</classname></link></emphasis>:  
+			Each <classname>EntityManager</classname> has a one-to-one
+			relation with a single 
+			<classname>javax.persistence.EntityTransaction</classname>.  
+			<classname>EntityTransaction</classname>s allow operations on 
+			persistent data to be grouped into units of work that either 
+			completely succeed or completely fail, leaving the datastore
+			in its original state.  These all-or-nothing operations are
+			important for maintaining data integrity.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>Query</primary></indexterm><indexterm><primary>EJB3 Persistence Query Language</primary><see>JPQL</see></indexterm><indexterm><primary>JPQL</primary></indexterm><indexterm><primary>EJB</primary><secondary>query language</secondary><see>JPQL</see></indexterm><indexterm><primary>Structured Query Language</primary><see>SQL</see></indexterm><indexterm><primary>SQL</primary></indexterm><emphasis role="bold"><link linkend="jpa_overview_query"><classname>Query</classname></link></emphasis>:  The
+			<classname>javax.persistence.Query</classname> interface is
+			implemented by each EJB vendor to find persistent objects
+			that meet certain criteria.  EJB standardizes support
+			for queries using both the EJB Query Language (JPQL) and
+			the Structured Query Language (SQL).  You obtain 
+			<classname>Query</classname> instances from an
+			<classname>EntityManager</classname>.
+			</para>
+        </listitem>
+      </itemizedlist>
+      <para>
+	The example below illustrates how the EJB interfaces interact to
+	execute an JPQL query and update persistent objects.  The example
+	assumes execution outside a container.
+	</para>
+      <example id="jpa_overview_arch_interact_outside">
+        <title>Interaction of Interfaces Outside Container</title>
+        <programlisting format="linespecific">
+// get an EntityManagerFactory using the Persistence class; typically 
+// the factory is cached for easy repeated use
+EntityManagerFactory factory = Persistence.createEntityManagerFactory (null);
+
+// get an EntityManager from the factory
+EntityManager em = factory.createEntityManager (PersistenceContextType.EXTENDED);
+
+// updates take place within transactions
+EntityTransaction tx = em.getTransaction ();
+tx.begin ();
+
+// query for all employees who work in our research division
+// and put in over 40 hours a week average
+Query query = em.createQuery ("select e from Employee e where "
+    + "e.division.name = 'Research' AND e.avgHours &gt; 40");
+List results = query.getResultList ();
+
+// give all those hard-working employees a raise
+for (Object res : results)
+{
+    Employee emp = (Employee) res;
+    emp.setSalary (emp.getSalary () * 1.1);
+}
+
+// commit the updates and free resources
+tx.commit ();
+em.close ();
+factory.close ();
+</programlisting>
+      </example>
+      <para>
+	Within a container, the <classname>EntityManager</classname> will be 
+	injected and transactional handled declaratively.  Thus, the in-container
+	version of the example consists entirely of business logic:
+	</para>
+      <example id="jpa_overview_arch_interact_inside">
+        <title>Interaction of Interfaces Inside Container</title>
+        <programlisting format="linespecific">
+// query for all employees who work in our research division
+// and put in over 40 hours a week average - note that the EntityManager em
+// is injected using a @Resource annotation
+Query query = em.createQuery ("select e from Employee e where "
+    + "e.division.name = 'Research' and e.avgHours &gt; 40");
+List results = query.getResultList ();
+
+// give all those hard-working employees a raise
+for (Object res : results)
+{
+    emp = (Employee) res;
+    emp.setSalary (emp.getSalary () * 1.1);
+} 
+</programlisting>
+      </example>
+      <para>
+	The remainder of this document explores the EJB interfaces in
+	detail.  We present them in roughly the order that you will use them as you 
+	develop your application.
+	</para>
+      <section id="jpa_overview_arch_exceptions">
+        <title>EJB Exceptions</title>
+        <indexterm zone="jpa_overview_arch_exceptions">
+          <primary>EJB</primary>
+          <secondary>exceptions</secondary>
+          <seealso>exceptions</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>exceptions</primary>
+          <secondary>EJB</secondary>
+        </indexterm>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 427 x 355 (see README) -->
+            <imagedata fileref="img/ejb3-exceptions.png" width="285px"/>
+          </imageobject>
+          <textobject>
+            <phrase>EJB persistence exception architecture</phrase>
+          </textobject>
+        </mediaobject>
+        <para>
+		The diagram above depicts the EJB persistence exception architecture.  
+		All exceptions are unchecked.  EJB persistence uses
+		standard exceptions where appropriate, most notably <classname>
+		IllegalArgumentException</classname>s and <classname>
+		IllegalStateException</classname>s.  The specification also provides
+		a few EJB-specific exceptions in the <literal>javax.persistence
+		</literal> package.  These exceptions should be self-explanatory.  See 
+		the <ulink url="http://java.sun.com/javaee/5/docs/api">Javadoc</ulink> for 
+		additional details on EJB exceptions.
+		</para>
+        <note>
+          <para>
+			All exceptions thrown by OpenJPA implement 
+			<ulink url="../apidocs/org/apache/openjpa/util/ExceptionInfo.html"><classname>
+			org.apache.openjpa.util.ExceptionInfo</classname></ulink> to provide you with
+			additional error information.
+			</para>
+        </note>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_pc">
+      <title>Entity</title>
+      <indexterm zone="jpa_overview_pc">
+        <primary>persistent classes</primary>
+      </indexterm>
+      <indexterm zone="jpa_overview_pc">
+        <primary>Entity</primary>
+        <seealso>persistent classes</seealso>
+      </indexterm>
+      <indexterm>
+        <primary>class</primary>
+        <secondary>persistent</secondary>
+        <see>persistent classes</see>
+      </indexterm>
+      <indexterm>
+        <primary>persistence capable</primary>
+        <see>Entity</see>
+      </indexterm>
+      <para>
+	JPA recognizes two types of persistent classes: <emphasis>
+	entity</emphasis> classes and <emphasis>embeddable</emphasis> classes.
+	Each persistent instance of an entity class - each 
+	<emphasis>entity</emphasis> - represents a unique datastore
+	record.  You can use the <classname>EntityManager</classname> to find an 
+	entity by its persistent identity (covered later in this chapter), or use 
+	a <classname>Query</classname> to find entities matching certain criteria.  
+	</para>
+      <para>
+	An instance of an embeddable class, on the other hand, is only stored
+	as part of a separate entity.  Embeddable instances have no
+	persistent identity, and are never returned directly from the
+	<classname>EntityManager</classname> or from a <classname>Query</classname>.
+	</para>
+      <para>
+	Despite these differences, there are few differences between entity classes
+	and embeddable classes.  In fact, writing either type
+	of persistent class is little different than writing any other 
+	class.  There are no special parent classes to extend from, field types to 
+	use, or methods to write.  This is one important way in which JPA makes
+	persistence transparent to you, the developer.
+	</para>
+      <note>
+        <para>
+		JPA supports both fields and JavaBean properties
+		as persistent state.  For simplicity, however, we will
+		refer to all persistent state as persistent fields, unless we
+		want to note a unique aspect of persistent properties.
+		</para>
+      </note>
+      <example id="jpa_overview_pc_pcclass">
+        <title>Persistent Class</title>
+        <programlisting format="linespecific">
+package org.mag;
+
+/**
+ * Example persistent class.  Notice that it looks exactly like any other
+ * class.  JPA makes writing persistent classes completely transparent.
+ */
+public class Magazine
+{
+    private String    isbn;
+    private String    title;
+    private Set       articles = new HashSet ();
+    private Article   coverArticle;
+    private int       copiesSold;
+    private double    price;
+    private Company   publisher;
+    private int       version;
+
+    protected Magazine ()
+    {
+    }
+
+    public Magazine (String title, String isbn)
+    {
+        this.title = title;
+        this.isbn = isbn;
+    }
+
+    public void publish (Company publisher, double price)
+    {
+        this.publisher = publisher;
+        publisher.addMagazine (this);
+        this.price = price;
+    }
+    
+    public void sell ()
+    {
+        copiesSold++;
+        publisher.addRevenue (price);
+    }
+
+    public void addArticle (Article article)
+    {
+        articles.add (article);
+    }
+
+    // rest of methods omitted
+}
+</programlisting>
+      </example>
+      <section id="jpa_overview_pc_restrict">
+        <title>Restrictions on Persistent Classes</title>
+        <indexterm zone="jpa_overview_pc_restrict">
+          <primary>persistent classes</primary>
+          <secondary>restrictions on</secondary>
+        </indexterm>
+        <para>
+		There are very few restrictions placed on persistent classes.
+		Still, it never hurts to familiarize yourself with exactly what
+		JPA does and does not support.
+		</para>
+        <section id="jpa_overview_pc_no_arg">
+          <title>Default or No-Arg Constructor</title>
+          <indexterm zone="jpa_overview_pc_no_arg">
+            <primary>persistent classes</primary>
+            <secondary>no-arg constructor requirement</secondary>
+          </indexterm>
+          <indexterm>
+            <primary>constructor</primary>
+            <secondary>no-arg constructor requirement</secondary>
+          </indexterm>
+          <para>
+			The JPA specification requires that all persistent
+			classes have a no-arg constructor.  This constructor
+			may be public or protected.  Because the compiler automatically
+			creates a default no-arg constructor when no other constructor
+			is defined, only classes that define constructors must also
+			include a no-arg constructor.
+			</para>
+          <note>
+            <para>
+				OpenJPA's <emphasis>enhancer</emphasis> will automatically add a 
+				protected no-arg constructor to your class when required.  
+				Therefore, this restriction does not apply when using
+				OpenJPA.  See <xref linkend="ref_guide_pc_enhance"/> 
+				of the Reference Guide for details.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_pc_final">
+          <title>Final</title>
+          <para>
+			Entity classes may not be final.  No method of an entity class can
+			be final.
+			</para>
+          <note>
+            <para>
+				OpenJPA supports final classes and final methods.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_pc_id">
+          <title>Identity Fields</title>
+          <indexterm zone="jpa_overview_pc_id">
+            <primary>identity fields</primary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_pc_id">
+            <primary>persistent classes</primary>
+            <secondary>JPA id requirement</secondary>
+          </indexterm>
+          <para>
+			All entity classes must declare one or more fields which together
+			form the persistent identity of an instance.  These are called 
+			<emphasis>identity</emphasis> or <emphasis>primary key</emphasis>
+			fields.  In our <classname>Magazine</classname> class, 
+			<literal>isbn</literal> and
+			<literal>title</literal> are identity fields, because no two 
+			magazine records in the datastore can have the same 
+			<literal>isbn</literal> and <literal>title</literal> values.
+			<xref linkend="jpa_overview_meta_id"/> will show you how to denote 
+			your identity fields in JPA metadata.  
+			<xref linkend="jpa_overview_pc_identity"/> below examines 
+			persistent identity.
+			</para>
+          <note>
+            <para>
+				OpenJPA fully supports identity fields, but does not require them.
+				See <xref linkend="ref_guide_pc_oid"/> of the Reference
+				Guide for details.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_pc_version">
+          <title>Version Field</title>
+          <indexterm zone="jpa_overview_pc_version">
+            <primary>version fields</primary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_pc_version">
+            <primary>persistent classes</primary>
+            <secondary>JPA version requirement</secondary>
+          </indexterm>
+          <para>
+			The <literal>version</literal> field in our <classname>Magazine
+			</classname> class may seem out of place.
+			JPA uses a version field in your entity to detect
+			concurrent modifications to the same datastore record.  When the
+			JPA runtime detects an attempt to concurrently modify 
+			the same record, it throws an exception to the transaction 
+			attempting to commit last.  This prevents overwriting the previous
+			commit with stale data.
+			</para>
+          <para>
+			The version field is not required, but without one concurrent 
+			threads or processes might succeed in making conflicting changes 
+			to the same record at the same time.  This is unacceptable to most
+			applications.  <xref linkend="jpa_overview_meta_version"/>
+			shows you how to designate a version field in JPA metadata.
+			</para>
+          <para>
+			The version field must be an integral type (<classname>
+			int</classname>, <classname>Long</classname>, etc) or a 
+			<classname>java.sql.Timestamp</classname>.	You should consider
+			version fields immutable.  Changing the field value has undefined
+			results.
+			</para>
+          <note>
+            <para>
+				OpenJPA fully supports version fields, but does not require them
+				for concurrency detection.  OpenJPA can maintain 
+				surrogate version values or use state comparisons to detect 
+				concurrent modifications.  See 
+				<xref linkend="ref_guide_mapping_ejb"/> in the Reference Guide.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_pc_restrict_inheritance">
+          <title>Inheritance</title>
+          <indexterm zone="jpa_overview_pc_restrict_inheritance">
+            <primary>persistent classes</primary>
+            <secondary>inheritance of</secondary>
+            <seealso>inheritance</seealso>
+          </indexterm>
+          <indexterm>
+            <primary>inheritance</primary>
+            <secondary>of persistent classes</secondary>
+          </indexterm>
+          <para>
+			JPA fully supports inheritance in persistent classes.  
+			It allows persistent classes to inherit from non-persistent classes,
+			persistent classes to inherit from other persistent classes,
+			and non-persistent classes to inherit from persistent classes.
+			It is even possible to form inheritance hierarchies in which
+			persistence skips generations.  There are, however, a few 
+			important limitations:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					Persistent classes cannot inherit from certain
+					natively-implemented system classes such as
+					<classname>java.net.Socket</classname> and 
+					<classname>java.lang.Thread</classname>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					If a persistent class inherits from a non-persistent
+					class, the fields of the non-persistent superclass
+					cannot be persisted.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					All classes in an inheritance tree must use the same
+					identity type.  We cover entity identity in
+					<xref linkend="jpa_overview_pc_identity"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_pc_restrict_fields">
+          <title>Persistent Fields</title>
+          <indexterm zone="jpa_overview_pc_restrict_fields">
+            <primary>persistent classes</primary>
+            <secondary>field restrictions</secondary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm>
+            <primary>field</primary>
+            <secondary>persistent</secondary>
+            <see>persistent fields</see>
+          </indexterm>
+          <indexterm zone="jpa_overview_pc_restrict_fields">
+            <primary>persistent fields</primary>
+            <secondary>restrictions on</secondary>
+          </indexterm>
+          <para>
+			JPA manages the state of all persistent fields.
+			Before you access persistent state, the JPA runtime
+			makes sure that it has been loaded from the datastore.  When you 
+			set a field, the runtime records that it has changed so that 
+			the new value will be persisted.  This allows you to treat the 
+			field in exactly the same way you treat any other field - another 
+			aspect of JPA's transparency.
+			</para>
+          <para>
+			JPA does not support static or final fields.
+			It does, however, include built-in support for most 
+			common field types.  These types can be roughly divided into three 
+			categories: immutable types, mutable types, and relations.
+			</para>
+          <para><indexterm><primary>persistent fields</primary><secondary>immutable types</secondary></indexterm><indexterm><primary>immutable</primary><secondary>persistent field types</secondary></indexterm><emphasis>Immutable</emphasis> types, once created, cannot be 	
+			changed.  The only way to alter a persistent field of an immutable 
+			type is to assign a new value to the field.  JPA 
+			supports the following immutable types:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					All primitives (<classname>int, float, byte</classname>,
+					etc)
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					All primitive wrappers (<classname>java.lang.Integer,
+					java.lang.Float, java.lang.Byte</classname>, etc)
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+                <classname>java.lang.String</classname>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <classname>java.math.BigInteger</classname>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <classname>java.math.BigDecimal</classname>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			JPA also supports <classname>byte[]</classname> and
+			<classname>char[]</classname> as immutable types.  That is, you
+			can persist fields of these types, but you should not manipulate
+			individual array indexes without resetting the array into the 
+			persistent field.
+			</para>
+<!-- ### EJB3 : Byte[], Character[] -->
+          <para><indexterm><primary>persistent fields</primary><secondary>mutable types</secondary><seealso>proxies</seealso></indexterm><indexterm><primary>mutable</primary><secondary>persistent field types</secondary><seealso>persistent fields</seealso><seealso>proxies</seealso></indexterm><indexterm><primary>persistent fields</primary><secondary>user-defined types</secondary></indexterm><indexterm><primary>user-defined</primary><secondary>persistent field types</secondary><seealso>persistent fields</seealso></indexterm>
+			Persistent fields of <emphasis>mutable</emphasis> types 
+			can be altered without assigning the field a new value.
+			Mutable types can be modified directly through their own
+			methods.  The JPA specification requires that
+			implementations support the following mutable field types:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <classname>java.util.Date</classname>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <classname>java.util.Calendar</classname>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <classname>java.sql.Date</classname>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <classname>java.sql.Timestamp</classname>
+              </para>
+            </listitem>
+            <listitem>
+              <para>Enums</para>
+            </listitem>
+            <listitem>
+              <para>Entity types (relations between entities)</para>
+            </listitem>
+            <listitem>
+              <para>Embeddable types</para>
+            </listitem>
+            <listitem>
+              <para><classname>java.util.Collection</classname>s of entities
+					</para>
+            </listitem>
+            <listitem>
+              <para><classname>java.util.Set</classname>s of entities
+					</para>
+            </listitem>
+            <listitem>
+              <para><classname>java.util.List</classname>s of entities
+					</para>
+            </listitem>
+            <listitem>
+              <para><classname>java.util.Map</classname>s in which each entry
+					maps the value of one of an entity's fields to that entity.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			Collection and map types may be parameterized.
+			</para>
+          <para><indexterm><primary>persistent fields</primary><secondary>of unknown types</secondary></indexterm><indexterm><primary>Object</primary><secondary>as persistent field type</secondary><seealso>persistent fields</seealso></indexterm>
+			Most JPA implementations also have support for 
+			persisting serializable values as binary data in the datastore.
+			<xref linkend="jpa_overview_meta"/> has more information on
+			persisting serializable types.
+			</para>
+          <note>
+            <para>
+				OpenJPA also supports arrays, <classname>
+				java.lang.Number</classname>, <classname>
+				java.util.Locale</classname>, all JDK 1.2 <classname>
+				Set</classname>, <classname>List</classname>, and <classname>
+				Map</classname> types, collections and maps of immutable and
+				embedded as well as entity types, and many other mutable and 
+				immutable field types.  OpenJPA also allows you to plug in 
+				support for custom types.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_pc_restrict_conclusion">
+          <title>Conclusions</title>
+          <para>
+			This section detailed all of the restrictions JPA 
+			places on persistent classes.  While it may seem like we presented 
+			a lot of information, you will seldom find yourself hindered by 
+			these restrictions in practice.  Additionally, there are often ways
+			of using JPA's other features to circumvent any 
+			limitations you run into.  
+			<!-- ### EJBDOC : good transition when lifecycle listeners are
+			     ### added back as next section
+			The next section explores a powerful JPA feature 
+			that is particularly useful for this purpose.
+			-->
+			</para>
+        </section>
+      </section>
+      <section id="jpa_overview_pc_identity">
+        <title>Entity Identity</title>
+        <indexterm zone="jpa_overview_pc_identity">
+          <primary>JPA</primary>
+          <secondary>identity</secondary>
+          <seealso>identity</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>entity identity</primary>
+          <see>identity</see>
+        </indexterm>
+        <indexterm zone="jpa_overview_pc_identity">
+          <primary>identity</primary>
+          <secondary>JPA</secondary>
+        </indexterm>
+        <para><indexterm><primary>identity</primary><secondary>numeric</secondary></indexterm><indexterm><primary>identity</primary><secondary>qualitative</secondary></indexterm><indexterm><primary>numeric identity</primary><seealso>identity</seealso></indexterm><indexterm><primary>qualitative identity</primary><seealso>identity</seealso></indexterm>
+		Java recognizes two forms of object identity: numeric identity and
+		qualitative identity.  If two references are 
+		<emphasis>numerically</emphasis> identical, then they refer to the 
+		same JVM instance in memory.  You can test for this using the 
+		<literal>==</literal> operator.  <emphasis>Qualitative</emphasis> 
+		identity, on the other hand, relies on some user-defined criteria to 
+		determine whether two objects are "equal".  You test for qualitative 
+		identity using the <methodname>equals</methodname> method.  By default,
+		this method simply relies on numeric identity.
+		</para>
+        <para>
+		JPA introduces another form of object identity, called 
+		<emphasis>entity identity</emphasis> or <emphasis>persistent 
+		identity</emphasis>.  Entity identity tests whether two persistent 
+		objects represent the same state in the datastore.
+		</para>
+        <para><indexterm><primary>persistent fields</primary><secondary>id</secondary></indexterm><indexterm><primary>id</primary><secondary>fields</secondary><seealso>persistent fields</seealso></indexterm>
+	 	The entity identity of each persistent instance is encapsulated in its 
+		<emphasis>identity field(s)</emphasis>.  If two entities of the same 
+		type have the same identity field values, then the two 
+		entities represent the same state in the datastore.  Each entity's 
+		identity field values must be unique among all other entites of the 
+		same type.
+		</para>
+        <para>
+		Identity fields must be primitives, primitive wrappers, 
+		<classname>String</classname>s, <classname>Date</classname>s,
+		<classname>Timestamp</classname>s, or embeddable types. Notably, other 
+		entities instances can <emphasis>not</emphasis> be used as identity 
+		fields.
+		</para>
+        <note>
+          <para>
+			For legacy schemas with binary primary key columns, OpenJPA
+			also supports using identity fields of type 
+			<classname>byte[]</classname>.  When you use a <classname>byte[]
+			</classname> identity field, you must 
+			create an identity class.  Identity classes are covered below.
+			</para>
+        </note>
+        <warning>
+          <para>
+			Changing the fields of an embeddable instance while it is assigned
+			to an identity field has undefined results.  Always treat 
+			embeddable identity instances as immutable objects in your 
+			applications.
+			</para>
+        </warning>
+        <para><indexterm><primary>identity</primary><secondary>uniqueness requirement</secondary></indexterm><indexterm><primary>uniquness requirement</primary><seealso>identity</seealso></indexterm>
+		If you are dealing with a single persistence context (see
+		<xref linkend="jpa_overview_emfactory_perscontext"/>),
+		then you do not have to compare identity fields to test 
+		whether two entity references represent the same state in the 
+		datastore.  There is a much easier way: the 
+		<literal>==</literal> operator.  JPA requires that 
+		each persistence context maintain only one JVM object to represent 
+		each unique datastore record.  Thus, entity identity is equivalent to 
+		numeric identity within a persistence context.  This is referred to as 
+		the <emphasis>uniqueness requirement</emphasis>. 
+		</para>
+        <para>
+		The uniqueness requirement is extremely important - without it, it
+		would be impossible to maintain data integrity.  Think of what 
+		could happen if two different objects in the same transaction
+		were allowed to represent the same persistent data.  If you made 
+		different modifications to each of these objects, which set of changes 
+		should be written to the datastore?  How would your application logic 
+		handle seeing two different "versions" of the same data?  Thanks to the
+		uniqueness requirement, these questions do not have to be answered.
+		</para>
+        <section id="jpa_overview_pc_identitycls">
+          <title>Identity Class</title>
+          <para><indexterm zone="jpa_overview_pc_identitycls"><primary>identity class</primary><seealso>identity</seealso></indexterm><indexterm zone="jpa_overview_pc_identitycls"><primary>identity</primary><secondary>class requirements</secondary></indexterm>
+			If your entity has only one identity field, you can use the value of
+			that field as the entity's identity object in all 
+			<link linkend="jpa_overview_em"><classname>EntityManager
+			</classname></link> APIs.  Otherwise, you must supply an identity 
+			class to use for identity objects.  Your identity
+			class must meet the following criteria:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>The class must be public.</para>
+            </listitem>
+            <listitem>
+              <para>The class must be serializable.</para>
+            </listitem>
+            <listitem>
+              <para>
+					The class must have a public no-args constructor.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					The names of the non-static fields or properties of the 
+					class must be the same as the names of the identity fields
+					or properties of the corresponding entity class, and the 
+					types must be identical.	
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					The <methodname>equals</methodname> and 
+					<methodname>hashCode</methodname> methods of the class
+					must use the values of all fields or properties 
+					corresponding to identity fields or properties in the 
+					entity class.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					If the class is an inner class, it must be
+					<literal>static</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					All entity classes related by inheritance must use the same
+					identity class, or else each entity class must have its 
+					own identity class whose inheritance hierarchy mirrors the 
+					inheritance hierarchy of the owning entity classes (see 
+					<xref linkend="jpa_overview_pc_identity_hierarchy"/>).
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				Though you may still create identity classes by
+				hand, OpenJPA provides the <classname>appidtool</classname>
+				to automatically generate proper identity classes
+				based on your identity fields.  See
+				<xref linkend="ref_guide_pc_oid_application"/> of the
+				Reference Guide.
+				</para>
+          </note>
+          <example id="jpa_overview_pc_identity_appidcode">
+            <title>Identity Class</title>
+            <para>
+				This example illustrates a proper identity class for an entity
+				with multiple identity fields.
+				</para>
+            <programlisting format="linespecific">
+/**
+ * Persistent class using application identity.
+ */
+public class Magazine
+{
+    private String isbn;    // identity field
+    private String title;   // identity field
+
+    // rest of fields and methods omitted
+
+
+    /**
+     * Application identity class for Magazine.
+     */
+    public static class MagazineId
+    {
+        // each identity field in the Magazine class must have a
+        // corresponding field in the identity class
+        public String isbn;
+        public String title;
+
+        /**
+         * Equality must be implemented in terms of identity field
+         * equality, and must use instanceof rather than comparing 
+         * classes directly (some JPA implementations may subclass the
+         * identity class).
+         */
+        public boolean equals (Object other)
+        {
+            if (other == this)
+                return true;
+            if (!(other instanceof MagazineId))
+                return false;
+    
+            MagazineId mi = (MagazineId) other;
+            return (isbn == mi.isbn
+                || (isbn != null &amp;&amp; isbn.equals (mi.isbn)))
+                &amp;&amp; (title == mi.title
+                || (title != null &amp;&amp; title.equals (mi.title)));
+        }
+     
+        /**
+         * Hashcode must also depend on identity values.
+         */
+        public int hashCode ()
+        {
+            return ((isbn == null) ? 0 : isbn.hashCode ())
+                ^ ((title == null) ? 0 : title.hashCode ());
+        } 
+
+        public String toString ()
+        {
+            return isbn + ":" + title;
+        }
+    }
+}
+</programlisting>
+          </example>
+          <section id="jpa_overview_pc_identity_hierarchy">
+            <title>Identity Hierarchies</title>
+            <indexterm zone="jpa_overview_pc_identity_hierarchy">
+              <primary>identity</primary>
+              <secondary>hierarchy</secondary>
+            </indexterm>
+            <mediaobject>
+              <imageobject>
+<!-- PNG image data, 320 x 267 (see README) -->
+                <imagedata fileref="img/appid-hierarchy.png" width="213px"/>
+              </imageobject>
+            </mediaobject>
+            <para>
+				An alternative to having a single identity
+				class for an entire inheritance hierarchy is to have
+				one identity class per level in the
+				inheritance hierarchy. The requirements for using
+				a hierarchy of identity classes are as follows:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+						The inheritance hierarchy of identity 
+						classes must exactly mirror the hierarchy of the
+						persistent classes that they identify. In the example
+						pictured above, abstract class
+						<classname>Person</classname> is extended by abstract
+						class <classname>Employee</classname>, which is extended
+						by non-abstract class <classname>
+						FullTimeEmployee</classname>, which is extended by
+						non-abstract class <classname>Manager</classname>.
+						The corresponding identity classes, then, are
+						an abstract <classname>PersonId</classname> class,
+						extended by an abstract 
+						<classname>EmployeeId</classname> class, extended by a 
+						non-abstract <classname>FullTimeEmployeeId</classname>
+						class, extended by a non-abstract
+						<classname>ManagerId</classname> class.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						Subclasses in the identity hierarchy
+						may define additional identity fields until
+						the hierarchy becomes non-abstract. In the
+						aforementioned example, <classname>Person</classname>
+						defines an identity field <literal>ssn</literal>,
+						<classname>Employee</classname> defines additional 
+						identity field <literal>userName</literal>, and 
+						<classname>FullTimeEmployee</classname> adds a final
+						identity field, <literal>empId</literal>.  
+						However, <classname>Manager</classname> may not define 
+						any additional identity fields, since it is a 
+						subclass of a non-abstract class.  The hierarchy of
+						identity classes, of course, must match the identity
+						field definitions of the persistent class hierarchy.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						It is not necessary for each abstract class to declare 
+						identity fields.  In the previous example, the 
+						abstract <classname>Person</classname> and 
+						<classname>Employee</classname> classes could declare 
+						no identity fields, and the first concrete subclass 
+						<classname>FullTimeEmployee</classname> could define 
+						one or more identity fields.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						All subclasses of a concrete identity class must
+						be <methodname>equals</methodname> and <methodname>
+						hashCode</methodname>-compatible with the concrete
+						superclass.  This means that in our example, a
+						<classname>ManagerId</classname> instance and a
+						<classname>FullTimeEmployeeId</classname> instance 
+						with the same identity field values should have the
+						same hash code, and should compare equal to each other
+						using the <methodname>equals</methodname> method of
+						either one.  In practice, this requirement reduces to
+						the following coding practices:  
+						</para>
+                <orderedlist>
+                  <listitem>
+                    <para>
+								Use <literal>instanceof</literal> instead of
+								comparing <classname>Class</classname> objects
+								in the <methodname>equals</methodname> methods
+								of your identity classes.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para>
+								An identity class that extends another 
+								non-abstract identity class should not override
+								<methodname>equals</methodname> or 
+								<methodname>hashCode</methodname>.
+								</para>
+                  </listitem>
+                </orderedlist>
+              </listitem>
+            </itemizedlist>
+          </section>
+        </section>
+      </section>
+      <section id="jpa_overview_pc_callbacks">
+        <title>Lifecycle Callbacks</title>
+        <indexterm zone="jpa_overview_pc_callbacks">
+          <primary>lifecycle callbacks</primary>
+        </indexterm>
+        <indexterm zone="jpa_overview_pc_callbacks">
+          <primary>persistent classes</primary>
+          <secondary>lifecycle callbacks</secondary>
+          <seealso>lifecycle callbacks</seealso>
+        </indexterm>
+        <para>
+		It is often necessary to perform various actions at different stages
+		of a persistent object's lifecycle.  JPA includes 
+		a variety of callbacks methods for monitoring changes in the 
+		lifecycle of your persistent objects.  These callbacks can
+		be defined on the persistent classes themselves and
+		on non-persistent listener classes.
+		</para>
+        <section id="jpa_overview_pc_callbacks_methods">
+          <title>Callback Methods</title>
+          <indexterm zone="jpa_overview_pc_callbacks_methods">
+            <primary>lifecycle callbacks</primary>
+            <secondary>callback methods</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_pc_callbacks_methods">
+            <primary>entity</primary>
+            <secondary>callback methods</secondary>
+          </indexterm>
+          <para>
+			Every persistence event has a corresponding callback method
+			marker.  These markers are shared between persistent classes
+			and their listeners.  You can use these markers to designate
+			a method for callback either by annotating that method or by
+			listing the method in the XML mapping file for a given class.
+			The lifecycle events and their corresponding method markers are:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><indexterm><primary>PrePersist</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PrePersist.html"><classname>PrePersist</classname></ulink>:
+					Methods marked with this annotation will be invoked 
+					before an object is persisted.  This could be used for 
+					assigning primary key values to persistent objects.
+					This is equivalent to the XML element tag 
+					<literal>pre-persist</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>PostPersist</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostPersist.html"><classname>PostPersist</classname></ulink>:
+					Methods marked with this annotation will be invoked 
+					after an object has transitioned to the persistent state.  
+					You might want to use such methods to update a screen
+					after a new row is added.  This is equivalent 
+					to the XML element tag <literal>post-persist</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>PostLoad</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostLoad.html"><classname>PostLoad</classname></ulink>:
+					Methods marked with this annotation will be invoked after 
+					all eagerly fetched fields of your class have been
+					loaded from the datastore.  No other persistent fields
+					can be accessed in this method.  This is equivalent 
+					to the XML element tag <literal>post-load</literal>.
+					</para>
+              <para><classname>PostLoad</classname> is often used to
+					initialize non-persistent fields whose values depend 
+					on the values of persistent fields, such as a complex
+					datastructure.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>PreUpdate</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PreUpdate.html"><classname>PreUpdate</classname></ulink>:
+					Methods marked with this annotation will be invoked 
+					just the persistent values in your objects are flushed
+					to the datastore. This is equivalent to the XML element tag 
+					<literal>pre-update</literal>.
+					</para>
+              <para><classname>PreUpdate</classname> is the complement to
+					<classname>PostLoad</classname>.  While methods marked
+					with <classname>PostLoad</classname> are most often used
+					to initialize non-persistent values from persistent data,
+					methods annotated with <classname>PreUpdate</classname>
+					is normally used to set persistent fields with information
+					cached in non-persistent data.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>PostUpdate</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostUpdate.html"><classname>PostUpdate</classname></ulink>:
+					Methods marked with this annotation will be invoked 
+					after changes to a given instance have been stored to the 
+					datastore. This is useful for clearing stale data cached
+					at the application layer.  This is equivalent to the 
+					XML element tag <literal>post-update</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>PreRemove</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PreRemove.html"><classname>PreRemove</classname></ulink>:
+					Methods marked with this annotation will be invoked 
+					before an object transactions to the deleted state.  
+					Access to persistent fields is valid within this method.
+					You might use this method to cascade the deletion to
+					related objects based on complex criteria, or to 
+					perform other cleanup. This is equivalent to the 
+					XML element tag <literal>pre-remove</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>PostRemove</primary><seealso>lifecycle callbacks</seealso></indexterm><ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/PostRemove.html"><classname>PostRemove</classname></ulink>:
+					Methods marked with this annotation will be invoked after 
+					an object has been marked as to be deleted.  This is 
+					equivalent to the XML element tag 
+					<literal>post-remove</literal>.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_callbacks_using">
+          <title>Using Callback Methods</title>
+          <para>
+			When declaring callback methods on a persistent class,
+			any method may be used which takes no arguments and is not
+			shared with any property access fields.  Multiple events
+			can be assigned to a single method as well.
+			</para>
+          <para>
+			Below is an example of how to declare callback methods
+			on persistent classes:
+			</para>
+          <programlisting format="linespecific">
+/**
+ * Example persistent class declaring our entity listener.
+ */
+@Entity
+public class Magazine
+{
+    @Transient 
+    private byte[][] data;
+
+    @ManyToMany
+    private List&lt;Photo&gt; photos;
+
+    @PostLoad
+    public void convertPhotos ()
+    {
+        data = new byte[photos.size ()][];
+        for (int i = 0; i &lt; photos.size (); i++)
+            data[i] = photos.get (i).toByteArray ();
+    }
+
+    @PreDelete
+    public void logMagazineDeletion ()
+    {
+        getLog ().debug ("deleting magazine containing" + photos.size () 
+            + " photos.");
+    }
+}
+
+</programlisting>
+          <para>
+			In an XML mapping file, we can define the same methods 
+			without annotations:
+			</para>
+          <programlisting format="linespecific">
+&lt;entity class="Magazine"&gt;
+    &lt;pre-remove&gt;logMagazineDeletion&lt;/pre-remove&gt;
+    &lt;post-load&gt;convertPhotos&lt;/post-load&gt;
+&lt;/entity&gt;
+</programlisting>
+          <note>
+            <para>
+				We fully explore persistence metadata annotations and XML in 
+				<xref linkend="jpa_overview_meta"/>.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_entity_listeners_using">
+          <title>Using Entity Listeners</title>
+          <para>
+			Mixing lifecycle event code into your persistent classes is not
+			always ideal.  It is often more elegant to handle cross-cutting 
+			lifecycle events in a non-persistent listener class.
+			JPA allows for this, requiring only that listener
+			classes have a public no-arg constructor.  Like persistent 
+			classes, your listener classes can consume any number of callbacks.
+			The callback methods must take in a single 
+			<classname>java.lang.Object</classname> argument which
+			represents the persistent object that triggered the event.
+			</para>
+          <para>
+			Entities can enumerate listeners using the 
+			<classname>EntityListeners</classname> annotation.  This annotation
+			takes an array of listener classes as its value.
+			</para>
+          <para>
+			Below is an example of how to declare an entity and its 
+			corresponding listener classes.
+			</para>
+          <programlisting format="linespecific">
+/**
+ * Example persistent class declaring our entity listener.
+ */
+@Entity
+@EntityListeners({ MagazineLogger.class, ... })
+public class Magazine
+{
+    // ... //
+}
+
+
+/**
+ * Example entity listener.
+ */
+public class MagazineLogger
+{
+    @PostPersist
+    public void logAddition (Object pc)
+    {
+        getLog ().debug ("Added new magazine:" + ((Magazine) pc).getTitle ());
+    }
+
+
+    @PreRemove
+    public void logDeletion (Object pc)
+    {
+        getLog ().debug ("Removing from circulation:" + 
+            ((Magazine) pc).getTitle ());
+    }
+}
+</programlisting>
+          <para>
+			In XML, we define both the listeners and their callback
+			methods as so:
+			</para>
+          <programlisting format="linespecific">
+&lt;entity class="Magazine"&gt;
+    &lt;entity-listeners&gt;
+        &lt;entity-listener class="MagazineLogger"&gt;
+            &lt;post-persist&gt;logAddition&lt;/post-persist&gt;
+            &lt;pre-remove&gt;logDeletion&lt;/pre-remove&gt;
+        &lt;/entity-listener&gt;
+    &lt;/entity-listeners&gt;
+&lt;/entity&gt;
+</programlisting>
+        </section>
+        <section id="jpa_overview_entity_listeners_exclude">
+          <title>Entity Listeners Hierarchy</title>
+          <indexterm zone="jpa_overview_entity_listeners_exclude">
+            <primary>lifecycle listeners</primary>
+            <secondary>hierarchy</secondary>
+          </indexterm>
+          <para>
+			Entity listener methods are invoked in a specific order when a 
+			given event is fired. So-called <emphasis>default</emphasis> 
+			listeners are invoked first: these are listeners
+			which have been defined in a package annotation or in the root 
+			element of XML mapping files.  Next, entity listeners are invoked
+			in the order of the inheritance hierarchy, with superclass listeners
+			being invoked before subclass listeners.  Finally, if an entity has
+			multiple listeners for the same event, the listeners are invoked 
+			in declaration order.
+			</para>
+          <para>
+			You can exclude default listeners and listeners defined in 
+			superclasses from the invocation chain through the use of two 
+			class-level annotations: 
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><classname>ExcludeDefaultListeners</classname>: This
+					annotation indicates that no default listeners will be
+					invoked for this class, or any of its subclasses. The XML
+					equivalent is the empty
+					<literal>exclude-default-listeners</literal> element.
+					</para>
+            </listitem>
+            <listitem>
+              <para><classname>ExcludeSuperclassListeners</classname>: This
+					annotation will cause OpenJPA to skip invoking any listeners
+					declared in superclasses.  The XML equivalent is empty the 
+					<literal>exclude-superclass-listeners</literal> element.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="jpa_overview_pc_conclusion">
+        <title>Conclusions</title>
+        <para>
+		This chapter covered everything you need to know to write persistent
+		class definitions in JPA.  JPA 
+		cannot use your persistent classes, however, until you complete one 
+		additional step: you must define the persistence metadata.  The next 
+		chapter explores metadata in detail.
+		</para>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_meta">
+      <title>Metadata</title>
+      <indexterm zone="jpa_overview_meta">
+        <primary>metadata</primary>
+      </indexterm>
+      <indexterm zone="jpa_overview_meta">
+        <primary>JPA</primary>
+        <secondary>metadata</secondary>
+        <seealso>metadata</seealso>
+      </indexterm>
+      <para>
+	JPA requires that you accompany each persistent class with
+	persistence metadata.  This metadata serves three primary purposes:
+	</para>
+      <orderedlist>
+        <listitem>
+          <para>To identify persistent classes.</para>
+        </listitem>
+        <listitem>
+          <para>To override default JPA behavior.</para>
+        </listitem>
+        <listitem>
+          <para>
+			To provide the JPA implementation with information that
+			it cannot glean from simply reflecting on the persistent class.
+			</para>
+        </listitem>
+      </orderedlist>
+      <para><indexterm><primary>annotations</primary></indexterm>
+	Persistence metadata is specified using either the Java 5 annotations 
+	defined in the <literal>javax.persistence</literal> package, XML
+	mapping files, or a mixture of both.  In the latter case, XML declarations
+	override conflicting annotations.  If you choose to use XML metadata, the 
+	XML files must be available at development and runtime, and must be 
+	discoverable via either of two strategies:
+	</para>
+      <orderedlist>
+        <listitem>
+          <para>
+			In a resource named <filename>orm.xml</filename> placed in
+			the <filename>META-INF</filename> directory of the classpath
+			or the jar archive containing your persistent classes.
+			</para>
+        </listitem>
+        <listitem>
+          <para>
+			Declared in your <link linkend="jpa_overview_persistence_xml"><filename>persistence.xml</filename></link> configuration file.  
+			In this case, each XML metadata file must be 
+			listed in a <literal>mapping-file</literal> element whose 
+			content is either a path to the given file or a resource 
+			location available to the class' class loader.
+			</para>
+        </listitem>
+      </orderedlist>
+      <para>
+	We describe the standard metadata annotations and XML equivalents throughout
+	this chapter.  The full schema for XML mapping files is available in
+	<xref linkend="jpa_overview_meta_xml"/>.
+	JPA also standardizes relational mapping metadata and named 
+	query metadata, which we discuss in <xref linkend="jpa_overview_mapping"/>
+	and <xref linkend="jpa_overview_query_named"/> respectively. 
+	</para>
+      <note>
+        <para>
+		OpenJPA defines many useful annotations beyond the standard set.  See
+		<xref linkend="ref_guide_meta_ejb"/> and 
+		<xref linkend="ref_guide_meta_ext"/> in the Reference Guide for details.
+		<!-- ### EJB -->
+		There are currently no XML equivalents for these extension annotations.
+		</para>
+      </note>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 553 x 580 (see README) -->
+          <imagedata fileref="img/ejb3-meta-model.png" width="369"/>
+        </imageobject>
+      </mediaobject>
+      <para>
+	Through the course of this chapter, we will create the persistent object 
+	model above.
+	</para>
+      <section id="jpa_overview_meta_class">
+        <title>Class Metadata</title>
+        <para>
+		The following metadata annotations and XML elements apply to persistent
+		class declarations.
+		</para>
+        <section id="jpa_overview_meta_entity">
+          <title>Entity</title>
+          <indexterm zone="jpa_overview_meta_entity">
+            <primary>Entity</primary>
+            <secondary>annotation</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity">
+            <primary>metadata</primary>
+            <secondary>Entity</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity">
+            <primary>annotations</primary>
+            <secondary>Entity</secondary>
+          </indexterm>
+          <para>
+			The <classname>Entity</classname> annotation denotes an entity 
+			class.  All entity classes must have this annotation.  The 
+			<classname>Entity</classname> annotation takes one optional 
+			property:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: Name used to refer to the 
+					entity in queries. Must not be a reserved literal 
+					in JPQL.  Defaults to the unqualified name of the entity 
+					class.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>entity</literal>.  It has
+			the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: The entity class.  This attribute
+					is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>name</literal>: Named used to refer to the class in
+					queries.  See the name property above.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal>: The access type to use for the
+					class.  Must either be <literal>FIELD</literal> or
+					<literal>PROPERTY</literal>.  For details on access 
+					types, see <xref linkend="jpa_overview_meta_field"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				OpenJPA uses a process called <emphasis>enhancement</emphasis> to
+				modify the bytecode of entities for transparent
+				lazy loading and immediate dirty tracking.  See 
+				<xref linkend="ref_guide_pc_enhance"/> in the Reference Guide
+				for details on enhancement.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_idclass">
+          <title>Id Class</title>
+          <indexterm zone="jpa_overview_meta_idclass">
+            <primary>IdClass</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_idclass">
+            <primary>metadata</primary>
+            <secondary>IdClass</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_idclass">
+            <primary>annotations</primary>
+            <secondary>IdClass</secondary>
+          </indexterm>
+          <para>
+			As we discussed in <xref linkend="jpa_overview_pc_identitycls"/>,
+			entities with multiple identity fields must use an <emphasis>
+			identity class</emphasis> to encapsulate their persistent identity.
+			The <classname>IdClass</classname> annotation specifies this class.
+			It accepts a single <classname>java.lang.Class</classname> value.
+			</para>
+          <para>
+			The equivalent XML element is <literal>id-class</literal>, which has
+			a single attribute:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: This required attribute lists
+					the class name for the identity class.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_embeddablesuper">
+          <title>Mapped Superclass</title>
+          <indexterm zone="jpa_overview_meta_embeddablesuper">
+            <primary>MappedSuperclass</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddablesuper">
+            <primary>metadata</primary>
+            <secondary>MappedSuperclass</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddablesuper">
+            <primary>annotations</primary>
+            <secondary>MappedSuperclass</secondary>
+          </indexterm>
+          <para>
+			A <emphasis>mapped superclass</emphasis> is a non-entity
+			class that can define persistent state and mapping information for
+			entity subclasses.  Mapped superclasses are usually abstract.
+			Unlike true entities, you cannot query a mapped superclass, 
+			pass a mapped superclass instance to any 
+			<classname>EntityManager</classname> or <classname>Query</classname>
+			methods, or declare a persistent relation with a mapped 
+			superclass target.  
+			You denote a mapped superclass with the <classname>MappedSuperclass
+			</classname> marker annotation.
+			</para>
+          <para>	
+			The equivalent XML element is <literal>mapped-superclass</literal>.
+			It expects the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: The entity class.  This attribute
+					is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal>: The access type to use for the
+					class.  Must either be <literal>FIELD</literal> or
+					<literal>PROPERTY</literal>.  For details on access 
+					types, see <xref linkend="jpa_overview_meta_field"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				OpenJPA allows you to query on mapped superclasses.  A
+				query on a mapped superclass will return all matching
+				subclass instances.  OpenJPA also allows you to declare relations
+				to mapped superclass types; however, you cannot query across
+				these relations.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_embeddable">
+          <title>Embeddable</title>
+          <indexterm zone="jpa_overview_meta_embeddable">
+            <primary>Embeddable</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddable">
+            <primary>metadata</primary>
+            <secondary>Embeddable</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddable">
+            <primary>annotations</primary>
+            <secondary>Embeddable</secondary>
+          </indexterm>
+          <para>
+			The <classname>Embeddable</classname> annotation designates an 
+			embeddable persistent class.  Embeddable instances are stored as
+			part of the record of their owning instance.  All embeddable 
+			classes must have this annotation.
+			</para>
+          <para>
+			A persistent class can either be an entity or an embeddable class,
+			but not both.
+			</para>
+          <para>
+			The equivalent XML element is <literal>embeddable</literal>.
+			It understands the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: The entity class.  This attribute
+					is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal>: The access type to use for the
+					class.  Must either be <literal>FIELD</literal> or
+					<literal>PROPERTY</literal>.  For details on access 
+					types, see <xref linkend="jpa_overview_meta_field"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				OpenJPA allows a persistent class to be both an entity and
+				an embeddable class.  Instances of the class will act as 
+				entites when persisted explicitly or assigned to non-embedded
+				fields of entities.  Instances will act as embedded values
+				when assigned to embedded fields of entities.
+				</para>
+            <para>
+				To signal that a class is both an entity and an embeddable class
+				in OpenJPA, simply add both the <literal>@Entity</literal> and the
+				<literal>@Embeddable</literal> annotations to the class.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_entity_listeners">
+          <title>EntityListeners</title>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>EntityListeners</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>entity-listeners</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>metadata</primary>
+            <secondary>EntityListeners</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>annotations</primary>
+            <secondary>EntityListeners</secondary>
+          </indexterm>
+          <para>
+			An entity may list its lifecycle event listeners
+			in the <classname>EntityListeners</classname> annotation.
+			This value of this annotation is an array of the listener 
+			<classname>Class</classname>es for the entity.
+			The equivalent XML element is <literal>entity-listeners</literal>.
+			For more details on entity listeners, see
+			<xref linkend="jpa_overview_pc_callbacks"/>.
+			</para>
+        </section>
+        <section id="jpa_overview_meta_classex">
+          <title>Example</title>
+          <para>
+			Here are the class declarations for our persistent object model,
+			annotated with the appropriate persistence metadata.  Note that
+			<classname>Magazine</classname> declares an identity class, and
+			that <classname>Document</classname> and <classname>Address
+			</classname> are a mapped superclass and an embeddable class, 
+			respectively. <classname>LifetimeSubscription</classname> and
+			<classname>TrialSubscription</classname> override the default
+			entity name to supply a shorter alias for use in queries.
+			</para>
+          <example id="jpa_overview_meta_classlisting">
+            <title>Class Metadata</title>
+            <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+public class Magazine
+{
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+public class Article
+{
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+public class Company
+{
+    ...
+}
+
+@Entity
+public class Author
+{
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    ...
+}
+
+@Entity
+public class Contract
+    extends Document
+{
+    ...
+}
+
+@Entity
+public class Subscription
+{
+    ...
+
+    @Entity
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+
+@Entity(name="Trial")
+public class TrialSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+            <para>
+				The equivalent declarations in XML:
+				</para>
+            <programlisting format="linespecific">
+&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
+    version="1.0"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        ...
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;id-class class="org.mag.Magazine$MagazineId"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Contract"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LineItem"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;embeddable class="org.mag.pub.Address"&gt;
+        ...
+    &lt;/embeddable&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_overview_meta_field">
+        <title>Field and Property Metadata</title>
+        <para>
+		The persistence implementation must be able to retrieve and set the 
+		persistent state of your entities, mapped superclasses, and 
+		embeddable types.  JPA offers two modes of
+		persistent state access: <emphasis>field access</emphasis>, and
+		<emphasis>property access</emphasis>.  Under field access, the 
+		implementation injects state directly into your persistent fields, and 
+		retrieves changed state from your fields as well.  To declare field 
+		access on an entity with XML metadata, set the <literal>access
+		</literal> attribute of your <literal>entity</literal> XML element to 
+		<literal>FIELD</literal>.  To use field access for an entity using
+		annotation metadata, simply place your metadata and mapping annotations
+		on your field declarations:
+		</para>
+        <programlisting format="linespecific">
+@ManyToOne
+private Company publisher;
+</programlisting>
+        <para><indexterm><primary>metadata</primary><secondary>property access</secondary></indexterm><indexterm><primary>persistent classes</primary><secondary>property access</secondary></indexterm><indexterm><primary>persistent properties</primary><seealso>persistent fields</seealso></indexterm>
+		Property access, on the other hand, retrieves and loads state through 
+		JavaBean "getter" and "setter" methods.  For a property 
+		<literal>p</literal> of type <literal>T</literal>, you must define the 
+		following getter method:
+		</para>
+        <programlisting format="linespecific">
+T getP ();
+</programlisting>
+        <para>
+		For boolean properties, this is also acceptable:
+		</para>
+        <programlisting format="linespecific">
+boolean isP ();
+</programlisting>
+        <para>
+		You must also define the following setter method:
+		</para>
+        <programlisting format="linespecific">
+void setP (T value);
+</programlisting>
+        <para>
+		To use property access, set your <literal>entity</literal> element's 
+		<literal>access</literal> attribute to <literal>PROPERTY</literal>, or
+		place your metadata and mapping annotations on the getter method:
+		</para>
+        <programlisting format="linespecific">
+@ManyToOne
+private Company getPublisher () { ... }
+
+private void setPublisher (Company publisher) { ... }
+</programlisting>
+        <warning>
+          <para>
+			When using property access, only the getter and setter method for
+			a property should ever access the underlying persistent field
+			directly.  Other methods, including internal business methods in
+			the persistent class, should go through the getter and setter 
+			methods when manipulating persistent state.
+			</para>
+          <para>
+			Also, take care when adding business logic to your 
+			getter and setter methods.  Consider that they are invoked by the 
+			persistence implementation to load and retrieve all persistent 
+			state; other side effects might not be desirable.
+			</para>
+        </warning>
+        <para>
+		Each class must use either field access or property access for all 
+		state; you cannot use both access types within the same class.  
+		Additionally, a subclass must use the same access type as its 
+		superclass.	
+		</para>
+        <para>
+		The remainder of this document uses the term
+		"persistent field" to refer to either a persistent field or a 
+		persistent property.
+		</para>
+        <section id="jpa_overview_meta_transient">
+          <title>Transient</title>
+          <indexterm zone="jpa_overview_meta_transient">
+            <primary>Transient</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_transient">
+            <primary>metadata</primary>
+            <secondary>Transient</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_transient">
+            <primary>annotations</primary>
+            <secondary>Transient</secondary>
+          </indexterm>
+          <para>
+			The <classname>Transient</classname> annotation specifies that a
+			field is non-persistent.  Use it to exclude fields from management
+			that would otherwise be persistent.  <classname>
+			Transient</classname> is a marker annotation only; it has no
+			properties.
+			</para>
+          <para>
+			The equivalent XML element is <literal>transient</literal>.  It
+			has a single attribute:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The transient field or property 
+					name.  This attribute is required.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_id">
+          <title>Id</title>
+          <indexterm zone="jpa_overview_meta_id">
+            <primary>Id</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_id">
+            <primary>metadata</primary>
+            <secondary>Id</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_id">
+            <primary>annotations</primary>
+            <secondary>Id</secondary>
+          </indexterm>
+          <para>
+			Annotate your simple identity fields with <classname>Id</classname>.
+			This annotation has no properties.  We explore entity identity and 
+			identity fields in <xref linkend="jpa_overview_pc_id"/>.  
+			</para>
+          <para>
+			The equivalent XML element is <literal>id</literal>.  It has one 
+			required attribute:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the identity field or
+					property.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_gen">
+          <title>Generated Value</title>
+          <indexterm zone="jpa_overview_meta_gen">
+            <primary>GeneratedValue</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_gen">
+            <primary>metadata</primary>
+            <secondary>GeneratedValue</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_gen">
+            <primary>annotations</primary>
+            <secondary>GeneratedValue</secondary>
+          </indexterm>
+          <para>
+			The previous section showed you how to declare your identity
+			fields with the <classname>Id</classname> annotation.  It is often
+			convenient to allow the persistence implementation to assign a 
+			unique value to your identity fields automatically.  JPA 
+			includes the the <classname>GeneratedValue</classname> 
+			annotation for this purpose.  You can only apply the <classname>
+			GeneratedValue</classname> annotation to numeric fields.  It has 
+			the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>GenerationType strategy</literal>: Enum value
+					specifying how to auto-generate the field value.
+					The <classname>GenerationType</classname> enum has the 
+					following values:
+					</para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>GeneratorType.AUTO</literal>: The default.
+							Assign the field a generated value, leaving the 
+							details to the JPA vendor.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>GenerationType.IDENTITY</literal>: The
+							database will assign an identity value on insert.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>GenerationType.SEQUENCE</literal>: Use a
+							datastore sequence to generate a field value.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>GenerationType.TABLE</literal>: Use a
+							sequence table to generate a field value.
+							</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para><literal>String generator</literal>: The name of a 
+					generator defined in mapping metadata.  We show you how
+					to define named generators in 
+					<xref linkend="jpa_overview_mapping_sequence"/>.
+					If the <classname>GenerationType</classname> is set but 
+					this property is unset, the JPA implementation 
+					uses appropriate defaults for the selected generation type.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>generated-value</literal>,
+			which includes the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>strategy</literal>: One of <literal>
+					TABLE</literal>, <literal>SEQUENCE</literal>, <literal>
+					IDENTITY</literal>, or <literal>AUTO</literal>, defaulting 
+					to <literal>AUTO</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>generator</literal>: Equivalent to the generator
+					property listed above.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				OpenJPA allows you to use the <classname>GeneratedValue</classname>
+				annotation on any field, not just identity fields.
+				Before using the <literal>IDENTITY</literal> generation 
+				strategy, however, read 
+				<xref linkend="ref_guide_pc_oid_pkgen_autoinc"/>
+				in the Reference Guide.  
+				</para>
+            <para>
+				OpenJPA also offers two additional 
+				generator strategies for non-numeric fields, which you can 
+				access by setting <literal>strategy</literal> to 
+				<literal>AUTO</literal> (the default), and setting
+				the <literal>generator</literal> string to:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><indexterm><primary>mapping metadata</primary><secondary>uuid-string</secondary></indexterm><indexterm><primary>uuid-string</primary></indexterm><literal>uuid-string</literal>: OpenJPA will generate a 
+						128-bit UUID unique
+						within the network, represented as a 16-character 
+						string.  For more information on UUIDs, see the IETF 
+						UUID draft specification at:
+						<ulink url="http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/"> 
+						http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/
+						</ulink></para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>mapping metadata</primary><secondary>uuid-hex</secondary></indexterm><indexterm><primary>uuid-hex</primary></indexterm><literal>uuid-hex</literal>: Same as <literal>
+						uuid-string</literal>, but represents the UUID as
+						a 32-character hexadecimal string.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				These string constants are defined in
+				<ulink url="../../api/openjpa/persistence/Generator.html"><classname>org.apache.openjpa.persistence.Generator</classname></ulink>.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_embedid">
+          <title>Embedded Id</title>
+          <indexterm zone="jpa_overview_meta_embedid">
+            <primary>EmbeddedId</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedid">
+            <primary>metadata</primary>
+            <secondary>EmbeddedId</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedid">
+            <primary>annotations</primary>
+            <secondary>EmbeddedId</secondary>
+          </indexterm>
+          <para>
+			If your entity has multiple identity values, you may declare 
+			multiple <literal>@Id</literal> fields, or you may declare a single 
+			<literal>@EmbeddedId</literal> field.  The type of a field 
+			annotated with <classname>EmbeddedId</classname> must be an
+			embeddable entity class.  The fields of this embeddable class are 
+			considered the identity values of the owning entity.  We explore 
+			entity identity and identity fields in 
+			<xref linkend="jpa_overview_pc_id"/>.  
+			</para>
+          <para>
+			The <classname>EmbeddedId</classname> annotation has no properties.
+			</para>
+          <para>
+			The equivalent XML element is <literal>embedded-id</literal>.  It 
+			has one required attribute:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the identity field or
+					property.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_version">
+          <title>Version</title>
+          <indexterm zone="jpa_overview_meta_version">
+            <primary>Version</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_version">
+            <primary>metadata</primary>
+            <secondary>Version</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_version">
+            <primary>annotations</primary>
+            <secondary>Version</secondary>
+          </indexterm>
+          <para>
+			Use the <classname>Version</classname> annotation to designate a
+			version field.  <xref linkend="jpa_overview_pc_version"/> 
+			explained the importance of version fields to JPA.
+			This is a marker annotation; it has no properties.
+			</para>
+          <para>
+			The equivalent XML element is <literal>version</literal>, which 
+			has a single attribute:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the version field or
+					property.  This attribute is required.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_basic">
+          <title>Basic</title>
+          <indexterm zone="jpa_overview_meta_basic">
+            <primary>Basic</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_basic">
+            <primary>metadata</primary>
+            <secondary>Basic</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_basic">
+            <primary>annotations</primary>
+            <secondary>Basic</secondary>
+          </indexterm>
+          <para><classname>Basic</classname> signifies a standard value persisted
+			as-is to the datastore.  You can use the <classname>Basic
+			</classname> annotation on persistent fields of the following types:
+			primitives, primitive wrappers,
+			<classname>java.lang.String</classname>,
+			<classname>byte[]</classname>, 
+			<classname>Byte[]</classname>,
+			<classname>char[]</classname>, 
+			<classname>Character[]</classname>,
+			<classname>java.math.BigDecimal</classname>,
+			<classname>java.math.BigInteger</classname>,
+			<classname>java.util.Date</classname>,
+			<classname>java.util.Calendar</classname>,
+			<classname>java.sql.Date</classname>, 
+			<classname>java.sql.Timestamp</classname>,
+			<classname>Enum</classname>s, and 
+			<classname>Serializable</classname> types.
+			</para>
+          <para><classname>Basic</classname> declares these properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					field eagerly (<literal>FetchType.EAGER</literal>) or 
+					lazily (<literal>FetchType.LAZY</literal>).
+					Defaults to <literal>FetchType.EAGER</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>: Whether the datastore
+					allows null values.  Defaults to true.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>basic</literal>.  It has
+			the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+					This attribute is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+					or<literal>LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>optional</literal>: Boolean indicating whether the
+					field value may be null.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <section id="jpa_overview_meta_fetch">
+            <title>Fetch Type</title>
+            <indexterm zone="jpa_overview_meta_fetch">
+              <primary>eager fetching</primary>
+              <secondary>FetchType</secondary>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_fetch">
+              <primary>FetchType</primary>
+              <seealso>eager fetching</seealso>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_fetch">
+              <primary>metadata</primary>
+              <secondary>FetchType</secondary>
+            </indexterm>
+            <para>
+				Many metadata annotations in JPA have a 
+				<literal>fetch</literal> property.  This property can take
+				on one of two values: <literal>FetchType.EAGER</literal> or
+				<literal>FetchType.LAZY</literal>.  <literal>FetchType.EAGER
+				</literal> means that the field is loaded by the JPA
+				implementation before it returns the persistent object to you.
+				Whenever you retrieve an entity from a query or from the
+				<classname>EntityManager</classname>, you are guaranteed that
+				all of its eager fields are populated with datastore data.
+				</para>
+            <para><literal>FetchType.LAZY</literal> is a hint to the JPA runtime
+				that you want to defer loading of the field until you access it.
+				This is called <emphasis>lazy loading</emphasis>.  Lazy loading
+				is completely transparent; when you attempt to read the field
+				for the first time, the JPA runtime will load the value from the
+				datastore and populate the field automatically.  Lazy loading
+				is only a hint and not a directive because some JPA
+				implementations cannot lazy-load certain field types.
+				</para>
+            <para>
+				With a mix of eager and lazily-loaded fields, you can ensure
+				that commonly-used fields load efficiently, and that other
+				state loads transparently when accessed.  As you will see
+				in <xref linkend="jpa_overview_emfactory_perscontext"/>, 
+				you can also use eager fetching to ensure that entites have
+				all needed data loaded before they become <emphasis>detached
+				</emphasis> at the end of a persistence context. 
+				</para>
+            <note>
+              <para>
+					OpenJPA can lazy-load any field type.  OpenJPA also allows you
+					to dynamically change which fields are eagerly or lazily
+					loaded at runtime.  See <xref linkend="ref_guide_fetch"/>
+					in the Reference Guide for details.
+					</para>
+              <para>
+					The Reference Guide details OpenJPA's eager fetching
+					behavior in <xref linkend="ref_guide_perfpack_eager"/>.
+					</para>
+            </note>
+          </section>
+        </section>
+        <section id="jpa_overview_meta_embedded">
+          <title>Embedded</title>
+          <indexterm zone="jpa_overview_meta_embedded">
+            <primary>Embedded</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedded">
+            <primary>metadata</primary>
+            <secondary>Embedded</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedded">
+            <primary>annotations</primary>
+            <secondary>Embedded</secondary>
+          </indexterm>
+          <para>
+			Use the <classname>Embedded</classname> marker annotation on 
+			embeddable field types.  Embedded fields are mapped as part of the 
+			datastore record of the declaring entity.  In our sample model, 
+			<classname>Author</classname> and <classname>Company</classname> 
+			each embed their <classname>Address</classname>, rather than 
+			forming a relation to an <classname>Address</classname> as a 
+			separate entity.
+			</para>
+          <para>
+			The equivalent XML element is <literal>embedded</literal>, which
+			expects a single attribute:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+					This attribute is required.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_manytoone">
+          <title>Many To One</title>
+          <indexterm zone="jpa_overview_meta_manytoone">
+            <primary>ManyToOne</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytoone">
+            <primary>metadata</primary>
+            <secondary>ManyToOne</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytoone">
+            <primary>annotations</primary>
+            <secondary>ManyToOne</secondary>
+          </indexterm>
+          <para>
+			When an entity <literal>A</literal> references a single entity
+			<literal>B</literal>, and other <literal>A</literal>s might also
+			reference the same <literal>B</literal>, we say there is a 
+			<emphasis>many to one</emphasis> relation from 
+			<literal>A</literal> to <literal>B</literal>.
+			In our sample model, for example, each magazine has a reference to 
+			its publisher.  Multiple magazines might have the same publisher.
+			We say, then, that the <literal>Magazine.publisher</literal> field
+			is a many to one relation from magazines to publishers.
+			</para>
+          <para>
+			JPA indicates many to one relations between 
+			entities with the <classname>ManyToOne</classname> annotation.
+			This annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+					related entity type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+					values defining cascade behavior for this field.  We
+					explore cascades below.  Defaults to an empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					field eagerly (<literal>FetchType.EAGER</literal>) or 
+					lazily (<literal>FetchType.LAZY</literal>).
+					Defaults to <literal>FetchType.EAGER</literal>.
+					See <xref linkend="jpa_overview_meta_fetch"/> above
+					for details on fetch types.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>:  Whether the related
+					object must exist.  If <literal>false</literal>, this
+					field cannot be null.  Defaults to <literal>true</literal>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>many-to-one</literal>.  It
+			accepts the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+					This attribute is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+					type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+					or<literal>LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>optional</literal>: Boolean indicating whether the
+					field value may be null.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <section id="jpa_overview_meta_cascade">
+            <title>Cascade Type</title>
+            <indexterm zone="jpa_overview_meta_cascade">
+              <primary>CascadeType</primary>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_cascade">
+              <primary>metadata</primary>
+              <secondary>CascadeType</secondary>
+            </indexterm>
+            <para>
+				We introduce the JPA <classname>EntityManager
+				</classname> in <xref linkend="jpa_overview_em"/>.
+				The <classname>EntityManager</classname> has APIs to persist
+				new entities, remove (delete) existing entities,
+				refresh entity state from the datastore, and merge <emphasis>
+				detached</emphasis> entity state back into the persistence
+				context.  We explore all of these APIs in detail later in the 
+				overview.
+				</para>
+            <para>
+				When the <classname>EntityManager</classname> is performing the
+				above operations, you can instruct it to automatically cascade 
+				the operation to the entities held in a persistent field with
+				the <literal>cascade</literal> property of your metadata 
+				annotation.  This process is recursive.  The <literal>cascade
+				</literal> property accepts an array of <classname>CascadeType
+				</classname> enum values. 
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>CascadeType.PERSIST</literal>: When persisting
+						an entity, also persist the entities held in this field.
+						We suggest liberal application of this cascade rule, 
+						because if the <classname>EntityManager</classname>
+						finds a field that references a new entity
+						during flush, and the field does not use
+						<literal>CascadeType.PERSIST</literal>, it is an error.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>CascadeType.REMOVE</literal>: When deleting
+						an entity, also delete the entities held in this field.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>CascadeType.REFRESH</literal>: When refreshing
+						an entity, also refresh the entities held in this field.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>CascadeType.MERGE</literal>: When merging
+						entity state, also merge the entities held in this 
+						field.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para><classname>CascadeType</classname> defines one additional value,
+				<literal>CascadeType.ALL</literal>, that acts as a shortcut for
+				all of the values above.  The following annotations are 
+				equivalent:
+				</para>
+            <programlisting format="linespecific">
+@ManyToOne(cascade={CascadeType.PERSIST,CascadeType.REMOVE,
+    CascadeType.REFRESH,CascadeType.MERGE})
+private Company publisher;
+</programlisting>
+            <programlisting format="linespecific">
+@ManyToOne(cascade=CascadeType.ALL)
+private Company publisher;
+</programlisting>
+            <para>
+				In XML, these enumeration constants are available as child 
+				elements of the <literal>cascade</literal> element.  The
+				<literal>cascade</literal> element is itself a child of	
+				<literal>many-to-one</literal>.  The following examples are 
+				equivalent:
+				</para>
+            <programlisting format="linespecific">
+&lt;many-to-one name="publisher"&gt;
+    &lt;cascade&gt;
+        &lt;cascade-persist/&gt;
+        &lt;cascade-merge/&gt;
+        &lt;cascade-remove/&gt;
+        &lt;cascade-refresh/&gt;
+    &lt;/cascade&gt;
+&lt;/many-to-one&gt;
+</programlisting>
+            <programlisting format="linespecific">
+&lt;many-to-one name="publisher"&gt;
+    &lt;cascade&gt;
+        &lt;cascade-all/&gt;
+    &lt;/cascade&gt;
+&lt;/many-to-one&gt;
+</programlisting>
+          </section>
+        </section>
+        <section id="jpa_overview_meta_onetomany">
+          <title>One To Many</title>
+          <indexterm zone="jpa_overview_meta_onetomany">
+            <primary>OneToMany</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetomany">
+            <primary>metadata</primary>
+            <secondary>OneToMany</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetomany">
+            <primary>annotations</primary>
+            <secondary>OneToMany</secondary>
+          </indexterm>
+          <para>
+			When an entity <literal>A</literal> references multiple
+			<literal>B</literal> entities, and no two <literal>A</literal>s 
+			reference the same <literal>B</literal>, we say there is a 
+			<emphasis>one to many</emphasis> relation from 
+			<literal>A</literal> to <literal>B</literal>.
+			</para>
+          <para>
+			One to many relations are the exact inverse of the many to one
+			relations we detailed in the preceding section.  In that
+			section, we said that the <literal>Magazine.publisher</literal> 
+			field is a many to one relation from magazines to publishers.  
+			Now, we see that the <literal>Company.mags</literal> field is 
+			the inverse - a one to many relation from publishers to 
+			magazines.  Each company may publish multiple magazines, but each
+			magazine can have only one publisher.
+			</para>
+          <para>
+			JPA indicates one to many relations between 
+			entities with the <classname>OneToMany</classname> annotation.
+			This annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+					related entity type.  This information is usually taken 
+					from the parameterized collection or map element type.  
+					You must supply it explicitly, however, if your field isn't
+					a parameterized type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the many to one
+					field in the related entity that maps this bidirectional 
+					relation.  We explain bidirectional relations below.
+					Leaving this property unset signals that this is a standard 
+					unidirectional relation.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+					values defining cascade behavior for the collection 
+					elements.  We explore cascades above in
+					<xref linkend="jpa_overview_meta_cascade"/>.  Defaults to 
+					an empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					field eagerly (<literal>FetchType.EAGER</literal>) or 
+					lazily (<literal>FetchType.LAZY</literal>).
+					Defaults to <literal>FetchType.LAZY</literal>.
+					See <xref linkend="jpa_overview_meta_fetch"/> above
+					for details on fetch types.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>one-to-many</literal>, which
+			includes the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+					This attribute is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+					type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+					or<literal>LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>mapped-by</literal>: The name of the field or 
+					property that owns the relation.  See 
+					<xref linkend="jpa_overview_meta_field"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			You may also nest the <literal>cascade</literal> element within
+			a <literal>one-to-many</literal> element.
+			</para>
+          <section id="jpa_overview_meta_mappedby">
+            <title>Bidirectional Relations</title>
+            <indexterm zone="jpa_overview_meta_mappedby">
+              <primary>bidirectional relations</primary>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_mappedby">
+              <primary>mappedBy</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_mappedby">
+              <primary>mapping metadata</primary>
+              <seealso>mappedBy property</seealso>
+            </indexterm>
+            <para>
+				When two fields are logical inverses of each other, they form 
+				a <emphasis>bidirectional relation</emphasis>.  Our model 
+				contains two bidirectional relations: 
+				<literal>Magazine.publisher</literal> and 
+				<literal>Company.mags</literal> form one bidirectional relation,
+				and <literal>Article.authors</literal> and 
+				<literal>Author.articles</literal> form the other.  In both
+				cases, there is a clear link between the two fields that form
+				the relationship.  A magazine refers to its publisher while 
+				the publisher refers to all its published magazines.  An
+				article refers to its authors while each author refers to her
+				written articles.
+				</para>
+            <para>
+				When the two fields of a bidirectional relation share the same 
+				datastore mapping, JPA formalizes the 
+				connection with the <literal>mappedBy</literal> property. 
+				Marking <literal>Company.mags</literal> as <literal>mappedBy
+				</literal> <literal>Magazine.publisher</literal> means two
+				things:
+				</para>
+            <orderedlist>
+              <listitem>
+                <para><literal>Company.mags</literal> uses the datastore
+						mapping for <literal>Magazine.publisher</literal>, but
+						inverses it.  In fact, it is illegal to specify 
+						any additional mapping information when you use the
+						<literal>mappedBy</literal> property.  All mapping
+						information is read from the referenced field.
+						We explore mapping in depth in 
+						<xref linkend="jpa_overview_mapping"/>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>Magazine.publisher</literal> is the
+						"owner" of the relation.  The field that specifies the
+						mapping data is always the owner.  This means that
+						changes to the <literal>Magazine.publisher</literal>
+						field are reflected in the datastore, while changes to
+						the <literal>Company.mags</literal> field alone are
+						not.  Changes to <literal>Company.mags</literal> may
+						still affect the JPA implementation's 
+						cache, however.  Thus, it is very important that you 
+						keep your object model consistent by properly 
+						maintaining both sides of your bidirectional relations 
+						at all times.
+						</para>
+              </listitem>
+            </orderedlist>
+            <para>
+				You should always take advantage of the <literal>mappedBy
+				</literal> property rather than mapping each field of a 
+				bidirectional relation independently.  Failing to do so may
+				result in the JPA implementation trying to update 
+				the database with conflicting data.  Be careful to only mark 
+				one side of the relation as <literal>mappedBy</literal>, 
+				however.  One side has to actually do the mapping!
+				</para>
+            <note>
+              <para>
+					You can configure OpenJPA to automatically synchronize both
+					sides of a bidirectional relation, or to perform various
+					actions when it detects inconsistent relations.  See
+					<xref linkend="ref_guide_inverses"/> in the Reference Guide
+					for details.
+					</para>
+            </note>
+          </section>
+        </section>
+        <section id="jpa_overview_meta_onetoone">
+          <title>One To One</title>
+          <indexterm zone="jpa_overview_meta_onetoone">
+            <primary>OneToOne</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetoone">
+            <primary>metadata</primary>
+            <secondary>OneToOne</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetoone">
+            <primary>annotations</primary>
+            <secondary>OneToOne</secondary>
+          </indexterm>
+          <para>
+			When an entity <literal>A</literal> references a single entity
+			<literal>B</literal>, and no other <literal>A</literal>s can 
+			reference the same <literal>B</literal>, we say there is a 
+			<emphasis>one to one</emphasis> relation between  
+			<literal>A</literal> and <literal>B</literal>.
+			In our sample model, <classname>Magazine</classname> has a one to
+			one relation to <classname>Article</classname> through the 
+			<literal>Magazine.coverArticle</literal> field.
+			No two magazines can have the same cover article.
+			</para>
+          <para>
+			JPA indicates one to one relations between 
+			entities with the <classname>OneToOne</classname> annotation.
+			This annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+					related entity type.  This information is usually taken 
+					from the field type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the field in the
+					related entity that maps this bidirectional relation.  We
+					explain bidirectional relations in
+					<xref linkend="jpa_overview_meta_mappedby"/> above.  
+					Leaving this property unset signals that this is a standard 
+					unidirectional relation.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+					values defining cascade behavior for this field.  We
+					explore cascades in 
+					<xref linkend="jpa_overview_meta_cascade"/> above.  
+					Defaults to an empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					field eagerly (<literal>FetchType.EAGER</literal>) or 
+					lazily (<literal>FetchType.LAZY</literal>).
+					Defaults to <literal>FetchType.EAGER</literal>.
+					See <xref linkend="jpa_overview_meta_fetch"/> above
+					for details on fetch types.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>:  Whether the related
+					object must exist.  If <literal>false</literal>, this
+					field cannot be null.  Defaults to <literal>true</literal>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>one-to-one</literal> which
+			understands the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+					This attribute is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+					type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+					or<literal>LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>mapped-by</literal>: The field that owns the 
+					relation.  See <xref linkend="jpa_overview_meta_field"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			You may also nest the <literal>cascade</literal> element within
+			a <literal>one-to-one</literal> element.
+			</para>
+        </section>
+        <section id="jpa_overview_meta_manytomany">
+          <title>Many To Many</title>
+          <indexterm zone="jpa_overview_meta_manytomany">
+            <primary>ManyToMany</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytomany">
+            <primary>metadata</primary>
+            <secondary>ManyToMany</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytomany">
+            <primary>annotations</primary>
+            <secondary>ManyToMany</secondary>
+          </indexterm>
+          <para>
+			When an entity <literal>A</literal> references multiple 
+			<literal>B</literal> entities, and other <literal>A</literal>s 
+			might reference some of the same <literal>B</literal>s, we say 
+			there is a <emphasis>many to many</emphasis> relation between 
+			<literal>A</literal> and <literal>B</literal>.
+			In our sample model, for example, each article has a reference to 
+			all the authors that contributed to the article.  Other articles
+			might have some of the same authors.
+			We say, then, that <classname>Article</classname> and 
+			<classname>Author</classname> have a many to many relation
+			through the <literal>Article.authors</literal> field.  
+			</para>
+          <para>
+			JPA indicates many to many relations between 
+			entities with the <classname>ManyToMany</classname> annotation.
+			This annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+					related entity type.  This information is usually taken 
+					from the parameterized collection or map element type.  
+					You must supply it explicitly, however, if your field 
+					isn't a parameterized type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the many to many
+					field in the related entity that maps this 
+					bidirectional relation.  
+					We explain bidirectional relations in
+					<xref linkend="jpa_overview_meta_mappedby"/> above.  
+					Leaving this property unset signals that this is a standard 
+					unidirectional relation.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+					values defining cascade behavior for the collection 
+					elements.  We explore cascades above in
+					<xref linkend="jpa_overview_meta_cascade"/>.  Defaults to 
+					an empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					field eagerly (<literal>FetchType.EAGER</literal>) or 
+					lazily (<literal>FetchType.LAZY</literal>).
+					Defaults to <literal>FetchType.LAZY</literal>.
+					See <xref linkend="jpa_overview_meta_fetch"/> above
+					for details on fetch types.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>many-to-many</literal>.  It
+			accepts the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+					This attribute is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+					type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+					or<literal>LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>mapped-by</literal>: The field that owns the 
+					relation.  See <xref linkend="jpa_overview_meta_field"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			You may also nest the <literal>cascade</literal> element within
+			a <literal>many-to-many</literal> element.
+			</para>
+        </section>
+        <section id="jpa_overview_meta_orderby">
+          <title>Order By</title>
+          <indexterm zone="jpa_overview_meta_orderby">
+            <primary>OrderBy</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_orderby">
+            <primary>metadata</primary>
+            <secondary>OrderBy</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_orderby">
+            <primary>annotations</primary>
+            <secondary>OrderBy</secondary>
+          </indexterm>
+          <para>
+			Datastores such as relational databases do not preserve the order
+			of records.  Your persistent <classname>List</classname> fields 
+			might be ordered one way the first time you retrieve an object from
+			the datastore, and a completely different way the next.  To ensure 
+			consistent ordering of collection fields, you must use the 
+			<classname>OrderBy</classname> annotation.  The <classname>OrderBy
+			</classname> annotation's value is a string defining the order of 
+			the collection elements.  An empty value means to sort on the
+			identity value(s) of the elements in ascending order.  Any 
+			other value must be of the form:  
+			</para>
+          <programlisting format="linespecific">
+&lt;field name&gt;[ ASC|DESC][, ...]
+</programlisting>
+          <para>
+			Each <literal>&lt;field name&gt;</literal> is the name of a 
+			persistent field in the collection's element type.  You can 
+			optionally follow each field by the keyword <literal>ASC</literal>
+			for ascending order, or <literal>DESC</literal> for descending 
+			order.  If the direction is omitted, it defaults to ascending.
+			</para>
+          <para>
+			The equivalent XML element is <literal>order-by</literal> which
+			can be listed as a sub-element of the <literal>one-to-many</literal>
+			or <literal>many-to-many</literal> elements.  The text within this
+			element is parsed as the order by string.
+			</para>
+          <note>
+            <para>
+				OpenJPA expands the available ordering syntax.  See
+				<xref linkend="order-by"/> in the Reference Guide for details.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_mapkey">
+          <title>Map Key</title>
+          <indexterm zone="jpa_overview_meta_mapkey">
+            <primary>MapKey</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_mapkey">
+            <primary>metadata</primary>
+            <secondary>MapKey</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_mapkey">
+            <primary>annotations</primary>
+            <secondary>MapKey</secondary>
+          </indexterm>
+          <para>
+			JPA supports persistent <classname>Map</classname> fields through
+			either a <link linkend="jpa_overview_meta_onetomany"><classname>
+			OneToMany</classname></link> or
+			<link linkend="jpa_overview_meta_manytomany"><classname>ManyToMany
+			</classname></link> association.  The related entities form the
+			map values.  JPA derives the map keys by extracting a field 
+			from each entity value.  The <classname>MapKey</classname> 
+			annotation designates the field that is used as the key.
+			It has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of a field in
+					the related entity class to use as the map key.  If no
+					name is given, defaults to the identity field of the
+					related entity class.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The equivalent XML element is <literal>map-key</literal> which
+			can be listed as a sub-element of the <literal>one-to-many</literal>
+			or <literal>many-to-many</literal> elements.  The <literal>map-key
+			</literal> element has the following attributes:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field in
+                    the related entity class to use as the map key.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_fielddefaults">
+          <title>Persistent Field Defaults</title>
+          <para>
+			In the absence of any of the annotations above, JPA
+			defines the following default behavior for declared fields:
+			</para>
+          <orderedlist>
+            <listitem>
+              <para>
+					Fields declared <literal>static, transient</literal>, 
+					or <literal>final</literal> default to non-persistent.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Fields of any primitive type, primitive wrapper type,
+					<classname>java.lang.String</classname>,
+					<classname>byte[]</classname>,
+					<classname>Byte[]</classname>,
+					<classname>char[]</classname>,
+					<classname>Character[]</classname>,
+					<classname>java.math.BigDecimal</classname>,
+					<classname>java.math.BigInteger</classname>,
+					<classname>java.util.Date</classname>,
+					<classname>java.util.Calendar</classname>,
+					<classname>java.sql.Date</classname>,
+					<classname>java.sql.Timestamp</classname>,
+					or any <classname>Serializable</classname> type
+					default to persistent, as 
+					if annotated with <link linkend="jpa_overview_meta_basic"><literal>@Basic</literal></link>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Fields of an embeddable type default to persistent, as
+					if annotated with 
+					<link linkend="jpa_overview_meta_embedded"><literal>
+					@Embedded</literal></link>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>All other fields default to non-persistent.</para>
+            </listitem>
+          </orderedlist>
+          <para>
+			Note that according to these defaults, all relations between
+			entities must be annotated explicitly.  Without an annotation,
+			a relation field will default to serialized storage if the
+			related entity type is serializable, or will default to being 
+			non-persistent if not.
+			</para>
+        </section>
+      </section>
+      <section id="jpa_overview_meta_xml">
+        <title>XML Schema</title>
+        <indexterm>
+          <primary>metadata</primary>
+          <secondary>XSD</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>JPA</primary>
+          <secondary>metadata</secondary>
+          <tertiary>XML</tertiary>
+          <seealso>metadata</seealso>
+        </indexterm>
+        <para>
+		We present the complete XML schema below.  Many of the elements relate
+		to object/relational mapping rather than metadata; these elements are
+		discussed in <xref linkend="jpa_overview_mapping"/>.
+		</para>
+        <programlisting format="linespecific">
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;xsd:schema targetNamespace="http://java.sun.com/xml/ns/persistence/orm" 
+  xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" 
+  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
+  elementFormDefault="qualified" 
+  attributeFormDefault="unqualified" 
+  version="1.0"&gt;
+
+  &lt;xsd:annotation&gt;
+    &lt;xsd:documentation&gt;
+      @(#)orm_1_0.xsd 1.0  Feb 14 2006
+    &lt;/xsd:documentation&gt;
+  &lt;/xsd:annotation&gt;
+  &lt;xsd:annotation&gt;
+     &lt;xsd:documentation&gt;
+
+       This is the XML Schema for the persistence object-relational 
+       mapping file.
+       The file may be named "META-INF/orm.xml" in the persistence 
+       archive or it may be named some other name which would be 
+       used to locate the file as resource on the classpath.
+
+     &lt;/xsd:documentation&gt;
+  &lt;/xsd:annotation&gt;
+
+  &lt;xsd:complexType name="emptyType"/&gt;
+
+  &lt;xsd:simpleType name="versionType"&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:pattern value="[0-9]+(\.[0-9]+)*"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:element name="entity-mappings"&gt;
+    &lt;xsd:complexType&gt;
+      &lt;xsd:annotation&gt;
+        &lt;xsd:documentation&gt;
+
+        The entity-mappings element is the root element of an mapping
+        file. It contains the following four types of elements:
+
+        1. The persistence-unit-metadata element contains metadata
+        for the entire persistence unit. It is undefined if this element
+        occurs in multiple mapping files within the same persistence unit.
+        
+        2. The package, schema, catalog and access elements apply to all of
+        the entity, mapped-superclass and embeddable elements defined in
+        the same file in which they occur.
+
+        3. The sequence-generator, table-generator, named-query,
+        named-native-query and sql-result-set-mapping elements are global
+        to the persistence unit. It is undefined to have more than one
+        sequence-generator or table-generator of the same name in the same
+        or different mapping files in a persistence unit. It is also 
+        undefined to have more than one named-query or named-native-query
+        of the same name in the same or different mapping files in a 
+        persistence unit.
+
+        4. The entity, mapped-superclass and embeddable elements each define
+        the mapping information for a managed persistent class. The mapping
+        information contained in these elements may be complete or it may
+        be partial.
+
+        &lt;/xsd:documentation&gt;
+      &lt;/xsd:annotation&gt;
+      &lt;xsd:sequence&gt;
+        &lt;xsd:element name="description" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="persistence-unit-metadata" 
+                     type="orm:persistence-unit-metadata"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="package" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="schema" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="catalog" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="access" type="orm:access-type"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="sequence-generator" type="orm:sequence-generator"
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="table-generator" type="orm:table-generator" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="named-query" type="orm:named-query" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="named-native-query" type="orm:named-native-query"
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="sql-result-set-mapping" 
+                     type="orm:sql-result-set-mapping" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="mapped-superclass" type="orm:mapped-superclass" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="entity" type="orm:entity" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="embeddable" type="orm:embeddable" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;/xsd:sequence&gt;
+      &lt;xsd:attribute name="version" type="orm:versionType" 
+                     fixed="1.0" use="required"/&gt;
+    &lt;/xsd:complexType&gt;
+  &lt;/xsd:element&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="persistence-unit-metadata"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        Metadata that applies to the persistence unit and not just to 
+        the mapping file in which it is contained. 
+
+        If the xml-mapping-metadata-complete element is specified then 
+        the complete set of mapping metadata for the persistence unit 
+        is contained in the XML mapping files for the persistence unit.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="xml-mapping-metadata-complete" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="persistence-unit-defaults" 
+                   type="orm:persistence-unit-defaults"
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="persistence-unit-defaults"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        These defaults are applied to the persistence unit as a whole 
+        unless they are overridden by local annotation or XML 
+        element settings. 
+        
+        schema - Used as the schema for all tables or secondary tables
+            that apply to the persistence unit
+        catalog - Used as the catalog for all tables or secondary tables
+            that apply to the persistence unit
+        access - Used as the access type for all managed classes in
+            the persistence unit
+        cascade-persist - Adds cascade-persist to the set of cascade options
+            in entity relationships of the persistence unit
+        entity-listeners - List of default entity listeners to be invoked 
+            on each entity in the persistence unit. 
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+        &lt;xsd:element name="schema" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="catalog" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="access" type="orm:access-type"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="cascade-persist" type="orm:emptyType" 
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="entity-listeners" type="orm:entity-listeners"
+                     minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        Defines the settings and mappings for an entity. Is allowed to be
+        sparsely populated and used in conjunction with the annotations.
+        Alternatively, the metadata-complete attribute can be used to 
+        indicate that no annotations on the entity class (and its fields
+        or properties) are to be processed. If this is the case then 
+        the defaulting rules for the entity and its subelements will 
+        be recursively applied.
+
+        @Target(TYPE) @Retention(RUNTIME)
+          public @interface Entity {
+          String name() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="description" type="xsd:string" minOccurs="0"/&gt;
+      &lt;xsd:element name="table" type="orm:table" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="secondary-table" type="orm:secondary-table" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="primary-key-join-column" 
+                   type="orm:primary-key-join-column" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="id-class" type="orm:id-class" minOccurs="0"/&gt;
+      &lt;xsd:element name="inheritance" type="orm:inheritance" minOccurs="0"/&gt;
+      &lt;xsd:element name="discriminator-value" type="orm:discriminator-value" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="discriminator-column" 
+                   type="orm:discriminator-column" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="sequence-generator" type="orm:sequence-generator" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="table-generator" type="orm:table-generator" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="named-query" type="orm:named-query" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="named-native-query" type="orm:named-native-query" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="sql-result-set-mapping" 
+                   type="orm:sql-result-set-mapping" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="exclude-default-listeners" type="orm:emptyType" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="exclude-superclass-listeners" type="orm:emptyType" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="entity-listeners" type="orm:entity-listeners" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-persist" type="orm:post-persist" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-update" type="orm:post-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-load" type="orm:post-load" minOccurs="0"/&gt;
+      &lt;xsd:element name="attribute-override" type="orm:attribute-override" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="association-override" 
+                   type="orm:association-override"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="attributes" type="orm:attributes" minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="access" type="orm:access-type"/&gt;
+    &lt;xsd:attribute name="metadata-complete" type="xsd:boolean"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="attributes"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        This element contains the entity field or property mappings.
+        It may be sparsely populated to include only a subset of the
+        fields or properties. If metadata-complete for the entity is true
+        then the remainder of the attributes will be defaulted according
+        to the default rules.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:choice&gt;
+        &lt;xsd:element name="id" type="orm:id" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="embedded-id" type="orm:embedded-id" 
+                     minOccurs="0"/&gt;
+      &lt;/xsd:choice&gt;
+      &lt;xsd:element name="basic" type="orm:basic"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="version" type="orm:version"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="many-to-one" type="orm:many-to-one"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="one-to-many" type="orm:one-to-many"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="one-to-one" type="orm:one-to-one"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="many-to-many" type="orm:many-to-many" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="embedded" type="orm:embedded"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="transient" type="orm:transient"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="access-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        This element determines how the persistence provider accesses the
+        state of an entity or embedded object.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="PROPERTY"/&gt;
+      &lt;xsd:enumeration value="FIELD"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity-listeners"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface EntityListeners {
+          Class[] value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="entity-listener" type="orm:entity-listener" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity-listener"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        Defines an entity listener to be invoked at lifecycle events
+        for the entities that list this listener.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-persist" type="orm:post-persist" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-update" type="orm:post-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-load" type="orm:post-load" minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="pre-persist"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PrePersist {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-persist"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostPersist {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="pre-remove"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PreRemove {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-remove"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostRemove {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="pre-update"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PreUpdate {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-update"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostUpdate {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-load"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostLoad {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="query-hint"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({}) @Retention(RUNTIME) 
+        public @interface QueryHint {
+          String name();
+          String value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="value" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="named-query"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface NamedQuery {
+          String name();
+          String query();
+          QueryHint[] hints() default {};
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="query" type="xsd:string"/&gt;
+      &lt;xsd:element name="hint" type="orm:query-hint" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="named-native-query"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface NamedNativeQuery {
+          String name();
+          String query();
+          QueryHint[] hints() default {};
+          Class resultClass() default void.class;
+          String resultSetMapping() default ""; //named SqlResultSetMapping
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="query" type="xsd:string"/&gt;
+      &lt;xsd:element name="hint" type="orm:query-hint" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="result-class" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="result-set-mapping" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="sql-result-set-mapping"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface SqlResultSetMapping {
+          String name();
+          EntityResult[] entities() default {};
+          ColumnResult[] columns() default {};
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="entity-result" type="orm:entity-result" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="column-result" type="orm:column-result" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity-result"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({}) @Retention(RUNTIME)
+        public @interface EntityResult {
+          Class entityClass();
+          FieldResult[] fields() default {};
+          String discriminatorColumn() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="field-result" type="orm:field-result" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="entity-class" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="discriminator-column" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="field-result"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({}) @Retention(RUNTIME)
+        public @interface FieldResult {
+          String name();
+          String column();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="column" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="column-result"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({}) @Retention(RUNTIME)
+        public @interface ColumnResult {
+          String name();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="table"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface Table {
+          String name() default "";
+          String catalog() default "";
+          String schema() default "";
+          UniqueConstraint[] uniqueConstraints() default {};
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="unique-constraint" type="orm:unique-constraint" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="catalog" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="schema" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="secondary-table"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface SecondaryTable {
+          String name();
+          String catalog() default "";
+          String schema() default "";
+          PrimaryKeyJoinColumn[] pkJoinColumns() default {};
+          UniqueConstraint[] uniqueConstraints() default {};
+         }
+
+       &lt;/xsd:documentation&gt;
+     &lt;/xsd:annotation&gt;
+     &lt;xsd:sequence&gt;
+       &lt;xsd:element name="primary-key-join-column" 
+                    type="orm:primary-key-join-column" 
+                    minOccurs="0" maxOccurs="unbounded"/&gt;
+       &lt;xsd:element name="unique-constraint" type="orm:unique-constraint" 
+                    minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="catalog" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="schema" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="unique-constraint"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({}) @Retention(RUNTIME)
+        public @interface UniqueConstraint {
+          String[] columnNames();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="column-name" type="xsd:string" 
+                   maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="column"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Column {
+          String name() default "";
+          boolean unique() default false;
+          boolean nullable() default true;
+          boolean insertable() default true;
+          boolean updatable() default true;
+          String columnDefinition() default "";
+          String table() default "";
+          int length() default 255;
+          int precision() default 0; // decimal precision
+          int scale() default 0; // decimal scale
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="unique" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="nullable" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="insertable" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="updatable" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="column-definition" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="table" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="length" type="xsd:int"/&gt;
+    &lt;xsd:attribute name="precision" type="xsd:int"/&gt;
+    &lt;xsd:attribute name="scale" type="xsd:int"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="join-column"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface JoinColumn {
+          String name() default "";
+          String referencedColumnName() default "";
+          boolean unique() default false;
+          boolean nullable() default true;
+          boolean insertable() default true;
+          boolean updatable() default true;
+          String columnDefinition() default "";
+          String table() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="referenced-column-name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="unique" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="nullable" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="insertable" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="updatable" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="column-definition" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="table" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="generation-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum GenerationType { TABLE, SEQUENCE, IDENTITY, AUTO };
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="TABLE"/&gt;
+      &lt;xsd:enumeration value="SEQUENCE"/&gt;
+      &lt;xsd:enumeration value="IDENTITY"/&gt;
+      &lt;xsd:enumeration value="AUTO"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="attribute-override"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface AttributeOverride {
+          String name();
+          Column column();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="column" type="orm:column"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="association-override"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface AssociationOverride {
+          String name();
+          JoinColumn[] joinColumns();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="join-column" type="orm:join-column"
+                   maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="id-class"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface IdClass {
+          Class value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="id"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Id {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="column" type="orm:column" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="generated-value" type="orm:generated-value"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="temporal" type="orm:temporal" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="table-generator" type="orm:table-generator" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="sequence-generator" type="orm:sequence-generator"
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="embedded-id"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface EmbeddedId {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="attribute-override" type="orm:attribute-override" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="transient"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Transient {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="version"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Version {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="column" type="orm:column" minOccurs="0"/&gt;
+      &lt;xsd:element name="temporal" type="orm:temporal" minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="basic"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Basic {
+          FetchType fetch() default EAGER;
+          boolean optional() default true;
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="column" type="orm:column" minOccurs="0"/&gt;
+      &lt;xsd:choice&gt;
+        &lt;xsd:element name="lob" type="orm:lob" minOccurs="0"/&gt;
+        &lt;xsd:element name="temporal" type="orm:temporal" minOccurs="0"/&gt;
+        &lt;xsd:element name="enumerated" type="orm:enumerated" minOccurs="0"/&gt;
+      &lt;/xsd:choice&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="fetch" type="orm:fetch-type"/&gt;
+    &lt;xsd:attribute name="optional" type="xsd:boolean"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="fetch-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum FetchType { LAZY, EAGER };
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="LAZY"/&gt;
+      &lt;xsd:enumeration value="EAGER"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="lob"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Lob {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="temporal"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Temporal {
+          TemporalType value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="orm:temporal-type"/&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="temporal-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum TemporalType {
+          DATE, // java.sql.Date
+          TIME, // java.sql.Time
+          TIMESTAMP // java.sql.Timestamp
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+      &lt;xsd:restriction base="xsd:token"&gt;
+        &lt;xsd:enumeration value="DATE"/&gt;
+        &lt;xsd:enumeration value="TIME"/&gt;
+        &lt;xsd:enumeration value="TIMESTAMP"/&gt;
+     &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="enumerated"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Enumerated {
+          EnumType value() default ORDINAL;
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="orm:enum-type"/&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="enum-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum EnumType {
+          ORDINAL,
+          STRING
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="ORDINAL"/&gt;
+      &lt;xsd:enumeration value="STRING"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="many-to-one"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface ManyToOne {
+          Class targetEntity() default void.class;
+          CascadeType[] cascade() default {};
+          FetchType fetch() default EAGER;
+          boolean optional() default true;
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:choice&gt;       
+        &lt;xsd:element name="join-column" type="orm:join-column" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="join-table" type="orm:join-table" 
+                     minOccurs="0"/&gt;
+      &lt;/xsd:choice&gt;       
+      &lt;xsd:element name="cascade" type="orm:cascade-type" 
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="target-entity" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="fetch" type="orm:fetch-type"/&gt;
+    &lt;xsd:attribute name="optional" type="xsd:boolean"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="cascade-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum CascadeType { ALL, PERSIST, MERGE, REMOVE, REFRESH};
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="cascade-all" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="cascade-persist" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="cascade-merge" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="cascade-remove" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="cascade-refresh" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="one-to-one"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface OneToOne {
+          Class targetEntity() default void.class;
+          CascadeType[] cascade() default {};
+          FetchType fetch() default EAGER;
+          boolean optional() default true;
+          String mappedBy() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:choice&gt;
+        &lt;xsd:element name="primary-key-join-column" 
+                     type="orm:primary-key-join-column" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="join-column" type="orm:join-column" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="join-table" type="orm:join-table" 
+                     minOccurs="0"/&gt;
+      &lt;/xsd:choice&gt;
+      &lt;xsd:element name="cascade" type="orm:cascade-type" 
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="target-entity" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="fetch" type="orm:fetch-type"/&gt;
+    &lt;xsd:attribute name="optional" type="xsd:boolean"/&gt;
+    &lt;xsd:attribute name="mapped-by" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="one-to-many"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface OneToMany {
+          Class targetEntity() default void.class;
+          CascadeType[] cascade() default {};
+          FetchType fetch() default LAZY;
+          String mappedBy() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="order-by" type="orm:order-by" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="map-key" type="orm:map-key" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:choice&gt;       
+        &lt;xsd:element name="join-table" type="orm:join-table" 
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="join-column" type="orm:join-column" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;/xsd:choice&gt;       
+      &lt;xsd:element name="cascade" type="orm:cascade-type" 
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="target-entity" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="fetch" type="orm:fetch-type"/&gt;
+    &lt;xsd:attribute name="mapped-by" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="join-table"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface JoinTable {
+          String name() default "";
+          String catalog() default "";
+          String schema() default "";
+          JoinColumn[] joinColumns() default {};
+          JoinColumn[] inverseJoinColumns() default {};
+          UniqueConstraint[] uniqueConstraints() default {};
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="join-column" type="orm:join-column" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="inverse-join-column" type="orm:join-column" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="unique-constraint" type="orm:unique-constraint" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="catalog" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="schema" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="many-to-many"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface ManyToMany {
+          Class targetEntity() default void.class;
+          CascadeType[] cascade() default {};
+          FetchType fetch() default LAZY;
+          String mappedBy() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="order-by" type="orm:order-by" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="map-key" type="orm:map-key" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="join-table" type="orm:join-table" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="cascade" type="orm:cascade-type" 
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="target-entity" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="fetch" type="orm:fetch-type"/&gt;
+    &lt;xsd:attribute name="mapped-by" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="generated-value"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface GeneratedValue {
+          GenerationType strategy() default AUTO;
+          String generator() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="strategy" type="orm:generation-type"/&gt;
+    &lt;xsd:attribute name="generator" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="map-key"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface MapKey {
+          String name() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="order-by"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface OrderBy {
+          String value() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:string"/&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="inheritance"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface Inheritance {
+          InheritanceType strategy() default SINGLE_TABLE;
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="strategy" type="orm:inheritance-type"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="inheritance-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum InheritanceType
+          { SINGLE_TABLE, JOINED, TABLE_PER_CLASS};
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="SINGLE_TABLE"/&gt;
+      &lt;xsd:enumeration value="JOINED"/&gt;
+      &lt;xsd:enumeration value="TABLE_PER_CLASS"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="discriminator-value"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface DiscriminatorValue {
+          String value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:string"/&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="discriminator-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        public enum DiscriminatorType { STRING, CHAR, INTEGER };
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="STRING"/&gt;
+      &lt;xsd:enumeration value="CHAR"/&gt;
+      &lt;xsd:enumeration value="INTEGER"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="primary-key-join-column"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface PrimaryKeyJoinColumn {
+          String name() default "";
+          String referencedColumnName() default "";
+          String columnDefinition() default "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="referenced-column-name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="column-definition" type="xsd:string"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="discriminator-column"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface DiscriminatorColumn {
+          String name() default "DTYPE";
+          DiscriminatorType discriminatorType() default STRING;
+          String columnDefinition() default "";
+          int length() default 31;
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="discriminator-type" type="orm:discriminator-type"/&gt;
+    &lt;xsd:attribute name="column-definition" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="length" type="xsd:int"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="embeddable"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        Defines the settings and mappings for embeddable objects. Is 
+        allowed to be sparsely populated and used in conjunction with 
+        the annotations. Alternatively, the metadata-complete attribute 
+        can be used to indicate that no annotations are to be processed 
+        in the class. If this is the case then the defaulting rules will 
+        be recursively applied.
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface Embeddable {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="description" type="xsd:string" minOccurs="0"/&gt;
+      &lt;xsd:element name="attributes" type="orm:embeddable-attributes" 
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="access" type="orm:access-type"/&gt;
+    &lt;xsd:attribute name="metadata-complete" type="xsd:boolean"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="embeddable-attributes"&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="basic" type="orm:basic" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="transient" type="orm:transient" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="embedded"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface Embedded {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="attribute-override" type="orm:attribute-override" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="mapped-superclass"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        Defines the settings and mappings for a mapped superclass. Is 
+        allowed to be sparsely populated and used in conjunction with 
+        the annotations. Alternatively, the metadata-complete attribute 
+        can be used to indicate that no annotations are to be processed 
+        If this is the case then the defaulting rules will be recursively 
+        applied.
+
+        @Target(TYPE) @Retention(RUNTIME)
+        public @interface MappedSuperclass{}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="description" type="xsd:string" minOccurs="0"/&gt;
+      &lt;xsd:element name="id-class" type="orm:id-class" minOccurs="0"/&gt;
+      &lt;xsd:element name="exclude-default-listeners" type="orm:emptyType" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="exclude-superclass-listeners" type="orm:emptyType" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="entity-listeners" type="orm:entity-listeners" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-persist" type="orm:post-persist" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-update" type="orm:post-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-load" type="orm:post-load" minOccurs="0"/&gt;
+      &lt;xsd:element name="attributes" type="orm:attributes" minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="access" type="orm:access-type"/&gt;
+    &lt;xsd:attribute name="metadata-complete" type="xsd:boolean"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="sequence-generator"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface SequenceGenerator {
+          String name();
+          String sequenceName() default "";
+          int initialValue() default 1;
+          int allocationSize() default 50;
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="sequence-name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="initial-value" type="xsd:int"/&gt;
+    &lt;xsd:attribute name="allocation-size" type="xsd:int"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="table-generator"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
+        public @interface TableGenerator {
+          String name();
+          String table() default "";
+          String catalog() default "";
+          String schema() default "";
+          String pkColumnName() default "";
+          String valueColumnName() default "";
+          String pkColumnValue() default "";
+          int initialValue() default 0;
+          int allocationSize() default 50;
+          UniqueConstraint[] uniqueConstraints() default {};
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="unique-constraint" type="orm:unique-constraint" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="table" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="catalog" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="schema" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="pk-column-name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="value-column-name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="pk-column-value" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="initial-value" type="xsd:int"/&gt;
+    &lt;xsd:attribute name="allocation-size" type="xsd:int"/&gt;
+  &lt;/xsd:complexType&gt;
+
+&lt;/xsd:schema&gt;
+</programlisting>
+      </section>
+      <section id="jpa_overview_meta_complete">
+        <title>Conclusion</title>
+        <para>
+		That exhausts persistence metadata annotations.  We present the class
+ 		definitions for our sample model below:
+		</para>
+        <example id="jpa_overview_meta_complete_ex">
+          <title>Complete Metadata</title>
+          <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+public class Magazine
+{
+    @Id private String isbn;
+    @Id private String title;
+    @Version private int version;
+
+    private double price;   // defaults to @Basic
+    private int copiesSold; // defaults to @Basic
+
+    @OneToOne(fetch=FetchType.LAZY, 
+        cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    private Article coverArticle;
+
+    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    @OrderBy
+    private Collection&lt;Article&gt; articles;
+
+    @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.PERSIST)
+    private Company publisher; 
+
+    @Transient private byte[] data;
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+public class Article
+{
+    @Id private long id;
+    @Version private int version;
+    
+    private String title;   // defaults to @Basic
+    private byte[] content; // defaults to @Basic
+
+    @ManyToMany(cascade=CascadeType.PERSIST)
+    @OrderBy("lastName, firstName")
+    private Collection&lt;Author&gt; authors;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+public class Company
+{
+    @Id private long id;
+    @Version private int version;
+
+    private String name;     // defaults to @Basic
+    private double revenue;  // defaults to @Basic
+    private Address address; // defaults to @Embedded
+    
+    @OneToMany(mappedBy="publisher", cascade=CascadeType.PERSIST)
+    private Collection&lt;Magazine&gt; mags;
+
+    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    private Collection&lt;Subscription&gt; subscriptions;
+
+    ...
+}
+
+@Entity
+public class Author
+{
+    @Id private long id;
+    @Version private int version;
+
+    private String firstName; // defaults to @Basic
+    private double lastName;  // defaults to @Basic
+    private Address address;  // defaults to @Embedded
+    
+    @ManyToMany(mappedBy="authors", cascade=CascadeType.PERSIST)
+    private Collection&lt;Article&gt; arts;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    private String street; // defaults to @Basic
+    private String city;   // defaults to @Basic
+    private String state;  // defaults to @Basic
+    private String zip;    // defaults to @Basic
+
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id private long id;
+    @Version private int version;
+
+    ...
+}
+
+@Entity
+public class Contract
+    extends Document
+{
+    private String terms; // defaults to @Basic
+
+    ...
+}
+
+@Entity
+public class Subscription
+{
+    @Id private long id;
+    @Version private int version;
+
+    private Date startDate; // defaults to @Basic
+    private double payment; // defaults to @Basic
+
+    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    @MapKey(name="num")
+    private Map&lt;Long,LineItem&gt; lineItems;
+
+    ...
+
+    @Entity
+    public static class LineItem
+        extends Contract
+    {
+        private String comments; // defaults to @Basic
+        private double price;    // defaults to @Basic
+        private long num;        // defaults to @Basic
+
+        @ManyToOne
+        private Magazine magazine;
+
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    @Basic(fetch=FetchType.LAZY)
+    private boolean getEliteClub () { ... }
+    public void setEliteClub (boolean elite) { ... }
+
+    ...
+}
+
+@Entity(name="Trial")
+public class TrialSubscription
+    extends Subscription
+{
+    public Date getEndDate () { ... }
+    public void setEndDate (Date end) { ... }
+
+    ...
+}
+</programlisting>
+          <para>
+		The same metadata declarations in XML:
+		</para>
+          <programlisting format="linespecific">
+&lt;entity-mappings&gt;
+    &lt;!-- declares a default access type for all entities --&gt;
+    &lt;access-type&gt;FIELD&lt;/access-type&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            &lt;version name="version"/&gt;
+        &lt;/attributes&gt;
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;id-class="org.mag.Magazine$MagazineId"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="isbn"/&gt;
+            &lt;id name="title"/&gt;
+            &lt;basic name="name"/&gt;
+            &lt;basic name="price"/&gt;
+            &lt;basic name="copiesSold"/&gt;
+            &lt;version name="version"/&gt;
+            &lt;many-to-one name="publisher" fetch="LAZY"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                &lt;/cascade&gt;
+            &lt;/many-to-one&gt;
+            &lt;one-to-many name="articles"&gt;
+                &lt;order-by/&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+            &lt;one-to-one name="coverArticle" fetch="LAZY"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-one&gt;
+            &lt;transient name="data"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"/&gt;
+            &lt;basic name="title"/&gt;
+            &lt;basic name="content"/&gt;
+            &lt;version name="version"/&gt;
+            &lt;many-to-many name="articles"&gt;
+                &lt;order-by&gt;lastName, firstName&lt;/order-by&gt;
+            &lt;/many-to-many&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"/&gt;
+            &lt;basic name="name"/&gt;
+            &lt;basic name="revenue"/&gt;
+            &lt;version name="version"/&gt;
+            &lt;one-to-many name="mags" mapped-by="publisher"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+            &lt;one-to-many name="subscriptions"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"/&gt;
+            &lt;basic name="firstName"/&gt;
+            &lt;basic name="lastName"/&gt;
+            &lt;version name="version"/&gt;
+            &lt;many-to-many name="arts" mapped-by="authors"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                &lt;/cascade&gt;
+            &lt;/many-to-many&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Contract"&gt;
+        &lt;attributes&gt;
+            &lt;basic name="terms"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Subscription"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"/&gt;
+            &lt;basic name="payment"/&gt;
+            &lt;basic name="startDate"/&gt;
+            &lt;version name="version"/&gt;
+            &lt;one-to-many name="items"&gt;
+                &lt;map-key name="num"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+        &lt;attributes&gt;
+            &lt;basic name="comments"/&gt;
+            &lt;basic name="price"/&gt;
+            &lt;basic name="num"/&gt;
+            &lt;many-to-one name="magazine"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"
+        access="PROPERTY"&gt;
+        &lt;attributes&gt;
+            &lt;basic name="eliteClub" fetch="LAZY"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        &lt;attributes&gt;
+            &lt;basic name="endDate"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;embeddable class="org.mag.pub.Address"&gt;
+        &lt;attributes&gt;
+            &lt;basic name="street"/&gt;
+            &lt;basic name="city"/&gt;
+            &lt;basic name="state"/&gt;
+            &lt;basic name="zip"/&gt;
+        &lt;/attributes&gt;
+    &lt;/embeddable&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+        </example>
+        <para><xref linkend="jpa_overview_mapping"/> will show you how to map your
+		persistent classes to the datastore using additional annotations and
+		XML markup.  First, however, we turn to the JPA runtime 
+		APIs.
+		</para>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_persistence">
+      <title>Persistence</title>
+      <indexterm zone="jpa_overview_persistence">
+        <primary>Persistence</primary>
+      </indexterm>
+      <indexterm zone="jpa_overview_persistence">
+        <primary>EntityManagerFactory</primary>
+        <secondary>construction</secondary>
+      </indexterm>
+      <indexterm zone="jpa_overview_persistence">
+        <primary>Persistence</primary>
+        <secondary>getEntityManagerFactory</secondary>
+      </indexterm>
+      <indexterm zone="jpa_overview_persistence">
+        <primary>getEntityManagerFactory</primary>
+        <seealso>Persistence</seealso>
+      </indexterm>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 427 x 121 (see README) -->
+          <imagedata fileref="img/persistence.png" width="285px"/>
+        </imageobject>
+      </mediaobject>
+      <note>
+        <para>
+		OpenJPA also includes the 
+		<ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"><classname>OpenJPAPersistence</classname></ulink> helper class to provide 
+		additional utility methods.
+		</para>
+      </note>
+      <para>
+	Within a container, you will typically use <emphasis>injection
+	</emphasis> to access an <classname>EntityManagerFactory</classname>.
+	Applications operating of a container, however,	can use the
+	<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Persistence.html"><classname>Persistence</classname></ulink> class to obtain
+	<classname>EntityManagerFactory</classname> objects in a vendor-neutral
+	fashion.
+	</para>
+      <programlisting format="linespecific">
+public static EntityManagerFactory createEntityManagerFactory (String name);
+public static EntityManagerFactory createEntityManagerFactory (String name, Map props);
+</programlisting>
+      <para>
+	Each <methodname>createEntityManagerFactory</methodname> method searches
+	the system for an <classname>EntityManagerFactory</classname> definition 
+	with the given name.  Use <literal>null</literal> for an unnamed factory.
+	The optional map contains vendor-specific property settings used to further
+	configure the factory.
+	</para>
+      <para><filename>persistence.xml</filename> files define <classname>
+	EntityManagerFactories</classname>.  The <methodname>
+	createEntityManagerFactory</methodname> methods search for <filename>
+	persistence.xml</filename> files within the <filename>META-INF</filename> 
+	directory of any <literal>CLASSPATH</literal> element.  For example, if 
+	your <literal>CLASSPATH</literal> contains the <filename>conf</filename>
+	directory, you could place an <classname>EntityManagerFactory</classname> 
+	definition in <filename>conf/META-INF/persistence.xml</filename>.
+	</para>
+      <section id="jpa_overview_persistence_xml">
+        <title>persistence.xml</title>
+        <para>
+		The <filename>persistence.xml</filename> file format obeys the following
+		Document Type Descriptor (DTD):
+		</para>
+        <programlisting format="linespecific">
+&lt;!ELEMENT persistence (persistence-unit*)&gt;
+&lt;!ELEMENT persistence-unit (description?,provider?,jta-datasource?,
+	non-jta-datasource?,(class|jar-file|mapping-file)*,
+	exclude-unlisted-classes?,properties?)&gt;
+&lt;!ATTLIST persistence-unit name CDATA #REQUIRED&gt;
+&lt;!ATTLIST persistence-unit transaction-type (JTA|RESOURCE_LOCAL) "JTA"&gt;
+&lt;!ELEMENT description (#PCDATA)&gt;
+&lt;!ELEMENT provider (#PCDATA)&gt;
+&lt;!ELEMENT jta-datasource (#PCDATA)&gt;
+&lt;!ELEMENT non-jta-datasource (#PCDATA)&gt;
+&lt;!ELEMENT mapping-file (#PCDATA)&gt;
+&lt;!ELEMENT jar-file (#PCDATA)&gt;
+&lt;!ELEMENT class (#PCDATA)&gt;
+&lt;!ELEMENT exclude-unlisted-classes EMPTY&gt;
+&lt;!ELEMENT properties (property*)&gt;
+&lt;!ELEMENT property EMPTY&gt;
+&lt;!ATTLIST property name CDATA #REQUIRED&gt;
+&lt;!ATTLIST property value CDATA #REQUIRED&gt;
+</programlisting>
+        <para>
+		The root element of a <filename>persistence.xml</filename> file is
+		<literal>persistence</literal>, which then contains one or more
+		<literal>persistence-unit</literal> definitions. 
+		Each persistence unit describes the configuration for the entity
+		managers created by the persistence unit's entity manager factory. 
+		The persistence unit can specify these elements and attribtues.
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>name</literal>: This is the name you pass to the
+				<methodname>Persistence.createEntityManagerFactory</methodname>
+				methods described above. The name attribute is required.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>transaction-type</literal>: Whether to use managed
+				(<literal>JTA</literal>) or local 
+				(<literal>RESOURCE_LOCAL</literal>) transaction management.
+				Defaults to <literal>JTA</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>provider</literal>: If you are using a third-party
+				JPA vendor, this element names its implementation of the 
+				<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/spi/PersistenceProvider.html"><classname>PersistenceProvider</classname></ulink> bootstrapping
+				interface. 
+				</para>
+            <note>
+              <para>
+					Set the <literal>provider</literal> to <classname>
+					org.apache.openjpa.persistence.PersistenceProviderImpl</classname>
+					to use OpenJPA. 
+					</para>
+            </note>
+          </listitem>
+          <listitem>
+            <para><literal>jta-data-source</literal>: The JNDI name of a JDBC
+				<classname>DataSource</classname> that is automatically enlisted
+				in JTA transactions.  This may be an XA <classname>
+				DataSource</classname>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>non-jta-data-source</literal>: The JNDI name of a JDBC
+				<classname>DataSource</classname> that is not enlisted
+				in JTA transactions.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>mapping-file</literal>*: The resource names of
+				XML mapping files for entities and embeddable classes.
+				You can also specify mapping information in an <filename>
+				orm.xml</filename> file in your <filename>META-INF</filename>
+				directory. If present, the <filename>orm.xml</filename>
+				mapping file will be read automatically.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>jar-file</literal>*: The names of jar files containing
+				entities and embeddable classes.  The implementation will scan
+				the jar for annotated classes.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>class</literal>*: The class names of entities and
+				embeddable classes.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>properties</literal>: This element contains nested
+				<literal>property</literal> elements used to specify 
+				vendor-specific settings.  Each <literal>property</literal>
+				has a name attribute and a value attribute.
+				</para>
+            <note>
+              <para>
+					The Reference Guide's <xref linkend="ref_guide_conf"/>
+					describes OpenJPA's configuration properties.
+					</para>
+            </note>
+          </listitem>
+        </itemizedlist>
+        <para>
+		Here is a typical <filename>persistence.xml</filename> file for a
+		non-EE environment:
+		</para>
+        <example id="jpa_overview_persistence_xmlex">
+          <title>persistence.xml</title>
+          <programlisting format="linespecific">
+&lt;?xml version="1.0"?&gt;
+&lt;persistence&gt;
+	&lt;persistence-unit name="openjpa"&gt;
+		&lt;provider&gt;org.apache.openjpa.persistence.PersistenceProviderImpl&lt;/provider&gt;
+		&lt;class&gt;tutorial.Animal&lt;/class&gt;
+		&lt;class&gt;tutorial.Dog&lt;/class&gt;
+		&lt;class&gt;tutorial.Rabbit&lt;/class&gt;
+		&lt;class&gt;tutorial.Snake&lt;/class&gt;
+		&lt;properties&gt;
+			&lt;property name="openjpa.ConnectionURL" value="jdbc:hsqldb:tutorial_database"/&gt;
+			&lt;property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/&gt;
+			&lt;property name="openjpa.ConnectionUserName" value="sa"/&gt;
+			&lt;property name="openjpa.ConnectionPassword" value=""/&gt;
+			&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/&gt;
+		&lt;/properties&gt;
+	&lt;/persistence-unit&gt;
+&lt;/persistence&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="jpa_overview_persistence_use">
+        <title>Non-EE Use</title>
+        <para>
+		The example below demonstrates the <classname>Persistence</classname>
+		class in action.  You will typically execute code like this on 
+		application startup, then cache the resulting factory for future use.
+		This bootstrapping code is only necessary in non-EE environments; in 
+		an EE environment <classname>EntityManagerFactories</classname> are 
+		typically injected.  
+		</para>
+        <example id="jpa_overview_persistence_getemfactory">
+          <title>Obtaining an EntityManagerFactory</title>
+          <programlisting format="linespecific">
+// if your persistence.xml file does not contain all settings already, you
+// can add vendor settings to a map 
+Properties props = new Properties ();
+...
+
+// create the factory defined by the "openjpa" entity-manager entry
+EntityManagerFactory emf = Persistence.createEntityManagerFactory ("openjpa", props);
+</programlisting>
+        </example>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_emfactory">
+      <title>EntityManagerFactory</title>
+      <indexterm zone="jpa_overview_emfactory">
+        <primary>EntityManagerFactory</primary>
+      </indexterm>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 418 x 274 (see README) -->
+          <imagedata fileref="img/entitymanagerfactory.png" width="279px"/>
+        </imageobject>
+      </mediaobject>
+      <para>
+	The <classname>EntityManagerFactory</classname> creates
+	<classname>EntityManager</classname> instances for application
+	use. 
+	</para>
+      <note>
+        <para>
+		OpenJPA extends the standard <classname>EntityManagerFactory</classname>
+		interface with the
+		<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html"><classname>OpenJPAEntityManagerFactory</classname></ulink> to provide
+		additional functionality.
+		</para>
+      </note>
+      <section id="jpa_overview_emfactory_obtain">
+        <title>Obtaining an EntityManagerFactory</title>
+        <indexterm zone="jpa_overview_emfactory_obtain">
+          <primary>EntityManagerFactory</primary>
+          <secondary>construction</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>Java Connector Architecture</primary>
+          <see>JCA</see>
+        </indexterm>
+        <indexterm>
+          <primary>JCA</primary>
+        </indexterm>
+        <para>
+		Within a container, you will typically use <emphasis>injection
+		</emphasis> to access an <classname>EntityManagerFactory</classname>.
+		There are, however, alternative mechanisms for 
+		<classname>EntityManagerFactory</classname> construction.
+		</para>
+        <para>
+		Some vendors may supply public constructors for their 
+		<classname>EntityManagerFactory</classname> implementations, but
+		we recommend using the Java Connector Architecture (JCA) in a managed 
+		environment, or the <classname>Persistence</classname> class'
+		<methodname>createEntityManagerFactory</methodname> methods in an
+		unmanaged environment, as described in
+		<xref linkend="jpa_overview_persistence"/>.  These strategies allow
+		vendors to pool factories, cutting down on resource utilization.
+		</para>
+        <para><indexterm><primary>JNDI</primary></indexterm>
+		JPA allows you to create and configure an
+		<classname>EntityManagerFactory</classname>, then store it in a 
+		Java Naming and Directory Interface (JNDI) tree for later retrieval 
+		and use.
+		</para>
+      </section>
+      <section id="jpa_overview_emfactory_em">
+        <title>Obtaining EntityManagers</title>
+        <indexterm zone="jpa_overview_emfactory_em">
+          <primary>EntityManager</primary>
+          <secondary>obtaining</secondary>
+          <seealso>EntityManagerFactory</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_emfactory_em">
+          <primary>EntityManagerFactory</primary>
+          <secondary>obtaining EntityManagers</secondary>
+        </indexterm>
+        <programlisting format="linespecific">
+public EntityManager createEntityManager ();
+public EntityManager createEntityManager (Map map);
+</programlisting>
+        <para>
+		The two <methodname>createEntityManager</methodname> methods above
+		create a new <classname>EntityManager</classname> each time they are 
+		invoked.  The optional <classname>Map</classname> is used to to supply
+		vendor-specific settings.   If you have configured your implementation
+		for JTA transactions and a JTA transaction is active, the returned 
+		<classname>EntityManager</classname> will be synchronized with that
+		transaction.
+		<!--
+		<classname>EntityManager</classname> with a persistence context type of
+		<literal>TRANSACTION</literal>.  The second version allows you to
+		specify the persistence context type.  We relate the differences 
+		between persistence context types 
+		<link linkend="jpa_overview_emfactory_perscontext">below</link>.
+		-->
+		</para>
+        <note>
+          <para>
+			OpenJPA recognizes the following string keys in the map supplied to
+			<methodname>createEntityManager</methodname>:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>openjpa.ConnectionUserName</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>openjpa.ConnectionPassword</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>openjpa.ConnectionRetainMode</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>openjpa.TransactionMode</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para><literal>openjpa.&lt;property&gt;</literal>, where 
+					<emphasis>&lt;property&gt;</emphasis> is any JavaBean
+					property of the 
+					<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"><classname>
+					org.apache.openjpa.persistence.OpenJPAEntityManager</classname></ulink>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The last option uses reflection to configure any property of OpenJPA's
+			<classname>EntityManager</classname> implementation with the value
+			supplied in your map.  The first options correspond exactly to
+			the same-named OpenJPA configuration keys described in
+			<xref linkend="ref_guide_conf"/> of the Reference Guide.
+			</para>
+        </note>
+      </section>
+      <section id="jpa_overview_emfactory_perscontext">
+        <title>Persistence Context</title>
+        <indexterm zone="jpa_overview_emfactory_perscontext">
+          <primary>persistence context</primary>
+        </indexterm>
+        <indexterm>
+          <primary>PersistenceContextType</primary>
+          <see>persistence context</see>
+        </indexterm>
+        <para>
+		A persistence context is a set of entities such that for any persistent
+		identity there is a unique entity instance.  Within a persistence
+		context, entities are <emphasis>managed</emphasis>.  The <classname>
+		EntityManager</classname> controls their lifecycle, and they can access
+		datastore resources.
+		</para>
+        <para>
+		When a persistence context ends, previously-managed entities become
+		<emphasis>detached</emphasis>.  A detached entity is no longer under
+		the control of the <classname>EntityManager</classname>, and no longer
+		has access to datastore resources.  We discuss detachment is detail in
+		<xref linkend="jpa_overview_em_lifecycle"/>.  For now, it is sufficient
+		to know that detachment as has two obvious consequences:
+		</para>
+        <orderedlist>
+          <listitem>
+            <para>
+				The detached entity cannot load any additional persistent
+				state.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				The <classname>EntityManager</classname> will not return the
+				detached entity from <methodname>find</methodname>, nor will
+				queries include the detached entity in their results.  Instead,
+				<methodname>find</methodname> method invocations and query 
+				executions that would normally incorporate the detached entity
+				will create a new managed entity with the same identity.
+				</para>
+          </listitem>
+        </orderedlist>
+        <note>
+          <para>
+			OpenJPA offers several features related to detaching entities.  See
+			<xref linkend="ref_guide_detach"/> in the Reference Guide.  
+			<xref linkend="ref_guide_detach_graph"/> in particular describes
+			how to use the <literal>DetachState</literal> setting to boost
+			the performance of merging detached entities.
+			</para>
+        </note>
+        <para> 
+		Injected <classname>EntityManager</classname>s have use a 
+		<emphasis>transaction</emphasis>, while <classname>
+		EntityManager</classname>s obtained through the
+		<classname>EntityManagerFactory</classname> have an <emphasis>
+		extended</emphasis> persistence context.  We describe these persistence
+		context types below.
+		</para>
+        <section id="jpa_overview_emfactory_perscontext_trans">
+          <title>Transaction Persistence Context</title>
+          <para>
+			Under the transaction persistence context model, an <classname>
+			EntityManager</classname> begins a new persistence context
+			with each transaction, and ends the context when the transaction 
+			commits or rolls back.  Within the transaction, entities you
+			retrieve through the <classname>EntityManager</classname> or via
+			<classname>Queries</classname> are managed entities.  They 
+			can access datastore resources to lazy-load additional 
+			persistent state as needed, and only one entity may exist for any 
+			persistent identity.
+			</para>
+          <para>
+			When the transaction completes, all entities lose their 
+			association with the <classname>EntityManager</classname> and 
+			become detached.  Traversing a persistent field that wasn't
+			already loaded now has undefined results.  And using the <classname>
+			EntityManager</classname> or a <classname>Query</classname> to 
+			retrieve additional objects may now create new instances with the 
+			same persistent identities as detached instances. 
+			</para>
+          <para>
+			If you use an <classname>EntityManager</classname> with a 
+			transaction persistence context model outside of 
+			an active transaction, each method invocation creates a new 
+			persistence context, performs the method action, and ends the 
+			persistence context.  For example, consider using the
+			<methodname>EntityManager.find</methodname> method outside 
+			of a transaction.  The <classname>EntityManager</classname> will 
+			create a temporary persistence context, perform the find operation,
+			end the persistence context, and return the detached result object 
+			to you.  A second call with the same id will return a second 
+			detached object.
+			</para>
+          <para>
+			When the next transaction begins, the <classname>EntityManager
+			</classname> will begin a new persistence context, and will again
+			start returning managed entities.  As you'll see in
+			<xref linkend="jpa_overview_em"/>, you can also merge the
+			previously-detached entites back into the new persistence context.
+			</para>
+          <example id="jpa_overview_emfactory_perscontext_transex">
+            <title>Behavior of Transaction Persistence Context</title>
+            <para>
+				The following code illustrates the behavior of entites under
+				an <classname>EntityManager</classname> using a transaction
+				persistence context.
+				</para>
+            <programlisting format="linespecific">
+EntityManager em; // injected
+...
+
+// outside a transaction:
+
+// each operation occurs in a separate persistence context, and returns 
+// a new detached instance
+Magazine mag1 = em.find (Magazine.class, magId);
+Magazine mag2 = em.find (Magazine.class, magId);
+assertTrue (mag2 != mag1);
+...
+
+// transaction begins:
+
+// within a transaction, a subsequent lookup doesn't return any of the
+// detached objects.  however, two lookups within the same transaction
+// return the same instance, because the persistence context spans the
+// transaction
+Magazine mag3 = em.find (Magazine.class, magId);
+assertTrue (mag3 != mag1 &amp;&amp; mag3 != mag2);
+Magazine mag4 = em.find (Magazine.class (magId);
+assertTrue (mag4 == mag3);
+...
+
+// transaction commits:
+
+// once again, each operation returns a new instance
+Magazine mag5 = em.find (Magazine.class, magId);
+assertTrue (mag5 != mag3);
+</programlisting>
+          </example>
+        </section>
+        <section id="jpa_overview_emfactory_perscontext_extend">
+          <title>Extended Persistence Context</title>
+          <para>
+			An <classname>EntityManager</classname> using an extended 
+			persistence context maintains the same persistence context for
+			its entire lifecycle.  Whether inside a transaction or not, all 
+			entities returned from the <classname>EntityManager</classname> 
+			are managed, and the <classname>EntityManager</classname> never 
+			creates two entity instances to represent the same persistent 
+			identity.  Entities only become detached when you finally close 
+			the <classname>EntityManager</classname> (or when they are 
+			serialized).
+			</para>
+          <example id="jpa_overview_emfactory_perscontext_extendex">
+            <title>Behavior of Extended Persistence Context</title>
+            <para>
+				The following code illustrates the behavior of entites under
+				an <classname>EntityManager</classname> using an extended
+				persistence context.
+				</para>
+            <programlisting format="linespecific">
+EntityManagerFactory emf = ...
+EntityManager em = emf.createEntityManager (PersistenceContextType.EXTENDED);
+
+// persistence context active for entire life of EM, so only one entity
+// for a given persistent identity
+Magazine mag1 = em.find (Magazine.class, magId);
+Magazine mag2 = em.find (Magazine.class, magId);
+assertTrue (mag2 == mag1);
+
+em.getTransaction ().begin ();
+
+// same persistence context active within the transaction
+Magazine mag3 = em.find (Magazine.class, magId);
+assertTrue (mag3 == mag1);
+Magazine mag4 = em.find (Magazine.class (magId);
+assertTrue (mag4 == mag1);
+
+em.getTransaction.commit ();
+
+// when the transaction commits, instance still managed
+Magazine mag5 = em.find (Magazine.class, magId);
+assertTrue (mag5 == mag1);
+
+// instance finally becomes detached when EM closes
+em.close ();
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_overview_emfactory_close">
+        <title>Closing the EntityManagerFactory</title>
+        <indexterm zone="jpa_overview_emfactory_close">
+          <primary>EntityManagerFactory</primary>
+          <secondary>closing</secondary>
+        </indexterm>
+        <programlisting format="linespecific">
+public boolean isOpen ();
+public void close ();
+</programlisting>
+        <para><classname>EntityManagerFactory</classname> instances are
+		heavyweight objects.  Each factory might maintain a metadata cache,
+		object state cache, <classname>EntityManager</classname> pool, 
+		connection pool, and more.  If your application no longer needs an 
+		<classname>EntityManagerFactory</classname>, you should close it
+		to free these resources.  When an <classname>EntityManagerFactory
+		</classname> closes, all <classname>EntityManager</classname>s 
+		from that factory, and by extension all entities managed
+		by those <classname>EntityManager</classname>s, become invalid.
+		Attempting to close an <classname>EntityManagerFactory</classname>
+		while one or more of its <classname>EntityManager</classname>s 
+		has an active transaction may result in an
+		<classname>IllegalStateException</classname>.
+		</para>
+        <para>
+		Closing an <classname>EntityManagerFactory</classname> should not
+		be taken lightly.  It is much better to keep a factory open for a long
+		period of time than to repeatedly create and close new factories.  Thus,
+		most applications will never close the factory, or only close it when
+		the application is exiting.  Only applications that require multiple
+		factories with different configurations have an obvious reason to
+		create and close multiple <classname>EntityManagerFactory
+		</classname> instances.  Once a factory is closed, all methods except
+		<methodname>isOpen</methodname> throw an <classname>
+		IllegalStateException</classname>.
+		</para>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_em">
+      <title>EntityManager</title>
+      <indexterm zone="jpa_overview_em">
+        <primary>EntityManager</primary>
+      </indexterm>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 283 x 391 (see README) -->
+          <imagedata fileref="img/entitymanager.png" width="189px"/>
+        </imageobject>
+      </mediaobject>
+      <para>
+	The diagram above presents an overview of the 
+	<classname>EntityManager</classname> interface.  For a complete 
+	treatment of the <classname>EntityManager</classname> API, see the 
+	<ulink url="jdo-javadoc/javax/jdo/EntityManager.html">
+	Javadoc</ulink> documentation.  Methods whose parameter signatures consist 
+	of an ellipsis (...) are overloaded to take multiple parameter types.
+	</para>
+      <note>
+        <para>
+		OpenJPA extends the standard <classname>EntityManager</classname> 
+		interface with the 
+		<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>org.apache.openjpa.persistence.OpenJPAEntityManager</classname></ulink> 
+		interface to provide additional functionality.
+		</para>
+      </note>
+      <para>
+	The <classname>EntityManager</classname> is the primary interface
+	used by application developers to interact with the EJB persistence runtime.
+	The methods of the <classname>EntityManager</classname> can be
+	divided into the following functional categories:
+	</para>
+      <itemizedlist>
+        <listitem>
+          <para><classname>Transaction</classname> association.</para>
+        </listitem>
+        <listitem>
+          <para>Entity lifecycle management.</para>
+        </listitem>
+        <listitem>
+          <para>Entity identity management.</para>
+        </listitem>
+        <listitem>
+          <para>Cache management.</para>
+        </listitem>
+        <listitem>
+          <para><classname>Query</classname> factory.</para>
+        </listitem>
+        <listitem>
+          <para>Closing.</para>
+        </listitem>
+      </itemizedlist>
+      <section id="jpa_overview_em_trans">
+        <title>Transaction Association</title>
+        <indexterm zone="jpa_overview_em_trans">
+          <primary>EntityManager</primary>
+          <secondary>obtaining the Transaction</secondary>
+          <seealso>transactions</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_em_trans">
+          <primary>Transaction</primary>
+          <secondary>obtaining from EntityManager</secondary>
+        </indexterm>
+        <programlisting format="linespecific">
+public EntityTransaction getTransaction ();
+</programlisting>
+        <para>
+		Every <classname>EntityManager</classname> has a one-to-one
+		relation with an <link linkend="jpa_overview_trans"><classname>EntityTransaction</classname></link> instance. In
+		fact, many vendors use a single class to implement both
+		the <classname>EntityManager</classname> and 
+		<classname>EntityTransaction</classname> interfaces.  If your
+		application requires multiple concurrent transactions, you will
+		use multiple <classname>EntityManager</classname>s.
+		</para>
+        <para>
+		You can retrieve the <classname>EntityTransaction</classname> 
+		associated with an <classname>EntityManager</classname> through the
+		<methodname>getTransaction</methodname> method.	 Note that most 
+		most EJB persistence implementations can integrate with an application
+		server's managed transactions.  If you take advantage of this feature, 
+		you will control transactions by declarative demarcation or through
+		the Java Transaction API (JTA) rather than through the
+		<classname>EntityTransaction</classname>.
+		</para>
+      </section>
+      <section id="jpa_overview_em_lifecycle">
+        <title>Entity Lifecycle Management</title>
+        <indexterm zone="jpa_overview_em_lifecycle">
+          <primary>EntityManager</primary>
+          <secondary>lifecycle operations</secondary>
+        </indexterm>
+        <para><classname>EntityManager</classname>s perform several actions
+		that affect the lifecycle state of entity instances.  
+		</para>
+        <programlisting format="linespecific">
+public void persist (Object entity);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>persist</secondary></indexterm><indexterm><primary>persist</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>persistent objects</primary><secondary>persisting</secondary></indexterm>
+		Transitions new instances to managed.  On the next flush or commit, 
+		the newly persisted instances will be inserted into the datastore.
+		</para>
+        <para>
+		For a given entity <literal>A</literal>, the <methodname>persist
+		</methodname> method behaves as follows:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a new entity, it becomes managed.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is an existing managed entity, it is
+				ignored.  However, the persist operation cascades as 
+				defined below.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a removed entity, it becomes managed.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a detached entity, an
+				<classname>IllegalArgumentException</classname> is thrown.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				The persist operation recurses on all relation fields of 
+				<literal>A</literal> whose 
+				<link linkend="jpa_overview_meta_cascade">cascades</link> 
+				include <literal>CascadeType.PERSIST</literal>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		This action can only be used in the context of an active transaction. 
+		</para>
+        <programlisting format="linespecific">
+public void remove (Object entity);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>remove</secondary></indexterm><indexterm><primary>remove</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>persistent objects</primary><secondary>deleting</secondary></indexterm>
+		Transitions managed instances to removed.  The instances will be 
+		deleted from the datastore on the next flush or commit.  Accessing
+		a removed entity has undefined results.
+		</para>
+        <para>
+		For a given entity <literal>A</literal>, the <methodname>remove
+		</methodname> method behaves as follows:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a new entity, it is ignored.  
+				However, the remove operation cascades as defined below.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is an existing managed entity, it 
+				becomes removed.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a removed entity, it is ignored.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a detached entity, an
+				<classname>IllegalArgumentException</classname> is thrown.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				The remove operation recurses on all relation fields of 
+				<literal>A</literal> whose 
+				<link linkend="jpa_overview_meta_cascade">cascades</link> 
+				include <literal>CascadeType.REMOVE</literal>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		This action can only be used in the context of an active transaction. 
+		</para>
+        <programlisting format="linespecific">
+public void refresh (Object entity);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>refresh</secondary></indexterm><indexterm><primary>refresh</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>persistent objects</primary><secondary>refreshing state</secondary></indexterm><indexterm><primary>transactions</primary><secondary>optimistic</secondary></indexterm>
+		Use the <methodname>refresh</methodname> action to make sure
+		the persistent state of an instance is synchronized with the
+		values in the datastore.  <methodname>refresh</methodname>
+		is intended for long-running optimistic transactions in
+		which there is a danger of seeing stale data.
+		</para>
+        <para>
+		For a given entity <literal>A</literal>, the <methodname>refresh
+		</methodname> method behaves as follows:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a new entity, it is ignored.  
+				However, the remove operation cascades as defined below.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is an existing managed entity, its 
+				state is refreshed from the datastore.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a removed entity, it is ignored.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a detached entity, an
+				<classname>IllegalArgumentException</classname> is thrown.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				The refresh operation recurses on all relation fields of 
+				<literal>A</literal> whose 
+				<link linkend="jpa_overview_meta_cascade">cascades</link> 
+				include <literal>CascadeType.REFRESH</literal>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <programlisting format="linespecific">
+public Object merge (Object entity);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>merge</secondary><seealso>detachment</seealso></indexterm><indexterm><primary>detachment</primary><secondary>EJB</secondary></indexterm><indexterm><primary>merge</primary><seealso>detachment</seealso></indexterm><indexterm><primary>data transfer object</primary></indexterm><indexterm><primary>value object</primary></indexterm>
+		A common use case for an application running in a servlet or
+		application server is to "detach" objects from all server resources,
+		modify them, and then "attach" them again. For example, a servlet
+		might store persistent data in a user session between a modification
+		based on a series of web forms. Between each form request, the web
+		container might decide to serialize the session, requiring that the
+		stored persistent state be disassociated from any other
+		resources. Similarly, a client/server application might
+		transfer persistent objects to a client via serialization, allow the
+		client to modify their state, and then have the client return the
+		modified data in order to be saved. This is sometimes referred to as
+		the <emphasis>data transfer object</emphasis> or <emphasis>value 
+		object</emphasis> pattern, and it allows fine-grained manipulation 
+		of data objects without incurring the overhead of multiple remote 
+		method invocations.
+		</para>
+        <para>
+		EJB persistence provides support for this pattern by automatically
+		detaching entities when they are serialized or when a persistence
+		context ends (see 
+		<xref linkend="jpa_overview_emfactory_perscontext"/> for an
+		exploration of persistence contexts).  The EJB persistence 
+		<emphasis>merge</emphasis> API re-attaches detached entities.
+		This allows you to detach a persistent instance, modify the
+		detached instance offline, and merge the instance back into an 
+		<classname>EntityManager</classname> (either the same one that 
+		detached the instance, or a new one). The changes will then be 
+		applied to the existing instance from the datastore.  
+		</para>
+        <para>
+		A detached entity maintains its persistent identity, but cannot load 
+		additional state from the datastore.  Accessing any persistent field or
+		property that was not loaded at the time of detachment has undefined 
+		results.  Also, be sure not to alter the version or identity fields of
+		detached instances if you plan on merging them later.
+		</para>
+        <para>
+		The <methodname>merge</methodname> method returns a managed copy of the
+		given detached entity.  Changes made to the persistent state of the
+		detached entity are applied to this managed instance.  Because merging 
+		involves changing persistent state, you can only merge within a 
+		transaction.
+		</para>
+        <para>
+		If you attempt to merge an instance whose representation has
+		changed in the datastore since detachment, the merge operation will
+		throw an exception, or the transaction in which you perform the 
+		merge will fail on commit, just as if a normal optimistic conflict
+		were detected.
+		</para>
+        <note>
+          <para>
+			OpenJPA offers enhancements to EJB persistence detachment 
+			functionality, including additional options to control which 
+			fields are detached.  See <xref linkend="ref_guide_detach"/> 
+			in the Reference Guide for details.
+			</para>
+        </note>
+        <para>
+		For a given entity <literal>A</literal>, the <methodname>merge
+		</methodname> method behaves as follows:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a detached entity, its state
+				is copied into existing managed instance <literal>A'</literal>
+				of the same entity identity, or a new managed copy of
+				<literal>A</literal> is created.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a new entity, a new managed
+				entity <literal>A'</literal> is created and the state of 
+				<literal>A</literal> is copied into <literal>A'</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is an existing managed entity, it is
+				ignored.  However, the merge operation still cascades as 
+				defined below.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				If <literal>A</literal> is a removed entity, an
+				<classname>IllegalArgumentException</classname> is thrown.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				The merge operation recurses on all relation fields of 
+				<literal>A</literal> whose 
+				<link linkend="jpa_overview_meta_cascade">cascades</link> 
+				include <literal>CascadeType.MERGE</literal>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <programlisting format="linespecific">
+public void lock (Object entity, LockModeType mode);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>lock</secondary></indexterm><indexterm><primary>locking</primary><seealso>EntityManager</seealso></indexterm>
+		This method locks the given entity using the named mode.  The
+		<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/LockmodeType.html"><classname>javax.persistence.LockModeType</classname></ulink> enum
+		defines two modes:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>READ</literal>: Other transactions may concurrently 
+				read the object, but cannot concurrently update it.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>WRITE</literal>: Other transactions cannot 
+				concurrently read or write the object. When a transaction
+				is committed that holds WRITE locks on any entites, those
+				entites will have their version incremented even if
+				the entities themselves did not change in the transaction.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <note>
+          <para>
+			OpenJPA has additional APIs for controlling object locking.  See
+			<xref linkend="ref_guide_locking"/> in the Reference Guide for
+			details.
+			</para>
+        </note>
+        <para>
+		The following diagram illustrates the lifecycle of an entity with
+		respect to the APIs presented in this section.
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 445 x 337 (see README) -->
+            <imagedata fileref="img/ejb3-state-transitions.png" width="297px"/>
+          </imageobject>
+        </mediaobject>
+      </section>
+      <section id="jpa_overview_em_lifeexamples">
+        <title>Lifecycle Examples</title>
+        <para>
+		The examples below demonstrate how to use the lifecycle methods
+		presented in the previous section.  The examples are appropriate for
+		out-of-container use.  Within a container, <classname>
+		EntityManager</classname>s are usually injected, and transactions are 
+		usually managed.  You would therefore omit the 
+		<methodname>createEntityManager</methodname> and <methodname>close
+		</methodname> calls, as well as all transaction demarcation code.
+		</para>
+        <example id="jpa_overview_em_lifecycle_persist">
+          <title>Persisting Objects</title>
+          <indexterm>
+            <primary>persistent objects</primary>
+            <secondary>persisting</secondary>
+            <tertiary>example</tertiary>
+          </indexterm>
+          <programlisting format="linespecific">
+// create some objects
+Magazine mag = new Magazine ("1B78-YU9L", "JavaWorld");
+
+Company pub = new Company ("Weston House");
+pub.setRevenue (1750000D);
+mag.setPublisher (pub);
+pub.addMagazine (mag);
+
+Article art = new Article ("EJB Rules!", "Transparent Object Persistence");
+art.addAuthor (new Author ("Fred", "Hoyle"));
+mag.addArticle (art);
+
+// persist
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+em.persist (mag);
+em.persist (pub);
+em.persist (art);
+em.getTransaction ().commit ();
+
+// or we could continue using the EntityManager...
+em.close ();
+</programlisting>
+        </example>
+        <example id="jpa_overview_em_lifecycle_update">
+          <title>Updating Objects</title>
+          <indexterm>
+            <primary>persistent objects</primary>
+            <secondary>updating</secondary>
+            <tertiary>example</tertiary>
+          </indexterm>
+          <programlisting format="linespecific">
+Magazine.MagazineId mi = new Magazine.MagazineId ();
+mi.isbn = "1B78-YU9L";
+mi.title = "JavaWorld";
+
+// updates should always be made within transactions; note that
+// there is no code explicitly linking the magazine or company
+// with the transaction; EJB automatically tracks all changes
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+Magazine mag = em.find (Magazine.class, mi);
+mag.setPrice (5.99);
+Company pub = mag.getPublisher ();
+pub.setRevenue (1750000D);
+em.getTransaction ().commit ();
+
+// or we could continue using the EntityManager...
+em.close ();
+</programlisting>
+        </example>
+        <example id="jpa_overview_em_lifecycle_delete">
+          <title>Removing Objects</title>
+          <indexterm>
+            <primary>persistent objects</primary>
+            <secondary>deleting</secondary>
+            <tertiary>example</tertiary>
+          </indexterm>
+          <programlisting format="linespecific">
+// assume we have an object id for the company whose subscriptions
+// we want to delete
+Object oid = ...;
+
+// deletes should always be made within transactions
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+Company pub = (Company) em.find (Company.class, oid);
+for (Subscription sub : pub.getSubscriptions ())
+    em.remove (sub);
+pub.getSubscriptions ().clear ();
+em.getTransaction ().commit ();
+
+// or we could continue using the EntityManager...
+em.close ();
+</programlisting>
+        </example>
+        <example id="jpa_overview_em_detachex">
+          <title>Detaching and Merging</title>
+          <para>
+			This example demonstrates a common client/server scenario.  The
+			client requests objects and makes changes to them, while the 
+			server handles the object lookups and transactions.
+			</para>
+          <programlisting format="linespecific">
+// CLIENT:
+// requests an object with a given oid
+Record detached = (Record) getFromServer (oid);
+
+...
+
+// SERVER:
+// send object to client; object detaches on EM close
+Object oid = processClientRequest ();
+EntityManager em = emf.createEntityManager ();
+Record record = em.find (Record.class, oid);
+em.close ();
+sendToClient (record);
+
+...
+
+// CLIENT:
+// makes some modifications and sends back to server
+detached.setSomeField ("bar");
+sendToServer (detached);
+
+...
+
+// SERVER:
+// merges the instance and commit the changes
+Record modified = (Record) processClientRequest ();
+EntityManager em = emf.createEntityManager ();
+em.getTransaction ().begin ();
+Record merged = (Record) em.merge (modified);
+merged.setLastModified (System.currentTimeMillis ());
+merged.setModifier (getClientIdentityCode ());
+em.getTransaction ().commit ();
+em.close ();
+</programlisting>
+        </example>
+      </section>
+      <section id="jpa_overview_em_identity">
+        <title>Entity Identity Management</title>
+        <para>
+		Each <classname>EntityManager</classname> is responsible for
+		managing the persistent identities of the managed objects in the
+		persistence context.  The following methods allow you to interact 
+		with the management of persistent identities.  The behavior of these
+		methods is deeply affected by the persistence context type of the
+		<classname>EntityManager</classname>; see 
+		<xref linkend="jpa_overview_emfactory_perscontext"/> for an
+		explanation of persistence contexts.
+		</para>
+        <programlisting format="linespecific">
+public &lt;T&gt; T find (Class&lt;T&gt; cls, Object oid);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>find</secondary><seealso>identity</seealso></indexterm><indexterm><primary>find</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>identity</primary><secondary>retrieving objects by identity</secondary></indexterm>
+		This method returns the persistent instance of the given type with
+		the given persistent identity.  If the instance is already present in
+		the current persistence context, the cached version will be returned.  
+		Otherwise, a new instance will be constructed and loaded with 
+		state from the datastore.  If no entity with the given type and identity
+		exists in the datastore, this method returns null.
+		</para>
+        <programlisting format="linespecific">
+public &lt;T&gt; T getReference (Class&lt;T&gt; cls, Object oid);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>getReference</secondary><seealso>identity</seealso></indexterm><indexterm><primary>getReference</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>identity</primary><secondary>retrieving objects by identity</secondary></indexterm><indexterm><primary>EntityNotFoundException</primary></indexterm>
+		This method is similar to <methodname>find</methodname>, but does not
+		necessarily go to the database when the entity is not found in cache.
+		The implementation may construct a <emphasis>hollow</emphasis> entity 
+		and return it to you instead.  Hollow entities do not have any
+		state loaded.  The state only gets loaded when you attempt to access
+		a persistent field.  At that time, the implementation may throw an
+		<classname>EntityNotFoundException</classname> if it discovers that
+		the entity does not exist in the datastore.  The implementation may
+		also throw an <classname>EntityNotFoundException</classname> from
+		the <methodname>getReference</methodname> method itself.  Unlike 
+		<methodname>find</methodname>, <methodname>getReference</methodname>
+		does not return null.
+		</para>
+        <programlisting format="linespecific">
+public boolean contains (Object entity);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>contains</secondary></indexterm><indexterm><primary>contains</primary><seealso>EntityManager</seealso></indexterm>
+		Returns true if the given entity is part of the current persistence
+		context, and false otherwise.  Removed entities are not considered part
+		of the current persistence context.
+		</para>
+      </section>
+      <section id="jpa_overview_em_cache">
+        <title>Cache Management</title>
+        <indexterm zone="jpa_overview_em_cache">
+          <primary>EntityManager</primary>
+          <secondary>cache</secondary>
+        </indexterm>
+        <programlisting format="linespecific">
+public void flush ();
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>flush</secondary></indexterm><indexterm><primary>flush</primary><seealso>EntityManager</seealso></indexterm><indexterm><primary>transactions</primary><secondary>flushing changes before commit</secondary></indexterm>
+		The <methodname>flush</methodname> method writes any changes that have
+		been made in the current transaction to the datastore.  If the
+		<classname>EntityManager</classname> does not already have a 
+		connection to the datastore, it obtains one for the flush and retains
+		it for the duration of the transaction.  Any exceptions during flush
+		cause the transaction to be marked for rollback.
+		See <xref linkend="jpa_overview_trans"/>.
+		</para>
+        <para>
+		Flushing requires an active transaction.  If there isn't a transaction
+		in progress, the <methodname>flush</methodname> method throws a
+		<classname>TransactionRequiredException</classname>.
+		</para>
+        <programlisting format="linespecific">
+public FlushModeType getFlushMode ();
+public void setFlushMode (FlushModeType flushMode);
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>FlushMode</secondary></indexterm><indexterm><primary>FlushMode</primary></indexterm>
+		The <classname>EntityManager</classname>'s <literal>FlushMode</literal>
+		property controls whether to flush transactional changes before 
+		executing queries.  This allows the query results to take into account
+		changes you have made during the current transaction.  Available
+		<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/FlushModeType.html"><classname>javax.persistence.FlushModeType</classname></ulink> constants
+		are:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>COMMIT</literal>: Only flush when committing, or
+				when told to do so through the <methodname>flush</methodname>
+				method.  Query results may not take into account changes made
+				in the current transaction.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>AUTO</literal>: The implementation is permitted to
+				flush before queries to ensure that the results reflect the
+				most recent object state.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		You can also set the flush mode on individual 
+		<link linkend="jpa_overview_query"><classname>Query</classname></link>
+		instances.
+		</para>
+        <note>
+          <para>
+			OpenJPA only flushes before a query if the query might be affected
+			by data changed in the current transaction.  Additionally,
+			OpenJPA allows fine-grained control over flushing behavior.
+			See the Reference Guide's 
+			<xref linkend="ref_guide_dbsetup_retain"/>.
+			</para>
+        </note>
+        <programlisting format="linespecific">
+public void clear ();
+</programlisting>
+        <para><indexterm><primary>EntityManager</primary><secondary>clear</secondary></indexterm><indexterm><primary>clear</primary><seealso>EntityManager</seealso></indexterm>
+		Clearing the <classname>EntityManager</classname> effectively ends the
+		persistence context.  All entities managed by
+		the <classname>EntityManager</classname> become detached. 
+		</para>
+      </section>
+      <section id="jpa_overview_em_query">
+        <title>Query Factory</title>
+        <indexterm zone="jpa_overview_em_query">
+          <primary>EntityManager</primary>
+          <secondary>as Query factory</secondary>
+          <seealso>Query</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_em_query">
+          <primary>Query</primary>
+          <secondary>creating</secondary>
+        </indexterm>
+        <programlisting format="linespecific">
+public Query createQuery (String query);
+</programlisting>
+        <para><classname>Query</classname> objects are used to find entities
+		matching certain criteria.  The <methodname>createQuery</methodname>
+		method creates a query using the given EJB Query Language (JPQL) 
+		string. See <xref linkend="jpa_overview_query"/> for details.
+		</para>
+        <programlisting format="linespecific">
+public Query createNamedQuery (String name);
+</programlisting>
+        <para>
+		This method retrieves a query defined in metadata by name.  The returned
+		<classname>Query</classname> instance is initialized with the 
+		information declared in metadata.  For more information on named 
+		queries, read <xref linkend="jpa_overview_query_named"/>.
+		</para>
+        <programlisting format="linespecific">
+public Query createNativeQuery (String sql);
+public Query createNativeQuery (String sql, Class resultCls);
+public Query createNativeQuery (String sql, String resultMapping);
+</programlisting>
+        <para><emphasis>Native</emphasis> queries are queries in the datastore's
+		native language.  For relational databases, this the Structured Query 
+		Language (SQL).  <xref linkend="jpa_overview_sqlquery"/> elaborates
+		on EJB persistence's native query support.  
+		</para>
+      </section>
+      <section id="jpa_overview_em_closing">
+        <title>Closing</title>
+        <indexterm zone="jpa_overview_em_closing">
+          <primary>EntityManager</primary>
+          <secondary>closing</secondary>
+        </indexterm>
+        <programlisting format="linespecific">
+public boolean isOpen ();
+public void close ();
+</programlisting>
+        <para>
+		When an <classname>EntityManager</classname> is no longer
+		needed, you should call its <methodname>close</methodname> method.
+		Closing an <classname>EntityManager</classname> releases any resources 
+		it is using.  The persistence context ends, and the entities managed by
+		the <classname>EntityManager</classname> become detached. 
+		Any <classname>Query</classname> instances the <classname>EntityManager
+		</classname> created become invalid.
+		Calling any method other than <methodname>isOpen</methodname> on a 
+		closed <classname>EntityManager</classname> results in an
+		<classname>IllegalStateException</classname>.  You cannot close a 
+		<classname>EntityManager</classname> that is in the middle of a
+		transaction.
+		</para>
+        <para>
+		If you are in a managed environment using injected entity managers,
+		you should not close them.  
+		</para>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_trans">
+      <title>Transaction</title>
+      <indexterm zone="jpa_overview_trans">
+        <primary>transactions</primary>
+        <seealso>Transaction</seealso>
+      </indexterm>
+      <para>
+	Transactions are critical to maintaining data integrity.  They are 
+	used to group operations into units of work that act in an 
+	all-or-nothing fashion.  Transactions have the following qualities:
+	</para>
+      <itemizedlist>
+        <listitem>
+          <para><indexterm><primary>atomicity</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>atomicity</secondary></indexterm><emphasis>Atomicity</emphasis>.  Atomicity refers to the
+			all-or-nothing property of transactions.  Either every 
+			data update in the transaction completes successfully, or they
+			all fail, leaving the datastore in its original state.  A
+			transaction cannot be only partially successful.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>consistency</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>consistency</secondary></indexterm><emphasis>Consistency</emphasis>.  Each transaction takes the
+			datastore from one consistent state to another consistent
+			state.  
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>isolation</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>isolation</secondary></indexterm><emphasis>Isolation</emphasis>.  Transactions are isolated from
+			each other.  When you are reading persistent data in one
+			transaction, you cannot "see" the changes that are being made
+			to that data in other transactions.  Similarly,
+			the updates you make in one transaction cannot conflict with
+			updates made in concurrent transactions.  The form of
+			conflict resolution employed depends on whether you are using
+			pessimistic or optimistic transactions.  Both types are
+			described later in this chapter.
+			</para>
+        </listitem>
+        <listitem>
+          <para><indexterm><primary>durability</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>durability</secondary></indexterm><emphasis>Durability</emphasis>.  The effects of successful
+			transactions are durable; the updates made to persistent data
+			last for the lifetime of the datastore.
+			</para>
+        </listitem>
+      </itemizedlist>
+      <para><indexterm><primary>ACID</primary><seealso>transactions</seealso></indexterm><indexterm><primary>transactions</primary><secondary>ACID</secondary></indexterm>
+	Together, these qualities are called the ACID properties of
+	transactions.  To understand why these properties are so important
+	to maintaining data integrity, consider the following example:
+	</para>
+      <para>
+	Suppose you create an application to manage bank accounts.  The 
+	application includes a method to transfer funds from one user to
+	another, and it looks something like this:
+	</para>
+      <programlisting format="linespecific">
+public void transferFunds (User from, User to, double amnt)
+{
+    from.decrementAccount (amnt);
+    to.incrementAccount (amnt);
+}
+</programlisting>
+      <para>
+	Now suppose that user Alice wants to transfer 100 dollars to user Bob.
+	No problem; you simply invoke your 
+	<methodname>transferFunds</methodname> method, supplying Alice in the
+	<literal>from</literal> parameter, Bob in the <literal>to</literal>
+	parameter, and <literal>100.00</literal> as the <literal>amnt</literal>.
+	The first line of the method is executed, and 100 dollars is subtracted
+	from Alice's account.  But then, something goes wrong.  An unexpected
+	exception occurs, or the hardware fails, and your method never
+	completes.
+	</para>
+      <para>
+	You are left with a situation in which the 100 dollars has simply 
+	disappeared.  Thanks to the first line of your method, it is no longer
+	in Alice's account, and yet it was never transferred to Bob's account 
+	either.  The datastore is in an inconsistent state.
+	</para>
+      <para>
+	The importance of transactions should now be clear.  If the two lines
+	of the <methodname>transferFunds</methodname> method had been placed 
+	together in a transaction, it would be impossible for only the
+	first line to succeed.  Either the funds would be transferred 
+	properly or they would not be transferred at all, and an exception
+	would be thrown.  Money could never vanish into thin air, and the data 
+	store could never get into an inconsistent state.  
+	</para>
+      <section id="jpa_overview_trans_types">
+        <title>Transaction Types</title>
+        <indexterm zone="jpa_overview_trans_types">
+          <primary>transactions</primary>
+          <secondary>types</secondary>
+        </indexterm>
+        <para>
+		There are two major types of transactions: pessimistic transactions 
+		and optimistic transactions.  Each type has both advantages and 
+		disadvantages.
+		</para>
+        <para><indexterm><primary>transactions</primary><secondary>pessimistic</secondary></indexterm><indexterm><primary>pessimistic transactions</primary><see>transactions, pessimistic</see></indexterm><indexterm><primary>deadlock</primary><seealso>transactions</seealso></indexterm>
+		Pessimistic transactions generally lock the datastore records they
+		act on, preventing other concurrent transactions from using the
+		same data.  This avoids conflicts between transactions, but 
+		consumes database resources.  Additionally, locking records
+		can result in <emphasis>deadlock</emphasis>, a situation in which two 
+		transactions are both waiting for the other to release its locks before
+		completing.  The results of a deadlock are datastore-dependent; 
+		usually one transaction is forcefully rolled back after some specified 
+		timeout interval, and an exception is thrown.
+		</para>
+        <para><indexterm><primary>transactions</primary><secondary>datastore</secondary></indexterm><indexterm><primary>datastore transactions</primary><see>transactions, datastore</see></indexterm>
+		This document will often use the term <emphasis>datastore</emphasis>
+		transaction in place of <emphasis>pessimistic</emphasis> transaction.
+		This is to acknowledge that some datastores do not support pessimistic 
+		semantics, and that the exact meaning of a non-optimistic JPA 
+		transaction is dependent on the datastore.  Most of the 
+		time, a datastore transaction is equivalent to a pessimistic 
+		transaction.  
+		</para>
+        <para><indexterm><primary>transactions</primary><secondary>optimistic</secondary></indexterm><indexterm><primary>optimistic transactions</primary><see>transactions, optimistic</see></indexterm>
+		Optimistic transactions consume less resources than
+		pessimistic/datastore transactions, but only at the expense of 
+		reliability.  Because optimistic transactions do not lock datastore 
+		records, two transactions might change the same persistent information
+		at the same time, and the conflict will not be detected until
+		the second transaction attempts to flush or commit.  At this time, the
+		second transaction will realize that another transaction has 
+		concurrently modified the same records (usually through a timestamp
+		or versioning system), and will throw an appropriate exception.
+		Note that optimistic transactions still maintain data integrity;
+		they are simply more likely to fail in heavily concurrent 
+		situations.
+		</para>
+        <para>
+		Despite their drawbacks, optimistic transactions are the best choice
+		for most applications.  They offer better performance, better
+		scalability, and lower risk of hanging due to deadlock.  
+		</para>
+        <note>
+          <para>
+			OpenJPA uses optimistic semantics by default, but supports both 
+			optimistic and datastore transactions.
+			OpenJPA also offers advanced locking and versioning APIs for 
+			fine-grained control over database resource allocation and object 
+			versioning.  See <xref linkend="ref_guide_locking"/> and
+			<xref linkend="ref_guide_lock_groups"/> of the Reference Guide for 
+			details on locking.  <xref linkend="jpa_overview_meta_version"/>
+			of this document covers standard object versioning.
+			<!-- ### EJBDOC : link additional strats when available from JPA -->
+			</para>
+        </note>
+      </section>
+      <section id="jpa_overview_trans_ejb3">
+        <title>The EntityTransaction Interface</title>
+        <indexterm zone="jpa_overview_trans_ejb3">
+          <primary>Transaction</primary>
+          <seealso>transactions</seealso>
+        </indexterm>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 193 x 157 (see README) -->
+            <imagedata fileref="img/ejb3-transaction.png" width="129px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		JPA integrates with your container's <emphasis>managed
+		</emphasis> transactions, allowing you to use the container's 
+		declarative transaction demarcation and its Java Transaction API (JTA) 
+		implementation for transaction management.  
+		Outside of a container, though, you must demarcate transactions
+		manually through JPA.  The <classname>
+		EntityTransaction</classname> interface controls unmanaged transactions
+		in JPA.  
+		</para>
+        <programlisting format="linespecific">
+public void begin ();
+public void commit ();
+public void rollback ();
+</programlisting>
+        <para><indexterm><primary>Transaction</primary><secondary>demarcation</secondary></indexterm><indexterm><primary>transactions</primary><secondary>demarcating</secondary></indexterm><indexterm><primary>Transaction</primary><secondary>begin</secondary></indexterm><indexterm><primary>Transaction</primary><secondary>commit</secondary></indexterm><indexterm><primary>Transaction</primary><secondary>rollback</secondary></indexterm>
+		The <methodname>begin</methodname>, <methodname>commit</methodname>,
+		and <methodname>rollback</methodname> methods demarcate transaction
+		boundaries.  The methods should be self-explanatory: 
+		<methodname>begin</methodname> starts a transaction, 
+		<methodname>commit</methodname> attempts to commit the transaction's
+		changes to the datastore, and <methodname>rollback</methodname>
+		aborts the transaction, in which case the datastore is 
+		"rolled back" to its previous state.  JPA 
+		implementations will automatically roll back transactions if any 
+		exception is thrown during the commit process.
+		</para>
+        <para>
+		Unless you are using an extended persistence context, committing or
+		rolling back also ends the persistence context.  All managed entites
+		will be detached from the <classname>EntityManager</classname>.
+		</para>
+        <programlisting format="linespecific">
+public boolean isActive ();
+</programlisting>
+        <para><indexterm><primary>Transaction</primary><secondary>isActive</secondary></indexterm>
+		Finally, the <methodname>isActive</methodname> method returns 
+		<literal>true</literal> if the transaction is in progress 
+		(<methodname>begin</methodname> has been called more recently than 
+		<methodname>commit</methodname> or 
+		<methodname>rollback</methodname>), and <literal>false</literal> 
+		otherwise.
+		</para>
+        <example id="jpa_overview_trans_group">
+          <title>Grouping Operations with Transactions</title>
+          <programlisting format="linespecific">
+public void transferFunds (EntityManager em, User from, User to, double amnt)
+{
+    // note: it would be better practice to move the transaction demarcation
+    // code out of this method, but for the purposes of example...
+    Transaction trans = em.getTransaction ();
+    trans.begin ();
+    try
+    {
+        from.decrementAccount (amnt);
+        to.incrementAccount (amnt);
+        trans.commit ();
+    }
+    catch (RuntimeException re)
+    {
+        if (trans.isActive ())
+            trans.rollback ();   // or could attempt to fix error and retry
+        throw re;
+    }
+}
+</programlisting>
+        </example>
+      </section>
+    </chapter>
+<!-- author: Marc Prud'hommeaux -->
+    <chapter id="jpa_overview_query">
+      <title>JPA Query</title>
+      <indexterm zone="jpa_overview_query">
+        <primary>JP Query</primary>
+        <seealso>JPQL</seealso>
+      </indexterm>
+      <indexterm>
+        <primary>queries</primary>
+        <see>Query</see>
+      </indexterm>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 292 x 265 (see README) -->
+          <imagedata fileref="img/ejb3-query.png" width="195px"/>
+        </imageobject>
+      </mediaobject>
+      <para>
+	The <classname>javax.persistence.Query</classname> interface is the 
+	mechanism for issuing queries in JPA. The primary query language used is
+	the Java Persistence Query Language, or <literal>JPQL</literal>.  JPQL is 
+	syntactically very similar to SQL, but is object-oriented rather than 
+	table-oriented.
+	</para>
+      <para>
+	The API for executing JPQL queries will be discussed in
+	<xref linkend="jpa_query_api"/>, and a full language
+	reference will be covered in <xref linkend="jpa_langref"/>.
+	</para>
+      <section id="jpa_query_api">
+        <title>JPQL API</title>
+        <section id="jpa_overview_query_basic">
+          <title>Query Basics</title>
+          <programlisting format="linespecific">SELECT x FROM Magazine x</programlisting>
+          <para>
+			The preceding is a simple JPQL query for all <classname>Magazine
+			</classname> entities.
+			</para>
+          <programlisting format="linespecific">
+public Query createQuery (String jpql);
+</programlisting>
+          <para>
+			The <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html"><methodname>EntityManager.createQuery</methodname></ulink>
+			method creates a <classname>Query</classname> instance from a given
+			JPQL string.
+			</para>
+          <programlisting format="linespecific">
+public List getResultList ();
+</programlisting>
+          <para>
+			Invoking
+			<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html#getResultList()"><methodname>Query.getResultList</methodname></ulink> executes the query
+			and returns a <classname>List</classname> containing the matching 
+			objects.  The following example executes our <classname>Magazine
+			</classname> query above:
+			</para>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createQuery ("SELECT x FROM Magazine x");
+List&lt;Magazine&gt; results = q.getResultList ();
+</programlisting>
+          <para>
+			A JPQL query has an internal namespace declared in
+			the <literal>from</literal> clause of the query. Arbitrary identifiers 
+			are assigned to entities so that they can be referenced elsewhere in the
+			query. In the query example above, the identifier 
+			<literal>x</literal> is assigned to the entity <classname>
+			Magazine</classname>.
+			</para>
+          <note>
+            <para>
+				The <literal>as</literal> keyword can optionally be used when 
+				declaring identifiers in the <literal>from</literal> clause. 
+				<literal>SELECT x FROM Magazine x</literal> and
+				<literal>SELECT x FROM Magazine AS x</literal> are synonymous.
+				</para>
+          </note>
+          <para>
+			Following the <literal>select</literal> clause of the query is the 
+			object or objects that the query returns. In the case of the query 
+			above, the query's result list will contain instances of the 
+			<classname>Magazine</classname> class.
+			</para>
+          <note>
+            <para>
+				When selecting entities, you can optional use the keyword 
+				<literal>object</literal>. The clauses <literal>select x</literal> 
+				and <literal>SELECT OBJECT(x)</literal> are synonymous.
+				</para>
+          </note>
+          <para>
+			The optional <literal>where</literal> clause places criteria on 
+			matching results.  For example:
+			</para>
+          <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.title = 'JDJ'</programlisting>
+          <para>
+			Keywords in JPQL expressions are case-insensitive, but
+			entity, identifier, and member names are not. For example,
+			the expression above could also be expressed as:
+			</para>
+          <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.title = 'JDJ'</programlisting>
+          <para>
+			But it could not be expressed as:
+			</para>
+          <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.TITLE = 'JDJ'</programlisting>
+          <para>
+			As with the <literal>select</literal> clause, alias names in the
+			<literal>where</literal> clause are resolved 
+			to the entity declared in the <literal>from</literal> clause. The query
+			above could be described in English as "for all <classname>Magazine
+			</classname> instances <literal>x</literal>, return a list of every 
+			<literal>x</literal> such that <literal>x</literal>'s <literal>title
+			</literal> field is equal to 'JDJ'".
+			</para>
+          <para>
+			JPQL uses SQL-like syntax for query criteria.  The <literal>and
+			</literal> and <literal>or</literal> logical operators chain
+			multiple criteria together:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro'
+</programlisting>
+          <para>
+			The <literal>=</literal> operator tests for equality.  <literal>&lt;&gt;
+			</literal> tests for inequality.  JPQL also
+			supports the following arithmetic operators for numeric comparisons:	
+			<literal>&gt;, &gt;=, &lt;, &lt;=</literal>.  For example:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.price &gt; 3.00 AND x.price &lt;= 5.00
+</programlisting>
+          <para>
+			This query returns all magazines whose price is greater than 3.00
+			and less than or equal to 5.00.
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.price &lt;&gt; 3.00
+</programlisting>
+          <para>
+			This query returns all Magazines whose price is not equals to 3.00.
+			</para>
+          <para>
+			You can group expressions together using parentheses in order to
+			specify how they are evaluated. This is similar to how parentheses are
+			used in Java. For example:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE (x.price &gt; 3.00 AND x.price &lt;= 5.00) OR x.price = 7.00
+</programlisting>
+          <para>
+			This expression would match magazines whose price
+			is 4.00, 5.00, or 7.00, but not 6.00. Alternately:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.price &gt; 3.00 AND (x.price &lt;= 5.00 OR x.price = 7.00)
+</programlisting>
+          <para>
+			This expression will magazines whose price is 5.00 or 7.00, but 
+			not 4.00 or 6.00.
+			</para>
+          <para>
+			JPQL also includes the following conditionals:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><indexterm><primary>BETWEEN expressions</primary></indexterm><literal>[NOT] BETWEEN</literal>: Shorthand for expressing 
+					that a value falls between two other values.
+					The following two statements are synonymous:
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.price &gt;= 3.00 AND x.price &lt;= 5.00
+</programlisting>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.price BETWEEN 3.00 AND 5.00
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>LIKE expressions</primary></indexterm><literal>[NOT] LIKE</literal>: Performs a string comparison 
+					with wildcard support. The special character '_' in the 
+					parameter means to match any single character, and the special 
+					character '%' means to match any sequence of characters.
+					The following statement matches title fields "JDJ" and 
+					"JavaPro", but not "IT Insider":
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.title LIKE 'J%'
+</programlisting>
+              <para>
+					The following statement matches the title field "JDJ" 
+					but not "JavaPro":
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.title LIKE 'J__'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>IN expressions</primary></indexterm><literal>[NOT] IN</literal>: Specifies that the member must be 
+					equal to one element of the provided list.
+					The following two statements are synonymous:
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.title IN ('JDJ', 'JavaPro', 'IT Insider')
+</programlisting>
+              <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.title = 'JDJ' OR x.title = 'JavaPro' OR x.title = 'IT Insider'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>IS EMPTY expressions</primary></indexterm><literal>IS [NOT] EMPTY</literal>: Specifies that the 
+					collection field holds no elements. For example:
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.articles is empty
+</programlisting>
+              <para>
+					This statement will return all magazines whose <literal>
+					articles</literal> member contains no elements.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>IS NULL expressions</primary></indexterm><literal>IS [NOT] NULL</literal>: Specifies that the field is 
+					equal to null. For example:
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.publisher is null
+</programlisting>
+              <para>
+					This statement will return all Magazine instances whose
+					"publisher" field is set to <literal>null</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>NOT expressions</primary></indexterm><literal>NOT</literal>: Negates the contained expression. For 
+					example, the following two statements are synonymous:
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE NOT(x.price = 10.0)
+</programlisting>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.price &lt;&gt; 10.0
+</programlisting>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_query_relations">
+          <title>Relation Traversal</title>
+          <para>
+			Relations between objects can be traversed using Java-like syntax.
+			For example, if the Magazine class has a field named "publisher" or
+			type Company, that relation can be queried as follows:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.publisher.name = 'Random House'
+</programlisting>
+          <para>
+			This query returns all <classname>Magazine</classname> instances whose 
+			<literal>publisher</literal> field is set to a <classname>Company 
+			</classname> instance whose name is "Random House".
+			</para>
+          <para>
+			Single-valued relation traversal implies that the relation is not null.
+			In SQL terms, this is known as an <emphasis>inner join</emphasis>. If 
+			you want to also include relations that are null, you can specify:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE x.publisher.name = 'Random House' or x.publisher is null
+</programlisting>
+          <para>
+			You can also traverse collection fields in queries, but you must declare
+			each traversal in the <literal>from</literal> clause.
+			Consider:
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x, IN(x.articles) y WHERE y.authorName = 'John Doe'
+</programlisting>
+          <para>
+			This query says that for each <classname>Magazine</classname> <literal>
+			x</literal>, traverse the <literal>articles</literal> relation and 
+			check each <classname>Article</classname> <literal>y</literal>, and 
+			pass the filter if <literal>y</literal>'s <literal>authorName</literal>
+			field is equal to "John Doe". In short, this query will return all 
+			magazines that have any articles written by John Doe.
+			</para>
+          <note>
+            <para>
+				The <literal>IN()</literal> syntax can also be expressed with the 
+				keywords <literal>inner join</literal>.  The statements
+				<literal>SELECT x FROM Magazine x, IN(x.articles) y WHERE 
+				y.authorName = 'John Doe'</literal> and
+				<literal>SELECT x FROM Magazine x inner join x.articles y
+				WHERE y.authorName = 'John Doe'</literal> are synonymous.
+				</para>
+          </note>
+        </section>
+        <section id="jpa_overview_join_fetch">
+          <title>Fetch Joins</title>
+          <para>
+			JPQL queries may specify one or more <literal>join fetch</literal> 
+			declarations, which allow the query to specify which fields
+			in the returned instances will be pre-fetched.
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x join fetch x.articles WHERE x.title = 'JDJ'
+</programlisting>
+          <para>
+			The query above returns <classname>Magazine</classname> instances 
+			and guarantees that the <literal>articles</literal> field will
+			already be fetched in the returned instances.
+			</para>
+          <para>
+			Multiple fields may be specified in separate
+			<literal>join fetch</literal> declarations:
+<programlisting format="linespecific">
+SELECT x FROM Magazine x join fetch x.articles join fetch x.authors WHERE x.title = 'JDJ'
+</programlisting>
+			</para>
+          <para>
+            <note>
+              <para>
+				Specifying the <literal>join fetch</literal> declaration
+				is functionally equivalent to adding the fields to
+				the Query's <classname>FetchConfiguration</classname>.
+				See <xref linkend="ref_guide_fetch"/>.
+				</para>
+            </note>
+          </para>
+        </section>
+        <section id="jpa_overview_query_functions">
+          <title>JPQL Functions</title>
+          <para>
+			As well as supporting direct field and relation comparisons,
+			JPQL supports a pre-defined set of functions that you can apply.
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><indexterm><primary>CONCAT function</primary></indexterm><literal>CONCAT(string1, string2)</literal>: Concatenates two 
+					string fields or literals. For example:
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE CONCAT(x.title, 's') = 'JDJs'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>SUBSTRING function</primary></indexterm><literal>SUBSTRING(string, startIndex, length)</literal>: 
+					Returns the part of the <literal>string</literal> argument 
+					starting at <literal>startIndex</literal> (1-based) and ending 
+					at <literal>length</literal> characters past <literal>
+					startIndex</literal>.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE SUBSTRING(x.title, 1, 1) = 'J'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TRIM function</primary></indexterm><literal>TRIM([LEADING | TRAILING | BOTH] [character FROM] 
+					string</literal>: Trims the specified character from 
+					either the beginning (<literal>LEADING</literal>)
+					end (<literal>TRAILING</literal>) or both (<literal>
+					BOTH</literal>) of the string argument. If no trim character is
+					specified, the space character will be trimmed.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE TRIM(BOTH 'J' FROM x.title) = 'D'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>LOWER function</primary></indexterm><literal>LOWER(string)</literal>: Returns the lower-case of the
+					specified string argument.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE LOWER(x.title) = 'jdj'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>UPPER function</primary></indexterm><literal>UPPER(string)</literal>: Returns the upper-case of the
+					specified string argument.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE UPPER(x.title) = 'JAVAPRO'
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>LENGTH function</primary></indexterm><literal>LENGTH(string)</literal>: Returns the number of 
+					characters in the specified string argument.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE LENGTH(x.title) = 3
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>LOCATE function</primary></indexterm><literal>LOCATE(searchString, candidateString [, 
+					startIndex])</literal>: Returns the first index of
+					<literal>searchString</literal> in <literal>
+					candidateString</literal>. Positions are 1-based.
+					If the string is not found, returns 0.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE LOCATE('D', x.title) = 2
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>ABS function</primary></indexterm><literal>ABS(number)</literal>: Returns the absolute value of 
+					the argument.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE ABS(x.price) &gt;= 5.00
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>SQRT function</primary></indexterm><literal>SQRT(number)</literal>: Returns the square root of 
+					the argument.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE SQRT(x.price) &gt;= 1.00
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>MOD function</primary></indexterm><literal>MOD(number, divisor)</literal>: Returns the modulo of 
+					<literal>number</literal> and <literal>divisor</literal>.
+					</para>
+              <programlisting format="linespecific">
+SELECT x FROM Magazine x WHERE MOD(x.price, 10) = 0
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>CURRENT_DATE function</primary></indexterm><literal>CURRENT_DATE</literal>: Returns the current date.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>CURRENT_TIME function</primary></indexterm><literal>CURRENT_TIME</literal>: Returns the current time.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>CURRENT_TIMESTAMP function</primary></indexterm><literal>CURRENT_TIMESTAMP</literal>: Returns the current 
+					timestamp.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_query_inheritance">
+          <title>Polymorphic Queries</title>
+          <para>
+			All JPQL queries are polymorphic, which means the <literal>from
+			</literal> clause of a query includes not only instances of the 
+			specific entity class to which it refers, but all subclasses of that 
+			class as well. The instances returned by a query include instances
+			of the subclasses that satisfy the query conditions.
+			For example, the following query may return instances of <classname>
+			Magazine</classname>, as well as <classname>Tabloid</classname> and
+			<classname>Digest</classname> instances, where <classname>Tabloid
+			</classname> and <classname>Digest</classname> are <classname>Magazine
+			</classname> subclasses.
+			</para>
+          <programlisting format="linespecific">SELECT x FROM Magazine x WHERE x.price &lt; 5</programlisting>
+        </section>
+        <section id="jpa_overview_query_params">
+          <title>Query Parameters</title>
+          <para>
+			JPQL provides support for parameterized queries. Either
+			named parameters or positional parameters may be specified in
+			the query string.  Parameters allow you to re-use query templates where
+			only the input parameters vary. A single query can
+			declare either named parameters or positional parameters, but
+			is not allowed to declare both named and positional parameters.
+			</para>
+          <programlisting format="linespecific">
+public Query setParameter (int pos, Object value);
+</programlisting>
+          <para>
+			Specify positional parameters in your JPQL string using an integer
+			prefixed by a question mark.  You can then populate the 
+			<classname>Query</classname> object with positional parameter values 
+			via calls to the <methodname>setParameter</methodname> method above.  
+			The method returns the <classname>Query</classname> instance for 
+			optional method chaining.
+			</para>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createQuery ("SELECT x FROM Magazine x WHERE x.title = ?1 and x.price &gt; ?2");
+q.setParameter (1, "JDJ").setParameter (2, 5.0);
+List&lt;Magazine&gt; results = q.getResultList ();
+</programlisting>
+          <para>	
+			This code will substitute <literal>JDJ</literal> for the <literal>?1
+			</literal> parameter and <literal>5.0</literal> for the <literal>?2
+			</literal> parameter, then execute the query with those values.
+			</para>
+          <programlisting format="linespecific">
+public Query setParameter (String name, Object value);
+</programlisting>
+          <para>
+			Named parameter are denoted by prefixing an arbitrary name with
+			a colon in your JPQL string.  You can then populate the <classname>
+			Query</classname> object with parameter values using the method above.
+			Like the positional parameter method, this method returns the
+			<classname>Query</classname> instance for optional method chaining.
+			</para>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createQuery ("SELECT x FROM Magazine x WHERE x.title = :titleParam and x.price &gt; :priceParam");
+q.setParameter ("titleParam", "JDJ").setParameter ("priceParam", 5.0);
+List&lt;Magazine&gt; results = q.getResultList ();
+</programlisting>
+          <para>
+			This code substitutes <literal>JDJ</literal> for the <literal>
+			:titleParam</literal> parameter and <literal>5.0</literal> for the 
+			<literal>:priceParam</literal> parameter, then executes the
+			query with those values.
+			</para>
+        </section>
+        <section id="jpa_overview_query_ordering">
+          <title>Ordering</title>
+          <para>
+			JPQL queries may optionally contain an <literal>order by</literal> 
+			clause which specifies one or more fields to order by when returning
+			query results.  You may follow the <literal>order by field</literal> 
+			clause with the <literal>asc</literal> or <literal>desc</literal> 
+			keywords, which indicate that ordering should be ascending or 
+			descending, respectively. If the direction is omitted, ordering is 
+			ascending by default.  
+			</para>
+          <programlisting format="linespecific">
+SELECT x FROM Magazine x order by x.title asc, x.price desc
+</programlisting>
+          <para>
+			The query above returns <classname>Magazine</classname> instances 
+			sorted by their title in ascending order. In cases where the 
+			titles of two or more magazines are the same, those instances will be 
+			sorted by price in descending order.
+			</para>
+        </section>
+        <section id="jpa_overview_query_aggregates">
+          <title>Aggregates</title>
+          <para>
+			JPQL queries can select aggregate data as well as objects.
+			JPQL includes the 
+			<literal>min</literal>, <literal>max</literal>,
+			<literal>avg</literal>, and <literal>count</literal> aggregates. These
+			functions can be used for reporting and summary queries.
+			</para>
+          <para>
+			The following query will return the average of all the
+			prices of all the magazines:
+			</para>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createQuery ("SELECT AVG(x.price) FROM Magazine x");
+Number result = (Number) q.getSingleResult ();
+</programlisting>
+          <para>
+			The following query will return the highest price of all
+			the magazines titled "JDJ":
+			</para>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createQuery ("SELECT MAX(x.price) FROM Magazine x WHERE x.title = 'JDJ'");
+Number result = (Number) q.getSingleResult ();
+</programlisting>
+        </section>
+        <section id="jpa_overview_query_named">
+          <title>Named Queries</title>
+          <para>
+			Query templates can be statically declared using the <literal>
+			NamedQuery</literal> and <literal>NamedQueries</literal> annotations.
+			For example:
+			</para>
+          <programlisting format="linespecific">
+@Entity
+@NamedQueries({
+    @NamedQuery(name="magsOverPrice",
+        query="SELECT x FROM Magazine x WHERE x.price &gt; ?1"),
+    @NamedQuery(name="magsByTitle",
+        query="SELECT x FROM Magazine x WHERE x.title = :titleParam")
+})
+public class Magazine
+{
+    ...
+}
+</programlisting>
+          <para>
+		These declarations will define two named queries called 
+		<literal>magsOverPrice</literal> and <literal>magsByTitle</literal>.
+		</para>
+          <programlisting format="linespecific">
+public Query createNamedQuery (String name);
+</programlisting>
+          <para>
+		You retrieve named queries with the above <classname>EntityManager
+		</classname> method.  For example:
+		</para>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createNamedQuery ("magsOverPrice");
+q.setParameter (1, 5.0f);
+List&lt;Magazine&gt; results = q.getResultList ();
+</programlisting>
+          <programlisting format="linespecific">
+EntityManager em = ...
+Query q = em.createNamedQuery ("magsByTitle");
+q.setParameter ("titleParam", "JDJ");
+List&lt;Magazine&gt; results = q.getResultList ();
+</programlisting>
+        </section>
+        <section id="jpa_overview_query_delete">
+          <title>Delete By Query</title>
+          <para>
+			Queries are useful not only for finding objects, but for efficiently
+			deleting them as well.  For example, you might delete all records 
+			created before a certain date.  Rather than bring these objects into
+			memory and delete them individually, JPA allows you to perform a single
+			bulk delete based on JPQL criteria.
+			</para>
+          <para>
+			Delete by query uses the same JPQL syntax as normal queries, with one
+			exception: begin your query string with the <literal>delete</literal> 
+			keyword instead of the <literal>select</literal> keyword.  To then 
+			execute the delete, you call the following <classname>Query</classname>
+			method:
+			</para>
+          <programlisting format="linespecific">
+public int executeUpdate ();
+</programlisting>
+          <para>
+			This method returns the number of objects deleted.
+			The following example deletes all subscriptions whose
+			expiration date has passed.
+			</para>
+          <example id="jpa_overview_query_deleteex">
+            <title>Delete by Query</title>
+            <programlisting format="linespecific">
+Query q = em.createQuery ("DELETE s FROM Subscription s WHERE s.subscriptionDate &lt; :today");
+q.setParameter ("today", new Date ());
+int deleted = q.executeUpdate ();
+</programlisting>
+          </example>
+        </section>
+        <section id="jpa_overview_query_update">
+          <title>Update By Query</title>
+          <para>
+			Similar to bulk deletes, it is sometimes necessary to perform
+			updates against a large number of queries in a single operation,
+			without having to bring all the instances down to the client.
+			Rather than bring these objects into memory and modifying
+			them individually, JPA allows you to perform a single
+			bulk update based on JPQL criteria.
+			</para>
+          <para>
+			Update by query uses the same JPQL syntax as normal queries, except
+			that the query string begins with the <literal>update</literal> 
+			keyword instead of <literal>select</literal>.  To 
+			execute the update, you call the following <classname>Query</classname>
+			method:
+			</para>
+          <programlisting format="linespecific">
+public int executeUpdate ();
+</programlisting>
+          <para>
+			This method returns the number of objects updated.
+			The following example updates all subscriptions whose
+			expiration date has passed to have the "paid" field set to true..
+			</para>
+          <example id="jpa_overview_query_updateex">
+            <title>Update by Query</title>
+            <programlisting format="linespecific">
+Query q = em.createQuery ("UPDATE Subscription s SET s.paid = :paid WHERE s.subscriptionDate &lt; :today");
+q.setParameter ("today", new Date ());
+q.setParameter ("paid", true);
+int updated = q.executeUpdate ();
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_langref">
+        <title>JPQL Language Reference</title>
+        <para>
+		The Java Persistence query language (JPQL) is used to define searches
+		against persistent entities independent of the mechanism used to
+		store those entities. As such, JPQL is "portable", and not constrained to
+		any particular data store.  The Java
+		Persistence query language is an extension of the Enterprise JavaBeans
+		query language, <literal>EJB QL</literal>, adding operations such
+		as bulk deletes and updates, join operations, aggregates, projections,
+		and subqueries. Furthermore, JPQL queries can be declared statically in
+		metadata, or can be dynamically built in code. This chapter provides the full
+		definition of the language.
+
+		<note><para>
+			Much of this section is paraphrased or taken directly
+			from Chapter 4 of the JSR 220 specification.
+		</para></note>
+
+		</para>
+        <section id="jpa_langref_stmnttypes">
+          <title>JPQL Statement Types</title>
+          <para>
+		A JPQL statement
+		may be either a <literal>SELECT</literal> statement, an <literal>UPDATE</literal>
+		statement, or a <literal>DELETE</literal> statement. This chapter refers to all
+		such statements as "queries". Where
+		it is important to distinguish among statement types, the specific
+		statement type is referenced. In BNF syntax, a query language statement
+		is defined as:
+
+<itemizedlist><listitem><para>QL_statement ::= select_statement | update_statement | delete_statement</para></listitem></itemizedlist>
+
+		The complete BNF for JPQL is defined in <xref linkend="jpa_langref_bnf"/>.
+
+		Any JPQL statement may be constructed
+		dynamically or may be statically defined in a metadata annotation or
+		XML descriptor element. All statement types may have parameters, as
+		discussed in <xref linkend="jpa_langref_input_params"/>.
+
+		</para>
+          <section id="jpa_langref_select">
+            <title>JPQL Select Statement</title>
+            <para>
+			A select statement is a string which consists of the following clauses:
+
+			<itemizedlist><listitem><para>
+			a <literal>SELECT</literal> clause, which determines the type of the objects or values
+			to be selected.
+				</para></listitem><listitem><para>
+			a <literal>FROM</literal> clause, which provides declarations that designate the domain to
+			which the expressions specified in the other clauses of the query apply.
+				</para></listitem><listitem><para>
+			an optional <literal>WHERE</literal> clause, which may be used to restrict the results
+			that are returned by the query.
+				</para></listitem><listitem><para>
+			an optional <literal>GROUP BY</literal> clause, which allows query results to be aggregated
+			in terms of groups.
+				</para></listitem><listitem><para>
+			an optional <literal>HAVING</literal> clause, which allows filtering over aggregated
+			groups.
+				</para></listitem><listitem><para>
+			an optional <literal>ORDER BY</literal> clause, which may be used to order the
+			results that are returned by the query.
+				</para></listitem></itemizedlist>
+
+			In BNF syntax, a select statement is defined as:
+
+<itemizedlist><listitem><para>select_statement ::= select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause]</para></listitem></itemizedlist>
+
+
+			A select statement
+			must always have a <literal>SELECT</literal>
+			and a <literal>FROM</literal> clause. The square brackets []
+			indicate that the other clauses are optional.
+
+			</para>
+          </section>
+          <section id="jpa_langref_bulk">
+            <title>JPQL Update and Delete Statements</title>
+            <para>
+			Update and delete statements provide bulk operations over sets of entities.
+			In BNF syntax, these operations are defined as:
+
+<itemizedlist><listitem><para>update_statement ::= update_clause [where_clause]</para></listitem><listitem><para>delete_statement ::= delete_clause [where_clause]</para></listitem></itemizedlist>
+
+			The update and delete clauses determine
+			the type of the entities to be updated or deleted.
+			The <literal>WHERE</literal> clause may
+			be used to restrict the scope of the update or delete operation. Update
+			and delete statements are described further in
+			<xref linkend="jpa_langref_bulk_ops"/>.
+			</para>
+          </section>
+        </section>
+        <section id="jpa_langref_schematypes">
+          <title>JPQL Abstract Schema Types and Query Domains</title>
+          <para>
+		The Java Persistence query
+		language is a typed language, and every expression has a type. The
+		type of an expression is derived from the structure of the expression,
+		the abstract schema types of the identification variable declarations,
+		the types to which the persistent fields and relationships evaluate,
+		and the types of literals. The abstract schema type of an entity is
+		derived from the entity class and the metadata information provided by
+		Java language annotations or in the XML descriptor.
+		</para>
+          <para> 
+		Informally, the abstract schema type of an entity can be characterized
+		as follows:
+
+			<itemizedlist><listitem><para>
+		For every persistent field or get accessor method (for a persistent
+		property) of the entity class, there is a field ("state-field") whose
+		abstract schema type corresponds to that of the field or the result type
+		of the accessor method.
+				</para></listitem><listitem><para> 
+		For every persistent relationship field or get accessor method (for a
+		persistent relationship property) of the entity class, there is a field
+		("association-field") whose type is the abstract schema type of the
+		related entity (or, if the relationship is a one-to-many or many-to-many,
+		a collection of such). Abstract schema types are specific to the query
+		language data model. The persistence provider is not required to implement
+		or otherwise materialize an abstract schema type. The domain of a query
+		consists of the abstract schema types of all entities that are defined
+		in the same persistence unit. The domain of a query may be restricted
+		by the navigability of the relationships of the entity on which it
+		is based. The association-fields of an entity's abstract schema type
+		determine navigability. Using the association-fields and their values,
+		a query can select related entities and use their abstract schema types
+		in the query.
+				</para></listitem></itemizedlist>
+
+		</para>
+          <section id="jpa_langref_schemanaming">
+            <title>JPQL Entity Naming</title>
+            <para>
+			Entities are designated in query strings by their entity
+			names. The entity name is defined by the name element of the Entity
+			annotation (or the entity-name XML descriptor element), and defaults to
+			the unqualified name of the entity class. Entity names are scoped within
+			the persistence unit and must be unique within the persistence unit.
+
+			</para>
+          </section>
+          <section id="jpa_langref_schemaexample">
+            <title>JPQL Schema Example</title>
+            <para>
+			This example assumes that the application developer
+			provides several entity classes, representing magazines, publishers,
+			authors, and articles.
+			The abstract schema
+			types for these entities are <literal>Magazine</literal>,
+			<literal>Publisher</literal>, <literal>Author</literal>,
+			and <literal>Article</literal>.
+			</para>
+            <para> 
+			Several Entities with Abstract Persistence Schemas Defined in the Same
+			Persistence Unit. The entity <literal>Publisher</literal> has a
+			one-to-many relationships with <literal>Magazine</literal>.
+			There is also a one-to-many
+			relationship between <literal>Magazine</literal> and 
+			<literal>Article</literal>. The entity <literal>Article</literal>
+			is related to <literal>Author</literal> in a one-to-one relationship.
+
+			</para>
+            <para> 
+			Queries to select magazines can be defined by navigating over the
+			association-fields and state-fields defined by Magazine and Author. A query
+			to find all magazines that have unpublished articles is as follows:
+
+<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE</programlisting>
+
+			This query navigates over the association-field authors of the
+			abstract schema type <literal>Magazine</literal> to find articles,
+			and uses the state-field
+			<literal>published</literal> of <literal>Article</literal> to select those 
+			magazines that have at least one article that is published.
+			Although predefined reserved identifiers,
+			such as <literal>DISTINCT</literal>, <literal>FROM</literal>, <literal>AS</literal>,
+			<literal>JOIN</literal>, <literal>WHERE</literal>, and <literal>FALSE</literal> appear in upper case
+			in this example, predefined reserved identifiers are case insensitive. The
+			<literal>SELECT</literal> clause of this example designates the return type of this query to
+			be of type Magazine. Because the same persistence unit defines the abstract
+			persistence schemas of the related entities, the developer can also
+			specify a query over <literal>articles</literal> that utilizes the abstract
+			schema type for
+			products, and hence the state-fields and association-fields of both the
+			abstract schema types Magazine and Author. For example, if the abstract
+			schema type Author has a state-field named firstName, a query over
+			articles can be specified using this state-field. Such a query might be
+			to find all magazines that have articles authored by someone with the
+			first name "John".
+
+<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine mag
+    JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John'</programlisting>
+
+			Because Magazine is related to Author by means of the relationships between
+			Magazine and Article and between Article and Author, navigation using
+			the association-fields authors and product is used to express the
+			query. This query is specified by using the abstract schema name Magazine,
+			which designates the abstract schema type over which the query ranges. The
+			basis for the navigation is provided by the association-fields authors
+			and product of the abstract schema types Magazine and Article respectively.
+
+
+			</para>
+          </section>
+        </section>
+        <section id="jpa_langref_fromclause">
+          <title>JPQL FROM Clause and Navigational Declarations</title>
+          <para>
+		The <literal>FROM</literal> clause of
+		a query defines the domain of the query by declaring identification
+		variables. An identification variable is an identifier declared in the
+		<literal>FROM</literal> clause of a query. The domain of the query may be constrained by
+		path expressions. Identification variables designate instances of a
+		particular entity abstract schema type. The <literal>FROM</literal> clause can contain
+		multiple identification variable declarations separated by a comma (,).
+		</para>
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para>from_clause ::= FROM identification_variable_declaration {, {identification_variable_declaration | collection_member_declaration}}*</para>
+              </listitem>
+              <listitem>
+                <para>identification_variable_declaration ::= range_variable_declaration { join | fetch_join }*  </para>
+              </listitem>
+              <listitem>
+                <para>range_variable_declaration ::= abstract_schema_name [AS] identification_variable</para>
+              </listitem>
+              <listitem>
+                <para>join ::= join_spec join_association_path_expression [AS] identification_variable</para>
+              </listitem>
+              <listitem>
+                <para>fetch_join ::= join_spec FETCH join_association_path_expression </para>
+              </listitem>
+              <listitem>
+                <para>join_association_path_expression ::= join_collection_valued_path_expression | join_single_valued_association_path_expression </para>
+              </listitem>
+              <listitem>
+                <para>join_spec ::= [ LEFT [OUTER] | INNER ] JOIN </para>
+              </listitem>
+              <listitem>
+                <para>collection_member_declaration ::= IN (collection_valued_path_expression) [AS] identification_variable</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <section id="jpa_langref_from_identifiers">
+            <title>JPQL FROM Identifiers</title>
+            <para>
+			An identifier is a character sequence of unlimited
+			length. The character sequence must begin with a Java identifier
+			start character, and all other characters must be Java identifier
+			part characters. An identifier start character is any character for
+			which the method <methodname>Character.isJavaIdentifierStart</methodname>
+			returns <literal>true</literal>. This
+			includes the underscore (_) character and the dollar sign ($)
+			character. An identifier part character is any character for which
+			the method <methodname>Character.isJavaIdentifierPart</methodname>
+			returns <literal>true</literal>. The question
+			mark (?) character is reserved for use by the Java Persistence query
+			language. The following are reserved identifiers: 
+
+			<itemizedlist><listitem><para><literal>SELECT</literal></para></listitem><listitem><para><literal>FROM</literal></para></listitem><listitem><para><literal>WHERE</literal></para></listitem><listitem><para><literal>UPDATE</literal></para></listitem><listitem><para><literal>DELETE</literal></para></listitem><listitem><para><literal>JOIN</literal></para></listitem><listitem><para><literal>OUTER</literal></para></listitem><listitem><para><literal>INNER</literal></para></listitem><listitem><para><literal>LEFT</literal></para></listitem><listitem><para><literal>GROUP</literal></para></listitem><listitem><para><literal>BY</literal></para></listitem><listitem><para><literal>HAVING</literal></para></listitem><listitem><para><literal>FETCH</literal></para></listitem><listitem><para><literal>DISTINCT</literal></para></listitem><listitem><para><literal>OBJECT</literal></para></listitem><listitem><para><literal>NULL</literal></para></listitem><listitem><para><literal>TRUE</literal></para></listitem><listitem><para><literal>FALSE</literal></para></listitem><listitem><para><literal>NOT</literal></para></listitem><listitem><para><literal>AND</literal></para></listitem><listitem><para><literal>OR</literal></para></listitem><listitem><para><literal>BETWEEN</literal></para></listitem><listitem><para><literal>LIKE</literal></para></listitem><listitem><para><literal>IN</literal></para></listitem><listitem><para><literal>AS</literal></para></listitem><listitem><para><literal>UNKNOWN</literal></para></listitem><listitem><para><literal>EMPTY</literal></para></listitem><listitem><para><literal>MEMBER</literal></para></listitem><listitem><para><literal>OF</literal></para></listitem><listitem><para><literal>IS</literal></para></listitem><listitem><para><literal>AVG</literal></para></listitem><listitem><para><literal>MAX</literal></para></listitem><listitem><para><literal>MIN</literal></para></listitem><listitem><para><literal>SUM</literal></para></listitem><listitem><para><literal>COUNT</literal></para></listitem><listitem><para><literal>ORDER</literal></para></listitem><listitem><para><literal>BY</literal></para></listitem><listitem><para><literal>ASC</literal></para></listitem><listitem><para><literal>DESC</literal></para></listitem><listitem><para><literal>MOD</literal></para></listitem><listitem><para><literal>UPPER</literal></para></listitem><listitem><para><literal>LOWER</literal></para></listitem><listitem><para><literal>TRIM</literal></para></listitem><listitem><para><literal>POSITION</literal></para></listitem><listitem><para><literal>CHARACTER_LENGTH</literal></para></listitem><listitem><para><literal>CHAR_LENGTH</literal></para></listitem><listitem><para><literal>BIT_LENGTH</literal></para></listitem><listitem><para><literal>CURRENT_TIME</literal></para></listitem><listitem><para><literal>CURRENT_DATE</literal></para></listitem><listitem><para><literal>CURRENT_TIMESTAMP</literal></para></listitem><listitem><para><literal>NEW</literal></para></listitem><listitem><para><literal>EXISTS</literal></para></listitem><listitem><para><literal>ALL</literal></para></listitem><listitem><para><literal>ANY</literal></para></listitem><listitem><para><literal>SOME</literal></para></listitem></itemizedlist>
+
+			Reserved identifiers are
+			case insensitive. Reserved identifiers must not be used as identification
+			variables. It is recommended that other SQL reserved words also not
+			be as identification variables in queries because they may be used as
+			reserved identifiers in future releases of the specification.  
+
+			</para>
+          </section>
+          <section id="jpa_langref_from_vars">
+            <title>JPQL Identification Variables</title>
+            <para>
+			An identification variable is a valid
+			identifier declared in the <literal>FROM</literal> clause of a query. All identification
+			variables must be declared in the <literal>FROM</literal> clause. Identification variables
+			cannot be declared in other clauses. An identification variable must not
+			be a reserved identifier or have the same name as any entity in the same
+			persistence unit: Identification variables are case insensitive. An
+			identification variable evaluates to a value of the type of the
+			expression used in declaring the variable. For example, consider the
+			previous query:
+
+<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine mag JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John'</programlisting>
+
+			In the <literal>FROM</literal> clause
+			declaration <literal>mag.articles</literal> <literal>art</literal>,
+			the identification variable <literal>art</literal> evaluates to
+			any <literal>Article</literal> value directly reachable from
+			<literal>Magazine</literal>. The association-field
+			<literal>articles</literal> is a collection of instances
+			of the abstract schema type <literal>Article</literal>
+			and the identification variable <literal>art</literal>
+			refers to an element of this
+			collection. The type of <literal>auth</literal> is the abstract
+			schema type of <literal>Author</literal>. An
+			identification variable ranges over the abstract schema type of an
+			entity. An identification variable designates an instance of an entity
+			abstract schema type or an element of a collection of entity abstract
+			schema type instances. Identification variables are existentially
+			quantified in a query. An identification variable always designates a
+			reference to a single value. It is declared in one of three ways: in a
+			range variable declaration, in a join clause, or in a collection member
+			declaration. The identification variable declarations are evaluated
+			from left to right in the <literal>FROM</literal> clause, and an identification variable
+			declaration can use the result of a preceding identification variable
+			declaration of the query string.
+
+			</para>
+          </section>
+          <section id="jpa_langref_range">
+            <title>JPQL Range Declarations</title>
+            <para>
+			The syntax for declaring an
+			identification variable as a range variable is similar to that of SQL;
+			optionally, it uses the AS keyword.
+<itemizedlist><listitem><para>range_variable_declaration ::= abstract_schema_name [AS] identification_variable</para></listitem></itemizedlist>
+			</para>
+            <para> 
+			Range variable declarations allow the developer
+			to designate a "root" for objects which may not be reachable by
+			navigation. In order to select values by comparing more than one instance
+			of an entity abstract schema type, more than one identification variable
+			ranging over the abstract schema type is needed in the <literal>FROM</literal> clause.
+
+			</para>
+            <para> 
+			The following query returns magazines whose price is greater than the
+			price of magazines published by "Adventure" publishers. This example illustrates the use of
+			two different identification variables in the <literal>FROM</literal> clause, both of the
+			abstract schema type Magazine. The <literal>SELECT</literal> clause of this query determines
+			that it is the magazines with prices greater than those of "Adventure" publisher's that are
+			returned.
+
+<programlisting format="linespecific">SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2
+WHERE mag1.price &gt; mag2.price AND mag2.publisher.name = 'Adventure'</programlisting>
+
+			</para>
+          </section>
+          <section id="jpa_langref_path">
+            <title>JPQL Path Expressions</title>
+            <para>
+			An identification variable followed by the
+			navigation operator (.) and a state-field or association-field is a
+			path expression. The type of the path expression is the type computed
+			as the result of navigation; that is, the type of the state-field
+			or association-field to which the expression navigates. Depending on
+			navigability, a path expression that leads to a association-field may
+			be further composed. Path expressions can be composed from other path
+			expressions if the original path expression evaluates to a single-valued
+			type (not a collection) corresponding to a association-field. Path
+			expression navigability is composed using "inner join" semantics. That is,
+			if the value of a non-terminal association-field in the path expression is
+			null, the path is considered to have no value, and does not participate
+			in the determination of the result. The syntax for single-valued path
+			expressions and collection valued path expressions is as follows:
+			</para>
+            <para>
+              <itemizedlist>
+                <listitem>
+                  <para>single_valued_path_expression ::= state_field_path_expression | single_valued_association_path_expression</para>
+                </listitem>
+                <listitem>
+                  <para>state_field_path_expression ::= {identification_variable | single_valued_association_path_expression}.state_field</para>
+                </listitem>
+                <listitem>
+                  <para>single_valued_association_path_expression ::= identification_variable.{single_valued_association_field.}*single_valued_association_field</para>
+                </listitem>
+                <listitem>
+                  <para>collection_valued_path_expression ::= identification_variable.{single_valued_association_field.}*collection_valued_association_field</para>
+                </listitem>
+                <listitem>
+                  <para>state_field ::= {embedded_class_state_field.}*simple_state_field</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+            <para> 
+			A single_valued_association_field is designated by the
+			name of an association-field in a one-to-one or many-to-one
+			relationship. The type of a single_valued_association_field and thus a
+			single_valued_association_path_expression is the abstract schema type of
+			the related entity. A collection_valued_association_field is designated
+			by the name of an association-field in a one-to-many or a many-to-many
+			relationship. The type of a collection_valued_association_field is a
+			collection of values of the abstract schema type of the related entity. An
+			embedded_class_state _field is designated by the name of an entity state
+			field that corresponds to an embedded class. Navigation to a related
+			entity results in a value of the related entity's abstract schema type.
+
+			</para>
+            <para> 
+			The evaluation of a path expression terminating in a state-field results
+			in the abstract schema type corresponding to the Java type designated by
+			the state-field. It is syntactically illegal to compose a path expression
+			from a path expression that evaluates to a collection. For example, if
+			<literal>mag</literal>
+			designates
+			<literal>Magazine</literal>,
+			the path expression <literal>mag.articles.author</literal> is illegal since
+			navigation to authors results in a collection. This case should produce
+			an error when the query string is verified. To handle such a navigation,
+			an identification variable must be declared in the <literal>FROM</literal> clause to range
+			over the elements of the <literal>articles</literal> collection. Another path expression
+			must be used to navigate over each such element in the <literal>WHERE</literal> clause of
+			the query, as in the following query which returns all authors that have
+			any articles in any magazines:
+
+<programlisting format="linespecific">SELECT DISTINCT art.author FROM Magazine AS mag, IN(mag.articles) art</programlisting>
+
+			</para>
+          </section>
+          <section id="jpa_langref_Joins">
+            <title>JPQL Joins</title>
+            <para>
+			An inner join may be implicitly specified by the use of a
+			cartesian product in the <literal>FROM</literal> clause and a join
+			condition in the <literal>WHERE</literal>
+			clause.
+			</para>
+            <para> 
+			The syntax for explicit join operations is as follows:
+			</para>
+            <para>
+              <itemizedlist>
+                <listitem>
+                  <para>join ::= join_spec join_association_path_expression [AS] identification_variable </para>
+                </listitem>
+                <listitem>
+                  <para>fetch_join ::= join_spec FETCH join_association_path_expression </para>
+                </listitem>
+                <listitem>
+                  <para>join_association_path_expression ::= join_collection_valued_path_expression | join_single_valued_association_path_expression</para>
+                </listitem>
+                <listitem>
+                  <para>join_spec ::= [ LEFT [OUTER] | INNER ] JOIN</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+            <para> 
+			The following inner and outer join operation types are supported.
+
+			</para>
+            <section id="jpa_langref_inner_joins">
+              <title>JPQL Inner Joins (Relationship Joins)</title>
+              <para>
+				The syntax for the inner join operation is
+
+<programlisting format="linespecific">
+[ INNER ] JOIN join_association_path_expression [AS] identification_variable
+</programlisting>
+
+				For example, the query below joins over the
+				relationship between publishers and magazines. This type of join typically
+				equates to a join over a foreign key relationship in the database.
+
+<programlisting format="linespecific">SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue &gt; 1000000</programlisting>
+
+				</para>
+              <para> 
+				The keyword <literal>INNER</literal> may optionally be used:
+
+<programlisting format="linespecific">SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue &gt; 1000000</programlisting>
+
+				This is equivalent to the following
+				query using the earlier <literal>IN</literal> construct. It selects those
+				publishers with revenue of over 1 million for which at least one magazine exists:
+
+<programlisting format="linespecific">SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue &gt; 1000000</programlisting>
+
+				</para>
+            </section>
+            <section id="jpa_langref_outer_joins">
+              <title>JPQL Outer Joins</title>
+              <para><literal>LEFT JOIN</literal> and <literal>LEFT OUTER JOIN</literal> are
+				synonymous. They enable the retrieval of a set of entities where
+				matching values in the join condition may be absent. The syntax for a
+				left outer join is:
+
+<programlisting format="linespecific">LEFT [OUTER] JOIN join_association_path_expression [AS] identification_variable</programlisting></para>
+              <para> 
+				For example:
+
+<programlisting format="linespecific">SELECT pub FROM Publisher pub LEFT JOIN pub.magazines mag WHERE pub.revenue &gt; 1000000</programlisting>
+
+				The keyword <literal>OUTER</literal> may optionally be used:
+
+<programlisting format="linespecific">SELECT pub FROM Publisher pub LEFT OUTER JOIN pub.magazines mags WHERE pub.revenue &gt; 1000000</programlisting>
+
+				An important use case
+				for <literal>LEFT JOIN</literal> is in enabling the prefetching of related data items as
+				a side effect of a query. This is accomplished by specifying the
+				<literal>LEFT JOIN</literal> as a <literal>FETCH JOIN</literal>.
+
+				</para>
+            </section>
+            <section id="jpa_langref_fetch_joins">
+              <title>JPQL Fetch Joins</title>
+              <para>
+				A <literal>FETCH JOIN</literal> enables the fetching of an association
+				as a side effect of the execution of a query.
+				A <literal>FETCH JOIN</literal> is specified
+				over an entity and its related entities. The syntax for a fetch join is
+
+<itemizedlist><listitem><para>fetch_join ::= [ LEFT [OUTER] | INNER ] JOIN FETCH join_association_path_expression </para></listitem></itemizedlist>
+				</para>
+              <para> 
+				The association referenced by the right
+				side of the <literal>FETCH JOIN</literal> clause must be
+				an association that belongs to an
+				entity that is returned as a result of the query. It is not permitted
+				to specify an identification variable for the entities referenced by
+				the right side of the <literal>FETCH JOIN</literal> clause, and
+				hence references to the
+				implicitly fetched entities cannot appear elsewhere in the query. The
+				following query returns a set of magazines. As a side effect, the
+				associated articles for those magazines are also retrieved, even
+				though they are not part of the explicit query result. The persistent
+				fields or properties of the articles that are eagerly fetched are
+				fully initialized. The initialization of the relationship properties
+				of the <literal>articles</literal> that are retrieved is determined
+				by the metadata for the <literal>Article</literal> entity class.
+
+<programlisting format="linespecific">SELECT mag FROM Magazine mag LEFT JOIN FETCH mag.articles WHERE mag.id = 1</programlisting>
+
+
+				</para>
+              <para>
+
+				A fetch join has the same join semantics as the corresponding inner or
+				outer join, except that the related objects specified on the right-hand
+				side of the join operation are not returned in the query result or
+				otherwise referenced in the query. Hence, for example, if magazine
+				id 1 has five articles, the above query returns five references to the
+				magazine 1 entity.
+
+				</para>
+            </section>
+          </section>
+          <section id="jpa_langref_collection_dec">
+            <title>JPQL Collection Member Declarations</title>
+            <para>
+			An identification variable declared
+			by a collection_member_declaration ranges over values of a collection
+			obtained by navigation using a path expression. Such a path expression
+			represents a navigation involving the association-fields of an entity
+			abstract schema type. Because a path expression can be based on another
+			path expression, the navigation can use the association-fields of related
+			entities. An identification variable of a collection member declaration
+			is declared using a special operator, the reserved
+			identifier <literal>IN</literal>. The
+			argument to the <literal>IN</literal> operator is a
+			collection-valued path expression. The
+			path expression evaluates to a collection type specified as a result of
+			navigation to a collection-valued association-field of an entity abstract
+			schema type. The syntax for declaring a collection member identification
+			variable is as follows:
+			</para>
+            <para>
+              <itemizedlist>
+                <listitem>
+                  <para>collection_member_declaration ::= IN (collection_valued_path_expression) [AS] identification_variable</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+            <para>
+
+			For example, the query
+
+<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine mag
+    JOIN mag.articles art
+    JOIN art.author auth
+    WHERE auth.lastName = 'Grisham'</programlisting>
+
+			may equivalently
+			be expressed as follows, using the <literal>IN</literal> operator:
+
+<programlisting format="linespecific">SELECT DISTINCT mag FROM Magazine mag,
+    IN(mag.articles) art
+    WHERE art.author.lastName = 'Grisham'</programlisting>
+
+			In this example, <literal>articles</literal> is the name of
+			an association-field whose value
+			is a collection of instances of the abstract schema
+			type <literal>Article</literal>. The
+			identification variable <literal>art</literal> designates a member
+			of this collection, a
+			single <literal>Article</literal> abstract schema type instance.
+			In this example, <literal>mag</literal> is an
+			identification variable of the abstract schema type
+			<literal>Magazine</literal>.
+
+			</para>
+          </section>
+          <section id="jpa_langref_polymorph">
+            <title>JPQL Polymorphism</title>
+            <para>
+			Java Persistence queries are automatically
+			polymorphic. The <literal>FROM</literal> clause of a query designates not only instances
+			of the specific entity classes to which explicitly refers but of
+			subclasses as well. The instances returned by a query include instances
+			of the subclasses that satisfy the query criteria.
+
+			</para>
+          </section>
+        </section>
+        <section id="jpa_langref_where">
+          <title>JPQL WHERE Clause</title>
+          <para>
+		The <literal>WHERE</literal> clause of a query consists of a conditional
+		expression used to select objects or values that satisfy the
+		expression. The <literal>WHERE</literal> clause restricts the result of a select statement
+		or the scope of an update or delete operation. A <literal>WHERE</literal> clause is defined
+		as follows:
+
+<itemizedlist><listitem><para>where_clause ::= WHERE conditional_expression</para></listitem></itemizedlist>
+		</para>
+          <para>
+
+		The <literal>GROUP BY</literal> construct
+		enables the aggregation of values according to the properties of an entity
+		class. The <literal>HAVING</literal> construct enables conditions to be specified that
+		further restrict the query result as restrictions upon the groups. The
+		syntax of the <literal>HAVING</literal> clause is as follows:
+
+<itemizedlist><listitem><para>having_clause ::= HAVING conditional_expression</para></listitem></itemizedlist>
+		</para>
+          <para>
+
+		The <literal>GROUP BY</literal> and <literal>HAVING</literal>
+		constructs are further discussed in <xref linkend="jpa_langref_group"/>.
+
+		</para>
+        </section>
+        <section id="jpa_langref_cond">
+          <title>JPQL Conditional Expressions</title>
+          <para>
+		The following sections describe the language
+		constructs that can be used in a conditional expression of the <literal>WHERE</literal>
+		clause or <literal>HAVING</literal> clause. State-fields that are mapped in serialized form
+		or as lobs may not be portably used in conditional expressions.
+
+		<note><para>
+			The implementation is not
+			expected to perform such query operations involving such fields in memory
+			rather than in the database.
+		</para></note>
+
+		</para>
+          <section id="jpa_langref_lit">
+            <title>JPQL Literals</title>
+            <para>
+			A string literal is enclosed in single quotes--for example:
+			'literal'. A string literal that includes a single quote is represented by
+			two single quotes--for example: 'literal''s'. String literals in queries,
+			like Java String literals, use unicode character encoding. The use of Java
+			escape notation is not supported in query string literals Exact numeric
+			literals support the use of Java integer literal syntax as well as SQL
+			exact numeric literal syntax. Approximate literals support the use Java
+			floating point literal syntax as well as SQL approximate numeric literal
+			syntax. Enum literals support the use of Java enum literal syntax. The
+			enum class name must be specified. Appropriate suffixes may be used
+			to indicate the specific type of a numeric literal in accordance with
+			the Java Language Specification. The boolean
+			literals are <literal>TRUE</literal> and <literal>FALSE</literal>.
+			Although predefined reserved literals appear in upper case, they are case insensitive.
+
+			</para>
+          </section>
+          <section id="jpa_langref_idvar">
+            <title>JPQL Identification Variables</title>
+            <para>
+			All identification variables used
+			in the <literal>WHERE</literal> or <literal>HAVING</literal> clause of a
+			<literal>SELECT</literal> or <literal>DELETE</literal> statement must
+			be declared in the <literal>FROM</literal> clause, as described in
+			<xref linkend="jpa_langref_from_vars"/>. The
+			identification variables used in the <literal>WHERE</literal> clause of
+			an <literal>UPDATE</literal> statement
+			must be declared in the <literal>UPDATE</literal> clause.
+			Identification variables are
+			existentially quantified in the <literal>WHERE</literal> and
+			<literal>HAVING</literal> clause. This means
+			that an identification variable represents a member of a collection
+			or an instance of an entity's abstract schema type. An identification
+			variable never designates a collection in its entirety.
+
+			</para>
+          </section>
+          <section id="jpa_langref_path_exp">
+            <title>JPQL Path Expressions</title>
+            <para>
+			It is illegal to use
+			a collection_valued_path_expression within a <literal>WHERE</literal> or
+			<literal>HAVING</literal> clause as part of a conditional expression except in an
+			empty_collection_comparison_expression, in a collection_member_expression,
+			or as an argument to the <literal>SIZE</literal> operator.
+
+			</para>
+          </section>
+          <section id="jpa_langref_input_params">
+            <title>JPQL Input Parameters</title>
+            <para>
+			Either positional or named parameters may be
+			used. Positional and named parameters may not be mixed in a single
+			query. Input parameters can only be used in the <literal>WHERE</literal>
+			clause or <literal>HAVING</literal> clause of a query.
+			</para>
+            <para>
+
+			Note that if an input parameter value is null, comparison operations
+			or arithmetic operations involving the input parameter will return an
+			unknown value. See <xref linkend="jpa_langref_null_values"/>.
+
+			</para>
+            <section id="jpa_langref_pos_params">
+              <title>JPQL Positional Parameters</title>
+              <para>
+				The following rules apply to positional
+				parameters.
+
+				<itemizedlist><listitem><para>
+				Input parameters are designated by the question mark (?) prefix followed
+				by an integer. For example: ?1.
+					</para></listitem><listitem><para>
+				Input parameters are numbered starting from 1.  Note that the same
+				parameter can be used more than once in the query string and that the
+				ordering of the use of parameters within the query string need not
+				conform to the order of the positional parameters.
+					</para></listitem></itemizedlist>
+
+				</para>
+            </section>
+            <section id="jpa_langref_named_params">
+              <title>JPQL Named Parameters</title>
+              <para>
+				A named parameter is an identifier that is
+				prefixed by the ":" symbol. It follows the rules for identifiers defined
+				in <xref linkend="jpa_langref_from_identifiers"/>. Named parameters are case sensitive.
+				</para>
+              <para>
+
+				Example:
+
+<programlisting format="linespecific">SELECT pub FROM Publisher pub WHERE pub.revenue &gt; :rev</programlisting>
+
+				</para>
+            </section>
+          </section>
+          <section id="jpa_langref_cond_comp">
+            <title>JPQL Conditional Expression Composition</title>
+            <para>
+			Conditional expressions are
+			composed of other conditional expressions, comparison operations,
+			logical operations, path expressions that evaluate to boolean values,
+			boolean literals, and boolean input parameters. Arithmetic expressions
+			can be used in comparison expressions. Arithmetic expressions are
+			composed of other arithmetic expressions, arithmetic operations, path
+			expressions that evaluate to numeric values, numeric literals, and numeric
+			input parameters. Arithmetic operations use numeric promotion. Standard
+			bracketing () for ordering expression evaluation is supported. Conditional
+			expressions are defined as follows:
+
+			</para>
+            <para>
+              <itemizedlist>
+                <listitem>
+                  <para>conditional_expression ::= conditional_term | conditional_expression OR conditional_term </para>
+                </listitem>
+                <listitem>
+                  <para>conditional_term ::= conditional_factor | conditional_term AND conditional_factor </para>
+                </listitem>
+                <listitem>
+                  <para>conditional_factor ::= [ NOT ] conditional_primary </para>
+                </listitem>
+                <listitem>
+                  <para>conditional_primary ::= simple_cond_expression | (conditional_expression) </para>
+                </listitem>
+                <listitem>
+                  <para>simple_cond_expression ::= comparison_expression | between_expression | like_expression | in_expression | null_comparison_expression | empty_collection_comparison_expression | collection_member_expression | exists_expression</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+            <para>
+			Aggregate functions can only be used in conditional expressions in
+			a <literal>HAVING</literal> clause. See
+			<xref linkend="jpa_langref_group"/>.
+			</para>
+          </section>
+          <section id="jpa_langref_operators">
+            <title>JPQL Operators and Operator Precedence</title>
+            <para>
+			The operators are listed below in order of decreasing precedence.
+
+				<itemizedlist><listitem><para>
+			Navigation operator (.)
+					</para></listitem><listitem><para>
+			Arithmetic operators: +, - unary *, /
+			multiplication and division +, - addition and subtraction
+					</para></listitem><listitem><para>
+			Comparison operators : =, &gt;, &gt;=, &lt;, &lt;=, &lt;&gt; (not equal), [<literal>NOT</literal>]
+			<literal>BETWEEN</literal>, [<literal>NOT</literal>] <literal>LIKE</literal>,
+			[<literal>NOT</literal>] <literal>IN</literal>, <literal>IS</literal> [<literal>NOT</literal>]
+			<literal>NULL</literal>, <literal>IS</literal> [<literal>NOT</literal>] <literal>EMPTY</literal>,
+			[<literal>NOT</literal>] <literal>MEMBER</literal> [<literal>OF</literal>]
+					</para></listitem><listitem><para>
+			Logical operators: <literal>NOT</literal> <literal>AND</literal> <literal>OR</literal>
+					</para></listitem></itemizedlist>
+
+			The following sections describe other operators used in specific expressions.
+			</para>
+          </section>
+          <section id="jpa_langref_between">
+            <title>JPQL Between Expressions</title>
+            <para>
+			The syntax for the use of the comparison
+			operator [<literal>NOT</literal>] <literal>BETWEEN</literal> in a
+			conditional expression is as follows:
+			</para>
+            <para>
+
+			arithmetic_expression [NOT] BETWEEN arithmetic_expression
+			AND arithmetic_expression | string_expression [NOT] BETWEEN
+			string_expression AND string_expression | datetime_expression [NOT]
+			BETWEEN datetime_expression AND datetime_expression
+			</para>
+            <para>The BETWEEN expression
+
+<programlisting format="linespecific">x BETWEEN y AND z</programlisting>
+
+			is semantically equivalent to:
+
+<programlisting format="linespecific">y &lt;= x AND x &lt;= z</programlisting>
+
+			The rules for unknown and
+			<literal>NULL</literal> values in comparison operations apply. See
+			<xref linkend="jpa_langref_null_values"/>. Examples
+			are:
+
+<programlisting format="linespecific">p.age BETWEEN 15 and 19</programlisting>
+
+			is equivalent to
+
+<programlisting format="linespecific">p.age &gt;= 15 AND p.age &lt;= 19</programlisting>
+			</para>
+            <para><programlisting format="linespecific">p.age NOT BETWEEN 15 and 19</programlisting>
+
+			is equivalent to
+
+<programlisting format="linespecific">p.age &lt; 15 OR p.age &gt; 19</programlisting></para>
+          </section>
+          <section id="jpa_langref_in">
+            <title>JPQL In Expressions</title>
+            <para>
+			The syntax for the use of the comparison operator
+			[<literal>NOT</literal>] <literal>IN</literal> in a conditional expression is as follows:
+
+
+			</para>
+            <para>
+              <itemizedlist>
+                <listitem>
+                  <para>in_expression ::= state_field_path_expression [NOT] IN ( in_item {, in_item}* | subquery) </para>
+                </listitem>
+                <listitem>
+                  <para>in_item ::= literal | input_parameter</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+            <para>
+
+			The state_field_path_expression must have a string, numeric, or enum
+			value. The literal and/or input_parameter values must be like the same
+			abstract schema type of the state_field_path_expression in type. (See
+			<xref linkend="jpa_langref_equality"/>).
+			</para>
+            <para>
+
+			The results of the subquery must be like the same abstract schema type
+			of the state_field_path_expression in type. Subqueries are discussed in
+			<xref linkend="jpa_langref_subqueries"/>. Examples are:
+
+<programlisting format="linespecific">o.country IN ('UK', 'US', 'France')</programlisting>
+
+			is true for UK and false for Peru, and is equivalent to the
+			expression:
+
+<programlisting format="linespecific">(o.country = 'UK') OR (o.country = 'US') OR (o.country = ' France')</programlisting> 
+
+			In the following expression:
+
+<programlisting format="linespecific">o.country NOT IN ('UK', 'US', 'France')</programlisting>
+
+			is false for UK and true for Peru, and is equivalent to the expression:
+
+<programlisting format="linespecific">NOT ((o.country = 'UK') OR (o.country = 'US') OR (o.country = 'France'))</programlisting>
+
+			 There must be at least one
+			element in the comma separated list that defines the set of values for
+			the <literal>IN</literal> expression. If the value of a state_field_path_expression in an
+			<literal>IN</literal> or <literal>NOT IN</literal> expression is
+			<literal>NULL</literal> or unknown, the value of the expression is unknown.
+
+			</para>
+          </section>
+          <section id="jpa_langref_like">
+            <title>JPQL Like Expressions</title>
+            <para>
+			The syntax for the use of the comparison operator
+			[<literal>NOT</literal>] <literal>LIKE</literal> in a
+			conditional expression is as follows:
+			</para>
+            <para>
+			string_expression [NOT] LIKE pattern_value [ESCAPE escape_character]
+			</para>
+            <para>
+			The string_expression must have a string value. The pattern_value is a
+			string literal or a string-valued input parameter in which an underscore
+			(_) stands for any single character, a percent (%) character stands
+			for any sequence of characters (including the empty sequence), and all
+			other characters stand for themselves. The optional escape_character is
+			a single-character string literal or a character-valued input parameter
+			(i.e., char or Character) and is used to escape the special meaning of
+			the underscore and percent characters in pattern_value. Examples are:
+
+			</para>
+            <para>
+              <itemizedlist>
+                <listitem>
+                  <para><programlisting format="linespecific">address.phone LIKE '12%3'</programlisting>
+					is true for '123' '12993' and false for '1234' 
+					</para>
+                </listitem>
+                <listitem>
+                  <para><programlisting format="linespecific">asentence.word LIKE 'l_se'</programlisting>
+					is true for 'lose' and false for 'loose' 
+					</para>
+                </listitem>
+                <listitem>
+                  <para><programlisting format="linespecific">aword.underscored LIKE '\_%' ESCAPE '\'</programlisting>
+					is true for '_foo' and false for 'bar' 
+					</para>
+                </listitem>
+                <listitem>
+                  <para><programlisting format="linespecific">address.phone NOT LIKE '12%3'</programlisting>
+
+			is false for '123'
+			and '12993' and true for '1234' If the value of the string_expression
+			or pattern_value is <literal>NULL</literal> or unknown, the value of the
+			<literal>LIKE</literal> expression
+			is unknown. If the escape_character is specified and is <literal>NULL</literal>, the value
+			of the <literal>LIKE</literal> expression is unknown.
+					</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+          </section>
+          <section id="jpa_langref_null">
+            <title>JPQL Null Comparison Expressions</title>
+            <para>
+			The syntax for the use of the
+			comparison operator <literal>IS NULL</literal> in a conditional expression is as follows:
+
+			</para>
+            <para>
+			{single_valued_path_expression | input_parameter } IS [NOT] NULL
+			</para>
+            <para>A null comparison expression tests whether or not the single-valued path
+			expression or input parameter is a <literal>NULL</literal> value.
+
+			</para>
+          </section>
+          <section id="jpa_langref_empty_comp">
+            <title>JPQL Empty Collection Comparison Expressions</title>
+            <para>
+			The syntax
+			for the use of the comparison operator <literal>IS EMPTY</literal> in an
+			empty_collection_comparison_expression is as follows:
+			</para>
+            <para>
+
+			collection_valued_path_expression IS [NOT] EMPTY
+
+			</para>
+            <para>
+
+			This expression tests whether or not the collection designated
+			by the collection-valued path expression is empty (i.e, has no
+			elements).
+
+			</para>
+            <para>
+			For example, the following query will return all magazines that
+			don't have any articles at all:
+
+<programlisting format="linespecific">SELECT mag FROM Magazine mag WHERE mag.articles IS EMPTY</programlisting>
+
+			If the value of the collection-valued path expression in an empty collection
+			comparison expression is unknown, the value of the empty comparison
+			expression is unknown.
+
+			</para>
+          </section>
+          <section id="jpa_langref_collection_member">
+            <title>JPQL Collection Member Expressions</title>
+            <para>
+			The use of the comparison
+			collection_member_expression is as follows: syntax for the operator
+			<literal>MEMBER OF</literal> in an
+
+<itemizedlist><listitem><para>collection_member_expression ::= entity_expression [NOT] MEMBER [OF] collection_valued_path_expression</para></listitem><listitem><para>entity_expression ::= single_valued_association_path_expression | simple_entity_expression </para></listitem><listitem><para>simple_entity_expression ::= identification_variable | input_parameter</para></listitem></itemizedlist>
+
+			</para>
+            <para>
+
+			This expression tests whether
+			the designated value is a member of the collection specified by the
+			collection-valued path expression. If the collection valued path
+			expression designates an empty collection, the value of the
+			<literal>MEMBER OF</literal> expression is <literal>FALSE</literal> and
+			the value of the <literal>NOT MEMBER OF</literal> expression is
+			<literal>TRUE</literal>. Otherwise, if the value of the collection-valued path expression
+			or single-valued association-field path expression in the collection
+			member expression is <literal>NULL</literal> or unknown, the value of the collection member
+			expression is unknown.
+
+			</para>
+          </section>
+          <section id="jpa_langref_exists">
+            <title>JPQL Exists Expressions</title>
+            <para>
+			An <literal>EXISTS</literal> expression is a predicate that is
+			true only if the result of the subquery consists of one or more values
+			and that is false otherwise. The syntax of an exists expression is
+
+<itemizedlist><listitem><para>exists_expression ::= [NOT] EXISTS (subquery)</para></listitem></itemizedlist>
+
+			</para>
+            <para>
+			The use of the reserved word OF is optional in this expression.
+
+			</para>
+            <para>
+			Example:
+
+<programlisting format="linespecific">SELECT DISTINCT auth FROM Author auth
+    WHERE EXISTS
+        (SELECT spouseAuthor FROM Author spouseAuthor WHERE spouseAuthor = auth.spouse)</programlisting>
+
+			The result of this query consists of all authors whose spouse is also an author.
+
+			</para>
+          </section>
+          <section id="jpa_langref_all_any">
+            <title>JPQL All or Any Expressions</title>
+            <para>
+			An <literal>ALL</literal> conditional expression is a predicate
+			that is true if the comparison operation is true for all values in the
+			result of the subquery or the result of the subquery is empty. An
+			<literal>ALL</literal> conditional expression is false
+			if the result of the comparison is false
+			for at least one row, and is unknown if neither true nor false. An
+			<literal>ANY</literal> conditional expression is a
+			predicate that is true if the comparison
+			operation is true for some value in the result of the subquery. An
+			<literal>ANY</literal> conditional expression is false if the
+			result of the subquery is empty
+			or if the comparison operation is false for every value in the result
+			of the subquery, and is unknown if neither true nor false. The keyword
+			<literal>SOME</literal> is synonymous with <literal>ANY</literal>.
+			The comparison operators used with <literal>ALL</literal>
+			or <literal>ANY</literal> conditional expressions are =, &lt;, &lt;=, &gt;, &gt;=, &lt;&gt;. The result of
+			the subquery must be like that of the other argument to the comparison
+			operator in type. See <xref linkend="jpa_langref_equality"/>.
+			The syntax of an <literal>ALL</literal> or <literal>ANY</literal>
+			expression is specified as follows:
+
+<itemizedlist><listitem><para>all_or_any_expression ::= { ALL | ANY | SOME} (subquery)</para></listitem></itemizedlist>
+
+			</para>
+            <para>
+
+			The following example select the authors who make the highest salary for
+			their magazine:
+
+<programlisting format="linespecific">SELECT auth FROM Author auth
+    WHERE auth.salary &gt;= ALL(SELECT a.salary FROM Author a WHERE a.magazine = auth.magazine)</programlisting>
+
+			</para>
+          </section>
+          <section id="jpa_langref_subqueries">
+            <title>JPQL Subqueries</title>
+            <para>
+			Subqueries may be used in the <literal>WHERE</literal> or
+			<literal>HAVING</literal> clause. The syntax for subqueries is as follows:
+
+<itemizedlist><listitem><para>subquery ::= simple_select_clause subquery_from_clause [where_clause] [groupby_clause] [having_clause] </para></listitem></itemizedlist>
+
+			</para>
+            <para>
+
+			Subqueries are restricted to the <literal>WHERE</literal> and
+			<literal>HAVING</literal> clauses in this
+			release. Support for subqueries in the <literal>FROM</literal>
+			clause will be considered in a later release of the specification.
+
+
+<itemizedlist><listitem><para>simple_select_clause ::= SELECT [DISTINCT] simple_select_expression </para></listitem><listitem><para>subquery_from_clause ::= FROM subselect_identification_variable_declaration {, subselect_identification_variable_declaration}*</para></listitem><listitem><para>subselect_identification_variable_declaration ::= identification_variable_declaration | association_path_expression [AS] identification_variable | collection_member_declaration</para></listitem><listitem><para>simple_select_expression ::= single_valued_path_expression | aggregate_expression | identification_variable</para></listitem></itemizedlist>
+
+			</para>
+            <para>
+
+			Examples:
+
+<programlisting format="linespecific">SELECT DISTINCT auth FROM Author auth
+    WHERE EXISTS (SELECT spouseAuth FROM Author spouseAuth WHERE spouseAuth = auth.spouse)</programlisting>
+
+<programlisting format="linespecific">SELECT mag FROM Magazine mag
+    WHERE (SELECT COUNT(art) FROM mag.articles art) &gt; 10</programlisting>
+
+			Note that some contexts in which
+			a subquery can be used require that the subquery be a scalar subquery
+			(i.e., produce a single result). This is illustrated in the following
+			example involving a numeric comparison operation.
+
+<programlisting format="linespecific">SELECT goodPublisher FROM Publisher goodPublisher
+    WHERE goodPublisher.revenue &lt; (SELECT AVG(p.revenue) FROM Publisher p)</programlisting>
+
+			</para>
+          </section>
+          <section id="jpa_langref_functional">
+            <title>JPQL Functional Expressions</title>
+            <para>
+			The JPQL includes
+			the following built-in functions, which may be used in the <literal>WHERE</literal>
+			or <literal>HAVING</literal> clause of a query. If the
+			value of any argument to a functional expression
+			is null or unknown, the value of the functional expression is unknown.
+
+			</para>
+            <section id="jpa_langref_string_fun">
+              <title>JPQL String Functions</title>
+              <para>
+                <itemizedlist>
+                  <listitem>
+                    <para>functions_returning_strings ::= CONCAT(string_primar y, string_primary) | SUBSTRING(string_primar y, simple_arithmetic_expression, simple_arithmetic_expression) | TRIM([[trim_specification] [trim_character] FROM] string_primary) | LOWER(string_primar y) | UPPER(string_primar y) </para>
+                  </listitem>
+                  <listitem>
+                    <para>trim_specification ::= LEADING | TRAILING | BOTH</para>
+                  </listitem>
+                  <listitem>
+                    <para>functions_returning_numerics ::= LENGTH(string_primar y) | LOCATE(string_primar y, string_primar y[, simple_arithmetic_expression])</para>
+                  </listitem>
+                </itemizedlist>
+              </para>
+              <para>
+
+				The <literal>CONCAT</literal> function returns a string that is a concatenation of its
+				arguments. The second and third arguments of the
+				<literal>SUBSTRING</literal> function denote
+				the starting position and length of the substring to be returned. These
+				arguments are integers. The first position of a string is denoted by
+				1. The <literal>SUBSTRING</literal> function returns a string.
+				The <literal>TRIM</literal> function trims
+				the specified character from a string. If the character to be trimmed
+				is not specified, it is assumed to be space (or blank). The optional
+				trim_character is a single-character string literal or a character-valued
+				input parameter (i.e., char or Character). If a trim specification
+				is not provided, <literal>BOTH</literal> is assumed.
+				The <literal>TRIM</literal> function returns the trimmed
+				string. The <literal>LOWER</literal> and <literal>UPPER</literal>
+				functions convert a string to lower and upper
+				case, respectively. They return a string. The <literal>LOCATE</literal> function returns
+				the position of a given string within a string, starting the search at
+				a specified position. It returns the first position at which the string
+				was found as an integer. The first argument is the string to be located;
+				the second argument is the string to be searched; the optional third
+				argument is an integer that represents the string position at which
+				the search is started (by default, the beginning of the string to be
+				searched). The first position in a string is denoted by 1. If the string
+				is not found, 0 is returned. The <literal>LENGTH</literal> function
+				returns the length of the string in characters as an integer.
+
+				</para>
+            </section>
+            <section id="jpa_langref_arithmetic">
+              <title>JPQL Arithmetic Functions</title>
+              <para>
+                <itemizedlist>
+                  <listitem>
+                    <para>functions_returning_numerics ::= ABS(simple_arithmetic_expression) | SQRT(simple_arithmetic_expression) | MOD(simple_arithmetic_expression, simple_arithmetic_expression) | SIZE(collection_valued_path_expression)</para>
+                  </listitem>
+                </itemizedlist>
+              </para>
+              <para>
+				The <literal>ABS</literal> function takes a numeric
+				argument and returns a number (integer, float, or double) of the same
+				type as the argument to the function. The
+				<literal>SQRT</literal> function takes a numeric
+				argument and returns a double.
+
+				</para>
+              <para>
+				Note that not all databases support the use of a trim character
+				other than the space character; use of this argument may result in
+				queries that are not portable. Note that not all databases support
+				the use of the third argument to <literal>LOCATE</literal>;
+				use of this argument may result
+				in queries that are not portable.
+
+				</para>
+              <para>
+
+				The <literal>MOD</literal> function takes two integer
+				arguments and returns an integer. The
+				<literal>SIZE</literal> function returns an integer value,
+				the number of elements of the
+				collection. If the collection is empty, the
+				<literal>SIZE</literal> function evaluates to
+				zero. Numeric arguments to these functions may correspond to the numeric
+				Java object types as well as the primitive numeric types.
+
+				</para>
+            </section>
+            <section id="jpa_langref_datetime">
+              <title>JPQL Datetime Functions</title>
+              <para>
+				functions_returning_datetime:= CURRENT_DATE |
+				CURRENT_TIME | CURRENT_TIMESTAMP
+				</para>
+              <para>
+
+				The datetime functions return the value of current date, time, and
+				timestamp on the database server.
+
+				</para>
+            </section>
+          </section>
+        </section>
+        <section id="jpa_langref_group">
+          <title>JPQL GROUP BY, HAVING</title>
+          <para>
+		The <literal>GROUP BY</literal> construct enables the aggregation of
+		values according to a set of properties. The <literal>HAVING</literal> construct enables
+		conditions to be specified that further restrict the query result. Such
+		conditions are restrictions upon the groups. The syntax of the
+		<literal>GROUP BY</literal> and <literal>HAVING</literal> clauses is as follows:
+
+		</para>
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para>groupby_clause ::= GROUP BY groupby_item {, groupby_item}* </para>
+              </listitem>
+              <listitem>
+                <para>groupby_item ::= single_valued_path_expression | identification_variable </para>
+              </listitem>
+              <listitem>
+                <para>having_clause ::= HAVING conditional_expression</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <para>
+
+		If a query contains both a <literal>WHERE</literal> clause
+		and a <literal>GROUP BY</literal> clause, the effect is that of first applying the where
+		clause, and then forming the groups and filtering them according to
+		the <literal>HAVING</literal> clause. The <literal>HAVING</literal>
+		clause causes those groups to be retained that satisfy the condition of
+		the <literal>HAVING</literal> clause. The requirements for
+		the <literal>SELECT</literal> clause when <literal>GROUP BY</literal>
+		is used follow those of SQL: namely, any item that appears in the
+		<literal>SELECT</literal> clause (other than as an argument
+		to an aggregate function) must also appear in the <literal>GROUP BY</literal>
+		clause. In forming the groups, null values are treated as the same for grouping
+		purposes. Grouping by an entity is permitted. In this case, the entity
+		must contain no serialized state fields or lob-valued state fields. The
+		<literal>HAVING</literal> clause must specify search conditions over the grouping items or
+		aggregate functions that apply to grouping items.
+
+
+		</para>
+          <para>
+
+		If there is no <literal>GROUP BY</literal> clause and the
+		<literal>HAVING</literal> clause is used, the
+		result is treated as a single group, and the select list can only
+		consist of aggregate functions.
+		When a query declares a <literal>HAVING</literal> clause, it must
+		always also declare a <literal>GROUP BY</literal> clause.
+		</para>
+        </section>
+        <section id="jpa_langref_select_clause">
+          <title>JPQL SELECT Clause</title>
+          <para>
+		The <literal>SELECT</literal> clause denotes the query result. More than
+		one value may be returned from the <literal>SELECT</literal> clause of a query.
+		The <literal>SELECT</literal> clause may contain one or more of the following elements: a single
+		range variable or identification variable that ranges over an entity
+		abstract schema type, a single-valued path expression, an aggregate
+		select expression, a constructor expression. The <literal>SELECT</literal> clause has the
+		following syntax:
+
+
+		</para>
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para>select_clause ::= SELECT [DISTINCT] select_expression {, select_expression}* </para>
+              </listitem>
+              <listitem>
+                <para>select_expression ::= single_valued_path_expression | aggregate_expression | identification_variable | OBJECT(identification_variable) | constructor_expression</para>
+              </listitem>
+              <listitem>
+                <para>constructor_expression ::= NEW constructor_name ( constructor_item {, constructor_item}* ) </para>
+              </listitem>
+              <listitem>
+                <para>constructor_item ::= single_valued_path_expression | aggregate_expression </para>
+              </listitem>
+              <listitem>
+                <para>aggregate_expression ::= { AVG | MAX | MIN | SUM } ([DISTINCT] state_field_path_expression) | COUNT ([DISTINCT] identification_variable | state_field_path_expression | single_valued_association_path_expression)</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <para>
+
+		For example:
+
+<programlisting format="linespecific">SELECT pub.id, pub.revenue
+    FROM Publisher pub JOIN pub.magazines mag WHERE mag.price &gt; 5.00</programlisting>
+
+		</para>
+          <para>
+
+		Note that the <literal>SELECT</literal> clause must be specified to return
+		only single-valued expressions. The query below is therefore not valid:
+
+<programlisting format="linespecific">SELECT mag.authors FROM Magazine AS mag</programlisting>
+
+		The <literal>DISTINCT</literal> keyword is used to specify that duplicate
+		values must be eliminated from the query result. If <literal>DISTINCT</literal> is not
+		specified, duplicate values are not eliminated. Standalone identification
+		variables in the <literal>SELECT</literal> clause may optionally be qualified by the
+		<literal>OBJECT</literal> operator. The <literal>SELECT</literal> clause must not
+		use the OBJECT operator to qualify path expressions.
+
+		</para>
+          <section id="jpa_langref_resulttype">
+            <title>JPQL Result Type of the SELECT Clause</title>
+            <para>
+			The type of the query result
+			specified by the <literal>SELECT</literal> clause of a query is an entity abstract schema
+			type, a state-field type, the result of an aggregate function, the result
+			of a construction operation, or some sequence of these. The result
+			type of the <literal>SELECT</literal> clause is defined by the the result types of the
+			select_expressions contained in it. When multiple select_expressions are
+			used in the <literal>SELECT</literal> clause, the result of the query is of type Object[],
+			and the elements in this result correspond in order to the order of
+			their specification in the <literal>SELECT</literal> clause and in type to the result
+			types of each of the select_expressions. The type of the result of a
+			select_expression is as follows:
+
+				<itemizedlist><listitem><para>
+			A single_valued_path_expression that is a state_field_path_expression
+			results in an object of the same type as the corresponding state field
+			of the entity. If the state field of the entity is a primitive type,
+			the corresponding object type is returned.
+					</para></listitem><listitem><para>
+			single_valued_path_expression that is a
+			single_valued_association_path_expression results in an entity object
+			of the type of the relationship field or the subtype of the relationship
+			field of the entity object as determined by the object/relational mapping.
+					</para></listitem><listitem><para>
+			The result type of an identification_variable is the type of the
+			entity to which that identification variable corresponds or a subtype
+			as determined by the object/relational mapping.
+					</para></listitem><listitem><para>
+			The result type of aggregate_expression is defined in section
+			<xref linkend="jpa_langref_aggregates"/>.
+					</para></listitem><listitem><para>
+			The result type of a constructor_expression is the type of the class
+			for which the constructor is defined. The types of the arguments to the
+			constructor are defined by the above rules.
+					</para></listitem></itemizedlist>
+
+			</para>
+          </section>
+          <section id="jpa_langref_constructor">
+            <title>JPQL Constructor Expressions</title>
+            <para>
+			in the <literal>SELECT</literal> Clause A constructor may
+			be used in the <literal>SELECT</literal> list to return one or more Java instances. The
+			specified class is not required to be an entity or to be mapped to the
+			database. The constructor name must be fully qualified.
+
+
+			</para>
+            <para>
+			If an entity class name is specified in the <literal>SELECT NEW</literal> clause,
+			the resulting entity instances are in the new state.
+
+<programlisting format="linespecific">SELECT NEW com.company.PublisherInfo(pub.id, pub.revenue, mag.price)
+    FROM Publisher pub JOIN pub.magazines mag WHERE mag.price &gt; 5.00</programlisting>
+
+			</para>
+          </section>
+          <section id="jpa_langref_null_select">
+            <title>JPQL Null Values in the Query Result</title>
+            <para>
+			If the result of a query corresponds
+			to a association-field or state-field whose value is null, that null
+			value is returned in the result of the query method.
+			The <literal>IS NOT NULL</literal>
+			construct can be used to eliminate such null values from the result set
+			of the query. Note, however, that state-field types defined in terms of
+			Java numeric primitive types cannot produce <literal>NULL</literal>
+			values in the query
+			result. A query that returns such a state-field type as a result type
+			must not return a null value.
+
+			</para>
+          </section>
+          <section id="jpa_langref_aggregates">
+            <title>JPQL Aggregate Functions</title>
+            <para>
+			in the <literal>SELECT</literal> Clause The result of a query may
+			be the result of an aggregate function applied to a path expression. The
+			following aggregate functions can be used in the <literal>SELECT</literal> clause of a query:
+			<literal>AVG</literal>, <literal>COUNT</literal>, <literal>MAX</literal>,
+			<literal>MIN</literal>, <literal>SUM</literal>.
+			For all aggregate functions except <literal>COUNT</literal>,
+			the path expression that is the argument to the aggregate function must
+			terminate in a state-field. The path expression argument to <literal>COUNT</literal> may
+			terminate in either a state-field or a association-field, or the argument
+			to <literal>COUNT</literal> may be an identification variable. Arguments to the functions
+			<literal>SUM</literal> and <literal>AVG</literal> must be numeric. Arguments
+			to the functions <literal>MAX</literal> and <literal>MIN</literal> must
+			correspond to orderable state-field types (i.e., numeric types, string
+			types, character types, or date types). The Java type that is contained
+			in the result of a query using an aggregate function is as follows:
+
+				<itemizedlist><listitem><para><literal>COUNT</literal> returns Long.
+					</para></listitem><listitem><para><literal>MAX</literal>, <literal>MIN</literal> return the type of the state-field to
+			which they are applied.
+					</para></listitem><listitem><para><literal>AVG</literal> returns Double.
+					</para></listitem><listitem><para><literal>SUM</literal> returns Long when
+			applied to state-fields of integral types (other than BigInteger); Double
+			when applied to state-fields of floating point types; BigInteger when
+			applied to state-fields of type BigInteger; and BigDecimal when applied
+			to state-fields of type BigDecimal. If <literal>SUM</literal>, <literal>AVG</literal>,
+			<literal>MAX</literal>, or <literal>MIN</literal> is used,
+			and there are no values to which the aggregate function can be applied,
+			the result of the aggregate function is <literal>NULL</literal>.
+			If <literal>COUNT</literal> is used, and
+			there are no values to which <literal>COUNT</literal> can be applied, the result of the
+			aggregate function is 0.
+					</para></listitem></itemizedlist>
+
+			</para>
+            <para>
+
+			The argument to an aggregate function may be preceded by the keyword
+			<literal>DISTINCT</literal> to specify that duplicate values are to be eliminated before
+			the aggregate function is applied. Null values are eliminated before
+			the aggregate function is applied, regardless of whether the keyword
+			<literal>DISTINCT</literal> is specified.
+
+			</para>
+            <section id="jpa_langref_agg_examples">
+              <title>JPQL Aggregate Examples</title>
+              <para>
+				Examples The following query returns the average price of all magazines:
+
+<programlisting format="linespecific">SELECT AVG(mag.price) FROM Magazine mag</programlisting>
+
+				The following query returns the sum total cost of all the prices from 
+				all the magazines published by 'Larry':
+
+<programlisting format="linespecific">SELECT SUM(mag.price) FROM Publisher pub JOIN pub.magazines mag pub.firstName = 'Larry'</programlisting>
+
+				The following query returns the total number of magazines:
+
+<programlisting format="linespecific">SELECT COUNT(mag) FROM Magazine mag</programlisting>
+
+				</para>
+            </section>
+          </section>
+        </section>
+        <section id="jpa_langref_orderby">
+          <title>JPQL ORDER BY Clause</title>
+          <para>
+		The <literal>ORDER BY</literal> clause allows the objects or values
+		that are returned by the query to be ordered.
+		The syntax of the <literal>ORDER BY</literal> clause is
+		</para>
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para>orderby_clause ::= ORDER BY orderby_item {, orderby_item}*</para>
+              </listitem>
+              <listitem>
+                <para>orderby_item ::= state_field_path_expression [ASC | DESC]</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <para>
+		It is legal to specify <literal>DISTINCT</literal> with <literal>MAX</literal>
+		or <literal>MIN</literal>, but it does not affect the result.
+
+		</para>
+          <para>
+
+		When the <literal>ORDER BY</literal> clause is used in a query, each element of the
+		<literal>SELECT</literal> clause of the query must be one of the following: an
+		identification variable x, optionally denoted as <literal>OBJECT(x)</literal>,
+		 a single_valued_association_path_expression,
+		or a state_field_path_expression. For example:
+
+<programlisting format="linespecific">
+SELECT pub FROM Publisher pub JOIN pub.magazines mag ORDER BY o.revenue, o.name
+</programlisting>
+
+		If more
+		than one orderby_item is specified, the left-to-right sequence of the
+		orderby_item elements determines the precedence, whereby the leftmost
+		orderby_item has highest precedence.
+		The keyword <literal>ASC</literal> specifies that
+		ascending ordering be used; the keyword
+		<literal>DESC</literal> specifies that descending
+		ordering be used. Ascending ordering is the default. SQL rules for the
+		ordering of null values apply: that is, all null values must appear before
+		all non-null values in the ordering or all null values must appear after
+		all non-null values in the ordering, but it is not specified which. The
+		ordering of the query result is preserved in the result of the query
+		method if the <literal>ORDER BY</literal> clause is used.
+
+
+		</para>
+        </section>
+        <section id="jpa_langref_bulk_ops">
+          <title>JPQL Bulk Update and Delete</title>
+          <para>
+		Operations Bulk update and delete operations
+		apply to entities of a single entity class (together with its subclasses,
+		if any). Only one entity abstract schema type may be specified in the
+		<literal>FROM</literal> or <literal>UPDATE</literal> clause.
+		The syntax of these operations is as follows:
+
+		</para>
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para>update_statement ::= update_clause [where_clause] </para>
+              </listitem>
+              <listitem>
+                <para>update_clause ::= UPDATE abstract_schema_name [[AS] identification_variable] SET update_item {, update_item}* </para>
+              </listitem>
+              <listitem>
+                <para>update_item ::= [identification_variable.]{state_field | single_valued_association_field} = new_value </para>
+              </listitem>
+              <listitem>
+                <para>new_value ::= simple_arithmetic_expression | string_primary | datetime_primary | boolean_primary | enum_primary simple_entity_expression | NULL</para>
+              </listitem>
+              <listitem>
+                <para>delete_statement ::= delete_clause [where_clause] </para>
+              </listitem>
+              <listitem>
+                <para>delete_clause ::= DELETE FROM abstract_schema_name [[AS] identification_variable]</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <para>
+
+		The syntax of
+		the <literal>WHERE</literal> clause is
+		described in <xref linkend="jpa_langref_where"/>.
+		A delete operation only
+		applies to entities of the specified class and its subclasses. It does
+		not cascade to related entities. The new_value specified for an update
+		operation must be compatible in type with the state-field to which it
+		is assigned. Bulk update maps directly to a database update operation,
+		bypassing optimistic locking checks. Portable applications must manually
+		update the value of the version column, if desired, and/or manually
+		validate the value of the version column. The persistence context is
+		not synchronized with the result of the bulk update or delete. Caution
+		should be used when executing bulk update or delete operations because
+		they may result in inconsistencies between the database and the entities
+		in the active persistence context. In general, bulk update and delete
+		operations should only be performed within a separate transaction or
+		at the beginning of a transaction (before entities have been accessed
+		whose state might be affected by such operations).
+
+
+		</para>
+          <para>
+
+		Examples:
+
+<programlisting format="linespecific">DELETE FROM Publisher pub WHERE pub.revenue &gt; 1000000.0</programlisting> 
+<programlisting format="linespecific">DELETE FROM Publisher pub WHERE pub.revenue = 0 AND pub.magazines IS EMPTY</programlisting> 
+<programlisting format="linespecific">UPDATE Publisher pub SET pub.status = 'outstanding'
+    WHERE pub.revenue &lt; 1000000 AND 20 &gt; (SELECT COUNT(mag) FROM pub.magazines mag)</programlisting>
+
+		</para>
+        </section>
+        <section id="jpa_langref_null_values">
+          <title>JPQL Null Values</title>
+          <para>
+		When the target of a reference does not exist in
+		the database, its value is regarded as <literal>NULL</literal>.
+		SQL 92 <literal>NULL</literal> semantics
+		defines the evaluation of conditional expressions containing <literal>NULL</literal>
+		values. The following is a brief description of these semantics:
+
+		</para>
+          <para>
+            <itemizedlist>
+              <listitem>
+                <para>
+		Comparison or arithmetic operations with a <literal>NULL</literal> value always yield
+		an unknown value. 
+					</para>
+              </listitem>
+              <listitem>
+                <para>
+		Two <literal>NULL</literal> values are not considered to be equal,
+		the comparison yields an unknown value.
+					</para>
+              </listitem>
+              <listitem>
+                <para>
+		Comparison or arithmetic
+		operations with an unknown value always yield an unknown value.
+					</para>
+              </listitem>
+              <listitem>
+                <para>
+		The <literal>IS NULL</literal> and <literal>IS NOT NULL</literal>
+		operators convert a <literal>NULL</literal> state-field or single-valued
+		association-field value into the respective
+		<literal>TRUE</literal> or <literal>FALSE</literal> value.
+					</para>
+              </listitem>
+            </itemizedlist>
+          </para>
+          <para>
+		Note: The JPQL defines the empty string, "",
+		as a string with 0 length, which is not equal to a <literal>NULL</literal> value. However,
+		<literal>NULL</literal> values and empty strings may not always be distinguished when
+		queries are mapped to some databases. Application developers should
+		therefore not rely on the semantics of query comparisons involving the
+		empty string and <literal>NULL</literal> value.
+
+		</para>
+        </section>
+        <section id="jpa_langref_equality">
+          <title>JPQL Equality and Comparison Semantics</title>
+          <para>
+
+		Only the values of like types are
+		permitted to be compared. A type is like another type if they correspond
+		to the same Java language type, or if one is a primitive Java language
+		type and the other is the wrappered Java class type equivalent (e.g.,
+		int and Integer are like types in this sense). There is one exception to
+		this rule: it is valid to compare numeric values for which the rules of
+		numeric promotion apply. Conditional expressions attempting to compare
+		non-like type values are disallowed except for this numeric case. Note
+		that the arithmetic operators and comparison operators are permitted to
+		be applied to state-fields and input parameters of the wrappered Java
+		class equivalents to the primitive numeric Java types. Two entities of
+		the same abstract schema type are equal if and only if they have the
+		same primary key value. Only equality/inequality comparisons over enums
+		are required to be supported.
+
+
+		</para>
+        </section>
+        <section id="jpa_langref_bnf">
+          <title>JPQL BNF</title>
+          <para>
+			The following is the BNF for the Java Persistence query language,
+			from section 4.14 of the JSR 220 specification.
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para>QL_statement ::= select_statement | update_statement | delete_statement </para>
+            </listitem>
+            <listitem>
+              <para>select_statement ::= select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause] </para>
+            </listitem>
+            <listitem>
+              <para>update_statement ::= update_clause [where_clause] </para>
+            </listitem>
+            <listitem>
+              <para>delete_statement ::= delete_clause [where_clause] </para>
+            </listitem>
+            <listitem>
+              <para>from_clause ::= <literal>FROM</literal> identification_variable_declaration {, {identification_variable_declaration | collection_member_declaration}}* </para>
+            </listitem>
+            <listitem>
+              <para>identification_variable_declaration ::= range_variable_declaration { join | fetch_join }* </para>
+            </listitem>
+            <listitem>
+              <para>range_variable_declaration ::= abstract_schema_name [<literal>AS</literal>] identification_variable</para>
+            </listitem>
+            <listitem>
+              <para>join ::= join_spec join_association_path_expression [<literal>AS</literal>] identification_variable</para>
+            </listitem>
+            <listitem>
+              <para>fetch_join ::= join_spec <literal>FETCH</literal> join_association_path_expression </para>
+            </listitem>
+            <listitem>
+              <para>association_path_expression ::= collection_valued_path_expression | single_valued_association_path_expression </para>
+            </listitem>
+            <listitem>
+              <para>join_spec ::= [<literal>LEFT</literal> [<literal>OUTER</literal>]|<literal>INNER</literal>] <literal>JOIN</literal> </para>
+            </listitem>
+            <listitem>
+              <para>join_association_path_expression ::= join_collection_valued_path_expression | join_single_valued_association_path_expression </para>
+            </listitem>
+            <listitem>
+              <para>join_collection_valued_path_expression ::= identification_variable.collection_valued_association_field </para>
+            </listitem>
+            <listitem>
+              <para>join_single_valued_association_path_expression ::= identification_variable.single_valued_association_field </para>
+            </listitem>
+            <listitem>
+              <para>collection_member_declaration ::= <literal>IN</literal> (collection_valued_path_expression) [<literal>AS</literal>] identification_variable </para>
+            </listitem>
+            <listitem>
+              <para>single_valued_path_expression ::= state_field_path_expression | single_valued_association_path_expression </para>
+            </listitem>
+            <listitem>
+              <para>state_field_path_expression ::= {identification_variable | single_valued_association_path_expression}.state_field </para>
+            </listitem>
+            <listitem>
+              <para>single_valued_association_path_expression ::= identification_variable.{single_valued_association_field.}* single_valued_association_field </para>
+            </listitem>
+            <listitem>
+              <para>collection_valued_path_expression ::= identification_variable.{single_valued_association_field.}*collection_valued_association_field </para>
+            </listitem>
+            <listitem>
+              <para>state_field ::= {embedded_class_state_field.}*simple_state_field </para>
+            </listitem>
+            <listitem>
+              <para>update_clause ::= <literal>UPDATE</literal> abstract_schema_name [[<literal>AS</literal>] identification_variable] <literal>SET</literal> update_item {, update_item}* </para>
+            </listitem>
+            <listitem>
+              <para>update_item ::= [identification_variable.]{state_field | single_valued_association_field}= new_value </para>
+            </listitem>
+            <listitem>
+              <para>new_value ::= simple_arithmetic_expression | string_primary | datetime_primary | boolean_primary | enum_primary simple_entity_expression | <literal>NULL</literal> </para>
+            </listitem>
+            <listitem>
+              <para>delete_clause ::= <literal>DELETE</literal> <literal>FROM</literal> abstract_schema_name [[<literal>AS</literal>] identification_variable] </para>
+            </listitem>
+            <listitem>
+              <para>select_clause ::= <literal>SELECT</literal> [<literal>DISTINCT</literal>] select_expression {, select_expression}* </para>
+            </listitem>
+            <listitem>
+              <para>select_expression ::= single_valued_path_expression | aggregate_expression | identification_variable | <literal>OBJECT</literal>(identification_variable)| constructor_expression </para>
+            </listitem>
+            <listitem>
+              <para>constructor_expression ::= <literal>NEW</literal> constructor_name( constructor_item {, constructor_item}*) </para>
+            </listitem>
+            <listitem>
+              <para>constructor_item ::= single_valued_path_expression | aggregate_expression </para>
+            </listitem>
+            <listitem>
+              <para>aggregate_expression ::= {<literal>AVG</literal> |<literal>MAX</literal> |<literal>MIN</literal> |<literal>SUM</literal>}([<literal>DISTINCT</literal>] state_field_path_expression) | <literal>COUNT</literal> ([<literal>DISTINCT</literal>] identification_variable | state_field_path_expression | single_valued_association_path_expression) </para>
+            </listitem>
+            <listitem>
+              <para>where_clause ::= <literal>WHERE</literal> conditional_expression </para>
+            </listitem>
+            <listitem>
+              <para>groupby_clause ::= <literal>GROUP</literal> <literal>BY</literal> groupby_item {, groupby_item}* </para>
+            </listitem>
+            <listitem>
+              <para>groupby_item ::= single_valued_path_expression | identification_variable </para>
+            </listitem>
+            <listitem>
+              <para>having_clause ::= <literal>HAVING</literal> conditional_expression </para>
+            </listitem>
+            <listitem>
+              <para>orderby_clause ::= <literal>ORDER</literal> <literal>BY</literal> orderby_item {, orderby_item}* </para>
+            </listitem>
+            <listitem>
+              <para>orderby_item ::= state_field_path_expression [<literal>ASC</literal> |<literal>DESC</literal> ] </para>
+            </listitem>
+            <listitem>
+              <para>subquery ::= simple_select_clause subquery_from_clause [where_clause] [groupby_clause] [having_clause] </para>
+            </listitem>
+            <listitem>
+              <para>subquery_from_clause ::= <literal>FROM</literal> subselect_identification_variable_declaration {, subselect_identification_variable_declaration}* </para>
+            </listitem>
+            <listitem>
+              <para>subselect_identification_variable_declaration ::= identification_variable_declaration | association_path_expression [<literal>AS</literal>] identification_variable | collection_member_declaration </para>
+            </listitem>
+            <listitem>
+              <para>simple_select_clause ::= <literal>SELECT</literal> [<literal>DISTINCT</literal>] simple_select_expression </para>
+            </listitem>
+            <listitem>
+              <para>simple_select_expression ::= single_valued_path_expression | aggregate_expression | identification_variable </para>
+            </listitem>
+            <listitem>
+              <para>conditional_expression ::= conditional_term | conditional_expression <literal>OR</literal> conditional_term </para>
+            </listitem>
+            <listitem>
+              <para>conditional_term ::= conditional_factor | conditional_term <literal>AND</literal> conditional_factor </para>
+            </listitem>
+            <listitem>
+              <para>conditional_factor ::= [<literal>NOT</literal> ] conditional_primary </para>
+            </listitem>
+            <listitem>
+              <para>conditional_primary ::= simple_cond_expression |(conditional_expression) </para>
+            </listitem>
+            <listitem>
+              <para>simple_cond_expression ::= comparison_expression | between_expression | like_expression | in_expression | null_comparison_expression | empty_collection_comparison_expression | collection_member_expression | exists_expression </para>
+            </listitem>
+            <listitem>
+              <para>between_expression ::= arithmetic_expression [<literal>NOT</literal>] <literal>BETWEEN</literal> arithmetic_expression <literal>AND</literal> arithmetic_expression | string_expression [<literal>NOT</literal>] <literal>BETWEEN</literal> string_expression <literal>AND</literal> string_expression | datetime_expression [<literal>NOT</literal>] <literal>BETWEEN</literal> datetime_expression <literal>AND</literal> datetime_expression </para>
+            </listitem>
+            <listitem>
+              <para>in_expression ::= state_field_path_expression [<literal>NOT</literal>] <literal>IN</literal>( in_item {, in_item}* | subquery) </para>
+            </listitem>
+            <listitem>
+              <para>in_item ::= literal | input_parameter </para>
+            </listitem>
+            <listitem>
+              <para>like_expression ::= string_expression [<literal>NOT</literal>] <literal>LIKE</literal> pattern_value [<literal>ESCAPE</literal> escape_character] </para>
+            </listitem>
+            <listitem>
+              <para>null_comparison_expression ::= {single_valued_path_expression | input_parameter}<literal>IS</literal> [<literal>NOT</literal>] <literal>NULL</literal> </para>
+            </listitem>
+            <listitem>
+              <para>empty_collection_comparison_expression ::= collection_valued_path_expression <literal>IS</literal> [<literal>NOT</literal>] <literal>EMPTY</literal> </para>
+            </listitem>
+            <listitem>
+              <para>collection_member_expression ::= entity_expression [<literal>NOT</literal>] <literal>MEMBER</literal> [<literal>OF</literal>] collection_valued_path_expression </para>
+            </listitem>
+            <listitem>
+              <para>exists_expression ::= [<literal>NOT</literal>] <literal>EXISTS</literal>(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>all_or_any_expression ::= {<literal>ALL</literal> |<literal>ANY</literal> |<literal>SOME</literal>}(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>comparison_expression ::= string_expressioncomparison_operator{string_expression|all_or_any_expression}| boolean_expression {=|&lt;&gt;} {boolean_expression | all_or_any_expression} | enum_expression {=|&lt;&gt;} {enum_expression | all_or_any_expression} | datetime_expression comparison_operator {datetime_expression | all_or_any_expression} | entity_expression {= |&lt;&gt; } {entity_expression | all_or_any_expression} | arithmetic_expression comparison_operator {arithmetic_expression | all_or_any_expression} </para>
+            </listitem>
+            <listitem>
+              <para>comparison_operator ::== |&gt; |&gt;= |&lt; |&lt;= |&lt;&gt; </para>
+            </listitem>
+            <listitem>
+              <para>arithmetic_expression ::= simple_arithmetic_expression |(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>simple_arithmetic_expression ::= arithmetic_term | simple_arithmetic_expression {+ |- } arithmetic_term </para>
+            </listitem>
+            <listitem>
+              <para>arithmetic_term ::= arithmetic_factor | arithmetic_term {* |/ } arithmetic_factor </para>
+            </listitem>
+            <listitem>
+              <para>arithmetic_factor ::= [{+ |-}] arithmetic_primary </para>
+            </listitem>
+            <listitem>
+              <para>arithmetic_primary ::= state_field_path_expression | numeric_literal | (simple_arithmetic_expression) | input_parameter | functions_returning_numerics | aggregate_expression </para>
+            </listitem>
+            <listitem>
+              <para>string_expression ::= string_primary |(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>string_primary ::= state_field_path_expression | string_literal | input_parameter | functions_returning_strings | aggregate_expression </para>
+            </listitem>
+            <listitem>
+              <para>datetime_expression ::= datetime_primary |(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>datetime_primary ::= state_field_path_expression | input_parameter | functions_returning_datetime | aggregate_expression </para>
+            </listitem>
+            <listitem>
+              <para>boolean_expression ::= boolean_primary |(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>boolean_primary ::= state_field_path_expression | boolean_literal | input_parameter | </para>
+            </listitem>
+            <listitem>
+              <para>enum_expression ::= enum_primary |(subquery) </para>
+            </listitem>
+            <listitem>
+              <para>enum_primary ::= state_field_path_expression | enum_literal | input_parameter | </para>
+            </listitem>
+            <listitem>
+              <para>entity_expression ::= single_valued_association_path_expression | simple_entity_expression </para>
+            </listitem>
+            <listitem>
+              <para>simple_entity_expression ::= identification_variable | input_parameter </para>
+            </listitem>
+            <listitem>
+              <para>functions_returning_numerics ::= <literal>LENGTH</literal>(string_primary)| <literal>LOCATE</literal>(string_primary,string_primary [, simple_arithmetic_expression]) | <literal>ABS</literal>(simple_arithmetic_expression) | <literal>SQRT</literal>(simple_arithmetic_expression) | <literal>MOD</literal>(simple_arithmetic_expression, simple_arithmetic_expression) | <literal>SIZE</literal>(collection_valued_path_expression) </para>
+            </listitem>
+            <listitem>
+              <para>functions_returning_datetime ::= <literal>CURRENT_DATE</literal>| <literal>CURRENT_TIME</literal> | <literal>CURRENT_TIMESTAMP</literal> </para>
+            </listitem>
+            <listitem>
+              <para>functions_returning_strings ::= <literal>CONCAT</literal>(string_primary, string_primary) | <literal>SUBSTRING</literal>(string_primary, simple_arithmetic_expression,simple_arithmetic_expression)| <literal>TRIM</literal>([[trim_specification] [trim_character] <literal>FROM</literal>] string_primary) | <literal>LOWER</literal>(string_primary) | <literal>UPPER</literal>(string_primary) </para>
+            </listitem>
+            <listitem>
+              <para>trim_specification ::= <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+    </chapter>
+<!-- author: Marc Prud'hommeaux -->
+<!-- based on ejb3-overview-sqlquery.xml -->
+    <chapter id="jpa_overview_sqlquery">
+      <title>SQL Queries</title>
+      <indexterm zone="jpa_overview_sqlquery">
+        <primary>SQL queries</primary>
+        <seealso>Query</seealso>
+      </indexterm>
+      <indexterm>
+        <primary>Query</primary>
+        <secondary>SQL</secondary>
+        <see>SQL queries</see>
+      </indexterm>
+      <indexterm>
+        <primary>SQL</primary>
+        <secondary>queries</secondary>
+        <see>SQL queries</see>
+      </indexterm>
+      <indexterm>
+        <primary>Native</primary>
+        <secondary>queries</secondary>
+        <see>SQL queries</see>
+      </indexterm>
+      <para>
+	JPQL is a powerful query language, but there are times when it is 
+	not enough.  Maybe you're migrating a JDBC application to JPA
+	on a strict deadline, and you don't have time to translate your existing 
+	SQL selects to JPQL.  Or maybe a certain query requires
+	database-specific SQL your JPA implementation doesn't support.  
+	Or maybe your DBA has spent hours crafting the perfect select statement 
+	for a query in your application's critical path.  Whatever the reason, SQL 
+	queries can remain an essential part of an application.
+	</para>
+      <para>
+	You are probably familiar with executing SQL queries by obtaining a 
+	<classname>java.sql.Connection</classname>, using the JDBC APIs to create
+	a <classname>Statement</classname>, and executing that <classname>Statement
+	</classname> to obtain a <classname>ResultSet</classname>.  And of course, 
+	you are free to continue using this low-level approach to SQL execution in 
+	your JPA applications.  However, JPA also supports executing SQL queries 
+	through the <classname>javax.persistence.Query</classname>
+	interface introduced in <xref linkend="jpa_overview_query"/>.
+	Using a JPA SQL query, you can retrieve either persistent objects
+	or projections of column values.  The following sections detail each use.
+	</para>
+      <section id="jpa_overview_sqlquery_create">
+        <title>Creating SQL Queries</title>
+        <indexterm zone="jpa_overview_sqlquery_create">
+          <primary>SQL queries</primary>
+          <secondary>creating</secondary>
+        </indexterm>
+        <para>
+		The <classname>EntityManager</classname> has two factory methods
+		suitable for creating SQL queries:
+		</para>
+        <programlisting format="linespecific">
+public Query createNativeQuery (String sqlString, Class resultClass);
+public Query createNativeQuery (String sqlString, String resultSetMapping);
+</programlisting>
+        <para>
+		The first method is used to create a new <classname>Query</classname> 
+		instance that will return instances of the specified class.
+		</para>
+        <para>
+		The second method uses a <literal>SqlResultSetMapping</literal>
+		to determine the type of object or objects to return.
+		The example below shows these methods in action.
+		</para>
+        <example id="jpa_overview_sqlquery_createex">
+          <title>Creating a SQL Query</title>
+          <programlisting format="linespecific">
+EntityManager em = ...;
+Query query = em.createNativeQuery ("SELECT * FROM MAG", Magazine.class);
+processMagazines (query.getResultList ());
+</programlisting>
+        </example>
+        <note>
+          <para><indexterm><primary>SQL queries</primary><secondary>stored procedures</secondary></indexterm><indexterm><primary>stored procedures</primary><secondary>as queries</secondary><seealso>Query</seealso></indexterm>
+			In addition to SELECT statements, OpenJPA supports stored procedure
+			invocations as SQL queries.  OpenJPA will assume any SQL that does 
+			not begin with the <literal>SELECT</literal> keyword (ignoring
+			case) is a stored procedure call, and invoke it as such at the
+			JDBC level.
+			</para>
+        </note>
+      </section>
+      <section id="jpa_overview_sqlquery_obj">
+        <title>Retrieving Persistent Objects with SQL</title>
+        <indexterm zone="jpa_overview_sqlquery_obj">
+          <primary>SQL queries</primary>
+          <secondary>retrieving persistent objects</secondary>
+        </indexterm>
+        <indexterm zone="jpa_overview_sqlquery_obj">
+          <primary>persistent objects</primary>
+          <secondary>retrieving with SQL</secondary>
+          <seealso>SQL queries</seealso>
+        </indexterm>
+        <para>
+		When you give a SQL <classname>Query</classname> a candidate class, it 
+		will return persistent instances of that class.  At a minimum, your 
+		SQL must select the 
+		class' primary key columns, discriminator column (if mapped), and
+		version column (also if mapped).  The JPA runtime uses the values
+		of the primary key columns to construct each result object's identity,
+		and possibly to match it with a persistent object already in the 
+		<classname>EntityManager</classname>'s cache.  When an object is 
+		not already cached, the
+		implementation creates a new object to represent the current result
+		row.  It might use the discriminator column value to make sure it 
+		constructs an object of the correct subclass.  Finally, the query 
+		records available version column data for use in optimistic concurrency
+		checking, should you later change the result object and flush it back 
+		to the database.
+		</para>
+        <para>
+		Aside from the primary key, discriminator, and version columns, any 
+		columns you select are used to populate the persistent fields of each 
+		result object.  JPA implementations will compete on how effectively 
+		they map your selected data to your persistent instance fields.
+		</para>
+        <para>
+		Let's make the discussion above concrete with an example.  It uses
+		the following simple mapping between a class and the database:
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 320 x 149 (see README) -->
+            <imagedata fileref="img/sqlquery-model.png" width="213px"/>
+          </imageobject>
+        </mediaobject>
+        <example id="jpa_overview_sqlquery_objex">
+          <title>Retrieving Persistent Objects</title>
+          <programlisting format="linespecific">
+Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, "
+    + "VERS FROM MAG WHERE PRICE &gt; 5 AND PRICE &lt; 10", Magazine.class);
+List&lt;Magazine&gt; results = query.getResultList ();
+for (Magazine mag : results)
+    processMagazine (mag);
+</programlisting>
+        </example>
+        <para>
+		The query above works as advertised, but isn't very flexible.  Let's
+		update it to take in parameters for the minimum and maximum price, 
+		so we can reuse it to find magazines in any price range:
+		</para>
+        <example id="jpa_overview_sqlquery_obj_paramex">
+          <title>SQL Query Parameters</title>
+          <programlisting format="linespecific">
+Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, "
+    + "VERS FROM MAG WHERE PRICE &gt; ?1 AND PRICE &lt; ?2", Magazine.class);
+
+query.setParameter (1, 5d);
+query.setParameter (2, 10d);
+
+List&lt;Magazine&gt; results = query.getResultList ();
+for (Magazine mag : results)
+    processMagazine (mag);
+</programlisting>
+        </example>
+        <para><indexterm><primary>SQL queries</primary><secondary>parameters</secondary></indexterm><indexterm><primary>parameters</primary><secondary>in SQL queries</secondary><seealso>SQL queries</seealso></indexterm>
+		Like JDBC prepared statements, SQL queries represent parameters with
+		question marks, but are followed by an integer to represent its
+		index.
+		</para>
+      </section>
+<!--
+	<section id="jpa_overview_sqlquery_proj">
+		<title>SQL Projections</title>
+		<indexterm zone="jpa_overview_sqlquery_proj">
+			<primary>SQL queries</primary>
+			<secondary>projections</secondary>
+		</indexterm>
+		<indexterm zone="jpa_overview_sqlquery_proj">
+			<primary>projections</primary>
+			<secondary>of column data</secondary>
+			<seealso>SQL queries</seealso>
+		</indexterm>
+		<para>
+		SQL queries without a candidate class are treated as projections of
+		column data.  If you select a single column, the query returns
+		a list of <classname>Object</classname>s.  If you select multiple
+		columns, it returns a list of <classname>Object[]</classname>s.
+		In either case, each column value is obtained using the 
+		<methodname>java.sql.ResultSet.getObject</methodname> method.  The 
+		following example demonstrates a query for the values of the 
+		<literal>ISBN</literal> and <literal>VERS</literal> columns of all 
+		<literal>MAG</literal> table records, using the data model we 
+		defined in <xref linkend="jpa_overview_sqlquery_obj"/>.
+		</para>
+		<example id="jpa_overview_sqlquery_projex">
+			<title>Column Projection</title>
+<programlisting>
+Query query = em.newQuery ("javax.persistence.query.SQL", 
+    "SELECT ISBN, VERS FROM MAG");
+List results = query.getResultList ();
+for (Iterator itr = results.iterator (); itr.hasNext ();)
+{
+    Object[] data = (Object[]) results.next ();
+    processISBNAndVersion (data[0], data[1]);
+}
+</programlisting>
+			<para>
+			Notice that in the code above, we did not set a candidate class. 
+			Therefore, the query is treated as a projection.
+			</para>
+		</example>
+		<para>
+		<indexterm>
+			<primary>SQL queries</primary>
+			<secondary>result class</secondary>
+		</indexterm>
+		Our discussion of JPQL query result classes in 
+		<xref linkend="jpa_overview_query_resultcls"/> also 
+		applies to SQL queries.  As with JPQL queries, SQL queries can 
+		automatically pack their results into objects of a specified type.  
+		JPA uses the <methodname>java.sql.ResultSetMetaData.getColumnLabel
+		</methodname> method to match each column alias to the result class' 
+		public fields and JavaBean setter methods.  Here is a modification of 
+		our example above that packs the selected column values into JavaBean
+		instances.
+		</para>
+		<example id="jpa_overview_sqlquery_proj_labelex">
+			<title>Result Class</title>
+<programlisting>
+public class Identity
+{
+    private String id;
+    private int versionNumber;
+
+    public void setId (String id)
+    {
+        this.id = id;
+    }
+
+    public String getId ()
+    {
+        return id;
+    }
+
+    public void setVersionNumber (int versionNumber)
+    {
+        this.versionNumber = versionNumber;
+    }
+ 
+    public int getVersionNumber ()
+    {
+        return versionNumber;
+    }
+}
+
+Query query = em.createNativeQuery ("javax.persistence.query.SQL", 
+    "SELECT ISBN AS id, VERS AS versionNumber FROM MAG", Identity.class);
+List results = query.getResultList ();
+for (Iterator itr = results.iterator (); itr.hasNext ();)
+    processIdentity ((Identity) itr.next ());
+</programlisting>
+		</example>
+	</section>
+	<section id="jpa_overview_sqlquery_named">
+		<title>Named SQL Queries</title>
+		<indexterm zone="jpa_overview_sqlquery_named">
+			<primary>SQL queries</primary>
+			<secondary>named</secondary>
+			<see>named queries</see>
+		</indexterm>
+		<indexterm zone="jpa_overview_sqlquery_named">
+			<primary>named queries</primary>
+			<secondary>SQL</secondary>
+		</indexterm>
+		<para>
+		We discussed how to write named JPQL queries in
+		<xref linkend="jpa_overview_query_named"/>.  Named queries, however,
+		are not limited to JPQL.  By setting the <literal>query</literal>
+		element's <literal>language</literal> attribute to <literal>
+		javax.persistence.query.SQL</literal>, you can define a named SQL query.  A 
+		named SQL query within a <literal>class</literal> element queries for
+		instances of that class; a named SQL query outside of a <literal>class
+		</literal> element acts as a column data projection.  
+		</para>
+		<example id="jpa_overview_sqlquery_namedex">
+			<title>Named SQL Queries</title>
+<programlisting>
+<![CDATA[<?xml version="1.0"?>
+<jdoquery>
+    <query name="salesReport" language="javax.persistence.query.SQL">
+        SELECT TITLE, PRICE * COPIES FROM MAG
+    </query>
+    <package name="org.mag">
+        <class name="Magazine">
+            <query name="findByTitle" language="javax.persistence.query.SQL">
+                SELECT * FROM MAG WHERE TITLE = ?
+            </query>
+        </class>
+    </package>
+</jdoquery>]]>
+</programlisting>
+			<para>
+			The <literal>salesReport</literal> query above returns the title
+			and revenue generated for each <classname>Magazine</classname>.
+			Because it is a projection, it does not have a candidate class, and
+			so we specify it at the root level.
+			</para>
+			<para>
+			The <literal>findByTitle</literal> query returns the <classname>
+			Magazine</classname> with the title given on execution.  The code 
+			below executes both queries.
+			</para>
+<programlisting>
+EntityManager em = ...;
+Query query = em.newNamedQuery (null, "salesReport");
+List sales = query.getResultList ();
+for (Iterator itr = sales.iterator (); itr.hasNext ();)
+{
+    Object[] salesData = (Object[]) itr.next ();
+    processSalesData ((String) salesData[0], (Number) salesData[1]);
+}
+
+query = em.newNamedQuery (Magazine.class, "findByTitle");
+query.setUnique (true);
+Magazine jdj = (Magazine) query.execute ("JDJ"); 
+</programlisting>
+		</example>
+	</section>
+	<section id="jpa_overview_sqlquery_conclusion">
+		<title>Conclusion</title>
+		<para>
+		If you've used relational databases extensively, you might be tempted
+		to perform all your JPA queries with SQL.  Try to resist this 
+		temptation.  SQL queries tie your application to the particulars of
+		your current table model and database vendor.  If you stick with JPQL,
+		on the other hand, you can port your application to other schemas and 
+		database vendors without any changes to your code.  Additionally,
+		most JPA implementations already produce highly optimized SQL from
+		your JPQL filters, and many are able to cache JPQL query results
+		for added performance. 
+		</para>
+	</section>
+	-->
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_mapping">
+      <title>Mapping Metadata</title>
+      <indexterm zone="jpa_overview_mapping">
+        <primary>mapping metadata</primary>
+      </indexterm>
+      <indexterm>
+        <primary>entities</primary>
+        <secondary>mapping to database</secondary>
+        <see>mapping metadata</see>
+      </indexterm>
+      <indexterm>
+        <primary>metadata</primary>
+        <secondary>mapping metadata</secondary>
+        <see>mapping metadata</see>
+      </indexterm>
+      <indexterm>
+        <primary>ORM</primary>
+        <seealso>mapping metadata</seealso>
+      </indexterm>
+      <indexterm zone="jpa_overview_mapping">
+        <primary>EJB</primary>
+        <secondary>object-relational mapping</secondary>
+        <seealso>mapping metadata</seealso>
+      </indexterm>
+      <para><emphasis>Object-relational mapping</emphasis> is the process of mapping 
+	entities to relational database tables.  In EJB persistence, you perform 
+	object/relational mapping through <emphasis>mapping metadata</emphasis>.
+	Mapping metadata uses annotations to describe how to link your object model
+	to your relational model.  
+	</para>
+      <note>
+        <para>
+		OpenJPA offers tools to automate mapping and schema creation.  See
+		<xref linkend="ref_guide_mapping"/> in the Reference Guide.
+		</para>
+      </note>
+      <para>
+	Throughout this chapter, we will draw on the object model introduced in
+	<xref linkend="jpa_overview_meta"/>.  We present that model again
+	below.  As we discuss various aspects of mapping metadata, we will
+	zoom in on specific areas of the model and show how we map the object 
+	layer to the relational layer.
+	</para>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 553 x 580 (see README) -->
+          <imagedata fileref="img/ejb3-meta-model.png" width="369px"/>
+        </imageobject>
+      </mediaobject>
+      <para>
+	All mapping metadata is optional.  Where no explicit mapping metadata is
+	given, EJB 3 persistence uses the defaults defined by the specification.
+	As we present each mapping throughout this chapter, we also describe the 
+	defaults that apply when the mapping is absent.
+	</para>
+      <section id="jpa_overview_mapping_table">
+        <title>Table</title>
+        <indexterm zone="jpa_overview_mapping_table">
+          <primary>mapping metadata</primary>
+          <secondary>class</secondary>
+          <tertiary>table attribute</tertiary>
+        </indexterm>
+        <para>
+		The <classname>Table</classname> annotation specifies the table 
+		for an entity class.  If you omit the <classname>Table</classname>
+		annotation, base entity classes default to a table with their 
+		unqualified class name.  The default table of an entity subclass 
+		depends on the inheritance strategy, as you will see in 
+		<xref linkend="jpa_overview_mapping_inher"/>.
+		</para>
+        <para><classname>Table</classname>s have the following properties:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>String name</literal>: The name of the table.  
+				Defaults to the unqualified entity class name.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>String schema</literal>: The table's schema.  If you 
+				do not name a schema, EJB uses the default schema for the 
+				database connection.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>String catalog</literal>: The table's catalog.  If 
+				you do not name a catalog, EJB uses the default catalog for the 
+				database connection.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>UniqueConstraint[] uniqueConstraints</literal>: An
+				array of unique constraints to place on the table.  
+				We cover unique constraints below.  Defaults
+				to an empty array.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The equivalent XML element is <literal>table</literal>.  It has
+		the following attributes, which correspond to the annotation
+		properties above:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>name</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>schema</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>catalog</literal>
+            </para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The <literal>table</literal> element also accepts nested <literal>
+		unique-constraint</literal> elements representing unique constraints.
+		We will detail unique constraints shortly.
+		</para>
+        <para>
+		Sometimes, some of the fields in a class are mapped to secondary 
+		tables.  In that case, use the class' <classname>Table</classname> 
+		annotation to name what you consider the class' primary table.  Later, 
+		we will see how to map certain fields to other tables.
+		</para>
+        <para>
+		The example below maps classes to tables according to the following
+		diagram.  The <literal>CONTRACT</literal>, <literal>SUB</literal>, and 
+		<literal>LINE_ITEM</literal> tables are in the <literal>CNTRCT</literal>
+		schema; all other tables are in the default schema.
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 513 x 410 (see README) -->
+            <imagedata fileref="img/mapping-tables.png" width="341px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		Note that the diagram does not include our model's <classname>Document
+		</classname> and <classname>Address</classname> classes. Mapped
+		superclasses and embeddable classes are never mapped to tables. 
+		</para>
+        <example id="jpa_overview_mapping_classex">
+          <title>Mapping Classes</title>
+          <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+public class Magazine
+{
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART")
+public class Article
+{
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+public class Contract
+    extends Document
+{
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+public class Subscription
+{
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+
+@Entity(name="Trial")
+public class TrialSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+          <para>The same mapping information expressed in XML:</para>
+          <programlisting format="linespecific">
+&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
+    version="1.0"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        ...
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;table name="MAG"/&gt;
+        &lt;id-class="org.mag.Magazine.MagazineId"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        &lt;table name="ART"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        &lt;table name="COMP"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        &lt;table name="AUTH"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Contract"&gt;
+        &lt;table schema="CNTRCT"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Subscription"&gt;
+        &lt;table name="SUB" schema="CNTRCT"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+        &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;embeddable class="org.mag.pub.Address"&gt;
+        ...
+    &lt;/embeddable&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="jpa_overview_mapping_unq">
+        <title>Unique Constraints</title>
+        <indexterm zone="jpa_overview_mapping_unq">
+          <primary>mapping metadata</primary>
+          <secondary>unique constraints</secondary>
+          <seealso>unique constraints</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_unq">
+          <primary>unique constraints</primary>
+        </indexterm>
+        <para>
+		Unique constraints ensure that the data in a column or combination of
+		columns is unique for each row.  A table's primary key, for example,
+		functions as an implicit unique constraint.  In EJB persistence, you 
+		represent other unique constraints with an array of <classname>
+		UniqueConstraint</classname> annotations within the table annotation. 
+		The unique constraints you define are used during table creation to
+		generate the proper database constraints, and may also be used at 
+		runtime to order <literal>INSERT</literal>, <literal>UPDATE</literal>, 
+		and <literal>DELETE</literal> statements.  For example, suppose there 
+		is a unique constraint on the columns of field <literal>F</literal>.  
+		In the same transaction, you remove an object <literal>A</literal> 
+		and persist a new object <literal>B</literal>, both with the same 
+		<literal>F</literal> value.  The EJB persistence runtime must ensure 
+		that the SQL deleting <literal>A</literal> is sent to the database 
+		before the SQL inserting <literal>B</literal> to avoid a unique 
+		constraint violation.  
+		</para>
+        <para><classname>UniqueConstraint</classname> has a single property:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>String[] columnNames</literal>: The names of the
+				columns the constraint spans.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		In XML, unique constraints are represented by nesting 
+		<literal>unique-constraint</literal> elements within the <literal>
+		table</literal> element.  Each <literal>unique-constraint</literal> 
+		element in turn nests <literal>column-name</literal> text elements 
+		to enumerate the contraint's columns.
+		</para>
+        <example id="jpa_overview_mapping_unq_attrex">
+          <title>Defining a Unique Constraint</title>
+          <para>
+			The following defines a unique constraint on the <literal>
+			TITLE</literal> column of the <literal>ART</literal> table:
+			</para>
+          <programlisting format="linespecific">
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+public class Article
+{
+    ...
+}
+</programlisting>
+          <para>The same metadata expressed in XML form:</para>
+          <programlisting format="linespecific">
+&lt;entity class="org.mag.Article"&gt;
+    &lt;table name="ART"&gt;
+        &lt;unique-constraint&gt;
+            &lt;column-name&gt;TITLE&lt;/column-name&gt;
+        &lt;/unique-constraint&gt;
+    &lt;/table&gt;
+    ...
+&lt;/entity&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="jpa_overview_mapping_column">
+        <title>Column</title>
+        <indexterm zone="jpa_overview_mapping_column">
+          <primary>mapping metadata</primary>
+          <secondary>Column</secondary>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_column">
+          <primary>Column</primary>
+          <secondary>in mapping metadata</secondary>
+          <seealso>mapping metadata</seealso>
+        </indexterm>
+        <para>
+		In the previous section, we saw that a <classname>UniqueConstraint
+		</classname> uses an array of column names.  Field mappings, 
+		however, use full-fledged <classname>Column</classname> annotations.	
+		Column annotations have the following properties:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>name property</tertiary></indexterm><literal>String name</literal>: The column name.  Defaults to 
+				the field name.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>columnDefinition property</tertiary></indexterm><literal>String columnDefinition</literal>: The 
+				database-specific column type name.  This property is only used
+				by vendors that support creating tables from your mapping 
+				metadata.  During table creation, the vendor will use the value 
+				of the <literal>columnDefinition</literal> as the declared 
+				column type.  If no <literal>columnDefinition</literal> is 
+				given, the vendor will choose an appropriate default based on 
+				the field type combined with the column's length, precision,
+				and scale. 
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>length property</tertiary></indexterm><literal>int length</literal>: The column length.  This 
+				property is typically only used during table creation, though 
+				some vendors might use it to validate data before flushing.  
+				<literal>CHAR</literal> and <literal>VARCHAR
+				</literal> columns typically default to a length of 255; other 
+				column types use the database default.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>precision property</tertiary></indexterm><literal>int precision</literal>: The precision of a numeric
+				column.  This property is often used in 
+				conjunction with <literal>scale</literal> to form the 
+				proper column type name during table creation.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>scale property</tertiary></indexterm><literal>int scale</literal>: The number of decimal digits a 
+				numeric column can hold.  This property is often used in 
+				conjunction with <literal>precision</literal> to form the 
+				proper column type name during table creation.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>nullable property</tertiary></indexterm><literal>boolean nullable</literal>: Whether the column can 
+				store null values.  Vendors may use this property both for table
+				creation and at runtime; however, it is never required.
+				Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>insertable property</tertiary></indexterm><literal>boolean insertable</literal>: By setting this property
+				to <literal>false</literal>, you can omit the column from
+				SQL <literal>INSERT</literal> statements.
+				Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>updatable property</tertiary></indexterm><literal>boolean updatable</literal>: By setting this property
+				to <literal>false</literal>, you can omit the column from
+				SQL <literal>UPDATE</literal> statements.
+				Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>table property</tertiary></indexterm><literal>String table</literal>: Sometimes you will
+				need to map fields to tables other than the primary table.
+				This property allows you specify that the column resides in a
+				secondary table.  We will see how to map fields to secondary	
+				tables later in the chapter.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The equivalent XML element is <literal>column</literal>.  This
+		element has attributes that are exactly equivalent to the <classname>
+		Column</classname> annotation's properties described above:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>name</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>column-definition</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>length</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>precision</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>scale</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>insertable</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>updatable</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>table</literal>
+            </para>
+          </listitem>
+        </itemizedlist>
+      </section>
+      <section id="jpa_overview_mapping_id">
+        <title>Identity Mapping</title>
+        <indexterm zone="jpa_overview_mapping_id">
+          <primary>Id</primary>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_id">
+          <primary>mapping metadata</primary>
+          <secondary>identity</secondary>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_id">
+          <primary>identity</primary>
+          <secondary>mapping</secondary>
+        </indexterm>
+        <para>
+		With our new knowledge of columns, we can map the identity fields
+		of our entities.  The diagram below now includes primary key columns 
+		for our model's tables.  The primary key column for 
+		<classname>Author</classname> uses nonstandard type <literal>
+		INTEGER64</literal>, and the <literal>Magazine.isbn</literal> field is 
+		mapped to a <literal>VARCHAR(9)</literal> column instead of a 
+		<literal>VARCHAR(255)</literal> column, which is the default for string
+		fields.  We do not need to point out either one of these oddities to 
+		the EJB persistence implementation for runtime use.  If, however, we 
+		want to use the EJB persistence implementation to create our tables for
+		us, it needs to know about any desired non-default column types.  
+		Therefore, the example following the diagram includes this data in its 
+		encoding of our mappings.
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 513 x 410 (see README) -->
+            <imagedata fileref="img/ejb3-mapping-identity.png" width="341px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		Note that many of our identity fields do not need to specify column
+		information, because they use the default column name and type.
+		</para>
+        <example id="jpa_overview_mapping_identityex">
+          <title>Identity Mapping</title>
+          <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+public class Article
+{
+    @Id private long id;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Column(name="AID", columnDefinition="INTEGER64")
+    @Id private long id;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+public class Contract
+    extends Document
+{
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+public class Subscription
+{
+    @Id private long id;
+
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+
+@Entity(name="Trial")
+public class TrialSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+          <para>
+			The same metadata for <literal>Magazine</literal> and
+			<literal>Company</literal> expressed in XML form:
+			</para>
+          <programlisting format="linespecific">
+&lt;entity class="org.mag.Magazine"&gt;
+    &lt;id-class class="org.mag.Magazine.Magazine.MagazineId"/&gt;
+    &lt;table name="MAG"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="isbn"&gt;
+            &lt;column length="9"/&gt;
+        &lt;/id&gt;
+        &lt;id name="title"/&gt;
+	    ...	
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.pub.Company"&gt;
+    &lt;table name="COMP"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"&gt;
+            &lt;column name="CID"/&gt;
+        &lt;/id&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="jpa_overview_mapping_sequence">
+        <title>Generators</title>
+        <indexterm zone="jpa_overview_mapping_sequence">
+          <primary>generators</primary>
+          <secondary>mapping metadata</secondary>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_sequence">
+          <primary>mapping metadata</primary>
+          <secondary>generators</secondary>
+          <seealso>TableGenerator</seealso>
+          <seealso>SequenceGenerator</seealso>
+        </indexterm>
+        <para>
+		One aspect of identity mapping not covered in the previous section is
+		EJB's ability to automatically assign a value to your numeric identity
+		fields using <emphasis>generators</emphasis>.  We discussed the 
+		available generator types in <xref linkend="jpa_overview_meta_id"/>.  
+		Now we show you how to define named generators.
+		</para>
+        <section id="jpa_overview_mapping_sequence_seqgen">
+          <title>Sequence Generator</title>
+          <indexterm zone="jpa_overview_mapping_sequence_seqgen">
+            <primary>generators</primary>
+            <secondary>SequenceGenerator</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_sequence_seqgen">
+            <primary>SequenceGenerator</primary>
+          </indexterm>
+          <para>
+			Most databases allow you to create native sequences.  These are
+			database structures that generate increasing
+			numeric values.  The <classname>SequenceGenerator</classname> 
+			annotation represents a named database sequence.  You can place
+			the annotation on any package, entity class, persistent field
+			declaration (if your entity uses field access), or getter method for
+			a persistent property (if your entity uses property access).
+			<classname>SequenceGenerator</classname> has the following 
+			properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><indexterm><primary>SequenceGenerator</primary><secondary>name property</secondary></indexterm><literal>String name</literal>: The generator name.  This
+					property is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>SequenceGenerator</primary><secondary>sequenceName property</secondary></indexterm><literal>String sequenceName</literal>: The name of the 
+					database sequence.  If you do not specify the database
+					sequence, your vendor will choose an appropriate default.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>SequenceGenerator</primary><secondary>initialValue property</secondary></indexterm><literal>int initialValue</literal>: The initial sequence
+					value. 
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>SequenceGenerator</primary><secondary>allocationSize property</secondary></indexterm><literal>int allocationSize</literal>: Some databases can
+					pre-allocate groups of sequence values.  This allows the
+					database to service sequence requests from cache, rather
+					than physically incrementing the sequence with every 
+					request.  This allocation size defaults to 50.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				OpenJPA allows you to use describe one of OpenJPA's built-in generator
+				implementations in the <literal>sequenceName</literal> property.
+				You can also set the <literal>sequenceName</literal> to 
+				<literal>system</literal> to use the system sequence defined by
+				the <link linkend="openjpa.Sequence"><literal>openjpa.Sequence
+				</literal></link> configuration property.  See the Reference 
+				Guide's <xref linkend="ref_guide_sequence"/> for details.
+				</para>
+          </note>
+          <para>
+			The XML element for a sequence generator
+			is <literal>sequence-generator</literal>. Its attributes mirror
+			the above annotation's properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>sequence-name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>initial-value</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>allocation-size</literal>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			To use a sequence generator, set your <classname>GeneratedValue
+			</classname> annotation's <literal>strategy</literal>
+			property to <literal>GenerationType.SEQUENCE</literal>, and its
+			<literal>generator</literal> property to the sequence generator's
+			declared name.  Or equivalently, set your <literal>generated-value
+			</literal> XML element's <literal>strategy</literal> attribute to
+			<literal>SEQUENCE</literal> and its <literal>generator</literal>
+			attribute to the generator name.
+			</para>
+        </section>
+        <section id="jpa_overview_mapping_sequence_tablegen">
+          <title>TableGenerator</title>
+          <indexterm zone="jpa_overview_mapping_sequence_tablegen">
+            <primary>generators</primary>
+            <secondary>TableGenerator</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_sequence_tablegen">
+            <primary>TableGenerator</primary>
+          </indexterm>
+          <para>
+			A <classname>TableGenerator</classname> refers to a database table
+			used to store increasing sequence values for one or more entities.
+			As with <classname>SequenceGenerator</classname>, you can place
+			the <classname>TableGenerator</classname> annotation on any 
+			package, entity class, persistent field declaration (if your 
+			entity uses field access), or getter method for a persistent 
+			property (if your entity uses property access).
+			<classname>TableGenerator</classname> has the following 
+			properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>name property</secondary></indexterm><literal>String name</literal>: The generator name.  This
+					property is required.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>table property</secondary></indexterm><literal>String table</literal>: The name of the
+					generator table.  If left unspecified, your vendor will 
+					choose a default table.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>schema property</secondary></indexterm><literal>String schema</literal>: The named table's 
+					schema.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>catalog property</secondary></indexterm><literal>String catalog</literal>: The named table's 
+					catalog.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>pkColumnName property</secondary></indexterm><literal>String pkColumnName</literal>: The name of the
+					primary key column in the generator table.  If 
+					unspecified, your implementation will choose a 
+					default.	
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>valueColumnName property</secondary></indexterm><literal>String valueColumnName</literal>: The name of 
+					the column that holds the sequence value.  
+					If unspecified, your implementation will
+					choose a default.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>pkColumnValue property</secondary></indexterm><literal>String pkColumnValue</literal>: The primary key
+					column value of the row in the generator table holding
+					this sequence value.  You can use the same generator table
+					for multiple logical sequences by supplying different 
+					<literal>pkColumnValue</literal>s.  If you do not specify
+					a value, the implementation will supply a default.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>initialValue property</secondary></indexterm><literal>int initialValue</literal>: The value of the 
+					generator's first issued number.
+					</para>
+            </listitem>
+            <listitem>
+              <para><indexterm><primary>TableGenerator</primary><secondary>allocationSize property</secondary></indexterm><literal>int allocationSize</literal>: The number of values
+					to allocate in memory for each trip to the database.  
+					Allocating values in memory allows the EJB persistence 
+					runtime to avoid accessing the database for every sequence 
+					request.  This number also specifies the amount 
+					that the sequence value is incremented each time the 
+					generator table is updated.  Defaults to 50.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The XML equivalent is the <literal>table-generator</literal> 
+			element.  This element's attributes correspond exactly to the 
+			above annotation's properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>table</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>schema</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>catalog</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>pk-column-name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>value-column-name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>pk-column-value</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>initial-value</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>allocation-size</literal>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			To use a table generator, set your <classname>GeneratedValue
+			</classname> annotation's <literal>strategy</literal>
+			property to <literal>GenerationType.TABLE</literal>, and its
+			<literal>generator</literal> property to the table generator's
+			declared name.  Or equivalently, set your <literal>generated-value
+			</literal> XML element's <literal>strategy</literal> attribute to
+			<literal>TABLE</literal> and its <literal>generator</literal>
+			attribute to the generator name.
+			</para>
+        </section>
+        <section id="jpa_overview_mapping_sequence_genex">
+          <title>Example</title>
+          <para>
+			Let's take advantage of generators in our entity model.  Here are
+			our updated mappings.
+			</para>
+          <example id="jpa_overview_mapping_sequenceex">
+            <title>Generator Mapping</title>
+            <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+@SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ")
+public class Article
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") 
+    private long id;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen")
+    @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK",
+        valueColumnName="AID")
+    @Column(name="AID", columnDefinition="INTEGER64")
+    private long id;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id
+    @GeneratedValue(generate=GenerationType.IDENTITY)
+    private long id;
+ 
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+public class Contract
+    extends Document
+{
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+public class Subscription
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+
+@Entity(name="Trial")
+public class TrialSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+            <para>
+			The same metadata for <literal>Article</literal> and
+			<literal>Author</literal> expressed in XML form:
+			</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.Article"&gt;
+    &lt;table name="ART"&gt;
+        &lt;unique-constraint&gt;
+            &lt;column-name&gt;TITLE&lt;/column-name&gt;
+        &lt;/unique-constraint&gt;
+    &lt;/table&gt;
+    &lt;sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"&gt;
+            &lt;generated-value strategy="SEQUENCE" generator="ArticleSeq"/&gt;
+        &lt;/id&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.pub.Author"&gt;
+    &lt;table name="AUTH"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"&gt;
+            &lt;column name="AID" column-definition="INTEGER64"/&gt;
+            &lt;generated-value strategy="TABLE" generator="AuthorGen"/&gt;
+            &lt;table-generator name="AuthorGen" table="AUTH_GEN" 
+                pk-column-name="PK" value-column-name="AID"/&gt;
+        &lt;/id&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_overview_mapping_inher">
+        <title>Inheritance</title>
+        <indexterm zone="jpa_overview_mapping_inher">
+          <primary>mapping metadata</primary>
+          <secondary>inheritance</secondary>
+          <seealso>inheritance</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_inher">
+          <primary>inheritance</primary>
+          <secondary>mapping</secondary>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_inher">
+          <primary>entities</primary>
+          <secondary>inheritance</secondary>
+          <seealso>inheritance</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>impedance mismatch</primary>
+        </indexterm>
+        <para>
+		In the 1990's programmers coined the term <emphasis>impedance mismatch
+		</emphasis> to describe the difficulties in bridging the object and
+		relational worlds.  Perhaps no feature of object modeling highlights 
+		the impedance mismatch better than inheritance.  There is no natural,
+		efficient way to represent an inheritance relationship in a relational
+		database.
+		</para>
+        <para><indexterm><primary>mapping metadata</primary><secondary>inheritance</secondary><tertiary>strategy attribute</tertiary></indexterm>
+		Luckily, EJB persistence gives you a choice of inheritance strategies,
+		making the best of a bad situation.  The base entity class 
+		defines the inheritance strategy for the hierarchy with the 
+		<classname>Inheritance</classname> annotation.  <classname>Inheritance
+		</classname> has the following properties:  
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>InheritanceType strategy</literal>: Enum value
+				declaring the inheritance strategy for the hierarchy.
+				Defaults to <literal>InheritanceType.SINGLE_TABLE</literal>.
+				We detail each of the available strategies below.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The corresponding XML element is <literal>inheritance</literal>, which 
+		has a single attribute:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>strategy</literal>: One of 
+				<literal>SINGLE_TABLE</literal>, <literal>JOINED</literal>,
+				or <literal>TABLE_PER_CLASS</literal>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The following sections describe EJB's standard inheritance
+		strategies.
+		</para>
+        <note>
+          <para>
+			OpenJPA allows you to vary your inheritance strategy for each
+			class, rather than forcing a single strategy per inheritance
+			hierarchy.  See <xref linkend="ref_guide_mapping_ejb"/> in the
+			Reference Guide for details.
+			</para>
+        </note>
+        <section id="jpa_overview_mapping_inher_single">
+          <title>Single Table</title>
+          <indexterm zone="jpa_overview_mapping_inher_single">
+            <primary>mapping metadata</primary>
+            <secondary>inheritance</secondary>
+            <tertiary>SINGLE_TABLE strategy</tertiary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_inher_single">
+            <primary>inheritance</primary>
+            <secondary>SINGLE_TABLE strategy</secondary>
+          </indexterm>
+          <para>
+			The <literal>InheritanceType.SINGLE_TABLE</literal> strategy
+			maps all classes in the hierarchy to the base class' table.
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 266 x 203 (see README) -->
+              <imagedata fileref="img/inher-superclass-table.png" width="177px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			In our model, <classname>Subscription</classname> is mapped to the
+			<literal>CNTRCT.SUB</literal> table.  <classname>
+			LifetimeSubscription</classname>, which extends <classname>
+			Subscription</classname>, adds its field data to this table as well.
+			</para>
+          <example id="jpa_overview_mapping_inher_singleex">
+            <title>Single Table Mapping</title>
+            <programlisting format="linespecific">
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
+public class Subscription
+{
+    ...
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+            <para>The same metadata expressed in XML form:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.subcribe.Subscription"&gt;
+    &lt;table name="SUB" schema="CNTRCT"/&gt;
+    &lt;inheritance strategy="SINGLE_TABLE"/&gt;
+    ...
+&lt;/entity&gt;
+&lt;entity class="org.mag.subscribe.LifetimeSubscription"&gt;
+    ...
+&lt;/entity&gt;
+</programlisting>
+          </example>
+          <para>
+			Single table inheritance is the default strategy.  Thus, we could
+			omit the <literal>@Inheritance</literal> annotation in the 
+			example above and get the same result.
+			</para>
+          <note>
+            <para><indexterm><primary>inheritance</primary><secondary>flat</secondary></indexterm><indexterm><primary>flat</primary><seealso>inheritance</seealso></indexterm>
+				Mapping subclass state to the superclass table is often called
+				<emphasis>flat</emphasis> inheritance mapping.
+				</para>
+          </note>
+          <section id="jpa_overview_mapping_inher_single_adv">
+            <title>Advantages</title>
+            <indexterm zone="jpa_overview_mapping_inher_single_adv">
+              <primary>inheritance</primary>
+              <secondary>SINGLE_TABLE strategy</secondary>
+              <tertiary>advantages</tertiary>
+            </indexterm>
+            <para>
+				Single table inheritance mapping is the 
+				fastest of all inheritance models, since it never requires a 
+				join to retrieve a persistent instance from the database.
+				Similarly, persisting or updating a persistent instance 
+				requires only a single <literal>INSERT</literal> or 
+				<literal>UPDATE</literal> statement.  Finally, relations to 
+				any class within a single table inheritance hierarchy are just 
+				as efficient as relations to a base class.
+				</para>
+          </section>
+          <section id="jpa_overview_mapping_inher_single_disadv">
+            <title>Disadvantages</title>
+            <indexterm zone="jpa_overview_mapping_inher_single_disadv">
+              <primary>inheritance</primary>
+              <secondary>SINGLE_TABLE strategy</secondary>
+              <tertiary>disadvantages</tertiary>
+            </indexterm>
+            <para>
+				The larger the inheritance model gets, the "wider"
+				the mapped table gets, in that for every field 
+				in the entire inheritance hierarchy, a column must
+				exist in the mapped table. This may have
+				undesirable consequence on the database size,
+				since a wide or deep inheritance hierarchy will result in
+				tables with many mostly-empty columns.
+				</para>
+          </section>
+        </section>
+        <section id="jpa_overview_mapping_inher_joined">
+          <title>Joined</title>
+          <indexterm zone="jpa_overview_mapping_inher_joined">
+            <primary>mapping metadata</primary>
+            <secondary>inheritance</secondary>
+            <tertiary>JOINED strategy</tertiary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_inher_joined">
+            <primary>inheritance</primary>
+            <secondary>JOINED strategy</secondary>
+          </indexterm>
+          <para>
+			The <literal>InheritanceType.JOINED</literal> strategy uses a 
+			different table for each class in the hierarchy.  Each table 
+			only includes state declared in its class.  Thus to load a subclass
+			instance, the EJB persistence implementation must read from the
+			subclass table as well as the table of each ancestor class, up to
+			the base entity class.
+			</para>
+          <note>
+            <para><indexterm><primary>inheritance</primary><secondary>vertical</secondary></indexterm><indexterm><primary>vertical</primary><seealso>inheritance</seealso></indexterm>
+				Using joined subclass tables is also called
+				<emphasis>vertical</emphasis> inheritance mapping.
+				</para>
+          </note>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 256 x 229 (see README) -->
+              <imagedata fileref="img/ejb3-inher-joined.png" width="171px"/>
+            </imageobject>
+          </mediaobject>
+          <para><classname>PrimaryKeyJoinColumn</classname> annotations 
+			tell the EJB implementation how to join each subclass table 
+			record to the corresponding record in its direct superclass table.
+			In our model, the <literal>LINE_ITEM.ID</literal> column joins to
+			the <literal>CONTRACT.ID</literal> column.  The 
+			<classname>PrimaryKeyJoinColumn</classname> annotation has 
+			the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the subclass 
+					table column.  When there is a single identity field, 
+					defaults to that field's column name.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String referencedColumnName</literal>: The name of
+					the superclass table column this subclass table column joins
+					to.  When there is a single identity field, defaults to
+					that field's column name.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String columnDefinition</literal>: This property 
+					has the same meaning as the <literal>columnDefinition
+					</literal> property on the <classname>Column</classname> 
+					annotation, described in 
+					<xref linkend="jpa_overview_mapping_column"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The XML equivalent is the <literal>primary-key-join-column
+			</literal> element.  Its attributes
+			mirror the annotation properties described above:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>referenced-column-name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>column-definition</literal>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The example below shows how we use <literal>InheritanceTable.JOINED
+			</literal> and a primary key join column to map our sample model 
+			according to the diagram above.  Note that a primary key join column
+			is not strictly needed, because there is only one identity column, 
+			and the subclass table column has the same name as the superclass 
+			table column.  In this situation, the defaults suffice.  However, 
+			we include the primary key join column for illustrative 
+			purposes. 
+			</para>
+          <example id="jpa_overview_mapping_inher_joinedex">
+            <title>Joined Subclass Tables</title>
+            <programlisting format="linespecific">
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+public class Contract
+    extends Document
+{
+    ...
+}
+
+public class Subscription
+{
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID")
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+</programlisting>
+            <para>The same metadata expressed in XML form:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.subcribe.Contract"&gt;
+    &lt;table schema="CNTRCT"/&gt;
+    &lt;inheritance strategy="JOINED"/&gt;
+    ...
+&lt;/entity&gt;
+&lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+    &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+    &lt;primary-key-join-column name="ID" referenced-column-name="PK"/&gt;
+    ...
+&lt;/entity&gt;
+</programlisting>
+          </example>
+          <para>
+			When there are multiple identity columns, you must define multiple
+			<classname>PrimaryKeyJoinColumn</classname>s using the aptly-named
+			<classname>PrimaryKeyJoinColumns</classname> annotation.  This 
+			annotation's value is an array of <classname>
+			PrimaryKeyJoinColumn</classname>s.  We could rewrite 
+			<classname>LineItem</classname>'s mapping as:
+			</para>
+          <programlisting format="linespecific">
+@Entity
+@Table(name="LINE_ITEM", schema="CNTRCT")
+@PrimaryKeyJoinColumns({
+    @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID")
+})
+public static class LineItem
+    extends Contract
+{
+    ...
+}
+</programlisting>
+          <para>
+			In XML, simply list as many <literal>
+			primary-key-join-column</literal> elements as necessary.
+			</para>
+          <section id="jpa_overview_mapping_inher_joined_adv">
+            <title>Advantages</title>
+            <indexterm zone="jpa_overview_mapping_inher_joined_adv">
+              <primary>inheritance</primary>
+              <secondary>JOINED strategy</secondary>
+              <tertiary>advantages</tertiary>
+            </indexterm>
+            <para>
+				The joined strategy has the following advantages:
+				</para>
+            <orderedlist>
+              <listitem>
+                <para><indexterm><primary>normalized</primary></indexterm>
+						Using joined subclass tables results in the most 
+						<emphasis>normalized</emphasis> database schema, 
+						meaning the schema with the least spurious or redundant 
+						data.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						As more subclasses are added to the data model over 
+						time, the only schema modification that needs to be 
+						made is the addition of corresponding subclass tables 
+						in the database (rather than having to change the 
+						structure of existing tables).
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						Relations to a base class using this strategy
+						can be loaded through standard joins and can use 
+						standard foreign keys, as opposed to the machinations 
+						required to load polymorphic relations to 
+						table-per-class base types, described below.
+						</para>
+              </listitem>
+            </orderedlist>
+          </section>
+          <section id="jpa_overview_mapping_inher_joined_disadv">
+            <title>Disadvantages</title>
+            <indexterm zone="jpa_overview_mapping_inher_joined_disadv">
+              <primary>inheritance</primary>
+              <secondary>JOINED strategy</secondary>
+              <tertiary>disadvantages</tertiary>
+            </indexterm>
+            <para>
+				Aside from certain uses of the table-per-class strategy 
+				described below, the joined strategy is often the slowest of
+				the inheritance models. Retrieving any subclass requires 
+				one or more database joins, and storing subclasses requires 
+				multiple <literal>INSERT</literal> or <literal>UPDATE</literal> 
+				statements. This is only the case when persistence operations 
+				are performed on subclasses; if most operations are performed 
+				on the least-derived persistent superclass, then this mapping 
+				is very fast.
+				</para>
+            <note>
+              <para>
+					When executing a select against a hierarchy that uses
+					joined subclass table inheritance, you must consider how to
+					load subclass state.  
+					<xref linkend="ref_guide_perfpack_eager"/> in the Reference
+					Guide describes OpenJPA's options for efficient data loading.
+					</para>
+            </note>
+          </section>
+        </section>
+        <section id="jpa_overview_mapping_inher_tpc">
+          <title>Table Per Class</title>
+          <indexterm zone="jpa_overview_mapping_inher_tpc">
+            <primary>mapping metadata</primary>
+            <secondary>inheritance</secondary>
+            <tertiary>TABLE_PER_CLASS strategy</tertiary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_inher_tpc">
+            <primary>inheritance</primary>
+            <secondary>TABLE_PER_CLASS strategy</secondary>
+          </indexterm>
+          <para>
+			Like the <literal>JOINED</literal> strategy, the <literal>
+			InheritanceType.TABLE_PER_CLASS</literal> strategy uses a different
+			table for each class in the hierarchy.  Unlike the <literal>JOINED
+			</literal> strategy, however, each table includes all state for an
+			instance of the corresponding class.  Thus to load a subclass
+			instance, the EJB persistence implementation must only read from the
+			subclass table; it does not need to join to superclass tables.
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 283 x 247 (see README) -->
+              <imagedata fileref="img/inher-tpc.png" width="189px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			Suppose that our sample model's <classname>Magazine</classname> 
+			class has a subclass <classname>Tabloid</classname>.  The classes
+			are mapped using the table-per-class strategy, as in the diagram 
+			above.  In a table-per-class mapping, <classname>
+			Magazine</classname>'s table <literal>MAG</literal> contains all 
+			state declared in the base <classname>Magazine</classname> class.  
+			<classname>Tabloid</classname> maps to a separate table, <literal>
+			TABLOID</literal>.  This table contains not only the state declared
+			in the <classname>Tabloid</classname> subclass, but all the base 
+			class state from <classname>Magazine</classname> as well.  Thus the
+			<literal>TABLOID</literal> table would contain columns for 
+			<literal>isbn</literal>, <literal>title</literal>, and other
+			<classname>Magazine</classname> fields.  These columns would default
+			to the names used in <classname>Magazine</classname>'s mapping 
+			metadata.  <xref linkend="jpa_overview_mapping_embed"/> will show 
+			you how to use <literal>AttributeOverride</literal>s and
+			<literal>AssociationOverride</literal>s to override superclass 
+			field mappings.
+			</para>
+          <example id="jpa_overview_mapping_inher_tpcex">
+            <title>Table Per Class Mapping</title>
+            <programlisting format="linespecific">
+@Entity
+@Table(name="MAG")
+@Inheritance(strategy=InheritanceType.TABLE_PER_CLASS)
+public class Magazine
+{
+    ...
+}
+
+@Entity
+@Table(name="TABLOID")
+public class Tabloid
+    extends Magazine
+{
+    ...
+}
+</programlisting>
+            <para>And the same classes in XML:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.Magazine"&gt;
+    &lt;table name="MAG"/&gt;
+    &lt;inheritance strategy="TABLE_PER_CLASS"/&gt;
+    ...
+&lt;/entity&gt;
+&lt;entity class="org.mag.Tabloid"&gt;
+    &lt;table name="TABLOID"/&gt;
+    ...
+&lt;/entity&gt;
+</programlisting>
+          </example>
+          <section id="jpa_overview_mapping_inher_tpc_adv">
+            <title>Advantages</title>
+            <indexterm zone="jpa_overview_mapping_inher_tpc_adv">
+              <primary>inheritance</primary>
+              <secondary>TABLE_PER_CLASS strategy</secondary>
+              <tertiary>advantages</tertiary>
+            </indexterm>
+            <para>
+				The table-per-class strategy is very efficient when operating
+				on instances of a known class.  Under these conditions, the
+				strategy never requires joining to superclass or subclass 
+				tables.  Reads, joins, inserts, updates, and deletes are all
+				efficient in the absence of polymorphic behavior.
+				Also, as in the joined strategy, adding additional classes
+				to the hierarchy does not require modifying existing class 
+				tables.
+				</para>
+          </section>
+          <section id="jpa_overview_mapping_inher_tpc_disadv">
+            <title>Disadvantages</title>
+            <indexterm zone="jpa_overview_mapping_inher_tpc_disadv">
+              <primary>inheritance</primary>
+              <secondary>TABLE_PER_CLASS strategy</secondary>
+              <tertiary>disadvantages</tertiary>
+            </indexterm>
+            <para>
+				Polymorphic relations to non-leaf classes in a table-per-class
+				hierarchy have many limitations.  When the concrete subclass
+				is not known, the related object could be in any of the subclass
+				tables, making joins through the relation impossible.  This
+				ambiguity also affects identity lookups and queries; these 
+				operations require multiple SQL <literal>SELECT</literal>s (one
+				for each possible subclass), or a complex 
+				<literal>UNION</literal>.  
+				</para>
+            <note>
+              <para><xref linkend="ref_guide_mapping_limits_tpc"/> in 
+					the Reference Guide describes the limitations OpenJPA 
+					places on table-per-class mapping.
+					</para>
+            </note>
+          </section>
+        </section>
+        <section id="jpa_overview_mapping_inher_together">
+          <title>Putting it All Together</title>
+          <para>
+			Now that we have covered EJB's inheritance strategies, we can
+			update our mapping document with inheritance information.  Here is 
+			the complete model:
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 513 x 410 (see README) -->
+              <imagedata fileref="img/ejb3-inher-all.png" width="341px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			And here is the corresponding mapping metadata:
+			</para>
+          <example id="jpa_overview_mapping_inher_togetherex">
+            <title>Inheritance Mapping</title>
+            <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+@SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ")
+public class Article
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") 
+    private long id;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen")
+    @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK",
+        valueColumnName="AID")
+    @Column(name="AID", columnDefinition="INTEGER64")
+    private long id;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+public class Contract
+    extends Document
+{
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
+public class Subscription
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID")
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+
+@Entity(name="Trial")
+public class TrialSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+            <para>The same metadata expressed in XML form:</para>
+            <programlisting format="linespecific">
+&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
+    version="1.0"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;table name="MAG"/&gt;
+        &lt;id-class="org.mag.Magazine.MagazineId"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="isbn"&gt;
+                &lt;column length="9"/&gt;
+            &lt;/id&gt;
+            &lt;id name="title"/&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        &lt;table name="ART"&gt;
+            &lt;unique-constraint&gt;
+               &lt;column-name&gt;TITLE&lt;/column-name&gt;
+            &lt;/unique-constraint&gt;
+        &lt;/table&gt;
+        &lt;sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="SEQUENCE" generator="ArticleSeq"/&gt;
+            &lt;/id&gt;
+           ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        &lt;table name="COMP"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="CID"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        &lt;table name="AUTH"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="AID" column-definition="INTEGER64"/&gt;
+                &lt;generated-value strategy="TABLE" generator="AuthorGen"/&gt;
+                &lt;table-generator name="AuthorGen" table="AUTH_GEN" 
+                    pk-column-name="PK" value-column-name="AID"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Contract"&gt;
+        &lt;table schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="JOINED"/&gt;
+        &lt;attributes&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Subscription"&gt;
+        &lt;table name="SUB" schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="SINGLE_TABLE"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+        &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+        &lt;primary-key-join-column name="ID" referenced-column-name="PK"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        ...
+    &lt;/entity&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_overview_mapping_discrim">
+        <title>Discriminator</title>
+        <indexterm zone="jpa_overview_mapping_discrim">
+          <primary>discriminator</primary>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_discrim">
+          <primary>mapping metadata</primary>
+          <secondary>discriminator</secondary>
+          <seealso>discriminator</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_discrim">
+          <primary>inheritance</primary>
+          <secondary>discriminator</secondary>
+          <seealso>discriminator</seealso>
+        </indexterm>
+        <para>
+		The <link linkend="jpa_overview_mapping_inher_single">single table
+		</link> inheritance strategy results in a single table containing 
+		records for two or more different classes in an inheritance hierarchy.
+		Similarly, using the <link linkend="jpa_overview_mapping_inher_joined">
+		joined</link> strategy results in the superclass table holding records 
+		for superclass instances as well as for the superclass state of 
+		subclass instances.  When selecting data, EJB needs a way to 
+		differentiate a row representing an object of one class from a row 
+		representing an object of another.  That is the job of the 
+		<emphasis>discriminator</emphasis> column.
+		</para>
+        <para>
+		The discriminator column is always in the table of the base entity.  It
+		holds a different value for records of each class, allowing the
+		EJB persistence runtime to determine what class of object each row
+		represents.  
+		</para>
+        <para>
+		The <classname>DiscriminatorColumn</classname> annotation represents
+		a discriminator column.  It has these properties:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>String name</literal>: The column name.  Defaults to
+				<literal>DTYPE</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>length</literal>: For string discriminator values,
+				the length of the column.  Defaults to 31.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>String columnDefinition</literal>: This property 
+				has the same meaning as the <literal>columnDefinition
+				</literal> property on the <classname>Column</classname> 
+				annotation, described in 
+				<xref linkend="jpa_overview_mapping_column"/>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>DiscriminatorType discriminatorType</literal>: Enum 
+				value declaring the discriminator strategy of the hierarchy.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The corresponding XML element is <literal>
+		discriminator-column</literal>.
+		Its attribues mirror the annotation properties above:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <literal>name</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>length</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>column-definition</literal>
+            </para>
+          </listitem>
+          <listitem>
+            <para><literal>discriminator-type</literal>: One of
+				<literal>STRING</literal>, <literal>CHAR</literal>, or
+				<literal>INTEGER</literal>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The <classname>DiscriminatorValue</classname> annotation specifies the
+		discriminator value for each class.  Though this annotation's value is
+		always a string, the implementation will parse it according to the
+		<classname>DiscriminatorColumn</classname>'s <literal>discriminatorType
+		</literal> property above.  The type defaults to 
+		<literal>DiscriminatorType.STRING</literal>, but may be <literal>
+		DiscriminatorType.CHAR</literal> or <literal>
+		DiscriminatorType.INTEGER</literal>.  If you do not specify a 
+		<classname>DiscriminatorValue</classname>, the provider will choose an
+		appropriate default.
+		</para>
+        <para>
+		The corresponding XML element is <literal>discriminator-value</literal>.
+		The text within this element is parsed as the discriminator value.
+		</para>
+        <note>
+          <para>
+			OpenJPA assumes your model employs a discriminator column if any of
+			the following are true: 
+			</para>
+          <orderedlist>
+            <listitem>
+              <para>
+					The base entity explicitly declares an inheritance type of
+					<literal>SINGLE_TABLE</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					The base entity sets a discriminator value.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					The base entity declares a discriminator column.
+					</para>
+            </listitem>
+          </orderedlist>
+          <para>
+			Only <literal>SINGLE_TABLE</literal> inheritance
+			hierarchies require a discriminator column and values. <literal>
+			JOINED</literal> hierarchies can use a discriminator to make 
+			some operations more efficient, but do not require one.  
+			<literal>TABLE_PER_CLASS</literal> hierarchies have no use 
+			for a discriminator.
+			</para>
+          <para>
+			OpenJPA defines additional discriminator strategies; see
+			<xref linkend="ref_guide_mapping_ejb"/> in the Reference Guide for
+			details.  OpenJPA also supports final entity classes.
+			OpenJPA does not use a discriminator on final classes. 
+			</para>
+        </note>
+        <para>
+		We can now translate our newfound knowledge of EJB discriminators
+		into concrete EJB mappings.  We first extend our diagram with
+		discriminator columns:
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 513 x 410 (see README) -->
+            <imagedata fileref="img/ejb3-discrim-all.png" width="341px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		Next, we present the updated mapping document.  Notice that in this
+		version, we have removed explicit inheritance annotations when the 
+		defaults sufficed.  Also, notice that entities using the default
+		<literal>DTYPE</literal> discriminator column mapping do not need an
+		explicit <classname>DiscriminatorColumn</classname> annotation. 
+		</para>
+        <example id="jpa_overview_mapping_discrimex">
+          <title>Discriminator Mapping</title>
+          <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+@DiscriminatorValue("Mag")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+@SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ")
+public class Article
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") 
+    private long id;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen")
+    @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK",
+        valueColumnName="AID")
+    @Column(name="AID", columnDefinition="INTEGER64")
+    private long id;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+@DiscriminatorColumn(name="CTYPE")
+public class Contract
+    extends Document
+{
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+@DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER)
+@DiscriminatorValue("1")
+public class Subscription
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+@DiscriminatorValue("2")
+public class LifetimeSubscription
+    extends Subscription
+{
+    ...
+}
+
+@Entity(name="Trial")
+@DiscriminatorValue("3")
+public class TrialSubscription
+    extends Subscription
+{
+    ...
+}
+</programlisting>
+          <para>The same metadata expressed in XML:</para>
+          <programlisting format="linespecific">
+&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
+    version="1.0"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;table name="MAG"/&gt;
+        &lt;id-class="org.mag.Magazine.MagazineId"/&gt;
+        &lt;discriminator-value&gt;Mag&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;id name="isbn"&gt;
+                &lt;column length="9"/&gt;
+            &lt;/id&gt;
+            &lt;id name="title"/&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        &lt;table name="ART"&gt;
+            &lt;unique-constraint&gt;
+                &lt;column-name&gt;TITLE&lt;/column-name&gt;
+            &lt;/unique-constraint&gt;
+        &lt;/table&gt;
+        &lt;sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="SEQUENCE" generator="ArticleSeq"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        &lt;table name="COMP"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="CID"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        &lt;table name="AUTH"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="AID" column-definition="INTEGER64"/&gt;
+                &lt;generated-value strategy="TABLE" generator="AuthorGen"/&gt;
+                &lt;table-generator name="AuthorGen" table="AUTH_GEN" 
+                    pk-column-name="PK" value-column-name="AID"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Contract"&gt;
+        &lt;table schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="JOINED"/&gt;
+        &lt;discriminator-column name="CTYPE"/&gt;
+        &lt;attributes&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Subscription"&gt;
+        &lt;table name="SUB" schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="SINGLE_TABLE"/&gt;
+        &lt;discriminator-value&gt;1&lt;/discriminator-value&gt;
+        &lt;discriminator-column name="KIND" discriminator-type="INTEGER"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+        &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+        &lt;primary-key-join-column name="ID" referenced-column-name="PK"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        &lt;discriminator-value&gt;2&lt;/discriminator-value&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        &lt;discriminator-value&gt;3&lt;/discriminator-value&gt;
+        ...
+    &lt;/entity&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="jpa_overview_mapping_field">
+        <title>Field Mapping</title>
+        <indexterm zone="jpa_overview_mapping_field">
+          <primary>mapping metadata</primary>
+          <secondary>field mapping</secondary>
+          <seealso>persistent fields</seealso>
+        </indexterm>
+        <indexterm zone="jpa_overview_mapping_field">
+          <primary>persistent fields</primary>
+          <secondary>mapping metadata</secondary>
+        </indexterm>
+        <para>
+		The following sections enumerate the myriad of field mappings EJB 
+		persistence supports.  EJB augments the persistence metadata
+		covered in <xref linkend="jpa_overview_meta"/> with
+		many new object-relational annotations.  As we explore the library of 
+		standard mappings, we introduce each of these enhancements in context.
+		</para>
+        <note>
+          <para>
+			OpenJPA supports many additional field types, and allows you to create
+			custom mappings for unsupported field types or database 
+			schemas.  See the Reference Guide's 
+			<xref linkend="ref_guide_mapping"/> for 
+			complete coverage of OpenJPA EJB's mapping capabilities.
+			</para>
+        </note>
+        <section id="jpa_overview_mapping_basic">
+          <title>Basic Mapping</title>
+          <indexterm zone="jpa_overview_mapping_basic">
+            <primary>mapping metadata</primary>
+            <secondary>basic fields</secondary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_basic">
+            <primary>persistent fields</primary>
+            <secondary>basic</secondary>
+          </indexterm>
+          <para>
+			A <emphasis>basic</emphasis> field mapping stores the field value
+			directly into a database column.  The following field metadata
+			types use basic mapping.  These types were defined in 
+			<xref linkend="jpa_overview_meta_field"/>.
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><link linkend="jpa_overview_meta_id"><classname>Id
+					</classname></link> fields.
+					</para>
+            </listitem>
+            <listitem>
+              <para><link linkend="jpa_overview_meta_version"><classname>
+					Version</classname></link> fields.
+					</para>
+            </listitem>
+            <listitem>
+              <para><link linkend="jpa_overview_meta_basic"><classname>Basic
+					</classname></link> fields.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			In fact, you have already seen examples of basic field mappings in 
+			this chapter - the mapping of all identity fields in
+			<xref linkend="jpa_overview_mapping_identityex"/>.  As you saw
+			in that section, to write a basic field mapping you use the
+			<classname>Column</classname> annotation to describe the column
+			the field value is stored in.  We discussed the <classname>Column
+			</classname> annotation in 
+			<xref linkend="jpa_overview_mapping_column"/>.  Recall that the 
+			name of the column defaults to the field name, and the type of the
+			column defaults to an appropriate type for the field type.  
+			These defaults allow you to sometimes omit the annotation
+			altogether.
+			</para>
+          <section id="jpa_overview_mapping_lob">
+            <title>LOBs</title>
+            <indexterm zone="jpa_overview_mapping_lob">
+              <primary>LOB</primary>
+            </indexterm>
+            <indexterm zone="jpa_overview_mapping_lob">
+              <primary>mapping metadata</primary>
+              <secondary>LOB types</secondary>
+            </indexterm>
+            <indexterm zone="jpa_overview_mapping_lob">
+              <primary>annotations</primary>
+              <secondary>Lob</secondary>
+            </indexterm>
+            <para>
+				Adding the <classname>Lob</classname> marker annotation to a
+				basic field signals that the data is to be stored as a 
+				LOB (Large OBject).  If the field holds string
+				or character data, it will map to a <literal>CLOB</literal>
+				(Character Large OBject) database column.  If the field holds 
+				any other data type, it will be stored as binary data in a 
+				<literal>BLOB</literal> (Binary Large OBject) column.  The 
+				implementation will serialize the Java value if needed.
+				</para>
+            <para>
+				The equivalent XML element is <literal>lob</literal>,
+				which has no children or attributes.
+				</para>
+          </section>
+          <section id="jpa_overview_mapping_enum">
+            <title>Enumerated</title>
+            <indexterm zone="jpa_overview_mapping_enum">
+              <primary>Enumerated</primary>
+            </indexterm>
+            <indexterm zone="jpa_overview_mapping_enum">
+              <primary>mapping metadata</primary>
+              <secondary>enums</secondary>
+            </indexterm>
+            <indexterm zone="jpa_overview_mapping_enum">
+              <primary>annotations</primary>
+              <secondary>Enumerated</secondary>
+            </indexterm>
+            <para>
+				You can apply the <classname>Enumerated</classname> annotation
+				to your <classname>Enum</classname> fields to control how they
+				map to the database.  The <classname>Enumerated</classname>
+				annotation's value one of the following constants from the 
+				<classname>EnumType</classname> enum: 
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>EnumType.ORDINAL</literal>: The default.
+						The persistence implementation places the ordinal value
+						of the enum in a numeric column.  This is an efficient 
+						mapping, but may break if you rearrange the Java 
+						enum declaration.  
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>EnumType.STRING</literal>: Store the name of
+						the enum value rather than the ordinal.  This mapping
+						uses a <literal>VARCHAR</literal> column rather than
+						a numeric one.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				The <classname>Enumerated</classname> annotation is 
+				optional.  Any un-annotated enumeration field defaults to
+				<literal>ORDINAL</literal> mapping.
+				</para>
+            <para>
+				The corresponding XML element is <literal>enumerated</literal>.
+				Its embedded text must be one of 
+				<literal>STRING</literal> or <literal>ORIDINAL</literal>.
+				</para>
+          </section>
+          <section id="jpa_overview_mapping_temporal">
+            <title>Temporal Types</title>
+            <indexterm zone="jpa_overview_mapping_temporal">
+              <primary>mapping metadata</primary>
+              <secondary>temporal types</secondary>
+            </indexterm>
+            <indexterm zone="jpa_overview_mapping_temporal">
+              <primary>persistent fields</primary>
+              <secondary>temporal</secondary>
+            </indexterm>
+            <para>
+				The <classname>Temporal</classname> annotation determines
+				how the implementation handles your basic <classname>
+				java.util.Date</classname> and <classname>
+				java.util.Calendar</classname> fields at the JDBC level.  The
+				<classname>Temporal</classname> annotation's value is a
+				constant from the <classname>TemporalType</classname> enum.
+				Available values are:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>TemporalType.TIMESTAMP</literal>: The default.
+						Use JDBC's timestamp APIs to manipulate the column
+						data.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>TemporalType.DATE</literal>: Use JDBC's 
+						SQL date APIs to manipulate the column data.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>TemporalType.TIME</literal>: Use JDBC's 
+						time APIs to manipulate the column data.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				If the <classname>Temporal</classname> annotation is omitted,
+				the implementation will treat the data as a timestamp.
+				</para>
+            <para>
+				The corresponding XML element is <literal>temporal</literal>,
+				whose text value must be one of:
+				<literal>TIME</literal>, <literal>DATE</literal>, or
+				<literal>TIMESTAMP</literal>.
+				</para>
+          </section>
+          <section id="jpa_overview_mapping_basic_example">
+            <title>The Updated Mappings</title>
+            <para>
+				Below we present an updated diagram of our model and its 
+				associated database schema, followed by the corresponding 
+				mapping metadata.  Note that the mapping metadata relies on 
+				defaults where possible.  Also note that as a mapped superclass,
+				<classname>Document</classname> can define mappings that will 
+				automatically transfer to its subclass' tables.  In 
+				<xref linkend="jpa_overview_mapping_embed"/>, you will see how
+				a subclass can override its mapped superclass' mappings.
+				</para>
+            <mediaobject>
+              <imageobject>
+<!-- PNG image data, 580 x 553 (see README) -->
+                <imagedata fileref="img/ejb3-basic-field.png" width="387px"/>
+              </imageobject>
+            </mediaobject>
+            <example id="jpa_overview_mapping_basicex">
+              <title>Basic Field Mapping</title>
+              <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+@DiscriminatorValue("Mag")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    @Column(name="VERS")
+    @Version private int version;
+    
+    private String name;
+    private double price;
+
+    @Column(name="COPIES")
+    private int copiesSold;
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+@SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ")
+public class Article
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") 
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    private String title;
+    private byte[] content;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    private String name;
+
+    @Column(name="REV")
+    private double revenue;
+
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen")
+    @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK",
+        valueColumnName="AID")
+    @Column(name="AID", columnDefinition="INTEGER64")
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    @Column(name="FNAME")
+    private String firstName;
+
+    @Column(name="LNAME")
+    private String lastName;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+@DiscriminatorColumn(name="CTYPE")
+public class Contract
+    extends Document
+{
+    @Lob
+    private String terms;
+
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+@DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER)
+@DiscriminatorValue("1")
+public class Subscription
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    @Column(name="START")
+    private Date startDate;
+
+    @Column(name="PAY")
+    private double payment;
+
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        @Column(name="COMM")
+        private String comments;
+
+        private double price;
+        private long num;
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+@DiscriminatorValue("2")
+public class LifetimeSubscription
+    extends Subscription
+{
+    @Basic(fetch=FetchType.LAZY)
+    @Column(name="ELITE")
+    private boolean getEliteClub () { ... }
+    public void setEliteClub (boolean elite) { ... }
+
+    ...
+}
+
+@Entity(name="Trial")
+@DiscriminatorValue("3")
+public class TrialSubscription
+    extends Subscription
+{
+    @Column(name="END")
+    public Date getEndDate () { ... }
+    public void setEndDate (Date end) { ... }
+
+    ...
+}
+</programlisting>
+              <para>The same metadata expressed in XML:</para>
+              <programlisting format="linespecific">
+&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
+    version="1.0"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;table name="MAG"/&gt;
+        &lt;id-class="org.mag.Magazine.MagazineId"/&gt;
+        &lt;discriminator-value&gt;Mag&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;id name="isbn"&gt;
+                &lt;column length="9"/&gt;
+            &lt;/id&gt;
+            &lt;id name="title"/&gt;
+            &lt;basic name="name"/&gt;
+            &lt;basic name="price"/&gt;
+            &lt;basic name="copiesSold"&gt;
+                &lt;column name="COPIES"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        &lt;table name="ART"&gt;
+            &lt;unique-constraint&gt;
+               &lt;column-name&gt;TITLE&lt;/column-name&gt;
+            &lt;/unique-constraint&gt;
+        &lt;/table&gt;
+        &lt;sequence-generator name="ArticleSeq", sequenceName="ART_SEQ"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="SEQUENCE" generator="ArticleSeq"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="title"/&gt;
+            &lt;basic name="content"/&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        &lt;table name="COMP"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="CID"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="name"/&gt;
+            &lt;basic name="revenue"&gt;
+                &lt;column name="REV"/&gt;
+            &lt;/basic&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        &lt;table name="AUTH"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="AID" column-definition="INTEGER64"/&gt;
+                &lt;generated-value strategy="TABLE" generator="AuthorGen"/&gt;
+                &lt;table-generator name="AuthorGen" table="AUTH_GEN" 
+                    pk-column-name="PK" value-column-name="AID"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="firstName"&gt;
+                &lt;column name="FNAME"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="lastName"&gt;
+                &lt;column name="LNAME"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Contract"&gt;
+        &lt;table schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="JOINED"/&gt;
+        &lt;discriminator-column name="CTYPE"/&gt;
+        &lt;attributes&gt;
+            &lt;basic name="terms"&gt;
+                &lt;lob/&gt;
+            &lt;/basic&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Subscription"&gt;
+        &lt;table name="SUB" schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="SINGLE_TABLE"/&gt;
+        &lt;discriminator-value&gt;1&lt;/discriminator-value&gt;
+        &lt;discriminator-column name="KIND" discriminator-type="INTEGER"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="payment"&gt;
+                &lt;column name="PAY"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="startDate"&gt;
+                &lt;column name="START"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+        &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+        &lt;primary-key-join-column name="ID" referenced-column-name="PK"/&gt;
+        &lt;attributes&gt;
+            &lt;basic name="comments"&gt;
+                &lt;column name="COMM"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="price"/&gt;
+            &lt;basic name="num"/&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        &lt;discriminator-value&gt;2&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;basic name="eliteClub" fetch="LAZY"&gt;
+                &lt;column name="ELITE"/&gt;
+            &lt;/basic&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        &lt;discriminator-value&gt;3&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;basic name="endDate"&gt;
+                &lt;column name="END"/&gt;
+            &lt;/basic&gt;
+            ...
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+            </example>
+          </section>
+        </section>
+        <section id="jpa_overview_mapping_secondary">
+          <title>Secondary Tables</title>
+          <indexterm zone="jpa_overview_mapping_secondary">
+            <primary>mapping metadata</primary>
+            <secondary>secondary table fields</secondary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_secondary">
+            <primary>persistent fields</primary>
+            <secondary>in secondary tables</secondary>
+          </indexterm>
+          <para>
+			Sometimes a a logical record is spread over multiple database
+			tables.  EJB persistence calls a class' declared table the 
+			<emphasis>primary</emphasis> table, and calls other tables that 
+			make up a logical record <emphasis>secondary</emphasis> tables.  
+			You can map any persistent field to a secondary table.  Just write 
+			the standard field mapping, then perform these two additional steps:
+			</para>
+          <orderedlist>
+            <listitem>
+              <para>
+					Set the <literal>table</literal> attribute of each
+					of the field's columns or join columns to the name of the 
+					secondary table.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Define the secondary table on the entity class declaration.
+					</para>
+            </listitem>
+          </orderedlist>
+          <para>
+			You define secondary tables with the <classname>SecondaryTable
+			</classname> annotation.  This annotation has all the properties
+			of the <classname>Table</classname> annotation covered in
+			<xref linkend="jpa_overview_mapping_table"/>, plus a <literal>
+			pkJoinColumns</literal> property.
+			</para>
+          <para>
+			The <literal>pkJoinColumns</literal> property is an array of 
+			<classname>PrimaryKeyJoinColumn</classname>s dictating how to join 
+			secondary table records to their owning primary table records.  Each
+			<classname>PrimaryKeyJoinColumn</classname> joins a secondary table
+			column to a primary key column in the primary table.  See
+			<xref linkend="jpa_overview_mapping_inher_joined"/> above for 
+			coverage of <classname>PrimaryKeyJoinColumn</classname>'s 
+			properties.
+			</para>
+          <para>
+			The corresponding XML element 
+			is <literal>secondary-table</literal>.  This element has all
+			the attributes of the <literal>table</literal> element, but also 
+			accepts nested <literal>primary-key-join-column</literal> elements.
+			</para>
+          <para>
+			In the following example, we move the <literal>Article.content
+			</literal> field we mapped in 
+			<xref linkend="jpa_overview_mapping_basic"/> into a joined 
+			secondary table, like so:
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 284 x 167 (see README) -->
+              <imagedata fileref="img/secondary-table.png" width="189px"/>
+            </imageobject>
+          </mediaobject>
+          <example id="jpa_overview_mapping_secondaryex">
+            <title>Secondary Table Field Mapping</title>
+            <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@Table(name="ART")
+@SecondaryTable(name="ART_DATA", 
+    pkJoinColumns=@PrimaryKeyJoinColumn(name="ART_ID", referencedColumnName="ID"))
+public class Article
+{
+    @Id private long id;
+
+    @Column(table="ART_DATA")
+    private byte[] content;
+
+    ...
+}
+</programlisting>
+            <para>And in XML:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.Article"&gt;
+    &lt;table name="ART"&gt;
+    &lt;secondary-table name="ART_DATA"&gt;
+        &lt;primary-key-join-column name="ART_ID" referenced-column-name="ID"/&gt;
+    &lt;/secondary-table&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"/&gt;
+        &lt;basic name="content"&gt;
+            &lt;column table="ART_DATA"/&gt;
+        &lt;/basic&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="jpa_overview_mapping_embed">
+          <title>Embedded Mapping</title>
+          <indexterm zone="jpa_overview_mapping_embed">
+            <primary>mapping metadata</primary>
+            <secondary>embedded fields</secondary>
+            <seealso>embedded</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_embed">
+            <primary>embedded</primary>
+            <secondary>mapping embedded fields</secondary>
+          </indexterm>
+          <para><xref linkend="jpa_overview_meta"/> describes EJB's concept of 
+			<emphasis>embeddable</emphasis> objects.  The field values of 
+			embedded objects are stored as part of the owning record, rather 
+			than as a separate database record.  Thus, instead of mapping a 
+			relation to an embeddable object as a foreign key, you map all the 
+			fields of the embeddable instance to columns in the owning field's 
+			table.
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 464 x 203 (see README) -->
+              <imagedata fileref="img/ejb3-embedded.png" width="309px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			EJB persistence defaults the embedded column names and descriptions
+			to those of the embeddable class' field mappings.  The <classname>
+			AttributeOverride</classname> annotation overrides a basic embedded
+			mapping. This annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the 
+					embedded class' field being mapped to this class' table.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>Column column</literal>: The column defining the 
+					mapping of the embedded class' field to this class' 
+					table.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The corresponding XML element is <literal>
+			attribute-override</literal>.  It has a single <literal>name
+			</literal> attribute to name the field being overridden,
+			and a single <literal>column</literal> child element.
+			</para>
+          <para>
+			To declare multiple overrides, use the <classname>AttributeOverrides
+			</classname> annotation, whose value is an array of 
+			<classname>AttributeOverride</classname>s.  In XML, simply list 
+			multiple <literal>attribute-override</literal> elements in 
+			succession.
+			</para>
+          <para>
+			To override a many to one or one to one relationship, use the
+			<classname>AssociationOverride</classname> annotation in place of
+			<classname>AttributeOverride</classname>.  <classname>
+			AssociationOverride</classname> has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the 
+					embedded class' field being mapped to this class' table.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>JoinColumn[] joinColumns</literal>: The foreign key
+					columns joining to the related record.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The corresponding XML element is <literal>
+			association-override</literal>.  It has a single <literal>name
+			</literal> attribute to name the field being overridden,
+			and one or more <literal>join-column</literal> child elements.
+			</para>
+          <para>
+			To declare multiple relation overrides, use the <classname>
+			AssociationOverrides</classname> annotation, whose value is an 
+			array of <classname>AssociationOverride</classname>s.  In XML, 
+			simply list multiple <literal>association-override</literal> 
+			elements in succession.
+			</para>
+          <example id="jpa_overview_mapping_embedex">
+            <title>Embedded Field Mapping</title>
+            <para>
+				In this example, <classname>Company</classname> overrides the
+				default mapping of <literal>Address.street</literal> and
+				<literal>Address.city</literal>.
+				All other embedded mappings are taken from the 
+				<classname>Address</classname> embeddable class.
+				</para>
+            <programlisting format="linespecific">
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Embedded
+    @AttributeOverrides({
+        @AttributeOverride(name="street", column=@Column(name="STRT")),
+        @AttributeOverride(name="city", column=@Column(name="ACITY"))
+    })
+    private Address address;
+    
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    // use all defaults from Address class mappings
+    private Address address;
+    
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    private String street;
+    private String city;
+    @Column(columnDefinition="CHAR(2)")
+    private String state;
+    private String zip;
+}
+</programlisting>
+            <para>The same metadata expressed in XML:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.pub.Company"&gt;
+    &lt;table name="COMP"/&gt;
+    &lt;attributes&gt;
+        ...
+        &lt;embedded name="address"&gt;
+            &lt;attribute-override name="street"&gt;
+               &lt;column name="STRT"/&gt;
+            &lt;/attribute-override&gt;
+            &lt;attribute-override name="city"&gt;
+               &lt;column name="ACITY"/&gt;
+            &lt;/attribute-override&gt;
+        &lt;/embedded&gt;
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.pub.Author"&gt;
+    &lt;table name="AUTH"/&gt;
+    &lt;attributes&gt;
+        &lt;embedded name="address"&gt;
+            &lt;!-- use all defaults from Address --&gt;
+        &lt;/embedded&gt;
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;embeddable class="org.mag.pub.Address"&gt;
+    &lt;attributes&gt;
+        &lt;basic name="street"/&gt;
+        &lt;basic name="city"/&gt;
+        &lt;basic name="state"&gt;
+            &lt;column column-definition="CHAR(2)"/&gt;
+        &lt;/basic&gt;
+        &lt;basic name="zip"/&gt;
+    &lt;/attributes&gt;
+&lt;/embeddable&gt;
+</programlisting>
+          </example>
+          <para>
+			You can also use attribute overrides on an entity class to 
+			override mappings defined by
+			its mapped superclass or table-per-class superclass.  The example 
+			below re-maps the <literal>Document.version</literal> field to the 
+			<classname>Contract</classname> table's <literal>CVERSION</literal>
+			column.
+			</para>
+          <example id="jpa_overview_mapping_joined_overex">
+            <title>Mapping Mapped Superclass Field</title>
+            <programlisting format="linespecific">
+@MappedSuperclass
+public abstract class Document
+{
+    @Column(name="VERS")
+    @Version private int version;
+
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+@DiscriminatorColumn(name="CTYPE")
+@AttributeOverride(name="version", column=@Column(name="CVERSION"))
+public class Contract
+    extends Document
+{
+    ...
+}
+</programlisting>
+            <para>The same metadata expressed in XML form:</para>
+            <programlisting format="linespecific">
+&lt;mapped-superclass class="org.mag.subcribe.Document"&gt;
+    &lt;attributes&gt;
+        &lt;version name="version"&gt;
+            &lt;column name="VERS"&gt;
+        &lt;/version&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/mapped-superclass&gt;
+&lt;entity class="org.mag.subcribe.Contract"&gt;
+    &lt;table schema="CNTRCT"/&gt;
+    &lt;inheritance strategy="JOINED"/&gt;
+    &lt;discriminator-column name="CTYPE"/&gt;
+    &lt;attribute-override name="version"&gt;
+        &lt;column name="CVERSION"/&gt;
+    &lt;/attribute-override&gt;
+    &lt;attributes&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="jpa_overview_mapping_rel">
+          <title>Direct Relations</title>
+          <indexterm zone="jpa_overview_mapping_rel">
+            <primary>mapping metadata</primary>
+            <secondary>direct relation fields</secondary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_rel">
+            <primary>persistent fields</primary>
+            <secondary>direct relations</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_rel">
+            <primary>one-one</primary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_rel">
+            <primary>many-one</primary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <para>
+			A direct relation is a non-embedded persistent field that holds a 
+			reference to another entity.
+			<link linkend="jpa_overview_meta_manytoone">many to one</link> and 
+			<link linkend="jpa_overview_meta_onetoone">one to one</link> 
+			metadata field types are mapped as direct
+			relations.  Our model has three direct relations: 
+			<classname>Magazine</classname>'s <literal>publisher</literal> 
+			field is a direct relation to a <classname>Company</classname>, 
+			<classname>Magazine</classname>'s <literal>coverArticle</literal> 
+			field is a direct relation to <classname>Article</classname>, and 
+			the <literal>LineItem.magazine</literal> field is a direct relation
+			to a <classname>Magazine</classname>.  Direct relations are 
+			represented in the database by foreign key columns:
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 374 x 386 (see README) -->
+              <imagedata fileref="img/ejb3-direct-relation.png" width="249px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			You typically map a direct relation with 
+			<classname>JoinColumn</classname> annotations describing how the 
+			local foreign key columns join to the primary key columns of the 
+			related record.  The <classname>JoinColumn</classname> annotation 
+			exposes the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the foreign key
+					column.  Defaults to the relation field name, plus an
+					underscore, plus the name of the referenced primary key 
+					column.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String referencedColumnName</literal>: The name 
+					of the primary key column being joined to.  If there is 
+					only one identity field in the related entity class, the 
+					join column name defaults to the name of the identity 
+					field's column.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean unique</literal>: Whether this column
+					is guaranteed to hold unique values for all rows.  Defaults
+					to false.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para><classname>JoinColumn</classname> also has the same <literal>
+			nullable</literal>, <literal>insertable</literal>, <literal>
+			updatable</literal>, <literal>columnDefinition</literal>, and
+			<literal>table</literal> properties as the <classname>
+			Column</classname> annotation.  See 
+			<xref linkend="jpa_overview_mapping_column"/> for details on these
+			properties.
+			</para>
+          <para>
+			The <literal>join-column</literal> element represents a join column
+			in XML.  Its attributes mirror the above annotation's properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                <literal>name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>referenced-column-name</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>unique</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>nullable</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>insertable</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>updatable</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>column-definition</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>table</literal>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			When there are multiple columns involved in the join, as when a 
+			<classname>LineItem</classname> references a <classname>Magazine
+			</classname> in our model, the <classname>JoinColumns</classname> 
+			annotation allows you to specify an array of <classname>JoinColumn
+			</classname> values.  In XML, simply list multiple
+			<literal>join-column</literal> elements.
+			</para>
+          <note>
+            <para>
+				OpenJPA supports many non-standard joins.  See
+				<xref linkend="ref_guide_mapping_notes_nonstdjoins"/> in the
+				Reference Guide for details.
+				</para>
+          </note>
+          <example id="jpa_overview_mapping_relex">
+            <title>Direct Relation Field Mapping</title>
+            <programlisting format="linespecific">
+package org.mag;
+
+@Table(name="AUTH")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    @OneToOne
+    @JoinColumn(name="COVER_ID" referencedColumnName="ID")
+    private Article coverArticle;
+
+    @ManyToOne
+    @JoinColumn(name="PUB_ID" referencedColumnName="CID")
+    private Company publisher;
+
+    ...
+}
+
+@Table(name="ART")
+public class Article
+{
+    @Id private long id;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    ...
+}
+
+
+package org.mag.subscribe;
+
+public class Subscription
+{
+    ...
+
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        @ManyToOne
+        @JoinColumns({
+            @JoinColumn(name="MAG_ISBN" referencedColumnName="ISBN"),
+            @JoinColumn(name="MAG_TITLE" referencedColumnName="TITLE")
+        })
+        private Magazine magazine;
+
+        ...
+    }
+}
+</programlisting>
+            <para>The same metadata expressed in XML form:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.Magazine"&gt;
+    &lt;table name="MAG"/&gt;
+    &lt;id-class="org.mag.Magazine.MagazineId"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="isbn"&gt;
+            &lt;column length="9"/&gt;
+        &lt;/id&gt;
+        &lt;id name="title"/&gt;
+        &lt;one-to-one name="coverArticle"&gt;
+            &lt;join-column name="COVER_ID" referenced-column-name="ID"/&gt;
+        &lt;/one-to-one&gt;
+        &lt;many-to-one name="publisher"&gt;
+            &lt;join-column name="PUB_IC" referenced-column-name="CID"/&gt;
+        &lt;/many-to-one&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.Article"&gt;
+    &lt;table name="ART"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"/&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.pub.Company"&gt;
+    &lt;table name="COMP"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"&gt;
+            &lt;column name="CID"/&gt;
+        &lt;/id&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+    &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+    &lt;primary-key-join-column name="ID" referenced-column-name="PK"/&gt;
+    &lt;attributes&gt;
+        &lt;many-to-one name="magazine"&gt;
+            &lt;join-column name="MAG_ISBN" referenced-column-name="ISBN"/&gt;
+            &lt;join-column name="MAG_TITLE" referenced-column-name="TITLE"/&gt;
+        &lt;/many-to-one&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+          </example>
+          <para>
+			When the entities in a one to one relation join on
+			shared primary key values rather than separate foreign key columns, 
+			use the <classname>PrimaryKeyJoinColumn(s)</classname> 
+			annotation or <literal>primary-key-join-column</literal> elements 
+			in place of <classname>JoinColumn(s)</classname> / <literal>
+			join-column</literal> elements.
+			</para>
+        </section>
+        <section id="jpa_overview_mapping_assoccoll">
+          <title>Join Table</title>
+          <indexterm zone="jpa_overview_mapping_assoccoll">
+            <primary>mapping metadata</primary>
+            <secondary>association table collection fields</secondary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_assoccoll">
+            <primary>persistent fields</primary>
+            <secondary>join table collections</secondary>
+          </indexterm>
+          <indexterm>
+            <primary>join table</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_assoccoll">
+            <primary>one-many</primary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_assoccoll">
+            <primary>many-many</primary>
+            <seealso>persistent fields</seealso>
+          </indexterm>
+          <para>
+			A <emphasis>join table</emphasis> consists of two foreign
+			keys.  Each row of a join table associates two objects together.  
+			EJB persistence uses join tables to represent collections of entity
+			objects: one foreign key refers back to the collection's owner, 
+			and the other refers to a collection element.
+			</para>
+          <para><link linkend="jpa_overview_meta_onetomany">one to many</link> and 
+			<link linkend="jpa_overview_meta_manytomany">many to many</link>
+			metadata field types can map to join 
+			tables.  Several fields in our model use join table mappings,
+			including <literal>Magazine.articles</literal> and <literal>
+			Article.authors</literal>.
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 391 x 407 (see README) -->
+              <imagedata fileref="img/ejb3-assoc-table.png" width="261px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			You define join tables with the <classname>JoinTable</classname> 
+			annotation.  This annotation has the following properties: 
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: Table name.  If not 
+					given, the name of the table defaults to the name of the
+					owning entity's table, plus an underscore, plus the name of
+					the related entity's table.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String catalog</literal>: Table catalog.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String schema</literal>: Table schema.</para>
+            </listitem>
+            <listitem>
+              <para><literal>JoinColumn[] joinColumns</literal>: Array
+					of <classname>JoinColumn</classname> sshowing how to
+					associate join table records with the owning row in the
+					primary table.  This property mirrors the
+					<literal>pkJoinColumns</literal> property of the <classname>
+					SecondaryTable</classname> annotation in functionality.
+					See <xref linkend="jpa_overview_mapping_secondary"/> to
+					refresh your memory on secondary tables.
+					</para>
+              <para>
+					If this is a bidirectional relation (see 
+					<xref linkend="jpa_overview_meta_mappedby"/>), the name 
+					of a join column defaults to the inverse field name, plus 
+					an underscore, plus the referenced primary key column name. 
+					Otherwise, the join column name defaults to the field's 
+					owning entity name, plus an underscore, plus the referenced
+					primary key column name. 
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>JoinColumn[] inverseJoinColumns</literal>: Array
+					of <classname>JoinColumns</classname> showing how to
+					associate join table records with the records that form the
+					elements of the collection.  These join columns are used
+					just like the join columns for direct relations, and they
+					have the same naming defaults.
+					Read <xref linkend="jpa_overview_mapping_rel"/> for a 
+					review of direct relation mapping.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para><literal>join-table</literal> is the corresponding XML element.
+			It has the same attributes as the <literal>table</literal>
+			element, but includes the ability to nest 
+			<literal>join-column</literal> and 
+			<literal>inverse-join-column</literal> elements as children.
+			We have seen <literal>join-column</literal> elements already;
+			<literal>inverse-join-column</literal> elements have the same
+			attributes.
+			</para>
+          <para>
+			Here are the join table mappings for the diagram above.
+			</para>
+          <example id="jpa_overview_mapping_assoccollex">
+            <title>Join Table Mapping</title>
+            <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@Table(name="MAG")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    @OneToMany(...)
+    @OrderBy
+    @JoinTable(name="MAG_ARTS",
+        joinColumns={
+            @JoinColumn(name="MAG_ISBN", referencedColumnName="ISBN"),
+            @JoinColumn(name="MAG_TITLE", referencedColumnName="TITLE")
+        },
+        inverseJoinColumns=@JoinColumn(name="ART_ID", referencedColumnName="ID"))
+    private Collection&lt;Article&gt; articles;
+
+    ...
+}
+
+@Entity
+@Table(name="ART")
+public class Article
+{
+    @Id private long id;
+
+    @ManyToMany(cascade=CascadeType.PERSIST)
+    @OrderBy("lastName, firstName")
+    @JoinTable(name="ART_AUTHS",
+        joinColumns=@JoinColumn(name="ART_ID", referencedColumnName="ID"),
+        inverseJoinColumns=@JoinColumn(name="AUTH_ID", referencedColumnName="AID"))
+    private Collection&lt;Author&gt; authors;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Column(name="AID", columnDefinition="INTEGER64")
+    @Id private long id;
+
+    ...
+}
+</programlisting>
+            <para>The same metadata expressed in XML:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.Magazine"&gt;
+    &lt;table name="MAG"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="isbn"&gt;
+            &lt;column length="9"/&gt;
+        &lt;/id&gt;
+        &lt;id name="title"/&gt;
+        &lt;one-to-many name="articles"&gt;
+            &lt;order-by/&gt;
+            &lt;join-table name="MAG_ARTS"&gt;
+                &lt;join-column name="MAG_ISBN" referenced-column-name="ISBN"/&gt;
+                &lt;join-column name="MAG_TITLE" referenced-column-name="TITLE"/&gt;
+            &lt;/join-table&gt;
+        &lt;/one-to-many&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.Article"&gt;
+    &lt;table name="ART"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"/&gt;
+            &lt;many-to-many name="articles"&gt;
+                &lt;order-by&gt;lastName, firstName&lt;/order-by&gt;
+                &lt;join-table name="ART_AUTHS"&gt;
+                    &lt;join-column name="ART_ID" referenced-column-name="ID"/&gt;
+                    &lt;inverse-join-column name="AUTH_ID" referenced-column-name="AID"/&gt;
+                &lt;/join-table&gt;
+            &lt;/many-to-many&gt;
+            ...
+       &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.pub.Author"&gt;
+    &lt;table name="AUTH"/&gt;
+    &lt;attributes&gt;
+        &lt;id name="id"&gt;
+            &lt;column name="AID" column-definition="INTEGER64"/&gt;
+        &lt;/id&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="jpa_overview_mapping_bidi">
+          <title>Bidirectional Mapping</title>
+          <indexterm zone="jpa_overview_mapping_bidi">
+            <primary>bidirectional relations</primary>
+            <secondary>mapping</secondary>
+          </indexterm>
+          <para><xref linkend="jpa_overview_meta_mappedby"/> introduced 
+		bidirectional relations.  To map a bidirectional relation, you map 
+		one field normally using the annotations we have covered throughout 
+		this chapter.  Then you use the <literal>mappedBy</literal> property
+		of the other field's metadata annotation or the corresponding 
+		<literal>mapped-by</literal> XML attribute to refer to the mapped 
+		field.  Look for this pattern in these bidirectional relations as
+		you peruse the complete mappings below:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Magazine.publisher</literal> and 
+				<literal>Company.ags</literal>.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>Article.authors</literal> and 
+				<literal>Author.articles</literal>.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_mapping_map">
+          <title>Map Mapping</title>
+          <indexterm zone="jpa_overview_mapping_map">
+            <primary>mapping metadata</primary>
+            <secondary>map fields</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_mapping_map">
+            <primary>persistent fields</primary>
+            <secondary>maps</secondary>
+          </indexterm>
+          <para>
+		All map fields in EJB persistence are modeled on either
+		one to many or many to many associations.  The map key is always 
+		derived from an associated
+		entity's field.  Thus map fields use the same mappings as any
+		one to many or many to many fields, namely dedicated 
+		<link linkend="jpa_overview_mapping_assoccoll">join tables</link> 
+		or <link linkend="jpa_overview_mapping_bidi">bidirectional 
+		relations</link>.  The only additions are the <classname>MapKey
+		</classname> annotation and <literal>map-key</literal> element to 
+		declare the key field.  We covered these additions in
+		in <xref linkend="jpa_overview_meta_mapkey"/>.
+		</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 382 x 274 (see README) -->
+              <imagedata fileref="img/ejb3-map.png" width="255px"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+		The example below maps <classname>Subscription</classname>'s map of
+		<classname>LineItem</classname>s to the <literal>SUB_ITEMS</literal>
+		join table.  The key for each map entry is the <classname>
+		LineItem</classname>'s <literal>num</literal> field value.
+		</para>
+          <example id="jpa_overview_mapping_mapex">
+            <title>Join Table Map Mapping</title>
+            <programlisting format="linespecific">
+package org.mag.subscribe;
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+public class Subscription
+{
+@OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+@MapKey(name="num")
+@JoinTable(name="SUB_ITEMS", schema="CNTRCT",
+    joinColumns=@JoinColumn(name="SUB_ID"),
+    inverseJoinColumns=@JoinColumn(name="ITEM_ID"))
+private Map&lt;Long,LineItem&gt; items;
+
+...
+
+@Entity
+@Table(name="LINE_ITEM", schema="CNTRCT")
+public static class LineItem
+    extends Contract
+{
+    private long num;
+
+    ...
+}
+}
+</programlisting>
+            <para>The same metadata expressed in XML:</para>
+            <programlisting format="linespecific">
+&lt;entity class="org.mag.subscribe.Subscription"&gt;
+    &lt;table name="SUB" schema="CNTRCT"/&gt;
+    &lt;attributes&gt;
+        ...
+        &lt;one-to-many name="items"&gt;
+            &lt;map-key name="num"&gt;
+            &lt;join-table name="MAG_ARTS"&gt;
+                &lt;join-column name="MAG_ISBN" referenced-column-name="ISBN"/&gt;
+                &lt;join-column name="MAG_TITLE" referenced-column-name="TITLE"/&gt;
+            &lt;/join-table&gt;
+            &lt;cascade&gt;
+                &lt;cascade-persist/&gt;
+                &lt;cascade-remove/&gt;
+            &lt;/cascade&gt;
+        &lt;/one-to-many&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+&lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+    &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+    &lt;attributes&gt;
+        ...
+        &lt;basic name="num"/&gt;
+        ...
+    &lt;/attributes&gt;
+&lt;/entity&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_overview_mapping_full">
+        <title>The Complete Mappings</title>
+        <para>
+		We began this chapter with the goal of mapping the following object
+		model:
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 553 x 580 (see README) -->
+            <imagedata fileref="img/ejb3-meta-model.png" width="369px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		That goal has now been met.  In the course of explaining EJB's 
+		object-relational mapping metadata, we slowly built the requisite schema
+		and mappings for the complete model.  First, the database schema:
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 490 x 662 (see README) -->
+            <imagedata fileref="img/ejb3-data-model.png" width="326px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		And finally, the complete entity mappings.  We have trimmed the mappings
+		to take advantage of EJB defaults where possible.
+		</para>
+        <example id="jpa_overview_mapping_fullex">
+          <title>Full Entity Mappings</title>
+          <programlisting format="linespecific">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+@DiscriminatorValue("Mag")
+public class Magazine
+{
+    @Column(length=9)
+    @Id private String isbn;
+    @Id private String title;
+
+    @Column(name="VERS")
+    @Version private int version;
+    
+    private String name;
+    private double price;
+
+    @Column(name="COPIES")
+    private int copiesSold;
+
+    @OneToOne(fetch=FetchType.LAZY, 
+        cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    @JoinColumn(name="COVER_ID")
+    private Article coverArticle;
+
+    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    @OrderBy
+    @JoinTable(name="MAG_ARTS",
+        joinColumns={
+            @JoinColumn(name="MAG_ISBN", referencedColumnName="ISBN"),
+            @JoinColumn(name="MAG_TITLE", referencedColumnName="TITLE")
+        },
+        inverseJoinColumns=@JoinColumn(name="ART_ID"))
+    private Collection&lt;Article&gt; articles;
+
+    @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.PERSIST)
+    @JoinColumn(name="PUB_ID")
+    private Company publisher; 
+
+    @Transient private byte[] data;
+
+
+    ...
+
+    public static class MagazineId
+    {
+        ...
+    }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+@SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ")
+public class Article
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") 
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    private String title;
+    private byte[] content;
+
+    @ManyToMany(cascade=CascadeType.PERSIST)
+    @OrderBy("lastName, firstName")
+    @JoinTable(name="ART_AUTHS",
+        joinColumns=@JoinColumn(name="ART_ID"),
+        inverseJoinColumns=@JoinColumn(name="AUTH_ID"))
+    private Collection&lt;Author&gt; authors;
+
+    ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Column(name="CID")
+    @Id private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    private String name;
+
+    @Column(name="REV")
+    private double revenue;
+
+    @Embedded
+    @AttributeOverrides({
+        @AttributeOverride(name="street", column=@Column(name="STRT")),
+        @AttributeOverride(name="city", column=@Column(name="ACITY"))
+    })
+    private Address address;
+    
+    @OneToMany(mappedBy="publisher", cascade=CascadeType.PERSIST)
+    private Collection&lt;Magazine&gt; mags;
+
+    @OneToMany(cascade=CascadeType.PERSIST,CascadeType.REMOVE)
+    @JoinTable(name="COMP_SUBS",
+        joinColumns=@JoinColumn(name="COMP_ID"),
+        inverseJoinColumns=@JoinColumn(name="SUB_ID"))
+    private Collection&lt;Subscription&gt; subscriptions;
+
+    ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen")
+    @TableGenerator(name="AuthorGen", tableName="AUTH_GEN", pkColumnName="PK",
+        valueColumnName="AID")
+    @Column(name="AID", columnDefinition="INTEGER64")
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    @Column(name="FNAME")
+    private String firstName;
+
+    @Column(name="LNAME")
+    private String lastName;
+
+    private Address address;
+    
+    @ManyToMany(mappedBy="authors", cascade=CascadeType.PERSIST)
+    private Collection&lt;Article&gt; arts;
+
+    ...
+}
+
+@Embeddable
+public class Address
+{
+    private String street;
+    private String city;
+    @Column(columnDefinition="CHAR(2)")
+    private String state;
+    private String zip;
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+@DiscriminatorColumn(name="CTYPE")
+public class Contract
+    extends Document
+{
+    @Lob
+    private String terms;
+
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+@DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER)
+@DiscriminatorValue("1")
+public class Subscription
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.IDENTITY)
+    private long id;
+
+    @Column(name="VERS")
+    @Version private int version;
+
+    @Column(name="START")
+    private Date startDate;
+
+    @Column(name="PAY")
+    private double payment;
+
+    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
+    @MapKey(name="num")
+    @JoinTable(name="SUB_ITEMS", schema="CNTRCT",
+        joinColumns=@JoinColumn(name="SUB_ID"),
+        inverseJoinColumns=@JoinColumn(name="ITEM_ID"))
+    private Map&lt;Long,LineItem&gt; items;
+
+    ...
+
+    @Entity
+    @Table(name="LINE_ITEM", schema="CNTRCT")
+    public static class LineItem
+        extends Contract
+    {
+        @Column(name="COMM")
+        private String comments;
+
+        private double price;
+        private long num;
+
+        @ManyToOne
+        @JoinColumns({
+             @JoinColumn(name="MAG_ISBN", referencedColumnName="ISBN"),
+             @JoinColumn(name="MAG_TITLE", referencedColumnName="TITLE")
+        })
+        private Magazine magazine;
+        ...
+    }
+}
+
+@Entity(name="Lifetime")
+@DiscriminatorValue("2")
+public class LifetimeSubscription
+    extends Subscription
+{
+    @Basic(fetch=FetchType.LAZY)
+    @Column(name="ELITE")
+    private boolean getEliteClub () { ... }
+    public void setEliteClub (boolean elite) { ... }
+
+    ...
+}
+
+@Entity(name="Trial")
+@DiscriminatorValue("3")
+public class TrialSubscription
+    extends Subscription
+{
+    @Column(name="END")
+    public Date getEndDate () { ... }
+    public void setEndDate (Date end) { ... }
+
+    ...
+}
+</programlisting>
+          <para>The same metadata expressed in XML form:</para>
+          <programlisting format="linespecific">
+&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
+    version="1.0"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+        &lt;/attributes&gt;
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;table name="MAG"/&gt;
+        &lt;id-class="org.mag.Magazine.MagazineId"/&gt;
+        &lt;discriminator-value&gt;Mag&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;id name="isbn"&gt;
+                &lt;column length="9"/&gt;
+            &lt;/id&gt;
+            &lt;id name="title"/&gt;
+            &lt;basic name="name"/&gt;
+            &lt;basic name="price"/&gt;
+            &lt;basic name="copiesSold"&gt;
+                &lt;column name="COPIES"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            &lt;many-to-one name="publisher" fetch="LAZY"&gt;
+                &lt;join-column name="PUB_ID"/&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                &lt;/cascade&gt;
+            &lt;/many-to-one&gt;
+            &lt;one-to-many name="articles"&gt;
+                &lt;order-by/&gt;
+                &lt;join-table name="MAG_ARTS"&gt;
+                    &lt;join-column name="MAG_ISBN" referenced-column-name="ISBN"/&gt;
+                    &lt;join-column name="MAG_TITLE" referenced-column-name="TITLE"/&gt;
+                    &lt;inverse-join-column name="ART_ID"/&gt;
+                &lt;/join-table&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+            &lt;one-to-one name="coverArticle" fetch="LAZY"&gt;
+                &lt;join-column name="COVER_ID"/&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-one&gt;
+            &lt;transient name="data"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        &lt;table name="ART"&gt;
+            &lt;unique-constraint&gt;
+               &lt;column-name&gt;TITLE&lt;/column-name&gt;
+            &lt;/unique-constraint&gt;
+        &lt;/table&gt;
+        &lt;sequence-generator name="ArticleSeq", sequenceName="ART_SEQ"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="SEQUENCE" generator="ArticleSeq"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="title"/&gt;
+            &lt;basic name="content"/&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            &lt;many-to-many name="articles"&gt;
+                &lt;order-by&gt;lastName, firstName&lt;/order-by&gt;
+                &lt;join-table name="ART_AUTHS"&gt;
+                    &lt;join-column name="ART_ID" referenced-column-name="ID"/&gt;
+                    &lt;inverse-join-column name="AUTH_ID" referenced-column-name="AID"/&gt;
+                &lt;/join-table&gt;
+            &lt;/many-to-many&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        &lt;table name="COMP"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="CID"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="name"/&gt;
+            &lt;basic name="revenue"&gt;
+                &lt;column name="REV"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            &lt;one-to-many name="mags" mapped-by="publisher"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+            &lt;one-to-many name="subscriptions"&gt;
+                &lt;join-table name="COMP_SUBS"&gt;
+                    &lt;join-column name="COMP_ID"/&gt;
+                    &lt;inverse-join-column name="SUB_ID"/&gt;
+                &lt;/join-table&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+            &lt;embedded name="address"&gt;
+                &lt;attribute-override name="street"&gt;
+                   &lt;column name="STRT"/&gt;
+                &lt;/attribute-override&gt;
+                &lt;attribute-override name="city"&gt;
+                   &lt;column name="ACITY"/&gt;
+                &lt;/attribute-override&gt;
+            &lt;/embedded&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        &lt;table name="AUTH"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;column name="AID" column-definition="INTEGER64"/&gt;
+                &lt;generated-value strategy="TABLE" generator="AuthorGen"/&gt;
+                &lt;table-generator name="AuthorGen" table="AUTH_GEN" 
+                    pk-column-name="PK" value-column-name="AID"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="firstName"&gt;
+                &lt;column name="FNAME"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="lastName"&gt;
+                &lt;column name="LNAME"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            &lt;many-to-many name="arts" mapped-by="authors"&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                &lt;/cascade&gt;
+            &lt;/many-to-many&gt;
+            &lt;embedded name="address"/&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Contract"&gt;
+        &lt;table schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="JOINED"/&gt;
+        &lt;discriminator-column name="CTYPE"/&gt;
+        &lt;attributes&gt;
+            &lt;basic name="terms"&gt;
+                &lt;lob/&gt;
+            &lt;/basic&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subcribe.Subscription"&gt;
+        &lt;table name="SUB" schema="CNTRCT"/&gt;
+        &lt;inheritance strategy="SINGLE_TABLE"/&gt;
+        &lt;discriminator-value&gt;1&lt;/discriminator-value&gt;
+        &lt;discriminator-column name="KIND" discriminator-type="INTEGER"/&gt;
+        &lt;attributes&gt;
+            &lt;id name="id"&gt;
+                &lt;generated-value strategy="IDENTITY"/&gt;
+            &lt;/id&gt;
+            &lt;basic name="payment"&gt;
+                &lt;column name="PAY"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="startDate"&gt;
+                &lt;column name="START"/&gt;
+            &lt;/basic&gt;
+            &lt;version name="version"&gt;
+                &lt;column name="VERS"/&gt;
+            &lt;/version&gt;
+            &lt;one-to-many name="items"&gt;
+                &lt;map-key name="num"&gt;
+                &lt;join-table name="SUB_ITEMS" schema="CNTRCT"&gt;
+                    &lt;join-column name="SUB_ID"/&gt;
+                    &lt;inverse-join-column name="ITEM_ID"/&gt;
+                &lt;/join-table&gt;
+                &lt;cascade&gt;
+                    &lt;cascade-persist/&gt;
+                    &lt;cascade-remove/&gt;
+                &lt;/cascade&gt;
+            &lt;/one-to-many&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Subscription.LineItem"&gt;
+        &lt;table name="LINE_ITEM" schema="CNTRCT"/&gt;
+        &lt;attributes&gt;
+            &lt;basic name="comments"&gt;
+                &lt;column name="COMM"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="price"/&gt;
+            &lt;basic name="num"/&gt;
+            &lt;many-to-one name="magazine"&gt;
+                &lt;join-column name="MAG_ISBN" referenced-column-name="ISBN"/&gt;
+                &lt;join-column name="MAG_TITLE" referenced-column-name="TITLE"/&gt;
+            &lt;/many-to-one&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        &lt;discriminator-value&gt;2&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;basic name="eliteClub" fetch="LAZY"&gt;
+                &lt;column name="ELITE"/&gt;
+            &lt;/basic&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        &lt;discriminator-value&gt;3&lt;/discriminator-value&gt;
+        &lt;attributes&gt;
+            &lt;basic name="endDate"&gt;
+                &lt;column name="END"/&gt;
+            &lt;/basic&gt;
+        &lt;/attributes&gt;
+    &lt;/entity&gt;
+    &lt;embeddable class="org.mag.pub.Address"&gt;
+        &lt;attributes&gt;
+            &lt;basic name="street"/&gt;
+            &lt;basic name="city"/&gt;
+            &lt;basic name="state"&gt;
+                &lt;column column-definition="CHAR(2)"/&gt;
+            &lt;/basic&gt;
+            &lt;basic name="zip"/&gt;
+        &lt;/attributes&gt;
+    &lt;/embeddable&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+        </example>
+      </section>
+    </chapter>
+<!-- author: Abe White -->
+    <chapter id="jpa_overview_conclusion">
+      <title>Conclusion</title>
+      <para>
+	This concludes our overview of the EJB persistence specification.  The
+	<link linkend="jpa_tutorials_intro">OpenJPA EJB Tutorials</link>
+	continue your EJB education with step-by-step instructions for 
+	building simple EJB persistence applications.  The 
+	<link linkend="ref_guide_intro">OpenJPA Reference Guide</link> contains 
+	detailed documentation on all aspects of the OpenJPA EJB persistence
+	implementation and core development tools.  
+<!-- ### JDO2MIG
+	Finally,
+	the <link linkend="gui_intro">Workbench Guide</link> teaches you how to
+	use the OpenJPA Development Workbench for GUI-driven development.
+-->
+	</para>
+    </chapter>
+  </part>
+  <part id="tutorials">
+    <title>Tutorials</title>
+    <chapter id="ejb_tutorials">
+      <title>JPA Tutorials</title>
+      <section id="jpa_tutorials_intro">
+        <title>OpenJPA JPA Tutorials</title>
+        <para>
+	These tutorials provide step-by-step examples of how to use various
+	facets of the OpenJPA JPA system. They assume a general knowledge 
+	of JPA and Java. For more information on these subjects, see
+	the following URLs:
+	</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <ulink url="http://java.sun.com/">Sun's Java site</ulink>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link linkend="jpa_overview_intro">JPA Overview Document</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link linkend="jpa_resources">Links to JPA</link>
+            </para>
+          </listitem>
+        </itemizedlist>
+        <section id="jpa_tutorial_requirements">
+          <title>Tutorial Requirements</title>
+          <para>
+		These tutorials require that JDK 1.5 or greater be installed
+		on your computer, and that <literal>java</literal> and 
+		<literal>javac</literal> are in your <literal>PATH</literal> when 
+		you open a command shell.
+		</para>
+        </section>
+      </section>
+      <section id="jpa_tutorial">
+        <title>OpenJPA JPA Tutorial</title>
+        <para>
+	In this tutorial you will become familiar with the basic tools and 
+	development processes under OpenJPA by creating a simple JPA application.
+	</para>
+        <section id="jpa_tutorial_chapter1">
+          <title>The Pet Shop</title>
+          <para>
+		Imagine that you have decided to create a software toolkit to be used 
+		by pet shop operators. This toolkit must provide a number of solutions 
+		to common problems encountered at pet shops. Industry analysts indicate
+		that the three most desired features are inventory maintenance, 
+		inventory growth simulation, and behavioral analysis. Not one to 
+		question the sage advice of experts, you choose to attack these three
+		problems first.
+		</para>
+          <para>
+		According to the aforementioned experts, most pet shops focus on three 
+		types of animals only: dogs, rabbits, and snakes. This ontology 
+		suggests the following class hierarchy:
+		</para>
+          <para>
+            <screen format="linespecific">
+                       Animal
+                         ^
+                         |
+               +--------------------+
+               |         |          |
+              Dog      Rabbit     Snake
+   	    </screen>
+          </para>
+          <section id="jpa_tutorial_files">
+            <title>Included Files</title>
+            <para>
+			We have provided an implementation of <classname>Animal</classname>
+			and <classname>Dog</classname> classes, plus some helper classes 
+			and files to create the initial schema and populate the database 
+			with some sample dogs. Let's take a closer look at these classes.
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><ulink url="../../../tutorial/persistence/AnimalMaintenance.java"><classname>
+					tutorial.persistence.AnimalMaintenance</classname></ulink>:
+					Provides some utility methods for examining and 
+					manipulating the animals stored in the database. We will
+					fill in method definitions in 
+					<xref linkend="jpa_tutorial_chapter3"/>.
+					</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../../../tutorial/persistence/Animal.java"><classname>tutorial.persistence.Animal</classname></ulink>:
+					This is the superclass of all animals that this pet store 
+					software can handle.
+					</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../../../tutorial/persistence/Dog.java"><classname>tutorial.persistence.Dog</classname></ulink>: 
+					Contains data and methods specific to dogs.
+					</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../../../tutorial/persistence/Rabbit.java"><classname>tutorial.persistence.Rabbit</classname></ulink>: 
+					Contains data and 
+					methods specific to rabbits. It will be used in 
+					<xref linkend="jpa_tutorial_chapter4"/>.
+					</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../../../tutorial/persistence/Snake.java"><classname>tutorial.persistence.Snake</classname></ulink>: 
+					Contains data and 
+					methods specific to snakes. It will be used in 
+					<xref linkend="jpa_tutorial_chapter5"/>.
+					</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../../../META-INF/persistence.xml"><filename>../../META-INF/persistence.xml</filename></ulink>:
+					This XML file contains OpenJPA-specific and standard JPA 
+					configuration settings.
+					</para>
+                <para>
+					It is important to load all persistent entity classes at
+					startup so that OpenJPA can match database discriminator values
+					to entity classes.  Often this happens automatically.  
+					Some parts of this tutorial, however, do require that all 
+					entity classes be loaded explicitly.  The JPA
+					standard includes persistent class listings in its XML
+					configuration format.  Add the following lines to <filename>
+					../../META-INF/persistence.xml</filename> between the
+					<literal>&lt;provider&gt;</literal> and the
+					<literal>&lt;properties&gt;</literal> elements:
+					</para>
+                <programlisting format="linespecific">
+&lt;class&gt;tutorial.persistence.Animal&lt;/class&gt;
+&lt;class&gt;tutorial.persistence.Dog&lt;/class&gt;
+</programlisting>
+              </listitem>
+              <listitem>
+                <para><ulink url="../../../tutorial/persistence/solutions"><filename>solutions</filename></ulink>: The solutions 
+					directory contains the complete solutions to this tutorial,
+					including finished versions of the
+					<filename>.java</filename> files listed above.
+					</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="jpa_tutorial_utilities">
+            <title>Important Utilities</title>
+            <itemizedlist>
+              <listitem>
+                <para><command>java</command>: Runs main methods in specified 
+					Java classes.
+					</para>
+              </listitem>
+              <listitem>
+                <para><command>javac</command>: Compiles <filename>.java
+					</filename> files into <filename>.class</filename> 
+					files that can be executed by <command>java</command>.
+					</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>openjpac</primary></indexterm><command>openjpac</command>:
+					Runs the OpenJPA enhancer against the specified
+					classes. More information is available in
+					<xref linkend="ref_guide_pc_enhance"/> of the Reference 
+					Guide.
+					</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>mappingtool</primary></indexterm><command>mappingtool</command>: A 
+					utility that can be used to create and maintain the 
+					object-relational mappings and schema of all persistent
+					classes in a JDBC-compliant datastore.  This functionality 
+					allows the underlying mappings and schema to be easily 
+					kept up-to-date with the Java classes in the system. See 
+					<xref linkend="ref_guide_mapping"/>
+					of the Reference Guide for more information.
+					</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+        </section>
+        <section id="jpa_tutorial_chapter2">
+          <title>Getting Started</title>
+          <para>
+		Let's compile the initial classes and see them in action. To do
+		so, we must compile the <filename>.java</filename> files, as we would 
+		with any Java project, and then pass the resulting classes through
+		the OpenJPA enhancer:
+		</para>
+          <note>
+            <para><indexterm><primary>CLASSPATH</primary></indexterm>
+			Be sure that your <envar>CLASSPATH</envar> is set correctly. 
+			Note that your OpenJPA
+			install directory should be in the <envar>CLASSPATH</envar>, as
+			the tutorial classes are located in the <literal>
+			tutorial/persistence</literal> directory under your OpenJPA install 
+			directory, and are in the <literal>tutorial.persistence</literal> 
+			package.
+			</para>
+          </note>
+          <orderedlist>
+            <listitem>
+              <para>
+				Make sure you are in the <filename>
+				tutorial/persistence</filename> 
+				directory.  All examples throughout the tutorial assume that
+				you are in this directory.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Examine <filename>Animal.java</filename>,
+				<filename>Dog.java</filename>, and
+				<filename>SeedDatabase.java</filename>
+				</para>
+              <para>
+				These files are good examples of the simplicity JPA
+				engenders.  As noted earlier, persisting an object or 
+				manipulating an object's persistent data requires almost no 
+				JPA-specific code.
+				For a very simple example of creating persistent objects,
+				please see the <literal>seed</literal> method of
+				<filename>SeedDatabase.java</filename>. Note the objects are
+				created with normal Java 
+				constructors. The files <filename>Animal.java</filename> and
+				<filename>Dog.java</filename> are also good examples of
+				how JPA allows you to manipulate persistent data 
+				without writing any specific JPA code, by providing
+				simple annotations.
+				</para>
+              <para>
+				Let's take a look at the <filename>Animal.java</filename> file.
+				Notice that the class is a Plain Old Java Object (POJO), with
+				several annotations describing how the class is mapped into
+				a relational database.  First, let's examine the class level
+				annotations:
+				</para>
+              <programlisting format="linespecific">
+@Entity(name="Animal")
+@Table(name="JPA_TUT_ANIMAL")
+@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
+@DiscriminatorColumn(name="SPECIES", length=100)
+public abstract class Animal
+{
+    ...
+}
+</programlisting>
+              <para>
+				The annotations serve to map the class into the database.  For
+				more information on these and other annotations, see
+				<xref linkend="jpa_overview_meta"/> and
+				<xref linkend="jpa_overview_mapping"/>.
+				</para>
+              <orderedlist>
+                <listitem>
+                  <para><command>@Entity</command>: This annotation indicates
+						that instances of this class may be persistent entities.
+						The value of the <command>name</command> attribute is
+						the entity name, and is used in queries, etc.
+						</para>
+                </listitem>
+                <listitem>
+                  <para><command>@Table</command>: This annotation is used
+						to map the entity to a primary table.  The value of the
+						<command>name</command> attribute specifies the name
+						of the relational table to use as the primary table.
+						</para>
+                </listitem>
+                <listitem>
+                  <para><command>@Inheritance</command>: When multiple classes
+						in an inheritance hierarchy are persistent entity types,
+						it is important to describe how the inheritance
+						hierarchy is mapped.  Setting the value of the
+						<command>strategy</command> attribute to
+						<command>InheritanceType.SINGLE_TABLE</command>
+						indicates that the primary table for all subclasses
+						shall be the same table as for the superclass.
+						</para>
+                </listitem>
+                <listitem>
+                  <para><command>@DiscriminatorColumn</command>: With a
+						<command>SINGLE_TABLE</command> inheritance mapping
+						strategy, instances of multiple classes will be stored
+						in the same table.  This annotation describes a column
+						in that table that is used to determine the type of
+						an instance whose data is stored in a particular row.
+						The <command>name</command> attribute is the name of
+						the column, and the <command>length</command> attribute
+						indicates the size of the column.  By default, the
+						unqualified class name for the instance is stored
+						in the discriminator column.  To store a different
+						value for a type, use the <command>@DiscriminatorValue
+						</command> annotation.
+						</para>
+                </listitem>
+              </orderedlist>
+              <para>
+				Let's take a look at our class' field annotations.
+				We have chosen to use <emphasis>field access</emphasis> for
+				our entities, meaning the persistence implementation will 
+				get and set persistent state directly through our class'
+				declared fields.  We could have chosen to use <emphasis>
+				property access</emphasis>, in which the implementation 
+				accesses persistent state through our JavaBean getter and
+				setter methods.  In that case, we would have annotated our
+				getter methods rather than our fields.
+				</para>
+              <programlisting format="linespecific">
+@Id
+@GeneratedValue
+@Column(name="ID")
+private long id;
+
+@Basic @Column(name="ANIMAL_NAME")
+private String name = null;
+
+@Basic @Column(name="COST")
+private float price = 0f;
+</programlisting>
+              <para>
+				The annotations serve to map the fields into the database.  For
+				more information on these and other annotations, see
+				<xref linkend="jpa_overview_meta"/>.
+				</para>
+              <orderedlist>
+                <listitem>
+                  <para><command>@Id</command>: This annotation indicates that
+						the field is to be mapped to a primary key column in
+						the database.  
+						</para>
+                </listitem>
+                <listitem>
+                  <para><command>@GeneratedValue</command>:
+						Indicates that the implementation will generate a 
+						value for the field automatically.
+						</para>
+                </listitem>
+                <listitem>
+                  <para><command>@Column</command>: This annotation describes
+						the column to which the field will be mapped.  The
+						<command>name</command> attribute specifies the name
+						of the column.
+						</para>
+                </listitem>
+                <listitem>
+                  <para><command>@Basic</command>: This annotation indicates
+						that the field is simply mapped into a column.  There
+						are other annotations that indicate entity
+						relationships and other more complex mappings.
+						</para>
+                </listitem>
+              </orderedlist>
+            </listitem>
+            <listitem>
+              <para>Compile the <filename>.java</filename> files.</para>
+              <programlisting format="linespecific">
+javac *.java
+</programlisting>
+              <para>
+				You can use any java compiler instead of 
+				<command>javac</command>.
+				</para>
+            </listitem>
+            <listitem>
+              <para>Enhance the persistent classes.</para>
+              <programlisting format="linespecific">
+openjpac -p persistence.xml Animal.java Dog.java
+</programlisting>
+              <para>
+				This step runs the OpenJPA enhancer on the 
+				<filename>Animal.java</filename> and
+				<filename>Dog.java</filename> files mentioned above.
+				See <xref linkend="ref_guide_pc_enhance"/> of the Reference 
+				Guide for more information on the enhancer, including how to
+				use automatic runtime enhancement.
+				</para>
+              <note>
+                <para>
+					The <literal>-p</literal> flag points the enhancer to your
+					<filename>persistence.xml</filename> configuration file.
+					All OpenJPA JPA tools look for default configuration in a
+					resource called <filename>openjpa.xml</filename> or
+					<filename>META-INF/openjpa.xml</filename>.  Thus you
+					can avoid passing the <literal>-p</literal> argument to
+					tools by using this configuration file name in place of
+					<filename>persistence.xml</filename>.  See
+					<xref linkend="ref_guide_conf"/> in the Reference Guide
+					for details on OpenJPA configuration.
+					</para>
+              </note>
+            </listitem>
+          </orderedlist>
+          <section id="jpa_tutorial_chapter2_datastore">
+            <title>Configuring the Datastore</title>
+            <para>
+			Now that we've compiled the source files and enhanced the
+			persistent classes, we're ready to set up the database. 
+			<ulink url="http://hsqldb.sourceforge.net">Hypersonic SQL</ulink>,
+			a pure Java relational database, is included in the OpenJPA 
+			distribution. 
+			We have included this database because it is simple to set up and 
+			has a small memory footprint; however, you can use this tutorial 
+			with any of the relational databases that we support.  You can also
+			write your own plugin for any database that we do not support. For 
+			the sake of simplicity, this tutorial only describes how to set up
+			connectivity to a Hypersonic SQL database. For more
+			information on how to connect to a different database or
+			how to add support for other databases, see
+			<xref linkend="ref_guide_dbsetup"/> of the 
+			Reference Guide.
+			</para>
+            <orderedlist>
+              <listitem>
+                <para><indexterm><primary>mappingtool</primary></indexterm>
+					Create the object-relational mappings and database schema.
+					</para>
+                <programlisting format="linespecific">
+mappingtool -p persistence.xml Animal.java Dog.java
+</programlisting>
+                <para>
+					This command propagates the necessary schema for the
+					specified classes to the database configured in 
+					<filename>persistence.xml</filename>.  If you are 
+					using the default Hypersonic SQL setup, the first time you 
+					run the mapping tool Hypersonic will create
+					<filename>tutorial_database.properties</filename> and
+					<filename>tutorial_database.script</filename> database
+					files in your current directory.  To 
+					delete the database, just delete these files.
+					</para>
+                <para>
+					By default, JPA uses object-relational mapping
+					information stored in annotations in your source files.
+					<xref linkend="jpa_overview_mapping"/> of the
+					JPA Overview will help you understand mapping
+					annotations.
+					Additionally, <xref linkend="ref_guide_mapping"/> of the 
+					Reference Guide describes your other mapping options in 
+					detail.
+					</para>
+                <para>
+					</para>
+                <para>
+					If you are curious, you can view the schema OpenJPA 
+					created for the tutorial classes with OpenJPA's schema tool: 
+					</para>
+                <programlisting format="linespecific">
+schematool -p persistence.xml -a reflect -f tmp.schema
+</programlisting>
+                <para>
+					This will create a <filename>tmp.schema</filename> file
+					with an XML representation of the database schema.  The
+					XML should be self explanatory; see
+					<xref linkend="ref_guide_schema_xml"/>
+					of the Reference Guide for details.  You may delete the
+					<filename>tmp.schema</filename> file before proceeding.
+					</para>
+              </listitem>
+              <listitem>
+                <para>Populate the database with sample data.</para>
+                <programlisting format="linespecific">
+java tutorial.persistence.SeedDatabase
+</programlisting>
+              </listitem>
+            </orderedlist>
+            <para>
+			Congratulations! You have now created an JPA-accessible
+			persistent store, and seeded it with some sample data.
+			</para>
+          </section>
+        </section>
+        <section id="jpa_tutorial_chapter3">
+          <title>Inventory Maintenance</title>
+          <para>
+		The most important element of a successful pet store product, say the 
+		experts, is an inventory maintenance mechanism. So, let's work on the 
+		<classname>Animal</classname> and <classname>Dog</classname> classes a
+		bit to permit user interaction with the database.
+		</para>
+          <para>
+		This chapter should familiarize you with some of the basics of the 
+		<ulink url="../../ejb-3_0-pr-spec-persistence.pdf">JPA 
+		specification</ulink> and the mechanics of compiling and enhancing 
+		persistent classes. You will also become familiar with the mapping 
+		tool for propagating the persistent schema into the database.
+		</para>
+          <para>
+		First, let's add some code to
+		<filename>AnimalMaintenance.java</filename> that allows us to examine
+		the animals currently in the database. 
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				Add code to <filename>AnimalMaintenance.java</filename>.
+				</para>
+              <para>
+				Modify the <methodname>getAnimals</methodname> method of 
+				<filename>AnimalMaintenance.java</filename> to look like this:
+				</para>
+              <programlisting format="linespecific">
+    /**
+     *  Return a list of animals that match the specified query filter.
+     *
+     *  @param  filter      the JPQL filter to apply to the query
+     *  @param  cls         the class of animal to query on
+     *  @param  em          the EntityManager to obtain the query from
+     */
+    public static List getAnimals (String filter, EntityManager em)
+    {
+        // Execute a query for the specified filter.
+        Query query = em.createQuery (filter);
+        return query.getResultList ();
+    }
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>
+				Compile <filename>AnimalMaintenance.java</filename>.
+				</para>
+              <programlisting format="linespecific">
+javac AnimalMaintenance.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>Take a look at the animals in the database.</para>
+              <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance list Animal
+</programlisting>
+              <para>
+				Notice that <methodname>list</methodname> optionally takes a
+				query filter. Let's explore the database some more, this time 
+				using filters:
+				</para>
+              <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance list "select a from Animal a where a.name = 'Binney'"
+java tutorial.persistence.AnimalMaintenance list "select a from Animal a where a.price &lt;= 50"
+</programlisting>
+              <para>
+				The Java Persistence Query Language (JPQL) is designed to look 
+				and behave much like an object oriented SQL dialect. The
+				<literal>name</literal> and <literal>price</literal> fields
+				identified in the above queries map to the member fields of
+				those names in <classname>
+				tutorial.persistence.Animal</classname>.  
+				More details on JPQL syntax is available in
+				<xref linkend="jpa_overview_query"/> of the JPA Overview.  
+				</para>
+            </listitem>
+          </orderedlist>
+          <para>
+		Great! Now that we can see the contents of the database,
+		let's add some code that lets us add and remove animals.
+		</para>
+          <section id="jpa_tutorial_chapter3_persist">
+            <title>Persisting Objects</title>
+            <para>
+			As new dogs are born or acquired, the store owner will
+			need to add new records to the inventory database. In this
+			section, we'll write the code to handle additions through
+			the <classname>tutorial.persistence.AnimalMaintenance</classname> 
+			class.
+			</para>
+            <para>
+			This section will familiarize you with the mechanism for
+			storing persistent instances in a JPA entity
+			manager. We will create a new dog, obtain a
+			<classname>Transaction</classname> from a 
+			<classname>EntityManager</classname>, and, within the 
+			transaction, make the new dog object persistent.
+			</para>
+            <para><classname>tutorial.persistence.AnimalMaintenance</classname> 
+			provides a reflection-based facility for creating any type of 
+			animal, provided that the animal has a two-argument constructor
+			whose first argument corresponds to the name of the animal
+			and whose second argument is an implementation-specific 
+			primitive. This reflection-based system is in place to keep this 
+			tutorial short and remove repetitive creation mechanisms. It is 
+			not a required part of the JPA specification.
+			</para>
+            <orderedlist>
+              <listitem>
+                <para>Add the following code to <filename>
+					AnimalMaintenance.java</filename>.
+					</para>
+                <para>
+					Modify the <methodname>persistObject</methodname> method of 
+					<filename>AnimalMaintenance.java</filename> to look like 
+					this:
+					</para>
+                <programlisting format="linespecific">
+    /**
+     *  Performs the actual JPA work of putting &lt;code&gt;object&lt;/code&gt;
+     *  into the data store.
+     *
+     *  @param  object  the object to persist in the data store
+     */
+    public static void persistObject (EntityManager em, Object object)
+    {
+        // Mark the beginning of the unit of work boundary.
+        em.getTransaction ().begin ();
+
+        em.persist (object);
+
+        // Mark the end of the unit of work boundary,
+        // and record all inserts in the database.
+        em.getTransaction ().commit ();
+        System.out.println ("Added " + object);
+    }
+</programlisting>
+                <note>
+                  <para>In the above code, we pass in an
+					<classname>EntityManager</classname>.
+					<classname>EntityManager</classname>s may be either
+					container managed or application managed.  In this tutorial,
+					because we're operating outside a container, we're using
+					application managed <classname>EntityManager</classname>s.
+					In managed environments,
+					<classname>EntityManager</classname>s are typically
+					container managed, and thus injected or looked up via JNDI.
+					Application managed <classname>EntityManager</classname>s
+					can be used in both managed and unmanaged environments, and
+					are created by an
+					<classname>EntityManagerFactory</classname>.  An
+					<classname>EntityManagerFactory</classname> can be obtained
+					from the
+					<classname>javax.persistence.Persistence</classname> class.
+					This class provides some convenience methods for
+					obtaining an <classname>EntityManagerFactory</classname>.
+					</para>
+                </note>
+              </listitem>
+              <listitem>
+                <para>
+					Recompile <filename>AnimalMaintenance.java</filename>.
+					</para>
+                <programlisting format="linespecific">
+javac AnimalMaintenance.java
+</programlisting>
+              </listitem>
+            </orderedlist>
+            <para>
+			You now have a mechanism for adding new dogs to the database. Go 
+			ahead and add some by running
+			<command>java tutorial.persistence.AnimalMaintenance add Dog &lt;name&gt; &lt;price&gt;</command> 
+			For example:
+			</para>
+            <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance add Dog Fluffy 35
+</programlisting>
+            <para>
+			You can view the contents of the database with:
+			</para>
+            <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance list Dog
+</programlisting>
+          </section>
+          <section id="jpa_tutorial_chapter3_delete">
+            <title>Deleting Objects</title>
+            <para>
+			What if someone decides to buy one of the dogs? The store owner 
+			will need to remove that animal from the database, since it is no 
+			longer in the inventory. 
+			</para>
+            <para>
+			This section demonstrates how to remove data from the datastore.
+			</para>
+            <orderedlist>
+              <listitem>
+                <para>
+					Add the following code to <filename>AnimalMaintenance.java
+					</filename>.
+					</para>
+                <para>
+					Modify the <methodname>deleteObjects</methodname> method of 
+					<filename>AnimalMaintenance.java</filename> to look like 
+					this:
+					</para>
+                <programlisting format="linespecific">
+    /**
+     *  Performs the actual JPA work of removing 
+     *  &lt;code&gt;objects&lt;/code&gt; from the datastore.
+     *
+     *  @param  objects     the objects to persist in the datastore
+     *  @param  em          the EntityManager to delete with
+     */
+    public static void deleteObjects (Collection objects, EntityManager em)
+    {
+        // Mark the beginning of the unit of work boundary.
+        em.getTransaction ().begin ();
+
+        // This method removes the objects in 'objects' from the data store.
+        for (Object ob : objects)
+        {
+            System.out.println ("Removed animal: " + ob);
+            em.remove (ob);
+        }
+
+        // Mark the end of the unit of work boundary, and record all
+        // deletes in the database.
+        em.getTransaction ().commit ();
+    }
+</programlisting>
+              </listitem>
+              <listitem>
+                <para>
+					Recompile <filename>AnimalMaintenance.java</filename>.
+					</para>
+                <programlisting format="linespecific">
+javac AnimalMaintenance.java
+</programlisting>
+              </listitem>
+              <listitem>
+                <para>Remove some animals from the database.</para>
+                <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance remove &lt;query&gt;
+</programlisting>
+                <para>
+					Where <replaceable>&lt;query&gt;</replaceable> is a query 
+					string like those used for listing animals above.
+					</para>
+              </listitem>
+            </orderedlist>
+            <para>
+			All right. We now have a basic pet shop inventory
+			management system. From this base, we will add some of the
+			more advanced features suggested by our industry experts.
+			</para>
+          </section>
+        </section>
+        <section id="jpa_tutorial_chapter4">
+          <title>Inventory Growth</title>
+          <para>
+		Now that we have the basic pet store framework in place, let's add 
+		support for the next pet in our list: the rabbit. The rabbit is a bit 
+		different than the dog; pet stores sell them all for the same price, 
+		but gender is critically important since rabbits reproduce rather 
+		easily and quickly. Let's put together a class representing a rabbit.
+		</para>
+          <para>
+		In this chapter, you will see some more queries and write a 
+		bidirectional relation between objects.
+		</para>
+          <para>
+		Provided with this tutorial is a file called 
+		<filename>Rabbit.java</filename> which contains a sample 
+		<classname>Rabbit</classname> implementation. 
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				Examine <filename>Rabbit.java</filename>.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				The Rabbit class above contains a bidirectional 
+				relationship between parents and children. From the Java side 
+				of things, a bidirectional relationship is simply a
+				pair of fields that are conceptually linked. There is no 
+				special Java work necessary to express bidirectionality. 
+				However, you must identify the relationship as bidirectional
+				using JPA <link linkend="jpa_overview_meta">
+				annotations</link> so the mapping tool can create the most 
+				efficient schema.
+				</para>
+              <para>
+				Insert this snippet of code immediately
+				<emphasis>before</emphasis> the <literal>children</literal>
+				field declaration in the <filename>Rabbit.java</filename> file.
+				</para>
+              <programlisting format="linespecific">
+    @ManyToMany
+    @JoinTable(name="RABBIT_CHILDREN",
+        joinColumns=@JoinColumn(name="PARENT_ID"),
+        inverseJoinColumns=@JoinColumn(name="CHILD_ID"))
+</programlisting>
+              <para>
+				The <literal>@ManyToMany</literal> annotation indicates that
+				<literal>children</literal> is one side of a many-to-many 
+				relation.  <literal>@JoinTable</literal> describes how this 
+				relation maps to a database join table.  The annotation's 
+				<literal>joinColumns</literal> name the join table's foreign 
+				key columns linking to the owning instance (the parent).  In 
+				this case, column <literal>RABBIT_CHILDREN.PARENT_ID</literal> 
+				is a foreign key to the parent's <literal>ID</literal> primary 
+				key column.  Similarly, the <literal>inverseJoinColumns
+				</literal> attribute denotes the foreign key columns linking to
+				the collection elements (the children).
+				For more details on the <literal>@JoinTable</literal>
+				annotation, see <xref linkend="jpa_overview_mapping"/> of the 
+				JPA Overview.  
+				</para>
+              <para>
+				Now we'll map the other side of this bidirectional relation,
+				the <literal>parents</literal> field.
+				Insert the following snippet of code immediately
+				<emphasis>before</emphasis> the <command>parents</command>
+				field declaration in the <filename>Rabbit.java</filename> file.
+				The <literal>mappedBy</literal> attribute identifies the name
+				of the owning side of the relation.
+				</para>
+              <programlisting format="linespecific">
+    @ManyToMany(mappedBy="children")
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>
+				Compile <filename>Rabbit.java</filename>.
+				</para>
+              <programlisting format="linespecific">
+javac Rabbit.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>
+				Enhance the <classname>Rabbit</classname> class.
+				</para>
+              <programlisting format="linespecific">
+openjpac -p persistence.xml Rabbit.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>
+				Refresh the object-relational mappings and database schema.
+				</para>
+              <programlisting format="linespecific">
+mappingtool -p persistence.xml Rabbit.java
+</programlisting>
+            </listitem>
+          </orderedlist>
+          <para>
+		Now that we have a Rabbit class, let's get some preliminary rabbit 
+		data into the database. 
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				Add a <literal>&lt;class&gt;</literal> entry for <classname>
+				Rabbit</classname> to 
+				<filename>../../META-INF/persistence.xml</filename>.
+				</para>
+              <programlisting format="linespecific">
+&lt;class&gt;tutorial.persistence.Rabbit&lt;/class&gt;
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>Create some rabbits.</para>
+              <para>
+				Run the following commands a few times to add some male
+				and female rabbits to the database:
+				</para>
+              <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance add Rabbit &lt;name&gt; false
+java tutorial.persistence.AnimalMaintenance add Rabbit &lt;name&gt; true
+</programlisting>
+              <para>
+				Now run some breeding iterations.
+				</para>
+              <programlisting format="linespecific">
+java tutorial.persistence.Rabbit breed 2
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>Look at your new rabbits.</para>
+              <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance list Rabbit
+java tutorial.persistence.AnimalMaintenance details "select r from Rabbit r where r.name = '&lt;name&gt;'"
+</programlisting>
+            </listitem>
+          </orderedlist>
+        </section>
+        <section id="jpa_tutorial_chapter5">
+          <title>Behavioral Analysis</title>
+          <para>
+		Often, pet stores sell snakes as well as rabbits and dogs.  Pet stores 
+		are primarily concerned with a snake's length; much like rabbits, pet 
+		store operators usually sell them all for a flat rate.
+		</para>
+          <para>
+		This chapter demonstrates more queries, schema manipulation, 
+		and additional relation types.
+		</para>
+          <para>
+		Provided with this tutorial is a file called <filename>Snake.java
+		</filename> which contains a sample <classname>Snake</classname> 
+		implementation. Let's get it compiled and loaded:
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				Examine and compile <filename>Snake.java</filename>.
+				</para>
+              <programlisting format="linespecific">
+javac Snake.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>Enhance the class.</para>
+              <programlisting format="linespecific">
+openjpac -p persistence.xml Snake.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>Refresh the mappings and database.</para>
+              <para>
+				As we have created a new persistent class, we must 
+				map it to the database and change the schema to match.  So
+				run the mapping tool:
+				</para>
+              <programlisting format="linespecific">
+mappingtool -p persistence.xml Snake.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>
+				Add a <literal>&lt;class&gt;</literal> entry for <classname>
+				Snake</classname> to 
+				<filename>../../META-INF/persistence.xml</filename>.
+				</para>
+              <programlisting format="linespecific">
+&lt;class&gt;tutorial.persistence.Snake&lt;/class&gt;
+</programlisting>
+            </listitem>
+          </orderedlist>
+          <para>
+		Once you have compiled everything, add a few snakes to the database 
+		using:
+		</para>
+          <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance add Snake "name" &lt;length&gt;
+</programlisting>
+          <para>
+		Where <replaceable>&lt;length&gt;</replaceable> is the length in feet 
+		for the new snake. To see the new snakes in the database, run:
+		</para>
+          <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance list Snake
+</programlisting>
+          <para>
+		Unfortunately for the massively developing rabbit population, snakes 
+		often eat rabbits. Any good inventory system should be able to capture 
+		this behavior. So, let's add some code to <filename>Snake.java
+		</filename> to support the snake's eating behavior.
+		</para>
+          <para>
+		First, let's modify <filename>Snake.java</filename> to contain a
+		list of eaten rabbits.
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				Add the following code snippets to
+				<filename>Snake.java</filename>.
+				</para>
+              <programlisting format="linespecific">
+    // This list will be persisted into the database as
+    // a one-to-many relation.
+    @OneToMany(mappedBy="eater")
+    private Set&lt;Rabbit&gt; giTract = new HashSet&lt;Rabbit&gt; ();
+</programlisting>
+              <para>
+				Note that we specified a <literal>mappedBy</literal>
+				attribute in this example. This is because the relation is 
+				bidirectional; that is, the rabbit has knowledge of which 
+				snake ate it. We could have left out the 
+				<literal>eater</literal> field and instead created a 
+				standard unidirectional relation.  In fact, in a bidirectional
+				many-to-one relation, the many side must always be the owner.
+				</para>
+              <para>
+				For more information on types of relations, see 
+				<xref linkend="jpa_overview_mapping_field"/> of the 
+				JPA Overview.
+				</para>
+              <para>
+    			Modify the <literal>toString (boolean)</literal> method to
+				output the giTract list.
+				</para>
+              <programlisting format="linespecific">
+    public String toString (boolean detailed)
+    {
+        StringBuffer buf = new StringBuffer (1024);
+        buf.append ("Snake ").append (getName ());
+
+        if (detailed)
+        {
+            buf.append (" (").append (length).append (" feet long) sells for ");
+            buf.append (getPrice ()).append (" dollars.");
+            buf.append ("  Its gastrointestinal tract contains:\n");
+            for (Rabbit rabbit : giTract)
+                buf.append ("\t").append (rabbit).append ("\n");
+        }
+        else
+            buf.append ("; ate " + giTract.size () + " rabbits.");
+
+        return buf.toString ();
+    }
+</programlisting>
+              <para>
+				Add the following methods.
+				</para>
+              <programlisting format="linespecific">
+    /**
+     *  Kills the specified rabbit and eats it.
+     */
+    public void eat (Rabbit dinner)
+    {
+        // Consume the rabbit.
+        dinner.kill ();
+        dinner.setEater (this);
+        giTract.add (dinner);
+        System.out.println ("Snake " + getName () + " ate rabbit " 
+            + dinner.getName () + ".");
+    }
+
+
+    /**
+     *  Locates the specified snake and tells it to eat a rabbit.
+     */
+    public static void eat (EntityManager em, String filter)
+    {
+        em.getTransaction ().begin ();
+
+        // Find the desired snake(s) in the data store.
+        Query query = em.createQuery (filter);
+        List&lt;Snake&gt; results = query.getResultList ();
+        if (results.isEmpty ())
+        {
+            System.out.println ("No snakes matching '" + filter + "' found");
+            return;
+        }
+
+        Query uneatenQuery = em.createQuery
+            ("select r from Rabbit r where r.isDead = false");
+        Random random = new Random ();
+        for (Snake snake : results)
+        {
+            // Run a query for a rabbit whose 'isDead' field indicates
+            // that it is alive.
+            List&lt;Rabbit&gt; menu = uneatenQuery.getResultList ();
+            if (menu.isEmpty ())
+            {
+                System.out.println ("No live rabbits in DB.");
+                break;
+            }
+
+            // Select a random rabbit from the list.
+            Rabbit dinner = menu.get (random.nextInt (menu.size ()));
+
+            // Perform the eating.
+            System.out.println (snake + " is eating:");
+            snake.eat (dinner);
+        }
+
+        em.getTransaction ().commit ();
+    }
+
+
+    public static void main (String[] args)
+    {
+        if (args.length == 2 &amp;&amp; args[0].equals ("eat"))
+        {
+            EntityManagerFactory emf = Persistence.
+                createEntityManagerFactory (null);
+            EntityManager em = emf.createEntityManager ();
+            eat (em, args[1]);
+            em.close ();
+            emf.close ();
+            return;
+        }
+
+        // If we get here, something went wrong.
+        System.out.println ("Usage:");
+        System.out.println ("  java tutorial.persistence.Snake eat "
+            + "\"snakequery\"");
+    }
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>
+				Add an <literal>eater</literal> field to 
+				<filename>Rabbit.java</filename>, and a getter and setter.
+				</para>
+              <programlisting format="linespecific">
+    @ManyToOne @JoinColumn(name="EATER_ID")
+    private Snake eater;
+
+    ...
+
+    public Snake getEater ()
+    {
+        return eater;
+    }
+
+
+    public void setEater (Snake snake)
+    {
+        eater = snake;
+    }
+</programlisting>
+              <para>
+				The <literal>@ManyToOne</literal> annotation indicates that this
+				is the many side of the bidirectional relation.  The many side
+				must always be the owner in this type of relation.  The
+				<literal>@JoinColumn</literal> describes the foreign key
+				that joins the rabbit table to the snake table.  The rabbit
+				table has an <literal>EATER_ID</literal> column that is a
+				foreign key to the <literal>ID</literal> primary key column
+				of the snake table.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Compile <filename>Snake.java</filename> and 
+				<filename>Rabbit.java</filename> and enhance the classes.
+				</para>
+              <programlisting format="linespecific">
+javac Snake.java Rabbit.java
+openjpac -p persistence.xml Snake.java Rabbit.java
+</programlisting>
+            </listitem>
+            <listitem>
+              <para>Refresh the mappings and database.</para>
+              <programlisting format="linespecific">
+mappingtool -p persistence.xml Snake.java Rabbit.java
+</programlisting>
+            </listitem>
+          </orderedlist>
+          <para>
+		Now, experiment with the following commands:
+		</para>
+          <programlisting format="linespecific">
+java tutorial.persistence.Snake eat "select s from Snake s where s.name = '&lt;name&gt;'"
+java tutorial.persistence.AnimalMaintenance details "select s from Snake s where s.name = '&lt;name&gt;'"
+</programlisting>
+          <section id="jpa_tutorial_chapter5_query">
+            <title>Complex Queries</title>
+            <para>
+			Imagine that one of the snakes in the database was named Killer. 
+			To find out which rabbits Killer ate, we could run either of the 
+			following two queries:
+			</para>
+            <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance details "select s from Snake s where s.name = 'Killer'"
+java tutorial.persistence.AnimalMaintenance list "select r from Rabbit r where r.eater.name = 'Killer'"
+</programlisting>
+            <para>
+			The first query is snake-centric - the query runs against the 
+			<classname>Snake</classname> class, looking for all snakes named
+			Killer and providing a detailed listing of them. The second is 
+			rabbit-centric - it examines the rabbits in the database for 
+			instances whose <literal>eater</literal> is named Killer.
+			This second query demonstrates the that simple java 'dot' syntax
+			is used when traversing an to-one field in a query.
+			</para>
+            <para>
+			It is also possible to traverse collection fields.  Imagine that 
+			there was a rabbit called Roger in the datastore and that one of 
+			the snakes ate it. In order to determine who ate Roger Rabbit, you 
+			could run a query like this:
+			</para>
+            <programlisting format="linespecific">
+java tutorial.persistence.AnimalMaintenance details "select s from Snake s inner join s.giTract r where r.name = 'Roger'"
+</programlisting>
+          </section>
+        </section>
+        <section id="jpa_tutorial-chapter6">
+          <title>Extra Features</title>
+          <para>
+		Congratulations! You are now the proud author of a pet store inventory 
+		suite. Now that you have all the major features of the pet store 
+		software implemented, it's time to add some extra features. You're on 
+		your own; think of some features that you think a pet store should have,
+		or just explore the features of JPA.
+		</para>
+          <para>
+		Here are a couple of suggestions to get you started:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para>Animal pricing.</para>
+              <para>
+				Modify <classname>Animal</classname> to contain an inventory 
+				cost and a resale price.  Calculate the real dollar amount 
+				eaten by the snakes (the sum of the inventory costs of all the 
+				consumed rabbits), and the cost assuming that all the eaten 
+				rabbits would have been sold had they been alive. Ignore the 
+				fact that the rabbits, had they lived, would have created more 
+				rabbits, and the implications of the reduced food costs due to 
+				the not-quite-as-hungry snakes and the smaller number of 
+				rabbits.
+				</para>
+            </listitem>
+            <listitem>
+              <para>Dog categorization.</para>
+              <para>
+   	   			Modify <classname>Dog</classname> to have a
+				relation to a new class called <classname>Breed</classname>, 
+				which contains a name identifying the breed of the dog and a 
+				description of the breed. Put together an admin tool for
+   	   			breeds and for associating dogs and breeds.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+<!-- ### EJBDOC 
+			&ejb3-reverse-tutorial.xml;
+	-->
+      <section id="jpa_j2ee_tutorial">
+        <title>J2EE Tutorial</title>
+        <para>
+	By deploying OpenJPA into a J2EE environment, you can maintain the 
+	simplicity and performance of OpenJPA, while leveraging J2EE 
+	technologies such as container managed transactions (JTA/JTS), 
+	enterprise objects with remote invocation (EJB), and managed 
+	deployment of multi-tiered applications via an application 
+	server.  This tutorial will demonstrate how to deploy OpenJPA-based 
+	J2EE applications and showcase some basic enterprise JPA
+	design techniques. The tutorial's sample application models
+	a basic garage catalog system.  While the application is 
+	relatively trivial, the code has been constructed to illustrate 
+	simple patterns and solutions to common problems when using 
+	OpenJPA in an enterprise environment.
+	</para>
+        <section id="jpa_j2ee_tutorial_requirements">
+          <title>Prerequisites for the OpenJPA J2EE Tutorial</title>
+          <para>
+		This tutorial assumes that you have installed OpenJPA and 
+		setup your classpath according to the installation instructions 
+		appropriate for your platform.  In addition, this 
+		tutorial requires that you have installed and configured a 
+		J2EE-compliant application server, such as WebLogic or JBoss,
+		running on JDK 1.5.  If you use a different
+		application server not listed here, this tutorial may be adaptable to 
+		your application server with small changes; refer to your application
+		server's documentation for any specific classpath and deployment 
+		descriptor requirements. 
+		</para>
+          <para>
+		This tutorial assumes a reasonable level of experience with 
+		OpenJPA and JPA.  We provide a number of other 
+		tutorials for basic concepts, including enhancement, schema 
+		mapping, and configuration.  This tutorial also assumes a 
+		basic level of experience with J2EE components, including 
+		session beans, JNDI, JSP, and EAR/WAR/JAR packaging.  Sun and/or 
+		your application server company may provide tutorials to get 
+		familiar with these components.
+		</para>
+          <para>
+		In addition, this tutorial uses Ant to build the deployment 
+		archives.  While this is the preferred way of building
+		a deployment of the tutorial, one can easily build the 
+		appropriate JAR, WAR, and EAR files by hand, although that 
+		is outside the scope of this document.
+		</para>
+        </section>
+        <section id="jpa_j2ee_tutorial_installation_types">
+          <title>J2EE Installation Types</title>
+          <para>
+		Every application server has a different installation process 
+		for installing J2EE components.  OpenJPA can be installed in a 
+		number of ways, which may or may not be appropriate to your 
+		application server.  While this document focuses mainly upon 
+		using OpenJPA as a JCA resource,  there are other ways to use 
+		OpenJPA in a J2EE environment.
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>JPA</literal>:  J2EE 5 allows for the
+				automatic injection of 
+				<classname>EntityManager</classname> instances
+				into the J2EE context. 
+				<!-- ### EJBDOC ###--></para>
+            </listitem>
+            <listitem>
+              <para><literal>JCA</literal>:  OpenJPA implements the 
+				JCA 1.0 spec, and the openjpa-persistence.rar file that comes in 
+				the <filename>jca/persistence</filename> directory of the 
+				distribution can be installed as any other JCA connection 
+				resource.  This is the preferred way to integrate OpenJPA into a 
+				pre-J2EE 5 environment.  It allows for simple installation 
+				(usually involving uploading or copying openjpa-persistence.rar 
+				into the application server's deployment directory), and 
+				guided configuration on many appservers<!--
+				doesn't work yet , as well as dynamic reloading 
+				for upgrading OpenJPA to a newer version-->.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Manual Binding into JNDI: Your application may require
+				some needs in initializing OpenJPA that go beyond the 
+				JPA and JCA specifications.  In this case, you can
+				manually instantiate OpenJPA and place it into the JNDI tree.
+				This process, however, is not seamless and can require a 
+				fair bit of custom application server code to bind an 
+				instance of 
+				<classname>org.apache.openjpa.persistence.EntityManagerFactoryImpl</classname>
+				into JNDI. 
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_j2ee_tutorial_installing_sample">
+          <title>Installing the J2EE Sample Application</title>
+          <para>
+		Installing the sample application involves first compiling
+		and building a deployment archive (.ear) file.  This file
+		then needs to be deployed into your application server.
+		</para>
+          <section id="jpa_j2ee_tutorial_building_sample">
+            <title>Compiling and Building The Sample Application</title>
+            <para>
+			Navigate to the <filename>samples/persistence/j2ee</filename> 
+			directory of your OpenJPA installation.
+			</para>
+            <para>
+			Ensure that the JNDI name in the setSessionContext() method in
+			ejb/CarBean.java matches your JCA installation. This defaults to
+			<literal>java:/openjpa-ejb</literal>, but the actual value will depend
+			on the configuration of your JCA deploy and your application 
+			server's JNDI context.  E.g. the default name for a WebLogic 9 
+			install would be simply <literal>openjpa-ejb</literal>.
+			</para>
+            <para>
+			Compile the source files in place both in this base directory 
+			as well as the nested <filename>ejb</filename> and 
+			<filename>jsp</filename> directories:
+			</para>
+            <programlisting format="linespecific">
+javac *.java  ejb/*.java jsp/*.java
+</programlisting>
+            <para>
+			Enhance the Car class. 
+			</para>
+            <programlisting format="linespecific">
+openjpac -p persistence.xml Car.java
+</programlisting>
+            <para>
+			Run the mapping tool; make sure that your <filename>
+			META-INF/persistence.xml</filename> file includes the same 
+			connection information (e.g. Driver, URL, etc.) as your 
+			JCA installation.  You should update your JCA configuration
+			to include <classname>samples.persistence.j2ee.Car</classname>
+			in the <link linkend="openjpa.MetaDataFactory">MetaDataFactory</link> 
+			property:
+			</para>
+            <programlisting format="linespecific">
+&lt;config-property name="MetaDataFactory"&gt;Types=samples.persistence.j2ee.Car&lt;/config-property/&gt;
+</programlisting>
+            <programlisting format="linespecific">
+mappingtool -p persistence.xml Car.java
+</programlisting>
+            <para>
+			Build an J2EE application archive by running Ant against the 
+			<filename>build.xml</filename>.  This will create 
+			<filename>openjpa-persistence-j2ee-sample.ear</filename>.  This ear 
+			can now be deployed to your appserver.  Be sure to add the class
+			<classname>samples.j2ee.Car</classname> to the
+			<literal>openjpa.PersistentClasses</literal> OpenJPA configuration
+			property.  This will automatically register the Entity.
+			</para>
+            <programlisting format="linespecific">
+ant -f build.xml
+</programlisting>
+          </section>
+          <section id="jpa_j2ee_tutorial_sample_jboss">
+            <title>Deploying Sample To JBoss</title>
+            <para>
+			Place the ear file in the <filename>deploy</filename> 
+			directory of your JBoss installation.  You can use the 
+			above hints to view the JNDI tree to see if 
+			<classname>samples.j2ee.ejb.CarHome</classname> was 
+			deployed to JNDI.
+			</para>
+          </section>
+          <section id="jpa_j2ee_tutorial_sample_weblogic">
+            <title>Deploying Sample To WebLogic 9</title>
+            <para>
+			Place the ear file in the <filename>autodeploy</filename>
+			directory of your WebLogic domain.  Production mode (see your 
+			startWebLogic.sh/cmd file) should be set to false to enable 
+			auto-deployment.  If the application was installed correctly, 
+			you should see <computeroutput>openjpa-persistence-j2ee-sample
+			</computeroutput> listed in the Deployments section of the admin 
+			console.  In addition you should find <literal>CarHome</literal> 
+			listed in the JNDI tree under 
+			<computeroutput>AdminServer-&gt;samples-&gt;j2ee-&gt;ejb
+			</computeroutput>.  Ensure that you have added the class
+			<classname>samples.j2ee.Car</classname> to the
+			<literal>openjpa.PersistentClasses</literal> OpenJPA configuration
+			property in the <literal>META-INF/ra.xml</literal> file.
+			</para>
+          </section>
+<!-- TODO 
+		<section id="jpa_j2ee_tutorial_sample_weblogic8">
+			<title>Deploying Sample To WebLogic 8.1</title>
+			<para>
+			Create a new directory named <filename>
+			openjpa-persistence-j2ee-sample.ear</filename>
+			in the <filename>applications</filename> directory of
+			your WebLogic domain.  Extract the EAR file (without copying
+			the EAR file) to this new directory:
+			</para>
+<programlisting>
+applications> mkdir openjpa-persistence-j2ee-sample.ear
+applications> cd openjpa-persistence-j2ee-sample.ear
+openjpa-persistence-j2ee-sample.ear> jar -xvf /path/to/openjpa-persistence-j2ee-sample.ear
+</programlisting>
+			<para>
+			Deploy the application by using the admin console
+			(Deployments -&gt; Applications -&gt; Deploy a new Application.
+			Select <literal>openjpa-persistence-j2ee-sample.ear</literal> and 
+			deploy to the proper server targets.  If you have installed the
+			application correctly, you should find CarHome
+			listed in the JNDI tree under
+			<computeroutput>myserver-&gt;samples-&gt;j2ee-&gt;ejb
+			</computeroutput>.
+			</para>
+		</section>
+		<section id="jpa_j2ee_tutorial_sample_sunone">
+			<title>Deploying Sample To SunONE / Sun JES</title>
+			<para>
+			Browse to the admin console in your web browser. Select 
+			<computeroutput>Applications/ Enterprise Applications
+			</computeroutput> from the left navigation panel.  Select 
+			<computeroutput>Deploy... </computeroutput> and in the 
+			following screen upload the <filename>
+			openjpa-persistence-j2ee-sample.ear</filename> 
+			file to the server.  Apply your changes by selecting the 
+			link in the upper right portion of the page.  You should 
+			now see <computeroutput>openjpa-persistence-j2ee-sample
+			</computeroutput> listed 
+			in the Enterprise Applications folder of the navigation panel.
+			</para>
+		</section>
+		<section id="jpa_j2ee_tutorial_sample_jrun">
+			<title>Deploying Sample To JRun</title>
+			<para>
+			Browse to the admin console in your web browser. Select 
+			<computeroutput>J2EE Components
+			</computeroutput> from the left navigation panel.  Select 
+			<computeroutput>Add</computeroutput> under the
+			<computeroutput>Enterprise Applications</computeroutput>
+			heading. Select the <filename>openjpa-persistence-j2ee-sample.ear
+			</filename> file and hit <computeroutput>Deploy</computeroutput>.
+			You should now see <computeroutput>Sample-OpenJPAJ2EE</computeroutput>
+			listed in the top-level folder of the navigation panel.
+			Select it, and then select the
+			<computeroutput>sample-ejb.jar#CarEJB</computeroutput>
+			component under
+			<computeroutput>Enterprise JavaBeans</computeroutput>
+			section, then change the <computeroutput>JNDI Name</computeroutput>
+			for the bean from the default value to
+			<computeroutput>samples.j2ee.ejb.CarHome</computeroutput> and hit
+			<computeroutput>Apply</computeroutput>.
+			</para>
+			<para>
+			If the OpenJPA resource adapter and the sample EAR are both
+			configured correctly, you should now be able to access
+			your sample application at JRun's deploy URL (e.g.,
+			<literal>http://localhost:8100/sample/</literal>).
+			</para>
+		</section>
+		<section id="jpa_j2ee_tutorial_sample_websphere">
+			<title>Deploying Sample To WebSphere</title>
+			<para>
+			Browse to the admin console in your web browser.  Select 
+			<computeroutput>Applications / Install New Application
+			</computeroutput> from the left navigation panel.  Select 
+			the path to your <filename>openjpa-persistence-j2ee-sample.ear
+			</filename> file and press <computeroutput>Next</computeroutput>.
+			</para>
+			<para>
+			On the following screen, leave the options at the default 
+			and select <computeroutput>Next</computeroutput>.  On the following
+			screen (<computeroutput>Install New Application->Step 1
+			</computeroutput>), ensure that the <computeroutput>Deploy EJBs
+			</computeroutput> option is checked.  Leave other options at their 
+			defaults.
+			</para>
+			<para>
+			Move on to Step 2.  On this screen enter <literal>
+			samples.j2ee.ejb.CarHome</literal> as the JNDI name for the 
+			<classname>Car</classname> EJB.  Continue through the 
+			remaining steps leaving options at the defaults.  Select 
+			<computeroutput>Finish</computeroutput> and ensure that 
+			the application is deployed correctly.
+			</para>
+			<para>
+			Save the changes to the domain configuration by either 
+			selecting the <computeroutput>Save</computeroutput> link 
+			that appears after the installation is complete or by 
+			selecting <computeroutput>Save</computeroutput> from the top menu.
+			</para>
+			<para>
+			To verify your installation, select <computeroutput>Applications 
+			/ Enterprise Applications</computeroutput> from the left 
+			navigation panel.  <computeroutput>Sample-OpenJPAJ2EE</computeroutput> 
+			should be listed in the list.  If the application has not 
+			started already, select the checkbox next to <computeroutput>
+			Sample-OpenJPAJ2EE</computeroutput>
+			and select <computeroutput>Start</computeroutput>.  
+			</para>
+		</section>
+		<section id="jpa_j2ee_tutorial_sample_borland">
+			<title>Deploying Sample To Borland Enterprise Server 5.2</title>
+			<para>
+			Deploy the EAR file using iastool or the console.  Note
+			that you may have to include the JDO library in your
+			stub generation process.  Also be sure that you have 
+			followed the JCA instructions for
+			BES as well as editing the ejb/CarBean.java file to
+			point to <literal>serial://openjpa-ejb</literal> JNDI location.
+			You should be able to see the CarEJB located in JNDI
+			located at the home classname.
+			</para>
+		</section>
+		-->
+        </section>
+        <section id="jpa_j2ee_tutorial_using">
+          <title>Using The Sample Application</title>
+          <para>
+		The sample application installs itself into the web layer at the 
+		context root of sample.  By browsing to 
+		<computeroutput>http://yourserver:yourport/openjpa-persistence-j2ee-sample
+		</computeroutput>, you should be presented with a simple 
+		list page with no cars.  You can edit, add, delete car instances.
+		In addition, you can query on the underlying <classname>Car</classname>
+		instances by passing in an JPQL query into the marked form (such as
+		<computeroutput>select car from Car car where car.model="Some Model"</computeroutput>).
+		</para>
+        </section>
+        <section id="jpa_j2ee_tutorial_architecture">
+          <title>Sample Architecture</title>
+          <para>
+		The garage application is a simple enterprise application that 
+		demonstrates some of the basic concepts necessary when 
+		using OpenJPA in the enterprise layer.
+		</para>
+          <para>
+		The core model wraps a stateless session bean facade around 
+		an entity.  Using a session bean provides both a remote interface 
+		for various clients as well as providing a transactional context in 
+		which to work (and thus avoiding any explicit transactional code).  
+		</para>
+          <para>
+		This session bean uses the JPA's detachment 
+		capabilities to provide an automatic Data Transfer Object mechanism
+		for the primary communication between the
+		application server and the (possibly remote) client. The <classname>Car
+		</classname> instance will be used as the primary object upon
+		which the client will work.
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>samples/persistence/j2ee/Car.java</literal>:
+				The core of the sample application.  This is the 
+				entity class that OpenJPA will use to persist the 
+				application data.  
+				Instances of this class will also fill the role of 
+				data transfer object (DTO) for EJB clients.  
+				To accomplish this, <classname>Car</classname> implements 
+				<classname>java.io.Serializable</classname> 
+				so that remote clients can access cars as parameters
+				and return values from the EJB.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>
+				samples/persistence/j2ee/jsp/SampleUtilities.java</literal>:
+				This is a simple facade to aggregate some common J2EE 
+				behavior into some static methods.  
+				By placing all of the functionality into a single 
+				facade class, we can reduce code maintenance of our JSPs.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>samples/persistence/j2ee/ejb/Car*.java</literal>:
+				The source for the <classname>CarEJB</classname> session bean.  
+				Clients can use the <classname>CarHome</classname> 
+				and <classname>CarRemote</classname> interfaces to 
+				find, manipulate, and persist changes to 
+				<classname>Car</classname> transfer object 
+				instances.  By using J2EE transactional features,
+				the implementation code in <filename>CarBean.java</filename> 
+				can be focused almost entirely upon business and 
+				persistence logic without worrying about transactions. 
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>samples/persistence/j2ee/jsp/*.jsp</literal>:
+				The web presentation client.  These JSPs are not aware of the
+				JPA; they simply use the <classname>CarEJB</classname> session 
+				bean and the <classname>Car</classname> transfer object to do 
+				all the work.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>samples/persistence/j2ee/resources/*</literal>:
+				Files required to deploy to the various appservers, 
+				including J2EE deployment descriptors, WAR/ EJB/ EAR 
+				descriptors, as well as appserver specific files.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>samples/persistence/j2ee/build.xml</literal>:
+				A simple Ant build file to help in creating a J2EE EAR file.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_j2ee_tutorial_notes">
+          <title>Code Notes and J2EE Tips</title>
+          <orderedlist>
+            <listitem>
+              <para>
+				Entity classes are excellent 
+				candidates for the Data Transfer Object Pattern.   
+				This pattern attempts to reduce network load, as well 
+				as group business logic into concise units.  
+				For example, <methodname>CarBean.edit</methodname> allows you 
+				to ensure that all values are correct before committing a 
+				transaction, instead of sequentially calling getters and 
+				setters on the session facade.  This is especially true when 
+				using RMI such as from a Swing based application 
+				connecting to an application server.
+				</para>
+              <para><classname>CarEJB</classname> works as a session bean facade 
+				to demarcate transactions, provide finder methods, and 
+				encapsulate complex business logic at the server level.
+				</para>
+            </listitem>
+            <listitem>
+              <para><methodname>EntityManager.close()</methodname> 
+				should be called at the end of every EJB method.  
+				In addition to ensuring that your code will not attempt to 
+				access a closed <classname>EntityManager</classname>, it 
+				allows OpenJPA to free up unused resources.
+				Since an <classname>EntityManager</classname> is created 
+				for every transaction, this can increase the scalability
+				of your application.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				You should not use <methodname>
+				EntityManager.getTransaction()</methodname> when using JTA
+				to manage your transactions. Instead, OpenJPA will integrate with
+				JTA to automatically govern transactions based on your EJB
+				transaction configuration.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				While serialization of entity instances is relatively 
+				straightforward, there are several things to keep in mind:
+				</para>
+              <itemizedlist>
+                <listitem>
+                  <para>
+						While "default fetch group" values will always be 
+						returned to the client upon serialization, lazily 
+						loaded fields will not as the 
+						<classname>EntityManager</classname> will 
+						have been closed before those fields attempt to 
+						serialize.  You can either access those fields 
+						before serialization, configure the fetch type of the
+						relationships, or configure your JPQL queries to 
+						eagerly fetch data.
+						</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para>
+				It is not necessarily required that you use EJBs and 
+				container-managed transactions to demarcate transactions, 
+				although that is probably the most common method.  
+				In EJBs using bean managed transactions, you can control
+				transactions through the
+				<classname>javax.transaction.UserTransaction</classname> interface.
+				Furthermore, outside of session beans you can control the 
+				JPA layer's transaction via the 
+				<classname>javax.persistence.EntityTransaction</classname> 
+				interface.
+				</para>
+            </listitem>
+            <listitem>
+              <para><classname>EntityManager</classname>s are allocated on a 
+				per-Transaction basis. 
+				Calling <methodname>getEntityManager</methodname> from 
+				the same <classname>EntityManagerFactory</classname> 
+				within the same EJB method call will always return the same
+				entity manager, although the user-visible object may be 
+				proxied, so might not compare equal using the 
+				<literal>==</literal> operator.  
+				</para>
+            </listitem>
+          </orderedlist>
+        </section>
+      </section>
+    </chapter>
+  </part>
+  <part id="ref_guide">
+    <title>OpenJPA <phrase>JPA</phrase> Reference Guide</title>
+<!-- author: Abe White -->
+    <chapter id="ref_guide_intro">
+      <title>Introduction</title>
+      <para>
+	OpenJPA <phrase>JPA</phrase> is a JDBC-based implementation of the JPA 
+	standard.  This document is a reference for the 
+	configuration and use of OpenJPA <phrase>JPA</phrase>. 
+	</para>
+      <section id="ref_guide_intro_audience">
+        <title>Intended Audience</title>
+        <para>
+		This document is intended for OpenJPA <phrase>JPA</phrase> developers.  It 
+		assumes strong knowledge of Java, familiarity with the eXtensible 
+		Markup Language (XML), and an understanding of JPA.
+		If you are not familiar with JPA, please read the
+		<link linkend="jpa_overview_intro">JPA Overview</link> 
+		before proceeding.  We also strongly recommend taking OpenJPA's hands-on 
+		<link linkend="tutorials">tutorials</link> to get comfortable 
+		with OpenJPA basics.
+		</para>
+        <para>
+		Certain sections of this guide cover advanced topics such as
+		custom object-relational mapping, enterprise integration, and using
+		OpenJPA with third-party tools.  These sections assume prior experience 
+		with the relevant subject.
+		</para>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_conf">
+      <title>Configuration</title>
+      <indexterm>
+        <primary>configuration</primary>
+      </indexterm>
+      <section id="ref_guide_conf_intro">
+        <title>Introduction</title>
+        <para>
+		This chapter describes the OpenJPA configuration framework.
+		It concludes with descriptions of all the configuration properties 
+		recognized by OpenJPA.  You may want to browse these properties now, 
+		but it is not necessary.  Most of them will be referenced later in 
+		the documentation as we explain the various features they apply to.
+		</para>
+      </section>
+      <section id="ref_guide_conf_specify">
+        <title>Runtime Configuration</title>
+        <indexterm zone="ref_guide_conf_specify">
+          <primary>configuration</primary>
+          <secondary>runtime</secondary>
+        </indexterm>
+        <para>
+		The OpenJPA runtime includes a comprehensive system of configuration 
+		defaults and overrides:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>openjpa.xml</primary></indexterm>
+				OpenJPA first looks for an optional <filename>openjpa.xml</filename> 
+				resource.  OpenJPA searches for this resource in each top-level
+				directory of your <literal>CLASSPATH</literal>.  OpenJPA will also
+				find the resource if you place it within a <filename>META-INF
+				</filename> directory in any top-level directory of the
+				<literal>CLASSPATH</literal>.  The <filename>openjpa.xml</filename>
+				resource contains property settings in 
+				<link linkend="jpa_overview_persistence_xml">JPA's XML
+				format</link>.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				You can customize the name or location of the above resource
+				by specifying the correct resource path 
+				in the <literal>openjpa.properties</literal> System property.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				You can override any value defined in the above resource
+				by setting the System property of the same name to the desired 
+				value.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Persistence</primary><secondary>createEntityManagerFactory</secondary></indexterm>
+				In JPA, the values in the standard <filename>
+				META-INF/persistence.xml</filename> bootstrapping file
+				used by the <link linkend="jpa_overview_persistence"><classname>Persistence</classname></link> class at runtime
+				override the values in the above resource, as well as any
+				System property settings.  The <classname>Map</classname> 
+				passed to <methodname>Persistence.createEntityManagerFactory
+				</methodname> at runtime also overrides previous settings,
+				including properties defined in <filename>
+				persistence.xml</filename>.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				When using JCA deployment the <literal>config-property</literal>
+				values in your <filename>ra.xml</filename> file override other 
+				settings.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				All OpenJPA command-line tools accept flags that allow you to
+				specify the configuration resource to use, and to override any
+				property.  <xref linkend="ref_guide_conf_devtools"/> 
+				describes these flags.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <note>
+          <para>
+			Internally, the OpenJPA <phrase>JPA</phrase> runtime environment and 
+			development tools manipulate property settings through 
+			a general
+			<ulink url="../apidocs/ResultObjectProvider/lib/conf/Configuration.html"><classname>Configuration</classname></ulink> interface, and in 
+			particular its 
+			<ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html"><classname>OpenJPAConfiguration</classname></ulink> and
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html"><classname>JDBCConfiguration</classname></ulink> subclasses.
+			For advanced customization, OpenJPA's extended runtime interfaces and
+			its development tools allow you to access these interfaces directly.
+			See the <ulink url="../javadoc">Javadoc</ulink> for details.
+			</para>
+        </note>
+      </section>
+      <section id="ref_guide_conf_devtools">
+        <title>Command Line Configuration</title>
+        <indexterm zone="ref_guide_conf_devtools">
+          <primary>configuration</primary>
+          <secondary>command line</secondary>
+        </indexterm>
+        <para>
+		OpenJPA development tools share the same set of configuration 
+		defaults and overrides as the runtime system.  They also allow you to 
+		specify property values on the command line:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>-properties/-p &lt;configuration file or resource&gt;
+				</literal>: Use the <literal>-properties</literal> flag, or 
+				its shorter <literal>-p</literal> form, to specify a 
+				configuration file to use.  Note that OpenJPA always searches the
+				default file locations described above, so this flag is only
+				needed when you do not have a default resource in place, or when
+				you wish to override the defaults.  The given value can be
+				the path to a file, or the resource name of a file somewhere in
+				the <literal>CLASSPATH</literal>.  OpenJPA will search the given
+				location as well as the location prefixed by <filename>
+				META-INF/</filename>.  Thus, to point a OpenJPA tool at 
+				<phrase><filename>META-INF/persistence.xml</filename>,
+				</phrase>
+				
+				you can use:
+				</para>
+            <programlisting format="linespecific">
+&lt;tool&gt; -p persistence.xml
+</programlisting>
+          </listitem>
+          <listitem>
+            <para><literal>-&lt;property name&gt; &lt;property value&gt;
+				</literal>:  Any configuration property that you can specify
+				in a configuration file can be overridden with a command line 
+				flag.  The flag name is always the last token of the 
+				corresponding property name, with the first letter in either 
+				upper or lower case.  For example, to override the 
+				<literal>openjpa.ConnectionUserName</literal> property,
+				you could pass the 
+				<literal>-connectionUserName &lt;value&gt;</literal> flag to
+				any tool.  Values set this way override both the values in the
+				configuration file and values set via System properties.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <section id="ref_guide_conf_devtools_format">
+          <title>Code Formatting</title>
+          <indexterm zone="ref_guide_conf_devtools_format">
+            <primary>code formatting</primary>
+          </indexterm>
+          <para>
+			Some OpenJPA development tools generate Java code.  
+			These tools share a common set of command-line flags for formatting
+			their output to match your coding style.  All code formatting flags
+			can begin with either the <literal>codeFormat</literal> or 
+			<literal>cf</literal> prefix.
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>-codeFormat./-cf.tabSpaces &lt;spaces&gt;
+					</literal>: The number of spaces that make up a tab, or 0 
+					to use tab characters.  Defaults to using tab characters.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>-codeFormat./-cf.spaceBeforeParen 
+					&lt;true/t | false/f&gt;</literal>: Whether or not to place 
+					a space before opening parentheses on method calls, if
+					statements, loops, etc.  Defaults to 
+					<literal>false</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>-codeFormat./-cf.spaceInParen 
+					&lt;true/t | false/f&gt;</literal>: Whether or not to place 
+					a space within parentheses; i.e. 
+					<literal>method( arg )</literal>.  Defaults to 
+					<literal>false</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>-codeFormat./-cf.braceOnSameLine 
+					&lt;true/t | false/f&gt;</literal>: Whether or not to place 
+					opening braces on the same line as the declaration that
+					begins the code block, or on the next line.  Defaults to
+					<literal>true</literal>. 
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>-codeFormat./-cf.braceAtSameTabLevel 
+					&lt;true/t | false/f&gt;</literal>: When the 
+					<literal>braceOnSameLine</literal> option is disabled, 
+					you can choose whether to place the brace at the same
+					tab level of the contained code.  Defaults to
+					<literal>false</literal>. 
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>-codeFormat./-cf.scoreBeforeFieldName 
+					&lt;true/t | false/f&gt;</literal>: Whether to prefix
+					an underscore to names of private member variables.
+					Defaults to <literal>false</literal>. 
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>-codeFormat./-cf.linesBetweenSections &lt;lines&gt;
+					</literal>: The number of lines to skip between sections of
+					code.  Defaults to 2.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <example id="ref_guide_conf_devtools_format_ex">
+            <title>Code Formatting with the Reverse Mapping Tool</title>
+            <programlisting format="linespecific">
+reversemappingtool -cf.spaceBeforeParen true -cf.tabSpaces 4
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_conf_plugins">
+        <title>Plugin Configuration</title>
+        <indexterm zone="ref_guide_conf_plugins">
+          <primary>configuration</primary>
+          <secondary>plugins</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>plugins</primary>
+          <see>configuration</see>
+        </indexterm>
+        <para>
+		Because OpenJPA is a highly customizable environment, many 
+		configuration properties relate to the creation and configuration of 
+		system plugins.  Plugin properties have a syntax very similar to that
+		of Java 5 annotations.  They allow you to specify both what class to 
+		use for the plugin and how to configure the public fields or bean 
+		properties of the instantiated plugin instance.  The easiest way to 
+		describe the plugin syntax is by example:
+		</para>
+        <para>
+		OpenJPA has a pluggable L2 caching mechanism that is controlled by the
+		<literal>openjpa.DataCache</literal> configuration property.
+		Suppose that you have created a new class,
+		<classname>com.xyz.MyDataCache</classname>, that you want OpenJPA to 
+		use for caching.  You've made instances of 
+		<literal>MyDataCache</literal> configurable via two methods, 
+		<methodname>setCacheSize(int size)</methodname> and 
+		<methodname>setRemoteHost(String host)</methodname>.  The sample 
+		below shows how you would tell OpenJPA to use an 
+		instance of your custom plugin with a max size of 1000 and a remote 
+		host of <literal>cacheserver</literal>.
+		</para>
+        <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" 
+    value="com.xyz.MyDataCache(CacheSize=1000, RemoteHost=cacheserver)"/&gt;
+</programlisting>
+        <para>
+		As you can see, plugin properties take a class name, followed by
+		a comma-separated list of values for the plugin's public fields or 
+		bean properties in parentheses.  OpenJPA will match each named property 
+		to a field or setter method in the instantiated plugin instance, and 
+		set the field or invoke the method with the given value (after 
+		converting the value to the right type,
+		of course).  The first letter of the property names can be in either
+		upper or lower case.  The following would also have been valid:
+		</para>
+        <programlisting format="linespecific">
+com.xyz.MyDataCache(cacheSize=1000, remoteHost=cacheserver)
+</programlisting>
+        <para>
+		If you do not need to pass any property settings to a plugin, you can
+		just name the class to use:
+		</para>
+        <programlisting format="linespecific">
+com.xyz.MyDataCache
+</programlisting>
+        <para>
+		Similarly, if the plugin has a default class that you do not want to
+		change, you can simply specify a list of property settings, without a 
+		class name.  For example, OpenJPA's query cache companion to the data cache
+		has a default implementation suitable to most users, but you still might
+		want to change the query cache's size. It has a <literal>CacheSize
+		</literal> property for this purpose:
+		</para>
+        <programlisting format="linespecific">
+CacheSize=1000
+</programlisting>
+        <para>
+		Finally, many of OpenJPA's built-in options for plugins have short alias
+		names that you can use in place of the full class name.  The 
+		data cache property, for example, has an available alias of
+		<literal>true</literal> for the standard cache implementation.  The
+		property value simply becomes:
+		</para>
+        <programlisting format="linespecific">
+true
+</programlisting>
+        <para>
+		The standard cache implementation class also has a <literal>CacheSize
+		</literal> property, so to use the standard implementation and 
+		configure the size, specify:
+		</para>
+        <programlisting format="linespecific">
+true(CacheSize=1000)
+</programlisting>
+        <para>  
+		The remainder of this chapter reviews the set of configuration 
+		properties OpenJPA recognizes. 
+		</para>
+      </section>
+      <section id="ref_guide_conf_openjpa">
+        <title>OpenJPA Properties</title>
+        <indexterm zone="ref_guide_conf_openjpa">
+          <primary>configuration</primary>
+          <secondary>of OpenJPA properties</secondary>
+        </indexterm>
+        <para>
+		OpenJPA defines many configuration properties.  Most of these 
+		properties are provided for advanced users who wish to customize OpenJPA's
+		behavior; the majority of developers can omit them.  The following
+		properties apply to any OpenJPA back-end, though the given descriptions 
+		are tailored to OpenJPA's default JDBC store.
+		</para>
+        <section id="openjpa.AggregateListeners">
+          <title>openjpa.AggregateListeners</title>
+          <indexterm zone="openjpa.AggregateListeners">
+            <primary>AggregateListeners</primary>
+          </indexterm>
+          <indexterm zone="openjpa.AggregateListeners">
+            <primary>Query</primary>
+            <secondary>AggregateListeners</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.AggregateListeners</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getAggregateListeners">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getAggregateListeners</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>AggregateListeners</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis>-
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			A comma-separated list of plugin strings
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing custom
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/exps/JDBCAggregateListener.html"><classname>
+			org.apache.openjpa.jdbc.kernel.exps.JDBCAggregateListener</classname></ulink>s
+			to make available to all queries, in addition to the standard set of
+			listeners.  See <xref linkend="ref_guide_enterprise_queryext"/> for
+			details on aggregate listeners.
+			</para>
+        </section>
+        <section id="openjpa.AutoClear">
+          <title>openjpa.AutoClear</title>
+          <indexterm zone="openjpa.AutoClear">
+            <primary>AutoClear</primary>
+          </indexterm>
+          <indexterm zone="openjpa.AutoClear">
+            <primary>transactions</primary>
+            <secondary>AutoClear</secondary>
+            <tertiary>AutoClear</tertiary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.AutoClear</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getAutoClear">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getAutoClear</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>AutoClear</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>datastore</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>datastore</literal>, <literal>all</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  When to automatically
+			clear instance state: on entering a datastore transaction, or on
+			entering any transaction.
+			</para>
+        </section>
+        <section id="openjpa.AutoDetach">
+          <title>openjpa.AutoDetach</title>
+          <indexterm zone="openjpa.AutoDetach">
+            <primary>AutoDetach</primary>
+          </indexterm>
+          <indexterm zone="openjpa.AutoDetach">
+            <primary>detach</primary>
+            <secondary>AutoDetach</secondary>
+            <tertiary>AutoDetach</tertiary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.AutoDetach</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getAutoDetach">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getAutoDetach</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>AutoDetach</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>close</literal>, <literal>commit</literal>,
+			<literal>nontx-read</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  A comma-separated
+			list of events when managed instances will be automatically
+			detached.
+			</para>
+        </section>
+        <section id="openjpa.BrokerFactory">
+          <title>openjpa.BrokerFactory</title>
+          <indexterm zone="openjpa.BrokerFactory">
+            <primary>BrokerFactory</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.BrokerFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getBrokerFactory">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getBrokerFactory</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>BrokerFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>jdbc</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>jdbc</literal>, <literal>abstractstore</literal>,
+			<literal>remote</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <ulink url="../apidocs/org/apache/openjpa/kernel/BrokerFactory.html"><classname>org.apache.openjpa.kernel.BrokerFactory</classname></ulink> type
+			to use.
+			</para>
+        </section>
+        <section id="openjpa.BrokerImpl">
+          <title>openjpa.BrokerImpl</title>
+          <indexterm zone="openjpa.BrokerImpl">
+            <primary>BrokerImpl</primary>
+          </indexterm>
+          <indexterm zone="openjpa.BrokerImpl">
+            <primary>Broker</primary>
+            <secondary>BrokerImpl</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.BrokerImpl</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getBrokerImpl">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getBrokerImpl</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>BrokerImpl</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing the 
+			<ulink url="../apidocs/org/apache/openjpa/kernel/Broker.html"><classname>
+			org.apache.openjpa.kernel.Broker</classname></ulink> type to use at runtime.  
+			See <xref linkend="ref_guide_runtime_pmextension"/> on for details.
+			</para>
+        </section>
+        <section id="openjpa.ClassResolver">
+          <title>openjpa.ClassResolver</title>
+          <indexterm zone="openjpa.ClassResolver">
+            <primary>ClassResolver</primary>
+          </indexterm>
+          <indexterm>
+            <primary>class loading</primary>
+            <see>ClassResolver</see>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ClassResolver</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getClassResolver">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getClassResolver</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ClassResolver</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <ulink url="../apidocs/org/apache/openjpa/util/ClassResolver.html"><classname>org.apache.openjpa.util.ClassResolver</classname></ulink>
+			implementation to use for class name resolution.  You may wish to 
+			plug in your own resolver if you have special classloading needs.
+			</para>
+        </section>
+        <section id="openjpa.Compatibility">
+          <title>openjpa.Compatibility</title>
+          <indexterm zone="openjpa.Compatibility">
+            <primary>Compatibility</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Compatibility">
+            <primary>backwards compatibility</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Compatibility</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getCompatibility">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getCompatibility</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Compatibility</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> Encapsulates options
+			to mimic the behavior of previous OpenJPA releases.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionDriverName">
+          <title>openjpa.ConnectionDriverName</title>
+          <indexterm zone="openjpa.ConnectionDriverName">
+            <primary>ConnectionDriverName</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionDriverName">
+            <primary>connections</primary>
+            <secondary>ConnectionDriverName</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionDriverName</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionDriverName">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionDriverName</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionDriverName</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The full class name
+			of either the JDBC <classname>java.sql.Driver</classname>, or
+			a <classname>javax.sql.DataSource</classname> implementation to
+			use to connect to the database.  See 
+			<xref linkend="ref_guide_dbsetup"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.Connection2DriverName">
+          <title>openjpa.Connection2DriverName</title>
+          <indexterm zone="openjpa.Connection2DriverName">
+            <primary>Connection2DriverName</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Connection2DriverName">
+            <primary>connections</primary>
+            <secondary>Connection2DriverName</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Connection2DriverName</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2DriverName">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2DriverName</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Connection2DriverName</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			This property is equivalent to the
+			<literal>openjpa.ConnectionDriverName</literal> property described in
+			<xref linkend="openjpa.ConnectionDriverName"/>, but applies to the 
+			alternate connection factory used for unmanaged connections.  
+			See <xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for 
+			details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactory">
+          <title>openjpa.ConnectionFactory</title>
+          <indexterm zone="openjpa.ConnectionFactory">
+            <primary>ConnectionFactory</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactory">
+            <primary>connections</primary>
+            <secondary>ConnectionFactory</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactory</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A 
+			<classname>javax.sql.DataSource</classname> to use to 
+			connect to the database.  See <xref linkend="ref_guide_dbsetup"/> 
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactory2">
+          <title>openjpa.ConnectionFactory2</title>
+          <indexterm zone="openjpa.ConnectionFactory2">
+            <primary>ConnectionFactory2</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactory2">
+            <primary>connections</primary>
+            <secondary>ConnectionFactory2</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactory2</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory2">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactory2</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> An unmanaged 
+			<classname>javax.sql.DataSource</classname> to use to 
+			connect to the database.  See <xref linkend="ref_guide_dbsetup"/> 
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactoryName">
+          <title>openjpa.ConnectionFactoryName</title>
+          <indexterm zone="openjpa.ConnectionFactoryName">
+            <primary>ConnectionFactoryName</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactoryName">
+            <primary>connections</primary>
+            <secondary>ConnectionFactoryName</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactoryName</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactoryName">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryName</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactoryName</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The JNDI location
+			of a <classname>javax.sql.DataSource</classname> to use to 
+			connect to the database.  See <xref linkend="ref_guide_dbsetup"/> 
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactory2Name">
+          <title>openjpa.ConnectionFactory2Name</title>
+          <indexterm zone="openjpa.ConnectionFactory2Name">
+            <primary>ConnectionFactory2Name</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactory2Name">
+            <primary>connections</primary>
+            <secondary>ConnectionFactory2Name</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactory2Name</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory2Name">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Name</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactory2Name</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> 
+			The JNDI location of an unmanaged <classname>javax.sql.DataSource
+			</classname> to use to connect to the database.
+			See <xref linkend="ref_guide_enterprise_xa"/> 
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactoryMode">
+          <title>openjpa.ConnectionFactoryMode</title>
+          <indexterm zone="openjpa.ConnectionFactoryMode">
+            <primary>ConnectionFactoryMode</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactoryMode">
+            <primary>connections</primary>
+            <secondary>ConnectionFactoryMode</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactoryMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactoryMode">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryMode</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactoryMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>local</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>local</literal>, <literal>managed</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> The connection 
+			factory mode to use when integrating with the application server's 
+			managed transactions.  See 
+			<xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactoryProperties">
+          <title>openjpa.ConnectionFactoryProperties</title>
+          <indexterm zone="openjpa.ConnectionFactoryProperties">
+            <primary>ConnectionFactoryProperties</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactoryProperties">
+            <primary>connections</primary>
+            <secondary>ConnectionFactoryProperties</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactoryProperties</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactoryProperties">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryProperties</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactoryProperties</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) listing
+			properties for configuration of the <classname>javax.sql.DataSource
+			</classname> in use.  See the <xref linkend="ref_guide_dbsetup"/> 
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionFactory2Properties">
+          <title>openjpa.ConnectionFactory2Properties</title>
+          <indexterm zone="openjpa.ConnectionFactory2Properties">
+            <primary>ConnectionFactory2Properties</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionFactory2Properties">
+            <primary>connections</primary>
+            <secondary>ConnectionFactory2Properties</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionFactory2Properties</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionFactory2Properties">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Properties</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionFactory2Properties</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			This property is equivalent to the
+			<literal>openjpa.ConnectionFactoryProperties</literal> property
+			described in <xref linkend="openjpa.ConnectionFactoryProperties"/>,
+			but applies to the alternate connection factory used for 
+			unmanaged connections.  See 
+			<xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionPassword">
+          <title>openjpa.ConnectionPassword</title>
+          <indexterm zone="openjpa.ConnectionPassword">
+            <primary>ConnectionPassword</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionPassword">
+            <primary>connections</primary>
+            <secondary>ConnectionPassword</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionPassword</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionPassword">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionPassword</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionPassword</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The password for
+			the user specified in the <literal>ConnectionUserName</literal>
+			property.  See <xref linkend="ref_guide_dbsetup"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.Connection2Password">
+          <title>openjpa.Connection2Password</title>
+          <indexterm zone="openjpa.Connection2Password">
+            <primary>Connection2Password</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Connection2Password">
+            <primary>connections</primary>
+            <secondary>Connection2Password</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Connection2Password</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2Password">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Password</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Connection2Password</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			This property is equivalent to the <literal>openjpa.ConnectionPassword
+			</literal> property described in 
+			<xref linkend="openjpa.ConnectionPassword"/>, but applies to the 
+			alternate connection factory used for unmanaged connections.  
+			See <xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for 
+			details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionProperties">
+          <title>openjpa.ConnectionProperties</title>
+          <indexterm zone="openjpa.ConnectionProperties">
+            <primary>ConnectionProperties</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionProperties">
+            <primary>connections</primary>
+            <secondary>ConnectionProperties</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionProperties</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionProperties">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionProperties</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionProperties</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string (see
+			<xref linkend="ref_guide_conf_plugins"/>) listing properties to 
+			configure the driver listed in the <literal>ConnectionDriverName
+			</literal> property described below.  See
+			<xref linkend="ref_guide_dbsetup"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.Connection2Properties">
+          <title>openjpa.Connection2Properties</title>
+          <indexterm zone="openjpa.Connection2Properties">
+            <primary>Connection2Properties</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Connection2Properties">
+            <primary>connections</primary>
+            <secondary>Connection2Properties</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Connection2Properties</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2Properties">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Properties</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Connection2Properties</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			This property is equivalent to the
+			<literal>openjpa.ConnectionProperties</literal> property
+			described in <xref linkend="openjpa.ConnectionProperties"/>,
+			but applies to the alternate connection factory used for 
+			unmanaged connections.  See 
+			<xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionURL">
+          <title>openjpa.ConnectionURL</title>
+          <indexterm zone="openjpa.ConnectionURL">
+            <primary>ConnectionURL</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionURL">
+            <primary>connections</primary>
+            <secondary>ConnectionURL</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionURL</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionURL">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionURL</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionURL</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The JDBC URL
+			for the database.  See <xref linkend="ref_guide_dbsetup"/> for 
+			details.
+			</para>
+        </section>
+        <section id="openjpa.Connection2URL">
+          <title>openjpa.Connection2URL</title>
+          <indexterm zone="openjpa.Connection2URL">
+            <primary>Connection2URL</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Connection2URL">
+            <primary>connections</primary>
+            <secondary>Connection2URL</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Connection2URL</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2URL">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2URL</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Connection2URL</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			This property is equivalent to the
+			<literal>openjpa.ConnectionURL</literal> property
+			described in <xref linkend="openjpa.ConnectionURL"/>,
+			but applies to the alternate connection factory used for 
+			unmanaged connections.  See
+			<xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionUserName">
+          <title>openjpa.ConnectionUserName</title>
+          <indexterm zone="openjpa.ConnectionUserName">
+            <primary>ConnectionUserName</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionUserName">
+            <primary>connections</primary>
+            <secondary>ConnectionUserName</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionUserName</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionUserName">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionUserName</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionUserName</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The user name to
+			use when connecting to the database.  See the 
+			<xref linkend="ref_guide_dbsetup"/> for details. 
+			</para>
+        </section>
+        <section id="openjpa.Connection2UserName">
+          <title>openjpa.Connection2UserName</title>
+          <indexterm zone="openjpa.Connection2UserName">
+            <primary>Connection2UserName</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Connection2UserName">
+            <primary>connections</primary>
+            <secondary>Connection2UserName</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Connection2UserName</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnection2UserName">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2UserName</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Connection2UserName</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			This property is equivalent to the
+			<literal>openjpa.ConnectionUserName</literal> property
+			described in <xref linkend="openjpa.ConnectionUserName"/>,
+			but applies to the alternate connection factory used for 
+			unmanaged connections.  See 
+			<xref linkend="ref_guide_dbsetup_thirdparty_enlist"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.ConnectionRetainMode">
+          <title>openjpa.ConnectionRetainMode</title>
+          <indexterm zone="openjpa.ConnectionRetainMode">
+            <primary>ConnectionRetainMode</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ConnectionRetainMode">
+            <primary>connections</primary>
+            <secondary>ConnectionRetainMode</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ConnectionRetainMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getConnectionRetainMode">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionRetainMode</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionRetainMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>on-demand</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Controls how OpenJPA
+			uses datastore connections.  This property can also be specified
+			for individual sessions.  See 
+			<xref linkend="ref_guide_dbsetup_retain"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.DataCache">
+          <title>openjpa.DataCache</title>
+          <indexterm zone="openjpa.DataCache">
+            <primary>DataCache</primary>
+          </indexterm>
+          <indexterm zone="openjpa.DataCache">
+            <primary>caching</primary>
+            <secondary>DataCache</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.DataCache</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDataCache">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getDataCache</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DataCache</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin list string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <ulink url="../apidocs/org/apache/openjpa/datacache/DataCache.html"><classname>org.apache.openjpa.datacache.DataCache</classname></ulink>s to
+			use for data caching. See <xref linkend="ref_guide_cache_conf"/> 
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.DataCacheManager">
+          <title>openjpa.DataCacheManager</title>
+          <indexterm zone="openjpa.DataCacheManager">
+            <primary>DataCacheManager</primary>
+          </indexterm>
+          <indexterm zone="openjpa.DataCacheManager">
+            <primary>caching</primary>
+            <secondary>DataCacheManager</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.DataCacheManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDataCacheManager">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheManager
+			</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DataCacheManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the 
+			<ulink url="../apidocs/org/apache/openjpa/datacache/DataCacheManager.html"><classname>openjpa.datacache.DataCacheManager</classname></ulink> that
+			manages the system data caches. See 
+			<xref linkend="ref_guide_cache"/> for details on data caching.
+			</para>
+        </section>
+        <section id="openjpa.DataCacheTimeout">
+          <title>openjpa.DataCacheTimeout</title>
+          <indexterm zone="openjpa.DataCacheTimeout">
+            <primary>DataCacheTimeout</primary>
+          </indexterm>
+          <indexterm zone="openjpa.DataCacheTimeout">
+            <primary>caching</primary>
+            <secondary>DataCacheTimeout</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.DataCacheTimeout</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDataCacheTimeout">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getDataCacheTimeout</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DataCacheTimeout</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>-1</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> The number of
+			milliseconds that data in the data cache is valid. Set this
+			to -1 to indicate that data should not expire from the
+			cache. This property can also be specified for individual
+			classes. See <xref linkend="ref_guide_cache_conf"/> for
+			details.
+			</para>
+        </section>
+        <section id="openjpa.DetachState">
+          <title>openjpa.DetachState</title>
+          <indexterm zone="openjpa.AutoDetach">
+            <primary>DetachState</primary>
+          </indexterm>
+          <indexterm zone="openjpa.AutoDetach">
+            <primary>detach</primary>
+            <secondary>DetachState</secondary>
+            <tertiary>DetachState</tertiary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.DetachState</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDetachState">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getDetachState</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DetachState</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>loaded</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>loaded</literal>, <literal>fgs</literal>,
+			<literal>all</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  Determines which
+			fields are part of the detached graph and related options.  For 
+			more details, see <xref linkend="ref_guide_detach_graph"/>.
+			</para>
+        </section>
+        <section id="openjpa.DynamicDataStructs">
+          <title>openjpa.DynamicDataStructs</title>
+          <indexterm zone="openjpa.DynamicDataStructs">
+            <primary>DynamicDataStructs</primary>
+          </indexterm>
+          <indexterm zone="openjpa.DynamicDataStructs">
+            <primary>caching</primary>
+            <secondary>DynamicDataStructs</secondary>
+          </indexterm>
+          <indexterm zone="openjpa.DynamicDataStructs">
+            <primary>remote</primary>
+            <secondary>DynamicDataStructs</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.DynamicDataStructs</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getDynamicDataStructs">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getDynamicDataStructs</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DynamicDataStructs</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Whether to dynamically
+			generate customized structs to hold persistent data.  Both the
+			OpenJPA data cache and the remote framework rely on data structs to 
+			cache and transfer persistent state.  With dynamic structs, OpenJPA 
+			can customize data storage for each class, eliminating the need to 
+			generate primitive wrapper objects.  This saves memory and speeds 
+			up certain runtime operations.  The price is a longer warm-up
+			time for the application - generating and loading custom classes
+			into the JVM takes time.  Therefore, only set this property to
+			<literal>true</literal> if you have a long-running application where
+			the initial cost of class generation is offset by memory
+			and speed optimization over time.
+			</para>
+        </section>
+        <section id="openjpa.FetchBatchSize">
+          <title>openjpa.FetchBatchSize</title>
+          <indexterm zone="openjpa.FetchBatchSize">
+            <primary>FetchBatchSize</primary>
+          </indexterm>
+          <indexterm zone="openjpa.FetchBatchSize">
+            <primary>large result sets</primary>
+            <secondary>FetchBatchSize</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.FetchBatchSize</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFetchBatchSize">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getFetchBatchSize</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>FetchBatchSize</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>-1</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  The number of
+			rows to fetch at once when scrolling through a result set.  The 
+			fetch size can also be set at runtime.
+			See <xref linkend="ref_guide_dbsetup_lrs"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.FetchGroups">
+          <title>openjpa.FetchGroups</title>
+          <indexterm zone="openjpa.FetchGroups">
+            <primary>fetch groups</primary>
+            <secondary>FetchGroups</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.FetchGroups</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFetchGroups">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getFetchGroups</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>FetchGroups</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  A comma-separated
+			list of fetch group names that are to be loaded when retrieving
+			objects from the datastore.  Fetch groups can also be set at
+			runtime.  See <xref linkend="ref_guide_fetch"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.FilterListeners">
+          <title>openjpa.FilterListeners</title>
+          <indexterm zone="openjpa.FilterListeners">
+            <primary>FilterListeners</primary>
+          </indexterm>
+          <indexterm zone="openjpa.FilterListeners">
+            <primary>Query</primary>
+            <secondary>FilterListeners</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.FilterListeners</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFilterListeners">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getFilterListeners</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>FilterListeners</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  A comma-separated
+			list of full plugin strings (see
+			<xref linkend="ref_guide_conf_plugins"/>) for custom
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/exps/JDBCFilterListener.html"><classname>
+			org.apache.openjpa.jdbc.kernel.exps.JDBCFilterListener</classname></ulink>s
+			to make available to all queries, in addition
+			to the standard set of listeners.  You can also add filter
+			listeners to individual queries.  See 
+			<xref linkend="ref_guide_enterprise_queryext"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.FlushBeforeQueries">
+          <title>openjpa.FlushBeforeQueries</title>
+          <indexterm zone="openjpa.FlushBeforeQueries">
+            <primary>FlushBeforeQueries</primary>
+          </indexterm>
+          <indexterm zone="openjpa.FlushBeforeQueries">
+            <primary>Query</primary>
+            <secondary>FlushBeforeQueries</secondary>
+          </indexterm>
+          <indexterm zone="openjpa.FlushBeforeQueries">
+            <primary>flush</primary>
+            <secondary>FlushBeforeQueries</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.FlushBeforeQueries</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.FlushBeforeQueries</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getFlushBeforeQueries">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getFlushBeforeQueries</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>FlushBeforeQueries</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>true</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Whether or not to
+			flush any changes made in the current transaction to the datastore
+			before executing a query.  See
+			<xref linkend="ref_guide_dbsetup_retain"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.IgnoreChanges">
+          <title>openjpa.IgnoreChanges</title>
+          <indexterm zone="openjpa.IgnoreChanges">
+            <primary>IgnoreChanges</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.IgnoreChanges</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getIgnoreChanges">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getIgnoreChanges</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>IgnoreChanges</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Whether to consider
+			modifications to persistent objects made in the current transaction
+			when evaluating queries.  Setting this to <literal>true</literal> 
+			allows OpenJPA to ignore changes and execute the query 
+			directly against the datastore.  A value of <literal>false</literal>
+			forces OpenJPA to consider whether the changes in the current 
+			transaction affect the query, and if so to either evaluate the query
+			in-memory or flush before running it against the datastore.  
+			</para>
+        </section>
+        <section id="openjpa.InverseManager">
+          <title>openjpa.InverseManager</title>
+          <indexterm zone="openjpa.InverseManager">
+            <primary>InverseManager</primary>
+          </indexterm>
+          <indexterm zone="openjpa.InverseManager">
+            <primary>bidirectional relation</primary>
+            <secondary>InverseManager</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.InverseManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getInverseManager">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getInverseManager</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>InverseManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>false</literal>, <literal>true</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing a <ulink url="../apidocs/org/apache/openjpa/kernel/InverseManager.html"><classname>org.apache.openjpa.kernel.InverseManager</classname></ulink>
+			to use for managing bidirectional relations upon a flush.
+			See <xref linkend="ref_guide_inverses"/> for usage documentation.
+			</para>
+        </section>
+        <section id="openjpa.LockManager">
+          <title>openjpa.LockManager</title>
+          <indexterm zone="openjpa.LockManager">
+            <primary>LockManager</primary>
+          </indexterm>
+          <indexterm zone="openjpa.LockManager">
+            <primary>locking</primary>
+            <secondary>LockManager</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.LockManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getLockManager">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getLockManager</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>LockManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>pessimistic</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>none</literal>, <literal>sjvm</literal>,
+			<literal>pessimistic</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing a <ulink url="../apidocs/org/apache/openjpa/kernel/LockManager.html"><classname>org.apache.openjpa.kernel.LockManager</classname></ulink>
+			to use for acquiring locks on persistent instances
+			during transactions.
+			</para>
+        </section>
+        <section id="openjpa.LockTimeout">
+          <title>openjpa.LockTimeout</title>
+          <indexterm zone="openjpa.LockTimeout">
+            <primary>LockTimeout</primary>
+          </indexterm>
+          <indexterm zone="openjpa.LockTimeout">
+            <primary>locking</primary>
+            <secondary>LockTimeout</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.LockTimeout</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getLockTimeout">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getLockTimeout</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>LockTimeout</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>-1</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  The number of
+			milliseconds to wait for an object lock before throwing an
+			exception, or -1 for no limit.  See
+			<xref linkend="ref_guide_locking"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.Log">
+          <title>openjpa.Log</title>
+          <indexterm zone="openjpa.Log">
+            <primary>Log</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Log">
+            <primary>logging</primary>
+            <secondary>Log</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Log</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getLog">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getLog</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Log</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>true</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>openjpa</literal>, <literal>commons</literal>,
+			<literal>log4j</literal>, <literal>none</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin
+			string (see <xref linkend="ref_guide_conf_plugins"/>)
+			describing a 
+			<ulink url="../apidocs/org/apache/openjpa/lib/log/LogFactory.html"><classname>org.apache.openjpa.lib.log.LogFactory</classname></ulink>
+			to use for logging. For details on logging,
+			see <xref linkend="ref_guide_logging"/>.
+			</para>
+        </section>
+        <section id="openjpa.ManagedRuntime">
+          <title>openjpa.ManagedRuntime</title>
+          <indexterm zone="openjpa.ManagedRuntime">
+            <primary>ManagedRuntime</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ManagedRuntime">
+            <primary>transactions</primary>
+            <secondary>managed</secondary>
+            <tertiary>ManagedRuntime</tertiary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ManagedRuntime</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getManagedRuntime">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getManagedRuntime</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ManagedRuntime</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>auto</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the
+			<ulink url="../apidocs/org/apache/openjpa/ee/ManagedRuntime.html"><classname>org.apache.openjpa.ee.ManagedRuntime</classname></ulink> implementation to use for obtaining a reference to the
+			<classname>TransactionManager</classname> in an enterprise
+			environment.  
+			</para>
+        </section>
+        <section id="openjpa.Mapping">
+          <title>openjpa.Mapping</title>
+          <indexterm zone="openjpa.Mapping">
+            <primary>Mapping</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Mapping</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMapping">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getMapping</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Mapping</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The symbolic name
+			of the object-to-datastore mapping to use.
+			</para>
+        </section>
+        <section id="openjpa.MetaDataFactory">
+          <title>openjpa.MetaDataFactory</title>
+          <indexterm zone="openjpa.MetaDataFactory">
+            <primary>MetaDataFactory</primary>
+          </indexterm>
+          <indexterm zone="openjpa.MetaDataFactory">
+            <primary>metadata</primary>
+            <secondary>MetaDataFactory</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.MetaDataFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMetaDataFactory">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getMetaDataFactory</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>MetaDataFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>jdo</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>jdo</literal>, <literal>jpa</literal>, 
+			<literal>openjpa3</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html"><classname>openjpa.meta.MetaDataFactory</classname></ulink> to 
+			use to store and retrieve metadata for your persistent classes.  See
+			<xref linkend="ref_guide_meta_factory"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.Multithreaded">
+          <title>openjpa.Multithreaded</title>
+          <indexterm zone="openjpa.Multithreaded">
+            <primary>Multithreaded</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Multithreaded">
+            <primary>threading</primary>
+            <secondary>Multithreaded</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Multithreaded</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getMultithreaded">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getMultithreaded</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Multithreaded</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>
+			Whether persistent instances and OpenJPA components will be accessed
+			by multiple threads at once.
+			</para>
+        </section>
+        <section id="openjpa.Optimistic">
+          <title>openjpa.Optimistic</title>
+          <indexterm zone="openjpa.Optimistic">
+            <primary>Optimistic</primary>
+          </indexterm>
+          <indexterm zone="openjpa.Optimistic">
+            <primary>transactions</primary>
+            <secondary>optimistic</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Optimistic</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getOptimistic">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getOptimistic</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Optimistic</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>true</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Selects between
+			optimistic and pessimistic (datastore) transactional modes.
+			</para>
+        </section>
+        <section id="openjpa.OrphanedKeyAction">
+          <title>openjpa.OrphanedKeyAction</title>
+          <indexterm zone="openjpa.OrphanedKeyAction">
+            <primary>OrphanedKeyAction</primary>
+          </indexterm>
+          <indexterm zone="openjpa.OrphanedKeyAction">
+            <primary>foreign keys</primary>
+            <secondary>OrphanedKeyAction</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.OrphanedKeyAction</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getOrphanedKeyAction">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getOrphanedKeyAction</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>OrphanedKeyAction</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>log</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>log</literal>, <literal>exception</literal>,
+			<literal>none</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing a <ulink url="../apidocs/org/apache/openjpa/event/OrphanedKeyAction.html"><classname>org.apache.openjpa.event.OrphanedKeyAction</classname></ulink>
+			to invoke when OpenJPA discovers an orphaned datastore key.
+			See <xref linkend="ref_guide_orphan"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.NontransactionalRead">
+          <title>openjpa.NontransactionalRead</title>
+          <indexterm zone="openjpa.NontransactionalRead">
+            <primary>NontransactionalRead</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.NontransactionalRead</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getNontransactionalRead">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalRead</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>NontransactionalRead</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>true</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Whether the OpenJPA
+			runtime will allow you to read data outside of a transaction.
+			</para>
+        </section>
+        <section id="openjpa.NontransactionalWrite">
+          <title>openjpa.NontransactionalWrite</title>
+          <indexterm zone="openjpa.NontransactionalWrite">
+            <primary>NontransactionalWrite</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.NontransactionalWrite</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getNontransactionalWrite">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalWrite</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>NontransactionalWrite</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Whether you can
+			modify persistent objects and perform persistence operations outside
+			of a transaction.  Changes will take effect on the next transaction.
+			</para>
+        </section>
+        <section id="openjpa.ProxyManager">
+          <title>openjpa.ProxyManager</title>
+          <indexterm zone="openjpa.ProxyManager">
+            <primary>ProxyManager</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ProxyManager">
+            <primary>proxies</primary>
+            <secondary>ProxyManager</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ProxyManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getProxyManager">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getProxyManager</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ProxyManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing a <ulink url="../apidocs/org/apache/openjpa/util/ProxyManager.html"><classname>org.apache.openjpa.util.ProxyManager</classname></ulink> to use for proxying mutable second class objects.
+			See <xref linkend="ref_guide_pc_scos_proxy_custom"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.QueryCache">
+          <title>openjpa.QueryCache</title>
+          <indexterm zone="openjpa.QueryCache">
+            <primary>QueryCache</primary>
+          </indexterm>
+          <indexterm zone="openjpa.QueryCache">
+            <primary>caching</primary>
+            <secondary>QueryCache</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.QueryCache</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getQueryCache">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getQueryCache</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>QueryCache</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis><literal>true</literal>,
+			when the data cache (see <xref linkend="openjpa.DataCache"/>) is
+			also enabled, <literal>false</literal> otherwise.
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing the 
+			<ulink url="../apidocs/org/apache/openjpa/datacache/QueryCache.html"><classname>org.apache.openjpa.datacache.QueryCache</classname></ulink> 
+			implementation to use for caching of queries loaded from the data 
+			store.  See <xref linkend="ref_guide_cache_query"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.QueryCompilationCache">
+          <title>openjpa.QueryCompilationCache</title>
+          <indexterm zone="openjpa.QueryCompilationCache">
+            <primary>QueryCompilationCache</primary>
+          </indexterm>
+          <indexterm zone="openjpa.QueryCompilationCache">
+            <primary>caching</primary>
+            <secondary>QueryCompilationCache</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.QueryCompilationCache</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getQueryCompilationCache">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getQueryCompilationCache</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>QueryCompilationCache</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis><literal>true</literal>.
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin
+			string (see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <literal>java.util.Map</literal> to use for
+			caching of data used during query compilation.
+			See <xref linkend="ref_guide_cache_querycomp"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.ReadLockLevel">
+          <title>openjpa.ReadLockLevel</title>
+          <indexterm zone="openjpa.ReadLockLevel">
+            <primary>ReadLockLevel</primary>
+          </indexterm>
+          <indexterm zone="openjpa.ReadLockLevel">
+            <primary>locking</primary>
+            <secondary>ReadLockLevel</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.ReadLockLevel</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getReadLockLevel">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getReadLockLevel</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ReadLockLevel</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>read</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>none</literal>, <literal>read</literal>, 
+			<literal>write</literal>, numeric values for lock-manager specific
+			lock levels
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  The default level
+			at which to lock objects retrieved during a non-optimistic
+			transaction.  Note that for the default JDBC lock manager, <literal>
+			read</literal> and <literal>write</literal> lock levels are
+			equivalent.
+			</para>
+        </section>
+        <section id="openjpa.RemoteCommitProvider">
+          <title>openjpa.RemoteCommitProvider</title>
+          <indexterm zone="openjpa.RemoteCommitProvider">
+            <primary>RemoteCommitProvider</primary>
+          </indexterm>
+          <indexterm zone="openjpa.RemoteCommitProvider">
+            <primary>caching</primary>
+            <secondary>RemoteCommitProvider</secondary>
+          </indexterm>
+          <indexterm zone="openjpa.RemoteCommitProvider">
+            <primary>remote</primary>
+            <secondary>RemoteCommitProvider</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.RemoteCommitProvider</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRemoteCommitProvider">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getRemoteCommitProvider</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>RemoteCommitProvider</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing the
+			<ulink url="../apidocs/org/apache/openjpa/event/RemoteCommitProvider.html"><classname>org.apache.openjpa.event.RemoteCommitProvider
+			</classname></ulink> implementation to use for distributed event
+			notification.  See <xref linkend="ref_guide_event_conf"/> for 
+			more information.
+			</para>
+        </section>
+        <section id="openjpa.RestoreState">
+          <title>openjpa.RestoreState</title>
+          <indexterm zone="openjpa.RestoreState">
+            <primary>RestoreState</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.RestoreState</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRestoreState">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getRestoreState</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>RestoreState</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>none</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>none</literal>, <literal>immutable</literal>, 
+			<literal>all</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> Whether to
+			restore managed fields to their pre-transaction values when
+			a rollback occurs.
+			</para>
+        </section>
+        <section id="openjpa.RetainState">
+          <title>openjpa.RetainState</title>
+          <indexterm zone="openjpa.RetainState">
+            <primary>RetainState</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.RetainState</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRetainState">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getRetainState</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>RetainState</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>true</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Whether persistent
+			fields retain their values on transaction commit.  
+			</para>
+        </section>
+        <section id="openjpa.RetryClassRegistration">
+          <title>openjpa.RetryClassRegistration</title>
+          <indexterm zone="openjpa.RetryClassRegistration">
+            <primary>RetryClassRegistration</primary>
+          </indexterm>
+          <indexterm zone="openjpa.RetryClassRegistration">
+            <primary>metadata</primary>
+            <secondary>RetryClassRegistration</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.RetryClassRegistration</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getRetryClassRegistration">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getRetryClassRegistration</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>RetryClassRegistration</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>false</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> Controls
+			whether to log a warning and defer registration instead of throwing
+			an exception when a persistent class cannot be fully 
+			processed.  This property should <emphasis>only</emphasis> be used 
+			in complex classloader situations where security is preventing
+			OpenJPA from reading registered classes.  Setting this to true
+			unnecessarily may obscure more serious problems.
+			</para>
+        </section>
+        <section id="openjpa.SavepointManager">
+          <title>openjpa.SavepointManager</title>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.SavepointManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="javadoc/openjpa/conf/OpenJPAConfiguration.html#getSavepointManager">
+			org.apache.openjpa.conf.OpenJPAConfiguration.getSavepointManager
+			</ulink>
+          </para>
+          <para><emphasis role="bold">Resource adaptor config-property:</emphasis>
+			SavepointManager
+			</para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>in-mem</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>in-mem</literal>, <literal>jdbc</literal>,
+			<literal>oracle</literal></para>
+          <para><emphasis role="bold">Description:</emphasis>  A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing a <ulink url="javadoc/openjpa/kernel/SavepointManager.html"><classname>org.apache.openjpa.kernel.SavepointManager</classname></ulink>
+			to use for managing transaction savepoints.  See <xref linkend="ref_guide_savepoints"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.Sequence">
+          <title>openjpa.Sequence</title>
+          <indexterm zone="openjpa.Sequence">
+            <primary>Sequence</primary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.Sequence</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getSequence">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getSequence</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Sequence</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>table</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing the
+			<ulink url="../apidocs/org/apache/openjpa/kernel/Seq.html"><classname>
+			org.apache.openjpa.kernel.Seq</classname></ulink> implementation to use for the
+			system sequence.  See <xref linkend="ref_guide_sequence"/> for 
+			more information.
+			</para>
+        </section>
+        <section id="openjpa.TransactionMode">
+          <title>openjpa.TransactionMode</title>
+          <indexterm zone="openjpa.TransactionMode">
+            <primary>TransactionMode</primary>
+          </indexterm>
+          <indexterm zone="openjpa.TransactionMode">
+            <primary>transactions</primary>
+            <secondary>TransactionMode</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.TransactionMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getTransactionMode">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getTransactionMode</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>TransactionMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>local</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>local</literal>, <literal>managed</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> The default 
+			transaction mode to use.  You can override this setting per-session.
+			</para>
+        </section>
+        <section id="openjpa.WriteLockLevel">
+          <title>openjpa.WriteLockLevel</title>
+          <indexterm zone="openjpa.WriteLockLevel">
+            <primary>WriteLockLevel</primary>
+          </indexterm>
+          <indexterm zone="openjpa.WriteLockLevel">
+            <primary>locking</primary>
+            <secondary>WriteLockLevel</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.WriteLockLevel</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/conf/OpenJPAConfiguration.html#getWriteLockLevel">
+              <methodname>org.apache.openjpa.conf.OpenJPAConfiguration.getWriteLockLevel</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>WriteLockLevel</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>write</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>none</literal>, <literal>read</literal>, 
+			<literal>write</literal>, numeric values for lock-manager specific
+			lock levels
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>  The default level
+			at which to lock objects changed during a non-optimistic
+			transaction.  Note that for the default JDBC lock manager, <literal>
+			read</literal> and <literal>write</literal> lock levels are
+			equivalent.
+			</para>
+        </section>
+      </section>
+      <section id="ref_guide_conf_jdbc">
+        <title>OpenJPA JDBC Properties</title>
+        <indexterm zone="ref_guide_conf_jdbc">
+          <primary>configuration</primary>
+          <secondary>of JDBC properties</secondary>
+        </indexterm>
+        <para>
+		The following properties apply exclusively to the OpenJPA JDBC back-end.
+		</para>
+        <section id="openjpa.jdbc.ConnectionDecorators">
+          <title>openjpa.jdbc.ConnectionDecorators</title>
+          <indexterm zone="openjpa.jdbc.ConnectionDecorators">
+            <primary>ConnectionDecorators</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.ConnectionDecorators">
+            <primary>connections</primary>
+            <secondary>ConnectionDecorators</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.ConnectionDecorators</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getConnectionDecorators">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getConnectionDecorators</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ConnectionDecorators</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A comma-separated
+			list of plugin strings (see 
+			<xref linkend="ref_guide_conf_plugins"/>) describing
+			<ulink url="../apidocs/org/apache/openjpa/lib/jdbc/ConnectionDecorator.html"><classname>org.apache.openjpa.lib.jdbc.ConnectionDecorator</classname></ulink> instances to install on the connection factory.
+			These decorators can wrap connections passed from the underlying 
+			<classname>DataSource</classname> to add functionality.  OpenJPA will 
+			pass all connections through the list of decorators before using 
+			them.  Note that by default OpenJPA <phrase>JPA</phrase> employs all of the 
+			built-in decorators in the 
+			<classname>org.apache.openjpa.lib.jdbc</classname> package already; you
+			do not need to list them here.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.DBDictionary">
+          <title>openjpa.jdbc.DBDictionary</title>
+          <indexterm zone="openjpa.jdbc.DBDictionary">
+            <primary>DBDictionary</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.DBDictionary">
+            <primary>JDBC</primary>
+            <secondary>DBDictionary</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.DBDictionary</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getDBDictionary">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDBDictionary</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DBDictionary</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> Based on the
+			<link linkend="openjpa.ConnectionURL"><literal>openjpa.ConnectionURL</literal></link><link linkend="openjpa.ConnectionDriverName"><literal>openjpa.ConnectionDriverName</literal></link></para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <ulink url="../apidocs/org/apache/openjpa/jdbc/sql/DBDictionary.html"><classname>org.apache.openjpa.jdbc.sql.DBDictionary</classname></ulink> to use 
+			for database interaction.  OpenJPA typically auto-configures the 
+			dictionary based on the JDBC URL, but you may have to set this 
+			property explicitly if you are
+			using an unrecognized driver, or to plug in your own dictionary
+			for a database OpenJPA <phrase>JPA</phrase> does not support out-of-the-box. 
+			See <xref linkend="ref_guide_dbsetup_dbsupport"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.DriverDataSource">
+          <title>openjpa.jdbc.DriverDataSource</title>
+          <indexterm zone="openjpa.jdbc.DriverDataSource">
+            <primary>DriverDataSource</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.DriverDataSource">
+            <primary>JDBC</primary>
+            <secondary>DriverDataSource</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.DriverDataSource</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getDriverDataSource">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDriverDataSource</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>DriverDataSource</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>pooling</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> The alias or
+			full class name of the 
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/DriverDataSource.html"><classname>org.apache.openjpa.jdbc.schema.DriverDataSource
+			</classname></ulink> implementation to use to wrap
+			JDBC Driver classes with javax.sql.DataSource instances.
+			The provided default implementation 
+			(<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/OpenJPAPoolingDataSource"><classname>org.apache.openjpa.jdbc.schema.OpenJPAPoolingDataSource</classname></ulink>,
+			will perform connection pooling as described at
+			<xref linkend="ref_guide_dbsetup"/>.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.EagerFetchMode">
+          <title>openjpa.jdbc.EagerFetchMode</title>
+          <indexterm zone="openjpa.jdbc.EagerFetchMode">
+            <primary>EagerFetchMode</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.EagerFetchMode">
+            <primary>eager fetching</primary>
+            <secondary>EagerFetchMode</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.EagerFetchMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getEagerFetchMode">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getEagerFetchMode</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>EagerFetchMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>parallel</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>parallel</literal>, <literal>join</literal>,
+			<literal>none</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> Optimizes how OpenJPA
+			loads persistent relations.  This setting can also be varied at
+			runtime.  See <xref linkend="ref_guide_perfpack_eager"/> for 
+			details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.FetchDirection">
+          <title>openjpa.jdbc.FetchDirection</title>
+          <indexterm zone="openjpa.jdbc.FetchDirection">
+            <primary>FetchDirection</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.FetchDirection">
+            <primary>large result sets</primary>
+            <secondary>FetchDirection</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.FetchDirection</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getFetchDirection">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getFetchDirection</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>FetchDirection</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>forward</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>forward</literal>, <literal>reverse</literal>,
+			<literal>unknown</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> The expected order
+			in which query result lists will be accessed.  This
+			property can also be varied at runtime.
+			See <xref linkend="ref_guide_dbsetup_lrs"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.JDBCListeners">
+          <title>openjpa.jdbc.JDBCListeners</title>
+          <indexterm zone="openjpa.jdbc.JDBCListeners">
+            <primary>JDBCListeners</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.JDBCListeners">
+            <primary>JDBC</primary>
+            <secondary>JDBCListeners</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.JDBCListeners</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getJDBCListeners">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getJDBCListeners</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>JDBCListeners</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A comma-separated
+			list of plugin strings (see 
+			<xref linkend="ref_guide_conf_plugins"/>) describing
+			<ulink url="../apidocs/org/apache/openjpa/lib/jdbc/JDBCListener.html"><classname>org.apache.openjpa.lib.jdbc.JDBCListener</classname></ulink>
+			event listeners to install.  These listeners will be notified
+			on various JDBC-related events.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.LRSSize">
+          <title>openjpa.jdbc.LRSSize</title>
+          <indexterm zone="openjpa.jdbc.LRSSize">
+            <primary>LRSSize</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.LRSSize">
+            <primary>large result sets</primary>
+            <secondary>LRSSize</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.LRSSize</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getLRSSize">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getLRSSize</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>LRSSize</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>query</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>query</literal>, <literal>last</literal>,
+			<literal>unknown</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> The strategy to use
+			to calculate the size of a result list.  This
+			property can also be varied at runtime.
+			See <xref linkend="ref_guide_dbsetup_lrs"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.MappingDefaults">
+          <title>openjpa.jdbc.MappingDefaults</title>
+          <indexterm zone="openjpa.jdbc.MappingDefaults">
+            <primary>MappingDefaults</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.MappingDefaults">
+            <primary>mapping metadata</primary>
+            <secondary>MappingDefaults</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.MappingDefaults</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getMappingDefaults">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingDefaults</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>MappingDefaults</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> default
+			</para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>default</literal>, <literal>jpa</literal>, 
+			<literal>openjpa3</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>) describing the 
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingDefaults.html"><classname>org.apache.openjpa.jdbc.meta.MappingDefaults</classname></ulink> to
+			use to define default column names, table names, and constraints
+			for your persistent classes.  See
+			<xref linkend="ref_guide_mapping_factory"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.MappingFactory">
+          <title>openjpa.jdbc.MappingFactory</title>
+          <indexterm zone="openjpa.jdbc.MappingFactory">
+            <primary>MappingFactory</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.MappingFactory">
+            <primary>mapping metadata</primary>
+            <secondary>MappingFactory</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.MappingFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getMappingFactory">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingFactory</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>MappingFactory</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>jdo-orm</literal>, <literal>jdo-table</literal>,
+			<literal>jpa</literal>, others
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the <ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html"><classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink> to 
+			use to store and retrieve object-relational mapping information 
+			for your persistent classes.  See
+			<xref linkend="ref_guide_mapping_factory"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.ResultSetType">
+          <title>openjpa.jdbc.ResultSetType</title>
+          <indexterm zone="openjpa.jdbc.ResultSetType">
+            <primary>ResultSetType</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.ResultSetType">
+            <primary>large result sets</primary>
+            <secondary>ResultSetType</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.ResultSetType</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getResultSetType">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getResultSetType</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>ResultSetType</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>forward-only
+			</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>forward-only</literal>, 
+			<literal>scroll-sensitive</literal>,
+			<literal>scroll-insensitive</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> The JDBC result set
+			type to use when fetching result lists.  This
+			property can also be varied at runtime.
+			See <xref linkend="ref_guide_dbsetup_lrs"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.Schema">
+          <title>openjpa.jdbc.Schema</title>
+          <indexterm zone="openjpa.jdbc.Schema">
+            <primary>schema</primary>
+            <secondary>Schema</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.Schema</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSchema">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchema</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Schema</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> The default schema
+			name to prepend to unqualified table names.  Also, the schema in
+			which OpenJPA will create new tables.  See 
+			<xref linkend="ref_guide_schema_def"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.SchemaFactory">
+          <title>openjpa.jdbc.SchemaFactory</title>
+          <indexterm zone="openjpa.jdbc.SchemaFactory">
+            <primary>SchemaFactory</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.SchemaFactory">
+            <primary>schema</primary>
+            <secondary>SchemaFactory</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.SchemaFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSchemaFactory">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemaFactory</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>SchemaFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>dynamic</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>dynamic</literal>, <literal>native</literal>,
+			<literal>file</literal>, <literal>table</literal>, others
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/SchemaFactory.html"><classname>org.apache.openjpa.jdbc.schema.SchemaFactory</classname></ulink> to 
+			use to store and retrieve information about the database schema.  
+			See <xref linkend="ref_guide_schema_info_factory"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.Schemas">
+          <title>openjpa.jdbc.Schemas</title>
+          <indexterm zone="openjpa.jdbc.Schemas">
+            <primary>schema</primary>
+            <secondary>Schemas</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.Schemas</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSchemas">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemas</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>Schemas</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis> A comma-separated
+			list of the schemas and/or tables used for your persistent
+			data.  See <xref linkend="ref_guide_schema_info_list"/>
+			for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.SQLFactory">
+          <title>openjpa.jdbc.SQLFactory</title>
+          <indexterm zone="openjpa.jdbc.SQLFactory">
+            <primary>SQLFactory</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.SQLFactory">
+            <primary>SQL</primary>
+            <secondary>SQLFactory</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.SQLFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSQLFactory">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSQLFactory</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>SQLFactory</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> A plugin string
+			(see <xref linkend="ref_guide_conf_plugins"/>)
+			describing the
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/SQLFactory.html"><classname>org.apache.openjpa.jdbc.sql.SQLFactory</classname></ulink> to 
+			use to abstract common SQL constructs.  
+			See <xref linkend="ref_guide_dbsetup_sqlfactory"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.SubclassFetchMode">
+          <title>openjpa.jdbc.SubclassFetchMode</title>
+          <indexterm zone="openjpa.jdbc.SubclassFetchMode">
+            <primary>SubclassFetchMode</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.SubclassFetchMode">
+            <primary>eager fetching</primary>
+            <secondary>SubclassFetchMode</secondary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.SubclassFetchMode">
+            <primary>inheritance</primary>
+            <secondary>SubclassFetchMode</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.SubclassFetchMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSubclassFetchMode">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSubclassFetchMode</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>SubclassFetchMode</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>parallel
+			</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>parallel</literal>, <literal>join</literal>,
+			<literal>none</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> How to select
+			subclass data when it is in other tables.  This 
+			setting can also be varied at runtime.
+			See <xref linkend="ref_guide_perfpack_eager"/>.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.SynchronizeMappings">
+          <title>openjpa.jdbc.SynchronizeMappings</title>
+          <indexterm zone="openjpa.jdbc.SynchronizeMappings">
+            <primary>SynchronizeMappings</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.SynchronizeMappings">
+            <primary>mapping metadata</primary>
+            <secondary>SynchronizeMappings</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.SynchronizeMappings</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getSynchronizeMappings">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSynchronizeMappings</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>SynchronizeMappings</literal>
+          </para>
+          <para><emphasis role="bold">Default:</emphasis> -
+			</para>
+          <para><emphasis role="bold">Description:</emphasis>
+			Controls whether OpenJPA will attempt to run the mapping tool on
+			all persistent classes to synchronize their mappings and schema
+			at runtime.  Useful for rapid test/debug cycles.  See
+			<xref linkend="ref_guide_mapping_synch"/> for more information.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.TransactionIsolation">
+          <title>openjpa.jdbc.TransactionIsolation</title>
+          <indexterm zone="openjpa.jdbc.TransactionIsolation">
+            <primary>TransactionIsolation</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.TransactionIsolation">
+            <primary>transactions</primary>
+            <secondary>TransactionIsolation</secondary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.TransactionIsolation">
+            <primary>JDBC</primary>
+            <secondary>TransactionIsolation</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.TransactionIsolation</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getTransactionIsolation">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getTransactionIsolation</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>TransactionIsolation</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Possible values:</emphasis><literal>default</literal>, <literal>none</literal>,
+			<literal>read-committed</literal>, 
+			<literal>read-uncommitted</literal>,
+			<literal>repeatable-read</literal>, <literal>serializable</literal></para>
+          <para><emphasis role="bold">Description:</emphasis> The JDBC transaction
+			isolation level to use.  See
+			<xref linkend="ref_guide_dbsetup_isolation"/> for details.
+			</para>
+        </section>
+        <section id="openjpa.jdbc.UpdateManager">
+          <title>openjpa.jdbc.UpdateManager</title>
+          <indexterm zone="openjpa.jdbc.UpdateManager">
+            <primary>UpdateManager</primary>
+          </indexterm>
+          <indexterm zone="openjpa.jdbc.UpdateManager">
+            <primary>JDBC</primary>
+            <secondary>UpdateManager</secondary>
+          </indexterm>
+          <para>
+            <emphasis role="bold">Property name:</emphasis>
+            <literal>openjpa.jdbc.UpdateManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Configuration API:</emphasis>
+            <ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html#getUpdateManager">
+              <methodname>org.apache.openjpa.jdbc.conf.JDBCConfiguration.getUpdateManager</methodname>
+            </ulink>
+          </para>
+          <para>
+            <emphasis role="bold">Resource adaptor config-property:</emphasis>
+            <literal>UpdateManager</literal>
+          </para>
+          <para>
+            <emphasis role="bold">Default:</emphasis>
+            <literal>default</literal>
+          </para>
+          <para><emphasis role="bold">Description:</emphasis> The full class
+			name of the 
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/UpdateManager.html"><classname>org.apache.openjpa.jdbc.kernel.UpdateManager
+			</classname></ulink> to use to flush persistent object changes
+			to the datastore.  The provided default implementation is
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/ConstraintUpdateManager"><classname>org.apache.openjpa.jdbc.kernel.ConstraintUpdateManager</classname></ulink>.
+			</para>
+        </section>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_logging">
+      <title>Logging</title>
+      <indexterm zone="ref_guide_logging">
+        <primary>logging</primary>
+      </indexterm>
+      <indexterm zone="ref_guide_logging">
+        <primary>Log</primary>
+      </indexterm>
+      <para>
+	Logging is an important means of gaining insight into your application's
+	runtime behavior.  OpenJPA
+	provides a flexible logging system that integrates with many
+	existing runtime systems, such as application servers and servlet
+	runners.
+	</para>
+      <para>
+	There are four built-in logging plugins: a 
+	<link linkend="ref_guide_logging_openjpa">default logging framework</link>
+	that covers most needs, a <link linkend="ref_guide_logging_log4j">
+	Log4J</link> delegate, an <link linkend="ref_guide_logging_commons">
+	Apache Commons Logging</link> delegate, and a 
+	<link linkend="ref_guide_logging_noop">no-op</link> implementation for
+	disabling logging.
+	</para>
+      <warning>
+        <para>
+		Logging can have a negative impact on performance. Disable
+		verbose logging (such as logging of SQL statements) before
+		running any performance tests. It is advisable to limit or
+		disable logging for a production system. You can
+		disable logging altogether by setting
+		the <literal>openjpa.Log</literal> property
+		to <literal>none</literal>.
+		</para>
+      </warning>
+      <section id="ref_guide_logging_channels">
+        <title>Logging Channels</title>
+        <indexterm zone="ref_guide_logging_channels">
+          <primary>logging</primary>
+          <secondary>channels</secondary>
+        </indexterm>
+        <para>
+		Logging is done over a number of <emphasis>logging channels</emphasis>,
+		each of which has a <emphasis>logging level</emphasis> which controls
+		the verbosity of log messages recorded for the channel.  OpenJPA uses
+		the following logging channels:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>openjpa.Tool</literal>: Messages issued by the OpenJPA
+				command line and Ant tools.  Most messages
+				are basic statements detailing which classes or files the 
+				tools are running on.  Detailed output is only available via
+				the logging category the tool belongs to, such as 
+				<literal>openjpa.Enhance</literal> for the enhancer
+				(see <xref linkend="ref_guide_pc_enhance"/>) or
+				<literal>openjpa.MetaData</literal> for the mapping tool
+				(see <xref linkend="ref_guide_mapping_mappingtool"/>).
+				This logging category is provided so that you can
+				get a general idea of what a tool is doing without having to
+				manipulate logging settings that might also affect runtime
+				behavior.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>configuration</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Configuration</literal>: Messages issued
+				by the configuration framework.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>enhancement</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Enhance</literal>: Messages pertaining to
+				enhancement and runtime class generation.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>metadata</primary><secondary>log messages</secondary></indexterm><literal>openjpa.MetaData</literal>: Details about the generation 
+				of metadata and object-relational mappings.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>openjpa.Runtime</literal>: General OpenJPA runtime messages.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Query</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Query</literal>: Messages about queries.
+				Query strings and any parameter values, if applicable, will be 
+				logged to the <literal>TRACE</literal> level at execution
+				time. Information about possible performance concerns
+				will be logged to the <literal>INFO</literal> level.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>remote</primary><secondary>log messages</secondary></indexterm><literal>openjpa.Remote</literal>: Remote connection and execution
+				messages.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>caching</primary><secondary>log messages</secondary></indexterm><literal>openjpa.DataCache</literal>: Messages from the L2 data 
+				cache plugins.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>JDBC</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.JDBC</literal>: JDBC connection information.
+				General JDBC information will be logged to the <literal>TRACE
+				</literal> level.  Information about possible performance 
+				concerns will be logged to the <literal>INFO</literal> level.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>SQL</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.SQL</literal>: This is the most common 
+				logging channel to use.  Detailed information about the 
+				execution of SQL statements will be sent to the 
+				<literal>TRACE</literal> level.  It is useful to enable this 
+				channel if you are curious about the exact SQL that OpenJPA 
+				issues to the datastore.
+				</para>
+            <para>
+				When using the built-in OpenJPA logging facilities, you can 
+				enable SQL logging by adding <literal>SQL=TRACE</literal> to
+				your <literal>openjpa.Log</literal> property.
+				</para>
+            <para>
+				OpenJPA can optionally reformat the logged SQL to
+				make it easier to read. To enable pretty-printing,
+				add <literal>PrettyPrint=true</literal> to the
+				<link linkend="openjpa.ConnectionFactoryProperties"><literal>
+				openjpa.ConnectionFactoryProperties</literal></link>
+				property. You can control how many columns wide the
+				pretty-printed SQL will be with the 
+				<literal>PrettyPrintLineLength</literal> property. The default 
+				line length is 60 columns.</para>
+            <para>
+				While pretty printing makes things easier to read, it can make 
+				output harder to process with tools like grep.
+				</para>
+            <para>
+				Pretty-printing properties configuration might look like so:
+				</para>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="SQL=TRACE"/&gt;
+&lt;property name="openjpa.ConnectionFactoryProperties" 
+    value="MaxActive=100, PrettyPrint=true, PrettyPrintLineLength=72"/&gt;
+</programlisting>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>schema</primary><secondary>log messages</secondary></indexterm><literal>openjpa.jdbc.Schema</literal>: Details about operations 
+				on the database schema.
+				</para>
+          </listitem>
+        </itemizedlist>
+      </section>
+      <section id="ref_guide_logging_openjpa">
+        <title>OpenJPA Logging</title>
+        <indexterm zone="ref_guide_logging_openjpa">
+          <primary>logging</primary>
+          <secondary>default</secondary>
+        </indexterm>
+        <para>
+		By default, OpenJPA uses a basic logging framework with the following
+		output format:
+		</para>
+        <para><literal>millis</literal><literal>level</literal>  [<literal>thread name</literal>] <literal>channel</literal> - <literal>message</literal></para>
+        <para>
+		For example, when loading an application that uses OpenJPA, a message 
+		like the following will be sent to the <literal>openjpa.Runtime</literal>
+		channel:
+		</para>
+        <programlisting format="linespecific">
+2107  INFO   [main] openjpa.Runtime - Starting OpenJPA 4.0.0
+</programlisting>
+        <para>
+		The default logging system accepts the following parameters:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>File</literal>: The name of the file to log to, or
+				<literal>stdout</literal> or <literal>stderr</literal> to send
+				messages to standard out and standard error, respectively.
+				By default, OpenJPA sends log messages to standard error.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>DefaultLevel</literal>: The default logging level of
+				unconfigured channels.  Recognized values are <literal>
+				TRACE, DEBUG, INFO, WARN,</literal> and <literal>ERROR
+				</literal>.  Defaults to <literal>INFO</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>DiagnosticContext</literal>: A string that will 
+				be prepended to all log messages.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>&lt;channel&gt;</literal>: Using the last token of
+				the <link linkend="ref_guide_logging_channels">logging channel 
+				</link> name, you can configure the log level to
+				use for that channel.  See the examples below.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_logging_openjpa_std_ex">
+          <title>Standard OpenJPA Log Configuration</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_logging_openjpa_sql_ex">
+          <title>Standard OpenJPA Log Configuration + All SQL Statements</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO, SQL=TRACE"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_logging_openjpa_file">
+          <title>Logging to a File</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Log" value="File=/tmp/org.apache.openjpa.log, DefaultLevel=WARN, Runtime=INFO, Tool=INFO"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_logging_noop">
+        <title>Disabling Logging</title>
+        <indexterm zone="ref_guide_logging_noop">
+          <primary>logging</primary>
+          <secondary>disabling</secondary>
+        </indexterm>
+        <para>
+		Disabling logging can be useful to analyze performance without
+		any I/O overhead or to reduce verbosity at the console. To do
+		this, set the <literal>openjpa.Log</literal> property
+		to <literal>none</literal>.
+		</para>
+        <para>
+		Disabling logging permanently, however, will cause all warnings
+		to be consumed.  We recommend using one of the
+		more sophisticated mechanisms described in this chapter.
+		</para>
+      </section>
+      <section id="ref_guide_logging_log4j">
+        <title>Log4J</title>
+        <indexterm zone="ref_guide_logging_log4j">
+          <primary>logging</primary>
+          <secondary>Log4j</secondary>
+        </indexterm>
+        <para>
+		When <literal>openjpa.Log</literal> is set
+		to <literal>log4j</literal>, OpenJPA will delegate to Log4J for logging.
+		In a standalone application, Log4J logging levels are
+		controlled by a resource named <filename>log4j.properties</filename>, 
+		which should be available as a top-level resource (either at the top 
+		level of a jar file, or in the root of one of
+		the <literal>CLASSPATH</literal> directories). When deploying to
+		a web or EJB application server, Log4J configuration is often
+		performed in a <filename>log4j.xml</filename> file instead of a
+		properties file. For further details on configuring Log4J,
+		please see the 
+		<ulink url="http://jakarta.apache.org/log4j/docs/manual.html">Log4J
+		Manual</ulink>. We present an example 
+		<filename>log4j.properties</filename> file below.
+		</para>
+        <example id="ref_guide_logging_log4j_ex">
+          <title>Standard Log4J Logging</title>
+          <programlisting format="linespecific">
+log4j.rootCategory=WARN, console
+log4j.category.openjpa.Tool=INFO
+log4j.category.openjpa.Runtime=INFO
+log4j.category.openjpa.Remote=WARN
+log4j.category.openjpa.DataCache=WARN
+log4j.category.openjpa.MetaData=WARN
+log4j.category.openjpa.Enhance=WARN
+log4j.category.openjpa.Query=WARN
+log4j.category.openjpa.jdbc.SQL=WARN
+log4j.category.openjpa.jdbc.JDBC=WARN
+log4j.category.openjpa.jdbc.Schema=WARN
+
+log4j.appender.console=org.apache.log4j.ConsoleAppender
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_logging_commons">
+        <title>Apache Commons Logging</title>
+        <indexterm zone="ref_guide_logging_commons">
+          <primary>logging</primary>
+          <secondary>Apache Commons</secondary>
+        </indexterm>
+        <para>
+		Set the <literal>openjpa.Log</literal> property to <literal>commons
+		</literal> to use the
+		<ulink url="http://jakarta.apache.org/commons/logging.html">
+		Apache Jakarta Commons Logging</ulink> thin library for issuing
+		log messages. The Commons Logging libraries act as a wrapper
+		around a number of popular logging APIs, including the
+		<ulink url="http://jakarta.apache.org/log4j/docs/index.html">
+		Jakarta Log4J</ulink> project, and the native
+		<ulink url="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
+		java.util.logging</ulink> package in JDK 1.4.  If neither of these
+		libraries are available, then logging will fall back to using simple 
+		console logging.
+		</para>
+        <para>
+		When using the Commons Logging framework in conjunction with
+		Log4J, configuration will be the same as was discussed in the
+		Log4J section above.
+		</para>
+        <section id="ref_guide_logging_jdk14">
+          <title>JDK 1.4 java.util.logging</title>
+          <indexterm zone="ref_guide_logging_jdk14">
+            <primary>logging</primary>
+            <secondary>JDK 1.4</secondary>
+          </indexterm>
+          <para>
+			When using JDK 1.4 or higher in conjunction with OpenJPA's
+			Commons Logging support, logging will proceed through Java's
+			built-in logging provided by the
+			<ulink url="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
+			java.util.logging</ulink> package. For details on
+			configuring the built-in logging system, please see the
+			<ulink url="http://java.sun.com/j2se/1.4/docs/guide/util/logging/overview.html">
+			Java Logging Overview</ulink>.
+			</para>
+          <para>
+			By default, JDK 1.4's logging package looks in
+			the <filename> JAVA_HOME/lib/logging.properties</filename>
+			file for logging configuration. This can be overridden with
+			the <literal> java.util.logging.config.file</literal> system
+			property. For example:
+			</para>
+          <programlisting format="linespecific">
+java -Djava.util.logging.config.file=mylogging.properties com.company.MyClass
+</programlisting>
+          <example id="ref_guide_logging_jdk14_propfile">
+            <title>JDK 1.4 Log Properties</title>
+            <programlisting format="linespecific">
+# specify the handlers to create in the root logger
+# (all loggers are children of the root logger)
+# the following creates two handlers
+handlers=java.util.logging.ConsoleHandler, java.util.logging.FileHandler
+    
+# set the default logging level for the root logger
+.level=ALL
+    
+# set the default logging level for new ConsoleHandler instances
+java.util.logging.ConsoleHandler.level=INFO
+
+# set the default logging level for new FileHandler instances
+java.util.logging.FileHandler.level=ALL
+
+# set the default formatter for new ConsoleHandler instances
+java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter
+
+# set the default logging level for all OpenJPA logs
+openjpa.Tool.level=INFO
+openjpa.Runtime.level=INFO
+openjpa.Remote.level=INFO
+openjpa.DataCache.level=INFO
+openjpa.MetaData.level=INFO
+openjpa.Enhance.level=INFO
+openjpa.Query.level=INFO
+openjpa.jdbc.SQL.level=INFO
+openjpa.jdbc.JDBC.level=INFO
+openjpa.jdbc.Schema.level=INFO
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_logging_custom">
+        <title>Custom Log</title>
+        <indexterm zone="ref_guide_logging_custom">
+          <primary>logging</primary>
+          <secondary>custom</secondary>
+        </indexterm>
+        <para>
+		If none of available logging systems meet your needs, you can configure
+		the logging system with a custom logger.  You might use
+		custom logging to integrate with a proprietary logging framework used 
+		by some applications servers, or for logging to a graphical component 
+		for GUI applications.
+		</para>
+        <para>
+		A custom logging framework must include an implementation of the
+		<ulink url="../apidocs/org/apache/openjpa/lib/log/LogFactory.html"><classname>org.apache.openjpa.lib.log.LogFactory</classname></ulink> interface.
+		We present a custom <classname>LogFactory</classname> below.
+		</para>
+        <example id="ref_guide_logging_custom_ex">
+          <title>Custom Logging Class</title>
+          <programlisting format="linespecific">
+package com.xyz;
+
+import org.apache.openjpa.lib.log.*;
+
+public class CustomLogFactory
+    implements LogFactory
+{   
+    private String _prefix = "CUSTOM LOG";
+
+    public void setPrefix (String prefix)
+    {
+        _prefix = prefix;
+    }
+ 
+    public Log getLog (String channel)
+    {
+        // Return a simple extension of AbstractLog that will log
+        // everything to the System.err stream. Note that this is 
+        // roughly equivalent to OpenJPA's default logging behavior.
+        return new AbstractLog ()
+        {
+            protected boolean isEnabled (short logLevel)
+            {
+                // log all levels
+                return true;
+            }
+
+            protected void log (short type, String message, Throwable t)
+            {
+                // just send everything to System.err
+                System.err.println (_prefix + ": " + type + ": "
+                    + message + ": " + t);
+            }
+        };
+    }
+}</programlisting>
+        </example>
+        <para>
+		To make OpenJPA use your custom log factory, set the 
+		<link linkend="openjpa.Log"><literal>openjpa.Log</literal></link> 
+		configuration property to your factory's full class name.  Because
+		this property is a plugin property (see 
+		<xref linkend="ref_guide_conf_plugins"/>), you can also pass parameters
+		to your factory.  For example, to use the example factory above and
+		set its prefix to "LOG MSG", you would set the 
+		<literal>openjpa.Log</literal> property to the following string:
+		</para>
+        <programlisting format="linespecific">
+com.xyz.CustomLogFactory(Prefix="LOG MSG")
+</programlisting>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_dbsetup">
+      <title>JDBC</title>
+      <indexterm zone="ref_guide_dbsetup">
+        <primary>JDBC</primary>
+      </indexterm>
+      <para>
+	OpenJPA <phrase>JPA</phrase> uses a relational database for object persistence. It 
+	communicates with the database using the Java DataBase Connectivity (JDBC) 
+	APIs.  This chapter describes how to configure OpenJPA to work with the
+	JDBC driver for your database, and how to access JDBC functionality at
+	runtime.
+	</para>
+      <section id="ref_guide_dbsetup_builtin">
+        <title>Using the OpenJPA DataSource</title>
+        <indexterm zone="ref_guide_dbsetup_builtin">
+          <primary>DataSource</primary>
+          <secondary>OpenJPA</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>connections</primary>
+          <seealso>DataSource</seealso>
+        </indexterm>
+        <para>
+		OpenJPA includes its own <classname>javax.sql.DataSource</classname>
+		implementation, complete with configurable connection pooling
+		and prepared statement caching.  If you choose to use
+		OpenJPA's <classname>DataSource</classname>, then you must specify
+		the following properties:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>ConnectionUserName</primary></indexterm><literal>openjpa.ConnectionUserName</literal>:
+				The JDBC user name for connecting to the database.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ConnectionPassword</primary></indexterm><literal>openjpa.ConnectionPassword</literal>:
+				The JDBC password for the above user.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ConnectionURL</primary></indexterm><literal>openjpa.ConnectionURL</literal>:
+				The JDBC URL for the database.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ConnectionDriverName</primary></indexterm><literal>openjpa.ConnectionDriverName</literal>:
+				The JDBC driver class.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		To configure advanced features such as connection pooling and prepared
+		statement caching, or to configure the underlying JDBC driver, use the 
+		following optional properties.  The syntax of these property strings 
+		follows the syntax of OpenJPA plugin parameters described in
+		<xref linkend="ref_guide_conf_plugins"/>.
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>ConnectionProperties</primary></indexterm><link linkend="openjpa.ConnectionProperties"><literal>openjpa.ConnectionProperties</literal></link>:
+				If the listed driver is an instance of 
+				<classname>java.sql.Driver</classname>, this string will
+				be parsed into a <classname>Properties</classname> instance, 
+				which will then be used to obtain database connections through 
+				the <methodname>Driver.connect(String url, 
+				Properties props)</methodname> method.  If, on the other hand, 
+				the listed driver is a <classname>
+				javax.sql.DataSource</classname>, 
+				the string will be treated as a plugin properties string, and 
+				matched to the bean setter methods of the 
+				<classname>DataSource</classname> instance.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ConnectionFactoryProperties</primary></indexterm><link linkend="openjpa.ConnectionFactoryProperties"><literal>openjpa.ConnectionFactoryProperties</literal></link>: 
+				OpenJPA's built-in <classname>DataSource</classname> 
+				allows you to set the following options via
+				this plugin string:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ExceptionAction</tertiary></indexterm><literal>ExceptionAction</literal>: The action to
+						take when when a connection that has thrown an exception
+						is returned to the pool.  Set to <literal>destroy
+						</literal> to destroy the connection. Set to <literal>
+						validate</literal> to validate the connection (subject
+						to the <literal>TestOnReturn</literal>, <literal>
+						TestOnBorrow</literal>, and other test settings).
+						Set to <literal>none</literal> to ignore the fact that
+						the connection has thrown an exception, and assume it
+						is still usable.  Defaults to <literal>
+						destroy</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxActive</tertiary></indexterm><literal>MaxActive</literal>: The maximum number of
+						database connections in use at one time.  A value of 0
+						disables connection pooling.  Defaults to 8.
+						This is the maximum number of connections that OpenJPA will
+						give out to your application. If a connection is
+ 						requested while <literal>MaxActive</literal> other
+						connections are in use, OpenJPA will wait for
+						<literal>MaxWait</literal> milliseconds for a connection
+						to be returned, and will then throw an exception if no
+						connection was made available.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxIdle</tertiary></indexterm><literal>MaxIdle</literal>: The maximum number of
+						idle database connections to keep in the pool.  Defaults
+						to 8. If this number is less than
+						<literal>MaxActive</literal>, then OpenJPA will close
+						extra connections that are returned to the pool if
+						there are already <literal>MaxIdle</literal> available
+						connections.  This allows for
+						unexpected or atypical load while still maintaining
+						a relatively small pool when there is less load on the
+						system.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxTotal</tertiary></indexterm><literal>MaxTotal</literal>: The maximum number of
+						database connections in the pool, whether active or
+						idle.  Defaults to -1, meaning no limit (the limit will
+						be dictated by <literal>MaxActive</literal> and
+						<literal>MaxIdle</literal> for each unique user name).
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxWait</tertiary></indexterm><literal>MaxWait</literal>: The maximum number of
+						milliseconds to wait for a free database connection to 
+						become available before giving up.  Defaults to 3000.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MinEvictableIdleTimeMillis</tertiary></indexterm><literal>MinEvictableIdleTimeMillis</literal>: The 
+						minimum number of milliseconds that a database 
+						connection can sit idle before it becomes a candidate 
+						for eviction from the pool.  Defaults to 30 minutes.  
+						Set to 0 to never evict a connection based on idle 
+						time alone.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>RollbackOnReturn</tertiary></indexterm><literal>RollbackOnReturn</literal>:
+						Force all connections to be rolled back when they
+						are retuned to the pool. If false, the <classname>
+						DataSource</classname> will
+						only roll back connections when it detects that there
+						have been any transactional updates on the connection.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TestOnBorrow</tertiary></indexterm><literal>TestOnBorrow</literal>: Whether to to validate
+						database connections before obtaining them from the 
+						pool.  Note that validation
+						only consists of a call to the connection's 
+						<methodname>isClosed</methodname> method unless you 
+						specify a <literal>ValidationSQL</literal> string.
+						Defaults to <literal>true</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TestOnReturn</tertiary></indexterm><literal>TestOnReturn</literal>: Set to <literal>true
+						</literal> to validate database connections when they 
+						are returned to the pool.  Note that validation 
+						only consists of a call to the connection's 
+						<methodname>isClosed</methodname> method unless you 
+						specify a <literal>ValidationSQL</literal> string.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TestWhileIdle</tertiary></indexterm><literal>TestWhileIdle</literal>: Set to 
+						<literal>true</literal> to periodically validate idle 
+						database connections.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TimeBetweenEvictionRunsMillis</tertiary></indexterm><literal>TimeBetweenEvictionRunsMillis</literal>: The
+						number of milliseconds between runs of the eviction
+						thread.  Defaults to <literal>-1</literal>, meaning 
+						the eviction thread will never run.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TrackParameters</tertiary></indexterm><literal>TrackParameters</literal>: When
+						<literal>true</literal>, OpenJPA will track the
+						parameters that were set for all
+						<classname>PreparedStatement</classname>s that
+						are executed or batched so that they can be
+						included in error messages.
+						Defaults to <literal>true</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ValidationSQL</tertiary></indexterm><literal>ValidationSQL</literal>: A simple SQL query to
+						issue to validate a database connection.  If this 
+						property is not set, then the only validation performed
+						is to use the <methodname>Connection.isClosed
+						</methodname> method.  The following table shows the
+						default settings for different databases.  If a database
+						is not shown, this property defaults to null.  
+						</para>
+                <table>
+                  <title>Validation SQL Defaults</title>
+                  <tgroup cols="2" align="left" colsep="1" rowsep="1">
+                    <colspec colname="db"/>
+                    <colspec colname="sql"/>
+                    <thead>
+                      <row>
+                        <entry colname="db">Database</entry>
+                        <entry colname="sql">SQL</entry>
+                      </row>
+                    </thead>
+                    <tbody>
+                      <row>
+                        <entry colname="db">DB2</entry>
+                        <entry colname="sql">
+											SELECT DISTINCT(CURRENT TIMESTAMP) 
+											FROM SYSIBM.SYSTABLES
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">Empress</entry>
+                        <entry colname="sql">
+											SELECT DISTINCT(TODAY) 
+											FROM SYS_TABLES
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">Informix</entry>
+                        <entry colname="sql">
+											SELECT DISTINCT CURRENT TIMESTAMP 
+											FROM INFORMIX.SYSTABLES
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">MySQL</entry>
+                        <entry colname="sql">
+											SELECT NOW()
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">Oracle</entry>
+                        <entry colname="sql">
+											SELECT SYSDATE FROM DUAL
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">Postgres</entry>
+                        <entry colname="sql">
+											SELECT NOW()
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">SQLServer</entry>
+                        <entry colname="sql">
+											SELECT GETDATE()
+										</entry>
+                      </row>
+                      <row>
+                        <entry colname="db">Sybase</entry>
+                        <entry colname="sql">
+											SELECT GETDATE()
+										</entry>
+                      </row>
+                    </tbody>
+                  </tgroup>
+                </table>
+                <para>
+						To disable validation SQL, set this property to
+						an empty string, as in 
+						<xref linkend="ref_guide_dbsetup_builtin_ex"/>
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ClosePoolSQL</tertiary></indexterm><literal>ClosePoolSQL</literal>: A simple SQL statement
+						to execute when the connection pool is completely
+						closed. This can be used, for example, to cleanly
+						issue a shutdown statement to a file-based
+						database.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ValidationTimeout</tertiary></indexterm><literal>ValidationTimeout</literal>:
+						The minimum number of milliseconds that must elapse 
+						before a connection will ever be re-validated.  This 
+						property is typically used with <literal>TestOnBorrow
+						</literal> or <literal>TestOnReturn</literal> to 
+						reduce the number of validations performed, because 
+						the same connection is often borrowed and returned many
+						times in a short span.  Defaults to 
+						<literal>300000</literal> (5 minutes).
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>WarningAction</tertiary></indexterm><literal>WarningAction</literal>:
+						The action to take when a
+						<classname>SQLWarning</classname> is detected on a
+		 				connection. Possible values are:
+						</para>
+                <itemizedlist>
+                  <listitem>
+                    <para><literal>ignore</literal>: Warnings will
+								not be checked for, and will be ignored.
+								This is the default.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para><literal>trace</literal>:
+								The warning will be logged on the
+								<literal>TRACE</literal>
+								channel of the JDBC log.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para><literal>info</literal>:
+								The warning will be logged on the
+								<literal>INFO</literal>
+								channel of the JDBC log.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para><literal>warn</literal>:
+								The warning will be logged on the
+								<literal>WARN</literal>
+								channel of the JDBC log.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para><literal>error</literal>:
+								The warning will be logged on the
+								<literal>ERROR</literal>
+								channel of the JDBC log.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para><literal>throw</literal>:
+								All <classname>SQLWarning</classname>
+								instances will be thrown as if they were
+								errors.
+								</para>
+                  </listitem>
+                  <listitem>
+                    <para><literal>handle</literal>:
+								The <classname>SQLWarning</classname>
+								instance will be passed through the
+								<methodname>handleWarning</methodname>
+								method of
+								<ulink url="javadoc/openjpa/jdbc/sql/DBDictionary.html"><classname>
+								org.apache.openjpa.jdbc.sql.DBDictionary</classname></ulink>,
+								which allows a custom extension
+								of the dictionary to use heuristic-based
+								warning handling.
+								</para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>WhenExhaustedAction</tertiary></indexterm><literal>WhenExhaustedAction</literal>: The action to
+						take when there are no available database connections
+						in the pool.  Set to <literal>exception</literal> to 
+						immediately throw an exception.  Set to <literal>
+						block</literal> to block until a connection is 
+						available or the maximum wait time is exceeded.  Set to
+						<literal>grow</literal> to automatically grow the pool.
+						Defaults to <literal>block</literal>.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				Additionally, the following properties are available whether 
+				you use OpenJPA's built-in <classname>DataSource</classname> 
+				or a third-party's:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><indexterm><primary>prepared statement</primary><secondary>pooling</secondary><tertiary>MaxCachedStatements</tertiary></indexterm><literal>MaxCachedStatements</literal>: The maximum
+						number of
+						<classname>java.sql.PreparedStatement</classname>s
+						to cache.  Statement caching can dramatically speed up 
+						some databases.  Defaults to 50 for OpenJPA's 
+						<classname>DataSource</classname>, and 0 for 
+						third-party <classname>DataSource</classname>s.  Most 
+						third-party <classname>DataSource</classname>s do not 
+						benefit from OpenJPA's prepared statement cache, because 
+						each returned connection has a unique hash code, 
+						making it impossible for OpenJPA to match connections to 
+						their cached statements.
+						</para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>JDBC</primary><secondary>QueryTimeout</secondary></indexterm><literal>QueryTimeout</literal>: The maximum number of
+						seconds the JDBC driver will wait for a statement to
+						execute.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_dbsetup_builtin_ex">
+          <title>Properties for the OpenJPA DataSource</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.ConnectionUserName" value="user"/&gt;
+&lt;property name="openjpa.ConnectionPassword" value="pass"/&gt;
+&lt;property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/&gt;
+&lt;property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/&gt;
+&lt;property name="openjpa.ConnectionFactoryProperties" 
+    value="MaxActive=50, MaxIdle=10, ValidationTimeout=50000, MaxCachedStatements=100, ValidationSQL=''"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_dbsetup_thirdparty">
+        <title>Using a Third-Party DataSource</title>
+        <indexterm zone="ref_guide_dbsetup_builtin">
+          <primary>DataSource</primary>
+          <secondary>third party</secondary>
+        </indexterm>
+        <para>
+		You can use OpenJPA with any third-party 
+		<classname>javax.sql.DataSource</classname>.  There are multiple ways
+		of telling OpenJPA about a <classname>DataSource</classname>:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>ConnectionFactory</primary></indexterm>
+				Set the <classname>DataSource</classname> into the map passed
+				to <methodname>Persistence.createEntityManagerFactory
+				</methodname> under the <link linkend="openjpa.ConnectionFactory"><literal>openjpa.ConnectionFactory</literal></link> key.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ConnectionFactoryName</primary></indexterm>
+				Bind the <classname>DataSource</classname> into JNDI, and then
+				specify its location in the
+				<phrase><literal>jta-data-source</literal> or
+				<literal>non-jta-data-source</literal> element of the
+				<link linkend="jpa_overview_persistence_xml">JPA XML 
+				format</link> (depending on whether the <classname>DataSource
+				</classname> is managed by JTA), or in the
+				</phrase><link linkend="openjpa.ConnectionFactoryName"><literal>openjpa.ConnectionFactoryName</literal></link> property.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ConnectionDriverName</primary></indexterm>
+				Specify the full class name of the 
+				<classname>DataSource</classname> implementation in the
+				<link linkend="openjpa.ConnectionDriverName"><literal>openjpa.ConnectionDriverName</literal></link> property 
+				in place of a JDBC driver.  In this configuration OpenJPA will 
+				instantiate an instance of the named class via reflection.  It 
+				will then configure the <classname>DataSource</classname> with 
+				the properties in the <link linkend="openjpa.ConnectionProperties"><literal>openjpa.ConnectionProperties</literal></link> setting.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		Some advanced features of OpenJPA's own <classname>DataSource</classname> 
+		can also be used with third-party implementations.  OpenJPA layers on top 
+		of the third-party <classname>DataSource</classname> to provide the 
+		extra functionality.  To configure these advanced features, including
+		prepared statement caching, use the 
+		<link linkend="openjpa.ConnectionFactoryProperties"><literal>openjpa.ConnectionFactoryProperties</literal></link> property
+		described in the previous section.
+		</para>
+        <example id="ref_guide_dbsetup_thirdparty_ex">
+          <title>Properties File for a Third-Party DataSource</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/&gt;
+&lt;property name="openjpa.ConnectionProperties" 
+    value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/&gt;
+&lt;property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/&gt;
+</programlisting>
+        </example>
+        <section id="ref_guide_dbsetup_thirdparty_enlist">
+          <title>Managed and XA DataSources</title>
+          <indexterm zone="ref_guide_dbsetup_thirdparty_enlist">
+            <primary>DataSource</primary>
+            <secondary>managed</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_dbsetup_thirdparty_enlist">
+            <primary>DataSource</primary>
+            <secondary>XA</secondary>
+          </indexterm>
+          <para><indexterm><primary>ConnectionFactoryMode</primary></indexterm>
+			Certain application servers automatically enlist their <classname>
+			DataSource</classname>s in global transactions.  When this is the 
+			case, OpenJPA should not attempt to commit the underlying connection, 
+			leaving JDBC transaction completion to the application server.  To 
+			notify OpenJPA that your third-party <classname>DataSource</classname>
+			is managed by the application server, set the 
+			<link linkend="openjpa.ConnectionFactoryMode"><literal>openjpa.ConnectionFactoryMode</literal></link> property to 
+			<literal>managed</literal>.
+			</para>
+          <para>
+			Note that OpenJPA can only use managed 
+			<classname>DataSource</classname>s when it is also
+			integrating with the application server's managed transactions.
+			Also 
+			note that all XA <classname>DataSource</classname>s are enlisted, 
+			and you must set this property when using any XA <classname>
+			DataSource</classname>.
+			</para>
+          <para>
+			When using a managed <classname>DataSource</classname>, you 
+			should also configure a second unmanaged
+			<classname>DataSource</classname> that OpenJPA can use to perform 
+			tasks that are independent of the global transaction.
+			The most common of these tasks is updating the sequence table OpenJPA
+			uses to generate unique primary key values for your 
+			datastore identity objects.  Configure the second <classname>
+			DataSource</classname> just as the first, but use the various "2" 
+			connection properties, such as
+			<literal>openjpa.ConnectionFactory2Name</literal>
+			or <literal>openjpa.Connection2DriverName</literal>. 
+			These properties are outlined in <xref linkend="ref_guide_conf"/>.
+			<phrase>
+			If your second <classname>DataSource</classname> is also bound to
+			JNDI, you can use JPA XML's <literal>non-jta-data-source</literal>
+			to specify its location.  
+			</phrase>
+			Typically, <phrase>though,</phrase> you will use 
+			OpenJPA's built-in implementation 
+			for the second <classname>DataSource</classname>
+			(see <xref linkend="ref_guide_dbsetup_builtin"/>).
+			</para>
+          <example id="ref_guide_enterprise_xa_conf_ex">
+            <title>Managed DataSource Configuration</title>
+            <programlisting format="linespecific">
+&lt;!-- managed DataSource --&gt;
+&lt;jta-data-source&gt;java:/OracleXASource&lt;/jta-data-source&gt;
+&lt;properties&gt;
+    &lt;!-- use OpenJPA's built-in DataSource for unmanaged connections --&gt;
+    &lt;property name="openjpa.Connection2UserName" value="scott"/&gt;
+    &lt;property name="openjpa.Connection2Password" value="tiger"/&gt;
+    &lt;property name="openjpa.Connection2URL" value="jdbc:oracle:thin:@CROM:1521:OpenJPADB"/&gt;
+    &lt;property name="openjpa.Connection2DriverName" value="oracle.jdbc.driver.OracleDriver"/&gt;
+    &lt;property name="openjpa.ConnectionFactory2Properties" value="MaxActive=20, MaxIdle=10"/&gt;
+    &lt;!-- managed transaction and enlisted configuration --&gt;
+    &lt;property name="openjpa.TransactionMode" value="managed"/&gt;
+    &lt;property name="openjpa.ConnectionFactoryMode" value="managed"/&gt;
+&lt;/properties&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_dbsetup_sqlconn">
+        <title>Runtime Access to DataSource</title>
+        <indexterm zone="ref_guide_dbsetup_sqlconn">
+          <primary>connections</primary>
+          <secondary>accessing DataSource</secondary>
+        </indexterm>
+        <indexterm zone="ref_guide_dbsetup_sqlconn">
+          <primary>JDBC</primary>
+          <secondary>accessing DataSource</secondary>
+        </indexterm>
+        <para>
+		The JPA standard defines how to access JDBC connections from enterprise
+		beans.  OpenJPA also provides APIs to access an <classname>
+		EntityManager</classname>'s connection, or to retrieve a connection
+		directly from the <classname>EntityManagerFactory</classname>'s 
+		<classname>DataSource</classname>.
+		</para>
+        <para>
+		The <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><methodname>OpenJPAEntityManager.getConnection</methodname></ulink> method
+		returns an <classname>EntityManager</classname>'s connection.  If the
+		<classname>EntityManager</classname> does not already have a connection,
+		it will obtain one.  The returned connection is only guaranteed to be
+		transactionally consistent with other <classname>EntityManager
+		</classname> operations if the <classname>EntityManager</classname> is
+		in a managed or non-optimistic transaction, if the <classname>
+		EntityManager</classname> has flushed in the current transaction, or if
+		you have used the <methodname>OpenJPAEntityManager.beginStore</methodname>
+		method to ensure that a datastore transaction is in progress.  Always
+		close the returned connection before attempting any other 
+		<classname>EntityManager</classname> operations.  OpenJPA will ensure that
+		the underlying native connection is not released if a datastore
+		transaction is in progress.
+		</para>
+        <example id="ref_guide_dbsetup_conn_ejb">
+          <title>Using the EntityManager's Connection</title>
+          <programlisting format="linespecific">
+import java.sql.*;
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+Connection conn = (Connection) kem.getConnection ();
+
+// do JDBC stuff
+
+conn.close ();
+</programlisting>
+        </example>
+        <para>
+		The example below shows how to use a connection directly from the
+		<classname>DataSource</classname>, rather than using an <classname>
+		EntityManager</classname>'s connection.	
+		</para>
+        <example id="ref_guide_dbsetup_conn_from_factory_ejb">
+          <title>Using the EntityManagerFactory's DataSource</title>
+          <programlisting format="linespecific">
+import java.sql.*;
+import javax.sql.*;
+import org.apache.openjpa.conf.*;
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+OpenJPAConfiguration conf = kemf.getConfiguration ();
+DataSource dataSource = (DataSource) conf.getConnectionFactory ();
+Connection conn = dataSource.getConnection ();
+
+// do JDBC stuff
+
+conn.close ();
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_dbsetup_dbsupport">
+        <title>Database Support</title>
+        <indexterm zone="ref_guide_dbsetup_dbsupport">
+          <primary>DBDictionary</primary>
+        </indexterm>
+        <indexterm zone="ref_guide_dbsetup_dbsupport">
+          <primary>relational database</primary>
+          <secondary>OpenJPA support</secondary>
+          <seealso>DBDictionary</seealso>
+        </indexterm>
+        <para>
+		OpenJPA <phrase>JPA</phrase> can take advantage of any JDBC 2.x compliant 
+		driver, making almost any major database a candidate for use. See 
+		our officially supported database list in 
+		<xref linkend="supported_databases"/> for more information.  Typically,
+		OpenJPA auto-configures its JDBC behavior and SQL dialect for your 
+		database, based on the values of your connection-related configuration 
+		properties.
+		</para>
+        <para>
+		If OpenJPA cannot detect what type of database you are using, or if
+		you are using an unsupported database, you will have to tell OpenJPA 
+		what <ulink url="../apidocs/org/apache/openjpa/jdbc/sql/DBDictionary.html"><classname>org.apache.openjpa.jdbc.sql.DBDictionary</classname></ulink> to use.  
+		The <classname>DBDictionary</classname> abstracts away the differences 
+		between databases.  You can plug a dictionary into OpenJPA using the 
+		<link linkend="openjpa.jdbc.DBDictionary"><literal>openjpa.jdbc.DBDictionary
+		</literal></link> configuration property.  The built-in dictionaries
+		are listed below.  If you are using an unsupported database, you may 
+		have to write your own <classname>DBDictionary</classname> subclass, 
+		a simple process.
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>Microsoft Access</primary></indexterm><literal>access</literal>: Dictionary for Microsoft
+				Access.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/AccessDictionary.html"><classname>org.apache.openjpa.jdbc.sql.AccessDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>DB2</primary></indexterm><literal>db2</literal>: Dictionary for IBM's DB2 database.
+				This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/DB2Dictionary.html"><classname>org.apache.openjpa.jdbc.sql.DB2Dictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Derby</primary></indexterm><literal>derby</literal>: Dictionary for the Apache Derby 
+				database. This is an alias for the 
+				<ulink url="javadoc/openjpa/jdbc/sql/DerbyDictionary.html"><classname>org.apache.openjpa.jdbc.sql.DerbyDictionary</classname> class.
+				</ulink></para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Empress</primary></indexterm><literal>empress</literal>: Dictionary for Empress database
+				This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/EmpressDictionary.html"><classname>org.apache.openjpa.jdbc.sql.EmpressDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>FoxPro</primary></indexterm><literal>foxpro</literal>: Dictionary for Microsoft
+				Visual FoxPro.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/FoxProDictionary.html"><classname>org.apache.openjpa.jdbc.sql.FoxProDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Hypersonic SQL</primary></indexterm><literal>hsql</literal>: Dictionary for the Hypersonic SQL 
+				database.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/HSQLDictionary.html"><classname>org.apache.openjpa.jdbc.sql.HSQLDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Informix</primary></indexterm><literal>informix</literal>: Dictionary for the Informix
+				database.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/InformixDictionary.html"><classname>org.apache.openjpa.jdbc.sql.InformixDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>JDataStore</primary></indexterm><literal>jdatastore</literal>: Dictionary for Borland
+				JDataStore.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/JDataStoreDictionary.html"><classname>org.apache.openjpa.jdbc.sql.JDataStoreDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>MySQL</primary></indexterm><literal>mysql</literal>: Dictionary for the MySQL
+				database.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/MySQLDictionary.html"><classname>org.apache.openjpa.jdbc.sql.MySQLDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Oracle</primary></indexterm><literal>oracle</literal>: Dictionary for Oracle.
+				This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/OracleDictionary.html"><classname>org.apache.openjpa.jdbc.sql.OracleDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Pointbase</primary></indexterm><literal>pointbase</literal>: Dictionary for Pointbase Embedded
+				database.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/PointbaseDictionary.html"><classname>org.apache.openjpa.jdbc.sql.PointbaseDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>PostgreSQL</primary></indexterm><literal>postgres</literal>: Dictionary for PostgreSQL.
+				This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/PostgresDictionary.html"><classname>org.apache.openjpa.jdbc.sql.PostgresDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>SQLServer</primary></indexterm><literal>sqlserver</literal>: Dictionary for Microsoft's
+				SQLServer database.  This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/SQLServerDictionary.html"><classname>org.apache.openjpa.jdbc.sql.SQLServerDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>Sybase</primary></indexterm><literal>sybase</literal>: Dictionary for Sybase.
+				This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/SybaseDictionary.html"><classname>org.apache.openjpa.jdbc.sql.SybaseDictionary</classname></ulink> class.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The example below demonstrates how to set a dictionary and configure
+		its properties in your configuration file.  The <literal>DBDictionary
+		</literal> property uses OpenJPA's
+		<link linkend="ref_guide_conf_plugins">plugin syntax</link>.
+		</para>
+        <example id="ref_guide_dbsetup_dbdict">
+          <title>Specifying a DBDictionary</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.DBDictionary" value="hsql(SimulateLocking=true)"/&gt;
+</programlisting>
+        </example>
+        <section id="ref_guide_dbsetup_dbdictprops">
+          <title>DBDictionary Properties</title>
+          <para>
+			The standard dictionaries all recognize the following properties. 
+			These properties will usually not need to be overridden, since the
+			dictionary implementation should use the appropriate default values
+			for your database. You typically won't use these properties 
+			unless you are designing your own <classname>DBDictionary
+			</classname> for an unsupported database.
+			</para>
+          <itemizedlist>
+            <listitem id="DBDictionary.DriverVendor">
+              <para><indexterm><primary>JDBC</primary><secondary>DriverVendor</secondary></indexterm><literal>DriverVendor</literal>: The vendor of the particular
+				JDBC driver you are using.  Some dictionaries must alter their
+				behavior depending on the driver vendor.  See the 
+				<literal>VENDOR_XXX</literal> constants defined in your
+				dictionary's Javadoc for available options.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.CatalogSeparator">
+              <para><indexterm><primary>SQL</primary><secondary>CatalogSeparator</secondary></indexterm><literal>CatalogSeparator</literal>:
+				The string the database uses to delimit between
+				the schema name and the table name. This is typically
+				<literal>"."</literal>, which is the default.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.CreatePrimaryKeys">
+              <para><indexterm><primary>DDL</primary><secondary>CreatePrimaryKeys</secondary></indexterm><literal>CreatePrimaryKeys</literal>: If
+				<literal>false</literal>, then do not create database
+				primary keys for identifiers. Defaults to
+				<literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ConstraintNameMode">
+              <para><indexterm><primary>DDL</primary><secondary>ConstraintNameMode</secondary></indexterm><literal>ConstraintNameMode</literal>: When
+				creating constraints, whether to put the constraint name 
+				before the definition (<literal>before</literal>), just after 
+				the constraint type name (<literal>mid</literal>), or after the 
+				constraint definition (<literal>after</literal>).
+				Defaults to <literal>before</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.MaxTableNameLength">
+              <para><indexterm><primary>DDL</primary><secondary>MaxTableNameLength</secondary></indexterm><literal>MaxTableNameLength</literal>: The maximum number
+				of characters in a table name.  Defaults to 128.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.MaxColumnNameLength">
+              <para><indexterm><primary>DDL</primary><secondary>MaxColumnNameLength</secondary></indexterm><literal>MaxColumnNameLength</literal>: The maximum number
+				of characters in a column name.  Defaults to 128.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.MaxConstraintNameLength">
+              <para><indexterm><primary>DDL</primary><secondary>MaxConstraintNameLength</secondary></indexterm><literal>MaxConstraintNameLength</literal>: The maximum number
+				of characters in a constraint name.  Defaults to 128.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.MaxIndexNameLength">
+              <para><indexterm><primary>DDL</primary><secondary>MaxIndexNameLength</secondary></indexterm><indexterm><primary>indexes</primary><secondary>MaxIndexNameLength</secondary></indexterm><literal>MaxIndexNameLength</literal>: The maximum number
+				of characters in an index name.  Defaults to 128.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.MaxAutoAssignNameLength">
+              <para><indexterm><primary>DDL</primary><secondary>MaxAutoAssignNameLength</secondary></indexterm><literal>MaxAutoAssignNameLength</literal>: Set 
+				this property to the maximum length of name for
+				sequences used for auto-increment columns.  Names
+				longer than this value are truncated.
+				Defaults to <literal>31</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.MaxIndexesPerTable">
+              <para><indexterm><primary>indexes</primary><secondary>MaxIndexesPerTable</secondary></indexterm><literal>MaxIndexesPerTable</literal>: The maximum number
+				of indexes that can be placed on a single table.  Defaults to
+				no limit.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsForeignKeys">
+              <para><indexterm><primary>foreign keys</primary><secondary>SupportsForeignKeys</secondary></indexterm><literal>SupportsForeignKeys</literal>: Whether the database
+				supports foreign keys.  Defaults to true.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsUniqueConstraints">
+              <para><indexterm><primary>unique constraints</primary><secondary>SupportsUniqueConstraints</secondary></indexterm><literal>SupportsUniqueConstraints</literal>: Whether the 
+				database supports unique constraints.  Defaults to true.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsDeferredConstraints">
+              <para><indexterm><primary>foreign keys</primary><secondary>SupportsDeferredConstraints</secondary></indexterm><literal>SupportsDeferredConstraints</literal>: Whether the 
+				database supports deferred constraints.  Defaults to true.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsRestrictDeleteAction">
+              <para><indexterm><primary>foreign keys</primary><secondary>SupportsRestrictDeleteAction</secondary></indexterm><literal>SupportsRestrictDeleteAction</literal>: Whether the 
+				database supports the RESTRICT foreign key delete action.
+				Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsCascadeDeleteAction">
+              <para><indexterm><primary>foreign keys</primary><secondary>SupportsCascadeDeleteAction</secondary></indexterm><literal>SupportsCascadeDeleteAction</literal>: Whether the 
+				database supports the CASCADE foreign key delete action.
+				Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsNullDeleteAction">
+              <para><indexterm><primary>foreign keys</primary><secondary>SupportsNullDeleteAction</secondary></indexterm><literal>SupportsNullDeleteAction</literal>: Whether the 
+				database supports the SET NULL foreign key delete action.
+				Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsDefaultDeleteAction">
+              <para><indexterm><primary>foreign keys</primary><secondary>SupportsDefaultDeleteAction</secondary></indexterm><literal>SupportsDefaultDeleteAction</literal>: Whether the 
+				database supports the SET DEFAULT foreign key delete action.
+				Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsAlterTableWithAddColumn">
+              <para><indexterm><primary>DDL</primary><secondary>SupportsAlterTableWithAddColumn</secondary></indexterm><literal>SupportsAlterTableWithAddColumn</literal>: Whether the 
+				database supports adding a new column in an ALTER TABLE	
+				statement.  Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsAlterTableWithDropColumn">
+              <para><indexterm><primary>DDL</primary><secondary>SupportsAlterTableWithDropColumn</secondary></indexterm><literal>SupportsAlterTableWithDropColumn</literal>: Whether 
+				the database supports dropping a column in an ALTER TABLE	
+				statement.  Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ReservedWords">
+              <para><indexterm><primary>SQL</primary><secondary>ReservedWords</secondary></indexterm><literal>ReservedWords</literal>: A comma-separated list of
+				reserved words for this database, beyond the standard SQL92
+				keywords.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SystemTables">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SystemTables</tertiary></indexterm><literal>SystemTables</literal>: A comma-separated list of
+				table names that should be ignored.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SystemSchemas">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SystemSchemas</tertiary></indexterm><literal>SystemSchemas</literal>: A comma-separated list of
+				schema names that should be ignored.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SchemaCase">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SchemaCase</tertiary></indexterm><literal>SchemaCase</literal>: The case to use when querying
+				the database metadata about schema components.  Defaults to
+				making all names upper case.  Available values are:
+				<literal>upper, lower, preserve</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ValidationSQL">
+              <para><indexterm><primary>connections</primary><secondary>ValidationSQL</secondary></indexterm><indexterm><primary>SQL</primary><secondary>ValidationSQL</secondary></indexterm><literal>ValidationSQL</literal>: The SQL used to 
+				validate that a connection is still in a valid state.  For 
+				example, "<literal>SELECT SYSDATE FROM DUAL</literal>" for 
+				Oracle.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.InitializationSQL">
+              <para><indexterm><primary>connections</primary><secondary>InitializationSQL</secondary></indexterm><indexterm><primary>SQL</primary><secondary>InitializationSQL</secondary></indexterm><literal>InitializationSQL</literal>: A piece of SQL to issue 
+				against the database whenever a connection is retrieved from 
+				the <classname>DataSource</classname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.JoinSyntax">
+              <para><indexterm><primary>joins</primary><secondary>JoinSyntax</secondary></indexterm><literal>JoinSyntax</literal>: The SQL join syntax
+				to use in select statements.  See
+				<xref linkend="ref_guide_dbsetup_sql92"/>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.CrossJoinClause">
+              <para><indexterm><primary>joins</primary><secondary>CrossJoinClause</secondary></indexterm><literal>CrossJoinClause</literal>: The clause to use for
+				a cross join (cartesian product).
+				Defaults to <literal>CROSS JOIN</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.InnerJoinClause">
+              <para><indexterm><primary>joins</primary><secondary>InnerJoinClause</secondary></indexterm><literal>InnerJoinClause</literal>: The clause to use for
+				an inner join.  Defaults to <literal>INNER JOIN</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.OuterJoinClause">
+              <para><indexterm><primary>joins</primary><secondary>OuterJoinClause</secondary></indexterm><literal>OuterJoinClause</literal>: The clause to use for
+				an left outer join.
+				Defaults to <literal>LEFT OUTER JOIN</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.RequiresConditionForCrossJoin">
+              <para><indexterm><primary>joins</primary><secondary>RequiresConditionForCrossJoin</secondary></indexterm><literal>RequiresConditionForCrossJoin</literal>: Some
+				databases require that there always be a conditional
+				statement for a cross join. If set, this parameter ensures
+				that there will always be some condition to the join clause.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ToUpperCaseFunction">
+              <para><indexterm><primary>SQL</primary><secondary>ToUpperCaseFunction</secondary></indexterm><literal>ToUpperCaseFunction</literal>: SQL function call for
+				for converting a string to upper case.  Use the token 
+				<literal>{0}</literal> to represent the argument.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ToLowerCaseFunction">
+              <para><indexterm><primary>SQL</primary><secondary>ToLowerCaseFunction</secondary></indexterm><literal>ToLowerCaseFunction</literal>: Name of the SQL function
+				for converting a string to lower case.  Use the token 
+				<literal>{0}</literal> to represent the argument.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.StringLengthFunction">
+              <para><indexterm><primary>SQL</primary><secondary>StringLengthFunction</secondary></indexterm><literal>StringLengthFunction</literal>: Name of the SQL 
+				function for getting the length of a string.  Use the token 
+				<literal>{0}</literal> to represent the argument.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SubstringFunctionName">
+              <para><indexterm><primary>SQL</primary><secondary>SubstringFunctionName</secondary></indexterm><literal>SubstringFunctionName</literal>: Name of the SQL 
+				function for getting the substring of a string.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.DistinctCountColumnSeparator">
+              <para><indexterm><primary>SQL</primary><secondary>DistinctCountColumnSeparator</secondary></indexterm><literal>DistinctCountColumnSeparator</literal>:
+				The string the database uses to delimit between column
+				expressions in a <literal>SELECT COUNT(DISTINCT column-list)
+				</literal> clause.  Defaults to null for most databases, 
+				meaning that multiple columns in a distinct COUNT clause are 
+				not supported.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ForUpdateClause">
+              <para><indexterm><primary>SQL</primary><secondary>ForUpdateClause</secondary></indexterm><indexterm><primary>locking</primary><secondary>ForUpdateClause</secondary></indexterm><literal>ForUpdateClause</literal>: The clause to append to 
+				<literal>SELECT</literal> statements to issue queries that 
+				obtain pessimistic locks. Defaults to 
+				<literal>FOR UPDATE</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.TableForUpdateClause">
+              <para><indexterm><primary>SQL</primary><secondary>TableForUpdateClause</secondary></indexterm><indexterm><primary>locking</primary><secondary>TableForUpdateClause</secondary></indexterm><literal>TableForUpdateClause</literal>: The clause to append 
+				to the end of each table alias in queries that obtain 
+				pessimistic locks.  Defaults to null.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsSelectForUpdate">
+              <para><indexterm><primary>locking</primary><secondary>SupportsSelectForUpdate</secondary></indexterm><literal>SupportsSelectForUpdate</literal>: If true, then the 
+				database supports <literal>SELECT</literal> statements with a 
+				pessimistic locking clause.  Defaults to true.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsLockingWithDistinctClause">
+              <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithDistinctClause</secondary></indexterm><literal>SupportsLockingWithDistinctClause</literal>: If true, 
+				then the database supports <literal>FOR UPDATE</literal> 
+				select clauses with <literal>DISTINCT</literal> clauses. 
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsLockingWithOuterJoin">
+              <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithOuterJoin</secondary></indexterm><literal>SupportsLockingWithOuterJoin</literal>: If true, then 
+				the database supports <literal>FOR UPDATE</literal> select 
+				clauses with outer join queries.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsLockingWithInnerJoin">
+              <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithInnerJoin</secondary></indexterm><literal>SupportsLockingWithInnerJoin</literal>: If true, then 
+				the database supports <literal>FOR UPDATE</literal> select 
+				clauses with inner join queries.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsLockingWithMultipleTables">
+              <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithMultipleTables</secondary></indexterm><literal>SupportsLockingWithMultipleTables</literal>: If true, 
+				then the database supports <literal>FOR UPDATE</literal> select
+				clauses that select from multiple tables.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsLockingWithOrderClause">
+              <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithOrderClause</secondary></indexterm><literal>SupportsLockingWithOrderClause</literal>: If true, 
+				then the database supports <literal>FOR UPDATE</literal> 
+				select clauses with <literal>ORDER BY</literal> clauses. 
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsLockingWithSelectRange">
+              <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithSelectRange</secondary></indexterm><literal>SupportsLockingWithSelectRange</literal>: If true, 
+				then the database supports <literal>FOR UPDATE</literal> 
+				select clauses with queries that select a range of data using
+				<literal>LIMIT</literal>, <literal>TOP</literal> or the 
+				database equivalent.  Defaults to true.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SimulateLocking">
+              <para><indexterm><primary>locking</primary><secondary>SimulateLocking</secondary></indexterm><literal>SimulateLocking</literal>: Some databases
+				do not support pessimistic locking, which will result in
+				an exception when you attempt a pessimistic
+				transaction.  Setting this property to
+				<literal>true</literal> bypasses the locking check to
+				allow pessimistic transactions even on databases that
+				do not support locking.  Defaults to <literal>false</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsQueryTimeout">
+              <para><indexterm><primary>JDBC</primary><secondary>QueryTimeout</secondary><tertiary>SupportsQueryTimeout</tertiary></indexterm><literal>SupportsQueryTimeout</literal>: If true, then the
+				JDBC driver supports calls to <methodname>
+				java.sql.Statement.setQueryTimeout</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsHaving">
+              <para><indexterm><primary>aggregates</primary><secondary>having</secondary><tertiary>SupportsHaving</tertiary></indexterm><literal>SupportsHaving</literal>: Whether this database
+				supports HAVING clauses in selects.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsSelectStartIndex">
+              <para><indexterm><primary>Query</primary><secondary>result range</secondary><tertiary>SupportsSelectStartIndex</tertiary></indexterm><literal>SupportsSelectStartIndex</literal>: Whether this 
+				database can create a select that skips the first N results.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsSelectEndIndex">
+              <para><indexterm><primary>Query</primary><secondary>result range</secondary><tertiary>SupportsSelectEndIndex</tertiary></indexterm><literal>SupportsSelectEndIndex</literal>: Whether this 
+				database can create a select that is limited to the first N 
+				results.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsSubselect">
+              <para><indexterm><primary>SQL</primary><secondary>SupportsSubselect</secondary></indexterm><indexterm><primary>JPQL</primary><secondary>subselects</secondary><tertiary>SupportsSubselect</tertiary></indexterm><literal>SupportsSubselect</literal>: Whether this database
+				supports subselects in queries.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.RequiresAliasForSubselect">
+              <para><indexterm><primary>SQL</primary><secondary>RequiresAliasForSubselect</secondary></indexterm><indexterm><primary>JPQL</primary><secondary>subselects</secondary><tertiary>RequiresAliasForSubselect</tertiary></indexterm><literal>RequiresAliasForSubselect</literal>: If true, then 
+				the database requires that subselects in a FROM clause be 
+				assigned an alias.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsMultipleNontransactionalResultSets">
+              <para><literal>SupportsMultipleNontransactionalResultSets</literal>:
+				If true, then a nontransactional connection is capable
+				of having multiple open <classname>ResultSet</classname>
+				instances.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.StorageLimitationsFatal">
+              <para><indexterm><primary>persistent fields</primary><secondary>StorageLimitationsFatal</secondary></indexterm><literal>StorageLimitationsFatal</literal>: If true, then any 
+				data truncation/rounding that is performed by the dictionary 
+				in order to store a value in the database will be treated as 
+				a fatal error, rather than just issuing a warning.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.StoreLargeNumbersAsStrings">
+              <para><indexterm><primary>persistent fields</primary><secondary>StoreLargeNumbersAsStrings</secondary></indexterm><literal>StoreLargeNumbersAsStrings</literal>: Many 
+				databases have limitations on the number of digits that can 
+				be stored in a numeric field (for example, Oracle can only 
+				store 38 digits).  For applications that operate
+				on very large <classname>BigInteger</classname> and 
+				<classname>BigDecimal</classname> values, it may be 
+				necessary to store these objects as string fields rather 
+				than the database's numeric type.  Note that this may 
+				prevent meaningful numeric queries from being executed 
+				against the database.  Defaults to 
+				<literal>false</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.StoreCharsAsNumbers">
+              <para><indexterm><primary>persistent fields</primary><secondary>StoreCharsAsNumbers</secondary></indexterm><literal>StoreCharsAsNumbers</literal>: Set this property
+				to <literal>false</literal> to store Java 
+				<literal>char</literal> fields as <literal>CHAR</literal>
+				values rather than numbers. Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseGetBytesForBlobs">
+              <para><indexterm><primary>BLOB</primary><secondary>UseGetBytesForBlobs</secondary></indexterm><literal>UseGetBytesForBlobs</literal>: If true, then 
+				<methodname>ResultSet.getBytes</methodname> will be used to 
+				obtain blob data rather than 
+				<methodname>ResultSet.getBinaryStream</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseGetObjectForBlobs">
+              <para><indexterm><primary>BLOB</primary><secondary>UseGetObjectForBlobs</secondary></indexterm><literal>UseGetObjectForBlobs</literal>: If true, then 
+				<methodname>ResultSet.getObject</methodname> will be used to 
+				obtain blob data rather than
+				<methodname>ResultSet.getBinaryStream</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseSetBytesForBlobs">
+              <para><indexterm><primary>BLOB</primary><secondary>UseSetBytesForBlobs</secondary></indexterm><literal>UseSetBytesForBlobs</literal>: If true, then
+				<methodname>PreparedStatement.setBytes</methodname>
+				will be used to set blob data, rather than
+				<methodname>PreparedStatement.setBinaryStream</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseGetStringForClobs">
+              <para><indexterm><primary>CLOB</primary><secondary>UseGetStringForClobs</secondary></indexterm><literal>UseGetStringForClobs</literal>: If true, then 
+				<methodname>ResultSet.getString</methodname> will be used to 
+				obtain clob data rather than
+				<methodname>ResultSet.getCharacterStream</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseSetStringForClobs">
+              <para><indexterm><primary>CLOB</primary><secondary>UseSetStringForClobs</secondary></indexterm><literal>UseSetStringForClobs</literal>: If true, then
+				<methodname>PreparedStatement.setString</methodname>
+				will be used to set clob data, rather than
+				<methodname>PreparedStatement.setCharacterStream</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.CharacterColumnSize">
+              <para><indexterm><primary>DDL</primary><secondary>CharacterColumnSize</secondary></indexterm><literal>CharacterColumnSize</literal>: The default size of
+				<literal>varchar</literal> and <literal>char</literal> columns.
+				Typically 255.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ArrayTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>ArrayTypeName</secondary></indexterm><literal>ArrayTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.ARRAY</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.BigintTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>BigintTypeName</secondary></indexterm><literal>BigintTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.BIGINT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.BinaryTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>BinaryTypeName</secondary></indexterm><literal>BinaryTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.BINARY</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.BitTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>BitTypeName</secondary></indexterm><literal>BitTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.BIT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.BlobTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>BlobTypeName</secondary></indexterm><indexterm><primary>BLOB</primary><secondary>BlobTypeName</secondary></indexterm><literal>BlobTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.BLOB</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.CharTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>CharTypeName</secondary></indexterm><literal>CharTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.CHAR</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.ClobTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>ClobTypeName</secondary></indexterm><indexterm><primary>CLOB</primary><secondary>ClobTypeName</secondary></indexterm><literal>ClobTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.CLOB</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.DateTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>DateTypeName</secondary></indexterm><literal>DateTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.DATE</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.DecimalTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>DecimalTypeName</secondary></indexterm><literal>DecimalTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.DECIMAL</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.DistinctTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>DistinctTypeName</secondary></indexterm><literal>DistinctTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.DISTINCT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.DoubleTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>DoubleTypeName</secondary></indexterm><literal>DoubleTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.DOUBLE</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.FloatTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>FloatTypeName</secondary></indexterm><literal>FloatTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.FLOAT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.IntegerTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>IntegerTypeName</secondary></indexterm><literal>IntegerTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.INTEGER</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.JavaObjectTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>JavaObjectTypeName</secondary></indexterm><literal>JavaObjectTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.JAVAOBJECT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.LongVarbinaryTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>LongVarbinaryTypeName</secondary></indexterm><literal>LongVarbinaryTypeName</literal>: The overridden default
+				column type for <literal>java.sql.Types.LONGVARBINARY</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.LongVarcharTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>LongVarcharTypeName</secondary></indexterm><literal>LongVarcharTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.LONGVARCHAR</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.NullTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>NullTypeName</secondary></indexterm><literal>NullTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.NULL</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.NumericTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>NumericTypeName</secondary></indexterm><literal>NumericTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.NUMERIC</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.OtherTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>OtherTypeName</secondary></indexterm><literal>OtherTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.OTHER</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.RealTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>RealTypeName</secondary></indexterm><literal>RealTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.REAL</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.RefTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>RefTypeName</secondary></indexterm><literal>RefTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.REF</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SmallintTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>SmallintTypeName</secondary></indexterm><literal>SmallintTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.SMALLINT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.StructTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>StructTypeName</secondary></indexterm><literal>StructTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.STRUCT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.TimeTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>TimeTypeName</secondary></indexterm><literal>TimeTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.TIME</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.TimestampTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>TimestampTypeName</secondary></indexterm><literal>TimestampTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.TIMESTAMP</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.TinyintTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>TinyintTypeName</secondary></indexterm><literal>TinyintTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.TINYINT</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.VarbinaryTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>VarbinaryTypeName</secondary></indexterm><literal>VarbinaryTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.VARBINARY</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.VarcharTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>VarcharTypeName</secondary></indexterm><literal>VarcharTypeName</literal>: The overridden default 
+				column type for <literal>java.sql.Types.VARCHAR</literal>.
+				This is only used when the schema is generated by
+				the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseSchemaName">
+              <para><indexterm><primary>schema</primary><secondary>UseSchemaName</secondary></indexterm><literal>UseSchemaName</literal>: If <literal>false</literal>, 
+				then avoid including the schema name in table name references.
+				Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.TableTypes">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>TableTypes</tertiary></indexterm><literal>TableTypes</literal>: Comma-separated list of table
+				types to use when looking for tables during schema reflection,
+				as defined in the 
+				<methodname>java.sql.DatabaseMetaData.getTableInfo</methodname>
+				JDBC method.  An example is: 
+				<literal>"TABLE,VIEW,ALIAS"</literal>.  Defaults to 
+				<literal>"TABLE"</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsSchemaForGetTables">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsSchemaForGetTables</tertiary></indexterm><literal>SupportsSchemaForGetTables</literal>: If false, then 
+				the database driver does not support using
+				the schema name for schema reflection on table names.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsSchemaForGetColumns">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsSchemaForGetColumns</tertiary></indexterm><literal>SupportsSchemaForGetColumns</literal>: If false, then 
+				the database driver does not support using
+				the schema name for schema reflection on column names.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsNullTableForGetColumns">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetColumns</tertiary></indexterm><literal>SupportsNullTableForGetColumns</literal>:
+				If true, then the database supports passing a 
+				<literal>null</literal> parameter to
+				<methodname>DatabaseMetaData.getColumns</methodname>
+				as an optimization to get information about all the tables.
+				Defaults to <literal>true</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsNullTableForGetPrimaryKeys">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetPrimaryKeys</tertiary></indexterm><literal>SupportsNullTableForGetPrimaryKeys</literal>:
+				If true, then the database supports passing a 
+				<literal>null</literal> parameter to
+				<methodname>DatabaseMetaData.getPrimaryKeys</methodname>
+				as an optimization to get information about all the tables.
+				Defaults to <literal>false</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsNullTableForGetIndexInfo">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetIndexInfo</tertiary></indexterm><literal>SupportsNullTableForGetIndexInfo</literal>:
+				If true, then the database supports passing a 
+				<literal>null</literal> parameter to
+				<methodname>DatabaseMetaData.getIndexInfo</methodname>
+				as an optimization to get information about all the tables.
+				Defaults to <literal>false</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.SupportsNullTableForGetImportedKeys">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetImportedKeys</tertiary></indexterm><literal>SupportsNullTableForGetImportedKeys</literal>:
+				If true, then the database supports passing a 
+				<literal>null</literal> parameter to
+				<methodname>DatabaseMetaData.getImportedKeys</methodname>
+				as an optimization to get information about all the tables.
+				Defaults to <literal>false</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.UseGetBestRowIdentifierForPrimaryKeys">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>UseGetBestRowIdentifierForPrimaryKeys</tertiary></indexterm><literal>UseGetBestRowIdentifierForPrimaryKeys</literal>:
+				If true, then metadata queries will use
+				<methodname>DatabaseMetaData.getBestRowIdentifier</methodname>
+				to obtain information about primary keys, rather than
+				<methodname>DatabaseMetaData.getPrimaryKeys</methodname>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.RequiresAutoCommitForMetadata">
+              <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>RequiresAutoCommitForMetaData</tertiary></indexterm><literal>RequiresAutoCommitForMetadata</literal>:
+				If true, then the JDBC driver requires that autocommit
+				be enabled before any schema interrogation operations can
+				take place.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.AutoAssignClause">
+              <para><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>AutoAssignClause</tertiary></indexterm><literal>AutoAssignClause</literal>: The column definition 
+				clause to append to a creation statement.  For example, 
+				"<literal>AUTO_INCREMENT</literal>" for MySQL.  This property 
+				is set automatically in the dictionary, and should not need to 
+				be overridden, and is only used when the schema is generated
+				using the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.AutoAssignTypeName">
+              <para><indexterm><primary>DDL</primary><secondary>AutoAssignTypeName</secondary></indexterm><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>AutoAssignTypeName</tertiary></indexterm><literal>AutoAssignTypeName</literal>: The column type name 
+				for auto-increment columns.  For example, 
+				"<literal>SERIAL</literal>" for PostgreSQL.  This property is 
+				set automatically in the dictionary, and should not need to be 
+				overridden, and is only used when the schema is generated
+				using the <literal>mappingtool</literal>.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.LastGeneratedKeyQuery">
+              <para><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>LastGeneratedKeyQuery</tertiary></indexterm><literal>LastGeneratedKeyQuery</literal>: The query to issue 
+				to obtain the last automatically generated key for an 
+				auto-increment column. For example, 
+				"<literal>select @@identity</literal>" for Sybase.
+				This property is set automatically in the
+				dictionary, and should not need to be overridden.
+				</para>
+            </listitem>
+            <listitem id="DBDictionary.NextSequenceQuery">
+              <para><indexterm><primary>Sequence</primary><secondary>NextSequenceQuery</secondary></indexterm><literal>NextSequenceQuery</literal>: A SQL string for 
+				obtaining a native sequence value.  May use a placeholder of 
+				<literal>{0}</literal> for the variable sequence name.  Defaults
+				to a database-appropriate value.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="ref_guide_dbsetup_dbsupport_mysql">
+          <title>MySQLDictionary Properties</title>
+          <indexterm zone="ref_guide_dbsetup_dbsupport_mysql">
+            <primary>MySQL</primary>
+            <seealso>DBDictionary</seealso>
+          </indexterm>
+          <para>
+			The <literal>mysql</literal> dictionary also understands the
+			following properties:
+			</para>
+          <itemizedlist>
+            <listitem id="MySQLDictionary.DriverDeserializesBlobs">
+              <para><indexterm><primary>MySQL</primary><secondary>DriverDeserializesBlobs</secondary></indexterm><literal>DriverDeserializesBlobs</literal>: Many MySQL 
+					drivers automatically deserialize BLOBs on calls to 
+					<methodname>ResultSet.getObject</methodname>.
+					The <classname>MySQLDictionary</classname> overrides the
+					standard <methodname>DBDictionary.getBlobObject</methodname>
+					method to take this into account.  If your driver does not
+					deserialize automatically, set this property to 
+					<literal>false</literal>.
+					</para>
+            </listitem>
+            <listitem id="MySQLDictionary.TableType">
+              <para><indexterm><primary>MySQL</primary><secondary>TableType</secondary></indexterm><literal>TableType</literal>: The MySQL table type to
+					use when creating tables.  Defaults to
+					<literal>innodb</literal>.
+					</para>
+            </listitem>
+            <listitem id="MySQLDictionary.UseClobs">
+              <para><indexterm><primary>MySQL</primary><secondary>UseClobs</secondary></indexterm><literal>UseClobs</literal>: Some older versions of
+					MySQL do not handle clobs correctly.  To enable clob
+					functionality, set this to true. Defaults to
+					<literal>false</literal>.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="ref_guide_dbsetup_dbsupport_oracle">
+          <title>OracleDictionary Properties</title>
+          <indexterm zone="ref_guide_dbsetup_dbsupport_oracle">
+            <primary>Oracle</primary>
+            <seealso>DBDictionary</seealso>
+          </indexterm>
+          <para>
+			The <literal>oracle</literal> dictionary understands the
+			following additional properties:
+			</para>
+          <itemizedlist>
+            <listitem id="OracleDictionary.UseTriggersForAutoAssign">
+              <para><indexterm><primary>Oracle</primary><secondary>UseTriggersForAutoAssign</secondary></indexterm><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>UseTriggersForAutoAssign</tertiary></indexterm><literal>UseTriggersForAutoAssign</literal>:
+					If true, then OpenJPA will allow simulation of auto-increment
+					columns by the use of Oracle triggers. OpenJPA will
+					assume that the current sequence value from the sequence
+					specified in the
+					<literal>AutoAssignSequenceName</literal> parameter 
+					will hold the value of the new primary key for rows that
+					have been inserted.
+					For more details on auto-increment support, see
+					<xref linkend="ref_guide_pc_oid_pkgen_autoinc"/>.
+					</para>
+            </listitem>
+            <listitem id="OracleDictionary.AutoAssignSequenceName">
+              <para><indexterm><primary>Oracle</primary><secondary>AutoAssignSequenceName</secondary></indexterm><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>AutoAssignSequenceName</tertiary></indexterm><literal>AutoAssignSequenceName</literal>:
+					The global name of the sequence that OpenJPA will
+					assume to hold the value of primary key value
+					for rows that use auto-increment. If left unset, OpenJPA will
+					use a the sequence named
+					<literal>"SEQ_&lt;table name&gt;"</literal>.
+					</para>
+            </listitem>
+            <listitem id="OracleDictionary.MaxEmbeddedBlobSize">
+              <para><indexterm><primary>Oracle</primary><secondary>MaxEmbeddedBlobSize</secondary></indexterm><indexterm><primary>BLOB</primary><secondary>MaxEmbeddedBlobSize</secondary></indexterm><literal>MaxEmbeddedBlobSize</literal>:
+					Oracle is unable to persist BLOBs using the embedded update
+					method when BLOBs get over a certain size.  The size depends
+					on database configuration, e.g. encoding.  This property
+					defines the maximum size BLOB to persist with the embedded
+					method.  Defaults to 4000 bytes.
+					</para>
+            </listitem>
+            <listitem id="OracleDictionary.MaxEmbeddedClobSize">
+              <para><indexterm><primary>Oracle</primary><secondary>MaxEmbeddedClobSize</secondary></indexterm><indexterm><primary>CLOB</primary><secondary>MaxEmbeddedClobSize</secondary></indexterm><literal>MaxEmbeddedClobSize</literal>:
+					Oracle is unable to persist CLOBs using the embedded update
+					method when Clobs get over a certain size.  The size depends
+					on database configuration, e.g. encoding.  This property
+					defines the maximum size CLOB to persist with the embedded
+					method.  Defaults to 4000 characters.
+					</para>
+            </listitem>
+            <listitem id="OracleDictionary.UseSetFormOfUseForUnicode">
+              <para><literal>UseSetFormOfUseForUnicode</literal>:
+					Prior to Oracle 10i, statements executed against
+					unicode capable columns (the <literal>NCHAR</literal>,
+					<literal>NVARCHAR</literal>, <literal>NCLOB</literal>
+					Oracle types) required special handling to be able to
+					store unicode values. Setting this property
+					to true (the default) will cause OpenJPA to attempt
+					to detect when the column of one of these types, and
+					if so, will attempt to correctly configure the
+					statement using the <methodname>
+					OraclePreparedStatement.setFormOfUse</methodname>.
+					For more details, see the Oracle
+					<ulink url="http://www.oracle.com/technology/sample_code/tech/java/codesnippet/jdbc/nchar/readme.html">
+					Readme For NChar</ulink>.
+					Note that this can only work if OpenJPA is able to
+					access the underlying
+					<classname>OraclePreparedStatement</classname> instance,
+					which may not be possible when using some third-party
+					datasources. If OpenJPA detects that this is the case,
+					a warning will be logged.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="ref_guide_dbsetup_sqlfactory">
+        <title>SQLFactory Properties</title>
+        <indexterm zone="ref_guide_dbsetup_dbsupport">
+          <primary>SQL</primary>
+          <secondary>SQLFactory</secondary>
+        </indexterm>
+        <para>
+		Some aspects of advanced SQL aren't configured through the
+		<classname>DBDictionary</classname>, but through the 
+		<classname>SQLFactory</classname>.  The 
+		<literal>openjpa.jdbc.SQLFactory</literal> configuration property is
+		a <link linkend="ref_guide_conf_plugins">plugin string</link>
+		you can use to configure the following parameters:
+		</para>
+        <itemizedlist>
+          <listitem id="SQLFactory.BatchLimit">
+            <para><indexterm><primary>prepared statement</primary><secondary>batching</secondary><tertiary>BatchLimit</tertiary></indexterm><literal>BatchLimit</literal>: The maximum number of SQL
+				update statements to batch together.  Set to 0 to disable
+				statement batching, or -1 for no limit.  See
+				<xref linkend="ref_guide_perfpack_batch"/>.
+				</para>
+          </listitem>
+          <listitem id="SQLFactory.BatchParameterLimit">
+            <para><indexterm><primary>prepared statement</primary><secondary>batching</secondary><tertiary>BatchParameterLimit</tertiary></indexterm><literal>BatchParameterLimit</literal>: The maximum number of
+				parameters that can be batched together for a single
+				batch update.  Some databases can only handle a certain
+				total number of prepared statement parameters in a single
+				batch.  This value will cause OpenJPA to flush a SQL batch
+				once the number of batched statements times the number of
+				bound parameters per statement exceeds this value.
+				Set to 0 to disable SQL batching, or -1 for no limit.
+				</para>
+          </listitem>
+          <listitem id="SQLFactory.SupportsUpdateCountsForBatch">
+            <para><indexterm><primary>prepared statement</primary><secondary>batching</secondary><tertiary>SupportsUpdateCountsForBatch</tertiary></indexterm><literal>SupportsUpdateCountsForBatch</literal>: Whether the
+				JDBC driver correctly returns the set of update counts when
+				a batch statement is executed.
+				</para>
+          </listitem>
+          <listitem id="SQLFactory.SupportsTotalCountsForBatch">
+            <para><indexterm><primary>prepared statement</primary><secondary>batching</secondary><tertiary>SupportsTotalCountsForBatch</tertiary></indexterm><literal>SupportsTotalCountsForBatch</literal>: If a JDBC 
+				driver doesn't support batch update counts, whether it
+				at least returns the total number of updates made when a batch
+				statement is executed.
+				</para>
+          </listitem>
+          <listitem id="SQLFactory.SupportsUnion">
+            <para><indexterm><primary>SQL</primary><secondary>union</secondary><tertiary>SupportsUnion</tertiary></indexterm><literal>SupportsUnion</literal>: Whether the database supports
+				SQL UNIONs.
+				</para>
+          </listitem>
+          <listitem id="SQLFactory.SupportsUnionWithUnalignedOrdering">
+            <para><indexterm><primary>SQL</primary><secondary>union</secondary><tertiary>SupportsUnionWithUnalignedOrdering</tertiary></indexterm><literal>SupportsUnionWithUnalignedOrdering</literal>: Whether 
+				the database supports SQL UNIONs that order on columns that are
+				not in the same position in all the SELECTs that make up the
+				UNION.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The defaults for these properties depend on the database in use.
+		</para>
+        <example id="ref_guide_dbsetup_sqlfactoryex">
+          <title>Configuring SQLFactory Properties</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.SQLFactory" value="BatchLimit=100, SupportsUnion=true"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_dbsetup_isolation">
+        <title>Setting the Transaction Isolation</title>
+        <indexterm zone="ref_guide_dbsetup_isolation">
+          <primary>transactions</primary>
+          <secondary>isolation</secondary>
+        </indexterm>
+        <indexterm zone="ref_guide_dbsetup_isolation">
+          <primary>JDBC</primary>
+          <secondary>transaction isolation</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>TransactionIsolation</primary>
+        </indexterm>
+        <para>
+		OpenJPA typically retains the default transaction isolation level
+		of the JDBC driver.  However, you can specify a transaction isolation
+		level to use through the <link linkend="openjpa.jdbc.TransactionIsolation"><literal>openjpa.jdbc.TransactionIsolation</literal></link> configuration 
+		property.  The following is a list of standard isolation levels.  
+		Note that not all databases support all isolation levels.
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>default</literal>: Use the JDBC driver's default
+				isolation level.  OpenJPA uses this option if you do not 
+				explicitly specify any other.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>none</literal>: No transaction isolation.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>read-committed</literal>: Dirty reads are
+				prevented; non-repeatable reads and phantom reads can
+				occur.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>read-uncommitted</literal>: Dirty reads,
+				non-repeatable reads and phantom reads can occur.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>repeatable-read</literal>: Dirty reads and
+				non-repeatable reads are prevented; phantom reads can occur.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>serializable</literal>: Dirty reads,
+				non-repeatable reads, and phantom reads are prevented.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_dbsetup_isoex">
+          <title>Specifying a Transaction Isolation</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.TransactionIsolation" value="repeatable-read"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_dbsetup_sql92">
+        <title>Setting the SQL Join Syntax</title>
+        <indexterm zone="ref_guide_dbsetup_sql92">
+          <primary>joins</primary>
+          <secondary>syntax options</secondary>
+        </indexterm>
+        <indexterm zone="ref_guide_dbsetup_sql92">
+          <primary>SQL</primary>
+          <secondary>join syntax</secondary>
+        </indexterm>
+        <para>
+		Object queries often involve using SQL joins behind the scenes.  You can
+		configure OpenJPA to use either SQL 92-style join syntax, in which joins
+		are placed in the SQL FROM clause, the traditional join syntax, in
+		which join criteria are part of the WHERE clause, or a database-specific
+		join syntax mandated by the <link linkend="ref_guide_dbsetup_dbdict"><classname>DBDictionary</classname></link>.  OpenJPA only supports outer 
+		joins when using SQL 92 syntax or a database-specific syntax with outer
+		join support.
+		</para>
+        <para>
+		The <link linkend="openjpa.jdbc.DBDictionary"><literal>
+		openjpa.jdbc.DBDictionary</literal></link> plugin accepts the
+		the <literal>JoinSyntax</literal> property to set
+		the system's default syntax.  The available values are:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>traditional</literal>: Traditional SQL 
+				join syntax; outer joins are not supported.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>database</literal>: The database's native 
+				join syntax.  Databases that do not have a native
+				syntax will default to one of the other options.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>sql92</literal>: ANSI SQL92 join syntax.  
+				Outer joins are supported.  Not all databases 
+				support this syntax.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		You can change the join syntax at runtime through the OpenJPA
+		fetch configuration API, which is described in 
+		<xref linkend="ref_guide_runtime"/>.
+		</para>
+        <example id="ref_guide_dbsetup_sql92_conf">
+          <title>Specifying the Join Syntax Default</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.DBDictionary" value="JoinSyntax=sql92"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_dbsetup_sql92_fetch">
+          <title>Specifying the Join Syntax at Runtime</title>
+          <programlisting format="linespecific">
+import org.apache.openjpa.persistence.jdbc.*; 
+
+... 
+
+Query q = em.createQuery ("select m from Magazine m where m.title = 'JDJ'");
+OpenJPAQuery kq = OpenJPAPersistence.cast (q);
+JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan ();
+fetch.setJoinSyntax (JDBCFetchPlan.JOIN_SYNTAX_SQL92);
+List results = q.getResultList ();
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_dbsetup_multidb">
+        <title>Accessing Multiple Databases</title>
+        <indexterm zone="ref_guide_dbsetup_multidb">
+          <primary>relational database</primary>
+          <secondary>accessing multiple databases</secondary>
+        </indexterm>
+        <para>
+		Through the properties we've covered thus far, you can configure each
+		<phrase><classname>EntityManagerFactory</classname></phrase>
+		
+		
+		to access a different database.  If your application accesses multiple
+		databases, we recommend that you maintain a separate properties file 
+		for each one.  This will allow you to easily load the appropriate
+		resource for each database at runtime, and to give the correct
+		configuration file to OpenJPA's command-line tools during development.
+		</para>
+      </section>
+      <section id="ref_guide_dbsetup_retain">
+        <title>Configuring the Use of JDBC Connections</title>
+        <indexterm zone="ref_guide_dbsetup_retain">
+          <primary>connections</primary>
+          <secondary>usage</secondary>
+        </indexterm>
+        <para>
+		In its default configuration, OpenJPA obtains JDBC connections on
+		an as-needed basis.  OpenJPA <classname>EntityManager</classname>s do
+		not retain a connection to the database unless they are in a datastore 
+		transaction or there are open <classname>Query</classname> results that
+		are using a live JDBC result set.  At all other times, including 
+		during optimistic transactions, <classname>EntityManager</classname>s 
+		request a connection for each query, then immediately release the 
+		connection back to the pool.
+		</para>
+        <para><indexterm><primary>ConnectionRetainMode</primary></indexterm>
+		In some cases, it may be more efficient to retain connections for
+		longer periods of time.  You can configure OpenJPA's use of JDBC
+		connections through the	
+		<link linkend="openjpa.ConnectionRetainMode"><literal>
+		openjpa.ConnectionRetainMode</literal></link> configuration property.  
+		The property accepts the following values:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>always</literal>: Each <classname>EntityManager
+				</classname> obtains a single connection and uses it until the
+				<classname>EntityManager</classname> closes.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>transaction</literal>: A connection is obtained
+				when each transaction begins (optimistic or datastore),
+				and is released when the transaction completes. 
+				Non-transactional connections are obtained on-demand.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>on-demand</literal>: Connections are obtained
+				only when needed.  This option is equivalent to 
+				the <literal>transaction</literal> option when datastore
+				transactions are used.  For optimistic transactions, 
+				though, it means that a connection will be retained only
+				for the duration of the datastore flush and commit process.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		You can also specify the connection retain mode of individual
+		<classname>EntityManager</classname>s when you retrieve them from 
+		the <classname>EntityManagerFactory</classname>.  See 
+		<xref linkend="ref_guide_runtime_emfactory"/> for details.
+		</para>
+        <para><indexterm><primary>FlushBeforeQueries</primary></indexterm>
+		The <link linkend="openjpa.FlushBeforeQueries"><literal>
+		openjpa.FlushBeforeQueries</literal></link> configuration property controls
+		another aspect of connection usage: whether to flush transactional
+		changes before executing object queries.  This setting only applies to 
+		queries that would otherwise have to be executed in-memory because the 
+		<link linkend="openjpa.IgnoreChanges"><literal>IgnoreChanges</literal></link> property is set to false and the query may involve objects that
+		have been changed in the current transaction.  Legal values are:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>true</literal>: Always flush rather than executing
+				the query in-memory.  If the current transaction is 
+				optimistic, OpenJPA will begin a non-locking datastore 
+				transaction.  This is the default.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>false</literal>: Never flush before a query.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>with-connection</literal>: Flush only if the
+				<classname>EntityManager</classname> has already 
+				established a dedicated connection to the datastore, otherwise 
+				execute the query in-memory.
+				</para>
+            <para>
+				This option is useful if
+				you use long-running optimistic transactions and want to
+				ensure that these transactions do not consume database
+				resources until commit.  OpenJPA's behavior with this option
+				is dependent on the transaction status and mode, as well as
+				the configured connection retain mode described earlier in
+				this section.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The flush mode can also be varied at runtime using the OpenJPA fetch 
+		configuration API, discussed in <xref linkend="ref_guide_runtime"/>.
+		</para>
+        <para><indexterm><primary>flush</primary><secondary>automatic</secondary></indexterm>
+		The table below describes the behavior of automatic flushing
+		in various situations. In all cases, flushing will only occur if OpenJPA 
+		detects that you have made modifications in
+		the current transaction that may affect the query's results.
+		</para>
+        <table>
+          <title>OpenJPA Automatic Flush Behavior</title>
+          <tgroup rowsep="1" colsep="1" align="left" cols="5">
+            <colspec colname="col1"/>
+            <colspec colname="col2"/>
+            <colspec colname="col3"/>
+            <colspec colname="col4"/>
+            <colspec colname="col5"/>
+            <thead>
+              <row>
+                <entry colname="col1"/>
+                <entry colname="col2">
+							FlushBeforeQueries = false
+						</entry>
+                <entry colname="col3">
+							FlushBeforeQueries = true
+						</entry>
+                <entry colname="col4">
+							FlushBeforeQueries = with-connection; 
+							ConnectionRetainMode = on-demand
+						</entry>
+                <entry colname="col5">
+							FlushBeforeQueries = with-connection; 
+							ConnectionRetainMode = transaction 
+							or always
+						</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry colname="col1">
+                  <emphasis role="bold">
+							IgnoreChanges = true
+							</emphasis>
+                </entry>
+                <entry colname="col2">no flush</entry>
+                <entry colname="col3">no flush</entry>
+                <entry colname="col4">no flush</entry>
+                <entry colname="col5">no flush</entry>
+              </row>
+              <row>
+                <entry colname="col1">
+                  <emphasis role="bold">
+							IgnoreChanges = false; no tx active
+							</emphasis>
+                </entry>
+                <entry colname="col2">no flush</entry>
+                <entry colname="col3">no flush</entry>
+                <entry colname="col4">no flush</entry>
+                <entry colname="col5">no flush</entry>
+              </row>
+              <row>
+                <entry colname="col1">
+                  <emphasis role="bold">
+							IgnoreChanges = false; datastore tx active
+							</emphasis>
+                </entry>
+                <entry colname="col2">no flush</entry>
+                <entry colname="col3">flush</entry>
+                <entry colname="col4">flush</entry>
+                <entry colname="col5">flush</entry>
+              </row>
+              <row>
+                <entry colname="col1">
+                  <emphasis role="bold">
+							IgnoreChanges = false; optimistic tx active
+							</emphasis>
+                </entry>
+                <entry colname="col2">no flush</entry>
+                <entry colname="col3">flush</entry>
+                <entry colname="col4">
+							no flush unless <methodname>flush</methodname> has 
+							already been invoked
+						</entry>
+                <entry colname="col5">flush</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+        <example id="ref_guide_dbsetup_sql92_retain_conf">
+          <title>Specifying Connection Usage Defaults</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.ConnectionRetainMode" value="on-demand"/&gt;
+&lt;property name="openjpa.FlushBeforeQueries" value="true"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_dbsetup_sql92_retain_runtime">
+          <title>Specifying Connection Usage at Runtime</title>
+          <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+... 
+
+// obtaining an em with a certain transaction and connection retain mode
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+EntityManager em = kemf.createEntityManager (PersistenceContextType.EXTENDED,
+    false, OpenJPAEntityManager.CONN_RETAIN_ALWAYS);
+
+...
+
+// changing the flush mode for an individual EntityManager
+OpenJPAEntityManager em = OpenJPAPersistence.cast (em);
+FetchPlan fetch = kem.getFetchPlan ();
+fetch.setFlushBeforeQueries (FetchPlan.QUERY_FLUSH_TRUE);
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_perfpack_batch">
+        <title>Statement Batching</title>
+        <indexterm zone="ref_guide_perfpack_batch">
+          <primary>prepared statement</primary>
+          <secondary>batching</secondary>
+        </indexterm>
+        <para>
+		In addition to connection pooling and prepared statement caching, OpenJPA
+		employs statement batching to speed up JDBC updates.
+		Statement batching is enabled by default for any JDBC driver that 
+		supports it.  When batching is on, OpenJPA automatically orders its SQL
+		statements to maximize the size of each batch.  This can result in 
+		large performance gains for transactions that modify a lot of data.
+		</para>
+        
+        <para>
+		You configure statement batching through the system
+		<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/DBDictionary.html"><classname>DBDictionary</classname></ulink>, which is controlled
+		by the <link linkend="openjpa.jdbc.DBDictionary"><literal>openjpa.jdbc.DBDictionary</literal></link> configuration
+		property.  The example below shows how to enable and disable statement 
+		batching via your configuration properties.
+		</para>
+        <example id="ref_guide_perfpack_batch_ex">
+          <title>Configuring SQL Batching</title>
+          <para>
+			The batch limit is the maximum number of statements OpenJPA will ever 
+			batch together.  A value of -1 means "no limit" - this is the 
+			default for most dictionaries.  A value of 0 disables batching.
+			</para>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.DBDictionary" value="BatchLimit=25"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_dbsetup_lrs">
+        <title>Large Result Sets</title>
+        <indexterm zone="ref_guide_dbsetup_lrs">
+          <primary>large result sets</primary>
+        </indexterm>
+        <indexterm>
+          <primary>JDBC</primary>
+          <secondary>large result sets</secondary>
+          <see>large result sets</see>
+        </indexterm>
+        <para>
+		By default, OpenJPA uses standard forward-only JDBC result sets, and
+		completely instantiates the results of database queries on execution.  
+		When using a JDBC driver that supports version 2.0 or higher
+		of the JDBC specification, however, you can configure OpenJPA to use
+		scrolling result sets that may not bring all results into memory
+		at once.  You can also configure the number of result objects OpenJPA 
+		keeps references to, allowing you to traverse potentially enormous 
+		amounts of data without exhausting JVM memory.
+		</para>
+        <note>
+          <para>
+			You can also configure on-demand loading for individual collection 
+			and map fields via large result set proxies.  See 
+			<xref linkend="ref_guide_pc_scos_proxy_lrs"/>.
+			</para>
+        </note>
+        <para>
+		Use the following properties to configure OpenJPA's handling of result 
+		sets:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>FetchBatchSize</primary></indexterm><link linkend="openjpa.FetchBatchSize"><literal>openjpa.FetchBatchSize</literal></link>: The number of
+				objects to instantiate at once when traversing a result set.
+				This number will be set as the fetch size on JDBC 
+				<classname>Statement</classname> objects used to obtain
+				result sets.  It also factors in to the number of objects
+				OpenJPA will maintain a hard reference to when traversing a 
+				query result.
+				</para>
+            <para>
+				The fetch size defaults to -1, meaning all results will be
+				instantiated immediately on query execution.  A value of 0
+				means to use the JDBC driver's default batch size.  Thus to
+				enable large result set handling, you must set this property
+				to 0 or to a positive number.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>ResultSetType</primary></indexterm><link linkend="openjpa.jdbc.ResultSetType"><literal>
+				openjpa.jdbc.ResultSetType</literal></link>: The type of result
+				set to use when executing database queries.  This
+				property accepts the following values, each of which corresponds
+				exactly to the same-named <classname>java.sql.ResultSet
+				</classname> constant:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>forward-only</literal>: This is the default.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>scroll-sensitive</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>scroll-insensitive</literal>
+                </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				Different JDBC drivers treat the different result set types
+				differently.  Not all drivers support all types.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>FetchDirection</primary></indexterm><link linkend="openjpa.jdbc.FetchDirection"><literal>
+				openjpa.jdbc.FetchDirection</literal></link>: The expected order
+				in which you will access the query results.  This property
+				affects the type of datastructure OpenJPA will use to hold the
+				results, and is also given to the JDBC driver in case it
+				can optimize for certain access patterns.  This
+				property accepts the following values, each of which corresponds
+				exactly to the same-named <classname>java.sql.ResultSet
+				</classname> FETCH constant:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>forward</literal>: This is the default.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>reverse</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>unknown</literal>
+                </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				Not all drivers support all fetch directions.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>LRSSize</primary></indexterm><link linkend="openjpa.jdbc.LRSSize"><literal>
+				openjpa.jdbc.LRSSize</literal></link>: The strategy OpenJPA will
+				use to determine the size of result sets.  This property is 
+				<emphasis role="bold">only</emphasis> used if you change the 
+				fetch batch size from its default of -1, so that OpenJPA begins 
+				to use on-demand result loading.  Available values are:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>query</literal>: This is the default.  The
+						first time you ask for the size of a query result,
+						OpenJPA will perform a <literal>SELECT COUNT(*)</literal>
+						query to determine the number of expected results.
+						Note that depending on transaction status and settings,
+						this can mean that the reported size is slightly
+						different than the actual number of results available.	
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>last</literal>: If you have chosen a
+						scrollable result set type, this setting will
+						use the <methodname>ResultSet.last</methodname>
+						method to move to the last element in the result
+						set and get its index. Unfortunately, some JDBC
+						drivers will bring all results into memory in
+						order to access the last one. Note that if you
+						do not choose a scrollable result set type, then
+						this will behave exactly
+						like <literal>unknown</literal>. The default
+						result set type is <literal>forward-only</literal>, so 
+						you must change the result set type in order for this
+						property to have an effect.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>unknown</literal>: Under this setting OpenJPA
+						will return <literal>Integer.MAX_VALUE</literal> as
+						the size for any query result that uses on-demand
+						loading.  
+						</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_dbsetup_lrs_def">
+          <title>Specifying Result Set Defaults</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.FetchBatchSize" value="20"/&gt;
+&lt;property name="openjpa.jdbc.ResultSetType" value="scroll-insensitive"/&gt;
+&lt;property name="openjpa.jdbc.FetchDirection" value="forward"/&gt;
+&lt;property name="openjpa.jdbc.LRSSize" value="last"/&gt;
+</programlisting>
+        </example>
+        <para>
+		Many <link linkend="ref_guide_runtime">OpenJPA runtime components
+		</link> also have methods to configure these properties
+		on a case-by-case basis through their fetch configuration.
+		See <xref linkend="ref_guide_runtime"/>.
+		</para>
+        <example id="ref_guide_dbsetup_lrs_runtime">
+          <title>Specifying Result Set Behavior at Runtime</title>
+          <programlisting format="linespecific">
+import java.sql.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+...
+
+Query q = em.createQuery ("select m from Magazine m where m.title = 'JDJ'");
+OpenJPAQuery kq = OpenJPAPersistence.cast (q);
+JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan ();
+fetch.setFetchSize (20);
+fetch.setResultSetType (ResultSet.TYPE_SCROLL_INSENSITIVE);
+fetch.setFetchDirection (ResultSet.FETCH_FORWARD);
+fetch.setLRSSize (JDBCFetchPlan.SIZE_LAST);
+List results = (List) q.getResultList ();
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_schema_def">
+        <title>Default Schema</title>
+        <indexterm zone="ref_guide_schema_def">
+          <primary>schema</primary>
+          <secondary>default</secondary>
+        </indexterm>
+        <para>
+		It is common to duplicate a database model in multiple schemas.  You
+		may have one schema for development and another for production, or
+		different database users may access different schemas.  OpenJPA facilitates
+		these patterns with the <link linkend="openjpa.jdbc.Schema"><literal>
+		openjpa.jdbc.Schema</literal></link> configuration property.  This property
+		establishes a default schema for any unqualified table names, allowing
+		you to leave schema names out of your mapping definitions.  
+		</para>
+        <para>
+		The <literal>Schema</literal> property also establishes the default
+		schema for new tables created through OpenJPA tools, such as the mapping
+		tool covered in <xref linkend="ref_guide_mapping_mappingtool"/>.
+		</para>
+      </section>
+      <section id="ref_guide_schema_info">
+        <title>Schema Reflection</title>
+        <indexterm zone="ref_guide_schema_info">
+          <primary>schema</primary>
+          <secondary>reflection</secondary>
+        </indexterm>
+        <para>
+		OpenJPA needs information about your database schema for two reasons.  
+		First, it can use schema information at runtime to validate that your 
+		schema is compatible with your persistent class definitions.  Second, 
+		OpenJPA requires schema information during development so that it can 
+		manipulate the schema to match your object model.  OpenJPA uses the 
+		<literal>SchemaFactory</literal> interface to provide runtime
+		mapping information, and the <classname>SchemaTool</classname>
+		for development-time data.  Each is presented below.
+		</para>
+        <section id="ref_guide_schema_info_list">
+          <title>Schemas List</title>
+          <indexterm zone="ref_guide_schema_info_list">
+            <primary>Schemas</primary>
+          </indexterm>
+          <indexterm zone="ref_guide_schema_info_list">
+            <primary>schema</primary>
+            <secondary>schemas list</secondary>
+          </indexterm>
+          <para>
+			By default, schema reflection acts on all the schemas your JDBC 
+			driver can "see".  You can limit the schemas and tables OpenJPA acts 
+			on with the <literal>openjpa.jdbc.Schemas</literal> configuration 
+			property.  This property accepts a comma-separated list of schemas 
+			and tables.  To list a schema, list its name.  To list a table, 
+			list its full name in the form 
+			<literal>&lt;schema-name&gt;.&lt;table-name&gt;</literal>.  If a 
+			table does not have a schema or you do not know its schema, list 
+			its name as <literal>.&lt;table-name&gt;</literal> (notice the 
+			preceding '.').  For example, to list the 
+			<literal>BUSOBJS</literal> schema, the <literal>ADDRESS</literal> 
+			table in the <literal>GENERAL</literal> schema, and the 
+			<literal>SYSTEM_INFO</literal> table, regardless of what schema it 
+			is in, use the string:
+			</para>
+          <programlisting format="linespecific">
+BUSOBJS,GENERAL.ADDRESS,.SYSTEM_INFO
+</programlisting>
+          <note>
+            <para>
+				Some databases are case-sensitive with respect to schema
+				and table names.  Oracle, for example, requires names
+				in all upper case.
+				</para>
+          </note>
+        </section>
+        <section id="ref_guide_schema_info_factory">
+          <title>Schema Factory</title>
+          <indexterm zone="ref_guide_schema_info_factory">
+            <primary>schema</primary>
+            <secondary>SchemaFactory</secondary>
+          </indexterm>
+          <para>
+			OpenJPA relies on the
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/SchemaFactory.html"><classname>openjpa.jdbc.SchemaFactory</classname></ulink> interface 
+			for runtime schema information.  You can control the schema factory
+			OpenJPA uses through the <literal>openjpa.jdbc.SchemaFactory</literal>
+			property.  There are several built-in options to choose from:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>dynamic</literal>: This is the default setting.
+					It is an alias for the
+					<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/DynamicSchemaFactory.html"><classname>org.apache.openjpa.jdbc.schema.DynamicSchemaFactory</classname></ulink>. The <classname>DynamicSchemaFactory</classname> 
+					is the most performant schema factory, because it does not 
+					validate mapping information against the database.
+					Instead, it assumes all object-relational mapping
+					information is correct, and dynamically builds an
+					in-memory representation of the schema from your mapping
+					metadata.  When using this factory, it is important that
+					your mapping metadata correctly represent your database's
+					foreign key constraints so that OpenJPA can order its SQL
+					statements to meet them.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>native</literal>: This is an alias for the
+					<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/LazySchemaFactory.html"><classname>org.apache.openjpa.jdbc.schema.LazySchemaFactory</classname></ulink>.  As persistent classes are loaded by the 
+					application, OpenJPA reads their metadata and 
+					object-relational mapping information.  This 
+					factory uses the <classname>java.sql.DatabaseMetaData
+					</classname> interface to reflect on the schema and ensure 
+					that it is consistent with the mapping data being read.  
+					Because the factory doesn't reflect on a table 
+					definition until that table is mentioned by the 
+					mapping information, we call it "lazy".  Use this
+					factory if you want up-front validation that your mapping
+					metadata is consistent with the database during development.
+					This factory accepts the following important properties:
+					</para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>ForeignKeys</literal>:  Set to <literal>
+							true</literal> to automatically read foreign key
+							information during schema validation.
+							</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para><literal>table</literal>: This is an alias for the
+					<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/TableSchemaFactory.html"><classname>org.apache.openjpa.jdbc.schema.TableSchemaFactory</classname></ulink>. This schema factory stores
+					schema information as an XML document in a database
+					table it creates for this purpose.  If your 
+					JDBC driver doesn't support the
+					<classname>java.sql.DatabaseMetaData</classname>
+					standard interface, but you still want some schema
+					validation to occur at runtime, you might use this
+					factory.  It is not recommended for most users, though,
+					because it is easy for the stored XML schema definition
+					to get out-of-synch with the actual database.  This factory
+					accepts the following properties:
+					</para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>Table</literal>:  The name of the table
+							to create to store schema information.  Defaults
+							to <literal>OPENJPA_SCHEMA</literal>.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>PrimaryKeyColumn</literal>:  The name of 
+							the table's numeric primary key column.  Defaults
+							to <literal>ID</literal>.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>SchemaColumn</literal>:  The name of 
+							the table's string column for holding the schema
+							definition as an XML string.  Defaults to
+							<literal>SCHEMA_DEF</literal>.
+							</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para><literal>file</literal>: This is an alias for the
+					<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/FileSchemaFactory.html"><classname>org.apache.openjpa.jdbc.schema.FileSchemaFactory</classname></ulink>. This factory is a lot like the
+					<classname>TableSchemaFactory</classname>, and has the
+					same advantages and disadvantages.  Instead
+					of storing its XML schema definition in a database
+					table, though, it stores it in a file.  This factory
+					accepts the following properties:
+					</para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>File</literal>:  The resource name
+							of the XML schema file.  By default, the factory
+							looks for a resource called <filename>
+							package.schema</filename>, located in any top-level
+							directory of the <literal>CLASSPATH</literal> or
+							in the top level of any jar in your
+							<literal>CLASSPATH</literal>.
+							</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+          <para>
+			You can switch freely between schema factories at any time.
+			The XML file format used by some factories is detailed 
+			in <xref linkend="ref_guide_schema_xml"/>.  As with any OpenJPA 
+			plugin, you can can also implement your own schema factory if you
+			have needs not met by the existing options.
+			</para>
+        </section>
+      </section>
+      <section id="ref_guide_schema_schematool">
+        <title>Schema Tool</title>
+        <indexterm zone="ref_guide_schema_schematool">
+          <primary>schema</primary>
+          <secondary>schema tool</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>schema</primary>
+          <secondary>DDL</secondary>
+          <see>DDL</see>
+        </indexterm>
+        <indexterm>
+          <primary>SQL</primary>
+          <secondary>DDL</secondary>
+          <see>DDL</see>
+        </indexterm>
+        <indexterm zone="ref_guide_schema_schematool">
+          <primary>DDL</primary>
+          <secondary>with schema tool</secondary>
+        </indexterm>
+        <para>
+		Most users will only access the schema tool indirectly, through the
+		interfaces provided by other tools.  You may find, however, that the 
+		schema tool is a powerful utility in its own right.
+		The schema tool has two functions:
+		</para>
+        <orderedlist>
+          <listitem>
+            <para>
+				To reflect on the current database schema, optionally 
+				translating it to an XML representation for further 
+				manipulation.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				To take in an XML schema definition, calculate the differences 
+				between the XML and the existing database schema, and apply the
+				necessary changes to make the database match the XML.
+				</para>
+          </listitem>
+        </orderedlist>
+        <para>
+		The <link linkend="ref_guide_schema_xml">XML format</link>
+		used by the schema tool abstracts away the differences between
+		SQL dialects used by different database vendors.  The tool also
+		automatically adapts its SQL to meet foreign key dependencies.
+		Thus the schema tool is useful as a general way to manipulate schemas.
+		</para>
+        <para>
+		You can invoke the schema tool through the
+		<literal>schematool</literal> shell/bat script included in the
+		OpenJPA distribution, or through its Java class,
+		<ulink url="../apidocs/org/apache/openjpa/jdbc/schema/SchemaTool.html"><classname>org.apache.openjpa.jdbc.schema.SchemaTool</classname></ulink>.  In 
+		addition to the universal flags of the <link linkend="ref_guide_conf">
+		configuration framework</link>, the schema tool accepts the following 
+		command line arguments:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>-ignoreErrors/-i &lt;true/t | false/f&gt;</literal>: 
+				If <literal>false</literal>, an exception will 
+				be thrown if the tool encounters any database errors.  
+				Defaults to <literal>false</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-file/-f &lt;stdout | output file&gt;</literal>: 
+				Use this option to write a SQL script for the planned
+				schema modifications, rather them committing them to the
+				database.  When used in conjunction with the 
+				<literal>export</literal> or <literal>reflect</literal> actions,				the named file will be used to write the exported schema XML.  
+  				If the file names a resource in the
+				<literal>CLASSPATH</literal>, data will be written
+				to that resource.  Use <literal>stdout</literal> to
+				write to standard output.  Defaults to
+				<literal>stdout</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-openjpaTables/-kt &lt;true/t | false/f&gt;</literal>:
+				When reflecting on the schema, whether to reflect on tables
+				and sequences whose names start with <literal>OPENJPA_</literal>.
+				Certain OpenJPA components may use such tables - for example, 
+				the <literal>table</literal> schema factory option covered 
+				in <xref linkend="ref_guide_schema_info_factory"/>.
+				When using other actions, <literal>openjpaTables</literal> 
+				controls whether these tables can be dropped.  Defaults to 
+				<literal>false</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-dropTables/-dt &lt;true/t | false/f&gt;</literal>:
+				Set this option to <literal>true</literal> to drop tables
+				that appear to be unused during <literal>retain</literal>
+				and <literal>refresh</literal> actions.  Defaults to
+				<literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-dropSequences/-dsq &lt;true/t | false/f&gt;</literal>:
+				Set this option to <literal>true</literal> to drop sequences
+				that appear to be unused during <literal>retain</literal>
+				and <literal>refresh</literal> actions.  Defaults to
+				<literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-sequences/-sq &lt;true/t | false/f&gt;</literal>: 
+				Whether to manipulate sequences.  
+				Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-indexes/-ix &lt;true/t | false/f&gt;</literal>: 
+				Whether to manipulate indexes on existing tables.
+				Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-primaryKeys/-pk &lt;true/t | false/f&gt;</literal>: 
+				Whether to manipulate primary keys on existing
+				tables.  Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-foreignKeys/-fk &lt;true/t | false/f&gt;</literal>: 
+				Whether to manipulate foreign keys on 
+				existing tables.  Defaults to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-record/-r &lt;true/t | false/f&gt;</literal>: Use
+				<literal>false</literal> to prevent writing the schema
+				changes made by the tool to the current
+				<link linkend="ref_guide_schema_info_factory"><literal>schema factory</literal></link>.  Defaults to
+				<literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-schemas/-s &lt;schema list&gt;</literal>: A list
+				of schema and table names that OpenJPA should access during
+				this run of the schema tool. This is equivalent to setting 
+				the <link linkend="openjpa.jdbc.Schemas">openjpa.jdbc.Schemas</link>
+				property for a single run.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The schema tool also accepts an <literal>-action</literal> or
+		<literal>-a</literal> flag.  The available actions are:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>add</literal>: This is the default action if you do
+				not specify one.  It brings the schema up-to-date with
+				the given XML document by adding tables, columns, indexes,
+				etc.  This action never drops any schema components.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>retain</literal>: Keep all schema components in
+				the given XML definition, but drop the rest from the
+				database.  This action never adds any schema components.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>drop</literal>: Drop all schema components in the
+				schema XML.  Tables will only be dropped if they would have
+				0 columns after dropping all columns listed in the XML.  
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>refresh</literal>: Equivalent to
+				<literal>retain</literal>, then <literal>add</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>build</literal>: Generate SQL to build a schema 
+				matching the one in the given XML file.  Unlike 
+				<literal>add</literal>, this option does not take into account
+				the fact that part of the schema defined in the XML file might 
+				already exist in the database.  Therefore, this action is 
+				typically used in conjunction with the <literal>-file</literal>
+				flag to write a SQL script.  This script can later be used to
+				recreate the schema in the XML.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>reflect</literal>: Generate an XML representation
+				of the current database schema.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>createDB</literal>: Generate SQL to re-create the
+				current database.  This action is typically used in 
+				conjunction with the <literal>-file</literal> flag to
+				write a SQL script that can be used to recreate the current
+				schema on a fresh database.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>dropDB</literal>: Generate SQL to drop the
+				current database.  Like <literal>createDB</literal>, this
+				action can be used with the <literal>-file</literal>
+				flag to script a database drop rather than perform it. 
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>import</literal>: Import the given XML schema
+				definition into the current schema factory.  Does nothing
+				if the factory does not store a record of the schema.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>export</literal>: Export the current schema
+				factory's stored schema definition to XML.  May produce
+				an empty file if the factory does not store a record of
+				the schema.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <note>
+          <para>
+			The schema tool manipulates tables, columns, indexes, constraints,
+			and sequences.  It cannot create or drop
+			the database schema objects in which the tables reside,
+			however.  If your XML documents refer to named database
+			schemas, those schemas must exist.
+			</para>
+        </note>
+        <para>
+		We present some examples of schema tool usage below.
+		</para>
+        <example id="ref_guide_schema_schematool_create">
+          <title>Schema Creation</title>
+          <indexterm zone="ref_guide_schema_schematool_create">
+            <primary>schema</primary>
+            <secondary>create with schema tool</secondary>
+          </indexterm>
+          <para>
+			Add the necessary schema components to the database to match
+			the given XML document, but don't drop any data:
+			</para>
+          <programlisting format="linespecific">
+schematool targetSchema.xml
+</programlisting>
+        </example>
+        <example id="ref_guide_schema_schematool_script">
+          <title>SQL Scripting</title>
+          <para>
+			Repeat the same action as the first example, but this time
+			don't change the database.  Instead, write any planned changes
+			to a SQL script:
+			</para>
+          <programlisting format="linespecific">
+schematool -f script.sql targetSchema.xml
+</programlisting>
+          <para>
+			Write a SQL script that will re-create the current database:
+			</para>
+          <programlisting format="linespecific">
+schematool -a createDB -f script.sql
+</programlisting>
+        </example>
+        <example id="ref_guide_schema_schematool_drop">
+          <title>Schema Drop</title>
+          <para>
+			Drop the current database:
+			</para>
+          <programlisting format="linespecific">
+schematool -a dropDB
+</programlisting>
+        </example>
+        <example id="ref_guide_schema_schematool_reflect">
+          <title>Schema Reflection</title>
+          <indexterm zone="ref_guide_schema_schematool_reflect">
+            <primary>schema</primary>
+            <secondary>reflection</secondary>
+            <tertiary>with schema tool</tertiary>
+          </indexterm>
+          <para>
+			Write an XML representation of the current schema to file
+			<filename>schema.xml</filename>.
+			</para>
+          <programlisting format="linespecific">
+schematool -a reflect -f schema.xml
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_schema_xml">
+        <title>XML Schema Format</title>
+        <indexterm zone="ref_guide_schema_xml">
+          <primary>schema</primary>
+          <secondary>XML representation</secondary>
+        </indexterm>
+        <para>
+		The <link linkend="ref_guide_schema_schematool">schema tool</link> and
+		<link linkend="ref_guide_schema_info_factory">
+		schema factories</link> all use the same XML format to represent
+		database schema.  The Document Type Definition (DTD) for
+		schema information is presented below, followed by examples
+		of schema definitions in XML.
+		</para>
+        <programlisting format="linespecific">
+&lt;!ELEMENT schemas (schema)+&gt;
+&lt;!ELEMENT schema (table|sequence)+&gt;
+&lt;!ATTLIST schema name CDATA #IMPLIED&gt;
+
+&lt;!ELEMENT sequence EMPTY&gt;
+&lt;!ATTLIST sequence name CDATA #REQUIRED&gt;
+&lt;!ATTLIST sequence initial-value CDATA #IMPLIED&gt;
+&lt;!ATTLIST sequence increment CDATA #IMPLIED&gt;
+&lt;!ATTLIST sequence allocate CDATA #IMPLIED&gt;
+
+&lt;!ELEMENT table (column|index|pk|fk)+&gt;
+&lt;!ATTLIST table name CDATA #REQUIRED&gt;
+
+&lt;!ELEMENT column EMPTY&gt;
+&lt;!ATTLIST column name CDATA #REQUIRED&gt; 
+&lt;!ATTLIST column type (array | bigint | binary | bit | blob | char | clob 
+    | date | decimal | distinct | double | float | integer | java_object 
+    | longvarbinary | longvarchar | null | numeric | other | real | ref 
+    | smallint | struct | time | timestamp | tinyint | varbinary | varchar) 
+    #REQUIRED&gt;
+&lt;!ATTLIST column not-null (true|false) "false"&gt;
+&lt;!ATTLIST column auto-assign (true|false) "false"&gt;
+&lt;!ATTLIST column default CDATA #IMPLIED&gt;
+&lt;!ATTLIST column size CDATA #IMPLIED&gt;
+&lt;!ATTLIST column decimal-digits CDATA #IMPLIED&gt;
+
+&lt;!-- the type-name attribute can be used when you want OpenJPA to   --&gt;
+&lt;!-- use a particular SQL type declaration when creating the     --&gt;
+&lt;!-- column. It is up to you to ensure that this type is         --&gt;
+&lt;!-- compatible with the JDBC type used in the type attribute.   --&gt;
+&lt;!ATTLIST column type-name CDATA #IMPLIED&gt;
+
+&lt;!-- the 'column' attribute of indexes, pks, and fks can be used --&gt;
+&lt;!-- when the element has only one column (or for foreign keys,  --&gt;
+&lt;!-- only one local column); in these cases the on/join child    --&gt;
+&lt;!-- elements can be omitted                                     --&gt;
+&lt;!ELEMENT index (on)*&gt;
+&lt;!ATTLIST index name CDATA #REQUIRED&gt;
+&lt;!ATTLIST index column CDATA #IMPLIED&gt;
+&lt;!ATTLIST index unique (true|false) "false"&gt;
+
+&lt;!-- the 'logical' attribute of pks should be set to 'true' if   --&gt; 
+&lt;!-- the primary key does not actually exist in the database,    --&gt; 
+&lt;!-- but the given column should be used as a primary key for    --&gt;
+&lt;!-- O-R purposes                                                --&gt;
+&lt;!ELEMENT pk (on)*&gt;
+&lt;!ATTLIST pk name CDATA #IMPLIED&gt;
+&lt;!ATTLIST pk column CDATA #IMPLIED&gt;
+&lt;!ATTLIST pk logical (true|false) "false"&gt;
+
+&lt;!ELEMENT on EMPTY&gt;
+&lt;!ATTLIST on column CDATA #REQUIRED&gt;
+
+&lt;!-- fks with a delete-action of 'none' are similar to logical   --&gt;
+&lt;!-- pks; they do not actually exist in the database, but        --&gt;
+&lt;!-- represent a logical relation between tables (or their       --&gt;
+&lt;!-- corresponding Java classes)                                 --&gt;
+&lt;!ELEMENT fk (join)*&gt;
+&lt;!ATTLIST fk name CDATA #IMPLIED&gt;
+&lt;!ATTLIST fk deferred (true|false) "false"&gt;
+&lt;!ATTLIST fk to-table CDATA #REQUIRED&gt;
+&lt;!ATTLIST fk column CDATA #IMPLIED&gt;
+&lt;!ATTLIST fk delete-action (cascade|default|exception|none|null) "none"&gt;
+
+&lt;!ELEMENT join EMPTY&gt;
+&lt;!ATTLIST join column CDATA #REQUIRED&gt;
+&lt;!ATTLIST join to-column CDATA #REQUIRED&gt;
+&lt;!ATTLIST join value CDATA #IMPLIED&gt;
+
+&lt;!-- unique constraint --&gt;
+&lt;!ELEMENT unique (on)*&gt;
+&lt;!ATTLIST unique name CDATA #IMPLIED&gt;
+&lt;!ATTLIST unique column CDATA #IMPLIED&gt;
+&lt;!ATTLIST unique deferred (true|false) "false"&gt;
+</programlisting>
+        <example id="ref_guide_schema_xml_basic">
+          <title>Basic Schema</title>
+          <para>
+			A very basic schema definition.
+			</para>
+          <programlisting format="linespecific">
+&lt;schemas&gt;
+    &lt;schema&gt;
+        &lt;sequence name="S_ARTS"/&gt;
+        &lt;table name="ARTICLE"&gt;
+            &lt;column name="TITLE" type="varchar" size="255" not-null="true"/&gt;
+            &lt;column name="AUTHOR_FNAME" type="varchar" size="28"&gt; 
+            &lt;column name="AUTHOR_LNAME" type="varchar" size="28"&gt; 
+            &lt;column name="CONTENT" type="clob"&gt; 
+        &lt;/table&gt;
+        &lt;table name="AUTHOR"&gt;
+            &lt;column name="FIRST_NAME" type="varchar" size="28" not-null="true"&gt; 
+            &lt;column name="LAST_NAME" type="varchar" size="28" not-null="true"&gt; 
+        &lt;/table&gt;
+    &lt;/schema&gt;
+&lt;/schemas&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_schema_xml_full">
+          <title>Full Schema</title>
+          <para>
+			Expansion of the above schema with primary keys, constraints,
+			and indexes, some of which span multiple columns.
+			</para>
+          <programlisting format="linespecific">
+&lt;schemas&gt;
+    &lt;schema&gt;
+        &lt;sequence name="S_ARTS"/&gt;
+        &lt;table name="ARTICLE"&gt;
+            &lt;column name="TITLE" type="varchar" size="255" not-null="true"/&gt;
+            &lt;column name="AUTHOR_FNAME" type="varchar" size="28"&gt; 
+            &lt;column name="AUTHOR_LNAME" type="varchar" size="28"&gt; 
+            &lt;column name="CONTENT" type="clob"&gt; 
+            &lt;pk column="TITLE"/&gt;
+            &lt;fk to-table="AUTHOR" delete-action="exception"&gt;
+                &lt;join column="AUTHOR_FNAME" to-column="FIRST_NAME"/&gt;
+                &lt;join column="AUTHOR_LNAME" to-column="LAST_NAME"/&gt;
+            &lt;/fk&gt;
+            &lt;index name="ARTICLE_AUTHOR"&gt;
+                &lt;on column="AUTHOR_FNAME"/&gt;
+                &lt;on column="AUTHOR_LNAME"/&gt;
+            &lt;/index&gt;
+        &lt;/table&gt;
+        &lt;table name="AUTHOR"&gt;
+            &lt;column name="FIRST_NAME" type="varchar" size="28" not-null="true"&gt; 
+            &lt;column name="LAST_NAME" type="varchar" size="28" not-null="true"&gt; 
+            &lt;pk&gt;
+                &lt;on column="FIRST_NAME"/&gt;
+                &lt;on column="LAST_NAME"/&gt;
+            &lt;/pk&gt;
+        &lt;/table&gt;
+    &lt;/schema&gt;
+&lt;/schemas&gt;
+</programlisting>
+        </example>
+      </section>
+    </chapter>
+    <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>
+        <indexterm zone="ref_guide_pc_pcclasses">
+          <primary>persistent classes</primary>
+          <secondary>list</secondary>
+        </indexterm>
+        <indexterm zone="ref_guide_pc_pcclasses">
+          <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.
+				</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>
+        <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>
+        </note>
+      </section>
+      <section id="ref_guide_pc_enhance">
+        <title>Enhancement</title>
+        <indexterm zone="ref_guide_pc_enhance">
+          <primary>enhancer</primary>
+        </indexterm>
+        <indexterm>
+          <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>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 509 x 133 (see README) -->
+            <imagedata fileref="img/enhancement.png" width="339px"/>
+          </imageobject>
+        </mediaobject>
+        <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>
+        <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">
+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>
+        </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>
+        </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">
+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">
+java -javaagent:/home/dev/openjpa/lib/org.apache.openjpa.jar=jdoEnhance=true,addDefaultConstructor=false com.xyz.Main
+</programlisting>
+          </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>
+        </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>
+        <indexterm zone="ref_guide_pc_oid">
+          <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>
+        <example id="ref_guide_pc_oid_datastoreentityex">
+          <title>JPA Datastore Identity Metadata</title>
+          <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@DataStoreId
+public class LineItem
+{
+    ... no @Id fields declared ...
+}
+</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>
+        </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">
+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>
+        </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>
+        </section>
+      </section>
+      <section id="ref_guide_inverses">
+        <title>Managed Inverses</title>
+        <indexterm zone="ref_guide_inverses">
+          <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>
+        <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">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Magazine
+{
+    @OneToOne
+    private Photograph coverPhoto;
+    
+    ...
+}
+
+@Entity
+public class Photograph
+{
+    @OneToOne
+    @InverseLogical("coverPhoto")
+    private Magazine mag;
+    
+    ...
+}
+</programlisting>
+          <programlisting format="linespecific">
+&lt;class name="Magazine"&gt;
+    &lt;field name="coverPhoto"/&gt;
+    ...
+&lt;/class&gt;
+&lt;class name="Photograph"&gt;
+    &lt;field name="mag"&gt;
+        &lt;extension vendor-name="openjpa" key="inverse-logical" value="coverPhoto"/&gt;
+    &lt;/field&gt;
+    ...
+&lt;/class&gt;
+</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>
+        <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">
+&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>
+        <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">
+&lt;property name="openjpa.InverseManager" value="true(Action=warn)"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_pc_scos">
+        <title>Persistent Fields</title>
+        <indexterm zone="ref_guide_pc_scos">
+          <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>
+        <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>
+        </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">
+public class Company
+{
+    // OpenJPA will detect the custom comparator in the initial field value
+    // and use it whenever loading data from the database into this field
+    private Collection employeesBySal = new TreeSet (new SalaryComparator ());
+    private Map departments;
+
+    public Company
+    {
+        // or we can initialize fields in our no-args constructor; even though
+        // this field is declared type Map, OpenJPA will detect that it's actually
+        // a TreeMap and use natural ordering for loaded data
+        departments = new TreeMap ();
+    }
+
+    // rest of class definition...
+}
+</programlisting>
+          </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>
+        </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">
+import org.apache.openjpa.persistence.*;
+
+...
+
+Collection employees = company.getEmployees (); // employees is a lrs collection
+Iterator itr = employees.iterator ();
+while (itr.hasNext ())
+    process ((Employee) itr.next ());
+OpenJPAPersistence.close (itr);
+</programlisting>
+            </example>
+            <para>
+				You can also add and remove from large result set proxies, just
+				as with standard fields.  OpenJPA keeps a record of all changes
+				to the elements of the proxy, which it uses to make sure 
+				the proper results are always returned from collection and
+				map methods, and to update the field's database record on
+				commit.
+				</para>
+            <para>
+              <phrase>
+				In order to use large result set proxies in JPA, add the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname>
+				org.apache.openjpa.persistence.LRS</classname></ulink> annotation to the
+				persistent field.
+				</phrase>
+            </para>
+            <para>
+				The following restrictions apply to large result set fields:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+						The field must be declared as either a 
+						<classname>java.util.Collection</classname> or 
+						<classname>java.util.Map</classname>.  It cannot be 
+						declared as any other type, including any sub-interface
+						of collection or map, or any concrete collection or map
+						class.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						The field cannot have an externalizer
+						(see <xref linkend="ref_guide_pc_extern"/>).
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						Because they rely on their owning object for context, 
+						large result set proxies cannot be transferred from one
+						persistent field to another.  The following code would 
+						result in an error on commit:
+						</para>
+                <programlisting format="linespecific">
+Collection employees = company.getEmployees ()  // employees is a lrs collection
+company.setEmployees (null);
+anotherCompany.setEmployees (employees);
+</programlisting>
+              </listitem>
+            </itemizedlist>
+            <example id="ref_guide_pc_scos_proxy_lrs_extension">
+              <title>Marking a Large Result Set Field</title>
+              <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Company
+{
+    @ManyToMany 
+    @LRS private Collection&lt;Employee&gt; employees;     
+
+    ...
+}
+</programlisting>
+            </example>
+          </section>
+          <section id="ref_guide_pc_scos_proxy_custom">
+            <title>Custom Proxies</title>
+            <indexterm zone="ref_guide_pc_scos_proxy_custom">
+              <primary>proxies</primary>
+              <secondary>custom</secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_pc_scos_proxy_custom">
+              <primary>proxies</primary>
+              <secondary>ProxyManager</secondary>
+            </indexterm>
+            <para>
+				OpenJPA manages proxies through the
+				<ulink url="../apidocs/org/apache/openjpa/util/ProxyManager.html"><classname>org.apache.openjpa.util.ProxyManager</classname></ulink> interface.
+				OpenJPA includes a default proxy manager, the
+				<classname>org.apache.openjpa.util.ProxyManagerImpl</classname> (with a plugin
+				alias name of <literal>default</literal>),
+				that will meet the needs of most users.   The default proxy
+				manager understands the following configuration properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>TrackChanges</literal>: Whether to use 
+						<link linkend="ref_guide_pc_scos_proxy_smart">smart 
+						proxies</link>.  Defaults to <literal>true</literal>.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				For custom behavior, OpenJPA allows you to define your own 
+				proxy classes, and your own proxy manager.  See the 
+				<literal>openjpa.util</literal> package 
+				<ulink url="../apidocs/">Javadoc</ulink> for details on the 
+				interfaces involved, and the utility classes OpenJPA provides to 
+				assist you.
+				</para>
+            <para>
+				You can plug your custom proxy manager into the OpenJPA runtime
+				through the <link linkend="openjpa.ProxyManager"><literal>
+				openjpa.ProxyManager</literal></link> configuration property.  
+				
+				</para>
+            <example id="ref_guide_pc_scos_proxy_custom_ex">
+              <title>Configuring the Proxy Manager</title>
+              <programlisting format="linespecific">
+&lt;property name="openjpa.ProxyManager" value="TrackChanges=false"/&gt;
+</programlisting>
+            </example>
+          </section>
+        </section>
+        <section id="ref_guide_pc_extern">
+          <title>Externalization</title>
+          <indexterm zone="ref_guide_pc_extern">
+            <primary>externalization</primary>
+          </indexterm>
+          <indexterm>
+            <primary>persistent fields</primary>
+            <secondary>externalization</secondary>
+            <see>externalization</see>
+          </indexterm>
+          <para>
+			OpenJPA offers the ability to write
+			<link linkend="ref_guide_mapping_custom_field">custom field 
+			mappings</link> in order to have complete control over the 
+			mechanism with which fields are stored, queried, and loaded from 
+			the datastore. Often, however, a custom mapping is overkill.  
+			There is often a simple transformation from a Java field value
+			to its database representation.  Thus, OpenJPA provides the 
+			externalization service.  Externalization allows you to specify 
+			methods that will externalize a field value to its database 
+			equivalent on store and then rebuild the value from its 
+			externalized form on load.
+			</para>
+          <note>
+            <para>
+				Fields of embeddable classes used for <literal>@EmbeddedId
+				</literal> values in JPA cannot have externalizers. 
+				</para>
+          </note>
+          <para>
+			The 
+			<phrase>
+			JPA <ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html"><classname>org.apache.openjpa.persistence.Externalizer</classname></ulink>
+			annotation
+			</phrase>
+			
+			
+			sets the name of a method that will be invoked to convert the field
+			into its external form for database storage. You can specify
+			either the name of a non-static method, which will be invoked on 
+			the field value, or a static method, which will be invoked with 
+			the field value as a parameter. Each method can also take an 
+			optional 
+			<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html"><classname>StoreContext</classname></ulink> parameter for 
+			access to a persistence context.  The return value of the method is
+			the field's external
+			form.  By default, OpenJPA assumes that all named methods belong to the
+			field value's class (or its superclasses).  You can, however, 
+			specify static methods of other classes using the format
+			<literal>&lt;class-name&gt;.&lt;method-name&gt;</literal>.
+			</para>
+          <para>
+			Given a field of type <classname>CustomType</classname> that 
+			externalizes to a string, the table below demonstrates several
+			possible externalizer methods and their corresponding
+			metadata extensions.
+			</para>
+          <table tocentry="1">
+            <title>Externalizer Options</title>
+            <tgroup cols="2" align="left" colsep="1" rowsep="1">
+              <colspec colname="method"/>
+              <colspec colname="extension"/>
+              <thead>
+                <row>
+                  <entry colname="method">Method</entry>
+                  <entry colname="extension">Extension</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public String CustomType.toString()
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Externalizer("toString")
+							</literal>
+                  </entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public String CustomType.toString(StoreContext ctx)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Externalizer("toString")
+							</literal>
+                  </entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public static String AnyClass.toString(CustomType ct)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Externalizer("AnyClass.toString")
+							</literal>
+                  </entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public static String AnyClass.toString(CustomType ct, StoreContext ctx)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Externalizer("AnyClass.toString")
+							</literal>
+                  </entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+          <para>
+			The 
+			<phrase>
+			JPA <ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>org.apache.openjpa.persistence.Factory</classname></ulink> annotation
+			</phrase>
+			
+			
+			contains the name of a method that will be invoked to 
+			instantiate the field from the external form stored in 
+			the database. Specify a static method name.  The method will
+			will be invoked with the externalized value and must return 
+			an instance of the field type. The method can also take an optional
+			<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html"><classname>StoreContext</classname></ulink> parameter for 
+			access to a persistence context.
+			If a factory is not specified, OpenJPA will use the constructor 
+			of the field type that takes a single argument of the external 
+			type, or will throw an exception if no constructor with that 
+			signature exists.
+			</para>
+          <para>
+			Given a field of type <classname>CustomType</classname> that 
+			externalizes to a string, the table below demonstrates several
+			possible factory methods and their corresponding
+			metadata extensions.
+			</para>
+          <table tocentry="1">
+            <title>Factory Options</title>
+            <tgroup cols="2" align="left" colsep="1" rowsep="1">
+              <colspec colname="method"/>
+              <colspec colname="extension"/>
+              <thead>
+                <row>
+                  <entry colname="method">Method</entry>
+                  <entry colname="extension">Extension</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public CustomType(String str)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+							none
+							</entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public static CustomType CustomType.fromString(String str)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Factory("fromString")
+							</literal>
+                  </entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public static CustomType CustomType.fromString(String str, StoreContext ctx)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Factory("fromString")
+							</literal>
+                  </entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public static CustomType AnyClass.fromString(String str)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Factory("AnyClass.fromString")
+							</literal>
+                  </entry>
+                </row>
+                <row>
+                  <entry colname="method">
+                    <literal>
+							public static CustomType AnyClass.fromString(String str, StoreContext ctx)
+							</literal>
+                  </entry>
+                  <entry colname="extension">
+                    <literal>
+							@Factory("AnyClass.fromString")
+							</literal>
+                  </entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+          <para>
+			If your externalized field is not a standard persistent type, you
+			must explicitly mark it persistent.
+			<phrase>
+			In JPA, you can force a persistent field by annotating it with 
+			<link linkend="ref_guide_meta_ejb_persistent"><classname>
+			org.apache.openjpa.persistence.Persistent</classname></link> annotation.
+			</phrase>
+			
+			</para>
+          <note>
+            <para>
+				If your custom field type is mutable and is not a standard
+				collection, map, or date class, OpenJPA will not be able to
+				detect changes to the field.  You must mark the field dirty
+				manully, or create a custom field proxy.
+				</para>
+            <para>
+              <phrase>
+				See <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><methodname>OpenJPAEntityManager.dirty</methodname></ulink> for how
+				to mark a field dirty manually in JPA.
+				</phrase>
+            </para>
+            <para>
+				See <xref linkend="ref_guide_pc_scos_proxy"/> for a discussion 
+				of proxies.
+				
+				</para>
+          </note>
+          <para>
+			You can externalize a field to virtually any value that is 
+			supported by OpenJPA's field mappings (embedded relations are the
+			exception; you must declare your field to be a persistence-capable 
+			type in order to embed it).  This means that
+			a field can externalize to something as simple as a primitive, 
+			something as complex as a collection or map of 
+			persistence-capable objects, or anything in between.  If you do 
+			choose to externalize to a collection or map, OpenJPA recognizes a 
+			family of metadata extensions for specying type information
+			for the externalized form of your fields - see 
+			<xref linkend="type"/>.  If the external form of your field 
+			is a persistence-capable object, or contains persistence-capable 
+			objects, OpenJPA will correctly include the objects in its 
+			persistence-by-reachability algorithms and its delete-dependent 
+			algorithms.
+			</para>
+          <para>
+			The example below demonstrates a few forms of externalization.
+			
+			</para>
+          <example id="ref_guide_pc_externex">
+            <title>Using Externalization</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Magazine
+{
+    // use Class.getName and Class.forName to go to/from strings
+    @Persistent
+    @Externalizer("getName") 
+    @Factory("forName")
+    private Class cls;
+
+    // use URL.getExternalForm for externalization. no factory; 
+    // we can rely on the URL string constructor
+    @Persistent
+    @Externalizer("toExternalForm")
+    private URL url;
+
+    // use our custom methods; notice how we use the KeyType and ElementType 
+    // annotations to specify the metadata for our externalized map
+    @Persistent 
+    @Externalizer("Magazine.mapFromCustomType")
+    @Factory("Magazine.mapToCustomType")
+    @KeyType(String.class) @ElementType(String.class)
+    private CustomType customType;
+
+    public static Map mapFromCustomType (CustomType customType)
+    {
+        ... logic to pack custom type into a map ...
+    }
+
+    public static CustomType mapToCustomType (Map map)
+    {
+        ... logic to create custom type from a map ...
+    }
+
+    ...
+}
+</programlisting>
+          </example>
+          <para><indexterm><primary>externalization</primary><secondary>queries</secondary></indexterm>
+			You can query externalized fields using parameters.
+			Pass in a value of the field type when executing the query.  OpenJPA 
+			will externalize the parameter using the externalizer method named 
+			in your metadata, and compare the externalized parameter with the 
+			value stored in the database.   As a shortcut, OpenJPA 
+			also allows you to use parameters or literals of the field's 
+			externalized type in queries, as demonstrated in the example below.
+			</para>
+          <note>
+            <para>
+				Currently, queries are limited 
+				to fields that externalize to a primitive, primitive wrapper,
+				string, or date types, due to constraints on query syntax.  
+				</para>
+          </note>
+          <example id="ref_guide_pc_extern_queryex">
+            <title>Querying Externalization Fields</title>
+            <para>
+				Assume the <classname>Magazine</classname> class has the
+				same fields as in the previous example.
+				</para>
+            <programlisting format="linespecific">
+// you can query using parameters
+Query q = em.createQuery ("select m from Magazine m where m.url = :u");
+q.setParameter ("u", new URL ("http://www.solarmetric.com"));
+List results = q.getResultList ();
+
+// or as a shortcut, you can use the externalized form directly
+q = em.createQuery ("select m from Magazine m where m.url = 'http://www.solarmetric.com'");
+results = q.getResultList ();
+</programlisting>
+          </example>
+          <section id="ref_guide_pc_extern_values">
+            <title>External Values</title>
+            <indexterm zone="ref_guide_pc_extern_values">
+              <primary>externalization</primary>
+              <secondary>external values</secondary>
+            </indexterm>
+            <para>
+				Externalization often takes simple constant values and
+				transforms them to constant values of a different type.
+				An example would be storing a <classname>boolean</classname> 
+				field as a <classname>char</classname>, where <literal>true
+				</literal> and <literal>false</literal> would be stored
+				in the database as <literal>'T'</literal> and 
+				<literal>'F'</literal> respectively.
+				</para>
+            <para>
+				OpenJPA allows you to define these simple translations in 
+				metadata, so that the field behaves as in
+				<link linkend="ref_guide_pc_extern">full-fledged 
+				externalization</link> without requiring 
+				externalizer and factory methods.  External values supports
+				translation of pre-defined simple types 
+				(primitives, primitive wrappers, and Strings), to other
+				pre-defined simple values.
+				</para>
+            <para>
+				Use the
+				<phrase>
+				JPA 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html"><classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
+				annotation
+				</phrase>
+				
+				
+				to define external value translations.  The 
+				values are defined in a format similar to that of 
+				<link linkend="ref_guide_conf_plugins">configuration
+				plugins</link>, except that the value pairs represent Java and 
+				datastore values.  To convert the Java boolean
+				values of <literal>true</literal> and <literal>false</literal>
+				to the character values <literal>T</literal> and <literal>F
+				</literal>, for example, you would use the extension value: 
+				<literal>true=T,false=F</literal>.
+				</para>
+            <para>
+				If the type of the datastore value is different from 
+				the field's type, use the 
+				<phrase>
+				JPA <ulink url="../apidocs/org/apache/openjpa/persistence/Type.html"><classname>org.apache.openjpa.persistence.Type</classname></ulink> annotation
+				</phrase>
+				
+				
+				to define the datastore type.
+				</para>
+            <example id="externvalues_ex">
+              <title>Using External Values</title>
+              <para>
+					This example uses external value translation to transform
+					a string field to an integer in the database.
+					</para>
+              <programlisting format="linespecific">
+public class Magazine
+{
+    @ExternalValues({"SMALL=5", "MEDIUM=8", "LARGE=10"})
+    @Type(int.class)
+    private String sizeWidth;
+
+    ...
+}
+</programlisting>
+            </example>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_fetch">
+        <title>Fetch Groups</title>
+        <indexterm zone="ref_guide_fetch">
+          <primary>fetch groups</primary>
+        </indexterm>
+        <para>
+	Fetch groups are sets of fields that load together.  They can be used to
+	to pool together associated fields in order to provide performance 
+	improvements over standard data fetching.  Specifying fetch groups allows 
+	for tuning of lazy loading and eager fetching behavior.
+	</para>
+        <para>
+	The JPA Overview's <xref linkend="jpa_overview_meta_fetch"/> 
+	describes how to use JPA metadata annotations to control whether a field is
+	fetched eagerly or lazily.  Fetch groups add a dynamic aspect to this 
+	standard ability.  As you will see, OpenJPA's JPA extensions allow you can add
+	and remove fetch groups at runtime to vary the sets of fields that are 
+	eagerly loaded.
+	</para>
+        <section id="ref_guide_fetch_custom">
+          <title>Custom Fetch Groups</title>
+          <para>
+		OpenJPA places any field that is eagerly loaded according to the JPA 
+		metadata rules into the built-in <emphasis>default
+		</emphasis> fetch group.  The default fetch group is always active; 
+		you cannot remove it at runtime.  Thus fields in this group are
+		always loaded immediately when an object is fetched from the datastore.
+		</para>
+          <para>
+		A field can be a member of zero or one fetch groups, including the 
+		default fetch group. That is, fields in the default fetch group cannot 
+		be in an additional fetch group, and a field cannot declare itself a 
+		member of more than one fetch group.  So to place a field in a custom
+		fetch group, you must first exclude it from eager fetching in your
+		JPA metadata, if it does not already default to lazy loading.
+		</para>
+          <para>
+		When lazy-loading a field, OpenJPA checks to see 
+		if that field declares itself to be a member of a fetch group. If so, 
+		OpenJPA will load all fields in that fetch group.
+		</para>
+          <para>
+		Additionally, it is possible to configure a OpenJPA <classname>
+		EntityManager</classname> or <classname>Query</classname> to use a 
+		particular fetch group or set of fetch groups
+		when loading new objects, as described later in this chapter.
+		When this is the case, OpenJPA loads the default fetch group plus any 
+		fields in the specified set of additional fetch groups.
+		</para>
+          <para>
+		You create fetch groups with the 
+		<ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroup.html"><classname>org.apache.openjpa.persistence.FetchGroup</classname></ulink> annotation.
+		If your class only has one custom fetch group, you can place this 
+		annotation directly on the class declaration.  Otherwise, use the 
+		<ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroups.html"><classname>org.apache.openjpa.persistence.FetchGroups</classname></ulink> annotation 
+		to declare an array of individual <classname>FetchGroup</classname> 
+		values.  The <classname>FetchGroup</classname> annotation has the 
+		following properties:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the fetch group.  
+				Fetch group names are global, and are expected to be shared 
+				among classes.  For example, a shopping website may use a 
+				<emphasis>detail</emphasis> fetch group in each product class 
+				to efficiently load all the data needed to display a product's
+				"detail" page.  The website might also define a 
+				sparse <emphasis>list</emphasis> fetch group containing only 
+				the fields needed to display a table of products, as in a search
+				result.
+				</para>
+              <para>
+				The following names are reserved for use by OpenJPA:
+				<literal>default</literal>, <literal>values</literal>, 
+				<literal>all</literal>, <literal>none</literal>, and any name
+				beginning with <literal>jdo</literal>, <literal>ejb</literal>,
+				or <literal>openjpa</literal>.
+				</para>
+            </listitem>
+<!--
+			<listitem>
+				<para>
+				<literal>String[] fetchGroups</literal>: Other fetch groups 
+				whose fields to include in this group.
+				</para>
+			</listitem>
+			-->
+            <listitem>
+              <para><literal>FetchAttribute[] attributes</literal>: The set of
+				persistent fields or properties in the fetch group.
+				</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+		As you might expect, listing a 
+		<ulink url="../apidocs/org/apache/openjpa/persistence/FetchAttribute.html"><classname>org.apache.openjpa.persistence.FetchAttribute</classname></ulink>
+		within a <classname>FetchGroup</classname> includes the corresponding
+		persistent field or property in the fetch group.  Each <classname>
+		FetchAttribute</classname> has the following properties:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the persistent 
+				field or property to include in the fetch group.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>depth</literal>: If the attribute represents a 
+				relation, the depth to which to recurse.  The current fetch 
+				group will be applied to the related object when fetching it,
+				and so on until the depth is exhausted or the related object has
+				no relations in the current fetch group.  Under the 
+				default depth of 1, the related object will be fetched, but none
+				of its relations will be traversed, even if they are in
+				the current fetch group.  With a depth of 2, the related object 
+				will be fetched, and if it has any relations in the 
+				current fetch group, those will be fetched with a depth of 1.
+				A depth of 0 indicates that the recursion continues until the
+				graph is exhausted or a related object has no relations
+				in the current fetch group.
+				</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+		Thus, to create a <emphasis>detail</emphasis> fetch group consisting of
+		the <literal>publisher</literal> and <literal>articles</literal> 
+		relations, with the fetch group applied recursively to the related 
+		objects, use:
+		</para>
+          <example id="ref_guide_fetch_customgroups">
+            <title>Custom Fetch Group Metadata</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@FetchGroups({
+    @FetchGroup(name="detail", attributes={
+        @FetchAttribute(name="publisher" depth=0),
+        @FetchAttribute(name="articles" depth=0)
+    }),
+    ...
+})
+public class Magazine
+{
+   ...
+}
+</programlisting>
+          </example>
+          <note>
+            <para>
+			OpenJPA currently only supports a depth of 0 for fetch attributes.
+			This restriction will be lifted in a future release, along with the
+			restriction limiting each attribute to a single fetch group.
+			</para>
+          </note>
+        </section>
+        <section id="ref_guide_fetch_conf">
+          <title>Custom Fetch Group Configuration</title>
+          <indexterm zone="ref_guide_fetch_conf">
+            <primary>fetch groups</primary>
+            <secondary>custom configuration</secondary>
+          </indexterm>
+          <para><indexterm><primary>fetch groups</primary><secondary>FetchGroups</secondary></indexterm>
+		You can control the default set of fetch groups with the
+		<link linkend="openjpa.FetchGroups"><literal>openjpa.FetchGroups</literal></link> configuration property.  Set this property to a comma-separated
+		list of fetch group names.
+		</para>
+          <para>
+		In JPA, OpenJPA's <classname>OpenJPAEntityManager</classname> and 
+		<classname>OpenJPAQuery</classname> extensions to the standard 
+		<classname>EntityManager</classname> and <classname>Query</classname>
+		interfaces provide access to a 
+		<ulink url="../../api/openjpa/persistence/FetchPlan.html"><classname>org.apache.openjpa.persistence.FetchPlan</classname></ulink> 
+		object.  The <classname>FetchPlan</classname>  
+		maintains the set of active fetch groups.  It begins with the 
+		groups defined in the <literal>openjpa.FetchGroups</literal> property,
+		but allows you to add and remove groups for an individual 
+		<classname>EntityManager</classname> or <classname>Query</classname> 
+		through the methods below.
+		</para>
+          <programlisting format="linespecific">
+public FetchPlan addFetchGroup (String group);
+public FetchPlan addFetchGroups (String... groups);
+public FetchPlan addFetchGroups (Collection groups);
+public FetchPlan removeFetchGroup (String group);
+public FetchPlan removeFetchGroups (String... groups);
+public FetchPlan removeFetchGroups (Collection groups);
+public FetchPlan resetFetchGroups ();
+public Collection&lt;String&gt; getFetchGroups (); 
+public void clearFetchGroups ();
+</programlisting>
+          <para><xref linkend="ref_guide_runtime"/> details the <classname>
+		OpenJPAEntityManager</classname>, <classname>OpenJPAQuery</classname>, and
+		<classname>FetchPlan</classname> interfaces.
+		</para>
+          <example id="ref_guide_fetch_conf_query">
+            <title>Using the FetchPlan</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAQuery kq = OpenJPAPersistence.cast (em.createQuery (...));
+kq.getFetchPlan ().addFetchGroup ("detail");
+List results = kq.getResultList ();
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_fetch_single_field">
+          <title>Per-field Fetch Configuration</title>
+          <indexterm zone="ref_guide_fetch_single_field">
+            <primary>fetch groups</primary>
+            <secondary>single fields</secondary>
+          </indexterm>
+          <para>
+		In addition to controlling fetch configuration on a
+		per-fetch-group basis, you can configure OpenJPA to include 
+		particular fields in the current fetch configuration. This
+		allows you to add individual fields that are not in the default
+		fetch group or in any other currently-active fetch groups to the
+		set of fields that will be eagerly loaded from the
+		database. 
+		</para>
+          <para>
+		JPA <classname>FetchPlan</classname> methods:
+		</para>
+          <programlisting format="linespecific">
+public FetchPlan addField (String field);
+public FetchPlan addFields (String... fields);
+public FetchPlan addFields (Class cls, String... fields);
+public FetchPlan addFields (Collection fields);
+public FetchPlan addFields (Class cls, Collection fields);
+public FetchPlan removeField (String field);
+public FetchPlan removeFields (String... fields);
+public FetchPlan removeFields (Class cls, String... fields);
+public FetchPlan removeFields (Collection fields);
+public FetchPlan removeFields (Class cls, Collection fields);
+public Collection&lt;String&gt; getFields (); 
+public void clearFields ();
+</programlisting>
+          <para>
+		The methods that take only string arguments use the fully-qualified 
+		field name, such as <literal>org.mag.Magazine.publisher</literal>.  
+		Similarly, <methodname>getFields</methodname> returns the set of 
+		fully-qualified field names.  In all methods, the named field
+		must be defined in the class specified in the invocation, not a 
+		superclass.  So, if the field <literal>publisher</literal> is
+		defined in base class <classname>Publication</classname> rather than
+		subclass <classname>Magazine</classname>, you must
+		invoke <literal>addField (Publication.class, "publisher")</literal>
+		and not <literal>addField (Magazine.class, "publisher")</literal>. 
+		This is stricter than Java's default field-masking algorithms, which 
+		would allow the latter method behavior if <literal>Magazine</literal> 
+		did not also define a field called <literal>publisher</literal>.
+		</para>
+          <para>
+		In order to avoid the cost of reflection, OpenJPA does not perform
+		any validation of the field name / class name pairs that you put
+		into the fetch configuration. If you specify non-existent class /
+		field pairs, nothing adverse will happen, but you will receive
+		no notification of the fact that the specified configuration is
+		not being used.
+		</para>
+          <example id="ref_guide_fetch-conf_per_field">
+            <title>Adding an Eager Field</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+kem.getFetchPlan ().addField (Magazine.class, "publisher");
+Magazine mag = em.find (Magazine.class, magId);
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_fetch_impl">
+          <title>Implementation Notes</title>
+          <itemizedlist>
+            <listitem>
+              <para>
+				Even when a direct relation is not eagerly fetched, OpenJPA 
+				selects the foreign key columns and caches the values.  This
+				way when you do traverse the relation, OpenJPA can often find the
+				related object in its cache, or at least avoid joins when 
+				loading the related object from the database.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				The above implicit foreign key-selecting behavior does not 
+				always apply when the relation is in a subclass table.  If the
+				subclass table would not otherwise be joined into the select,
+				OpenJPA avoids the extra join just to select the foreign key 
+				values.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="ref_guide_perfpack_eager">
+        <title>Eager Fetching</title>
+        <indexterm zone="ref_guide_perfpack_eager">
+          <primary>eager fetching</primary>
+        </indexterm>
+        <indexterm>
+          <primary>persistent fields</primary>
+          <see>eager fetching</see>
+        </indexterm>
+        <indexterm zone="ref_guide_perfpack_eager">
+          <primary>fetch groups</primary>
+          <secondary>eager fetching</secondary>
+          <seealso>eager fetching</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>lazy loading</primary>
+          <seealso>eager fetching</seealso>
+          <seealso>fetch groups</seealso>
+        </indexterm>
+        <para>
+		Eager fetching is the ability to efficiently load subclass data and 
+		related objects along with the base instances being queried.  
+		Typically, OpenJPA has to make a trip to the database whenever a 
+		relation is loaded, or when you first access data that is mapped to a 
+		table other than the least-derived superclass table.  If you perform a 
+		query that returns 100 <classname>Person</classname> objects, and then 
+		you have to retrieve the <classname>Address</classname> for each 
+		person, OpenJPA may make as many as 101 queries (the initial 
+		query, plus one for the address of each person returned).  Or if some
+		of the <classname>Person</classname> instances turn out to be 
+		<classname>Employee</classname>s, where <classname>Employee</classname>
+		has additional data in its own joined table, OpenJPA once again might need
+		to make extra database trips to access the additional employee data.
+		With eager fetching, OpenJPA can reduce these cases to a single query.
+		</para>
+        
+        <para>
+		Eager fetching only affects relations in the fetch groups being loaded
+		(see <xref linkend="ref_guide_fetch"/>).  In
+		other words, relations that would not normally be loaded immediately
+		when retrieving an object or accessing a field are not affected by
+		eager fetching.  In our example above, the address of each person would
+		only be eagerly fetched if the query were configured to include the 
+		address field or its fetch group, or if the address were in the default
+		fetch group.  This allows you to control exactly which fields are 
+		eagerly fetched in different situations.  Similarly, queries that 
+		exclude subclasses aren't affected by eager subclass fetching, 
+		described below.
+		</para>
+        <para>
+		Eager fetching has three modes:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>none</literal>: No eager fetching is performed.
+				Related objects are always loaded in an independent select 
+				statement. No joined subclass data is loaded unless it is in
+				the table(s) for the base type being queried.  Unjoined subclass
+				data is loaded using separate select statements rather than
+				a SQL UNION operation.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>eager fetching</primary><secondary>join mode</secondary></indexterm><literal>join</literal>: In this mode, OpenJPA joins to to-one
+				relations in the configured fetch groups.  If OpenJPA is loading 
+				data for a single instance, then OpenJPA will also 
+				join to any collection field in the configured 
+				fetch groups.  When loading data for multiple instances, though,
+				(such as when executing a <classname>Query</classname>) OpenJPA 
+				will not join to collections by default. Instead, OpenJPA defaults
+				to <literal>parallel</literal> mode for collections, as
+				described below.  You can force OpenJPA use a join rather than
+				parallel mode for a collection field using the metadata 
+				extension described in <xref linkend="eager-fetch-mode"/>.
+				</para>
+            <para><indexterm><primary>outer joins</primary></indexterm>
+				Under <literal>join</literal> mode, OpenJPA uses a left outer join
+				(or inner join, if the relations' field metadata declares the
+				relation non-nullable) to select the 
+				related data along with the data for the target objects.
+				This process works recursively for to-one joins, so that if 
+				<classname>Person</classname> has an 
+				<classname>Address</classname>, and
+				<classname>Address</classname> has a 
+				<classname>TelephoneNumber</classname>, and the fetch groups
+				are configured correctly, OpenJPA might issue a single select that
+				joins across the tables for all three classes.  To-many joins
+				can not recursively spawn other to-many joins, but they can
+				spawn recursive to-one joins.
+				</para>
+            <para>
+				Under the <literal>join</literal> subclass fetch mode, subclass
+				data in joined tables is selected by outer joining to all 
+				possible subclass tables of the type being queried.  Unjoined
+				subclass data is selected with a SQL UNION where possible.
+				As you'll see below, subclass data fetching is configured 
+				separately from relation fetching, and can be disabled for 
+				specific classes.
+				</para>
+            <note>
+              <para>
+					Some databases may not support UNIONs or outer joins.  Also,
+					OpenJPA can not use outer joins if you have set the
+					<link linkend="openjpa.jdbc.DBDictionary"><literal>
+					DBDictionary</literal></link>'s <literal>JoinSyntax
+					</literal> to <literal>traditional</literal>.
+					See <xref linkend="ref_guide_dbsetup_sql92"/>.
+					</para>
+            </note>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>eager fetching</primary><secondary>parallel mode</secondary></indexterm><literal>parallel</literal>:  Under this mode, OpenJPA selects 
+				to-one relations and joined collections as outlined
+				in the <literal>join</literal> mode description above.  Unjoined
+				collection fields, however, are eagerly fetched using a 
+				separate select statement for each collection, executed in 
+				parallel with the select statement for the target objects.  
+				The parallel selects use the <literal>WHERE</literal> 
+				conditions from the primary select, but add their own joins to 
+				reach the related data.  Thus, if you perform a query that 
+				returns 100 <classname>Company</classname> objects, where each 
+				company has a list of <classname>Employee</classname> objects 
+				and <classname>Department</classname> objects, OpenJPA will make 
+				3 queries. The first will select the company objects, the second
+				will select the employees for those companies, and
+				the third will select the departments for the same companies.  
+				Just as for joins, this process can be
+				recursively applied to the objects in the relations being
+				eagerly fetched.  Continuing our example, if the 
+				<classname>Employee</classname> class
+				had a list of <classname>Projects</classname> in one of the
+				fetch groups being loaded, OpenJPA would execute a single 
+				additional select in parallel to load the projects of all 
+				employees of the matching companies.
+				</para>
+            <para>
+				Using an additional select to load each collection avoids
+				transferring more data than necessary from the database to
+				the application.  If eager joins were used instead of parallel
+				select statements, each collection added to the 
+				configured fetch groups would cause the amount of data being 
+				transferred to rise dangerously, to the point that you could 
+				easily overwhelm the network.
+				</para>
+            <para>
+				Polymorphic to-one relations to table-per-class mappings use
+				parallel eager fetching because proper joins are impossible. 
+				You can force other to-one relations to use parallel rather than
+				join mode eager fetching using the metadata extension described
+				in <xref linkend="eager-fetch-mode"/>.
+				</para>
+            <para>
+				Setting your subclass fetch mode to <literal>parallel</literal>
+				affects table-per-class and vertical inheritance hierarchies.
+				Under parallel mode, OpenJPA issues separate selects for each 
+				subclass in a table-per-class inheritance hierarchy, rather 
+				than UNIONing all subclass tables together as in join mode.
+				This applies to any operation on a table-per-class base class: 
+				query, by-id lookup, or relation traversal.  
+				</para>
+            <para>
+				When dealing with a vertically-mapped hierarchy, on the other
+				hand, parallel subclass fetch mode only applies to queries.
+				Rather than outer-joining to subclass tables, OpenJPA will issue 
+				the query separately for each subclass.  In all other 
+				situations, parallel subclass fetch mode acts just like join 
+				mode in regards to vertically-mapped subclasses. 
+				</para>
+            <para>
+				When OpenJPA knows that it is selecting for a single object only,
+				it never uses <literal>parallel</literal> mode, because the
+				additional selects can be made lazily just as efficiently.  
+				This mode only increases efficiency over <literal>join
+				</literal> mode when multiple objects with eager relations
+				are being loaded, or when multiple selects might be faster than
+				joining to all possible subclasses.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <section id="ref_guide_perfpack_eager_conf">
+          <title>Configuring Eager Fetching</title>
+          <indexterm zone="ref_guide_perfpack_eager_conf">
+            <primary>eager fetching</primary>
+            <secondary>configuration</secondary>
+          </indexterm>
+          <para><indexterm><primary>EagerFetchMode</primary></indexterm><indexterm><primary>SubclassFetchMode</primary></indexterm><indexterm><primary>eager fetching</primary><secondary>EagerFetchMode</secondary></indexterm><indexterm><primary>eager fetching</primary><secondary>SubclassFetchMode</secondary></indexterm>
+			You can control OpenJPA's default eager fetch mode through the
+			<link linkend="openjpa.jdbc.EagerFetchMode"><literal>
+			openjpa.jdbc.EagerFetchMode</literal></link> and 
+			<link linkend="openjpa.jdbc.SubclassFetchMode"><literal>openjpa.jdbc.SubclassFetchMode</literal></link> configuration 
+			properties.  Set each of these properties to one of the mode names 
+			described in the previous section: <literal>none, join, 
+			parallel</literal>.  If left unset, the eager fetch mode defaults 
+			to <literal>parallel</literal> and the subclass fetch mode defaults
+			to <literal>join</literal> These are generally the most robust and 
+			performant strategies.
+			</para>
+          <para>
+			You can easily override the default fetch modes at runtime for any
+			lookup or query through OpenJPA's fetch configuration APIs.  See 
+			<xref linkend="ref_guide_runtime"/> for details.
+			</para>
+          <example id="ref_guide_perfpack_eager_def">
+            <title>Setting the Default Eager Fetch Mode</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.EagerFetchMode" value="parallel"/&gt;
+&lt;property name="openjpa.jdbc.SubclassFetchMode" value="join"/&gt;
+</programlisting>
+          </example>
+          <example id="ref_guide_perfpack_eager_runtime">
+            <title>Setting the Eager Fetch Mode at Runtime</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+...
+
+Query q = em.createQuery ("select p from Person p where p.address.state = 'TX'");
+OpenJPAQuery kq = OpenJPAPersistence.cast (q);
+JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan ();
+fetch.setEagerFetchMode (JDBCFetchPlan.EAGER_PARALLEL);
+fetch.setSubclassFetchMode (JDBCFetchPlan.EAGER_JOIN);
+List results = q.getResultList ();
+</programlisting>
+          </example>
+          <para>
+			You can specify a default subclass fetch mode for an individual
+			class with the metadata extension described in 
+			<xref linkend="subclass-fetch-mode"/>.  	
+			Note, however, that you cannot "upgrade" the runtime fetch mode
+			with your class setting.  If the runtime fetch mode is 
+			<literal>none</literal>, no eager subclass data fetching will
+			take place, regardless of your metadata setting.
+			</para>
+          <para>
+			This applies to the eager fetch mode metadata extension as well 
+			(see <xref linkend="eager-fetch-mode"/>).
+			You can use this extension to disable eager fetching on a field or 
+			to declare that a collection would rather use joins than parallel 
+			selects or vice versa.  But an extension value of 
+			<literal>join</literal> won't cause any eager joining if the fetch 
+			configuration's setting is <literal>none</literal>.
+			</para>
+        </section>
+        <section id="ref_guide_perfpack_eager_consider">
+          <title>Eager Fetching Considerations and Limitations</title>
+          <para>
+			There are several important points that you should consider when
+			using eager fetching:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><indexterm><primary>eager fetching</primary><secondary>with large result sets</secondary></indexterm><indexterm><primary>large result sets</primary><secondary>interaction with eager fetching</secondary></indexterm>
+					When you are using <literal>parallel</literal> eager fetch
+					mode and you have large result sets enabled (see
+					<xref linkend="ref_guide_dbsetup_lrs"/>) or you place
+					a range on a query, OpenJPA performs the needed parallel 
+					selects on one page of results at a time.  For example, 
+					suppose your <literal>FetchBatchSize</literal> is set to
+					20, and you perform a large result set
+					query on a class that has collection fields in the
+					configured fetch groups.  OpenJPA will immediately cache
+					the first <literal>20</literal> results of the query using
+					<literal>join</literal> mode eager fetching only.  Then,
+					it will issue the extra selects needed to eager fetch
+					your collection fields according to <literal>parallel
+					</literal> mode.  Each select will use a SQL
+					<literal>IN</literal> clause (or multiple <literal>OR
+					</literal> clauses if your class has a compound primary key)
+					to limit the selected collection elements to those owned
+					by the 20 cached results.
+					</para>
+              <para>
+					Once you iterate past the first 20 results, OpenJPA will
+					cache the next 20 and again issue any needed extra selects
+					for collection fields, and so on.  This pattern ensures that
+					you get the benefits of eager fetching without bringing
+					more data into memory than anticipated.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Eager fetching can sometimes be <emphasis>less</emphasis> 
+					efficient than standard fetching when circular relations 
+					are included in the configured fetch groups.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Once OpenJPA eager-joins into a class, it cannot issue any
+					further eager to-many joins or parallel selects from that 
+					class in the same query.  To-one joins, however, can 
+					recurse to any level.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Using a to-many join makes it impossible to determine the 
+					number of instances the result set contains without 
+					traversing the entire set.  This is because each result
+					object might be represented by multiple rows.  Thus, queries
+					with a range specification or queries configured for lazy
+					result set traversal automatically turn off eager to-many
+					joining.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					OpenJPA cannot eagerly join to polymorphic relations to 
+					non-leaf classes in a table-per-class inheritance hierarchy.
+					You can work around this restriction using the mapping 
+					extensions described in <xref linkend="nonpolymorphic"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="ref_guide_lock_groups">
+        <title>Lock Groups</title>
+        <indexterm zone="ref_guide_lock_groups">
+          <primary>locking</primary>
+          <secondary>lock groups</secondary>
+        </indexterm>
+        <indexterm zone="ref_guide_lock_groups">
+          <primary>lock groups</primary>
+          <seealso>locking</seealso>
+        </indexterm>
+        <para>
+	OpenJPA supports both optimistic and datastore locking strategies, but 
+	optimistic locking is the preferred approach in most applications.
+	Typically, optimistic locking is performed at the object level of 
+	granularity. That is, changes to any part of the same object in concurrent 
+	transactions will result in an optimistic locking exception being thrown 
+	by the transaction that commits last. In many applications, this is
+	acceptable. However, if your application has a high likelihood of
+	concurrent writes to different parts of the same object, then it may
+	be advantageous to use a finer-grained optimistic
+	lock. Additionally, certain parts of an object model may be best
+	modeled without any locking at all, or with a last-commit-wins
+	strategy. It is for these types of situations that OpenJPA offers
+	customizable optimistic lock groups, which allow you to achieve
+	sub-object-level locking granularity.
+	</para>
+        
+        <para>
+	For example, an <classname>Employee</classname> class may have some fields 
+	configurable by the employee the object represents (<literal>
+	firstName</literal>, <literal>lastName</literal>, <literal>
+	phoneNumber</literal>), some that are only modifiable by that employee's
+	manager (<literal>salary</literal>, <literal>title</literal>), and some in 
+	which concurrent updates are acceptable (a list of <literal>
+	projects</literal>). In such a model, you can greatly
+	improve the success of concurrent updates in optimistic transactions
+	by putting <literal>firstName</literal>, <literal>lastName</literal>, and 
+	<literal>phoneNumber</literal> into one lock group, 
+	<literal>salary</literal> and <literal>title</literal> into another, and 
+	excluding the <literal>projects</literal> field from optimistic lock 
+	checks altogether.
+	</para>
+        <para><phrase>
+	You specify a field's lock group in JPA metadata with the 
+	<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroup.html"><classname>org.apache.openjpa.persistence.LockGroup</classname></ulink> annotation.
+	</phrase>
+	
+	See <xref linkend="lock-group"/> for details on lock group metadata. 
+	</para>
+        <example id="ref_guide_lock_groups_metadata">
+          <title>Lock Group Metadata</title>
+          <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Employee
+{
+    // default lock group
+    private String firstName;
+    private String lastName;
+    private String phoneNumber;
+
+    // named lock group
+    @LockGroup("corporate") private float  salary;
+    @LockGroup("corporate") private String title;
+
+    // no lock group; allow concurrent modifications
+    @LockGroup(LockGroup.NONE) private Set&lt;Project&gt; projects;
+
+    ...
+}
+</programlisting>
+        </example>
+        <para>
+	Currently, lock groups are only supported when using number and 
+	timestamp version strategies.  They are not supported in the 
+	state-comparison strategy, though you can still exclude 
+	fields from participating in optimistic versioning under this strategy 
+	by setting the their lock group to <literal>none</literal>.  
+	</para>
+        <section id="ref_guide_lock_groups_and_subclasses">
+          <title>Lock Groups and Subclasses</title>
+          <indexterm zone="ref_guide_lock_groups_and_subclasses">
+            <primary>lock groups</primary>
+            <secondary>subclasses</secondary>
+          </indexterm>
+          <para>
+		Due to mapping restrictions, subclasses cannot simply declare 
+		additional lock groups implicitly, as is done in the example shown 
+		above. Instead, the least-derived mapped type in the persistent 
+		hierarchy must list all lock groups that its children can use via the 
+		<phrase><ulink url="../apidocs/org/apache/openjpa/persistence/LockGroups.html"><classname>
+		org.apache.openjpa.persistence.LockGroups</classname></ulink> annotation
+		</phrase>
+		
+		
+		For example, if the <classname>Employee</classname>
+		class in the last example extended <classname>Person</classname>, the
+		metadata would have looked like so:
+		</para>
+          <example id="ref_guide_lock_groups_and_subclasses_metadata">
+            <title>Lock Group Metadata</title>
+<!-- ### EJBDOC -->
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@LockGroups({"corporate"})
+public class Person
+{
+    // default lock group
+    private String firstName;
+    private String lastName;
+    private String phoneNumber;
+
+    ...
+}
+
+@Entity
+public class Employee
+    extends Person
+{
+    // named lock group
+    @LockGroup("corporate") private float  salary;
+    @LockGroup("corporate") private String title;
+
+    // no lock group; allow concurrent modifications
+    @LockGroup(LockGroup.NONE) private Set&lt;Project&gt; projects;
+
+    ...
+}
+</programlisting>
+            <programlisting format="linespecific">
+public class Person
+{
+    private String firstName;
+    private String lastName;
+    private String phoneNumber;
+
+    ...
+}
+
+
+public class Employee
+    extends Person
+{
+    // these fields can only be set by the employee's manager
+    private float  salary;
+    private String title;
+
+    // this field might be updated concurrently by the employee,
+    // other team members, or the employee's manager
+    private Set projects;
+
+    ...
+}
+
+
+&lt;?xml version="1.0"?&gt;
+&lt;jdo&gt;
+  &lt;package name=""&gt;
+    &lt;class name="Person"&gt;
+      &lt;!-- here we list the lock groups that will be used by Employee --&gt;
+      &lt;extension vendor-name="openjpa" key="lock-groups" value="corporate"/&gt;
+    &lt;/class&gt;
+    &lt;class name="Employee"&gt;
+      &lt;!-- named lock group --&gt;
+      &lt;field name="salary"&gt;
+        &lt;extension vendor-name="openjpa" key="lock-group" value="corporate"/&gt;
+      &lt;/field&gt;
+      &lt;field name="title"&gt;
+        &lt;extension vendor-name="openjpa" key="lock-group" value="corporate"/&gt;
+      &lt;/field&gt;
+      &lt;!-- no lock group; allow concurrent modifications --&gt;
+      &lt;field name="projects"&gt;
+        &lt;collection element-type="Project"/&gt;
+        &lt;extension vendor-name="openjpa" key="lock-group" value="none"/&gt;
+      &lt;/field&gt;
+    &lt;/class&gt;
+  &lt;/package&gt;
+&lt;/jdo&gt;
+</programlisting>
+          </example>
+          <para>
+		The exceptions to this rule are the <literal>none</literal> and 
+		<literal>default</literal> built-in lock groups. They can be used
+		at any point in the inheritance hierarchy without pre-declaration.
+		Additionally, the lock groups listing can contain
+		lock groups that would otherwise be implicitly defined in the 
+		least-derived type metadata.
+		</para>
+        </section>
+        <section id="ref_guide_lock_group_mapping">
+          <title>Lock Group Mapping</title>
+          <indexterm zone="ref_guide_lock_group_mapping">
+            <primary>lock groups</primary>
+            <secondary>mapping metadata</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_lock_group_mapping">
+            <primary>mapping metadata</primary>
+            <secondary>version</secondary>
+            <tertiary>lock group mapping</tertiary>
+            <seealso>lock groups</seealso>
+          </indexterm>
+          <para>
+		When using custom lock groups with a relational database,
+		OpenJPA will need a version column for each of the groups, instead of
+		just one version column.  This means that you must use surrogate
+		versioning; you cannot use a version field.  OpenJPA also currently 
+		requires that all the version columns for a given object be in the 
+		same table. Finally, it is only possible to use a single version 
+		strategy for a given object.  That is, you cannot have one version 
+		number column and another timestamp version column.
+		</para>
+          <para>
+            <phrase>
+		Use the 
+		<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionColumn.html"><classname>org.apache.openjpa.persistence.jdbc.VersionColumn(s)</classname></ulink>
+		annotation to specify the version column for each lock group in JPA 
+		mapping.
+		</phrase>
+          </para>
+          <example id="ref_guide_lock_groups_mapping_ex">
+            <title>Mapping Lock Groups</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+@Table(name="EMP")
+@VersionColumns({
+    @VersionColumn(name="VERS_CORP" lockGroup="corporate"),
+    @VersionColumn(name="VERS")
+})
+public class Employee
+{
+    ...
+}
+</programlisting>
+          </example>
+        </section>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_meta">
+      <title>Metadata</title>
+      <para>
+	The JPA Overview covers JPA metadata in 
+	<xref linkend="jpa_overview_meta"/>.
+	This chapter discusses OpenJPA's extensions to standard JPA metadata.
+	</para>
+      <section id="ref_guide_meta_factory">
+        <title>Metadata Factory</title>
+        <indexterm zone="ref_guide_meta_factory">
+          <primary>metadata</primary>
+          <secondary>loading and storing</secondary>
+          <see>MetaDataFactory</see>
+        </indexterm>
+        <para>
+		The <link linkend="openjpa.MetaDataFactory"><literal>openjpa.MetaDataFactory
+		</literal></link> configuration property controls metadata loading and
+		storing.  This property takes a plugin string (see 
+		<xref linkend="ref_guide_conf_plugins"/>) describing
+		a concrete <ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html"><classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink> implementation.
+		A metadata factory can load mapping information as well as persistence 
+		metadata, or it can leave mapping information to a separate 
+		<emphasis>mapping factory</emphasis> (see 
+		<xref linkend="ref_guide_mapping_factory"/>).  
+		OpenJPA recognizes the following built-in metadata factories:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>jpa</literal>: Standard JPA metadata.  
+				This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html"><classname>
+				org.apache.openjpa.persistence.PersistenceMetaDataFactory</classname></ulink>.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The standard metadata factories all accept the following properties for
+		locating persistent classes.  Each property represents a different 
+		mechanism for locating persistent types; you can choose the mechanism or
+		combination of mechanisms that are most convenient.  See 
+		<xref linkend="ref_guide_pc_pcclasses"/> for a discussion of when it
+		is necessary to list your persistent classes. 
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>Types</literal>: A semicolon-separated list of 
+				fully-qualified persistent class names.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>Resources</literal>: A semicolon-separated list of
+				resource paths to metadata files or jar archives.  
+				Each jar archive will be scanned for 
+				<phrase>annotated JPA entities</phrase>
+				
+				
+				.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>URLs</literal>: A semicolon-separated list of URLs
+				of metadata files or jar archives.  
+				Each jar archive will be scanned for 
+				<phrase>annotated JPA entities</phrase>
+				
+				
+				.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>ClasspathScan</literal>: A semicolon-separated list of
+				directories or jar archives listed in your classpath.
+				Each directory and jar archive will be scanned for 
+				<phrase>annotated JPA entities</phrase>
+				
+				
+				.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_meta_stdfactoryex">
+          <title>Setting a Standard Metadata Factory</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.MetaDataFactory" value="jpa"/&gt;
+</programlisting>
+        </example>
+        <example id="ref_guide_meta_customfactoryex">
+          <title>Setting a Custom Metadata Factory</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.MetaDataFactory" value="com.xyz.CustomMetaDataFactory"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_meta_ejb">
+        <title>Additional JPA Metadata</title>
+        <indexterm zone="ref_guide_meta_ejb">
+          <primary>metadata</primary>
+          <secondary>JPA additions</secondary>
+        </indexterm>
+        <para>
+		This section describes OpenJPA's core additions to standard entity
+		metadata.  We present the object-relational mapping syntax to
+		support these additions in <xref linkend="ref_guide_mapping_ejb"/>.
+		Finally, <xref linkend="ref_guide_meta_ext"/> covers additional 
+		extensions to  JPA metadata that allow you to access auxiliary
+		OpenJPA features.
+		</para>
+        <section id="ref_guide_meta_ejb_datastoreid">
+          <title>Datastore Identity</title>
+          <indexterm zone="ref_guide_meta_ejb_datastoreid">
+            <primary>identity</primary>
+            <secondary>datastore</secondary>
+          </indexterm>
+          <para>
+			JPA typically requires you to declare one or more
+			<literal>Id</literal> fields to act as primary keys.  OpenJPA, however,
+			can create and maintain a surrogate primary key value when you do
+			not declare any <literal>Id</literal> fields.  This form of 
+			persistent identity is called <emphasis>datastore 
+			identity</emphasis>.  <xref linkend="ref_guide_pc_oid"/> discusses 
+			OpenJPA's support for datastore identity in JPA.  We
+			cover how to map your datastore identity primary key column in
+			<xref linkend="ref_guide_mapping_ejb_datastoreid"/>
+			</para>
+        </section>
+        <section id="ref_guide_meta_ejb_version">
+          <title>Surrogate Version</title>
+          <indexterm zone="ref_guide_meta_ejb_version">
+            <primary>version</primary>
+            <secondary>surrogate</secondary>
+          </indexterm>
+          <para>
+			Just as OpenJPA can maintain your entity's identity without any
+			<literal>Id</literal> fields, OpenJPA can maintain your entity's
+			optimistic version without any <literal>Version</literal> fields.
+			<xref linkend="ref_guide_mapping_ejb_version"/> shows you how
+			to map surrogate version columns.
+			</para>
+        </section>
+        <section id="ref_guide_meta_ejb_persistent">
+          <title>Persistent Field Values</title>
+          <indexterm zone="ref_guide_meta_ejb_persistent">
+            <primary>persistent fields</primary>
+          </indexterm>
+          <para>
+			JPA defines <literal>Basic</literal>,
+			<literal>Lob</literal>, <literal>Embedded</literal>, 
+			<literal>ManyToOne</literal>, and <literal>OneToOne</literal> 
+			persistence strategies for direct field values.  OpenJPA supports all 
+			of these standard strategies, but adds one of its own: 
+			<literal>Persistent</literal>.  The 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/Persistent.html"><classname>org.apache.openjpa.persistence.Persistent</classname></ulink> metadata
+			annotation can represent any direct field value, including
+			custom types.  It has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					field eagerly or lazily.  Corresponds exactly to the
+					same-named property of standard JPA annotations
+					such as <link linkend="jpa_overview_meta_basic"><classname>
+					Basic</classname></link>. Defaults to
+					<literal>FetchType.EAGER</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+					values defining cascade behavior for this field.  
+					Corresponds exactly to the same-named property of standard
+					JPA annotations such as 
+					<link linkend="jpa_overview_meta_manytoone"><classname>
+					ManyToOne</classname></link>. Defaults to empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the field in the
+					related entity that maps this bidirectional relation.
+					Corresponds to the same-named property of standard JPA 
+					annotations such as 
+					<link linkend="jpa_overview_meta_onetoone"><classname>
+					OneToOne</classname></link>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>: Whether the value can
+					be null.  Corresponds to the same-named property of standard
+					JPA annotations such as 
+					<link linkend="jpa_overview_meta_manytoone"><classname>
+					ManyToOne</classname></link>, but can apply to non-entity
+					object values as well. Defaults to <literal>true</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean embedded</literal>: Set this property to
+					<literal>true</literal> if the field value is stored as
+					an embedded object.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			Though you can use the <classname>Persistent</classname> annotation
+			in place of most of the standard direct field annotations mentioned
+			above, we recommend primarily using it for non-standard and custom
+			types for which no standard JPA annotation exists.  For example,
+			<xref linkend="ref_guide_mapping_ejb_columns"/> demonstrates the
+			use of the <classname>Persistent</classname> annotation to denote
+			a persistent <classname>java.awt.Point</classname> field.
+			</para>
+        </section>
+        <section id="ref_guide_meta_ejb_persistent_coll">
+          <title>Persistent Collection Fields</title>
+          <indexterm zone="ref_guide_meta_ejb_persistent_coll">
+            <primary>persistent fields</primary>
+            <secondary>collection metadata</secondary>
+          </indexterm>
+          <para>
+			JPA standardizes support for collections of entities with the
+			<literal>OneToMany</literal> and <literal>ManyToMany</literal>
+			persistence strategies.  OpenJPA expands collection support to handle
+			collections of simple types (primitive wrappers, 
+			<classname>String</classname>s, etc), custom types, and embedded 
+			objects.
+			</para>
+          <para>
+			The
+			<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentCollection.html"><classname>org.apache.openjpa.persistence.PersistentCollection</classname></ulink>
+			metadata annotation represents a persistent collection field.
+			It has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class elementType</literal>: The class of the
+					collection elements.  This information is usually taken 
+					from the parameterized collection element type.  You must 
+					supply it explicitly, however, if your field isn't a 
+					parameterized type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					collection eagerly or lazily.  Corresponds exactly to the
+					same-named property of standard JPA annotations
+					such as <link linkend="jpa_overview_meta_basic"><classname>
+					Basic</classname></link>. Defaults to
+					<literal>FetchType.LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the field in the
+					related entity that maps this bidirectional relation.
+					Corresponds to the same-named property of standard JPA 
+					annotations such as 
+					<link linkend="jpa_overview_meta_manytomany"><classname>
+					ManyToMany</classname></link>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] elementCascade</literal>: Array of 
+					enum values defining cascade behavior for the collection 
+					elements.  Corresponds exactly to the <literal>cascade
+					</literal> property of standard JPA annotations
+					such as <link linkend="jpa_overview_meta_manytomany"><classname>ManyToMany</classname></link>. Defaults to 
+					empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean elementEmbedded</literal>: Set this
+					property to <literal>true</literal> if the elements are
+					stored as embedded objects.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para><xref linkend="ref_guide_mapping_ejb_coll"/> contains several 
+			examples of using <classname>PersistentCollection</classname> to 
+			mark non-standard collection fields persistent.
+			</para>
+        </section>
+        <section id="ref_guide_meta_ejb_persistent_map">
+          <title>Persistent Map Fields</title>
+          <indexterm zone="ref_guide_meta_ejb_persistent_map">
+            <primary>persistent fields</primary>
+            <secondary>map metadata</secondary>
+          </indexterm>
+          <para>
+			JPA has limited support for maps.  OpenJPA introduces the 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentMap.html"><classname>org.apache.openjpa.persistence.PersistentMap</classname></ulink>
+			metadata annotation to represent a persistent map field.
+			It has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class keyType</literal>: The class of the
+					map keys.  This information is usually taken 
+					from the parameterized map key type.  You must 
+					supply it explicitly, however, if your field isn't a 
+					parameterized type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>Class elementType</literal>: The class of the
+					map values.  This information is usually taken 
+					from the parameterized map value type.  You must 
+					supply it explicitly, however, if your field isn't a 
+					parameterized type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+					collection eagerly or lazily.  Corresponds exactly to the
+					same-named property of standard JPA annotations
+					such as <link linkend="jpa_overview_meta_basic"><classname>
+					Basic</classname></link>. Defaults to
+					<literal>FetchType.LAZY</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] keyCascade</literal>: Array of 
+					enum values defining cascade behavior for the map 
+					keys.  Corresponds exactly to the <literal>cascade
+					</literal> property of standard JPA annotations
+					such as <link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname></link>. Defaults to 
+					empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] elementCascade</literal>: Array of 
+					enum values defining cascade behavior for the map 
+					values.  Corresponds exactly to the <literal>cascade
+					</literal> property of standard JPA annotations
+					such as <link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname></link>. Defaults to 
+					empty array.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean keyEmbedded</literal>: Set this
+					property to <literal>true</literal> if the map keys are
+					stored as embedded objects.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean elementEmbedded</literal>: Set this
+					property to <literal>true</literal> if the map values are
+					stored as embedded objects.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			Map keys and values in OpenJPA can be entities, simple types
+			(primitive wrappers, <classname>String</classname>s, etc),
+			custom types, or embedded objects.
+			<xref linkend="ref_guide_mapping_ejb_map"/> contains several 
+			examples of using <classname>PersistentMap</classname> to annotate 
+			persistent map fields.
+			</para>
+        </section>
+      </section>
+      <section id="ref_guide_meta_ext">
+        <title>Metadata Extensions</title>
+        <indexterm zone="ref_guide_meta_ext">
+          <primary>metadata</primary>
+          <secondary>extensions</secondary>
+        </indexterm>
+        <para>
+		OpenJPA extends standard metadata to allow you to access advanced OpenJPA 
+		functionality. This section covers persistence metadata extensions; we 
+		discuss mapping metadata extensions in 
+		<xref linkend="ref_guide_mapping_ext"/>. 
+		All metadata extensions are optional; OpenJPA will rely on its defaults
+		when no explicit data is provided.
+		</para>
+        <section id="ref_guide_meta_class">
+          <title>Class Extensions</title>
+          <para>
+			OpenJPA recognizes the following class extensions:
+			</para>
+          <section id="fetch-groups">
+            <title>Fetch Groups</title>
+            <indexterm zone="data-cache">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>fetch groups</tertiary>
+              <seealso>fetch groups</seealso>
+            </indexterm>
+            <para>
+				
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroups.html"><classname>org.apache.openjpa.persistence.FetchGroups</classname></ulink>
+				and <ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroup.html"><classname>org.apache.openjpa.persistence.FetchGroup</classname></ulink>
+				annotations allow you to define fetch groups in your JPA 
+				entities.  <xref linkend="ref_guide_fetch"/> discusses OpenJPA's 
+				support for fetch groups in general; see 
+				<xref linkend="ref_guide_fetch_custom"/> for how to use these
+				annotations in particular.
+				</para>
+          </section>
+          <section id="data-cache">
+            <title>Data Cache</title>
+            <indexterm zone="data-cache">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>data cache</tertiary>
+              <seealso>caching</seealso>
+            </indexterm>
+            <para><xref linkend="ref_guide_cache"/> examines caching in OpenJPA.	
+				Metadata extensions allow individual classes to override 
+				system caching defaults.
+				</para>
+            <para>
+				OpenJPA JPA defines the 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/DataCache.html"><classname>org.apache.openjpa.persistence.DataCache</classname></ulink>
+				annotation for caching information.  This annotation has the
+				following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>boolean enabled</literal>: Whether to cache
+						data for instances of the class.  Defaults to
+						<literal>true</literal> for base classes, or the
+						superclass value for subclasses.  If you set this 
+						property to <literal>false</literal>, all other 
+						properties are ignored.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>String name</literal>: Place data for instances
+						of the class in a named cache.  By default, instance 
+						data is placed in the same cache as superclass data, or
+						the default cache configured through
+						the <link linkend="openjpa.DataCache"><literal>
+						openjpa.DataCache</literal></link> configuration property
+						for base classes.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>int timeout</literal>: The number of 
+						milliseconds data for the class remains valid.  Use
+						-1 for no timeout.  Defaults to the
+						<link linkend="openjpa.DataCacheTimeout"><literal>
+						openjpa.DataCacheTimeout</literal></link> property value.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				The <literal>data-cache</literal> key accepts the 
+				following values:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>true</literal>: Use the default cache, as
+						configured by the <link linkend="openjpa.DataCache"><literal>openjpa.DataCache</literal></link> configuration 
+						property. This is the default when no extension is 
+						given, unless a superclass names a different cache.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>false</literal>: Data for instances of this 
+						class should not be cached.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>&lt;cache-name&gt;</literal>:  Place data for
+						instances of this class into the cache with name 
+						<literal>&lt;cache-name&gt;</literal>.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="detached-state-field">
+            <title>Detached State</title>
+            <indexterm zone="detached-state-field">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>detached state field</tertiary>
+              <seealso>detachment</seealso>
+            </indexterm>
+            <para>
+				The OpenJPA <link linkend="ref_guide_pc_enhance">enhancer</link> 
+				may add a synthetic field to detachable classes to hold detached
+				state (see <xref linkend="ref_guide_detach_graph"/> 
+				for details).  You can instead declare your own detached state 
+				field or supress the creation of a detached state field 
+				altogether.  In the latter case, your class must not use 
+				<link linkend="ref_guide_pc_oid">datastore identity</link>,
+				and should declare a version field to detect optimistic 
+				concurrency errors during detached modifications.
+				</para>
+            <para>
+				OpenJPA JPA defines the 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/DetachedState.html"><classname>org.apache.openjpa.persistence.DetachedState</classname></ulink> annotation for controlling detached state.  When used
+				to annotate a class, <classname>DetachedState</classname>
+				recognizes the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>boolean enabled</literal>: Set to false to
+						suppress the use of detached state.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>String fieldName</literal>: Use this property 
+						to declare your own detached state field.  The field
+						must be of type <classname>Object</classname>.  
+						Typically this property is only used if the field is
+						inherited from a non-persisted superclass.  If the field
+						is declared in your entity class, you will typically
+						annotate the field directly, as described below.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				If you declare your own detached state field, you can annotate
+				that field with <classname>DetachedState</classname> directly,
+				rather than placing the annotation at the class level and using
+				the <literal>fieldName</literal> property.  When placed on a
+				field, <classname>DetachedState</classname> acts as a marker 
+				annotation; it does not recognize any properties.  Your 
+				annotated field must be of type <classname>Object</classname>.
+				</para>
+          </section>
+          <section id="lock-groups">
+            <title>Lock Groups</title>
+            <para>
+				OpenJPA requires you to pre-declare subclass lock groups in the
+				least-derived mapped class.  
+				<phrase>
+				The JPA 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroups.html"><classname>org.apache.openjpa.persistence.LockGroups</classname></ulink>
+				annotation accepts an array of lock group names.
+				</phrase>
+				
+				For details on lock groups, see 
+				<xref linkend="ref_guide_lock_groups_and_subclasses"/>.
+				</para>
+          </section>
+          <section id="auditable">
+            <title>Auditable</title>
+            <para>
+				Reserved for future use.
+				</para>
+          </section>
+        </section>
+        <section id="ref_guide_meta_field">
+          <title>Field Extensions</title>
+          <para>
+			OpenJPA recognizes the following field extensions:
+			</para>
+          <section id="dependent">
+            <title>Dependent</title>
+            <indexterm zone="data-cache">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>dependent</tertiary>
+            </indexterm>
+            <para>
+				In a <emphasis>dependent</emphasis> relation, the referenced
+				object is deleted whenever the owning object is deleted, or 
+				whenever the relation is severed by nulling or resetting the 
+				owning field.  For example, if the 
+				<literal>Magazine.coverArticle</literal> field is marked 
+				dependent, then setting <literal>Magazine.coverArticle</literal>
+				to a new <classname>Article</classname> instance will 
+				automatically delete the old <classname>Article</classname> 
+				stored in the field.  Similarly, deleting a <classname>Magazine
+				</classname> object will automatically delete its current cover
+				<classname>Article</classname>.
+				You can prevent an orphaned dependent object from being deleted
+				by assigning it to another relation in the same transaction.
+				</para>
+            <para>
+				
+				OpenJPA JPA offers a family of marker annotations to
+				denote dependent relations in JPA entities:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><ulink url="../apidocs/org/apache/openjpa/persistence/Dependent.html"><classname>
+						org.apache.openjpa.persistence.Dependent</classname></ulink>: Marks
+						a direct relation as dependent.
+						</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../apidocs/org/apache/openjpa/persistence/ElementDependent.html"><classname>
+						org.apache.openjpa.persistence.ElementDependent</classname></ulink>: 
+						Marks the entity elements of a collection, array, or 
+						map field as dependent.
+						</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../apidocs/org/apache/openjpa/persistence/KeyDependent.html"><classname>
+						org.apache.openjpa.persistence.KeyDependent</classname></ulink>: 
+						Marks the key entities in a map field as dependent.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="lrs">
+            <title>LRS</title>
+            <indexterm zone="lrs">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>lrs</tertiary>
+              <seealso>large result sets</seealso>
+            </indexterm>
+            <para>
+				This boolean extension, denoted by 
+				<phrase>
+				the JPA <ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname>org.apache.openjpa.persistence.LRS</classname></ulink> annotation,
+				</phrase>
+				
+				
+				indicates that a field should use 
+				OpenJPA's special large result set collection or map proxies.  
+				A complete description of large result set proxies is 
+				available in <xref linkend="ref_guide_pc_scos_proxy_lrs"/>.
+				</para>
+          </section>
+          <section id="order-by">
+            <title>Order-By</title>
+            <indexterm zone="order-by">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>order-by</tertiary>
+            </indexterm>
+            <para><phrase>
+				The JPA Overview's 
+				<xref linkend="jpa_overview_meta_orderby"/> describes JPA's 
+				<literal>OrderBy</literal> annotation for loading the elements
+				of collection fields in a prescribed order.
+				</phrase>
+				
+				
+				
+				Ordering syntax is as follows:
+				</para>
+            <programlisting format="linespecific">
+#element|&lt;field name&gt;[ asc|ascending|desc|descending][, ...]
+</programlisting>
+            <para>
+				The token <literal>#element</literal> represents the element
+				value.  Simple element types such as strings and primitive
+				wrappers are sorted based on their natural ordering.  If the
+				collection holds persistent objects, its elements are sorted 
+				based on the natural ordering of the objects' primary key 
+				values.  By substituting a field name for the <literal>
+				#element</literal> token, you can order a collection of 
+				persistent objects by an arbitrary field in the related type,
+				rather than by primary key.
+				</para>
+            <para>
+				The field name or <literal>#element</literal> token may be
+				followed by the keywords <literal>asc/ascending</literal> or 
+				<literal>desc/descending</literal> in either all-upper or 
+				all-lower case to mandate ascending and descending order.
+				If the direction is omitted, OpenJPA defaults to ascending order.
+				</para>
+            <para>
+				Note that the defined ordering is only applied when the 
+				collection is loaded from the datastore.  It is not maintained
+				by OpenJPA as you modify the collection in memory.
+				</para>
+            <para>
+				The following ordering string orders a collection by its 
+				element values in descending order:
+				</para>
+            <programlisting format="linespecific">
+"#element desc"
+</programlisting>
+            <para>
+				The following ordering string orders a collection of 
+				<classname>Author</classname> objects by each author's last
+				name in ascending order.  If two last names are equal, the
+				authors are ordered by first name in ascending order.
+				</para>
+            <programlisting format="linespecific">
+"firstName, lastName"
+</programlisting>
+          </section>
+          <section id="inverse-logical">
+            <title>Inverse-Logical</title>
+            <indexterm zone="inverse-logical">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>inverse-logical</tertiary>
+              <seealso>bidirectional relations</seealso>
+            </indexterm>
+            <para>
+				This extension names the inverse field in a logical 
+				bidirectional relation.  
+				<phrase>
+				To create a logical bidrectional relation in OpenJPA JPA, use the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html"><classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink> 
+				annotation.
+				</phrase>
+				
+				We discuss logical bidirectional relations and this extension
+				in detail in <xref linkend="ref_guide_inverses"/>.
+				</para>
+          </section>
+          <section id="lock-group">
+            <title>Lock Group</title>
+            <indexterm zone="lock-group">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>lock group</tertiary>
+              <seealso>locking</seealso>
+            </indexterm>
+            <para>
+				Lock groups allow for fine-grained optimistic locking 
+				concurrency.  
+				Use
+				<phrase>
+				OpenJPA JPA's 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroup.html"><classname>org.apache.openjpa.persistence.LockGroup</classname></ulink>
+				annotation
+				</phrase>
+				
+				
+				to name the lock group for a field.  You can exclude a field 
+				from optimistic locking with a value of <literal>none</literal>.
+				We discuss lock groups and this extension further in 
+				<xref linkend="ref_guide_lock_groups"/>.
+				</para>
+          </section>
+          <section id="read-only">
+            <title>Read-Only</title>
+            <indexterm zone="read-only">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>read-only</tertiary>
+              <seealso>persistent fields</seealso>
+            </indexterm>
+            <indexterm zone="read-only">
+              <primary>persistent fields</primary>
+              <secondary>read only</secondary>
+            </indexterm>
+            <para>
+				The read-only extension makes a field unwritable.  The 
+				extension only applies to existing persistent objects; new 
+				object fields are always writeable.
+				</para>
+            <para>
+				To mark a field read-only in JPA metadata, set the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/ReadOnly.html"><classname>org.apache.openjpa.persistence.ReadOnly</classname></ulink>
+				annotation to a
+				<ulink url="../apidocs/org/apache/openjpa/persistence/UpdateAction.html"><classname>org.apache.openjpa.persistence.UpdateAction</classname></ulink>
+				enum value.  The <classname>UpdateAction</classname> enum
+				includes:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>UpdateAction.IGNORE</literal>: Updates to the 
+						field are completely ignored.  The field is not 
+						considered dirty.
+						The new value will not even get stored in the
+						OpenJPA <link linkend="ref_guide_cache">data cache</link>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>UpdateAction.RESTRICT</literal>: Any attempt 
+						to change the field will result in an immediate 
+						exception.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="type">
+            <title>Type</title>
+            <indexterm zone="type">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>type</tertiary>
+              <seealso>persistent fields</seealso>
+            </indexterm>
+            <para>
+				OpenJPA has three levels of support for relations:
+				</para>
+            <orderedlist>
+              <listitem>
+                <para>
+						Relations that hold a reference to an object of a 
+						concrete persistent class are supported by storing 
+						the primary key values of the related instance in 
+						the database.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						Relations that hold a reference to an object of an
+						unknown persistent class are supported by storing 
+						the stringified identity value of the related 
+						instance.  This level of support does not allow 
+						queries across the relation.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+						Relations that hold an unknown object or interface.
+						The only way to support these relations is to 
+						serialize their value to the database.  This does 
+						not allow you to query the field, and is not very 
+						efficient.
+						</para>
+              </listitem>
+            </orderedlist>
+            <para>
+				Clearly, when you declare a field's type to be another
+				persistence-capable class, OpenJPA uses level 1 support.  
+				By default, OpenJPA assumes that any interface-typed fields 
+				you declare will be implemented only by other persistent 
+				classes, and assigns interfaces level 2 support.  The exception
+				to this rule is the <classname>java.io.Serializable</classname> 
+				interface.  If you declare a field to be of type 
+				<classname>Serializable</classname>, OpenJPA lumps it
+				together with <classname>java.lang.Object</classname>
+				fields and other non-interface, unrecognized field types,
+				which are all assigned level 3 support.
+				</para>
+            <para>
+				With OpenJPA's type family of metadata extensions, you can 
+				control the level of support given to your 
+				unknown/interface-typed fields.  Setting the value of this 
+				extension to 
+				<phrase><classname>Entity</classname></phrase>
+				
+				
+				
+				indicates that the field value will always be some persistent 
+				object, and gives level 2 support.  Setting the value of this
+				extension to the class of a concrete persistent
+				type is even better; it gives you level 1 
+				support (just as if you had declared your field to be
+				of that type in the first place).  Setting this extension
+				to <classname>Object</classname> uses level 3 
+				support.  This is useful when you have an interface
+				relation that may <emphasis role="bold">not</emphasis> 
+				hold other persistent objects (recall that OpenJPA 
+				assumes interface fields will always hold persistent
+				instances by default).
+				</para>
+            <para>
+				This extension is also used with OpenJPA's externalization feature,
+				described in <xref linkend="ref_guide_pc_extern"/>.
+				</para>
+            <para>
+				OpenJPA JPA defines the following type annotations for field 
+				values, collection, array, and map elements, and map keys,
+				respectively:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/Type.html">
+                    <classname>org.apache.openjpa.persistence.Type</classname>
+                  </ulink>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/ElementType.html">
+                    <classname>org.apache.openjpa.persistence.ElementType
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/KeyType.html">
+                    <classname>org.apache.openjpa.persistence.KeyType
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="externalizer">
+            <title>Externalizer</title>
+            <indexterm zone="externalizer">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>externalizer</tertiary>
+              <seealso>externalization</seealso>
+            </indexterm>
+            <para>
+				The 
+				<phrase>
+				JPA 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html"><classname>org.apache.openjpa.persistence.Externalizer</classname></ulink>
+				annotation
+				</phrase>
+				
+				
+				names a method to transform a field value into a value of 
+				another type.  See <xref linkend="ref_guide_pc_extern"/>
+				for details.
+				</para>
+          </section>
+          <section id="factory">
+            <title>Factory</title>
+            <indexterm zone="factory">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>factory</tertiary>
+              <seealso>externalization</seealso>
+            </indexterm>
+            <para>
+				The 
+				<phrase>
+				JPA <ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>org.apache.openjpa.persistence.Factory</classname></ulink>
+				annotation
+				</phrase>
+				
+				
+				names a method to re-create a field value from its 
+				externalized form.  See <xref linkend="ref_guide_pc_extern"/> 
+				for details.
+				</para>
+          </section>
+          <section id="external-values">
+            <title>External Values</title>
+            <indexterm zone="factory">
+              <primary>metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>external values</tertiary>
+              <seealso>externalization</seealso>
+            </indexterm>
+            <para>
+				The 
+				<phrase>
+				JPA 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html"><classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
+				annotation
+				</phrase>
+				
+				
+				declares values for transformation of simple fields
+				to different constant values in the datastore.
+				See <xref linkend="ref_guide_pc_extern_values"/> for details.
+				</para>
+          </section>
+        </section>
+        <section id="ref_guide_meta_example">
+          <title>Example</title>
+          <para>
+			The following example shows you how to specify extensions in 
+			metadata.
+			</para>
+          <example id="ref_guide_metaex">
+            <title>OpenJPA Metadata Extensions</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@DataCache(enabled=false)
+public class Magazine
+{
+    @ManyToMany
+    @LRS
+    @LockGroup(LockGroup.NONE)
+    private Collection&lt;Subscriber&gt; subscribers;
+
+    @ExternalValues({"true=1", "false=2"})
+    @Type(int.class)
+    private boolean weekly;
+
+    @PersistentCollection
+    @OrderBy("#element DESC")
+    private List&lt;String&gt; subtitles;
+
+    ...
+}
+</programlisting>
+          </example>
+        </section>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_mapping">
+      <title>Mapping</title>
+      <indexterm zone="ref_guide_mapping">
+        <primary>mapping metadata</primary>
+      </indexterm>
+      <para>
+	The JPA Overview's <xref linkend="jpa_overview_mapping"/> 
+	explains object-relational mapping under JPA.  This chapter reviews the 
+	mapping utilities OpenJPA provides and examines OpenJPA features that go beyond 
+	the JPA specification.
+	</para>
+      <section id="ref_guide_mapping_mappingtool">
+        <title>Forward Mapping</title>
+        <indexterm zone="ref_guide_mapping_mappingtool">
+          <primary>forward mapping</primary>
+        </indexterm>
+        <indexterm zone="ref_guide_mapping_mappingtool">
+          <primary>mapping tool</primary>
+          <seealso>forward mapping</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>mapping metadata</primary>
+          <secondary>forward mapping</secondary>
+          <see>forward mapping</see>
+        </indexterm>
+        <para><emphasis>Forward mapping</emphasis> is the process of creating 
+		mappings and their corresponding database schema from your object 
+		model.  OpenJPA supports forward mapping through the <emphasis>mapping 
+		tool</emphasis>.  The next section presents several common mapping tool
+		use cases.  You can invoke the tool through the <literal>mappingtool
+		</literal> shell/batch script included in the OpenJPA distribution, 
+		or through its Java class,
+		<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingTool"><classname>
+		org.apache.openjpa.jdbc.meta.MappingTool</classname></ulink>.  
+		</para>
+        <note>
+          <para><xref linkend="ref_guide_integration_mappingtool"/> 
+			describes the mapping tool Ant task.
+			</para>
+        </note>
+        <example id="ref_guide_mapping_mappingtool_typical">
+          <title>Using the Mapping Tool</title>
+          <programlisting format="linespecific">
+mappingtool Magazine.java
+</programlisting>
+        </example>
+        <para>
+		In addition to the universal flags of the 
+		<link linkend="ref_guide_conf_devtools">configuration framework</link>, 
+		the mapping tool accepts the following command line arguments:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>-schemaAction/-sa &lt;add | refresh | drop | build 
+				| retain | none&gt;</literal>: The action to take on the 
+				schema.  These options correspond to the same-named actions on 
+				the schema tool described in 
+				<xref linkend="ref_guide_schema_schematool"/>.
+				Unless you are running the mapping tool on all of your 
+				persistent types at once or dropping a mapping, we strongly 
+				recommend you use the default <literal>add</literal> action or 
+				the <literal>build</literal> action.  Otherwise you may end up 
+				inadvertently dropping schema components that are used by 
+				classes you are not currently running the tool over.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-schemaFile/-sf &lt;stdout | output file&gt;</literal>:
+				Use this option to write the planned schema to an XML 
+				document rather than modify the database.  The document can
+				then be manipulated and committed to the database with the
+				<link linkend="ref_guide_schema_schematool">
+				schema tool</link>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-sqlFile/-sql &lt;stdout | output file&gt;</literal>:
+				Use this option to write the planned schema modifications to
+				a SQL script rather than modify the database.  Combine this
+				with a <literal>schemaAction</literal> of 
+				<literal>build</literal> to generate a script that recreates
+				the schema for the current mappings, even if the schema already
+				exists.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-dropTables/-dt &lt;true/t | false/f&gt;</literal>: 
+				Corresponds to the same-named option on the schema tool.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-dropSequences/-dsq &lt;true/t | false/f&gt;</literal>:
+				Corresponds to the same-named option on the schema tool.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-openjpaTables/-kt &lt;true/t | false/f&gt;</literal>: 
+				Corresponds to the same-named option on the schema tool.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-ignoreErrors/-i &lt;true/t | false/f&gt;</literal>: 
+				Corresponds to the same-named option on the schema tool.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-schemas/-s &lt;schema and table names&gt;</literal>: 
+				Corresponds to the same-named option on the schema tool.
+				This option is ignored if <literal>readSchema</literal> is not
+				set to <literal>true</literal>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-readSchema/-rs &lt;true/t | false/f&gt;</literal>: 
+				Set this option to <literal>true</literal> to read the entire
+				existing schema when the tool runs.  Reading the existing schema
+				ensures that OpenJPA does not generate any mappings that use
+				table, index, primary key, or foreign key names that conflict
+				with existing names.  Depending on the JDBC driver, though,
+				it can be a slow process for large schemas.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-primaryKeys/-pk &lt;true/t | false/f&gt;</literal>:
+				Whether to read and manipulate primary key information of 
+				existing tables.  Defaults to false.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-foreignKeys/-fk &lt;true/t | false/f&gt;</literal>:
+				Whether to read and manipulate foreign key information of 
+				existing tables.  Defaults to false.  This means that to add
+				any new foreign keys to a class that has already been mapped, 
+				you must explicitly set this flag to true.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-indexes/-ix &lt;true/t | false/f&gt;</literal>:
+				Whether to read and manipulate index information of 
+				existing tables.  Defaults to false.  This means that to add
+				any new indexes to a class that has already been mapped once, 
+				you must explicitly set this flag to true.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-sequences/-sq &lt;true/t | false/f&gt;</literal>:
+				Whether to manipulate sequences.  Defaults to true.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>-meta/-m &lt;true/t | false/f&gt;</literal>: Whether 
+				the given action applies to metadata rather than or in addition
+				to mappings.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The mapping tool also uses an <literal>-action/-a</literal> argument 
+		to specify the action to take on each class.  The available actions are:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>buildSchema</literal>: This is the default action when
+				using JPA mapping defaults (see 
+				<xref linkend="ref_guide_mapping_defaults"/>).  It makes the 
+				database schema match your existing mappings. If your provided 
+				mappings conflict with a class definition, OpenJPA will fail with 
+				an informative exception.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>validate</literal>: Ensure that the mappings for
+				the given classes are valid and that they match the schema.
+				No mappings or tables will be changed.  An exception is
+				thrown if any mappings are invalid.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		Each additional argument to the tool should be one of:
+		</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 mapping tool, it will run on
+		the classes in your persistent classes list (see 
+		<xref linkend="ref_guide_pc_pcclasses"/>).
+		</para>
+        <para>
+		The mappings generated by the mapping tool are stored by the system
+		<emphasis>mapping factory</emphasis>.  
+		<xref linkend="ref_guide_mapping_factory"/> discusses your mapping
+		factory options.
+		</para>
+        <section id="ref_guide_mapping_mappingtool_examples">
+          <title>Using the Mapping Tool</title>
+          <indexterm zone="ref_guide_mapping_mappingtool_examples">
+            <primary>mapping tool</primary>
+            <secondary>use cases</secondary>
+          </indexterm>
+          <para>
+			The JPA specification defines a comprehensive set of
+			defaults for missing mapping information.  Thus, forward mapping
+			in JPA is virtually automatic.  After using the mapping 
+			annotations covered in <xref linkend="jpa_overview_mapping"/> of
+			the JPA Overview to override any unsatisfactory 
+			defaults, run the mapping tool's <literal>buildSchema</literal> 
+			action on your persistent classes.  This is the default action when
+			you use JPA mapping defaults 
+			(see <xref linkend="ref_guide_mapping_defaults"/>).
+			</para>
+          <para>
+			The <literal>buildSchema</literal> action manipulates the database
+			schema to match your mappings.  It fails if any of your mappings
+			don't match your object model.
+			</para>
+          <example id="ref_guide_mapping_mappingtool_buildschema">
+            <title>Creating the Relational Schema from Mappings</title>
+            <programlisting format="linespecific">
+mappingtool Magazine.java
+</programlisting>
+          </example>
+          <para>
+			To drop the schema for a persistent class, set the mapping tool's
+			<literal>schemaAction</literal> to <literal>drop</literal>. 
+			</para>
+          <example id="ref_guide_mapping_mappingtool_dropschema">
+            <title>Dropping Mappings and Association Schema</title>
+            <programlisting format="linespecific">
+mappingtool -sa drop Magazine.java
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_ddl_examples">
+          <title>Generating DDL SQL</title>
+          <indexterm zone="ref_guide_ddl_examples">
+            <primary>mapping tool</primary>
+            <secondary>DDL generation</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_ddl_examples">
+            <primary>DDL</primary>
+            <secondary>with mapping tool</secondary>
+          </indexterm>
+          <para>
+			The examples below show how to use the mapping tool to generate 
+			DDL SQL scripts, rather than modifying the database directly.
+			</para>
+          <example id="ref_guid_mapping_ddl_full_ddl">
+            <title>Create DDL for Current Mappings</title>
+            <para>
+				This example uses your existing mappings to determine the 
+				needed schema, then writes the SQL to create that schema to
+				<filename>create.sql</filename>. 
+				</para>
+            <programlisting format="linespecific">
+mappingtool -a buildSchema -sa build -sql create.sql Magazine.java
+</programlisting>
+          </example>
+          <example id="ref_guid_mapping_ddl_part_ddl">
+            <title>Create DDL to Update Database for Current 
+				Mappings</title>
+            <para>
+				This example uses your existing mappings to determine the 
+				needed schema.  It then writes the SQL to add any missing 
+				tables and columns to the current schema to 
+				<filename>update.sql</filename>.
+				</para>
+            <programlisting format="linespecific">
+mappingtool -a buildSchema -sql update.sql Magazine.java
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_mapping_synch">
+          <title>Runtime Forward Mapping</title>
+          <indexterm zone="ref_guide_mapping_synch">
+            <primary>forward mapping</primary>
+            <secondary>automatic runtime mapping</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_synch">
+            <primary>mapping metadata</primary>
+            <secondary>automatic runtime mapping</secondary>
+          </indexterm>
+          <para>
+			You can configure OpenJPA to automatically run the mapping tool 
+			at runtime through the 
+			<link linkend="openjpa.jdbc.SynchronizeMappings"><literal>
+			openjpa.jdbc.SynchronizeMappings</literal></link> configuration 
+			property.  Using this property saves you the trouble of running 
+			the mapping tool manually, and is meant for use during rapid 
+			test/debug cycles.
+			</para>
+          <para>
+			In order to enable automatic runtime mapping, you must first list
+			all your persistent classes as described in
+			<xref linkend="ref_guide_pc_pcclasses"/>.
+			</para>
+          <para>
+			OpenJPA will run the mapping tool on these classes when your 
+			application obtains its first <classname>EntityManager</classname>.
+			</para>
+          <para>
+			The <literal>openjpa.jdbc.SynchronizeMappings</literal> property is
+			a plugin string (see <xref linkend="ref_guide_conf_plugins"/>) 
+			where the class name is the mapping tool action to invoke, and
+			the properties are the <classname>MappingTool</classname> class' 
+			JavaBean properties.  These properties correspond go the long 
+			versions of the tool's command line flags.
+			</para>
+          <example id="ref_guide_mapping_synchex">
+            <title>Configuring Runtime Forward Mapping</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/&gt;
+</programlisting>
+            <para>
+				The setting above corresponds to running the following command:
+				</para>
+            <programlisting format="linespecific">
+mappingtool -a buildSchema -fk true
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_pc_reverse">
+        <title>Reverse Mapping</title>
+        <indexterm zone="ref_guide_pc_reverse">
+          <primary>reverse mapping</primary>
+        </indexterm>
+        <indexterm zone="ref_guide_pc_reverse">
+          <primary>reverse mapping tool</primary>
+          <seealso>reverse mapping</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>mapping metadata</primary>
+          <secondary>reverse mapping</secondary>
+          <see>reverse mapping</see>
+        </indexterm>
+        <para>
+		OpenJPA includes a <emphasis>reverse mapping</emphasis> tool for 
+		generating persistent class definitions, complete with 
+		metadata, from an existing database schema.  You do not 
+		have to use the reverse mapping tool to access an existing schema; you 
+		are free to write your classes and mappings yourself, as described in
+		<xref linkend="ref_guide_mapping_middle"/>.  The reverse mapping tool, 
+		however, can give you an excellent starting point from which to grow 
+		your persistent classes.
+		</para>
+<!-- ### EJBDOC -->
+        <note>
+          <para>
+			The reverse mapping tool in this release does not yet output JPA 
+			annotations.  It is limited to JDO metadata output.
+			</para>
+        </note>
+        <para>
+		To use the reverse mapping tool, follow the steps below:
+		</para>
+        <orderedlist>
+          <listitem>
+            <para>
+				Use the <link linkend="ref_guide_schema_schematool">
+				schema tool</link> to export your current schema 
+				to an XML schema file.  You can skip this step and the next
+				step if you want to run the reverse mapping tool directly
+				against the database.
+				</para>
+            <example id="ref_guide_pc_reverse_schemagen">
+              <title>Reflection with the Schema Tool</title>
+              <programlisting format="linespecific">
+schematool -a reflect -f schema.xml
+</programlisting>
+            </example>
+          </listitem>
+          <listitem>
+            <para>
+				Examine the generated schema file.  JDBC drivers often provide
+				incomplete or faulty metadata, in which case the file will
+				not exactly match the actual schema. 
+				Alter the XML file to match the true schema.  The XML format 
+				for the schema file is described in
+				<xref linkend="ref_guide_schema_xml"/>.
+				</para>
+            <para>
+				After fixing any errors in the schema file, modify the XML
+				to include foreign keys between all relations.
+				The schema tool will have automatically detected existing
+				foreign key constraints; many schemas, however, do not employ 
+				database foreign keys for every relation.  By manually
+				adding any missing foreign keys, you will give the reverse 
+				mapping tool the information it needs to generate the 
+				proper relations between the persistent classes it creates.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				Run the reverse mapping tool on the finished schema file.
+				If you do not supply the schema file to reverse map, the tool 
+				will run directly against the schema in the database.  The
+				tool can be run via the included
+				<literal>reversemappingtool</literal> script, or through
+				its Java class, 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseMappingTool"><classname>org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></ulink>.
+				</para>
+            <example id="ref_guide_pc_reverse_reversemappingtool">
+              <title>Using the Reverse Mapping Tool</title>
+              <programlisting format="linespecific">
+reversemappingtool -pkg com.xyz -d ~/src -cp customizer.properties schema.xml
+</programlisting>
+            </example>
+            <para>
+  				In addition to OpenJPA's <link linkend="ref_guide_conf_devtools">
+				standard configuration flags</link>, including 
+				<link linkend="ref_guide_conf_devtools_format">code formatting
+				options</link>, the reverse mapping tool recognizes the
+				following command line arguments:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>-schemas/-s &lt;schema and table names&gt;
+						</literal>: A comma-separated list of schema and 
+						table names to reverse map, if no XML schema file is
+						supplied.  Each element of the list must follow the 
+						naming conventions for the <literal>openjpa.jdbc.Schemas
+						</literal> property described in 
+						<xref linkend="ref_guide_schema_info_list"/>.  In fact, 
+						if this flag is omitted, it defaults to the value of the
+						<literal>Schemas</literal> property.  If the
+						<literal>Schemas</literal> property is not defined,
+						all schemas will be reverse-mapped.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-package/-pkg &lt;package name&gt;</literal>: 
+						The package name of the generated classes.  If no
+						package name is given, the generated code will not 
+						contain package declarations.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-directory/-d &lt;output directory&gt;
+						</literal>: All generated code and metadata will be
+						written to the directory at this path.  If the path does
+						not match the package of a class, the package
+						structure will be created beneath this directory.  
+						Defaults to the current directory.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-useSchemaName/-sn &lt;true/t | false/f&gt;
+						</literal>: Set this flag to <literal>true</literal> 
+						to include the schema as well as table name in the 
+						name of each generated class.  This can be useful when 
+						dealing with multiple schemas with same-named tables.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-useForeignKeyName/-fkn 
+						&lt;true/t | false/f&gt;</literal>: Set this flag to 
+						<literal>true</literal> if you would like field names 
+						for relations to be based on the database foreign key 
+						name.  By default, relation field names are derived 
+						from the name of the related class.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-nullableAsObject/-no &lt;true/t | false/f&gt;
+						</literal>: By default, all non-foreign key columns
+						are mapped to primitives.  Set this flag to 
+						<literal>true</literal> to generate primitive wrapper 
+						fields instead for columns that allow null values.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-blobAsObject/-bo &lt;true/t | false/f&gt;
+						</literal>: By default, all binary columns are mapped
+						to <classname>byte[]</classname> fields.  Set this flag
+						to <literal>true</literal> to map them to 
+						<classname>Object</classname> fields instead.  Note that
+						when mapped this way, the column is presumed to contain
+						a serialized Java object.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-primaryKeyOnJoin/-pkj &lt;true/t | false/f&gt;
+						</literal>: The standard reverse mapping tool behavior
+						is to map all tables with primary keys to persistent
+						classes.  If your schema has primary keys on 
+						many-many join tables as well, set this flag to 
+						<literal>true</literal> to avoid creating classes for 
+						those tables.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-inverseRelations/-ir &lt;true/t 
+						| false/f&gt;</literal>: Set to <literal>false</literal>
+						to prevent the creation of inverse 1-many/1-1 
+						relations for every many-1/1-1 relation detected.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-useDatastoreIdentity/-ds 
+						&lt;true/t | false/f&gt;</literal>: Set to 
+						<literal>true</literal> to use datastore identity 
+						for tables that have single numeric primary key 
+						columns.  The tool typically uses application identity 
+						for all generated classes.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-useBuiltinIdentityClass/-bic &lt;true/t 
+						| false/f&gt;</literal>: Set to <literal>false</literal>
+						to prevent the tool from using built-in application
+						identity classes when possible.  This will force the 
+						tool to to create custom application identity classes 
+						even when there is only one primary key column.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-innerIdentityClasses/-inn &lt;true/t 
+						| false/f&gt;</literal>: Set to <literal>true</literal>
+						to have any generated application identity classes be
+						created as static inner classes within the persistent
+						classes.  Defaults to <literal>false</literal>.  
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-identityClassSuffix/-is 
+						&lt;suffix&gt;</literal>:  Suffix to append to class 
+						names to form application identity class names, or for 
+						inner identity classes, the inner class name.  
+						Defaults to <literal>Id</literal>.
+						</para>
+              </listitem>
+<!-- ### EJBDOC : need some EJB equiv -->
+<!-- ### EJBDOC : need some EJB equiv -->
+<!-- ### EJBDOC : need some EJB equiv form XML / anno -->
+              <listitem>
+                <para><literal>-typeMap/-typ &lt;type mapping&gt;</literal>: 
+						A string that specifies the default Java classes to 
+						generate for each SQL type that is seen in the schema. 
+						The format is <literal>
+						SQLTYPE1=JavaClass1,SQLTYPE2=JavaClass2</literal>.
+						The SQL type name first looks for a customization 
+						based on <literal>SQLTYPE(SIZE,PRECISION)</literal>, 
+						then <literal>SQLTYPE(SIZE)</literal>, then
+						<literal>SQLTYPE(SIZE,PRECISION)</literal>. So
+						if a column whose type name is
+						<literal>CHAR</literal> is found, it will first look
+						for the <literal>CHAR(50,0)</literal> type name
+						specification, then it will look for
+						<literal>CHAR(50)</literal>, and finally it will
+						just look for <literal>CHAR</literal>.
+						For example, to generate a char array for
+						every <literal>CHAR</literal> column whose size
+						is exactly 50, and to generate a
+						<literal>short</literal> for every type name of
+						<literal>INTEGER</literal>, you might specify:
+						<literal>CHAR(50)=char[],INTEGER=short</literal>.
+						Note that since various databases report different
+						type names differently, one database's type name
+						specification might not work for another database.
+						Enable <literal>TRACE</literal> level logging on the
+						<literal>MetaData</literal> channel to track which
+						type names OpenJPA is examining.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-customizerClass/-cc 
+						&lt;class name&gt;</literal>: The full class name of a
+						<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html"><classname>org.apache.openjpa.jdbc.meta.ReverseCustomizer</classname></ulink> customization plugin.  If you do
+						not specify a reverse customizer of your own, the 
+						system defaults to a  
+						<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html"><classname>PropertiesReverseCustomizer</classname></ulink>.  This customizer allows you to specify 
+						simple customization options in the properties file
+						given with the <literal>-customizerProperties</literal>
+						flag below.  We present the available property keys
+						<link linkend="ref_guide_pc_reverse_custom">
+						below</link>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-customizerProperties/-cp &lt;properties
+						file or resource&gt;</literal>: The path or resource 
+						name of a properties file to pass to the reverse 
+						customizer on initialization.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>-customizer./-c.&lt;property name&gt; 
+						&lt;property value&gt;</literal>: The given property
+						name will be matched with the corresponding Java bean
+						property in the specified reverse customizer, and set
+						to the given value.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				Running the tool will generate <filename>.java</filename> files 
+				for each generated class (and its application identity class,
+				if applicable), along with all necessary persistence metadata
+				and mappings. 
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				Examine the generated class, metadata, and mapping
+				information, and modify it as necessary.  Remember that
+				the reverse mapping tool only provides a starting point, and
+				you are free to make whatever modifications you like to the 
+				code it generates. 
+				</para>
+            <para>
+				After you are satisfied with the generated classes and their 
+				mappings, you should first compile them with 
+				<literal>javac</literal>, <literal>jikes</literal>, or your
+				favorite Java compiler.  Make sure the classes and their
+				metadata are located in the directory corresponding to
+				the <literal>-package</literal> flag you gave the reverse
+				mapping tool.  Finally, enhance the classes if necessary (see
+				<xref linkend="ref_guide_pc_enhance"/>).
+				</para>
+          </listitem>
+        </orderedlist>
+        <para>
+		Your persistent classes are now ready to access your existing schema.
+		</para>
+        <section id="ref_guide_pc_reverse_custom">
+          <title>Customizing Reverse Mapping</title>
+          <para>
+			The <classname>org.apache.openjpa.jdbc.meta.ReverseCustomizer</classname> plugin 
+			interface allows you to customze the reverse mapping process.  See 
+			the class
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseCustomizer.html">
+			Javadoc</ulink> for details on the hooks that this interface
+			provides.  Specify the concrete plugin implementation to use with
+			the <literal>-customizerClass/-cc</literal> command-line flag, 
+			described in the preceding section.
+			</para>
+          <para>
+			By default, the reverse mapping tool uses a
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/PropertiesReverseCustomizer.html"><classname>org.apache.openjpa.jdbc.meta.PropertiesReverseCustomizer</classname></ulink>.  This customizer allows you to perform 
+			relatively simple customizations through the properties file named
+			with the <literal>-customizerProperties</literal> tool flag.  
+			The customizer recognizes the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>&lt;table name&gt;.table-type &lt;type&gt;
+					</literal>: Override the default type of the table with
+					name <literal>&lt;table name&gt;</literal>.  Legal values 
+					are: 
+					</para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>base</literal>: Primary table for a base
+							class.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>secondary</literal>: Secondary table for 
+							a class.  The table must have a foreign key joining
+							to a class table.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>secondary-outer</literal>: Outer-joined
+							secondary table for a class.  The table must have 
+							a foreign key joining to a class table.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>association</literal>: Association table.
+							The table must have two foreign keys to class 
+							tables.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>collection</literal>: Collection table.
+							The table must have one foreign key to a class
+							table and one data column.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>subclass</literal>: A joined subclass
+							table.  The table must have a foreign key to the
+							superclass' table.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>none</literal>: The table should not be
+							reverse-mapped.
+							</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;class name&gt;.rename &lt;new class name&gt;
+					</literal>: Override the given tool-generated name 
+					<literal>&lt;class name&gt;</literal>
+					with a new value.  Use full class names, including package.
+					You are free to rename a class to a new package.  Specify
+					a value of <literal>none</literal> to reject the class and 
+					leave the corresponding table unmapped.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;table name&gt;.class-name 
+					&lt;new class name&gt;</literal>: Assign the given
+					fully-qualified class name to the type created from the
+					table with name <literal>&lt;table name&gt;</literal>.
+					Use a value of <literal>none</literal> to prevent reverse
+					mapping this table.  This property can be used in place
+					of the <literal>rename</literal> property.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;class name&gt;.identity &lt;datastore | 
+					builtin | identity class name&gt;</literal>: Set this 
+					property to <literal>datastore</literal> to use datastore 
+					identity for the class <literal>&lt;class 
+					name&gt;</literal>, <literal>builtin</literal> to use 
+					a built-in identity class, or the desired
+					application identity class name.  Give full class names, 
+					including package.  You are free to change the package of 
+					the identity class this way.  If the persistent class has 
+					been renamed, use the new class name for this property key.
+					Remember that datastore identity requires a table with a 
+					single numeric primary key column, and built-in identity
+					requires a single primary key column of any type.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;class name&gt;.&lt;field name&gt;.rename
+					&lt;new field name&gt;</literal>: Override the 
+					tool-generated <literal>&lt;field name&gt;</literal> in
+					class <literal>&lt;class name&gt;</literal> with the given 
+					name.  Use the field owner's full class name in the 
+					property key.  If the
+					field owner's class was renamed, use the new class name.
+					The property value should be the new field name, without 
+					the preceding class name.  Use a value of <literal>none
+					</literal> to reject the generated mapping and remove the
+					field from the class.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;table name&gt;.&lt;column name&gt;.field-name
+					&lt;new field name&gt;</literal>: Set the generated field
+					name for the <literal>&lt;table name&gt;</literal> table's
+					<literal>&lt;column name&gt;</literal> column.  If this is
+					a multi-column mapping, any of the columns can be used.
+					Use a value of <literal>none</literal> to prevent the column
+					and its associated columns from being reverse-mapped.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;class name&gt;.&lt;field name&gt;.type
+					&lt;field type&gt;</literal>: The type to give the named 
+					field.  Use full class names.  If the field	or the field's
+					owner class has been renamed, use the new name.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>&lt;class name&gt;.&lt;field name&gt;.value
+					</literal>: The initial value for the named field.  The 
+					given string will be placed as-is in the generated Java 
+					code, so be sure it is valid Java.  If the
+					field or the field's owner class has been renamed, use the 
+					new name.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			All property keys are optional; if not specified, the customizer 
+			keeps the default value generated by the reverse mapping tool.
+			</para>
+          <example id="ref_guide_pc_reverse_custom_ex">
+            <title>Customizing Reverse Mapping with Properties</title>
+            <programlisting format="linespecific">
+reversemappingtool -pkg com.xyz -cp custom.properties schema.xml
+</programlisting>
+            <para>
+				Example <filename>custom.properties</filename>:
+				</para>
+            <programlisting format="linespecific">
+com.xyz.TblMagazine.rename:             com.xyz.Magazine
+com.xyz.TblArticle.rename:              com.xyz.Article
+com.xyz.TblPubCompany.rename:           com.xyz.pub.Company
+com.xyz.TblSysInfo.rename:              none
+
+com.xyz.Magazine.allArticles.rename:    articles
+com.xyz.Magazine.articles.type:         java.util.Collection
+com.xyz.Magazine.articles.value:        new TreeSet()
+com.xyz.Magazine.identity:              datastore
+
+com.xyz.pub.Company.identity:           com.xyz.pub.CompanyId
+</programlisting>
+          </example>
+          <para>
+			Your OpenJPA download includes the <classname>
+			PropertiesReverseCustomizer</classname> source code.  You can use
+			this code as an example when writing your own customization class.
+			</para>
+        </section>
+      </section>
+      <section id="ref_guide_mapping_middle">
+        <title>Meet-in-the-Middle Mapping</title>
+        <indexterm zone="ref_guide_pc_reverse">
+          <primary>meet-in-the-middle mapping</primary>
+        </indexterm>
+        <indexterm zone="ref_guide_pc_reverse">
+          <primary>reverse mapping tool</primary>
+          <seealso>reverse mapping</seealso>
+        </indexterm>
+        <indexterm>
+          <primary>mapping metadata</primary>
+          <secondary>meet-in-the-middle mapping</secondary>
+          <see>meet-in-the-middle mapping</see>
+        </indexterm>
+        <para>
+		In the <emphasis>meet-in-the-middle</emphasis> mapping approach, you
+		control both the relational model and the object model.  It is up 
+		to you to define the mappings between these models.  OpenJPA has two 
+		tools to aid meet-in-the-middle mapping.  First, the OpenJPA Workbench 
+		includes a visual interface to wiring your classes and schema together.
+<!-- ### JDO2MIG
+		See <xref linkend="gui_intro"/> to get started with the Workbench.
+-->
+		Second, the mapping tool's <literal>validate</literal> action is useful
+		to meet-in-the-middle mappers.  We examined the mapping tool in
+		<xref linkend="ref_guide_mapping_mappingtool"/>.  The <literal>validate
+		</literal> action verifies that the mapping information for a class 
+		matches the class definition and the existing schema.  It throws an
+		informative exception when your mappings are incorrect.
+		</para>
+        <example id="ref_guide_mapping_mappingtool_validate">
+          <title>Validating Mappings</title>
+          <programlisting format="linespecific">
+mappingtool -a validate Magazine.java
+</programlisting>
+        </example>
+        <para>
+		The <literal>buildSchema</literal> action we discussed in
+		<xref linkend="ref_guide_mapping_mappingtool"/> is also somewhat useful
+		during meet-in-the-middle mapping.  Unlike the 
+		<literal>validate</literal> action, which throws an exception if
+		your mapping data does not match the existing schema, 
+		the <literal>buildSchema</literal> action assumes your mapping data 
+		is correct, and modifies the schema to match your mappings.  This lets 
+		you modify your mapping data manually, but saves you the hassle of 
+		using your database's tools to bring the schema up-to-date.
+		</para>
+        <para><literal>buildSchema</literal> is the default action when you use 
+		JPA mapping defaults (<xref linkend="ref_guide_mapping_defaults"/>).
+		</para>
+        <example id="ref_guide_mapping_middle_buildschema_mid">
+          <title>Creating the Relational Schema from Mappings</title>
+          <programlisting format="linespecific">
+mappingtool Magazine.java
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_mapping_defaults">
+        <title>Mapping Defaults</title>
+        <indexterm zone="ref_guide_mapping_defaults">
+          <primary>MappingDefaults</primary>
+        </indexterm>
+        <indexterm>
+          <primary>mapping metadata</primary>
+          <secondary>defaults</secondary>
+          <see>MappingDefaults</see>
+        </indexterm>
+        <para>
+		The previous sections showed how to use the mapping tool to generate
+		default mappings.  But how does the mapping tool know what mappings
+		to generate?  The answer lies in the
+		<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingDefaults.html"><classname>
+		org.apache.openjpa.jdbc.meta.MappingDefaults</classname></ulink> interface.  OpenJPA
+		uses an instance of this interface to decide how to name tables and
+		columns, where to put foreign keys, and generally how to create a
+		schema that matches your object model.  
+		</para>
+        <important>
+          <para>
+			OpenJPA relies on foreign key constraint information at runtime to
+			order SQL appropriately.  Be sure to set your mapping defaults to
+			reflect your existing database constraints, or use explicit
+			foreign key mappings as described in
+			<phrase><xref linkend="ref_guide_mapping_ejb_fk"/></phrase> 
+			
+			.
+			</para>
+        </important>
+        <para>
+		The <link linkend="openjpa.jdbc.MappingDefaults"><literal>
+		openjpa.jdbc.MappingDefaults</literal></link> configuration property
+		controls the <classname>MappingDefaults</classname> interface
+		implementation in use.  This is a plugin property (see
+		<xref linkend="ref_guide_conf_plugins"/>), so you can substitute your
+		own implementation or configure the existing ones.  OpenJPA includes the
+		following standard implementations:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>jpa</literal>: Provides defaults in compliance with
+				the JPA standard.  This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/PersistenceMappingDefaults.html"><classname>org.apache.openjpa.persistence.jdbc.PersistenceMappingDefaults
+				</classname></ulink> class.  This class extends the 
+				<classname>MappingDefaultsImpl</classname> class described 
+				below, so it has all the same properties (though with 
+				different default values).
+				</para>
+          </listitem>
+          <listitem>
+            <para><phrase><literal>default</literal>:
+				</phrase>
+				This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingDefaultsImpl.html"><classname>org.apache.openjpa.jdbc.meta.MappingDefaultsImpl</classname></ulink> class.  This default implementation is highly 
+				configurable.  It has the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>DefaultMissingInfo</literal>: Whether to 
+						default missing column and table names rather than
+						throw an exception.  Defaults to false, meaning full
+						mappings are required at runtime and when using
+						mapping tool actions like <literal>buildSchema</literal>
+						and <literal>validate</literal>.
+						</para>
+                <para>
+						The <literal>jpa</literal> plugin above sets this
+						property to true to meet the JPA specification.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>BaseClassStrategy</literal>: The default
+						mapping strategy for base classes.  You can specify a
+						built-in strategy alias or the full class name of a 
+						<link linkend="ref_guide_mapping_custom_class">
+						custom class strategy</link>.  You can also use OpenJPA's 
+						plugin format (see 
+						<xref linkend="ref_guide_conf_plugins"/>) 
+						to pass arguments to the strategy instance.  See the
+						<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/strats/package-summary.html"><literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package
+						for available strategies.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>SubclassStrategy</literal>: The default
+						mapping strategy for subclasses.  You can specify a
+						builtin strategy alias or the full class name of a 
+						<link linkend="ref_guide_mapping_custom_class">
+						custom class strategy</link>.  You can also use OpenJPA's 
+						plugin format (see 
+						<xref linkend="ref_guide_conf_plugins"/>) 
+						to pass arguments to the strategy instance.  
+						Common strategies are <literal>vertical</literal> and
+						<literal>flat</literal>, the default.  See the
+						<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/strats/package-summary.html"><literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package
+						for all available strategies.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>VersionStrategy</literal>: The default
+						version strategy for classes without a
+						version field.  You can specify a builtin strategy 
+						alias or the full class name of a 
+						<link linkend="ref_guide_mapping_custom_versdiscrim">
+						custom version strategy</link>.  You can also use 
+						OpenJPA's plugin format (see 
+						<xref linkend="ref_guide_conf_plugins"/>) 
+						to pass arguments to the strategy instance.  
+						Common strategies are <literal>none</literal>,
+						<literal>state-comparison</literal>, <literal>
+						timestamp</literal>, and <literal>
+						version-number</literal>, the default.  See the
+						<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/strats/package-summary.html"><literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package
+						for all available strategies.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>DiscriminatorStrategy</literal>: The default
+						discriminator strategy when no discriminator value is
+						given.  You can specify a builtin strategy alias or 
+						the full class name of a 
+						<link linkend="ref_guide_mapping_custom_versdiscrim">
+						custom discriminator strategy</link>.  You can also use 
+						OpenJPA's plugin format (see 
+						<xref linkend="ref_guide_conf_plugins"/>) 
+						to pass arguments to the strategy instance.  
+						Common strategies are <literal>final</literal> for
+						a base class without subclasses, <literal>none
+						</literal> to use joins to subclass tables rather than 
+						a discriminator column, and <literal>
+						class-name</literal>, the default.  See the
+						<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/strats/package-summary.html"><literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package
+						for all available strategies.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>FieldStrategies</literal>: This property
+						associates field types with custom strategies.  The 
+						format of this property is similar to that of plugin 
+						strings (see <xref linkend="ref_guide_conf_plugins"/>),
+						without the class name.  It is a comma-separated list 
+						of key/value pairs, where each key is a possible field 
+						type, and each value is itself a plugin string 
+						describing the strategy for that type.  We present an 
+						example below.  See 
+						<xref linkend="ref_guide_mapping_custom_field"/> for
+						information on custum field strategies.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>ForeignKeyDeleteAction</literal>:
+						The default delete action of foreign keys representing 
+						relations to other objects. Recognized values include
+						<literal>restrict</literal>, <literal>cascade</literal>,
+						<literal>null</literal>, <literal>default</literal>.  
+						These values correspond exactly to the standard 
+						database foreign key actions of the same names.  
+						</para>
+                <para>
+						The value <literal>none</literal> tells OpenJPA not to
+						create database foreign keys on relation columns.  
+						This is the default.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>JoinForeignKeyDeleteAction</literal>:
+						The defualt delete action of foreign keys that join
+						join secondary, collection, map, or subclass tables to 
+						the primary table.  Accepts the same values as the
+						<literal>ForeignKeyDeleteAction</literal> property 
+						above.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>DeferConstraints</literal>: Whether to use
+						deferred database constraints if possible.  Defaults
+						to false.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>IndexLogicalForeignKeys</literal>: Boolean
+						property controlling whether to create indexes on
+						logical foreign keys.  Logical foreign keys are 
+						columns that represent a link between tables, but
+						have been configured through the <literal>ForeignKey
+						</literal> properties above not to use a physical 
+						database foreign key.  Defaults to true.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>DataStoreIdColumnName</literal>: The default
+						name of datastore identity columns.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>DiscriminatorColumnName</literal>: The default
+						name of discriminator columns.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>IndexDiscriminator</literal>: Whether to index
+						the discriminator column.  Defaults to true.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>VersionColumnName</literal>: The default
+						name of version columns.  If you use custom lock groups,
+						this name may be combined with lock group names.  See
+						<xref linkend="ref_guide_lock_groups"/> for more
+						information on lock groups.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>IndexVersion</literal>: Whether to index
+						the version column.  Defaults to false.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>AddNullIndicator</literal>: Whether to create 
+						a synthetic null indicator column for embedded mappings.
+						The null indicator column allows OpenJPA to distinguish
+						between a null embedded object and one with default
+						values for all persistent fields.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>NullIndicatorColumnName</literal>: The default
+						name of synthetic null indicator columns for embedded
+						objects.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>OrderLists</literal>: Whether to create a
+						database ordering column for maintaining the order of
+						persistent lists and arrays.  Defaults to true.
+						</para>
+                <para>
+						The <literal>jpa</literal> plugin above sets this 
+						property to false in accordance with the JPA
+						specification.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>OrderColumnName</literal>: The default
+						name of collection and array ordering columns.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>StoreEnumOrdinal</literal>: 
+						Set to true to store enum fields as numeric ordinal
+						values in the database.  The default is to store
+						the enum value name as a string, which is more robust
+						if the Java enum declaration might be rearranged.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>StoreUnmappedObjectIdString</literal>: 
+						Set to true to store the stringified identity of
+						related objects when the declared related type is
+						unmapped.  By default, OpenJPA stores the related object's
+						primary key value(s).  However, this breaks down if 
+						different subclasses of the related type use 
+						incompatible primary key structures.  In that case,
+						stringifying the identity value is the better choice.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The example below turns on foreign key generation during schema 
+		creation and associates the <classname>org.mag.data.InfoStruct
+		</classname> field type with the custom <classname>
+		org.mag.mapping.InfoStructHandler</classname> value handler.
+		</para>
+        <example id="ref_guide_mapping_defaults_conf">
+          <title>Configuring Mapping Defaults</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.jdbc.MappingDefaults" 
+    value="ForeignKeyDeleteAction=restrict, 
+    FieldStrategies='org.mag.data.InfoStruct=org.mag.mapping.InfoStructHandler'"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_mapping_factory">
+        <title>Mapping Factory</title>
+        <indexterm zone="ref_guide_mapping_factory">
+          <primary>MappingFactory</primary>
+        </indexterm>
+        <indexterm>
+          <primary>mapping metadata</primary>
+          <secondary>loading and storing</secondary>
+          <see>MappingFactory</see>
+        </indexterm>
+        <para>
+		An important decision in the object-relational mapping process
+		is how and where to store the data necessary to map your persistent
+		classes to the database schema.
+		</para>
+        <para>
+		In JPA, mapping metadata is defined in annotations.  Future
+		versions of the JPA drafts will also define a mapping
+		XML format.  <xref linkend="jpa_overview_mapping"/> in the
+		JPA Overview describes JPA mapping options.
+		</para>
+        <para><xref linkend="ref_guide_meta_factory"/> introduced OpenJPA's <classname>
+		MetaDataFactory</classname> interface.  OpenJPA uses this same interface
+		to abstract the storage and retrieval of mapping information.  OpenJPA
+		includes the built-in mapping factories below, and you can create 
+		your own factory if you have custom needs.  You control which mapping 
+		factory OpenJPA uses with the <link linkend="openjpa.jdbc.MappingFactory"><literal>openjpa.jdbc.MappingFactory</literal></link> configuration 
+		property.
+		</para>
+        <para>
+		The bundled mapping factories are:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>-</literal>:  Leaving the <literal>
+				openjpa.jdbc.MappingFactory</literal> property unset allows your
+				metadata factory to take over mappings as well.
+				</para>
+            <para>
+				If you are using the <literal>jpa</literal> metadata factory,
+				OpenJPA will read mapping information from your annotations when
+				you leave the mapping factory unspecified.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_mapping_factory_ejb">
+          <title>Standard JPA Configuration</title>
+          <para>
+			In the standard JPA configuration, the mapping factory 
+			is left unset.
+			</para>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.MetaDataFactory" value="jpa"/&gt;
+</programlisting>
+        </example>
+      </section>
+      <section id="ref_guide_mapping_notes_nonstdjoins">
+        <title>Non-Standard Joins</title>
+        <indexterm zone="ref_guide_mapping_notes_nonstdjoins">
+          <primary>joins</primary>
+          <secondary>non-standard</secondary>
+        </indexterm>
+        <para>
+		The JPA Overview's <xref linkend="jpa_overview_mapping"/> 
+		explains join mapping.  All of the examples in that document,
+		however, use "standard" joins, in that there is one foreign key column
+		for each primary key column in the target table.  OpenJPA supports 
+		additional join patterns, including partial primary key joins, 
+		non-primary key joins, and joins using constant values.
+		</para>
+        <para><indexterm><primary>joins</primary><secondary>partial primary key</secondary></indexterm>
+		In a partial primary key join, the source table only has foreign key
+		columns for a subset of the primary key columns in the target table.
+		So long as this subset of columns correctly identifies the proper
+		row(s) in the referenced table, OpenJPA will function properly.
+		There is no special syntax for expressing a partial primary key join -
+		just do not include column definitions for missing foreign key columns.
+		</para>
+        <para><indexterm><primary>joins</primary><secondary>non-primary key</secondary></indexterm>
+		In a non-primary key join, at least one of the target columns is not a 
+		primary key.  Once again, OpenJPA supports this join type with the same 
+		syntax as a primary key join.  There is one restriction, however: each 
+		non-primary key column you are joining to must be controlled by a 
+		field mapping that implements the
+		<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/Joinable.html"><classname>
+		org.apache.openjpa.jdbc.meta.Joinable</classname></ulink> interface.   All built in
+		basic mappings implement this interface, including basic fields of 
+		embedded objects.  OpenJPA will also respect any custom mappings that 
+		implement this interface.  See 
+		<xref linkend="ref_guide_mapping_custom"/> for an examination of 
+		custom mappings.
+		</para>
+        <para><indexterm><primary>joins</primary><secondary>constant</secondary></indexterm>
+		Not all joins consist of only links between columns.  In some cases
+		you might have a schema in which one of the join criteria is
+		that a column in the source or target table must have some constant 
+		value.  OpenJPA calls joins involving constant values <emphasis>constant
+		joins</emphasis>.
+		</para>
+        <para>
+		To form a constant join in JPA mapping, first set the 
+		<literal>JoinColumn</literal>'s <literal>name</literal> attribute to 
+		the name of the column.  If the column with the constant value is the 
+		target of the join, give its fully qualified name in the form 
+		<literal>&lt;table name&gt;.&lt;column name&gt;</literal>.
+		Next, set the <literal>referencedColumnName</literal> attribute to the 
+		constant value.  If the constant value is a string, place it in single 
+		quotes to differentiate it from a column name.
+		</para>
+        <mediaobject>
+          <imageobject>
+<!-- PNG image data, 427 x 211 (see README) -->
+            <imagedata fileref="img/joins-constant.png" width="285px"/>
+          </imageobject>
+        </mediaobject>
+        <para>
+		Consider the tables above.  First, we want to join row 
+		<literal>T1.R1</literal> to row <literal>T2.R1</literal>.  If we just
+		join column <literal>T1.FK</literal> to <literal>T2.PK1</literal>, we
+		will wind up matching both <literal>T2.R1</literal> and <literal>
+		T2.R2</literal>.  So in addition to joining <literal>T1.FK</literal>
+		to <literal>T2.PK1</literal>, we also have to specify that 
+		<literal>T2.PK2</literal> has the value <literal>a</literal>.  Here is
+		how we'd accomplish this in mapping metadata.
+		</para>
+        <programlisting format="linespecific"> 
+@Entity
+@Table(name="T1")
+public class ...
+{
+    @ManyToOne
+    @JoinColumns({
+        @JoinColumn(name="FK" referencedColumnName="PK1"),
+        @JoinColumn(name="T2.PK2" referencedColumnName="'a'")
+    });
+    private ...;
+}
+</programlisting>
+        <para>
+		Notice that we had to fully qualify the name of column <literal>PK2
+		</literal> because it is in the target table.  Also notice that we put
+		single quotes around the constant value so that it won't be confused
+		with a column name.  You do not need single quotes for numeric 
+		constants.  For example, the syntax to join <literal>T1.R2</literal> to 
+		<literal>T2.R4</literal> is:
+		</para>
+        <programlisting format="linespecific"> 
+@Entity
+@Table(name="T1")
+public class ...
+{
+    @ManyToOne
+    @JoinColumns({
+        @JoinColumn(name="FK" referencedColumnName="PK2"),
+        @JoinColumn(name="T2.PK1" referencedColumnName="2")
+    });
+    private ...;
+}
+</programlisting>
+        <para>
+		Finally, from the inverse direction, these joins would look like this:
+		</para>
+        <programlisting format="linespecific"> 
+@Entity
+@Table(name="T2")
+public class ...
+{
+    @ManyToOne
+    @JoinColumns({
+        @JoinColumn(name="T1.FK" referencedColumnName="PK1"),
+        @JoinColumn(name="PK2" referencedColumnName="'a'")
+    });
+    private ...;
+
+    @ManyToOne
+    @JoinColumns({
+        @JoinColumn(name="T1.FK" referencedColumnName="PK2"),
+        @JoinColumn(name="PK1" referencedColumnName="2")
+    });
+    private ...;
+}
+</programlisting>
+      </section>
+      <section id="ref_guide_mapping_ejb">
+        <title>Additional JPA Mappings</title>
+        <indexterm zone="ref_guide_mapping_ejb">
+          <primary>mapping metadata</primary>
+          <secondary>JPA additions</secondary>
+        </indexterm>
+        <para>
+		OpenJPA supports many persistence strategies beyond those of the JPA
+		specification.  <xref linkend="ref_guide_meta_ejb"/>
+		covered the logical metadata for OpenJPA's additional persistence 
+		strategies.  We now demonstrate how to map entities using these 
+		strategies to the database.
+		</para>
+        <section id="ref_guide_mapping_ejb_datastoreid">
+          <title>Datastore Identity Mapping</title>
+          <indexterm zone="ref_guide_mapping_ejb_datastoreid">
+            <primary>datastore identity</primary>
+            <secondary>mapping</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_ejb_datastoreid">
+            <primary>mapping metadata</primary>
+            <secondary>datastore identity</secondary>
+            <seealso>identity</seealso>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_ejb_datastoreid">
+            <primary>DataStoreIdColumn</primary>
+            <seealso>mapping metadata</seealso>
+          </indexterm>
+          <indexterm>
+            <primary>primary key</primary>
+          </indexterm>
+          <para><xref linkend="ref_guide_pc_oid"/> describes how to use datastore
+			identity in JPA.  OpenJPA requires a single numeric 
+			primary key column to hold datastore identity values.  The
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/DataStoreIdColumn.html"><classname>org.apache.openjpa.persistence.jdbc.DataStoreIdColumn</classname></ulink> annotation customizes the datastore identity column.  This 
+			annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>:  Defaults to 
+					<literal>ID</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>int precision</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>String columnDefinition</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>boolean insertable</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>boolean updatable</literal>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			All properties correspond exactly to the same-named properties on 
+			the standard <classname>Column</classname> annotation, described in
+			<xref linkend="jpa_overview_mapping_column"/>.
+			</para>
+          <example id="ref_guide_mapping_ejb_datastoreidex">
+            <title>Datastore Identity Mapping</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+@Table(name="LOGS")
+@DataStoreIdColumn(name="ENTRY")
+public class LogEntry
+{
+    @Lob
+    private String content;
+
+    ...
+}
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_mapping_ejb_version">
+          <title>Surrogate Version Mapping</title>
+          <indexterm zone="ref_guide_mapping_ejb_datastoreid">
+            <primary>version</primary>
+            <secondary>mapping</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_ejb_version">
+            <primary>mapping metadata</primary>
+            <secondary>version</secondary>
+            <seealso>version</seealso>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_ejb_version">
+            <primary>VersionColumn</primary>
+            <seealso>mapping metadata</seealso>
+          </indexterm>
+          <para>
+			OpenJPA supports version fields as defined by the JPA
+			specification, but allows you to use a surrogate version column
+			in place of a version field if you like.  You map the surrogate 
+			version column with the 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionColumn.html"><classname>org.apache.openjpa.persistence.jdbc.VersionColumn</classname></ulink> 
+			annotation.  If you take advantage of OpenJPA's ability to define
+			multiple <link linkend="ref_guide_lock_groups">lock groups</link>,
+			you may have multiple version columns.  In that case, use the 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionColumns.html"><classname>org.apache.openjpa.persistence.jdbc.VersionColumns</classname></ulink> 
+			annotation to declare an array of 
+			<classname>VersionColumn</classname> values.
+			Each <classname>VersionColumn</classname> has the following 
+			properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>:  Defaults to 
+					<literal>VERSN</literal>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>String lockGroup</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>int length</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>int precision</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>int scale</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>String columnDefinition</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>boolean nullable</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>boolean insertable</literal>
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                <literal>boolean updatable</literal>
+              </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The <literal>lockGroup</literal> property allows you to specify that
+			a version column is for some lock group other than the default
+			group.  See <xref linkend="ref_guide_lock_groups"/> for an example.
+			All other properties correspond exactly to the same-named 
+			properties on the standard <classname>Column</classname> annotation,
+			described in <xref linkend="jpa_overview_mapping_column"/>.
+			</para>
+          <para>
+			By default, OpenJPA assumes that surrogate versioning uses a version
+			number strategy.  You can choose a different strategy with the
+			<classname>VersionStrategy</classname> annotation described in
+			<xref linkend="version-strategy"/>.
+			</para>
+        </section>
+        <section id="ref_guide_mapping_ejb_columns">
+          <title>Multi-Column Mappings</title>
+          <indexterm zone="ref_guide_mapping_ejb_columns">
+            <primary>mapping metadata</primary>
+            <secondary>column</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_ejb_columns">
+            <primary>mapping metadata</primary>
+            <secondary>multi-column mappings</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_mapping_ejb_columns">
+            <primary>Columns</primary>
+            <seealso>mapping metadata</seealso>
+          </indexterm>
+          <para>
+			OpenJPA makes it easy to create multi-column 
+			<link linkend="ref_guide_mapping_custom_field">custom 
+			mappings</link>.  The JPA specification includes a
+			<classname>Column</classname> annotation, but is missing a way to
+			declare multiple columns for a single field.  OpenJPA remedies this
+			with the 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Columns.html"><classname>org.apache.openjpa.persistence.jdbc.Columns</classname></ulink>
+			annotation, which contains an array of <classname>Column</classname>
+			values.  <xref linkend="ref_guide_mapping_custom_field_conf_extex"/>
+			uses OpenJPA's <classname>Columns</classname> annotation to map a
+			<classname>java.awt.Point</classname> to separate X and Y columns.
+			</para>
+          <para>
+			Remember to annotate custom field types with <classname>
+			Persistent</classname>, as described in
+			<xref linkend="ref_guide_meta_ejb_persistent"/>.
+			</para>
+        </section>
+        <section id="ref_guide_mapping_ejb_fieldjoin">
+          <title>Join Column Attribute Targets</title>
+          <para><xref linkend="jpa_overview_mapping_rel"/> in the JPA
+			Overview introduced you to the <classname>JoinColumn</classname>
+			annotation.  A <classname>JoinColumn</classname>'s <literal>
+			referencedColumnName</literal> property declares which column in
+			the table of the related type this join column links to.  Suppose, 
+			however, that the related type is unmapped, or that it is part of
+			a table-per-class inheritance hierarchy.  Each subclass that might
+			be assigned to the field could reside in a different table, and
+			could use entirely different names for its primary key columns.  
+			It becomes impossible to supply a single <literal>
+			referencedColumnName</literal> that works for all subclasses.
+			</para>
+          <para>
+			OpenJPA rectifies this by allowing you to declare which 
+			<emphasis>attribute</emphasis> in the related type each join column
+			links to, rather than which column.  If the attribute is mapped 
+			differently in various subclass tables, OpenJPA automatically forms the
+			proper join for the subclass record at hand.  The
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/XJoinColumn.html"><classname>org.apache.openjpa.persistence.jdbc.XJoinColumn</classname></ulink>
+			annotation has all the same properties as the standard 
+			<classname>JoinColumn</classname> annotation, but adds an
+			additional <literal>referencedAttributeName</literal> property for
+			this purpose.  Simply use a <classname>XJoinColumn</classname>
+			in place of a <classname>JoinColumn</classname> whenever you need
+			to access this added functionality.
+			</para>
+          <para>
+			For compound keys, use the
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/XJoinColumns.html"><classname>org.apache.openjpa.persistence.jdbc.XJoinColumns</classname></ulink> annotation.  The value of this annotation is an array of
+			individual <classname>XJoinColumn</classname>s.
+			</para>
+        </section>
+        <section id="ref_guide_mapping_ejb_embed">
+          <title>Embedded Mapping</title>
+          <para>
+			JPA uses the <classname>AttributeOverride</classname>
+			annotation to override the default mappings of an embeddable
+			class.  The JPA Overview details this process in
+			<xref linkend="jpa_overview_mapping_embed"/>.  <classname>
+			AttributeOverride</classname>s suffice for simple mappings, but
+			do not allow you to override complex mappings.  Also, JPA 
+			has no way to differentitate between a null embedded
+			object and one with default values for all of its fields.
+			</para>
+          <para>
+			OpenJPA overcomes these shortcomings with the 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EmbeddedMapping.html"><classname>org.apache.openjpa.persistence.jdbc.EmbeddedMapping</classname></ulink>
+			annotation.  This annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String nullIndicatorColumnName</literal>: If the
+					named column's value is <literal>NULL</literal>, then the 
+					embedded object is assumed to be null.  If the named column
+					has a non-<literal>NULL</literal> value, then the embedded 
+					object will get loaded and 
+					populated with data from the other embedded fields.  
+					This property is entirely optional.  By default, OpenJPA 
+					always assumes the embedded object is non-null, just as
+					in standard JPA mapping.
+					</para>
+              <para>
+					If the column you name does not belong to any fields of the 
+					embedded object, OpenJPA will create a synthetic null-indicator
+					column with this name.  In fact, you can specify a value of
+					<literal>true</literal> to simply indicate that you want
+					a synthetic null-indicator column, without having to 
+					come up with a name for it.  A value of <literal>false
+					</literal> signals that you explicitly do not want a
+					null-indicator column created for this mapping (in case you
+					have configured your 
+					<link linkend="ref_guide_mapping_defaults">mapping defaults
+					</link> to create one by default).
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>String nullIndicatorFieldName</literal>: Rather 
+					than name a null indicator column, you can name a field of
+					the embedded type.  OpenJPA will use the column of this field
+					as the null-indicator column.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>MappingOverride[] overrides</literal>: This array
+					allows you to override any mapping of the embedded object.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The <classname>EmbeddedMapping</classname>'s 
+			<literal>overrides</literal> array serves the same purpose as
+			standard JPA's <classname>AttributeOverride</classname>s and
+			<classname>AssociationOverride</classname>s.  In fact,
+			you can also use the <classname>MappingOverride</classname> 
+			annotation on an entity class to override a complex mapping of its
+			mapped superclass, just as you can with <classname>
+			AttributeOverride</classname> and <classname>
+			AssociationOverride</classname>s.  The <classname>MappingOverrides
+			</classname> annotation, whose value is an array of
+			<classname>MappingOverride</classname>s, allows you to overide
+			multiple mapped superclass mappings.
+			</para>
+          <para>
+			Each
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/MappingOverride.html"><classname>org.apache.openjpa.persistence.jdbc.MappingOverride</classname></ulink>
+			annotation has the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of the field
+					that is being overridden.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>Column[] columns</literal>: Columns for the new
+					field mapping.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>XJoinColumn[] joinColumns</literal>: Join 
+					columns for the new field mapping, if it is a relation 
+					field.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>ContainerTable containerTable</literal>: Table
+					for the new collection or map field mapping.  We 
+					cover collection mappings in
+					<xref linkend="ref_guide_mapping_ejb_coll"/>, and map 
+					mappings in
+					<xref linkend="ref_guide_mapping_ejb_map"/>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>ElementColumn[] elementColumns</literal>: Element 
+					columns for the new collection or map field mapping.
+					You will see how to use element columns in
+					<xref linkend="ref_guide_mapping_ejb_coll_cols"/>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>ElementJoinColumn[] elementJoinColumns</literal>: 
+					Element join columns for the new collection or map 
+					field mapping.  You will see how to use element join 
+					columns in
+					<xref linkend="ref_guide_mapping_ejb_coll_joincols"/>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>KeyColumn[] keyColumns</literal>: Map key 
+					columns for the new map field mapping.
+					You will see how to use key columns in
+					<xref linkend="ref_guide_mapping_ejb_map_keycols"/>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>KeyJoinColumn[] keyJoinColumns</literal>: 
+					Key join columns for the new map field mapping.
+					You will see how to use key join columns in
+					<xref linkend="ref_guide_mapping_ejb_map_keyjoincols"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			The following example defines an embeddable <classname>
+			PathCoordinate</classname> class with a custom
+			mapping of a <classname>java.awt.Point</classname> field to two
+			columns.  It then defines an entity which embeds a <classname>
+			PointCoordinate</classname> and overrides the default 
+			mapping for the point field.  The entity also declares that if the
+			<classname>PathCoordinate</classname>'s <literal>siteName</literal>
+			field column is null, it means that no <classname>PathCoordinate
+			</classname> is stored in the embedded record; the owning field
+			will load as null.
+			</para>
+          <example id="ref_guide_mapping_ejb_embedex">
+            <title>Overriding Complex Mappings</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Embeddable
+public class PathCoordinate
+{
+    private String siteName;
+
+    @Persistent
+    @Strategy("com.xyz.openjpa.PointValueHandler")
+    private Point point;
+
+    ...
+}
+
+@Entity
+public class Path
+{
+    @Embedded
+    @EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={
+        @MappingOverride(name="siteName", columns=@Column(name="START_SITE")),
+        @MappingOverride(name="point", columns={
+            @Column(name="START_X"),
+            @Column(name="START_Y")
+        })
+    })
+    private PathCoordinate start;
+
+    ...
+}
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_mapping_ejb_coll">
+          <title>Collections</title>
+          <indexterm zone="ref_guide_mapping_ejb_coll">
+            <primary>mapping metadata</primary>
+            <secondary>collections</secondary>
+          </indexterm>
+          <para>
+			In <xref linkend="ref_guide_meta_ejb_persistent_coll"/>, we 
+			explored the <classname>PersistentCollection</classname> annotation
+			for persistent collection fields that aren't a standard
+			<literal>OneToMany</literal> or <literal>ManyToMany</literal>
+			relation.  To map these non-standard collections, combine OpenJPA's
+			<classname>ContainerTable</classname> annotation with <classname>
+			ElementColumn</classname>s, <classname>
+			ElementJoinColumn</classname>s, or an <classname>
+			ElementEmbeddedMapping</classname>.  We explore the annotations
+			below.
+			</para>
+          <section id="ref_guide_mapping_ejb_coll_table">
+            <title>Container Table</title>
+            <indexterm zone="ref_guide_mapping_ejb_coll_table">
+              <primary>ContainerTable</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ContainerTable.html"><classname>org.apache.openjpa.persistence.jdbc.ContainerTable</classname></ulink> annotation describes a database table that holds 
+				collection (or map) elements.  This annotation has the 
+				following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+                  <literal>String name</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>String catalog</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>String schema</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>XJoinColumn[] joinColumns</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>ForeignKey joinForeignKey</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>Index joinIndex</literal>
+                </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				The <literal>name</literal>, <literal>catalog</literal>, 
+				<literal>schema</literal>, and <literal>joinColumns</literal>
+				properties describe the container table and how it joins to 
+				the owning entity's table.  These properties correspond 
+				to the same-named properties on the standard <classname>
+				JoinTable</classname> annotation, described in
+				<xref linkend="jpa_overview_mapping_assoccoll"/>.  If left
+				unspecified, the name of the table defaults to 
+				the first five characters of the entity table name, plus an
+				underscore, plus the field name.  The
+				<literal>joinForeignKey</literal> and <literal>
+				joinIndex</literal> properties override default foreign key
+				and index generation for the join columns.  We explore foreign
+				keys and indexes later in this chapter.
+				</para>
+            <para>
+				You may notice that the container table does not define how
+				to store the collection elements.  That is left to separate
+				annotations, which are the subject of the next sections.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_coll_cols">
+            <title>Element Columns</title>
+            <indexterm zone="ref_guide_mapping_ejb_coll_cols">
+              <primary>ElementColumn</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				Just as the JPA <classname>Column</classname>	
+				annotation maps a simple value (primitive wrapper, <classname>
+				String</classname>, etc), OpenJPA's
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementColumn.html"><classname>org.apache.openjpa.persistence.jdbc.ElementColumn</classname></ulink> annotation maps a simple element value.  To map custom
+				multi-column elements, use the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementColumns.html"><classname>org.apache.openjpa.persistence.jdbc.ElementColumns</classname></ulink> annotation, whose value is an array of <classname>
+				ElementColumn</classname>s.
+				</para>
+            <para>
+				An <classname>ElementColumn</classname> always resides in 
+				a container table, so it does not have the <literal>
+				table</literal> property of a standard <classname>
+				Column</classname>.  Otherwise, the <classname>ElementColumn
+				</classname> and standard <classname>Column</classname> 
+				annotations are equivalent.  See
+				<xref linkend="jpa_overview_mapping_column"/> in the JPA 
+				Overview for a review of the <classname>Column
+				</classname> annotation.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_coll_joincols">
+            <title>Element Join Columns</title>
+            <indexterm zone="ref_guide_mapping_ejb_coll_joincols">
+              <primary>ElementJoinColumn</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				Element join columns are equivalent to standard JPA
+				join columns, except that they represent a join to a collection
+				or map element entity rather than a direct relation.  You 
+				represent an element join column with OpenJPA's
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementJoinColumn.html"><classname>org.apache.openjpa.persistence.jdbc.ElementJoinColumn</classname></ulink> annotation.  To declare a compound join, enclose an
+				array of <classname>ElementJoinColumn</classname>s in the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementJoinColumns.html"><classname>org.apache.openjpa.persistence.jdbc.ElementJoinColumns</classname></ulink> annotation.
+				</para>
+            <para>
+				An <classname>ElementJoinColumn</classname> always resides in 
+				a container table, so it does not have the <literal>
+				table</literal> property of a standard <classname>
+				JoinColumn</classname>.  Like <classname>
+				XJoinColumn</classname>s above, <classname>
+				ElementJoinColumn</classname>s can reference a linked attribute 
+				rather than a static linked column.  Otherwise, the <classname>
+				ElementJoinColumn</classname> and standard <classname>JoinColumn
+				</classname> annotations are equivalent.  See
+				<xref linkend="jpa_overview_mapping_rel"/> in the JPA 
+				Overview for a review of the <classname>JoinColumn
+				</classname> annotation.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_coll_embed">
+            <title>Element Embedded Mapping</title>
+            <indexterm zone="ref_guide_mapping_ejb_coll_embed">
+              <primary>ElementEmbeddedMapping</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementEmbeddedMapping.html"><classname>org.apache.openjpa.persistence.jdbc.ElementEmbeddedMapping
+				</classname></ulink> annotation allows you to map your
+				collection or map's embedded element type to your container 
+				table.  This annotation has exactly the same properties as the 
+				<classname>EmbeddedMapping</classname> annotation described
+				<link linkend="ref_guide_mapping_ejb_embed">above</link>.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_coll_order">
+            <title>Order Column</title>
+            <indexterm zone="ref_guide_mapping_ejb_coll_order">
+              <primary>OrderColumn</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				Relational databases do not guarantee that records are returned
+				in insertion order.  If you want to make sure that your 
+				collection elements are loaded in the same order they were in
+				when last stored, you must declare an order column.  OpenJPA's
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/OrderColumn"><classname>org.apache.openjpa.persistence.jdbc.OrderColumn</classname></ulink>
+				annotation has the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>String name</literal>:  Defaults to 
+						<literal>ORDR</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>boolean enabled</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>int precision</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>String columnDefinition</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>boolean insertable</literal>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <literal>boolean updatable</literal>
+                </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				Order columns are always in the container table.
+				You can explicitly turn off ordering (if you have enabled it
+				by default via your <link linkend="ref_guide_mapping_defaults">
+				mapping defaults</link>) by setting the <literal>enabled
+				</literal> property to <literal>false</literal>.  All other 
+				properties correspond exactly to the same-named properties on 
+				the standard <classname>Column</classname> annotation, 
+				described in <xref linkend="jpa_overview_mapping_column"/>.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_coll_ex">
+            <title>Examples</title>
+            <mediaobject>
+              <imageobject>
+<!-- PNG image data, 383 x 176 (see README) -->
+                <imagedata fileref="img/basic-coll.png" width="255px"/>
+              </imageobject>
+            </mediaobject>
+            <para>
+				Our first example maps the <literal>Article.subtitles</literal>
+				field to the <literal>ART_SUBS</literal> container table, as
+				shown in the diagram above.  Notice the use of <classname>
+				ContainerTable</classname> in combination with 
+				<classname>ElementColumn</classname> and <classname>OrderColumn
+				</classname> to map this ordered list of strings.
+				</para>
+            <example id="ref_guide_mapping_ejb_coll_simpleex">
+              <title>String List Mapping</title>
+              <programlisting format="linespecific">
+package org.mag;
+
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+@Table(name="ART")
+public class Article
+{
+    @Id private long id;
+
+    @PersistentCollection
+    @ContainerTable(name="ART_SUBS", joinColumns=@XJoinColumn(name="ART_ID"))
+    @ElementColumn(name="SUBTITLE")
+    @OrderColumn(name="ORD")
+    private List&lt;String&gt; subtitles;
+
+    ...
+}
+</programlisting>
+            </example>
+            <para>
+				Now we map a collection of embedded <classname>Address
+				</classname> objects for a <classname>Company</classname>,
+				according to the following diagram:
+				</para>
+            <mediaobject>
+              <imageobject>
+<!-- PNG image data, 545 x 239 (see README) -->
+                <imagedata fileref="img/embedded-coll.png" width="363px"/>
+              </imageobject>
+            </mediaobject>
+            <example id="ref_guide_mapping_ejb_coll_embedex">
+              <title>Embedded Element Mapping</title>
+              <programlisting format="linespecific">
+package org.mag.pub;
+
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Embeddable
+public class Address
+{
+    ...
+}
+
+@Entity
+@Table(name="COMP")
+public class Company
+{
+    @Id private long id;
+  
+    @PersistentCollection(elementEmbedded=true)
+    @ContainerTable(name="COMP_ADDRS", joinColumns=@XJoinColumn(name="COMP_ID"))
+    @ElementEmbeddedMapping(overrides=@MappingOverride(name="state", 
+        columns=@Column(columnDefinition="CHAR(2)")))
+    private Collection&lt;Address&gt; addresses;
+
+    ...
+}
+</programlisting>
+            </example>
+          </section>
+        </section>
+        <section id="ref_guide_mapping_ejb_onemany">
+          <title>One-Sided One-Many Mapping</title>
+          <indexterm zone="ref_guide_mapping_ejb_onemany">
+            <primary>mapping metadata</primary>
+            <secondary>collections</secondary>
+            <tertiary>JPA one-sided one-many</tertiary>
+          </indexterm>
+          <para>
+			The previous section covered the use of <classname>ElementJoinColumn
+			</classname> annotations in conjunction with a <classname>
+			ContainerTable</classname> for mapping collections to dedicate 
+			tables. <classname>ElementJoinColumn</classname>s, however, have 
+			one additional use: to create a one-sided one-many mapping.  
+			Standard JPA supports <classname>OneToMany</classname> 
+			fields without a <literal>mappedBy</literal> inverse, but only by 
+			mapping these fields to a <classname>JoinTable</classname> (see
+			<xref linkend="jpa_overview_mapping_assoccoll"/> in the JPA
+			Overview for details).  Often, you'd like to create
+			a one-many association based on an inverse foreign key (logical
+			or actual) in the table of the related type.
+			</para>
+          <mediaobject>
+            <imageobject>
+<!-- PNG image data, 392 x 192 (see README) -->
+              <imagedata fileref="img/inv-key-coll.png" width="261"/>
+            </imageobject>
+          </mediaobject>
+          <para>
+			Consider the model above.  <classname>Subscription</classname> has
+			a collection of <classname>LineItem</classname>s, but <classname>
+			LineItem</classname> has no inverse relation to <classname>
+			Subscription</classname>.  To retrieve all of the <classname>
+			LineItem</classname> records for a <classname>
+			Subscription</classname>, we join the <literal>SUB_ID</literal>
+			inverse foreign key column in the <literal>LINE_ITEM</literal>
+			table to the primary key column of the <literal>SUB</literal> 
+			table.  The example below shows how to represent this model in
+			mapping annotations.  Note that OpenJPA automatically assumes an 
+			inverse foreign key mapping when element join columns are given, but
+			no container or join table is given.
+			</para>
+          <example id="ref_guide_mapping_ejb_onemanyex">
+            <title>One-Sided One-Many Mapping</title>
+            <programlisting format="linespecific">
+package org.mag.subscribe;
+
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+@Table(name="LINE_ITEM", schema="CNTRCT")
+public class LineItem
+{
+    ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+public class Subscription
+{
+    @Id private long id;
+
+    @OneToMany
+    @ElementJoinColumn(name="SUB_ID", target="ID")
+    private Collection&lt;LineItem&gt; items;
+
+    ...
+}
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_mapping_ejb_map">
+          <title>Maps</title>
+          <indexterm zone="ref_guide_mapping_ejb_map">
+            <primary>mapping metadata</primary>
+            <secondary>maps</secondary>
+          </indexterm>
+          <para><xref linkend="ref_guide_meta_ejb_persistent_map"/> discussed
+			the <classname>PersistentMap</classname> annotation for persistent 
+			map fields. To map these non-standard fields to the database, 
+			combine OpenJPA's <classname>ContainerTable</classname> annotation 
+			with <classname>KeyColumn</classname>s, <classname>
+			KeyJoinColumn</classname>s, or an <classname>
+			KeyEmbeddedMapping</classname> and
+			<classname>ElementColumn</classname>s, <classname>
+			ElementJoinColumn</classname>s, or an <classname>
+			ElementEmbeddedMapping</classname>.
+			</para>
+          <para>
+			We detailed the <literal>ContainerTable</literal> annotation in
+			<xref linkend="ref_guide_mapping_ejb_coll_table"/>.
+			We also discussed element columns, join columns, and embedded 
+			mappings in <xref linkend="ref_guide_mapping_ejb_coll_cols"/>,
+			<xref linkend="ref_guide_mapping_ejb_coll_joincols"/>, and
+			<xref linkend="ref_guide_mapping_ejb_coll_embed"/>.
+			Key columns, join columns, and embedded mappings are new, however;
+			we tackle them below.
+			</para>
+          <section id="ref_guide_mapping_ejb_map_keycols">
+            <title>Key Columns</title>
+            <indexterm zone="ref_guide_mapping_ejb_map_keycols">
+              <primary>KeyColumn</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				Key columns serve the same role for map keys as the element 
+				columns described in 
+				<xref linkend="ref_guide_mapping_ejb_coll_cols"/> serve for 
+				collection elements.  OpenJPA's
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyColumn.html"><classname>org.apache.openjpa.persistence.jdbc.KeyColumn</classname></ulink> annotation represents a map key.  To map custom
+				multi-column keys, use the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyColumns.html"><classname>org.apache.openjpa.persistence.jdbc.KeyColumns</classname></ulink> annotation, whose value is an array of <classname>
+				KeyColumn</classname>s.
+				</para>
+            <para>
+				A <classname>KeyColumn</classname> always resides in 
+				a container table, so it does not have the <literal>
+				table</literal> property of a standard <classname>
+				Column</classname>.  Otherwise, the <classname>KeyColumn
+				</classname> and standard <classname>Column</classname> 
+				annotations are equivalent.  See
+				<xref linkend="jpa_overview_mapping_column"/> in the JPA 
+				Overview for a review of the <classname>Column
+				</classname> annotation.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_map_keyjoincols">
+            <title>Key Join Columns</title>
+            <indexterm zone="ref_guide_mapping_ejb_map_keyjoincols">
+              <primary>KeyJoinColumn</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				Key join columns are equivalent to standard JPA
+				join columns, except that they represent a join to a map
+				key entity rather than a direct relation.  You represent
+				a key join column with OpenJPA's
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyJoinColumn.html"><classname>org.apache.openjpa.persistence.jdbc.KeyJoinColumn</classname></ulink> annotation.  To declare a compound join, enclose an
+				array of <classname>KeyJoinColumn</classname>s in the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyJoinColumns.html"><classname>org.apache.openjpa.persistence.jdbc.KeyJoinColumns</classname></ulink> annotation.
+				</para>
+            <para>
+				A <classname>KeyJoinColumn</classname> always resides in 
+				a container table, so it does not have the <literal>
+				table</literal> property of a standard <classname>
+				JoinColumn</classname>.  Like <classname>
+				XJoinColumn</classname>s above, <classname>
+				KeyJoinColumn</classname>s can reference a linked field 
+				rather than a static linked column.  Otherwise, the <classname>
+				KeyJoinColumn</classname> and standard <classname>JoinColumn
+				</classname> annotations are equivalent.  See
+				<xref linkend="jpa_overview_mapping_rel"/> in the JPA 
+				Overview for a review of the <classname>JoinColumn
+				</classname> annotation.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_map_embedkey">
+            <title>Key Embedded Mapping</title>
+            <indexterm zone="ref_guide_mapping_ejb_map_embedkey">
+              <primary>KeyEmbeddedMapping</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyEmbeddedMapping.html"><classname>org.apache.openjpa.persistence.jdbc.KeyEmbeddedMapping</classname></ulink> annotation allows you to map your map field's embedded
+				key type to your container table.  This annotation has exactly 
+				the same properties as the 
+				<classname>EmbeddedMapping</classname> annotation described
+				<link linkend="ref_guide_mapping_ejb_embed">above</link>.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_map_ex">
+            <title>Examples</title>
+            <mediaobject>
+              <imageobject>
+<!-- PNG image data, 410 x 266 (see README) -->
+                <imagedata fileref="img/string-rel-map.png" width="273px"/>
+              </imageobject>
+            </mediaobject>
+            <para>
+				Map mapping in OpenJPA uses the same principles you saw in 
+				collection mapping.  The example below maps the <literal>
+				Article.authors</literal> map according to the diagram above.
+				</para>
+            <example id="ref_guide_mapping_ejb_map_stringrelmap">
+              <title>String Key, Entity Value Map Mapping</title>
+              <programlisting format="linespecific">
+package org.mag.pub;
+
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+@Table(name="AUTH")
+@DataStoreIdColumn(name="AID" columnDefinition="INTEGER64")
+public class Author
+{
+    ...
+}
+
+package org.mag;
+
+@Entity
+@Table(name="ART")
+public class Article
+{
+    @Id private long id;
+ 
+    @PersistentMap
+    @ContainerTable(name="ART_AUTHS", joinColumns=@XJoinColumn(name="ART_ID"))
+    @KeyColumn(name="LNAME")
+    @ElementJoinColumn(name="AUTH_ID")
+    private Map&lt;String,Author&gt; authors;
+
+    ...
+}
+</programlisting>
+            </example>
+          </section>
+        </section>
+        <section id="ref_guide_mapping_ejb_constraints">
+          <title>Indexes and Constraints</title>
+          <para>
+			OpenJPA uses index information during schema generation to index
+			the proper columns.  OpenJPA uses foreign key and unique constraint
+			information during schema creation to generate the proper database
+			constraints, and also at runtime to order SQL statements to avoid 
+			constraint violations while maximizing SQL batch size.	
+			</para>
+          <para>
+			OpenJPA assumes certain columns have indexes or constraints based
+			on your mapping defaults, as detailed in
+			<xref linkend="ref_guide_mapping_defaults"/>.  You can override
+			the configured defaults on individual joins, field values, 
+			collection elements, map keys, or map values using the annotations
+			presented in the following sections.
+			</para>
+          <section id="ref_guide_mapping_ejb_index">
+            <title>Indexes</title>
+            <indexterm zone="ref_guide_mapping_ejb_index">
+              <primary>mapping metadata</primary>
+              <secondary>indexes</secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_mapping_ejb_index">
+              <primary>indexes</primary>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Index.html"><classname>org.apache.openjpa.persistence.jdbc.Index</classname></ulink>
+				annotation represents an index on the columns of a field.  It
+				is also used within the 
+				<link linkend="ref_guide_mapping_ejb_coll_table"><classname>
+				ConterainTable</classname></link> annotation to index join 
+				columns.
+				</para>
+            <para>
+				To index the columns of a collection or map element or map key, 
+				use the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementIndex.html"><classname>
+				org.apache.openjpa.persistence.jdbc.ElementIndex</classname></ulink> and
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyIndex.html"><classname>org.apache.openjpa.persistence.jdbc.KeyIndex</classname></ulink>
+				annotations, respectively.  These annotations have the
+				following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>boolean enabled</literal>: Set this property
+						to <literal>false</literal> to explicitly tell OpenJPA not
+						to index these columns, when OpenJPA would otherwise do so.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>String name</literal>: The name of the index.
+						OpenJPA will choose a name if you do not provide one.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>boolean unique</literal>: Whether to create
+						a unique index.  Defaults to false.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="ref_guide_mapping_ejb_fk">
+            <title>Foreign Keys</title>
+            <indexterm zone="ref_guide_mapping_ejb_fk">
+              <primary>mapping metadata</primary>
+              <secondary>foreign keys</secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_mapping_ejb_fk">
+              <primary>foreign keys</primary>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ForeignKey.html"><classname>org.apache.openjpa.persistence.jdbc.ForeignKey</classname></ulink>
+				annotation represents a foreign key on the columns of a field.
+				It is also used within the 
+				<link linkend="ref_guide_mapping_ejb_coll_table"><classname>
+				ContainerTable</classname></link>
+				annotation to set a database foreign key on join columns.
+				</para>
+            <para>
+				To set a constraint to the columns of a collection or map
+				element or map value, use the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementForeignKey.html"><classname>
+				org.apache.openjpa.persistence.jdbc.ElementForeignKey</classname></ulink> and
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyForeignKey.html"><classname>
+				org.apache.openjpa.persistence.jdbc.KeyForeignKey</classname></ulink>
+				annotations, respectively.  These annotations 
+				have the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>boolean enabled</literal>: Set this property
+						to <literal>false</literal> to explicitly tell OpenJPA not
+						to set a foreign key on these columns, when OpenJPA would 
+						otherwise do so.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>String name</literal>: The name of the foreign
+						key.  OpenJPA will choose a name if you do not provide one,
+						or will create an anonymous key.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>boolean deferred</literal>: Whether to create
+						a deferred key if supported by the database.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>ForeignKeyAction deleteAction</literal>: 
+						Value from the 
+						<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ForeignKeyAction.html"><classname>org.apache.openjpa.persistence.jdbc.ForeignKeyAction
+						</classname></ulink> enum identifying the desired 
+						delete action.  Defaults to <literal>RESTRICT</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>ForeignKeyAction updateAction</literal>: 
+						Value from the 
+						<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ForeignKeyAction.html"><classname>org.apache.openjpa.persistence.jdbc.ForeignKeyAction
+						</classname></ulink> enum identifying the desired 
+						update action.  Defaults to <literal>RESTRICT</literal>.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				Keep in mind that OpenJPA uses foreign key information at runtime
+				to avoid constraint violations; it is important, therefore,
+				that your <link linkend="ref_guide_mapping_defaults">mapping
+				defaults</link> and foreign key annotations combine to 
+				accurately reflect your existing database constraints.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_ejb_unique">
+            <title>Unique Constraints</title>
+            <indexterm zone="ref_guide_mapping_ejb_unique">
+              <primary>mapping metadata</primary>
+              <secondary>unique constraints</secondary>
+            </indexterm>
+            <indexterm zone="ref_guide_mapping_ejb_unique">
+              <primary>unique constraints</primary>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Unique.html"><classname>org.apache.openjpa.persistence.jdbc.Unique</classname></ulink>
+				annotation represents a unqiue constraint on the columns of a 
+				field.  It is more convenient than using the <literal>
+				uniqueConstraints</literal> property of standard JPA
+				<classname>Table</classname> and <classname>SecondaryTable
+				</classname> annotations, because you can apply it directly to
+				the constrained field.  The <classname>Unique</classname> 
+				annotation has the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>boolean enabled</literal>: Set this property
+						to <literal>false</literal> to explicitly tell OpenJPA not
+						to constrain these columns, when OpenJPA would otherwise 
+						do so.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>String name</literal>: The name of the 
+						constraint.  OpenJPA will choose a name if you do not 
+						provide one, or will create an anonymous constraint.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>boolean deferred</literal>: Whether to create
+						a deferred constraint if supported by the database.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="ref_guide_mapping_ejb_constraintex">
+            <title>Examples</title>
+            <para>
+				Here again is our map example from
+				<xref linkend="ref_guide_mapping_ejb_map"/>, now with 
+				explicit indexes and constraints added.
+				</para>
+            <mediaobject>
+              <imageobject>
+<!-- PNG image data, 410 x 266 (see README) -->
+                <imagedata fileref="img/string-rel-map.png" width="273px"/>
+              </imageobject>
+            </mediaobject>
+            <example id="ref_guide_mapping_ejb_constraintex_map">
+              <title>Constraint Mapping</title>
+              <programlisting format="linespecific">
+package org.mag.pub;
+
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+@Table(name="AUTH")
+@DataStoreIdColumn(name="AID" columnDefinition="INTEGER64")
+public class Author
+{
+    ...
+}
+
+package org.mag;
+
+@Entity
+@Table(name="ART")
+public class Article
+{
+    @Id private long id;
+ 
+    @PersistentMap
+    @ContainerTable(name="ART_AUTHS", joinColumns=@XJoinColumn(name="ART_ID")
+        joinForeignKey=@ForeignKey(deleteAction=ForeignKeyAction.CASCADE))
+    @KeyColumn(name="LNAME")
+    @KeyIndex(name="I_AUTH_LNAME")
+    @ElementJoinColumn(name="AUTH_ID")
+    @ElementForeignKey(deleteAction=ForeignKeyAction.RESTRICT)
+    private Map&lt;String,Author&gt; authors;
+
+    ...
+}
+</programlisting>
+            </example>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_mapping_limits">
+        <title>Mapping Limitations</title>
+        <indexterm zone="ref_guide_mapping_limits">
+          <primary>mapping metadata</primary>
+          <secondary>limitations</secondary>
+        </indexterm>
+        <para>
+		The following sections outline the limitations OpenJPA places on 
+		specific mapping strategies.
+		</para>
+        <section id="ref_guide_mapping_limits_tpc">
+          <title>Table Per Class</title>
+          <indexterm zone="ref_guide_mapping_limits">
+            <primary>mapping metadata</primary>
+            <secondary>limitations</secondary>
+            <tertiary>table-per-class</tertiary>
+          </indexterm>
+          <para>
+			Table-per-class inheritance mapping has the following limitations:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					You cannot traverse polymorphic relations to non-leaf
+					classes in a table-per-class inheritance hierarchy in
+					queries.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					You cannot map a one-sided polymorphic relation to a 
+					non-leaf class in a table-per-class inheritance hierarchy 
+					using an inverse foreign key. 
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					You cannot use an order column in a polymorphic
+					relation to a non-leaf class in a table-per-class 
+					inheritance hierarchy mapped with an inverse foreign key.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Table-per-class hierarchies impose limitations on eager
+					fetching.  See 
+					<xref linkend="ref_guide_perfpack_eager_consider"/>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+				Non-polymorphic relations do not suffer from these limitations.
+				You can declare a non-polymorphic relation using the extensions
+				described in <xref linkend="nonpolymorphic"/>.
+				</para>
+          </note>
+        </section>
+      </section>
+      <section id="ref_guide_mapping_ext">
+        <title>Mapping Extensions</title>
+        <para>
+		Mapping extensions allow you to access OpenJPA-specific 
+		functionality from your mappings.  Note that all extensions
+		below are specific to mappings.  If you store your mappings
+		separately from your persistence metadata, these extensions
+		must be specified along with the mapping information, not the 
+		persistence metadata information.
+		</para>
+        <section id="ref_guide_mapping_ext_cls">
+          <title>Class Extensions</title>
+          <para>
+			OpenJPA recognizes the following class extensions.
+			</para>
+          <section id="subclass-fetch-mode">
+            <title>Subclass Fetch Mode</title>
+            <indexterm zone="subclass-fetch-mode">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>subclass fetch mode</tertiary>
+              <seealso>eager fetching</seealso>
+            </indexterm>
+            <para>
+				This extension specifies how to eagerly fetch subclass state.  
+				It overrides the global 
+				<link linkend="openjpa.jdbc.SubclassFetchMode"><literal>
+				openjpa.jdbc.SubclassFetchMode</literal></link> property.  
+				<phrase>
+				Set the JPA 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/SubclassFetchMode.html"><classname>org.apache.openjpa.persistence.jdbc.SubclassFetchMode</classname></ulink> annotation to a value from the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EagerFetchType.html"><classname>org.apache.openjpa.persistence.jdbc.EagerFetchType</classname></ulink>enum: <literal>JOIN</literal>, 
+				<literal>PARALLEL</literal>, or <literal>NONE</literal>.
+				</phrase>
+				
+				See <xref linkend="ref_guide_perfpack_eager"/> for a 
+				discussion of eager fetching. 
+				</para>
+          </section>
+          <section id="class-strategy">
+            <title>Strategy</title>
+            <indexterm zone="strategy">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>strategy</tertiary>
+              <seealso>custom mapping</seealso>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html"><classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
+				class annotation allows you to specify a custom mapping 
+				strategy for your class.  See 
+				<xref linkend="ref_guide_mapping_custom"/> for information on
+				custom mappings.  
+				
+				</para>
+          </section>
+          <section id="discriminator-strategy">
+            <title>Discriminator Strategy</title>
+            <indexterm zone="strategy">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>discriminator strategy</tertiary>
+              <seealso>custom mapping</seealso>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy
+				</classname></ulink> class annotation allows you to specify a 
+				custom discriminator strategy.  See 
+				<xref linkend="ref_guide_mapping_custom"/> for information on
+				custom mappings.  
+				
+				</para>
+          </section>
+          <section id="version-strategy">
+            <title>Version Strategy</title>
+            <indexterm zone="strategy">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>version strategy</tertiary>
+              <seealso>custom mapping</seealso>
+            </indexterm>
+            <para>
+				The 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.VersionStrategy</classname></ulink> class annotation allows you to specify a custom 
+				version strategy.  See 
+				<xref linkend="ref_guide_mapping_custom"/> for information on
+				custom mappings.  
+				
+				</para>
+          </section>
+        </section>
+        <section id="ref_guide_mapping_ext_field">
+          <title>Field Extensions</title>
+          <para>
+			OpenJPA recognizes the following field extensions.
+			</para>
+          <section id="eager-fetch-mode">
+            <title>Eager Fetch Mode</title>
+            <indexterm zone="eager-fetch-mode">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>eager fetch mode</tertiary>
+              <seealso>eager fetching</seealso>
+            </indexterm>
+            <para>
+				This extension specifies how to eagerly fetch related objects.
+				It overrides the global 
+				<link linkend="openjpa.jdbc.EagerFetchMode"><literal>
+				openjpa.jdbc.EagerFetchMode</literal></link> property.  
+				<phrase>
+				Set the JPA 
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EagerFetchMode.html"><classname>org.apache.openjpa.persistence.jdbc.EagerFetchMode</classname></ulink> annotation to a value from the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EagerFetchType.html"><classname>org.apache.openjpa.persistence.jdbc.EagerFetchType</classname></ulink> enum: <literal>JOIN</literal>, 
+				<literal>PARALLEL</literal>, or <literal>NONE</literal>.
+				</phrase>
+				
+				See <xref linkend="ref_guide_perfpack_eager"/> for a 
+				discussion of eager fetching. 
+				</para>
+          </section>
+          <section id="nonpolymorphic">
+            <title>Nonpolymorphic</title>
+            <indexterm zone="nonpolymorphic">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>nonpolymorphic</tertiary>
+            </indexterm>
+            <para>
+				All fields in Java are polymorphic.  If you declare a
+				field of type <literal>T</literal>, you can assign any subclass
+				of <literal>T</literal> to the field as well.  This is very
+				convenient, but can make relation traversal very inefficient
+				under some inheritance strategies.  It can even make querying
+				across the field impossible.  Often, you know that certain
+				fields do not need to be entirely polymorphic.  By telling 
+				OpenJPA about such fields, you can improve the efficiency of your 
+				relations.
+				</para>
+            <note>
+              <para>
+					OpenJPA also includes the <literal>type</literal> metadata
+					extension for narrowing the declared type of a field
+					See <xref linkend="type"/>.  
+					</para>
+            </note>
+            <para>
+				OpenJPA JPA defines the following extensions for nonpolymorphic
+				values:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Nonpolymorphic.html">
+                    <classname>org.apache.openjpa.persistence.jdbc.Nonpolymorphic
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementNonpolymorphic.html">
+                    <classname>org.apache.openjpa.persistence.jdbc.ElementNonpolymorphic
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyNonpolymorphic.html">
+                    <classname>org.apache.openjpa.persistence.jdbc.KeyNonpolymorphic
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				The value of these extensions is a constant from the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/NonpolymorphicType.html"><classname>org.apache.openjpa.persistence.jdbc.NonpolymorphicType</classname></ulink> enumeration.  The default value, <literal>
+				EXACT</literal>, indicates that the relation will always be of 
+				the exact declared type.  A value of <literal>
+				JOINABLE</literal>, on the other hand, means that the relation
+				might be to any joinable subclass of the declared type.  This
+				value only excludes table-per-class subclasses.
+				</para>
+          </section>
+          <section id="class-criteria">
+            <title>Class Criteria</title>
+            <indexterm zone="eager-fetch-mode">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>class criteria</tertiary>
+              <seealso>joins</seealso>
+            </indexterm>
+            <indexterm zone="eager-fetch-mode">
+              <primary>joins</primary>
+              <secondary>class criteria</secondary>
+            </indexterm>
+            <para>
+				This family of boolean extensions determines whether OpenJPA will 
+				use the expected class of related objects as criteria in the SQL
+				it issues to load a relation field.  Typically, this is
+				not needed.  The foreign key values uniquely identify the
+				record for the related object.  Under some rare mappings,
+				however, you may need to consider both foreign key values and
+				the expected class of the related object - for example, if
+				you have an inverse relation that shares the 
+				foreign key with another inverse relation to an object
+				of a different subclass.  In these cases, set the proper class
+				critera extension to <literal>true</literal> to force OpenJPA to 
+				append class criteria to its select SQL.
+				</para>
+            <para>
+				OpenJPA JPA defines the following class criteria annotations
+				for field relations, array, collection, and map element 
+				relations, and map key relations, respectively:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ClassCriteria.html">
+                    <classname>org.apache.openjpa.persistence.jdbc.ClassCriteria
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementClassCriteria.html">
+                    <classname>org.apache.openjpa.persistence.jdbc.ElementClassCriteria
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyClassCriteria.html">
+                    <classname>org.apache.openjpa.persistence.jdbc.KeyClassCriteria
+						</classname>
+                  </ulink>
+                </para>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="strategy">
+            <title>Strategy</title>
+            <indexterm zone="strategy">
+              <primary>mapping metadata</primary>
+              <secondary>extensions</secondary>
+              <tertiary>strategy</tertiary>
+              <seealso>custom mapping</seealso>
+            </indexterm>
+            <para>
+				OpenJPA's family of strategy extensions allow you to specify a 
+				custom mapping strategy or value handler for a field.  See
+				<xref linkend="ref_guide_mapping_custom"/> for information on
+				custom mappings.
+				</para>
+            <para>
+				OpenJPA includes the following JPA strategy annotations:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html"><classname>org.apache.openjpa.persistence.jdbc.Strategy
+						</classname></ulink>: Field strategy or value handler
+						plugin string.
+						</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.ElementStrategy
+						</classname></ulink>: Array, collection, or map element
+						value handler plugin string.
+						</para>
+              </listitem>
+              <listitem>
+                <para><ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.KeyStrategy
+						</classname></ulink>: Map key value handler plugin 
+						string.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <itemizedlist>
+              <listitem>
+                <para><literal>jdbc-strategy</literal>: Field strategy or 
+						value handler plugin string.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>jdbc-element-strategy</literal>: Collection or
+						array element value handler plugin string.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>jdbc-key-strategy</literal>: Map key value 
+						handler plugin string.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>jdbc-value-strategy</literal>: Map value 
+						handler plugin string.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_mapping_custom">
+        <title>Custom Mappings</title>
+        <indexterm zone="ref_guide_mapping_custom">
+          <primary>custom mapping</primary>
+        </indexterm>
+        <indexterm>
+          <primary>mapping metadata</primary>
+          <secondary>custom mapping</secondary>
+          <see>custom mapping</see>
+        </indexterm>
+        <para>
+		In OpenJPA, you are not limited to the set of standard mappings defined by
+		the specification.  OpenJPA allows you to define custom class, 
+		discriminator, version, and field mapping strategies with all the 
+		power of OpenJPA's built-in strategies.  
+		
+		</para>
+        <section id="ref_guide_mapping_custom_class">
+          <title>Custom Class Mapping</title>
+          <para>
+			To create a custom class mapping, write an implementation of the 
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ClassStrategy.html"><classname>org.apache.openjpa.jdbc.meta.ClassStrategy</classname></ulink> 
+			interface.  You will probably want to extend one of the existing 
+			abstract or concrete strategies in the 
+			<literal>org.apache.openjpa.jdbc.meta.strats</literal> package.
+			</para>
+          <para><phrase>
+			The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html"><classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
+			annotation allows you to declare a custom class mapping strategy
+			in JPA mapping metadata.  Set the value of the annotation to the
+			full class name of your custom strategy.
+			</phrase>
+			
+			You can configure your strategy class' bean properties using 
+			OpenJPA's plugin syntax, detailed in 
+			<xref linkend="ref_guide_conf_plugins"/>.
+			</para>
+        </section>
+        <section id="ref_guide_mapping_custom_versdiscrim">
+          <title>Custom Discriminator and Version Strategies</title>
+          <para>
+			To define a custom discriminator or version strategy, implement
+			the <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/DiscriminatorStrategy.html"><classname>org.apache.openjpa.jdbc.meta.DiscriminatorStrategy</classname></ulink>
+			or <ulink url="../apidocs/org/apache/openjpa/jdbc/meta/VersionStrategy.html"><classname>org.apache.openjpa.jdbc.meta.VersionStrategy</classname></ulink> 
+			interface, respectively.  You might extend one of the existing
+			abstract or concrete strategies in the 
+			<literal>org.apache.openjpa.jdbc.meta.strats</literal> package.
+			</para>
+          <para>
+			OpenJPA includes the 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy</classname></ulink> and 
+			<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.VersionStrategy</classname></ulink>
+			class annotations for declaring a custom discriminator or
+			version strategy in JPA mapping metadata.  Set the string value of 
+			these annotations to the full class name of your implementation, or
+			to the class name or alias of an existing OpenJPA implementation.
+			</para>
+          <para>
+			As with custom class mappings, you can configure your strategy 
+			class' bean properties using OpenJPA's plugin syntax, detailed in 
+			<xref linkend="ref_guide_conf_plugins"/>.
+			</para>
+        </section>
+        <section id="ref_guide_mapping_custom_field">
+          <title>Custom Field Mapping</title>
+          <indexterm zone="ref_guide_mapping_custom_field">
+            <primary>custom mapping</primary>
+            <secondary>field mapping</secondary>
+          </indexterm>
+          <para>
+			While custom class, discriminator, and version mapping can be 
+			useful, custom field mappings are far more common.  OpenJPA offers two
+			types of custom field mappings: value handlers, and full custom
+			field strategies.  The following sections examine each.
+			</para>
+          <section id="ref_guide_mapping_custom_vhandler">
+            <title>Value Handlers</title>
+            <indexterm zone="ref_guide_mapping_custom_fieldstrat">
+              <primary>custom mapping</primary>
+              <secondary>field mapping</secondary>
+              <tertiary>value handler</tertiary>
+            </indexterm>
+            <para>
+				Value handlers make it trivial to map any type that you can
+				break down into one or more simple values.  All value handlers
+				implement the <classname>org.apache.openjpa.jdbc.meta.ValueHandler</classname>
+				interface; see its 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ValueHandler.html">
+				Javadoc</ulink> for details.  Rather than give synthetic 
+				examples of value handlers, OpenJPA provides the source to most 
+				of the built-in handlers in the 
+				<filename>src/openjpa/jdbc/meta/strats</filename> directory of 
+				your OpenJPA distribution.  Use these functional implementations 
+				as examples when you create your own value handlers.
+				</para>
+            <para>
+				Note that value handlers are not only simple to write, but are
+				highly reusable.  For example, imagine that you create a 
+				handler for <classname>java.awt.Point</classname> values.  You
+				can not only use this handler to map fields of type 
+				<classname>Point</classname>, but also to map <classname>
+				Collection</classname>s or <classname>Map</classname>s of 
+				<classname>Point</classname>s with no additional work.
+				</para>
+          </section>
+          <section id="ref_guide_mapping_custom_fieldstrat">
+            <title>Field Strategies</title>
+            <indexterm zone="ref_guide_mapping_custom_fieldstrat">
+              <primary>custom mapping</primary>
+              <secondary>field mapping</secondary>
+              <tertiary>field strategy</tertiary>
+            </indexterm>
+            <para>
+				OpenJPA interacts with persistent fields through the
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/FieldStrategy"><classname>org.apache.openjpa.jdbc.meta.FieldStrategy</classname></ulink> 
+				interface.  You can implement this interface yourself to 
+				create a custom field strategy, or extend one of the existing 
+				abstract or concrete strategies in the <literal>
+				org.apache.openjpa.jdbc.meta.strats</literal> package.  Creating a custom 
+				field strategy is more difficult than writing a custom value 
+				handler, but gives you more freedom in how you interact with 
+				the database.
+				
+				</para>
+          </section>
+          <section id="ref_guide_mapping_custom_field_conf">
+            <title>Configuration</title>
+            <indexterm zone="ref_guide_mapping_custom_field_conf">
+              <primary>custom mapping</primary>
+              <secondary>field mapping</secondary>
+              <tertiary>configuration</tertiary>
+            </indexterm>
+            <para>
+				OpenJPA gives you two ways to configure your custom field mappings.
+				The <literal>FieldStrategies</literal> property of the built-in
+				<classname>MappingDefaults</classname> implementations allows
+				you to globally associate field types with their corresponding 
+				custom value handler or strategy.  OpenJPA will automatically use 
+				your custom strategies when it encounters a field of the 
+				associated type.  OpenJPA will use your custom value handlers 
+				whenever it encounters a field, collection element, map key, 
+				or map value of the associated type. 
+				<xref linkend="ref_guide_mapping_defaults"/> described mapping
+				defaults in detail.
+				</para>
+            <para>
+				Your other option is to explicitly install a custom value 
+				handler or strategy on a particular field.  To do so, specify 
+				the full name of your implementation class in the proper mapping
+				metadata extension.  
+				<phrase>
+				OpenJPA JPA includes the
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html"><classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>,
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.ElementStrategy</classname></ulink>,
+				and
+				<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyStrategy.html"><classname>org.apache.openjpa.persistence.jdbc.KeyStrategy</classname></ulink>
+				annotations.
+				</phrase>
+				
+				You can configure the named strategy or handler's bean 
+				properties in these extensions using OpenJPA's plugin format (see 
+				<xref linkend="ref_guide_conf_plugins"/>).
+				</para>
+            <para>
+				The example below installs a custom strategy on the
+				<literal>coverImage</literal> field, uses a custom value handler
+				for the <literal>primaryInfoStruct</literal> field, and 
+				uses the same value handler for the elements of the 
+				<literal>secondaryInfoStructs</literal> collection.
+				</para>
+            <example id="ref_guide_mapping_custom_field_conf_extex">
+              <title>Custom Mappings via Extensions</title>
+              <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+@Entity
+public class Magazine
+{
+    @Persistent
+    @Strategy("org.mag.mapping.ImageStrategy")
+    @Column(name="IMG")
+    private Image coverImage;
+ 
+    @Persistent
+    @Strategy("org.mag.mapping.InfoStructHandler")
+    @Columns({
+        @Column(name="DATA1"),
+        @Column(name="DATA2"),
+        @Column(name="DATA3")
+    })
+    private InfoStruct primaryInfoStruct;
+
+    @PersistentCollection
+    @ContainerTable(name="SEC_STRUCTS", joinColumns=@XJoinColumn(name="MAG_ID"))
+    @ElementStrategy("org.mag.mapping.InfoStructHandler")
+    @ElementColumns({
+        @ElementColumn(name="DATA1"),
+        @ElementColumn(name="DATA2"),
+        @ElementColumn(name="DATA3")
+    })
+    private Collection&lt;InfoStruct&gt; secondaryInfoStructs;
+
+    ...
+}
+</programlisting>
+            </example>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_orphan">
+        <title>Orphaned Keys</title>
+        <para>
+		Unless you apply database foreign key constraints extensively, it is
+		possible to end up with orphaned keys in your database.  For example,
+		suppose <classname>Magazine</classname> <literal>m</literal> has a 
+		reference to <classname>Article</classname> <literal>a</literal>. If you
+		delete <literal>a</literal> without nulling <literal>m</literal>'s 
+		reference, <literal>m</literal>'s database record will wind up with
+		an orphaned key to the non-existent <literal>a</literal> record.  
+		</para>
+        <note>
+          <para>
+			One way of avoiding orphaned keys is to use 
+			<emphasis>dependent</emphasis> fields.
+			</para>
+        </note>
+        <para>
+		OpenJPA's <link linkend="openjpa.OrphanedKeyAction"><literal>
+		openjpa.OrphanedKeyAction</literal></link> configuration property controls
+		what action to take when OpenJPA encounters an orphaned key.  You can set
+		this plugin string (see <xref linkend="ref_guide_conf_plugins"/>) to
+		a custom implementation of the 
+		<ulink url="../apidocs/org/apache/openjpa/event/OrphanedKeyAction.html"><classname>
+		org.apache.openjpa.event.OrphanedKeyAction</classname></ulink> interface, or use
+		one of the built-in options:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><literal>log</literal>: This is the default setting.  
+				This option logs a message for each orphaned key.  
+				It is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/event/LogOrphanedKeyAction.html"><classname>org.apache.openjpa.event.LogOrphanedKeyAction</classname></ulink>
+				class, which has the following additional properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Channel</literal>: The channel to log to.
+						Defaults to <literal>openjpa.Runtime</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>Level</literal>: The level to log at.
+						Defaults to <literal>WARN</literal>.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+          <listitem>
+            <para><literal>exception</literal>: Throw an exception
+				when OpenJPA discovers an orphaned key.  This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/event/ExceptionOrphanedKeyAction.html"><classname>org.apache.openjpa.event.ExceptionOrphanedKeyAction</classname></ulink> class.
+				</para>
+            <para>
+				In JPA, the exception type will be <classname>
+				javax.persistence.EntityNotFoundException</classname>.
+				</para>
+          </listitem>
+          <listitem>
+            <para><literal>none</literal>: Ignore orphaned keys.
+				This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/event/NoneOrphanedKeyAction.html"><classname>org.apache.openjpa.event.NoneOrphanedKeyAction</classname></ulink>
+				class.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <example id="ref_guide_orphan_logex">
+          <title>Custom Logging Orphaned Keys</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.OrphanedKeyAction" value="log(Channel=Orphans, Level=DEBUG)"/&gt;
+</programlisting>
+        </example>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_deploy">
+      <title>Deployment</title>
+      <para>
+	OpenJPA deployment includes choosing a factory deployment strategy,
+	and in a managed environment, optionally integrating with your application
+	server's managed and XA transactions.  This chapter examines each aspect
+	of deployment in turn.
+	</para>
+      <section id="ref_guide_deploy_factory">
+        <title>Factory Deployment</title>
+        <para>
+		OpenJPA offers several 
+		<phrase><classname>EntityManagerFactory</classname></phrase>
+		
+		
+		deployment options.
+		</para>
+        <section id="ref_guide_deploy_factory_standalone">
+          <title>Standalone Deployment</title>
+          <indexterm zone="ref_guide_deploy_factory_standalone">
+            <primary>deployment</primary>
+            <secondary>standalone</secondary>
+            <seealso>Persistence</seealso>
+          </indexterm>
+          <para>
+			The JPA Overview describes the 
+			<classname>javax.persistence.Persistence</classname> class.  You 
+			can use <classname>Persistence</classname> to obtain 
+			<classname>EntityManagerFactory</classname> instances, as 
+			demonstrated in <xref linkend="jpa_overview_persistence"/>.
+			OpenJPA also extends <classname>Persistence</classname> to add
+			additional <classname>EntityManagerFactory</classname> 
+			creation methods.  The
+			<classname>org.apache.openjpa.persistence.OpenJPAPersistence</classname> class
+			<ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html">
+			Javadoc</ulink> details these extensions.
+			</para>
+          <para>
+			After obtaining the factory, you can cache it for all 
+			<phrase><classname>EntityManager</classname></phrase>
+			 
+			
+			creation duties.
+			</para>
+        </section>
+        <section id="ref_guide_deploy_inject">
+          <title>EntityManager Injection</title>
+<!-- ### EJBDOC -->
+          <para>
+			To be decided.
+			</para>
+        </section>
+        <section id="ref_guide_deploy_jca_ejb">
+          <title>OpenJPA JPA JCA Deployment</title>
+          <indexterm zone="ref_guide_deploy_jca_ejb">
+            <primary>deployment</primary>
+            <secondary>JCA</secondary>
+            <seealso>JCA</seealso>
+          </indexterm>
+          <indexterm zone="ref_guide_deploy_jca_ejb">
+            <primary>JCA</primary>
+            <secondary>deployment</secondary>
+          </indexterm>
+          <para>
+			OpenJPA can deploy OpenJPA JPA through the Java Connector Architecture
+			(JCA) in any JCA-compliant application server that supports
+			JDK 1.5 (all EJB 3 implementations require JDK 1.5).  We present
+			the deployment steps for the most common servers below.
+			</para>
+          <section id="ref_guide_deploy_jca_ejb_weblogic9">
+            <title>WebLogic 9</title>
+            <indexterm zone="ref_guide_deploy_jca_ejb_weblogic9">
+              <primary>Weblogic</primary>
+            </indexterm>
+            <indexterm zone="ref_guide_deploy_jca_ejb_weblogic9">
+              <primary>JCA</primary>
+              <secondary>Weblogic 9</secondary>
+            </indexterm>
+            <para><!-- ### JDO2MIG : everything in system path for now -->
+				First, ensure that your JDBC driver is in your system classpath.
+				In addition, you will be adding the OpenJPA and specification API
+				jars to the system classpath.  You can accomplish this by
+				editing <filename>startWebLogic.sh/.cmd</filename>.
+				</para>
+            <warning>
+              <para>Currently WebLogic ships with an old version
+					of the EJB 3 libraries.  Be sure to put 
+					<filename>org.apache.openjpa.jar</filename> in the <emphasis>beginning
+					</emphasis> of the <literal>CLASSPATH</literal>.</para>
+            </warning>
+            <para>
+				The next step is to deploy 
+				<filename>openjpa-persistence.rar</filename> from the 
+				<filename>jca/persistence</filename> directory of your OpenJPA
+				installation.  Copy this file to the <filename>autodeploy
+				</filename> directory of your domain.  
+				</para>
+            <para>
+				We will now extract <filename>META-INF/ra.xml</filename>
+				and <filename>META-INF/weblogic-ra.xml</filename>
+				to edit our configuration:
+				</para>
+            <programlisting format="linespecific">
+jar xvf openjpa-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml
+</programlisting>
+            <para>
+				Now you should configure OpenJPA JCA by editing
+				<filename>META-INF/ra.xml</filename> substituting
+				<literal>config-property-value</literal> stanzas
+				with your own values.  You can comment out
+				properties (config-property stanzas) which you are
+				not using or you can leave them at their default settings.
+				Edit <filename>META-INF/weblogic-ra.xml</filename>
+				to configure the JNDI location to which you
+				want OpenJPA to be bound.
+				</para>
+            <para>
+				Now we can re-jar the manifest files back into the 
+				<filename>RAR</filename> file.
+				</para>
+            <programlisting format="linespecific">
+jar uvf openjpa-ejb.rar META-INF/ra.xml META-INF/weblogic-ra.xml
+rm META-INF/ra.xml META-IN/weblogic-ra.xml
+rmdir META-INF
+</programlisting>
+            <para>
+				Now you can start WebLogic and WebLogic should
+				deploy OpenJPA for you.  If you have installed OpenJPA correctly, 
+				at this point, one should be able to see OpenJPA bound to the 
+				JNDI location which you specified earlier.
+				</para>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_enterprise_xa">
+        <title>XA Transactions</title>
+        <indexterm zone="ref_guide_enterprise_xa">
+          <primary>transactions</primary>
+          <secondary>XA</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>XA transactions</primary>
+          <see>transactions</see>
+        </indexterm>
+        <para>
+		The X/Open Distributed Transaction Processing (X/Open DTP)
+		model, designed by <ulink url="http://www.xopen.org">Open Group</ulink>
+		(a vendor consortium), defines a standard communication architecture
+		that provides the following:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+				Concurrent execution of applications on shared resources.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				Coordination of transactions across applications.
+				</para>
+          </listitem>
+          <listitem>
+            <para>
+				Components, interfaces, and protocols that define the 
+				architecture and provide portability of applications.
+				</para>
+          </listitem>
+          <listitem>
+            <para>Atomicity of transaction systems.</para>
+          </listitem>
+          <listitem>
+            <para>
+				Single-thread control and sequential function-calling.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The X/Open DTP XA standard defines the application programming
+		interfaces that a resource manager uses to communicate
+		with a transaction manager. The XA interfaces enable resource
+		managers to join transactions, to perform two-phase commit,
+		and to recover in-doubt transactions following a failure.
+		</para>
+        <section id="ref_guide_enterprise_xa_req">
+          <title>Using OpenJPA with XA Transactions</title>
+          <para>
+			OpenJPA supports XA-compliant transactions when used in a properly
+			configured managed environment. The following components are 
+			required:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					A managed environment that provides an XA compliant 
+					transaction manager. Examples of this are application 
+					servers such as JBoss and WebLogic.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Instances of a <classname>javax.sql.XADataSource</classname>
+					for each of the <classname>DataSource</classname>s that 
+					OpenJPA will use.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			Given these components, setting up OpenJPA to participate in 
+			distributed transactions is a simple two-step process:
+			</para>
+          <orderedlist>
+            <listitem>
+              <para>
+					Point OpenJPA at an enlisted 
+					<classname>XADataSource</classname>, and configure a 
+					second non-enlisted data source.
+					See <xref linkend="ref_guide_dbsetup_thirdparty_enlist"/>.
+					</para>
+            </listitem>
+          </orderedlist>
+        </section>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_runtime">
+      <title>Runtime Extensions</title>
+      <para>
+	This chapter describes OpenJPA extensions to the standard 
+	<phrase>JPA</phrase>
+	
+	
+	interfaces, and outlines some additional features of the OpenJPA runtime.
+	</para>
+      <section id="ref_guide_runtime_arch">
+        <title>Architecture</title>
+        <para>
+		Internally, OpenJPA does not adhere to any persistence specification.  The
+		OpenJPA kernel has its own set of APIs and components.  Specifications like
+		JPA and JDO are simply different "personalities" that can
+		OpenJPA's native kernel can adopt.
+		</para>
+        <para>
+		As a OpenJPA <phrase>JPA</phrase> user, you will not normally see beneath OpenJPA's
+		JPA personality.  OpenJPA allows you to access its feature set
+		without leaving the comfort of JPA.  Where OpenJPA goes beyond standard 
+		JPA functionality, we have crafted JPA-specific APIs to 
+		each OpenJPA extension for as seamless an experience as possible.
+		</para>
+        <para>
+		When writing OpenJPA plugins or otherwise extending the OpenJPA runtime, 
+		however, you will use OpenJPA's native APIs.  So that you won't feel lost,
+		the list below associates each specification interface with 
+		its backing native OpenJPA component:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><classname>javax.persistence.EntityManagerFactory</classname>:
+				<emphasis><classname>org.apache.openjpa.kernel.BrokerFactory</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>javax.persistence.EntityManager</classname>:
+				<emphasis><classname>org.apache.openjpa.kernel.Broker</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>javax.persistence.Query</classname>:
+				<emphasis><classname>org.apache.openjpa.kernel.Query</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>org.apache.openjpa.persistence.Extent</classname>:
+				<emphasis><classname>org.apache.openjpa.kernel.Extent</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>org.apache.openjpa.persistence.StoreCache</classname>:
+				<emphasis><classname>org.apache.openjpa.datacache.DataCache</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>org.apache.openjpa.persistence.QueryResultCache</classname>:
+				<emphasis><classname>org.apache.openjpa.datacache.QueryCache</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>org.apache.openjpa.persistence.FetchPlan</classname>:
+				<emphasis><classname>org.apache.openjpa.kernel.FetchConfiguration</classname></emphasis></para>
+          </listitem>
+          <listitem>
+            <para><classname>org.apache.openjpa.persistence.Generator</classname>:
+				<emphasis><classname>org.apache.openjpa.kernel.Seq</classname></emphasis></para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The <link linkend="ref_guide_runtime_openjpapersistence"><classname>
+		org.apache.openjpa.persistence.OpenJPAPersistence</classname></link> helper allows you 
+		to convert between <classname>EntityManagerFactories</classname> and
+		<classname>BrokerFactories</classname>, 
+		<classname>EntityManager</classname>s and
+		<classname>Broker</classname>s. 
+		</para>
+        <section id="ref_guide_runtime_pmextension">
+          <title>Broker Customization</title>
+          <indexterm zone="ref_guide_runtime_pmextension">
+            <primary>OpenJPAEntityManager</primary>
+            <secondary>extending</secondary>
+          </indexterm>
+          <para>
+			Some advanced users may want to add capabilities to OpenJPA's internal
+			<ulink url="../apidocs/org/apache/openjpa/kernel/BrokerImpl.html"><classname>org.apache.openjpa.kernel.BrokerImpl</classname></ulink>.
+			You can configure OpenJPA to use a custom subclass of
+			<classname>BrokerImpl</classname> through the 
+			<link linkend="openjpa.BrokerImpl"><literal>openjpa.BrokerImpl</literal></link> configuration property.  Set this property to the full 
+			class name of your custom subclass.
+			</para>
+          <para>
+			As a <link linkend="ref_guide_conf_plugins">plugin string</link>, 
+			you can also use this property to configure the <classname>
+			BrokerImpl</classname> with the following properties:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>EvictFromDataCache</literal>: When evicting an
+					object through the <methodname>OpenJPAEntityManager.evict
+					</methodname> methods, whether to also evict it from the 
+					OpenJPA's <link linkend="ref_guide_cache">data cache</link>.
+					Defaults to <literal>false</literal>.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <example id="ref_guide_runtime_pm_evictex">
+            <title>Evict from Data Cache</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_runtime_ejb">
+        <title>JPA Extensions</title>
+        <para>
+		The following sections outline the runtime interfaces you can use
+		to access OpenJPA-specific functionality from JPA.  Each 
+		interface contains services and convenience methods missing from the 
+		JPA specification.  OpenJPA strives to use the same naming 
+		conventions and API patterns as standard JPA methods in all
+		extensions, so that OpenJPA JDO APIs feel as much as possible like 
+		standard JPA.
+		</para>
+        <para>
+		You may have noticed the examples throughout this document using the
+		<methodname>OpenJPAPersistence.cast</methodname> methods to cast from
+		standard JPA interfaces to OpenJPA extended interfaces. 
+		This is the recommended practice.  Some application server vendors
+		may proxy OpenJPA's JPA implementation, preventing a straight
+		cast.  <classname>OpenJPAPersistence</classname>'s <methodname>cast
+		</methodname> methods work around these proxies.
+		</para>
+        <programlisting format="linespecific"> 
+public static OpenJPAEntityManagerFactory cast (EntityManagerFactory emf);
+public static OpenJPAEntityManager cast (EntityManager em);
+public static OpenJPAQuery cast (Query q);
+</programlisting>
+        <para>
+		We provide additional information on the <classname>OpenJPAPersistence
+		</classname> helper <link linkend="ref_guide_runtime_openjpapersistence">
+		below</link>.
+		</para>
+        <section id="ref_guide_runtime_emfactory">
+          <title>OpenJPAEntityManagerFactory</title>
+          <indexterm zone="ref_guide_runtime_emfactory">
+            <primary>OpenJPAEntityManagerFactory</primary>
+          </indexterm>
+          <indexterm>
+            <primary>EntityManagerFactory</primary>
+            <secondary>OpenJPA extensions</secondary>
+            <see>OpenJPAEntityManagerFactory</see>
+          </indexterm>
+          <para>
+			The <classname>org.apache.openjpa.persistence.OpenJPAEntityManagerFactory</classname>
+			interface extends the basic <classname>
+			javax.persistence.EntityManagerFactory</classname> with 
+			OpenJPA-specific features.  The <classname>OpenJPAEntityManagerFactory
+			</classname> offers APIs to obtain 
+			managed and unmanaged <classname>EntityManager</classname>s from 
+			the same factory, to access the OpenJPA data and query caches, and to 
+			perform other OpenJPA-specific operations.  See the
+			<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html">
+			interface Javadoc</ulink> for details.
+			</para>
+        </section>
+        <section id="ref_guide_runtime_em">
+          <title>OpenJPAEntityManager</title>
+          <indexterm zone="ref_guide_runtime_em">
+            <primary>OpenJPAEntityManager</primary>
+          </indexterm>
+          <indexterm>
+            <primary>EntityManager</primary>
+            <secondary>OpenJPA extensions</secondary>
+            <see>OpenJPAEntityManager</see>
+          </indexterm>
+          <para>
+			All OpenJPA <classname>EntityManager</classname>s implement the 
+			<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>org.apache.openjpa.persistence.OpenJPAEntityManager</classname></ulink> 
+			interface.  This interface extends the standard <classname>
+			javax.persistence.EntityManager</classname>.  Just as the
+			standard <classname>EntityManager</classname> is the primary 
+			window into JPA services, the <classname>
+			OpenJPAEntityManager</classname> is the primary window from JPA
+			into OpenJPA-specific functionality.  We strongly 
+			encourage you to investigate the API extensions this interface 
+			contains.
+			</para>
+        </section>
+        <section id="ref_guide_runtime_ejbquery">
+          <title>OpenJPAQuery</title>
+          <indexterm zone="ref_guide_runtime_ejbquery">
+            <primary>OpenJPAQuery</primary>
+          </indexterm>
+          <indexterm>
+            <primary>Query</primary>
+            <secondary>OpenJPA extensions</secondary>
+            <see>OpenJPAQuery</see>
+          </indexterm>
+          <para>
+			OpenJPA extends JPA's standard query functionality with the
+			<classname>org.apache.openjpa.persistence.OpenJPAQuery</classname> interface.  See 
+			its <ulink url="../../api/openjpa/persistence/OpenJPAQuery.html">Javadoc
+			</ulink> for details on the convenience methods it provides.
+			</para>
+        </section>
+        <section id="ref_guide_runtime_ejbextent">
+          <title>Extent</title>
+          <indexterm zone="ref_guide_runtime_ejbextent">
+            <primary>Extent</primary>
+          </indexterm>
+          <indexterm>
+            <primary>Extent</primary>
+            <secondary>OpenJPA extensions</secondary>
+            <see>OpenJPAExtent</see>
+          </indexterm>
+          <para>
+			An <classname>Extent</classname> is a logical view of all persistent
+			instances of a given entity class, possibly including subclasses. 
+			OpenJPA adds the <ulink url="../../api/openjpa/persistence/Extent.html"><classname>org.apache.openjpa.persistence.Extent</classname></ulink> class 
+			to the set of Java Persistence APIs.  The following code illustrates
+			iterating over all instances of the <classname>Magazine</classname>
+			entity, without subclasses:
+			</para>
+          <example id="ref_guide_runtime_ejbextentex">
+            <title>Using a JPA Extent</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+Extent&lt;Magazine&gt; mags = kem.getExtent (Magazine.class, false);
+for (Magazine m : mags)
+    processMagazine (m);
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_runtime_ejbcache">
+          <title>StoreCache</title>
+          <indexterm zone="ref_guide_runtime_ejbcache">
+            <primary>StoreCache</primary>
+          </indexterm>
+          <para>
+			In addition to the <classname>EntityManager</classname> object
+			cache mandated by the JPA specification, OpenJPA includes
+			a flexible datastore-level cache.  You can access this cache
+			from your JPA code using the 
+			<ulink url="../../api/openjpa/persistence/StoreCache.html"><classname>
+			org.apache.openjpa.persistence.StoreCache</classname></ulink> facade.  
+			<xref linkend="ref_guide_cache"/> has detailed information on
+			OpenJPA's data caching system, including the 
+			<classname>StoreCache</classname> facade.
+			</para>
+        </section>
+        <section id="ref_guide_runtime_ejbquerycache">
+          <title>QueryResultCache</title>
+          <indexterm zone="ref_guide_runtime_ejbquerycache">
+            <primary>QueryResultCache</primary>
+          </indexterm>
+          <para>
+			OpenJPA can cache query results as well as persistent object data.  The
+			<ulink url="../../api/openjpa/persistence/QueryResultCache.html"><classname>org.apache.openjpa.persistence.QueryResultCache</classname></ulink> 
+			is an JPA-flavored facade to OpenJPA's internal query cache.  See
+			<xref linkend="ref_guide_cache_query"/> for details on query caching
+			in OpenJPA.
+			</para>
+        </section>
+        <section id="ref_guide_runtime_ejbfetch">
+          <title>FetchPlan</title>
+          <indexterm zone="ref_guide_runtime_ejbfetch">
+            <primary>FetchPlan</primary>
+          </indexterm>
+          <indexterm>
+            <primary>eager fetching</primary>
+            <seealso>FetchPlan</seealso>
+          </indexterm>
+          <para>
+			Many of the aforementioned OpenJPA interfaces give you access to a 
+			<classname>org.apache.openjpa.persistence.FetchPlan</classname>
+			instance.  The <classname>FetchPlan</classname> allows you
+			to exercise some control over how objects are fetched from the 
+			datastore, including <link linkend="ref_guide_dbsetup_lrs">large 
+			result set support</link>, <link linkend="ref_guide_fetch">custom 
+			fetch groups</link>, and <link linkend="ref_guide_locking">lock 
+			levels</link>.  
+			</para>
+          <para>
+			OpenJPA goes one step further, extending <classname>FetchPlan
+			</classname> with
+			<ulink url="../../api/openjpa/persistence/jdbc/JDBCFetchPlan.html"><classname>org.apache.openjpa.persistence.jdbc.JDBCFetchPlan</classname></ulink> to add additional JDBC-specific tuning methods.
+			Unless you have customized OpenJPA to use a non-relational back-end
+			(see <xref linkend="ref_guide_enterprise_abstractstore"/>), all
+			<classname>FetchPlan</classname>s in OpenJPA implement
+			<classname>JDBCFetchPlan</classname>, so feel free to cast
+			to this interface.
+			</para>
+          <para>
+			Fetch plans pass on from parent components to child
+			components.  The <classname>EntityManagerFactory</classname> 
+			settings (via your configuration properties) for things like the 
+			fetch size, result set type, and custom fetch groups are passed on 
+			to the fetch plan of the <classname>
+			EntityManager</classname>s it produces.  The settings 
+			of each <classname>EntityManager</classname>, in turn, are passed 
+			on to each <classname>Query</classname> and <classname>Extent
+			</classname> it returns.  Note that the opposite, however, is not 
+			true.  Modifying the fetch plan of a 
+			<classname>Query</classname> or <classname>Extent</classname> does 
+			not affect the <classname>EntityManager</classname>'s configuration.
+			Likewise, modifying an <classname>EntityManager</classname>'s 
+			configuration does not affect the <classname>
+			EntityManagerFactory</classname>.
+			</para>
+          <para><xref linkend="ref_guide_fetch"/> includes examples using
+			<classname>FetchPlan</classname>s.
+			</para>
+        </section>
+        <section id="ref_guide_runtime_openjpapersistence">
+          <title>OpenJPAPersistence</title>
+          <indexterm zone="ref_guide_runtime_openjpapersistence">
+            <primary>OpenJPAPersistence</primary>
+          </indexterm>
+          <para><ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"><classname>org.apache.openjpa.persistence.OpenJPAPersistence</classname></ulink> is 
+			a static helper class that adds OpenJPA-specific utility methods to 
+			<classname>javax.persistence.Persistence</classname>.
+			</para>
+        </section>
+      </section>
+      <section id="ref_guide_locking">
+        <title>Object Locking</title>
+        <indexterm zone="ref_guide_locking">
+          <primary>locking</primary>
+        </indexterm>
+        <para>
+	Controlling how and when objects are locked is an important part of 
+	maximizing the performance of your application under load.  This section
+	describes OpenJPA's APIs for explicit locking, as well as its rules for
+	implicit locking.
+	</para>
+        <section id="ref_guide_locking_default">
+          <title>Configuring Default Locking</title>
+          <indexterm zone="ref_guide_locking_default">
+            <primary>locking</primary>
+            <secondary>defaults configuration</secondary>
+          </indexterm>
+          <para><indexterm><primary>locking</primary><secondary>levels</secondary></indexterm><indexterm><primary>ReadLockLevel</primary></indexterm><indexterm><primary>WriteLockLevel</primary></indexterm>
+		You can control OpenJPA's default transactional read and write lock levels
+		through the <link linkend="openjpa.ReadLockLevel"><literal>
+		openjpa.ReadLockLevel</literal></link> and 
+		<link linkend="openjpa.WriteLockLevel"><literal>openjpa.WriteLockLevel
+		</literal></link> configuration properties.  Each property accepts a 
+		value of <literal>none</literal>, <literal>read</literal>, 
+		<literal>write</literal>, or a number corresponding to a lock
+		level defined by the <link linkend="ref_guide_locking_lockmgr">lock 
+		manager</link> in use.  These properties apply only to non-optimistic 
+		transactions; during optimistic transactions, OpenJPA never locks objects 
+		by default.
+		</para>
+          <para><indexterm><primary>LockTimeout</primary></indexterm><indexterm><primary>locking</primary><secondary>timeout</secondary></indexterm>
+		You can control the default amount of time OpenJPA will wait when trying 
+		to obtain locks through the <link linkend="openjpa.LockTimeout"><literal>
+		openjpa.LockTimeout</literal></link> configuration property.  Set this
+		property to the number of milliseconds you are willing to wait for
+		a lock before OpenJPA will throw an exception, or to -1 for no limit.  It
+		defaults to -1.
+		</para>
+          <example id="ref_guide_locking_default_conf">
+            <title>Setting Default Lock Levels</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.ReadLockLevel" value="none"/&gt;
+&lt;property name="openjpa.WriteLockLevel" value="write"/&gt;
+&lt;property name="openjpa.LockTimeout" value="30000"/&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_locking_runtime">
+          <title>Configuring Lock Levels at Runtime</title>
+          <indexterm zone="ref_guide_locking_runtime">
+            <primary>locking</primary>
+            <secondary>runtime configuration</secondary>
+          </indexterm>
+          <para>
+		At runtime, you can override the default lock levels through the
+		<classname>FetchPlan</classname> interface described above.
+		At the beginning of each
+		datastore transaction, OpenJPA initializes the <classname>
+		EntityManager</classname>'s fetch plan with the default lock 
+		levels and timeouts described in the previous section.  By changing the
+		fetch plan's locking properties, you can control how objects 
+		loaded at different points in the transaction are locked.  You can 
+		also use the fetch plan of an individual 
+		<classname>Query</classname> to apply your locking changes only to 
+		objects loaded through that <classname>Query</classname>.
+		</para>
+          <programlisting format="linespecific">
+public LockModeType getReadLockMode ();
+public FetchPlan setReadLockMode (LockModeType mode);
+public LockModeType getWriteLockMode ();
+public FetchPlan setWriteLockMode (LockModeType mode);
+long getLockTimeout ();
+FetchPlan setLockTimeout (long timeout);
+</programlisting>
+          <para>
+		Controlling locking through these runtime APIs works even during
+		optimistic transactions.  At the end of the transaction, OpenJPA resets 
+		the fetch plan's lock levels to <literal>none</literal>.
+		You cannot lock objects outside of a transaction.
+		</para>
+          <example id="ref_guide_locking_fetch">
+            <title>Setting Runtime Lock Levels</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+EntityManager em = ...;
+em.getTransaction ().begin ();
+
+// load stock we know we're going to update at write lock mode
+Query q = em.createQuery ("select s from Stock s where symbol = :s");
+q.setParameter ("s", symbol);
+OpenJPAQuery kq = OpenJPAPersistence.cast (q);
+FetchPlan fetch = kq.getFetchPlan ();
+fetch.setReadLockMode (LockModeType.WRITE);
+fetch.setLockTimeout (3000); // 3 seconds
+Stock stock = (Stock) q.getSingleResult ();
+
+// load an object we don't need locked at none lock mode
+fetch = (OpenJPAPersistence.cast (em)).getFetchPlan ();
+fetch.setReadLockMode (null);
+Market market = em.find (Market.class, marketId);
+
+stock.setPrice (market.calculatePrice (stock));
+em.getTransaction ().commit ();
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_locking_apis">
+          <title>Object Locking APIs</title>
+          <indexterm zone="ref_guide_locking_apis">
+            <primary>locking</primary>
+            <secondary>runtime APIs</secondary>
+          </indexterm>
+          <para>
+		In addition to allowing you to control implicit locking levels, OpenJPA
+		provides explicit APIs to lock objects and to retrieve their current
+		lock level.
+		</para>
+          <programlisting format="linespecific">
+public LockModeType OpenJPAEntityManager.getLockMode (Object pc);
+</programlisting>
+          <para>
+		Returns the level at which the given object is currently locked.
+		</para>
+          <para>
+		In addition to the standard 
+		<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html"><methodname>EntityManager.lock (Object, LockModeType)</methodname></ulink> method, the
+		<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>OpenJPAEntityManager</classname></ulink> exposes the following
+		methods to lock objects explicitly:
+		</para>
+          <programlisting format="linespecific">
+public void lock (Object pc);
+public void lock (Object pc, LockModeType mode, long timeout);
+public void lockAll (Object... pcs);
+public void lockAll (Object... pcs, LockModeType mode, long timeout);
+public void lockAll (Collection pcs);
+public void lockAll (Collection pcs, LockModeType mode, long timeout);
+</programlisting>
+          <para>
+		Methods that do not take a lock level or timeout parameter default
+		to the current fetch plan.  The example below demonstrates
+		these methods in action.
+		</para>
+          <example id="ref_guide_locking_explicit">
+            <title>Locking APIs</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+// retrieve the lock level of an object
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+Stock stock = ...;
+LockModeType level = kem.getLockMode (stock);
+if (level == OpenJPAModeType.WRITE) ...
+
+...
+
+kem.setOptimistic (true);
+kem.getTransaction ().begin ();
+
+// override default of not locking during an opt trans to lock stock object
+kem.lock (stock, LockModeType.WRITE, 1000);
+stock.setPrice (market.calculatePrice (stock));
+
+kem.getTransaction ().commit ();
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_locking_lockmgr">
+          <title>Lock Manager</title>
+          <indexterm zone="ref_guide_locking_lockmgr">
+            <primary>locking</primary>
+            <secondary>LockManager</secondary>
+          </indexterm>
+          <para><indexterm><primary>LockManager</primary></indexterm>
+		OpenJPA delegates the actual work of locking objects to the system's
+		<ulink url="../apidocs/org/apache/openjpa/kernel/LockManager.html"><classname>
+		org.apache.openjpa.kernel.LockManager</classname></ulink>.  This plugin is controlled
+		by the <link linkend="openjpa.LockManager"><literal>openjpa.LockManager
+		</literal></link> configuration property.  You can write your own lock
+		manager, or use one of the bundled options:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>pessimistic</literal>: This is an alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/PessimisticLockManager.html"><classname>org.apache.openjpa.jdbc.kernel.PessimisticLockManager</classname></ulink>, which uses SELECT FOR UPDATE statements (or the 
+				database's equivalent) to lock the database rows corresponding
+				to locked objects.  This lock manager does not distinguish
+				between read locks and write locks; all locks are write locks. 
+				</para>
+              <para>
+				The <literal>pessimistic</literal> LockManager can be
+				configued to additionally perform the version checking
+				and incrementing behavior of the <literal>version</literal>
+				lock manager described below by setting its
+				<literal>VersionCheckOnReadLock</literal>
+				and <literal>VersionUpdateOnWriteLock</literal> properties:
+				</para>
+              <programlisting format="linespecific">
+&lt;property name="openjpa.LockManager" value="pessimistic(VersionCheckOnReadLock=true,VersionUpdateOnWriteLock=true)"/&gt;
+</programlisting>
+            </listitem>
+            <listitem>
+              <para><literal>none</literal>: An alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/kernel/NoneLockManager.html"><classname>org.apache.openjpa.kernel.NoneLockManager</classname></ulink>, 
+				which does not perform any locking at all.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>sjvm</literal>: An alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/kernel/SingleJVMExclusiveLockManager.html"><classname>org.apache.openjpa.kernel.SingleJVMExclusiveLockManager
+				</classname></ulink>.  This lock manager uses in-memory mutexes
+				to obtain exclusive locks on object ids.  It does not perform
+				any database-level locking.  Also, it does not distinguish
+				between read and write locks; all locks are write locks.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>version</literal>: An alias for the 
+				<ulink url="../apidocs/org/apache/openjpa/kernel/VersionLockManager.html"><classname>org.apache.openjpa.kernel.VersionLockManager
+				</classname></ulink>.  This lock manager does not perform
+				any exclusive locking, but instead ensures read consistency
+				by verifying that the version of all read-locked instances
+				is unchanged at the end of the transaction. Furthermore, a
+				write lock will force an increment to the version at the
+				end of the transaction, even if the object is not
+				otherwise modified. This ensures read consistency with
+				non-blocking behavior.
+				</para>
+              <para>
+				This is the default <literal>openjpa.LockManager</literal>
+				setting in JPA.
+				</para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+			In order for the <literal>version</literal> lock manager
+			to prevent the dirty read phenomenon, the underlying data
+			store's transaction isolation level must be set to
+			the equivalent of "read committed" or higher.
+			</para>
+          </note>
+          <example id="ref_guide_locking_disable">
+            <title>Disabling Locking</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.LockManager" value="none"/&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_locking_rules">
+          <title>Rules for Locking Behavior</title>
+          <indexterm zone="ref_guide_locking_rules">
+            <primary>locking</primary>
+            <secondary>behavior</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_locking_rules">
+            <primary>lazy loading</primary>
+            <secondary>locking behavior</secondary>
+          </indexterm>
+          <para>
+		Advanced persistence concepts like lazy-loading and object uniquing 
+		create several locking corner-cases.  The rules below outline OpenJPA's 
+		implicit locking behavior in these cases. 
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				When an object's state is first read within a transaction, the 
+				object is locked at the fetch plan's current read lock
+				level.  Future reads of additional lazy state for the object 
+				will use the same read lock level, even if the fetch 
+				plan's level has changed.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				When an object's state is first modified within a transaction, 
+				the object is locked at the write lock level in effect when
+				the object was first read, even if the fetch plan's 
+				level has changed.  If the object was not read previously, the 
+				current write lock level is used.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				When objects are accessed through a persistent relation field,
+				the related objects are loaded with the fetch plan's 
+				current lock levels, not the lock levels of the object owning 
+				the field.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Whenever an object is accessed within a transaction,
+				the object is re-locked at the current read lock
+				level.  The current read and write lock levels become those that
+				the object "remembers" according to rules one and two above.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				If you lock	an object explicitly through the APIs demonstrated
+				above, it is re-locked at the specified level.  This level 
+				also becomes both the read and write level that the object 
+				"remembers" according to rules one and two above.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				When an object is already locked at a given lock level, 
+				re-locking at a lower level has no effect.  Locks cannot be
+				downgraded during a transaction.
+				</para>
+            </listitem>
+          </orderedlist>
+        </section>
+        <section id="ref_guide_locking_issues">
+          <title>Known Issues and Limitations</title>
+          <indexterm zone="ref_guide_locking_issues">
+            <primary>locking</primary>
+            <secondary>caveats</secondary>
+          </indexterm>
+          <para>
+		Due to performance concerns and database limitations, locking cannot
+		be perfect.  You should be aware of the issues outlined in this 
+		section, as they may affect your application.
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+				Typically, during optimistic transactions OpenJPA does not 
+				start an actual database transaction until you flush or the 
+				optimistic transaction commits.  This allows for very long-lived
+				transactions without consuming database resources.
+				When using the default lock manager, however, OpenJPA must begin a 
+				database transaction whenever you decide to lock an object 
+				during an optimistic transaction.  This is because the
+				default lock manager uses database locks, and databases cannot
+				lock rows without a transaction in progress.  OpenJPA will log
+				an INFO message to the <literal>openjpa.Runtime</literal> logging
+				channel when it begins a datastore transaction just to lock
+				an object.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				In order to maintain reasonable performance levels when 
+				loading object state, OpenJPA can only guarantee that an 
+				object is locked at the proper lock level <emphasis>after
+				</emphasis> the state has been retrieved from the database.
+				This means that it is technically possible for another 
+				transaction to "sneak in" and modify the database record after
+				OpenJPA retrieves the state, but before it locks the object.  The
+				only way to positively guarantee that the object is locked and
+				has the most recent state to refresh the object after locking 
+				it.
+				</para>
+              <para>
+				When using the default lock manager, the case above can only
+				occur when OpenJPA cannot issue the state-loading SELECT as a
+				locking statement due to database limitations.  For example, 
+				some databases cannot lock SELECTs that use joins.
+				The default lock manager will log an INFO message to the
+				<literal>openjpa.Runtime</literal> logging channel whenever it 
+				cannot lock the initial SELECT due to database limitations.
+				By paying attention to these log messages, you can see where 
+				you might consider using an object refresh to guarantee that 
+				you have the most recent state, or where you might rethink the 
+				way you load the state in question to circumvent the database
+				limitations that prevent OpenJPA from issuing a locking SELECT in 
+				the first place.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="ref_guide_savepoints">
+        <title>Savepoints</title>
+        <indexterm zone="ref_guide_savepoints">
+          <primary>savepoint</primary>
+        </indexterm>
+        <para>
+	Savepoints allow for fine grained control over the transactional behavior
+	of your application.  OpenJPA's savepoint API allow you to set intermediate
+	rollback points in your transaction.  You can then choose to rollback 
+	changes made only after a specific savepoint, then commit or continue 
+	making new changes in the transaction.  This feature is useful for 
+	multi-stage transactions, such as editing a set of objects over several 
+	web pages or user screens.  Savepoints also provide more flexibilty 
+	to conditional transaction behavior, such as choosing to commit or 
+	rollback a portion of the transaction based on the results of the 
+	changes.  This chapter describes how to use and configure OpenJPA savepoints.
+	</para>
+        <section id="reg_guide_savepoints_using">
+          <title>Using Savepoints</title>
+          <para>
+		OpenJPA's
+		<phrase><ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>OpenJPAEntityManager</classname></ulink></phrase>
+		
+		
+		have the following methods to control savepoint behavior.
+		Note that the savepoints work in tandem with the current
+		transaction.  This means that savepoints require an open transaction, 
+		and that a rollback of the transaction will rollback all of 
+		the changes in the transaction regardless of any savepoints set.
+		</para>
+          <programlisting format="linespecific">
+void setSavepoint (String name);
+void releaseSavepoint (String name);
+void rollbackToSavepoint (String name);
+</programlisting>
+          <para>
+		To set a savepoint, simply call <methodname>setSavepoint</methodname>, 
+		passing in a symbolic savepoint name.  
+		This savepoint will define a point at which you can preserve
+		the state of transactional objects for the duration of the current
+		transaction.
+		</para>
+          <para>
+		Having set a named savepoint, you can rollback changes made after that
+		point by calling <methodname>rollbackToSavepoint</methodname>.  This 
+		method will keep the current transaction active,
+		while restoring all transactional instances back to their saved state.
+		Instances that were deleted after the save point will no longer
+		be marked for deletion.  Similarly, transient instances that were
+		made persistent after the savepoint will become transient again.  
+		Savepoints made after this savepoint will be released and no longer 
+		valid, although you can still set new savepoints.  Savepoints will also
+		be cleared after the current transaction is committed or rolled back.
+		</para>
+          <para>
+		If a savepoint is no longer needed, you can release any resources
+		such as in memory state and datastore resources by calling
+		<methodname>releaseSavepoint</methodname>.
+		This method should not be called for savepoints that have been 
+		released automatically through other means, such as commit of a 
+		transaction or rollback to a prior savepoint.  While savepoints
+		made after this savepoint will also be released, there are no other
+		effects on the current transaction.
+		</para>
+          <para>
+		The following simple example illustrates setting, releasing, and
+		rolling back to a savepoint.
+		</para>
+          <example id="ref_guide_savepoints_example">
+            <title>Using Savepoints</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+kem.getTransaction ().begin ();
+
+Magazine mag = kem.find (Magazine.class, id);
+mag.setPageCount (300);
+kem.setSavepoint ("pages");
+
+mag.setPrice (mag.getPageCount () * pricePerPage);
+// we decide to release pages since price depends on pages.
+kem.releaseSavepoint ("pages");
+kem.setSavepoint ("price");
+
+mag.setPrice (testPrice);
+...
+
+// we determine the test price is not good
+kem.rollbackToSavepoint ("price");
+
+// the price is now restored to mag.getPageCount () * pricePerPage
+kem.getTransaction ().commit ();
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_savepoints_conf">
+          <title>Configuring Savepoints</title>
+          <para>
+		OpenJPA uses the <ulink url="javadoc/openjpa/kernel/SavepointManager"><classname>org.apache.openjpa.kernel.SavepointManager</classname></ulink> 
+		<link linkend="ref_guide_conf_plugins">plugin</link> to handle
+		perserving the savepoint state.  OpenJPA includes the following
+		<classname>SavepointManager</classname> plugins:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>in-mem</literal>: The default.  This is an alias
+				for the <ulink url="org.apache.openjpa.kernel.InMemorySavepointManager"><classname>org.apache.openjpa.kernel.InMemorySavepointManager</classname></ulink>.  This plugin stores all state, including field 
+				values, in memory.  Due to this behavior, each set savepoint 
+				is designed for small to medium transactional object counts.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>jdbc</literal>: This is an alias for the <ulink url="org.apache.openjpa.jdbc.kernel.JDBCSavepointManager"><classname>
+				org.apache.openjpa.jdbc.kernel.JDBCSavepointManager</classname></ulink>.
+				This plugin requires <literal>JDBC 3</literal> and <classname>
+				java.sql.Savepoint</classname> support to operate.  Note that 
+				this plugin implements savepoints by issuing a flush to the 
+				database.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>oracle</literal>: This is an alias for the <ulink url="org.apache.openjpa.jdbc.sql.OracleSavepointManager"><classname>
+				org.apache.openjpa.jdbc.sql.OracleSavepointManager</classname></ulink>.
+				This plugin operates similarly to the <literal>JDBC</literal>
+				plugin; however, it uses Oracle-specific calls.
+				This plugin requires using the Oracle JDBC driver and database,
+				versions <literal>9.2</literal> or higher.  Note that this 
+				plugin implements savepoints by issuing a flush to the database.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="ref_guide_enterprise_queryext">
+        <title>Query Language Extensions</title>
+        <indexterm zone="ref_guide_enterprise_queryext">
+          <primary>Query</primary>
+          <secondary>language extensions</secondary>
+          <seealso>JPQL</seealso>
+        </indexterm>
+        <para>
+	JPQL is a powerful, easy-to-use query language, but you may
+	occasionally find it limiting in some way. To circumvent the
+	limitations of JPQL, OpenJPA provides extensions to the JPQL language, and
+	allows you to extend it as well.
+	</para>
+<!-- ### EJBDOC : remove note when parser upgraded -->
+        <warning>
+          <para>
+		The JPQL parser in this release does not yet allow extensions.  They
+		will be made available to JPQL users in a future release.
+		</para>
+        </warning>
+        <section id="ref_guide_enterprise_queryext_jdoql">
+          <title>Filter Extensions</title>
+          <indexterm zone="ref_guide_enterprise_queryext_jdoql">
+            <primary>JPQL</primary>
+            <secondary>language extension</secondary>
+          </indexterm>
+          <para>
+		Filter extensions are custom methods that you can use in your
+		query filter, having, ordering, and result strings.  OpenJPA provides 
+		some built-in filter extensions, and you can develop your own custom 
+		extensions as needed. You can optionally preface all filter extensions 
+		with <literal>ext:</literal> in your query string.  For example, the 
+		following example uses a hypothetical <literal>firstThreeChars
+		</literal> extension to search for cities whose name begins with
+		the 3 characters 'H', 'a', 'r'.
+		</para>
+          <example id="ref_guide_enterprise_queryext_jdoql_ext">
+            <title>Basic Filter Extension</title>
+            <programlisting format="linespecific">
+Query q = em.createQuery ("select c from City c where c.name.ext:firstThreeChars () = 'Har'");
+List results = q.getResultList ();
+</programlisting>
+          </example>
+          <para>
+		Note that it is perfectly OK to chain together extensions.  For
+		example, let's modify our search above to be case-insensitive using
+		another hypothetical extension, <literal>equalsIgnoreCase</literal>:
+		</para>
+          <example id="ref_guide_enterprise_queryext_jdoql_chain">
+            <title>Chaining Filter Extensions</title>
+            <programlisting format="linespecific">
+Query query = em.createQuery ("select c from City c where "
+    + "c.name.ext:firstThreeChars ().ext:equalsIgnoreCase ('Har')");
+List results = q.getResultList ();
+</programlisting>
+          </example>
+          <para>
+		Finally, when using filter extensions you must be aware that any
+		SQL-specific extensions can only execute against the database, and 
+		cannot be used for in-memory queries (recall that OpenJPA executes queries
+		in-memory when you supply a candidate collection rather than a 
+		class, or when you set the <literal>IgnoreChanges</literal>
+		and <literal>FlushBeforeQueries</literal> properties to 
+		<literal>false</literal> and you execute a query within a transaction 
+		in which you've modified data that may affect the results).
+		</para>
+          <section id="ref_guide_enterprise_queryext_jdoql_included">
+            <title>Included Filter Extensions</title>
+            <para>
+			OpenJPA includes two default filter extensions to enhance the power
+			of your queries.
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><indexterm><primary>JPQL</primary><secondary>language extension</secondary><tertiary>getColumn</tertiary></indexterm><literal>getColumn</literal>: Places the proper alias for
+					the given column name into the SELECT statement that is 
+					issued.  This extension cannot be used for in-memory 
+					queries.  When traversing relations, the column is assumed 
+					to be in the primary table of the related type.
+					</para>
+                <programlisting format="linespecific">
+select e from Employee e where e.company.address.ext:getColumn ('ID') = 5
+</programlisting>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>JPQL</primary><secondary>language extension</secondary><tertiary>sql</tertiary></indexterm><literal>sql</literal>: Embeds the given SQL argument
+					into the SELECT statement.
+					This extension cannot be used for in-memory queries.
+					</para>
+                <programlisting format="linespecific">
+select p from Product p where p.price &lt; ext:sql ('(SELECT AVG(PRICE) FROM PRODUCTS)')
+</programlisting>
+              </listitem>
+            </itemizedlist>
+          </section>
+          <section id="ref_guide_enterprise_queryext_jdoql_custom">
+            <title>Developing Custom Filter Extensions</title>
+            <indexterm zone="ref_guide_enterprise_queryext_jdoql_custom">
+              <primary>JPQL</primary>
+              <secondary>language extension</secondary>
+              <tertiary>custom</tertiary>
+            </indexterm>
+            <para>
+			You can write your own extensions by implementing the
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/exps/JDBCFilterListener.html"><classname>org.apache.openjpa.jdbc.kernel.exps.JDBCFilterListener</classname></ulink> interface.  View the Javadoc documentation for details.  
+			Additionally, the source for all of OpenJPA's built-in query 
+			extensions is included in your OpenJPA download to get you started.  
+			The built-in extensions reside in the <filename>
+			src/openjpa/kernel/exps</filename> and <filename>
+			src/openjpa/jdbc/kernel/exps</filename> directories of your 
+			distribution.
+			</para>
+          </section>
+          <section id="ref_guide_enterprise_queryext_jdoql_conf">
+            <title>Configuring Filter Extensions</title>
+            <indexterm zone="ref_guide_enterprise_queryext_jdoql_conf">
+              <primary>JPQL</primary>
+              <secondary>language extension</secondary>
+              <tertiary>configuration</tertiary>
+            </indexterm>
+            <para>
+			There are two ways to register your custom filter extensions with 
+			OpenJPA:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><emphasis>Registration by properties:</emphasis>
+					You can register custom filter extensions by setting the
+					<link linkend="openjpa.FilterListeners"><literal>
+					openjpa.FilterListeners</literal></link> configuration 
+					property to a comma-separated list of plugin strings
+					(see <xref linkend="ref_guide_conf_plugins"/>)
+					describing your extensions classes.  Extensions 
+					registered in this fashion must have a public no-arg 
+					constructor.  They must also be thread safe, because they 
+					will be shared across all queries.
+					</para>
+              </listitem>
+              <listitem>
+                <para><emphasis>Per-query registration:</emphasis>  You can 
+					register filter extensions for an 
+					individual <classname>Query</classname> through the
+					<methodname>OpenJPAQuery.addFilterListener</methodname>
+					method.  You might use per-query registration for very 
+					specific extensions that do not apply globally.
+					</para>
+                <para>
+					See the <classname>OpenJPAQuery</classname>
+					<ulink url="../../api/openjpa/persistence/OpenJPAQuery.html">Javadoc
+					</ulink> for details.
+					</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+        </section>
+        <section id="ref_guide_aggregates_custom">
+          <title>Aggregate Extensions</title>
+          <indexterm zone="ref_guide_aggregates_custom">
+            <primary>JPQL</primary>
+            <secondary>aggregate extension</secondary>
+          </indexterm>
+          <para>
+		Just as you can write your own filter methods, you can write your 
+		own query aggregates by implementing the
+		<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/exps/JDBCAggregateListener.html"><classname>org.apache.openjpa.jdbc.kernel.exps.JDBCAggregateListener</classname></ulink> interface.  View the Javadoc documentation for details.  When
+		using your custom aggregates in result or having query clauses, you can
+		optionally prefix the function name with <literal>ext:</literal> to 
+		identify it as an extension.
+		</para>
+          <section id="ref_guide_aggregates_conf">
+            <title>Configuring Query Aggregates</title>
+            <indexterm zone="ref_guide_aggregates_conf">
+              <primary>JPQL</primary>
+              <secondary>aggregate extension</secondary>
+              <tertiary>configuration</tertiary>
+            </indexterm>
+            <para>
+			There are two ways to register your custom query aggregates with 
+			OpenJPA:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><emphasis>Registration by properties:</emphasis>
+					You can register custom query aggregates by setting the
+					<link linkend="openjpa.AggregateListeners"><literal>
+					openjpa.AggregateListeners</literal></link> configuration 
+					property to a comma-separated list of plugin strings 
+					(see <xref linkend="ref_guide_conf_plugins"/>)
+					describing your aggregate implementation.  Aggregates 
+					registered in this fashion must have a public
+					no-arg constructor.  They must also be thread safe,
+					because they will be shared across all queries.
+					</para>
+              </listitem>
+              <listitem>
+                <para><emphasis>Per-query registration:</emphasis> 
+					You can register query aggregates for an individual 
+					<classname>Query</classname> through the 
+					<methodname>OpenJPAQuery.addAggregateListener</methodname>
+					method.  You might use per-query registration for
+					very specific aggregates that do not apply globally.
+					</para>
+                <para>
+					See the <classname>OpenJPAQuery</classname>
+					<ulink url="../../api/openjpa/persistence/OpenJPAQuery.html">Javadoc
+					</ulink> for details.
+					</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+        </section>
+        <section id="ref_guide_enterprise_methodql">
+          <title>MethodQL</title>
+          <indexterm zone="ref_guide_enterprise_methodql">
+            <primary>MethodQL</primary>
+          </indexterm>
+          <indexterm>
+            <primary>Query</primary>
+            <secondary>MethodQL</secondary>
+            <see>MethodQL</see>
+          </indexterm>
+          <para>
+		If JPQL and SQL queries do not match your needs, OpenJPA also allows you 
+		to name a Java method to use to load a set of objects.
+		In a <emphasis>MethodQL</emphasis> query, the query string 
+		names a static method to invoke to determine the matching objects:
+		</para>
+          <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+// the method query language is 'openjpa.MethodQL'.
+// set the query string to the method to execute, including full class name; if
+// the class is in the candidate class' package or in the query imports, you
+// can omit the package; if the method is in the candidate class, you can omit
+// the class name and just specify the method name
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (emf);
+OpenJPAQuery q = kem.createQuery ("openjpa.MethodQL", "com.xyz.Finder.getByName");
+
+// set the type of objects that the method returns
+q.setResultClass (Person.class);
+
+// parameters are passed the same way as in standard queries
+q.setParameter ("firstName", "Fred").setParameter ("lastName", "Lucas");
+
+// this executes your method to get the results
+List results = q.getResultList ();
+</programlisting>
+          <para>
+		For datastore queries, the method must have the following signature:
+		</para>
+          <programlisting format="linespecific">
+public static <ulink url="../apidocs/org/apache/openjpa/lib/rop/ResultObjectProvider.html">ResultObjectProvider</ulink> xxx(<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html">StoreContext</ulink> ctx, 
+    <ulink url="../apidocs/org/apache/openjpa/meta/ClassMetaData.html">ClassMetaData</ulink> meta, boolean subclasses, Map params, <ulink url="../apidocs/org/apache/openjpa/kernel/FetchConfiguration.html">FetchConfiguration</ulink> fetch)
+</programlisting>
+          <para>
+		The returned result object provider should produce objects of the 
+		candidate class that match the method's search criteria.  If the
+		returned objects do not have all fields in the given fetch configuration
+		loaded, OpenJPA will make additional trips to the datastore as necessary
+		to fill in the data for the missing fields.
+		</para>
+          <para>
+		In-memory execution is slightly different, taking in one object
+		at a time and returning a boolean on whether the object matches the
+		query:
+		</para>
+          <programlisting format="linespecific">
+public static boolean xxx(<ulink url="../apidocs/org/apache/openjpa/kernel/StoreContext.html">StoreContext</ulink> ctx, <ulink url="../apidocs/org/apache/openjpa/meta/ClassMetaData.html">ClassMetaData</ulink> meta, 
+    boolean subclasses, Object obj, Map params, <ulink url="../apidocs/org/apache/openjpa/kernel/FetchConfiguration.html">FetchConfiguration</ulink> fetch)
+</programlisting>
+          <para>
+		In both method versions, the given <literal>params</literal> map 
+		contains the names and values of all the parameters for the query.
+		</para>
+        </section>
+      </section>
+      <section id="ref_guide_sequence">
+        <title>Generators</title>
+        <indexterm zone="ref_guide_sequence">
+          <primary>generators</primary>
+          <secondary>Seq interface</secondary>
+        </indexterm>
+        <para>
+		The JPA Overview's <xref linkend="jpa_overview_mapping"/> details
+		using generators to automatically populate identity fields in JPA.
+		</para>
+        <para>
+		OpenJPA represents all generators internally with the 
+		<ulink url="../apidocs/org/apache/openjpa/kernel/Seq.html"><classname>org.apache.openjpa.kernel.Seq</classname></ulink> interface.  This 
+		interface supplies all the context you need to create your own custom
+		generators, including the current persistence environment,
+		the JDBC <classname>DataSource</classname>, and other essentials.  
+		The <ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/AbstractJDBCSeq.html"><classname>org.apache.openjpa.jdbc.kernel.AbstractJDBCSeq</classname></ulink> helps
+		you create custom JDBC-based sequences.
+		OpenJPA also supplies the following built-in <classname>Seq</classname>s:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para><indexterm><primary>generators</primary><secondary>table</secondary></indexterm><literal>table</literal>: This is OpenJPA's default implementation.
+				It is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/TableJDBCSeq.html"><classname>org.apache.openjpa.jdbc.kernel.TableJDBCSeq</classname></ulink>
+				class.  The <classname>TableJDBCSeq</classname> uses a special
+				single-row table to store a global sequence number.  If the 
+				table does not already exist, it is created the first time you 
+				run the <link linkend="ref_guide_mapping_mappingtool">
+				mapping tool</link>'s on a class that requires it.  You can also
+				use the class' <methodname>main</methodname> method or the
+				<literal>sequencetable</literal> shell/bat script to manipulate
+				the table; see the <methodname>TableJDBCSeq.main</methodname> 
+				method Javadoc for usage details.
+				</para>
+            <para>
+				This <classname>Seq</classname> has the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Table</literal>: The name of the sequence 
+						number table to use.  Defaults to 
+						<literal>OPENJPA_SEQUENCE_TABLE</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>PrimaryKeyColumn</literal>: The name of
+						the primary key column for the sequence table.
+						Defaults to <literal>ID</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>SequenceColumn</literal>:  The name of 
+						the column that will hold the current sequence
+						value.  Defaults to <literal>SEQUENCE_VALUE</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>Allocate</literal>: The number of values to
+						allocate on each database trip.  Defaults to 
+						50, meaning the class will set aside the next 50 
+						numbers each time it accesses the sequence table, which
+						in turn means it only has to make a database trip to 
+						get new sequence numbers once every 50 sequence number
+						requests.
+						</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>generators</primary><secondary>class-table</secondary></indexterm><literal>class-table</literal>: This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/ClassTableJDBCSeq.html"><classname>org.apache.openjpa.jdbc.kernel.ClassTableJDBCSeq
+				</classname></ulink>.  This <classname>Seq</classname> is like
+				the <classname>TableJDBCSeq</classname> above, but maintains a 
+				separate table row, and therefore a separate sequence number,
+				for each base persistent class. It has all the properties of 
+				the <classname>TableJDBCSeq</classname>.  Its table name 
+				defaults to <literal>OPENJPA_SEQUENCES_TABLE</literal>.  It
+				also adds the following properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>IgnoreUnmapped</literal>: Whether to ignore
+						unmapped base classes, and instead use one row per
+						least-derived mapped class.  Defaults to
+						<literal>false</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>UseAliases</literal>: Whether to use
+						each class' entity name as the primary key value of each
+						row, rather than the full class name.  Defaults to
+						<literal>false</literal>.
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				As with the <classname>TableJDBCSeq</classname>, the <classname>
+				ClassTableJDBCSeq</classname> creates its table automatically
+				during mapping tool runs.  However, you can manually manipulate
+				the table through the class' <methodname>main</methodname> 
+				method, or through the <literal>classsequencetable</literal>
+				shell/bat script.  See the Javadoc for the <methodname>
+				ClassTableJDBCSeq.main</methodname> method for usage details.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>generators</primary><secondary>value-table</secondary></indexterm><literal>value-table</literal>: This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/ValueTableJDBCSeq.html"><classname>org.apache.openjpa.jdbc.kernel.ValueTableJDBCSeq
+				</classname></ulink>.  This <classname>Seq</classname> is like
+				the <classname>ClassTableJDBCSeq</classname> above, but has
+				an arbitrary number of rows for sequence values, rather than
+				a fixed pattern of one row per class.   Its table
+				defaults to <literal>OPENJPA_SEQUENCES_TABLE</literal>.
+				It has all the properties of the 
+				<classname>TableJDBCSeq</classname>, plus:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>PrimaryKeyValue</literal>: The primary key
+						value used by this instance.	
+						</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+				As with the <classname>TableJDBCSeq</classname>, the <classname>
+				ValueTableJDBCSeq</classname> creates its table automatically 
+				during mapping tool runs.  However, you can manually manipulate
+				the table through the class' <methodname>main</methodname> 
+				method, or through the <literal>valuesequencetable</literal>
+				shell/bat script.  See the Javadoc for the <methodname>
+				ValueTableJDBCSeq.main</methodname> method for usage details.
+				</para>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>generators</primary><secondary>native</secondary></indexterm><literal>native</literal>: This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/jdbc/kernel/NativeJDBCSeq.html"><classname>org.apache.openjpa.jdbc.kernel.NativeJDBCSeq</classname></ulink>.
+				Many databases have a concept of "native sequences" - a 
+				built-in mechanism for obtaining incrementing 
+				numbers.  For example, in Oracle, you can create a database 
+				sequence with a statement like <literal>CREATE SEQUENCE 
+				MYSEQUENCE</literal>.  Sequence values can then be 
+				atomically obtained and incremented with the statement 
+				<literal>SELECT MYSEQUENCE.NEXTVAL FROM DUAL</literal>.
+				OpenJPA provides support for this common mechanism of 
+				sequence generation with the <classname>
+				NativeJDBCSeq</classname>, which accepts the following 
+				properties:
+				</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Sequence</literal>: The name of the database 
+						sequence.  Defaults to <literal>OPENJPA_SEQUENCE</literal>.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>InitialValue</literal>: The initial sequence
+						value.  Defaults to 1.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>Increment</literal>: The amount the sequence
+						increments.  Defaults to 1.
+						</para>
+              </listitem>
+              <listitem>
+                <para><literal>Allocate</literal>: Some database can allocate
+						values in-memory to service subsequent sequence requests
+						faster. 
+						</para>
+              </listitem>
+            </itemizedlist>
+          </listitem>
+          <listitem>
+            <para><indexterm><primary>generators</primary><secondary>time</secondary></indexterm><literal>time</literal>: This is an alias for the
+				<ulink url="../apidocs/org/apache/openjpa/kernel/TimeSeededSeq.html"><classname>org.apache.openjpa.kernel.TimeSeededSeq</classname></ulink>.
+				This type uses an in-memory static counter, initialized to the 
+				current time in milliseconds and monotonically incremented for 
+				each value requested.  It is only suitable for single-JVM 
+				environments.
+				</para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		You can use JPA <literal>SequenceGenerator</literal>s to describe any
+		built-in <classname>Seq</classname>s or your own <classname>Seq
+		</classname> implementation.  Set the <literal>sequenceName</literal> 
+		attribute to a plugin string describing your choice.  See 
+		<xref linkend="jpa_overview_mapping_sequence"/> in the JPA
+		Overview for details on defining <literal>SequenceGenerator</literal>s.
+		</para>
+        <para>
+		See <xref linkend="ref_guide_conf_plugins"/> for plugin string 
+		formatting.
+		</para>
+        <example id="ref_guide_sequence_named">
+          <title>Named Seq Sequence</title>
+          <programlisting format="linespecific">
+@Entity
+@Table(name="AUTO")
+public class Author
+{
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="AuthorSeq")
+    @SequenceGenerator(name="AuthorSeq" sequence="table(Table=AUTO_SEQ, Increment=100)")
+    @Column(name="AID")
+    private long id;
+ 
+    ...
+}
+</programlisting>
+          <para>
+			Note that if you want to use a plugin string without any arguments,
+			you must still suffix the plugin type with <literal>()</literal>
+			to differentiate it from a sequence name in the <literal>
+			SequenceGenerator.sequence</literal> attribute:
+			</para>
+          <programlisting format="linespecific">
+@SequenceGenerator(name="AuthorSeq", sequence="table()")
+</programlisting>
+        </example>
+        <para>
+		OpenJPA maintains a <emphasis>system</emphasis> sequence to generate 
+		datastore identity values for classes that do not declare a specific 
+		datastore identity strategy.  You can configure the system sequence 
+		through the <link linkend="openjpa.Sequence"><literal>openjpa.Sequence
+		</literal></link> configuration property.  This property accepts a 
+		plugin string describing a <classname>Seq</classname> instance.
+		</para>
+        <example id="ref_guide_sequence_systemex">
+          <title>System Sequence Configuration</title>
+          <programlisting format="linespecific">
+&lt;property name="openjpa.Sequence" value="table(Table=OPENJPASEQ, Increment=100)"/&gt;
+</programlisting>
+        </example>
+        <para>
+		In JPA, set your <literal>GeneratedValue</literal> 
+		annotation's <literal>strategy</literal> attribute to 
+		<literal>AUTO</literal> to use the configured system sequence.  Or,
+		because <literal>AUTO</literal> is the default strategy, use the
+		annotation without attributes:
+		</para>
+        <programlisting format="linespecific">
+@GeneratedValue
+private long id;
+</programlisting>
+        <section id="ref_guide_sequence_runtime">
+          <title>Runtime Access</title>
+          <indexterm zone="ref_guide_sequence_runtime">
+            <primary>Sequence</primary>
+            <secondary>runtime access</secondary>
+          </indexterm>
+          <para>
+			OpenJPA JPA allows you to access named generators at runtime
+			through the <methodname>OpenJPAEntityManager.getNamedGenerator
+			</methodname> method:
+			</para>
+          <programlisting format="linespecific">
+public Generator getNamedGenerator (String name);
+</programlisting>
+          <para>
+			The returned <ulink url="../../api/openjpa/persistence/Generator.html"><classname>org.apache.openjpa.persistence.Generator</classname></ulink> is a 
+			facade over an internal OpenJPA <classname>Seq</classname>.
+			</para>
+          <para>
+			The <classname>OpenJPAEntityManager</classname> includes 
+			additional APIs to retrieve the identity generator of any class, 
+			or the generator of any field.  With these APIs, you do not have
+			to know the generator name.  Additionally, they allow you to access
+			the implicit generator used by default for datastore identity
+			classes.  See the 
+			<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+			Javadoc</ulink> for the <methodname>
+			OpenJPAEntityManager.getIdentityGenerator</methodname> and 
+			<methodname>OpenJPAEntityManager.getFieldGenerator</methodname> 
+			methods for API details.  
+			</para>
+        </section>
+      </section>
+      <section id="ref_guide_runtime_pm_event">
+        <title>Transaction Events</title>
+        <indexterm zone="ref_guide_runtime_pm_event">
+          <primary>transactions</primary>
+          <secondary>events</secondary>
+        </indexterm>
+        <para>
+		The OpenJPA runtime supports
+		broadcasting transaction-related events.  By registering one or more
+		<ulink url="../apidocs/org/apache/openjpa/event/TransactionListener.html"><classname>org.apache.openjpa.event.TransactionListener</classname></ulink>s, you can 
+		receive notifications when transactions begin, flush, rollback, commit,
+		and more.  Where appropriate, event notifications include the set of 
+		persistence-capable objects participating in the transaction.
+		</para>
+        <programlisting format="linespecific">
+public void addTransactionListener (Object listener);
+public void removeTransactionListener (Object listener);
+</programlisting>
+        <para>
+		These <classname>OpenJPAEntityManager</classname> methods allow you
+		to add and remove listeners.
+		</para>
+        <para>
+		For details on the transaction framework, see the <literal>
+		org.apache.openjpa.event</literal> package
+		<ulink url="../apidocs/org/apache/openjpa/event/package.html">Javadoc</ulink>.
+		Also see <xref linkend="ref_guide_event"/> for a description of
+		OpenJPA's remote event support.
+		</para>
+      </section>
+      <section id="ref_guide_enterprise_abstractstore">
+        <title>Non-Relational Stores</title>
+        <para>
+		It is possible to adapt OpenJPA to access a non-relational datastore
+		by creating an implementation of the 
+		<ulink url="../apidocs/org/apache/openjpa/kernel/StoreManager.html"><literal>org.apache.openjpa.kernel.StoreManager</literal></ulink> interface. OpenJPA
+		provides an abstract <literal>StoreManager</literal> implementation to 
+		facilitate this process. See the <literal>org.apache.openjpa.abstractstore</literal> 
+		package <ulink url="../apidocs/org/apache/openjpa/abstractstore">Javadoc</ulink> for 
+		details.  
+		
+		</para>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_caching">
+      <title>Caching</title>
+      <para>
+	OpenJPA utilizes several configurable caches to maximize performance.
+	This chapter explores OpenJPA's data cache, query cache, and query compilation
+	cache.
+	</para>
+      <section id="ref_guide_cache">
+        <title>Data Cache</title>
+        <indexterm zone="ref_guide_cache">
+          <primary>caching</primary>
+          <secondary>data cache</secondary>
+        </indexterm>
+        <para>
+	The OpenJPA data cache is an optional cache of persistent object data that
+	operates at the <classname>EntityManagerFactory</classname>
+	level. This cache is designed to significantly increase
+	performance while remaining in full compliance with the JPA
+	standard. This means that turning on the caching option can
+	transparently increase the performance of your application, with
+	no changes to your code.
+	</para>
+        
+        <para>
+	OpenJPA's data cache is not related to the <classname>EntityManager
+	</classname> cache dictated by the JPA specification. The JPA 
+	specification mandates behavior for the <classname>EntityManager</classname>
+	cache aimed at guaranteeing transaction isolation when operating on
+	persistent objects. 
+	</para>
+        <para>
+	OpenJPA's data cache is designed to
+	provide significant performance increases over cacheless
+	operation, while guaranteeing that behavior will be
+	identical in both cache-enabled and cacheless operation.
+	</para>
+        <para>
+	There are five ways to access data via the OpenJPA APIs:
+	standard relation traversal, large result set relation traversal, 
+	queries, looking up an object by id, and iteration over an 
+	<classname>Extent</classname>. OpenJPA's cache plugin accelerates three of 
+	these mechanisms. It does not provide any caching of large result set 
+	relations or <classname>Extent</classname> iterators. If you find yourself 
+	in need of higher-performance <classname>Extent</classname> iteration, see 
+	<xref linkend="ref_guide_cache_limits_extent"/>.
+	<table><title>Data access methods</title><tgroup cols="2" align="left" colsep="1" rowsep="1"><colspec colname="access-method"/><colspec colname="cacheable"/><thead><row><entry colname="access-method">Access method</entry><entry colname="cacheable">Uses cache</entry></row></thead><tbody><row><entry colname="access-method">
+						Standard relation traversal
+					</entry><entry colname="cacheable">Yes</entry></row><row><entry colname="access-method">
+						Large result set relation traversal
+					</entry><entry colname="cacheable">No</entry></row><row><entry colname="access-method">Query</entry><entry colname="cacheable">Yes</entry></row><row><entry colname="access-method">
+						Lookups by object id
+					</entry><entry colname="cacheable">Yes</entry></row><row><entry colname="access-method">
+						Iteration over an <classname>Extent</classname>
+					</entry><entry colname="cacheable">No</entry></row></tbody></tgroup></table>
+	</para>
+        <para>
+	When enabled, the cache is checked before making a trip to the
+	datastore. Data is stored in the cache when objects are
+	committed and when persistent objects are loaded from the
+	datastore.
+	</para>
+        <para>
+	OpenJPA's data cache can in both single-JVM and multi-JVM environments. 
+	Multi-JVM caching is achieved through the use of the distributed event 
+	notification framework described in <xref linkend="ref_guide_event"/>,
+	or through one of OpenJPA's integrations with third-party distributed caches
+	(see <xref linkend="ref_guide_datacacheintegrations"/>).
+	</para>
+        <para>
+	The single JVM mode of operation maintains and shares a data
+	cache across all <classname>EntityManager</classname>
+	instances obtained from a particular
+	<classname>EntityManagerFactory</classname>. This is not
+	appropriate for use in a distributed environment, as caches in
+	different JVMs or created from different
+	<classname>EntityManagerFactory</classname> objects will
+	not be synchronized.
+	</para>
+        <section id="ref_guide_cache_conf">
+          <title>Data Cache Configuration</title>
+          <para>
+		To enable the basic single-factory cache set the
+		<link linkend="openjpa.DataCache"><literal>openjpa.DataCache</literal></link>
+		property to <literal>true</literal>, and set the
+		<link linkend="openjpa.RemoteCommitProvider"><literal>
+		openjpa.RemoteCommitProvider</literal></link> property to 
+		<literal>sjvm</literal>:
+		</para>
+          <example id="ref_guide_cache_conf_sjvm">
+            <title>Single-JVM Data Cache</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" value="true"/&gt;
+&lt;property name="openjpa.RemoteCommitProvider" value="sjvm"/&gt;
+</programlisting>
+          </example>
+          <para>
+		To configure the data cache to remain up-to-date in a distributed
+		environment, set the <link linkend="openjpa.RemoteCommitProvider"><literal>
+		openjpa.RemoteCommitProvider</literal></link> property appropriately, or
+		integrate OpenJPA with a third-party caching solution.
+		Remote commit providers are described in
+		<xref linkend="ref_guide_event"/>.  
+		<xref linkend="ref_guide_datacacheintegrations"/> enumerates supported
+		third-party caching solutions.
+		</para>
+          <para><indexterm><primary>caching</primary><secondary>size</secondary></indexterm>
+		OpenJPA's default implementation maintains a least-recently-used map 
+		of object ids to cache data. By default,
+		1000 elements are kept in cache. This can be adjusted by setting
+		the <literal>CacheSize</literal> property in your plugin string - see 
+		below for an example.  Objects that are pinned into the cache are not 
+		counted when determining if the cache size exceeds the maximum.
+		</para>
+          <para>
+		Expired objects are moved to a soft reference map, so they may stick 
+		around for a little while longer. You can control
+		the number of soft references OpenJPA keeps with the <literal>
+		SoftReferenceSize</literal> property.  Soft references are unlimited by
+		default.  Set to 0 to disable soft references completely.
+		</para>
+          <example id="ref_guide_cache_conf_size">
+            <title>Data Cache Size</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" value="true(CacheSize=5000, SoftReferenceSize=0)"/&gt;
+</programlisting>
+          </example>
+          <para><indexterm><primary>caching</primary><secondary>timeout</secondary></indexterm>
+		You can specify a cache timeout value for a class by setting the 
+		timeout <link linkend="ref_guide_meta_ext">metadata extension</link>
+		to the amount of time in milliseconds a class's data is valid. Use a 
+		value of -1 for no expiration.  This is the default value.
+		</para>
+          <example id="ex_timeout_cache">
+            <title>Data Cache Timeout</title>
+            <para>
+			Timeout <classname>Employee</classname> objects after 10 seconds.
+			</para>
+            <programlisting format="linespecific">
+@Entity
+@DataCache(timeout=10000)
+public class Employee
+{
+    ...
+}
+</programlisting>
+          </example>
+          <para>
+		See the <ulink url="../apidocs/org/apache/openjpa/persistence/DataCache.html"><classname>org.apache.openjpa.persistence.DataCache</classname></ulink> Javadoc
+		for more information on the <classname>DataCache</classname> annotation.
+		</para>
+          <para><indexterm><primary>caching</primary><secondary>cron-style invalidation</secondary></indexterm>
+		A cache can specify that it should be cleared at certain times
+		rather than using data timeouts.  The
+		<literal>EvictionSchedule</literal> property of OpenJPA's 
+		cache implementation accepts a <literal>cron</literal>
+		style eviction schedule.  The format of this property is a 
+		whitespace-separated list of five tokens, where the 
+		<literal>*</literal> symbol (asterisk), indicates match all.  The 
+		tokens are, in order:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para>Minute</para>
+            </listitem>
+            <listitem>
+              <para>Hour of Day</para>
+            </listitem>
+            <listitem>
+              <para>Day of Month</para>
+            </listitem>
+            <listitem>
+              <para>Month</para>
+            </listitem>
+            <listitem>
+              <para>Day of Week</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+		For example, the following <literal>openjpa.DataCache</literal> setting
+		schedules the default cache to evict values
+		from the cache at 15 and 45 minutes past 3 PM on Sunday.
+		</para>
+          <programlisting format="linespecific">
+true(EvictionSchedule='15,45 15 * * 1')
+</programlisting>
+          <para><indexterm><primary>caching</primary><secondary>named caches</secondary></indexterm>
+		It is also possible for different persistence-capable classes to use
+		different caches. This is achieved by specifying a cache name in
+		a <link linkend="ref_guide_meta_ext">metadata extension</link>.
+		</para>
+          <example id="ex_non_default_cache">
+            <title>Named Data Cache Specification</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@DataCache(name="small-cache", timeout=10000)
+public class Employee
+{
+    ...
+}
+</programlisting>
+          </example>
+          <para>
+		See the <ulink url="../apidocs/org/apache/openjpa/persistence/DataCache.html"><classname>org.apache.openjpa.persistence.DataCache</classname></ulink> Javadoc
+		for more information on the <classname>DataCache</classname> annotation.
+		</para>
+          <para>
+		The metadata above will cause instances of the <classname>Employee
+		</classname> class to be stored in a cache named <literal>
+		small-cache</literal>. 
+		This <literal>small-cache</literal> cache can be explicitly configured 
+		in the <literal>openjpa.DataCache</literal> plugin string, or can be
+		implicitly defined, in which case it will take on the same
+		default configuration properties as the default cache identified
+		in the <literal>openjpa.DataCache</literal> property.
+		</para>
+          <example id="ref_guide_cache_named">
+            <title>Named Data Cache Configuration</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" value="true, true(Name=small-cache, CacheSize=100)"/&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_cache_use">
+          <title>Data Cache Usage</title>
+          <para>
+		The <literal>org.apache.openjpa.datacache</literal> package defines OpenJPA's
+		data caching framework.  While you may use this framework directly
+		(see its <ulink url="../apidocs/org/apache/openjpa/datacache/package-summary.html">
+		Javadoc</ulink> for details), its APIs are meant primarily for 
+		service providers.  In fact, <xref linkend="ref_guide_cache_extension"/>
+		below has tips on how to use this package to extend OpenJPA's caching 
+		service yourself.
+		</para>
+          <para>
+		Rather than use the low-level <literal>org.apache.openjpa.datacache</literal>
+		package APIs, JPA users should typically access the data 
+		cache through OpenJPA's high-level 
+		<ulink url="../../api/openjpa/persistence/StoreCache.html"><classname>org.apache.openjpa.persistence.StoreCache</classname></ulink> facade.  
+		This facade has methods to pin and unpin records, evict data from the 
+		cache, and more.  
+		</para>
+          <programlisting format="linespecific">
+public StoreCache getStoreCache ();
+public StoreCache getStoreCache (String name);
+</programlisting>
+          <para>
+		You obtain the <classname>StoreCache</classname> through the
+		<methodname>OpenJPAEntityManagerFactory.getStoreCache</methodname> methods.
+		When you have multiple data caches configured as in the 
+		<literal>small-cache</literal> example above, the <classname>
+		StoreCache</classname> can act as a unified facade over all your
+		caches.  For every oid parameter to the <classname>StoreCache
+		</classname> methods, it determines the correct data cache for that 
+		oid's corresponding persistent class, and dynamically delegates to 
+		that cache.
+		</para>
+          <para>
+		If you know that you want to access a certain data cache and no others,
+		the <ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html"><methodname>OpenJPAEntityManagerFactory.getStoreCache(String name)
+		</methodname></ulink> method returns a <classname>StoreCache</classname>
+		interface to a particular named data cache.
+		</para>
+          <example id="ref_guide_cache_access_ejb">
+            <title>Accessing the StoreCache</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+StoreCache cache = kemf.getStoreCache ();
+...
+StoreCache smallCache = kemf.getStoreCache ("small-cache");
+...
+</programlisting>
+          </example>
+          <programlisting format="linespecific">
+public void evict (Class cls, Object oid);
+public void evictAll ();
+public void evictAll (Class cls, Object... oids);
+public void evictAll (Class cls, Collection oids);
+</programlisting>
+          <para>
+		The <methodname>evict</methodname> methods tell the cache to release 
+		data.  Each method takes an entity class and one or more identity 
+		values, and releases the cached data for the corresponding persistent 
+		instances.  The <methodname>evictAll</methodname> method with no 
+		arguments clears the cache.  Eviction is useful when the datastore is 
+		changed by a separate process outside OpenJPA's control.  In this 
+		scenario, you typically
+		have to manually evict the data from the datastore cache; otherwise the
+		OpenJPA runtime, oblivious to the changes, will maintain its stale copy.
+		</para>
+          <programlisting format="linespecific">
+public void pin (Class cls, Object oid);
+public void pinAll (Class cls, Object... oids);
+public void pinAll (Class cls, Collection oids);
+public void unpin (Class cls, Object oid);
+public void unpinAll (Class cls, Object... oids);
+public void unpinAll (Class cls, Collection oids);
+</programlisting>
+          <para>
+		Most caches are of limited size.  Pinning an identity to the cache
+		ensures that the cache will mill not kick the data for the corresponding
+		instance out of the cache, unless you manually evict it.  Note that even
+		after manual eviction, the data will get pinned again the next time it 
+		is fetched from the store.  You can only remove a pin and make the data
+		once again available for normal cache overflow eviction through the
+		<methodname>unpin</methodname> methods.  Use pinning when you want a 
+		guarantee that a certain object will always be available from cache, 
+		rather than requiring a datastore trip.
+		</para>
+          <example id="ref_guide_cache_use_ejb">
+            <title>StoreCache Usage</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+StoreCache cache = kemf.getStoreCache ();
+cache.pin (Magazine.class, popularMag.getId ());
+cache.evict (Magazine.class, changedMag.getId ());
+</programlisting>
+          </example>
+          <para>
+		See the <classname>StoreCache</classname> 
+		<ulink url="../../api/openjpa/persistence/StoreCache.html">Javadoc</ulink>
+		for information on additional functionality it provides.
+		Also, <xref linkend="ref_guide_runtime"/> discusses OpenJPA's other 
+		extensions to the standard set of JPA runtime interfaces.
+		</para>
+          <para>
+		The examples above include calls to <methodname>evict</methodname> to
+		manually remove data from the data cache.  Rather than evicting objects 
+		from the data cache directly, you can also configure OpenJPA to 
+		automatically evict objects from the data cache when
+		you use the <classname>OpenJPAEntityManager</classname>'s eviction APIs.
+		</para>
+          <example id="ref_guide_cache_pmevict">
+            <title>Automatic Data Cache Eviction</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/&gt;
+</programlisting>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+kem.evict (changedMag);  // will evict from data cache also
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_cache_query">
+          <title>Query Cache</title>
+          <indexterm zone="ref_guide_cache_query">
+            <primary>caching</primary>
+            <secondary>query cache</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_cache_query">
+            <primary>Query</primary>
+            <secondary>result caching</secondary>
+          </indexterm>
+          <para>
+		In addition to the data cache, the <literal>org.apache.openjpa.datacache</literal>
+		package defines service provider interfaces for a query cache.
+		The query cache is enabled by default when the data cache
+		is enabled. The query cache stores the object ids returned by
+		query executions. When you run a query, OpenJPA assembles a key based on
+		the query properties and the parameters used at execution time,
+		and checks for a cached query result. If one is found, the
+		object ids in the cached result are looked up, and the resultant
+		persistence-capable objects are returned. Otherwise, the query
+		is executed against the database, and the object ids loaded by
+		the query are put into the cache. The object id list is not
+		cached until the list returned at query execution time is fully
+		traversed.
+		</para>
+          <para>
+		OpenJPA JPA exposes a high-level interface to the query cache through
+		the <ulink url="../../api/openjpa/persistence/QueryResultCache.html"><classname>org.apache.openjpa.persistence.QueryResultCache</classname></ulink> class.
+		You can access this class through the <classname>
+		OpenJPAEntityManagerFactory</classname>.
+		</para>
+          <example id="ref_guide_cache_queryaccess">
+            <title>Accessing the QueryResultCache</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+QueryResultCache qcache = kemf.getQueryResultCache ();
+</programlisting>
+          </example>
+          <para>
+		The default query cache implementation caches 100 query
+		executions in a least-recently-used cache. This can be changed
+		by setting the cache size in the <literal>CacheSize</literal>
+		plugin property.  Like the data cache, the query cache also has a
+		backing soft reference map.  The <literal>SoftReferenceSize</literal>
+		property controls the size of this map.  It is disabled by default.
+		</para>
+          <example id="ref_guide_cache_cachesize">
+            <title>Query Cache Size</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.QueryCache" value="CacheSize=1000, SoftReferenceSize=100"/&gt;
+</programlisting>
+          </example>
+          <para>
+		To disable the query cache completely, set the 
+		<literal>openjpa.QueryCache</literal> property to <literal>false</literal>:
+		</para>
+          <example id="ref_guide_cache_disablequery">
+            <title>Disabling the Query Cache</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.QueryCache" value="false"/&gt;
+</programlisting>
+          </example>
+          <para>
+		There are certain situations in which the query cache is bypassed:
+		</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+				Caching is not used for in-memory queries (queries in which 
+				the candidates are a collection instead of a class or 
+				<classname>Extent</classname>).
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Caching is not used in transactions that have 
+				<literal>IgnoreChanges</literal> set to <literal>false</literal>
+				and in which modifications to classes in the query's access 
+				path have occurred. If none of the classes in the access path 
+				have been touched, then cached results are still valid and
+				are used.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Caching is not used in pessimistic transactions, since OpenJPA 
+				must go to the database to lock the appropriate rows.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Caching is not used when the the data cache does not have any
+				cached data for an id in a query result.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Queries that use persistence-capable objects as parameters are
+				only cached if the parameter is directly compared to field,
+				as in:
+				</para>
+              <programlisting format="linespecific">
+select e from Employee e where e.company.address = :addr
+</programlisting>
+              <para>
+				If you extract field values from the parameter in your query
+				string, or if the parameter is used in collection element
+				comparisons, the query is not cached.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Queries that result in projections of custom field types or
+				<classname>BigDecimal</classname> or 
+				<classname>BigInteger</classname> fields are not cached.
+				</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+		Cache results are removed from the cache when instances of
+		classes in a cached query's access path are touched. That is, if
+		a query accesses data in class <classname>A</classname>, and instances 
+		of class <classname>A</classname> are modified, deleted, or inserted, 
+		then the cached query result is dropped from the cache.
+		</para>
+          <para>
+		It is possible to tell the query cache that a class has been altered. 
+		This is only necessary when the changes occur via direct modification 
+		of the database outside of OpenJPA's control.  You can also evict 
+		individual queries, or clear the entire cache.
+		</para>
+          <programlisting format="linespecific">
+public void evict (Query q);
+public void evictAll (Class cls);
+public void evictAll ();
+</programlisting>
+          <para>
+		For JPA queries with parameters, set the desired parameter values
+		into the <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html"><classname>Query</classname></ulink> instance before calling the
+		above methods.
+		</para>
+          <example id="ref_guide_cache_query_classchange">
+            <title>Evicting Queries</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+QueryResultCache qcache = kemf.getQueryResultCache ();
+
+// evict all queries that can be affected by changes to Magazines
+qcache.evictAll (Magazine.class);
+
+// evict an individual query with parameters
+EntityManager em = emf.createEntityManager ();
+Query q = em.createQuery (...).
+    setParameter (0, paramVal0).
+    setParameter (1, paramVal1);
+qcache.evict (q);
+</programlisting>
+          </example>
+          <para>
+		When using one of OpenJPA's distributed cache implementations, it is
+		necessary to perform this in every JVM - the change notification is 
+		not propagated automatically. When using a coherent cache 
+		implementation such as OpenJPA's Tangosol cache implementation, it is not 
+		necessary to do this in every JVM (although it won't hurt to do so), 
+		as the cache results are stored directly in the coherent cache.
+		</para>
+          <para>
+		Queries can also be pinned and unpinned
+		through the <classname>QueryResultCache</classname>.  The semantics of
+		these operations are the same as pinning and unpinning data from the
+		data cache.
+		</para>
+          <programlisting format="linespecific">
+public void pin (Query q);
+public void unpin (Query q);
+</programlisting>
+          <para>
+		For JPA queries with parameters, set the desired parameter values
+		into the <ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/Query.html"><classname>Query</classname></ulink> instance before calling the
+		above methods.
+		</para>
+          <para>
+		The following example shows these APIs in action.
+		</para>
+          <example id="ref_guide_cache_query_pin">
+            <title>Pinning, and Unpinning Query Results</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf);
+QueryResultCache qcache = kemf.getQueryResultCache ();
+EntityManager em = emf.createEntityManager ();
+
+Query pinQuery = em.createQuery (...).
+    setParameter (0, paramVal0).
+    setParameter (1, paramVal1);
+qcache.pin (pinQuery);
+Query unpinQuery = em.createQuery (...).
+    setParameter (0, paramVal0).
+    setParameter (1, paramVal1);
+qcache.unpin (unpinQuery);
+</programlisting>
+          </example>
+          <para>
+		Pinning data into the cache instructs the cache to not expire the 
+		pinned results when cache flushing occurs. However, pinned results 
+		will be removed from the cache if an event occurs that invalidates the 
+		results.
+		</para>
+<!--
+		### known issues:
+			- timeouts of query cache data based on access path timeouts
+			- distributed cache
+				- fire class change notifications
+			- tangosol
+				- either fire ccn's or store queries in cache
+			- access path
+		-->
+          <para>
+		You can disable caching on a per-<classname>EntityManager
+		</classname> or per-<classname>Query</classname> basis:
+		</para>
+          <example id="ref_guide_cache_query_disable">
+            <title>Disabling and Enabling Query Caching</title>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+// temporarily disable query caching for all queries created from em
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+kem.getFetchPlan ().setQueryResultCache (false);
+
+// re-enable caching for a particular query
+OpenJPAQuery kq = kem.createQuery (...);
+kq.getFetchPlan ().setQueryResultCache (true);
+</programlisting>
+            <programlisting format="linespecific">
+import org.apache.openjpa.jdo.*;
+
+...
+
+// temporarily disable query caching for all queries created from pm
+PersistenceManager pm = ...;
+OpenJPAFetchPlan fetch = (OpenJPAFetchPlan) pm.getFetchPlan ();
+fetch.setQueryResultCache (false);
+
+// re-enable caching for a particular query
+Query q = pm.newQuery (...);
+OpenJPAFetchPlan fetch = OpenJPAJDOHelper.cast (pm.getFetchPlan ());
+fetch.setQueryResultCache (true);
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_cache_concurrent">
+          <title>The Concurrent Data Cache</title>
+          <para>
+		The <emphasis>concurrent</emphasis> is a new data cache plugin for OpenJPA.
+		It has not been as thoroughly tested as OpenJPA's standard data cache. 
+		The concurrent cache can, however, offer considerably greater 
+		performance and scalability characteristics compared to the standard 
+		cache when the following conditions are met:  
+		</para>
+          <orderedlist>
+            <listitem>
+              <para>
+				The cache is big enough to hold all of your commonly-used data.	
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Your application is heavily concurrent.
+				</para>
+            </listitem>
+          </orderedlist>
+          <para>
+		Additionally, this cache does not fully index its contents by class,
+		but rather just keeps track of which clasess are in the cache. It 
+		services requests to drop given classes by checking to see if any 
+		instances of that class might be in the cache, and then clearing the
+		entire cache. This inefficiency can easily be worked around with careful
+		cache partitioning.
+		</para>
+          <para>
+		To use the concurrent data cache instead of the standard data cache, 
+		set your <literal>openjpa.DataCache</literal> property to 
+		<literal>concurrent</literal> instead of <literal>true</literal>.
+		Or, you can mix concurrent and standard caches in a set of named
+		caches.
+		</para>
+          <para>
+		The concurrent cache has the following configuration parameters:
+		</para>
+          <orderedlist>
+            <listitem>
+              <para><literal>CacheSize</literal>: The maximum number of 
+				objects that this cache will hold. The default is 1000 objects. 
+				This setting differs from the setting for the default data cache
+				in that instances that are pinned into cache do count towards 
+				this limit.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>Name</literal>: The unique name of the cache.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>EvictionSchedule</literal>: A cron-style eviction
+				schedule that this cache should follow.
+				</para>
+            </listitem>
+            <listitem>
+              <para><literal>LRUThresholdRatio</literal>: The ratio above which 
+				this implementation should start applying its 
+				least-recently-used algorithm to prepare for eviction should 
+				the need arise. Default is 80%. Values should be integers 
+				between 1 and 100.
+				</para>
+            </listitem>
+          </orderedlist>
+          <example id="ref_guide_cache_concurrent_conf">
+            <title>Concurrent Data Cache Configuration</title>
+            <para>
+			The following configuration uses the standard OpenJPA cache as the
+			primary cache and a named concurrent cache as a secondary cache.
+			Various classes can be configured to use this secondary cache in
+			their metadata.
+			</para>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" value="true, concurrent(Name=secondary)"/&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_datacacheintegrations">
+          <title>Third-Party Integrations</title>
+          <para>
+		OpenJPA includes built-in integrations with Tangosol Coherence and
+		GemStone GemFire caching products.
+		</para>
+          <section id="ref_guide_cache_tangosol">
+            <title>Tangosol Integration</title>
+            <indexterm zone="ref_guide_cache_tangosol">
+              <primary>caching</primary>
+              <secondary>tangosol integration</secondary>
+            </indexterm>
+            <para>
+			The OpenJPA data cache can integrate with Tangosol's Coherence caching
+			system.  To use Tangosol integration, set the 
+			<link linkend="openjpa.DataCache"><literal>openjpa.DataCache</literal></link> configuration property to <literal>tangosol</literal>, with
+			the appropriate plugin properties for your Tangosol setup.  For 
+			example:
+			</para>
+            <example id="ref_guide_cache_tangosol_conf">
+              <title>Tangosol Cache Configuration</title>
+              <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" value="tangosol(TangosolCacheName=openjpa)"/&gt;
+</programlisting>
+            </example>
+            <para>
+			The Tangosol cache understands the following properties:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>TangosolCacheName</literal>: The name of the 
+					Tangosol Coherence cache to use.  Defaults to 
+					<literal>openjpa</literal>.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>TangosolCacheType</literal>: The type of Tangosol 
+					Coherence cache to use (optional).  Valid values are
+					<literal>named</literal>, <literal>distributed</literal>, or
+					<literal>replicated</literal>. Defaults to <literal>
+					named</literal>, which means that the cache is looked 
+					up via the <literal>
+					com.tangosol.net.CacheFactory.getCache(String)</literal>
+					method. This method looks up the cached by name as
+					defined in the Coherence configuration.
+					</para>
+                <note>
+                  <para>
+						As of this writing, it is not possible to use a Tangosol
+						Coherence 1.2.2 distributed cache type with Apple's OS X
+						1.3.1 JVM. Use their replicated cache instead.
+						</para>
+                </note>
+              </listitem>
+              <listitem>
+                <para><literal>ClearOnClose</literal>: Whether the Tangosol
+					named cache should be completely cleared when the
+					<phrase><classname>EntityManagerFactory</classname></phrase>
+					
+					
+					is closed.  Defaults to <literal>false</literal>.
+					</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+			The OpenJPA query cache can also integrate with Tangosol's Coherence 
+			caching system.  To use Tangosol query cache integration, set the 
+			<link linkend="openjpa.QueryCache"><literal>openjpa.QueryCache</literal></link> configuration property to <literal>tangosol</literal>, 
+			with the appropriate plugin properties for your Tangosol setup.  
+			For example:
+			</para>
+            <example id="ref_guide_cache_tangosol_query_conf">
+              <title>Tangosol Query Cache Configuration</title>
+              <programlisting format="linespecific">
+&lt;property name="openjpa.QueryCache" value="tangosol(TangosolCacheName=openjpa-query)"/&gt;
+</programlisting>
+            </example>
+            <para>
+			The Tangosol query cache understands the same properties as the 
+			data cache, with a default Tangosol cache name of 
+			<literal>openjpa-query</literal>.
+			</para>
+          </section>
+          <section id="ref_guide_cache_gemfire">
+            <title>GemStone GemFire Integration</title>
+            <para>
+			The OpenJPA data cache can integrate with GemStone's GemFire v3.5.1
+			caching system.
+			later. To use GemFire in OpenJPA you will need to change your
+			<literal>gemfire.properties</literal> to have the property 
+			<literal>enable-shared-memory=true</literal>.  You will also need 
+			to add both OpenJPA and GemFire to your classpath and then start 
+			a GemFire server.
+			</para>
+            <programlisting format="linespecific">
+prompt&gt; gemfire start
+</programlisting>
+            <para>
+			By default, the GemFire data cache will use a GemFire region of 
+			<literal>root/openjpa-data-cache</literal> and the GemFire query cache 
+			will use a region of <literal>root/openjpa-query-cache</literal>. This 
+			can be changed be setting the optional property 
+			<literal>GemFireCacheName</literal>. 
+			</para>
+            <example id="ref_guide_datacacheintegrations_gemfire_conf">
+              <title>GemFire Cache Configuration</title>
+              <para><filename>persistence.xml</filename>:
+				</para>
+              <programlisting format="linespecific">
+&lt;property name="openjpa.DataCache" 
+    value="gemfire(GemFireCacheName=/root/my-openjpa-data-cache)"/&gt;
+&lt;property name="openjpa.QueryCache" 
+    value="gemfire(GemFireCacheName=/root/my-openjpa-query-cache)"/&gt;
+</programlisting>
+              <para>GemFire <filename>cache.xml</filename>:</para>
+              <programlisting format="linespecific">
+...
+    &lt;shared-root-region name="root"&gt;
+        &lt;region-attributes&gt;
+        ...
+        &lt;/region-attributes&gt;
+        &lt;region name="My-openjpa-data-cache"&gt;
+            &lt;region-attributes&gt;
+            &lt;/region-attributes&gt;
+        &lt;/region&gt;
+        &lt;region name="My-openjpa-query-cache"&gt;
+            &lt;region-attributes&gt;
+            &lt;/region-attributes&gt;
+        &lt;/region&gt;
+    &lt;/shared-root-region&gt;
+    ...
+</programlisting>
+            </example>
+            <para>
+			If you set GemFire for both <literal>openjpa.DataCache</literal> and 
+			<literal>openjpa.QueryCache</literal> you aren't required to 
+			specify a <literal>openjpa.RemoteCommitProvider</literal> unless you 
+			are registering your own <classname>
+			RemoteCommitListener</classname>s.
+			</para>
+            <para>
+			Some notes regarding using GemFire with OpenJPA:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para>
+					Custom field types mapped with externalizers or custom 
+					mappings must be serializable.
+					</para>
+              </listitem>
+              <listitem>
+                <para>
+					The <link linkend="openjpa.DynamicDataStructs"><literal>
+					openjpa.DynamicDataStructs</literal></link> option
+					is not supported.
+					</para>
+              </listitem>
+            </itemizedlist>
+          </section>
+        </section>
+        <section id="ref_guide_cache_extension">
+          <title>Cache Extension</title>
+          <indexterm zone="ref_guide_cache_extension">
+            <primary>caching</primary>
+            <secondary>data cache</secondary>
+            <tertiary>extension</tertiary>
+          </indexterm>
+          <indexterm zone="ref_guide_cache_extension">
+            <primary>caching</primary>
+            <secondary>query cache</secondary>
+            <tertiary>extension</tertiary>
+          </indexterm>
+          <para>
+		The provided data cache classes can be easily extended to
+		add additional functionality. If you are adding new behavior,
+		you should extend <classname>org.apache.openjpa.datacache.DataCacheImpl</classname>. 
+		To use your own storage mechanism, extend
+		<classname>org.apache.openjpa.datacache.AbstractDataCache</classname>, or implement
+		<classname>org.apache.openjpa.datacache.DataCache</classname> directly.
+		If you want to implement a distributed cache that uses an
+		unsupported method for communications, create an implementation
+		of <classname>org.apache.openjpa.event.RemoteCommitProvider</classname>. This 
+		process is described in greater detail in 
+		<xref linkend="ref_guide_event_customization"/>.
+		</para>
+          <para>
+		The query cache is just as easy to extend.  Add functionality by 
+		extending the default 
+		<classname>org.apache.openjpa.datacache.QueryCacheImpl</classname>.  Implement your
+		own storage mechanism for query results by extending 
+		<classname>org.apache.openjpa.datacache.AbstractQueryCache</classname> or implementing
+		the <classname>org.apache.openjpa.datacache.QueryCache</classname> interface directly.
+		</para>
+        </section>
+        <section id="ref_guide_cache_notes">
+          <title>Important Notes</title>
+          <itemizedlist>
+            <listitem>
+              <para>
+				The default cache implementations <emphasis>do not</emphasis> 
+				automatically refresh objects in other <classname>
+				EntityManager</classname>s
+				when the cache is updated or invalidated. This behavior would 
+				not be compliant with the JPA specification.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				Invoking <methodname>OpenJPAEntityManager.evict</methodname>
+				<emphasis>does not</emphasis> result in
+				the corresponding data being dropped from the data cache, unless
+				you have set the proper configuration options as explained 
+				above (see <xref linkend="ref_guide_cache_pmevict"/>).  Other 
+				methods related to the <classname>EntityManager</classname>
+				cache also do not effect the data cache.
+				</para>
+              <para>
+				The data cache 
+				assumes that it is up-to-date with respect to the datastore, 
+				so it is effectively an in-memory extension of the database. To 
+				manipulate the data cache, you should generally use the data
+				cache facades presented in this chapter.
+				</para>
+            </listitem>
+            <listitem>
+              <para>
+				You must specify a <classname>org.apache.openjpa.event.RemoteCommitProvider
+				</classname> (via the <link linkend="openjpa.RemoteCommitProvider"><literal>openjpa.RemoteCommitProvider</literal></link> 
+				property) in order to use the data cache, even when using the 
+				cache in a single-JVM mode.  When using it in a single-JVM 
+				context, set this property to <literal>sjvm</literal>.
+				</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="datastore_cache_issues">
+          <title>Known Issues and Limitations</title>
+          <indexterm zone="datastore_cache_issues">
+            <primary>caching</primary>
+            <secondary>issues and limitations</secondary>
+          </indexterm>
+          <itemizedlist>
+            <listitem>
+              <para>
+				When using datastore (pessimistic) transactions in concert 
+				with the distributed caching implementations, it is possible 
+				to read stale data when reading data outside a transaction.
+				</para>
+              <para>
+				For example, if you have two JVMs (JVM A and JVM B) both 
+				communicating with each other, and JVM A obtains a data
+				store lock on a particular object's underlying data, it is
+				possible for JVM B to load the data from the cache without
+				going to the datastore, and therefore load data that should
+				be locked. This will only happen if JVM B attempts to read
+				data that is already in its cache during the period between
+				when JVM A locked the data and JVM B received and processed
+				the invalidation notification.
+				</para>
+              <para>
+				This problem is impossible to solve without putting together a 
+				two-phase commit system for cache notifications, which would 
+				add significant overhead to the caching implementation. As a 
+				result, we recommend that people use optimistic locking when 
+				using data caching. If you do not, then understand that some 
+				of your non-transactional data may not be consistent with the 
+				datastore.
+				</para>
+              <para>
+				Note that when loading objects in a transaction, the 
+				appropriate datastore transactions will be obtained. So,
+				transactional code will maintain its integrity.
+				</para>
+            </listitem>
+            <listitem>
+              <para><classname>Extent</classname>s are not cached. So, if you plan 
+				on iterating over a list of all the objects in an 
+				<classname>Extent</classname> on a regular basis, you will 
+				only benefit from caching if you do so with a 
+				<classname>Query</classname> instead:
+				</para>
+              <example id="ref_guide_cache_limits_extent">
+                <title>Query Replaces Extent</title>
+                <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+Extent extent = kem.getExtent (Magazine.class, false);
+
+// This iterator does not benefit from caching...
+Iterator uncachedIterator = extent.iterator ();
+
+// ... but this one does.
+OpenJPAQuery extentQuery = kem.createQuery (...);
+extentQuery.setSubclasses (false);
+Iterator cachedIterator = extentQuery.getResultList ().iterator ();
+</programlisting>
+              </example>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+      <section id="ref_guide_cache_querycomp">
+        <title>Query Compilation Cache</title>
+        <indexterm zone="ref_guide_cache_querycomp">
+          <primary>caching</primary>
+          <secondary>query compilation cache</secondary>
+        </indexterm>
+        <para>
+		The query compilation cache is a <classname>Map</classname> used to
+		cache parsed query strings.  As a result, most queries are
+		only parsed once in OpenJPA, and cached thereafter.  You can control the
+		compilation cache through the 
+		<link linkend="openjpa.QueryCompilationCache"><literal>
+		openjpa.QueryCompilationCache</literal></link> configuration property.
+		This property accepts a plugin string (see 
+		<xref linkend="ref_guide_conf_plugins"/>) describing the
+		<classname>Map</classname> used to associate query strings and their 
+		parsed form.  This property accepts the following aliases:
+		</para>
+        <table>
+          <title>Pre-defined aliases</title>
+          <tgroup cols="2" align="left" colsep="1" rowsep="1">
+            <colspec colname="alias"/>
+            <colspec colname="value"/>
+            <colspec colname="notes"/>
+            <thead>
+              <row>
+                <entry colname="alias">Alias</entry>
+                <entry colname="value">Value</entry>
+                <entry colname="notes">Notes</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry colname="alias">
+                  <literal>true</literal>
+                </entry>
+                <entry colname="value">
+                  <literal>openjpa.util.CacheMap</literal>
+                </entry>
+                <entry colname="notes">
+							The default option.  Uses a 
+							<ulink url="../apidocs/org/apache/openjpa/util/CacheMap.html"><literal>CacheMap</literal></ulink> to store 
+							compilation data.  <literal>CacheMap</literal> uses
+							a least-recently-used strategy for a fixed number 
+							of cache entries, and an optional soft reference 
+							map for entries that are moved out of the LRU 
+							space. So, for applications that have a 
+							monotonically increasing number of distinct queries,
+							this option can be used to ensure that a fixed 
+							amount of memory is used by the cache.
+						</entry>
+              </row>
+              <row>
+                <entry colname="alias">
+                  <literal>all</literal>
+                </entry>
+                <entry colname="value">
+                  <literal>java.util.HashMap</literal>
+                </entry>
+                <entry colname="notes">
+							This is the fastest option, but compilation data is
+							never dropped from the cache, so if you use a large 
+							number of dynamic queries, this option may result in
+							ever-increasing memory usage. Note that if your 
+							queries only differ in the values of the parameters,
+							this should not be an issue.
+						</entry>
+              </row>
+              <row>
+                <entry colname="alias">
+                  <literal>false</literal>
+                </entry>
+                <entry colname="value">
+                  <emphasis>none</emphasis>
+                </entry>
+                <entry colname="notes">
+							Disables the compilation cache.
+						</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_remote">
+      <title>Remote and Offline Operation</title>
+      <indexterm zone="ref_guide_remote">
+        <primary>remote</primary>
+      </indexterm>
+      <indexterm>
+        <primary>offline</primary>
+        <see>remote</see>
+      </indexterm>
+      <para>
+	The standard JPA runtime environment is 
+	<emphasis>local</emphasis> and <emphasis>online</emphasis>.  It is 
+	<emphasis>local</emphasis> in that components such as 
+	<classname>EntityManager</classname>s and queries connect directly to
+	the datastore and execute their actions in the same JVM as the code using 
+	them.  It is <emphasis>online</emphasis> in that all changes to managed 
+	objects must be made in the context of an active <classname>
+	EntityManager</classname>.  
+	These two properties, combined with the fact that <classname>
+	EntityManager</classname>s cannot be serialized for storage or network 
+	transfer, make the standard JPA runtime difficult to 
+	incorporate into some enterprise and client/server program designs.
+	</para>
+      <para>
+	OpenJPA extends the standard runtime to add <emphasis>remote</emphasis>
+	and <emphasis>offline</emphasis> capabilities in the form of enhanced
+	<link linkend="ref_guide_detach">Detach and Attach APIs</link> and
+	<link linkend="ref_guide_event">Remote Commit Events</link>.
+	The following sections explain these capabilities in detail.
+	</para>
+      <section id="ref_guide_detach">
+        <title>Detach and Attach</title>
+        <indexterm zone="ref_guide_detach">
+          <primary>detachment</primary>
+        </indexterm>
+        <indexterm>
+          <primary>attachment</primary>
+          <see>detachment</see>
+        </indexterm>
+<!-- ### EJBDOC : more specific links to EM detach discussion -->
+        <para>
+		The JPA Overview describes the specification's standard 
+		detach and attach APIs in <xref linkend="jpa_overview_em"/>.  
+		This section enumerates OpenJPA's enhancements to the standard behavior.
+		</para>
+        <section id="ref_guide_detach_behavior">
+          <title>Detach Behavior</title>
+          <indexterm zone="ref_guide_detach_behavior">
+            <primary>detachment</primary>
+            <secondary>behavior</secondary>
+          </indexterm>
+          <para>
+			In JPA, objects detach automatically when they are
+			serialized or when a <link linkend="jpa_overview_emfactory_perscontext">persistence 
+			context</link> ends.  The specification does not define any way to
+			explicitly detach objects.  The extended 
+			<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>OpenJPAEntityManager</classname></ulink>, however, allows 
+			you to explicitly detach objects at any time.
+			</para>
+          <programlisting format="linespecific">
+public Object detach (Object pc):
+public Object[] detachAll (Object... pcs):
+public Collection detachAll (Collection pcs):
+</programlisting>
+          <para>
+			Each detach method returns detached copies of the given instances.
+			The copy mechanism is similar to serialization, except that only 
+			certain fields are traversed. We will see how to control which 
+			fields are detached in a later section.
+			</para>
+          <para><indexterm><primary>detachment</primary><secondary>of dirty objects</secondary></indexterm>
+			When detaching an instance that has been modified in the current
+			transaction (and thus made dirty), the current transaction
+			is flushed. This means that when subsequently re-attaching 
+			the detached instances, OpenJPA assumes that the transaction from 
+			which they were originally detached was committed; if 
+			it has been rolled back, then the re-attachment process will throw 
+			an optimistic concurrency exception.
+			</para>
+          <para>
+			You can stop OpenJPA from assuming the transaction will commit by
+			invoking <methodname>OpenJPAEntityManager.setRollbackOnly</methodname> 
+			prior to detaching your objects.  Setting the 
+			<literal>RollbackOnly</literal> flag prevents OpenJPA from flushing 
+			when detaching dirty objects; instead OpenJPA just runs its pre-flush 
+			actions (see the 
+			<methodname>OpenJPAEntityManager.preFlush</methodname>
+			<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+			Javadoc</ulink> for details).
+			</para>
+          <para>
+			This allows you to use the same 
+			instances in multiple attach/modify/detach/rollback cycles.  
+			Alternatively, you might also prevent a flush by making your 
+			modifications outside of a transaction (with 
+			<literal>NontransactionalWrite</literal> enabled) before detaching.
+			</para>
+        </section>
+        <section id="ref_guide_attach_behavior">
+          <title>Attach Behavior</title>
+          <indexterm zone="ref_guide_attach_behavior">
+            <primary>attachment</primary>
+            <secondary>behavior</secondary>
+          </indexterm>
+          <para>
+			When attaching, OpenJPA uses several strategies to determine the 
+			optimal way to merge changes made to the detached instance.  As 
+			you will see, these strategies can even be used to attach changes 
+			made to a transient instance which was never detached in the first 
+			place.
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					If the instance was detached and 
+					<link linkend="ref_guide_detach_graph">detached state</link>
+					is enabled, OpenJPA will use the detached state to determine 
+					the object's version and primary key values.  In addition,
+					this state will tell OpenJPA which fields were loaded at the 
+					time of detach, and in turn where to expect changes.  Loaded
+					detached fields with null values will set the attached
+					instance's corresponding fields to null.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					If the instance has
+					<phrase>
+					a <literal>Version</literal> field,
+					</phrase>
+					
+					
+					OpenJPA will consider the object detached if the version
+					field has a non-default value, and new otherwise.  
+					</para>
+              <para>
+					When attaching null fields in these cases, OpenJPA cannot 
+					distinguish between a field that was unloaded and one that
+					was intentionally set to null. In this case, OpenJPA will use 
+					the current 
+					<link linkend="ref_guide_detach_graph">detach state</link>
+					setting to determine how to handle null fields: 
+					fields that would have been included in the detached state 
+					are treated as loaded, and will in turn set the 
+					corresponding attached field to null.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					If neither of the above cases apply, OpenJPA will check to
+					see if an instance with the same primary key values exists
+					in the database.  If so, the object is considered detached.
+					Otherwise, it is considered new.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <para>
+			These strategies will be assigned on a per-instance basis,
+			such that during the attachment of an object graph more than
+			one of the above strategies may be used.
+			</para>
+          <para>
+			If you attempt to attach a versioned instance whose representation 
+			has changed in the datastore since detachment, OpenJPA will throw an
+			optimistic concurrency exception upon commit or flush, just as if 
+			a normal optimistic conflict was detected. When attaching an 
+			instance whose database record has 
+			been deleted since detaching, or when attaching a detached 
+			instance into a manager that has a stale version of the object, 
+			OpenJPA will throw an optimistic concurrency exception
+			from the attach method. In these cases, OpenJPA sets the 
+			<literal>RollbackOnly</literal> flag on the transaction.
+			</para>
+        </section>
+        <section id="ref_guide_detach_graph">
+          <title>Defining the Detached Object Graph</title>
+          <indexterm zone="ref_guide_detach_graph">
+            <primary>detachment</primary>
+            <secondary>defining the object graph</secondary>
+          </indexterm>
+          <para>
+			When detached objects lose their association with the OpenJPA
+			runtime, they also lose the ability to load additional state
+			from the datastore.  It is important, therefore, to populate objects
+			with all the persistent state you will need before detaching them.
+			While you are free to do this manually, OpenJPA includes
+			facilities for automatically populating objects when they detach.
+			The <link linkend="openjpa.DetachState"><literal>openjpa.DetachState
+			</literal></link> configuration property determines which fields
+			and relations are detached by default.   All settings are recursive.
+			They are:
+			</para>
+          <orderedlist>
+            <listitem>
+              <para><literal>loaded</literal>: Detach all fields and relations 
+					that are already loaded, but don't include unloaded fields 
+					in the detached graph.  This is the default.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>fgs</literal>: Detach all fields and relations in 
+					the default fetch group, and any other fetch groups that 
+					you have added to the current
+					<link linkend="ref_guide_runtime">fetch 
+					configuration</link>.  For more information on custom 
+					fetch groups, see <xref linkend="ref_guide_fetch"/>.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>all</literal>: Detach all fields and relations.  
+					Be very careful when
+					using this mode; if you have a highly-connected domain 
+					model, you could end up bringing every object in the
+					database into memory!
+					</para>
+            </listitem>
+          </orderedlist>
+          <para>
+  			Any field that is not included in the set determined by the detach
+			mode is set to its Java default value in the detached instance.
+			</para>
+          <para>
+			The <literal>openjpa.DetachState</literal> option is actually a 
+			plugin string (see <xref linkend="ref_guide_conf_plugins"/>) that
+			allows you to also configure the following options related to
+			detached state:
+			</para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>DetachedStateField</literal>: As described in 
+					<xref linkend="ref_guide_attach_behavior"/> above, OpenJPA can
+					take advantage of a <emphasis>detached state field
+					</emphasis> to make the attach process more efficient.
+					This field is added by the enhancer and is not visible to
+					your application.  Set this property to one of the
+					following values:
+					</para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>transient</literal>: Use a transient 
+							detached state field.  This gives the benefits of
+							a detached state field to local objects that are
+							never serialized, but retains
+							serialization compatibility for client tiers without
+							access to the enhanced versions of your classes. 
+							This is the default.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>true</literal>: Use a non-transient 
+							detached state field so that objects crossing
+							serialization barriers can still be attached 
+							efficiently.  This requires, however, that your
+							client tier have the enhanced versions of your
+							classes and the OpenJPA libraries.
+							</para>
+                </listitem>
+                <listitem>
+                  <para><literal>false</literal>: Do not use a detached
+							state field.
+							</para>
+                </listitem>
+              </itemizedlist>
+              <para>
+					You can override the setting of this property or declare
+					your own detached state field on individual classes using 
+					OpenJPA's metadata extensions.  See 
+					<xref linkend="ref_guide_detach_field"/> below.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>DetachedStateManager</literal>: Whether to use a
+					detached state manager.  A detached state manager makes
+					attachment much more efficient.  Like a detached state 
+					field, however, it breaks serialization compatibility with
+					the unenhanced class if it isn't transient.
+					</para>
+              <para>
+					This setting piggybacks on the <literal>DetachedStateField
+					</literal> setting above.  If your detached state field is 
+					transient, the detached state manager will also be 
+					transient. If the detached state field is disabled, the 
+					detached state manager will also be disabled.  This is 
+					typically what you'll want.  By setting <literal>
+					DetachedStateField</literal> to true (or transient) and 
+					setting this property to false, however, you can use a 
+					detached state field <emphasis role="bold">without
+					</emphasis> using a detached state manager.   This may be 
+					useful for debugging or for legacy OpenJPA users who find 
+					differences between OpenJPA's behavior with a detached state 
+					manager and OpenJPA's older behavior without one.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>AccessUnloaded</literal>: Whether to allow access
+					to unloaded fields of detached objects.  Defaults to true.
+					Set to false to throw an exception whenever an unloaded
+					field is accessed.  This option is only available when you
+					use detached state managers, as determined by the settings
+					above.
+					</para>
+            </listitem>
+          </itemizedlist>
+          <example id="ref_guide_detach_graph_confex">
+            <title>Configuring Detached State</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.DetachState" value="fgs(DetachedStateField=true)"/&gt;
+</programlisting>
+          </example>
+          <para>
+			You can also alter the set of fields that will be included in the
+			detached graph at runtime.
+			<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>OpenJPAEntityManager</classname></ulink>s expose the 
+			following APIs for controlling detached state:
+			</para>
+          <programlisting format="linespecific">
+public static final int DETACH_LOADED;
+public static final int DETACH_FGS;
+public static final int DETACH_ALL;
+public int getDetachState ();
+public void setDetachState (int mode);
+</programlisting>
+          <section id="ref_guide_detach_field">
+            <title>Detached State Field</title>
+            <indexterm zone="ref_guide_detach_field">
+              <primary>detachment</primary>
+              <secondary>detached state field</secondary>
+            </indexterm>
+            <para>
+				When the detached state field is enabled, the OpenJPA enhancer 
+				adds an additional field to the enhanced version of your class.
+				This field of type <classname>Object</classname>.  OpenJPA uses
+				this field for bookkeeping information, such as the versioning
+				data needed to detect optimistic concurrency violations when the
+				object is re-attached. 
+				</para>
+            <para>
+				It is possible to define this detached state field yourself.
+				Declaring this field in your class metadata prevents the 
+				enhancer from adding any extra fields to the class, and keeps 
+				the enhanced class serialization-compatible with 
+				the unenhanced version.
+				The detached state field must not be persistent.
+				See <xref linkend="detached-state-field"/> for details on
+				how to declare a detached state field.
+				</para>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Magazine
+    implements Serializable
+{
+    private String name;
+    @DetachedState private Object state;
+    ...
+}
+</programlisting>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_event">
+        <title>Remote Event Notification Framework</title>
+        <indexterm zone="ref_guide_event">
+          <primary>remote</primary>
+          <secondary>events</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>events</primary>
+          <secondary>remote</secondary>
+          <see>remote, events</see>
+        </indexterm>
+        <para><indexterm><primary>remote</primary><secondary>events</secondary><tertiary>RemoteCommitProvider</tertiary></indexterm><indexterm><primary>remote</primary><secondary>events</secondary><tertiary>RemoteCommitListener</tertiary></indexterm>
+	The remote event notification framework allows a subset of the 
+	information available through OpenJPA's transaction events (see 
+	<xref linkend="ref_guide_runtime_pm_event"/>) to be broadcast to remote 
+	listeners.  OpenJPA's <link linkend="ref_guide_cache">data cache</link>, for 
+	example, uses remote events to remain synchronized when deployed in 
+	multiple JVMs.
+	</para>
+        
+        <para>
+	To enable remote events, you must configure the <classname>
+	EntityManagerFactory</classname> to use a  
+	<literal>RemoteCommitProvider</literal> (see below). 
+	</para>
+        <para>
+	When a <literal>RemoteCommitProvider</literal> is properly configured, you 
+	can register <ulink url="../apidocs/org/apache/openjpa/event/RemoteCommitListener.html"><classname>RemoteCommitListener</classname></ulink>s that will be alerted 
+	with a list of modified object ids whenever a transaction on a remote 
+	machine successfully commits.
+	</para>
+        <section id="ref_guide_event_conf">
+          <title>Remote Commit Provider Configuration</title>
+          <indexterm zone="ref_guide_event_conf">
+            <primary>remote</primary>
+            <secondary>events</secondary>
+            <tertiary>configuration</tertiary>
+          </indexterm>
+          <para>
+		OpenJPA includes built in remote commit providers for JMS and TCP 
+		communication.
+		</para>
+          <section id="ref_guide_event_conf_jms">
+            <title>JMS</title>
+            <indexterm zone="ref_guide_event_conf_jms">
+              <primary>remote</primary>
+              <secondary>events</secondary>
+              <tertiary>JMS</tertiary>
+            </indexterm>
+            <para>
+			OpenJPA includes built in remote commit providers for JMS and TCP
+			communication.  The JMS remote commit provider can be configured by 
+			setting the <link linkend="openjpa.RemoteCommitProvider"><literal>
+			openjpa.RemoteCommitProvider</literal></link> property
+			to contain the appropriate configuration properties. The JMS
+			provider understands the following properties:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Topic</literal>: The topic that the remote commit
+					provider should publish notifications to and subscribe
+					to for notifications sent from other JVMs.  Defaults to
+					<literal>topic/OpenJPACommitProviderTopic</literal></para>
+              </listitem>
+              <listitem>
+                <para><literal>TopicConnectionFactory</literal>: The JNDI name of
+					a <classname>javax.jms.TopicConnectionFactory</classname>
+					factory to use for finding topics.  Defaults to <literal>
+					java:/ConnectionFactory</literal>. This setting may
+					vary depending on the application server in use; consult
+					the application server's documentation for details
+					of the default JNDI name for the 
+					<classname>javax.jms.TopicConnectionFactory</classname>
+					instance. For example, under Weblogic, the JNDI name
+					for the TopicConnectionFactory is
+					<literal>javax.jms.TopicConnectionFactory</literal>.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>ExceptionReconnectAttempts</literal>: The number of
+					times to attempt to reconnect if the JMS system notifies 
+					OpenJPA of a serious connection error.  Defaults to 0, meaning
+					OpenJPA will log the error but otherwise ignore it, hoping the
+					connection is still valid.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>*</literal>: All other configuration properties 
+					will be interpreted as settings to pass to the JNDI 
+					<classname>InitialContext</classname> on construction.  For
+					example, you might set the <literal>java.naming.provider.url
+					</literal> property to the URL of the context provider.
+					</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+			To configure a factory to use the JMS provider, your properties 
+			might look like the following:
+			</para>
+            <note>
+              <para>
+				Because of the nature of JMS, it is important that you invoke
+				<methodname>EntityManagerFactory.close</methodname>
+				when finished with a factory.  If you do not do so, a daemon 
+				thread will stay up in the JVM, preventing the JVM from exiting.
+				</para>
+            </note>
+          </section>
+          <section id="ref_guide_event_conf_tcp">
+            <title>TCP</title>
+            <indexterm zone="ref_guide_event_conf_tcp">
+              <primary>remote</primary>
+              <secondary>events</secondary>
+              <tertiary>TCP</tertiary>
+            </indexterm>
+            <para>
+			The TCP remote commit provider has several options that are
+			defined as host specifications containing a host name or IP
+			address and an optional port separated by a colon. For example,
+			the host specification <literal>saturn.bea.com:1234</literal>
+			represents an <classname>InetAddress</classname> retrieved by 
+			invoking <methodname>InetAddress.getByName ("saturn.bea.com")
+			</methodname> and a port of 1234.
+			</para>
+            <para><indexterm><primary>TCP provider</primary></indexterm>
+			The TCP provider can be configured by setting the <literal>
+			openjpa.RemoteCommitProvider</literal> plugin property to contain the 
+			appropriate configuration settings. The TCP provider understands the
+			following properties:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Port</literal>: The TCP port that the provider 
+					should listen on for commit notifications.  Defaults to 
+					5636.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>Addresses</literal>: A semicolon-separated list of 
+					IP addresses to which notifications should be sent. No 
+					default value.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>NumBroadcastThreads</literal>: The number of 
+					threads to create for the purpose of transmitting events to
+					peers.  You sould increase this value as the number of 
+					concurrent transactions increases. The maximum number of 
+					concurrent transactions is a function of the size of the 
+					connection pool.  See the the <literal>MaxActive</literal> 
+					property of
+					<literal>openjpa.ConnectionFactoryProperties</literal> in
+					<xref linkend="ref_guide_dbsetup_builtin"/>.
+					Setting a value of 0 will result in behavior where the
+					thread invoking <methodname>commit</methodname> will 
+					perform the broadcast directly.  Defaults to 2.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>RecoveryTimeMillis</literal>: Amount of time to 
+					wait in milliseconds before attempting to reconnect to a 
+					peer of the cluster when connectivity to the peer is lost. 
+					Defaults to 15000.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>MaxIdle</literal>: The number of TCP sockets 
+					(channels) to keep open to each peer in the cluster for 
+					the transmission of events.  Defaults to 2.
+					</para>
+              </listitem>
+              <listitem>
+                <para><literal>MaxActive</literal>: The maximum allowed number 
+					of TCP sockets (channels) to open simultaneously 
+					between each peer in the cluster.
+					Defaults to 2.
+					</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+			To configure a factory to use the TCP provider, your properties 
+			might look like the following:
+			</para>
+            <example id="ref_guide_event_conf_tcpex">
+              <title>TCP Remote Commit Provider Configuration</title>
+              <programlisting format="linespecific">
+&lt;property name="openjpa.RemoteCommitProvider" 
+    value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/&gt;
+</programlisting>
+            </example>
+          </section>
+          <section id="ref_guide_event_conf_common">
+            <title>Common Properties</title>
+            <indexterm zone="ref_guide_event_conf_common">
+              <primary>remote</primary>
+              <secondary>events</secondary>
+              <tertiary>common properties</tertiary>
+            </indexterm>
+            <para>
+			In addition to the provider-specific configuration options above,
+			all providers accept the following plugin properties:
+			</para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>TransmitPersistedObjectIds</literal>: Whether 
+					remote commit events will include the object ids of 
+					instances persisted in the transaction.  By default only 
+					the class names of types persisted in the transaction are 
+					sent.  This results in smaller events and more efficient 
+					network utilization.  If you have registered your own 
+					remote commit listeners, however, you may require the 
+					persisted object ids as well.
+					</para>
+              </listitem>
+            </itemizedlist>
+            <para>
+			To transmit persisted object ids in our remote commit events
+			using the JMS provider, we modify the previous example as follows:
+			</para>
+          </section>
+        </section>
+        <section id="ref_guide_event_customization">
+          <title>Customization</title>
+          <indexterm zone="ref_guide_event_customization">
+            <primary>remote</primary>
+            <secondary>events</secondary>
+            <tertiary>customization</tertiary>
+          </indexterm>
+          <para>
+		You can develop additional mechanisms for remote event notification be
+		by creating an implementation of the 
+		<ulink url="../apidocs/org/apache/openjpa/event/RemoteCommitProvider.html"><classname>
+		RemoteCommitProvider</classname></ulink> interface, possibly by 
+		extending the 
+		<ulink url="../apidocs/org/apache/openjpa/event/AbstractRemoteCommitProvider.html"><classname>AbstractRemoteCommitProvider</classname></ulink>
+		abstract class. For details on particular customization needs,
+		contact us at <ulink url="mailto:support@solarmetric.com">
+		support@solarmetric.com</ulink>.
+		</para>
+        </section>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_integration">
+      <title>Third Party Integration</title>
+      <para>
+	OpenJPA provides a number of mechanisms for integrating with third-party 
+	tools. The following chapter will illustrate these integration features.
+	</para>
+      <section id="ref_guide_integration_ant">
+        <title>Apache Ant</title>
+        <indexterm zone="ref_guide_integration_ant">
+          <primary>Ant</primary>
+        </indexterm>
+        <para>
+		Ant is a very popular tool for building Java projects. It is similar to
+		the <literal>make</literal> command, but is Java-centric and has
+		more modern features. Ant is open source, and can be downloaded
+		from Apache's Ant web page at
+		<ulink url="http://jakarta.apache.org/ant/">
+		http://jakarta.apache.org/ant/</ulink>.
+		Ant has become the de-facto standard build tool for Java, and
+		many commercial integrated development environments provide
+		some support for using ant build files. The remainder of this
+		section assumes familiarity with writing Ant
+		<filename>build.xml</filename> files.
+		</para>
+        <para>
+		OpenJPA provides pre-built Ant task definitions for all bundled tools:
+		</para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <link linkend="ref_guide_integration_enhance">Enhancer
+				Task</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link linkend="ref_guide_integration_appidtool">Application
+				Identity Tool Task</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link linkend="ref_guide_integration_mappingtool">Mapping 
+				Tool Task</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link linkend="ref_guide_integration_revmappingtool">Reverse
+				Mapping Tool Task</link>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <link linkend="ref_guide_integration_schematool">Schema Tool
+				Task</link>
+            </para>
+          </listitem>
+        </itemizedlist>
+        <para>
+		The source code for all the ant tasks is provided with the distribution
+		under the <filename>src</filename> directory. This allows you
+		to customize various aspects of the ant tasks in order to better 
+		integrate into your development environment.
+		</para>
+        <section id="ref_guide_integration_conf">
+          <title>Common Ant Configuration Options</title>
+          <indexterm>
+            <primary>Ant</primary>
+            <secondary>configuration options</secondary>
+          </indexterm>
+          <para>
+			All OpenJPA tasks accept a nested <literal>config</literal>
+			element, which defines the configuration environment in which
+			the specified task will run. The attributes for the
+			<literal>config</literal> tag are defined by the 
+			<ulink url="../apidocs/org/apache/openjpa/jdbc/conf/JDBCConfiguration.html"><classname>JDBCConfiguration</classname></ulink> bean methods. 
+			Note that excluding the <literal>config</literal> element 
+			will cause the Ant task to use the default system configuration 
+			mechanism, such as the configuration defined in the 
+			<phrase><filename>org.apache.openjpa.xml</filename></phrase>
+			
+			
+			file.
+			</para>
+          <para>
+			Following is an example of how to use the nested
+			<literal>config</literal> tag in a <filename>build.xml</filename> 
+			file:
+			</para>
+          <example id="ref_guide_integration_conf_config">
+            <title>Using the &lt;config&gt; Ant Tag</title>
+            <programlisting format="linespecific">
+&lt;mappingtool&gt;
+  &lt;fileset dir="${basedir}"&gt;
+    &lt;include name="**/model/*.java" /&gt;
+  &lt;/fileset&gt;
+  &lt;config connectionUserName="scott" connectionPassword="tiger"
+    connectionURL="jdbc:oracle:thin:@saturn:1521:solarsid"
+    connectionDriverName="oracle.jdbc.driver.OracleDriver" /&gt;
+&lt;/mappingtool&gt;
+</programlisting>
+          </example>
+          <para>
+			It is also possible to specify a <literal>properties</literal> 
+			or <literal>propertiesFile</literal> attribute on the 
+			<literal>config</literal> tag, which will be used to 
+			locate a properties resource or file. The resource will be 
+			loaded relative to the current CLASSPATH.
+			</para>
+          <example id="ref_guide_integration_props">
+            <title>Using the Properties Attribute of the &lt;config&gt; 
+				Tag</title>
+            <programlisting format="linespecific">
+&lt;mappingtool&gt;
+  &lt;fileset dir="${basedir}"&gt;
+    &lt;include name="**/model/*.java"/&gt;
+  &lt;/fileset&gt;
+  &lt;config properties="openjpa-dev.properties"/&gt;
+&lt;/mappingtool&gt;
+</programlisting>
+          </example>
+          <example id="ref_guide_integration_propsfile">
+            <title>Using the PropertiesFile Attribute of the &lt;config&gt; 
+				Tag</title>
+            <programlisting format="linespecific">
+&lt;mappingtool&gt;
+  &lt;fileset dir="${basedir}"&gt;
+    &lt;include name="**/model/*.java"/&gt;
+  &lt;/fileset&gt;
+  &lt;config propertiesFile="../conf/openjpa-dev.properties"/&gt;
+&lt;/mappingtool&gt;
+</programlisting>
+          </example>
+          <para>
+			Tasks also accept a nested <literal>classpath</literal> 
+			element, which you can use in place of the default classpath.
+			The <literal>classpath</literal> argument behaves the same 
+			as it does for Ant's standard <literal>javac</literal>
+			element. It is sometimes the case that projects are compiled
+			to a separate directory than the source tree. If the target
+			path for compiled classes is not included in the project's
+			classpath, then a <literal>classpath</literal> element
+			that includes the target class directory needs to be included so 
+			the enhancer and mapping tool can locate the relevant classes.
+			</para>
+          <para>
+			Following is an example of using a <literal>classpath</literal> tag:
+			</para>
+          <example id="ref_guide_integration_conf_classpath">
+            <title>Using the &lt;classpath&gt; Ant Tag</title>
+            <programlisting format="linespecific">
+&lt;openjpac&gt;
+  &lt;fileset dir="${basedir}/source"&gt;
+    &lt;include name="**/model/*.java" /&gt;
+  &lt;/fileset&gt;
+  &lt;classpath&gt;
+    &lt;pathelement location="${basedir}/classes"/&gt;
+    &lt;pathelement location="${basedir}/source"/&gt;
+    &lt;pathelement path="${java.class.path}"/&gt;
+  &lt;/classpath&gt;
+&lt;/openjpac&gt;
+</programlisting>
+          </example>
+          <para>
+			Finally, tasks that invoke code-generation tools like the
+			application identity tool and reverse mapping tool accept a nested
+			<literal>codeformat</literal> element.  See the code formatting
+			documentation in <xref linkend="ref_guide_conf_devtools_format"/>
+			for a list of code formatting attributes.
+			</para>
+          <example id="ref_guide_integration_conf_codeformat">
+            <title>Using the &lt;codeformat&gt; Ant Tag</title>
+            <programlisting format="linespecific">
+&lt;reversemappingtool package="com.xyz.jdo" directory="${basedir}/src"&gt;
+  &lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
+&lt;/reversemappingtool&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_integration_enhance">
+          <title>Enhancer Ant Task</title>
+          <indexterm zone="ref_guide_integration_enhance">
+            <primary>Ant</primary>
+            <secondary>enhancer task</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_integration_enhance">
+            <primary>enhancer</primary>
+            <secondary>Ant task</secondary>
+          </indexterm>
+          <para>
+			The enhancer task allows you to invoke the OpenJPA enhancer
+			directly from within the Ant build process.  The task's 
+			parameters correspond exactly to the long versions of the 
+			command-line arguments to <link linkend="ref_guide_pc_enhance"><literal>openjpac</literal></link>.
+			</para>
+          <para>	
+			The enhancer task accepts a nested <literal>fileset</literal> tag 
+			to specify the files that should be processed. You can specify 
+			<filename>.java</filename> or <filename>.class</filename> files.
+			If you do not specify any files, the task will run on the classes 
+			listed in your <link linkend="openjpa.MetaDataFactory"><literal>
+			openjpa.MetaDataFactory</literal></link> property.
+			</para>
+          <para>
+			Following is an example of using the enhancer task
+			in a <filename>build.xml</filename> file:
+			</para>
+          <example id="ref_guide_integration_enhance_task">
+            <title>Invoking the Enhancer from Ant</title>
+            <programlisting format="linespecific">
+&lt;target name="enhance"&gt;
+  &lt;!-- define the openjpac task; this can be done at the top of the    --&gt;
+  &lt;!-- build.xml file, so it will be available for all targets      --&gt;
+  &lt;taskdef name="openjpac" classname="org.apache.openjpa.ant.PCEnhancerTask"/&gt;
+
+  &lt;!-- invoke enhancer on all .jdo files below the current directory --&gt;
+  &lt;openjpac&gt;
+    &lt;fileset dir="."&gt;
+      &lt;include name="**/model/*.java" /&gt;
+    &lt;/fileset&gt;
+  &lt;/openjpac&gt;
+&lt;/target&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_integration_appidtool">
+          <title>Application Identity Tool Ant Task</title>
+          <indexterm zone="ref_guide_integration_enhance">
+            <primary>Ant</primary>
+            <secondary>application identity tool task</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_integration_enhance">
+            <primary>application identity tool</primary>
+            <secondary>Ant task</secondary>
+          </indexterm>
+          <para>
+			The application identity tool task allows you to invoke the 
+			application identity tool directly from within the Ant build 
+			process.  The task's parameters correspond exactly to the long 
+			versions of the command-line arguments to
+			<link linkend="ref_guide_pc_appid_appidtool"><literal>appidtool</literal></link>.
+			</para>
+          <para>	
+			The application identity tool task accepts a nested 
+			<literal>fileset</literal> tag to specify the files that should be 
+			processed. You can specify 
+			<filename>.java</filename> or <filename>.class</filename> files.
+			If you do not specify any files, the task will run on the classes 
+			listed in your <link linkend="openjpa.MetaDataFactory"><literal>
+			openjpa.MetaDataFactory</literal></link> property.
+			</para>
+          <para>
+			Following is an example of using the application identity tool task
+			in a <filename>build.xml</filename> file:
+			</para>
+          <example id="ref_guide_integration_appidtool_task">
+            <title>Invoking the Application Identity Tool from Ant</title>
+            <programlisting format="linespecific">
+&lt;target name="appids"&gt;
+  &lt;!-- define the appidtool task; this can be done at the top of     --&gt;
+  &lt;!-- the build.xml file, so it will be available for all targets   --&gt;
+  &lt;taskdef name="appidtool" classname="org.apache.openjpa.ant.ApplicationIdToolTask"/&gt;
+
+  &lt;!-- invoke tool on all .jdo files below the current directory     --&gt;
+  &lt;appidtool&gt;
+    &lt;fileset dir="."&gt;
+      &lt;include name="**/model/*.java" /&gt;
+    &lt;/fileset&gt;
+    &lt;codeformat spaceBeforeParen="true" braceOnSameLine="false"/&gt;
+  &lt;/appidtool&gt;
+&lt;/target&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_integration_mappingtool">
+          <title>Mapping Tool Ant Task</title>
+          <indexterm zone="ref_guide_integration_mappingtool">
+            <primary>Ant</primary>
+            <secondary>mapping tool task</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_integration_mappingtool">
+            <primary>mapping tool</primary>
+            <secondary>Ant task</secondary>
+          </indexterm>
+          <para>
+			The mapping tool task allows you to directly invoke the
+			mapping tool from within the Ant build process.  It is useful for
+			making sure that the database schema and object-relational mapping
+			data is always synchronized with your persistent class definitions,
+			without needing to remember to invoke the mapping tool manually.
+			The task's parameters correspond exactly to the long versions of
+			the command-line arguments to the 
+			<link linkend="ref_guide_mapping_mappingtool"><literal>
+			mappingtool</literal></link>.
+			</para>
+          <para>	
+			The mapping tool task accepts a nested 
+			<literal>fileset</literal> tag to specify the files that should be 
+			processed. You can specify 
+			<filename>.java</filename> or <filename>.class</filename> files.
+			If you do not specify any files, the task will run on the classes 
+			listed in your <link linkend="openjpa.MetaDataFactory"><literal>
+			openjpa.MetaDataFactory</literal></link> property.
+			</para>
+          <para>
+			Following is an example of a <filename>build.xml</filename>
+			target that invokes the mapping tool:
+			</para>
+          <example id="ref_guide_integration_mappingtool_task">
+            <title>Invoking the Mapping Tool from Ant</title>
+            <programlisting format="linespecific">
+&lt;target name="refresh"&gt;
+  &lt;!-- define the mappingtool task; this can be done at the top of --&gt;
+  &lt;!-- the build.xml file, so it will be available for all targets --&gt;
+  &lt;taskdef name="mappingtool" classname="org.apache.openjpa.jdbc.ant.MappingToolTask"/&gt;
+
+  &lt;!-- add the schema components for all .jdo files below the      --&gt;
+  &lt;!-- current directory                                           --&gt;
+  &lt;mappingtool action="buildSchema"&gt;
+    &lt;fileset dir="."&gt;
+      &lt;include name="**/*.jdo" /&gt;
+    &lt;/fileset&gt;
+  &lt;/mappingtool&gt;
+&lt;/target&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_integration_revmappingtool">
+          <title>Reverse Mapping Tool Ant Task</title>
+          <indexterm zone="ref_guide_integration_revmappingtool">
+            <primary>Ant</primary>
+            <secondary>reverse mapping tool task</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_integration_revmappingtool">
+            <primary>reverse mapping tool</primary>
+            <secondary>Ant task</secondary>
+          </indexterm>
+          <para>
+			The reverse mapping tool task allows you to directly invoke the
+			reverse mapping tool from within Ant.  While many users will only 
+			run the reverse mapping process once, others will make it part of 
+			their build process.  The task's parameters correspond exactly to 
+			the long versions of the command-line arguments to the 
+			<link linkend="ref_guide_pc_reverse_reversemappingtool"><literal>
+			reversemappingtool</literal></link>.
+			</para>
+          <para>
+			Following is an example of a <filename>build.xml</filename>
+			target that invokes the reverse mapping tool:
+			</para>
+          <example id="ref_guide_integration_revmappingtool_task">
+            <title>Invoking the Reverse Mapping Tool from Ant</title>
+            <programlisting format="linespecific">
+&lt;target name="reversemap"&gt;
+  &lt;!-- define the reversemappingtool task; this can be done at the top of --&gt;
+  &lt;!-- the build.xml file, so it will be available for all targets        --&gt;
+  &lt;taskdef name="reversemappingtool" 
+    classname="org.apache.openjpa.jdbc.ant.ReverseMappingToolTask"/&gt;
+
+  &lt;!-- reverse map the entire database --&gt;
+  &lt;reversemappingtool package="com.xyz.model" directory="${basedir}/src"
+    customizerProperties="${basedir}/conf/reverse.properties"&gt;
+    &lt;codeformat tabSpaces="4" spaceBeforeParen="true" braceOnSameLine="false"/&gt;
+  &lt;/reversemappingtool&gt;
+&lt;/target&gt;
+</programlisting>
+          </example>
+        </section>
+        <section id="ref_guide_integration_schematool">
+          <title>Schema Tool Ant Task</title>
+          <indexterm zone="ref_guide_integration_schematool">
+            <primary>Ant</primary>
+            <secondary>schema tool task</secondary>
+          </indexterm>
+          <indexterm zone="ref_guide_integration_schematool">
+            <primary>schema tool</primary>
+            <secondary>Ant task</secondary>
+          </indexterm>
+          <para>
+			The schema tool task allows you to directly invoke the
+			schema tool from within the Ant build process.
+			The task's parameters correspond exactly to the long versions
+			of the command-line arguments to the 
+			<link linkend="ref_guide_schema_schematool"><literal>
+			schematool</literal></link>.
+			</para>
+          <para>
+			Following is an example of a <filename>build.xml</filename>
+			target that invokes the schema tool:
+			</para>
+          <example id="ref_guide_integration_schematool_task">
+            <title>Invoking the Schema Tool from Ant</title>
+            <programlisting format="linespecific">
+&lt;target name="schema"&gt;
+  &lt;!-- define the schematool task; this can be done at the top of  --&gt;
+  &lt;!-- the build.xml file, so it will be available for all targets --&gt;
+  &lt;taskdef name="schematool" classname="org.apache.openjpa.jdbc.ant.SchemaToolTask"/&gt;
+
+  &lt;!-- add the schema components for all .schema files below the   --&gt;
+  &lt;!-- current directory                                           --&gt;
+  &lt;schematool action="add"&gt;
+    &lt;fileset dir="."&gt;
+      &lt;include name="**/*.schema" /&gt;
+    &lt;/fileset&gt;
+  &lt;/schematool&gt;
+&lt;/target&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="ref_guide_integration_maven">
+        <title>Maven</title>
+        <indexterm zone="ref_guide_integration_maven">
+          <primary>Maven</primary>
+        </indexterm>
+      </section>
+    </chapter>
+    <chapter id="ref_guide_optimization">
+      <title>Optimization Guidelines</title>
+      <indexterm zone="ref_guide_optimization">
+        <primary>optimization guidelines</primary>
+      </indexterm>
+      <para>
+	There are numerous techniques you can use in order to ensure that OpenJPA 
+	operates in the fastest and most efficient manner. Following are some 
+	guidelines. Each describes what impact it will have on performance and
+	scalability. Note that general guidelines regarding performance or
+	scalability issues are just that - guidelines. Depending on the
+	particular characteristics of your application, the optimal settings
+	may be considerably different than what is outlined below.
+	</para>
+      <para>
+	In the following table, each row is labeled with a list of
+	italicized keywords. These keywords identify what characteristics
+	the row in question may improve upon.  Many of the rows are marked with 
+	one or both of the <emphasis>performance</emphasis> and 
+	<emphasis>scalability</emphasis> labels. It is important to bear
+	in mind the differences between performance and scalability (for the
+	most part, we are referring to system-wide scalability, and not
+	necessarily only scalability within a single JVM). The
+	performance-related hints will probably improve the performance of
+	your application for a given user load, whereas the
+	scalability-related hints will probably increase the total number of
+	users that your application can service. Sometimes, increasing
+	performance will decrease scalability, and vice versa. Typically,
+	options that reduce the amount of work done on the database server
+	will improve scalability, whereas those that push more work onto the
+	server will have a negative impact on scalability.
+	</para>
+      <table>
+        <title>Optimization Guidelines</title>
+        <tgroup cols="2" align="left" colsep="1" rowsep="1">
+          <colspec colname="name"/>
+          <colspec colname="desc" colwidth="4*"/>
+          <tbody valign="top">
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Optimize database indexes</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					The default set of indexes created by OpenJPA's mapping 
+					tool may not always be the most appropriate for your 
+					application. Manually setting indexes in your mapping
+					metadata or manually manipulating database indexes to 
+					include frequently-queried fields (as well as dropping 
+					indexes on rarely-queried fields) can yield significant 
+					performance benefits.
+					<para>
+					A database must do extra work on insert, update, and
+					delete to maintain an index. This extra work will benefit
+					selects with WHERE clauses, which will execute much faster
+					when the terms in the WHERE clause are appropriately
+					indexed. So, for a read-mostly application, appropriate
+					indexing will slow down updates (which are rare) but greatly
+					accelerate reads. This means that the system as a whole will
+					be faster, and also that the database will experience less
+					load, meaning that the system will be more scalable.
+					</para>
+					<para>
+					Bear in mind that over-indexing is a bad thing, both
+					for scalability and performance, especially for applications
+					that perform lots of inserts, updates, or deletes.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use the best JDBC driver</emphasis>
+                <para>
+                  <emphasis>performance, scalability, reliability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					The JDBC driver provided by the database vendor is not 
+					always the fastest and most efficient. Some JDBC drivers 
+					do not support features like batched statements, the lack 
+					of which can significantly slow down OpenJPA's data access
+					and increase load on the database, reducing system 
+					performance and scalability.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">JVM optimizations</emphasis>
+                <para>
+                  <emphasis>performance, reliability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					Manipulating various parameters of the Java Virtual Machine
+					(such as hotspot compilation modes and the maximum memory)
+					can result in performance improvements. For more details
+					about optimizing the JVM execution environment, please see 
+					<ulink url="http://java.sun.com/docs/hotspot/PerformanceFAQ.html"/>.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use the data cache</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					Using OpenJPA's <link linkend="ref_guide_cache">data and 
+					query caching</link> features can often result 
+					in a dramatic improvement in performance. Additionally, 
+					these caches can significantly reduce the amount of load on
+					the database, increasing the scalability characteristics of
+					your application.  Also, be sure to read about the 
+					<link linkend="ref_guide_cache_concurrent">concurrent cache
+					</link> option to see if it fits your needs.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Set <literal>LargeTransaction
+					</literal> to true, or set <literal>PopulateDataCache
+					</literal> to false</emphasis>
+                <para>
+                  <emphasis>performance vs. scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					When using OpenJPA's <link linkend="ref_guide_cache">data 
+					caching</link> features (available in OpenJPA JDO 
+					Performance Pack and Enterprise Edition) 
+					in a transaction that will delete, modify, or create 
+					a very large number of objects you can set <literal>
+					LargeTransaction</literal> to true and perform periodic 
+					flushes during your transaction to reduce its memory 
+					requirements.  See the Javadoc:
+					<phrase><ulink url="javadoc/openjpa/persistence/OpenJPAEntityManager.html">
+					OpenJPAEntityManager.setLargeTransaction</ulink></phrase>
+					
+					
+					Note that transactions in large mode have to
+					more aggressively flush items from the data cache.
+					<para>
+					If your transaction will visit objects that you know
+					are very unlikely to be accessed by other transactions,
+					for example an exhaustive report run only once a month,
+					you can turn off population of the data cache so that
+					the transaction doesn't fill the entire data cache with
+					objects that won't be accessed again.
+					Again, see the Javadoc: 
+					<phrase><ulink url="javadoc/openjpa/persistence/OpenJPAEntityManager.html">
+					OpenJPAEntityManager.setPopulateDataCache</ulink></phrase>
+					
+					
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Disable logging, performance 
+					tracking</emphasis>
+                <para>
+                  <emphasis>performance</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					Developer options such as verbose logging and the 
+					JDBC performance tracker can result in serious performance 
+					hits for your application. Before evaluating OpenJPA's
+					performance, these options should all be disabled.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Set <literal>IgnoreChanges</literal> 
+					to true, or set <literal>FlushBeforeQueries</literal> to 
+					true</emphasis>
+                <para>
+                  <emphasis>performance vs. scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					When both the <link linkend="openjpa.IgnoreChanges"><literal>openjpa.IgnoreChanges</literal></link> and 
+					<link linkend="openjpa.FlushBeforeQueries"><literal>
+					openjpa.FlushBeforeQueries</literal></link> properties are set
+					to false, OpenJPA needs to consider in-memory dirty instances 
+					during queries.  This can sometimes result in OpenJPA needing 
+					to evaluate the entire extent objects in order to 
+					return the correct query results, which can have drastic 
+					performance consequences.  If it is appropriate for your 
+					application, configuring 
+					<literal>FlushBeforeQueries</literal>
+					to automatically flush before queries involving dirty
+					objects will ensure that this never
+					happens. Setting <literal>IgnoreChanges</literal> to 
+					false will result in a small performance hit even if 
+					<literal>FlushBeforeQueries</literal> is true, as 
+					incremental flushing is not as efficient overall as 
+					delaying all flushing to a single operation during commit. 
+					This is because incrementally flushing decreases OpenJPA's 
+					ability to maximize statement batching, and increases 
+					resource utilization.
+					<para>
+					Note that the default setting of 
+					<literal>FlushBeforeQueries</literal> is 
+					<literal>with-connection</literal>, which means that data 
+					will be flushed only if a dedicated connection is already 
+					in use by the <classname>EntityManager</classname>. 
+					So, the default value may not be appropriate for you.
+					</para>
+					
+					
+					<para>
+					Setting <literal>IgnoreChanges</literal> to 
+					<literal>true</literal> will help performance, since dirty
+					objects can be ignored for queries, meaning that 
+					incremental flushing or client-side processing
+					is not necessary. It will also improve scalability, since 
+					overall database server usage is diminished.  On the other 
+					hand, setting <literal>IgnoreChanges</literal> to 
+					<literal>false</literal> will have a negative impact on
+					scalability, even when using automatic flushing before
+					queries, since more operations will be performed on the
+					database server.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Configure <literal>
+					openjpa.ConnectionRetainMode</literal> appropriately</emphasis>
+                <para>
+                  <emphasis>performance vs. scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					The <link linkend="openjpa.ConnectionRetainMode"><literal>
+					ConnectionRetainMode</literal></link> configuration option 
+					controls when OpenJPA will obtain a connection, and how long 
+					it will hold that connection. The optimal settings for this
+					option will vary considerably depending on the particular 
+					behavior of your application. You may even benefit from 
+					using different retain modes for different parts of your
+					application.
+					<para>
+					The default setting of <literal>on-demand</literal> 
+					minimizes the amount of time that OpenJPA holds onto a 
+					datastore connection. This is generally the best option 
+					from a scalability standpoind, as database resources are 
+					held for a minimal amount of time. However, if your 
+					connection pool is overly small relative to the number of 
+					concurrent sessions that need access to the 
+					database, or if your <classname>DataSource</classname> is 
+					not efficient at managing its pool, then this default value 
+					could cause undesirable pool contention.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Ensure that batch updates are 
+					available</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					When performing bulk inserts, updates, or deletes, OpenJPA 
+					will use batched statements. If this feature is not 
+					available in your JDBC driver, then OpenJPA will need to 
+					issue multiple SQL statements instead of a single batch 
+					statement.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use 
+					flat inheritance</emphasis>
+                <para>
+                  <emphasis>performance, scalability vs. disk space</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					Mapping inheritance hierarchies to a single database table
+					is faster for most operations than other strategies
+					employing multiple tables. If it is appropriate for your 
+					application, you should use this strategy whenever possible.
+					<para>
+					However, this strategy will require more disk 
+					space on the database side. Disk space is relatively 
+					inexpensive, but if your object model is particularly 
+					large, it can become a factor.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">High sequence increment</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					For applications that perform large bulk inserts, the 
+					retrieval of sequence numbers can be a bottleneck. 
+					Increasing sequence increments and using table-based rather
+					than native database sequences can reduce or eliminate 
+					this bottleneck. In some cases,
+					implementing your own sequence factory can further optimize
+					sequence number retrieval.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use optimistic transactions</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					Using datastore transactions translates into pessimistic 
+					database row locking, which can be a performance hit 
+					(depending on the database). If appropriate for your 
+					application, optimistic transactions are typically faster 
+					than datastore transactions.
+					<para>
+					Optimistic transactions provide the same transactional
+					guarantees as datastore transactions, except that you must
+					handle a potential optimistic verification exception at the
+					end of a transaction instead of assuming that a transaction
+					will successfully complete. In many applications, it is
+					unlikely that different concurrent transactions will operate
+					on the same set of data at the same time, so optimistic
+					verification increases the concurrency, and therefore both
+					the performance and scalability characteristics, of the
+					application. A common approach to handling optimistic
+					verification exceptions is to simply present the end user
+					with the fact that concurrent modifications happened, and
+					require that the user redo any work.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use query aggregates and projections
+					</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					Using aggregates to compute reporting data on the database
+					server can drastically speed up queries.  Similarly, using
+					projections when you are interested in specific
+					object fields or relations rather than the entire object
+					state can reduce the amount of data OpenJPA must transfer
+					from the database to your application.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Always close resources</emphasis>
+                <para>
+                  <emphasis>scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+                <para>	
+					Under certain settings, <classname>
+					EntityManager</classname>s, OpenJPA <classname>Extent
+					</classname> iterators, and <classname>Query</classname> 
+					results may be backed by resources in the database.  
+					</para>
+                <para>
+					For example, if you have
+					configured OpenJPA to use scrollable cursors and lazy object
+					instantiation by default, each query result will hold open 
+					a <classname>ResultSet</classname> object, which, in turn, 
+					will hold open a <classname>Statement</classname> object 
+					(preventing it from being re-used).  Garbage collection 
+					will clean up these resources, so it is never necessary to 
+					explicitly close them, but it is always faster if it is 
+					done at the application level.
+					</para>
+              </entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Optimize connection pool 
+					settings</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+                <para>
+				    OpenJPA's built-in connection pool's default settings may
+					not be optimal for all applications. For applications that
+					instantiate and close many <classname>
+					EntityManager</classname>s (such as a
+					web application), increasing the size of the connection
+					pool will reduce the overhead of waiting on free connections
+					or opening new connections.  
+					</para>
+                <para>
+					You may want to tune the 
+					prepared statement pool size with the connection pool size.
+					</para>
+              </entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use detached state managers</emphasis>
+                <para>
+                  <emphasis>performance</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+                <para>
+					Attaching and even persisting instances can be more 
+					efficient when your detached objects use detached state 
+					managers.  By default, OpenJPA does not use detached state 
+					managers when serializing an instance across tiers.  See 
+					<xref linkend="ref_guide_detach_graph"/> for how to force
+					OpenJPA to use detached state managers across tiers, and for
+					other options for more efficient attachment.
+					</para>
+                <para>
+					The downside of using a detached state manager
+					across tiers is that your enhanced persistent classes and
+					the OpenJPA libraries must be available on the client tier.
+					</para>
+              </entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Utilize the <classname>
+					EntityManager</classname> cache</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"> 
+					When possible and appropriate, re-using <classname>
+					EntityManager</classname>s and setting the 
+					<link linkend="openjpa.RetainState"><literal>
+					RetainState</literal></link> configuration option to 
+					<literal>true</literal> may result in significant 
+					performance gains, since the <classname>
+					EntityManager</classname>'s built-in
+					object cache will be used.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Enable multithreaded operation only 
+					when necessary</emphasis>
+                <para>
+                  <emphasis>performance</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					OpenJPA respects the <link linkend="openjpa.Multithreaded"><literal>openjpa.Multithreaded</literal></link> option in
+					that it does not impose synchronization overhead for
+					applications that set this value to 
+					<literal>false</literal>. If your application is 
+					guaranteed to only use single-threaded access to OpenJPA
+					resources and persistent objects, setting this option to 
+					<literal>false</literal> will result
+					in the elimination of synchronization overhead, and may 
+					result in a modest performance increase.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Enable large data set 
+					handling</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					If you execute queries that return large numbers of objects
+					or have relations (collections or maps) that are large, and
+					if you often only access parts of these data sets, enabling
+					<link linkend="ref_guide_dbsetup_lrs">large result set 
+					handling</link> where appropriate can
+					dramatically speed up your application, since OpenJPA will
+					bring the data sets into memory from the database only as
+					necessary.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Disable large data set handling
+					</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					If you have enabled scrollable result sets and on-demand 
+					loading but do you not require it, consider disabling it 
+					again.  Some JDBC drivers and databases (SQLServer for 
+					example) are much slower when used with scrolling result 
+					sets.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use short discriminator values, or
+					turn off the discriminator
+					</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					The default discriminator strategy of storing the class
+					name in the discriminator column is quite robust, in that 
+					it can handle any class and needs no configuration, but 
+					the downside of this robustness is that it puts a 
+					relatively lengthy string into each row of the database. 
+					With a little application-specific configuration, you can 
+					easily reduce this to a single character or integer. This 
+					can result in significant performance gains when dealing 
+					with many small objects, 
+					since the subclass indicator data can become a significant 
+					proportion of the data transferred between the JVM and 
+					the database.
+					<para>
+					Alternately, if certain persistent classes in your 
+					application do not make use of inheritance, then you can 
+					disable the discriminator for these classes altogether.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use the <classname>
+					DynamicSchemaFactory</classname></emphasis>
+                <para>
+                  <emphasis>performance, validation</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					If you are using a <link linkend="openjpa.jdbc.SchemaFactory"><literal>openjpa.jdbc.SchemaFactory</literal></link> setting
+					of something other than the default of <literal>
+					dynamic</literal>, consider switching back.  While other
+					factories can ensure that object-relational mapping 
+					information is valid when a persistent class is first used,
+					this can be a slow process.  Though the validation is only 
+					performed once for each class, switching back to the
+					<classname>DynamicSchemaFactory</classname> 
+					can reduce the warm-up time for your application.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Do not use XA transactions</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc"><link linkend="ref_guide_enterprise_xa">XA transactions
+					</link> can be orders of magnitude slower than standard 
+					transactions. Unless distributed transaction functionality 
+					is required by your application, use standard transactions.
+					<para>
+					Recall that XA transactions are distinct from
+					managed transactions - managed transaction services
+					such as that provided by EJB declarative transactions
+					can be used both with XA and non-XA transactions. XA
+					transactions should only be used when a given business
+					transaction involves multiple different transactional
+					resources (an Oracle database and an IBM transactional
+					message queue, for example).
+					</para></entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use <classname>Set</classname>s 
+					instead of <classname>List/Collection</classname>s
+					</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					There is a small amount of extra overhead for OpenJPA to 
+					maintain collections where each element is not guaranteed 
+					to be unique.  If your application does not require 
+					duplicates for a collection, you should always declare your
+					fields to be of type <classname>Set, SortedSet, 
+					HashSet,</classname> or <classname>TreeSet</classname>.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use query parameters instead of
+					encoding search data in filter strings</emphasis>
+                <para>
+                  <emphasis>performance</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					If your queries depend on parameter data only known at
+					runtime, you should use query parameters rather than
+					dynamically building different query strings. OpenJPA
+					performs aggressive caching of query compilation
+					data, and the effectiveness of this cache is diminished if
+					multiple query filters are used where a single one could
+					have sufficed.
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Tune your fetch groups
+					appropriately</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					The <link linkend="ref_guide_fetch">fetch groups</link>
+					used when loading an object control how much data is
+					eagerly loaded, and by extension, which fields must be
+					lazily loaded at a future time. The ideal fetch group
+					configuration loads all the data that is needed in one
+					fetch, and no extra fields - this minimizes both the
+					amount of data transferred from the database, and the
+					number of trips to the database.
+					<para>
+					If extra fields are specified in the fetch groups
+					(in particular, large fields such as binary data, or
+					relations to other persistence-capable objects), then
+					network overhead (for the extra data) and database
+					processing (for any necessary additional joins) will
+					hurt your application's performance. If too few fields
+					are specified in the fetch groups, then OpenJPA will have
+					to make additional trips to the database to load
+					additional fields as necessary.
+					</para>
+					</entry>
+            </row>
+            <row>
+              <entry colname="name">
+                <emphasis role="bold">Use eager fetching</emphasis>
+                <para>
+                  <emphasis>performance, scalability</emphasis>
+                </para>
+              </entry>
+              <entry colname="desc">
+					Using <link linkend="ref_guide_perfpack_eager">eager 
+					fetching</link> when loading subclass data or traversing 
+					relations for each instance in a large collection of 
+					results can speed up data loading by orders of magnitude.
+					</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </chapter>
+  </part>
+  <part id="samples_guide_part">
+    <title>OpenJPA <phrase>JPA</phrase> Samples</title>
+    <chapter id="samples_guide">
+      <title>OpenJPA Sample Code</title>
+      <para>
+	The OpenJPA distribution comes with a number of examples that
+	illustrate the usage of various features.
+	</para>
+<!--
+	This is information on the sample application. It will be included
+	in the documentation (see doc/openjpa/samples-guide.xml). It will also
+	automatically be converted into a README.txt file in this directory
+	in the "release.org.apache.openjpa.releasedocs" build target phase of the release.
+-->
+      <section id="samples_guide_interop">
+        <title>JDO - JPA Persistence Interoperability</title>
+        <para>This sample demonstrates how to combine JDO and JPA in a single
+application. The <filename>MachineMain.java</filename> program uses both
+<classname>EntityManager</classname>s and <classname>PersistenceManager</classname>s 
+in a single transaction including persist, delete and query operations.</para>
+        <para>The sample includes both annotated persistent classes as well as JDOR 
+metadata information.  The application can switch to either system simply
+by changing the bootstrap mechanism.  Depending on which configuration
+system you use, OpenJPA will read the corresponding metadata format.  You can
+override some or all of this behavior using OpenJPA's configuration options, 
+such as <link linkend="openjpa.MetaDataFactory">openjpa.MetaDataFactory</link>.</para>
+        <para>To use this sample, you should ensure that either a <filename>jdo.properties</filename>
+or <filename>persistence.xml</filename> are in the <filename>META-INF</filename> directory 
+in your <envar>CLASSPATH</envar>. The rest of the files for this sample are located in the 
+<filename>samples/mixed</filename> directory of the OpenJPA installation.  This tutorial requires JDK 5.  
+To run this tutorial:</para>
+        <itemizedlist>
+          <listitem>
+            <para>Ensure that your environment is set properly as described in the
+	README and that your current path is in the mixed sample directory.</para>
+          </listitem>
+          <listitem>
+            <para>
+	You may want to edit <literal>ConnectionURL</literal> to point to an absolute 
+    URL (e.g. <filename>C:/openjpa/mixed-sample-db</filename>) if using a file-based database like 
+	<literal>HSQL</literal>.</para>
+          </listitem>
+          <listitem>
+            <para>Include the list of persistent classes in your configuration file.  For
+	JPA, you will want to add the following lines to 
+	<filename>persistence.xml</filename> before the <literal>&lt;property&gt;</literal> lines:
+	</para>
+            <programlisting format="linespecific">
+&lt;class&gt;samples.mixed.Machine&lt;/class&gt;
+&lt;class&gt;samples.mixed.Crane&lt;/class&gt;
+&lt;class&gt;samples.mixed.Bulldozer&lt;/class&gt;
+&lt;class&gt;samples.mixed.Operator&lt;/class&gt;
+</programlisting>
+            <para>
+	If you are using JDO, point the metadata factory at the <filename>.jdo</filename>
+resource containing your persistent classes:
+	</para>
+            <programlisting format="linespecific">
+openjpa.MetaDataFactory: Resources=samples/mixed/package.jdo
+</programlisting>
+          </listitem>
+          <listitem>
+            <para>Compile the classes:
+	
+	</para>
+            <para>
+              <userinput>javac *.java</userinput>
+            </para>
+          </listitem>
+          <listitem>
+            <para>You should then proceed to pass in the configuration file you are using
+	to the enhancer:
+
+	</para>
+            <para>
+              <userinput>openjpac -p persistence.xml Machine.java Crane.java Bulldozer.java Operator.java</userinput>
+            </para>
+            <para>
+		or
+	</para>
+            <para>
+              <userinput>jdoc -p jdo.properties Machine.java Crane.java Bulldozer.java Operator.java</userinput>
+            </para>
+          </listitem>
+          <listitem>
+            <para>Similarly, you should pass in the same argument to <literal>mappingtool</literal>:
+
+	</para>
+            <para>
+              <userinput>mappingtool -p persistence.xml -a buildSchema Machine.java Crane.java Bulldozer.java Operator.java</userinput>
+            </para>
+            <para>
+		or
+	</para>
+            <para>
+              <userinput>mappingtool -p jdo.properties -a buildSchema Machine.java Crane.java Bulldozer.java Operator.java</userinput>
+            </para>
+          </listitem>
+          <listitem>
+            <para>You can now run the sample application.  The first argument is
+	which operation you want the program to run.  The second argument tells 
+	the application which bootstrap system to use:
+
+	</para>
+            <para>
+              <userinput>java samples.mixed.MachineMain &lt;create | delete&gt; &lt;jdo | jpa&gt;</userinput>
+            </para>
+          </listitem>
+        </itemizedlist>
+      </section>
+      <section id="samples_guide_ejbdiv">
+        <title>JPA</title>
+<!--
+	This is information on the sample application. It will be included
+	in the documentation (see doc/openjpa/samples-guide.xml). It will also
+	automatically be converted into a README.txt file in this directory
+	in the "release.jdo.releasedocs" build target phase of the release.
+-->
+        <section id="samples_guide_model_humres_ejb">
+          <title>Sample Human Resources Model</title>
+          <para>The files for this sample are located in the <filename>samples/persistence/models/humres</filename> 
+directory of the OpenJPA installation.  This sample demonstrates the mapping of 
+an example "Human Resources" schema. The following concepts are illustrated
+in this sample:</para>
+          <itemizedlist>
+            <listitem>
+              <para>Value Mappings</para>
+            </listitem>
+            <listitem>
+              <para>One to One Mappings</para>
+            </listitem>
+            <listitem>
+              <para>One to Many Mappings (with and without inverses)</para>
+            </listitem>
+          </itemizedlist>
+        </section>
+      </section>
+    </chapter>
+  </part>
+<!-- ### JDO2MIG
+	<part id="gui_guide">
+		<title>OpenJPA Development Workbench Guide</title>
+		&gui-guide.xml;
+	</part>
+-->
+  <appendix id="jpa_resources">
+    <title>JPA Resources</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <ulink url="http://java.sun.com/aboutJava/communityprocess/jsr/jsr_220_dataobj.html">
+			EJB 3 JSR page</ulink>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <ulink url="http://java.sun.com/products/ejb">Sun EJB page</ulink>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <ulink url="http://java.sun.com/javaee/5/docs/api/index.html">Locally mirrored 
+			javax.persistence Javadoc</ulink>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <ulink url="../../api/index.html">OpenJPA API Javadoc</ulink>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <ulink url="../apidocs/index.html">Full OpenJPA Javadoc</ulink>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <ulink url="Persistence.pdf">Locally mirrored JPA
+			specification</ulink>
+        </para>
+      </listitem>
+    </itemizedlist>
+  </appendix>
+  <appendix id="supported_databases">
+    <title>Supported Databases</title>
+    <para>
+	Following is a table of the database and JDBC driver
+	versions that are supported by OpenJPA <phrase>JPA</phrase>.
+	<table tocentry="1"><title>Supported Databases and JDBC Drivers</title><tgroup rowsep="1" colsep="1" align="left" cols="4"><colspec colname="dbname"/><colspec colname="dbversion"/><colspec colname="drivname"/><colspec colname="drivversion"/><thead><row><entry colname="dbname">Database Name</entry><entry colname="dbversion">Database Version</entry><entry colname="drivname">JDBC Driver Name</entry><entry colname="drivversion">JDBC Driver Version</entry></row></thead><tbody><row><entry colname="dbname">Apache Derby</entry><entry colname="dbversion">10.1.2.1</entry><entry colname="drivname">Apache Derby Embedded JDBC Driver</entry><entry colname="drivversion">10.1.2.1</entry></row><row><entry colname="dbname">Borland Interbase</entry><entry colname="dbversion">7.1.0.202</entry><entry colname="drivname">Interclient</entry><entry colname="drivversion">4.5.1</entry></row><row><entry colname="dbname">Borland JDataStore</entry><entry colname="dbversion">6.0</entry><entry colname="drivname">
+						Borland JDataStore
+					</entry><entry colname="drivversion">6.0</entry></row><row><entry colname="dbname">DB2</entry><entry colname="dbversion">8.1</entry><entry colname="drivname">
+						IBM DB2 JDBC Universal Driver
+					</entry><entry colname="drivversion">1.0.581</entry></row><row><entry colname="dbname">Empress</entry><entry colname="dbversion">8.62</entry><entry colname="drivname">
+						Empress Category 2 JDBC Driver
+					</entry><entry colname="drivversion">8.62</entry></row><row><entry colname="dbname">Firebird</entry><entry colname="dbversion">1.5</entry><entry colname="drivname">JayBird JCA/JDBC driver</entry><entry colname="drivversion">1.0.1</entry></row><row><entry colname="dbname">Hypersonic Database Engine</entry><entry colname="dbversion">1.8.0</entry><entry colname="drivname">Hypersonic</entry><entry colname="drivversion">1.8.0</entry></row><row><entry colname="dbname">Informix Dynamic Server</entry><entry colname="dbversion">9.30.UC10</entry><entry colname="drivname">Informix JDBC driver</entry><entry colname="drivversion">2.21.JC2</entry></row><row><entry colname="dbname">InterSystems Cache</entry><entry colname="dbversion">5.0</entry><entry colname="drivname">Cache JDBC Driver</entry><entry colname="drivversion">5.0</entry></row><row><entry colname="dbname">Microsoft Access</entry><entry colname="dbversion">9.0 (a.k.a. "2000")</entry><entry colname="drivname">
+						DataDirect SequeLink
+					</entry><entry colname="drivversion">5.4.0038</entry></row><row><entry colname="dbname">Microsoft SQL Server</entry><entry colname="dbversion">
+						9.00.1399 (SQL Server 2005)
+					</entry><entry colname="drivname">SQLServer</entry><entry colname="drivversion">1.0.809.102</entry></row><row><entry colname="dbname">Microsoft Visual FoxPro</entry><entry colname="dbversion">7.0</entry><entry colname="drivname">
+						DataDirect SequeLink
+					</entry><entry colname="drivversion">5.4.0038</entry></row><row><entry colname="dbname">MySQL</entry><entry colname="dbversion">3.23.43-log</entry><entry colname="drivname">MySQL Driver</entry><entry colname="drivversion">3.0.14</entry></row><row><entry colname="dbname">Oracle</entry><entry colname="dbversion">8.1,9.2,10.1</entry><entry colname="drivname">Oracle JDBC driver</entry><entry colname="drivversion">10.2.0.1.0</entry></row><row><entry colname="dbname">Pointbase</entry><entry colname="dbversion">4.4</entry><entry colname="drivname">Pointbase JDBC driver</entry><entry colname="drivversion">4.4 (4.4) </entry></row><row><entry colname="dbname">PostgreSQL</entry><entry colname="dbversion">7.2.1</entry><entry colname="drivname">PostgreSQL Native Driver</entry><entry colname="drivversion">7.2 (7.2)</entry></row><row><entry colname="dbname">
+						Sybase Adaptive Server Enterprise
+					</entry><entry colname="dbversion">12.5</entry><entry colname="drivname">jConnect</entry><entry colname="drivversion">5.5 (5.5)</entry></row></tbody></tgroup></table>
+    </para>
+    <section id="dbsupport_derby">
+      <title>Apache Derby</title>
+      <example id="example_props_derby">
+        <title>Example properties for Derby</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: org.apache.derby.jdbc.EmbeddedDriver
+openjpa.ConnectionURL: jdbc:derby:DB_NAME;create=true
+</programlisting>
+      </example>
+    </section>
+    <section id="dbsupport_interbase">
+      <title>Borland Interbase</title>
+      <example id="example_props_interbase">
+        <title>Example properties for Interbase</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: interbase.interclient.Driver
+openjpa.ConnectionURL: jdbc:interbase://SERVER_NAME:SERVER_PORT/DB_PATH
+</programlisting>
+      </example>
+      <section id="dbsupport_interbase_issues">
+        <title>Known issues with Interbase</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						Interbase does not support record locking, so datastore
+						transactions cannot use the pessimistic lock manager.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Interbase does not support the
+						<literal>LOWER</literal>, <literal>SUBSTRING</literal>,
+						or <literal>INSTR</literal> SQL functions,
+						which means that
+						<methodname>toLowerCase()</methodname>,
+						<methodname>indexOf()</methodname>,
+						and <methodname>substring()</methodname>
+						methods in <phrase>JPA</phrase>QL cannot be used.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_jdatastore">
+      <title>JDataStore</title>
+      <example id="example_props_jdatastore">
+        <title>Example properties for JDataStore</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.borland.datastore.jdbc.DataStoreDriver
+openjpa.ConnectionURL: jdbc:borland:dslocal:db-jdatastore.jds;create=true
+</programlisting>
+      </example>
+    </section>
+    <section id="dbsupport_db2">
+      <title>IBM DB2</title>
+      <example id="example_props_db2">
+        <title>Example properties for IBM DB2</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.ibm.db2.jcc.DB2Driver
+openjpa.ConnectionURL: jdbc:db2://SERVER_NAME:SERVER_PORT/DB_NAME
+</programlisting>
+      </example>
+      <section id="dbsupport_db2_issues">
+        <title>Known issues with DB2</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>Floats and doubles may lose precision when stored.</para>
+            </listitem>
+            <listitem>
+              <para>Empty char values are stored as NULL.</para>
+            </listitem>
+            <listitem>
+              <para>
+			Fields of type BLOB and CLOB are limited to 1M. This number can be 
+			increased by extending <classname>DB2Dictionary</classname>.
+			</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_empress">
+      <title>Empress</title>
+      <example id="example_props_empress">
+        <title>Example properties for Empress</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: empress.jdbc.empressDriver
+openjpa.ConnectionURL: jdbc:empress://SERVER=yourserver;PORT=6322;DATABASE=yourdb
+</programlisting>
+      </example>
+      <section id="dbsupport_empress_issues">
+        <title>Known issues with Empress</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						Empress enforces pessimistic semantics (lock 
+						on read) when not using 
+						<literal>AllowConcurrentRead</literal> property
+						(which bypasses row locking) for 
+						<classname>EmpressDictionary</classname>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Only the category 2 non-local driver is supported.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_hypersonic">
+      <title>Hypersonic</title>
+      <example id="example_props_hypersonic">
+        <title>Example properties for Hypersonic</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: org.hsqldb.jdbcDriver
+openjpa.ConnectionURL: jdbc:hsqldb:DB_NAME
+</programlisting>
+      </example>
+      <section id="dbsupport_hypersonic_issues">
+        <title>Known issues with Hypersonic</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						Hypersonic does not properly support foreign key
+						constraints.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Hypersonic does not support pessimistic locking,
+						so non-optimistic transactions will fail unless
+						the <literal>SimulateLocking</literal> property
+						is set for the <link linkend="openjpa.jdbc.DBDictionary">
+						openjpa.jdbc.DBDictionary</link>
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_firebird">
+      <title>Firebird</title>
+      <example id="example_props_firebird">
+        <title>Example properties for Firebird</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: org.firebirdsql.jdbc.FBDriver
+openjpa.ConnectionURL: jdbc:firebirdsql://SERVER_NAME:SERVER_PORT/DB_PATH
+</programlisting>
+      </example>
+      <section id="dbsupport_firebird_issues">
+        <title>Known issues with Firebird</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					The Firebird JDBC driver does not have proper support
+					for batch updates, so batch updates are disabled.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+					Firebird does not support auto-increment columns.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Firebird does not support the
+						<literal>LOWER</literal>, <literal>SUBSTRING</literal>,
+						or <literal>INSTR</literal> SQL functions,
+						which means that
+						<methodname>toLowerCase()</methodname>,
+						<methodname>indexOf()</methodname>,
+						and <methodname>substring()</methodname>
+						methods in <phrase>JPA</phrase>QL cannot be used.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_informix">
+      <title>Informix</title>
+      <example id="example_props_informix">
+        <title>Example properties for Informix Dynamic Server</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.informix.jdbc.IfxDriver
+openjpa.ConnectionURL: \
+  jdbc:informix-sqli://SERVER_NAME:SERVER_PORT/DB_NAME:INFORMIXSERVER=SERVER_ID
+</programlisting>
+      </example>
+      <section id="dbsupport_informix_issues">
+        <title>Known issues with Informix</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					none
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_intersystems_cache">
+      <title>InterSystems Cache</title>
+      <example id="example_props_intersystems_cache">
+        <title>Example properties for InterSystems Cache</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.intersys.jdbc.CacheDriver
+openjpa.ConnectionURL: jdbc:Cache://SERVER_NAME:SERVER_PORT/DB_NAME
+</programlisting>
+      </example>
+      <section id="dbsupport_intersystems_cache_issues">
+        <title>Known issues with InterSystems Cache</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+					Support for Cache is done via SQL access over JDBC, not
+					through their object database APIs.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_access">
+      <title>Microsoft Access</title>
+      <example id="example_props_access">
+        <title>Example properties for Microsoft Access</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.ddtek.jdbc.sequelink.SequeLinkDriver
+openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT
+</programlisting>
+      </example>
+      <section id="dbsupport_access_issues">
+        <title>Known issues with Microsoft Access</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>Using the Sun JDBC-ODBC bridge to connect
+			is not supported.</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_sqlserver">
+      <title>Microsoft SQL Server</title>
+      <example id="example_props_sqlserver">
+        <title>Example properties for Microsoft SQLServer</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.microsoft.sqlserver.jdbc.SQLServerDriver
+openjpa.ConnectionURL: \
+    jdbc:sqlserver://SERVER_NAME:1433;DatabaseName=DB_NAME;selectMethod=cursor;sendStringParametersAsUnicode=false
+</programlisting>
+      </example>
+      <section id="dbsupport_sqlserver_issues">
+        <title>Known issues with SQL Server</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						SQL Server date fields are accurate only to the
+						nearest 3 milliseconds, possibly resulting in
+						precision loss in stored dates.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						The ConnectionURL must always contain the
+						"<literal>selectMethod=cursor</literal>" string.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Adding <literal>sendStringParametersAsUnicode=false
+						</literal> to the ConnectionURL may significantly 
+						increase performance.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						The Microsoft SQL Server driver only emulates
+						batch updates. The DataDirect JDBC driver has
+						true support for batch updates, and may result
+						in a significant performance gain.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Floats and doubles may lose precision when stored.
+					</para>
+            </listitem>
+            <listitem>
+              <para><literal>TEXT</literal> columns cannot be used
+						in queries.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_foxpro">
+      <title>Microsoft FoxPro</title>
+      <example id="example_props_foxpro">
+        <title>Example properties for Microsoft FoxPro</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.ddtek.jdbc.sequelink.SequeLinkDriver
+openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT
+</programlisting>
+      </example>
+      <section id="dbsupport_foxpro_issues">
+        <title>Known issues with Microsoft FoxPro</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>Using the Sun JDBC-ODBC bridge to connect
+			is not supported.</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_mysql">
+      <title>MySQL</title>
+      <example id="example_props_mysql">
+        <title>Example properties for MySQL</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.mysql.jdbc.Driver
+openjpa.ConnectionURL: jdbc:mysql://SERVER_NAME/DB_NAME
+</programlisting>
+      </example>
+      <section id="dbsupport_mysql_issues">
+        <title>Known issues with MySQL</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						The default table types that MySQL uses do not
+						support transactions, which will prevent OpenJPA from
+						being able to roll back transactions. Use the 
+						<literal>InnoDB</literal> table type
+						for any tables that OpenJPA will access.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						MySQL does not support sub-selects in versions
+						prior to 4.1, and are disabled by default. Some
+						operations (such as the <function>isEmpty()</function>
+						method in a query) will fail due to this. If
+						you are using MySQL 4.1 or later, you can lift
+						this restriction by setting the
+						<literal>SupportsSubselect=true</literal> parameter
+						of the <link linkend="openjpa.jdbc.DBDictionary">openjpa.jdbc.DBDictionary</link> property.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Rollback due to database error or optimistic lock
+						violation is not supported unless the table type
+						is one of the MySQL transactional types. Explicit
+						calls to <function>rollback()</function> before a 
+						transaction has been committed, however, are
+						always supported.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Floats and doubles may lose precision when stored
+						in some datastores.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						When storing a field of type
+						<classname>java.math.BigDecimal</classname>, some
+						datastores will add extraneous trailing 0 
+						characters, causing an equality mismatch between
+						the field that is stored and the field that is
+						retrieved.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Some version of the MySQL JDBC driver have a bug
+						that prevents OpenJPA from being able to interrogate
+						the database for foreign keys. Version
+						3.0.14 (or higher) of the MySQL driver is required
+						in order to get around this bug.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_oracle">
+      <title>Oracle</title>
+      <example id="example_props_oracle">
+        <title>Example properties for Oracle</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: oracle.jdbc.driver.OracleDriver
+openjpa.ConnectionURL: jdbc:oracle:thin:@SERVER_NAME:1521:DB_NAME
+</programlisting>
+      </example>
+      <section id="dbsupport_oracle_query_hints">
+        <title>Using Query Hints with Oracle</title>
+        <para>
+			Oracle has support for "query hints", which are formatted
+			comments embedded in SQL that provide some hint for
+			how the query should be executed. These hints are usually
+			designed to provide suggestions to the Oracle query
+			optimizer for how to efficiently perform a certainly query,
+			and aren't typically needed for any but the most intensive
+			queries.
+			</para>
+        <example id="dbsupport_oracle_query_hints_ex">
+          <title>Using Oracle Hints</title>
+          <programlisting format="linespecific">
+Query query = pm.createQuery (...);
+query.addExtension (org.apache.openjpa.jdbc.sql.OracleDictionary.SELECT_HINT,
+    "/*+ first_rows(100) */");
+List results = (List) query.execute ();
+</programlisting>
+          <programlisting format="linespecific">
+Query query = em.createQuery (...);
+query.setHint (org.apache.openjpa.jdbc.sql.OracleDictionary.SELECT_HINT,
+    "/*+ first_rows(100) */");
+List results = query.getResultList ();
+</programlisting>
+        </example>
+      </section>
+      <section id="dbsupport_oracle_issues">
+        <title>Known issues with Oracle</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						The Oracle JDBC driver has significant differences
+						between different versions. It is important to
+						use the officially supported version of the driver
+						(10.2.0.1.0), which is backward compatible
+						with previous versions of the Oracle server.
+						It can be downloaded from 
+						<ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc101040.html">http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc101040.html</ulink>.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						For VARCHAR fields, <literal>null</literal>
+						and a blank string are equivalent. This means that
+						an object that stores a null string field will
+						have it get read back as a blank string.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Oracle corp's JDBC driver for Oracle has only limited
+						support for batch updates. The result for OpenJPA is
+						that in some cases, the exact object that failed an
+						optimistic lock check cannot be determined, and OpenJPA
+						will throw an <classname>OptimisticVerificationException</classname> with
+						more failed objects than actually failed.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Oracle cannot store numbers with more than 38 digits
+						in numeric columns.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Floats and doubles may lose precision when stored.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						CLOB columns cannot be used in queries.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_pointbase">
+      <title>Pointbase</title>
+      <example id="example_props_pointbase">
+        <title>Example properties for Pointbase</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.pointbase.jdbc.jdbcUniversalDriver
+openjpa.ConnectionURL: \
+    jdbc:pointbase:DB_NAME,database.home=pointbasedb,create=true,cache.size=10000,database.pagesize=30720
+</programlisting>
+      </example>
+      <section id="dbsupport_pointbase_issues">
+        <title>Known issues with Pointbase</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+			Fields of type BLOB and CLOB are limited to 1M. This number can be 
+			increased by extending <classname>PointbaseDictionary</classname>.
+			</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_postgresql">
+      <title>PostgreSQL</title>
+      <example id="example_props_postgresql">
+        <title>Example properties for PostgreSQL</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: org.postgresql.Driver
+openjpa.ConnectionURL: jdbc:postgresql://SERVER_NAME:5432/DB_NAME
+</programlisting>
+      </example>
+      <section id="dbsupport_postgresql_issues">
+        <title>Known issues with PostgreSQL</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						Floats and doubles may lose precision when stored.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						PostgreSQL cannot store very low and very high dates.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Empty string/char values are stored as NULL.
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+    <section id="dbsupport_sybase">
+      <title>Sybase Adaptive Server</title>
+      <example id="example_props_sybase">
+        <title>Example properties for Sybase</title>
+        <programlisting format="linespecific">
+openjpa.ConnectionDriverName: com.sybase.jdbc2.jdbc.SybDriver
+openjpa.ConnectionURL: \
+    jdbc:sybase:Tds:SERVER_NAME:4100/DB_NAME?ServiceName=DB_NAME&amp;BE_AS_JDBC_COMPLIANT_AS_POSSIBLE=true
+</programlisting>
+      </example>
+      <section id="dbsupport_sybase_issues">
+        <title>Known issues with Sybase</title>
+        <para>
+          <itemizedlist>
+            <listitem>
+              <para>
+						The "<literal>DYNAMIC_PREPARE</literal>" parameter
+						of the Sybase JDBC driver cannot be used with OpenJPA.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Datastore locking cannot be used when manipulating
+						many-to-many relations using the default OpenJPA
+						schema created by the schematool,
+						unless an auto-increment primary key field is
+						manually added to the table.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						Persisting a zero-length string results in a
+						string with a single space characted being returned
+						from Sybase, Inc.'s JDBC driver.
+					</para>
+            </listitem>
+            <listitem>
+              <para>
+						The <literal>BE_AS_JDBC_COMPLIANT_AS_POSSIBLE</literal>
+						is required in order to use datastore (pessimistic)
+						locking. Failure to set this property may lead
+						to obscure errors like "<literal>FOR UPDATE can
+						not be used in a SELECT which is not part of
+						the declaration of a cursor or which is not
+						inside a stored procedure.</literal>".
+					</para>
+            </listitem>
+          </itemizedlist>
+        </para>
+      </section>
+    </section>
+  </appendix>
+</book>
diff --git a/openjpa-project/src/doc/manual/style.css b/openjpa-project/src/doc/manual/style.css
new file mode 100644
index 000000000..139b56104
--- /dev/null
+++ b/openjpa-project/src/doc/manual/style.css
@@ -0,0 +1,71 @@
+body, td, th {
+    font-size: 95%;
+    font-family: Arial, Geneva, Helvetica, sans-serif;
+    color: black;
+    background-color: white;
+}
+
+menu {
+    margin-left: 1em;
+    padding-left: 1em;
+    white-space: nowrap;
+}
+
+
+table.colortable {
+    background-color: #dddddd;
+}
+
+h2 {
+    font-size: 130%;
+    font-weight: bold;
+}
+
+h3 {
+    font-size: 110%;
+    font-weight: bold;
+}
+
+h4 {
+    font-size: 100%;
+    font-weight: bold;
+}
+
+.menuheader {
+    font-weight: bold;
+}
+
+.navleft {
+    padding-right: 5px;
+    border: 1px solid #cccccc;
+    border-width: 0px 1px 0px 0px;
+}
+
+.navright {
+    padding-left: 5px;
+    border: 1px solid #cccccc;
+    border-width: 0px 0px 0px 1px;
+}
+
+.section-content {
+    padding-left: 1em;
+    padding-right: 1em;
+}
+
+.footer {
+    text-align: center;
+    font-size: 80%;
+}
+
+.note {
+    margin: 1em;
+    padding: 1em;
+    border: 2px solid gray;
+}
+
+.source {
+    margin: 0em 1em 0em 1em;
+    padding: 0em 1em 0em 1em;
+    border: 2px solid #bbbbbb;
+    white-space: pre;
+}
diff --git a/openjpa-xmlstore/pom.xml b/openjpa-xmlstore/pom.xml
index 717db7595..91eb64c82 100644
--- a/openjpa-xmlstore/pom.xml
+++ b/openjpa-xmlstore/pom.xml
@@ -10,11 +10,9 @@
     <description>XML Store for OpenJPA</description>
     <url>http://incubator.apache.org/projects/openjpa</url>
     <parent>
-
         <groupId>org.apache.openjpa</groupId>
         <artifactId>openjpa</artifactId>
-        <version>0.0.1</version>
-
+        <version>0.9.0</version>
     </parent>
     <dependencies>
 
diff --git a/pom.xml b/pom.xml
index 3774271ed..0fac078d4 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1,15 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+            http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
+    <prerequisites>
+        <maven>2.0.4</maven>
+    </prerequisites>
     <groupId>org.apache.openjpa</groupId>
     <artifactId>openjpa</artifactId>
     <packaging>pom</packaging>
 
     <name>OpenJPA</name>
     <description>OpenJPA</description>
-    <version>0.0.1</version>
+
+    <!--
+        Changing this version needs to also be done in all children poms
+        See: http://jira.codehaus.org/browse/MNG-624
+    -->
+    <version>0.9.0</version>
+
     <url>http://incubator.apache.org/projects/openjpa</url>
+
     <issueManagement>
         <system>jira</system>
         <url>http://issues.apache.org/jira/browse/OPENJPA</url>
@@ -75,81 +87,111 @@
     </organization>
     <scm>
         <connection>
-            scm:svn:http://svn.apache.org/repos/asf/incubator/openjpa/${pom.artifactId}</connection>
+            scm:svn:http://svn.apache.org/repos/asf/incubator/openjpa/trunk</connection>
         <developerConnection>
-            scm:svn:https://svn.apache.org/repos/asf/incubator/openjpa/${pom.artifactId}</developerConnection>
+            scm:svn:https://svn.apache.org/repos/asf/incubator/openjpa/trunk</developerConnection>
         <url>
-            https://svn.apache.org/repos/asf/incubator/openjpa/${pom.artifactId}</url>
+            https://svn.apache.org/repos/asf/incubator/openjpa/trunk</url>
     </scm>
-    <modules>
 
+    <modules>
         <module>openjpa-lib</module>
         <module>openjpa-kernel</module>
-        <module>openjpa-kernel-5</module>
         <module>openjpa-jdbc</module>
-        <module>openjpa-jdbc-5</module>
-        <module>openjpa-persistence</module>
-        <module>openjpa-persistence-jdbc</module>
         <module>openjpa-xmlstore</module>
-
+        <module>openjpa-project</module>
     </modules>
-    <repositories>
 
+    <profiles>
+        <profile>
+            <id>jdk1.5</id>
+            <activation>
+                <jdk>1.5</jdk>
+            </activation>
+            <modules>
+                <module>openjpa-persistence</module>
+                <module>openjpa-persistence-jdbc</module>
+                <module>openjpa-kernel-5</module>
+                <module>openjpa-jdbc-5</module>
+            </modules>
+        </profile>
+
+        <profile>
+            <id>release</id>
+            <activation>
+                <property>
+                    <name>release</name>
+                </property>
+            </activation>
+            <modules>
+                <module>openjpa-project</module>
+            </modules>
+        </profile>
+    </profiles>
+
+    <repositories>
         <repository>
             <id>central</id>
             <name>Maven Repository Switchboard</name>
             <url>http://www.ibiblio.org/maven2</url>
         </repository>
-
-
         <repository>
             <id>java-net</id>
             <name>dev.java.net repository</name>
             <url>https://maven-repository.dev.java.net/nonav/repository</url>
             <layout>legacy</layout>
         </repository>
-
-
         <repository>
             <id>serp</id>
             <name>Serp Project Repository</name>
             <url>http://serp.sourceforge.net/m2repo</url>
         </repository>
-
     </repositories>
     <dependencies>
-
         <dependency>
-
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
             <version>3.8.1</version>
             <scope>compile</scope>
-
         </dependency>
-
     </dependencies>
+
     <build>
+        <!-- needed to let maven pass the "compile" phase -->
+        <testSourceDirectory>/none/</testSourceDirectory>
 
         <plugins>
-
             <plugin>
-
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
                 <configuration>
                     <source>1.5</source>
                     <target>1.5</target>
                 </configuration>
-
             </plugin>
-
         </plugins>
-
     </build>
 
     <reporting>
         <plugins>
+            <plugin>
+                <artifactId>maven-project-info-reports-plugin</artifactId>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>jdepend-maven-plugin</report>
+                            <!-- <report>jxr-maven-plugin</report> -->
+                            <report>surefire-report-maven-plugin</report>
+                            <report>maven-javadoc-plugin</report>
+                            <report>project-team</report>
+                            <report>mailing-list</report>
+                            <report>issue-tracking</report>
+                            <report>license</report>
+                            <report>scm</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
+            </plugin>
             <plugin>
                 <artifactId>maven-surefire-plugin</artifactId>
             </plugin>
@@ -157,42 +199,40 @@
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>taglist-maven-plugin</artifactId>
             </plugin>
-            <plugin>
-                <groupId>org.codehaus.mojo</groupId>
-                <artifactId>jxr-maven-plugin</artifactId>
-                <configuration>
-                    <aggregate>true</aggregate>
-                </configuration>
-            </plugin>
+
+
+            <!--
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <configuration>
                     <aggregate>true</aggregate>
                     <linksource>true</linksource>
+                    <maxmemory>512m</maxmemory>
                     <links>
                         <link>http://java.sun.com/j2se/1.5.0/docs/api</link>
                         <link>http://java.sun.com/javaee/5/docs/api</link>
-                        <link>
-                            http://jakarta.apache.org/commons/collections/api-release</link>
+                        <link>http://jakarta.apache.org/commons/collections/api-release</link>
                     </links>
                 </configuration>
             </plugin>
+            -->
+
+
         </plugins>
     </reporting>
     <distributionManagement>
-        <repository>
-            <id>bea-internal</id>
-            <name>Internal BEA OpenJPA test site</name>
-            <url>file:///${user.home}/web/devel/openjpa/dist</url>
-        </repository>
-        <site>
-            <id>bea-internal</id>
-            <name>Internal BEA OpenJPA test sit</name>
-            <url>file:///${user.home}/web/devel/openjpa/site</url>
-        </site>
+      <repository>
+        <id>people.apache.org</id>
+        <url>scp://people.apache.org/home/mprudhom/public_html/openjpa/m2repo</url>
+      </repository>
+      <snapshotRepository>
+        <id>openjpa</id>
+        <url>scp://people.apache.org/home/mprudhom/public_html/openjpa/m2snapshot</url>
+      </snapshotRepository>
+      <site>
+        <id>people.apache.org</id>
+        <url>scpexe://people.apache.org/home/mprudhom/public_html/openjpa/site/</url>
+      </site>
     </distributionManagement>
-
 </project>
-
-
diff --git a/src/site/apt/building.apt b/src/site/apt/building.apt
new file mode 100644
index 000000000..caf528f55
--- /dev/null
+++ b/src/site/apt/building.apt
@@ -0,0 +1,23 @@
+ ------
+ openjpa
+ ------
+
+Building OpenJPA
+
+ Building OpenJPA requires an installation of {{{http://maven.apache.org/}Maven 2}}.
+
+ Check out the sources then run:
+
++--------------------------------+                        
+mvn compile
++--------------------------------+                        
+
+ To run the tests:
+
++--------------------------------+                        
+mvn test
++--------------------------------+                        
+
+
+
+
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
new file mode 100644
index 000000000..aa87ce65e
--- /dev/null
+++ b/src/site/apt/index.apt
@@ -0,0 +1,11 @@
+ ------
+ openjpa
+ ------
+
+Welcome to the OpenJPA project site!
+
+ OpenJPA is a set of Java persistence Application Program Interfaces (APIs) that are based on the Enterprise Java Beans 3.0 persistenace specification. This is the distribution and project management site for OpenJPA. For community resources, please see the {{{http://wiki.apache.org/incubator/OpenJPA}OpenJPA wiki}}.
+
+ To download OpenJPA, please go to the {{{downloads.html}downloads}} page.
+
+
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 000000000..0651b83c3
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="OpenJPA">
+    <bannerLeft>
+        <name>OpenJPA</name>
+        <!-- <src>http://www.apache.org/images/asf_logo_wide.gif</src> -->
+        <!-- <href>/</href> -->
+    </bannerLeft>     
+    <body>
+        <menu name="OpenJPA">
+            <item name="Home" href="index.html"/>
+            <item name="Manual" href="openjpa-project/manual/manual.html"/>
+            <item name="Download" href="downloads.html"/>
+            <item name="Building" href="building.html"/>
+        </menu>
+
+        <menu name="Community">
+            <item name="Issue Tracker"
+                href="https://issues.apache.org/jira/browse/OPENJPA"/>
+            <item name="Wiki"
+                href="http://wiki.apache.org/incubator/OpenJPA"/>
+        </menu>
+
+        <menu ref="parent"/>
+        <menu ref="reports"/>
+
+        <!-- <menu ref="modules"/> -->
+    </body>
+
+    <skin>
+        <groupId>org.apache.maven.skins</groupId>
+        <artifactId>maven-stylus-skin</artifactId>
+        <version>1.0</version>
+    </skin>
+</project>
diff --git a/src/site/xdoc/downloads.xml b/src/site/xdoc/downloads.xml
new file mode 100644
index 000000000..027a288c4
--- /dev/null
+++ b/src/site/xdoc/downloads.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+    <properties>
+        <title>OpenJPA Downloads</title>
+    </properties>
+    <body>
+        <section name="Certified Downloads">
+            <p>
+            Currently, Apache OpenJPA has no certified releases.
+            </p>
+        </section>
+
+        <section name="Milestone Downloads">
+            <p>
+            The following non-certified milestone releases are available.
+            These milestone releases are 'technology demonstrations' and not
+            offered as a J2EE-compatible JPA implementation.
+            </p>
+
+            <p><strong>0.9.0</strong> - <i>July 25, 2006</i></p>
+            <ul>
+                <li>
+                    <a href="openjpa-project/downloads/openjpa-0.9.0.zip">binary zip</a>
+                    -
+                    <a href="openjpa-project/downloads/openjpa-0.9.0-sources.zip">source zip</a>
+                </li>
+            </ul>
+
+        </section>
+    </body>
+</document>
+