Chapter 7. Association Mappings
Prev |  | Next

## Chapter 7. Association Mappings

## 7.1. Introduction

Association mappings are the often most difficult thing to get right. In this section we'll go through the canonical cases one by one, starting with unidirectional mappings, and then considering the bidirectional cases. We'll use `Person` and `Address` in all the examples.

We'll classify associations by whether or not they map to an intervening join table, and by multiplicity.

Nullable foreign keys are not considered good practice in traditional data modelling, so all our examples use not null foreign keys. This is not a requirement of Hibernate, and the mappings will all work if you drop the nullability constraints.

## 7.2. Unidirectional associations

### 7.2.1. many to one

A unidirectional many-to-one association is the most common kind of unidirectional association.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <many-to-one name="address"
            column="addressId"
            not-null="true"/>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key, addressId bigint not null )
    create table Address ( addressId bigint not null primary key )

### 7.2.2. one to one

A unidirectional one-to-one association on a foreign key is almost identical. The only difference is the column unique constraint.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <many-to-one name="address"
            column="addressId"
            unique="true"
            not-null="true"/>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key, addressId bigint not null unique )
    create table Address ( addressId bigint not null primary key )

A unidirectional one-to-one association on a primary key usually uses a special id generator. (Notice that we've reversed the direction of the association in this example.)

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
    </class>

    <class name="Address">
        <id name="id" column="personId">
            <generator class="foreign">
                <param name="property">person</param>
            </generator>
        </id>
        <one-to-one name="person" constrained="true"/>
    </class>

    create table Person ( personId bigint not null primary key )
    create table Address ( personId bigint not null primary key )

### 7.2.3. one to many

A unidirectional one-to-many association on a foreign key is a very unusual case, and is not really recommended.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <set name="addresses">
            <key column="personId"
                not-null="true"/>
            <one-to-many class="Address"/>
        </set>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key )
    create table Address ( addressId bigint not null primary key, personId bigint not null )

We think it's better to use a join table for this kind of association.

## 7.3. Unidirectional associations with join tables

### 7.3.1. one to many

A unidirectional one-to-many association on a join table is much preferred. Notice that by specifying `unique="true"`, we have changed the multiplicity from many-to-many to one-to-many.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <set name="addresses" table="PersonAddress">
            <key column="personId"/>
            <many-to-many column="addressId"
                unique="true"
                class="Address"/>
        </set>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId not null, addressId bigint not null primary key )
    create table Address ( addressId bigint not null primary key )

### 7.3.2. many to one

A unidirectional many-to-one association on a join table is quite common when the association is optional.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <join table="PersonAddress"
            optional="true">
            <key column="personId" unique="true"/>
            <many-to-one name="address"
                column="addressId"
                not-null="true"/>
        </join>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId bigint not null primary key, addressId bigint not null )
    create table Address ( addressId bigint not null primary key )

### 7.3.3. one to one

A unidirectional one-to-one association on a join table is extremely unusual, but possible.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <join table="PersonAddress"
            optional="true">
            <key column="personId"
                unique="true"/>
            <many-to-one name="address"
                column="addressId"
                not-null="true"
                unique="true"/>
        </join>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
    create table Address ( addressId bigint not null primary key )

### 7.3.4. many to many

Finally, we have a unidirectional many-to-many association.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <set name="addresses" table="PersonAddress">
            <key column="personId"/>
            <many-to-many column="addressId"
                class="Address"/>
        </set>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
    create table Address ( addressId bigint not null primary key )

## 7.4. Bidirectional associations

### 7.4.1. one to many / many to one

A bidirectional many-to-one association is the most common kind of association. (This is the standard parent/child relationship.)

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <many-to-one name="address"
            column="addressId"
            not-null="true"/>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
        <set name="people" inverse="true">
            <key column="addressId"/>
            <one-to-many class="Person"/>
        </set>
    </class>

    create table Person ( personId bigint not null primary key, addressId bigint not null )
    create table Address ( addressId bigint not null primary key )

If you use a `List` (or other indexed collection) you need to set the `key` column of the foreign key to `not null`, and let Hibernate manage the association from the collections side to maintain the index of each element (making the other side virtually inverse by setting `update="false"` and `insert="false"`):

    <class name="Person">
       <id name="id"/>
       ...
       <many-to-one name="address"
          column="addressId"
          not-null="true"
          insert="false"
          update="false"/>
    </class>

    <class name="Address">
       <id name="id"/>
       ...
       <list name="people">
          <key column="addressId" not-null="true"/>
          <list-index column="peopleIdx"/>
          <one-to-many class="Person"/>
       </list>
    </class>

It is important that you define `not-null="true"` on the `<key>` element of the collection mapping if the underlying foreign key column is `NOT NULL`. Don't only declare `not-null="true"` on a possible nested `<column>` element, but on the `<key>` element.

### 7.4.2. one to one

A bidirectional one-to-one association on a foreign key is quite common.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <many-to-one name="address"
            column="addressId"
            unique="true"
            not-null="true"/>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
       <one-to-one name="person"
            property-ref="address"/>
    </class>

    create table Person ( personId bigint not null primary key, addressId bigint not null unique )
    create table Address ( addressId bigint not null primary key )

A bidirectional one-to-one association on a primary key uses the special id generator.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <one-to-one name="address"/>
    </class>

    <class name="Address">
        <id name="id" column="personId">
            <generator class="foreign">
                <param name="property">person</param>
            </generator>
        </id>
        <one-to-one name="person"
            constrained="true"/>
    </class>

    create table Person ( personId bigint not null primary key )
    create table Address ( personId bigint not null primary key )

## 7.5. Bidirectional associations with join tables

### 7.5.1. one to many / many to one

A bidirectional one-to-many association on a join table. Note that the `inverse="true"` can go on either end of the association, on the collection, or on the join.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <set name="addresses"
            table="PersonAddress">
            <key column="personId"/>
            <many-to-many column="addressId"
                unique="true"
                class="Address"/>
        </set>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
        <join table="PersonAddress"
            inverse="true"
            optional="true">
            <key column="addressId"/>
            <many-to-one name="person"
                column="personId"
                not-null="true"/>
        </join>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId bigint not null, addressId bigint not null primary key )
    create table Address ( addressId bigint not null primary key )

### 7.5.2. one to one

A bidirectional one-to-one association on a join table is extremely unusual, but possible.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <join table="PersonAddress"
            optional="true">
            <key column="personId"
                unique="true"/>
            <many-to-one name="address"
                column="addressId"
                not-null="true"
                unique="true"/>
        </join>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
        <join table="PersonAddress"
            optional="true"
            inverse="true">
            <key column="addressId"
                unique="true"/>
            <many-to-one name="person"
                column="personId"
                not-null="true"
                unique="true"/>
        </join>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
    create table Address ( addressId bigint not null primary key )

### 7.5.3. many to many

Finally, we have a bidirectional many-to-many association.

    <class name="Person">
        <id name="id" column="personId">
            <generator class="native"/>
        </id>
        <set name="addresses" table="PersonAddress">
            <key column="personId"/>
            <many-to-many column="addressId"
                class="Address"/>
        </set>
    </class>

    <class name="Address">
        <id name="id" column="addressId">
            <generator class="native"/>
        </id>
        <set name="people" inverse="true" table="PersonAddress">
            <key column="addressId"/>
            <many-to-many column="personId"
                class="Person"/>
        </set>
    </class>

    create table Person ( personId bigint not null primary key )
    create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
    create table Address ( addressId bigint not null primary key )

## 7.6. More complex association mappings

More complex association joins are extremely rare. Hibernate makes it possible to handle more complex situations using SQL fragments embedded in the mapping document. For example, if a table with historical account information data defines `accountNumber`, `effectiveEndDate` and `effectiveStartDate`columns, mapped as follows:

    <properties name="currentAccountKey">
        <property name="accountNumber" type="string" not-null="true"/>
        <property name="currentAccount" type="boolean">
            <formula>case when effectiveEndDate is null then 1 else 0 end</formula>
        </property>
    </properties>
    <property name="effectiveEndDate" type="date"/>
    <property name="effectiveStateDate" type="date" not-null="true"/>

Then we can map an association to the current instance (the one with null `effectiveEndDate`) using:

    <many-to-one name="currentAccountInfo"
            property-ref="currentAccountKey"
            class="AccountInfo">
        <column name="accountNumber"/>
        <formula>'1'</formula>
    </many-to-one>

In a more complex example, imagine that the association between `Employee` and `Organization` is maintained in an `Employment` table full of historical employment data. Then an association to the employee's most recent employer (the one with the most recent `startDate`) might be mapped this way:

    <join>
        <key column="employeeId"/>
        <subselect>
            select employeeId, orgId
            from Employments
            group by orgId
            having startDate = max(startDate)
        </subselect>
        <many-to-one name="mostRecentEmployer"
                class="Organization"
                column="orgId"/>
    </join>

You can get quite creative with this functionality, but it is usually more practical to handle these kinds of cases using HQL or a criteria query.

Prev | Up | Next
Chapter 6. Collection Mapping | Home | Chapter 8. Component Mapping