list v. bag - javadoc, migration guide

hibernate-core/src/main/java/org/hibernate/boot/SessionFactoryBuilder.java

@@ -640,7 +640,10 @@ public interface SessionFactoryBuilder {
 
 	/**
 	 * @see JpaCompliance#isJpaListComplianceEnabled()
+	 *
+	 * @deprecated Use {@link org.hibernate.cfg.AvailableSettings#DEFAULT_LIST_SEMANTICS} instead
 	 */
+	@Deprecated( since = "6.0" )
 	SessionFactoryBuilder enableJpaListCompliance(boolean enabled);
 
 	/**

hibernate-core/src/main/java/org/hibernate/cfg/AvailableSettings.java

@@ -785,20 +785,19 @@ public interface AvailableSettings {
 	 * list index configuration.
 	 * <p/>
 	 * Historically Hibernate interpreted this using
-	 * {@link org.hibernate.metamodel.CollectionClassification#BAG} semantics. The JPA-compliant
-	 * default is to consider it a {@link org.hibernate.metamodel.CollectionClassification#LIST}.
+	 * {@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}, or
-	 *     <li>a {@link Class} representing either {@link java.util.List} or {@link java.util.Collection}.
+	 *     <li>an instance of {@code CollectionClassification}
+	 *     <li>the (case insensitive) name of a {@code CollectionClassification} (bag 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.
 	 *
-	 * @see org.hibernate.jpa.spi.JpaCompliance#isJpaListComplianceEnabled()
-	 *
 	 * @since 6.0
 	 */
 	String DEFAULT_LIST_SEMANTICS = "hibernate.mapping.default_list_semantics";
@@ -2147,7 +2146,13 @@ public interface AvailableSettings {
 	 * @see org.hibernate.jpa.spi.JpaCompliance#isJpaListComplianceEnabled()
 	 *
 	 * @since 5.3
+	 *
+	 * @deprecated Use {@link org.hibernate.cfg.AvailableSettings#DEFAULT_LIST_SEMANTICS} instead.
+	 * The specification is actually undefined in terms of how this should be handled.  It actually
+	 * says that portable applications should not rely on a specific behavior in terms of a List
+	 * with no `@OrderColumn`
 	 */
+	@Deprecated( since = "6.0" )
 	String JPA_LIST_COMPLIANCE	= "hibernate.jpa.compliance.list";
 
 	/**

hibernate-core/src/main/java/org/hibernate/jpa/spi/JpaCompliance.java

@@ -7,6 +7,7 @@
 package org.hibernate.jpa.spi;
 
 import org.hibernate.Transaction;
+import org.hibernate.cfg.AvailableSettings;
 
 /**
  * Encapsulates settings controlling whether Hibernate complies strictly
@@ -56,7 +57,10 @@ public interface JpaCompliance {
 	 * interpreting the mapping as a "list", rather than a "bag"
 	 *
 	 * @see org.hibernate.cfg.AvailableSettings#JPA_LIST_COMPLIANCE
+	 *
+	 * @deprecated Use {@link org.hibernate.cfg.AvailableSettings#DEFAULT_LIST_SEMANTICS} instead
 	 */
+	@Deprecated( since = "6.0" )
 	boolean isJpaListComplianceEnabled();
 
 	/**

hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/Jpa.java

@@ -80,6 +80,7 @@ public @interface Jpa {
 
 	/**
 	 * @see JpaCompliance#isJpaListComplianceEnabled()
+	 * @see org.hibernate.cfg.AvailableSettings#DEFAULT_LIST_SEMANTICS
 	 */
 	boolean listMappingComplianceEnabled() default false;
 

migration-guide.adoc

@@ -235,6 +235,41 @@ See https://docs.jboss.org/hibernate/orm/6.0/userguide/html_single/Hibernate_Use
 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