You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by st...@apache.org on 2015/06/01 22:19:02 UTC
svn commit: r953480 [32/37] - in
/websites/production/openjpa/content/builds/2.4.0: ./ apache-openjpa/
apache-openjpa/docs/
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_mapping_notes_nonstdjoins.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_mapping_notes_nonstdjoins.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_mapping_notes_nonstdjoins.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,131 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>6. Non-Standard Joins</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_mapping.html" title="Chapter 7. Mapping"><link rel="prev" href="ref_guide_mapping_factory.html" title="5. Mapping Factory"><link rel="next" href="ref_guide_mapping_jpa.html" title="7. Additional JPA Mappings"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6.
+ Non-Standard Joins
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping_factory.html">Prev</a> </td><th width="60%" align="center">Chapter 7.
+ Mapping
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_mapping_jpa.html">Next</a></td></tr></table><hr></div><div class="section" title="6. Non-Standard Joins"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_mapping_notes_nonstdjoins">6.
+ Non-Standard Joins
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e14149"></a>
+ <p>
+The JPA Overview's <a class="xref" href="jpa_overview_mapping.html" title="Chapter 13. Mapping Metadata">Chapter 13, <i>
+ Mapping Metadata
+ </i></a> 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
+joins, non-primary key joins, and joins using constant values.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e14155"></a>
+In a partial primary key join, the source table only has foreign key columns for
+a subset of the primary key columns in the target table. So long as this subset
+of columns correctly identifies the proper row(s) in the referenced table,
+OpenJPA will function properly. There is no special syntax for expressing a
+partial primary key join - just do not include column definitions for missing
+foreign key columns.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e14159"></a>
+In a non-primary key join, at least one of the target columns is not a primary
+key. Once again, OpenJPA supports this join type with the same syntax as a
+primary key join. There is one restriction, however: each non-primary key column
+you are joining to must be controlled by a field mapping that implements the
+<a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/meta/Joinable.html" target="_top"><code class="classname">
+org.apache.openjpa.jdbc.meta.Joinable</code></a> 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 <a class="xref" href="ref_guide_mapping_custom.html" title="10. Custom Mappings">Section 10, “
+ Custom Mappings
+ ”</a> for an
+examination of custom mappings.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e14166"></a>
+Not all joins consist of only links between columns. In some cases you might
+have a schema in which one of the join criteria is that a column in the source
+or target table must have some constant value. OpenJPA calls joins involving
+constant values <span class="emphasis"><em>constant joins</em></span>.
+ </p>
+ <p>
+To form a constant join in JPA mapping, first set the <code class="literal">JoinColumn
+</code>'s <code class="literal">name</code> attribute to the name of the column. If the
+column with the constant value is the target of the join, give its fully
+qualified name in the form <code class="literal"><table name>.<column name>
+</code>. Next, set the <code class="literal">referencedColumnName</code> attribute to
+the constant value. If the constant value is a string, place it in single quotes
+to differentiate it from a column name.
+ </p>
+ <div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="285"><tr><td><img src="img/joins-constant.png"></td></tr></table></div>
+ <p>
+Consider the tables above. First, we want to join row <code class="literal">T1.R1</code>
+to row <code class="literal">T2.R1</code>. If we just join column <code class="literal">T1.FK</code>
+to <code class="literal">T2.PK1</code>, we will wind up matching both <code class="literal">T2.R1
+</code> and <code class="literal"> T2.R2</code>. So in addition to joining <code class="literal">
+T1.FK</code> to <code class="literal">T2.PK1</code>, we also have to specify that
+<code class="literal">T2.PK2</code> has the value <code class="literal">a</code>. Here is how we'd
+accomplish this in mapping metadata.
+ </p>
+<pre class="programlisting">
+@Entity
+@Table(name="T1")
+public class ... {
+
+ @ManyToOne
+ @JoinColumns({
+ @JoinColumn(name="FK" referencedColumnName="PK1"),
+ @JoinColumn(name="T2.PK2" referencedColumnName="'a'")
+ });
+ private ...;
+}
+</pre>
+ <p>
+Notice that we had to fully qualify the name of column <code class="literal">PK2</code>
+because it is in the target table. Also notice that we put single quotes around
+the constant value so that it won't be confused with a column name. You do not
+need single quotes for numeric constants. For example, the syntax to join
+<code class="literal">T1.R2</code> to <code class="literal">T2.R4</code> is:
+ </p>
+<pre class="programlisting">
+@Entity
+@Table(name="T1")
+public class ... {
+
+ @ManyToOne
+ @JoinColumns({
+ @JoinColumn(name="FK" referencedColumnName="PK2"),
+ @JoinColumn(name="T2.PK1" referencedColumnName="2")
+ });
+ private ...;
+}
+</pre>
+ <p>
+Finally, from the inverse direction, these joins would look like this:
+ </p>
+<pre class="programlisting">
+@Entity
+@Table(name="T2")
+public class ... {
+
+ @ManyToOne
+ @JoinColumns({
+ @JoinColumn(name="T1.FK" referencedColumnName="PK1"),
+ @JoinColumn(name="PK2" referencedColumnName="'a'")
+ });
+ private ...;
+
+ @ManyToOne
+ @JoinColumns({
+ @JoinColumn(name="T1.FK" referencedColumnName="PK2"),
+ @JoinColumn(name="PK1" referencedColumnName="2")
+ });
+ private ...;
+}
+</pre>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_mapping_factory.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_mapping_jpa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.
+ Mapping Factory
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 7.
+ Additional JPA Mappings
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_mapping_notes_nonstdjoins.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,149 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 6. Metadata</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_perfpack_eager.html" title="8. Eager Fetching"><link rel="next" href="ref_guide_meta_repository.html" title="2. Metadata Repository"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6.
+ Metadata
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_perfpack_eager.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_meta_repository.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 6. Metadata" id="ref_guide_meta"><div class="titlepage"><div><div><h2 class="title">Chapter 6.
+ Metadata
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_meta.html#ref_guide_meta_factory">1.
+ Metadata Factory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_repository.html">2. Metadata Repository</a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html">3.
+ Additional JPA Metadata
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_datastoreid">3.1.
+ Datastore Identity
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_version">3.2.
+ Surrogate Version
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent">3.3.
+ Persistent Field Values
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_meta_ext.html">4.
+ Metadata Extensions
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_class">4.1.
+ Class Extensions
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#fetch-groups">4.1.1.
+ Fetch Groups
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#data-cache">4.1.2.
+ Data Cache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#detached-state-field">4.1.3.
+ Detached State
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_field">4.2.
+ Field Extensions
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#dependent">4.2.1.
+ Dependent
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#load-fetch-group">4.2.2.
+ Load Fetch Group
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#lrs">4.2.3.
+ LRS
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#inverse-logical">4.2.4.
+ Inverse-Logical
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#read-only">4.2.5.
+ Read-Only
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#type">4.2.6.
+ Type
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#externalizer">4.2.7.
+ Externalizer
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#factory">4.2.8.
+ Factory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#external-values">4.2.9.
+ External Values
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_example">4.3.
+ Example
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_xml">4.4.
+ XML extensions
+ </a></span></dt></dl></dd></dl></div>
+
+ <p>
+The JPA Overview covers JPA metadata in <a class="xref" href="jpa_overview_meta.html" title="Chapter 5. Metadata">Chapter 5, <i>
+ Metadata
+ </i></a>.
+This chapter discusses OpenJPA's extensions to standard JPA metadata.
+ </p>
+ <div class="section" title="1. Metadata Factory"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_meta_factory">1.
+ Metadata Factory
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e13076"></a>
+ <p>
+The <a class="link" href="ref_guide_conf_openjpa.html#openjpa.MetaDataFactory" title="5.48. openjpa.MetaDataFactory"><code class="literal">openjpa.MetaDataFactory
+</code></a> configuration property controls metadata loading and storing.
+This property takes a plugin string (see
+<a class="xref" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">Section 4, “
+ Plugin Configuration
+ ”</a>) describing a concrete
+<a class="ulink" href="../javadoc/org/apache/openjpa/meta/MetaDataFactory.html" target="_top">
+<code class="classname">org.apache.openjpa.meta.MetaDataFactory</code></a>
+implementation. A metadata factory can load mapping information as well as
+persistence metadata, or it can leave mapping information to a separate
+<span class="emphasis"><em>mapping factory</em></span> (see
+<a class="xref" href="ref_guide_mapping_factory.html" title="5. Mapping Factory">Section 5, “
+ Mapping Factory
+ ”</a>). OpenJPA recognizes the
+following built-in metadata factories:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">jpa</code>: Standard JPA metadata. This is an alias for the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html" target="_top">
+<code class="classname">
+org.apache.openjpa.persistence.PersistenceMetaDataFactory</code></a>.
+ </p>
+ </li></ul></div>
+ <p>
+JPA has built-in settings for listing your persistent classes, which
+the <a class="link" href="jpa_overview_persistence.html#jpa_overview_persistence_xml" title="1. persistence.xml">JPA Overview</a> 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
+<a class="xref" href="ref_guide_pc.html#ref_guide_pc_pcclasses" title="1. Persistent Class List">Section 1, “
+ Persistent Class List
+ ”</a> for a discussion of when it is
+necessary to list your persistent classes.
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">Types</code>: A semicolon-separated list of fully-qualified
+persistent class names.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">Resources</code>: A semicolon-separated list of resource paths to
+metadata files or jar archives. Each jar archive will be scanned for
+annotated JPA entities.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">URLs</code>: A semicolon-separated list of URLs of metadata files
+or jar archives. Each jar archive will be scanned for annotated JPA
+entities.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">ClasspathScan</code>: A semicolon-separated list of directories or
+jar archives listed in your classpath. Each directory and jar archive will be
+scanned for annotated JPA entities.
+ </p>
+ </li></ul></div>
+ <div class="example"><a name="ref_guide_meta_stdfactoryex"></a><p class="title"><b>Example 6.1.
+ Setting a Standard Metadata Factory
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.MetaDataFactory" value="jpa(ClasspathScan=build;lib.jar)"/>
+</pre>
+ </div></div><br class="example-break">
+ <div class="example"><a name="ref_guide_meta_customfactoryex"></a><p class="title"><b>Example 6.2.
+ Setting a Custom Metadata Factory
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.MetaDataFactory" value="com.xyz.CustomMetaDataFactory"/>
+</pre>
+ </div></div><br class="example-break">
+ </div>
+
+
+
+
+
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_perfpack_eager.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_meta_repository.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.
+ Eager Fetching
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. Metadata Repository</td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_ext.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_ext.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_ext.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,540 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>4. Metadata Extensions</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_meta.html" title="Chapter 6. Metadata"><link rel="prev" href="ref_guide_meta_jpa.html" title="3. Additional JPA Metadata"><link rel="next" href="ref_guide_mapping.html" title="Chapter 7. Mapping"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.
+ Metadata Extensions
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_meta_jpa.html">Prev</a> </td><th width="60%" align="center">Chapter 6.
+ Metadata
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_mapping.html">Next</a></td></tr></table><hr></div><div class="section" title="4. Metadata Extensions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_meta_ext">4.
+ Metadata Extensions
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_class">4.1.
+ Class Extensions
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#fetch-groups">4.1.1.
+ Fetch Groups
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#data-cache">4.1.2.
+ Data Cache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#detached-state-field">4.1.3.
+ Detached State
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_field">4.2.
+ Field Extensions
+ </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#dependent">4.2.1.
+ Dependent
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#load-fetch-group">4.2.2.
+ Load Fetch Group
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#lrs">4.2.3.
+ LRS
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#inverse-logical">4.2.4.
+ Inverse-Logical
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#read-only">4.2.5.
+ Read-Only
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#type">4.2.6.
+ Type
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#externalizer">4.2.7.
+ Externalizer
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#factory">4.2.8.
+ Factory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#external-values">4.2.9.
+ External Values
+ </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_example">4.3.
+ Example
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#ref_guide_meta_xml">4.4.
+ XML extensions
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e13277"></a>
+ <p>
+OpenJPA extends standard metadata to allow you to access advanced OpenJPA
+functionality. This section covers persistence metadata extensions; we discuss
+mapping metadata extensions in <a class="xref" href="ref_guide_mapping_ext.html" title="9. Mapping Extensions">Section 9, “
+ Mapping Extensions
+ ”</a>.
+All metadata extensions are optional; OpenJPA will rely on its defaults when no
+explicit data is provided.
+ </p>
+ <div class="section" title="4.1. Class Extensions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_class">4.1.
+ Class Extensions
+ </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#fetch-groups">4.1.1.
+ Fetch Groups
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#data-cache">4.1.2.
+ Data Cache
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#detached-state-field">4.1.3.
+ Detached State
+ </a></span></dt></dl></div>
+
+ <p>
+OpenJPA recognizes the following class extensions:
+ </p>
+ <div class="section" title="4.1.1. Fetch Groups"><div class="titlepage"><div><div><h4 class="title" id="fetch-groups">4.1.1.
+ Fetch Groups
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13287"></a>
+ <p>
+The <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/FetchGroups.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.FetchGroups</code></a> and
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/FetchGroup.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.FetchGroup</code></a>
+annotations allow you to define fetch groups in your JPA entities.
+<a class="xref" href="ref_guide_fetch.html" title="7. Fetch Groups">Section 7, “
+ Fetch Groups
+ ”</a> discusses OpenJPA's support for fetch
+groups in general; see <a class="xref" href="ref_guide_fetch.html#ref_guide_fetch_custom" title="7.1. Custom Fetch Groups">Section 7.1, “
+ Custom Fetch Groups
+ ”</a> for how to
+use these annotations in particular.
+ </p>
+ </div>
+ <div class="section" title="4.1.2. Data Cache"><div class="titlepage"><div><div><h4 class="title" id="data-cache">4.1.2.
+ Data Cache
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13301"></a>
+ <p>
+<a class="xref" href="ref_guide_caching.html#ref_guide_cache" title="1. Data Cache">Section 1, “
+ Data Cache
+ ”</a> examines caching in OpenJPA. Metadata
+extensions allow individual classes to override system caching defaults.
+ </p>
+ <p>
+OpenJPA defines the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/DataCache.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.DataCache</code></a>
+annotation for caching information. This annotation has the following
+properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">boolean enabled</code>: Whether to cache data for instances of the
+class. Defaults to <code class="literal">true</code> for base classes, or the superclass
+value for subclasses. If you set this property to <code class="literal">false</code>, all
+other properties are ignored.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">int timeout</code>: The number of milliseconds data for the class
+remains valid. Use -1 for no timeout. Defaults to the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.DataCacheTimeout" title="5.29. openjpa.DataCacheTimeout"><code class="literal"> openjpa.DataCacheTimeout
+</code></a> property value.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="4.1.3. Detached State"><div class="titlepage"><div><div><h4 class="title" id="detached-state-field">4.1.3.
+ Detached State
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13324"></a>
+ <p>
+The OpenJPA <a class="link" href="ref_guide_pc_enhance.html" title="2. Enhancement">enhancer</a> may add a
+synthetic field to detachable classes to hold detached state (see
+<a class="xref" href="ref_guide_remote.html#ref_guide_detach_graph" title="1.3. Defining the Detached Object Graph">Section 1.3, “
+ Defining the Detached Object Graph
+ ”</a> for details). You can instead
+declare your own detached state field or suppress the creation of a detached
+state field altogether. In the latter case, your class must not use
+<a class="link" href="ref_guide_pc_oid.html" title="4. Object Identity">datastore identity</a>, and should declare
+a version field to detect optimistic concurrency errors during detached
+modifications.
+ </p>
+ <p>
+OpenJPA defines the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/DetachedState.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.DetachedState</code></a>
+annotation for controlling detached state. When used to annotate a class,
+<code class="classname">DetachedState</code> recognizes the following properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">boolean enabled</code>: Set to false to suppress the use of
+detached state.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">String fieldName</code>: Use this property to declare your own
+detached state field. The field must be of type <code class="classname">Object</code>.
+Typically this property is only used if the field is inherited from a
+non-persisted superclass. If the field is declared in your entity class, you
+will typically annotate the field directly, as described below.
+ </p>
+ </li></ul></div>
+ <p>
+If you declare your own detached state field, you can annotate that field with
+<code class="classname">DetachedState</code> directly, rather than placing the
+annotation at the class level and using the <code class="literal">fieldName</code>
+property. When placed on a field, <code class="classname">DetachedState</code> acts as a
+marker annotation; it does not recognize any properties. Your annotated field
+must be of type <code class="classname">Object</code>.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="4.2. Field Extensions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_field">4.2.
+ Field Extensions
+ </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_meta_ext.html#dependent">4.2.1.
+ Dependent
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#load-fetch-group">4.2.2.
+ Load Fetch Group
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#lrs">4.2.3.
+ LRS
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#inverse-logical">4.2.4.
+ Inverse-Logical
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#read-only">4.2.5.
+ Read-Only
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#type">4.2.6.
+ Type
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#externalizer">4.2.7.
+ Externalizer
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#factory">4.2.8.
+ Factory
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_ext.html#external-values">4.2.9.
+ External Values
+ </a></span></dt></dl></div>
+
+ <p>
+OpenJPA recognizes the following field extensions:
+ </p>
+ <div class="section" title="4.2.1. Dependent"><div class="titlepage"><div><div><h4 class="title" id="dependent">4.2.1.
+ Dependent
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13355"></a>
+ <p>
+In a <span class="emphasis"><em>dependent</em></span> relation, the referenced object is deleted
+whenever the owning object is deleted, or whenever the relation is severed by
+nulling or resetting the owning field. For example, if the <code class="literal">
+Magazine.coverArticle</code> field is marked dependent, then setting
+<code class="literal">Magazine.coverArticle</code> to a new <code class="classname">Article</code>
+instance will automatically delete the old <code class="classname">Article</code> stored
+in the field. Similarly, deleting a <code class="classname">Magazine</code> object will
+automatically delete its current cover <code class="classname">Article</code>. (This
+latter processing is analogous to using JPA's CascadeType.REMOVE functionality
+as described in <a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_cascade" title="2.9.1. Cascade Type">Section 2.9.1, “
+ Cascade Type
+ ”</a>.) You can
+prevent an orphaned dependent object from being automatically deleted by
+assigning it to another relation in the same transaction.
+ </p>
+ <p>
+OpenJPA offers a family of marker annotations to denote dependent relations in
+JPA entities:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Dependent.html" target="_top">
+<code class="classname"> org.apache.openjpa.persistence.Dependent</code></a>: Marks
+a direct relation as dependent.
+ </p>
+ </li><li class="listitem">
+ <p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/ElementDependent.html" target="_top">
+<code class="classname"> org.apache.openjpa.persistence.ElementDependent</code></a>
+: Marks the entity elements of a collection, array, or map field as dependent.
+ </p>
+ </li><li class="listitem">
+ <p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/KeyDependent.html" target="_top">
+<code class="classname"> org.apache.openjpa.persistence.KeyDependent</code></a>:
+Marks the key entities in a map field as dependent.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="4.2.2. Load Fetch Group"><div class="titlepage"><div><div><h4 class="title" id="load-fetch-group">4.2.2.
+ Load Fetch Group
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13384"></a>
+ <a class="indexterm" name="d5e13388"></a>
+ <p>
+The <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/LoadFetchGroup.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.LoadFetchGroup</code></a>
+annotation specifies a field's load fetch group.
+<a class="xref" href="ref_guide_fetch.html" title="7. Fetch Groups">Section 7, “
+ Fetch Groups
+ ”</a> discusses OpenJPA's support for fetch groups
+in general; see <a class="xref" href="ref_guide_fetch.html#ref_guide_fetch_custom" title="7.1. Custom Fetch Groups">Section 7.1, “
+ Custom Fetch Groups
+ ”</a> for how to use this
+annotation in particular.
+ </p>
+ </div>
+ <div class="section" title="4.2.3. LRS"><div class="titlepage"><div><div><h4 class="title" id="lrs">4.2.3.
+ LRS
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13398"></a>
+ <p>
+This boolean extension, denoted by the OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/LRS.html" target="_top"><code class="classname">
+org.apache.openjpa.persistence.LRS</code></a> 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 <a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_lrs" title="6.4.2. Large Result Set Proxies">Section 6.4.2, “
+ Large Result Set Proxies
+ ”</a>.
+ </p>
+ </div>
+ <div class="section" title="4.2.4. Inverse-Logical"><div class="titlepage"><div><div><h4 class="title" id="inverse-logical">4.2.4.
+ Inverse-Logical
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13409"></a>
+ <p>
+This extension names the inverse field in a logical bidirectional relation.
+To create a logical bidirectional relation in OpenJPA, use the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/InverseLogical.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.InverseLogical</code></a>
+annotation. We discuss logical bidirectional relations and this
+extension in detail in <a class="xref" href="ref_guide_inverses.html" title="5. Managed Inverses">Section 5, “
+ Managed Inverses
+ ”</a>.
+ </p>
+ </div>
+ <div class="section" title="4.2.5. Read-Only"><div class="titlepage"><div><div><h4 class="title" id="read-only">4.2.5.
+ Read-Only
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13420"></a>
+ <a class="indexterm" name="d5e13425"></a>
+ <p>
+The read-only extension makes a field unwritable. The extension only applies to
+existing persistent objects; new object fields are always writeable.
+ </p>
+ <p>
+To mark a field read-only in JPA metadata, set the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/ReadOnly.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.ReadOnly</code></a>
+annotation to an
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/UpdateAction.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.UpdateAction</code></a> enum
+value. The <code class="classname">UpdateAction</code> enum includes:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">UpdateAction.IGNORE</code>: Updates to the field are completely
+ignored. The field is not considered dirty. The new value will not even get
+stored in the OpenJPA <a class="link" href="ref_guide_caching.html#ref_guide_cache" title="1. Data Cache">data cache</a>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">UpdateAction.RESTRICT</code>: Any attempt to change the field will
+result in an immediate exception.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="4.2.6. Type"><div class="titlepage"><div><div><h4 class="title" id="type">4.2.6.
+ Type
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13445"></a>
+ <p>
+OpenJPA has three levels of support for relations:
+ </p>
+ <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ <p>
+Relations that hold a reference to an object of a concrete persistent class are
+supported by storing the primary key values of the related instance in the
+database.
+ </p>
+ </li><li class="listitem">
+ <p>
+Relations that hold a reference to an object of an unknown persistent class are
+supported by storing the stringified identity value of the related instance.
+This level of support does not allow queries across the relation.
+ </p>
+ </li><li class="listitem">
+ <p>
+Relations that hold an unknown object or interface. The only way to support
+these relations is to serialize their value to the database. This does not allow
+you to query the field, and is not very efficient.
+ </p>
+ </li></ol></div>
+ <p>
+Clearly, when you declare a field's type to be another persistence-capable
+class, OpenJPA uses level 1 support. By default, OpenJPA assumes that any
+interface-typed fields you declare will be implemented only by other persistent
+classes, and assigns interfaces level 2 support. The exception to this rule is
+the <code class="classname">java.io.Serializable</code> interface. If you declare a
+field to be of type <code class="classname">Serializable</code>, OpenJPA lumps it
+together with <code class="classname">java.lang.Object</code> fields and other
+non-interface, unrecognized field types, which are all assigned level 3 support.
+ </p>
+ <p>
+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 <code class="classname">Entity</code> 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
+field to be of that type in the first place). Setting this extension to
+<code class="classname">Object</code> uses level 3 support. This is useful when you have
+an interface relation that may <span class="bold"><strong>not</strong></span> hold other
+persistent objects (recall that OpenJPA assumes interface fields will always
+hold persistent instances by default).
+ </p>
+ <p>
+This extension is also used with OpenJPA's externalization feature, described in
+<a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “
+ Externalization
+ ”</a>.
+ </p>
+ <p>
+OpenJPA defines the following type annotations for field values, collection,
+array, and map elements, and map keys, respectively:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Type.html" target="_top"><code class="classname">
+org.apache.openjpa.persistence.Type</code></a>
+ </p>
+ </li><li class="listitem">
+ <p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/ElementType.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.ElementType</code></a>
+ </p>
+ </li><li class="listitem">
+ <p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/KeyType.html" target="_top"><code class="classname">
+org.apache.openjpa.persistence.KeyType</code></a>
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="4.2.7. Externalizer"><div class="titlepage"><div><div><h4 class="title" id="externalizer">4.2.7.
+ Externalizer
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13484"></a>
+ <p>
+The OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Externalizer.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.Externalizer</code></a>
+annotation names a method to transform a field value into a value of
+another type. See <a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “
+ Externalization
+ ”</a> for details.
+ </p>
+ </div>
+ <div class="section" title="4.2.8. Factory"><div class="titlepage"><div><div><h4 class="title" id="factory">4.2.8.
+ Factory
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13495"></a>
+ <p>
+The OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Factory.html" target="_top"><code class="classname">
+org.apache.openjpa.persistence.Factory</code></a> annotation
+names a method to re-create a field value from its externalized form. See
+<a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_extern" title="6.5. Externalization">Section 6.5, “
+ Externalization
+ ”</a> for details.
+ </p>
+ </div>
+ <div class="section" title="4.2.9. External Values"><div class="titlepage"><div><div><h4 class="title" id="external-values">4.2.9.
+ External Values
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e13506"></a>
+ <p>
+The OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/ExternalValues.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.ExternalValues</code></a>
+annotation declares values for transformation of simple fields to
+different constant values in the datastore. See
+<a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_extern_values" title="6.5.1. External Values">Section 6.5.1, “
+ External Values
+ ”</a> for details.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="4.3. Example"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_example">4.3.
+ Example
+ </h3></div></div></div>
+
+ <p>
+The following example shows you how to specify extensions in metadata.
+ </p>
+ <div class="example"><a name="ref_guide_metaex"></a><p class="title"><b>Example 6.4.
+ OpenJPA Metadata Extensions
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@DataCache(enabled=false)
+public class Magazine
+{
+ @ManyToMany
+ @LRS
+ private Collection<Subscriber> subscribers;
+
+ @ExternalValues({"true=1", "false=2"})
+ @Type(int.class)
+ private boolean weekly;
+
+ ...
+}
+</pre>
+ </div></div><br class="example-break">
+ </div>
+ <div class="section" title="4.4. XML extensions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_xml">4.4.
+ XML extensions
+ </h3></div></div></div>
+
+ <p>
+OpenJPA has extended the JPA 2.0 schema to include elements and attributes corresponding
+to OpenJPA extended metadata and mapping annotations. The schema are contained in 2
+files: <a class="ulink" href="http://openjpa.apache.org/builds/latest/docs/schema/extendable/extendable-orm.xsd" target="_top">
+extendable-orm.xsd</a> and
+<a class="ulink" href="http://openjpa.apache.org/builds/latest/docs/schema/openjpa-orm.xsd" target="_top">openjpa-orm.xsd</a>.
+The extendable-orm.xsd file provides copies of some of the JPA 2.0 schema elements with additional schema to make it
+extendable.
+The openjpa-orm.xsd file extends the extendable-orm.xsd with OpenJPA specific elements and attributes representing
+OpenJPA annotations. Currently, only a subset of annotations have actually been implemented, and some of those
+have been partially tested. The current status can be found by comments in the
+<a class="ulink" href="http://openjpa.apache.org/builds/latest/docs/schema/openjpa-orm.xsd" target="_top">openjpa-orm.xsd</a>
+schema file.
+ </p>
+ <p>
+In order to use the OpenJPA extensions in your mapping file you must include the namespaces for these 2 new
+schemas as well as for the schema for JPA 2.0, as shown in the following example:
+ </p>
+ <div class="example"><a name="ref_guide_schema_ex"></a><p class="title"><b>Example 6.5.
+ OpenJPA Schema Extensions
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<entity-mappings xmlns="http://www.apache.org/openjpa/ns/orm/extendable"
+ xmlns:openjpa="http://www.apache.org/openjpa/ns/orm"
+ xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ version="2.0">
+
+ <entity class="org.apache.openjpa.persistence.jdbc.annotations.MultiColumnVersionPC"
+ metadata-complete="true">
+ <table name="MCV"/>
+ <attributes>
+ <id name="id">
+ <orm:generated-value/>
+ </id>
+ <basic name="id"/>
+ <basic name="name"/>
+ </attributes>
+ <openjpa:entity version-strategy="version-numbers">
+ <openjpa:version-columns>
+ <openjpa:version-column name="v1"/>
+ <openjpa:version-column name="v2"/>
+ <openjpa:version-column name="v3"
+ column-definition="FLOAT"
+ scale="3"
+ precision="10"/>
+ </openjpa:version-columns>
+ </openjpa:entity>
+ </entity>
+
+</entity-mappings>
+
+</pre>
+ </div></div><br class="example-break">
+ </div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_meta_jpa.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_meta.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_mapping.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.
+ Additional JPA Metadata
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7.
+ Mapping
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_ext.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_jpa.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_jpa.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_jpa.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,233 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>3. Additional JPA Metadata</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_meta.html" title="Chapter 6. Metadata"><link rel="prev" href="ref_guide_meta_repository.html" title="2. Metadata Repository"><link rel="next" href="ref_guide_meta_ext.html" title="4. Metadata Extensions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.
+ Additional JPA Metadata
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_meta_repository.html">Prev</a> </td><th width="60%" align="center">Chapter 6.
+ Metadata
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_meta_ext.html">Next</a></td></tr></table><hr></div><div class="section" title="3. Additional JPA Metadata"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_meta_jpa">3.
+ Additional JPA Metadata
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_datastoreid">3.1.
+ Datastore Identity
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_version">3.2.
+ Surrogate Version
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent">3.3.
+ Persistent Field Values
+ </a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</a></span></dt><dt><span class="section"><a href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e13128"></a>
+ <p>
+This section describes OpenJPA's core additions to standard entity metadata. We
+present the object-relational mapping syntax to support these additions in
+<a class="xref" href="ref_guide_mapping_jpa.html" title="7. Additional JPA Mappings">Section 7, “
+ Additional JPA Mappings
+ ”</a>. Finally,
+<a class="xref" href="ref_guide_meta_ext.html" title="4. Metadata Extensions">Section 4, “
+ Metadata Extensions
+ ”</a> covers additional extensions to JPA
+metadata that allow you to access auxiliary OpenJPA features.
+ </p>
+ <div class="section" title="3.1. Datastore Identity"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_jpa_datastoreid">3.1.
+ Datastore Identity
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e13136"></a>
+ <p>
+JPA typically requires you to declare one or more <code class="literal">Id</code> fields
+to act as primary keys. OpenJPA, however, can create and maintain a surrogate
+primary key value when you do not declare any <code class="literal">Id</code> fields. This
+form of persistent identity is called <span class="emphasis"><em>datastore identity</em></span>.
+<a class="xref" href="ref_guide_pc_oid.html" title="4. Object Identity">Section 4, “
+ Object Identity
+ ”</a> discusses OpenJPA's support for
+datastore identity in JPA. We cover how to map your datastore identity primary
+key column in <a class="xref" href="ref_guide_mapping_jpa.html#ref_guide_mapping_jpa_datastoreid" title="7.1. Datastore Identity Mapping">Section 7.1, “
+ Datastore Identity Mapping
+ ”</a>
+ </p>
+ </div>
+ <div class="section" title="3.2. Surrogate Version"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_jpa_version">3.2.
+ Surrogate Version
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e13147"></a>
+ <p>
+Just as OpenJPA can maintain your entity's identity without any <code class="literal">Id
+</code> fields, OpenJPA can maintain your entity's optimistic version without
+any <code class="literal">Version</code> fields.
+<a class="xref" href="ref_guide_mapping_jpa.html#ref_guide_mapping_jpa_version" title="7.2. Surrogate Version Mapping">Section 7.2, “
+ Surrogate Version Mapping
+ ”</a> shows you how to map
+surrogate version columns.
+ </p>
+ </div>
+ <div class="section" title="3.3. Persistent Field Values"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_jpa_persistent">3.3.
+ Persistent Field Values
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e13156"></a>
+ <p>
+JPA defines <code class="literal">Basic</code>, <code class="literal">Lob</code>, <code class="literal">Embedded
+</code>, <code class="literal">ManyToOne</code>, and <code class="literal">OneToOne</code>
+persistence strategies for direct field values. OpenJPA supports all of these
+standard strategies, but adds one of its own: <code class="literal">Persistent</code>.
+The <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Persistent.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.Persistent</code></a>
+metadata annotation can represent any direct field value, including custom
+types. It has the following properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">FetchType fetch</code>: Whether to load the field eagerly or
+lazily. Corresponds exactly to the same-named property of standard JPA
+annotations such as <a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_basic" title="2.7. Basic"><code class="classname"> Basic
+</code></a>. Defaults to <code class="literal">FetchType.EAGER</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CascadeType[] cascade</code>: Array of enum values defining cascade
+behavior for this field. Corresponds exactly to the same-named property of
+standard JPA annotations such as <a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_manytoone" title="2.9. Many To One">
+<code class="classname"> ManyToOne</code></a>. Defaults to empty array.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">String mappedBy</code>: Names the field in the related entity that
+maps this bidirectional relation. Corresponds to the same-named property of
+standard JPA annotations such as <a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_onetoone" title="2.11. One To One">
+<code class="classname"> OneToOne</code></a>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">boolean optional</code>: Whether the value can be null. Corresponds
+to the same-named property of standard JPA annotations such as
+<a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_manytoone" title="2.9. Many To One"><code class="classname"> ManyToOne</code>
+</a>, but can apply to non-entity object values as well. Defaults to
+<code class="literal">true</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">boolean embedded</code>: Set this property to <code class="literal">true
+</code> if the field value is stored as an embedded object.
+ </p>
+ </li></ul></div>
+ <p>
+Though you can use the <code class="classname">Persistent</code> 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, <a class="xref" href="ref_guide_mapping_jpa.html#ref_guide_mapping_jpa_columns" title="7.3. Multi-Column Mappings">Section 7.3, “
+ Multi-Column Mappings
+ ”</a>
+ demonstrates the use of the <code class="classname">Persistent</code> annotation
+to denote a persistent <code class="classname">java.awt.Point</code> field.
+ </p>
+ </div>
+ <div class="section" title="3.4. Persistent Collection Fields"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_jpa_persistent_coll">3.4. Persistent Collection Fields</h3></div></div></div>
+
+ <a class="indexterm" name="d5e13201"></a>
+ <p>
+JPA standardizes support for collections of entities with the <code class="literal">
+OneToMany</code> and <code class="literal">ManyToMany</code> persistence strategies.
+OpenJPA supports these strategies, and may be extended for other strategies as
+well. For extended strategies, use the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/PersistentCollection.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.PersistentCollection</code></a> metadata
+annotation to represents any persistent collection field. It has the following
+properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">Class elementType</code>: 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.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">FetchType fetch</code>: Whether to load the collection eagerly or
+lazily. Corresponds exactly to the same-named property of standard JPA
+annotations such as <a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_basic" title="2.7. Basic"><code class="classname">
+Basic</code></a>. Defaults to <code class="literal">FetchType.LAZY</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">String mappedBy</code>: Names the field in the related entity that
+maps this bidirectional relation. Corresponds to the same-named property of
+standard JPA annotations such as <a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_manytomany" title="2.12. Many To Many">
+<code class="classname">ManyToMany</code></a>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CascadeType[] elementCascade</code>: Array of enum values defining
+cascade behavior for the collection elements. Corresponds exactly to the
+<code class="literal">cascade</code> property of standard JPA annotations such as
+<a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_manytomany" title="2.12. Many To Many"><code class="classname">
+ManyToMany</code></a>. Defaults to empty array.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">boolean elementEmbedded</code>: Set this property to <code class="literal">true
+</code> if the elements are stored as embedded objects.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="3.5. Persistent Map Fields"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_jpa_persistent_map">3.5. Persistent Map Fields</h3></div></div></div>
+
+ <a class="indexterm" name="d5e13236"></a>
+ <p>
+JPA has limited support for maps. If you extend JPA's standard map support to
+encompass new mappings, use the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/PersistentMap.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.PersistentMap</code></a> metadata
+annotation to represent your custom persistent map fields. It has the
+following properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">Class keyType</code>: 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.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">Class elementType</code>: 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.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">FetchType fetch</code>: Whether to load the collection eagerly or
+lazily. Corresponds exactly to the same-named property of standard JPA
+annotations such as <a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_basic" title="2.7. Basic"><code class="classname">
+Basic</code></a>. Defaults to <code class="literal">FetchType.LAZY</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CascadeType[] keyCascade</code>: Array of enum values defining
+cascade behavior for the map keys. Corresponds exactly to the <code class="literal">cascade
+</code> property of standard JPA annotations such as
+<a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_manytoone" title="2.9. Many To One"><code class="classname">
+ManyToOne</code></a>. Defaults to empty array.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">CascadeType[] elementCascade</code>: Array of enum values defining
+cascade behavior for the map values. Corresponds exactly to the
+<code class="literal">cascade</code> property of standard JPA annotations such as
+<a class="link" href="jpa_overview_meta_field.html#jpa_overview_meta_manytoone" title="2.9. Many To One"><code class="classname">
+ManyToOne</code></a>. Defaults to empty array.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">boolean keyEmbedded</code>: Set this property to <code class="literal">true
+</code> if the map keys are stored as embedded objects.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">boolean elementEmbedded</code>: Set this property to <code class="literal">
+true</code> if the map values are stored as embedded objects.
+ </p>
+ </li></ul></div>
+ </div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_meta_repository.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_meta.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_meta_ext.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. Metadata Repository </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 4.
+ Metadata Extensions
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_jpa.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_repository.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_repository.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_repository.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,30 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. Metadata Repository</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_meta.html" title="Chapter 6. Metadata"><link rel="prev" href="ref_guide_meta.html" title="Chapter 6. Metadata"><link rel="next" href="ref_guide_meta_jpa.html" title="3. Additional JPA Metadata"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. Metadata Repository</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_meta.html">Prev</a> </td><th width="60%" align="center">Chapter 6.
+ Metadata
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_meta_jpa.html">Next</a></td></tr></table><hr></div><div class="section" title="2. Metadata Repository"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_meta_repository">2. Metadata Repository</h2></div></div></div>
+ <p>The openjpa.MetaDataRepository configuration property controls the configuration of
+ the MetaDataRepository. The following are valid properties:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <code class="literal">Preload</code>: A boolean property. If true, OpenJPA will eagerly load the repository on
+ EntityManagerFactory creation. As a result, all Entity classes will be eagerly loaded by the JVM.
+ Once MetaData preloading completes, all locking is removed from the MetaDataRepository and this will
+ result in a much more scalable repository. If false, the repository will be lazily loaded as Entity
+ classes are loaded by the JVM. The default value is false.
+ </p>
+ </li></ul></div>
+
+
+ <div class="example"><a name="ref_guide_meta_repo"></a><p class="title"><b>Example 6.3.
+ Setting the Preload Property on Metadata Repository
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.MetaDataRepository" value="Preload=true"/>
+</pre>
+ </div></div><br class="example-break">
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_meta.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_meta.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_meta_jpa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6.
+ Metadata
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3.
+ Additional JPA Metadata
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_meta_repository.html
------------------------------------------------------------------------------
svn:eol-style = native