HHH-16383 - NaturalIdClass

Author: sebersole

documentation/src/main/asciidoc/introduction/Entities.adoc

@@ -526,6 +526,20 @@ Hibernate automatically generates a `UNIQUE` constraint on the columns mapped by
 Consider using the natural id attributes to implement <<equals-and-hash>>.
 ====
 
+In cases where the natural id is defined by multiple attributes, Hibernate also offers the link:{doc-javadoc-url}org/hibernate/annotations/NaturalIdClass.html[`@NaturalIdClass`] annotation which acts similarly to the Jakarta Persistence `@IdClass` annotation for <<load-by-natural-id,find operations>> -
+
+[source,java]
+----
+record BookKey(String isbn, int printing) {}
+
+@Entity
+@NaturalIdClass(BookKey.class)
+class Book {
+    ...
+}
+----
+
+
 The payoff for doing this extra work, as we will see <<natural-id-cache,much later>>, is that we can take advantage of optimized natural id lookups that make use of the second-level cache.
 
 Note that even when you've identified a natural key, we still recommend the use of a generated surrogate key in foreign keys, since this makes your data model _much_ easier to change.

documentation/src/main/asciidoc/introduction/Interacting.adoc

@@ -276,6 +276,7 @@ Modifications are automatically detected when the session is <<flush,flushed>>.
 
 On the other hand, except for `getReference()`, the following operations all result in immediate access to the database:
 
+[[methods-for-reading]]
 .Methods for reading and locking data
 [%breakable,cols="30,~"]
 |===
@@ -368,6 +369,25 @@ The following code results in a single SQL `select` statement:
 List<Book> books = session.findMultiple(Book.class, bookIds);
 ----
 
+[[load-by-natural-id]]
+As discussed <<natural-id-attributes,earlier>>, Hibernate offers the ability to map a natural id and perform load operations using that natural id.
+This is accomplished using the `KeyType#NATURAL` `FindOption` -
+
+[source,java]
+----
+var bookKey = new BookKey(...);
+var book = session.find(Book.class, bookKey, NATURAL);
+var books = session.findMultiple(Book.class, List.of(bookKey), NATURAL);
+----
+
+When loading by natural id, the type of value accepted depends on the type of natural id.
+For single-attribute natural ids, whether defined by a basic or embedded type, the attribute type should be used.
+For multi-attribute natural ids, Hibernate will accept a number of forms:
+
+* If a link:{doc-javadoc-url}org/hibernate/annotations/NaturalIdClass.html[`@NaturalIdClass`] is defined, an instance of the natural id class may be used.
+* A `List` of the individual attribute values, ordered alphabetically by name, may be used.
+* A `Map` of the individual attribute values, keyed by the attribute name, may be used.
+
 Each of the operations we've seen so far affects a single entity instance passed as an argument.
 But there's a way to set things up so that an operation will propagate to associated entities.
 
@@ -595,7 +615,8 @@ Therefore, Hibernate has some APIs that streamline certain more complicated look
 
 [NOTE]
 ====
-Since the introduction of `FindOption` in JPA 3.2, `byId()` is now much less useful.
+Since the introduction of `FindOption` in JPA 3.2, `byId()` is now much less useful and deprecated.
+Instead, use `find()` and `findMultiple()` as discussed <<methods-for-reading,earlier>>.
 ====
 
 Batch loading is very useful when we need to retrieve multiple instances of the same entity class by id: