Hibernate requires that persistent collection-valued fields be declared as an interface type, for example: The actual interface might be java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap or ... anything you like! (Where "anything you like" means you will have to write an implementation of org.hibernate.usertype.UserCollectionType.) Notice how we initialized the instance variable with an instance of HashSet. This is the best way to initialize collection valued properties of newly instantiated (non-persistent) instances. When you make the instance persistent - by calling persist(), for example - Hibernate will actually replace the HashSet with an instance of Hibernate's own implementation of Set. Watch out for errors like this: The persistent collections injected by Hibernate behave like HashMap, HashSet, TreeMap, TreeSet or ArrayList, depending upon the interface type. Collections instances have the usual behavior of value types. They are automatically persisted when referenced by a persistent object and automatically deleted when unreferenced. If a collection is passed from one persistent object to another, its elements might be moved from one table to another. Two entities may not share a reference to the same collection instance. Due to the underlying relational model, collection-valued properties do not support null value semantics; Hibernate does not distinguish between a null collection reference and an empty collection. You shouldn't have to worry much about any of this. Use persistent collections the same way you use ordinary Java collections. Just make sure you understand the semantics of bidirectional associations (discussed later). The Hibernate mapping element used for mapping a collection depends upon the type of the interface. For example, a <set> element is used for mapping properties of type Set. ]]> Apart from <set>, there is also <list>, <map>, <bag>, <array> and <primitive-array> mapping elements. The <map> element is representative: ]]> name the collection property name table (optional - defaults to property name) the name of the collection table (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) enable lazy initialization (not available for arrays) inverse (optional - defaults to false) mark this collection as the "inverse" end of a bidirectional association cascade (optional - defaults to none) enable operations to cascade to child entities sort (optional) specify a sorted collection with natural sort order, or a given comparator class order-by (optional, JDK1.4 only) specify 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) specify an arbitrary SQL WHERE condition to be used when retrieving or removing the collection (useful if the collection should contain only a subset of the available data) fetch (optional, defaults to select) Choose between outer-join fetching, fetching by sequential select, and fetching by sequential subselect. Only one collection may be fetched by outer join per SQL SELECT. batch-size (optional, defaults to 1) specify a "batch size" for lazily fetching instances of this collection. access (optional - defaults to property): The strategy Hibernate should use for accessing the property value. optimistic-lock (optional - defaults to true): Species that changes to the state of the collection results in increment of the owning entity's version. (For one to many associations, it is often reasonable to disable this setting.) 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 may 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 might need to specify not-null="true". ]]> The foreign key constraint may use ON DELETE CASCADE. ]]> See the previous chapter for a full definition of the <key> element. Collections may contain almost any other Hibernate type, including all basic types, custom types, components, and of course, references to other entities. This is an important distinction: an object in a collection might be handled with "value" semantics (its lifecycle fully depends on the collection owner) or it might be a reference to another entity, with its own lifecycle. In the latter case, only the "link" between the two objects is considered to be 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. All collection mappings, except those with set and bag semantics, need an index column in the collection table - 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 may be an entity reference mapped with <map-key-many-to-many>, or it may 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 (numbered from zero, by default). ]]> 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. ]]> 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 (optional, defaults to integer): The type of the collection index. ]]> column (optional): The name of the foreign key column for the collection index values. formula (optional): A SQL formula used to evaluate the foreign key of the map key. class (required): The entity class used as the collection index. If your table doesn't have an index column, and you still wish to use List as the property type, you should map the property as a Hibernate <bag>. A bag does not retain its order when it is retrieved from the database, but it may be optionally sorted or ordered. There are quite a range of mappings that can be generated for collections, covering many common relational models. We suggest you experiment with the schema generation tool to get a feeling for how various mapping declarations translate to database tables. Any collection of values or many-to-many association 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, we use the <element> tag. ]]> 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. ]]> 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): Enable 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. Some examples, first, a set of strings: ]]> A bag containing integers (with an iteration order determined by the order-by attribute): ]]> An array of entities - in this case, a many to many association: ]]> A map from string indices to dates: ]]> A list of components (discussed in the next chapter): ]]> 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 may not belong to more than one instance of the collection An instance of the contained entity class may not appear at more than one value of the collection index An association from Product to Part requires 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. ]]> 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. Notice that the <one-to-many> element does not need to declare any columns. Nor is it necessary to specify the table name anywhere. Very important note: 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. This 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. ]]> Hibernate supports collections implementing java.util.SortedMap and java.util.SortedSet. You must specify a comparator in the mapping file: ]]> Allowed values of the sort attribute are unsorted, natural and the name of a class implementing java.util.Comparator. Sorted collections actually behave like java.util.TreeSet or java.util.TreeMap. If you want the database itself to order the collection elements use the order-by attribute of set, bag or map mappings. This solution is only available under JDK 1.4 or higher (it is implemented using LinkedHashSet or LinkedHashMap). This performs the ordering in the SQL query, not in memory. ]]> Note that the value of the order-by attribute is an SQL ordering, not a HQL ordering! Associations may even be sorted by some arbitrary criteria at runtime using a collection filter(). A bidirectional association allows navigation from both "ends" of the association. Two kinds of bidirectional association are supported: one-to-many set or bag valued at one end, single-valued at the other many-to-many set or bag valued at both ends You may specify a bidirectional many-to-many association simply by mapping two many-to-many associations to the same database table and declaring one end as inverse (which one is your choice, but it can not be an indexed collection). Here's an example of a bidirectional many-to-many association; each category can have many items and each item can be in many categories: ... ... ]]> Changes made only to the inverse end of the association are not persisted. This means that Hibernate has two representations in memory for every bidirectional association, one link from A to B and another link from B to A. This is easier to understand if you think about the Java object model and how we create a many-to-many relationship in Java: The non-inverse side is used to save the in-memory representation to the database. You may define a bidirectional one-to-many association by mapping a one-to-many association to the same table column(s) as a many-to-one association and declaring the many-valued end inverse="true". .... .... ]]> Mapping one end of an association with inverse="true" doesn't affect the operation of cascades, these are orthogonal concepts! There are three possible approaches to mapping a ternary association. One is to use a Map with an association as its index: ]]> ]]> A second approach is to simply remodel the association as an entity class. This is the approach we use most commonly. A final alternative is to use composite elements, which we will discuss later. If you've fully embraced our view that composite keys are a bad thing and that entities should have synthetic identifiers (surrogate keys), then you might find it a bit odd that the many to many associations and collections of values that we've shown so far all map to tables with composite keys! Now, this point is quite arguable; a pure association table doesn't seem to benefit much from a surrogate key (though a collection of composite values might). Nevertheless, Hibernate provides a feature that allows you to map many to many associations and collections of values to a table with a surrogate key. The <idbag> element lets you map a List (or Collection) with bag semantics. ]]> As you can see, an <idbag> has a synthetic id generator, just like an entity class! A different surrogate key is assigned to each collection row. Hibernate does not provide any mechanism to discover the surrogate key value of a particular row, however. Note that the update performance of an <idbag> is much better than a regular <bag>! Hibernate can locate individual rows efficiently and update or delete them individually, just like a list, map or set. In the current implementation, the native identifier generation strategy is not supported for <idbag> collection identifiers. The previous sections are pretty confusing. So lets look at an example. This class: has a collection of Child instances. If each child has at most one parent, the most natural mapping is a one-to-many association: ]]> This maps to the following table definitions: If the parent is required, use a bidirectional one-to-many association: ]]> Notice the NOT NULL constraint: Alternatively, if you absolutely insist that this association should be unidirectional, you can declare the NOT NULL constraint on the <key> mapping: ]]> On the other hand, if a child might have multiple parents, a many-to-many association is appropriate: ]]> Table definitions: For more examples and a complete walk-through a parent/child relationship mapping, see . Even more exotic association mappings are possible, we will catalog all possibilities in the next chapter.