You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by su...@apache.org on 2020/10/23 23:13:12 UTC
[groovy] branch GROOVY-8258 updated: GROOVY-8258: add javadoc
This is an automated email from the ASF dual-hosted git repository.
sunlan pushed a commit to branch GROOVY-8258
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/GROOVY-8258 by this push:
new 3c64cd2 GROOVY-8258: add javadoc
3c64cd2 is described below
commit 3c64cd2a35f0a65034356d92f6ec64bd2f5ffbef
Author: Daniel Sun <su...@apache.org>
AuthorDate: Sat Oct 24 07:13:02 2020 +0800
GROOVY-8258: add javadoc
---
.../groovy/ginq/provider/collection/Queryable.java | 226 +++++++++++++++++++++
.../provider/collection/QueryableCollection.java | 1 -
2 files changed, 226 insertions(+), 1 deletion(-)
diff --git a/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/Queryable.java b/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/Queryable.java
index c099b41..2231051 100644
--- a/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/Queryable.java
+++ b/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/Queryable.java
@@ -37,77 +37,303 @@ import java.util.stream.Stream;
*/
@Internal
public interface Queryable<T> {
+ /**
+ * Factory method to create {@link Queryable} instance
+ *
+ * @param iterable iterable object, e.g. {@link List}
+ * @param <T> the type of element
+ * @return the {@link Queryable} instance
+ * @since 4.0.0
+ */
static <T> Queryable<T> from(Iterable<T> iterable) {
return new QueryableCollection<>(iterable);
}
+ /**
+ * Factory method to create {@link Queryable} instance
+ *
+ * @param queryable queryable object
+ * @param <T> the type of element
+ * @return the {@link Queryable} instance
+ * @since 4.0.0
+ */
static <T> Queryable<T> from(Queryable<T> queryable) {
return new QueryableCollection<>(queryable);
}
+ /**
+ * Factory method to create {@link Queryable} instance
+ *
+ * @param sourceStream stream object
+ * @param <T> the type of element
+ * @return the {@link Queryable} instance
+ * @since 4.0.0
+ */
static <T> Queryable<T> from(Stream<? extends T> sourceStream) {
return new QueryableCollection<>(sourceStream);
}
+ /**
+ * Inner join another {@link Queryable} instance
+ *
+ * @param queryable another {@link Queryable} instance
+ * @param joiner join condition
+ * @param <U> the type of element from another {@link Queryable} instance
+ * @return the join result
+ * @since 4.0.0
+ */
<U> Queryable<Tuple2<T, U>> innerJoin(Queryable<? extends U> queryable, BiPredicate<? super T, ? super U> joiner);
+ /**
+ * Left join another {@link Queryable} instance
+ *
+ * @param queryable another {@link Queryable} instance
+ * @param joiner join condition
+ * @param <U> the type of element from another {@link Queryable} instance
+ * @return the join result
+ * @since 4.0.0
+ */
<U> Queryable<Tuple2<T, U>> leftJoin(Queryable<? extends U> queryable, BiPredicate<? super T, ? super U> joiner);
+ /**
+ * Right join another {@link Queryable} instance
+ *
+ * @param queryable another {@link Queryable} instance
+ * @param joiner join condition
+ * @param <U> the type of element from another {@link Queryable} instance
+ * @return the join result
+ * @since 4.0.0
+ */
<U> Queryable<Tuple2<T, U>> rightJoin(Queryable<? extends U> queryable, BiPredicate<? super T, ? super U> joiner);
+ /**
+ * Full join another {@link Queryable} instance
+ *
+ * @param queryable another {@link Queryable} instance
+ * @param joiner join condition
+ * @param <U> the type of element from another {@link Queryable} instance
+ * @return the join result
+ * @since 4.0.0
+ */
default <U> Queryable<Tuple2<T, U>> fullJoin(Queryable<? extends U> queryable, BiPredicate<? super T, ? super U> joiner) {
Queryable<Tuple2<T, U>> lj = this.leftJoin(queryable, joiner);
Queryable<Tuple2<T, U>> rj = this.rightJoin(queryable, joiner);
return lj.union(rj);
}
+ /**
+ * Cross join another {@link Queryable} instance
+ *
+ * @param queryable another {@link Queryable} instance
+ * @param <U> the type of element from another {@link Queryable} instance
+ * @return the join result
+ * @since 4.0.0
+ */
<U> Queryable<Tuple2<T, U>> crossJoin(Queryable<? extends U> queryable);
+ /**
+ * Filter {@link Queryable} instance via some condition
+ *
+ * @param filter the filter condition
+ * @return filter result
+ * @since 4.0.0
+ */
Queryable<T> where(Predicate<? super T> filter);
+ /**
+ * Group by {@link Queryable} instance
+ *
+ * @param classifier the classifier for group by
+ * @param having the filter condition
+ * @param <K> the type of group key
+ * @return the result of group by
+ * @since 4.0.0
+ */
<K> Queryable<Tuple2<K, Queryable<T>>> groupBy(Function<? super T, ? extends K> classifier, Predicate<? super Tuple2<? extends K, Queryable<? extends T>>> having);
+ /**
+ * Group by {@link Queryable} instance without {@code having} clause
+ *
+ * @param classifier the classifier for group by
+ * @param <K> the type of group key
+ * @return the result of group by
+ * @since 4.0.0
+ */
default <K> Queryable<Tuple2<K, Queryable<T>>> groupBy(Function<? super T, ? extends K> classifier) {
return groupBy(classifier, null);
}
+ /**
+ * Sort {@link Queryable} instance
+ *
+ * @param orders the order rules for sorting
+ * @param <U> the type of field to sort
+ * @return the result of order by
+ * @since 4.0.0
+ */
<U extends Comparable<? super U>> Queryable<T> orderBy(Order<? super T, ? extends U>... orders);
+ /**
+ * Paginate {@link Queryable} instance, similar to MySQL's {@code limit}
+ *
+ * @param offset the start position
+ * @param size the size to take
+ * @return the result of paginating
+ * @since 4.0.0
+ */
Queryable<T> limit(long offset, long size);
+ /**
+ * Paginate {@link Queryable} instance, similar to MySQL's {@code limit}
+ *
+ * @param size the size to take
+ * @return the result of paginating
+ * @since 4.0.0
+ */
default Queryable<T> limit(long size) {
return limit(0, size);
}
+ /**
+ * Project {@link Queryable} instance
+ *
+ * @param mapper project fields
+ * @param <U> the type of project record
+ * @return the result of projecting
+ * @since 4.0.0
+ */
<U> Queryable<U> select(Function<? super T, ? extends U> mapper);
+ /**
+ * Eliminate duplicated records
+ *
+ * @return the distinct result
+ * @since 4.0.0
+ */
Queryable<T> distinct();
+ /**
+ * Union another {@link Queryable} instance
+ *
+ * @param queryable the other {@link Queryable} instance
+ * @return the union result
+ * @since 4.0.0
+ */
default Queryable<T> union(Queryable<? extends T> queryable) {
return this.unionAll(queryable).distinct();
}
+ /**
+ * Union all another {@link Queryable} instance
+ *
+ * @param queryable the other {@link Queryable} instance
+ * @return the union all result
+ * @since 4.0.0
+ */
Queryable<T> unionAll(Queryable<? extends T> queryable);
+ /**
+ * Intersect another {@link Queryable} instance
+ *
+ * @param queryable the other {@link Queryable} instance
+ * @return the intersect result
+ * @since 4.0.0
+ */
Queryable<T> intersect(Queryable<? extends T> queryable);
+ /**
+ * Minus another {@link Queryable} instance
+ *
+ * @param queryable the other {@link Queryable} instance
+ * @return the minus result
+ * @since 4.0.0
+ */
Queryable<T> minus(Queryable<? extends T> queryable);
+ /**
+ * Convert the {@link Queryable} instance to {@link List<T>} instance
+ *
+ * @return the result list
+ * @since 4.0.0
+ */
List<T> toList();
+ /**
+ * Create {@link Stream<T>} object for the {@link Queryable} instance
+ *
+ * @return the result stream
+ * @since 4.0.0
+ */
default Stream<T> stream() {
return toList().stream();
}
// Built-in aggregate functions {
+ /**
+ * Aggreate function {@code count}, similar to SQL's {@code count}
+ *
+ * @return count result
+ * @since 4.0.0
+ */
Long count();
+
+ /**
+ * Aggregate function {@code count}, similar to SQL's {@code count}
+ * Note: if the chosen field is {@code null}, the field will not be counted
+ *
+ * @param mapper choose the field to count
+ * @return count result
+ * @since 4.0.0
+ */
<U> Long count(Function<? super T, ? extends U> mapper);
+
+ /**
+ * Aggregate function {@code sum}, similar to SQL's {@code sum}
+ *
+ * @param mapper choose the field to sum
+ * @return sum result
+ * @since 4.0.0
+ */
BigDecimal sum(Function<? super T, ? extends Number> mapper);
+
+ /**
+ * Aggregate function {@code min}, similar to SQL's {@code min}
+ *
+ * @param mapper choose the field to find the minimum
+ * @param <U> the field type
+ * @return min result
+ * @since 4.0.0
+ */
<U extends Comparable<? super U>> U min(Function<? super T, ? extends U> mapper);
+
+ /**
+ * Aggregate function {@code max}, similar to SQL's {@code max}
+ *
+ * @param mapper choose the field to find the maximum
+ * @param <U> the field type
+ * @return min result
+ * @since 4.0.0
+ */
<U extends Comparable<? super U>> U max(Function<? super T, ? extends U> mapper);
+
+ /**
+ * The most powerful aggregate function in GINQ, it will receive the grouped result({@link Queryable} instance) and apply any processing
+ *
+ * @param mapper map the grouped result({@link Queryable} instance) to aggregate result
+ * @param <U> the type aggregate result
+ * @return aggregate result
+ * @since 4.0.0
+ */
<U> U agg(Function<? super Queryable<? extends T>, ? extends U> mapper);
// } Built-in aggregate functions
+ /**
+ * Represents an order rule
+ *
+ * @param <T> the type of element from {@link Queryable} instance
+ * @param <U> the type of field to sort
+ * @since 4.0.0
+ */
class Order<T, U extends Comparable<? super U>> {
private final Function<? super T, ? extends U> keyExtractor;
private final boolean asc;
diff --git a/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/QueryableCollection.java b/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/QueryableCollection.java
index 8d2bad4..7fd7fc8 100644
--- a/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/QueryableCollection.java
+++ b/subprojects/groovy-ginq/src/main/groovy/org/apache/groovy/ginq/provider/collection/QueryableCollection.java
@@ -62,7 +62,6 @@ class QueryableCollection<T> implements Queryable<T>, Serializable {
this((Iterable<T>) toIterable(sourceStream));
}
- // @Override
public Iterator<T> iterator() {
return sourceIterable.iterator();
}