From 0f73283c0fb87979f383c4b7f358117c4ebcc034 Mon Sep 17 00:00:00 2001 From: David Karnok Date: Mon, 19 Feb 2018 21:41:01 +0100 Subject: [PATCH] 2.x: Add finite requirement to various collector operators JavaDoc (#5856) * 2.x: Add finite requirement to various collector operators * Updated wording to "accumulator object" --- src/main/java/io/reactivex/Flowable.java | 96 ++++++++++++++++++---- src/main/java/io/reactivex/Observable.java | 95 +++++++++++++++++---- 2 files changed, 158 insertions(+), 33 deletions(-) diff --git a/src/main/java/io/reactivex/Flowable.java b/src/main/java/io/reactivex/Flowable.java index f906f89c20..a80732ef0d 100644 --- a/src/main/java/io/reactivex/Flowable.java +++ b/src/main/java/io/reactivex/Flowable.java @@ -6706,12 +6706,16 @@ public final Flowable cast(final Class clazz) { } /** - * Collects items emitted by the source Publisher into a single mutable data structure and returns + * Collects items emitted by the finite source Publisher into a single mutable data structure and returns * a Single that emits this structure. *

* *

* This is a simplified version of {@code reduce} that does not need to return the state on each pass. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
This operator does not support backpressure because by intent it will receive all values and reduce @@ -6740,12 +6744,16 @@ public final Single collect(Callable initialItemSupplier, Bi } /** - * Collects items emitted by the source Publisher into a single mutable data structure and returns + * Collects items emitted by the finite source Publisher into a single mutable data structure and returns * a Single that emits this structure. *

* *

* This is a simplified version of {@code reduce} that does not need to return the state on each pass. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
This operator does not support backpressure because by intent it will receive all values and reduce @@ -11148,7 +11156,7 @@ public final Flowable rebatchRequests(int n) { /** * Returns a Maybe that applies a specified accumulator function to the first item emitted by a source * Publisher, then feeds the result of that function along with the second item emitted by the source - * Publisher into the same function, and so on until all items have been emitted by the source Publisher, + * Publisher into the same function, and so on until all items have been emitted by the finite source Publisher, * and emits the final result from the final call to your function as its sole item. *

* If the source is empty, a {@code NoSuchElementException} is signalled. @@ -11158,6 +11166,10 @@ public final Flowable rebatchRequests(int n) { * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate," * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method * that does a similar operation on lists. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure of its downstream consumer and consumes the @@ -11186,7 +11198,7 @@ public final Maybe reduce(BiFunction reducer) { * Returns a Single that applies a specified accumulator function to the first item emitted by a source * Publisher and a specified seed value, then feeds the result of that function along with the second item * emitted by a Publisher into the same function, and so on until all items have been emitted by the - * source Publisher, emitting the final result from the final call to your function as its sole item. + * finite source Publisher, emitting the final result from the final call to your function as its sole item. *

* *

@@ -11211,6 +11223,10 @@ public final Maybe reduce(BiFunction reducer) { * * source.reduceWith(() -> new ArrayList<>(), (list, item) -> list.add(item))); * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure of its downstream consumer and consumes the @@ -11244,7 +11260,7 @@ public final Single reduce(R seed, BiFunction reducer) { * Returns a Single that applies a specified accumulator function to the first item emitted by a source * Publisher and a seed value derived from calling a specified seedSupplier, then feeds the result * of that function along with the second item emitted by a Publisher into the same function, and so on until - * all items have been emitted by the source Publisher, emitting the final result from the final call to your + * all items have been emitted by the finite source Publisher, emitting the final result from the final call to your * function as its sole item. *

* @@ -11252,6 +11268,10 @@ public final Single reduce(R seed, BiFunction reducer) { * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate," * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method * that does a similar operation on lists. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure of its downstream consumer and consumes the @@ -15175,12 +15195,16 @@ public final > Single toList(Callable coll } /** - * Returns a Single that emits a single HashMap containing all items emitted by the source Publisher, + * Returns a Single that emits a single HashMap containing all items emitted by the finite source Publisher, * mapped by the keys returned by a specified {@code keySelector} function. *

* *

* If more than one source item maps to the same key, the HashMap will contain the latest of those items. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15206,12 +15230,16 @@ public final Single> toMap(final Function /** * Returns a Single that emits a single HashMap containing values corresponding to items emitted by the - * source Publisher, mapped by the keys returned by a specified {@code keySelector} function. + * finite source Publisher, mapped by the keys returned by a specified {@code keySelector} function. *

* *

* If more than one source item maps to the same key, the HashMap will contain a single entry that * corresponds to the latest of those items. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15241,9 +15269,13 @@ public final Single> toMap(final Function * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15277,9 +15309,13 @@ public final Single> toMap(final Function * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
This operator does not support backpressure as by intent it is requesting and buffering everything.
@@ -15306,10 +15342,14 @@ public final Single>> toMultimap(Function * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15340,9 +15380,13 @@ public final Single>> toMultimap(Function * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15383,9 +15427,13 @@ public final Single>> toMultimap( /** * Returns a Single that emits a single Map, returned by a specified {@code mapFactory} function, that * contains an ArrayList of values, extracted by a specified {@code valueSelector} function from items - * emitted by the source Publisher and keyed by the {@code keySelector} function. + * emitted by the finite source Publisher and keyed by the {@code keySelector} function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15437,7 +15485,7 @@ public final Observable toObservable() { } /** - * Returns a Single that emits a list that contains the items emitted by the source Publisher, in a + * Returns a Single that emits a list that contains the items emitted by the finite source Publisher, in a * sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all * other items in the sequence. * @@ -15446,6 +15494,10 @@ public final Observable toObservable() { * sequence is terminated with a {@link ClassCastException}. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15465,10 +15517,14 @@ public final Single> toSortedList() { } /** - * Returns a Single that emits a list that contains the items emitted by the source Publisher, in a + * Returns a Single that emits a list that contains the items emitted by the finite source Publisher, in a * sorted order based on a specified comparison function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15493,10 +15549,14 @@ public final Single> toSortedList(final Comparator comparator } /** - * Returns a Single that emits a list that contains the items emitted by the source Publisher, in a + * Returns a Single that emits a list that contains the items emitted by the finite source Publisher, in a * sorted order based on a specified comparison function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an @@ -15524,7 +15584,7 @@ public final Single> toSortedList(final Comparator comparator } /** - * Returns a Flowable that emits a list that contains the items emitted by the source Publisher, in a + * Returns a Flowable that emits a list that contains the items emitted by the finite source Publisher, in a * sorted order. Each item emitted by the Publisher must implement {@link Comparable} with respect to all * other items in the sequence. * @@ -15533,6 +15593,10 @@ public final Single> toSortedList(final Comparator comparator * sequence is terminated with a {@link ClassCastException}. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the source {@code Publisher} in an diff --git a/src/main/java/io/reactivex/Observable.java b/src/main/java/io/reactivex/Observable.java index ebd48d6537..0d8fd01825 100644 --- a/src/main/java/io/reactivex/Observable.java +++ b/src/main/java/io/reactivex/Observable.java @@ -6116,12 +6116,16 @@ public final Observable cast(final Class clazz) { } /** - * Collects items emitted by the source ObservableSource into a single mutable data structure and returns + * Collects items emitted by the finite source ObservableSource into a single mutable data structure and returns * a Single that emits this structure. *

* *

* This is a simplified version of {@code reduce} that does not need to return the state on each pass. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code collect} does not operate by default on a particular {@link Scheduler}.
@@ -6146,12 +6150,16 @@ public final Single collect(Callable initialValueSupplier, B } /** - * Collects items emitted by the source ObservableSource into a single mutable data structure and returns + * Collects items emitted by the finite source ObservableSource into a single mutable data structure and returns * a Single that emits this structure. *

* *

* This is a simplified version of {@code reduce} that does not need to return the state on each pass. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code collectInto} does not operate by default on a particular {@link Scheduler}.
@@ -9428,7 +9436,7 @@ public final Observable publish(Function, ? extends /** * Returns a Maybe that applies a specified accumulator function to the first item emitted by a source * ObservableSource, then feeds the result of that function along with the second item emitted by the source - * ObservableSource into the same function, and so on until all items have been emitted by the source ObservableSource, + * ObservableSource into the same function, and so on until all items have been emitted by the finite source ObservableSource, * and emits the final result from the final call to your function as its sole item. *

* @@ -9436,6 +9444,10 @@ public final Observable publish(Function, ? extends * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate," * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method * that does a similar operation on lists. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code reduce} does not operate by default on a particular {@link Scheduler}.
@@ -9460,7 +9472,7 @@ public final Maybe reduce(BiFunction reducer) { * Returns a Single that applies a specified accumulator function to the first item emitted by a source * ObservableSource and a specified seed value, then feeds the result of that function along with the second item * emitted by an ObservableSource into the same function, and so on until all items have been emitted by the - * source ObservableSource, emitting the final result from the final call to your function as its sole item. + * finite source ObservableSource, emitting the final result from the final call to your function as its sole item. *

* *

@@ -9485,6 +9497,10 @@ public final Maybe reduce(BiFunction reducer) { * * source.reduceWith(() -> new ArrayList<>(), (list, item) -> list.add(item))); * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code reduce} does not operate by default on a particular {@link Scheduler}.
@@ -9514,7 +9530,7 @@ public final Single reduce(R seed, BiFunction reducer) { * Returns a Single that applies a specified accumulator function to the first item emitted by a source * ObservableSource and a seed value derived from calling a specified seedSupplier, then feeds the result * of that function along with the second item emitted by an ObservableSource into the same function, - * and so on until all items have been emitted by the source ObservableSource, emitting the final result + * and so on until all items have been emitted by the finite source ObservableSource, emitting the final result * from the final call to your function as its sole item. *

* @@ -9522,6 +9538,10 @@ public final Single reduce(R seed, BiFunction reducer) { * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate," * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method * that does a similar operation on lists. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code reduceWith} does not operate by default on a particular {@link Scheduler}.
@@ -12916,12 +12936,17 @@ public final > Single toList(Callable coll } /** - * Returns a Single that emits a single HashMap containing all items emitted by the source ObservableSource, - * mapped by the keys returned by a specified {@code keySelector} function. + * Returns a Single that emits a single HashMap containing all items emitted by the + * finite source ObservableSource, mapped by the keys returned by a specified + * {@code keySelector} function. *

* *

* If more than one source item maps to the same key, the HashMap will contain the latest of those items. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toMap} does not operate by default on a particular {@link Scheduler}.
@@ -12943,12 +12968,16 @@ public final Single> toMap(final Function /** * Returns a Single that emits a single HashMap containing values corresponding to items emitted by the - * source ObservableSource, mapped by the keys returned by a specified {@code keySelector} function. + * finite source ObservableSource, mapped by the keys returned by a specified {@code keySelector} function. *

* *

* If more than one source item maps to the same key, the HashMap will contain a single entry that * corresponds to the latest of those items. + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toMap} does not operate by default on a particular {@link Scheduler}.
@@ -12976,9 +13005,13 @@ public final Single> toMap( /** * Returns a Single that emits a single Map, returned by a specified {@code mapFactory} function, that - * contains keys and values extracted from the items emitted by the source ObservableSource. + * contains keys and values extracted from the items emitted by the finite source ObservableSource. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toMap} does not operate by default on a particular {@link Scheduler}.
@@ -13010,9 +13043,13 @@ public final Single> toMap( /** * Returns a Single that emits a single HashMap that contains an ArrayList of items emitted by the - * source ObservableSource keyed by a specified {@code keySelector} function. + * finite source ObservableSource keyed by a specified {@code keySelector} function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
@@ -13037,10 +13074,14 @@ public final Single>> toMultimap(Function * + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
@@ -13106,9 +13147,13 @@ public final Single>> toMultimap( /** * Returns a Single that emits a single Map, returned by a specified {@code mapFactory} function, that * contains an ArrayList of values, extracted by a specified {@code valueSelector} function from items - * emitted by the source ObservableSource and keyed by the {@code keySelector} function. + * emitted by the finite source ObservableSource and keyed by the {@code keySelector} function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
@@ -13193,7 +13238,7 @@ public final Flowable toFlowable(BackpressureStrategy strategy) { } /** - * Returns a Single that emits a list that contains the items emitted by the source ObservableSource, in a + * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all * other items in the sequence. * @@ -13202,6 +13247,10 @@ public final Flowable toFlowable(BackpressureStrategy strategy) { * sequence is terminated with a {@link ClassCastException}. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
@@ -13217,10 +13266,14 @@ public final Single> toSortedList() { } /** - * Returns a Single that emits a list that contains the items emitted by the source ObservableSource, in a + * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a * sorted order based on a specified comparison function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
@@ -13241,10 +13294,14 @@ public final Single> toSortedList(final Comparator comparator } /** - * Returns a Single that emits a list that contains the items emitted by the source ObservableSource, in a + * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a * sorted order based on a specified comparison function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
@@ -13268,7 +13325,7 @@ public final Single> toSortedList(final Comparator comparator } /** - * Returns a Single that emits a list that contains the items emitted by the source ObservableSource, in a + * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all * other items in the sequence. * @@ -13277,6 +13334,10 @@ public final Single> toSortedList(final Comparator comparator * sequence is terminated with a {@link ClassCastException}. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.