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

@@ -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
 

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.

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.`
+|===============
+