HHH-19364 call mutation of the specification "Augmentation"

Author: gavinking

hibernate-core/src/main/java/org/hibernate/query/programmatic/MutationSpecification.java

@@ -45,12 +45,24 @@ public interface MutationSpecification<T> extends QuerySpecification<T> {
 	@Override
 	MutationSpecification<T> addRestriction(Restriction<T> restriction);
 
+	/**
+	 * A function capable of modifying or augmenting a criteria query.
+	 *
+	 * @param <T> The target entity type
+	 */
 	@FunctionalInterface
-	interface Mutator<T> {
-		void mutate(CriteriaBuilder builder, CommonAbstractCriteria query, Root<T> mutationTarget);
+	interface Augmentation<T> {
+		void augment(CriteriaBuilder builder, CommonAbstractCriteria query, Root<T> mutationTarget);
 	}
 
-	MutationSpecification<T> mutate(Mutator<T> mutation);
+	/**
+	 * Add an {@linkplain Augmentation augmentation} to the specification.
+	 *
+	 * @param augmentation A function capable of modifying or augmenting a criteria query.
+	 *
+	 * @return {@code this} for method chaining.
+	 */
+	MutationSpecification<T> addAugmentation(Augmentation<T> augmentation);
 
 	/**
 	 * Finalize the building and create the {@linkplain SelectionQuery} instance.

hibernate-core/src/main/java/org/hibernate/query/programmatic/SelectionSpecification.java

@@ -101,12 +101,24 @@ public interface SelectionSpecification<T> extends QuerySpecification<T> {
 	 */
 	SelectionSpecification<T> addFetching(Path<T,?> fetchPath);
 
+	/**
+	 * A function capable of modifying or augmenting a criteria query.
+	 *
+	 * @param <T> The root entity type
+	 */
 	@FunctionalInterface
-	interface Mutator<T> {
-		void mutate(CriteriaBuilder builder, CriteriaQuery<T> query, Root<T> root);
+	interface Augmentation<T> {
+		void augment(CriteriaBuilder builder, CriteriaQuery<T> query, Root<T> root);
 	}
 
-	SelectionSpecification<T> mutate(Mutator<T> mutation);
+	/**
+	 * Add an {@linkplain Augmentation augmentation} to the specification.
+	 *
+	 * @param augmentation A function capable of modifying or augmenting a criteria query.
+	 *
+	 * @return {@code this} for method chaining.
+	 */
+	SelectionSpecification<T> addAugmentation(Augmentation<T> augmentation);
 
 	/**
 	 * Covariant override.

hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/MutationSpecificationImpl.java

@@ -74,9 +74,9 @@ public MutationSpecification<T> addRestriction(Restriction<T> restriction) {
 	}
 
 	@Override
-	public MutationSpecification<T> mutate(Mutator<T> mutation) {
+	public MutationSpecification<T> addAugmentation(Augmentation<T> augmentation) {
 		specifications.add( (sqmStatement, mutationTargetRoot) ->
-				mutation.mutate( sqmStatement.nodeBuilder(), sqmStatement, mutationTargetRoot ) );
+				augmentation.augment( sqmStatement.nodeBuilder(), sqmStatement, mutationTargetRoot ) );
 		return this;
 	}
 

hibernate-core/src/main/java/org/hibernate/query/programmatic/internal/SelectionSpecificationImpl.java

@@ -73,9 +73,9 @@ public SelectionSpecification<T> addRestriction(Restriction<T> restriction) {
 	}
 
 	@Override
-	public SelectionSpecification<T> mutate(Mutator<T> mutation) {
+	public SelectionSpecification<T> addAugmentation(Augmentation<T> augmentation) {
 		specifications.add( (sqmStatement, root) ->
-				mutation.mutate( sqmStatement.nodeBuilder(), sqmStatement, root ) );
+				augmentation.augment( sqmStatement.nodeBuilder(), sqmStatement, root ) );
 		return this;
 	}
 

hibernate-core/src/test/java/org/hibernate/orm/test/query/dynamic/SimpleQuerySpecificationTests.java

@@ -201,7 +201,7 @@ void testCriteriaFormWithMutation(SessionFactoryScope factoryScope) {
 		factoryScope.inTransaction( (session) -> {
 			sqlCollector.clear();
 			SelectionSpecification.create( BasicEntity.class )
-					.mutate( (builder, query, entity) -> query.where( builder.like( entity.get( BasicEntity_.name ), "%" ) ) )
+					.addAugmentation( (builder, query, entity) -> query.where( builder.like( entity.get( BasicEntity_.name ), "%" ) ) )
 					.addOrdering( Order.asc( BasicEntity_.position ) )
 					.createQuery( session )
 					.getResultList();