RFR(L): 8151179: address issues raised by JCK team on JEP 274 API

[Michael Haupt]

Dear all,

please review this change.
Bug: https://bugs.openjdk.java.net/browse/JDK-8151179
Webrev: http://cr.openjdk.java.net/~mhaupt/8151179/webrev.00/

The change addresses concerns about the JEP 274 API that were raised by the JCK team. One consequence is that the convenience wrappers for the generic loop combinator are now somewhat restrictive about the handles passed to them as arguments. They have to be created with the appropriate matching signatures. This minor inconvenience is easily overcome by utilising available API such as MethodHandles.constant(), .empty(), or .dropToMatch(). In case the full handle signature inference power is desired, the generic loop combinator, MethodHandles.loop(), still provides this.

Most of the changes affect the API documentation, but the behavioural changes in some of the methods also reflect on the pertaining tests.

Thanks,

Michael

-- 

 <http://www.oracle.com/>
Dr. Michael Haupt | Principal Member of Technical Staff
Phone: +49 331 200 7277 | Fax: +49 331 200 7561
Oracle Java Platform Group | LangTools Team | Nashorn
Oracle Deutschland B.V. & Co. KG | Schiffbauergasse 14 | 14467 Potsdam, Germany

ORACLE Deutschland B.V. & Co. KG | Hauptverwaltung: Riesstraße 25, D-80992 München
Registergericht: Amtsgericht München, HRA 95603

Komplementärin: ORACLE Deutschland Verwaltung B.V. | Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Handelsregister der Handelskammer Midden-Nederland, Nr. 30143697
Geschäftsführer: Alexander van der Ven, Jan Schultheiss, Val Maher
 <http://www.oracle.com/commitment>	Oracle is committed to developing practices and products that help protect the environment