HHH-10808 - Update documentation according to 5.2 changes

Document Session-level JDBC batch size setting and add a new example for fetching a projection using Query.stream

documentation/src/main/asciidoc/userguide/chapters/batch/Batching.adoc

@@ -34,6 +34,20 @@ The following settings control this behavior.
 	Forces Hibernate to order inserts to allow for more batching to be used.
 	Comes with a performance hit, so benchmark before and after to see if this actually helps or hurts your application.
 
+[NOTE]
+====
+Since version 5.2, Hibernate allows overriding the global JDBC batch size given by the `hibernate.jdbc.batch_size` configuration property for a given `Session`.
+====
+
+[[batch-session-jdbc-batch-size-example]]
+.Hibernate specific JDBC batch size configuration on a per `Session` basis
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/BatchTest.java[tags=batch-session-jdbc-batch-size-example]
+----
+====
+
 [[batch-session-batch]]
 === Session batching
 

documentation/src/main/asciidoc/userguide/chapters/query/hql/HQL.adoc

@@ -295,10 +295,29 @@ include::{sourcedir}/HQLTest.java[tags=hql-api-list-example]
 ----
 ====
 
+[NOTE]
+====
 Since 5.2, Hibernate offers support for returning a `Stream` which can be later used to transform the underlying `ResultSet`.
 
+Internally, the `stream()` behaves like a `Query#scroll` and the underlying result is backed by a `ScrollableResults`.
+For this reason, the `Stream` contains an `Object[]` instead of the actual `Query` result type.
+====
+
+Fetching a projection using the `Query#stream` method can be done as follows:
+
+[[hql-api-stream-projection-example]]
+.Hibernate `stream()` using a projection result type
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/HQLTest.java[tags=hql-api-stream-projection-example]
+----
+====
+
+When fetching entities, the `Object[]` must be mapped to the original query result type prior to applying any further transformations.
+
 [[hql-api-stream-example]]
-.Hibernate `stream()` result
+.Hibernate `stream()` using an entity result type
 ====
 [source, JAVA, indent=0]
 ----
@@ -306,11 +325,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-api-stream-example]
 ----
 ====
 
-[NOTE]
+It is also possible to extract a single result from a `Query`.
-====
-Internally, the `stream()` behaves like a `Query#scroll` and the underlying result is backed by a `ScrollableResults`.
-For this reason, the `Stream` contains an `Object[]` instead of the actual `Query` result type.
-====
 
 [[hql-api-unique-result-example]]
 .Hibernate `uniqueResult()`

documentation/src/test/java/org/hibernate/userguide/batch/BatchTest.java

@@ -63,6 +63,15 @@ public class BatchTest extends BaseEntityManagerFunctionalTestCase {
 			entityManager.persist( new Person( "Vlad" ) );
 			entityManager.persist( new Person( "Mihalcea" ) );
 		} );
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			String oldName = "Vlad";
+			String newName = "Alexandru";
+			//tag::batch-session-jdbc-batch-size-example[]
+			entityManager
+				.unwrap( Session.class )
+				.setJdbcBatchSize( 10 );
+			//end::batch-session-jdbc-batch-size-example[]
+		} );
 		doInJPA( this::entityManagerFactory, entityManager -> {
 			String oldName = "Vlad";
 			String newName = "Alexandru";

documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java

@@ -34,6 +34,7 @@ import org.hibernate.userguide.model.Call;
 import org.hibernate.userguide.model.CreditCardPayment;
 import org.hibernate.userguide.model.Payment;
 import org.hibernate.userguide.model.Person;
+import org.hibernate.userguide.model.PersonNames;
 import org.hibernate.userguide.model.Phone;
 import org.hibernate.userguide.model.PhoneType;
 import org.hibernate.userguide.model.WireTransferPayment;
@@ -807,6 +808,27 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 		});
 	}
 
+	@Test
+	public void test_hql_api_stream_projection_example() {
+		doInJPA( this::entityManagerFactory, entityManager -> {
+			Session session = entityManager.unwrap( Session.class );
+			//tag::hql-api-stream-projection-example[]
+			Stream<Object[]> persons = session.createQuery(
+				"select p.name, p.nickName " +
+				"from Person p " +
+				"where p.name like :name" )
+			.setParameter( "name", "J%" )
+			.stream();
+
+			List<PersonNames> personNames = persons
+				.map( row -> new PersonNames( (String) row[0], (String)row[1] ) )
+				.collect(Collectors.toList());
+			//end::hql-api-stream-projection-example[]
+
+			assertEquals( 1, personNames.size() );
+		});
+	}
+
 	@Test
 	public void test_hql_api_unique_result_example() {
 		doInJPA( this::entityManagerFactory, entityManager -> {

documentation/src/test/java/org/hibernate/userguide/pc/PersistenceContextTest.java

@@ -150,17 +150,17 @@ public class PersistenceContextTest extends BaseEntityManagerFunctionalTestCase
 
 			//tag::pc-find-by-natural-id-example[]
 			Book book = session
-					.byNaturalId( Book.class )
+				.byNaturalId( Book.class )
-					.using( "isbn", isbn )
+				.using( "isbn", isbn )
-					.load( );
+				.load( );
 			//end::pc-find-by-natural-id-example[]
 			assertNotNull(book);
 
 			//tag::pc-find-optional-by-simple-natural-id-example[]
 			Optional<Book> optionalBook = session
-					.byNaturalId( Book.class )
+				.byNaturalId( Book.class )
-					.using( "isbn", isbn )
+				.using( "isbn", isbn )
-					.loadOptional( );
+				.loadOptional( );
 			//end::pc-find-optional-by-simple-natural-id-example[]
 		} );