EclipseLink/UserGuide/JPA/Basic JPA Development/Entities/Ids/IdClass

EclipseLink JPA

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

Key API

• @IdClass

@IdClass

Use the @IdClass annotation to specify a composite primary key class (usually made up of two or more primitive, JDK object types or Entity types) for an entity or MappedSuperclass.

Note: Composite primary keys typically arise during mapping from legacy databases when the database key is comprised of several columns.

A composite primary key class has the following characteristics:

• It is a POJO class.
• It is a public class with a public no-argument constructor.
• If you use property-based access, the properties of the primary key class are public or protected.
• It is serializable.
• It defines equals and hashCode methods. The semantics of value equality for these methods must be consistent with the database equality for the database types to which the key is mapped.
• Its fields or properties must correspond in type and name to the entity primary key fields or properties annotated with @Id.
• An instance of the IdClass is used with the EntityManager find() operation, to find an entity by its id.

Alternatively, you can make the composite primary key class an embedded class owned by the entity (see @EmbeddedId).

The @IdClass annotation has a required attribute value that you set to the class to specify this class as a composite primary key class.

The Nonembedded Composite Primary Key Class example, below, shows a nonembedded composite primary key class. In this class, fields empName and birthDay must correspond in name and type to properties in the entity class. The @IdClass Annotation example, below, shows how to configure an entity with this nonembedded composite primary key class using the @IdClass annotation. Because entity class fields empName and birthDay are used in the primary key, you must also annotate them using the @Id annotation (see @Id).

Example: Nonembedded Composite Primary Key Class

 public class EmployeePK implements Serializable {
 
     private String empName;
     private Date birthDay;
 
     public EmployeePK() {
     }
 
     public String getName() {
         return this.empName;
     }
 
     public void setName(String name) {
         this.empName = name;
     }
 
     public Date getBirthDay() {
         return this.birthDay;
     }
 
     public void setBirthDay(Date date) {
         this.birthDay = date;
     }
 
     public int hashCode() {
         return (int)this.empName.hashCode();
     }
 
     public boolean equals(Object obj) {
         if (obj == this) return true;
         if (!(obj instanceof EmployeePK)) return false;
         EmployeePK pk = (EmployeePK) obj;
         return pk.birthDay.equals(this.birthDay) && pk.empName.equals(this.empName);
     }
 }

Example: @IdClass Annotation

@IdClass(EmployeePK.class)
@Entity
public class Employee implements Serializable{
 
   @Id String empName;
   @Id Date birthDay;
   ...
}

Example: <id-class> XML

<entity class="Employee">
    <id-class class="EmployeePK"/>
    <attributes>
        <id name="empName"/>
        <id name="birthDay"/>
    </attributes>
</entity>

If one of the Id values comes from a OneToOne or ManyToOne relationship, then the IdClass must contain the Id of the related entity.

The Composite Primary Key Class With Foreign Key example, below, shows a composite primary key class that is composed of a foreign key. The id class contains the id of the department, not a department reference.

Example: Composite Primary Key Class With Foreign Key

public class EmployeePK implements Serializable {
 
     private long empId;
     private long department;
 
     public EmployeePK() {
     }
 
     public long getEmpId() {
         return this.empId;
     }
 
     public void setEmpId(long empId) {
         this.empId = empId;
     }
 
     public long getDepartment() {
         return this.department;
     }
 
     public void setDepartment(long department) {
         this.department = department;
     }
 
     public int hashCode() {
         return (int)this.empId.hashCode();
     }
 
     public boolean equals(Object obj) {
         if (obj == this) return true;
         if (!(obj instanceof EmployeePK)) return false;
         EmployeePK pk = (EmployeePK) obj;
         return pk.empId.equals(this.empId) && pk.department.equals(this.department);
     }
}

Example: @IdClass Annotation With ManyToOne

@IdClass(EmployeePK.class)
@Entity
public class Employee implements Serializable{
 
   @Id
   long empId;
   @Id
   @ManyToOne
   Department department;
   ...
}

Example: <id-class> XML With <many-to-one>

<entity class="Employee">
    <id-class class="EmployeePK"/>
    <attributes>
        <id name="empId"/>
        <many-to-one name="department" id="true">
            <id/>
        </many-to-one>
    </attributes>
</entity>

For more information, see Section 11.1.19 "IdClass Annotation" in the JPA Specification.

Version: 2.2.0 DRAFT
Other versions...

@Id	Configuring Entities	@EmbeddedId
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...