| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>6. Generators</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.2 User's Guide"><link rel="up" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions"><link rel="prev" href="ref_guide_enterprise_methodql.html" title="5. MethodQL"><link rel="next" href="ref_guide_runtime_pm_event.html" title="7. 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. |
| Generators |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_enterprise_methodql.html">Prev</a> </td><th width="60%" align="center">Chapter 9. |
| Runtime Extensions |
| </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_runtime_pm_event.html">Next</a></td></tr></table><hr></div><div class="section" title="6. Generators"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_sequence">6. |
| 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="d5e15644"></a> |
| <p> |
| The JPA Overview's <a class="xref" href="jpa_overview_mapping.html" title="Chapter 13. Mapping Metadata">Chapter 13, <i> |
| Mapping Metadata |
| </i></a> details using |
| generators to automatically populate identity fields in JPA. |
| </p> |
| <p> |
| OpenJPA represents all generators internally with the |
| <a class="ulink" 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 class="ulink" 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 class="itemizedlist" type="disc"><li class="listitem"> |
| <p> |
| <a class="indexterm" name="d5e15659"></a> |
| <code class="literal">table</code>: This is OpenJPA's default implementation. It is an |
| alias for the |
| <a class="ulink" 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 class="link" href="ref_guide_mapping.html#ref_guide_mapping_mappingtool" title="1. 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 class="itemizedlist" type="circle"><li class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <p> |
| <a class="indexterm" name="d5e15690"></a> |
| <code class="literal">class-table</code>: This is an alias for the |
| <a class="ulink" 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 class="itemizedlist" type="circle"><li class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <p> |
| <a class="indexterm" name="d5e15716"></a> |
| <code class="literal">value-table</code>: This is an alias for the |
| <a class="ulink" 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 class="itemizedlist" type="circle"><li class="listitem"> |
| <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 class="listitem"> |
| <p> |
| <a class="indexterm" name="d5e15737"></a> |
| <code class="literal">native</code>: This is an alias for the |
| <a class="ulink" 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 database, 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 class="itemizedlist" type="circle"><li class="listitem"> |
| <p> |
| <code class="literal">Sequence</code>: The name of the database sequence. Defaults to |
| <code class="literal">OPENJPA_SEQUENCE</code>. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">InitialValue</code>: The initial sequence value. Defaults to 1. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">Increment</code>: The amount the sequence increments. Defaults to 1. |
| </p> |
| </li><li class="listitem"> |
| <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, 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 class="listitem"> |
| <p> |
| <a class="indexterm" name="d5e15762"></a> |
| <code class="literal">time</code>: This is an alias for the |
| <a class="ulink" 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. |
| </p> |
| |
| <div class="blockquote"><blockquote class="blockquote"> |
| <p> |
| If specifying your own class name, you must include parentheses at the end of |
| the class name, even if you have no plugin properties to configure. |
| (E.g., <code class="literal">sequenceName="com.example.SeqImpl()"</code>. |
| </p> |
| </blockquote></div> |
| |
| <p> |
| See <a class="xref" href="jpa_overview_mapping_sequence.html" title="5. Generators">Section 5, “ |
| Generators |
| ”</a> in the JPA Overview for |
| details on defining <code class="literal">SequenceGenerator</code>s. |
| </p> |
| |
| <p> |
| See <a class="xref" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">Section 4, “ |
| Plugin Configuration |
| ”</a> for plugin string formatting. |
| </p> |
| <div class="example"><a name="ref_guide_sequence_named"></a><p class="title"><b>Example 9.8. |
| 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", sequenceName="table(Table=AUTO_SEQ)", allocationSize=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.sequenceName</code> attribute: |
| </p> |
| <pre class="programlisting"> |
| @SequenceGenerator(name="AuthorSeq", sequenceName="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 class="link" href="ref_guide_conf_openjpa.html#openjpa.Sequence" title="5.67. 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 9.9. |
| System Sequence Configuration |
| </b></p><div class="example-contents"> |
| |
| <pre class="programlisting"> |
| <property name="openjpa.Sequence" value="time(Increment=100)"/> |
| </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" title="6.1. Runtime Access"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_sequence_runtime">6.1. |
| Runtime Access |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15804"></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 class="ulink" 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 class="ulink" 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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_runtime_pm_event.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. |
| MethodQL |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 7. |
| Transaction Events |
| </td></tr></table></div></body></html> |