| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>5. Generators</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA User's Guide"><link rel="up" href="jpa_overview_mapping.html" title="Chapter 12. Mapping Metadata"><link rel="prev" href="jpa_overview_mapping_id.html" title="4. Identity Mapping"><link rel="next" href="jpa_overview_mapping_inher.html" title="6. Inheritance"></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">5. |
| Generators |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_mapping_id.html">Prev</a> </td><th width="60%" align="center">Chapter 12. |
| Mapping Metadata |
| </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_mapping_inher.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_mapping_sequence"></a>5. |
| Generators |
| </h2></div></div></div><div class="toc"><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. |
| TableGenerator |
| </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></div><a class="indexterm" name="d0e9942"></a><a class="indexterm" name="d0e9947"></a><p> |
| 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 |
| <span class="emphasis"><em>generators</em></span>. We discussed the available generator types in |
| <a href="jpa_overview_meta_field.html#jpa_overview_meta_id" title="2.2. Id">Section 2.2, “ |
| Id |
| ”</a>. Now we show you how to define |
| named generators. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_sequence_seqgen"></a>5.1. |
| Sequence Generator |
| </h3></div></div></div><a class="indexterm" name="d0e9966"></a><a class="indexterm" name="d0e9971"></a><p> |
| Most databases allow you to create native sequences. These are database |
| structures that generate increasing numeric values. The <code class="classname"> |
| SequenceGenerator</code> 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). <code class="classname"> |
| SequenceGenerator</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e9986"></a> |
| <code class="literal">String name</code>: The generator name. This property is required. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e9998"></a> |
| <code class="literal">String sequenceName</code>: The name of the database sequence. If |
| you do not specify the database sequence, your vendor will choose an appropriate |
| default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10010"></a> |
| <code class="literal">int initialValue</code>: The initial sequence value. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10022"></a> |
| <code class="literal">int allocationSize</code>: 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. |
| </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA allows you to use one of OpenJPA's built-in generator |
| implementations in the <code class="literal">sequenceName</code> property. You can also |
| set the <code class="literal">sequenceName</code> to <code class="literal">system</code> to use the |
| system sequence defined by the <a href="ref_guide_conf_openjpa.html#openjpa.Sequence" title="5.58. openjpa.Sequence"><code class="literal"> |
| openjpa.Sequence</code></a> configuration property. See the Reference |
| Guide's <a href="ref_guide_sequence.html" title="6. Generators">Section 6, “ |
| Generators |
| ”</a> for details. |
| </p></div><p> |
| The XML element for a sequence generator is <code class="literal">sequence-generator |
| </code>. Its attributes mirror the above annotation's properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">sequence-name</code> |
| </p></li><li><p> |
| <code class="literal">initial-value</code> |
| </p></li><li><p> |
| <code class="literal">allocation-size</code> |
| </p></li></ul></div><p> |
| To use a sequence generator, set your <code class="classname">GeneratedValue</code> |
| annotation's <code class="literal">strategy</code> property to <code class="literal"> |
| GenerationType.SEQUENCE</code>, and its <code class="literal">generator</code> property |
| to the sequence generator's declared name. Or equivalently, set your <code class="literal"> |
| generated-value</code> XML element's <code class="literal">strategy</code> attribute to |
| <code class="literal">SEQUENCE</code> and its <code class="literal">generator</code> attribute to |
| the generator name. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_sequence_tablegen"></a>5.2. |
| TableGenerator |
| </h3></div></div></div><a class="indexterm" name="d0e10108"></a><a class="indexterm" name="d0e10113"></a><p> |
| A <code class="classname">TableGenerator</code> refers to a database table used to store |
| increasing sequence values for one or more entities. As with <code class="classname"> |
| SequenceGenerator</code>, you can place the <code class="classname">TableGenerator |
| </code> 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). <code class="classname"> |
| TableGenerator</code> has the following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <a class="indexterm" name="d0e10134"></a> |
| <code class="literal">String name</code>: The generator name. This property is required. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10146"></a> |
| <code class="literal">String table</code>: The name of the generator table. If left |
| unspecified, your vendor will choose a default table. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10158"></a> |
| <code class="literal">String schema</code>: The named table's schema. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10170"></a> |
| <code class="literal">String catalog</code>: The named table's catalog. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10182"></a> |
| <code class="literal">String pkColumnName</code>: The name of the primary key column in |
| the generator table. If unspecified, your implementation will choose a default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10194"></a> |
| <code class="literal">String valueColumnName</code>: The name of the column that holds |
| the sequence value. If unspecified, your implementation will choose a default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10206"></a> |
| <code class="literal">String pkColumnValue</code>: 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 <code class="literal"> |
| pkColumnValue</code> s. If you do not specify a value, the implementation |
| will supply a default. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10221"></a> |
| <code class="literal">int initialValue</code>: The value of the generator's first issued |
| number. |
| </p></li><li><p> |
| <a class="indexterm" name="d0e10233"></a> |
| <code class="literal">int allocationSize</code>: 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. |
| </p></li></ul></div><p> |
| The XML equivalent is the <code class="literal">table-generator</code> element. This |
| element's attributes correspond exactly to the above annotation's properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code> |
| </p></li><li><p> |
| <code class="literal">table</code> |
| </p></li><li><p> |
| <code class="literal">schema</code> |
| </p></li><li><p> |
| <code class="literal">catalog</code> |
| </p></li><li><p> |
| <code class="literal">pk-column-name</code> |
| </p></li><li><p> |
| <code class="literal">value-column-name</code> |
| </p></li><li><p> |
| <code class="literal">pk-column-value</code> |
| </p></li><li><p> |
| <code class="literal">initial-value</code> |
| </p></li><li><p> |
| <code class="literal">allocation-size</code> |
| </p></li></ul></div><p> |
| To use a table generator, set your <code class="classname">GeneratedValue</code> |
| annotation's <code class="literal">strategy</code> property to <code class="literal"> |
| GenerationType.TABLE</code>, and its <code class="literal">generator</code> property to |
| the table generator's declared name. Or equivalently, set your <code class="literal"> |
| generated-value</code> XML element's <code class="literal">strategy</code> attribute to |
| <code class="literal">TABLE</code> and its <code class="literal">generator</code> attribute to the |
| generator name. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="jpa_overview_mapping_sequence_genex"></a>5.3. |
| Example |
| </h3></div></div></div><p> |
| Let's take advantage of generators in our entity model. Here are our updated |
| mappings. |
| </p><div class="example"><a name="jpa_overview_mapping_sequenceex"></a><p class="title"><b>Example 12.4. |
| Generator Mapping |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| package org.mag; |
| |
| @Entity |
| @IdClass(Magazine.MagazineId.class) |
| @Table(name="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(generate=GenerationType.IDENTITY) |
| private long id; |
| |
| ... |
| } |
| |
| @Entity |
| @Table(schema="CNTRCT") |
| public class Contract |
| extends Document { |
| |
| ... |
| } |
| |
| @Entity |
| @Table(name="SUB", schema="CNTRCT") |
| 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") |
| public class LifetimeSubscription |
| extends Subscription { |
| ... |
| } |
| |
| @Entity(name="Trial") |
| public class TrialSubscription |
| extends Subscription { |
| ... |
| } |
| </pre><p> |
| The same metadata for <code class="literal">Article</code> and <code class="literal">Author</code> |
| expressed in XML form: |
| </p><pre class="programlisting"> |
| <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.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> |
| </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_mapping_id.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_inher.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. |
| Identity Mapping |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 6. |
| Inheritance |
| </td></tr></table></div></body></html> |