Legacy systems often contain composite natural keys, i.e. identifiers composed from different database fields.
Hibernate offers three ways to deal with it. One is the @IdClass annotation that allows you to create an annotation-free class containing all the fields you like to use and use those fields again in your annotated entity class, annotating them with @Id.
Normally you need to map the class member name with the database field name. I.e. if you use the members userId and versionId, it’s quite likely you have to map them to database fields named USER_ID and FIELD_ID.
With the JPA annotations you do so using the @Column-annotation. But there is a bug. Hibernate completely ignores the @Column annotation if used in conjunction with other annotations, e.g. @Id.
Please vote for fixing this ugly, ugly bug.