Google Git
Sign in
apache / openjpa-site / 36cfd139db917058976908071948336fbc1ff605 / . / content / builds / 3.1.0 / apache-openjpa / docs / jpa_overview_mapping_sequence.html
blob: c8ff1b6181f7d22dcbb8f46a6cba78209a563fe8 [file] [log] [blame]
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>5.&nbsp; Generators</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 3.0 User's Guide"><link rel="up" href="jpa_overview_mapping.html" title="Chapter&nbsp;13.&nbsp; Mapping Metadata"><link rel="prev" href="jpa_overview_mapping_id.html" title="4.&nbsp; Identity Mapping"><link rel="next" href="jpa_overview_mapping_inher.html" title="6.&nbsp; 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.&nbsp;
Generators
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_mapping_id.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;13.&nbsp;
Mapping Metadata
</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_mapping_inher.html">Next</a></td></tr></table><hr></div><div class="section" id="jpa_overview_mapping_sequence"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.&nbsp;
Generators
</h2></div></div></div><div class="toc"><dl class="toc"><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></div>
<a class="indexterm" name="d5e5656"></a>
<a class="indexterm" name="d5e5659"></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 class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_id" title="2.3.&nbsp; Id">Section&nbsp;2.3, &#8220;
Id
&#8221;</a>. Now we show you how to define
named generators.
</p>
<div class="section" id="jpa_overview_mapping_sequence_seqgen"><div class="titlepage"><div><div><h3 class="title">5.1.&nbsp;
Sequence Generator
</h3></div></div></div>
<a class="indexterm" name="d5e5669"></a>
<a class="indexterm" name="d5e5672"></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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
<p>
<a class="indexterm" name="d5e5680"></a>
<code class="literal">String name</code>: The generator name. This property is required.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5686"></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 class="listitem">
<p>
<a class="indexterm" name="d5e5692"></a>
<code class="literal">int initialValue</code>: The initial sequence value.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5698"></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 sequence is accessed. Defaults to 50.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5704"></a>
<code class="literal">String schema</code>: The sequence's schema. If you do not name a
schema, JPA uses the default schema for the database connection.
</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 class="link" href="ref_guide_conf_openjpa.html#openjpa.Sequence" title="5.67.&nbsp; openjpa.Sequence"><code class="literal">
openjpa.Sequence</code></a> configuration property. See the Reference
Guide's <a class="xref" href="ref_guide_sequence.html" title="6.&nbsp; Generators">Section&nbsp;6, &#8220;
Generators
&#8221;</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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
<p>
<code class="literal">name</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">sequence-name</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">initial-value</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">allocation-size</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">schema</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" id="jpa_overview_mapping_sequence_tablegen"><div class="titlepage"><div><div><h3 class="title">5.2.&nbsp;
Table Generator
</h3></div></div></div>
<a class="indexterm" name="d5e5745"></a>
<a class="indexterm" name="d5e5748"></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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
<p>
<a class="indexterm" name="d5e5758"></a>
<code class="literal">String name</code>: The generator name. This property is required.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5764"></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 class="listitem">
<p>
<a class="indexterm" name="d5e5770"></a>
<code class="literal">String schema</code>: The named table's schema.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5776"></a>
<code class="literal">String catalog</code>: The named table's catalog.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5782"></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 class="listitem">
<p>
<a class="indexterm" name="d5e5788"></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 class="listitem">
<p>
<a class="indexterm" name="d5e5794"></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 class="listitem">
<p>
<a class="indexterm" name="d5e5801"></a>
<code class="literal">int initialValue</code>: The value of the generator's first issued
number.
</p>
</li><li class="listitem">
<p>
<a class="indexterm" name="d5e5807"></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 class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
<p>
<code class="literal">name</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">table</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><li class="listitem">
<p>
<code class="literal">pk-column-name</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">value-column-name</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">pk-column-value</code>
</p>
</li><li class="listitem">
<p>
<code class="literal">initial-value</code>
</p>
</li><li class="listitem">
<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" id="jpa_overview_mapping_sequence_genex"><div class="titlepage"><div><div><h3 class="title">5.3.&nbsp;
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" id="jpa_overview_mapping_sequenceex"><p class="title"><b>Example&nbsp;13.4.&nbsp;
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">
&lt;entity class="org.mag.Article"&gt;
&lt;table name="ART"&gt;
&lt;unique-constraint&gt;
&lt;column-name&gt;TITLE&lt;/column-name&gt;
&lt;/unique-constraint&gt;
&lt;/table&gt;
&lt;sequence-generator name="ArticleSeq" sequence-name="ART_SEQ"/&gt;
&lt;attributes&gt;
&lt;id name="id"&gt;
&lt;generated-value strategy="SEQUENCE" generator="ArticleSeq"/&gt;
&lt;/id&gt;
...
&lt;/attributes&gt;
&lt;/entity&gt;
&lt;entity class="org.mag.pub.Author"&gt;
&lt;table name="AUTH"/&gt;
&lt;attributes&gt;
&lt;id name="id"&gt;
&lt;column name="AID" column-definition="INTEGER64"/&gt;
&lt;generated-value strategy="TABLE" generator="AuthorGen"/&gt;
&lt;table-generator name="AuthorGen" table="AUTH_GEN"
pk-column-name="PK" value-column-name="AID"/&gt;
&lt;/id&gt;
...
&lt;/attributes&gt;
&lt;/entity&gt;
</pre>
</div></div><br class="example-break">
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_mapping_id.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_mapping.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_mapping_inher.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.&nbsp;
Identity Mapping
&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;6.&nbsp;
Inheritance
</td></tr></table></div></body></html>