From 58533057a0aa95e53342c4a3ed9c50dfed859a44 Mon Sep 17 00:00:00 2001 From: Patrick Linskey Date: Fri, 27 Jul 2007 18:18:10 +0000 Subject: [PATCH] OPENJPA-298 git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@560342 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/doc/manual/jpa_overview_pc.xml | 2 +- .../src/doc/manual/jpa_tutorials.xml | 16 +- .../src/doc/manual/ref_guide_mapping.xml | 100 ++++++------- .../src/doc/manual/ref_guide_optimization.xml | 19 +++ .../src/doc/manual/ref_guide_pc.xml | 137 ++++++++++++++---- .../src/doc/manual/samples_guide.xml | 2 +- 6 files changed, 189 insertions(+), 87 deletions(-) diff --git a/openjpa-project/src/doc/manual/jpa_overview_pc.xml b/openjpa-project/src/doc/manual/jpa_overview_pc.xml index 21bed8791..1250f1c0a 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_pc.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_pc.xml @@ -177,7 +177,7 @@ constructor. OpenJPA's enhancer will automatically add a protected no-arg constructor to your class when required. Therefore, this restriction does -not apply when using OpenJPA. See +not apply when using the enhancer. See of the Reference Guide for details. diff --git a/openjpa-project/src/doc/manual/jpa_tutorials.xml b/openjpa-project/src/doc/manual/jpa_tutorials.xml index 9faf3c299..e98a62fb0 100644 --- a/openjpa-project/src/doc/manual/jpa_tutorials.xml +++ b/openjpa-project/src/doc/manual/jpa_tutorials.xml @@ -222,7 +222,7 @@ information. Let's compile the initial classes and see them in action. To do so, we must compile the .java 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. @@ -387,7 +387,7 @@ You can use any java compiler instead of javac. -Enhance the persistent classes. +Enhance the persistent classes. (Optional) java org.apache.openjpa.enhance.PCEnhancer Animal.java Dog.java @@ -396,7 +396,7 @@ java org.apache.openjpa.enhance.PCEnhancer Animal.java Dog.java This step runs the OpenJPA enhancer on the Animal.java and Dog.java files mentioned above. See 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. @@ -417,7 +417,7 @@ OpenJPA configuration. Configuring the Datastore -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. Hypersonic SQL, 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 @@ javac Rabbit.java -Enhance the Rabbit class. +Enhance the Rabbit class. (Optional) java org.apache.openjpa.enhance.PCEnhancer Rabbit.java @@ -907,7 +907,7 @@ javac Snake.java -Enhance the class. +Enhance the class. (Optional) java org.apache.openjpa.enhance.PCEnhancer Snake.java @@ -1118,7 +1118,7 @@ key that joins the rabbit table to the snake table. The rabbit table has an Compile Snake.java and Rabbit.java and -enhance the classes. +optionally enhance the classes. javac Snake.java Rabbit.java @@ -1320,7 +1320,7 @@ nested ejb and jsp directories: javac *.java ejb/*.java jsp/*.java -Enhance the Car class. +Enhance the Car class. (Optional) java org.apache.openjpa.enhance.PCEnhancer Car.java diff --git a/openjpa-project/src/doc/manual/ref_guide_mapping.xml b/openjpa-project/src/doc/manual/ref_guide_mapping.xml index fa3105e9e..350432a37 100644 --- a/openjpa-project/src/doc/manual/ref_guide_mapping.xml +++ b/openjpa-project/src/doc/manual/ref_guide_mapping.xml @@ -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. --> @@ -205,7 +205,7 @@ the action to take on each class. The available actions are: <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 @@ generation. <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 @@ the system defaults to a <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 @@ generates. <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 @@ In the <emphasis>meet-in-the-middle</emphasis> mapping approach, you control both the relational model and the object model. It is up to you to define the mappings between these models. 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 @@ schema that matches your object model. <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 @@ properties (though with different default values), as well as: <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 @@ The bundled mapping factories are: <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 @@ public class Subscription { </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 @@ batch size. </para> <para> OpenJPA assumes certain columns have indexes or constraints based on your -mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>. +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 @@ The <ulink url="../javadoc/org/apache/openjpa/persistence/jdbc/ForeignKey.html"> 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 @@ entity property mapped to an XML column. <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 @@ XML functions. </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 @@ used in the FROM , GROUP BY, HAVING, ORDER BY clauses </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 @@ in which the JPA entity Order has <classname><shipAddress></classname> per <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 @@ in which the JPA entity Order has <classname><shipAddress></classname> per </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 @@ public class Address { protected List<String> street; @XmlElement(name = "City", required = true) protected String city; - + /** * Getter and Setter methods. - * - */ - ... + * + */ + ... } </programlisting> </example> @@ -2580,9 +2580,9 @@ public class USAAddress /** * Getter and Setter methods. - * - */ - ... + * + */ + ... } </programlisting> </example> @@ -2609,10 +2609,10 @@ public class CANAddress /** * Getter and Setter methods. - * - */ - ... -} + * + */ + ... +} </programlisting> </example> <example id="ref_guide_xmlmapping_annorder"> @@ -2621,9 +2621,9 @@ public class CANAddress @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 @@ em.persist(o1); Sample EJB Queries for XML Column mapping -. 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) @@ -3044,7 +3044,7 @@ array or collection element relations, respectively: -OpenJPA's +OpenJPA's org.apache.openjpa.persistence.jdbc.Strategy extension allows you to specify a custom mapping @@ -3174,8 +3174,8 @@ or more simple values. All value handlers implement the org.apache.openjpa.jdbc.meta.ValueHandler interface; see its Javadoc for details. Also, examine the built-in handlers in the -src/openjpa/jdbc/meta/strats directory of your OpenJPA source -distribution. Use these functional implementations as examples when you +src/openjpa/jdbc/meta/strats directory of your OpenJPA source +distribution. Use these functional implementations as examples when you create your own value handlers. @@ -3227,7 +3227,7 @@ MappingDefaults implementations allows you to globally associate field types with their corresponding custom value handler or strategy. OpenJPA will automatically use your custom strategies when it encounters a field of the associated type. OpenJPA will use your custom value handlers whenever it -encounters a field of the associated type. +encounters a field of the associated type. described mapping defaults in detail. diff --git a/openjpa-project/src/doc/manual/ref_guide_optimization.xml b/openjpa-project/src/doc/manual/ref_guide_optimization.xml index 55939607c..fd39b6e3b 100644 --- a/openjpa-project/src/doc/manual/ref_guide_optimization.xml +++ b/openjpa-project/src/doc/manual/ref_guide_optimization.xml @@ -167,6 +167,25 @@ OpenJPAEntityManager.setPopulateDataCache + + + + Run the OpenJPA enhancer on your persistent classes, + either at build-time or deploy-time. + + +performance, scalability, memory footprint + + + +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 + for details. + + diff --git a/openjpa-project/src/doc/manual/ref_guide_pc.xml b/openjpa-project/src/doc/manual/ref_guide_pc.xml index 3eb4103e9..227394b70 100644 --- a/openjpa-project/src/doc/manual/ref_guide_pc.xml +++ b/openjpa-project/src/doc/manual/ref_guide_pc.xml @@ -114,7 +114,7 @@ any unlisted class is not persistent. In order to provide optimal runtime performance, flexible lazy loading, and -efficient, immediate dirty tracking, OpenJPA uses an enhancer +efficient, immediate dirty tracking, OpenJPA can use an enhancer . 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 getId method in your source file. The diagram above illustrates the compilation of a persistent class. -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. @@ -269,14 +269,14 @@ class load error, simply re-compile and re-enhance the offending classes. -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. -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. @@ -325,7 +325,7 @@ java -javaagent:/home/dev/openjpa/lib/openjpa.jar com.xyz.Main You can pass settings to the agent using OpenJPA's plugin syntax (see ). The agent accepts the long -form of any of the standard configuration options +form of any of the standard configuration options ( ). 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 @@ check whether each class loaded into the JVM is persistent, and enhance it accordingly. This may slow down class load times significantly. + + +runtimeEnhancement: Boolean controlling whether OpenJPA +class enhancement should be available in this JVM execution. Default: +true + + + + +runtimeRedefinition: Boolean controlling whether OpenJPA +class redefinition should be available in this JVM execution. Default: +true + + @@ -361,38 +375,107 @@ java -javaagent:/home/dev/openjpa/lib/openjpa.jar=addDefaultConstructor=false co </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 - + enhancer - serialization + omitting - of enhanced types + outside a container - - - serialization - - - of enhanced types - - -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 -for details. - +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. + + + +Deploy-time enhancement: 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. + + +Java 6 class retransformation: if you are running your +application in a Java 6 environment, OpenJPA will attempt to dynamically +register a ClassTransformer 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 instanceof operator +will work as expected, but o.getClass() will return the +subclass instead of the class that you wrote. + + +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. + + +Java 5 class redefinition: 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 runtimeEnhancement javaagent flag to +false, or on any classes that are skipped by the OpenJPA +runtime enhancement process for some reason. + + +state comparison and subclassing: 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. + + +If you are using property access 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. + + +If you are using field access 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. + +
diff --git a/openjpa-project/src/doc/manual/samples_guide.xml b/openjpa-project/src/doc/manual/samples_guide.xml index 4b0247be4..71df6b867 100644 --- a/openjpa-project/src/doc/manual/samples_guide.xml +++ b/openjpa-project/src/doc/manual/samples_guide.xml @@ -102,7 +102,7 @@ Compile the classes: You should then proceed to pass in the configuration file you are using to the -enhancer: +enhancer: (Optional) java org.apache.openjpa.enhance.PCEnhancer -p persistence.xml Machine.java Crane.java Bulldozer.java