Bug 59836

Summary: Tracker: Replace primitives with enums
Product: POI Reporter: Javen O'Neal <onealj>
Component: POI OverallAssignee: POI Developers List <dev>
Status: NEW ---    
Severity: enhancement    
Priority: P2    
Version: 3.15-dev   
Target Milestone: ---   
Hardware: PC   
OS: Linux   
Bug Depends on: 55330, 59877, 60136, 60605, 60666, 58190, 58636, 58671, 59264, 59790, 59791, 59833, 59837, 59873, 59907, 60187, 60228, 60795, 60803, 61898, 61940    
Bug Blocks:    

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