updated RI code and API javadoc

[Yuri Gaevsky]

Greetings.

Some follow up: currently the methods of the java.dyn.Linkage class have
the following behaviour with respect to null parameter(s):

[1] Linkage.registerBootstrapMethod(String name) [name is null]:
	Exception thrown: java.lang.NullPointerException

[2] Linkage.registerBootstrapMethod(Class<?> runtime, String name) [name is null]:
	Exception thrown: java.lang.NullPointerException
     Linkage.registerBootstrapMethod(Class<?> runtime, String name) [runtime is null]:
	Exception thrown: java.lang.IllegalArgumentException: nothing to resolve
     Linkage.registerBootstrapMethod(Class<?> runtime, String name) [runtime and name are null]:
	Exception thrown: java.lang.NullPointerException

[3] Linkage.registerBootstrapMethod(Class callerClass, MethodHandle bootstrapMethod) [callerClass is null]:
	No exception thrown
     Linkage.registerBootstrapMethod(Class callerClass, MethodHandle bootstrapMethod) [bootstrapMethod is null]:
	Exception thrown: java.lang.IllegalArgumentException: null bootstrap method
     Linkage.registerBootstrapMethod(Class callerClass, MethodHandle bootstrapMethod) [callerClass and bootstrapMethod are null]:
	Exception thrown: java.lang.IllegalArgumentException: null bootstrap method

[4] Linkage.getBootstrapMethod(Class callerClass) [callerClass is null]:
	No exception thrown

[5] Linkage.invalidateCallerClass(Class<?> callerClass) [callerClass is null]:
	Exception thrown: java.lang.UnsupportedOperationException: NYI

Note that NPE is not documented anywhere in the class though it looks reasonable
for all methods there.

Best regards,
-Yuri

Yuri Gaevsky wrote:
> John,
> 
> A couple of minor comments regarding the latest java.dyn.* javadoc:
> 
> a) "Requirements for Writing Java API Specifications" [1] specifies under the
>      heading "Method Specification", item number 4:
>        Null Argument Values - For each reference type argument, specify the
>        behavior when null is passed in. See two examples. NOTE: If possible,
>        document the general null argument behavior at the package or class level,
>        such as causing a java.lang.NullPointerException to be thrown. Deviations
>        from this behavior can then be documented at the method level.
> 
>      So, is it possible to add at the java.dyn package level something like:
>        Unless otherwise specified, methods in this package will throw a
>        NullPointerException if given a null argument.
>      and update javadoc for those methods which still can accept null values?
> 
> 
> b) "How to Write Doc Comments for the Javadoc Tool" doc [2] recommends
>      as follows:
>        The description is in 3rd person declarative rather than 2nd person
>        imperative.
>          Gets the label. (preferred)
>          Get the label.  (avoid)
> 
> Thanks,
> -Yuri
> 
> [1] http://java.sun.com/j2se/javadoc/writingapispecs/index.html
> [2] http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide
> 
> John Rose wrote:
>> 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/
>>
>> I added filterArguments 
>> <http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#filterArguments(java.dyn.MethodHandle,%20java.dyn.MethodHandle...)>, 
>> 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/~jrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#foldArguments(java.dyn.MethodHandle,%252520java.dyn.MethodHandle)> (requires 
>> argument dropping/reordering).
>>
>> -- John
>>
>> P.S.  I also added something called dynamicInvoker 
>> <http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#dynamicInvoker(java.dyn.CallSite)>. 
>>  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.
>>
>>
>> ------------------------------------------------------------------------
>>
>> _______________________________________________
>> mlvm-dev mailing list
>> mlvm-dev at openjdk.java.net
>> http://mail.openjdk.java.net/mailman/listinfo/mlvm-dev
> _______________________________________________
> mlvm-dev mailing list
> mlvm-dev at openjdk.java.net
> http://mail.openjdk.java.net/mailman/listinfo/mlvm-dev