<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>6.&nbsp; 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="ref_guide_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions"><link rel="prev" href="ref_guide_enterprise_methodql.html" title="5.&nbsp; MethodQL"><link rel="next" href="ref_guide_runtime_pm_event.html" title="7.&nbsp; Transaction Events"></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">6.&nbsp;
            Generators
        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_enterprise_methodql.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;9.&nbsp;
        Runtime Extensions
    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_runtime_pm_event.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="ref_guide_sequence"></a>6.&nbsp;
            Generators
        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_sequence.html#ref_guide_sequence_runtime">6.1. 
                Runtime Access
            </a></span></dt></dl></div><a class="indexterm" name="d0e28073"></a><p>
The JPA Overview's <a href="jpa_overview_mapping.html" title="Chapter&nbsp;12.&nbsp; Mapping Metadata">Chapter&nbsp;12, <i xmlns:xlink="http://www.w3.org/1999/xlink">
        Mapping Metadata
    </i></a> details using
generators to automatically populate identity fields in JPA.
        </p><p>
OpenJPA represents all generators internally with the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/Seq.html" target="_top"><code class="classname">
org.apache.openjpa.kernel.Seq</code></a> interface. This interface
supplies all the context you need to create your own custom generators,
including the current persistence environment, the JDBC <code class="classname">DataSource
</code>, and other essentials. The
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/AbstractJDBCSeq.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.kernel.AbstractJDBCSeq</code></a>
helps you create custom JDBC-based sequences. OpenJPA also supplies the
following built-in <code class="classname">Seq</code>s:
        </p><div class="itemizedlist"><ul type="disc"><li><p>
                <a class="indexterm" name="d0e28103"></a>
<code class="literal">table</code>: This is OpenJPA's default implementation. It is an
alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/TableJDBCSeq.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.kernel.TableJDBCSeq</code></a>
class. The <code class="classname">TableJDBCSeq</code> uses a special single-row table
to store a global sequence number. If the table does not already exist, it is
created the first time you run the
<a href="ref_guide_mapping.html#ref_guide_mapping_mappingtool" title="1.&nbsp; Forward Mapping">mapping tool</a> on a class
that requires it. You can also use the class's <code class="methodname">main</code>
method to manipulate the table; see the 
<code class="methodname">TableJDBCSeq.main</code> method Javadoc for usage details.
                </p><p>
This <code class="classname">Seq</code> has the following properties:
                </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">Table</code>: The name of the sequence number table to use.
Defaults to <code class="literal">OPENJPA_SEQUENCE_TABLE</code>. If the entities are 
mapped to the same table name but with different schema name within one 
PersistenceUnit, one <code class="literal">OPENJPA_SEQUENCE_TABLE</code> is created 
for each schema.
                        </p></li><li><p>
<code class="literal">PrimaryKeyColumn</code>: The name of the primary key column for the
sequence table. Defaults to <code class="literal">ID</code>.
                        </p></li><li><p>
<code class="literal">SequenceColumn</code>: The name of the column that will hold the
current sequence value. Defaults to <code class="literal">SEQUENCE_VALUE</code>.
                        </p></li><li><p>
<code class="literal">Allocate</code>: The number of values to allocate on each database
trip. Defaults to 50, meaning the class will set aside the next 50 numbers each
time it accesses the sequence table, which in turn means it only has to make a
database trip to get new sequence numbers once every 50 sequence number
requests.
                        </p></li></ul></div></li><li><p>
                <a class="indexterm" name="d0e28174"></a>
<code class="literal">class-table</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/ClassTableJDBCSeq.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.kernel.ClassTableJDBCSeq</code></a>
. This <code class="classname">Seq</code> is like the <code class="classname">TableJDBCSeq
</code> above, but maintains a separate table row, and therefore a separate
sequence number, for each base persistent class. It has all the properties of
the <code class="classname">TableJDBCSeq</code>. Its table name defaults to <code class="literal">
OPENJPA_SEQUENCES_TABLE</code>. It also adds the following properties:
                </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">IgnoreUnmapped</code>: Whether to ignore unmapped base classes, and
instead use one row per least-derived mapped class. Defaults to <code class="literal">
false</code>.
                        </p></li><li><p>
<code class="literal">UseAliases</code>: Whether to use each class' entity name as the
primary key value of each row, rather than the full class name. Defaults to
<code class="literal">false</code>.
                        </p></li></ul></div><p>
As with the <code class="classname">TableJDBCSeq</code>, the <code class="classname">
ClassTableJDBCSeq</code> creates its table automatically during mapping
tool runs. However, you can manually manipulate the table through the class'
<code class="methodname">main</code> method. See the Javadoc for the
<code class="methodname"> ClassTableJDBCSeq.main</code> method for usage details.
                </p></li><li><p>
                <a class="indexterm" name="d0e28236"></a>
<code class="literal">value-table</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/ValueTableJDBCSeq.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.kernel.ValueTableJDBCSeq</code></a>
. This <code class="classname">Seq</code> is like the <code class="classname">ClassTableJDBCSeq
</code> above, but has an arbitrary number of rows for sequence values,
rather than a fixed pattern of one row per class. Its table defaults to
<code class="literal">OPENJPA_SEQUENCES_TABLE</code>. It has all the properties of the
<code class="classname">TableJDBCSeq</code>, plus:
                </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">PrimaryKeyValue</code>: The primary key value used by this instance.
                        </p></li></ul></div><p>
As with the <code class="classname">TableJDBCSeq</code>, the <code class="classname">
ValueTableJDBCSeq</code> creates its table automatically during mapping
tool runs. However, you can manually manipulate the table through the class'
<code class="methodname">main</code> method. See the Javadoc for the
<code class="methodname">ValueTableJDBCSeq.main</code> method for usage details.
                </p></li><li><p>
                <a class="indexterm" name="d0e28286"></a>
<code class="literal">native</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/kernel/NativeJDBCSeq.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.kernel.NativeJDBCSeq</code></a>.
Many databases have a concept of "native sequences" - a built-in mechanism for
obtaining incrementing numbers. For example, in Oracle, you can create a
database sequence with a statement like <code class="literal">CREATE SEQUENCE MYSEQUENCE
</code>. Sequence values can then be atomically obtained and incremented
with the statement <code class="literal">SELECT MYSEQUENCE.NEXTVAL FROM DUAL</code>.
OpenJPA provides support for this common mechanism of sequence generation with
the <code class="classname"> NativeJDBCSeq</code>, which accepts the following
properties:
                </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">Sequence</code>: The name of the database sequence. Defaults to
<code class="literal">OPENJPA_SEQUENCE</code>.
                        </p></li><li><p>
<code class="literal">InitialValue</code>: The initial sequence value. Defaults to 1.
                        </p></li><li><p>
<code class="literal">Increment</code>: The amount the sequence increments. Defaults to 1.
                        </p></li><li><p>
<code class="literal">Allocate</code>: Some database can allocate values in-memory to
service subsequent sequence requests faster.
                        </p></li></ul></div></li><li><p>
                <a class="indexterm" name="d0e28340"></a>
<code class="literal">time</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/TimeSeededSeq.html" target="_top">
<code class="classname">org.apache.openjpa.kernel.TimeSeededSeq</code></a>. This
type uses an in-memory static counter, initialized to the current time in
milliseconds and monotonically incremented for each value requested. It is only
suitable for single-JVM environments.
                </p></li></ul></div><p>
You can use JPA <code class="literal">SequenceGenerator</code>s to describe any built-in
<code class="classname">Seq</code>s or your own <code class="classname">Seq</code>
implementation. Set the <code class="literal">sequenceName</code> attribute to a plugin
string describing your choice. See
<a href="jpa_overview_mapping_sequence.html" title="5.&nbsp; Generators">Section&nbsp;5, &#8220;
            Generators
        &#8221;</a> in the JPA Overview for
details on defining <code class="literal">SequenceGenerator</code>s.
        </p><p>
See <a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
            Plugin Configuration
        &#8221;</a> for plugin string formatting.
        </p><div class="example"><a name="ref_guide_sequence_named"></a><p class="title"><b>Example&nbsp;9.8.&nbsp;
                Named Seq Sequence
            </b></p><div class="example-contents"><pre class="programlisting">
@Entity
@Table(name="AUTO")
public class Author {

    @Id
    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="AuthorSeq")
    @SequenceGenerator(name="AuthorSeq" sequence="table(Table=AUTO_SEQ, Increment=100)")
    @Column(name="AID")
    private long id;
 
    ...
}
</pre><p>
Note that if you want to use a plugin string without any arguments, you must
still suffix the plugin type with <code class="literal">()</code> to differentiate it from
a sequence name in the <code class="literal"> SequenceGenerator.sequence</code> attribute:
            </p><pre class="programlisting">
@SequenceGenerator(name="AuthorSeq", sequence="table()")
</pre></div></div><br class="example-break"><p>
OpenJPA maintains a <span class="emphasis"><em>system</em></span> sequence to generate datastore
identity values for classes that do not declare a specific datastore identity
strategy. You can configure the system sequence through the
<a href="ref_guide_conf_openjpa.html#openjpa.Sequence" title="5.58.&nbsp; openjpa.Sequence"><code class="literal">openjpa.Sequence</code></a>
configuration property. This property accepts a plugin string describing a
<code class="classname">Seq</code> instance.
        </p><div class="example"><a name="ref_guide_sequence_systemex"></a><p class="title"><b>Example&nbsp;9.9.&nbsp;
                System Sequence Configuration
            </b></p><div class="example-contents"><pre class="programlisting">
&lt;property name="openjpa.Sequence" value="table(Table=OPENJPASEQ, Increment=100)"/&gt;
</pre></div></div><br class="example-break"><p>
In JPA, set your <code class="literal">GeneratedValue</code> annotation's <code class="literal">
strategy</code> attribute to <code class="literal">AUTO</code> to use the configured
system sequence. Or, because <code class="literal">AUTO</code> is the default strategy,
use the annotation without attributes:
        </p><pre class="programlisting">
@GeneratedValue
private long id;
</pre><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_sequence_runtime"></a>6.1.&nbsp;
                Runtime Access
            </h3></div></div></div><a class="indexterm" name="d0e28428"></a><p>
OpenJPA allows you to access named generators at runtime through the
<code class="methodname">OpenJPAEntityManager.getNamedGenerator</code> method:
            </p><pre class="programlisting">
public Generator getNamedGenerator(String name);
</pre><p>
The returned 
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/Generator.html" target="_top">
<code class="classname">org.apache.openjpa.persistence.Generator</code></a> is a
facade over an internal OpenJPA <code class="classname">Seq</code>.
            </p><p>
The <code class="classname">OpenJPAEntityManager</code> includes additional APIs to
retrieve the identity generator of any class, or the generator of any field.
With these APIs, you do not have to know the generator name. Additionally, they
allow you to access the implicit generator used by default for datastore
identity classes. See the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top">
Javadoc</a> for the <code class="methodname"> OpenJPAEntityManager.getIdentityGenerator
</code> and <code class="methodname">OpenJPAEntityManager.getFieldGenerator
</code> methods for API details.
            </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_enterprise_methodql.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_runtime_pm_event.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.&nbsp;
                MethodQL
            &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;7.&nbsp;
            Transaction Events
        </td></tr></table></div></body></html>