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 [9/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/jpa_overview_mapping.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,340 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 13. Mapping 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="jpa_overview.html" title="Part 2. Java Persistence API"><link rel="prev" href="jpa_overview_sqlquery_obj.html" title="2. Retrieving Persistent Objects with SQL"><link rel="next" href="jpa_overview_mapping_unq.html" title="2. Unique Constraints"></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 13.
+ Mapping Metadata
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_sqlquery_obj.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_mapping_unq.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 13. Mapping Metadata" id="jpa_overview_mapping"><div class="titlepage"><div><div><h2 class="title">Chapter 13.
+ Mapping Metadata
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="jpa_overview_mapping.html#jpa_overview_mapping_table">1.
+ Table
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_unq.html">2.
+ Unique Constraints
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_column.html">3.
+ Column
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_id.html">4.
+ Identity Mapping
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_sequence.html">5.
+ Generators
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_sequence.html#jpa_overview_mapping_sequence_seqgen">5.1.
+ Sequence Generator
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_sequence.html#jpa_overview_mapping_sequence_tablegen">5.2.
+ Table Generator
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_sequence.html#jpa_overview_mapping_sequence_genex">5.3.
+ Example
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_inher.html">6.
+ Inheritance
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_single">6.1.
+ Single Table
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_single_adv">6.1.1.
+ Advantages
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_single_disadv">6.1.2.
+ Disadvantages
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_joined">6.2.
+ Joined
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_joined_adv">6.2.1.
+ Advantages
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_joined_disadv">6.2.2.
+ Disadvantages
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_tpc">6.3.
+ Table Per Class
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_tpc_adv">6.3.1.
+ Advantages
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_tpc_disadv">6.3.2.
+ Disadvantages
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_together">6.4.
+ Putting it All Together
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_discrim.html">7.
+ Discriminator
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html">8.
+ Field Mapping
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_basic">8.1.
+ Basic Mapping
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_lob">8.1.1.
+ LOBs
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_enum">8.1.2.
+ Enumerated
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_temporal">8.1.3.
+ Temporal Types
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_basic_example">8.1.4.
+ The Updated Mappings
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_secondary">8.2.
+ Secondary Tables
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_embed">8.3.
+ Embedded Mapping
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_rel">8.4.
+ Direct Relations
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_assoccoll">8.5.
+ Join Table
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_bidi">8.6.
+ Bidirectional Mapping
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_mapping_field.html#jpa_overview_mapping_map">8.7.
+ Map Mapping
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_mapping_full.html">9.
+ The Complete Mappings
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e5386"></a>
+ <a class="indexterm" name="d5e5388"></a>
+ <a class="indexterm" name="d5e5392"></a>
+ <a class="indexterm" name="d5e5396"></a>
+ <a class="indexterm" name="d5e5399"></a>
+ <p>
+<span class="emphasis"><em>Object-relational mapping</em></span> is the process of mapping
+entities to relational database tables. In JPA, you perform
+object/relational mapping through <span class="emphasis"><em>mapping metadata</em></span>.
+Mapping metadata uses annotations to describe how to link your object model to
+your relational model.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA offers tools to automate mapping and schema creation. See
+<a class="xref" href="ref_guide_mapping.html" title="Chapter 7. Mapping">Chapter 7, <i>
+ Mapping
+ </i></a> in the Reference Guide.
+ </p>
+ </div>
+ <p>
+Throughout this chapter, we will draw on the object model introduced in
+<a class="xref" href="jpa_overview_meta.html" title="Chapter 5. Metadata">Chapter 5, <i>
+ Metadata
+ </i></a>. We present that model again below.
+As we discuss various aspects of mapping metadata, we will zoom in on specific
+areas of the model and show how we map the object layer to the relational layer.
+ </p>
+ <div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="369"><tr><td><img src="img/jpa-meta-model.png"></td></tr></table></div>
+ <p>
+All mapping metadata is optional. Where no explicit mapping metadata is given,
+JPA uses the defaults defined by the specification. As we present
+each mapping throughout this chapter, we also describe the defaults that apply
+when the mapping is absent.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+Mapping metadata is used primarily with schema generation. This metadata should not
+be relied upon for validation prior to communicating with the database.
+For example using the @Column(nullable=false) annotation does not do up front validation
+that the value in the entity is correct.
+ </p>
+ </div>
+ <div class="section" title="1. Table"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_mapping_table">1.
+ Table
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e5419"></a>
+ <p>
+The <code class="classname">Table</code> annotation specifies the table for an entity
+class. If you omit the <code class="classname">Table</code> annotation, base entity
+classes default to a table with their unqualified class name. The default table
+of an entity subclass depends on the inheritance strategy, as you will see in
+<a class="xref" href="jpa_overview_mapping_inher.html" title="6. Inheritance">Section 6, “
+ Inheritance
+ ”</a>.
+ </p>
+ <p>
+<code class="classname">Table</code>s have the following properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">String name</code>: The name of the table. Defaults to the
+unqualified entity class name.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">String schema</code>: The table's schema. If you do not name a
+schema, JPA uses the default schema for the database connection.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">String catalog</code>: The table's catalog. If you do not name a
+catalog, JPA uses the default catalog for the database connection.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">UniqueConstraint[] uniqueConstraints</code>: An array of unique
+constraints to place on the table. We cover unique constraints below. Defaults
+to an empty array.
+ </p>
+ </li></ul></div>
+ <p>
+The equivalent XML element is <code class="literal">table</code>. It has the following
+attributes, which correspond to the annotation properties above:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">name</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">schema</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">catalog</code>
+ </p>
+ </li></ul></div>
+ <p>
+The <code class="literal">table</code> element also accepts nested <code class="literal">
+unique-constraint</code> elements representing unique constraints. We will
+detail unique constraints shortly.
+ </p>
+ <p>
+Sometimes, some of the fields in a class are mapped to secondary tables. In that
+case, use the class' <code class="classname">Table</code> annotation to name what you
+consider the class' primary table. Later, we will see how to map certain fields
+to other tables.
+ </p>
+ <p>
+The example below maps classes to tables to separate schemas. The
+<code class="literal">CONTRACT</code>, <code class="literal">SUB</code>, and <code class="literal">LINE_ITEM
+</code> tables are in the <code class="literal">CNTRCT</code> schema; all other tables
+are in the default schema.
+ </p>
+ <div class="example"><a name="jpa_overview_mapping_classex"></a><p class="title"><b>Example 13.1.
+ Mapping Classes
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+public class Magazine {
+ ...
+
+ public static class MagazineId {
+ ...
+ }
+}
+
+@Entity
+@Table(name="ART")
+public class Article {
+ ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company {
+ ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author {
+ ...
+}
+
+@Embeddable
+public class Address {
+ ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document {
+ ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+public class Contract
+ extends Document {
+ ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+public class Subscription {
+ ...
+
+ @Entity
+ @Table(name="LINE_ITEM", schema="CNTRCT")
+ 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 same mapping information expressed 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">
+ <table name="MAG"/>
+ <id-class="org.mag.Magazine.MagazineId"/>
+ ...
+ </entity>
+ <entity class="org.mag.Article">
+ <table name="ART"/>
+ ...
+ </entity>
+ <entity class="org.mag.pub.Company">
+ <table name="COMP"/>
+ ...
+ </entity>
+ <entity class="org.mag.pub.Author">
+ <table name="AUTH"/>
+ ...
+ </entity>
+ <entity class="org.mag.subcribe.Contract">
+ <table schema="CNTRCT"/>
+ ...
+ </entity>
+ <entity class="org.mag.subcribe.Subscription">
+ <table name="SUB" schema="CNTRCT"/>
+ ...
+ </entity>
+ <entity class="org.mag.subscribe.Subscription.LineItem">
+ <table name="LINE_ITEM" schema="CNTRCT"/>
+ ...
+ </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 class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_sqlquery_obj.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_mapping_unq.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
+ Retrieving Persistent Objects with SQL
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2.
+ Unique Constraints
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping_column.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping_column.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping_column.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,130 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>3. Column</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="jpa_overview_mapping.html" title="Chapter 13. Mapping Metadata"><link rel="prev" href="jpa_overview_mapping_unq.html" title="2. Unique Constraints"><link rel="next" href="jpa_overview_mapping_id.html" title="4. Identity 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">3.
+ Column
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_mapping_unq.html">Prev</a> </td><th width="60%" align="center">Chapter 13.
+ Mapping Metadata
+ </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_mapping_id.html">Next</a></td></tr></table><hr></div><div class="section" title="3. Column"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_mapping_column">3.
+ Column
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e5512"></a>
+ <a class="indexterm" name="d5e5515"></a>
+ <p>
+In the previous section, we saw that a <code class="classname">UniqueConstraint</code>
+uses an array of column names. Field mappings, however, use full-fledged
+<code class="classname">Column</code> annotations. Column annotations have the following
+properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5525"></a>
+<code class="literal">String name</code>: The column name. Defaults to the field name.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5532"></a>
+<code class="literal">String columnDefinition</code>: The database-specific column type
+name. This property is only used by vendors that support creating tables from
+your mapping metadata. During table creation, the vendor will use the value of
+the <code class="literal">columnDefinition</code> as the declared column type. If no
+<code class="literal">columnDefinition</code> is given, the vendor will choose an
+appropriate default based on the field type combined with the column's length,
+precision, and scale.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5541"></a>
+<code class="literal">int length</code>: The column length. This property is typically
+only used during table creation, though some vendors might use it to validate
+data before flushing. <code class="literal">CHAR</code> and <code class="literal">VARCHAR</code>
+columns typically default to a length of 255; other column types use the
+database default.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5550"></a>
+<code class="literal">int precision</code>: The precision of a numeric column. This
+property is often used in conjunction with <code class="literal">scale</code> to form the
+proper column type name during table creation.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5558"></a>
+<code class="literal">int scale</code>: The number of decimal digits a numeric column can
+hold. This property is often used in conjunction with <code class="literal">precision
+</code> to form the proper column type name during table creation.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5566"></a>
+<code class="literal">boolean nullable</code>: Whether the column can store null values.
+Vendors may use this property both for table creation and at runtime; however,
+it is never required. Defaults to <code class="literal">true</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5574"></a>
+<code class="literal">boolean insertable</code>: By setting this property to <code class="literal">
+false</code>, you can omit the column from SQL <code class="literal">INSERT</code>
+statements. Defaults to <code class="literal">true</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5584"></a>
+<code class="literal">boolean updatable</code>: By setting this property to <code class="literal">
+false</code>, you can omit the column from SQL <code class="literal">UPDATE</code>
+statements. Defaults to <code class="literal">true</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e5594"></a>
+<code class="literal">String table</code>: Sometimes you will need to map fields to
+tables other than the primary table. This property allows you specify that the
+column resides in a secondary table. We will see how to map fields to secondary
+tables later in the chapter.
+ </p>
+ </li></ul></div>
+ <p>
+The equivalent XML element is <code class="literal">column</code>. This element has
+attributes that are exactly equivalent to the <code class="classname"> Column</code>
+annotation's properties described above:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">name</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">column-definition</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">length</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">precision</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">scale</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">insertable</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">updatable</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">table</code>
+ </p>
+ </li></ul></div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_mapping_unq.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_mapping.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_mapping_id.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
+ Unique Constraints
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 4.
+ Identity 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/jpa_overview_mapping_column.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping_discrim.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping_discrim.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_mapping_discrim.html Mon Jun 1 20:19:00 2015
@@ -0,0 +1,369 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>7. Discriminator</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="jpa_overview_mapping.html" title="Chapter 13. Mapping Metadata"><link rel="prev" href="jpa_overview_mapping_inher.html" title="6. Inheritance"><link rel="next" href="jpa_overview_mapping_field.html" title="8. Field 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">7.
+ Discriminator
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_mapping_inher.html">Prev</a> </td><th width="60%" align="center">Chapter 13.
+ Mapping Metadata
+ </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_mapping_field.html">Next</a></td></tr></table><hr></div><div class="section" title="7. Discriminator"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_mapping_discrim">7.
+ Discriminator
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e6122"></a>
+ <a class="indexterm" name="d5e6124"></a>
+ <a class="indexterm" name="d5e6128"></a>
+ <p>
+The <a class="link" href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_single" title="6.1. Single Table">single table</a>
+inheritance strategy results in a single table containing records for two or
+more different classes in an inheritance hierarchy. Similarly, using the
+<a class="link" href="jpa_overview_mapping_inher.html#jpa_overview_mapping_inher_joined" title="6.2. Joined"> joined</a> strategy
+results in the superclass table holding records for superclass instances as well
+as for the superclass state of subclass instances. When selecting data, JPA
+needs a way to differentiate a row representing an object of one class from a
+row representing an object of another. That is the job of the <span class="emphasis"><em>
+discriminator</em></span> column.
+ </p>
+ <p>
+The discriminator column is always in the table of the base entity. It holds a
+different value for records of each class, allowing the JPA runtime
+to determine what class of object each row represents.
+ </p>
+ <p>
+The <code class="classname">DiscriminatorColumn</code> annotation represents a
+discriminator column. It has these properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">String name</code>: The column name. Defaults to <code class="literal">DTYPE
+</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">length</code>: For string discriminator values, the length of the
+column. Defaults to 31.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">String columnDefinition</code>: This property has the same meaning
+as the <code class="literal">columnDefinition</code> property on the <code class="classname">Column
+</code> annotation, described in
+<a class="xref" href="jpa_overview_mapping_column.html" title="3. Column">Section 3, “
+ Column
+ ”</a>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">DiscriminatorType discriminatorType</code>: Enum value declaring
+the discriminator strategy of the hierarchy.
+ </p>
+ </li></ul></div>
+ <p>
+The corresponding XML element is <code class="literal"> discriminator-column</code>. Its
+attributes mirror the annotation properties above:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="literal">name</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">length</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">column-definition</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">discriminator-type</code>: One of <code class="literal">STRING</code>,
+<code class="literal">CHAR</code>, or <code class="literal">INTEGER</code>.
+ </p>
+ </li></ul></div>
+ <p>
+The <code class="classname">DiscriminatorValue</code> annotation specifies the
+discriminator value for each class. Though this annotation's value is always a
+string, the implementation will parse it according to the <code class="classname">
+DiscriminatorColumn</code>'s <code class="literal">discriminatorType</code> property
+above. The type defaults to <code class="literal">DiscriminatorType.STRING</code>, but
+may be <code class="literal"> DiscriminatorType.CHAR</code> or <code class="literal">
+DiscriminatorType.INTEGER</code>. If you do not specify a <code class="classname">
+DiscriminatorValue</code>, the provider will choose an appropriate
+default.
+ </p>
+ <p>
+The corresponding XML element is <code class="literal">discriminator-value</code>. The
+text within this element is parsed as the discriminator value.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA assumes your model employs a discriminator column if any of the
+following are true:
+ </p>
+ <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ <p>
+The base entity explicitly declares an inheritance type of <code class="literal">
+SINGLE_TABLE</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+The base entity sets a discriminator value.
+ </p>
+ </li><li class="listitem">
+ <p>
+The base entity declares a discriminator column.
+ </p>
+ </li></ol></div>
+ <p>
+Only <code class="literal">SINGLE_TABLE</code> inheritance hierarchies require a
+discriminator column and values. <code class="literal"> JOINED</code> hierarchies can use
+a discriminator to make some operations more efficient, but do not require one.
+<code class="literal">TABLE_PER_CLASS</code> hierarchies have no use for a discriminator.
+ </p>
+ <p>
+OpenJPA defines additional discriminator strategies; see
+<a class="xref" href="ref_guide_mapping_jpa.html" title="7. Additional JPA Mappings">Section 7, “
+ Additional JPA Mappings
+ ”</a> in the Reference Guide for
+details. OpenJPA also supports final entity classes. OpenJPA does not use a
+discriminator on final classes.
+ </p>
+ </div>
+ <p>
+We can now translate our newfound knowledge of JPA discriminators into concrete
+JPA mappings. We first extend our diagram with discriminator columns:
+ </p>
+ <div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="341"><tr><td><img src="img/jpa-discrim-all.png"></td></tr></table></div>
+ <p>
+Next, we present the updated mapping document. Notice that in this version, we
+have removed explicit inheritance annotations when the defaults sufficed. Also,
+notice that entities using the default <code class="literal">DTYPE</code> discriminator
+column mapping do not need an explicit <code class="classname">DiscriminatorColumn
+</code> annotation.
+ </p>
+ <div class="example"><a name="jpa_overview_mapping_discrimex"></a><p class="title"><b>Example 13.9.
+ Discriminator Mapping
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+package org.mag;
+
+@Entity
+@IdClass(Magazine.MagazineId.class)
+@Table(name="MAG")
+@DiscriminatorValue("Mag")
+public class Magazine {
+
+ @Column(length=9)
+ @Id private String isbn;
+ @Id private String title;
+
+ ...
+
+ public static class MagazineId {
+ ...
+ }
+}
+
+@Entity
+@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
+@SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ")
+public class Article {
+
+ @Id
+ @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq")
+ private long id;
+
+ ...
+}
+
+
+package org.mag.pub;
+
+@Entity
+@Table(name="COMP")
+public class Company {
+
+ @Column(name="CID")
+ @Id private long id;
+
+ ...
+}
+
+@Entity
+@Table(name="AUTH")
+public class Author {
+
+ @Id
+ @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen")
+ @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK",
+ valueColumnName="AID")
+ @Column(name="AID", columnDefinition="INTEGER64")
+ private long id;
+
+ ...
+}
+
+@Embeddable
+public class Address {
+ ...
+}
+
+
+package org.mag.subscribe;
+
+@MappedSuperclass
+public abstract class Document {
+
+ @Id
+ @GeneratedValue(strategy=GenerationType.IDENTITY)
+ private long id;
+
+ ...
+}
+
+@Entity
+@Table(schema="CNTRCT")
+@Inheritance(strategy=InheritanceType.JOINED)
+@DiscriminatorColumn(name="CTYPE")
+public class Contract
+ extends Document {
+ ...
+}
+
+@Entity
+@Table(name="SUB", schema="CNTRCT")
+@DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER)
+@DiscriminatorValue("1")
+public class Subscription {
+
+ @Id
+ @GeneratedValue(strategy=GenerationType.IDENTITY)
+ private long id;
+
+ ...
+
+ @Entity
+ @Table(name="LINE_ITEM", schema="CNTRCT")
+ public static class LineItem
+ extends Contract {
+ ...
+ }
+}
+
+@Entity(name="Lifetime")
+@DiscriminatorValue("2")
+public class LifetimeSubscription
+ extends Subscription {
+ ...
+}
+
+@Entity(name="Trial")
+@DiscriminatorValue("3")
+public class TrialSubscription
+ extends Subscription {
+ ...
+}
+</pre>
+ <p>
+The same metadata expressed 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">
+ <attributes>
+ <id name="id">
+ <generated-value strategy="IDENTITY"/>
+ </id>
+ ...
+ </attributes>
+ </mapped-superclass>
+ <entity class="org.mag.Magazine">
+ <table name="MAG"/>
+ <id-class="org.mag.Magazine.MagazineId"/>
+ <discriminator-value>Mag</discriminator-value>
+ <attributes>
+ <id name="isbn">
+ <column length="9"/>
+ </id>
+ <id name="title"/>
+ ...
+ </attributes>
+ </entity>
+ <entity class="org.mag.Article">
+ <table name="ART">
+ <unique-constraint>
+ <column-name>TITLE</column-name>
+ </unique-constraint>
+ </table>
+ <sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/>
+ <attributes>
+ <id name="id">
+ <generated-value strategy="SEQUENCE" generator="ArticleSeq"/>
+ </id>
+ ...
+ </attributes>
+ </entity>
+ <entity class="org.mag.pub.Company">
+ <table name="COMP"/>
+ <attributes>
+ <id name="id">
+ <column name="CID"/>
+ </id>
+ ...
+ </attributes>
+ </entity>
+ <entity class="org.mag.pub.Author">
+ <table name="AUTH"/>
+ <attributes>
+ <id name="id">
+ <column name="AID" column-definition="INTEGER64"/>
+ <generated-value strategy="TABLE" generator="AuthorGen"/>
+ <table-generator name="AuthorGen" table="AUTH_GEN"
+ pk-column-name="PK" value-column-name="AID"/>
+ </id>
+ ...
+ </attributes>
+ </entity>
+ <entity class="org.mag.subcribe.Contract">
+ <table schema="CNTRCT"/>
+ <inheritance strategy="JOINED"/>
+ <discriminator-column name="CTYPE"/>
+ <attributes>
+ ...
+ </attributes>
+ </entity>
+ <entity class="org.mag.subcribe.Subscription">
+ <table name="SUB" schema="CNTRCT"/>
+ <inheritance strategy="SINGLE_TABLE"/>
+ <discriminator-value>1</discriminator-value>
+ <discriminator-column name="KIND" discriminator-type="INTEGER"/>
+ <attributes>
+ <id name="id">
+ <generated-value strategy="IDENTITY"/>
+ </id>
+ ...
+ </attributes>
+ </entity>
+ <entity class="org.mag.subscribe.Subscription.LineItem">
+ <table name="LINE_ITEM" schema="CNTRCT"/>
+ <primary-key-join-column name="ID" referenced-column-name="PK"/>
+ ...
+ </entity>
+ <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime">
+ <discriminator-value>2</discriminator-value>
+ ...
+ </entity>
+ <entity class="org.mag.subscribe.TrialSubscription" name="Trial">
+ <discriminator-value>3</discriminator-value>
+ ...
+ </entity>
+</entity-mappings>
+</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="jpa_overview_mapping_inher.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_mapping.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_mapping_field.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.
+ Inheritance
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 8.
+ Field 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/jpa_overview_mapping_discrim.html
------------------------------------------------------------------------------
svn:eol-style = native