added streaming

README.md

@@ -81,6 +81,7 @@ Furthermore, the provided implementation offers the following features:
   - calling `insert(new IdInteval<>("ID1", 1, 2)))` and `insert(new IdInteval<>("ID2", 1, 2)))` will inserted two intervals (independent of the storage)
 - easy extendable `IInterval` type, so that every type of data associated to intervals can be handled (since 1.5.0)
 - `IntervalTree` implements `Collection` interface (since 1.5.0)
+- `IntervalTree` provides a real `Stream` for `overlap(...)` operation, see [Streaming](docs/Streaming.md) (since 1.6.3)
 - `Interval` (see [documentation](docs/Interval.md)) implements [Allen's Interval Algebra](https://en.wikipedia.org/wiki/Allen's_interval_algebra) (since 1.5.2)
 - store, cache, and persist, see [documentation](docs/StoreCachePersist.md) (since 1.6.0)
   - use `IntervalCollectionObserver` and `ObservableIntervalCollection` to keep your database (storage) up-to-date

docs/Streaming.md

@@ -0,0 +1,21 @@
+# Streaming the `IntervalTree`
+
+When iterating over a Java `Collection`, it is pretty common to do so
+by using an `Iterator`. There are many discussion on how to iterate over
+an amount of items, e.g.,
+[1](https://stackoverflow.com/questions/31210791/iterator-versus-stream-of-java-8),
+[2](http://blog.takipi.com/benchmark-how-java-8-lambdas-and-streams-can-make-your-code-5-times-slower/).
+
+Besides the nicely readable code, `Streams` may have positive or negative
+impact on the performance of someones application. Until version `1.6.3`
+the `IntervalTree` provided "only" a `stream()` and `iterator()`, as needed by
+the `Collection` interface, whereby the `stream()` implementation was
+based on the `iterator()`. Both of these methods enabled the user to iterate
+over the full content of the `IntervalTree`.
+
+Since `1.6.3` the `IntervalTree` also provides a `overlapStream()` method,
+which "pushes" the overlapping intervals through the stream.
+
+## Further Information
+
+- [Processing Data with Java SE 8 Streams](http://www.oracle.com/technetwork/articles/java/ma14-java-se-8-streams-2177646.html)

src/com/brein/time/timeintervals/indexes/IntervalTree.java

@@ -81,6 +81,14 @@ public Stream<IInterval> overlapStream(final IInterval query) {
         }
     }
 
+    public Collection<IInterval> overlap(final IInterval query) {
+        if (this.root == null) {
+            return Collections.emptyList();
+        } else {
+            return _overlap(this.root, query).collect(Collectors.toList());
+        }
+    }
+
     protected Stream<IInterval> _overlap(final IntervalTreeNode node, final IInterval query) {
 
         if (node == null) {
@@ -113,14 +121,6 @@ protected Stream<IInterval> _overlap(final IntervalTreeNode node, final IInterva
         return Stream.of(nodeStream, leftNodeStream, rightNodeStream).flatMap(s -> s);
     }
 
-    public Collection<IInterval> overlap(final IInterval query) {
-        if (this.root == null) {
-            return Collections.emptyList();
-        } else {
-            return _overlap(this.root, query).collect(Collectors.toList());
-        }
-    }
-
     public IntervalTree insert(final IInterval interval) {
         add(interval);
         return this;