Hello Dave,
It's not clear if you are questioning the merit of creating the newer
method "getCell(int)", or whether the old method "getCell(short)"
should have been deprecated at all, so I'll attempt to answer both
concerns.
The most visible reason why POI is moving away from bytes and shorts
is the need for typecasts when using literal integer constants, even
when the value is quite obviously within range. For example without
the new method "row.getCell(5)" would not compile. We would have to
write "row.getCell((short)5)".
There have been several POI bugs involving representation of unsigned
(ushort, ubyte) quantities with java datatypes (signed) of the same
width (short, byte). When shorts and bytes are used, the corrected
code generally needs more typecasts and bit mask expressions. If
those datatypes are changed to int, the code is usually simpler and
easier to read.
The new method "getCell(int) method may in the first place have been
introduced as a result of the XSSF common interface work (a separate
reason, as suggested by Mark B).
That sort-of explains the rationale for creating the new method
"getCell(int)". The reason for deprecating the old is to eliminate
overloading (of "getCell"). Method overloading is sometimes very
handy but has quite a few pitfalls, and for that reason POI tries to
use overloading sparingly.
As far as the exact meaning of the '@deprecated' tag, in POI (unlike
in the java runtime library) it means "This method will be removed in
a future POI version". An alternative is always given. A deprecation
date has been provided in most places, to help POI users prioritize
clean-up of their own code.
You mentioned the comment from the the first line of the deprecated method:
int ushortCellNum = cellnum & 0x0000FFFF; // avoid sign extension
The bit-mask is correct for 16-bit unsigned conversion. Masking with
0xFF would be wrong because it would silently convert every possible
input to a valid column index. For example: is it sensible for
"getCell((short)300)" to succeed? Maybe it looks pointless to
convert values in the range (-32768...-1) to (32768...65535) is
because the maximum column index is 255. This conversion to unsigned
16-bit has been done because it's more likely that the caller intends
an unsigned quantity (column indexes are never negative). So if a
negative value *does* get into this method, it's probably better to
format the error message in terms of the unsigned 16 bit quantity.
Similar results could have been achieved with bounds checking the
argument, but would involve duplicating all the MissingCellPolicy
logic too.
So - that line of code is there for making better error messages, and
has little to do with the reasons for the deprecation.
regards,
Josh
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
