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 <[email protected]> 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);
