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/10/03 00:22:21 UTC
svn commit: r452243 [6/6] - in /incubator/openjpa/trunk:
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/
openjpa-kernel/src/main/java/org/apache/openjpa/kernel/
openjpa-kernel/src/ma...
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml Mon Oct 2 15:22:18 2006
@@ -3,8 +3,8 @@
Metadata
</title>
<para>
-The JPA Overview covers JPA metadata in <xref linkend="jpa_overview_meta"/>
-. This chapter discusses OpenJPA's extensions to standard JPA metadata.
+The JPA Overview covers JPA metadata in <xref linkend="jpa_overview_meta"/>.
+This chapter discusses OpenJPA's extensions to standard JPA metadata.
</para>
<section id="ref_guide_meta_factory">
<title>
@@ -24,14 +24,14 @@
<para>
The <link linkend="openjpa.MetaDataFactory"><literal>openjpa.MetaDataFactory
</literal></link> configuration property controls metadata loading and storing.
-This property takes a plugin string (see <xref linkend="ref_guide_conf_plugins"/>
-) describing a concrete
+This property takes a plugin string (see
+<xref linkend="ref_guide_conf_plugins"/>) describing a concrete
<ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html">
<classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink>
implementation. A metadata factory can load mapping information as well as
persistence metadata, or it can leave mapping information to a separate
<emphasis>mapping factory</emphasis> (see
-<xref linkend="ref_guide_mapping_factory"/> ). OpenJPA recognizes the
+<xref linkend="ref_guide_mapping_factory"/>). OpenJPA recognizes the
following built-in metadata factories:
</para>
<itemizedlist>
@@ -39,17 +39,20 @@
<para>
<literal>jpa</literal>: Standard JPA metadata. This is an alias for the
<ulink url="../apidocs/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html">
-<classname> org.apache.openjpa.persistence.PersistenceMetaDataFactory
-</classname></ulink>.
+<classname>
+org.apache.openjpa.persistence.PersistenceMetaDataFactory</classname></ulink>.
</para>
</listitem>
</itemizedlist>
<para>
-The standard metadata factories all accept the following properties for locating
-persistent classes. Each property represents a different mechanism for locating
-persistent types; you can choose the mechanism or combination of mechanisms that
-are most convenient. See <xref linkend="ref_guide_pc_pcclasses"/> for a
-discussion of when it is necessary to list your persistent classes.
+JPA has built-in settings for listing your persistent classes, which
+the <link linkend="jpa_overview_persistence_xml">JPA Overview</link> describes.
+OpenJPA supports these JPA standard settings by translating them into its own
+internal metadata factory properties. Each internal property represents a
+different mechanism for locating persistent types; you can choose the mechanism
+or combination of mechanisms that are most convenient. See
+<xref linkend="ref_guide_pc_pcclasses"/> for a discussion of when it is
+necessary to list your persistent classes.
</para>
<itemizedlist>
<listitem>
@@ -61,22 +64,22 @@
<listitem>
<para>
<literal>Resources</literal>: A semicolon-separated list of resource paths to
-metadata files or jar archives. Each jar archive will be scanned for <phrase>
-annotated JPA entities</phrase>.
+metadata files or jar archives. Each jar archive will be scanned for
+annotated JPA entities.
</para>
</listitem>
<listitem>
<para>
<literal>URLs</literal>: A semicolon-separated list of URLs of metadata files
-or jar archives. Each jar archive will be scanned for <phrase>annotated JPA
-entities</phrase>.
+or jar archives. Each jar archive will be scanned for annotated JPA
+entities.
</para>
</listitem>
<listitem>
<para>
<literal>ClasspathScan</literal>: A semicolon-separated list of directories or
jar archives listed in your classpath. Each directory and jar archive will be
-scanned for <phrase>annotated JPA entities</phrase>.
+scanned for annotated JPA entities.
</para>
</listitem>
</itemizedlist>
@@ -85,7 +88,7 @@
Setting a Standard Metadata Factory
</title>
<programlisting>
-<property name="openjpa.MetaDataFactory" value="jpa"/>
+<property name="openjpa.MetaDataFactory" value="jpa(ClasspathScan=build;lib.jar)"/>
</programlisting>
</example>
<example id="ref_guide_meta_customfactoryex">
@@ -227,160 +230,6 @@
to denote a persistent <classname>java.awt.Point</classname> field.
</para>
</section>
- <section id="ref_guide_meta_jpa_persistent_coll">
- <title>
- Persistent Collection Fields
- </title>
- <indexterm zone="ref_guide_meta_jpa_persistent_coll">
- <primary>
- persistent fields
- </primary>
- <secondary>
- collection metadata
- </secondary>
- </indexterm>
- <para>
-JPA standardizes support for collections of entities with the <literal>
-OneToMany</literal> and <literal>ManyToMany</literal> persistence strategies.
-OpenJPA expands collection support to handle collections of simple types
-(primitive wrappers, <classname>String</classname> s, etc), custom types, and
-embedded objects.
- </para>
- <para>
-The
-<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentCollection.html">
-<classname>org.apache.openjpa.persistence.PersistentCollection</classname>
-</ulink> metadata annotation represents a persistent collection field. It has
-the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<literal>Class elementType</literal>: The class of the collection elements.
-This information is usually taken from the parameterized collection element
-type. You must supply it explicitly, however, if your field isn't a
-parameterized type.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>FetchType fetch</literal>: Whether to load the collection eagerly or
-lazily. Corresponds exactly to the same-named property of standard JPA
-annotations such as <link linkend="jpa_overview_meta_basic"><classname> Basic
-</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>String mappedBy</literal>: Names the field in the related entity that
-maps this bidirectional relation. Corresponds to the same-named property of
-standard JPA annotations such as <link linkend="jpa_overview_meta_manytomany">
-<classname> ManyToMany</classname></link>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>CascadeType[] elementCascade</literal>: Array of enum values defining
-cascade behavior for the collection elements. Corresponds exactly to the
-<literal>cascade</literal> property of standard JPA annotations such as
-<link linkend="jpa_overview_meta_manytomany"><classname>ManyToMany</classname>
-</link>. Defaults to empty array.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>boolean elementEmbedded</literal>: Set this property to <literal>true
-</literal> if the elements are stored as embedded objects.
- </para>
- </listitem>
- </itemizedlist>
- <para>
-<xref linkend="ref_guide_mapping_jpa_coll"/> contains several examples of
-using <classname>PersistentCollection</classname> to mark non-standard
-collection fields persistent.
- </para>
- </section>
- <section id="ref_guide_meta_jpa_persistent_map">
- <title>
- Persistent Map Fields
- </title>
- <indexterm zone="ref_guide_meta_jpa_persistent_map">
- <primary>
- persistent fields
- </primary>
- <secondary>
- map metadata
- </secondary>
- </indexterm>
- <para>
-JPA has limited support for maps. OpenJPA introduces the
-<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentMap.html">
-<classname>org.apache.openjpa.persistence.PersistentMap</classname></ulink>
-metadata annotation to represent a persistent map field. It has the following
-properties:
- </para>
- <itemizedlist>
- <listitem>
- <para>
-<literal>Class keyType</literal>: The class of the map keys. This information
-is usually taken from the parameterized map key type. You must supply it
-explicitly, however, if your field isn't a parameterized type.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>Class elementType</literal>: The class of the map values. This
-information is usually taken from the parameterized map value type. You must
-supply it explicitly, however, if your field isn't a parameterized type.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>FetchType fetch</literal>: Whether to load the collection eagerly or
-lazily. Corresponds exactly to the same-named property of standard JPA
-annotations such as <link linkend="jpa_overview_meta_basic"><classname> Basic
-</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>CascadeType[] keyCascade</literal>: Array of enum values defining
-cascade behavior for the map keys. Corresponds exactly to the <literal>cascade
-</literal> property of standard JPA annotations such as
-<link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname>
-</link>. Defaults to empty array.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>CascadeType[] elementCascade</literal>: Array of enum values defining
-cascade behavior for the map values. Corresponds exactly to the <literal>
-cascade</literal> property of standard JPA annotations such as
-<link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname>
-</link>. Defaults to empty array.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>boolean keyEmbedded</literal>: Set this property to <literal>true
-</literal> if the map keys are stored as embedded objects.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>boolean elementEmbedded</literal>: Set this property to <literal>true
-</literal> if the map values are stored as embedded objects.
- </para>
- </listitem>
- </itemizedlist>
- <para>
-Map keys and values in OpenJPA can be entities, simple types (primitive
-wrappers, <classname>String</classname> s, etc), custom types, or embedded
-objects. <xref linkend="ref_guide_mapping_jpa_map"/> contains several
-examples of using <classname>PersistentMap</classname> to annotate persistent
-map fields.
- </para>
- </section>
</section>
<section id="ref_guide_meta_ext">
<title>
@@ -477,15 +326,6 @@
</listitem>
<listitem>
<para>
-<literal>String name</literal>: Place data for instances of the class in a
-named cache. By default, instance data is placed in the same cache as superclass
-data, or the default cache configured through the
-<link linkend="openjpa.DataCache"><literal> openjpa.DataCache</literal></link>
-configuration property for base classes.
- </para>
- </listitem>
- <listitem>
- <para>
<literal>int timeout</literal>: The number of milliseconds data for the class
remains valid. Use -1 for no timeout. Defaults to the
<link linkend="openjpa.DataCacheTimeout"><literal> openjpa.DataCacheTimeout
@@ -669,74 +509,14 @@
</seealso>
</indexterm>
<para>
-This boolean extension, denoted by <phrase> the JPA
+This boolean extension, denoted by the OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname>
-org.apache.openjpa.persistence.LRS</classname></ulink> annotation,</phrase>
+org.apache.openjpa.persistence.LRS</classname></ulink> annotation,
indicates that a field should use OpenJPA's special large result set collection
or map proxies. A complete description of large result set proxies is available
in <xref linkend="ref_guide_pc_scos_proxy_lrs"/>.
</para>
</section>
- <section id="order-by">
- <title>
- Order-By
- </title>
- <indexterm zone="order-by">
- <primary>
- metadata
- </primary>
- <secondary>
- extensions
- </secondary>
- <tertiary>
- order-by
- </tertiary>
- </indexterm>
- <para>
-<phrase> The JPA Overview's <xref linkend="jpa_overview_meta_orderby"/>
-describes JPA's <literal>OrderBy</literal> annotation for loading the elements
-of collection fields in a prescribed order.</phrase> Ordering syntax is as
-follows:
- </para>
-<programlisting>
-#element|<field name>[ asc|ascending|desc|descending][, ...]
-</programlisting>
- <para>
-The token <literal>#element</literal> represents the element value. Simple
-element types such as strings and primitive wrappers are sorted based on their
-natural ordering. If the collection holds persistent objects, its elements are
-sorted based on the natural ordering of the objects' primary key values. By
-substituting a field name for the <literal> #element</literal> token, you can
-order a collection of persistent objects by an arbitrary field in the related
-type, rather than by primary key.
- </para>
- <para>
-The field name or <literal>#element</literal> token may be followed by the
-keywords <literal>asc/ascending</literal> or <literal>desc/descending</literal>
-in either all-upper or all-lower case to mandate ascending and descending order.
-If the direction is omitted, OpenJPA defaults to ascending order.
- </para>
- <para>
-Note that the defined ordering is only applied when the collection is loaded
-from the datastore. It is not maintained by OpenJPA as you modify the collection
-in memory.
- </para>
- <para>
-The following ordering string orders a collection by its element values in
-descending order:
- </para>
-<programlisting>
-"#element desc"
-</programlisting>
- <para>
-The following ordering string orders a collection of <classname>Author
-</classname> objects by each author's last name in ascending order. If two last
-names are equal, the authors are ordered by first name in ascending order.
- </para>
-<programlisting>
-"firstName, lastName"
-</programlisting>
- </section>
<section id="inverse-logical">
<title>
Inverse-Logical
@@ -757,10 +537,10 @@
</indexterm>
<para>
This extension names the inverse field in a logical bidirectional relation.
-<phrase> To create a logical bidrectional relation in OpenJPA, use the
+To create a logical bidrectional relation in OpenJPA, use the
<ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html">
<classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink>
-annotation.</phrase> We discuss logical bidirectional relations and this
+annotation. We discuss logical bidirectional relations and this
extension in detail in <xref linkend="ref_guide_inverses"/>.
</para>
</section>
@@ -798,7 +578,7 @@
To mark a field read-only in JPA metadata, set the
<ulink url="../apidocs/org/apache/openjpa/persistence/ReadOnly.html">
<classname>org.apache.openjpa.persistence.ReadOnly</classname></ulink>
-annotation to a
+annotation to an
<ulink url="../apidocs/org/apache/openjpa/persistence/UpdateAction.html">
<classname>org.apache.openjpa.persistence.UpdateAction</classname></ulink> enum
value. The <classname>UpdateAction</classname> enum includes:
@@ -876,7 +656,7 @@
<para>
With OpenJPA's type family of metadata extensions, you can control the level of
support given to your unknown/interface-typed fields. Setting the value of this
-extension to <phrase><classname>Entity</classname></phrase> indicates that the
+extension to <classname>Entity</classname> indicates that the
field value will always be some persistent object, and gives level 2 support.
Setting the value of this extension to the class of a concrete persistent type
is even better; it gives you level 1 support (just as if you had declared your
@@ -934,10 +714,10 @@
</seealso>
</indexterm>
<para>
-The <phrase> JPA
+The OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html">
<classname>org.apache.openjpa.persistence.Externalizer</classname></ulink>
-annotation</phrase> names a method to transform a field value into a value of
+annotation names a method to transform a field value into a value of
another type. See <xref linkend="ref_guide_pc_extern"/> for details.
</para>
</section>
@@ -960,9 +740,9 @@
</seealso>
</indexterm>
<para>
-The <phrase> JPA
+The OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>
-org.apache.openjpa.persistence.Factory</classname></ulink> annotation</phrase>
+org.apache.openjpa.persistence.Factory</classname></ulink> annotation
names a method to re-create a field value from its externalized form. See
<xref linkend="ref_guide_pc_extern"/> for details.
</para>
@@ -986,10 +766,10 @@
</seealso>
</indexterm>
<para>
-The <phrase> JPA
+The OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html">
<classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
-annotation</phrase> declares values for transformation of simple fields to
+annotation declares values for transformation of simple fields to
different constant values in the datastore. See
<xref linkend="ref_guide_pc_extern_values"/> for details.
</para>
@@ -1020,10 +800,6 @@
@ExternalValues({"true=1", "false=2"})
@Type(int.class)
private boolean weekly;
-
- @PersistentCollection
- @OrderBy("#element DESC")
- private List<String> subtitles;
...
}
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml Mon Oct 2 15:22:18 2006
@@ -186,12 +186,10 @@
flushes during your transaction to reduce its memory
requirements. See the Javadoc:
- <phrase>
- <ulink url="javadoc/openjpa/persistence/OpenJPAEntityManager.html">
+ <ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
OpenJPAEntityManager.setLargeTransaction
- </ulink>
- </phrase>
+ </ulink>
@@ -203,9 +201,9 @@
accessed by other transactions, for example an exhaustive report run only once a
month, you can turn off population of the data cache so that the transaction
doesn't fill the entire data cache with objects that won't be accessed again.
-Again, see the Javadoc: <phrase>
-<ulink url="javadoc/openjpa/persistence/OpenJPAEntityManager.html">
-OpenJPAEntityManager.setPopulateDataCache</ulink></phrase>
+Again, see the Javadoc:
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
+OpenJPAEntityManager.setPopulateDataCache</ulink>
</para>
</entry>
</row>
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?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- 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 Mon Oct 2 15:22:18 2006
@@ -57,14 +57,14 @@
<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
+<xref linkend="ref_guide_mapping_synch"/>), OpenJPA must know all of your
persistent classes up-front.
</para>
</listitem>
</itemizedlist>
<para>
When any of these conditions are a factor in your JPA application, use the
-<literal>class</literal>, <literal> mapping-file</literal>, and <literal>
+<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>
@@ -101,20 +101,19 @@
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
+compatible with Java debuggers. 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>
+the <methodname>getId</methodname> method in your source file.
</para>
<mediaobject>
<imageobject>
<!-- PNG image data, 509 x 133 (see README) -->
<imagedata fileref="img/enhancement.png" width="339px"/>
-
</imageobject>
</mediaobject>
<para>
@@ -139,13 +138,13 @@
</indexterm>
<para>
The enhancer can be invoked at build time
-via the Java tool,
-<classname>org.apache.openjpa.enhance.PCEnhancer</classname>.
+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"/>
-.
+You can also enhance via Ant; see
+<xref linkend="ref_guide_integration_enhance"/>.
</para>
</note>
<example id="ref_guide_pc_enhance_enhancer">
@@ -182,8 +181,8 @@
<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>.
+persistent classes that don't already have one. Defaults to <literal>
+true</literal>.
</para>
</listitem>
<listitem>
@@ -218,8 +217,7 @@
</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"/>
- ).
+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
@@ -286,38 +284,30 @@
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
+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.
+-javaagent</literal> set to the path to your OpenJPA jar 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
+java -javaagent:/home/dev/openjpa/lib/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
+<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"/>:
@@ -330,11 +320,6 @@
</listitem>
<listitem>
<para>
-<literal>jdoEnhance</literal>
- </para>
- </listitem>
- <listitem>
- <para>
<literal>enforcePropertyRestrictions</literal>
</para>
</listitem>
@@ -353,7 +338,7 @@
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
+java -javaagent:/home/dev/openjpa/lib/openjpa.jar=addDefaultConstructor=false com.xyz.Main
</programlisting>
</example>
</section>
@@ -420,7 +405,7 @@
</para>
<para>
To retrieve the identity value of a datastore identity entity, use the
-<methodname>OpenJPAEntityManager.getObjectId (Object entity)</methodname>
+<methodname>OpenJPAEntityManager.getObjectId(Object entity)</methodname>
method. See <xref linkend="ref_guide_runtime_em"/> for more information on
the <classname>OpenJPAEntityManager</classname>.
</para>
@@ -433,8 +418,8 @@
@Entity
@DataStoreId
-public class LineItem
-{
+public class LineItem {
+
... no @Id fields declared ...
}
</programlisting>
@@ -491,7 +476,7 @@
</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
+OpenJPA'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,
@@ -513,7 +498,7 @@
class code, you can set the <literal>@IdClass</literal> annotation.
</para>
<para>
-The application identity tool can be invoked via the Java class,
+The application identity tool can be invoked via its Java class,
<ulink url="../apidocs/org/apache/openjpa/enhance/ApplicationIdTool">
<classname>org.apache.openjpa.enhance.ApplicationIdTool</classname></ulink>.
</para>
@@ -534,7 +519,7 @@
<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
+<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>
@@ -605,8 +590,7 @@
</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"/>
-).
+your persistent classes list (see <xref linkend="ref_guide_pc_pcclasses"/>).
</para>
</section>
<section id="ref_guide_pc_oid_pkgen_autoinc">
@@ -666,14 +650,6 @@
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>
@@ -696,11 +672,10 @@
relations that also share datastore storage in JPA.
</para>
<para>
-OpenJPA also allows you to define purely logical bidirectional relations.
-<phrase> The
+OpenJPA also allows you to define purely logical bidirectional relations. 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>
+annotation names a logical inverse in JPA metadata.
</para>
<example id="ref_guide_inverses_logicalex">
<title>
@@ -717,8 +692,8 @@
import org.apache.openjpa.persistence.*;
@Entity
-public class Magazine
-{
+public class Magazine {
+
@OneToOne
private Photograph coverPhoto;
@@ -726,8 +701,8 @@
}
@Entity
-public class Photograph
-{
+public class Photograph {
+
@OneToOne
@InverseLogical("coverPhoto")
private Magazine mag;
@@ -735,18 +710,6 @@
...
}
</programlisting>
-<programlisting>
-<class name="Magazine">
- <field name="coverPhoto"/>
- ...
-</class>
-<class name="Photograph">
- <field name="mag">
- <extension vendor-name="openjpa" key="inverse-logical" value="coverPhoto"/>
- </field>
- ...
-</class>
-</programlisting>
</example>
<para>
Java does not provide any native facilities to ensure that both sides of a
@@ -878,19 +841,18 @@
fields in the class below.
</para>
<programlisting>
-public class Company
-{
+public class Company {
+
// OpenJPA will detect the custom comparator in the initial field value
// and use it whenever loading data from the database into this field
- private Collection employeesBySal = new TreeSet (new SalaryComparator ());
+ private Collection employeesBySal = new TreeSet(new SalaryComparator());
private Map departments;
- public Company
- {
+ public Company {
// or we can initialize fields in our no-args constructor; even though
- // this field is declared type Map, OpenJPA will detect that it's actually
- // a TreeMap and use natural ordering for loaded data
- departments = new TreeMap ();
+ // this field is declared type Map, OpenJPA will detect that it's
+ // actually a TreeMap and use natural ordering for loaded data
+ departments = new TreeMap();
}
// rest of class definition...
@@ -978,7 +940,7 @@
</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
+</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.
@@ -1019,7 +981,7 @@
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
+<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.
@@ -1038,11 +1000,11 @@
...
-Collection employees = company.getEmployees (); // employees is a lrs collection
-Iterator itr = employees.iterator ();
-while (itr.hasNext ())
- process ((Employee) itr.next ());
-OpenJPAPersistence.close (itr);
+Collection employees = company.getEmployees(); // employees is a lrs collection
+Iterator itr = employees.iterator();
+while (itr.hasNext())
+ process((Employee) itr.next());
+OpenJPAPersistence.close(itr);
</programlisting>
</example>
<para>
@@ -1052,10 +1014,10 @@
collection and map methods, and to update the field's database record on commit.
</para>
<para>
-<phrase> In order to use large result set proxies in JPA, add the
+In order to use large result set proxies in JPA, add the
<ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname>
org.apache.openjpa.persistence.LRS</classname></ulink> annotation to the
-persistent field.</phrase>
+persistent field.
</para>
<para>
The following restrictions apply to large result set fields:
@@ -1071,8 +1033,8 @@
</listitem>
<listitem>
<para>
-The field cannot have an externalizer (see <xref linkend="ref_guide_pc_extern"/>
- ).
+The field cannot have an externalizer (see
+<xref linkend="ref_guide_pc_extern"/>).
</para>
</listitem>
<listitem>
@@ -1082,9 +1044,9 @@
would result in an error on commit:
</para>
<programlisting>
-Collection employees = company.getEmployees () // employees is a lrs collection
-company.setEmployees (null);
-anotherCompany.setEmployees (employees);
+Collection employees = company.getEmployees() // employees is a lrs collection
+company.setEmployees(null);
+anotherCompany.setEmployees(employees);
</programlisting>
</listitem>
</itemizedlist>
@@ -1096,8 +1058,8 @@
import org.apache.openjpa.persistence.*;
@Entity
-public class Company
-{
+public class Company {
+
@ManyToMany
@LRS private Collection<Employee> employees;
@@ -1132,7 +1094,7 @@
org.apache.openjpa.util.ProxyManager</classname></ulink> interface. OpenJPA
includes a default proxy manager, the <classname>
org.apache.openjpa.util.ProxyManagerImpl</classname> (with a plugin alias name
-of <literal>default</literal> ), that will meet the needs of most users. The
+of <literal>default</literal>), that will meet the needs of most users. The
default proxy manager understands the following configuration properties:
</para>
<itemizedlist>
@@ -1203,10 +1165,10 @@
</para>
</note>
<para>
-The <phrase> JPA
+The OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html">
<classname>org.apache.openjpa.persistence.Externalizer</classname></ulink>
-annotation</phrase> sets the name of a method that will be invoked to convert
+annotation sets the name of a method that will be invoked to convert
the field into its external form for database storage. You can specify either
the name of a non-static method, which will be invoked on the field value, or a
static method, which will be invoked with the field value as a parameter. Each
@@ -1235,10 +1197,10 @@
<thead>
<row>
<entry colname="method">
- Method
+Method
</entry>
<entry colname="extension">
- Extension
+Extension
</entry>
</row>
</thead>
@@ -1246,64 +1208,48 @@
<row>
<entry colname="method">
<literal>
-
- public String CustomType.toString()
-
+public String CustomType.toString()
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Externalizer("toString")
-
+@Externalizer("toString")
</literal>
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public String CustomType.toString(StoreContext ctx)
-
+public String CustomType.toString(StoreContext ctx)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Externalizer("toString")
-
+@Externalizer("toString")
</literal>
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public static String AnyClass.toString(CustomType ct)
-
+public static String AnyClass.toString(CustomType ct)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Externalizer("AnyClass.toString")
-
+@Externalizer("AnyClass.toString")
</literal>
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public static String AnyClass.toString(CustomType ct, StoreContext ctx)
-
+public static String AnyClass.toString(CustomType ct, StoreContext ctx)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Externalizer("AnyClass.toString")
-
+@Externalizer("AnyClass.toString")
</literal>
</entry>
</row>
@@ -1311,9 +1257,9 @@
</tgroup>
</table>
<para>
-The <phrase> JPA
+The OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>
-org.apache.openjpa.persistence.Factory</classname></ulink> annotation</phrase>
+org.apache.openjpa.persistence.Factory</classname></ulink> annotation
contains the name of a method that will be invoked to instantiate the field from
the external form stored in the database. Specify a static method name. The
method will will be invoked with the externalized value and must return an
@@ -1335,16 +1281,14 @@
</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="method"/>
-
<colspec colname="extension"/>
-
<thead>
<row>
<entry colname="method">
- Method
+Method
</entry>
<entry colname="extension">
- Extension
+Extension
</entry>
</row>
</thead>
@@ -1352,78 +1296,58 @@
<row>
<entry colname="method">
<literal>
-
- public CustomType(String str)
-
+public CustomType(String str)
</literal>
</entry>
<entry colname="extension">
-
- none
-
+none
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public static CustomType CustomType.fromString(String str)
-
+public static CustomType CustomType.fromString(String str)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Factory("fromString")
-
+@Factory("fromString")
</literal>
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public static CustomType CustomType.fromString(String str, StoreContext ctx)
-
+public static CustomType CustomType.fromString(String str, StoreContext ctx)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Factory("fromString")
-
+@Factory("fromString")
</literal>
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public static CustomType AnyClass.fromString(String str)
-
+public static CustomType AnyClass.fromString(String str)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Factory("AnyClass.fromString")
-
+@Factory("AnyClass.fromString")
</literal>
</entry>
</row>
<row>
<entry colname="method">
<literal>
-
- public static CustomType AnyClass.fromString(String str, StoreContext ctx)
-
+public static CustomType AnyClass.fromString(String str, StoreContext ctx)
</literal>
</entry>
<entry colname="extension">
<literal>
-
- @Factory("AnyClass.fromString")
-
+@Factory("AnyClass.fromString")
</literal>
</entry>
</row>
@@ -1432,24 +1356,19 @@
</table>
<para>
If your externalized field is not a standard persistent type, you must
-explicitly mark it persistent. <phrase> In JPA, you can force a persistent field
+explicitly mark it persistent. In OpenJPA, you can force a persistent field
by annotating it with <link linkend="ref_guide_meta_jpa_persistent"><classname>
org.apache.openjpa.persistence.Persistent</classname></link> annotation.
-</phrase>
</para>
<note>
<para>
If your custom field type is mutable and is not a standard collection, map, or
date class, OpenJPA will not be able to detect changes to the field. You must
-mark the field dirty manully, or create a custom field proxy.
- </para>
- <para>
-<phrase> See
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+mark the field dirty manually, or create a custom field proxy.
+See
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<methodname>OpenJPAEntityManager.dirty</methodname></ulink> for how to mark a
-field dirty manually in JPA.</phrase>
- </para>
- <para>
+field dirty manually in JPA.
See <xref linkend="ref_guide_pc_scos_proxy"/> for a discussion of proxies.
</para>
</note>
@@ -1458,13 +1377,13 @@
OpenJPA's field mappings (embedded relations are the exception; you must declare
your field to be a persistence-capable type in order to embed it). This means
that a field can externalize to something as simple as a primitive, something as
-complex as a collection or map of persistence-capable objects, or anything in
+complex as a collection or map of entities, or anything in
between. If you do choose to externalize to a collection or map, OpenJPA
recognizes a family of metadata extensions for specying type information for the
externalized form of your fields - see <xref linkend="type"/>. If the
-external form of your field is a persistence-capable object, or contains
-persistence-capable objects, OpenJPA will correctly include the objects in its
-persistence-by-reachability algorithms and its delete-dependent algorithms.
+external form of your field is an entity object or contains entities, OpenJPA
+will correctly include the objects in its persistence-by-reachability
+algorithms and its delete-dependent algorithms.
</para>
<para>
The example below demonstrates a few forms of externalization.
@@ -1477,8 +1396,8 @@
import org.apache.openjpa.persistence.*;
@Entity
-public class Magazine
-{
+public class Magazine {
+
// use Class.getName and Class.forName to go to/from strings
@Persistent
@Externalizer("getName")
@@ -1491,22 +1410,19 @@
@Externalizer("toExternalForm")
private URL url;
- // use our custom methods; notice how we use the KeyType and ElementType
- // annotations to specify the metadata for our externalized map
+ // use our custom methods
@Persistent
- @Externalizer("Magazine.mapFromCustomType")
- @Factory("Magazine.mapToCustomType")
- @KeyType(String.class) @ElementType(String.class)
+ @Externalizer("Magazine.authorsFromCustomType")
+ @Factory("Magazine.authorsToCustomType")
+ @ElementType(Author.class)
private CustomType customType;
- public static Map mapFromCustomType (CustomType customType)
- {
- ... logic to pack custom type into a map ...
+ public static Collection authorsFromCustomType(CustomType customType) {
+ ... logic to pack custom type into a list of authors ...
}
- public static CustomType mapToCustomType (Map map)
- {
- ... logic to create custom type from a map ...
+ public static CustomType authorsToCustomType (Collection authors) {
+ ... logic to create custom type from a collection of authors ...
}
...
@@ -1545,13 +1461,13 @@
</para>
<programlisting>
// you can query using parameters
-Query q = em.createQuery ("select m from Magazine m where m.url = :u");
-q.setParameter ("u", new URL ("http://www.solarmetric.com"));
-List results = q.getResultList ();
+Query q = em.createQuery("select m from Magazine m where m.url = :u");
+q.setParameter("u", new URL("http://www.solarmetric.com"));
+List results = q.getResultList();
// or as a shortcut, you can use the externalized form directly
-q = em.createQuery ("select m from Magazine m where m.url = 'http://www.solarmetric.com'");
-results = q.getResultList ();
+q = em.createQuery("select m from Magazine m where m.url = 'http://www.solarmetric.com'");
+results = q.getResultList();
</programlisting>
</example>
<section id="ref_guide_pc_extern_values">
@@ -1581,10 +1497,10 @@
primitive wrappers, and Strings), to other pre-defined simple values.
</para>
<para>
-Use the <phrase> JPA
+Use the OpenJPA
<ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html">
<classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
-annotation</phrase> to define external value translations. The values are
+annotation to define external value translations. The values are
defined in a format similar to that of <link linkend="ref_guide_conf_plugins">
configuration plugins</link>, except that the value pairs represent Java and
datastore values. To convert the Java boolean values of <literal>true</literal>
@@ -1594,9 +1510,9 @@
</para>
<para>
If the type of the datastore value is different from the field's type, use the
-<phrase> JPA <ulink url="../apidocs/org/apache/openjpa/persistence/Type.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/Type.html">
<classname>org.apache.openjpa.persistence.Type</classname></ulink> annotation
-</phrase> to define the datastore type.
+to define the datastore type.
</para>
<example id="externvalues_ex">
<title>
@@ -1607,8 +1523,8 @@
integer in the database.
</para>
<programlisting>
-public class Magazine
-{
+public class Magazine {
+
@ExternalValues({"SMALL=5", "MEDIUM=8", "LARGE=10"})
@Type(int.class)
private String sizeWidth;
@@ -1746,8 +1662,7 @@
}),
...
})
-public class Magazine
-{
+public class Magazine {
...
}
</programlisting>
@@ -1787,8 +1702,8 @@
}),
...
})
-public class Magazine
-{
+public class Magazine {
+
@ManyToOne(fetch=FetchType.LAZY)
@LoadFetchGroup("detail")
private Publisher publisher;
@@ -1844,25 +1759,25 @@
OpenJPA's <classname>OpenJPAEntityManager</classname> and <classname>
OpenJPAQuery</classname> extensions to the standard <classname>EntityManager
</classname> and <classname>Query</classname> interfaces provide access to a
-<ulink url="../../api/openjpa/persistence/FetchPlan.html"><classname>
-org.apache.openjpa.persistence.FetchPlan</classname></ulink> object. The
-<classname>FetchPlan</classname> maintains the set of active fetch groups and
-the maximum fetch depth. It begins with the groups and depth defined in the
+<ulink url="../apidocs/org/apache/openjpa/persistence/FetchPlan.html">
+<classname>org.apache.openjpa.persistence.FetchPlan</classname></ulink> object.
+The <classname>FetchPlan</classname> maintains the set of active fetch groups
+and the maximum fetch depth. It begins with the groups and depth defined in the
<literal>openjpa.FetchGroups</literal> and <literal>openjpa.MaxFetchDepth
</literal> properties, but allows you to add or remove groups and change the
maximum fetch depth for an individual <classname>EntityManager</classname> or
<classname>Query</classname> through the methods below.
</para>
<programlisting>
-public FetchPlan addFetchGroup (String group);
-public FetchPlan addFetchGroups (String... groups);
-public FetchPlan addFetchGroups (Collection groups);
-public FetchPlan removeFetchGroup (String group);
-public FetchPlan removeFetchGroups (String... groups);
-public FetchPlan removeFetchGroups (Collection groups);
-public FetchPlan resetFetchGroups ();
-public Collection<String> getFetchGroups ();
-public void clearFetchGroups ();
+public FetchPlan addFetchGroup(String group);
+public FetchPlan addFetchGroups(String... groups);
+public FetchPlan addFetchGroups(Collection groups);
+public FetchPlan removeFetchGrop(String group);
+public FetchPlan removeFetchGroups(String... groups);
+public FetchPlan removeFetchGroups(Collection groups);
+public FetchPlan resetFetchGroups();
+public Collection<String> getFetchGroups();
+public void clearFetchGroups();
public FetchPlan setMaxFetchDepth(int depth);
public int getMaxFetchDepth();
</programlisting>
@@ -1880,9 +1795,9 @@
...
-OpenJPAQuery kq = OpenJPAPersistence.cast (em.createQuery (...));
-kq.getFetchPlan ().setMaxFetchDepth(3).addFetchGroup ("detail");
-List results = kq.getResultList ();
+OpenJPAQuery kq = OpenJPAPersistence.cast(em.createQuery(...));
+kq.getFetchPlan().setMaxFetchDepth(3).addFetchGroup("detail");
+List results = kq.getResultList();
</programlisting>
</example>
</section>
@@ -1909,18 +1824,18 @@
JPA <classname>FetchPlan</classname> methods:
</para>
<programlisting>
-public FetchPlan addField (String field);
-public FetchPlan addFields (String... fields);
-public FetchPlan addFields (Class cls, String... fields);
-public FetchPlan addFields (Collection fields);
-public FetchPlan addFields (Class cls, Collection fields);
-public FetchPlan removeField (String field);
-public FetchPlan removeFields (String... fields);
-public FetchPlan removeFields (Class cls, String... fields);
-public FetchPlan removeFields (Collection fields);
-public FetchPlan removeFields (Class cls, Collection fields);
-public Collection<String> getFields ();
-public void clearFields ();
+public FetchPlan addField(String field);
+public FetchPlan addFields(String... fields);
+public FetchPlan addFields(Class cls, String... fields);
+public FetchPlan addFields(Collection fields);
+public FetchPlan addFields(Class cls, Collection fields);
+public FetchPlan removeField(String field);
+public FetchPlan removeFields(String... fields);
+public FetchPlan removeFields(Class cls, String... fields);
+public FetchPlan removeFields(Collection fields);
+public FetchPlan removeFields(Class cls, Collection fields);
+public Collection<String> getFields();
+public void clearFields();
</programlisting>
<para>
The methods that take only string arguments use the fully-qualified field name,
@@ -1952,9 +1867,9 @@
...
-OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
-kem.getFetchPlan ().addField (Magazine.class, "publisher");
-Magazine mag = em.find (Magazine.class, magId);
+OpenJPAEntityManager kem = OpenJPAPersistence.cast(em);
+kem.getFetchPlan().addField(Magazine.class, "publisher");
+Magazine mag = em.find(Magazine.class, magId);
</programlisting>
</example>
</section>
@@ -2100,13 +2015,12 @@
<para>
Under the <literal>join</literal> subclass fetch mode, subclass data in joined
tables is selected by outer joining to all possible subclass tables of the type
-being queried. Unjoined subclass data is selected with a SQL UNION where
-possible. As you'll see below, subclass data fetching is configured separately
-from relation fetching, and can be disabled for specific classes.
+being queried. As you'll see below, subclass data fetching is configured
+separately from relation fetching, and can be disabled for specific classes.
</para>
<note>
<para>
-Some databases may not support UNIONs or outer joins. Also, OpenJPA can not use
+Some databases may not support outer joins. Also, OpenJPA can not use
outer joins if you have set the <link linkend="openjpa.jdbc.DBDictionary">
<literal> DBDictionary</literal></link>'s <literal>JoinSyntax</literal> to
<literal>traditional</literal>. See <xref linkend="ref_guide_dbsetup_sql92"/>.
@@ -2155,16 +2069,8 @@
metadata extension described in <xref linkend="eager-fetch-mode"/>.
</para>
<para>
-Setting your subclass fetch mode to <literal>parallel</literal> affects
-table-per-class and vertical inheritance hierarchies. Under parallel mode,
-OpenJPA issues separate selects for each subclass in a table-per-class
-inheritance hierarchy, rather than UNIONing all subclass tables together as in
-join mode. This applies to any operation on a table-per-class base class: query,
-by-id lookup, or relation traversal.
- </para>
- <para>
-When dealing with a vertically-mapped hierarchy, on the other hand, parallel
-subclass fetch mode only applies to queries. Rather than outer-joining to
+Parallel subclass fetch mode only applies to queries on joined inheritance
+hierarchies. Rather than outer-joining to
subclass tables, OpenJPA will issue the query separately for each subclass. In
all other situations, parallel subclass fetch mode acts just like join mode in
regards to vertically-mapped subclasses.
@@ -2253,12 +2159,12 @@
...
-Query q = em.createQuery ("select p from Person p where p.address.state = 'TX'");
-OpenJPAQuery kq = OpenJPAPersistence.cast (q);
-JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan ();
-fetch.setEagerFetchMode (JDBCFetchPlan.EAGER_PARALLEL);
-fetch.setSubclassFetchMode (JDBCFetchPlan.EAGER_JOIN);
-List results = q.getResultList ();
+Query q = em.createQuery("select p from Person p where p.address.state = 'TX'");
+OpenJPAQuery kq = OpenJPAPersistence.cast(q);
+JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan();
+fetch.setEagerFetchMode(JDBCFetchPlan.EAGER_PARALLEL);
+fetch.setSubclassFetchMode(JDBCFetchPlan.EAGER_JOIN);
+List results = q.getResultList();
</programlisting>
</example>
<para>
@@ -2270,7 +2176,7 @@
</para>
<para>
This applies to the eager fetch mode metadata extension as well (see
-<xref linkend="eager-fetch-mode"/> ). You can use this extension to
+<xref linkend="eager-fetch-mode"/>). You can use this extension to
disable eager fetching on a field or to declare that a collection would rather
use joins than parallel selects or vice versa. But an extension value of
<literal>join</literal> won't cause any eager joining if the fetch
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml Mon Oct 2 15:22:18 2006
@@ -73,7 +73,7 @@
<link linkend="jpa_overview_emfactory_perscontext">persistence context</link>
ends. The specification does not define any way to explicitly detach objects.
The extended
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<classname>OpenJPAEntityManager</classname></ulink>, however, allows you to
explicitly detach objects at any time.
</para>
@@ -111,8 +111,8 @@
from flushing when detaching dirty objects; instead OpenJPA just runs its
pre-flush actions (see the <methodname>OpenJPAEntityManager.preFlush
</methodname>
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"> Javadoc
-</ulink> for details).
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
+Javadoc</ulink> for details).
</para>
<para>
This allows you to use the same instances in multiple
@@ -152,7 +152,7 @@
</listitem>
<listitem>
<para>
-If the instance has <phrase> a <literal>Version</literal> field,</phrase>
+If the instance has a <literal>Version</literal> field,
OpenJPA will consider the object detached if the version field has a non-default
value, and new otherwise.
</para>
@@ -322,7 +322,7 @@
<para>
You can also alter the set of fields that will be included in the detached graph
at runtime.
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<classname>OpenJPAEntityManager</classname></ulink>s expose the following APIs
for controlling detached state:
</para>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_runtime.xml Mon Oct 2 15:22:18 2006
@@ -3,7 +3,7 @@
Runtime Extensions
</title>
<para>
-This chapter describes OpenJPA extensions to the standard <phrase>JPA</phrase>
+This chapter describes OpenJPA extensions to the standard JPA
interfaces, and outlines some additional features of the OpenJPA runtime.
</para>
<section id="ref_guide_runtime_arch">
@@ -17,7 +17,7 @@
can adopt.
</para>
<para>
-As a OpenJPA <phrase>JPA</phrase> user, you will not normally see beneath
+As a OpenJPA user, you will not normally see beneath
OpenJPA's JPA personality. OpenJPA allows you to access its feature set without
leaving the comfort of JPA. Where OpenJPA goes beyond standard JPA
functionality, we have crafted JPA-specific APIs to each OpenJPA extension for
@@ -190,7 +190,7 @@
obtain managed and unmanaged <classname>EntityManager</classname>s from the
same factory, to access the OpenJPA data and query caches, and to perform other
OpenJPA-specific operations. See the
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html">
interface Javadoc</ulink> for details.
</para>
</section>
@@ -216,7 +216,7 @@
</indexterm>
<para>
All OpenJPA <classname>EntityManager</classname>s implement the
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<classname>org.apache.openjpa.persistence.OpenJPAEntityManager</classname>
</ulink> interface. This interface extends the standard <classname>
javax.persistence.EntityManager</classname>. Just as the standard <classname>
@@ -249,7 +249,7 @@
<para>
OpenJPA extends JPA's standard query functionality with the <classname>
org.apache.openjpa.persistence.OpenJPAQuery</classname> interface. See its
-<ulink url="../../api/openjpa/persistence/OpenJPAQuery.html">Javadoc</ulink> for
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAQuery.html">Javadoc</ulink> for
details on the convenience methods it provides.
</para>
</section>
@@ -276,7 +276,7 @@
<para>
An <classname>Extent</classname> is a logical view of all persistent instances
of a given entity class, possibly including subclasses. OpenJPA adds the
-<ulink url="../../api/openjpa/persistence/Extent.html"><classname>
+<ulink url="../apidocs/org/apache/openjpa/persistence/Extent.html"><classname>
org.apache.openjpa.persistence.Extent</classname></ulink> class to the set of
Java Persistence APIs. The following code illustrates iterating over all
instances of the <classname>Magazine</classname> entity, without subclasses:
@@ -310,8 +310,8 @@
In addition to the <classname>EntityManager</classname> object cache mandated by
the JPA specification, OpenJPA includes a flexible datastore-level cache. You
can access this cache from your JPA code using the
-<ulink url="../../api/openjpa/persistence/StoreCache.html"><classname>
-org.apache.openjpa.persistence.StoreCache</classname></ulink> facade.
+<ulink url="../apidocs/org/apache/openjpa/persistence/StoreCache.html">
+<classname>org.apache.openjpa.persistence.StoreCache</classname></ulink> facade.
<xref linkend="ref_guide_cache"/> has detailed information on OpenJPA's
data caching system, including the <classname>StoreCache</classname> facade.
</para>
@@ -327,9 +327,9 @@
</indexterm>
<para>
OpenJPA can cache query results as well as persistent object data. The
-<ulink url="../../api/openjpa/persistence/QueryResultCache.html"><classname>
-org.apache.openjpa.persistence.QueryResultCache</classname></ulink> is an
-JPA-flavored facade to OpenJPA's internal query cache. See
+<ulink url="../apidocs/org/apache/openjpa/persistence/QueryResultCache.html">
+<classname>org.apache.openjpa.persistence.QueryResultCache</classname></ulink>
+is an JPA-flavored facade to OpenJPA's internal query cache. See
<xref linkend="ref_guide_cache_query"/> for details on query caching in
OpenJPA.
</para>
@@ -361,10 +361,10 @@
</para>
<para>
OpenJPA goes one step further, extending <classname>FetchPlan</classname> with
-<ulink url="../../api/openjpa/persistence/jdbc/JDBCFetchPlan.html"><classname>
-org.apache.openjpa.persistence.jdbc.JDBCFetchPlan</classname></ulink> to add
-additional JDBC-specific tuning methods. Unless you have customized OpenJPA to
-use a non-relational back-end (see
+<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/JDBCFetchPlan.html">
+<classname>org.apache.openjpa.persistence.jdbc.JDBCFetchPlan</classname></ulink>
+to add additional JDBC-specific tuning methods. Unless you have customized
+OpenJPA to use a non-relational back-end (see
<xref linkend="ref_guide_enterprise_abstractstore"/> ), all <classname>
FetchPlan</classname>s in OpenJPA implement <classname>JDBCFetchPlan</classname>
, so feel free to cast to this interface.
@@ -397,10 +397,10 @@
</primary>
</indexterm>
<para>
-<ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"><classname>
-org.apache.openjpa.persistence.OpenJPAPersistence</classname></ulink> is a
-static helper class that adds OpenJPA-specific utility methods to <classname>
-javax.persistence.Persistence</classname>.
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAPersistence.html">
+<classname>org.apache.openjpa.persistence.OpenJPAPersistence</classname></ulink>
+is a static helper class that adds OpenJPA-specific utility methods to
+<classname>javax.persistence.Persistence</classname>.
</para>
</section>
</section>
@@ -586,7 +586,7 @@
<ulink url="http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html">
<methodname>EntityManager.lock (Object, LockModeType)</methodname></ulink>
method, the
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<classname>OpenJPAEntityManager</classname></ulink> exposes the following
methods to lock objects explicitly:
</para>
@@ -879,9 +879,9 @@
Using Savepoints
</title>
<para>
-OpenJPA's <phrase>
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
-<classname>OpenJPAEntityManager</classname></ulink></phrase> have the following
+OpenJPA's
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
+<classname>OpenJPAEntityManager</classname></ulink> have the following
methods to control savepoint behavior. Note that the savepoints work in tandem
with the current transaction. This means that savepoints require an open
transaction, and that a rollback of the transaction will rollback all of the
@@ -958,7 +958,8 @@
Configuring Savepoints
</title>
<para>
-OpenJPA uses the <ulink url="javadoc/openjpa/kernel/SavepointManager">
+OpenJPA uses the
+<ulink url="../apidocs/org/apache/openjpa/kernel/SavepointManager">
<classname>org.apache.openjpa.kernel.SavepointManager</classname></ulink>
<link linkend="ref_guide_conf_plugins">plugin</link> to handle perserving the
savepoint state. OpenJPA includes the following <classname>SavepointManager
@@ -1199,8 +1200,8 @@
</para>
<para>
See the <classname>OpenJPAQuery</classname>
-<ulink url="../../api/openjpa/persistence/OpenJPAQuery.html">Javadoc</ulink> for
-details.
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAQuery.html">
+Javadoc</ulink> for details.
</para>
</listitem>
</itemizedlist>
@@ -1267,8 +1268,8 @@
</para>
<para>
See the <classname>OpenJPAQuery</classname>
-<ulink url="../../api/openjpa/persistence/OpenJPAQuery.html">Javadoc</ulink> for
-details.
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAQuery.html">
+Javadoc</ulink> for details.
</para>
</listitem>
</itemizedlist>
@@ -1687,7 +1688,8 @@
public Generator getNamedGenerator (String name);
</programlisting>
<para>
-The returned <ulink url="../../api/openjpa/persistence/Generator.html">
+The returned
+<ulink url="../apidocs/org/apache/openjpa/persistence/Generator.html">
<classname>org.apache.openjpa.persistence.Generator</classname></ulink> is a
facade over an internal OpenJPA <classname>Seq</classname>.
</para>
@@ -1697,8 +1699,8 @@
With these APIs, you do not have to know the generator name. Additionally, they
allow you to access the implicit generator used by default for datastore
identity classes. See the
-<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"> Javadoc
-</ulink> for the <methodname> OpenJPAEntityManager.getIdentityGenerator
+<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
+Javadoc</ulink> for the <methodname> OpenJPAEntityManager.getIdentityGenerator
</methodname> and <methodname>OpenJPAEntityManager.getFieldGenerator
</methodname> methods for API details.
</para>
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml?view=diff&rev=452243&r1=452242&r2=452243
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml Mon Oct 2 15:22:18 2006
@@ -4,7 +4,7 @@
</title>
<para>
Following is a table of the database and JDBC driver versions that are supported
-by OpenJPA <phrase>JPA</phrase>.
+by OpenJPA.
</para>
<table tocentry="1">
<title>
@@ -326,10 +326,7 @@
<listitem>
<para>
Interbase does not support the <literal>LOWER</literal>, <literal>SUBSTRING
-</literal>, or <literal>INSTR</literal> SQL functions, which means that
-<methodname>toLowerCase()</methodname>, <methodname>indexOf()</methodname>, and
-<methodname>substring()</methodname> methods in <phrase>JPA</phrase> QL cannot
-be used.
+</literal>, or <literal>INSTR</literal> SQL functions>
</para>
</listitem>
</itemizedlist>
@@ -482,10 +479,7 @@
<listitem>
<para>
Firebird does not support the <literal>LOWER</literal>, <literal>SUBSTRING
-</literal>, or <literal>INSTR</literal> SQL functions, which means that
-<methodname>toLowerCase()</methodname>, <methodname>indexOf()</methodname>, and
-<methodname>substring()</methodname> methods in <phrase>JPA</phrase> QL cannot
-be used.
+</literal>, or <literal>INSTR</literal> SQL functions.
</para>
</listitem>
</itemizedlist>