Naturally Hibernate also allows persisting collections. These persistent collections can contain almost any other Hibernate type, including basic types, custom types, embeddables, and references to other entities. In this context, the distinction between value and reference semantics is very important. An object in a collection might be handled with value semantics (its lifecycle being fully dependant 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 a state held by the collection.
The owner of the collection is always an entity, even if the collection is defined by an embeddable type. Collections form one/many-to-many associations between types so there can be:
-
value type collections
-
embeddable type collections
-
entity collections
Hibernate uses its own collection implementations which are enriched with lazy-loading, caching or state change detection semantics.
For this reason, persistent collections must be declared as an interface type.
The actual interface might be java.util.Collection, java.util.List, java.util.Set, java.util.Map, java.util.SortedSet, java.util.SortedMap or even other object types (meaning you will have to write an implementation of org.hibernate.usertype.UserCollectionType).
As the following example demonstrates, it’s important to use the interface type and not the collection implementation, as declared in the entity mapping.
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeElementCollectionTest.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeElementCollectionTest.java[role=include]|
Note
|
It is important that collections be defined using the appropriate Java Collections Framework interface rather than a specific implementation. From a theoretical perspective, this just follows good design principles. From a practical perspective, Hibernate (like other persistence providers) will use their own collection implementations which conform to the Java Collections Framework interfaces. |
The persistent collections injected by Hibernate behave like ArrayList, HashSet, TreeSet, HashMap or TreeMap, depending on the interface type.
Value and embeddable type collections have a similar behavior to basic types since 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.
|
Important
|
Two entities cannot share a reference to the same collection instance. Collection-valued properties do not support null value semantics because Hibernate does not distinguish between a null collection reference and an empty collection. |
Collections of value type include basic and embeddable types. Collections cannot be nested, and, when used in collections, embeddable types are not allowed to define other collections.
For collections of value types, JPA 2.0 defines the @ElementCollection annotation.
The lifecycle of the value-type collection is entirely controlled by its owning entity.
Considering the previous example mapping, when clearing the phone collection, Hibernate deletes all the associated phones. When adding a new element to the value type collection, Hibernate issues a new insert statement.
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeElementCollectionTest.java[role=include]link:extras/collections/collections-value-type-collection-lifecycle-example.sql[role=include]If removing all elements or adding new ones is rather straightforward, removing a certain entry actually requires reconstructing the whole collection from scratch.
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeElementCollectionTest.java[role=include]link:extras/collections/collections-value-type-collection-remove-example.sql[role=include]Depending on the number of elements, this behavior might not be efficient, if many elements need to be deleted and reinserted back into the database table.
A workaround is to use an @OrderColumn, which, although not as efficient as when using the actual link table primary key, might improve the efficiency of the remove operations.
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeOrderColumnElementCollectionTest.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeOrderColumnElementCollectionTest.java[role=include]link:extras/collections/collections-value-type-collection-order-column-remove-example.sql[role=include]|
Note
|
The |
Embeddable type collections behave the same way as value type collections. Adding embeddables to the collection triggers the associated insert statements and removing elements from the collection will generate delete statements.
link:../../../../../test/java/org/hibernate/userguide/collections/EmbeddableTypeElementCollectionTest.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/EmbeddableTypeElementCollectionTest.java[role=include]link:extras/collections/collections-embeddable-type-collection-lifecycle-example.sql[role=include]If value type collections can only form a one-to-many association between an owner entity and multiple basic or embeddable types, entity collections can represent both @OneToMany and @ManyToMany associations.
From a relational database perspective, associations are defined by the foreign key side (the child-side). With value type collections, only the entity can control the association (the parent-side), but for a collection of entities, both sides of the association are managed by the persistence context.
For this reason, entity collections can be devised into two main categories: unidirectional and bidirectional associations. Unidirectional associations are very similar to value type collections since only the parent side controls this relationship. Bidirectional associations are more tricky since, even if sides need to be in-sync at all times, only one side is responsible for managing the association. A bidirectional association has an owning side and an inverse (mappedBy) side.
Another way of categorizing entity collections is by the underlying collection type, and so we can have:
-
bags
-
indexed lists
-
sets
-
sorted sets
-
maps
-
sorted maps
-
arrays
In the following sections, we will go through all these collection types and discuss both unidirectional and bidirectional associations.
Bags are unordered lists, and we can have unidirectional bags or bidirectional ones.
The unidirectional bag is mapped using a single @OneToMany annotation on the parent side of the association.
Behind the scenes, Hibernate requires an association table to manage the parent-child relationship, as we can see in the following example:
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalBagTest.java[role=include]link:extras/collections/collections-unidirectional-bag-example.sql[role=include]|
Note
|
Because both the parent and the child sides are entities, the persistence context manages each entity separately. The cascading mechanism allows you to propagate an entity state transition from a parent entity to its children. |
By marking the parent side with the CascadeType.ALL attribute, the unidirectional association lifecycle becomes very similar to that of a value type collection.
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalBagTest.java[role=include]link:extras/collections/collections-unidirectional-bag-lifecycle-example.sql[role=include]In the example above, once the parent entity is persisted, the child entities are going to be persisted as well.
|
Note
|
Just like value type collections, unidirectional bags are not as efficient when it comes to modifying the collection structure (removing or reshuffling elements). Because the parent-side cannot uniquely identify each individual child, Hibernate deletes all link table rows associated with the parent entity and re-adds the remaining ones that are found in the current collection state. |
The bidirectional bag is the most common type of entity collection.
The @ManyToOne side is the owning side of the bidirectional bag association, while the @OneToMany is the inverse side, being marked with the mappedBy attribute.
link:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalBagTest.java[role=include]link:extras/collections/collections-bidirectional-bag-example.sql[role=include]link:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalBagTest.java[role=include]link:extras/collections/collections-bidirectional-bag-lifecycle-example.sql[role=include]link:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalBagOrphanRemovalTest.java[role=include]link:extras/collections/collections-bidirectional-bag-orphan-removal-example.sql[role=include]When rerunning the previous example, the child will get removed because the parent-side propagates the removal upon dissociating the child entity reference.
Although they use the List interface on the Java side, bags don’t retain element order.
To preserve the collection element order, there are two possibilities:
@OrderBy-
the collection is ordered upon retrieval using a child entity property
@OrderColumn-
the collection uses a dedicated order column in the collection link table
When using the @OrderBy annotation, the mapping looks as follows:
@OrderBy listlink:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalOrderedByListTest.java[role=include]The database mapping is the same as with the Unidirectional bags example, so it won’t be repeated. Upon fetching the collection, Hibernate generates the following select statement:
@OrderBy list select statementlink:extras/collections/collections-unidirectional-ordered-list-order-by-select-example.sql[role=include]The child table column is used to order the list elements.
|
Note
|
The If no property is specified (e.g. |
Another ordering option is to use the @OrderColumn annotation:
@OrderColumn listlink:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalOrderColumnListTest.java[role=include]link:extras/collections/collections-unidirectional-ordered-list-order-column-example.sql[role=include]This time, the link table takes the order_id column and uses it to materialize the collection element order.
When fetching the list, the following select query is executed:
@OrderColumn list select statementlink:extras/collections/collections-unidirectional-ordered-list-order-column-select-example.sql[role=include]With the order_id column in place, Hibernate can order the list in-memory after it’s being fetched from the database.
The mapping is similar with the Bidirectional bags example, just that the parent side is going to be annotated with either @OrderBy or @OrderColumn.
@OrderBy listlink:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalOrderByListTest.java[role=include]Just like with the unidirectional @OrderBy list, the number column is used to order the statement on the SQL level.
When using the @OrderColumn annotation, the order_id column is going to be embedded in the child table:
@OrderColumn listlink:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalOrderColumnListTest.java[role=include]link:extras/collections/collections-bidirectional-ordered-list-order-column-example.sql[role=include]When fetching the collection, Hibernate will use the fetched ordered columns to sort the elements according to the @OrderColumn mapping.
You can customize the ordinal of the underlying ordered list by using the @ListIndexBase annotation.
@ListIndexBase mapping examplelink:../../../../../test/java/org/hibernate/userguide/collections/OrderColumnListIndexBaseTest.java[role=include]When inserting two Phone records, Hibernate is going to start the List index from 100 this time.
@ListIndexBase persist examplelink:../../../../../test/java/org/hibernate/userguide/collections/OrderColumnListIndexBaseTest.java[role=include]link:extras/collections/collections-customizing-ordered-list-ordinal-persist-example.sql[role=include]While the JPA
{jpaJavadocUrlPrefix}OrderBy.html[@OrderBy] annotation allows you to specify the entity attributes used for sorting
when fetching the current annotated collection, the Hibernate specific
@OrderBy annotation is used to specify a SQL clause instead.
In the following example, the @OrderBy annotation uses the CHAR_LENGTH SQL function to order the Article entities
by the number of characters of the name attribute.
@OrderBy mapping examplelink:../../../../../test/java/org/hibernate/userguide/collections/OrderedBySQLTest.java[role=include]When fetching the articles collection, Hibernate uses the ORDER BY SQL clause provided by the mapping:
@OrderBy fetching examplelink:../../../../../test/java/org/hibernate/userguide/collections/OrderedBySQLTest.java[role=include]link:extras/collections/collections-customizing-ordered-by-sql-clause-fetching-example.sql[role=include]Sets are collections that don’t allow duplicate entries and Hibernate supports both the unordered Set and the natural-ordering SortedSet.
The unidirectional set uses a link table to hold the parent-child associations and the entity mapping looks as follows:
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalSetTest.java[role=include]The unidirectional set lifecycle is similar to that of the Unidirectional bags, so it can be omitted.
The only difference is that Set doesn’t allow duplicates, but this constraint is enforced by the Java object contract rather than the database mapping.
|
Note
|
When using Sets, it’s very important to supply proper equals/hashCode implementations for child entities. In the absence of a custom equals/hashCode implementation logic, Hibernate will use the default Java reference-based object equality which might render unexpected results when mixing detached and managed object instances. |
Just like bidirectional bags, the bidirectional set doesn’t use a link table, and the child table has a foreign key referencing the parent table primary key. The lifecycle is just like with bidirectional bags except for the duplicates which are filtered out.
link:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalSetTest.java[role=include]For sorted sets, the entity mapping must use the SortedSet interface instead.
According to the SortedSet contract, all elements must implement the Comparable interface and therefore provide the sorting logic.
A SortedSet that relies on the natural sorting order given by the child element Comparable implementation logic might be annotated with the @SortNatural Hibernate annotation.
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalSortedSetTest.java[role=include]The lifecycle and the database mapping are identical to the Unidirectional bags, so they are intentionally omitted.
To provide a custom sorting logic, Hibernate also provides a @SortComparator annotation:
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalComparatorSortedSetTest.java[role=include]The @SortNatural and @SortComparator work the same for bidirectional sorted sets too:
link:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalSortedSetTest.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalComparatorSortedSetTest.java[role=include]|
Note
|
Before v6, |
A java.util.Map is a ternary association because it requires a parent entity, a map key, and a value.
An entity can either be a map key or a map value, depending on the mapping.
Hibernate allows using the following map keys:
MapKeyColumn-
for value type maps, the map key is a column in the link table that defines the grouping logic
MapKey-
the map key is either the primary key or another property of the entity stored as a map entry value
MapKeyEnumerated-
the map key is an
Enumof the target child entity MapKeyTemporal-
the map key is a
Dateor aCalendarof the target child entity MapKeyJoinColumn-
the map key is an entity mapped as an association in the child entity that’s stored as a map entry key
A map of value type must use the @ElementCollection annotation, just like value type lists, bags or sets.
link:../../../../../test/java/org/hibernate/userguide/collections/ElementCollectionMapTest.java[role=include]link:extras/collections/collections-map-value-type-entity-key-example.sql[role=include]Adding entries to the map generates the following SQL statements:
link:../../../../../test/java/org/hibernate/userguide/collections/ElementCollectionMapTest.java[role=include]link:extras/collections/collections-map-value-type-entity-key-add-example.sql[role=include]Hibernate defines the
@MapKeyType annotation
which you can use to customize the Map key type.
Considering you have the following tables in your database:
link:extras/collections/collections-map-custom-key-type-sql-example.sql[role=include]The call_register records the call history for every person.
The call_timestamp_epoch column stores the phone call timestamp as a Unix timestamp since the Unix epoch.
|
Note
|
The |
Since we want to map all the calls by their associated java.util.Date, not by their timestamp since epoch which is a number, the entity mapping looks as follows:
@MapKeyType mapping examplelink:../../../../../test/java/org/hibernate/userguide/collections/MapKeyTypeTest.java[role=include]The associated TimestampEpochType looks as follows:
link:../../../../../test/java/org/hibernate/userguide/collections/type/TimestampEpochType.java[role=include]
The TimestampEpochType allows us to map a Unix timestamp since epoch to a java.util.Date.
But, without the @MapKeyType Hibernate annotation, it would not be possible to customize the Map key type.
Considering you have the following PhoneNumber interface with an implementation given by the MobilePhone class type:
PhoneNumber interface and the MobilePhone class typelink:../../../../../test/java/org/hibernate/userguide/collections/MapKeyClassTest.java[role=include]If you want to use the PhoneNumber interface as a java.util.Map key, then you need to supply the
{jpaJavadocUrlPrefix}MapKeyClass.html[@MapKeyClass] annotation as well.
@MapKeyClass mapping examplelink:../../../../../test/java/org/hibernate/userguide/collections/MapKeyClassTest.java[role=include]link:extras/collections/collections-map-key-class-mapping-example.sql[role=include]When inserting a Person with a callRegister containing 2 MobilePhone references,
Hibernate generates the following SQL statements:
@MapKeyClass persist examplelink:../../../../../test/java/org/hibernate/userguide/collections/MapKeyClassTest.java[role=include]link:extras/collections/collections-map-key-class-persist-example.sql[role=include]When fetching a Person and accessing the callRegister Map,
Hibernate generates the following SQL statements:
@MapKeyClass fetch examplelink:../../../../../test/java/org/hibernate/userguide/collections/MapKeyClassTest.java[role=include]link:extras/collections/collections-map-key-class-fetch-example.sql[role=include]A unidirectional map exposes a parent-child association from the parent-side only.
The following example shows a unidirectional map which also uses a @MapKeyTemporal annotation.
The map key is a timestamp, and it’s taken from the child entity table.
|
Note
|
The |
link:../../../../../test/java/org/hibernate/userguide/collections/UnidirectionalMapTest.java[role=include]link:extras/collections/collections-map-unidirectional-example.sql[role=include]Like most bidirectional associations, this relationship is owned by the child-side while the parent is the inverse side and can propagate its own state transitions to the child entities.
In the following example, you can see that @MapKeyEnumerated was used so that the Phone enumeration becomes the map key.
link:../../../../../test/java/org/hibernate/userguide/collections/BidirectionalMapTest.java[role=include]link:extras/collections/collections-map-bidirectional-example.sql[role=include]When discussing arrays, it is important to understand the distinction between SQL array types and Java arrays that are mapped as part of the application’s domain model.
Not all databases implement the SQL-99 ARRAY type and, for this reason, Hibernate doesn’t support native database array types.
Hibernate does support the mapping of arrays in the Java domain model - conceptually the same as mapping a List. However, it is important to realize that it is impossible for Hibernate to offer lazy-loading for arrays of entities and, for this reason, it is strongly recommended to map a "collection" of entities using a List rather than an array.
By default, Hibernate will choose a BINARY type, as supported by the current Dialect.
link:../../../../../test/java/org/hibernate/userguide/collections/ArrayTest.java[role=include]link:extras/collections/collections-array-binary-example.sql[role=include]|
Note
|
If you want to map arrays such as Check out this article for an example of how to write such a custom Hibernate Type. |
Notice how all the previous examples explicitly mark the collection attribute as either ElementCollection, OneToMany or ManyToMany.
Collections not marked as such require a custom Hibernate Type and the collection elements must be stored in a single database column.
This is sometimes beneficial. Consider a use-case such as a VARCHAR column that represents a delimited list/set of Strings.
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeCollectionTest.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/type/CommaDelimitedStringsJavaTypeDescriptor.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/type/CommaDelimitedStringsType.java[role=include]The developer can use the comma-delimited collection like any other collection we’ve discussed so far and Hibernate will take care of the type transformation part. The collection itself behaves like any other basic value type, as its lifecycle is bound to its owner entity.
link:../../../../../test/java/org/hibernate/userguide/collections/BasicTypeCollectionTest.java[role=include]link:extras/collections/collections-comma-delimited-collection-lifecycle-example.sql[role=include]See the Hibernate Integrations Guide for more details on developing custom value type mappings.
If you wish to use other collection types than List, Set or Map, like Queue for instance,
you have to use a custom collection type, as illustrated by the following example:
link:../../../../../test/java/org/hibernate/userguide/collections/QueueTest.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/type/QueueType.java[role=include]
link:../../../../../test/java/org/hibernate/userguide/collections/type/PersistentQueue.java[role=include]|
Note
|
The reason why the
However, the custom collection type can still be customized as long as the base type is one of the aforementioned persistent types. |
This way, the Phone collection can be used as a java.util.Queue:
link:../../../../../test/java/org/hibernate/userguide/collections/QueueTest.java[role=include]