Proposed API for JEP 259: Stack-Walking API

[Mandy Chung]

> On Nov 18, 2015, at 1:11 AM, Peter Levart <peter.levart at gmail.com> wrote:
> 
> Hi Mandy,
> 
> Just one nit...
> 
> On 11/17/2015 11:59 PM, Mandy Chung wrote:
>>> Apart from the orphaned paragraph fragment at the end looks good to me, but that’s just my opinion.
>> I caught that that after I clicked sent :(
>> 
>> This is a better version.
>> 
>> /**
>>  * 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.
> 
> - if this {@code StackWalker} has been configured.
> + this {@code StackWalker} has been configured with.

Fixed.

> 
> Otherwise I think this is fine now.
> 
> I was just thinking of getCallerClass() suitability to be an instance method. It requires StackWalker instance to be configured with RETAIN_CLASS_REFERENCE and ignores SHOW_REFLECT_FRAMES and SHOW_HIDDEN_FRAMES options. Do you anticipate other options in the future that could actually affect how getCallerClass() operates? If not, then perhaps it could just be a static method to simplify use. What do you think?
> 

It’s an instance method because the stack walker must have RETAIN_CLASS_REFERENCE option so that it will do stack-based permission check only at the getInstance time.  If it’s a static method, the getCallerClass will perform stack-based permission check at each call that we want to avoid.

Mandy