HHH-18198 -

Removed org.hibernate.annotations.Target
Created new org.hibernate.annotations.TargetEmbeddable

Signed-off-by: Jan Schatteman <[email protected]>

Author: jrenaat

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

@@ -300,52 +300,49 @@ Embeddable types that are used as collection entries, map keys or entity type id
 ====
 
 [[embeddable-Target]]
-==== `@Target` mapping
+==== `@TargetEmbeddable` mapping
 
-The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/Target.html[`@Target`] annotation is used to specify the implementation class of a given association that is mapped via an interface.
-The
-{jpaJavadocUrlPrefix}ManyToOne.html[`@ManyToOne`],
-{jpaJavadocUrlPrefix}OneToOne.html[`@OneToOne`],
-{jpaJavadocUrlPrefix}OneToMany.html[`@OneToMany`], and
-{jpaJavadocUrlPrefix}ManyToMany.html[`@ManyToMany`]
-feature a {jpaJavadocUrlPrefix}ManyToOne.html#targetEntity--[`targetEntity`] attribute to specify the actual class of the entity association when an interface is used for the mapping.
+The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/TargetEmbeddable.html[`@TargetEmbeddable`] annotation is used to specify the implementation class of an embeddable-valued mapping when the declared type is a non-concrete type (interface, etc.).
 
-The {jpaJavadocUrlPrefix}ElementCollection.html[`@ElementCollection`] association has a {jpaJavadocUrlPrefix}ElementCollection.html#targetClass--[`targetClass`] attribute for the same purpose.
+[NOTE]
+====
+An "embeddable-valued mapping" may be an `@EmbeddedId`, `@Embedded` or `@ElementCollection`.
+====
 
-However, for simple embeddable types, there is no such construct and so you need to use the Hibernate-specific `@Target` annotation instead.
+`@TargetEmbeddable` may be specified on the embeddable-valued mapping, as shown in <<embeddable-Target-example>>, or it may be defined on the interface/class used as the declared type, illustrated in <<embeddable-Target-example2>>.
 
 [[embeddable-Target-example]]
-.`@Target` mapping usage
+.Embeddable-valued mapping usage
 ====
 [source, java, indent=0]
 ----
-include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-example]
+include::{example-dir-emeddable}/TargetEmbeddableOnEmbeddedTest.java[tags=embeddable-Target-example]
 ----
 ====
 
 The `coordinates` embeddable type is mapped as the `Coordinates` interface.
 However, Hibernate needs to know the actual implementation type, which is `GPS` in this case,
-hence the `@Target` annotation is used to provide this information.
+hence the `@TargetEmbeddable` annotation is used to provide this information.
 
 Assuming we have persisted the following `City` entity:
 
 [[embeddable-Target-persist-example]]
-.`@Target` persist example
+.`@TargetEmbeddable` persist example
 ====
 [source, java, indent=0]
 ----
-include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-persist-example]
+include::{example-dir-emeddable}/TargetEmbeddableOnEmbeddedTest.java[tags=embeddable-Target-persist-example]
 ----
 ====
 
-When fetching the `City` entity, the `coordinates` property is mapped by the `@Target` expression:
+When fetching the `City` entity, the `coordinates` property is mapped by the `@TargetEmbeddable` expression:
 
 [[embeddable-Target-fetching-example]]
-.`@Target` fetching example
+.`@TargetEmbeddable` fetching example
 ====
 [source, java, indent=0]
 ----
-include::{example-dir-emeddable}/TargetTest.java[tags=embeddable-Target-fetching-example]
+include::{example-dir-emeddable}/TargetEmbeddableOnEmbeddedTest.java[tags=embeddable-Target-fetching-example]
 ----
 
 [source, SQL, indent=0]
@@ -354,7 +351,15 @@ include::{extrasdir}/embeddable/embeddable-Target-fetching-example.sql[]
 ----
 ====
 
-Therefore, the `@Target` annotation is used to define a custom join association between the parent-child association.
+[[embeddable-Target-example2]]
+.Interface mapping usage
+====
+[source, java, indent=0]
+----
+include::{example-dir-emeddable}/TargetEmbeddableOnInterfaceTest.java[tags=embeddable-Target-example2]
+----
+====
+
 
 [[embeddable-Parent]]
 ==== `@Parent` mapping

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

@@ -0,0 +1,26 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.Retention;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Specifies the target type for a {@link jakarta.persistence.Embedded} entity property.
+ * <p>
+ * It's intended to be used exclusively in conjunction with @Embedded.
+ */
+@java.lang.annotation.Target({FIELD, METHOD, TYPE})
+@Retention(RUNTIME)
+public @interface TargetEmbeddable {
+	/**
+	 * The target type for a {@link jakarta.persistence.Embedded} entity property
+	 */
+	Class<?> value();
+}

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

@@ -1101,14 +1101,6 @@ private void normalSupplementalDetails(MemberDetails attribute) {
 				}
 			}
 
-			final var targetAnn = attribute.locateAnnotationUsage( Target.class, getSourceModelContext() );
-			if ( targetAnn != null ) {
-				DEPRECATION_LOGGER.deprecatedAnnotation( Target.class, attribute.getName() );
-				return (BasicJavaType<?>)
-						typeConfiguration.getJavaTypeRegistry()
-								.getDescriptor( targetAnn.value() );
-			}
-
 			return null;
 		};
 

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

@@ -16,7 +16,7 @@
 import org.hibernate.annotations.JavaType;
 import org.hibernate.annotations.JdbcTypeCode;
 import org.hibernate.annotations.ManyToAny;
-import org.hibernate.annotations.Target;
+import org.hibernate.annotations.TargetEmbeddable;
 import org.hibernate.annotations.Type;
 import org.hibernate.boot.MappingException;
 import org.hibernate.boot.jaxb.Origin;
@@ -326,7 +326,7 @@ private AccessType determineLocalClassDefinedAccessStrategy() {
 	}
 
 	private static boolean discoverTypeWithoutReflection(ClassDetails classDetails, MemberDetails memberDetails) {
-		if ( memberDetails.hasDirectAnnotationUsage( Target.class ) ) {
+		if ( memberDetails.hasDirectAnnotationUsage( TargetEmbeddable.class ) ) {
 			return true;
 		}
 

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

@@ -5,8 +5,9 @@
 package org.hibernate.boot.model.internal;
 
 import jakarta.persistence.Access;
+import jakarta.persistence.Embedded;
 import org.hibernate.MappingException;
-import org.hibernate.annotations.Target;
+import org.hibernate.annotations.TargetEmbeddable;
 import org.hibernate.boot.models.internal.ModelsHelper;
 import org.hibernate.boot.spi.AccessType;
 import org.hibernate.boot.spi.MetadataBuildingContext;
@@ -18,6 +19,7 @@
 import org.hibernate.models.spi.MemberDetails;
 import org.hibernate.models.spi.ModelsContext;
 import org.hibernate.models.spi.TypeDetails;
+import org.hibernate.models.spi.TypeDetails.Kind;
 import org.hibernate.models.spi.TypeVariableScope;
 
 /**
@@ -88,23 +90,38 @@ public TypeDetails getPropertyType() throws MappingException {
 					sourceModelContext.getClassDetailsRegistry(),
 					() -> new DynamicClassDetails( targetName, sourceModelContext )
 			);
-			return new ClassTypeDetailsImpl( classDetails, TypeDetails.Kind.CLASS );
+			return new ClassTypeDetailsImpl( classDetails, Kind.CLASS );
 		}
 
-		final Target legacyTargetAnnotation = propertyMember.getDirectAnnotationUsage( Target.class );
-		if ( legacyTargetAnnotation != null ) {
-			return resolveLegacyTargetAnnotation( legacyTargetAnnotation, sourceModelContext );
+		final TargetEmbeddable targetEmbeddable = getTargetEmbeddableAnnotation(propertyMember);
+		if ( targetEmbeddable != null ) {
+			return resolveTargetEmbeddableAnnotation( targetEmbeddable, sourceModelContext );
 		}
 
 		return propertyMember.resolveRelativeType( ownerType );
 	}
 
-	private static ClassTypeDetailsImpl resolveLegacyTargetAnnotation(
-			Target legacyTargetAnnotation,
+	private TargetEmbeddable getTargetEmbeddableAnnotation(MemberDetails memberDetails) {
+		TargetEmbeddable targetEmbeddable = memberDetails.getDirectAnnotationUsage( TargetEmbeddable.class );
+		if ( targetEmbeddable != null ) {
+			if (!memberDetails.hasDirectAnnotationUsage(Embedded.class) ) {
+				// If set on an attribute, it should be an @Embedded
+				throw new MappingException( "The @TargetEmbeddable annotation can only be set on an element marked with @Embedded" );
+			}
+		}
+		else {
+			// Set on an interface
+			targetEmbeddable = memberDetails.getAssociatedType().determineRawClass().getDirectAnnotationUsage( TargetEmbeddable.class );
+		}
+		return targetEmbeddable;
+	}
+
+	private static ClassTypeDetailsImpl resolveTargetEmbeddableAnnotation(
+			TargetEmbeddable targetEmbeddable,
 			ModelsContext sourceModelContext) {
 		final ClassDetailsRegistry classDetailsRegistry = sourceModelContext.getClassDetailsRegistry();
-		final ClassDetails targetClassDetails = classDetailsRegistry.resolveClassDetails( legacyTargetAnnotation.value().getName() );
-		return new ClassTypeDetailsImpl( targetClassDetails, TypeDetails.Kind.CLASS );
+		final ClassDetails targetClassDetails = classDetailsRegistry.resolveClassDetails( targetEmbeddable.value().getName() );
+		return new ClassTypeDetailsImpl( targetClassDetails, Kind.CLASS );
 	}
 
 	@Override
@@ -118,12 +135,12 @@ public TypeDetails getClassOrElementType() throws MappingException {
 					modelsContext.getClassDetailsRegistry(),
 					() -> new DynamicClassDetails( targetName, modelsContext )
 			);
-			return new ClassTypeDetailsImpl( classDetails, TypeDetails.Kind.CLASS );
+			return new ClassTypeDetailsImpl( classDetails, Kind.CLASS );
 		}
 
-		final Target legacyTargetAnnotation = propertyMember.getDirectAnnotationUsage( Target.class );
-		if ( legacyTargetAnnotation != null ) {
-			return resolveLegacyTargetAnnotation( legacyTargetAnnotation, modelsContext );
+		final TargetEmbeddable targetEmbeddable = getTargetEmbeddableAnnotation(propertyMember);
+		if ( targetEmbeddable != null ) {
+			return resolveTargetEmbeddableAnnotation( targetEmbeddable, modelsContext );
 		}
 
 		return propertyMember.resolveRelativeAssociatedType( ownerType );
@@ -136,9 +153,9 @@ public ClassDetails getClassOrPluralElement() throws MappingException {
 			return buildingContext.getMetadataCollector().getClassDetailsRegistry().getClassDetails( xmlTarget.value() );
 		}
 
-		final Target legacyTarget = propertyMember.getDirectAnnotationUsage( Target.class );
-		if ( legacyTarget != null ) {
-			final String targetName = legacyTarget.value().getName();
+		final TargetEmbeddable targetEmbeddable = getTargetEmbeddableAnnotation(propertyMember);
+		if ( targetEmbeddable != null ) {
+			final String targetName = targetEmbeddable.value().getName();
 			return buildingContext.getMetadataCollector().getClassDetailsRegistry().getClassDetails( targetName );
 		}
 

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

@@ -599,9 +599,9 @@ public interface HibernateAnnotations {
 			Synchronize.class,
 			SynchronizeAnnotation.class
 	);
-	OrmAnnotationDescriptor<Target,TargetLegacyAnnotation> TARGET_LEGACY = new OrmAnnotationDescriptor<>(
-			Target.class,
-			TargetLegacyAnnotation.class
+	OrmAnnotationDescriptor<TargetEmbeddable,TargetEmbeddableAnnotation> TARGET_EMBEDDABLE = new OrmAnnotationDescriptor<>(
+			TargetEmbeddable.class,
+			TargetEmbeddableAnnotation.class
 	);
 	SpecializedAnnotationDescriptor<TenantId,TenantIdAnnotation> TENANT_ID = new SpecializedAnnotationDescriptor<>(
 			TenantId.class,

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

@@ -4,40 +4,40 @@
  */
 package org.hibernate.boot.models.annotations.internal;
 
+import org.hibernate.annotations.TargetEmbeddable;
+import org.hibernate.models.spi.ModelsContext;
+
 import java.lang.annotation.Annotation;
 import java.util.Map;
 
-import org.hibernate.annotations.Target;
-import org.hibernate.models.spi.ModelsContext;
-
 @SuppressWarnings({ "ClassExplicitlyAnnotation", "unused" })
 @jakarta.annotation.Generated("org.hibernate.orm.build.annotations.ClassGeneratorProcessor")
-public class TargetLegacyAnnotation implements Target {
+public class TargetEmbeddableAnnotation implements TargetEmbeddable {
 	private Class<?> value;
 
 	/**
 	 * Used in creating dynamic annotation instances (e.g. from XML)
 	 */
-	public TargetLegacyAnnotation(ModelsContext modelContext) {
+	public TargetEmbeddableAnnotation(ModelsContext modelContext) {
 	}
 
 	/**
 	 * Used in creating annotation instances from JDK variant
 	 */
-	public TargetLegacyAnnotation(Target annotation, ModelsContext modelContext) {
+	public TargetEmbeddableAnnotation(TargetEmbeddable annotation, ModelsContext modelContext) {
 		this.value = annotation.value();
 	}
 
 	/**
 	 * Used in creating annotation instances from Jandex variant
 	 */
-	public TargetLegacyAnnotation(Map<String, Object> attributeValues, ModelsContext modelContext) {
+	public TargetEmbeddableAnnotation(Map<String, Object> attributeValues, ModelsContext modelContext) {
 		this.value = (Class<?>) attributeValues.get( "value" );
 	}
 
 	@Override
 	public Class<? extends Annotation> annotationType() {
-		return Target.class;
+		return TargetEmbeddable.class;
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/TargetLegacyAnnotation.java renamed to hibernate-core/src/main/java/org/hibernate/boot/models/annotations/internal/TargetEmbeddableAnnotation.java

@@ -8,7 +8,7 @@
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
 
-import org.hibernate.annotations.Target;
+import org.hibernate.annotations.TargetEmbeddable;
 
 /**
  * @author Emmanuel Bernard
@@ -21,7 +21,7 @@ public class LuggageImpl implements Luggage {
 	private Owner owner;
 
 	@Embedded
-	@Target(OwnerImpl.class)
+	@TargetEmbeddable(OwnerImpl.class)
 	public Owner getOwner() {
 		return owner;
 	}

hibernate-core/src/test/java/org/hibernate/orm/test/annotations/target/LuggageImpl.java

@@ -11,7 +11,7 @@
 import jakarta.persistence.Id;
 
 import org.hibernate.annotations.Parent;
-import org.hibernate.annotations.Target;
+import org.hibernate.annotations.TargetEmbeddable;
 import org.hibernate.orm.test.jpa.BaseEntityManagerFunctionalTestCase;
 
 import org.junit.Test;
@@ -110,7 +110,7 @@ public static class City {
 		private String name;
 
 		@Embedded
-		@Target(GPS.class)
+		@TargetEmbeddable(GPS.class)
 		private GPS coordinates;
 
 		//Getters and setters omitted for brevity

hibernate-core/src/test/java/org/hibernate/orm/test/mapping/basic/ParentTest.java

@@ -11,7 +11,7 @@
 import jakarta.persistence.Id;
 
 import org.hibernate.annotations.Parent;
-import org.hibernate.annotations.Target;
+import org.hibernate.annotations.TargetEmbeddable;
 import org.hibernate.orm.test.jpa.BaseEntityManagerFunctionalTestCase;
 
 import org.junit.Test;
@@ -110,7 +110,7 @@ public static class City {
 		private String name;
 
 		@Embedded
-		@Target(GPS.class)
+		@TargetEmbeddable(GPS.class)
 		private GPS coordinates;
 
 		//Getters and setters omitted for brevity