6.2.4. 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>