A DESCRIPTION OF THE PROBLEM :
Long narrowing conversion methods such as .intValue() should describe the algorithm used and risks.

For the example of Long.intValue() on could expect that the narrowing conversion would properly behave if the long value is larger than Integer.MAX_VALUE and would return Integer.MAX_VALUE in this case.

However, looking at the implementation is performs a simple cast, which is defined as the following the in JLS 2.0 in section "5.1.3 Narrowing Primitive Conversion": "A narrowing conversion of a signed integer to an integral type T simply discards all but the n lowest order bits, where n is the number of bits used to represent type T. In addition to a possible loss of information about the magnitude of the numeric value, this may cause the sign of the resulting value to differ from the sign of the input value."

Consequently, Long.intValue() with a large long number may returrn a negative number. I suggest this is clearly documented.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
At least provide a reference to the JLS narrowing conversion, but I really suggest to make a copy of the following extract in section "5.1.3 Narrowing Primitive Conversion": "A narrowing conversion of a signed integer to an integral type T simply discards all but the n lowest order bits, where n is the number of bits used to represent type T. In addition to a possible loss of information about the magnitude of the numeric value, this may cause the sign of the resulting value to differ from the sign of the input value."

ACTUAL -
public long longValue()
Returns the value of this Long as a long value.

Specified by:
longValue in class Number
Returns:
the numeric value represented by this object after conversion to type long.

URL OF FAULTY DOCUMENTATION :
docs/api/java/lang/Long.html#intValue()
###@###.### 2005-04-11 10:16:12 GMT