[bug-55330] add getMargin(PageMargin)

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1902880 13f79535-47bb-0310-9956-ffa450edef68

poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFSheet.java

@@ -774,12 +774,28 @@ public class SXSSFSheet implements Sheet, OoxmlSheetExtensions {
      *
      * @param margin which margin to get
      * @return the size of the margin
+     * @deprecated use {@link #getMargin(PageMargin)}
      */
     @Override
+    @Deprecated
+    @Removal(version = "7.0.0")
     public double getMargin(short margin) {
         return _sh.getMargin(margin);
     }
 
+
+    /**
+     * Gets the size of the margin in inches.
+     *
+     * @param margin which margin to get
+     * @return the size of the margin
+     * @since POI 5.2.3
+     */
+    @Override
+    public double getMargin(PageMargin margin) {
+        return _sh.getMargin(margin);
+    }
+
     /**
      * Sets the size of the margin in inches.
      *
@@ -985,7 +1001,7 @@ public class SXSSFSheet implements Sheet, OoxmlSheetExtensions {
      */
     @Override
     @Deprecated
-    @Removal(version = "POI 7.0.0")
+    @Removal(version = "7.0.0")
     public void createSplitPane(int xSplitPos, int ySplitPos, int leftmostColumn, int topRow, int activePane) {
         _sh.createSplitPane(xSplitPos, ySplitPos, leftmostColumn, topRow, activePane);
     }

poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSheet.java

@@ -754,7 +754,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx
      */
     @Override
     @Deprecated
-    @Removal(version = "POI 7.0.0")
+    @Removal(version = "7.0.0")
     public void createSplitPane(int xSplitPos, int ySplitPos, int leftmostColumn, int topRow, int activePane) {
         createFreezePane(xSplitPos, ySplitPos, leftmostColumn, topRow);
         if (xSplitPos > 0 || ySplitPos > 0) {
@@ -1220,26 +1220,41 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx
      * @see Sheet#BottomMargin
      * @see Sheet#HeaderMargin
      * @see Sheet#FooterMargin
+     * @deprecated use {@link #getMargin(PageMargin)}
      */
     @Override
+    @Deprecated
+    @Removal(version = "7.0.0")
     public double getMargin(short margin) {
+        return getMargin(PageMargin.getByShortValue(margin));
+    }
+
+    /**
+     * Gets the size of the margin in inches.
+     *
+     * @param margin which margin to get
+     * @return the size of the margin
+     * @since POI 5.2.3
+     */
+    @Override
+    public double getMargin(PageMargin margin) {
         if (!worksheet.isSetPageMargins()) {
             return 0;
         }
 
         CTPageMargins pageMargins = worksheet.getPageMargins();
         switch (margin) {
-            case LeftMargin:
+            case LEFT:
                 return pageMargins.getLeft();
-            case RightMargin:
+            case RIGHT:
                 return pageMargins.getRight();
-            case TopMargin:
+            case TOP:
                 return pageMargins.getTop();
-            case BottomMargin:
+            case BOTTOM:
                 return pageMargins.getBottom();
-            case HeaderMargin:
+            case HEADER:
                 return pageMargins.getHeader();
-            case FooterMargin:
+            case FOOTER:
                 return pageMargins.getFooter();
             default :
                 throw new IllegalArgumentException("Unknown margin constant:  " + margin);

poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFSheet.java

@@ -69,6 +69,7 @@ import org.apache.poi.ss.usermodel.CellStyle;
 import org.apache.poi.ss.usermodel.DataValidation;
 import org.apache.poi.ss.usermodel.DataValidationHelper;
 import org.apache.poi.ss.usermodel.FormulaEvaluator;
+import org.apache.poi.ss.usermodel.PageMargin;
 import org.apache.poi.ss.usermodel.PaneType;
 import org.apache.poi.ss.usermodel.Row;
 import org.apache.poi.ss.usermodel.Sheet;
@@ -1309,16 +1310,31 @@ public final class HSSFSheet implements Sheet {
      *
      * @param margin which margin to get
      * @return the size of the margin
+     * @deprecated use {@link #getMargin(PageMargin)}
      */
     @Override
+    @Deprecated
+    @Removal(version = "7.0.0")
     public double getMargin(short margin) {
+        return getMargin(PageMargin.getByShortValue(margin));
+    }
+
+    /**
+     * Gets the size of the margin in inches.
+     *
+     * @param margin which margin to get
+     * @return the size of the margin
+     * @since POI 5.2.3
+     */
+    @Override
+    public double getMargin(PageMargin margin) {
         switch (margin) {
-            case FooterMargin:
+            case FOOTER:
                 return _sheet.getPageSettings().getPrintSetup().getFooterMargin();
-            case HeaderMargin:
+            case HEADER:
                 return _sheet.getPageSettings().getPrintSetup().getHeaderMargin();
             default:
-                return _sheet.getPageSettings().getMargin(margin);
+                return _sheet.getPageSettings().getMargin(margin.getLegacyApiValue());
         }
     }
 
@@ -1843,7 +1859,7 @@ public final class HSSFSheet implements Sheet {
      */
     @Override
     @Deprecated
-    @Removal(version = "POI 7.0.0")
+    @Removal(version = "7.0.0")
     public void createSplitPane(int xSplitPos, int ySplitPos, int leftmostColumn, int topRow, int activePane) {
         getSheet().createSplitPane(xSplitPos, ySplitPos, topRow, leftmostColumn, activePane);
     }

poi/src/main/java/org/apache/poi/ss/usermodel/PageMargin.java

@@ -0,0 +1,113 @@
+/* ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+package org.apache.poi.ss.usermodel;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Enumeration which represents the various margins which are present within an
+ * Excel worksheet
+ *
+ * <p>
+ * Page margins are relevant when printing worksheets, and define the amount of
+ * empty space on the edges of each printed page
+ * </p>
+ *
+ * @since POI 5.2.3
+ */
+public enum PageMargin {
+
+    /**
+     * Left margin, the empty space on the left of displayed worksheet data when
+     * printing
+     */
+    LEFT(Sheet.LeftMargin),
+
+    /**
+     * Right margin, the empty space on the right of displayed worksheet data
+     * when printing
+     */
+    RIGHT(Sheet.RightMargin),
+
+    /**
+     * Top margin, the empty space on the top of displayed worksheet data when
+     * printing
+     */
+    TOP(Sheet.TopMargin),
+
+    /**
+     * Bottom margin, the empty space on the bottom of displayed worksheet data
+     * when printing
+     */
+    BOTTOM(Sheet.BottomMargin),
+
+    /**
+     * Header margin, the empty space between the header and the top of the page
+     * when printing
+     */
+    HEADER(Sheet.HeaderMargin),
+
+    /**
+     * Footer margin, the empty space between the footer and the bottom of the
+     * page when printing
+     */
+    FOOTER(Sheet.FooterMargin);
+
+    /**
+     * Map relating the old API constant values to their corresponding
+     * enumeration value
+     */
+    private static final Map<Short, PageMargin> PAGE_MARGIN_BY_LEGACY_API_VALUE;
+
+    static {
+        PAGE_MARGIN_BY_LEGACY_API_VALUE = new HashMap<>();
+
+        for (PageMargin margin : values()) {
+            PAGE_MARGIN_BY_LEGACY_API_VALUE.put(margin.legacyApiValue, margin);
+        }
+    }
+
+    /**
+     * The old API constant value which corresponded to this page margin
+     */
+    private final short legacyApiValue;
+
+    /**
+     * @param legacyApiValue The old API constant value which corresponded to this page
+     *                       margin
+     */
+    PageMargin(short legacyApiValue) {
+        this.legacyApiValue = legacyApiValue;
+    }
+
+    public short getLegacyApiValue() {
+        return legacyApiValue;
+    }
+
+    /**
+     * Retrieves the enumeration value which corresponds to a legacy API
+     * constant value
+     *
+     * @param legacyApiValue An old API margin constant value
+     * @return The PageMargin enumeration which corresponds to the given value,
+     * or null if no corresponding value exists
+     */
+    public static PageMargin getByShortValue(short legacyApiValue) {
+        return PAGE_MARGIN_BY_LEGACY_API_VALUE.get(legacyApiValue);
+    }
+}

poi/src/main/java/org/apache/poi/ss/usermodel/Sheet.java

@@ -624,9 +624,21 @@ public interface Sheet extends Iterable<Row> {
      *
      * @param margin which margin to get
      * @return the size of the margin
+     * @deprecated use {@link #getMargin(PageMargin)}
      */
+    @Deprecated
+    @Removal(version = "7.0.0")
     double getMargin(short margin);
 
+    /**
+     * Gets the size of the margin in inches.
+     *
+     * @param margin which margin to get
+     * @return the size of the margin
+     * @since POI 5.2.3
+     */
+    double getMargin(PageMargin margin);
+
     /**
      * Sets the size of the margin in inches.
      *
@@ -781,7 +793,7 @@ public interface Sheet extends Iterable<Row> {
      * @deprecated use {@link #createSplitPane(int, int, int, int, PaneType)}
      */
     @Deprecated
-    @Removal(version = "POI 7.0.0")
+    @Removal(version = "7.0.0")
     void createSplitPane(int xSplitPos, int ySplitPos, int leftmostColumn, int topRow, int activePane);
 
     /**