HHH-7221 - Document natural-id improvements as well as load-access APIs

documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml

@@ -39,6 +39,7 @@
     <xi:include href="Database_Access.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     <xi:include href="chapters/transactions/Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     <xi:include href="chapters/pc/Persistence_Context.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="chapters/loading/Loading.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     <xi:include href="Batch_Processing.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     <xi:include href="Locking.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
     <xi:include href="Caching.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

documentation/src/main/docbook/devguide/en-US/chapters/pc/Persistence_Context.xml

@@ -141,6 +141,60 @@
         </para>
     </section>
 
+    <section>
+        <title>Obtain an entity by natural-id</title>
+
+        <para>
+            In addition to allowing to load by identifier, Hibernate allows applications to load by declared
+            natural identifier.
+        </para>
+        <example>
+            <title>Example of simple natural-id access</title>
+            <programlisting role="JAVA"><xi:include href="extras/SimpleNaturalIdLoading.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+        </example>
+        <example>
+            <title>Example of natural-id access</title>
+            <programlisting role="JAVA"><xi:include href="extras/NaturalIdLoading.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+        </example>
+        <para>
+            Just like we saw above, access entity data by natural id allows both the <methodname>load</methodname>
+            and <methodname>getReference</methodname> forms, with the same semantics.
+        </para>
+
+        <para>
+            Accessing persistent data by identifier and by natural-id is consistent in the Hibernate API.  Each defines
+            the same 2 data access methods:
+        </para>
+        <variablelist>
+            <varlistentry>
+                <term><methodname>getReference</methodname></term>
+                <listitem>
+                    <para>
+                        Should be used in cases where the identifier is assumed to exist, where non-existence would be
+                        an actual error.  Should never be used to test existence.  That is because this method will
+                        prefer to create and return a proxy if the data is not already associated with the Session
+                        rather than hit the database.  The quintessential use-case for using this method is to create
+                        foreign-key based associations.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><methodname>load</methodname></term>
+                <listitem>
+                    <para>
+                        Will return the persistent data associated with the given identifier value or null if that
+                        identifier does not exist.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+        <para>
+            In addition to those 2 methods, each also defines the method <methodname>with</methodname> accepting
+            a <interfacename>org.hibernate.LockOptions</interfacename> argument.  Locking is discussed in a separate
+            chapter.
+        </para>
+    </section>
+
     <section>
         <title>Refresh entity state</title>
 

documentation/src/main/docbook/devguide/en-US/chapters/pc/extras/GetReferenceWithSession.java

@@ -1,2 +1,2 @@
 Book book = new Book();
-book.setAuthor( session.load( Author.class, authorId ) );
+book.setAuthor( session.byId( Author.class ).getReference( authorId ) );

documentation/src/main/docbook/devguide/en-US/chapters/pc/extras/LoadWithSession.java

@@ -1 +1 @@
-session.get( Author.class, authorId );
+session.byId( Author.class ).load( authorId );

documentation/src/main/docbook/devguide/en-US/chapters/pc/extras/NaturalIdLoading.java

@@ -0,0 +1,31 @@
+import java.lang.String;
+
+@Entity
+public class User {
+	@Id
+	@GeneratedValue
+	Long id;
+
+	@NaturalId
+	String system;
+
+	@NaturalId
+	String userName;
+
+	...
+}
+
+// use getReference() to create associations...
+Resource aResource = (Resource) session.byId( Resource.class ).getReference( 123 );
+User aUser = (User) session.byNaturalId( User.class )
+		.using( "system", "prod" )
+		.using( "userName", "steve" )
+		.getReference();
+aResource.assignTo( user );
+
+
+// use load() to pull initialzed data
+return session.byNaturalId( User.class )
+		.using( "system", "prod" )
+		.using( "userName", "steve" )
+		.load();

documentation/src/main/docbook/devguide/en-US/chapters/pc/extras/SimpleNaturalIdLoading.java

@@ -0,0 +1,20 @@
+@Entity
+public class User {
+	@Id
+	@GeneratedValue
+	Long id;
+
+	@NaturalId
+	String userName;
+
+	...
+}
+
+// use getReference() to create associations...
+Resource aResource = (Resource) session.byId( Resource.class ).getReference( 123 );
+User aUser = (User) session.bySimpleNaturalId( User.class ).getReference( "steve" );
+aResource.assignTo( user );
+
+
+// use load() to pull initialzed data
+return session.bySimpleNaturalId( User.class ).load( "steve" );