Bug 59836 - Tracker: Replace primitives with enums
Summary: Tracker: Replace primitives with enums
Status: NEW
Alias: None
Product: POI
Classification: Unclassified
Component: POI Overall (show other bugs)
Version: 3.15-dev
Hardware: PC Linux
: P2 enhancement (vote)
Target Milestone: ---
Assignee: POI Developers List
URL:
Keywords:
Depends on: 59877 60136 60605 60666 55330 58190 58636 58671 59264 59790 59791 59833 59837 59873 59907 60187 60228 60795 60803 61898 61940
Blocks:
  Show dependency tree
 
Reported: 2016-07-10 06:51 UTC by Javen O'Neal
Modified: 2017-12-31 00:14 UTC (History)
0 users



Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Javen O'Neal 2016-07-10 06:51:05 UTC
This is a aggregate bug for recent changes in classes from using short or int to using enums with codes.

Benefits:
* self-explanatory usage rather than needing to list the valid constants in the javadocs
* easier to distinguish arguments in function signatures (not just a 5 ints)
* clearer error messages, no functions needed to convert code to string
* free range checking (less boiler plate code that does the same)
* type safety

Drawbacks:
* some permgen overhead
* type checking execution overhead

Overall, this seems like a good thing.

In effort to maintain backwards compatibility, the following is suggested:

If there is currently
int getSomething();
void setSomething(int);

Then we should add
enum getSomethingEnum();
void setSomething(Enum);

And deprecate
void setSomething(int);
int getSomething();

It's a bit tricky handling getSomething/getSomethingEnum while maintaining backwards compatibility because at some point the signature will abruptly change. Both getters should be offered for a while with a note encouraging users to use the constants or enums rather than using literal values. This is good coding practice anyway to not hard-code literal values, but is especially important with regard to backwards compatibility here.

At least 2 releases later, but not later than POI 4.0:
Delete void setSomething(int);
Delete int getSomething();
Rename enum getSomethingEnum(); to enum getSomething();

In the end, we will have
enum getSomething();
void setSomething(enum);
as the only two methods.
Comment 1 Javen O'Neal 2016-09-22 23:36:59 UTC
Todo: update https://poi.apache.org/spreadsheet/quick-guide.html
Comment 3 Andreas Beeker 2017-01-22 22:03:09 UTC
preparation for removing those many HSSFColor subclasses with an enum via r1779866