7.2. Collection mappings

Note

There are quite a range of mappings that can be generated for collections that cover many common relational models. We suggest you experiment with the schema generation tool so that you understand how various mapping declarations translate to database tables.
The Hibernate mapping element used for mapping a collection depends upon the type of interface. For example, a <set> element is used for mapping properties of type Set.
<class name="Product">
    <id name="serialNumber" column="productSerialNumber"/>
    <set name="parts">
        <key column="productSerialNumber" not-null="true"/>
        <one-to-many class="Part"/>
    </set>
</class>
Apart from <set>, there is also <list>, <map>, <bag>, <array> and <primitive-array> mapping elements. The <map> element is representative:
<map
    name="propertyName"                                          1
    table="table_name"                                           2
    schema="schema_name"                                         3
    lazy="true|extra|false"                                      4
    inverse="true|false"                                         5
    cascade="all|none|save-update|delete|all-delete-orphan|delete-orphan"    6
    sort="unsorted|natural|comparatorClass"                      7
    order-by="column_name asc|desc"                              8
    where="arbitrary sql where condition"                        9
    fetch="join|select|subselect"                                10
    batch-size="N"                                               11
    access="field|property|ClassName"                            12
    optimistic-lock="true|false"                                 13
    mutable="true|false"                                         14
    node="element-name|."
    embed-xml="true|false"
>
 
    <key .... />
    <map-key .... />
    <element .... />
</map>

1

name: the collection property name

2

table (optional - defaults to property name): the name of the collection table. It is not used for one-to-many associations.

3

schema (optional): the name of a table schema to override the schema declared on the root element

4

lazy (optional - defaults to true): disables lazy fetching and specifies that the association is always eagerly fetched. It can also be used to enable "extra-lazy" fetching where most operations do not initialize the collection. This is suitable for large collections.

5

inverse (optional - defaults to false): marks this collection as the "inverse" end of a bidirectional association.

6

cascade (optional - defaults to none): enables operations to cascade to child entities.

7

sort (optional): specifies a sorted collection with natural sort order or a given comparator class.

8

order-by (optional, JDK1.4 only): specifies a table column or columns that define the iteration order of the Map, Set or bag, together with an optional asc or desc.

9

where (optional): specifies an arbitrary SQL WHERE condition that is used when retrieving or removing the collection. This is useful if the collection needs to contain only a subset of the available data.

10

fetch (optional, defaults to select): chooses between outer-join fetching, fetching by sequential select, and fetching by sequential subselect.

11

batch-size (optional, defaults to 1): specifies a "batch size" for lazily fetching instances of this collection.

12

access (optional - defaults to property): the strategy Hibernate uses for accessing the collection property value.

13

optimistic-lock (optional - defaults to true): specifies that changes to the state of the collection results in increments of the owning entity's version. For one-to-many associations you may want to disable this setting.

14

mutable (optional - defaults to true): a value of false specifies that the elements of the collection never change. This allows for minor performance optimization in some cases.

7.2.1. Collection foreign keys

Collection instances are distinguished in the database by the foreign key of the entity that owns the collection. This foreign key is referred to as the collection key column, or columns, of the collection table. The collection key column is mapped by the <key> element.
There can be a nullability constraint on the foreign key column. For most collections, this is implied. For unidirectional one-to-many associations, the foreign key column is nullable by default, so you may need to specify not-null="true".
<key column="productSerialNumber" not-null="true"/>
The foreign key constraint can use ON DELETE CASCADE.
<key column="productSerialNumber" on-delete="cascade"/>
See the previous chapter for a full definition of the <key> element.