Proposed API for JEP 259: Stack-Walking API

[Mandy Chung]

> On Nov 10, 2015, at 1:07 AM, Peter Levart <peter.levart at gmail.com> wrote:
> 
> Hi Mandy,
> 
> On 11/10/2015 03:20 AM, Mandy Chung wrote:
>> I have updated the APIs to incorporate all the feedback.  Thank you all.  Let me know if I miss any.  
>> 
>> Summary:
>> 1. Change to use wildcard walk(Function<? super Stream<StackFrame>, ? extends T> function) 
>> 2. Removed the walk method taking IntUnaryOperator batchSizeMapper argument
>> 3. Add the new static factory method to create StackWalker and keep the constructors private
>> 4. StackFrame::getFileName and StackFrame::getLineNumber return Optional<String>, OptionaIInt respectively as they are optional. 
>> 4. maxDepth is not really needed as the user can use Stream::limit.  So taken out.
>> 5. Add StackWalker::create(Set<Option> options, int estimateDepth) to take an estimate depth to give a hint the estimated number of frames to traverse by this walker.  The implementation may use it to tune the buffer size.
>> 
>> Javadoc
>>    
>> http://cr.openjdk.java.net/~mchung/jdk9/jep259/api/java/lang/StackWalker.html
>> 
>> 
>> FYI.  I’ll post the webrevs in a new code review thread.
>> Mandy
>> 
> 
> Javadoc says that a StackWalker instance can be reused, but nothing is said whether it is thread-safe. Can a single instance be used to walk the stack from multiple threads?

It can.  Will update the javadoc.

> 
> In getCallerClass, an example can be added to the description:
> If this getCallerClass method is called by the last frame on the stack, for example when this getCallerClass method is invoked from the static main entry point or a method called from a JNI attached thread such as Thread::run, this method returns an empty Optional since the caller's class is not found.
> 
> 
> ResourceBundle example needs to be updated.
> 

I will update that.

Thanks
Mandy