Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc
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. Contrary to natural expectations, the ordering of a list is by default not maintained.
This column can be configured via the `jakarta.persistence.OrderColumn` annotation. To maintain the order, it is necessary to explicitly use the `jakarta.persistence.OrderColumn` annotation.
[[NOTE]] [[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 The default column name that stores the index is derived from the attribute name, by suffixing `_ORDER`.
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 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]] [[collection-list-ordercolumn-ex]]
.@OrderColumn .@OrderColumn
==== ====

2
hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataBuilderImpl.java
View File

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

8
hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java
View File

@ -812,19 +812,13 @@ public interface AvailableSettings {
* Hibernate detects a plural attribute typed as {@link java.util.List} with no explicit * Hibernate detects a plural attribute typed as {@link java.util.List} with no explicit
* list index configuration. * list index configuration.
* <p/> * <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: * Accepts any of:
* <ul> * <ul>
* <li>an instance of {@code CollectionClassification} * <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} * <li>a {@link Class} representing either {@link java.util.List} or {@link java.util.Collection}
* </ul> * </ul>
* <p/> * <p/>
* Backwards compatibility can be achieved by specifying `hibernate.mapping.default_list_semantics=bag` e.g.
* *
* @since 6.0 * @since 6.0
*/ */

3
hibernate-envers/src/test/resources/hibernate.properties
View File

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

36
migration-guide.adoc
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 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` 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 === Misc
* The default type for `Duration` was changed to `NUMERIC` which could lead to schema validation errors * The default type for `Duration` was changed to `NUMERIC` which could lead to schema validation errors