Code Review for JEP 259: Stack-Walking API

[Mandy Chung]

On Nov 17, 2015, at 4:00 PM, Ian Rogers <irogers at google.com> wrote:
> 
> Should the StackWalker.StackFrame interface provide a way to get the java.lang.reflect.Method/Constructor/Member?
> 

Not in the scope of this JEP.

Mandy

> Thanks,
> Ian
> 
> On Tue, Nov 17, 2015 at 3:56 PM, Mandy Chung <mandy.chung at oracle.com> wrote:
> Thanks Peter.
> 
> > - threre's no ResourceBundle.getBundle(String, ClassLoader) method.
> > - Util -> ResourceBundleUtil (or ResourceBundleUtil -> Util)
> >
> 
> Fixed.
> 
> > :
> > - Stream.findFirst() returns Optional<E>, not E.
> >
> 
> Fixed.
> 
> I updated javadoc for getCallerClass per our discussion.
> 
> /**
>  * Gets the {@code Class} object of the caller invoking the method
>  * that calls this {@code getCallerClass} method.
>  *
>  * <p> Reflection frames, {@link java.lang.invoke.MethodHandle} and
>  * hidden frames are filtered regardless of the
>  * {@link Option#SHOW_REFLECT_FRAMES SHOW_REFLECT_FRAMES}
>  * and {@link Option#SHOW_HIDDEN_FRAMES SHOW_HIDDEN_FRAMES} options
>  * if this {@code StackWalker} has been configured.
>  *
>  * <p> This method throws {@code UnsupportedOperationException} if
>  * this {@code StackWalker} is not configured with
>  * {@link Option#RETAIN_CLASS_REFERENCE RETAIN_CLASS_REFERENCE} option
>  * or this method is called from the last frame on the stack.
>  *
>  * @apiNote
>  * For example, {@code Util::getResourceBundle} loads a resource bundle
>  * on behalf of the caller.  It calls this {@code getCallerClass} method
>  * to find the method calling {@code Util::getResourceBundle} and use the caller's
>  * class loader to load the resource bundle. The caller class in this example
>  * is the {@code MyTool} class.
>  *
>  * <pre>{@code
>  *     class Util {
>  *         private final StackWalker walker = StackWalker.getInstance(Option.RETAIN_CLASS_REFERENCE);
>  *         public ResourceBundle getResourceBundle(String bundleName) {
>  *             Class<?> caller = walker.getCallerClass();
>  *             return ResourceBundle.getBundle(bundleName, Locale.getDefault(), caller.getClassLoader());
>  *         }
>  *     }
>  *
>  *     class MyTool {
>  *         private final Util util = new Util();
>  *         private void init() {
>  *             ResourceBundle rb = util.getResourceBundle("mybundle");
>  *         }
>  *     }
>  * }</pre>
>  *
>  * An equivalent way to find the caller class using the
>  * {@link StackWalker#walk walk} method is as follows
>  * (filtering the reflection frames, {@code MethodHandle} and hidden frames
>  * not shown below):
>  * <pre>{@code
>  *     Optional<Class<?>> caller = walker.walk(s ->
>  *         s.map(StackFrame::getDeclaringClass)
>  *          .skip(2)
>  *          .findFirst());
>  * }</pre>
>  *
>  * When the {@code getCallerClass} method is called from a method that
>  * is the last frame on the stack,
>  * for example, {@code static public void main} method launched by the
>  * {@code java} launcher or a method invoked from a JNI attached thread.
>  * {@code UnsupportedOperationException} is thrown.
>  *
>  * @return {@code Class} object of the caller's caller invoking this method.
>  *
>  * @throws UnsupportedOperationException if this {@code StackWalker}
>  *         is not configured with {@link Option#RETAIN_CLASS_REFERENCE
>  *         Option.RETAIN_CLASS_REFERENCE}.
>  * @throws UnsupportedOperationException if there is no caller frame, i.e.
>  *         when this {@code getCallerClass} method is called from a method
>  *         which is the last frame on the stack.
>  */
> 
> Mandy
>