From 3a02d6f14e4b87f2fffe1dd94363efa9027f9145 Mon Sep 17 00:00:00 2001
From: Thomas Darimont <tdarimont@pivotal.io>
Date: Fri, 20 Mar 2015 13:00:14 +0100
Subject: [PATCH] DATACMNS-654 - Documented usage of Java 8 Streams in
 repositories.

Added section to repository documentation on how to use streams. Added an overview table for the generally supported return types for query methods.

Original pull request: #119.
---
 src/main/asciidoc/index.adoc                  |  1 +
 src/main/asciidoc/repositories.adoc           | 33 +++++++++++++++++++
 ...pository-query-return-types-reference.adoc | 24 ++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 src/main/asciidoc/repository-query-return-types-reference.adoc

diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc
index 48414ee5e..60016a8e1 100644
--- a/src/main/asciidoc/index.adoc
+++ b/src/main/asciidoc/index.adoc
@@ -29,5 +29,6 @@ include::auditing.adoc[]
 include::repository-namespace-reference.adoc[]
 include::repository-populator-namespace-reference.adoc[]
 include::repository-query-keywords-reference.adoc[]
+include::repository-query-return-types-reference.adoc[]
 :leveloffset: -1
 
diff --git a/src/main/asciidoc/repositories.adoc b/src/main/asciidoc/repositories.adoc
index 918580efb..2c218ae8c 100644
--- a/src/main/asciidoc/repositories.adoc
+++ b/src/main/asciidoc/repositories.adoc
@@ -332,6 +332,39 @@ If pagination or slicing is applied to a limiting query pagination (and the calc
 
 NOTE: Note that limiting the results in combination with dynamic sorting via a `Sort` parameter allows to express query methods for the 'K' smallest as well as for the 'K' biggest elements.
 
+[[repositories.query-streaming]]
+=== Streaming query results
+
+The results of query methods can be processed incrementally by using a Java 8 `Stream<T>` as return type.
+Instead of simply wrapping the query results in a `Stream` data store specific methods are used to
+perform the streaming.
+
+.Stream the result of a query with Java 8 `Stream<T>`
+====
+[source, java]
+----
+@Query("select u from User u")
+Stream<User> findAllByCustomQueryAndStream();
+
+Stream<User> readAllByFirstnameNotNull();
+
+@Query("select u from User u")
+Stream<User> streamAllPaged(Pageable pageable);
+----
+====
+NOTE: A `Stream` potentially wraps underlying data store specific resources and must therefore be closed after usage. The closing can be done manually via the `close()` method of `Stream` or by using a  Java 7 `TWR`-block.
+
+.Working with a `Stream<T>` result in a TWR block
+====
+[source, java]
+----
+try (Stream<User> stream = repository.findAllByCustomQueryAndStream()){
+  stream.forEach(/* process user */);
+}
+----
+====
+NOTE: Not all data store specific repository implementations support `Stream<T>` as a return type.
+
 [[repositories.create-instances]]
 == Creating repository instances
 In this section you create instances and bean definitions for the repository interfaces defined. One way to do so is using the Spring namespace that is shipped with each Spring Data module that supports the repository mechanism although we generally recommend to use the Java-Config style configuration.
diff --git a/src/main/asciidoc/repository-query-return-types-reference.adoc b/src/main/asciidoc/repository-query-return-types-reference.adoc
new file mode 100644
index 000000000..ad8ab81cf
--- /dev/null
+++ b/src/main/asciidoc/repository-query-return-types-reference.adoc
@@ -0,0 +1,24 @@
+[[repository-query-return-types]]
+[appendix]
+= Repository query return types
+
+== Supported query return types
+The following table lists the return types generally supported by Spring Data repositories. However, consult the store-specific documentation for the exact list of supported return-types, because some listed here might not be supported in a particular store.
+
+.Query return types
+[options="header", cols="1,3"]
+|===============
+|Return type|Description
+|`void`|`Denotes no return value`
+|`Primitives`|`Java primitives`
+|`Wrapper types`|`Java wrapper types`
+|`T`|`An entity or single attribute type T`
+|`Iterator<T>`|`Iterator`
+|`Collection<T>`|`Collection`
+|`List<T>`|`List`
+|`Optional<T>`|`Java 8 or Guava Optional`
+|`Stream<T>`|`Java 8 Stream`
+|`Slice`|`A sized chunk of data with information whether there is more data available.`
+|`Page<T>`|`A Slice with additional information, e.g. total # of results.`
+|===============
+