| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 5. Metadata</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="jpa_overview.html" title="Part 2. Java Persistence API"><link rel="prev" href="jpa_overview_pc_conclusion.html" title="4. Conclusions"><link rel="next" href="jpa_overview_meta_field.html" title="2. Field and Property 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">Chapter 5. |
| Metadata |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc_conclusion.html">Prev</a> </td><th width="60%" align="center">Part 2. Java Persistence API</th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_meta_field.html">Next</a></td></tr></table><hr></div><div class="chapter" id="jpa_overview_meta"><div class="titlepage"><div><div><h2 class="title">Chapter 5. |
| Metadata |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_class">1. |
| Class Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_entity">1.1. |
| Entity |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_idclass">1.2. |
| Id Class |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_embeddablesuper">1.3. |
| Mapped Superclass |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_embeddable">1.4. |
| Embeddable |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_entity_listeners">1.5. |
| EntityListeners |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_classex">1.6. |
| Example |
| </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_meta_field.html">2. |
| Field and Property Metadata |
| </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_explicit_access">2.1. |
| Explicit Access |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_transient">2.2. |
| Transient |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_id">2.3. |
| Id |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_gen">2.4. |
| Generated Value |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_embedid">2.5. |
| Embedded Id |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_version">2.6. |
| Version |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_basic">2.7. |
| Basic |
| </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_fetch">2.7.1. |
| Fetch Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_embedded">2.8. |
| Embedded |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_manytoone">2.9. |
| Many To One |
| </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_cascade">2.9.1. |
| Cascade Type |
| </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_onetomany">2.10. |
| One To Many |
| </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_mappedby">2.10.1. |
| Bidirectional Relations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_onetoone">2.11. |
| One To One |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_manytomany">2.12. |
| Many To Many |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_orderby">2.13. |
| Order By |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_mapkey">2.14. |
| Map Key |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_field.html#jpa_overview_meta_fielddefaults">2.15. |
| Persistent Field Defaults |
| </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_meta_xml.html">3. |
| XML Schema |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta_complete.html">4. |
| Conclusion |
| </a></span></dt></dl></div> |
| |
| <a class="indexterm" name="d5e996"></a> |
| <a class="indexterm" name="d5e998"></a> |
| <p> |
| JPA requires that you accompany each persistent class with persistence metadata. |
| This metadata serves three primary purposes: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> |
| <p> |
| To identify persistent classes. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| To override default JPA behavior. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| To provide the JPA implementation with information that it cannot glean from |
| simply reflecting on the persistent class. |
| </p> |
| </li></ol></div> |
| <p> |
| <a class="indexterm" name="d5e1011"></a> |
| Persistence metadata is specified using either the Java annotations defined in |
| the <code class="literal">javax.persistence</code> package, XML mapping files, or a |
| mixture of both. In the latter case, XML declarations override conflicting |
| annotations. If you choose to use XML metadata, the XML files must be available |
| at development and runtime, and must be discoverable via either of two |
| strategies: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> |
| <p> |
| In a resource named <code class="filename">orm.xml</code> placed in a <code class="filename"> |
| META-INF</code> directory within a directory in your classpath or within a |
| jar archive containing your persistent classes. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| Declared in your <a class="link" href="jpa_overview_persistence.html#jpa_overview_persistence_xml" title="1. persistence.xml"><code class="filename"> |
| persistence.xml</code></a> configuration file. In this case, each XML |
| metadata file must be listed in a <code class="literal">mapping-file</code> element whose |
| content is either a path to the given file or a resource location available to |
| the class' class loader. |
| </p> |
| </li></ol></div> |
| <p> |
| We describe the standard metadata annotations and XML equivalents throughout |
| this chapter. The full schema for XML mapping files is available in |
| <a class="xref" href="jpa_overview_meta_xml.html" title="3. XML Schema">Section 3, “ |
| XML Schema |
| ”</a>. JPA also standardizes relational |
| mapping metadata and named query metadata, which we discuss in |
| <a class="xref" href="jpa_overview_mapping.html" title="Chapter 13. Mapping Metadata">Chapter 13, <i> |
| Mapping Metadata |
| </i></a> and |
| <a class="xref" href="jpa_overview_query.html#jpa_overview_query_named" title="1.11. Named Queries">Section 1.11, “ |
| Named Queries |
| ”</a> respectively. |
| </p> |
| <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| OpenJPA defines many useful annotations beyond the standard set. See |
| <a class="xref" href="ref_guide_meta_jpa.html" title="3. Additional JPA Metadata">Section 3, “ |
| Additional JPA Metadata |
| ”</a> and |
| <a class="xref" href="ref_guide_meta_ext.html" title="4. Metadata Extensions">Section 4, “ |
| Metadata Extensions |
| ”</a> |
| in the Reference Guide for details. There are currently no XML equivalents for |
| these extension annotations. |
| </p> |
| </div> |
| <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| Persistence metadata may be used to validate the contents of your entities prior to communicating |
| with the database. This differs from mapping meta data which is primarily used for schema generation. |
| For example if you indicate that a relationship is not optional (e.g. @Basic(optional=false)) OpenJPA |
| will validate that the variable in your entity is not null <span class="emphasis"><em>before</em></span> inserting a row |
| in the database. |
| </p> |
| </div> |
| <div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" style="cellpadding: 0; cellspacing: 0;" width="369"><tr><td><img src="img/jpa-meta-model.png"></td></tr></table></div> |
| <p> |
| Through the course of this chapter, we will create the persistent object model |
| above. |
| </p> |
| <div class="section" id="jpa_overview_meta_class"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1. |
| Class Metadata |
| </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_entity">1.1. |
| Entity |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_idclass">1.2. |
| Id Class |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_embeddablesuper">1.3. |
| Mapped Superclass |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_embeddable">1.4. |
| Embeddable |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_entity_listeners">1.5. |
| EntityListeners |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_meta.html#jpa_overview_meta_classex">1.6. |
| Example |
| </a></span></dt></dl></div> |
| |
| <p> |
| The following metadata annotations and XML elements apply to persistent class |
| declarations. |
| </p> |
| <div class="section" id="jpa_overview_meta_entity"><div class="titlepage"><div><div><h3 class="title">1.1. |
| Entity |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e1044"></a> |
| <a class="indexterm" name="d5e1047"></a> |
| <a class="indexterm" name="d5e1050"></a> |
| <p> |
| The <code class="classname">Entity</code> annotation denotes an entity class. All entity |
| classes must have this annotation. The <code class="classname">Entity</code> annotation |
| takes one optional property: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> |
| <p> |
| <code class="literal">String name</code>: Name used to refer to the entity in queries. |
| Must not be a reserved literal in JPQL. Defaults to the unqualified name of the |
| entity class. |
| </p> |
| </li></ul></div> |
| <p> |
| The equivalent XML element is <code class="literal">entity</code>. It has the following |
| attributes: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> |
| <p> |
| <code class="literal">class</code>: The entity class. This attribute is required. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">name</code>: Named used to refer to the class in queries. See the |
| name property above. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">access</code>: The access type to use for the class. Must either be |
| <code class="literal">FIELD</code> or <code class="literal">PROPERTY</code>. For details on access |
| types, see <a class="xref" href="jpa_overview_meta_field.html" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p> |
| </li></ul></div> |
| <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| OpenJPA uses a process called <span class="emphasis"><em>enhancement</em></span> to modify the |
| bytecode of entities for transparent lazy loading and immediate dirty tracking. |
| See <a class="xref" href="ref_guide_pc_enhance.html" title="2. Enhancement">Section 2, “ |
| Enhancement |
| ”</a> in the Reference Guide for |
| details on enhancement. |
| </p> |
| </div> |
| </div> |
| <div class="section" id="jpa_overview_meta_idclass"><div class="titlepage"><div><div><h3 class="title">1.2. |
| Id Class |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e1081"></a> |
| <a class="indexterm" name="d5e1083"></a> |
| <a class="indexterm" name="d5e1086"></a> |
| <p> |
| As we discussed in <a class="xref" href="jpa_overview_pc_identity.html#jpa_overview_pc_identitycls" title="2.1. Identity Class">Section 2.1, “ |
| Identity Class |
| ”</a>, |
| entities with multiple identity fields must use an <span class="emphasis"><em> identity class |
| </em></span> to encapsulate their persistent identity. The <code class="classname">IdClass |
| </code> annotation specifies this class. It accepts a single <code class="classname"> |
| java.lang.Class</code> value. |
| </p> |
| <p> |
| The equivalent XML element is <code class="literal">id-class</code>, which has a single |
| attribute: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> |
| <p> |
| <code class="literal">class</code>: Set this required attribute to the name of the |
| identity class. |
| </p> |
| </li></ul></div> |
| </div> |
| <div class="section" id="jpa_overview_meta_embeddablesuper"><div class="titlepage"><div><div><h3 class="title">1.3. |
| Mapped Superclass |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e1102"></a> |
| <a class="indexterm" name="d5e1104"></a> |
| <a class="indexterm" name="d5e1107"></a> |
| <p> |
| A <span class="emphasis"><em>mapped superclass</em></span> is a non-entity class that can define |
| persistent state and mapping information for entity subclasses. Mapped |
| superclasses are usually abstract. Unlike true entities, you cannot query a |
| mapped superclass, pass a mapped superclass instance to any <code class="classname"> |
| EntityManager</code> or <code class="classname">Query</code> methods, or declare a |
| persistent relation with a mapped superclass target. You denote a mapped |
| superclass with the <code class="classname">MappedSuperclass</code> marker annotation. |
| </p> |
| <p> |
| The equivalent XML element is <code class="literal">mapped-superclass</code>. It expects |
| the following attributes: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> |
| <p> |
| <code class="literal">class</code>: The entity class. This attribute is required. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">access</code>: The access type to use for the class. Must either be |
| <code class="literal">FIELD</code> or <code class="literal">PROPERTY</code>. For details on access |
| types, see <a class="xref" href="jpa_overview_meta_field.html" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p> |
| </li></ul></div> |
| <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| OpenJPA allows you to query on mapped superclasses. A query on a mapped |
| superclass will return all matching subclass instances. OpenJPA also allows you |
| to declare relations to mapped superclass types; however, you cannot query |
| across these relations. |
| </p> |
| </div> |
| </div> |
| <div class="section" id="jpa_overview_meta_embeddable"><div class="titlepage"><div><div><h3 class="title">1.4. |
| Embeddable |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e1131"></a> |
| <a class="indexterm" name="d5e1133"></a> |
| <a class="indexterm" name="d5e1136"></a> |
| <p> |
| The <code class="classname">Embeddable</code> annotation designates an embeddable |
| persistent class. Embeddable instances are stored as part of the record of their |
| owning instance. All embeddable classes must have this annotation. |
| </p> |
| <p> |
| A persistent class can either be an entity or an embeddable class, but not both. |
| </p> |
| <p> |
| The equivalent XML element is <code class="literal">embeddable</code>. It understands the |
| following attributes: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> |
| <p> |
| <code class="literal">class</code>: The entity class. This attribute is required. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">access</code>: The access type to use for the class. Must either be |
| <code class="literal">FIELD</code> or <code class="literal">PROPERTY</code>. For details on access |
| types, see <a class="xref" href="jpa_overview_meta_field.html" title="2. Field and Property Metadata">Section 2, “ |
| Field and Property Metadata |
| ”</a>. |
| </p> |
| </li></ul></div> |
| <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| OpenJPA allows a persistent class to be both an entity and an embeddable class. |
| Instances of the class will act as entities when persisted explicitly or assigned |
| to non-embedded fields of entities. Instances will act as embedded values when |
| assigned to embedded fields of entities. |
| </p> |
| <p> |
| To signal that a class is both an entity and an embeddable class in OpenJPA, |
| simply add both the <code class="literal">@Entity</code> and the <code class="literal">@Embeddable |
| </code> annotations to the class. |
| </p> |
| </div> |
| </div> |
| <div class="section" id="jpa_overview_meta_entity_listeners"><div class="titlepage"><div><div><h3 class="title">1.5. |
| EntityListeners |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e1161"></a> |
| <a class="indexterm" name="d5e1163"></a> |
| <a class="indexterm" name="d5e1165"></a> |
| <a class="indexterm" name="d5e1168"></a> |
| <p> |
| An entity may list its lifecycle event listeners in the <code class="classname"> |
| EntityListeners</code> annotation. This value of this annotation is an |
| array of the listener <code class="classname">Class</code> es for the entity. The |
| equivalent XML element is <code class="literal">entity-listeners</code>. For more details |
| on entity listeners, see <a class="xref" href="jpa_overview_pc_callbacks.html" title="3. Lifecycle Callbacks">Section 3, “ |
| Lifecycle Callbacks |
| ”</a>. |
| </p> |
| </div> |
| <div class="section" id="jpa_overview_meta_classex"><div class="titlepage"><div><div><h3 class="title">1.6. |
| Example |
| </h3></div></div></div> |
| |
| <p> |
| Here are the class declarations for our persistent object model, annotated with |
| the appropriate persistence metadata. Note that <code class="classname">Magazine</code> |
| declares an identity class, and that <code class="classname">Document</code> and |
| <code class="classname">Address</code> are a mapped superclass and an embeddable class, |
| respectively. <code class="classname">LifetimeSubscription</code> and <code class="classname"> |
| TrialSubscription</code> override the default entity name to supply a |
| shorter alias for use in queries. |
| </p> |
| <div class="example" id="jpa_overview_meta_classlisting"><p class="title"><b>Example 5.1. |
| Class Metadata |
| </b></p><div class="example-contents"> |
| |
| <pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| public class Magazine { |
| ... |
| |
| public static class MagazineId { |
| ... |
| } |
| } |
| |
| @Entity |
| public class Article { |
| ... |
| } |
| |
| |
| package org.mag.pub; |
| |
| @Entity |
| public class Company { |
| ... |
| } |
| |
| @Entity |
| public class Author { |
| ... |
| } |
| |
| @Embeddable |
| public class Address { |
| ... |
| } |
| |
| |
| package org.mag.subscribe; |
| |
| @MappedSuperclass |
| public abstract class Document { |
| ... |
| } |
| |
| @Entity |
| public class Contract |
| extends Document { |
| ... |
| } |
| |
| @Entity |
| public class Subscription { |
| ... |
| |
| @Entity |
| public static class LineItem |
| extends Contract { |
| ... |
| } |
| } |
| |
| @Entity(name="Lifetime") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre> |
| <p> |
| The equivalent declarations in XML: |
| </p> |
| <pre class="programlisting"> |
| <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd" |
| version="1.0"> |
| <mapped-superclass class="org.mag.subscribe.Document"> |
| ... |
| </mapped-superclass> |
| <entity class="org.mag.Magazine"> |
| <id-class class="org.mag.Magazine$MagazineId"/> |
| ... |
| </entity> |
| <entity class="org.mag.Article"> |
| ... |
| </entity> |
| <entity class="org.mag.pub.Company"> |
| ... |
| </entity> |
| <entity class="org.mag.pub.Author"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.Contract"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LineItem"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"> |
| ... |
| </entity> |
| <entity class="org.mag.subscribe.TrialSubscription" name="Trial"> |
| ... |
| </entity> |
| <embeddable class="org.mag.pub.Address"> |
| ... |
| </embeddable> |
| </entity-mappings> |
| </pre> |
| </div></div><br class="example-break"> |
| </div> |
| </div> |
| |
| |
| |
| </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_pc_conclusion.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_meta_field.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. |
| Conclusions |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. |
| Field and Property Metadata |
| </td></tr></table></div></body></html> |