United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4102267 : java.lang.Throwable.fillInStackTrace text ambiguous

Details
Type:
Bug
Submit Date:
1998-01-07
Status:
Closed
Updated Date:
2000-07-28
Project Name:
JDK
Resolved Date:
2000-07-28
Component:
docs
OS:
generic
Sub-Component:
guides
CPU:
generic
Priority:
P4
Resolution:
Won't Fix
Affected Versions:
1.2.0
Fixed Versions:

Related Reports

Sub Tasks

Description

Name: dgC58589			Date: 01/07/98


(See http://www.javasoft.com/products/jdk/1.2/docs/api/java.lang.Throwable.html#fillInStackTrace() .)

The documentation for java.lang.Throwable.fillInStackTrace
is not clear.  It is not apparent what the method
is good for, or exactly what difference it makes.

There is an example, but it is not a good one--
it's not a case where calling fillInStackTrace 
makes much difference.  (Well, maybe the line
number changes, but the chain of called method
names does not.)


The text should mention that:
- the stack trace is already filled in when the 
    exception is constructed, from the stack at 
    the point of the creation of the exception
    object (to help indicate that fillInStackTrace
    is needed only for changing this default)
- fillInStackTrace updates (replaces) the existing
    stack trace in the exception with the stack 
    trace from the point of the call to 
    fillInStackTrace

The example should show an exception originally
generated in a called function (so that calling
fillInStackTrace makes a noticeable difference 
(cutting off the chain of called methods)).

Text should point out that calling fillInStackTrace
is useful for suppressing some details of the call
stack for exceptions created in deeper-nested
method calls.  (Or for updating in a stack trace
for an exception creating at a higher level and
passed in, which would, of course, be a really
weird use.)
(Review ID: 22685)
======================================================================

                                    

Comments
EVALUATION

Plans have been made to improve the documentation of class Throwable in the near future but no change will be made at this time.
jamie.ho@Eng 2000-07-27
                                     
2000-07-27
PUBLIC COMMENTS

Plans have been made to improve the documentation of class Throwable in the near future but no change will be made at this time.
jamie.ho@Eng 2000-07-27
                                     
2000-07-27



Hardware and Software, Engineered to Work Together