updated RI code and API javadoc

[Rémi Forax]

John Rose a écrit :
> I pushed a lot more testing and implementation code for the reference 
> implementation.  Finally permuteArguments works, as do all the 
> variations of varargs processing.
>
> Here's the updated javadoc; it's getting better:
>   http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/ 
> <http://cr.openjdk.java.net/%7Ejrose/pres/indy-javadoc-mlvm/>
>
> I added filterArguments 
> <http://cr.openjdk.java.net/%7Ejrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#filterArguments%28java.dyn.MethodHandle,%20java.dyn.MethodHandle...%29>, 
> since I remember people asking for it during last year's Summit.  Such 
> a simple use case (single argument transformation with a unary 
> function) is too awkward to implement in terms of foldArguments 
> <http://cr.openjdk.java.net/%7Ejrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#foldArguments%28java.dyn.MethodHandle,%252520java.dyn.MethodHandle%29> (requires 
> argument dropping/reordering).

Hi John, hi all,
I am currently trying to sync the backport with latest RI changes,
I have noticed that fold (previously named combine) has no position 
argument anymore.
I suppose that the rational is that if one want to insert the combiner
at another index he can use permuteArguments().
I wonder if it's interresting to apply the same idea to insertArguments.

About filterArguments, the implementation is not aligned with the doc, 
the doc says that the array of filters
can have any size but the implementation raises an IAE if the size of 
the array
is greater than the number of paramater types of the target.

Moreover, the pseudocode use ?: which is not described anywhere,
I think it should be remplaced by
filters[i] = filters[i] != null ?  filters[i] : identity

>
> -- John
>
> P.S.  I also added something called dynamicInvoker 
> <http://cr.openjdk.java.net/%7Ejrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#dynamicInvoker%28java.dyn.CallSite%29>. 
>  It is a simple thing which turns a CallSite into a simulated 
> invokedynamic instruction; this rounds out the Lookup.find{Static,*} 
> functionality to include the new invoke instruction.  Not sure if it 
> is the right thing, though.

I am not currently able to find a use case of dynamicInvoker,
anyway, it's not a big change.
Just a remark, in the doc of dynamicInvoker, one can use publicLookup() 
instead of lookup()
to get getTarget().


Else, you introduce some method named "methodType" and
I don't think it worth it.
It only save some keystrokes, at the cost of:
- have twice the same API
- have to understand why some MethodType.make() have no equivalent method in
  MethodHandles.

By the way, snippets included in the doc comments of methods methodType(...)
doesn't declare m as a MethodHandle.

cheers,
Rémi