You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [4/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_mapping.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_mapping.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_mapping.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_mapping.xml Thu Aug 24 13:41:12 2006
@@ -1,155 +1,192 @@
-
- <chapter id="jpa_overview_mapping">
- <title>Mapping Metadata</title>
- <indexterm zone="jpa_overview_mapping">
- <primary>mapping metadata</primary>
- </indexterm>
- <indexterm>
- <primary>entities</primary>
- <secondary>mapping to database</secondary>
- <see>mapping metadata</see>
- </indexterm>
- <indexterm>
- <primary>metadata</primary>
- <secondary>mapping metadata</secondary>
- <see>mapping metadata</see>
- </indexterm>
- <indexterm>
- <primary>ORM</primary>
- <seealso>mapping metadata</seealso>
- </indexterm>
- <indexterm zone="jpa_overview_mapping">
- <primary>EJB</primary>
- <secondary>object-relational mapping</secondary>
- <seealso>mapping metadata</seealso>
- </indexterm>
- <para><emphasis>Object-relational mapping</emphasis> is the process of mapping
- entities to relational database tables. In EJB persistence, you perform
- object/relational mapping through <emphasis>mapping metadata</emphasis>.
- Mapping metadata uses annotations to describe how to link your object model
- to your relational model.
- </para>
- <note>
+<chapter id="jpa_overview_mapping">
+ <title>
+ Mapping Metadata
+ </title>
+ <indexterm zone="jpa_overview_mapping">
+ <primary>
+ mapping metadata
+ </primary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ entities
+ </primary>
+ <secondary>
+ mapping to database
+ </secondary>
+ <see>
+ mapping metadata
+ </see>
+ </indexterm>
+ <indexterm>
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ mapping metadata
+ </secondary>
+ <see>
+ mapping metadata
+ </see>
+ </indexterm>
+ <indexterm>
+ <primary>
+ ORM
+ </primary>
+ <seealso>
+ mapping metadata
+ </seealso>
+ </indexterm>
+ <indexterm zone="jpa_overview_mapping">
+ <primary>
+ JPA
+ </primary>
+ <secondary>
+ object-relational mapping
+ </secondary>
+ <seealso>
+ mapping metadata
+ </seealso>
+ </indexterm>
+ <para>
+<emphasis>Object-relational mapping</emphasis> is the process of mapping
+entities to relational database tables. In JPA, you perform
+object/relational mapping through <emphasis>mapping metadata</emphasis>.
+Mapping metadata uses annotations to describe how to link your object model to
+your relational model.
+ </para>
+ <note>
<para>
- OpenJPA offers tools to automate mapping and schema creation. See
- <xref linkend="ref_guide_mapping"/> in the Reference Guide.
+OpenJPA offers tools to automate mapping and schema creation. See
+<xref linkend="ref_guide_mapping"></xref> in the Reference Guide.
+ </para>
+ </note>
+ <para>
+Throughout this chapter, we will draw on the object model introduced in
+<xref linkend="jpa_overview_meta"></xref>. 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.
</para>
- </note>
- <para>
- Throughout this chapter, we will draw on the object model introduced in
- <xref linkend="jpa_overview_meta"/>. 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.
- </para>
- <mediaobject>
+ <mediaobject>
<imageobject>
-<!-- PNG image data, 553 x 580 (see README) -->
- <imagedata fileref="img/jpa-meta-model.png" width="369px"/>
+ <!-- PNG image data, 553 x 580 (see README) -->
+ <imagedata fileref="img/jpa-meta-model.png" width="369px">
+ </imagedata>
</imageobject>
- </mediaobject>
- <para>
- All mapping metadata is optional. Where no explicit mapping metadata is
- given, EJB 3 persistence 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.
- </para>
- <section id="jpa_overview_mapping_table">
- <title>Table</title>
+ </mediaobject>
+ <para>
+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.
+ </para>
+ <section id="jpa_overview_mapping_table">
+ <title>
+ Table
+ </title>
<indexterm zone="jpa_overview_mapping_table">
- <primary>mapping metadata</primary>
- <secondary>class</secondary>
- <tertiary>table attribute</tertiary>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ class
+ </secondary>
+ <tertiary>
+ table attribute
+ </tertiary>
</indexterm>
<para>
- The <classname>Table</classname> annotation specifies the table
- for an entity class. If you omit the <classname>Table</classname>
- 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
- <xref linkend="jpa_overview_mapping_inher"/>.
- </para>
- <para><classname>Table</classname>s have the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>String name</literal>: The name of the table.
- Defaults to the unqualified entity class name.
+The <classname>Table</classname> annotation specifies the table for an entity
+class. If you omit the <classname>Table</classname> 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
+<xref linkend="jpa_overview_mapping_inher"></xref>.
</para>
- </listitem>
- <listitem>
- <para><literal>String schema</literal>: The table's schema. If you
- do not name a schema, EJB uses the default schema for the
- database connection.
- </para>
- </listitem>
- <listitem>
- <para><literal>String catalog</literal>: The table's catalog. If
- you do not name a catalog, EJB uses the default catalog for the
- database connection.
- </para>
- </listitem>
- <listitem>
- <para><literal>UniqueConstraint[] uniqueConstraints</literal>: An
- array of unique constraints to place on the table.
- We cover unique constraints below. Defaults
- to an empty array.
+ <para>
+<classname>Table</classname>s have the following properties:
</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>String name</literal>: The name of the table. Defaults to the
+unqualified entity class name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>String schema</literal>: The table's schema. If you do not name a
+schema, JPA uses the default schema for the database connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>String catalog</literal>: The table's catalog. If you do not name a
+catalog, JPA uses the default catalog for the database connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>UniqueConstraint[] uniqueConstraints</literal>: An array of unique
+constraints to place on the table. We cover unique constraints below. Defaults
+to an empty array.
+ </para>
+ </listitem>
</itemizedlist>
<para>
- The equivalent XML element is <literal>table</literal>. It has
- the following attributes, which correspond to the annotation
- properties above:
- </para>
+The equivalent XML element is <literal>table</literal>. It has the following
+attributes, which correspond to the annotation properties above:
+ </para>
<itemizedlist>
- <listitem>
- <para>
- <literal>name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>schema</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>catalog</literal>
- </para>
- </listitem>
+ <listitem>
+ <para>
+<literal>name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>schema</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>catalog</literal>
+ </para>
+ </listitem>
</itemizedlist>
<para>
- The <literal>table</literal> element also accepts nested <literal>
- unique-constraint</literal> elements representing unique constraints.
- We will detail unique constraints shortly.
- </para>
+The <literal>table</literal> element also accepts nested <literal>
+unique-constraint</literal> elements representing unique constraints. We will
+detail unique constraints shortly.
+ </para>
<para>
- Sometimes, some of the fields in a class are mapped to secondary
- tables. In that case, use the class' <classname>Table</classname>
- annotation to name what you consider the class' primary table. Later,
- we will see how to map certain fields to other tables.
- </para>
+Sometimes, some of the fields in a class are mapped to secondary tables. In that
+case, use the class' <classname>Table</classname> annotation to name what you
+consider the class' primary table. Later, we will see how to map certain fields
+to other tables.
+ </para>
<para>
- The example below maps classes to tables according to the following
- diagram. The <literal>CONTRACT</literal>, <literal>SUB</literal>, and
- <literal>LINE_ITEM</literal> tables are in the <literal>CNTRCT</literal>
- schema; all other tables are in the default schema.
- </para>
+The example below maps classes to tables according to the following diagram. The
+<literal>CONTRACT</literal>, <literal>SUB</literal>, and <literal>LINE_ITEM
+</literal> tables are in the <literal>CNTRCT</literal> schema; all other tables
+are in the default schema.
+ </para>
<mediaobject>
- <imageobject>
-<!-- PNG image data, 513 x 410 (see README) -->
- <imagedata fileref="img/mapping-tables.png" width="341px"/>
- </imageobject>
+ <imageobject>
+ <!-- PNG image data, 513 x 410 (see README) -->
+ <imagedata fileref="img/mapping-tables.png" width="341px">
+ </imagedata>
+ </imageobject>
</mediaobject>
<para>
- Note that the diagram does not include our model's <classname>Document
- </classname> and <classname>Address</classname> classes. Mapped
- superclasses and embeddable classes are never mapped to tables.
- </para>
+Note that the diagram does not include our model's <classname>Document
+</classname> and <classname>Address</classname> classes. Mapped superclasses and
+embeddable classes are never mapped to tables.
+ </para>
<example id="jpa_overview_mapping_classex">
- <title>Mapping Classes</title>
- <programlisting format="linespecific">
+ <title>
+ Mapping Classes
+ </title>
+<programlisting>
package org.mag;
@Entity
@@ -241,8 +278,10 @@
...
}
</programlisting>
- <para>The same mapping information expressed in XML:</para>
- <programlisting format="linespecific">
+ <para>
+The same mapping information expressed in XML:
+ </para>
+<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"
@@ -291,58 +330,70 @@
</entity-mappings>
</programlisting>
</example>
- </section>
- <section id="jpa_overview_mapping_unq">
- <title>Unique Constraints</title>
+ </section>
+ <section id="jpa_overview_mapping_unq">
+ <title>
+ Unique Constraints
+ </title>
<indexterm zone="jpa_overview_mapping_unq">
- <primary>mapping metadata</primary>
- <secondary>unique constraints</secondary>
- <seealso>unique constraints</seealso>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ unique constraints
+ </secondary>
+ <seealso>
+ unique constraints
+ </seealso>
</indexterm>
<indexterm zone="jpa_overview_mapping_unq">
- <primary>unique constraints</primary>
+ <primary>
+ unique constraints
+ </primary>
</indexterm>
<para>
- Unique constraints ensure that the data in a column or combination of
- columns is unique for each row. A table's primary key, for example,
- functions as an implicit unique constraint. In EJB persistence, you
- represent other unique constraints with an array of <classname>
- UniqueConstraint</classname> annotations within the table annotation.
- The unique constraints you define are used during table creation to
- generate the proper database constraints, and may also be used at
- runtime to order <literal>INSERT</literal>, <literal>UPDATE</literal>,
- and <literal>DELETE</literal> statements. For example, suppose there
- is a unique constraint on the columns of field <literal>F</literal>.
- In the same transaction, you remove an object <literal>A</literal>
- and persist a new object <literal>B</literal>, both with the same
- <literal>F</literal> value. The EJB persistence runtime must ensure
- that the SQL deleting <literal>A</literal> is sent to the database
- before the SQL inserting <literal>B</literal> to avoid a unique
- constraint violation.
- </para>
- <para><classname>UniqueConstraint</classname> has a single property:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>String[] columnNames</literal>: The names of the
- columns the constraint spans.
+Unique constraints ensure that the data in a column or combination of columns is
+unique for each row. A table's primary key, for example, functions as an
+implicit unique constraint. In JPA, you represent other unique
+constraints with an array of <classname> UniqueConstraint</classname>
+annotations within the table annotation. The unique constraints you define are
+used during table creation to generate the proper database constraints, and may
+also be used at runtime to order <literal>INSERT</literal>, <literal>UPDATE
+</literal>, and <literal>DELETE</literal> statements. For example, suppose there
+is a unique constraint on the columns of field <literal>F</literal>. In the
+same transaction, you remove an object <literal>A</literal> and persist a new
+object <literal>B</literal>, both with the same <literal>F</literal> value. The
+JPA runtime must ensure that the SQL deleting <literal>A</literal>
+is sent to the database before the SQL inserting <literal>B</literal> to avoid a
+unique constraint violation.
</para>
- </listitem>
+ <para>
+<classname>UniqueConstraint</classname> has a single property:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>String[] columnNames</literal>: The names of the columns the
+constraint spans.
+ </para>
+ </listitem>
</itemizedlist>
<para>
- In XML, unique constraints are represented by nesting
- <literal>unique-constraint</literal> elements within the <literal>
- table</literal> element. Each <literal>unique-constraint</literal>
- element in turn nests <literal>column-name</literal> text elements
- to enumerate the contraint's columns.
- </para>
+In XML, unique constraints are represented by nesting <literal>
+unique-constraint</literal> elements within the <literal> table</literal>
+element. Each <literal>unique-constraint</literal> element in turn nests
+<literal>column-name</literal> text elements to enumerate the contraint's
+columns.
+ </para>
<example id="jpa_overview_mapping_unq_attrex">
- <title>Defining a Unique Constraint</title>
- <para>
- The following defines a unique constraint on the <literal>
- TITLE</literal> column of the <literal>ART</literal> table:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Defining a Unique Constraint
+ </title>
+ <para>
+The following defines a unique constraint on the <literal> TITLE</literal>
+column of the <literal>ART</literal> table:
+ </para>
+<programlisting>
@Entity
@Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE"))
public class Article
@@ -350,8 +401,10 @@
...
}
</programlisting>
- <para>The same metadata expressed in XML form:</para>
- <programlisting format="linespecific">
+ <para>
+The same metadata expressed in XML form:
+ </para>
+<programlisting>
<entity class="org.mag.Article">
<table name="ART">
<unique-constraint>
@@ -362,184 +415,307 @@
</entity>
</programlisting>
</example>
- </section>
- <section id="jpa_overview_mapping_column">
- <title>Column</title>
+ </section>
+ <section id="jpa_overview_mapping_column">
+ <title>
+ Column
+ </title>
<indexterm zone="jpa_overview_mapping_column">
- <primary>mapping metadata</primary>
- <secondary>Column</secondary>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
</indexterm>
<indexterm zone="jpa_overview_mapping_column">
- <primary>Column</primary>
- <secondary>in mapping metadata</secondary>
- <seealso>mapping metadata</seealso>
+ <primary>
+ Column
+ </primary>
+ <secondary>
+ in mapping metadata
+ </secondary>
+ <seealso>
+ mapping metadata
+ </seealso>
</indexterm>
<para>
- In the previous section, we saw that a <classname>UniqueConstraint
- </classname> uses an array of column names. Field mappings,
- however, use full-fledged <classname>Column</classname> annotations.
- Column annotations have the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>name property</tertiary></indexterm><literal>String name</literal>: The column name. Defaults to
- the field name.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>columnDefinition property</tertiary></indexterm><literal>String columnDefinition</literal>: 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 <literal>columnDefinition</literal> as the declared
- column type. If no <literal>columnDefinition</literal> is
- given, the vendor will choose an appropriate default based on
- the field type combined with the column's length, precision,
- and scale.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>length property</tertiary></indexterm><literal>int length</literal>: The column length. This
- property is typically only used during table creation, though
- some vendors might use it to validate data before flushing.
- <literal>CHAR</literal> and <literal>VARCHAR
- </literal> columns typically default to a length of 255; other
- column types use the database default.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>precision property</tertiary></indexterm><literal>int precision</literal>: The precision of a numeric
- column. This property is often used in
- conjunction with <literal>scale</literal> to form the
- proper column type name during table creation.
+In the previous section, we saw that a <classname>UniqueConstraint</classname>
+uses an array of column names. Field mappings, however, use full-fledged
+<classname>Column</classname> annotations. Column annotations have the following
+properties:
</para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>scale property</tertiary></indexterm><literal>int scale</literal>: The number of decimal digits a
- numeric column can hold. This property is often used in
- conjunction with <literal>precision</literal> to form the
- proper column type name during table creation.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>nullable property</tertiary></indexterm><literal>boolean nullable</literal>: 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 <literal>true</literal>.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>insertable property</tertiary></indexterm><literal>boolean insertable</literal>: By setting this property
- to <literal>false</literal>, you can omit the column from
- SQL <literal>INSERT</literal> statements.
- Defaults to <literal>true</literal>.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>updatable property</tertiary></indexterm><literal>boolean updatable</literal>: By setting this property
- to <literal>false</literal>, you can omit the column from
- SQL <literal>UPDATE</literal> statements.
- Defaults to <literal>true</literal>.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>Column</secondary><tertiary>table property</tertiary></indexterm><literal>String table</literal>: 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.
- </para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ name property
+ </tertiary>
+ </indexterm>
+<literal>String name</literal>: The column name. Defaults to the field name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ columnDefinition property
+ </tertiary>
+ </indexterm>
+<literal>String columnDefinition</literal>: 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 <literal>columnDefinition</literal> as the declared column type. If no
+<literal>columnDefinition</literal> is given, the vendor will choose an
+appropriate default based on the field type combined with the column's length,
+precision, and scale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ length property
+ </tertiary>
+ </indexterm>
+<literal>int length</literal>: The column length. This property is typically
+only used during table creation, though some vendors might use it to validate
+data before flushing. <literal>CHAR</literal> and <literal>VARCHAR</literal>
+columns typically default to a length of 255; other column types use the
+database default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ precision property
+ </tertiary>
+ </indexterm>
+<literal>int precision</literal>: The precision of a numeric column. This
+property is often used in conjunction with <literal>scale</literal> to form the
+proper column type name during table creation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ scale property
+ </tertiary>
+ </indexterm>
+<literal>int scale</literal>: The number of decimal digits a numeric column can
+hold. This property is often used in conjunction with <literal>precision
+</literal> to form the proper column type name during table creation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ nullable property
+ </tertiary>
+ </indexterm>
+<literal>boolean nullable</literal>: 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 <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ insertable property
+ </tertiary>
+ </indexterm>
+<literal>boolean insertable</literal>: By setting this property to <literal>
+false</literal>, you can omit the column from SQL <literal>INSERT</literal>
+statements. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ updatable property
+ </tertiary>
+ </indexterm>
+<literal>boolean updatable</literal>: By setting this property to <literal>
+false</literal>, you can omit the column from SQL <literal>UPDATE</literal>
+statements. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ Column
+ </secondary>
+ <tertiary>
+ table property
+ </tertiary>
+ </indexterm>
+<literal>String table</literal>: 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.
+ </para>
+ </listitem>
</itemizedlist>
<para>
- The equivalent XML element is <literal>column</literal>. This
- element has attributes that are exactly equivalent to the <classname>
- Column</classname> annotation's properties described above:
- </para>
+The equivalent XML element is <literal>column</literal>. This element has
+attributes that are exactly equivalent to the <classname> Column</classname>
+annotation's properties described above:
+ </para>
<itemizedlist>
- <listitem>
- <para>
- <literal>name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>column-definition</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>length</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>precision</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>scale</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>insertable</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>updatable</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>table</literal>
- </para>
- </listitem>
+ <listitem>
+ <para>
+<literal>name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>column-definition</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>length</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>precision</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>scale</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>insertable</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>updatable</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>table</literal>
+ </para>
+ </listitem>
</itemizedlist>
- </section>
- <section id="jpa_overview_mapping_id">
- <title>Identity Mapping</title>
+ </section>
+ <section id="jpa_overview_mapping_id">
+ <title>
+ Identity Mapping
+ </title>
<indexterm zone="jpa_overview_mapping_id">
- <primary>Id</primary>
+ <primary>
+ Id
+ </primary>
</indexterm>
<indexterm zone="jpa_overview_mapping_id">
- <primary>mapping metadata</primary>
- <secondary>identity</secondary>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ identity
+ </secondary>
</indexterm>
<indexterm zone="jpa_overview_mapping_id">
- <primary>identity</primary>
- <secondary>mapping</secondary>
+ <primary>
+ identity
+ </primary>
+ <secondary>
+ mapping
+ </secondary>
</indexterm>
<para>
- With our new knowledge of columns, we can map the identity fields
- of our entities. The diagram below now includes primary key columns
- for our model's tables. The primary key column for
- <classname>Author</classname> uses nonstandard type <literal>
- INTEGER64</literal>, and the <literal>Magazine.isbn</literal> field is
- mapped to a <literal>VARCHAR(9)</literal> column instead of a
- <literal>VARCHAR(255)</literal> column, which is the default for string
- fields. We do not need to point out either one of these oddities to
- the EJB persistence implementation for runtime use. If, however, we
- want to use the EJB persistence implementation to create our tables for
- us, it needs to know about any desired non-default column types.
- Therefore, the example following the diagram includes this data in its
- encoding of our mappings.
- </para>
+With our new knowledge of columns, we can map the identity fields of our
+entities. The diagram below now includes primary key columns for our model's
+tables. The primary key column for <classname>Author</classname> uses
+nonstandard type <literal> INTEGER64</literal>, and the <literal>Magazine.isbn
+</literal> field is mapped to a <literal>VARCHAR(9)</literal> column instead of
+a <literal>VARCHAR(255)</literal> column, which is the default for string
+fields. We do not need to point out either one of these oddities to the JPA
+implementation for runtime use. If, however, we want to use the JPA
+implementation to create our tables for us, it needs to know about
+any desired non-default column types. Therefore, the example following the
+diagram includes this data in its encoding of our mappings.
+ </para>
<mediaobject>
- <imageobject>
-<!-- PNG image data, 513 x 410 (see README) -->
- <imagedata fileref="img/jpa-mapping-identity.png" width="341px"/>
- </imageobject>
+ <imageobject>
+ <!-- PNG image data, 513 x 410 (see README) -->
+ <imagedata fileref="img/jpa-mapping-identity.png" width="341px">
+ </imagedata>
+ </imageobject>
</mediaobject>
<para>
- Note that many of our identity fields do not need to specify column
- information, because they use the default column name and type.
- </para>
+Note that many of our identity fields do not need to specify column information,
+because they use the default column name and type.
+ </para>
<example id="jpa_overview_mapping_identityex">
- <title>Identity Mapping</title>
- <programlisting format="linespecific">
+ <title>
+ Identity Mapping
+ </title>
+<programlisting>
package org.mag;
@Entity
@@ -649,11 +825,11 @@
...
}
</programlisting>
- <para>
- The same metadata for <literal>Magazine</literal> and
- <literal>Company</literal> expressed in XML form:
- </para>
- <programlisting format="linespecific">
+ <para>
+The same metadata for <literal>Magazine</literal> and <literal>Company</literal>
+expressed in XML form:
+ </para>
+<programlisting>
<entity class="org.mag.Magazine">
<id-class class="org.mag.Magazine.Magazine.MagazineId"/>
<table name="MAG"/>
@@ -676,274 +852,402 @@
</entity>
</programlisting>
</example>
- </section>
- <section id="jpa_overview_mapping_sequence">
- <title>Generators</title>
+ </section>
+ <section id="jpa_overview_mapping_sequence">
+ <title>
+ Generators
+ </title>
<indexterm zone="jpa_overview_mapping_sequence">
- <primary>generators</primary>
- <secondary>mapping metadata</secondary>
+ <primary>
+ generators
+ </primary>
+ <secondary>
+ mapping metadata
+ </secondary>
</indexterm>
<indexterm zone="jpa_overview_mapping_sequence">
- <primary>mapping metadata</primary>
- <secondary>generators</secondary>
- <seealso>TableGenerator</seealso>
- <seealso>SequenceGenerator</seealso>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ generators
+ </secondary>
+ <seealso>
+ TableGenerator
+ </seealso>
+ <seealso>
+ SequenceGenerator
+ </seealso>
</indexterm>
<para>
- One aspect of identity mapping not covered in the previous section is
- EJB's ability to automatically assign a value to your numeric identity
- fields using <emphasis>generators</emphasis>. We discussed the
- available generator types in <xref linkend="jpa_overview_meta_id"/>.
- Now we show you how to define named generators.
- </para>
+One aspect of identity mapping not covered in the previous section is JPA's
+ability to automatically assign a value to your numeric identity fields using
+<emphasis>generators</emphasis>. We discussed the available generator types in
+<xref linkend="jpa_overview_meta_id"></xref>. Now we show you how to define
+named generators.
+ </para>
<section id="jpa_overview_mapping_sequence_seqgen">
- <title>Sequence Generator</title>
- <indexterm zone="jpa_overview_mapping_sequence_seqgen">
- <primary>generators</primary>
- <secondary>SequenceGenerator</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_mapping_sequence_seqgen">
- <primary>SequenceGenerator</primary>
- </indexterm>
- <para>
- Most databases allow you to create native sequences. These are
- database structures that generate increasing
- numeric values. The <classname>SequenceGenerator</classname>
- annotation represents a named database sequence. You can place
- the annotation on any package, entity class, persistent field
- declaration (if your entity uses field access), or getter method for
- a persistent property (if your entity uses property access).
- <classname>SequenceGenerator</classname> has the following
- properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><indexterm><primary>SequenceGenerator</primary><secondary>name property</secondary></indexterm><literal>String name</literal>: The generator name. This
- property is required.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>SequenceGenerator</primary><secondary>sequenceName property</secondary></indexterm><literal>String sequenceName</literal>: The name of the
- database sequence. If you do not specify the database
- sequence, your vendor will choose an appropriate default.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>SequenceGenerator</primary><secondary>initialValue property</secondary></indexterm><literal>int initialValue</literal>: The initial sequence
- value.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>SequenceGenerator</primary><secondary>allocationSize property</secondary></indexterm><literal>int allocationSize</literal>: Some databases can
- pre-allocate groups of sequence values. This allows the
- database to service sequence requests from cache, rather
- than physically incrementing the sequence with every
- request. This allocation size defaults to 50.
- </para>
- </listitem>
- </itemizedlist>
- <note>
+ <title>
+ Sequence Generator
+ </title>
+ <indexterm zone="jpa_overview_mapping_sequence_seqgen">
+ <primary>
+ generators
+ </primary>
+ <secondary>
+ SequenceGenerator
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_mapping_sequence_seqgen">
+ <primary>
+ SequenceGenerator
+ </primary>
+ </indexterm>
<para>
- OpenJPA allows you to use describe one of OpenJPA's built-in generator
- implementations in the <literal>sequenceName</literal> property.
- You can also set the <literal>sequenceName</literal> to
- <literal>system</literal> to use the system sequence defined by
- the <link linkend="openjpa.Sequence"><literal>openjpa.Sequence
- </literal></link> configuration property. See the Reference
- Guide's <xref linkend="ref_guide_sequence"/> for details.
- </para>
- </note>
- <para>
- The XML element for a sequence generator
- is <literal>sequence-generator</literal>. Its attributes mirror
- the above annotation's properties:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>sequence-name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>initial-value</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>allocation-size</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- To use a sequence generator, set your <classname>GeneratedValue
- </classname> annotation's <literal>strategy</literal>
- property to <literal>GenerationType.SEQUENCE</literal>, and its
- <literal>generator</literal> property to the sequence generator's
- declared name. Or equivalently, set your <literal>generated-value
- </literal> XML element's <literal>strategy</literal> attribute to
- <literal>SEQUENCE</literal> and its <literal>generator</literal>
- attribute to the generator name.
- </para>
+Most databases allow you to create native sequences. These are database
+structures that generate increasing numeric values. The <classname>
+SequenceGenerator</classname> annotation represents a named database sequence.
+You can place the annotation on any package, entity class, persistent field
+declaration (if your entity uses field access), or getter method for a
+persistent property (if your entity uses property access). <classname>
+SequenceGenerator</classname> has the following properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ SequenceGenerator
+ </primary>
+ <secondary>
+ name property
+ </secondary>
+ </indexterm>
+<literal>String name</literal>: The generator name. This property is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ SequenceGenerator
+ </primary>
+ <secondary>
+ sequenceName property
+ </secondary>
+ </indexterm>
+<literal>String sequenceName</literal>: The name of the database sequence. If
+you do not specify the database sequence, your vendor will choose an appropriate
+default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ SequenceGenerator
+ </primary>
+ <secondary>
+ initialValue property
+ </secondary>
+ </indexterm>
+<literal>int initialValue</literal>: The initial sequence value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ SequenceGenerator
+ </primary>
+ <secondary>
+ allocationSize property
+ </secondary>
+ </indexterm>
+<literal>int allocationSize</literal>: Some databases can pre-allocate groups
+of sequence values. This allows the database to service sequence requests from
+cache, rather than physically incrementing the sequence with every request. This
+allocation size defaults to 50.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+OpenJPA allows you to use describe one of OpenJPA's built-in generator
+implementations in the <literal>sequenceName</literal> property. You can also
+set the <literal>sequenceName</literal> to <literal>system</literal> to use the
+system sequence defined by the <link linkend="openjpa.Sequence"><literal>
+openjpa.Sequence</literal></link> configuration property. See the Reference
+Guide's <xref linkend="ref_guide_sequence"></xref> for details.
+ </para>
+ </note>
+ <para>
+The XML element for a sequence generator is <literal>sequence-generator
+</literal>. Its attributes mirror the above annotation's properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>sequence-name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>initial-value</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>allocation-size</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+To use a sequence generator, set your <classname>GeneratedValue</classname>
+annotation's <literal>strategy</literal> property to <literal>
+GenerationType.SEQUENCE</literal>, and its <literal>generator</literal> property
+to the sequence generator's declared name. Or equivalently, set your <literal>
+generated-value</literal> XML element's <literal>strategy</literal> attribute to
+<literal>SEQUENCE</literal> and its <literal>generator</literal> attribute to
+the generator name.
+ </para>
</section>
<section id="jpa_overview_mapping_sequence_tablegen">
- <title>TableGenerator</title>
- <indexterm zone="jpa_overview_mapping_sequence_tablegen">
- <primary>generators</primary>
- <secondary>TableGenerator</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_mapping_sequence_tablegen">
- <primary>TableGenerator</primary>
- </indexterm>
- <para>
- A <classname>TableGenerator</classname> refers to a database table
- used to store increasing sequence values for one or more entities.
- As with <classname>SequenceGenerator</classname>, you can place
- the <classname>TableGenerator</classname> annotation on any
- package, entity class, persistent field declaration (if your
- entity uses field access), or getter method for a persistent
- property (if your entity uses property access).
- <classname>TableGenerator</classname> has the following
- properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>name property</secondary></indexterm><literal>String name</literal>: The generator name. This
- property is required.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>table property</secondary></indexterm><literal>String table</literal>: The name of the
- generator table. If left unspecified, your vendor will
- choose a default table.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>schema property</secondary></indexterm><literal>String schema</literal>: The named table's
- schema.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>catalog property</secondary></indexterm><literal>String catalog</literal>: The named table's
- catalog.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>pkColumnName property</secondary></indexterm><literal>String pkColumnName</literal>: The name of the
- primary key column in the generator table. If
- unspecified, your implementation will choose a
- default.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>valueColumnName property</secondary></indexterm><literal>String valueColumnName</literal>: The name of
- the column that holds the sequence value.
- If unspecified, your implementation will
- choose a default.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>pkColumnValue property</secondary></indexterm><literal>String pkColumnValue</literal>: The primary key
- column value of the row in the generator table holding
- this sequence value. You can use the same generator table
- for multiple logical sequences by supplying different
- <literal>pkColumnValue</literal>s. If you do not specify
- a value, the implementation will supply a default.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>initialValue property</secondary></indexterm><literal>int initialValue</literal>: The value of the
- generator's first issued number.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>TableGenerator</primary><secondary>allocationSize property</secondary></indexterm><literal>int allocationSize</literal>: The number of values
- to allocate in memory for each trip to the database.
- Allocating values in memory allows the EJB persistence
- runtime to avoid accessing the database for every sequence
- request. This number also specifies the amount
- that the sequence value is incremented each time the
- generator table is updated. Defaults to 50.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The XML equivalent is the <literal>table-generator</literal>
- element. This element's attributes correspond exactly to the
- above annotation's properties:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>table</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>schema</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>catalog</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pk-column-name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>value-column-name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pk-column-value</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>initial-value</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>allocation-size</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- To use a table generator, set your <classname>GeneratedValue
- </classname> annotation's <literal>strategy</literal>
- property to <literal>GenerationType.TABLE</literal>, and its
- <literal>generator</literal> property to the table generator's
- declared name. Or equivalently, set your <literal>generated-value
- </literal> XML element's <literal>strategy</literal> attribute to
- <literal>TABLE</literal> and its <literal>generator</literal>
- attribute to the generator name.
- </para>
+ <title>
+ TableGenerator
+ </title>
+ <indexterm zone="jpa_overview_mapping_sequence_tablegen">
+ <primary>
+ generators
+ </primary>
+ <secondary>
+ TableGenerator
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_mapping_sequence_tablegen">
+ <primary>
+ TableGenerator
+ </primary>
+ </indexterm>
+ <para>
+A <classname>TableGenerator</classname> refers to a database table used to store
+increasing sequence values for one or more entities. As with <classname>
+SequenceGenerator</classname>, you can place the <classname>TableGenerator
+</classname> annotation on any package, entity class, persistent field
+declaration (if your entity uses field access), or getter method for a
+persistent property (if your entity uses property access). <classname>
+TableGenerator</classname> has the following properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ name property
+ </secondary>
+ </indexterm>
+<literal>String name</literal>: The generator name. This property is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ table property
+ </secondary>
+ </indexterm>
+<literal>String table</literal>: The name of the generator table. If left
+unspecified, your vendor will choose a default table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ schema property
+ </secondary>
+ </indexterm>
+<literal>String schema</literal>: The named table's schema.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ catalog property
+ </secondary>
+ </indexterm>
+<literal>String catalog</literal>: The named table's catalog.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ pkColumnName property
+ </secondary>
+ </indexterm>
+<literal>String pkColumnName</literal>: The name of the primary key column in
+the generator table. If unspecified, your implementation will choose a default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ valueColumnName property
+ </secondary>
+ </indexterm>
+<literal>String valueColumnName</literal>: The name of the column that holds
+the sequence value. If unspecified, your implementation will choose a default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ pkColumnValue property
+ </secondary>
+ </indexterm>
+<literal>String pkColumnValue</literal>: The primary key column value of the
+row in the generator table holding this sequence value. You can use the same
+generator table for multiple logical sequences by supplying different <literal>
+pkColumnValue</literal> s. If you do not specify a value, the implementation
+will supply a default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ initialValue property
+ </secondary>
+ </indexterm>
+<literal>int initialValue</literal>: The value of the generator's first issued
+number.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ TableGenerator
+ </primary>
+ <secondary>
+ allocationSize property
+ </secondary>
+ </indexterm>
+<literal>int allocationSize</literal>: The number of values to allocate in
+memory for each trip to the database. Allocating values in memory allows the JPA
+runtime to avoid accessing the database for every sequence request.
+This number also specifies the amount that the sequence value is incremented
+each time the generator table is updated. Defaults to 50.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The XML equivalent is the <literal>table-generator</literal> element. This
+element's attributes correspond exactly to the above annotation's properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>table</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>schema</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>catalog</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>pk-column-name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>value-column-name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>pk-column-value</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>initial-value</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>allocation-size</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+To use a table generator, set your <classname>GeneratedValue</classname>
+annotation's <literal>strategy</literal> property to <literal>
+GenerationType.TABLE</literal>, and its <literal>generator</literal> property to
+the table generator's declared name. Or equivalently, set your <literal>
+generated-value</literal> XML element's <literal>strategy</literal> attribute to
+<literal>TABLE</literal> and its <literal>generator</literal> attribute to the
+generator name.
+ </para>
</section>
<section id="jpa_overview_mapping_sequence_genex">
- <title>Example</title>
- <para>
- Let's take advantage of generators in our entity model. Here are
- our updated mappings.
- </para>
- <example id="jpa_overview_mapping_sequenceex">
- <title>Generator Mapping</title>
- <programlisting format="linespecific">
+ <title>
+ Example
+ </title>
+ <para>
+Let's take advantage of generators in our entity model. Here are our updated
+mappings.
+ </para>
+ <example id="jpa_overview_mapping_sequenceex">
+ <title>
+ Generator Mapping
+ </title>
+<programlisting>
package org.mag;
@Entity
@@ -1062,11 +1366,11 @@
...
}
</programlisting>
- <para>
- The same metadata for <literal>Article</literal> and
- <literal>Author</literal> expressed in XML form:
- </para>
- <programlisting format="linespecific">
+ <para>
+The same metadata for <literal>Article</literal> and <literal>Author</literal>
+expressed in XML form:
+ </para>
+<programlisting>
<entity class="org.mag.Article">
<table name="ART">
<unique-constraint>
@@ -1094,106 +1398,150 @@
</attributes>
</entity>
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="jpa_overview_mapping_inher">
- <title>Inheritance</title>
+ </section>
+ <section id="jpa_overview_mapping_inher">
+ <title>
+ Inheritance
+ </title>
<indexterm zone="jpa_overview_mapping_inher">
- <primary>mapping metadata</primary>
- <secondary>inheritance</secondary>
- <seealso>inheritance</seealso>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ inheritance
+ </secondary>
+ <seealso>
+ inheritance
+ </seealso>
</indexterm>
<indexterm zone="jpa_overview_mapping_inher">
- <primary>inheritance</primary>
- <secondary>mapping</secondary>
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ mapping
+ </secondary>
</indexterm>
<indexterm zone="jpa_overview_mapping_inher">
- <primary>entities</primary>
- <secondary>inheritance</secondary>
- <seealso>inheritance</seealso>
+ <primary>
+ entities
+ </primary>
+ <secondary>
+ inheritance
+ </secondary>
+ <seealso>
+ inheritance
+ </seealso>
</indexterm>
<indexterm>
- <primary>impedance mismatch</primary>
+ <primary>
+ impedance mismatch
+ </primary>
</indexterm>
<para>
- In the 1990's programmers coined the term <emphasis>impedance mismatch
- </emphasis> to describe the difficulties in bridging the object and
- relational worlds. Perhaps no feature of object modeling highlights
- the impedance mismatch better than inheritance. There is no natural,
- efficient way to represent an inheritance relationship in a relational
- database.
- </para>
- <para><indexterm><primary>mapping metadata</primary><secondary>inheritance</secondary><tertiary>strategy attribute</tertiary></indexterm>
- Luckily, EJB persistence gives you a choice of inheritance strategies,
- making the best of a bad situation. The base entity class
- defines the inheritance strategy for the hierarchy with the
- <classname>Inheritance</classname> annotation. <classname>Inheritance
- </classname> has the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>InheritanceType strategy</literal>: Enum value
- declaring the inheritance strategy for the hierarchy.
- Defaults to <literal>InheritanceType.SINGLE_TABLE</literal>.
- We detail each of the available strategies below.
+In the 1990's programmers coined the term <emphasis>impedance mismatch
+</emphasis> to describe the difficulties in bridging the object and relational
+worlds. Perhaps no feature of object modeling highlights the impedance mismatch
+better than inheritance. There is no natural, efficient way to represent an
+inheritance relationship in a relational database.
</para>
- </listitem>
- </itemizedlist>
<para>
- The corresponding XML element is <literal>inheritance</literal>, which
- has a single attribute:
- </para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ inheritance
+ </secondary>
+ <tertiary>
+ strategy attribute
+ </tertiary>
+ </indexterm>
+Luckily, JPA gives you a choice of inheritance strategies, making
+the best of a bad situation. The base entity class defines the inheritance
+strategy for the hierarchy with the <classname>Inheritance</classname>
+annotation. <classname>Inheritance</classname> has the following properties:
+ </para>
<itemizedlist>
- <listitem>
- <para><literal>strategy</literal>: One of
- <literal>SINGLE_TABLE</literal>, <literal>JOINED</literal>,
- or <literal>TABLE_PER_CLASS</literal>.
+ <listitem>
+ <para>
+<literal>InheritanceType strategy</literal>: Enum value declaring the
+inheritance strategy for the hierarchy. Defaults to <literal>
+InheritanceType.SINGLE_TABLE</literal>. We detail each of the available
+strategies below.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The corresponding XML element is <literal>inheritance</literal>, which has a
+single attribute:
</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>strategy</literal>: One of <literal>SINGLE_TABLE</literal>, <literal>
+JOINED</literal>, or <literal>TABLE_PER_CLASS</literal>.
+ </para>
+ </listitem>
</itemizedlist>
<para>
- The following sections describe EJB's standard inheritance
- strategies.
- </para>
+The following sections describe JPA's standard inheritance strategies.
+ </para>
<note>
- <para>
- OpenJPA allows you to vary your inheritance strategy for each
- class, rather than forcing a single strategy per inheritance
- hierarchy. See <xref linkend="ref_guide_mapping_ejb"/> in the
- Reference Guide for details.
- </para>
+ <para>
+OpenJPA allows you to vary your inheritance strategy for each class, rather than
+forcing a single strategy per inheritance hierarchy. See
+<xref linkend="ref_guide_mapping_jpa"></xref> in the Reference Guide for
+details.
+ </para>
</note>
<section id="jpa_overview_mapping_inher_single">
- <title>Single Table</title>
- <indexterm zone="jpa_overview_mapping_inher_single">
- <primary>mapping metadata</primary>
- <secondary>inheritance</secondary>
- <tertiary>SINGLE_TABLE strategy</tertiary>
- </indexterm>
- <indexterm zone="jpa_overview_mapping_inher_single">
- <primary>inheritance</primary>
- <secondary>SINGLE_TABLE strategy</secondary>
- </indexterm>
- <para>
- The <literal>InheritanceType.SINGLE_TABLE</literal> strategy
- maps all classes in the hierarchy to the base class' table.
- </para>
- <mediaobject>
- <imageobject>
-<!-- PNG image data, 266 x 203 (see README) -->
- <imagedata fileref="img/inher-superclass-table.png" width="177px"/>
- </imageobject>
- </mediaobject>
- <para>
- In our model, <classname>Subscription</classname> is mapped to the
- <literal>CNTRCT.SUB</literal> table. <classname>
- LifetimeSubscription</classname>, which extends <classname>
- Subscription</classname>, adds its field data to this table as well.
- </para>
- <example id="jpa_overview_mapping_inher_singleex">
- <title>Single Table Mapping</title>
- <programlisting format="linespecific">
+ <title>
+ Single Table
+ </title>
+ <indexterm zone="jpa_overview_mapping_inher_single">
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ inheritance
+ </secondary>
+ <tertiary>
+ SINGLE_TABLE strategy
+ </tertiary>
+ </indexterm>
+ <indexterm zone="jpa_overview_mapping_inher_single">
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ SINGLE_TABLE strategy
+ </secondary>
+ </indexterm>
+ <para>
+The <literal>InheritanceType.SINGLE_TABLE</literal> strategy maps all classes in
+the hierarchy to the base class' table.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <!-- PNG image data, 266 x 203 (see README) -->
+ <imagedata fileref="img/inher-superclass-table.png" width="177px">
+ </imagedata>
+ </imageobject>
+ </mediaobject>
+ <para>
+In our model, <classname>Subscription</classname> is mapped to the <literal>
+CNTRCT.SUB</literal> table. <classname> LifetimeSubscription</classname>, which
+extends <classname> Subscription</classname>, adds its field data to this table
+as well.
+ </para>
+ <example id="jpa_overview_mapping_inher_singleex">
+ <title>
+ Single Table Mapping
+ </title>
+<programlisting>
@Entity
@Table(name="SUB", schema="CNTRCT")
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@@ -1209,8 +1557,10 @@
...
}
</programlisting>
- <para>The same metadata expressed in XML form:</para>
- <programlisting format="linespecific">
+ <para>
+The same metadata expressed in XML form:
+ </para>
+<programlisting>
<entity class="org.mag.subcribe.Subscription">
<table name="SUB" schema="CNTRCT"/>
<inheritance strategy="SINGLE_TABLE"/>
@@ -1220,151 +1570,206 @@
...
</entity>
</programlisting>
- </example>
- <para>
- Single table inheritance is the default strategy. Thus, we could
- omit the <literal>@Inheritance</literal> annotation in the
- example above and get the same result.
- </para>
- <note>
- <para><indexterm><primary>inheritance</primary><secondary>flat</secondary></indexterm><indexterm><primary>flat</primary><seealso>inheritance</seealso></indexterm>
- Mapping subclass state to the superclass table is often called
- <emphasis>flat</emphasis> inheritance mapping.
- </para>
- </note>
- <section id="jpa_overview_mapping_inher_single_adv">
- <title>Advantages</title>
- <indexterm zone="jpa_overview_mapping_inher_single_adv">
- <primary>inheritance</primary>
- <secondary>SINGLE_TABLE strategy</secondary>
- <tertiary>advantages</tertiary>
- </indexterm>
- <para>
- Single table inheritance mapping is the
- fastest of all inheritance models, since it never requires a
- join to retrieve a persistent instance from the database.
- Similarly, persisting or updating a persistent instance
- requires only a single <literal>INSERT</literal> or
- <literal>UPDATE</literal> statement. Finally, relations to
- any class within a single table inheritance hierarchy are just
- as efficient as relations to a base class.
- </para>
- </section>
- <section id="jpa_overview_mapping_inher_single_disadv">
- <title>Disadvantages</title>
- <indexterm zone="jpa_overview_mapping_inher_single_disadv">
- <primary>inheritance</primary>
- <secondary>SINGLE_TABLE strategy</secondary>
- <tertiary>disadvantages</tertiary>
- </indexterm>
+ </example>
<para>
- The larger the inheritance model gets, the "wider"
- the mapped table gets, in that for every field
- in the entire inheritance hierarchy, a column must
- exist in the mapped table. This may have
- undesirable consequence on the database size,
- since a wide or deep inheritance hierarchy will result in
- tables with many mostly-empty columns.
- </para>
- </section>
+Single table inheritance is the default strategy. Thus, we could omit the
+<literal>@Inheritance</literal> annotation in the example above and get the same
+result.
+ </para>
+ <note>
+ <para>
+ <indexterm>
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ flat
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ flat
+ </primary>
+ <seealso>
+ inheritance
+ </seealso>
+ </indexterm>
+Mapping subclass state to the superclass table is often called <emphasis>flat
+</emphasis> inheritance mapping.
+ </para>
+ </note>
+ <section id="jpa_overview_mapping_inher_single_adv">
+ <title>
+ Advantages
+ </title>
+ <indexterm zone="jpa_overview_mapping_inher_single_adv">
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ SINGLE_TABLE strategy
+ </secondary>
+ <tertiary>
+ advantages
+ </tertiary>
+ </indexterm>
+ <para>
+Single table inheritance mapping is the fastest of all inheritance models, since
+it never requires a join to retrieve a persistent instance from the database.
+Similarly, persisting or updating a persistent instance requires only a single
+<literal>INSERT</literal> or <literal>UPDATE</literal> statement. Finally,
+relations to any class within a single table inheritance hierarchy are just as
+efficient as relations to a base class.
+ </para>
+ </section>
+ <section id="jpa_overview_mapping_inher_single_disadv">
+ <title>
+ Disadvantages
+ </title>
+ <indexterm zone="jpa_overview_mapping_inher_single_disadv">
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ SINGLE_TABLE strategy
+ </secondary>
+ <tertiary>
+ disadvantages
+ </tertiary>
+ </indexterm>
+ <para>
+The larger the inheritance model gets, the "wider" the mapped table gets, in
+that for every field in the entire inheritance hierarchy, a column must exist in
+the mapped table. This may have undesirable consequence on the database size,
+since a wide or deep inheritance hierarchy will result in tables with many
+mostly-empty columns.
+ </para>
+ </section>
</section>
<section id="jpa_overview_mapping_inher_joined">
- <title>Joined</title>
- <indexterm zone="jpa_overview_mapping_inher_joined">
- <primary>mapping metadata</primary>
- <secondary>inheritance</secondary>
- <tertiary>JOINED strategy</tertiary>
- </indexterm>
- <indexterm zone="jpa_overview_mapping_inher_joined">
- <primary>inheritance</primary>
- <secondary>JOINED strategy</secondary>
- </indexterm>
- <para>
- The <literal>InheritanceType.JOINED</literal> strategy uses a
- different table for each class in the hierarchy. Each table
- only includes state declared in its class. Thus to load a subclass
- instance, the EJB persistence implementation must read from the
- subclass table as well as the table of each ancestor class, up to
- the base entity class.
- </para>
- <note>
- <para><indexterm><primary>inheritance</primary><secondary>vertical</secondary></indexterm><indexterm><primary>vertical</primary><seealso>inheritance</seealso></indexterm>
- Using joined subclass tables is also called
- <emphasis>vertical</emphasis> inheritance mapping.
- </para>
- </note>
- <mediaobject>
- <imageobject>
-<!-- PNG image data, 256 x 229 (see README) -->
- <imagedata fileref="img/jpa-inher-joined.png" width="171px"/>
- </imageobject>
- </mediaobject>
- <para><classname>PrimaryKeyJoinColumn</classname> annotations
- tell the EJB implementation how to join each subclass table
- record to the corresponding record in its direct superclass table.
- In our model, the <literal>LINE_ITEM.ID</literal> column joins to
- the <literal>CONTRACT.ID</literal> column. The
- <classname>PrimaryKeyJoinColumn</classname> annotation has
- the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>String name</literal>: The name of the subclass
- table column. When there is a single identity field,
- defaults to that field's column name.
- </para>
- </listitem>
- <listitem>
- <para><literal>String referencedColumnName</literal>: The name of
- the superclass table column this subclass table column joins
- to. When there is a single identity field, defaults to
- that field's column name.
- </para>
- </listitem>
- <listitem>
- <para><literal>String columnDefinition</literal>: This property
- has the same meaning as the <literal>columnDefinition
- </literal> property on the <classname>Column</classname>
- annotation, described in
- <xref linkend="jpa_overview_mapping_column"/>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The XML equivalent is the <literal>primary-key-join-column
- </literal> element. Its attributes
- mirror the annotation properties described above:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>referenced-column-name</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>column-definition</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The example below shows how we use <literal>InheritanceTable.JOINED
- </literal> and a primary key join column to map our sample model
- according to the diagram above. Note that a primary key join column
- is not strictly needed, because there is only one identity column,
- and the subclass table column has the same name as the superclass
- table column. In this situation, the defaults suffice. However,
- we include the primary key join column for illustrative
- purposes.
- </para>
- <example id="jpa_overview_mapping_inher_joinedex">
- <title>Joined Subclass Tables</title>
- <programlisting format="linespecific">
+ <title>
+ Joined
+ </title>
+ <indexterm zone="jpa_overview_mapping_inher_joined">
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ inheritance
+ </secondary>
+ <tertiary>
+ JOINED strategy
+ </tertiary>
+ </indexterm>
+ <indexterm zone="jpa_overview_mapping_inher_joined">
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ JOINED strategy
+ </secondary>
+ </indexterm>
+ <para>
+The <literal>InheritanceType.JOINED</literal> strategy uses a different table
+for each class in the hierarchy. Each table only includes state declared in its
+class. Thus to load a subclass instance, the JPA implementation must
+read from the subclass table as well as the table of each ancestor class, up to
+the base entity class.
+ </para>
+ <note>
+ <para>
+ <indexterm>
+ <primary>
+ inheritance
+ </primary>
+ <secondary>
+ vertical
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ vertical
+ </primary>
+ <seealso>
+ inheritance
+ </seealso>
+ </indexterm>
+Using joined subclass tables is also called <emphasis>vertical</emphasis>
+inheritance mapping.
+ </para>
+ </note>
+ <mediaobject>
+ <imageobject>
+ <!-- PNG image data, 256 x 229 (see README) -->
+ <imagedata fileref="img/jpa-inher-joined.png" width="171px">
+ </imagedata>
+ </imageobject>
+ </mediaobject>
+ <para>
+<classname>PrimaryKeyJoinColumn</classname> annotations tell the JPA
+implementation how to join each subclass table record to the corresponding
+record in its direct superclass table. In our model, the <literal>LINE_ITEM.ID
+</literal> column joins to the <literal>CONTRACT.ID</literal> column. The
+<classname>PrimaryKeyJoinColumn</classname> annotation has the following
+properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>String name</literal>: The name of the subclass table column. When
+there is a single identity field, defaults to that field's column name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>String referencedColumnName</literal>: The name of the superclass
+table column this subclass table column joins to. When there is a single
+identity field, defaults to that field's column name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>String columnDefinition</literal>: This property has the same meaning
+as the <literal>columnDefinition</literal> property on the <classname>Column
+</classname> annotation, described in
+<xref linkend="jpa_overview_mapping_column"></xref>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The XML equivalent is the <literal>primary-key-join-column</literal> element.
+Its attributes mirror the annotation properties described above:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>referenced-column-name</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>column-definition</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
[... 2650 lines stripped ...]