HHH-16383 - NaturalIdClass

Author: sebersole

hibernate-core/src/main/java/org/hibernate/NaturalIdLoadAccess.java

@@ -5,7 +5,6 @@
 package org.hibernate;
 
 import jakarta.persistence.EntityGraph;
-
 import jakarta.persistence.PessimisticLockScope;
 import jakarta.persistence.Timeout;
 import jakarta.persistence.metamodel.SingularAttribute;
@@ -35,7 +34,10 @@
  * @see Session#byNaturalId(Class)
  * @see org.hibernate.annotations.NaturalId
  * @see SimpleNaturalIdLoadAccess
+ *
+ * @deprecated (since 7.3) Use {@linkplain Session#findByNaturalId} instead.
  */
+@Deprecated
 public interface NaturalIdLoadAccess<T> {
 
 	/**

hibernate-core/src/main/java/org/hibernate/NaturalIdMultiLoadAccess.java

@@ -36,7 +36,10 @@
  *
  * @see Session#byMultipleNaturalId(Class)
  * @see org.hibernate.annotations.NaturalId
+ *
+ * @deprecated (since 7.3) Use {@linkplain Session#findMultipleByNaturalId} instead.
  */
+@Deprecated
 public interface NaturalIdMultiLoadAccess<T> {
 
 	/**

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -558,6 +558,42 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 */
 	Object find(String entityName, Object primaryKey, FindOption... options);
 
+	/// Find an entity by [natural-id][org.hibernate.annotations.NaturalId].
+	///
+	/// @param entityType The type of entity to load.
+	/// @param naturalId The natural-id value.
+	/// @param options The options to apply to the find operation.
+	///
+	/// @apiNote For non-aggregated composite natural-ids, consider leveraging a [org.hibernate.annotations.NaturalIdClass].
+	<T> T findByNaturalId(Class<T> entityType, Object naturalId, FindOption... options);
+
+	/// Find an entity by [natural-id][org.hibernate.annotations.NaturalId].
+	///
+	/// @param entityName The name of the entity type to load.
+	/// @param naturalId The natural-id value.
+	/// @param options The options to apply to the find operation.
+	///
+	/// @apiNote For non-aggregated composite natural-ids, consider leveraging a [org.hibernate.annotations.NaturalIdClass].
+	Object findByNaturalId(String entityName, Object naturalId, FindOption... options);
+
+	/// Find multiple entities by [natural-id][org.hibernate.annotations.NaturalId].
+	///
+	/// @param entityType The type of entity to load.
+	/// @param naturalIds The natural-id values.
+	/// @param options The options to apply to the find operation.  May contain [FindMultipleOption] values.
+	///
+	/// @apiNote For non-aggregated composite natural-ids, consider leveraging a [org.hibernate.annotations.NaturalIdClass].
+	<T> List<T> findMultipleByNaturalId(Class<T> entityType, List<Object> naturalIds, FindOption... options);
+
+	/// Find multiple entities by [natural-id][org.hibernate.annotations.NaturalId].
+	///
+	/// @param entityName The name of the entity type to load.
+	/// @param naturalIds The natural-id values.
+	/// @param options The options to apply to the find operation.  May contain [FindMultipleOption] values.
+	///
+	/// @apiNote For non-aggregated composite natural-ids, consider leveraging a [org.hibernate.annotations.NaturalIdClass].
+	List<Object> findMultipleByNaturalId(String entityName, List<Object> naturalIds, FindOption... options);
+
 	/**
 	 * Return the persistent instances of the given entity class with the given identifiers
 	 * as a list. The position of an instance in the returned list matches the position of its
@@ -1203,7 +1239,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @throws HibernateException If the given class does not resolve as a mapped entity,
 	 *                            or if the entity does not declare a natural id
+	 *
+	 * @deprecated (since 7.3) : Use {@linkplain #findByNaturalId} instead.
 	 */
+	@Deprecated
 	<T> NaturalIdLoadAccess<T> byNaturalId(Class<T> entityClass);
 
 	/**
@@ -1218,7 +1257,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @throws HibernateException If the given name does not resolve to a mapped entity,
 	 *                            or if the entity does not declare a natural id
+	 *
+	 * @deprecated (since 7.3) : Use {@linkplain #findByNaturalId} instead.
 	 */
+	@Deprecated
 	<T> NaturalIdLoadAccess<T> byNaturalId(String entityName);
 
 	/**
@@ -1233,7 +1275,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @throws HibernateException If the given class does not resolve as a mapped entity,
 	 *                            or if the entity does not declare a natural id
+	 *
+	 * @deprecated (since 7.3) : Use {@linkplain #findByNaturalId} instead.
 	 */
+	@Deprecated
 	<T> SimpleNaturalIdLoadAccess<T> bySimpleNaturalId(Class<T> entityClass);
 
 	/**
@@ -1248,7 +1293,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @throws HibernateException If the given name does not resolve to a mapped entity,
 	 *                            or if the entity does not declare a natural id
+	 *
+	 * @deprecated (since 7.3) : Use {@linkplain #findByNaturalId} instead.
 	 */
+	@Deprecated
 	<T> SimpleNaturalIdLoadAccess<T> bySimpleNaturalId(String entityName);
 
 	/**
@@ -1262,7 +1310,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @throws HibernateException If the given class does not resolve as a mapped entity,
 	 *                            or if the entity does not declare a natural id
+	 *
+	 * @deprecated (since 7.3) : Use {@linkplain #findMultipleByNaturalId} instead.
 	 */
+	@Deprecated
 	<T> NaturalIdMultiLoadAccess<T> byMultipleNaturalId(Class<T> entityClass);
 
 	/**
@@ -1276,7 +1327,10 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 *
 	 * @throws HibernateException If the given name does not resolve to a mapped entity,
 	 *                            or if the entity does not declare a natural id
+	 *
+	 * @deprecated (since 7.3) : Use {@linkplain #findMultipleByNaturalId} instead.
 	 */
+	@Deprecated
 	<T> NaturalIdMultiLoadAccess<T> byMultipleNaturalId(String entityName);
 
 	/**

hibernate-core/src/main/java/org/hibernate/SimpleNaturalIdLoadAccess.java

@@ -29,7 +29,10 @@
  * @see Session#bySimpleNaturalId(Class)
  * @see org.hibernate.annotations.NaturalId
  * @see NaturalIdLoadAccess
+ *
+ * @deprecated (since 7.3) Use {@linkplain Session#findByNaturalId} instead.
  */
+@Deprecated
 public interface SimpleNaturalIdLoadAccess<T> {
 
 	/**

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

@@ -4,87 +4,95 @@
  */
 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;
 
-/**
- * Specifies that a field or property of an entity class is part of
- * the natural id of the entity. This annotation is very useful when
- * the primary key of an entity class is a surrogate key, that is,
- * a {@linkplain jakarta.persistence.GeneratedValue system-generated}
- * synthetic identifier, with no domain-model semantics. There should
- * always be some other field or combination of fields which uniquely
- * identifies an instance of the entity from the point of view of the
- * user of the system. This is the <em>natural id</em> of the entity.
- * <p>
- * A natural id may be a single field or property of the entity:
- * <pre>
- * &#64;Entity
- * &#64;Cache &#64;NaturalIdCache
- * class Person {
- *
- *     //synthetic id
- *     &#64;GeneratedValue @Id
- *     Long id;
- *
- *     &#64;NotNull
- *     String name;
- *
- *     //simple natural id
- *     &#64;NotNull @NaturalId
- *     String ssn;
- *
- *     ...
- * }
- * </pre>
- * <p>
- * or it may be a composite value:
- * <pre>
- * &#64;Entity
- * &#64;Cache &#64;NaturalIdCache
- * class Vehicle {
- *
- *     //synthetic id
- *     &#64;GeneratedValue @Id
- *     Long id;
- *
- *     //composite natural id
- *
- *     &#64;Enumerated
- *     &#64;NotNull &#64;NaturalId
- *     Region region;
- *
- *     &#64;NotNull &#64;NaturalId
- *     String registration;
- *
- *     ...
- * }
- * </pre>
- * <p>
- * Unlike the {@linkplain jakarta.persistence.Id primary identifier}
- * of an entity, a natural id may be {@linkplain #mutable}.
- * <p>
- * On the other hand, a field or property which forms part of a natural
- * id may never be null, and so it's a good idea to use {@code @NaturalId}
- * in conjunction with the Bean Validation {@code @NotNull} annotation
- * or {@link jakarta.persistence.Basic#optional @Basic(optional=false)}.
- * <p>
- * The {@link org.hibernate.Session} interface offers several methods
- * that allow an entity instance to be retrieved by its
- * {@linkplain org.hibernate.Session#bySimpleNaturalId(Class) simple}
- * or {@linkplain org.hibernate.Session#byNaturalId(Class) composite}
- * natural id value. If the entity is also marked for {@linkplain
- * NaturalIdCache natural id caching}, then these methods may be able
- * to avoid a database round trip.
- *
- * @author Nicolás Lichtmaier
- *
- * @see NaturalIdCache
- */
+/// Specifies that a field or property of an entity class is part of
+/// the natural id of the entity. This annotation is very useful when
+/// the primary key of an entity class is a surrogate key, that is,
+/// a {@linkplain jakarta.persistence.GeneratedValue system-generated}
+/// synthetic identifier, with no domain-model semantics. There should
+/// always be some other field or combination of fields which uniquely
+/// identifies an instance of the entity from the point of view of the
+/// user of the system. This is the _natural id_ of the entity.
+///
+/// A natural id may be a single (basic or embedded) attribute of the entity:
+/// ````java
+/// @Entity
+/// class Person {
+///
+///     //synthetic id
+///     @GeneratedValue @Id
+///     Long id;
+///
+///     @NotNull
+///     String name;
+///
+///     //simple natural id
+///     @NotNull @NaturalId
+///     String ssn;
+///
+///     ...
+/// }
+/// ```
+///
+/// or it may be a non-aggregated composite value:
+/// ```java
+/// @Entity
+/// class Vehicle {
+///
+///     //synthetic id
+///     @GeneratedValue @Id
+///     Long id;
+///
+///     //composite natural id
+///
+///     @Enumerated
+///     @NotNull
+///	    @NaturalId
+///     Region region;
+///
+///     @NotNull
+///     @NaturalId
+///     String registration;
+///
+///     ...
+/// }
+/// ```
+///
+/// Unlike the {@linkplain jakarta.persistence.Id primary identifier}
+/// of an entity, a natural id may be {@linkplain #mutable}.
+///
+/// On the other hand, a field or property which forms part of a natural
+/// id may never be null, and so it's a good idea to use `@NaturalId`
+/// in conjunction with the Bean Validation `@NotNull` annotation
+/// or [@Basic(optional=false)][jakarta.persistence.Basic#optional()].
+///
+/// The [org.hibernate.Session] interface offers several methods
+/// that allow retrieval of one or more entity references by natural-id
+/// allow an entity instance to be retrieved by its natural-id:
+/// * [org.hibernate.Session#findByNaturalId] allows loading a single
+/// 	entity instance by natural-id.
+/// * [org.hibernate.Session#findMultipleByNaturalId] allows loading multiple
+/// 	entity instances by natural-id.
+///
+/// If the entity is also marked for [natural id caching][NaturalIdCache],
+/// then these methods may be able to avoid a database round trip.
+///
+/// @see org.hibernate.Session#findByNaturalId
+/// @see org.hibernate.Session#findMultipleByNaturalId
+/// @see NaturalIdClass
+/// @see NaturalIdCache
+///
+/// @apiNote For non-aggregated composite natural-id cases, it is recommended to
+/// leverage [@NaturalIdClass][NaturalIdClass] for loading.
+///
+/// @author Nicolás Lichtmaier
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface NaturalId {

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

@@ -0,0 +1,48 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+
+/// Models a non-aggregated composite natural-id for the purpose of loading.
+/// The non-aggregated form uses multiple [@NaturalId][NaturalId] as opposed
+/// to the aggregated form which uses a single [@NaturalId][NaturalId] combined
+/// with [@Embedded][jakarta.persistence.Embedded].
+/// Functions in a similar fashion as [@IdClass][jakarta.persistence.IdClass] for
+/// non-aggregated composite identifiers.
+///
+/// ```java
+/// @Entity
+/// @NaturalIdClass(OrderNaturalId.class)
+/// class Order {
+///     @Id
+/// 	Integer id;
+/// 	@NaturalId @ManyToOne
+/// 	Customer customer;
+/// 	@NaturalId
+/// 	Integer orderNumber;
+///     ...
+/// }
+///
+/// class OrderNaturalId {
+/// 	Integer customer;
+/// 	Integer orderNumber;
+/// 	...
+/// }
+/// ```
+///
+/// @see NaturalId
+/// @see jakarta.persistence.IdClass
+///
+/// @author Steve Ebersole
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface NaturalIdClass {
+	/// The class to use for loading the associated entity by natural-id.
+	Class<?> value();
+}