streamsupport Files

NEW
---

 - JDK-8238286: Add new flatMap stream operation multiMap (Java 16)

 - JDK-8180352: Add Stream.toList() method (Java 16)

 - JDK-8234131: Misc. changes imported from jsr166 CVS 2021-01

 - JDK-8156071: List.of: reduce array copying during creation

 - JDK-8255150: Add utility methods to check long indexes and ranges

 - JDK-8238669: Long.divideUnsigned is slow for certain values

 - JDK-8254350: CompletableFuture.get may swallow InterruptedException

 - JDK-8259796: Timed CompletableFuture.get swallows InterruptedException

 - JDK-8254973: ThreadPerTaskExecutor does not throw NPE in #execute

 - JDK-8250240: Address use of default constructors in java.util.concurrent

 - JDK-8247402: Map::compute Javadoc confusing implementation requirements

 - JDK-8228615: Optional.empty doc should suggest using isEmpty

 - JDK-8245970: IntStream.reduce Javadoc should not mention average

 - JDK-8243655: Map.replace javadoc code snippet typo

 - JDK-8253066: Typo in Stream.mapMulti

 - JDK-8259816: Typo in java.util.stream package description

 - Add Loom's CompletableFuture.completed (Project Loom)

 - Completed Java 16 port



GENERAL
-------

 - The provided Jar files are compiled for Java 6 (Bytecode version 50).
   You'll need Retrolambda (https://github.com/orfjackal/retrolambda)
   to build the core streamsupport.jar from its sources

 - To create a Stream from a java.util Collection use the static
   j8.u.s.StreamSupport methods StreamSupport#stream(Collection),
   or, for parallel Streams, StreamSupport#parallelStream(Collection)

 - The static methods from interface j.u.s.Stream are located in
   j8.u.s.RefStreams which also contains the new Java 9 j.u.s.Stream
   default methods.

 - As of release 1.4, the former single streamsupport.jar has been
   partitioned into a core streamsupport.jar and 3 additional optional
   components:

   * streamsupport-cfuture (CompletableFuture API)
   * streamsupport-atomic  (j8.u.c.atomic package)
   * streamsupport-flow    (Java 9 Flow API)

   All of them have a dependency on the core streamsupport.jar

 - As of release 1.5, a new optional component "streamsupport-literal"
   that contains the implementation for JEP 269 (Java 9) has been added.
   See JEP 269: Convenience Factory Methods for Collections
   http://openjdk.java.net/jeps/269

   * streamsupport-literal (Java 9 Collections factory methods)

   From release 1.5.3 onwards streamsupport-literal can be used without
   any dependencies.

 - As of release 1.5.3 streamsupport detects when it is running on a
   stream enabled Android 7+ device and automatically delegates to the
   Android Spliterators (contributed by Tobias Thierer, ticket#240).

   This feature can be disabled by setting the system property
   "java8.util.Spliterators.jre.delegation.enabled" to false.

 - Release 1.6.0 introduces some new methods from the Java 10 API

 - As of release 1.6.0 "streamsupport-literal" has been merged into the
   core streamsupport.jar component in order to make the new Collectors
   for unmodifiable Lists, Sets, and Maps (JDK-8184690) possible.

   streamsupport-literal-1.6.0 is still available as a standalone component
   without any dependencies but has been discontinued in release 1.6.1

 - As of release 1.6.1, j8.u.c.Phaser has moved to the streamsupport-atomic
   component and j8.u.c.CompletionException has moved to streamsupport-cfuture
   (the only place where it is used).
   streamsupport-literal is no longer maintained but the 1.6.0 version can
   still be used since it doesn't have any dependencies on other artifacts.

 - Release 1.7.0 completes the Java 11 port and adds a couple of new methods
   from Java 12, especially a new merging Collector (JDK-8205461) and new
   exception handling methods for CompletableFuture (JDK-8210971).

 - Release 1.7.1 completes the Java 12 port and adds some improvements and
   bug fixes from Java 13.

 - Release 1.7.2 has a new Dual-pivot quicksort implementation, adds a few
   Java 9 methods to J8Arrays, is overall a bit smaller and adds some
   improvements and minor documentation fixes from Java 14.

 - Release 1.7.3 completes the Java 16 port and adds two new Stream methods
   (multiMap and toList) introduced in Java 16.



KNOWN PROBLEMS
--------------

 - Incorrect LinkedHashMap Spliterator ordering in Android N.

   The implementation of LinkedHashMap's collection views' spliterators in
   Android Nougat (API levels 24 and 25) uses the wrong order (inconsistent
   with the iterators, which use the correct order), despite reporting
   Spliterator#ORDERED (however, the unordered HashMap spliterators are used).

   Since streamsupport 1.5.3 and later will by default delegate to the Android 7.x
   spliterators you'd be affected by this unordered behavior on Android 7.x unless
   you disable spliterator delegation altogether or you work around this behavior
   on API level 24 and 25 as follows.

   You may use the following code to obtain a correctly ordered Spliterator:

   For a Collection view
   col = lhm.keySet(), col = lhm.entrySet() or col = lhm.values(), use

   Spliterator sp = java8.util.Spliterators.spliterator(col, c) where

   int c = Spliterator.DISTINCT | Spliterator.ORDERED | Spliterator.SIZED

   for keySet() and entrySet() and

   int c = Spliterator.ORDERED | Spliterator.SIZED for values()

   to obtain a correctly ordered spliterator. Then, instead of
   StreamSupport.stream(col) or StreamSupport.parallelStream(col), use

   java8.util.stream.StreamSupport.stream(sp, false)

   to construct a (nonparallel) java8.util.stream.Stream from the Spliterator sp.

   Note that these workarounds are only suggested where lhm is a LinkedHashMap.
   Note further that everything works perfectly fine on API level 23 and below (if
   you don't plan to deploy on Android 7.x devices, you can ignore this whole advice
   altogether).

   To mitigate the risk if you don't follow this advice, streamsupport 1.5.3 (and
   later) exercises a check whether the spliterator for a HashMap collection view
   reports ORDERED (a bug) and excepts these cases from the delegation mechanism
   (using the reflective implementation instead. So, in effect the same mechanism
   that is used on API level 23 and below gets employed in this case).

   But note that this check isn't 100% fool-proof as the LinkedHashMap (or its
   collection view) could be wrapped, for example in a j.u.Collections$UnmodifiableMap
   (whose UnmodifiableEntrySetSpliterator delegates back to the defective
   HashMap$EntrySpliterator).

   Since we can't know an arbitrary wrapper beforehand there is nothing streamsupport
   can do about this in such cases - you have been warned.

   The latest version of LinkedHashMap in AOSP implements its Spliterators via
   Spliterators.spliterator(), which means that this bug has already been fixed
   in Android O.



OUTLOOK
-------

 - This will most likely be the last streamsupport release.