HHH-18198 - Remove @target

Author: sebersole

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

@@ -299,60 +299,39 @@ This usage is covered in detail in <<chapters/domain/identifiers.adoc#identifier
 Embeddable types that are used as collection entries, map keys or entity type identifiers cannot include their own collection mappings.
 ====
 
+
 [[embeddable-Target]]
 ==== `@TargetEmbeddable` 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.).
-
-[NOTE]
-====
-An "embeddable-valued mapping" may be an `@EmbeddedId`, `@Embedded` or `@ElementCollection`.
-====
+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).
 
-`@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>>.
+As an example, consider an `@Embedded` attribute (`City.coordinates`) whose declared type (`Coordinates`) is an interface.  However, Hibernate needs to know about the concrete type to use, which is `GPS` in this case.  The `@TargetEmbeddable` annotation is used to provide this information.
 
 [[embeddable-Target-example]]
-.Embeddable-valued mapping usage
+.Embedded mapping example
 ====
 [source, java, indent=0]
 ----
 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 `@TargetEmbeddable` annotation is used to provide this information.
+The mapping works just like any embeddable-valued mapping at this point, with Hibernate using `GPS` "under the covers":
 
-Assuming we have persisted the following `City` entity:
-
-[[embeddable-Target-persist-example]]
-.`@TargetEmbeddable` persist example
-====
-[source, java, indent=0]
-----
-include::{example-dir-emeddable}/TargetEmbeddableOnEmbeddedTest.java[tags=embeddable-Target-persist-example]
-----
-====
-
-When fetching the `City` entity, the `coordinates` property is mapped by the `@TargetEmbeddable` expression:
 
 [[embeddable-Target-fetching-example]]
-.`@TargetEmbeddable` fetching example
+.Usage example
 ====
 [source, java, indent=0]
 ----
 include::{example-dir-emeddable}/TargetEmbeddableOnEmbeddedTest.java[tags=embeddable-Target-fetching-example]
 ----
-
-[source, SQL, indent=0]
-----
-include::{extrasdir}/embeddable/embeddable-Target-fetching-example.sql[]
-----
 ====
 
+For `@Embedded` and `@EmbeddedId` cases, `@TargetEmbeddable` may be specified on the member's declared type instead of the member itself:
+
 [[embeddable-Target-example2]]
-.Interface mapping usage
+.Interface mapping example
 ====
 [source, java, indent=0]
 ----

documentation/src/main/asciidoc/userguide/chapters/domain/extras/embeddable/embeddable-Target-fetching-example.sql

@@ -5,6 +5,7 @@
 package org.hibernate.boot.model.internal;
 
 import jakarta.persistence.Access;
+import jakarta.persistence.ElementCollection;
 import jakarta.persistence.Embedded;
 import org.hibernate.MappingException;
 import org.hibernate.annotations.TargetEmbeddable;
@@ -22,6 +23,8 @@
 import org.hibernate.models.spi.TypeDetails.Kind;
 import org.hibernate.models.spi.TypeVariableScope;
 
+import java.util.Locale;
+
 /**
  * Retrieve all inferred data from an annotated element
  *
@@ -93,27 +96,42 @@ public TypeDetails getPropertyType() throws MappingException {
 			return new ClassTypeDetailsImpl( classDetails, Kind.CLASS );
 		}
 
-		final TargetEmbeddable targetEmbeddable = getTargetEmbeddableAnnotation(propertyMember);
+		final TargetEmbeddable targetEmbeddable = getTargetEmbeddableAnnotation( propertyMember );
 		if ( targetEmbeddable != null ) {
 			return resolveTargetEmbeddableAnnotation( targetEmbeddable, sourceModelContext );
 		}
 
 		return propertyMember.resolveRelativeType( ownerType );
 	}
 
-	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" );
+	private static TargetEmbeddable getTargetEmbeddableAnnotation(MemberDetails memberDetails) {
+		// first we look for the annotation on the member itself
+		final TargetEmbeddable memberAnnotation = memberDetails.getDirectAnnotationUsage( TargetEmbeddable.class );
+		if ( memberAnnotation != null ) {
+			// this should only be allowed for embedded or collections-of-embeddables.
+			// 		NOTE: this is tricky to check for collections-of-embeddables as it
+			// 		would require a deep check of the collection's component type, so
+			// 		for now just assume the mapping is correct if we find @ElementCollection
+			final boolean allowed = memberDetails.hasDirectAnnotationUsage( Embedded.class )
+					|| memberDetails.hasDirectAnnotationUsage( ElementCollection.class );
+			if ( !allowed ) {
+				throw new MappingException(
+						String.format(
+								Locale.ROOT,
+								"@TargetEmbeddable can only be specified on properties marked with @Embedded or @ElementCollection [%s$%s]",
+								memberDetails.getDeclaringType().getName(),
+								memberDetails.getName()
+						)
+				);
 			}
+
+			return memberAnnotation;
 		}
-		else {
-			// Set on an interface
-			targetEmbeddable = memberDetails.getAssociatedType().determineRawClass().getDirectAnnotationUsage( TargetEmbeddable.class );
-		}
-		return targetEmbeddable;
+
+		// then, look on the member's type
+		// 		NOTE: this is not supported for collections-of-embeddables
+		// 		for the same reason stated above
+		return memberDetails.getAssociatedType().determineRawClass().getDirectAnnotationUsage( TargetEmbeddable.class );
 	}
 
 	private static ClassTypeDetailsImpl resolveTargetEmbeddableAnnotation(

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

@@ -9,60 +9,52 @@
 import jakarta.persistence.Entity;
 import jakarta.persistence.GeneratedValue;
 import jakarta.persistence.Id;
-
 import org.hibernate.annotations.TargetEmbeddable;
-import org.hibernate.orm.test.jpa.BaseEntityManagerFunctionalTestCase;
-
+import org.hibernate.testing.orm.junit.DomainModel;
+import org.hibernate.testing.orm.junit.SessionFactory;
+import org.hibernate.testing.orm.junit.SessionFactoryScope;
 import org.junit.Test;
 
-import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
 import static org.junit.Assert.assertEquals;
 
 /**
- * @author Vlad Mihalcea
+ * @author Jan Schatteman
  */
-public class TargetEmbeddableOnEmbeddedTest extends BaseEntityManagerFunctionalTestCase {
-
-	@Override
-	protected Class<?>[] getAnnotatedClasses() {
-		return new Class<?>[] {
-			City.class,
-		};
-	}
-
+@SuppressWarnings("JUnitMalformedDeclaration")
+@DomainModel( annotatedClasses = TargetEmbeddableOnEmbeddedTest.City.class )
+@SessionFactory
+public class TargetEmbeddableOnEmbeddedTest {
 	@Test
-	public void testLifecycle() {
-		//tag::embeddable-Target-persist-example[]
-		doInJPA(this::entityManagerFactory, entityManager -> {
-
+	public void testLifecycle(SessionFactoryScope factoryScope) {
+		factoryScope.inTransaction( (session) -> {
 			City cluj = new City();
-			cluj.setName("Cluj");
-			cluj.setCoordinates(new GPS(46.77120, 23.62360));
-
-			entityManager.persist(cluj);
-		});
-		//end::embeddable-Target-persist-example[]
-
-
-		//tag::embeddable-Target-fetching-example[]
-		doInJPA(this::entityManagerFactory, entityManager -> {
-
-			City cluj = entityManager.find(City.class, 1L);
-
-			assertEquals(46.77120, cluj.getCoordinates().x(), 0.00001);
-			assertEquals(23.62360, cluj.getCoordinates().y(), 0.00001);
-		});
-		//end::embeddable-Target-fetching-example[]
+			cluj.setName( "Cluj" );
+			cluj.setCoordinates( new GPS(46.77120, 23.62360 ) );
+
+			session.persist( cluj );
+		} );
+
+		factoryScope.inTransaction( (session) -> {
+//tag::embeddable-Target-fetching-example[]
+			City city = session.find(City.class, 1L);
+			assert city.getCoordinates() instanceof GPS;
+//end::embeddable-Target-fetching-example[]
+			assertEquals(46.77120, city.getCoordinates().x(), 0.00001);
+			assertEquals(23.62360, city.getCoordinates().y(), 0.00001);
+		} );
 	}
 
-	//tag::embeddable-Target-example[]
+//tag::embeddable-Target-example[]
 	public interface Coordinates {
 		double x();
 		double y();
 	}
 
 	@Embeddable
 	public static class GPS implements Coordinates {
+		// Omitted for brevity
+
+//end::embeddable-Target-example[]
 
 		private double latitude;
 
@@ -85,24 +77,26 @@ public double x() {
 		public double y() {
 			return longitude;
 		}
+
+//tag::embeddable-Target-example[]
 	}
 
 	@Entity(name = "City")
 	public static class City {
+		// Omitted for brevity
 
+//end::embeddable-Target-example[]
 		@Id
 		@GeneratedValue
 		private Long id;
 
 		private String name;
 
+//tag::embeddable-Target-example[]
 		@Embedded
 		@TargetEmbeddable(GPS.class)
 		private Coordinates coordinates;
-
-		//Getters and setters omitted for brevity
-
-	//end::embeddable-Target-example[]
+//end::embeddable-Target-example[]
 
 		public Long getId() {
 			return id;
@@ -123,7 +117,7 @@ public Coordinates getCoordinates() {
 		public void setCoordinates(Coordinates coordinates) {
 			this.coordinates = coordinates;
 		}
-	//tag::embeddable-Target-example[]
+//tag::embeddable-Target-example[]
 	}
-	//end::embeddable-Target-example[]
+//end::embeddable-Target-example[]
 }