title: Purpose of @MapsId annotation in Hibernate
body: <p>I am trying to understand what difference the @MapsId annotation makes in Hibernate. I have gone through the Hibernate documentation but I am still confused on the explanation given there as I am new to Hibernate.</p>
  
  <p>The <a href="http://docs.jboss.org/hibernate/orm/4.3/manual/en-US/html/ch05.html" rel="noreferrer">document</a> says this:</p>
  
  <pre><code>@Entity
  class Customer {
     @EmbeddedId CustomerId id;
     boolean preferredCustomer;
  
     @MapsId("userId")
     @JoinColumns({
        @JoinColumn(name="userfirstname_fk", referencedColumnName="firstName"),
        @JoinColumn(name="userlastname_fk", referencedColumnName="lastName")
     })
     @OneToOne User user;
  }
  
  @Embeddable
  class CustomerId implements Serializable {
     UserId userId;
     String customerNumber;
  
     //implements equals and hashCode
  }
  
  @Entity 
  class User {
     @EmbeddedId UserId id;
     Integer age;
  }
  
  @Embeddable
  class UserId implements Serializable {
     String firstName;
     String lastName;
  
     //implements equals and hashCode
  }
  </code></pre>
  
  <blockquote>
    <p>In the embedded id object, the association is represented as the
    identifier of the associated entity. But you can link its value to a
    regular association in the entity via the @MapsId annotation. The
    @MapsId value correspond to the property name of the embedded id
    object containing the associated entity's identifier. In the database,
    it means that the Customer.user and the CustomerId.userId properties
    share the same underlying column (user_fk in this case).</p>
  </blockquote>
  
  <p>I am not clear on what this explanation says, so I tired with <code>hbm2ddl</code> set as <code>create</code> in my configuration file and I observed these:</p>
  
  <p>With @MapsId and @JoinColumns on Customer entity the DDL statements are:</p>
  
  <pre><code>Hibernate: create table CUSTOMER (customerNumber varchar2(255 char) not null, preferredCustomer number(1,0) not null, userfirstname_fk varchar2(255 char) not null, userlastname_fk varchar2(255 char) not null, primary key (customerNumber, userfirstname_fk, userlastname_fk))
  Hibernate: create table USER (firstName varchar2(255 char) not null, lastName varchar2(255 char) not null, age number(10,0), primary key (firstName, lastName))
  Hibernate: alter table CUSTOMER add constraint UK_xxxx  unique (userfirstname_fk, userlastname_fk)
  Hibernate: alter table CUSTOMER add constraint FK_xxxx foreign key (userfirstname_fk, userlastname_fk) references TBL_USER
  </code></pre>
  
  <p>If I remove the @MapsId and @JoinColumns annotations I see these:</p>
  
  <pre><code>Hibernate: create table CUSTOMER (customerNumber varchar2(255 char) not null, firstName varchar2(255 char), lastName varchar2(255 char), preferredCustomer number(1,0) not null, user_firstName varchar2(255 char), user_lastName varchar2(255 char), primary key (customerNumber, firstName, lastName))
  Hibernate: create table USER (firstName varchar2(255 char) not null, lastName varchar2(255 char) not null, age number(10,0), primary key (firstName, lastName))
  Hibernate: alter table CUSTOMER add constraint FK_xxxx foreign key (user_firstName, user_lastName) references TBL_USER
  </code></pre>
  
  <p>Please help me in understanding the concept of the @MapsId annotation in Hibernate.</p>