Red Hat Training

A Red Hat training course is available for Red Hat JBoss Web Server

6.2. Collection Mappings

6.2.1. About 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"
    table="table_name"
    schema="schema_name"
    lazy="true|extra|false"
    inverse="true|false"
    cascade="all|none|save-update|delete|all-delete-orphan|delete-orphan"
    sort="unsorted|natural|comparatorClass"
    order-by="column_name asc|desc"
    where="arbitrary sql where condition"
    fetch="join|select|subselect"
    batch-size="N"
    access="field|property|ClassName"
    optimistic-lock="true|false"
    mutable="true|false"
    node="element-name|."
    embed-xml="true|false"
>
 
    <key .... />
    <map-key .... />
    <element .... />
</map>
name: the collection property name
table (optional - defaults to property name): the name of the collection table. It is not used for one-to-many associations.
schema (optional): the name of a table schema to override the schema declared on the root element
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.
inverse (optional - defaults to false): marks this collection as the "inverse" end of a bidirectional association.
cascade (optional - defaults to none): enables operations to cascade to child entities.
sort (optional): specifies a sorted collection with natural sort order or a given comparator class.
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.
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.
fetch (optional, defaults to select): chooses between outer-join fetching, fetching by sequential select, and fetching by sequential subselect.
batch-size (optional, defaults to 1): specifies a "batch size" for lazily fetching instances of this collection.
access (optional - defaults to property): the strategy Hibernate uses for accessing the collection property value.
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.
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.
Report a bug

6.2.2. 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.
Report a bug

6.2.3. Collection Elements

Collections can contain almost any other Hibernate type, including: basic types, custom types, components and references to other entities. This is an important distinction. An object in a collection might be handled with "value" semantics (its life cycle fully depends on the collection owner), or it might be a reference to another entity with its own life cycle. In the latter case, only the "link" between the two objects is considered to be a state held by the collection.
The contained type is referred to as the collection element type. Collection elements are mapped by <element> or <composite-element>, or in the case of entity references, with <one-to-many> or <many-to-many>. The first two map elements with value semantics, the next two are used to map entity associations.
Report a bug

6.2.4. Indexed Collections

All collection mappings, except those with set and bag semantics, need an index column in the collection table. An index column is a column that maps to an array index, or List index, or Map key. The index of a Map may be of any basic type, mapped with <map-key>. It can be an entity reference mapped with <map-key-many-to-many>, or it can be a composite type mapped with <composite-map-key>. The index of an array or list is always of type integer and is mapped using the <list-index> element. The mapped column contains sequential integers that are numbered from zero by default. 
<list-index 
        column="column_name"
        base="0|1|..."/>
column_name (required): the name of the column holding the collection index values.
base (optional - defaults to 0): the value of the index column that corresponds to the first element of the list or array. 
<map-key 
        column="column_name"
        formula="any SQL expression"
        type="type_name"
        node="@attribute-name"
        length="N"/>
column (optional): the name of the column holding the collection index values.
formula (optional): a SQL formula used to evaluate the key of the map.
type (required): the type of the map keys. 
<map-key-many-to-many
        column="column_name"
        formula="any SQL expression"
        class="ClassName"
/>
column (optional): the name of the foreign key column for the collection index values.
formula (optional): a SQ formula used to evaluate the foreign key of the map key.
class (required): the entity class used as the map key.
If your table does not have an index column, and you still wish to use List as the property type, you can map the property as a Hibernate <bag>. A bag does not retain its order when it is persisted to the database, but it can be optionally sorted or ordered when it is retrieved from the database.
Report a bug

6.2.5. Collections of Values and Many-to-many Associations

Any collection of values or many-to-many associations requires a dedicated collection table with a foreign key column or columns, collection element column or columns, and possibly an index column or columns.
For a collection of values use the <element> tag. For example: 
<element
        column="column_name"
        formula="any SQL expression"
        type="typename"
        length="L"
        precision="P"
        scale="S"
        not-null="true|false"
        unique="true|false"
        node="element-name"
/>
column (optional): the name of the column holding the collection element values.
formula (optional): an SQL formula used to evaluate the element.
type (required): the type of the collection element.
A many-to-many association is specified using the <many-to-many> element. 
<many-to-many
        column="column_name"
        formula="any SQL expression"
        class="ClassName"
        fetch="select|join"
        unique="true|false"
        not-found="ignore|exception"
        entity-name="EntityName"
        property-ref="propertyNameFromAssociatedClass"
        node="element-name"
        embed-xml="true|false"
    />
column (optional): the name of the element foreign key column.
formula (optional): an SQL formula used to evaluate the element foreign key value.
class (required): the name of the associated class.
fetch (optional - defaults to join): enables outer-join or sequential select fetching for this association. This is a special case; for full eager fetching in a single SELECT of an entity and its many-to-many relationships to other entities, you would enable join fetching,not only of the collection itself, but also with this attribute on the <many-to-many> nested element.
unique (optional): enables the DDL generation of a unique constraint for the foreign-key column. This makes the association multiplicity effectively one-to-many.
not-found (optional - defaults to exception): specifies how foreign keys that reference missing rows will be handled: ignore will treat a missing row as a null association.
entity-name (optional): the entity name of the associated class, as an alternative to class.
property-ref (optional): the name of a property of the associated class that is joined to this foreign key. If not specified, the primary key of the associated class is used.
Here are some examples.
A set of strings: 
<set name="names" table="person_names">
    <key column="person_id"/>
    <element column="person_name" type="string"/>
</set>
A bag containing integers with an iteration order determined by the order-by attribute: 
<bag name="sizes" 
        table="item_sizes" 
        order-by="size asc">
    <key column="item_id"/>
    <element column="size" type="integer"/>
</bag>
An array of entities, in this case, a many-to-many association: 
<array name="addresses" 
        table="PersonAddress" 
        cascade="persist">
    <key column="personId"/>
    <list-index column="sortOrder"/>
    <many-to-many column="addressId" class="Address"/>
</array>
A map from string indices to dates: 
<map name="holidays" 
        table="holidays" 
        schema="dbo" 
        order-by="hol_name asc">
    <key column="id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map>
A list of components (this is discussed in the next chapter): 
<list name="carComponents" 
        table="CarComponents">
    <key column="carId"/>
    <list-index column="sortOrder"/>
    <composite-element class="CarComponent">
        <property name="price"/>
        <property name="type"/>
        <property name="serialNumber" column="serialNum"/>
    </composite-element>
</list>
Report a bug

6.2.6. One-to-many Associations

A one-to-many association links the tables of two classes via a foreign key with no intervening collection table. This mapping loses certain semantics of normal Java collections:
  • An instance of the contained entity class cannot belong to more than one instance of the collection.
  • An instance of the contained entity class cannot appear at more than one value of the collection index.
An association from Product to Part requires the existence of a foreign key column and possibly an index column to the Part table. A <one-to-many> tag indicates that this is a one-to-many association. 
<one-to-many 
        class="ClassName"
        not-found="ignore|exception"
        entity-name="EntityName"
        node="element-name"
        embed-xml="true|false"
    />
class (required): the name of the associated class.
not-found (optional - defaults to exception): specifies how cached identifiers that reference missing rows will be handled. ignore will treat a missing row as a null association.
entity-name (optional): the entity name of the associated class, as an alternative to class.
The <one-to-many> element does not need to declare any columns. Nor is it necessary to specify the table name anywhere.

Warning

If the foreign key column of a <one-to-many> association is declared NOT NULL, you must declare the <key> mapping not-null="true" or use a bidirectional association with the collection mapping marked inverse="true". See the discussion of bidirectional associations later in this chapter for more information.
The following example shows a map of Part entities by name, where partName is a persistent property of Part. Notice the use of a formula-based index: 
<map name="parts"
        cascade="all">
    <key column="productId" not-null="true"/>
    <map-key formula="partName"/>
    <one-to-many class="Part"/>
</map>
Report a bug