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 a1a7d3abecbd614a9e21f7590538c3a1fcc20829 Author: Alexis Manin <[email protected]> AuthorDate: Tue Aug 27 10:05:47 2019 +0200 doc(SQL-Store): minor javadoc addition for stream delegation applied to sql queries. --- .../apache/sis/internal/sql/feature/StreamSQL.java | 52 ++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/storage/sis-sqlstore/src/main/java/org/apache/sis/internal/sql/feature/StreamSQL.java b/storage/sis-sqlstore/src/main/java/org/apache/sis/internal/sql/feature/StreamSQL.java index c93798b..1a59655 100644 --- a/storage/sis-sqlstore/src/main/java/org/apache/sis/internal/sql/feature/StreamSQL.java +++ b/storage/sis-sqlstore/src/main/java/org/apache/sis/internal/sql/feature/StreamSQL.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.sql.feature; import java.sql.Connection; @@ -11,6 +27,7 @@ import java.util.function.DoubleConsumer; import java.util.function.DoubleFunction; import java.util.function.DoubleUnaryOperator; import java.util.function.Function; +import java.util.function.Predicate; import java.util.function.Supplier; import java.util.function.ToDoubleFunction; import java.util.function.ToIntFunction; @@ -28,6 +45,21 @@ import org.apache.sis.internal.util.StreamDecoration; import org.apache.sis.storage.DataStoreException; import org.apache.sis.util.collection.BackingStoreException; +import static org.apache.sis.util.ArgumentChecks.ensureNonNull; + +/** + * Manages query lifecycle and optimizations. Operations like {@link #count()}, {@link #distinct()}, {@link #skip(long)} + * and {@link #limit(long)} are delegated to underlying SQL database. This class consistently propagate optimisation + * strategies through streams obtained using {@link #map(Function)}, {@link #mapToDouble(ToDoubleFunction)} and + * {@link #peek(Consumer)} operations. However, for result consistency, no optimization is stacked once either + * {@link #filter(Predicate)} or {@link #flatMap(Function)} operations are called, as they modify browing flow (the + * count of stream elements is not bound 1 to 1 to query result rows). + * + * @since 1.0 + * + * @author Alexis Manin (Geomatys) + * + */ class StreamSQL extends StreamDecoration<Feature> { final Features.Builder queryBuilder; @@ -144,7 +176,14 @@ class StreamSQL extends StreamDecoration<Feature> { .onClose(() -> queryBuilder.parent.closeRef(connectionRef)); } + /** + * Transform a callable into supplier by catching any potential verified exception and rethrowing it as a {@link BackingStoreException}. + * @param generator The callable to use in a non-verified error context. Must not be null. + * @param <T> The return type of input callable. + * @return A supplier that delegates work to given callable, wrapping any verified exception in the process. + */ private static <T> Supplier<T> uncheck(final Callable<T> generator) { + ensureNonNull("Generator", generator); return () -> { try { return generator.call(); @@ -156,6 +195,13 @@ class StreamSQL extends StreamDecoration<Feature> { }; } + /** + * Describes a stream on which a {@link Stream#map(Function) mapping operation} has been set. It serves to delegate + * optimizable operation to underlying sql stream (which could be an indirect parent). + * + * @param <I> Type of object received as input of mapping operation. + * @param <O> Return type of mapping operation. + */ private static class MappedStream<I, O> extends StreamDecoration<O> { private final Function<? super I, ? extends O> mapper; private Stream<I> source; @@ -239,6 +285,12 @@ class StreamSQL extends StreamDecoration<Feature> { } } + /** + * Same purpose as {@link MappedStream}, but specialized for {@link Stream#mapToDouble(ToDoubleFunction) double mapping} + * operations. + * + * @param <T> Type of objects contained in source stream (before double mapping). + */ private static class ToDoubleStream<T> extends DoubleStreamDecoration { Stream<T> source;
