Bug 59264

Summary: Unify interface for setting cell border line styles using BorderStyle enum instead of short code
Product: POI Reporter: Javen O'Neal <onealj>
Component: SS CommonAssignee: POI Developers List <dev>
Status: RESOLVED FIXED    
Severity: enhancement    
Priority: P2    
Version: 3.15-dev   
Target Milestone: ---   
Hardware: PC   
OS: All   
Bug Depends on:    
Bug Blocks: 58787, 59836    
Attachments: promote ss.usermodel.BorderStyle.java as class to get/set border style with
Created a worksheet showing how the border styles are used
XLS version

Description Javen O'Neal 2016-04-02 20:23:36 UTC
The BORDER_* constants in CellStyle [1] should be converted to enums to them more discoverable and safer.

A conversion was already done at the XSSF level in bug 45942 with BorderStyle.java. These changes need to be brought up to Common SS so that they can be used by HSSF workbooks as well.

[1] https://poi.apache.org/apidocs/org/apache/poi/ss/usermodel/CellStyle.html
Comment 1 Javen O'Neal 2016-04-05 04:33:47 UTC
Created attachment 33725 [details]
promote ss.usermodel.BorderStyle.java as class to get/set border style with

Need to be careful not to cause regressions with regard to HAIR/DOTTED (bug 55341). I believe HAIR is smaller dots than DOTTED.

hssf record BorderFormatting has not been replaced yet. Not sure if it needs to, though, since it's lower level anyways.
Comment 2 Javen O'Neal 2016-04-05 04:35:45 UTC
Created attachment 33726 [details]
Created a worksheet showing how the border styles are used

Similar to attachment 30660 [details] from bug 55341, but includes text to define what each type of border style is attempting to be.
Comment 3 Javen O'Neal 2016-04-05 04:35:59 UTC
Created attachment 33727 [details]
XLS version
Comment 4 Javen O'Neal 2016-04-05 21:43:22 UTC
Implemented in r1737751, r1737752, r1737879, r1737884, r1737885, r1737886

Backwards-incompatible changes:
* Change: BorderStyle.MEDIUM_DASH_DOT_DOTC renamed to MEDIUM_DASH_DOT_DOT
  Affected classes:
    o.a.p.ss.usermodel.BorderStyle
* Change: getBorderX returns BorderStyle instead of short.
  Affected classes:
    o.a.p.hssf.usermodel.HSSFBorderFormatting
    o.a.p.hssf.usermodel.HSSFCellStyle
    o.a.p.ss.usermodel.BorderFormatting
    o.a.p.ss.usermodel.BorderStyle
    o.a.p.ss.usermodel.CellStyle
    o.a.p.xssf.usermodel.XSSFBorderFormatting
    o.a.p.xssf.usermodel.XSSFCellStyle

Deprecated features (will be removed in a future release):
* Change: short BORDER_* constants deprecated. Use BorderStyle enum values instead.
  Affected classes:
    o.a.p.ss.usermodel.BorderFormatting
    o.a.p.ss.usermodel.CellStyle
* Change: setBorderX(short) deprecated. Use setBorderX(BorderStyle) instead.
  Affected classes:
    o.a.p.hssf.usermodel.HSSFBorderFormatting
    o.a.p.hssf.usermodel.HSSFCellStyle
    o.a.p.ss.usermodel.BorderFormatting
    o.a.p.ss.usermodel.BorderStyle
    o.a.p.ss.usermodel.CellStyle
    o.a.p.xssf.usermodel.XSSFBorderFormatting
    o.a.p.xssf.usermodel.XSSFCellStyle
* Change: getBorderLeftEnum deprecated. Use getBorderLeft instead.
  Affected classes:
    o.a.p.xssf.usermodel.XSSFCellStyle
* Change: CellUtil.getFormatProperties/setFormatProperties operate on BorderStyle enums instead of shorts for border line styles
  Affected classes:
    o.a.p.ss.util.CellUtil
  Side-note: This deprecation warning is inside a private method. How do I alert developers that setting BorderStyles with short/Short will be deprecated besides raising an runtime ClassCastException when BorderStyles become required?

Per comment 1, BaseTestBorderStyle [1] tests to make sure that HAIR and DOTTED enums are as expected. HAIR is smaller dots than DOTTED. Anyone wondering what each border style looks like can open test-data/spreadsheet/59264.xls or 59264.xlsx.

[1] https://svn.apache.org/viewvc/poi/trunk/src/testcases/org/apache/poi/ss/usermodel/BaseTestBorderStyle.java?view=markup&pathrev=1737879
Comment 5 Javen O'Neal 2016-04-05 23:32:57 UTC
Updated JavaDocs in r1737894. These changes will be available in POI 3.15 beta 2.

Updated change log in r1737888.
Comment 6 Javen O'Neal 2016-09-14 05:27:08 UTC
r1760627 reverted part of r1737879 for backwards compatibility with POI 3.14.
BorderFormatting#getBorder[Top|Bottom|Left|Right|Diagonal]() returns short
BorderFormatting#getBorder[Top|Bottom|Left|Right|Diagonal]Enum() returns BorderStyle enum

r1760630 reverted part of r1737879 for backwards compatibility with POI 3.14.
CellStyle#getBorder[Top|Bottom|Left|Right]() returns short
CellStyle#getBorder[Top|Bottom|Left|Right]Enum() returns BorderStyle enum

These changes will be included in POI 3.15 final. POI will be binary backwards compatible with POI 3.14.