openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mprud...@apache.org
Subject svn commit: r433761 [8/18] - in /incubator/openjpa/trunk/openjpa-project: ./ src/doc/manual/
Date Tue, 22 Aug 2006 21:28:55 GMT
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml?rev=433761&r1=433760&r2=433761&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/manual.xml Tue Aug 22 14:28:53 2006
@@ -1,33837 +1,94 @@
 <?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"> ]>
+<!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">
+
+    <!ENTITY openjpa_intro.xml SYSTEM "openjpa_intro.xml">
+    <!ENTITY jpa_overview_intro.xml SYSTEM "jpa_overview_intro.xml">
+    <!ENTITY jpa_overview_why.xml SYSTEM "jpa_overview_why.xml">
+    <!ENTITY jpa_overview_arch.xml SYSTEM "jpa_overview_arch.xml">
+    <!ENTITY jpa_overview_pc.xml SYSTEM "jpa_overview_pc.xml">
+    <!ENTITY jpa_overview_meta.xml SYSTEM "jpa_overview_meta.xml">
+    <!ENTITY jpa_overview_persistence.xml SYSTEM "jpa_overview_persistence.xml">
+    <!ENTITY jpa_overview_emfactory.xml SYSTEM "jpa_overview_emfactory.xml">
+    <!ENTITY jpa_overview_em.xml SYSTEM "jpa_overview_em.xml">
+    <!ENTITY jpa_overview_trans.xml SYSTEM "jpa_overview_trans.xml">
+    <!ENTITY jpa_overview_query.xml SYSTEM "jpa_overview_query.xml">
+    <!ENTITY jpa_overview_sqlquery.xml SYSTEM "jpa_overview_sqlquery.xml">
+    <!ENTITY jpa_overview_mapping.xml SYSTEM "jpa_overview_mapping.xml">
+    <!ENTITY jpa_overview_conclusion.xml SYSTEM "jpa_overview_conclusion.xml">
+    <!ENTITY jpa_tutorials.xml SYSTEM "jpa_tutorials.xml">
+    <!ENTITY ref_guide_intro.xml SYSTEM "ref_guide_intro.xml">
+    <!ENTITY ref_guide_conf.xml SYSTEM "ref_guide_conf.xml">
+    <!ENTITY ref_guide_logging.xml SYSTEM "ref_guide_logging.xml">
+    <!ENTITY ref_guide_dbsetup.xml SYSTEM "ref_guide_dbsetup.xml">
+    <!ENTITY ref_guide_pc.xml SYSTEM "ref_guide_pc.xml">
+    <!ENTITY ref_guide_meta.xml SYSTEM "ref_guide_meta.xml">
+    <!ENTITY ref_guide_mapping.xml SYSTEM "ref_guide_mapping.xml">
+    <!ENTITY ref_guide_deploy.xml SYSTEM "ref_guide_deploy.xml">
+    <!ENTITY ref_guide_runtime.xml SYSTEM "ref_guide_runtime.xml">
+    <!ENTITY ref_guide_caching.xml SYSTEM "ref_guide_caching.xml">
+    <!ENTITY ref_guide_remote.xml SYSTEM "ref_guide_remote.xml">
+    <!ENTITY ref_guide_integration.xml SYSTEM "ref_guide_integration.xml">
+    <!ENTITY ref_guide_optimization.xml SYSTEM "ref_guide_optimization.xml">
+    <!ENTITY samples_guide.xml SYSTEM "samples_guide.xml">
+    <!ENTITY jpa_resources.xml SYSTEM "jpa_resources.xml">
+    <!ENTITY supported_databases.xml SYSTEM "supported_databases.xml">
+]>
 <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 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/jpa-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/jpa-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/jpa-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>.

[... 31920 lines stripped ...]


Mime
View raw message