HHH-18843 remove deprecated @OrderBy

documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc

@@ -156,7 +156,7 @@ after the collection is loaded, the collection would need to be refreshed to re-
 the elements.  For this reason, ordered sets are not recommended - if the application
 needs ordering of the set elements, a sorted set should be preferred.  For this reason,
 it is not covered in the User Guide.  See the javadocs for `jakarta.persistence.OrderBy`
-or `org.hibernate.annotations.OrderBy` for details.
+or `org.hibernate.annotations.SQLOrder` for details.
 
 There are 2 options for sorting a set - naturally or using an explicit comparator.
 

hibernate-core/src/main/java/org/hibernate/annotations/DialectOverride.java

@@ -90,33 +90,6 @@ public interface DialectOverride {
 		Check[] value();
 	}
 
-	/**
-	 * Specializes an {@link org.hibernate.annotations.OrderBy}
-	 * in a certain dialect.
-	 *
-	 * @deprecated Use {@link SQLOrder}
-	 */
-	@Target({METHOD, FIELD})
-	@Retention(RUNTIME)
-	@Repeatable(OrderBys.class)
-	@OverridesAnnotation(org.hibernate.annotations.OrderBy.class)
-	@Deprecated(since = "6.3", forRemoval = true)
-	@interface OrderBy {
-		/**
-		 * The {@link Dialect} in which this override applies.
-		 */
-		Class<? extends Dialect> dialect();
-		Version before() default @Version(major = MAX_VALUE);
-		Version sameOrAfter() default @Version(major = MIN_VALUE);
-
-		org.hibernate.annotations.OrderBy override();
-	}
-	@Target({METHOD, FIELD})
-	@Retention(RUNTIME)
-	@interface OrderBys {
-		OrderBy[] value();
-	}
-
 	/**
 	 * Specializes an {@link org.hibernate.annotations.SQLOrder}
 	 * in a certain dialect.

hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java

@@ -1,65 +0,0 @@
-/*
- * SPDX-License-Identifier: LGPL-2.1-or-later
- * Copyright Red Hat Inc. and Hibernate Authors
- */
-package org.hibernate.annotations;
-
-import java.lang.annotation.Retention;
-import java.lang.annotation.Target;
-
-import static java.lang.annotation.ElementType.FIELD;
-import static java.lang.annotation.ElementType.METHOD;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
-/**
- * Order a collection using an expression written in native SQL.
- * <p>
- * The order is applied by the database when the collection is fetched,
- * but is not maintained by operations that mutate the collection in
- * memory.
- * <p>
- * If the collection is a {@link java.util.Set} or {@link java.util.Map},
- * the order is maintained using a {@link java.util.LinkedHashSet} or
- * {@link java.util.LinkedHashMap}. If the collection is a bag or
- * {@link java.util.List}, the order is maintained by the underlying
- * {@link java.util.ArrayList}.
- * <p>
- * There are several other ways to order or sort a collection:
- * <ul>
- * <li>Use the JPA-defined {@link jakarta.persistence.OrderBy} annotation
- *     to order using an expression written in HQL/JPQL. Since HQL is more
- *     portable between databases, this is the preferred alternative most
- *     of the time.
- * <li>Use {@link SortComparator} to sort the collection in memory using
- *     a {@link java.util.Comparator}, or {@link SortNatural} to sort the
- *     collection in memory according to its {@linkplain java.util.Comparator
- *     natural order}.
- * <li>Use {@link jakarta.persistence.OrderColumn} to maintain the order
- *     of a {@link java.util.List} with a dedicated index column.
- * </ul>
- * <p>
- * It's illegal to use {@code OrderBy} together with the JPA-defined
- * {@link jakarta.persistence.OrderBy} for the same collection.
- *
- * @see jakarta.persistence.OrderBy
- * @see SortComparator
- * @see SortNatural
- *
- * @author Emmanuel Bernard
- * @author Steve Ebersole
- *
- * @see DialectOverride.OrderBy
- *
- * @deprecated Use {@link SQLOrder} instead. This annotation will be
- *             removed eventually, since its unqualified name collides
- *             with {@link jakarta.persistence.OrderBy}.
- */
-@Target({METHOD, FIELD})
-@Retention(RUNTIME)
-@Deprecated(since = "6.3", forRemoval = true)
-public @interface OrderBy {
-	/**
-	 * The native SQL expression used to sort the collection elements.
-	 */
-	String clause();
-}

hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java

@@ -237,7 +237,6 @@ public abstract class CollectionBinder {
 	private boolean hibernateExtensionMapping;
 
 	private jakarta.persistence.OrderBy jpaOrderBy;
-	private org.hibernate.annotations.OrderBy sqlOrderBy;
 	private SQLOrder sqlOrder;
 	private SortNatural naturalSort;
 	private SortComparator comparatorSort;
@@ -287,7 +286,6 @@ public abstract class CollectionBinder {
 		collectionBinder.setMapKey( property.getAnnotationUsage( MapKey.class, sourceModelContext ) );
 		collectionBinder.setPropertyName( inferredData.getPropertyName() );
 		collectionBinder.setJpaOrderBy( property.getAnnotationUsage( OrderBy.class, sourceModelContext ) );
-		collectionBinder.setSqlOrderBy( getOverridableAnnotation( property, org.hibernate.annotations.OrderBy.class, context ) );
 		collectionBinder.setSqlOrder( getOverridableAnnotation( property, SQLOrder.class, context ) );
 		collectionBinder.setNaturalSort( property.getAnnotationUsage( SortNatural.class, sourceModelContext ) );
 		collectionBinder.setComparatorSort( property.getAnnotationUsage( SortComparator.class, sourceModelContext ) );
@@ -841,11 +839,6 @@ public abstract class CollectionBinder {
 		this.jpaOrderBy = jpaOrderBy;
 	}
 
-	@SuppressWarnings("removal")
-	public void setSqlOrderBy(org.hibernate.annotations.OrderBy sqlOrderBy) {
-		this.sqlOrderBy = sqlOrderBy;
-	}
-
 	public void setSqlOrder(SQLOrder sqlOrder) {
 		this.sqlOrder = sqlOrder;
 	}
@@ -1095,7 +1088,7 @@ public abstract class CollectionBinder {
 			}
 
 			if ( property.hasDirectAnnotationUsage( jakarta.persistence.OrderBy.class )
-					|| property.hasDirectAnnotationUsage( org.hibernate.annotations.OrderBy.class ) ) {
+					|| property.hasDirectAnnotationUsage( org.hibernate.annotations.SQLOrder.class ) ) {
 				return CollectionClassification.BAG;
 			}
 
@@ -1443,15 +1436,12 @@ public abstract class CollectionBinder {
 			comparatorClass = null;
 		}
 
-		if ( jpaOrderBy != null && ( sqlOrderBy != null || sqlOrder != null ) ) {
+		if ( jpaOrderBy != null && sqlOrder != null ) {
 			throw buildIllegalOrderCombination();
 		}
-		boolean ordered = jpaOrderBy != null || sqlOrderBy != null || sqlOrder != null ;
+		final boolean ordered = jpaOrderBy != null || sqlOrder != null ;
 		if ( ordered ) {
 			// we can only apply the sql-based order by up front.  The jpa order by has to wait for second pass
-			if ( sqlOrderBy != null ) {
-				collection.setOrderBy( sqlOrderBy.clause() );
-			}
 			if ( sqlOrder != null ) {
 				collection.setOrderBy( sqlOrder.value() );
 			}
@@ -1490,7 +1480,7 @@ public abstract class CollectionBinder {
 						"Collection '%s' is annotated both '@%s' and '@%s'",
 						safeCollectionRole(),
 						jakarta.persistence.OrderBy.class.getName(),
-						org.hibernate.annotations.OrderBy.class.getName()
+						org.hibernate.annotations.SQLOrder.class.getName()
 				)
 		);
 	}
@@ -1502,7 +1492,7 @@ public abstract class CollectionBinder {
 						"Collection '%s' is both sorted and ordered (only one of '@%s', '@%s', '@%s', and '@%s' may be used)",
 						safeCollectionRole(),
 						jakarta.persistence.OrderBy.class.getName(),
-						org.hibernate.annotations.OrderBy.class.getName(),
+						org.hibernate.annotations.SQLOrder.class.getName(),
 						SortComparator.class.getName(),
 						SortNatural.class.getName()
 				)

hibernate-core/src/main/java/org/hibernate/boot/model/internal/ListBinder.java

@@ -7,9 +7,7 @@ package org.hibernate.boot.model.internal;
 import java.util.Map;
 import java.util.function.Supplier;
 
-import org.hibernate.AnnotationException;
 import org.hibernate.MappingException;
-import org.hibernate.annotations.OrderBy;
 import org.hibernate.boot.spi.MetadataBuildingContext;
 import org.hibernate.boot.spi.SecondPass;
 import org.hibernate.mapping.Collection;
@@ -47,13 +45,6 @@ public class ListBinder extends CollectionBinder {
 		return new List( getCustomTypeBeanResolver(), owner, getBuildingContext() );
 	}
 
-	@Override
-	public void setSqlOrderBy(OrderBy orderByAnn) {
-		if ( orderByAnn != null ) {
-			throw new AnnotationException( "A collection of type 'List' is annotated '@OrderBy'" );
-		}
-	}
-
 	@Override
 	public SecondPass getSecondPass() {
 		return new CollectionSecondPass( ListBinder.this.collection ) {

hibernate-core/src/main/java/org/hibernate/boot/model/internal/SetBinder.java

@@ -6,7 +6,6 @@ package org.hibernate.boot.model.internal;
 
 import java.util.function.Supplier;
 
-import org.hibernate.annotations.OrderBy;
 import org.hibernate.boot.spi.MetadataBuildingContext;
 import org.hibernate.mapping.Collection;
 import org.hibernate.mapping.PersistentClass;
@@ -34,10 +33,4 @@ public class SetBinder extends CollectionBinder {
 		return new Set( getCustomTypeBeanResolver(), persistentClass, getBuildingContext() );
 	}
 
-	@Override
-	public void setSqlOrderBy(OrderBy orderByAnn) {
-		if ( orderByAnn != null ) {
-			super.setSqlOrderBy( orderByAnn );
-		}
-	}
 }

hibernate-core/src/main/java/org/hibernate/boot/models/DialectOverrideAnnotations.java

@@ -27,8 +27,6 @@ import org.hibernate.boot.models.annotations.internal.OverriddenGeneratedColumnA
 import org.hibernate.boot.models.annotations.internal.OverriddenGeneratedColumnsAnnotation;
 import org.hibernate.boot.models.annotations.internal.OverriddenJoinFormulaAnnotation;
 import org.hibernate.boot.models.annotations.internal.OverriddenJoinFormulasAnnotation;
-import org.hibernate.boot.models.annotations.internal.OverriddenOrderByAnnotation;
-import org.hibernate.boot.models.annotations.internal.OverriddenOrderBysAnnotation;
 import org.hibernate.boot.models.annotations.internal.OverriddenSQLDeleteAllAnnotation;
 import org.hibernate.boot.models.annotations.internal.OverriddenSQLDeleteAllsAnnotation;
 import org.hibernate.boot.models.annotations.internal.OverriddenSQLDeleteAnnotation;
@@ -61,15 +59,6 @@ public interface DialectOverrideAnnotations {
 			OverriddenCheckAnnotation.class,
 			DIALECT_OVERRIDE_CHECKS
 	);
-	OrmAnnotationDescriptor<DialectOverride.OrderBys, OverriddenOrderBysAnnotation> DIALECT_OVERRIDE_ORDER_BYS = new OrmAnnotationDescriptor<>(
-			DialectOverride.OrderBys.class,
-			OverriddenOrderBysAnnotation.class
-	);
-	OrmAnnotationDescriptor<DialectOverride.OrderBy, OverriddenOrderByAnnotation> DIALECT_OVERRIDE_ORDER_BY = new OrmAnnotationDescriptor<>(
-			DialectOverride.OrderBy.class,
-			OverriddenOrderByAnnotation.class,
-			DIALECT_OVERRIDE_ORDER_BYS
-	);
 	OrmAnnotationDescriptor<DialectOverride.ColumnDefaults, OverriddenColumnDefaultsAnnotation> DIALECT_OVERRIDE_COLUMN_DEFAULTS = new OrmAnnotationDescriptor<>(
 			DialectOverride.ColumnDefaults.class,
 			OverriddenColumnDefaultsAnnotation.class

hibernate-core/src/main/java/org/hibernate/boot/models/HibernateAnnotations.java

@@ -470,10 +470,6 @@ public interface HibernateAnnotations {
 			OptimisticLocking.class,
 			OptimisticLockingAnnotation.class
 	);
-	OrmAnnotationDescriptor<OrderBy,OrderByAnnotation> ORDER_BY = new OrmAnnotationDescriptor<>(
-			OrderBy.class,
-			OrderByAnnotation.class
-	);
 	OrmAnnotationDescriptor<ParamDef,ParamDefAnnotation> PARAM_DEF = new OrmAnnotationDescriptor<>(
 			ParamDef.class,
 			ParamDefAnnotation.class

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/OrderByAnnotation.java

@@ -1,54 +0,0 @@
-/*
- * SPDX-License-Identifier: LGPL-2.1-or-later
- * Copyright Red Hat Inc. and Hibernate Authors
- */
-package org.hibernate.boot.models.annotations.internal;
-
-import java.lang.annotation.Annotation;
-import java.util.Map;
-
-import org.hibernate.annotations.OrderBy;
-import org.hibernate.models.spi.SourceModelBuildingContext;
-
-@SuppressWarnings({ "ClassExplicitlyAnnotation", "unused" })
-@jakarta.annotation.Generated("org.hibernate.orm.build.annotations.ClassGeneratorProcessor")
-public class OrderByAnnotation implements OrderBy {
-	private String clause;
-
-	/**
-	 * Used in creating dynamic annotation instances (e.g. from XML)
-	 */
-	public OrderByAnnotation(SourceModelBuildingContext modelContext) {
-		this.clause = "";
-	}
-
-	/**
-	 * Used in creating annotation instances from JDK variant
-	 */
-	public OrderByAnnotation(OrderBy annotation, SourceModelBuildingContext modelContext) {
-		clause = annotation.clause();
-	}
-
-	/**
-	 * Used in creating annotation instances from Jandex variant
-	 */
-	public OrderByAnnotation(Map<String, Object> attributeValues, SourceModelBuildingContext modelContext) {
-		clause = (String) attributeValues.get( "clause" );
-	}
-
-	@Override
-	public Class<? extends Annotation> annotationType() {
-		return OrderBy.class;
-	}
-
-	@Override
-	public String clause() {
-		return clause;
-	}
-
-	public void clause(String value) {
-		this.clause = value;
-	}
-
-
-}

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/OverriddenOrderByAnnotation.java

@@ -1,76 +0,0 @@
-/*
- * SPDX-License-Identifier: LGPL-2.1-or-later
- * Copyright Red Hat Inc. and Hibernate Authors
- */
-package org.hibernate.boot.models.annotations.internal;
-
-import java.lang.annotation.Annotation;
-import java.util.Map;
-
-import org.hibernate.annotations.DialectOverride;
-import org.hibernate.annotations.OrderBy;
-import org.hibernate.boot.models.HibernateAnnotations;
-import org.hibernate.boot.models.annotations.spi.AbstractOverrider;
-import org.hibernate.boot.models.annotations.spi.DialectOverrider;
-import org.hibernate.models.spi.AnnotationDescriptor;
-import org.hibernate.models.spi.SourceModelBuildingContext;
-
-import static org.hibernate.boot.models.DialectOverrideAnnotations.DIALECT_OVERRIDE_ORDER_BY;
-import static org.hibernate.boot.models.internal.OrmAnnotationHelper.extractJdkValue;
-
-/**
- * @author Steve Ebersole
- */
-@SuppressWarnings("ClassExplicitlyAnnotation")
-public class OverriddenOrderByAnnotation
-		extends AbstractOverrider<OrderBy>
-		implements DialectOverride.OrderBy, DialectOverrider<OrderBy> {
-	private OrderBy override;
-
-	/**
-	 * Used in creating dynamic annotation instances (e.g. from XML)
-	 */
-	public OverriddenOrderByAnnotation(SourceModelBuildingContext sourceModelContext) {
-	}
-
-	/**
-	 * Used in creating annotation instances from JDK variant
-	 */
-	public OverriddenOrderByAnnotation(
-			DialectOverride.OrderBy annotation,
-			SourceModelBuildingContext sourceModelContext) {
-		dialect( annotation.dialect() );
-		before( annotation.before() );
-		sameOrAfter( annotation.sameOrAfter() );
-		override( extractJdkValue( annotation, DIALECT_OVERRIDE_ORDER_BY, "override", sourceModelContext ) );
-	}
-
-	/**
-	 * Used in creating annotation instances from Jandex variant
-	 */
-	public OverriddenOrderByAnnotation(
-			Map<String, Object> attributeValues,
-			SourceModelBuildingContext sourceModelContext) {
-		super( attributeValues, DIALECT_OVERRIDE_ORDER_BY, sourceModelContext );
-		override( (OrderBy) attributeValues.get( "override" ) );
-	}
-
-	@Override
-	public AnnotationDescriptor<OrderBy> getOverriddenDescriptor() {
-		return HibernateAnnotations.ORDER_BY;
-	}
-
-	@Override
-	public OrderBy override() {
-		return override;
-	}
-
-	public void override(OrderBy value) {
-		this.override = value;
-	}
-
-	@Override
-	public Class<? extends Annotation> annotationType() {
-		return DialectOverride.OrderBy.class;
-	}
-}

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/OverriddenOrderBysAnnotation.java

@@ -1,59 +0,0 @@
-/*
- * SPDX-License-Identifier: LGPL-2.1-or-later
- * Copyright Red Hat Inc. and Hibernate Authors
- */
-package org.hibernate.boot.models.annotations.internal;
-
-import java.lang.annotation.Annotation;
-import java.util.Map;
-
-import org.hibernate.annotations.DialectOverride;
-import org.hibernate.boot.models.annotations.spi.RepeatableContainer;
-import org.hibernate.models.spi.SourceModelBuildingContext;
-
-import static org.hibernate.boot.models.DialectOverrideAnnotations.DIALECT_OVERRIDE_ORDER_BYS;
-import static org.hibernate.boot.models.internal.OrmAnnotationHelper.extractJdkValue;
-
-/**
- * @author Steve Ebersole
- */
-@SuppressWarnings("ClassExplicitlyAnnotation")
-public class OverriddenOrderBysAnnotation
-		implements DialectOverride.OrderBys, RepeatableContainer<DialectOverride.OrderBy> {
-	private DialectOverride.OrderBy[] value;
-
-	/**
-	 * Used in creating dynamic annotation instances (e.g. from XML)
-	 */
-	public OverriddenOrderBysAnnotation(SourceModelBuildingContext modelContext) {
-	}
-
-	/**
-	 * Used in creating annotation instances from JDK variant
-	 */
-	public OverriddenOrderBysAnnotation(DialectOverride.OrderBys annotation, SourceModelBuildingContext modelContext) {
-		this.value = extractJdkValue( annotation, DIALECT_OVERRIDE_ORDER_BYS, "value", modelContext );
-	}
-
-	/**
-	 * Used in creating annotation instances from Jandex variant
-	 */
-	public OverriddenOrderBysAnnotation(Map<String, Object> attributeValues, SourceModelBuildingContext modelContext) {
-		this.value = (DialectOverride.OrderBy[]) attributeValues.get( "value" );
-	}
-
-	@Override
-	public DialectOverride.OrderBy[] value() {
-		return value;
-	}
-
-	@Override
-	public void value(DialectOverride.OrderBy[] value) {
-		this.value = value;
-	}
-
-	@Override
-	public Class<? extends Annotation> annotationType() {
-		return DialectOverride.OrderBys.class;
-	}
-}

hibernate-core/src/main/java/org/hibernate/metamodel/CollectionClassification.java

@@ -67,7 +67,7 @@ public enum CollectionClassification {
 	 * as {@link java.util.Set}.
 	 *
 	 * @see jakarta.persistence.OrderBy
-	 * @see org.hibernate.annotations.OrderBy
+	 * @see org.hibernate.annotations.SQLOrder
 	 */
 	ORDERED_SET( PluralAttribute.CollectionType.SET, false ),
 
@@ -93,7 +93,7 @@ public enum CollectionClassification {
 	 * as {@link java.util.Map}.
 	 *
 	 * @see jakarta.persistence.OrderBy
-	 * @see org.hibernate.annotations.OrderBy
+	 * @see org.hibernate.annotations.SQLOrder
 	 */
 	ORDERED_MAP( PluralAttribute.CollectionType.MAP, true );
 

hibernate-core/src/main/java/org/hibernate/metamodel/mapping/ordering/OrderByFragmentTranslator.java

@@ -24,8 +24,8 @@ import org.antlr.v4.runtime.misc.ParseCancellationException;
  * with an order set or map.
  *
  * @author Steve Ebersole
+ *
  * @see jakarta.persistence.OrderBy
- * @see org.hibernate.annotations.OrderBy
  */
 public class OrderByFragmentTranslator {
 	private static final Logger LOG = Logger.getLogger( OrderByFragmentTranslator.class.getName() );

hibernate-core/src/main/java/org/hibernate/metamodel/mapping/ordering/package-info.java

@@ -9,6 +9,6 @@
  * Support for set and map ordering
  *
  * @see jakarta.persistence.OrderBy
- * @see org.hibernate.annotations.OrderBy
+ * @see org.hibernate.annotations.SQLOrder
  */
 package org.hibernate.metamodel.mapping.ordering;

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/collections/SortNaturalByDefaultTests.java

@@ -34,7 +34,6 @@ import static org.hamcrest.MatcherAssert.assertThat;
  * <ul>
  *     <li>{@link org.hibernate.annotations.SortNatural @SortNatural}</li>
  *     <li>{@link org.hibernate.annotations.SortComparator @SortComparator}</li>
- *     <li>{@link org.hibernate.annotations.OrderBy @OrderBy(from hibernate)}</li>
  *     <li>{@link jakarta.persistence.OrderBy @OrderBy(from JPA)}</li>
  * </ul>
  *

migration-guide.adoc

@@ -429,15 +429,15 @@ In Hibernate 7, these SQL `UPDATE` statements only occur if the `@OrderColumn` i
 ** Removed `@SelectBeforeUpdate`
 ** Removed `@DynamicInsert#value` and `@DynamicUpdate#value`
 ** Removed `@Loader`
-** Removed `@Table`
+** Removed `@Table` -> use JPA `@Table`
-** Removed `@Where` and `@WhereJoinTable`
+** Removed `@Where` and `@WhereJoinTable` -> use `@SQLRestriction` or `@SQLJoinTableRestriction`
-** Removed `@ForeignKey`
+** Removed `@OrderBy` -> use `@SQLOrder` or JPA `@OrderBy`
-** Removed `@Index`
+** Removed `@ForeignKey` -> use JPA `@ForeignKey`
-** Removed `@IndexColumn`
+** Removed `@Index` -> use JPA `@Index`
+** Removed `@IndexColumn` -> use JPA `@OrderColumn`
 ** Removed `@GeneratorType` (and `GenerationTime`, etc)
 ** Removed `@LazyToOne`
 ** Removed `@LazyCollection`
-** Removed `@IndexColumn`
 ** Replaced uses of `CacheModeType` with `CacheMode`
 ** Removed `@TestForIssue` (for testing purposes) -> use `org.hibernate.testing.orm.junit.JiraKey` and `org.hibernate.testing.orm.junit.JiraKeyGroup`