Google Git
Sign in
apache / openjpa-site / f4f8b894b02554a0a851bbf380ef41d45c445062 / . / content / builds / 2.2.0 / apache-openjpa / docs / ref_guide_meta_ext.html
blob: 320ce17fa1d507d99b9435901d1bcbbc9fd6d22e [file] [log] [blame]
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>4.&nbsp; 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.2 User's Guide"><link rel="up" href="ref_guide_meta.html" title="Chapter&nbsp;6.&nbsp; Metadata"><link rel="prev" href="ref_guide_meta_jpa.html" title="3.&nbsp; Additional JPA Metadata"><link rel="next" href="ref_guide_mapping.html" title="Chapter&nbsp;7.&nbsp; 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.&nbsp;
Metadata Extensions
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_meta_jpa.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;6.&nbsp;
Metadata
</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_mapping.html">Next</a></td></tr></table><hr></div><div class="section" title="4.&nbsp; Metadata Extensions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_meta_ext">4.&nbsp;
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="d5e13142"></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.&nbsp; Mapping Extensions">Section&nbsp;9, &#8220;
Mapping Extensions
&#8221;</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.&nbsp; Class Extensions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_class">4.1.&nbsp;
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.&nbsp; Fetch Groups"><div class="titlepage"><div><div><h4 class="title" id="fetch-groups">4.1.1.&nbsp;
Fetch Groups
</h4></div></div></div>
<a class="indexterm" name="d5e13152"></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.&nbsp; Fetch Groups">Section&nbsp;7, &#8220;
Fetch Groups
&#8221;</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.&nbsp; Custom Fetch Groups">Section&nbsp;7.1, &#8220;
Custom Fetch Groups
&#8221;</a> for how to
use these annotations in particular.
</p>
</div>
<div class="section" title="4.1.2.&nbsp; Data Cache"><div class="titlepage"><div><div><h4 class="title" id="data-cache">4.1.2.&nbsp;
Data Cache
</h4></div></div></div>
<a class="indexterm" name="d5e13166"></a>
<p>
<a class="xref" href="ref_guide_caching.html#ref_guide_cache" title="1.&nbsp; Data Cache">Section&nbsp;1, &#8220;
Data Cache
&#8221;</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.&nbsp; openjpa.DataCacheTimeout"><code class="literal"> openjpa.DataCacheTimeout
</code></a> property value.
</p>
</li></ul></div>
</div>
<div class="section" title="4.1.3.&nbsp; Detached State"><div class="titlepage"><div><div><h4 class="title" id="detached-state-field">4.1.3.&nbsp;
Detached State
</h4></div></div></div>
<a class="indexterm" name="d5e13189"></a>
<p>
The OpenJPA <a class="link" href="ref_guide_pc_enhance.html" title="2.&nbsp; 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.&nbsp; Defining the Detached Object Graph">Section&nbsp;1.3, &#8220;
Defining the Detached Object Graph
&#8221;</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.&nbsp; 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.&nbsp; Field Extensions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_field">4.2.&nbsp;
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.&nbsp; Dependent"><div class="titlepage"><div><div><h4 class="title" id="dependent">4.2.1.&nbsp;
Dependent
</h4></div></div></div>
<a class="indexterm" name="d5e13220"></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.&nbsp; Cascade Type">Section&nbsp;2.9.1, &#8220;
Cascade Type
&#8221;</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.&nbsp; Load Fetch Group"><div class="titlepage"><div><div><h4 class="title" id="load-fetch-group">4.2.2.&nbsp;
Load Fetch Group
</h4></div></div></div>
<a class="indexterm" name="d5e13249"></a>
<a class="indexterm" name="d5e13253"></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.&nbsp; Fetch Groups">Section&nbsp;7, &#8220;
Fetch Groups
&#8221;</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.&nbsp; Custom Fetch Groups">Section&nbsp;7.1, &#8220;
Custom Fetch Groups
&#8221;</a> for how to use this
annotation in particular.
</p>
</div>
<div class="section" title="4.2.3.&nbsp; LRS"><div class="titlepage"><div><div><h4 class="title" id="lrs">4.2.3.&nbsp;
LRS
</h4></div></div></div>
<a class="indexterm" name="d5e13263"></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.&nbsp; Large Result Set Proxies">Section&nbsp;6.4.2, &#8220;
Large Result Set Proxies
&#8221;</a>.
</p>
</div>
<div class="section" title="4.2.4.&nbsp; Inverse-Logical"><div class="titlepage"><div><div><h4 class="title" id="inverse-logical">4.2.4.&nbsp;
Inverse-Logical
</h4></div></div></div>
<a class="indexterm" name="d5e13274"></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.&nbsp; Managed Inverses">Section&nbsp;5, &#8220;
Managed Inverses
&#8221;</a>.
</p>
</div>
<div class="section" title="4.2.5.&nbsp; Read-Only"><div class="titlepage"><div><div><h4 class="title" id="read-only">4.2.5.&nbsp;
Read-Only
</h4></div></div></div>
<a class="indexterm" name="d5e13285"></a>
<a class="indexterm" name="d5e13290"></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.&nbsp; 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.&nbsp; Type"><div class="titlepage"><div><div><h4 class="title" id="type">4.2.6.&nbsp;
Type
</h4></div></div></div>
<a class="indexterm" name="d5e13310"></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.&nbsp; Externalization">Section&nbsp;6.5, &#8220;
Externalization
&#8221;</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.&nbsp; Externalizer"><div class="titlepage"><div><div><h4 class="title" id="externalizer">4.2.7.&nbsp;
Externalizer
</h4></div></div></div>
<a class="indexterm" name="d5e13349"></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.&nbsp; Externalization">Section&nbsp;6.5, &#8220;
Externalization
&#8221;</a> for details.
</p>
</div>
<div class="section" title="4.2.8.&nbsp; Factory"><div class="titlepage"><div><div><h4 class="title" id="factory">4.2.8.&nbsp;
Factory
</h4></div></div></div>
<a class="indexterm" name="d5e13360"></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.&nbsp; Externalization">Section&nbsp;6.5, &#8220;
Externalization
&#8221;</a> for details.
</p>
</div>
<div class="section" title="4.2.9.&nbsp; External Values"><div class="titlepage"><div><div><h4 class="title" id="external-values">4.2.9.&nbsp;
External Values
</h4></div></div></div>
<a class="indexterm" name="d5e13371"></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.&nbsp; External Values">Section&nbsp;6.5.1, &#8220;
External Values
&#8221;</a> for details.
</p>
</div>
</div>
<div class="section" title="4.3.&nbsp; Example"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_example">4.3.&nbsp;
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&nbsp;6.4.&nbsp;
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&lt;Subscriber&gt; 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.&nbsp; XML extensions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_meta_xml">4.4.&nbsp;
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-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&nbsp;6.5.&nbsp;
OpenJPA Schema Extensions
</b></p><div class="example-contents">
<pre class="programlisting">
&lt;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"&gt;
&lt;entity class="org.apache.openjpa.persistence.jdbc.annotations.MultiColumnVersionPC"
metadata-complete="true"&gt;
&lt;table name="MCV"/&gt;
&lt;attributes&gt;
&lt;id name="id"&gt;
&lt;orm:generated-value/&gt;
&lt;/id&gt;
&lt;basic name="id"/&gt;
&lt;basic name="name"/&gt;
&lt;/attributes&gt;
&lt;openjpa:entity version-strategy="version-numbers"&gt;
&lt;openjpa:version-columns&gt;
&lt;openjpa:version-column name="v1"/&gt;
&lt;openjpa:version-column name="v2"/&gt;
&lt;openjpa:version-column name="v3"
column-definition="FLOAT"
scale="3"
precision="10"/&gt;
&lt;/openjpa:version-columns&gt;
&lt;/openjpa:entity&gt;
&lt;/entity&gt;
&lt;/entity-mappings&gt;
</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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_meta.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_mapping.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.&nbsp;
Additional JPA Metadata
&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;7.&nbsp;
Mapping
</td></tr></table></div></body></html>