You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by pc...@apache.org on 2007/07/27 20:18:12 UTC
svn commit: r560342 - in /openjpa/trunk/openjpa-project/src/doc/manual:
jpa_overview_pc.xml jpa_tutorials.xml ref_guide_mapping.xml
ref_guide_optimization.xml ref_guide_pc.xml samples_guide.xml
Author: pcl
Date: Fri Jul 27 11:18:10 2007
New Revision: 560342
URL: http://svn.apache.org/viewvc?view=rev&rev=560342
Log:
OPENJPA-298
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml
openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml?view=diff&rev=560342&r1=560341&r2=560342
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_pc.xml Fri Jul 27 11:18:10 2007
@@ -177,7 +177,7 @@
<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"/>
+not apply when using the enhancer. See <xref linkend="ref_guide_pc_enhance"/>
of the Reference Guide for details.
</para>
</note>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml?view=diff&rev=560342&r1=560341&r2=560342
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml Fri Jul 27 11:18:10 2007
@@ -222,7 +222,7 @@
<para>
Let's compile the initial classes and see them in action. To do so, we must
compile the <filename>.java</filename> files, as we would with any Java project,
-and then pass the resulting classes through the OpenJPA enhancer:
+and then optionally pass the resulting classes through the OpenJPA enhancer.
</para>
<note>
<para>
@@ -387,7 +387,7 @@
</listitem>
<listitem>
<para>
-Enhance the persistent classes.
+Enhance the persistent classes. (Optional)
</para>
<programlisting>
java org.apache.openjpa.enhance.PCEnhancer Animal.java Dog.java
@@ -396,7 +396,7 @@
This step runs the OpenJPA enhancer on the <filename>Animal.java</filename> and
<filename>Dog.java</filename> files mentioned above. See
<xref linkend="ref_guide_pc_enhance"/> of the Reference Guide for more
-information on the enhancer, including how to use automatic runtime enhancement.
+information on the enhancer, including alternatives to enhancement.
</para>
<note>
<para>
@@ -417,7 +417,7 @@
Configuring the Datastore
</title>
<para>
-Now that we've compiled the source files and enhanced the persistent classes,
+Now that we've compiled the source files,
we're ready to set up the database. <ulink url="http://hsqldb.sourceforge.net">
Hypersonic SQL</ulink>, a pure Java relational database, is included in the
OpenJPA distribution. We have included this database because it is simple to set
@@ -819,7 +819,7 @@
</listitem>
<listitem>
<para>
-Enhance the <classname>Rabbit</classname> class.
+Enhance the <classname>Rabbit</classname> class. (Optional)
</para>
<programlisting>
java org.apache.openjpa.enhance.PCEnhancer Rabbit.java
@@ -907,7 +907,7 @@
</listitem>
<listitem>
<para>
-Enhance the class.
+Enhance the class. (Optional)
</para>
<programlisting>
java org.apache.openjpa.enhance.PCEnhancer Snake.java
@@ -1118,7 +1118,7 @@
<listitem>
<para>
Compile <filename>Snake.java</filename> and <filename>Rabbit.java</filename> and
-enhance the classes.
+optionally enhance the classes.
</para>
<programlisting>
javac Snake.java Rabbit.java
@@ -1320,7 +1320,7 @@
javac *.java ejb/*.java jsp/*.java
</programlisting>
<para>
-Enhance the Car class.
+Enhance the Car class. (Optional)
</para>
<programlisting>
java org.apache.openjpa.enhance.PCEnhancer Car.java
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml?view=diff&rev=560342&r1=560341&r2=560342
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml Fri Jul 27 11:18:10 2007
@@ -7,15 +7,15 @@
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
-
+
http://www.apache.org/licenses/LICENSE-2.0
-
+
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
- under the License.
+ under the License.
-->
<chapter id="ref_guide_mapping">
<title>
@@ -205,7 +205,7 @@
<para>
<literal>buildSchema</literal>: This is the default action. It
makes the database schema match your existing mappings. If your provided
-mappings conflict with your class definitions, OpenJPA will fail with an
+mappings conflict with your class definitions, OpenJPA will fail with an
informative exception.
</para>
</listitem>
@@ -548,7 +548,7 @@
<listitem>
<para>
<literal>-annotations/-ann <true/t | false/f></literal>: Set to true to
-generate JPA annotations in generated java classes.
+generate JPA annotations in generated java classes.
</para>
</listitem>
<listitem>
@@ -677,7 +677,7 @@
<classname>PropertiesReverseCustomizer</classname></ulink>. This customizer
allows you to specify simple customization options in the properties file given
with the <literal>-customizerProperties</literal> flag below. We present the
-available property keys <link linkend="ref_guide_pc_reverse_custom">
+available property keys <link linkend="ref_guide_pc_reverse_custom">
below</link>.
</para>
</listitem>
@@ -714,12 +714,12 @@
<para>
After you are satisfied with the generated classes and their mappings, you
should first compile the classes with <literal>javac</literal>, <literal>
-jikes</literal>, or your favorite Java compiler. Make sure the classes are
-located in the directory corresponding to the <literal>-package</literal> flag
+jikes</literal>, or your favorite Java compiler. Make sure the classes are
+located in the directory corresponding to the <literal>-package</literal> flag
you gave the reverse mapping tool. Next, if you have generated an <filename>
orm.xml</filename>, move that file to a <filename>META-INF</filename> directory
within a directory in your classpath. Finally, enhance the classes
-if necessary (see <xref linkend="ref_guide_pc_enhance"/> ).
+if necessary (see <xref linkend="ref_guide_pc_enhance"/>).
</para>
</listitem>
</orderedlist>
@@ -929,7 +929,7 @@
mapping approach, you control both the relational model and the object model. It
is up to you to define the mappings between these models. The mapping
tool's <literal>validate</literal> action is useful to meet-in-the-middle
-mappers. This action verifies that the mapping information for a class matches
+mappers. This action verifies that the mapping information for a class matches
the class definition and the existing schema. It throws an informative exception
when your mappings are incorrect.
</para>
@@ -986,8 +986,8 @@
<para>
OpenJPA relies on foreign key constraint information at runtime to order SQL
appropriately. Be sure to set your mapping defaults to reflect your existing
-database constraints, set the schema factory to reflect on the database for
-constraint information (see <xref linkend="ref_guide_schema_info_factory"/>),
+database constraints, set the schema factory to reflect on the database for
+constraint information (see <xref linkend="ref_guide_schema_info_factory"/>),
or use explicit foreign key mappings as described in
<xref linkend="ref_guide_mapping_jpa_fk"/>.
</para>
@@ -1015,7 +1015,7 @@
<listitem>
<para>
<literal>PrependFieldNameToJoinTableInverseJoinColumns</literal>: Whether to
-prepend the owning field name to the names of inverse join columns in join
+prepend the owning field name to the names of inverse join columns in join
tables. Defaults to true per the JPA specification. Set to false for
compatibility with older OpenJPA versions which did not prepend the field name.
</para>
@@ -1281,8 +1281,8 @@
<para>
<literal>-</literal>: Leaving the <literal> openjpa.jdbc.MappingFactory
</literal> property unset allows your metadata factory to take over mappings as
-well. If you are using the default <literal>jpa</literal> metadata factory,
-OpenJPA will read mapping information from your annotations and
+well. If you are using the default <literal>jpa</literal> metadata factory,
+OpenJPA will read mapping information from your annotations and
<filename>orm.xml</filename> when you leave the mapping factory unspecified.
</para>
</listitem>
@@ -2172,7 +2172,7 @@
</indexterm>
<para>
We detailed the <literal>ContainerTable</literal> annotation in
-<xref linkend="ref_guide_mapping_jpa_coll_table"/>. Custom map mappings may
+<xref linkend="ref_guide_mapping_jpa_coll_table"/>. Custom map mappings may
also use this annotation to represent a map table.
</para>
</section>
@@ -2189,7 +2189,7 @@
</para>
<para>
OpenJPA assumes certain columns have indexes or constraints based on your
-mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>.
+mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>.
You can override the configured defaults on individual joins, field
values, collection elements, map keys, or map values using the annotations
presented in the following sections.
@@ -2267,7 +2267,7 @@
annotation represents a foreign key on the columns of a field. It is also used
within the <link linkend="ref_guide_mapping_jpa_coll_table"><classname>
ContainerTable</classname></link> annotation to set a database foreign key on
-join columns. To set a constraint to the columns of a collection element, use
+join columns. To set a constraint to the columns of a collection element, use
the
<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/ElementForeignKey.html">
<classname> org.apache.openjpa.persistence.jdbc.ElementForeignKey</classname>
@@ -2397,20 +2397,20 @@
<para>
Annotate the entity property using the XMLValueHandler strategy:
</para>
-<programlisting>
+<programlisting>
@Persistent
@Strategy("org.apache.openjpa.jdbc.meta.strats.XMLValueHandler")
</programlisting>
<para>
The default fetch type is EAGER but can be changed to LAZY by using:
</para>
-<programlisting>
+<programlisting>
@Persistence(fetch=FetchType.LAZY)
</programlisting>
<para>
The entity property class is required to have
-jaxb binding annotations. This is produced when the classes are generated
-from an xml schema using the jaxb generator XJC.Ensure that <classname>@XmlRootElement</classname>
+jaxb binding annotations. This is produced when the classes are generated
+from an xml schema using the jaxb generator XJC.Ensure that <classname>@XmlRootElement</classname>
appears in the root class. In some case this annotation needs to be added manually if it is missing.
</para>
<para>
@@ -2427,8 +2427,8 @@
</para>
<para>
The path expression must be single valued.Path expressions over xml
-mapped classes can only be used in WHERE as an operand to a simple predicate
-(= <> < > >= <=).
+mapped classes can only be used in WHERE as an operand to a simple predicate
+(= <> < > >= <=).
</para>
<para>
Path expressions over XML mapped fields can not be:
@@ -2456,9 +2456,9 @@
</listitem>
</itemizedlist>
<para>
-XML schema must not contain namespace declarations. The EJB query path
+XML schema must not contain namespace declarations. The EJB query path
expressions can not refer to java fields generated from XML ANY type or
-XML mixed element types.
+XML mixed element types.
</para>
<para>
The datatype generated by JAXB must be a valid EJB query type
@@ -2479,7 +2479,7 @@
<xs:complexType name="Address">
<xs:sequence>
<xs:element name="Name" type="xs:string" />
- <xs:element name="Street" type="xs:string"
+ <xs:element name="Street" type="xs:string"
minOccurs="1" maxOccurs="3" />
<xs:element name="City" type="xs:string" />
</xs:sequence>
@@ -2524,8 +2524,8 @@
</example>
<para>
Java classes <link linkend="ref_guide_xmlmapping_address">Address</link>,
-<link linkend="ref_guide_xmlmapping_usaaddress">USAAddress</link> and
-<link linkend="ref_guide_xmlmapping_canaddress">CANAddress</link>
+<link linkend="ref_guide_xmlmapping_usaaddress">USAAddress</link> and
+<link linkend="ref_guide_xmlmapping_canaddress">CANAddress</link>
are produced using jaxb XJC generator from myaddress schema.
</para>
<example id="ref_guide_xmlmapping_address">
@@ -2548,12 +2548,12 @@
protected List<String> street;
@XmlElement(name = "City", required = true)
protected String city;
-
+
/**
* Getter and Setter methods.
- *
- */
- ...
+ *
+ */
+ ...
}
</programlisting>
</example>
@@ -2580,9 +2580,9 @@
/**
* Getter and Setter methods.
- *
- */
- ...
+ *
+ */
+ ...
}
</programlisting>
</example>
@@ -2609,10 +2609,10 @@
/**
* Getter and Setter methods.
- *
- */
- ...
-}
+ *
+ */
+ ...
+}
</programlisting>
</example>
<example id="ref_guide_xmlmapping_annorder">
@@ -2621,9 +2621,9 @@
</title>
<programlisting>
@Entity
-public class Order {
+public class Order {
@Id private into id;
- @Persistent
+ @Persistent
@Strategy ("org.apache.openjpa.jdbc.meta.strats.XMLValueHandler")
private Address shipAddress;
...
@@ -2657,12 +2657,12 @@
Sample EJB Queries for XML Column mapping
</title>
<programlisting>
-. select o from Order o where o.shipAddress.city = "San Jose" or
+. select o from Order o where o.shipAddress.city = "San Jose" or
o.shipAddress.city = "San Francisco" (OK)
-
-. select o.shipaAddress from Order o (OK)
-. select o.shipAddress.city from Order o (INVALID)
+. select o.shipaAddress from Order o (OK)
+
+. select o.shipAddress.city from Order o (INVALID)
. select o from Order o where o.shipAddress.street = "San Jose" (INVALID multi valued)
</programlisting>
@@ -3044,7 +3044,7 @@
</seealso>
</indexterm>
<para>
-OpenJPA's
+OpenJPA's
<ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/Strategy.html">
<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
extension allows you to specify a custom mapping
@@ -3174,8 +3174,8 @@
org.apache.openjpa.jdbc.meta.ValueHandler</classname> interface; see its
<ulink url="../javadoc/org/apache/openjpa/jdbc/meta/ValueHandler.html"> Javadoc
</ulink> for details. Also, examine the built-in handlers in the <filename>
-src/openjpa/jdbc/meta/strats</filename> directory of your OpenJPA source
-distribution. Use these functional implementations as examples when you
+src/openjpa/jdbc/meta/strats</filename> directory of your OpenJPA source
+distribution. Use these functional implementations as examples when you
create your own value handlers.
</para>
</section>
@@ -3227,7 +3227,7 @@
field types with their corresponding custom value handler or strategy. OpenJPA
will automatically use your custom strategies when it encounters a field of the
associated type. OpenJPA will use your custom value handlers whenever it
-encounters a field of the associated type.
+encounters a field of the associated type.
<xref linkend="ref_guide_mapping_defaults"/> described mapping
defaults in detail.
</para>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml?view=diff&rev=560342&r1=560341&r2=560342
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml Fri Jul 27 11:18:10 2007
@@ -170,6 +170,25 @@
<row>
<entry colname="name">
<emphasis role="bold">
+ Run the OpenJPA enhancer on your persistent classes,
+ either at build-time or deploy-time.
+ </emphasis>
+ <para>
+<emphasis>performance, scalability, memory footprint</emphasis>
+ </para>
+ </entry>
+ <entry colname="desc">
+OpenJPA performs best when your persistent classes have been run through the
+OpenJPA post-compilation bytecode enhancer. When dealing with enhanced classes,
+OpenJPA can make a number of assumptions that reduce memory footprint and
+accelerate persistent data access. When evaluating OpenJPA's performance,
+build-time or deploy-time enhancement should be enabled. See
+<xref linkend="ref_guide_pc_enhance"/> for details.
+ </entry>
+ </row>
+ <row>
+ <entry colname="name">
+ <emphasis role="bold">
Disable logging, performance tracking
</emphasis>
<para>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml?view=diff&rev=560342&r1=560341&r2=560342
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_pc.xml Fri Jul 27 11:18:10 2007
@@ -114,7 +114,7 @@
</indexterm>
<para>
In order to provide optimal runtime performance, flexible lazy loading, and
-efficient, immediate dirty tracking, OpenJPA uses an <emphasis> enhancer
+efficient, immediate dirty tracking, OpenJPA can use 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
@@ -139,7 +139,7 @@
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
+You can add the OpenJPA enhancer to your build process, or use Java 1.5's
instrumentation features to transparently enhance persistent classes when they
are loaded into the JVM. The following sections describe each option.
</para>
@@ -269,14 +269,14 @@
</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
+The Java EE 5 specification includes hooks to automatically enhance JPA entities
+when they are deployed into a container. Thus, if you are using a Java EE
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,
+If your application server does not support the Java EE 5 enhancement hooks,
consider using the build-time enhancement described above, or the more general
runtime enhancement described in the next section.
</para>
@@ -325,7 +325,7 @@
<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
+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
@@ -351,6 +351,20 @@
accordingly. This may slow down class load times significantly.
</para>
</listitem>
+ <listitem>
+ <para>
+<literal>runtimeEnhancement</literal>: Boolean controlling whether OpenJPA
+class enhancement should be available in this JVM execution. Default:
+<literal>true</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>runtimeRedefinition</literal>: Boolean controlling whether OpenJPA
+class redefinition should be available in this JVM execution. Default:
+<literal>true</literal>
+ </para>
+ </listitem>
</itemizedlist>
<example id="ref_guide_pc_enhance_runtime_opt_ex">
<title>
@@ -361,38 +375,107 @@
</programlisting>
</example>
</section>
- <section id="ref_guide_pc_enhance_sercompat">
+ <section id="ref_guide_pc_enhance_unenhanced_types">
<title>
- Serializing Enhanced Types
+ Omitting the OpenJPA enhancer
</title>
- <indexterm zone="ref_guide_pc_enhance_sercompat">
+ <indexterm zone="ref_guide_pc_enhance_unenhanced_types">
<primary>
enhancer
</primary>
<secondary>
- serialization
+ omitting
</secondary>
<tertiary>
- of enhanced types
+ outside a container
</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>
+OpenJPA does not require that the enhancer be run. If you do not run the
+enhancer, OpenJPA will fall back to one of several possible alternatives for
+state tracking, depending on the execution environment.
+ </para>
+ <itemizedlist>
+ <listitem><para>
+<emphasis>Deploy-time enhancement</emphasis>: if you are running your
+application inside a Java EE 5 container, or another environment that supports
+the JPA container contract, then OpenJPA will automatically perform class
+transformation at deploy time.
+ </para></listitem>
+ <listitem><para>
+<emphasis>Java 6 class retransformation</emphasis>: if you are running your
+application in a Java 6 environment, OpenJPA will attempt to dynamically
+register a <literal>ClassTransformer</literal> that will redefine your
+persistent classes on the fly to track access to persistent data. Additionally,
+OpenJPA will create a subclass for each of your persistent classes. When
+you execute a query or traverse a relation, OpenJPA will return an instance
+of the subclass. This means that the <literal>instanceof</literal> operator
+will work as expected, but <literal>o.getClass()</literal> will return the
+subclass instead of the class that you wrote.
+ </para>
+ <para>
+You do not need to do anything at all to get this behavior. OpenJPA will
+automatically detect whether or not the execution environment is capable of
+Java 6 class retransformation.
+ </para></listitem>
+ <listitem><para>
+<emphasis>Java 5 class redefinition</emphasis>: if you are running your
+application in a Java 5 environment, and you specify the OpenJPA javaagent,
+OpenJPA will use Java 5 class redefinition to redefine any persistent classes
+that are not enhanced by thet OpenJPA javaagent. Aside from the requirement
+that you specify a javaagent on the command line, this behavior is exactly the
+same as the Java 6 class retransformation behavior. Of course, since the
+OpenJPA javaagent performs enhancement by default, this will only be available
+if you set the <literal>runtimeEnhancement</literal> javaagent flag to
+<literal>false</literal>, or on any classes that are skipped by the OpenJPA
+runtime enhancement process for some reason.
+ </para></listitem>
+ <listitem><para>
+<emphasis>state comparison and subclassing</emphasis>: if you are running
+in a Java 5 environment without a javaagent, or in a Java 6 environment that
+does not support class retransformation, OpenJPA will still create subclasses
+as outlined above. However, in some cases, OpenJPA may not be able to receive
+notifications when you read or write persistent data.
+ </para>
+ <para>
+If you are using <emphasis>property access</emphasis> for your persistent data,
+then OpenJPA will be able to track all accesses for instances that you load
+from the database, but not for instances that you create. This is because
+OpenJPA will create new instances of its dynamically-generated subclass when
+it loads data from the database. The dynamically-generated subclass has
+code in the setters and getters that notify OpenJPA about persistent data
+access. This means that new instances that you create will be subject to
+state-comparison checks (see discussion below) to compute which fields to
+write to the database, and that OpenJPA will ignore requests to evict
+persistent data from such instances. In practice, this is not a particularly
+bad limitation, since OpenJPA already knows that it must insert all field
+values for new instances. So, this is only really an issue if you flush
+changes to the database while inserting new records; after such a flush,
+OpenJPA will need to hold potentially-unneeded hard references to the
+new-flushed instances.
+ </para>
+ <para>
+If you are using <emphasis>field access</emphasis> for your persistent data,
+then OpenJPA will not be able to track accesses for any instances, including
+ones that you load from the database. So, OpenJPA will perform state-comparison
+checks to determine which fields are dirty. These state comparison checks are
+costly in two ways. First, there is a performance penalty at flush / commit
+time, since OpenJPA must walk through every field of every instance to determine
+which fields of which records are dirty. Second, there is a memory penalty,
+since OpenJPA must hold hard references to all instances that were loaded at
+any time in a given transaction, and since OpenJPA must keep a copy of all
+the initial values of the loaded data for later comparison. Additionally,
+OpenJPA will ignore requests to evict persistent state for these types of
+instances. Finally, the default lazy loading configuration will be ignored for
+single-valued fields (one-to-one, many-to-one, and any other non-collection
+or non-map field that has a lazy loading configuration). If you use fetch
+groups or programmatically configure your fetch plan, OpenJPA will obey these
+directives, but will be unable to lazily load any data that you exclude from
+loading. As a result of these limitations, it is not recommended that you use
+field access if you are not either running the enhancer or using OpenJPA with
+a javaagent or in a Java 6 environment.
+ </para></listitem>
+ </itemizedlist>
</section>
</section>
<section id="ref_guide_pc_oid">
Modified: openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml?view=diff&rev=560342&r1=560341&r2=560342
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/samples_guide.xml Fri Jul 27 11:18:10 2007
@@ -102,7 +102,7 @@
<listitem>
<para>
You should then proceed to pass in the configuration file you are using to the
-enhancer:
+enhancer: (Optional)
</para>
<para>
<userinput>java org.apache.openjpa.enhance.PCEnhancer -p persistence.xml Machine.java Crane.java Bulldozer.java