sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ama...@apache.org
Subject [sis] 06/45: doc(Utility): write about stream decoration classes
Date Tue, 12 Nov 2019 16:44:33 GMT
This is an automated email from the ASF dual-hosted git repository.

amanin pushed a commit to branch refactor/sql-store
in repository https://gitbox.apache.org/repos/asf/sis.git

commit 4ade44b649515484821633eace486e40550dd4a0
Author: Alexis Manin <amanin@apache.org>
AuthorDate: Mon Aug 26 14:43:50 2019 +0200

    doc(Utility): write about stream decoration classes
---
 .../sis/internal/util/BaseStreamDecoration.java    | 42 +++++++++++++++++--
 .../sis/internal/util/DoubleStreamDecoration.java  | 23 +++++++++++
 .../apache/sis/internal/util/StreamDecoration.java | 48 ++++++++++++++++------
 3 files changed, 98 insertions(+), 15 deletions(-)

diff --git a/core/sis-utility/src/main/java/org/apache/sis/internal/util/BaseStreamDecoration.java
b/core/sis-utility/src/main/java/org/apache/sis/internal/util/BaseStreamDecoration.java
index f20e32d..980aac1 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/internal/util/BaseStreamDecoration.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/internal/util/BaseStreamDecoration.java
@@ -1,9 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.apache.sis.internal.util;
 
 import java.util.Iterator;
 import java.util.Spliterator;
 import java.util.stream.BaseStream;
+import javax.validation.constraints.NotNull;
 
+/**
+ * Delegates operations to an underlying stream provided by {@link #createDecoratedStream()}.
Allows for custom logic
+ * decoration. See {@link StreamDecoration} for further details.
+ *
+ * @param <T> Type of values contained in the stream, as defined in {@link BaseStream}
+ * @param <S> Type of stream implementation, as defined in {@link BaseStream}
+ *
+ *  @since 1.0
+ *
+ * @author Alexis Manin (Geomatys)
+ */
 public abstract class BaseStreamDecoration<T, S extends BaseStream<T, S>> implements
BaseStream<T, S> {
 
     private S decorated;
@@ -12,9 +40,10 @@ public abstract class BaseStreamDecoration<T, S extends BaseStream<T,
S>> implem
 
     /**
      * Get previously created wrapped stream, or create it if never done.
-     * @return
+     * @return The stream containing actual data.
      */
-    protected final S getOrCreate() {
+
+    protected final @NotNull S getOrCreate() {
         if (closed) throw new IllegalStateException("Stream has already been closed.");
         if (decorated == null) {
             decorated = createDecoratedStream();
@@ -23,7 +52,14 @@ public abstract class BaseStreamDecoration<T, S extends BaseStream<T,
S>> implem
         return decorated;
     }
 
-    protected abstract S createDecoratedStream();
+    /**
+     * Operation that creates underlying stream to delegate operations to as a last resort.
Note that sub-classes should
+     * never call this method. Instead, please use {@link #getOrCreate()}, ensuring that
decorated stream is created
+     * only once, then potentially re-used multiple times.
+     *
+     * @return A new, non-consumed stream to delegate actions to.
+     */
+    protected abstract @NotNull S createDecoratedStream();
 
     @Override
     public void close() {
diff --git a/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleStreamDecoration.java
b/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleStreamDecoration.java
index 1215169..22e0fe1 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleStreamDecoration.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/internal/util/DoubleStreamDecoration.java
@@ -1,3 +1,19 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.apache.sis.internal.util;
 
 import java.util.DoubleSummaryStatistics;
@@ -19,6 +35,13 @@ import java.util.stream.IntStream;
 import java.util.stream.LongStream;
 import java.util.stream.Stream;
 
+/**
+ * A specialization of {@link StreamDecoration} for {@link DoubleStream streams of double
value}.
+ *
+ * @since 1.0
+ *
+ * @author Alexis Manin (Geomatys)
+ */
 public abstract class DoubleStreamDecoration extends BaseStreamDecoration<Double, DoubleStream>
implements DoubleStream {
 
     @Override
diff --git a/core/sis-utility/src/main/java/org/apache/sis/internal/util/StreamDecoration.java
b/core/sis-utility/src/main/java/org/apache/sis/internal/util/StreamDecoration.java
index 45cd0f8..75f143f 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/internal/util/StreamDecoration.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/internal/util/StreamDecoration.java
@@ -1,3 +1,19 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.apache.sis.internal.util;
 
 import java.util.Comparator;
@@ -19,6 +35,26 @@ import java.util.stream.IntStream;
 import java.util.stream.LongStream;
 import java.util.stream.Stream;
 
+/**
+ * Allows for delegation for a subset of behaviors of a stream to a custom component.
+ * How it works: This class is simply delegating all {@link Stream} interface operations
to the one provided by
+ * {@link #createDecoratedStream()} implementation. It allows implementations to short-circuit
a certain number of
+ * methods to provide their own solution. For example, if you've got a streamable dataset
whose count can be provided
+ * efficiently by a third-party tool (typically COUNT query on SQL databases), you can create
a {@link StreamDecoration}
+ * with an overrided count method running the count query instead of counting elements of
the stream manually.
+ *
+ * Another exemple would be intermediate operations. Let's keep SQL queries as example. If
you create a stream executing
+ * a statement on terminal operations, you could override {@link Stream#limit(long)} and
{@link Stream#skip(long)}
+ * methods to set LIMIT and OFFSET criterias in an SQL query.
+ *
+ * For an advanced example, you can look at {@link org.apache.sis.internal.sql.feature.StreamSQL}
class.
+ *
+ * @param <T> The type of objects contained in the stream, as specified in {@link Stream}
interface.
+ *
+ * @since 1.0
+ *
+ * @author Alexis Manin (Geomatys)
+ */
 public abstract class StreamDecoration<T> extends BaseStreamDecoration<T, Stream<T>>
implements Stream<T> {
 
     @Override
@@ -96,18 +132,6 @@ public abstract class StreamDecoration<T> extends BaseStreamDecoration<T,
Stream
         return getOrCreate().skip(n);
     }
 
-/*
-    @Override
-    public Stream<T> takeWhile(Predicate<? super T> predicate) {
-        return getDecoratedStream().takeWhile(predicate);
-    }
-
-    @Override
-    public Stream<T> dropWhile(Predicate<? super T> predicate) {
-        return getDecoratedStream().dropWhile(predicate);
-    }
-*/
-
     @Override
     public void forEach(Consumer<? super T> action) {
         getOrCreate().forEach(action);


Mime
View raw message