Switch back to bag by default for list semantics

This commit is contained in:
Christian Beikov 2022-02-02 18:05:09 +01:00
parent 4f7d4b7fdb
commit 7aaeebe3af
5 changed files with 10 additions and 57 deletions

View File

@ -84,22 +84,18 @@ include::{classificationTestsDir}/list/EntityWithList.java[tags=collections-list
----
====
The ordering of a list is maintained as a column in the database to hold the element's index.
This column can be configured via the `jakarta.persistence.OrderColumn` annotation.
Contrary to natural expectations, the ordering of a list is by default not maintained.
To maintain the order, it is necessary to explicitly use the `jakarta.persistence.OrderColumn` annotation.
[[NOTE]]
====
Historically, Hibernate interpreted a `List` attribute without `@OrderColumn` as a BAG.
Starting in 6.0, Hibernate allows to configure the default semantics of `List` without `@OrderColumn`
via the `hibernate.mapping.default_list_semantics` setting.
To switch to the more natural LIST semantics with an implicit order-column, set the setting to `LIST`.
Starting in 6.0, however, Hibernate has moved to the more natural choice to map such
Lists using LIST semantics with an implicit order-column. For applications needing backwards
compatibility, Hibernate has added the `hibernate.mapping.default_list_semantics` setting. To
achieve the legacy behavior, set `hibernate.mapping.default_list_semantics=bag`
The default column name that stores the index is derived from the attribute name, by suffixing `_ORDER`.
====
The mapping above would store the index in a column named `names_ORDER`, per the default
for `jakarta.persistence.OrderColumn#name`. We can also explicitly name the column to use; e.g.
[[collection-list-ordercolumn-ex]]
.@OrderColumn
====

View File

@ -478,7 +478,7 @@ public class MetadataBuilderImpl implements MetadataBuilderImplementor, TypeCont
}
return classification;
},
CollectionClassification.LIST
CollectionClassification.BAG
);
}

View File

@ -812,19 +812,13 @@ public interface AvailableSettings {
* Hibernate detects a plural attribute typed as {@link java.util.List} with no explicit
* list index configuration.
* <p/>
* Historically Hibernate interpreted this using
* {@linkplain org.hibernate.metamodel.CollectionClassification#BAG BAG} semantics.
* Starting in 6.0, Hibernate now interprets this situation using
* {@linkplain org.hibernate.metamodel.CollectionClassification#LIST LIST} semantics.
* <p/>
* Accepts any of:
* <ul>
* <li>an instance of {@code CollectionClassification}
* <li>the (case insensitive) name of a {@code CollectionClassification} (bag e.g.)
* <li>the (case insensitive) name of a {@code CollectionClassification} (list e.g.)
* <li>a {@link Class} representing either {@link java.util.List} or {@link java.util.Collection}
* </ul>
* <p/>
* Backwards compatibility can be achieved by specifying `hibernate.mapping.default_list_semantics=bag` e.g.
*
* @since 6.0
*/

View File

@ -21,6 +21,5 @@ hibernate.cache.region_prefix hibernate.test
hibernate.cache.region.factory_class org.hibernate.testing.cache.CachingRegionFactory
hibernate.service.allow_crawling=false
## backwards compatibility wrt bag v. list for "implicit" List mappings
hibernate.mapping.default_list_semantics=bag
## make sure we use bag semantics for "implicit" List mappings
hibernate.mapping.default_list_semantics=bag

View File

@ -260,42 +260,6 @@ plural attribute classification
See https://docs.jboss.org/hibernate/orm/6.0/userguide/html_single/Hibernate_User_Guide.html#collection-type-reg-ann
for details of using `@CollectionTypeRegistration`
[[collection-list-as-bag]]
==== List as BAG
Historically, Hibernate treated `List` attributes with no explicit ordering details using its
BAG semantics.
```
@ElementCollection
List<String> names;
```
This is not the most natural decision and is rooted in the original annotation
support being too closely related to the `hbm.xml` mapping format.
Starting in 6.0, Hibernate now makes the more natural interpretation of such a mapping using its
LIST semantics. It treats the above example with an implicit an `@OrderColumn`. The above mapping
is now equivalent to
```
@ElementCollection
@OrderColumn(...)
List<String> names;
```
A new "compatibility flag" has been added to allow continuing with the legacy behavior:
```
hibernate.mapping.default_list_semantics=bag
```
The same can be achieved for specific attributes using the new `@Bag` annotation as well.
=== Misc
* The default type for `Duration` was changed to `NUMERIC` which could lead to schema validation errors