sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ama...@apache.org
Subject [sis] 07/45: doc(SQL-Store): minor javadoc addition for stream delegation applied to sql queries.
Date Tue, 12 Nov 2019 16:44:34 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 a1a7d3abecbd614a9e21f7590538c3a1fcc20829
Author: Alexis Manin <amanin@apache.org>
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;


Mime
View raw message