streamsupport Files

NEW
---

 - JDK-8178409: Misc. changes imported from jsr166 CVS 2017-07

 - JDK-8185099: Misc. changes imported from jsr166 CVS 2017-08

 - reenable LHM Spliterator delegation on Android O [#314]

 - test on Android O preview [#315]

 - reduce method count and jar size [#303]

 - enforce Spliterator delegation on Java 9 [#299]

 - please refer to the 1.5.6 milestone tickets for more details



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.



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
-------

 - Keeping up with the bugfixes and improvements in the OpenJDK
   repo. Maybe also new Java 10 methods. Yet, this shouldn't be
   taken as a promise to deliver soon.