You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by kw...@apache.org on 2006/09/06 18:35:07 UTC
svn commit: r440775 [4/5] - in /incubator/openjpa/sandboxes/OPENJPA-24:
openjpa-kernel/src/main/java/org/apache/openjpa/enhance/
openjpa-kernel/src/main/java/org/apache/openjpa/kernel/
openjpa-kernel/src/main/java/org/apache/openjpa/meta/ openjpa-kerne...
Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_mapping.xml?view=diff&rev=440775&r1=440774&r2=440775
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_mapping.xml (original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_mapping.xml Wed Sep 6 09:35:03 2006
@@ -8,7 +8,7 @@
</primary>
</indexterm>
<para>
-The JPA Overview's <xref linkend="jpa_overview_mapping"></xref> explains
+The JPA Overview's <xref linkend="jpa_overview_mapping"/> explains
object-relational mapping under JPA. This chapter reviews the mapping utilities
OpenJPA provides and examines OpenJPA features that go beyond the JPA
specification.
@@ -53,7 +53,7 @@
</para>
<note>
<para>
-<xref linkend="ref_guide_integration_mappingtool"></xref> describes the mapping
+<xref linkend="ref_guide_integration_mappingtool"/> describes the mapping
tool Ant task.
</para>
</note>
@@ -76,7 +76,7 @@
<literal>-schemaAction/-sa <add | refresh | drop | build | retain | none>
</literal>: The action to take on the schema. These options correspond to the
same-named actions on the schema tool described in
-<xref linkend="ref_guide_schema_schematool"></xref>. Unless you are running the
+<xref linkend="ref_guide_schema_schematool"/>. Unless you are running the
mapping tool on all of your persistent types at once or dropping a mapping, we
strongly recommend you use the default <literal>add</literal> action or the
<literal>build</literal> action. Otherwise you may end up inadvertently dropping
@@ -185,7 +185,7 @@
<listitem>
<para>
<literal>buildSchema</literal>: This is the default action when using JPA
-mapping defaults (see <xref linkend="ref_guide_mapping_defaults"></xref> ). It
+mapping defaults (see <xref linkend="ref_guide_mapping_defaults"/> ). It
makes the database schema match your existing mappings. If your provided
mappings conflict with a class definition, OpenJPA will fail with an informative
exception.
@@ -222,11 +222,11 @@
<para>
If you do not supply any arguments to the mapping tool, it will run on the
classes in your persistent classes list (see
-<xref linkend="ref_guide_pc_pcclasses"></xref> ).
+<xref linkend="ref_guide_pc_pcclasses"/> ).
</para>
<para>
The mappings generated by the mapping tool are stored by the system <emphasis>
-mapping factory</emphasis>. <xref linkend="ref_guide_mapping_factory"></xref>
+mapping factory</emphasis>. <xref linkend="ref_guide_mapping_factory"/>
discusses your mapping factory options.
</para>
<section id="ref_guide_mapping_mappingtool_examples">
@@ -244,11 +244,11 @@
<para>
The JPA specification defines a comprehensive set of defaults for missing
mapping information. Thus, forward mapping in JPA is virtually automatic. After
-using the mapping annotations covered in <xref linkend="jpa_overview_mapping">
-</xref> of the JPA Overview to override any unsatisfactory defaults, run the
+using the mapping annotations covered in <xref linkend="jpa_overview_mapping"/>
+ of the JPA Overview to override any unsatisfactory defaults, run the
mapping tool's <literal>buildSchema</literal> action on your persistent classes.
This is the default action when you use JPA mapping defaults (see
-<xref linkend="ref_guide_mapping_defaults"></xref> ).
+<xref linkend="ref_guide_mapping_defaults"/> ).
</para>
<para>
The <literal>buildSchema</literal> action manipulates the database schema to
@@ -356,8 +356,8 @@
</para>
<para>
In order to enable automatic runtime mapping, you must first list all your
-persistent classes as described in <xref linkend="ref_guide_pc_pcclasses">
-</xref>.
+persistent classes as described in <xref linkend="ref_guide_pc_pcclasses"/>
+.
</para>
<para>
OpenJPA will run the mapping tool on these classes when your application obtains
@@ -365,7 +365,7 @@
</para>
<para>
The <literal>openjpa.jdbc.SynchronizeMappings</literal> property is a plugin
-string (see <xref linkend="ref_guide_conf_plugins"></xref>) where the class
+string (see <xref linkend="ref_guide_conf_plugins"/>) where the class
name is the mapping tool action to invoke, and the properties are the
<classname>MappingTool</classname> class' JavaBean properties. These properties
correspond go the long versions of the tool's command line flags.
@@ -419,7 +419,7 @@
persistent class definitions, complete with metadata, from an existing database
schema. You do not have to use the reverse mapping tool to access an existing
schema; you are free to write your classes and mappings yourself, as described
-in <xref linkend="ref_guide_mapping_middle"></xref>. The reverse mapping tool,
+in <xref linkend="ref_guide_mapping_middle"/>. The reverse mapping tool,
however, can give you an excellent starting point from which to grow your
persistent classes.
</para>
@@ -455,7 +455,7 @@
Examine the generated schema file. JDBC drivers often provide incomplete or
faulty metadata, in which case the file will not exactly match the actual
schema. Alter the XML file to match the true schema. The XML format for the
-schema file is described in <xref linkend="ref_guide_schema_xml"></xref>.
+schema file is described in <xref linkend="ref_guide_schema_xml"/>.
</para>
<para>
After fixing any errors in the schema file, modify the XML to include foreign
@@ -496,7 +496,7 @@
comma-separated list of schema and table names to reverse map, if no XML schema
file is supplied. Each element of the list must follow the naming conventions
for the <literal>openjpa.jdbc.Schemas</literal> property described in
-<xref linkend="ref_guide_schema_info_list"></xref>. In fact, if this flag is
+<xref linkend="ref_guide_schema_info_list"/>. In fact, if this flag is
omitted, it defaults to the value of the <literal>Schemas</literal> property. If
the <literal>Schemas</literal> property is not defined, all schemas will be
reverse-mapped.
@@ -668,7 +668,7 @@
</literal>, or your favorite Java compiler. Make sure the classes and their
metadata are located in the directory corresponding to the <literal>-package
</literal> flag you gave the reverse mapping tool. Finally, enhance the classes
-if necessary (see <xref linkend="ref_guide_pc_enhance"></xref> ).
+if necessary (see <xref linkend="ref_guide_pc_enhance"/> ).
</para>
</listitem>
</orderedlist>
@@ -884,7 +884,7 @@
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. We examined the mapping tool in
-<xref linkend="ref_guide_mapping_mappingtool"></xref>. The <literal>validate
+<xref linkend="ref_guide_mapping_mappingtool"/>. The <literal>validate
</literal> 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.
@@ -899,7 +899,7 @@
</example>
<para>
The <literal>buildSchema</literal> action we discussed in
-<xref linkend="ref_guide_mapping_mappingtool"></xref> is also somewhat useful
+<xref linkend="ref_guide_mapping_mappingtool"/> is also somewhat useful
during meet-in-the-middle mapping. Unlike the <literal>validate</literal>
action, which throws an exception if your mapping data does not match the
existing schema, the <literal>buildSchema</literal> action assumes your mapping
@@ -909,7 +909,7 @@
</para>
<para>
<literal>buildSchema</literal> is the default action when you use JPA mapping
-defaults ( <xref linkend="ref_guide_mapping_defaults"></xref> ).
+defaults ( <xref linkend="ref_guide_mapping_defaults"/> ).
</para>
<example id="ref_guide_mapping_middle_buildschema_mid">
<title>
@@ -955,14 +955,14 @@
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, or use explicit foreign key mappings as described in
-<phrase><xref linkend="ref_guide_mapping_jpa_fk"></xref></phrase>.
+<phrase><xref linkend="ref_guide_mapping_jpa_fk"/></phrase>.
</para>
</important>
<para>
The <link linkend="openjpa.jdbc.MappingDefaults"><literal>
openjpa.jdbc.MappingDefaults</literal></link> configuration property controls
the <classname>MappingDefaults</classname> interface implementation in use. This
-is a plugin property (see <xref linkend="ref_guide_conf_plugins"></xref> ), so
+is a plugin property (see <xref linkend="ref_guide_conf_plugins"/> ), so
you can substitute your own implementation or configure the existing ones.
OpenJPA includes the following standard implementations:
</para>
@@ -1005,7 +1005,7 @@
classes. You can specify a built-in strategy alias or the full class name of a
<link linkend="ref_guide_mapping_custom_class"> custom class strategy</link>.
You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"></xref>) to pass arguments to the
+<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
strategy instance. See the
<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/strats/package-summary.html">
<literal>org.apache.openjpa.jdbc.meta.strats</literal></ulink> package for
@@ -1018,7 +1018,7 @@
subclasses. You can specify a builtin strategy alias or the full class name of a
<link linkend="ref_guide_mapping_custom_class"> custom class strategy</link>.
You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"></xref>) to pass arguments to the
+<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
strategy instance. Common strategies are <literal>vertical</literal> and
<literal>flat</literal>, the default. See the
<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/strats/package-summary.html">
@@ -1032,7 +1032,7 @@
without a version field. You can specify a builtin strategy alias or the full
class name of a <link linkend="ref_guide_mapping_custom_versdiscrim"> custom
version strategy</link>. You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"></xref>) to pass arguments to the
+<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
strategy instance. Common strategies are <literal>none</literal>, <literal>
state-comparison</literal>, <literal> timestamp</literal>, and <literal>
version-number</literal>, the default. See the
@@ -1048,7 +1048,7 @@
or the full class name of a
<link linkend="ref_guide_mapping_custom_versdiscrim"> custom discriminator
strategy</link>. You can also use OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"></xref>) to pass arguments to the
+<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
strategy instance. Common strategies are <literal>final</literal> for a base
class without subclasses, <literal>none</literal> to use joins to subclass
tables rather than a discriminator column, and <literal> class-name</literal>,
@@ -1062,11 +1062,11 @@
<para>
<literal>FieldStrategies</literal>: This property associates field types with
custom strategies. The format of this property is similar to that of plugin
-strings (see <xref linkend="ref_guide_conf_plugins"></xref> ), without the class
+strings (see <xref linkend="ref_guide_conf_plugins"/> ), without the class
name. It is a comma-separated list of key/value pairs, where each key is a
possible field type, and each value is itself a plugin string describing the
strategy for that type. We present an example below. See
-<xref linkend="ref_guide_mapping_custom_field"></xref> for information on custum
+<xref linkend="ref_guide_mapping_custom_field"/> for information on custum
field strategies.
</para>
</listitem>
@@ -1128,7 +1128,7 @@
<para>
<literal>VersionColumnName</literal>: The default name of version columns. If
you use custom lock groups, this name may be combined with lock group names. See
-<xref linkend="ref_guide_lock_groups"></xref> for more information on lock
+<xref linkend="ref_guide_lock_groups"/> for more information on lock
groups.
</para>
</listitem>
@@ -1234,11 +1234,11 @@
<para>
In JPA, mapping metadata is defined in annotations. Future versions of the JPA
drafts will also define a mapping XML format.
-<xref linkend="jpa_overview_mapping"></xref> in the JPA Overview describes JPA
+<xref linkend="jpa_overview_mapping"/> in the JPA Overview describes JPA
mapping options.
</para>
<para>
-<xref linkend="ref_guide_meta_factory"></xref> introduced OpenJPA's <classname>
+<xref linkend="ref_guide_meta_factory"/> introduced OpenJPA's <classname>
MetaDataFactory</classname> interface. OpenJPA uses this same interface to
abstract the storage and retrieval of mapping information. OpenJPA includes the
built-in mapping factories below, and you can create your own factory if you
@@ -1288,7 +1288,7 @@
</secondary>
</indexterm>
<para>
-The JPA Overview's <xref linkend="jpa_overview_mapping"></xref> explains join
+The JPA Overview's <xref linkend="jpa_overview_mapping"/> explains join
mapping. All of the examples in that document, however, use "standard" joins, in
that there is one foreign key column for each primary key column in the target
table. OpenJPA supports additional join patterns, including partial primary key
@@ -1327,7 +1327,7 @@
org.apache.openjpa.jdbc.meta.Joinable</classname></ulink> interface. All built
in basic mappings implement this interface, including basic fields of embedded
objects. OpenJPA will also respect any custom mappings that implement this
-interface. See <xref linkend="ref_guide_mapping_custom"></xref> for an
+interface. See <xref linkend="ref_guide_mapping_custom"/> for an
examination of custom mappings.
</para>
<para>
@@ -1356,8 +1356,8 @@
<mediaobject>
<imageobject>
<!-- PNG image data, 427 x 211 (see README) -->
- <imagedata fileref="img/joins-constant.png" width="285px">
- </imagedata>
+ <imagedata fileref="img/joins-constant.png" width="285px"/>
+
</imageobject>
</mediaobject>
<para>
@@ -1440,7 +1440,7 @@
</indexterm>
<para>
OpenJPA supports many persistence strategies beyond those of the JPA
-specification. <xref linkend="ref_guide_meta_jpa"></xref> covered the logical
+specification. <xref linkend="ref_guide_meta_jpa"/> covered the logical
metadata for OpenJPA's additional persistence strategies. We now demonstrate how
to map entities using these strategies to the database.
</para>
@@ -1481,7 +1481,7 @@
</primary>
</indexterm>
<para>
-<xref linkend="ref_guide_pc_oid"></xref> describes how to use datastore identity
+<xref linkend="ref_guide_pc_oid"/> describes how to use datastore identity
in JPA. OpenJPA requires a single numeric primary key column to hold datastore
identity values. The
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/DataStoreIdColumn.html">
@@ -1519,7 +1519,7 @@
<para>
All properties correspond exactly to the same-named properties on the standard
<classname>Column</classname> annotation, described in
-<xref linkend="jpa_overview_mapping_column"></xref>.
+<xref linkend="jpa_overview_mapping_column"/>.
</para>
<example id="ref_guide_mapping_jpa_datastoreidex">
<title>
@@ -1637,16 +1637,16 @@
<para>
The <literal>lockGroup</literal> property allows you to specify that a version
column is for some lock group other than the default group. See
-<xref linkend="ref_guide_lock_groups"></xref> for an example. All other
+<xref linkend="ref_guide_lock_groups"/> for an example. All other
properties correspond exactly to the same-named properties on the standard
<classname>Column</classname> annotation, described in
-<xref linkend="jpa_overview_mapping_column"></xref>.
+<xref linkend="jpa_overview_mapping_column"/>.
</para>
<para>
By default, OpenJPA assumes that surrogate versioning uses a version number
strategy. You can choose a different strategy with the <classname>
VersionStrategy</classname> annotation described in
-<xref linkend="version-strategy"></xref>.
+<xref linkend="version-strategy"/>.
</para>
</section>
<section id="ref_guide_mapping_jpa_columns">
@@ -1686,13 +1686,10 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Columns.html">
<classname>org.apache.openjpa.persistence.jdbc.Columns</classname></ulink>
annotation, which contains an array of <classname>Column</classname> values.
-<xref linkend="ref_guide_mapping_custom_field_conf_extex"></xref> uses OpenJPA's
-<classname>Columns</classname> annotation to map a <classname>java.awt.Point
-</classname> to separate X and Y columns.
</para>
<para>
Remember to annotate custom field types with <classname> Persistent</classname>
-, as described in <xref linkend="ref_guide_meta_jpa_persistent"></xref>.
+, as described in <xref linkend="ref_guide_meta_jpa_persistent"/>.
</para>
</section>
<section id="ref_guide_mapping_jpa_fieldjoin">
@@ -1700,7 +1697,7 @@
Join Column Attribute Targets
</title>
<para>
-<xref linkend="jpa_overview_mapping_rel"></xref> in the JPA Overview introduced
+<xref linkend="jpa_overview_mapping_rel"/> in the JPA Overview introduced
you to the <classname>JoinColumn</classname> annotation. A <classname>
JoinColumn</classname>'s <literal> referencedColumnName</literal> property
declares which column in the table of the related type this join column links
@@ -1738,7 +1735,7 @@
<para>
JPA uses the <classname>AttributeOverride</classname> annotation to override the
default mappings of an embeddable class. The JPA Overview details this process
-in <xref linkend="jpa_overview_mapping_embed"></xref>. <classname>
+in <xref linkend="jpa_overview_mapping_embed"/>. <classname>
AttributeOverride</classname>s suffice for simple mappings, but do not allow
you to override complex mappings. Also, JPA has no way to differentitate between
a null embedded object and one with default values for all of its fields.
@@ -1822,36 +1819,15 @@
<para>
<literal>ContainerTable containerTable</literal>: Table for the new collection
or map field mapping. We cover collection mappings in
-<xref linkend="ref_guide_mapping_jpa_coll"></xref>, and map mappings in
-<xref linkend="ref_guide_mapping_jpa_map"></xref>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>ElementColumn[] elementColumns</literal>: Element columns for the new
-collection or map field mapping. You will see how to use element columns in
-<xref linkend="ref_guide_mapping_jpa_coll_cols"></xref>.
+<xref linkend="ref_guide_mapping_jpa_coll"/>, and map mappings in
+<xref linkend="ref_guide_mapping_jpa_map"/>.
</para>
</listitem>
<listitem>
<para>
<literal>ElementJoinColumn[] elementJoinColumns</literal>: Element join columns
for the new collection or map field mapping. You will see how to use element
-join columns in <xref linkend="ref_guide_mapping_jpa_coll_joincols"></xref>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>KeyColumn[] keyColumns</literal>: Map key columns for the new map
-field mapping. You will see how to use key columns in
-<xref linkend="ref_guide_mapping_jpa_map_keycols"></xref>.
- </para>
- </listitem>
- <listitem>
- <para>
-<literal>KeyJoinColumn[] keyJoinColumns</literal>: Key join columns for the new
-map field mapping. You will see how to use key join columns in
-<xref linkend="ref_guide_mapping_jpa_map_keyjoincols"></xref>.
+join columns in <xref linkend="ref_guide_mapping_jpa_coll_joincols"/>.
</para>
</listitem>
</itemizedlist>
@@ -1915,14 +1891,13 @@
</secondary>
</indexterm>
<para>
-In <xref linkend="ref_guide_meta_jpa_persistent_coll"></xref>, we explored the
+In <xref linkend="ref_guide_meta_jpa_persistent_coll"/>, we explored the
<classname>PersistentCollection</classname> annotation for persistent collection
fields that aren't a standard <literal>OneToMany</literal> or <literal>
ManyToMany</literal> relation. To map these non-standard collections, combine
-OpenJPA's <classname>ContainerTable</classname> annotation with <classname>
-ElementColumn</classname> s, <classname> ElementJoinColumn</classname> s, or an
-<classname> ElementEmbeddedMapping</classname>. We explore the annotations
-below.
+OpenJPA's <classname>ContainerTable</classname> annotation with
+<classname>ElementJoinColumn</classname>s.
+We explore the annotations below.
</para>
<section id="ref_guide_mapping_jpa_coll_table">
<title>
@@ -1980,7 +1955,7 @@
</literal>, and <literal>joinColumns</literal> properties describe the container
table and how it joins to the owning entity's table. These properties correspond
to the same-named properties on the standard <classname> JoinTable</classname>
-annotation, described in <xref linkend="jpa_overview_mapping_assoccoll"></xref>
+annotation, described in <xref linkend="jpa_overview_mapping_assoccoll"/>
. If left unspecified, the name of the table defaults to the first five
characters of the entity table name, plus an underscore, plus the field name.
The <literal>joinForeignKey</literal> and <literal> joinIndex</literal>
@@ -1993,39 +1968,6 @@
of the next sections.
</para>
</section>
- <section id="ref_guide_mapping_jpa_coll_cols">
- <title>
- Element Columns
- </title>
- <indexterm zone="ref_guide_mapping_jpa_coll_cols">
- <primary>
- ElementColumn
- </primary>
- <seealso>
- mapping metadata
- </seealso>
- </indexterm>
- <para>
-Just as the JPA <classname>Column</classname> annotation maps a simple value
-(primitive wrapper, <classname> String</classname>, etc), OpenJPA's
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementColumn</classname></ulink>
-annotation maps a simple element value. To map custom multi-column elements, use
-the
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementColumns.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementColumns</classname>
-</ulink> annotation, whose value is an array of <classname> ElementColumn
-</classname> s.
- </para>
- <para>
-An <classname>ElementColumn</classname> always resides in a container table, so
-it does not have the <literal> table</literal> property of a standard
-<classname> Column</classname>. Otherwise, the <classname>ElementColumn
-</classname> and standard <classname>Column</classname> annotations are
-equivalent. See <xref linkend="jpa_overview_mapping_column"></xref> in the JPA
-Overview for a review of the <classname>Column</classname> annotation.
- </para>
- </section>
<section id="ref_guide_mapping_jpa_coll_joincols">
<title>
Element Join Columns
@@ -2057,7 +1999,7 @@
above, <classname> ElementJoinColumn</classname>s can reference a linked
attribute rather than a static linked column. Otherwise, the <classname>
ElementJoinColumn</classname> and standard <classname>JoinColumn</classname>
-annotations are equivalent. See <xref linkend="jpa_overview_mapping_rel"></xref>
+annotations are equivalent. See <xref linkend="jpa_overview_mapping_rel"/>
in the JPA Overview for a review of the <classname>JoinColumn</classname>
annotation.
</para>
@@ -2144,97 +2086,9 @@
the <literal>enabled</literal> property to <literal>false</literal>. All other
properties correspond exactly to the same-named properties on the standard
<classname>Column</classname> annotation, described in
-<xref linkend="jpa_overview_mapping_column"></xref>.
+<xref linkend="jpa_overview_mapping_column"/>.
</para>
</section>
- <section id="ref_guide_mapping_jpa_coll_ex">
- <title>
- Examples
- </title>
- <mediaobject>
- <imageobject>
- <!-- PNG image data, 383 x 176 (see README) -->
- <imagedata fileref="img/basic-coll.png" width="255px">
- </imagedata>
- </imageobject>
- </mediaobject>
- <para>
-Our first example maps the <literal>Article.subtitles</literal> field to the
-<literal>ART_SUBS</literal> container table, as shown in the diagram above.
-Notice the use of <classname> ContainerTable</classname> in combination with
-<classname>ElementColumn</classname> and <classname>OrderColumn</classname> to
-map this ordered list of strings.
- </para>
- <example id="ref_guide_mapping_jpa_coll_simpleex">
- <title>
- String List Mapping
- </title>
-<programlisting>
-package org.mag;
-
-import org.apache.openjpa.persistence.*;
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Entity
-@Table(name="ART")
-public class Article
-{
- @Id private long id;
-
- @PersistentCollection
- @ContainerTable(name="ART_SUBS", joinColumns=@XJoinColumn(name="ART_ID"))
- @ElementColumn(name="SUBTITLE")
- @OrderColumn(name="ORD")
- private List<String> subtitles;
-
- ...
-}
-</programlisting>
- </example>
- <para>
-Now we map a collection of embedded <classname>Address</classname> objects for a
-<classname>Company</classname>, according to the following diagram:
- </para>
- <mediaobject>
- <imageobject>
- <!-- PNG image data, 545 x 239 (see README) -->
- <imagedata fileref="img/embedded-coll.png" width="363px">
- </imagedata>
- </imageobject>
- </mediaobject>
- <example id="ref_guide_mapping_jpa_coll_embedex">
- <title>
- Embedded Element Mapping
- </title>
-<programlisting>
-package org.mag.pub;
-
-import org.apache.openjpa.persistence.*;
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Embeddable
-public class Address
-{
- ...
-}
-
-@Entity
-@Table(name="COMP")
-public class Company
-{
- @Id private long id;
-
- @PersistentCollection(elementEmbedded=true)
- @ContainerTable(name="COMP_ADDRS", joinColumns=@XJoinColumn(name="COMP_ID"))
- @ElementEmbeddedMapping(overrides=@MappingOverride(name="state",
- columns=@Column(columnDefinition="CHAR(2)")))
- private Collection<Address> addresses;
-
- ...
-}
-</programlisting>
- </example>
- </section>
</section>
<section id="ref_guide_mapping_jpa_onemany">
<title>
@@ -2253,28 +2107,28 @@
</indexterm>
<para>
The previous section covered the use of <classname>ElementJoinColumn</classname>
-annotations in conjunction with a <classname> ContainerTable</classname> for
+annotations in conjunction with a <classname>ContainerTable</classname> for
mapping collections to dedicate tables. <classname>ElementJoinColumn</classname>
s, however, have one additional use: to create a one-sided one-many mapping.
Standard JPA supports <classname>OneToMany</classname> fields without a
<literal>mappedBy</literal> inverse, but only by mapping these fields to a
<classname>JoinTable</classname> (see
-<xref linkend="jpa_overview_mapping_assoccoll"></xref> in the JPA Overview for
+<xref linkend="jpa_overview_mapping_assoccoll"/> in the JPA Overview for
details). Often, you'd like to create a one-many association based on an inverse
foreign key (logical or actual) in the table of the related type.
</para>
<mediaobject>
<imageobject>
<!-- PNG image data, 392 x 192 (see README) -->
- <imagedata fileref="img/inv-key-coll.png" width="261">
- </imagedata>
+ <imagedata fileref="img/inv-key-coll.png" width="261"/>
+
</imageobject>
</mediaobject>
<para>
Consider the model above. <classname>Subscription</classname> has a collection
-of <classname>LineItem</classname> s, but <classname> LineItem</classname> has
-no inverse relation to <classname> Subscription</classname>. To retrieve all of
-the <classname> LineItem</classname> records for a <classname> Subscription
+of <classname>LineItem</classname> s, but <classname>LineItem</classname> has
+no inverse relation to <classname>Subscription</classname>. To retrieve all of
+the <classname>LineItem</classname> records for a <classname>Subscription
</classname>, we join the <literal>SUB_ID</literal> inverse foreign key column
in the <literal>LINE_ITEM</literal> table to the primary key column of the
<literal>SUB</literal> table. The example below shows how to represent this
@@ -2326,166 +2180,13 @@
</secondary>
</indexterm>
<para>
-<xref linkend="ref_guide_meta_jpa_persistent_map"></xref> discussed the
-<classname>PersistentMap</classname> annotation for persistent map fields. To
-map these non-standard fields to the database, combine OpenJPA's <classname>
-ContainerTable</classname> annotation with <classname>KeyColumn</classname> s,
-<classname> KeyJoinColumn</classname> s, or an <classname> KeyEmbeddedMapping
-</classname> and <classname>ElementColumn</classname> s, <classname>
-ElementJoinColumn</classname> s, or an <classname> ElementEmbeddedMapping
-</classname>.
- </para>
- <para>
We detailed the <literal>ContainerTable</literal> annotation in
-<xref linkend="ref_guide_mapping_jpa_coll_table"></xref>. We also discussed
-element columns, join columns, and embedded mappings in
-<xref linkend="ref_guide_mapping_jpa_coll_cols"></xref>,
-<xref linkend="ref_guide_mapping_jpa_coll_joincols"></xref>, and
-<xref linkend="ref_guide_mapping_jpa_coll_embed"></xref>. Key columns, join
+<xref linkend="ref_guide_mapping_jpa_coll_table"/>. We also discussed
+join columns embedded mappings in
+<xref linkend="ref_guide_mapping_jpa_coll_joincols"/> and
+<xref linkend="ref_guide_mapping_jpa_coll_embed"/>. Key columns, join
columns, and embedded mappings are new, however; we tackle them below.
</para>
- <section id="ref_guide_mapping_jpa_map_keycols">
- <title>
- Key Columns
- </title>
- <indexterm zone="ref_guide_mapping_jpa_map_keycols">
- <primary>
- KeyColumn
- </primary>
- <seealso>
- mapping metadata
- </seealso>
- </indexterm>
- <para>
-Key columns serve the same role for map keys as the element columns described in
-<xref linkend="ref_guide_mapping_jpa_coll_cols"></xref> serve for collection
-elements. OpenJPA's
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyColumn</classname></ulink>
-annotation represents a map key. To map custom multi-column keys, use the
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyColumns.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyColumns</classname></ulink>
-annotation, whose value is an array of <classname> KeyColumn</classname> s.
- </para>
- <para>
-A <classname>KeyColumn</classname> always resides in a container table, so it
-does not have the <literal> table</literal> property of a standard <classname>
-Column</classname>. Otherwise, the <classname>KeyColumn</classname> and standard
-<classname>Column</classname> annotations are equivalent. See
-<xref linkend="jpa_overview_mapping_column"></xref> in the JPA Overview for a
-review of the <classname>Column</classname> annotation.
- </para>
- </section>
- <section id="ref_guide_mapping_jpa_map_keyjoincols">
- <title>
- Key Join Columns
- </title>
- <indexterm zone="ref_guide_mapping_jpa_map_keyjoincols">
- <primary>
- KeyJoinColumn
- </primary>
- <seealso>
- mapping metadata
- </seealso>
- </indexterm>
- <para>
-Key join columns are equivalent to standard JPA join columns, except that they
-represent a join to a map key entity rather than a direct relation. You
-represent a key join column with OpenJPA's
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyJoinColumn.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyJoinColumn</classname></ulink>
-annotation. To declare a compound join, enclose an array of <classname>
-KeyJoinColumn</classname>s in the
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyJoinColumns.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyJoinColumns</classname>
-</ulink> annotation.
- </para>
- <para>
-A <classname>KeyJoinColumn</classname> always resides in a container table, so
-it does not have the <literal> table</literal> property of a standard
-<classname> JoinColumn</classname>. Like <classname> XJoinColumn</classname>s
-above, <classname> KeyJoinColumn</classname>s can reference a linked field
-rather than a static linked column. Otherwise, the <classname> KeyJoinColumn
-</classname> and standard <classname>JoinColumn</classname> annotations are
-equivalent. See <xref linkend="jpa_overview_mapping_rel"></xref> in the JPA
-Overview for a review of the <classname>JoinColumn</classname> annotation.
- </para>
- </section>
- <section id="ref_guide_mapping_jpa_map_embedkey">
- <title>
- Key Embedded Mapping
- </title>
- <indexterm zone="ref_guide_mapping_jpa_map_embedkey">
- <primary>
- KeyEmbeddedMapping
- </primary>
- <seealso>
- mapping metadata
- </seealso>
- </indexterm>
- <para>
-The
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyEmbeddedMapping.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyEmbeddedMapping</classname>
-</ulink> annotation allows you to map your map field's embedded key type to your
-container table. This annotation has exactly the same properties as the
-<classname>EmbeddedMapping</classname> annotation described
-<link linkend="ref_guide_mapping_jpa_embed">above</link>.
- </para>
- </section>
- <section id="ref_guide_mapping_jpa_map_ex">
- <title>
- Examples
- </title>
- <mediaobject>
- <imageobject>
- <!-- PNG image data, 410 x 266 (see README) -->
- <imagedata fileref="img/string-rel-map.png" width="273px">
- </imagedata>
- </imageobject>
- </mediaobject>
- <para>
-Map mapping in OpenJPA uses the same principles you saw in collection mapping.
-The example below maps the <literal> Article.authors</literal> map according to
-the diagram above.
- </para>
- <example id="ref_guide_mapping_jpa_map_stringrelmap">
- <title>
- String Key, Entity Value Map Mapping
- </title>
-<programlisting>
-package org.mag.pub;
-
-import org.apache.openjpa.persistence.*;
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Entity
-@Table(name="AUTH")
-@DataStoreIdColumn(name="AID" columnDefinition="INTEGER64")
-public class Author
-{
- ...
-}
-
-package org.mag;
-
-@Entity
-@Table(name="ART")
-public class Article
-{
- @Id private long id;
-
- @PersistentMap
- @ContainerTable(name="ART_AUTHS", joinColumns=@XJoinColumn(name="ART_ID"))
- @KeyColumn(name="LNAME")
- @ElementJoinColumn(name="AUTH_ID")
- private Map<String,Author> authors;
-
- ...
-}
-</programlisting>
- </example>
- </section>
</section>
<section id="ref_guide_mapping_jpa_constraints">
<title>
@@ -2500,8 +2201,8 @@
</para>
<para>
OpenJPA assumes certain columns have indexes or constraints based on your
-mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults">
-</xref>. You can override the configured defaults on individual joins, field
+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.
</para>
@@ -2526,7 +2227,7 @@
The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Index.html">
<classname>org.apache.openjpa.persistence.jdbc.Index</classname></ulink>
annotation represents an index on the columns of a field. It is also used within
-the <link linkend="ref_guide_mapping_jpa_coll_table"><classname> ConterainTable
+the <link linkend="ref_guide_mapping_jpa_coll_table"><classname>ContainerTable
</classname></link> annotation to index join columns.
</para>
<para>
@@ -2696,55 +2397,16 @@
Examples
</title>
<para>
-Here again is our map example from <xref linkend="ref_guide_mapping_jpa_map">
-</xref>, now with explicit indexes and constraints added.
+Here again is our map example from <xref linkend="ref_guide_mapping_jpa_map"/>
+, now with explicit indexes and constraints added.
</para>
<mediaobject>
<imageobject>
<!-- PNG image data, 410 x 266 (see README) -->
- <imagedata fileref="img/string-rel-map.png" width="273px">
- </imagedata>
+ <imagedata fileref="img/string-rel-map.png" width="273px"/>
+
</imageobject>
</mediaobject>
- <example id="ref_guide_mapping_jpa_constraintex_map">
- <title>
- Constraint Mapping
- </title>
-<programlisting>
-package org.mag.pub;
-
-import org.apache.openjpa.persistence.*;
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Entity
-@Table(name="AUTH")
-@DataStoreIdColumn(name="AID" columnDefinition="INTEGER64")
-public class Author
-{
- ...
-}
-
-package org.mag;
-
-@Entity
-@Table(name="ART")
-public class Article
-{
- @Id private long id;
-
- @PersistentMap
- @ContainerTable(name="ART_AUTHS", joinColumns=@XJoinColumn(name="ART_ID")
- joinForeignKey=@ForeignKey(deleteAction=ForeignKeyAction.CASCADE))
- @KeyColumn(name="LNAME")
- @KeyIndex(name="I_AUTH_LNAME")
- @ElementJoinColumn(name="AUTH_ID")
- @ElementForeignKey(deleteAction=ForeignKeyAction.RESTRICT)
- private Map<String,Author> authors;
-
- ...
-}
-</programlisting>
- </example>
</section>
</section>
</section>
@@ -2804,7 +2466,7 @@
<listitem>
<para>
Table-per-class hierarchies impose limitations on eager fetching. See
-<xref linkend="ref_guide_perfpack_eager_consider"></xref>.
+<xref linkend="ref_guide_perfpack_eager_consider"/>.
</para>
</listitem>
</itemizedlist>
@@ -2812,7 +2474,7 @@
<para>
Non-polymorphic relations do not suffer from these limitations. You can declare
a non-polymorphic relation using the extensions described in
-<xref linkend="nonpolymorphic"></xref>.
+<xref linkend="nonpolymorphic"/>.
</para>
</note>
</section>
@@ -2863,8 +2525,8 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EagerFetchType.html">
<classname>org.apache.openjpa.persistence.jdbc.EagerFetchType</classname>
</ulink> enum: <literal>JOIN</literal>, <literal>PARALLEL</literal>, or
-<literal>NONE</literal>.</phrase> See <xref linkend="ref_guide_perfpack_eager">
-</xref> for a discussion of eager fetching.
+<literal>NONE</literal>.</phrase> See <xref linkend="ref_guide_perfpack_eager"/>
+ for a discussion of eager fetching.
</para>
</section>
<section id="class-strategy">
@@ -2889,7 +2551,7 @@
The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
class annotation allows you to specify a custom mapping strategy for your class.
-See <xref linkend="ref_guide_mapping_custom"></xref> for information on custom
+See <xref linkend="ref_guide_mapping_custom"/> for information on custom
mappings.
</para>
</section>
@@ -2916,7 +2578,7 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/DiscriminatorStrategy.html">
<classname>org.apache.openjpa.persistence.jdbc.DiscriminatorStrategy</classname>
</ulink> class annotation allows you to specify a custom discriminator strategy.
-See <xref linkend="ref_guide_mapping_custom"></xref> for information on custom
+See <xref linkend="ref_guide_mapping_custom"/> for information on custom
mappings.
</para>
</section>
@@ -2943,7 +2605,7 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/VersionStrategy.html">
<classname>org.apache.openjpa.persistence.jdbc.VersionStrategy</classname>
</ulink> class annotation allows you to specify a custom version strategy. See
-<xref linkend="ref_guide_mapping_custom"></xref> for information on custom
+<xref linkend="ref_guide_mapping_custom"/> for information on custom
mappings.
</para>
</section>
@@ -2976,15 +2638,15 @@
<para>
This extension specifies how to eagerly fetch related objects. It overrides the
global <link linkend="openjpa.jdbc.EagerFetchMode"><literal>
-openjpa.jdbc.EagerFetchMode</literal></link> property. <phrase> Set the JPA
+openjpa.jdbc.EagerFetchMode</literal></link> property. <phrase>Set the JPA
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EagerFetchMode.html">
<classname>org.apache.openjpa.persistence.jdbc.EagerFetchMode</classname>
</ulink> annotation to a value from the
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/EagerFetchType.html">
<classname>org.apache.openjpa.persistence.jdbc.EagerFetchType</classname>
</ulink> enum: <literal>JOIN</literal>, <literal>PARALLEL</literal>, or
-<literal>NONE</literal>.</phrase> See <xref linkend="ref_guide_perfpack_eager">
-</xref> for a discussion of eager fetching.
+<literal>NONE</literal>.</phrase> See <xref linkend="ref_guide_perfpack_eager"/>
+ for a discussion of eager fetching.
</para>
</section>
<section id="nonpolymorphic">
@@ -3014,7 +2676,7 @@
<note>
<para>
OpenJPA also includes the <literal>type</literal> metadata extension for
-narrowing the declared type of a field See <xref linkend="type"></xref>.
+narrowing the declared type of a field See <xref linkend="type"/>.
</para>
</note>
<para>
@@ -3047,9 +2709,9 @@
The value of these extensions is a constant from the
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/NonpolymorphicType.html">
<classname>org.apache.openjpa.persistence.jdbc.NonpolymorphicType</classname>
-</ulink> enumeration. The default value, <literal> EXACT</literal>, indicates
+</ulink> enumeration. The default value, <literal>EXACT</literal>, indicates
that the relation will always be of the exact declared type. A value of
-<literal> JOINABLE</literal>, on the other hand, means that the relation might
+<literal>JOINABLE</literal>, on the other hand, means that the relation might
be to any joinable subclass of the declared type. This value only excludes
table-per-class subclasses.
</para>
@@ -3140,7 +2802,7 @@
<para>
OpenJPA's family of strategy extensions allow you to specify a custom mapping
strategy or value handler for a field. See
-<xref linkend="ref_guide_mapping_custom"></xref> for information on custom
+<xref linkend="ref_guide_mapping_custom"/> for information on custom
mappings.
</para>
<para>
@@ -3156,13 +2818,6 @@
</listitem>
<listitem>
<para>
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementStrategy.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementStrategy</classname>
-</ulink>: Array, collection, or map element value handler plugin string.
- </para>
- </listitem>
- <listitem>
- <para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyStrategy.html">
<classname>org.apache.openjpa.persistence.jdbc.KeyStrategy</classname></ulink>:
Map key value handler plugin string.
@@ -3235,14 +2890,14 @@
</literal> package.
</para>
<para>
-<phrase> The
+<phrase>The
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
annotation allows you to declare a custom class mapping strategy in JPA mapping
metadata. Set the value of the annotation to the full class name of your custom
strategy.</phrase> You can configure your strategy class' bean properties using
-OpenJPA's plugin syntax, detailed in <xref linkend="ref_guide_conf_plugins">
-</xref>.
+OpenJPA's plugin syntax, detailed in <xref linkend="ref_guide_conf_plugins"/>
+.
</para>
</section>
<section id="ref_guide_mapping_custom_versdiscrim">
@@ -3275,7 +2930,7 @@
<para>
As with custom class mappings, you can configure your strategy class' bean
properties using OpenJPA's plugin syntax, detailed in
-<xref linkend="ref_guide_conf_plugins"></xref>.
+<xref linkend="ref_guide_conf_plugins"/>.
</para>
</section>
<section id="ref_guide_mapping_custom_field">
@@ -3380,69 +3035,19 @@
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, collection element, map key, or map value of the associated
-type. <xref linkend="ref_guide_mapping_defaults"></xref> described mapping
+type. <xref linkend="ref_guide_mapping_defaults"/> described mapping
defaults in detail.
</para>
<para>
Your other option is to explicitly install a custom value handler or strategy on
a particular field. To do so, specify the full name of your implementation class
-in the proper mapping metadata extension. <phrase> OpenJPA includes the
+in the proper mapping metadata extension. <phrase>OpenJPA includes the
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
-<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>,
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementStrategy.html">
-<classname>org.apache.openjpa.persistence.jdbc.ElementStrategy</classname>
-</ulink>, and
-<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyStrategy.html">
-<classname>org.apache.openjpa.persistence.jdbc.KeyStrategy</classname></ulink>
-annotations.</phrase> You can configure the named strategy or handler's bean
+<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
+annotation.</phrase> You can configure the named strategy or handler's bean
properties in these extensions using OpenJPA's plugin format (see
-<xref linkend="ref_guide_conf_plugins"></xref> ).
- </para>
- <para>
-The example below installs a custom strategy on the <literal>coverImage
-</literal> field, uses a custom value handler for the <literal>
-primaryInfoStruct</literal> field, and uses the same value handler for the
-elements of the <literal>secondaryInfoStructs</literal> collection.
+<xref linkend="ref_guide_conf_plugins"/> ).
</para>
- <example id="ref_guide_mapping_custom_field_conf_extex">
- <title>
- Custom Mappings via Extensions
- </title>
-<programlisting>
-import org.apache.openjpa.persistence.*;
-import org.apache.openjpa.persistence.jdbc.*;
-
-@Entity
-public class Magazine
-{
- @Persistent
- @Strategy("org.mag.mapping.ImageStrategy")
- @Column(name="IMG")
- private Image coverImage;
-
- @Persistent
- @Strategy("org.mag.mapping.InfoStructHandler")
- @Columns({
- @Column(name="DATA1"),
- @Column(name="DATA2"),
- @Column(name="DATA3")
- })
- private InfoStruct primaryInfoStruct;
-
- @PersistentCollection
- @ContainerTable(name="SEC_STRUCTS", joinColumns=@XJoinColumn(name="MAG_ID"))
- @ElementStrategy("org.mag.mapping.InfoStructHandler")
- @ElementColumns({
- @ElementColumn(name="DATA1"),
- @ElementColumn(name="DATA2"),
- @ElementColumn(name="DATA3")
- })
- private Collection<InfoStruct> secondaryInfoStructs;
-
- ...
-}
-</programlisting>
- </example>
</section>
</section>
</section>
@@ -3469,7 +3074,7 @@
OpenJPA's <link linkend="openjpa.OrphanedKeyAction"><literal>
openjpa.OrphanedKeyAction</literal></link> configuration property controls what
action to take when OpenJPA encounters an orphaned key. You can set this plugin
-string (see <xref linkend="ref_guide_conf_plugins"></xref>) to a custom
+string (see <xref linkend="ref_guide_conf_plugins"/>) to a custom
implementation of the
<ulink url="../apidocs/org/apache/openjpa/event/OrphanedKeyAction.html">
<classname> org.apache.openjpa.event.OrphanedKeyAction</classname></ulink>
Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_meta.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_meta.xml?view=diff&rev=440775&r1=440774&r2=440775
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_meta.xml (original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_meta.xml Wed Sep 6 09:35:03 2006
@@ -3,8 +3,8 @@
Metadata
</title>
<para>
-The JPA Overview covers JPA metadata in <xref linkend="jpa_overview_meta">
-</xref>. 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">
-</xref>) 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"></xref> ). OpenJPA recognizes the
+<xref linkend="ref_guide_mapping_factory"/> ). OpenJPA recognizes the
following built-in metadata factories:
</para>
<itemizedlist>
@@ -48,7 +48,7 @@
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"></xref> for a
+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>
@@ -112,8 +112,8 @@
<para>
This section describes OpenJPA's core additions to standard entity metadata. We
present the object-relational mapping syntax to support these additions in
-<xref linkend="ref_guide_mapping_jpa"></xref>. Finally,
-<xref linkend="ref_guide_meta_ext"></xref> covers additional extensions to JPA
+<xref linkend="ref_guide_mapping_jpa"/>. Finally,
+<xref linkend="ref_guide_meta_ext"/> covers additional extensions to JPA
metadata that allow you to access auxiliary OpenJPA features.
</para>
<section id="ref_guide_meta_jpa_datastoreid">
@@ -133,9 +133,9 @@
to act as primary keys. OpenJPA, however, can create and maintain a surrogate
primary key value when you do not declare any <literal>Id</literal> fields. This
form of persistent identity is called <emphasis>datastore identity</emphasis>.
-<xref linkend="ref_guide_pc_oid"></xref> discusses OpenJPA's support for
+<xref linkend="ref_guide_pc_oid"/> discusses OpenJPA's support for
datastore identity in JPA. We cover how to map your datastore identity primary
-key column in <xref linkend="ref_guide_mapping_jpa_datastoreid"></xref>
+key column in <xref linkend="ref_guide_mapping_jpa_datastoreid"/>
</para>
</section>
<section id="ref_guide_meta_jpa_version">
@@ -154,7 +154,7 @@
Just as OpenJPA can maintain your entity's identity without any <literal>Id
</literal> fields, OpenJPA can maintain your entity's optimistic version without
any <literal>Version</literal> fields.
-<xref linkend="ref_guide_mapping_jpa_version"></xref> shows you how to map
+<xref linkend="ref_guide_mapping_jpa_version"/> shows you how to map
surrogate version columns.
</para>
</section>
@@ -222,8 +222,8 @@
Though you can use the <classname>Persistent</classname> annotation in place of
most of the standard direct field annotations mentioned above, we recommend
primarily using it for non-standard and custom types for which no standard JPA
-annotation exists. For example, <xref linkend="ref_guide_mapping_jpa_columns">
-</xref> demonstrates the use of the <classname>Persistent</classname> annotation
+annotation exists. For example, <xref linkend="ref_guide_mapping_jpa_columns"/>
+ demonstrates the use of the <classname>Persistent</classname> annotation
to denote a persistent <classname>java.awt.Point</classname> field.
</para>
</section>
@@ -295,7 +295,7 @@
</listitem>
</itemizedlist>
<para>
-<xref linkend="ref_guide_mapping_jpa_coll"></xref> contains several examples of
+<xref linkend="ref_guide_mapping_jpa_coll"/> contains several examples of
using <classname>PersistentCollection</classname> to mark non-standard
collection fields persistent.
</para>
@@ -376,7 +376,7 @@
<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"></xref> contains several
+objects. <xref linkend="ref_guide_mapping_jpa_map"/> contains several
examples of using <classname>PersistentMap</classname> to annotate persistent
map fields.
</para>
@@ -397,7 +397,7 @@
<para>
OpenJPA extends standard metadata to allow you to access advanced OpenJPA
functionality. This section covers persistence metadata extensions; we discuss
-mapping metadata extensions in <xref linkend="ref_guide_mapping_ext"></xref>.
+mapping metadata extensions in <xref linkend="ref_guide_mapping_ext"/>.
All metadata extensions are optional; OpenJPA will rely on its defaults when no
explicit data is provided.
</para>
@@ -432,8 +432,8 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroup.html">
<classname>org.apache.openjpa.persistence.FetchGroup</classname></ulink>
annotations allow you to define fetch groups in your JPA entities.
-<xref linkend="ref_guide_fetch"></xref> discusses OpenJPA's support for fetch
-groups in general; see <xref linkend="ref_guide_fetch_custom"></xref> for how to
+<xref linkend="ref_guide_fetch"/> discusses OpenJPA's support for fetch
+groups in general; see <xref linkend="ref_guide_fetch_custom"/> for how to
use these annotations in particular.
</para>
</section>
@@ -456,7 +456,7 @@
</seealso>
</indexterm>
<para>
-<xref linkend="ref_guide_cache"></xref> examines caching in OpenJPA. Metadata
+<xref linkend="ref_guide_cache"/> examines caching in OpenJPA. Metadata
extensions allow individual classes to override system caching defaults.
</para>
<para>
@@ -540,7 +540,7 @@
<para>
The OpenJPA <link linkend="ref_guide_pc_enhance">enhancer</link> may add a
synthetic field to detachable classes to hold detached state (see
-<xref linkend="ref_guide_detach_graph"></xref> for details). You can instead
+<xref linkend="ref_guide_detach_graph"/> for details). You can instead
declare your own detached state field or supress the creation of a detached
state field altogether. In the latter case, your class must not use
<link linkend="ref_guide_pc_oid">datastore identity</link>, and should declare
@@ -590,7 +590,7 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroups.html">
<classname>org.apache.openjpa.persistence.LockGroups</classname></ulink>
annotation accepts an array of lock group names.</phrase> For details on lock
-groups, see <xref linkend="ref_guide_lock_groups_and_subclasses"></xref>.
+groups, see <xref linkend="ref_guide_lock_groups_and_subclasses"/>.
</para>
</section>
<section id="auditable">
@@ -688,7 +688,7 @@
org.apache.openjpa.persistence.LRS</classname></ulink> annotation,</phrase>
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"></xref>.
+in <xref linkend="ref_guide_pc_scos_proxy_lrs"/>.
</para>
</section>
<section id="order-by">
@@ -707,7 +707,7 @@
</tertiary>
</indexterm>
<para>
-<phrase> The JPA Overview's <xref linkend="jpa_overview_meta_orderby"></xref>
+<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:
@@ -775,7 +775,7 @@
<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
-extension in detail in <xref linkend="ref_guide_inverses"></xref>.
+extension in detail in <xref linkend="ref_guide_inverses"/>.
</para>
</section>
<section id="lock-group">
@@ -802,8 +802,8 @@
<classname>org.apache.openjpa.persistence.LockGroup</classname></ulink>
annotation</phrase> to name the lock group for a field. You can exclude a field
from optimistic locking with a value of <literal>none</literal>. We discuss
-lock groups and this extension further in <xref linkend="ref_guide_lock_groups">
-</xref>.
+lock groups and this extension further in <xref linkend="ref_guide_lock_groups"/>
+.
</para>
</section>
<section id="read-only">
@@ -930,7 +930,7 @@
</para>
<para>
This extension is also used with OpenJPA's externalization feature, described in
-<xref linkend="ref_guide_pc_extern"></xref>.
+<xref linkend="ref_guide_pc_extern"/>.
</para>
<para>
OpenJPA defines the following type annotations for field values, collection,
@@ -980,7 +980,7 @@
<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
-another type. See <xref linkend="ref_guide_pc_extern"></xref> for details.
+another type. See <xref linkend="ref_guide_pc_extern"/> for details.
</para>
</section>
<section id="factory">
@@ -1006,7 +1006,7 @@
<ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>
org.apache.openjpa.persistence.Factory</classname></ulink> annotation</phrase>
names a method to re-create a field value from its externalized form. See
-<xref linkend="ref_guide_pc_extern"></xref> for details.
+<xref linkend="ref_guide_pc_extern"/> for details.
</para>
</section>
<section id="external-values">
@@ -1033,7 +1033,7 @@
<classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
annotation</phrase> declares values for transformation of simple fields to
different constant values in the datastore. See
-<xref linkend="ref_guide_pc_extern_values"></xref> for details.
+<xref linkend="ref_guide_pc_extern_values"/> for details.
</para>
</section>
</section>
Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_optimization.xml?view=diff&rev=440775&r1=440774&r2=440775
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_optimization.xml (original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_optimization.xml Wed Sep 6 09:35:03 2006
@@ -36,10 +36,10 @@
Optimization Guidelines
</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colname="name">
- </colspec>
- <colspec colname="desc" colwidth="4*">
- </colspec>
+ <colspec colname="name"/>
+
+ <colspec colname="desc" colwidth="4*"/>
+
<tbody valign="top">
<row>
<entry colname="name">
@@ -533,7 +533,7 @@
Attaching and even persisting instances can be more efficient when your detached
objects use detached state managers. By default, OpenJPA does not use detached
state managers when serializing an instance across tiers. See
-<xref linkend="ref_guide_detach_graph"></xref> for how to force OpenJPA to use
+<xref linkend="ref_guide_detach_graph"/> for how to force OpenJPA to use
detached state managers across tiers, and for other options for more efficient
attachment.
</para>
Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml?view=diff&rev=440775&r1=440774&r2=440775
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml (original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_pc.xml Wed Sep 6 09:35:03 2006
@@ -8,7 +8,7 @@
</primary>
</indexterm>
<para>
-Persistent class basics are covered in <xref linkend="jpa_overview_pc"></xref>
+Persistent class basics are covered in <xref linkend="jpa_overview_pc"/>
of the JPA Overview. This chapter details the persistent class features OpenJPA
offers beyond the core JPA specification.
</para>
@@ -57,7 +57,7 @@
<listitem>
<para>
If you configure OpenJPA to create the needed database schema on startup (see
-<xref linkend="ref_guide_mapping_synch"></xref> ), OpenJPA must know all of your
+<xref linkend="ref_guide_mapping_synch"/> ), OpenJPA must know all of your
persistent classes up-front.
</para>
</listitem>
@@ -66,7 +66,7 @@
When any of these conditions are a factor in your JPA application, use the
<literal>class</literal>, <literal> mapping-file</literal>, and <literal>
jar-file</literal> elements of JPA's standard XML format to list your persistent
-classes. See <xref linkend="jpa_overview_persistence_xml"></xref> for details.
+classes. See <xref linkend="jpa_overview_persistence_xml"/> for details.
</para>
<note>
<para>
@@ -113,8 +113,8 @@
<mediaobject>
<imageobject>
<!-- PNG image data, 509 x 133 (see README) -->
- <imagedata fileref="img/enhancement.png" width="339px">
- </imagedata>
+ <imagedata fileref="img/enhancement.png" width="339px"/>
+
</imageobject>
</mediaobject>
<para>
@@ -144,8 +144,8 @@
</para>
<note>
<para>
-You can also enhance via Ant; see <xref linkend="ref_guide_integration_enhance">
-</xref>.
+You can also enhance via Ant; see <xref linkend="ref_guide_integration_enhance"/>
+.
</para>
</note>
<example id="ref_guide_pc_enhance_enhancer">
@@ -158,7 +158,7 @@
</example>
<para>
The enhancer accepts the standard set of command-line arguments defined by the
-configuration framework (see <xref linkend="ref_guide_conf_devtools"></xref> ),
+configuration framework (see <xref linkend="ref_guide_conf_devtools"/> ),
along with the following flags:
</para>
<itemizedlist>
@@ -218,8 +218,8 @@
</itemizedlist>
<para>
If you do not supply any arguments to the enhancer, it will run on the classes
-in your persistent class list (see <xref linkend="ref_guide_pc_pcclasses">
-</xref> ).
+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
@@ -296,8 +296,8 @@
<para>
Searching for metadata for every class loaded by the JVM can slow application
initialization. One way to speed things up is to take advantage of the optional
-persistent class list described in <xref linkend="ref_guide_pc_pcclasses">
-</xref>. If you declare a persistent class list, OpenJPA will only search for
+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>
@@ -315,12 +315,12 @@
</example>
<para>
You can pass settings to the agent using OpenJPA's plugin syntax (see
-<xref linkend="ref_guide_conf_plugins"></xref> ). The agent accepts the long
+<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"></xref> ). It also accepts the following
+<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"></xref>:
+<xref linkend="ref_guide_pc_enhance_build"/>:
</para>
<itemizedlist>
<listitem>
@@ -386,7 +386,7 @@
between a server using OpenJPA and a client that does not have access to
enhanced classes or OpenJPA libraries. In some cases, however, you can make the
persist and attach processes more robust and efficient by allowing breaks in
-serialization compatibility. See <xref linkend="ref_guide_detach_graph"></xref>
+serialization compatibility. See <xref linkend="ref_guide_detach_graph"/>
for details.
</para>
</section>
@@ -416,12 +416,12 @@
annotation. This annotation has <literal>strategy</literal> and <literal>
generator</literal> properties that mirror the same-named properties on the
standard <classname>javax.persistence.GeneratedValue</classname> annotation
-described in <xref linkend="jpa_overview_meta_id"></xref> of the JPA Overview.
+described in <xref linkend="jpa_overview_meta_id"/> of the JPA Overview.
</para>
<para>
To retrieve the identity value of a datastore identity entity, use the
<methodname>OpenJPAEntityManager.getObjectId (Object entity)</methodname>
-method. See <xref linkend="ref_guide_runtime_em"></xref> for more information on
+method. See <xref linkend="ref_guide_runtime_em"/> for more information on
the <classname>OpenJPAEntityManager</classname>.
</para>
<example id="ref_guide_pc_oid_datastoreentityex">
@@ -520,7 +520,7 @@
</para>
<note>
<para>
-<xref linkend="ref_guide_integration_appidtool"></xref> describes the
+<xref linkend="ref_guide_integration_appidtool"/> describes the
application identity tool's Ant task.
</para>
</note>
@@ -535,8 +535,8 @@
<para>
The application identity tool accepts the standard set of command-line arguments
defined by the configuration framework (see
-<xref linkend="ref_guide_conf_devtools"></xref> ), including code formatting
-flags described in <xref linkend="ref_guide_conf_devtools_format"></xref>. It
+<xref linkend="ref_guide_conf_devtools"/> ), including code formatting
+flags described in <xref linkend="ref_guide_conf_devtools_format"/>. It
also accepts the following arguments:
</para>
<itemizedlist>
@@ -606,7 +606,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"></xref>
+your persistent classes list (see <xref linkend="ref_guide_pc_pcclasses"/>
).
</para>
</section>
@@ -639,7 +639,7 @@
</secondary>
</indexterm>
<para>
-<xref linkend="jpa_overview_meta_gen"></xref> explains how to use JPA's
+<xref linkend="jpa_overview_meta_gen"/> explains how to use JPA's
<literal>IDENTITY</literal> generation type to automatically assign field
values. However, here are some additional caveats you should be aware of when
using <literal>IDENTITY</literal> generation:
@@ -648,7 +648,7 @@
<listitem>
<para>
Your database must support auto-increment / identity columns, or some equivalent
-(see <xref linkend="ref_guide_dbsetup_dbsupport_oracle"></xref> for how to
+(see <xref linkend="ref_guide_dbsetup_dbsupport_oracle"/> for how to
configure a combination of triggers and sequences to fake auto-increment support
in Oracle).
</para>
@@ -692,7 +692,7 @@
</indexterm>
<para>
Bidirectional relations are an essential part of data modeling.
-<xref linkend="jpa_overview_mapping"></xref> in the JPA Overview explains how to
+<xref linkend="jpa_overview_mapping"/> in the JPA Overview explains how to
use the <literal>mappedBy</literal> annotation attribute to form bidirectional
relations that also share datastore storage in JPA.
</para>
@@ -1072,8 +1072,8 @@
</listitem>
<listitem>
<para>
-The field cannot have an externalizer (see <xref linkend="ref_guide_pc_extern">
-</xref> ).
+The field cannot have an externalizer (see <xref linkend="ref_guide_pc_extern"/>
+ ).
</para>
</listitem>
<listitem>
@@ -1229,10 +1229,10 @@
Externalizer Options
</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colname="method">
- </colspec>
- <colspec colname="extension">
- </colspec>
+ <colspec colname="method"/>
+
+ <colspec colname="extension"/>
+
<thead>
<row>
<entry colname="method">
@@ -1335,10 +1335,10 @@
Factory Options
</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colname="method">
- </colspec>
- <colspec colname="extension">
- </colspec>
+ <colspec colname="method"/>
+
+ <colspec colname="extension"/>
+
<thead>
<row>
<entry colname="method">
@@ -1451,7 +1451,7 @@
field dirty manually in JPA.</phrase>
</para>
<para>
-See <xref linkend="ref_guide_pc_scos_proxy"></xref> for a discussion of proxies.
+See <xref linkend="ref_guide_pc_scos_proxy"/> for a discussion of proxies.
</para>
</note>
<para>
@@ -1462,7 +1462,7 @@
complex as a collection or map of persistence-capable objects, 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"></xref>. If 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.
@@ -1637,7 +1637,7 @@
loading and eager fetching behavior.
</para>
<para>
-The JPA Overview's <xref linkend="jpa_overview_meta_fetch"></xref> describes how
+The JPA Overview's <xref linkend="jpa_overview_meta_fetch"/> describes how
to use JPA metadata annotations to control whether a field is fetched eagerly or
lazily. Fetch groups add a dynamic aspect to this standard ability. As you will
see, OpenJPA's JPA extensions allow you can add and remove fetch groups at
@@ -1831,7 +1831,7 @@
public void clearFetchGroups ();
</programlisting>
<para>
-<xref linkend="ref_guide_runtime"></xref> details the <classname>
+<xref linkend="ref_guide_runtime"/> details the <classname>
OpenJPAEntityManager</classname>, <classname>OpenJPAQuery</classname>, and
<classname>FetchPlan</classname> interfaces.
</para>
@@ -2002,7 +2002,7 @@
</para>
<para>
Eager fetching only affects relations in the fetch groups being loaded (see
-<xref linkend="ref_guide_fetch"></xref> ). In other words, relations that would
+<xref linkend="ref_guide_fetch"/> ). In other words, relations that would
not normally be loaded immediately when retrieving an object or accessing a
field are not affected by eager fetching. In our example above, the address of
each person would only be eagerly fetched if the query were configured to
@@ -2042,7 +2042,7 @@
Instead, OpenJPA defaults to <literal>parallel</literal> mode for collections,
as described below. You can force OpenJPA use a join rather than parallel mode
for a collection field using the metadata extension described in
-<xref linkend="eager-fetch-mode"></xref>.
+<xref linkend="eager-fetch-mode"/>.
</para>
<para>
<indexterm>
@@ -2072,8 +2072,8 @@
Some databases may not support UNIONs or 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">
-</xref>.
+<literal>traditional</literal>. See <xref linkend="ref_guide_dbsetup_sql92"/>
+.
</para>
</note>
</listitem>
@@ -2116,7 +2116,7 @@
Polymorphic to-one relations to table-per-class mappings use parallel eager
fetching because proper joins are impossible. You can force other to-one
relations to use parallel rather than join mode eager fetching using the
-metadata extension described in <xref linkend="eager-fetch-mode"></xref>.
+metadata extension described in <xref linkend="eager-fetch-mode"/>.
</para>
<para>
Setting your subclass fetch mode to <literal>parallel</literal> affects
@@ -2196,7 +2196,7 @@
<para>
You can easily override the default fetch modes at runtime for any lookup or
query through OpenJPA's fetch configuration APIs. See
-<xref linkend="ref_guide_runtime"></xref> for details.
+<xref linkend="ref_guide_runtime"/> for details.
</para>
<example id="ref_guide_perfpack_eager_def">
<title>
@@ -2227,14 +2227,14 @@
</example>
<para>
You can specify a default subclass fetch mode for an individual class with the
-metadata extension described in <xref linkend="subclass-fetch-mode"></xref>.
+metadata extension described in <xref linkend="subclass-fetch-mode"/>.
Note, however, that you cannot "upgrade" the runtime fetch mode with your class
setting. If the runtime fetch mode is <literal>none</literal>, no eager
subclass data fetching will take place, regardless of your metadata setting.
</para>
<para>
This applies to the eager fetch mode metadata extension as well (see
-<xref linkend="eager-fetch-mode"></xref> ). 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
@@ -2269,7 +2269,7 @@
</secondary>
</indexterm>
When you are using <literal>parallel</literal> eager fetch mode and you have
-large result sets enabled (see <xref linkend="ref_guide_dbsetup_lrs"></xref>)
+large result sets enabled (see <xref linkend="ref_guide_dbsetup_lrs"/>)
or you place a range on a query, OpenJPA performs the needed parallel selects on
one page of results at a time. For example, suppose your <literal>
FetchBatchSize</literal> is set to 20, and you perform a large result set query
@@ -2316,7 +2316,7 @@
<para>
OpenJPA cannot eagerly join to polymorphic relations to non-leaf classes in a
table-per-class inheritance hierarchy. You can work around this restriction
-using the mapping extensions described in <xref linkend="nonpolymorphic"></xref>
+using the mapping extensions described in <xref linkend="nonpolymorphic"/>
.
</para>
</listitem>
@@ -2374,7 +2374,7 @@
<phrase> You specify a field's lock group in JPA metadata with the
<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroup.html">
<classname>org.apache.openjpa.persistence.LockGroup</classname></ulink>
-annotation.</phrase> See <xref linkend="lock-group"></xref> for details on lock
+annotation.</phrase> See <xref linkend="lock-group"/> for details on lock
group metadata.
</para>
<example id="ref_guide_lock_groups_metadata">
Modified: incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml?view=diff&rev=440775&r1=440774&r2=440775
==============================================================================
--- incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml (original)
+++ incubator/openjpa/sandboxes/OPENJPA-24/openjpa-project/src/doc/manual/ref_guide_remote.xml Wed Sep 6 09:35:03 2006
@@ -53,7 +53,7 @@
</indexterm>
<para>
The JPA Overview describes the specification's standard detach and attach APIs
-in <xref linkend="jpa_overview_em_lifecycle"></xref>. This section enumerates
+in <xref linkend="jpa_overview_em_lifecycle"/>. This section enumerates
OpenJPA's enhancements to the standard behavior.
</para>
<section id="ref_guide_detach_behavior">
@@ -223,7 +223,7 @@
<literal>fgs</literal>: Detach all fields and relations in the default fetch
group, and any other fetch groups that you have added to the current
<link linkend="ref_guide_runtime">fetch configuration</link>. For more
-information on custom fetch groups, see <xref linkend="ref_guide_fetch"></xref>
+information on custom fetch groups, see <xref linkend="ref_guide_fetch"/>
.
</para>
</listitem>
@@ -241,14 +241,14 @@
</para>
<para>
The <literal>openjpa.DetachState</literal> option is actually a plugin string
-(see <xref linkend="ref_guide_conf_plugins"></xref>) that allows you to also
+(see <xref linkend="ref_guide_conf_plugins"/>) that allows you to also
configure the following options related to detached state:
</para>
<itemizedlist>
<listitem>
<para>
<literal>DetachedStateField</literal>: As described in
-<xref linkend="ref_guide_attach_behavior"></xref> above, OpenJPA can take
+<xref linkend="ref_guide_attach_behavior"/> above, OpenJPA can take
advantage of a <emphasis>detached state field</emphasis> to make the attach
process more efficient. This field is added by the enhancer and is not visible
to your application. Set this property to one of the following values:
@@ -279,7 +279,7 @@
<para>
You can override the setting of this property or declare your own detached state
field on individual classes using OpenJPA's metadata extensions. See
-<xref linkend="ref_guide_detach_field"></xref> below.
+<xref linkend="ref_guide_detach_field"/> below.
</para>
</listitem>
<listitem>
@@ -357,7 +357,7 @@
field in your class metadata prevents the enhancer from adding any extra fields
to the class, and keeps the enhanced class serialization-compatible with the
unenhanced version. The detached state field must not be persistent. See
-<xref linkend="detached-state-field"></xref> for details on how to declare a
+<xref linkend="detached-state-field"/> for details on how to declare a
detached state field.
</para>
<programlisting>
@@ -423,7 +423,7 @@
</indexterm>
The remote event notification framework allows a subset of the information
available through OpenJPA's transaction events (see
-<xref linkend="ref_guide_runtime_pm_event"></xref>) to be broadcast to remote
+<xref linkend="ref_guide_runtime_pm_event"/>) to be broadcast to remote
listeners. OpenJPA's <link linkend="ref_guide_cache">data cache</link>, for
example, uses remote events to remain synchronized when deployed in multiple
JVMs.
@@ -586,7 +586,7 @@
transactions is a function of the size of the connection pool. See the the
<literal>MaxActive</literal> property of <literal>
openjpa.ConnectionFactoryProperties</literal> in
-<xref linkend="ref_guide_dbsetup_builtin"></xref>. Setting a value of 0 will
+<xref linkend="ref_guide_dbsetup_builtin"/>. Setting a value of 0 will
result in behavior where the thread invoking <methodname>commit</methodname>
will perform the broadcast directly. Defaults to 2.
</para>