HHH-6073

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

@@ -8,7 +8,7 @@
   <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Database_Access.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-  <xi:include href="Data_Operations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="Persistence_Context.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/Persistence_Context.xml

@@ -8,8 +8,9 @@
 
     <para>
         Both the <interfacename>org.hibernate.Session</interfacename> API and
-        <interfacename>javax.persistence.EntityManager</interfacename> API provide methods for working with entities.
+        <interfacename>javax.persistence.EntityManager</interfacename> API represent a context for dealing with
-        This chapter will explore the available operations in each.
+        persistent data.  This concept is called a <literal>persistence context</literal>.  Persistent data has a
+        state in relation to both a persistence context and the underlying database.
     </para>
 
     <itemizedlist>
@@ -307,4 +308,79 @@ return managed;]]>
         </section>
 
     </section>
+
+
+    <section>
+        <title>Checking persistent state</title>
+
+        <para>
+            An application can verify the state of entities and collections in relation to the persistence context.
+        </para>
+        <example>
+            <title>Examples of verifying managed state</title>
+            <programlisting><![CDATA[assert session.contains( cat );]]></programlisting>
+            <programlisting><![CDATA[assert entityManager.contains( cat );]]></programlisting>
+        </example>
+        <example>
+            <title>Examples of verifying laziness</title>
+            <programlisting>
+<![CDATA[if ( Hibernate.isInitialized( customer.getAddress() ) {
+    //display address if loaded
+}
+if ( Hibernate.isInitialized( customer.getOrders ) ) {
+    //display orders if loaded
+}
+if (Hibernate.isPropertyInitialized(customer, "detailedBio") ) {
+    //display property detailedBio if loaded
+}]]>
+            </programlisting>
+            <programlisting>
+<![CDATA[javax.persistence.PersistenceUnitUtil jpaUtil = entityManager.getEntityManagerFactory().getPersistenceUnitUtil();
+if ( jpaUtil.isLoaded( customer.getAddress() ) {
+    //display address if loaded
+}
+if ( jpaUtil.isLoaded( customer.getOrders ) ) {
+    //display orders if loaded
+}
+if (jpaUtil.isLoaded(customer, "detailedBio") ) {
+    //display property detailedBio if loaded
+}]]>
+            </programlisting>
+        </example>
+        <para>
+            In JPA there is an alternative means to check laziness using the following
+            <interfacename>javax.persistence.PersistenceUtil</interfacename> pattern.  However, the
+            <interfacename>javax.persistence.PersistenceUnitUtil</interfacename> is recommended where ever possible
+        </para>
+        <example>
+            <title>Alternative JPA means to verify laziness</title>
+            <programlisting>
+<![CDATA[javax.persistence.PersistenceUtil jpaUtil = javax.persistence.Persistence.getPersistenceUtil();
+if ( jpaUtil.isLoaded( customer.getAddress() ) {
+    //display address if loaded
+}
+if ( jpaUtil.isLoaded( customer.getOrders ) ) {
+    //display orders if loaded
+}
+if (jpaUtil.isLoaded(customer, "detailedBio") ) {
+    //display property detailedBio if loaded
+}]]>
+            </programlisting>
+        </example>
+
+    </section>
+
+    <section>
+        <title>Accessing Hibernate APIs from JPA</title>
+        <para>
+            JPA defines an incredibly useful method to allow applications access to the APIs of the underlying provider.
+        </para>
+        <example>
+            <title>Usage of EntityManager.unwrap</title>
+            <programlisting>
+<![CDATA[Session session = entityManager.unwrap( Session.class );
+SessionImplementor sessionImplementor = entityManager.unwrap( SessionImplementor.class );]]>
+            </programlisting>
+        </example>
+    </section>
 </chapter>

documentation/src/main/docbook/devguide/en-US/extras/evicting_from_second_level_cache.java

@@ -1,7 +1,15 @@
-sessionFactory.evict(Cat.class, catId); //evict a particular Cat
+sessionFactory.getCache().containsEntity(Cat.class, catId); // is this particular Cat currently in the cache
 
-sessionFactory.evict(Cat.class);  //evict all Cats
+sessionFactory.getCache().evictEntity(Cat.class, catId); // evict a particular Cat
 
-sessionFactory.evictCollection("Cat.kittens", catId); //evict a particular collection of kittens
+sessionFactory.getCache().evictEntityRegion(Cat.class);  // evict all Cats
 
-sessionFactory.evictCollection("Cat.kittens"); //evict all kitten collections
+sessionFactory.getCache().evictEntityRegions();  // evict all entity data
+
+sessionFactory.getCache().containsCollection("Cat.kittens", catId); // is this particular collection currently in the cache
+
+sessionFactory.getCache().evictCollection("Cat.kittens", catId); // evict a particular collection of kittens
+
+sessionFactory.getCache().evictCollectionRegion("Cat.kittens"); // evict all kitten collections
+
+sessionFactory.getCache().evictCollectionRegions(); // evict all collection data

hibernate-entitymanager/src/main/docbook/en/master.xml

@@ -102,10 +102,10 @@
   <xi:include href="modules/architecture.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="modules/configuration.xml"
+  <xi:include href="modules/migrated/configuration.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="modules/entitymanagerapi.xml"
+  <xi:include href="modules/migrated/entitymanagerapi.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <xi:include href="modules/metamodel.xml"
@@ -117,7 +117,7 @@
   <xi:include href="modules/listeners.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="modules/batch.xml"
+  <xi:include href="modules/migrated/batch.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <xi:include href="modules/query_ejbql.xml"