Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/Id"
m |
(→Allowing Zero Value Primary Keys) |
||
(21 intermediate revisions by the same user not shown) | |||
Line 3: | Line 3: | ||
|toc=n | |toc=n | ||
|eclipselink=y | |eclipselink=y | ||
− | |eclipselinktype=JPA}} | + | |eclipselinktype=JPA |
+ | |api=y | ||
+ | |apis= | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Id.html @Id] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Id.html @IdClass] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Id.html @GeneratedValue] | ||
+ | *[http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/annotations/PrimaryKey.html @PrimaryKey] | ||
+ | }} | ||
=@Id= | =@Id= | ||
− | Use the <tt>@Id</tt> annotation to designate one or more persistent fields or properties as the entity's primary key. | + | Use the <tt>@Id</tt> annotation or <code><id></code> XML element to designate one or more persistent fields or properties as the entity's primary key. |
− | For each entity, you must designate | + | For each entity, you must designate one of the following: |
* one <tt>@Id</tt>, or | * one <tt>@Id</tt>, or | ||
* one <tt>[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/EmbeddedId|@EmbeddedId]]</tt>, or | * one <tt>[[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/EmbeddedId|@EmbeddedId]]</tt>, or | ||
Line 13: | Line 20: | ||
{{EclipseLink_Note | {{EclipseLink_Note | ||
− | |note=The | + | |note=The <tt>@Id</tt> and <tt>@IdClass</tt> combination – is only applicable to composite primary key configuration. |
}} | }} | ||
Line 20: | Line 27: | ||
By default, the entities <code>Id</code> must be set by the application, normally before the <code>persist</code> is called. A [[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/GeneratedValue|@GeneratedValue]] can be used to have EclipseLink generate the Id value. | By default, the entities <code>Id</code> must be set by the application, normally before the <code>persist</code> is called. A [[EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Entity/GeneratedValue|@GeneratedValue]] can be used to have EclipseLink generate the Id value. | ||
+ | |||
+ | If the <code>Id</code> (or part of the Id) is also a foreign key from a reference to another entity, the <tt>@Id</tt> annotation should be placed on the <tt>@OneToOne</tt> or <tt>@ManyToOne</tt> attribute. The entity's <code>Id</code> is then composed of the <code>Id</code> of the referenced entity. | ||
+ | |||
+ | {{EclipseLink_Note | ||
+ | |note=The id of a persistent object instance must never be changed and cannot be updated. | ||
+ | }} | ||
This example shows how to use this annotation to designate the persistent field <tt>empID</tt> as the primary key of the <tt>Employee</tt> table. | This example shows how to use this annotation to designate the persistent field <tt>empID</tt> as the primary key of the <tt>Employee</tt> table. | ||
<span id="Id_Annotation_Example"></span> | <span id="Id_Annotation_Example"></span> | ||
− | ====== ''Example: | + | ======''Example: @Id Annotation''====== |
<source lang="java"> | <source lang="java"> | ||
− | + | @Entity | |
− | + | public class Employee implements Serializable { | |
− | + | @Id | |
− | + | private int empID; | |
− | + | ... | |
− | + | } | |
− | + | ||
</source> | </source> | ||
− | + | <span id="Id_XML_Example"></span> | |
+ | ======''Example: Id XML''====== | ||
+ | |||
+ | <source lang="xml"> | ||
+ | <entity class="Employee"> | ||
+ | <attributes> | ||
+ | <id name="empID"/> | ||
+ | ... | ||
+ | </attributes> | ||
+ | </entity> | ||
+ | </source> | ||
{{EclipseLink_Spec | {{EclipseLink_Spec | ||
Line 42: | Line 64: | ||
|section=Section 11.1.18 "Id Annotation"}} | |section=Section 11.1.18 "Id Annotation"}} | ||
+ | The <tt>@Id</tt> annotation supports the use of EclipseLink converters. See [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings/Default_Conversions_and_Converters|Using EclipseLink JPA Converters]]. | ||
+ | |||
+ | It is possible to generate the value for an <code>Id</code> using the <code>prePersist</code> event, or through triggers when using the Oracle database platform. See [[EclipseLink/UserGuide/JPA/Advanced_JPA_Development/Returning|Returning]]. | ||
+ | |||
+ | ==Allowing Zero Value Primary Keys== | ||
+ | By default, EclipseLink interprets zero as ''null'' for primitive types that cannot be null (such as <tt>int</tt> and <tt>long</tt>) causing zero to be an invalid value for primary keys. You can modify this setting by using the '''eclipselink.id-validation''' property in the <tt>persistence.xml file</tt>, or by using the <code>@PrimaryKey</code> annotation to configure an <code>IdValidation</code> for an entity class.<br/> | ||
+ | Valid values are defined in the <code>IdValidation</code> enum: | ||
+ | *'''NULL''' – EclipseLink interprets zero values as ''zero''. This permits primary keys to use a value of zero. | ||
+ | *'''ZERO''' (default) – EclipseLink interprets zero as ''null''. | ||
+ | *'''NEGATIVE''' – EclipseLink interprets negative values as ''null''. | ||
+ | *'''NONE''' – EclipseLink does not validate the id value. | ||
+ | |||
+ | You can also use the <code>@PrimaryKey</code> annotation to configure the id validation for a specific entity. | ||
{{EclipseLink_JPA | {{EclipseLink_JPA | ||
− | |previous=[[EclipseLink/UserGuide/JPA/ | + | |previous=[[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Creating_and_Configuring_Entities|Configuring Entities]] |
− | |next= [[EclipseLink/UserGuide/JPA/ | + | |next= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Ids/IdClass|@IdClass]] |
− | |up= [[EclipseLink/UserGuide/JPA/ | + | |up= [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Entities/Creating_and_Configuring_Entities|Configuring Entities]] |
|version=2.2.0 DRAFT}} | |version=2.2.0 DRAFT}} |
Latest revision as of 13:33, 20 June 2011
EclipseLink JPA
EclipseLink | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source |
Key API
@Id
Use the @Id annotation or <id>
XML element to designate one or more persistent fields or properties as the entity's primary key.
For each entity, you must designate one of the following:
- one @Id, or
- one @EmbeddedId, or
- multiple @Id and an @IdClass
Note: The @Id and @IdClass combination – is only applicable to composite primary key configuration.
The @Id annotation does not have attributes.
By default, the entities Id
must be set by the application, normally before the persist
is called. A @GeneratedValue can be used to have EclipseLink generate the Id value.
If the Id
(or part of the Id) is also a foreign key from a reference to another entity, the @Id annotation should be placed on the @OneToOne or @ManyToOne attribute. The entity's Id
is then composed of the Id
of the referenced entity.
Note: The id of a persistent object instance must never be changed and cannot be updated.
This example shows how to use this annotation to designate the persistent field empID as the primary key of the Employee table.
Example: @Id Annotation
@Entity public class Employee implements Serializable { @Id private int empID; ... }
Example: Id XML
<entity class="Employee"> <attributes> <id name="empID"/> ... </attributes> </entity>
For more information, see Section 11.1.18 "Id Annotation" in the JPA Specification.
The @Id annotation supports the use of EclipseLink converters. See Using EclipseLink JPA Converters.
It is possible to generate the value for an Id
using the prePersist
event, or through triggers when using the Oracle database platform. See Returning.
Allowing Zero Value Primary Keys
By default, EclipseLink interprets zero as null for primitive types that cannot be null (such as int and long) causing zero to be an invalid value for primary keys. You can modify this setting by using the eclipselink.id-validation property in the persistence.xml file, or by using the @PrimaryKey
annotation to configure an IdValidation
for an entity class.
Valid values are defined in the IdValidation
enum:
- NULL – EclipseLink interprets zero values as zero. This permits primary keys to use a value of zero.
- ZERO (default) – EclipseLink interprets zero as null.
- NEGATIVE – EclipseLink interprets negative values as null.
- NONE – EclipseLink does not validate the id value.
You can also use the @PrimaryKey
annotation to configure the id validation for a specific entity.