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