Name: nt126004 Date: 02/14/2002


FULL PRODUCT VERSION :
java version "1.3.1_02"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_02-b02)
Java HotSpot(TM) Client VM (build 1.3.1_02-b02, mixed mode)


FULL OPERATING SYSTEM VERSION :
Microsoft Window 2000 [Version 5.00.2195]

ADDITIONAL OPERATING SYSTEMS :
Mac OSX Version 10.1.2 Build SP48



A DESCRIPTION OF THE PROBLEM :
The setLineNumber() method of the LineNumberReader performs
in a completely counterintuitive manner. The expected behavior
would be from both the method name and additionally the method
summary, to set the current line number to be read from.

In fact, setLineNumber() does nothing to that end and apparently
sets an arbitrary counter within the class itself. To what end
neither I nor anyone else will ever know since there is no mention
of this counter anywhere in the Javadoc.

The problem is that because there is no documentation to the
contrary, one assumes one is doing something wrong or in fact
that the method is broken. Only when one does an exhaustive
search on this method is any light shed on the real purpose of the
setLineNumber() method!

This problem has been reported before as a bug (4178689). It was closed as
not a bug but the problem still exists that developers are misled as to
the purpose of setLineNumber and spend valuable time tracking
down the cause.

Instead of reporting a bug, there should be clear and concise
explanation on the LineNumberReader Javadoc that
setLineNumber() does not set the current line but an internal
counter which has nothing to do with the current line being read!

For this reason I am not reporting a bug but a plead for better
Ease of Use through better documentation. As of 1.3.1_02 the
documentation makes no mention of the common
misunderstanding.


REGRESSION. Last worked in version 1.1.8

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Set LineNumberReader.setLineNumber(2)
2. Do LineNumberReader.readLine()
3. Line number 1 is read instead of line number 2.

This is well and better documented in previous bug reports

EXPECTED VERSUS ACTUAL BEHAVIOR :
The LineNumberReader to read from the line set by the
setLineNumber(int) method.

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
As I already stated, this is well documented in previous bug reports
---------- END SOURCE ----------
(Review ID: 139596)
======================================================================