Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/TableGenerator"

m (@TableGenerator Annotation)
 
(18 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=@TableGenerator Annotation=
+
{{EclipseLink_UserGuide
If you use the [[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/GeneratedValue|<tt>@GeneratedValue</tt> annotation]] to specify a primary key generator of type <tt>TABLE</tt>, then you can use the <tt>@TableGenerator</tt> annotation to fine-tune this primary key generator to do the following:
+
|info=y
 +
|toc=n
 +
|eclipselink=y
 +
|eclipselinktype=JPA
 +
|api=y
 +
|apis=
 +
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/TableGenerator.html @TableGenerator]
 +
}}
 +
 
 +
=@TableGenerator=
 +
If you use the [[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/GeneratedValue|<tt>@GeneratedValue</tt>]] annotation to specify a primary key generator of type <tt>TABLE</tt>, then you can use the <tt>@TableGenerator</tt> annotation to fine-tune this primary key generator to do the following:
 
* change the name of the primary key generator's table, because the name is awkward, a reserved word, incompatible with a preexisting data model, or invalid as a table name in your database;
 
* change the name of the primary key generator's table, because the name is awkward, a reserved word, incompatible with a preexisting data model, or invalid as a table name in your database;
 
* change the allocation size to match your application requirements or database performance parameters;
 
* change the allocation size to match your application requirements or database performance parameters;
Line 6: Line 16:
 
* configure the primary key generator's table with a specific catalog or schema;
 
* configure the primary key generator's table with a specific catalog or schema;
 
* configure a unique constraint on one or more columns of the primary key generator's table;
 
* configure a unique constraint on one or more columns of the primary key generator's table;
{{EclipseLink_Spec|section=Section 9.1.38 "TableGenerator Annotation"}}
+
{{EclipseLink_Spec|section=Section 11.1.46 "TableGenerator Annotation"}}
 
+
The <tt>@TableGenerator</tt> annotation has the following attributes:
+
 
{{EclipseLink_AttributeTable
 
{{EclipseLink_AttributeTable
 
|caption=@TableGenerator Attributes
 
|caption=@TableGenerator Attributes
Line 19: Line 27:
 
<tr>
 
<tr>
 
  <td>'''<tt>allocationSize</tt>'''</td>
 
  <td>'''<tt>allocationSize</tt>'''</td>
  <td> – By default, EclipseLink persistence provider uses an allocation size of 50.<br>If this allocation size does not match your application requirements or database performance parameters, set this attribute to the <tt>int</tt> value you want.</td>
+
  <td>An <tt>int</tt> value to match your your application requirements or database performance parameters.
 
  <td>50</td>
 
  <td>50</td>
 
  <td>No</td>
 
  <td>No</td>
Line 25: Line 33:
 
<tr>
 
<tr>
 
  <td>'''<tt>catalog</tt>'''</td>
 
  <td>'''<tt>catalog</tt>'''</td>
  <td>By default, EclipseLink persistence provider uses whatever the default catalog is for your database.<br>If the default catalog is inappropriate for your application, set the value of this attribute to the <tt>String</tt> catalog name to use.</td>
+
  <td>A <tt>String</tt> catalog name.
  <td></td>
+
  <td>Default catalog for database</td>
 
  <td>No</td>
 
  <td>No</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>initialValue</tt>'''</td>
 
  <td>'''<tt>initialValue</tt>'''</td>
  <td>By default, EclipseLink persistence provider starts all primary key values from 0.<br>If this does not match an existing data model, set this attribute to the <tt>int</tt> value you want.</td>
+
  <td>An <tt>int</tt> initial primary key value.  
 
  <td>0</td>
 
  <td>0</td>
 
  <td>No</td>
 
  <td>No</td>
Line 37: Line 45:
 
<tr>
 
<tr>
 
  <td>'''<tt>pkColumnName</tt>'''</td>  
 
  <td>'''<tt>pkColumnName</tt>'''</td>  
  <td>By default, EclipseLink persistence provider supplies a name for the primary key column in the generator table: <tt>"SEQ_NAME"</tt>.<br>If this name is inappropriate for your application, set the value of this attribute to the <tt>String</tt> name you want.</td>
+
  <td>A <tt>String</tt> name for the primary key column in the generator table.  
 
  <td>SEQ_NAME</td>
 
  <td>SEQ_NAME</td>
 
  <td>No</td>
 
  <td>No</td>
Line 43: Line 51:
 
<tr>
 
<tr>
 
  <td>'''<tt>pkColumnValue</tt>'''</td>
 
  <td>'''<tt>pkColumnValue</tt>'''</td>
  <td>By default, EclipseLink persistence provider supplies a suitable primary key value for the primary key column in the generator table: <tt>TableGenereator.name</tt>.<br>If this value is inappropriate for your application, set the value of this attribute to the <tt>String</tt> value you want.</td>
+
  <td><tt>String</tt> primary key value for the primary key column in the generator table. </td>
  <td></td>
+
  <td>TableGenereator.name</td>
 
  <td>No</td>
 
  <td>No</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>schema</tt>'''</td>
 
  <td>'''<tt>schema</tt>'''</td>
  <td>By default, EclipseLink persistence provider uses whatever the default schema is for your database.<br>If this value is inappropriate for your application, set the value of this attribute to the <tt>String</tt> schema name you choose.</td>
+
  <td>The <tt>String</tt> name of the schema.</td>
  <td></td>
+
  <td>Default schema of the database</td>
 
  <td>No</td>
 
  <td>No</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>table</tt>'''</td>
 
  <td>'''<tt>table</tt>'''</td>
  <td> By default, EclipseLink persistence provider supplies a suitable name for the table that stores the generated id values: <tt>"SEQUENCE"</tt>.<br>If this value is inappropriate for your application, set the value of this attribute to the <tt>String</tt> table name you want.</td>
+
  <td>A <tt>String</tt> name of the table in which to store the generated ID values.</td>
 
  <td>SEQUENCE</td>
 
  <td>SEQUENCE</td>
 
  <td>No</td>
 
  <td>No</td>
Line 62: Line 70:
 
  <td>'''<tt>uniqueConstraints</tt>'''</td>
 
  <td>'''<tt>uniqueConstraints</tt>'''</td>
 
  <td>By default, EclipseLink persistence provider assumes that none of the columns in the primary key generator table have unique constraints.<br>If unique constraints do apply to one or more columns in this table, set the value of this attribute to an array of one or more <tt>UniqueConstraint</tt> instances.  
 
  <td>By default, EclipseLink persistence provider assumes that none of the columns in the primary key generator table have unique constraints.<br>If unique constraints do apply to one or more columns in this table, set the value of this attribute to an array of one or more <tt>UniqueConstraint</tt> instances.  
{{EclipseLink_Spec|section=Section 9.1.4 "UniqueConstraint Annotation"}}</td>
+
{{EclipseLink_Spec|section=Section 11.1.49 "UniqueConstraint Annotation"}}</td>
  <td></td>
+
  <td>No additional constraints</td>
 
  <td>No</td>
 
  <td>No</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
  <td>'''<tt>valueColumnName</tt>'''</td>
 
  <td>'''<tt>valueColumnName</tt>'''</td>
  <td>By default, EclipseLink persistence provider supplies a suitable name for the column that stores the generated id values: <tt>"SEQ_COUNT"</tt>.<br>If the default column name is inappropriate for your application, set the value of this attribute to the <tt>String</tt> column name you want.</td>
+
  <td>A <tt>String</tt> name of the column that stores the generated ID values.
 
  <td>SEQ_COUNT</td>
 
  <td>SEQ_COUNT</td>
 
  <td>No</td>
 
  <td>No</td>
 
</tr>
 
</tr>
</table>}}
+
}}
 +
 
  
The [[#Example 18-9|Usage of @TableGenerator]] example shows how to use this annotation to specify the allocation size for the <tt>TABLE</tt> primary key generator named <tt>Emp_Gen</tt>.
+
The following example shows how to use this annotation to specify the allocation size for the <tt>TABLE</tt> primary key generator named <tt>Emp_Gen</tt>.
  
<span id="Example 18-9"></span>
+
<span id="Example: @TableGenerator"></span>
''''' Usage of @TableGenerator'''''
+
======''Example: Using @TableGenerator''======
 
<source lang="java">
 
<source lang="java">
@Entity
+
@Entity
public class Employee implements Serializable {
+
public class Employee implements Serializable {
    ...
+
    ...
    @Id
+
    @Id
    @TableGenerator(name="Emp_Gen", allocationSize=1)
+
    @TableGenerator(name="Emp_Gen", allocationSize=1)
    @GeneratorValue(strategy=TABLE, generator="Emp_Gen")
+
    @GeneratorValue(strategy=TABLE, generator="Emp_Gen")
    @Column(name="CUST_ID")
+
    @Column(name="EMP_ID")
    public Long getId() {
+
    public Long getId() {
        return id;
+
        return id;
    }
+
    }
    ...
+
    ...
}
+
}
 
</source>
 
</source>
 +
 +
======''Example: Using <code><nowiki><table-generator></nowiki></code>''======
 +
 +
<source lang="xml">
 +
<entity class="Employee">
 +
    <attributes>
 +
        <id name="id">
 +
            <column name="EMP_ID"/>
 +
            <generated-value generator="Emp_Gen" strategy="TABLE"/>
 +
            <table-generator name="Emp_Gen" allocationSize="1"/>
 +
        </id>
 +
        ...
 +
    </attributes>
 +
</entity>
 +
</source>
 +
<br>
  
 
Every table that you use for id generation should have two columns – if there are more columns, only two will be used. The first column is of a string type and is used to identify the particular generator sequence. It is the primary key for all of the generators in the table. The name of this column is specified by the <tt>pkColumnName</tt> attribute. The second column is of an integer type and stores the actual id sequence that is being generated. The value stored in this column is the last identifier that was allocated in the sequence. The name of this column is specified by the <tt>valueColumnName</tt> attribute.
 
Every table that you use for id generation should have two columns – if there are more columns, only two will be used. The first column is of a string type and is used to identify the particular generator sequence. It is the primary key for all of the generators in the table. The name of this column is specified by the <tt>pkColumnName</tt> attribute. The second column is of an integer type and stores the actual id sequence that is being generated. The value stored in this column is the last identifier that was allocated in the sequence. The name of this column is specified by the <tt>valueColumnName</tt> attribute.
Line 101: Line 126:
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA
|previous=[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/GeneratedValue|@GeneratedValue]]
+
|previous=[[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/GeneratedValue|@GeneratedValue]]
|next=    [[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/SequenceGenerator|@SequenceGenerator]]
+
|next=    [[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/SequenceGenerator|@SequenceGenerator]]
|up=      [[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity|Entity]]
+
|up=      [[EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Creating_and_Configuring_Entities|Configuring Entities]]
|version= 2.1.0
+
|version=2.2.0 DRAFT}}
}}
+

Latest revision as of 11:01, 14 June 2011

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API


@TableGenerator

If you use the @GeneratedValue annotation to specify a primary key generator of type TABLE, then you can use the @TableGenerator annotation to fine-tune this primary key generator to do the following:

  • change the name of the primary key generator's table, because the name is awkward, a reserved word, incompatible with a preexisting data model, or invalid as a table name in your database;
  • change the allocation size to match your application requirements or database performance parameters;
  • change the initial value to match an existing data model (for example, if you are building on an existing data set, for which a range of primary key values has already been assigned or reserved);
  • configure the primary key generator's table with a specific catalog or schema;
  • configure a unique constraint on one or more columns of the primary key generator's table;
Elug javaspec icon.gif

For more information, see Section 11.1.46 "TableGenerator Annotation" in the JPA Specification.

@TableGenerator Attributes
Attribute Description Default Required?
name The name of the generator must match the name of a GeneratedValue with its strategy attribute set to TABLE. The scope of the generator name is global to the persistence unit (across all generator types). Yes
allocationSize An int value to match your your application requirements or database performance parameters. 50 No
catalog A String catalog name. Default catalog for database No
initialValue An int initial primary key value. 0 No
pkColumnName A String name for the primary key column in the generator table. SEQ_NAME No
pkColumnValue String primary key value for the primary key column in the generator table. TableGenereator.name No
schema The String name of the schema. Default schema of the database No
table A String name of the table in which to store the generated ID values. SEQUENCE No
uniqueConstraints By default, EclipseLink persistence provider assumes that none of the columns in the primary key generator table have unique constraints.
If unique constraints do apply to one or more columns in this table, set the value of this attribute to an array of one or more UniqueConstraint instances.
Elug javaspec icon.gif

For more information, see Section 11.1.49 "UniqueConstraint Annotation" in the JPA Specification.

No additional constraints No
valueColumnName A String name of the column that stores the generated ID values. SEQ_COUNT No


The following example shows how to use this annotation to specify the allocation size for the TABLE primary key generator named Emp_Gen.

Example: Using @TableGenerator
@Entity
public class Employee implements Serializable {
    ...
    @Id
    @TableGenerator(name="Emp_Gen", allocationSize=1)
    @GeneratorValue(strategy=TABLE, generator="Emp_Gen")
    @Column(name="EMP_ID")
    public Long getId() {
        return id;
    }
    ...
}
Example: Using <table-generator>
<entity class="Employee">
    <attributes>
        <id name="id">
            <column name="EMP_ID"/>
            <generated-value generator="Emp_Gen" strategy="TABLE"/>
            <table-generator name="Emp_Gen" allocationSize="1"/>
        </id>
        ...
    </attributes>
</entity>


Every table that you use for id generation should have two columns – if there are more columns, only two will be used. The first column is of a string type and is used to identify the particular generator sequence. It is the primary key for all of the generators in the table. The name of this column is specified by the pkColumnName attribute. The second column is of an integer type and stores the actual id sequence that is being generated. The value stored in this column is the last identifier that was allocated in the sequence. The name of this column is specified by the valueColumnName attribute.

Each defined generator represents a row in the table. The name of the generator becomes the value stored in the pkColumnName column for that row and is used by EclipseLink persistence provider to look up the generator to obtain its last allocated value.



Eclipselink-logo.gif
Version: 2.2.0 DRAFT
Other versions...