Problems with EJB 3.0 @IdClass specification

Note that comments below are based upon the Proposed Final Draft specification of EJB 3.0.

I feel that the specification of @IdClass is not at all clear. There are several problems:

1. It is not clear what the class that represents the composite primary key is used for.

Is it just an informative construct designed to tell the Enity Manager which fields of the Entity represent the key?

How and when are clients expected to use this class?

From trial and error and guesswork I have deduced that the class that represents primary key is essentially for two reasons:

a) First to tell the Entity Manager which fields of an Entity correspond to the composite primary key.
b) Secondly, for use in the EntityManager.find() and EntityManager.getReference() methods, as the second argument.

It is also not clearly stated anywhere whether the primary key class needs to be annotated in any manner. Clearly, if it is used as @EmbeddedId then it must be annotated using @Embeddable, but if it is used as @IdClass then no annotation is needed.

2. There aren't any examples illustrating the use of @IdClass. There are few code snippets that depict @IdClass usage, but these do not adhere to the requirements defined for primary key classes.

Section 9.1.13 shows an entity called Employee, but does not show the EmployeePK class.

Section 9.1.31 (page 190) shows a primary key class EmpPK but this class does not adhere to the rules - ie, not Serializable, and does not implement hashCode() and equals().