6.3.4. Primary-Key Classes and Composite Keys
Sometimes relational mappings require a primary key to be composed of multiple persistent properties. For instance, let's say that our relational model specified that our Customer entity should be identified by both its last name and its Social Security number instead of an autogenerated numeric key. These are called composite keys. The Java Persistence specification provides multiple ways to map this type of model. One is through the @javax.persistence.IdClass annotation; the other is through the @javax.persistence.EmbeddedId annotation.
6.3.4.1. @IdClass
The first way to define a primary-key class (and, for that matter, composite keys) is to use the @IdClass annotation. Your bean class does not use this primary-key class internally, but it does use it to interact with the entity manager when finding a persisted object through its primary key. @IdClass is a class-level annotation and specifies what primary-key class you should use when interacting with the entity manager.
@Target(TYPE)
@Retention(RUNTIME)
public @interface IdClass
{
Class value( );
}
In your bean class, you designate one or more properties that make up your primary key, using the @Id annotation. These properties must map exactly to properties in the @IdClass. Let's look at changing our Customer bean class to have a composite key made up of last name and Social Security number. First, let's define our primary-key class:
package com.titan.domain;
public class CustomerPK
implements java.io.Serializable {
private String lastName;
private long ssn;
public CustomerPK( ) {}
public CustomerPK(String lastName, long ssn)
{
this.lastName = lastName;
this.ssn = ssn;
}
public String getLastName( ) { return this.lastName; }
public void setLastName(String lastName) { this.lastName = lastName; }
public long getSsn( ) { return ssn; }
public void setSsn(long ssn) { this.ssn = ssn; }
public boolean equals(Object obj)
{
if (obj == this) return true;
if (!(obj instanceof CustomerPK)) return false;
CustomerPK pk = (CustomerPK)obj;
if (!lastName.equals(pk.lastName)) return false;
if (ssn != pk.ssn) return false;
return true;
}
public int hashCode( )
{
return lastName.hashCode( ) + (int)ssn;
}
}
The primary-key class must meet these requirements:
It must be serializable.
It must have a public no-arg constructor.
It must implement the equals( ) and hashCode( ) methods.
Our Customer bean must have the same exact properties as the CustomerPK class, and these properties are annotated with multiple @Id annotations:
package com.titan.domain;
import javax.persistence.*;
@Entity
@IdClass(CustomerPK.class)
public class Customer implements java.io.Serializable {
private String firstName;
private String lastName;
private long ssn;
public String getFirstName( ) { return firstName; }
public void setFirstName(String firstName) { this.firstName = firstName; }
@Id
public String getLastName( ) { return lastName; }
public void setLastName(String lastName) { this.lastName = lastName; }
@Id
public long getSsn( ) { return ssn; }
public void setSsn(long ssn) { this.ssn = ssn; }
}
Primary-key autogeneration is not supported for composite keys and primary-key classes. You will have to manually create the key values in code.
Let's now look at the XML mapping equivalent to @IdClass:
<entity-mappings>
<entity class="com.titan.domain.Customer" access="PROPERTY">
<id-class>com.titan.domain.CustomerPK</id-class>
<attributes>
<id name="lastName"/>
<id name="ssn"/>
</attributes>
</entity>
</entity-mappings>
The <id-class> element is a subelement of <entity>, and its value is the fully qualified class name of the primary-key class. Notice also that multiple <id> elements for each property map to the primary-key class.
The primary-key class is used whenever you are querying for the Customer:
CustomerPK pk = new CustomerPK("Burke", 9999999);
Customer cust = entityManager.find(Customer.class, pk);
Whenever you call an EntityManager method like find( ) or getreference( ), you must use the primary key class to identify the entity.
