bug 59873: replace Hyperlink.LINK_* int constants with HyperlinkType enum

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

5 files changed, 163 insertions, 45 deletions

diff --git a/src/java/org/apache/poi/common/usermodel/Hyperlink.java b/src/java/org/apache/poi/common/usermodel/Hyperlink.java
index f75c890204..132a3eb4c3 100644
--- a/src/java/org/apache/poi/common/usermodel/Hyperlink.java
+++ b/src/java/org/apache/poi/common/usermodel/Hyperlink.java
@@ -22,23 +22,31 @@ package org.apache.poi.common.usermodel;
 public interface Hyperlink {
     /**
      * Link to an existing file or web page
+     * 
+     * @deprecated POI 3.15 beta 3. Use {@link HyperlinkType#URL} instead.
      */
-    public static final int LINK_URL = 1;
+    public static final int LINK_URL = 1; // HyperlinkType.URL.getCode()
 
     /**
      * Link to a place in this document
+     * 
+     * @deprecated POI 3.15 beta 3. Use {@link HyperlinkType#DOCUMENT} instead.
      */
-    public static final int LINK_DOCUMENT = 2;
+    public static final int LINK_DOCUMENT = 2; // HyperlinkType.DOCUMENT.getCode()
 
     /**
      * Link to an E-mail address
+     * 
+     * @deprecated POI 3.15 beta 3. Use {@link HyperlinkType#EMAIL} instead.
      */
-    public static final int LINK_EMAIL = 3;
+    public static final int LINK_EMAIL = 3; // HyperlinkType.EMAIL.getCode()
 
     /**
-     * Link to a file
+     * Link to an file
+     * 
+     * @deprecated POI 3.15 beta 3. Use {@link HyperlinkType#FILE} instead.
      */
-    public static final int LINK_FILE = 4;
+    public static final int LINK_FILE = 4; // HyperlinkType.FILE.getCode()
 
     
     /**
@@ -73,6 +81,16 @@ public interface Hyperlink {
      * Return the type of this hyperlink
      *
      * @return the type of this hyperlink
+     * @see HyperlinkType#forInt(int)
+     * @deprecated POI 3.15 beta 3. Use {@link #getTypeEnum()}
      */
     public int getType();
+    
+    /**
+     * Return the type of this hyperlink
+     *
+     * @return the type of this hyperlink
+     * @since POI 3.15 beta 3
+     */
+    public HyperlinkType getTypeEnum();
 }
diff --git a/src/java/org/apache/poi/common/usermodel/HyperlinkType.java b/src/java/org/apache/poi/common/usermodel/HyperlinkType.java
new file mode 100644
index 0000000000..0d8e139c87
--- /dev/null
+++ b/src/java/org/apache/poi/common/usermodel/HyperlinkType.java
@@ -0,0 +1,75 @@
+/* ====================================================================
+   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.common.usermodel;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.apache.poi.util.Internal;
+
+/**
+ * @since POI 3.15 beta 3
+ */
+public enum HyperlinkType {
+    /** Not a hyperlink */
+    @Internal
+    NONE(-1),
+    
+    /**
+     * Link to an existing file or web page
+     */
+    URL(1),
+
+    /**
+     * Link to a place in this document
+     */
+    DOCUMENT(2),
+
+    /**
+     * Link to an E-mail address
+     */
+    EMAIL(3),
+
+    /**
+     * Link to a file
+     */
+    FILE(4);
+    
+    private final int code;
+    private HyperlinkType(int code) {
+        this.code = code;
+    }
+    
+    private static final Map<Integer, HyperlinkType> map = new HashMap<Integer, HyperlinkType>();
+    static {
+        for (HyperlinkType type : values()) {
+            map.put(type.getCode(), type);
+        }
+    }
+    
+    public int getCode() {
+        return code;
+    }
+    
+    public static HyperlinkType forInt(int code) {
+        HyperlinkType type = map.get(code);
+        if (type == null) {
+            throw new IllegalArgumentException("Invalid type: " + code);
+        }
+        return type;
+    }
+}
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFCreationHelper.java b/src/java/org/apache/poi/hssf/usermodel/HSSFCreationHelper.java
index 337255fd3b..7ce7ef1be8 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFCreationHelper.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFCreationHelper.java
@@ -17,6 +17,7 @@
 
 package org.apache.poi.hssf.usermodel;
 
+import org.apache.poi.common.usermodel.HyperlinkType;
 import org.apache.poi.hssf.record.common.ExtendedColor;
 import org.apache.poi.ss.usermodel.CreationHelper;
 import org.apache.poi.util.Internal;
@@ -44,10 +45,19 @@ public class HSSFCreationHelper implements CreationHelper {
         return workbook.createDataFormat();
     }
 
+    /**
+     * {@inheritDoc}
+     * @deprecated POI 3.15 beta 3. Use {@link #createHyperlink(HyperlinkType)} instead.
+     */
+    @Deprecated
     @Override
     public HSSFHyperlink createHyperlink(int type) {
         return new HSSFHyperlink(type);
     }
+    @Override
+    public HSSFHyperlink createHyperlink(HyperlinkType type) {
+        return new HSSFHyperlink(type);
+    }
 
     @Override
     public HSSFExtendedColor createExtendedColor() {
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFHyperlink.java b/src/java/org/apache/poi/hssf/usermodel/HSSFHyperlink.java
index 1f3175121c..d91498679c 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFHyperlink.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFHyperlink.java
@@ -16,37 +16,15 @@
 ==================================================================== */
 package org.apache.poi.hssf.usermodel;
 
+import org.apache.poi.common.usermodel.HyperlinkType;
 import org.apache.poi.hssf.record.HyperlinkRecord;
 import org.apache.poi.ss.usermodel.Hyperlink;
+import org.apache.poi.util.Internal;
 
 /**
  * Represents an Excel hyperlink.
  */
-public class HSSFHyperlink implements Hyperlink {

-

-    /**

-     * Link to an existing file or web page
-     * May be deprecated in the future. Consider using {@link Hyperlink#LINK_URL} instead.

-     */

-    public static final int LINK_URL = Hyperlink.LINK_URL;

-

-    /**
-     * Link to a place in this document
-     * May be deprecated in the future. Consider using {@link Hyperlink#LINK_DOCUMENT} instead.
-     */
-    public static final int LINK_DOCUMENT = Hyperlink.LINK_DOCUMENT;
-
-    /**
-     * Link to an E-mail address
-     * May be deprecated in the future. Consider using {@link Hyperlink#LINK_EMAIL} instead.
-     */
-    public static final int LINK_EMAIL = Hyperlink.LINK_EMAIL;
-
-    /**
-     * Link to a file
-     * May be deprecated in the future. Consider using {@link Hyperlink#LINK_FILE} instead.
-     */
-    public static final int LINK_FILE = Hyperlink.LINK_FILE;
+public class HSSFHyperlink implements Hyperlink {
 
     /**
      * Low-level record object that stores the actual hyperlink data
@@ -56,26 +34,43 @@ public class HSSFHyperlink implements Hyperlink {
     /**

      * If we create a new hyperlink remember its type

      */

-    final protected int link_type;

-

+    final protected HyperlinkType link_type;

+
     /**
      * Construct a new hyperlink
+     * 
+     * This method is internal to be used only by {@link HSSFCreationHelper#createHyperlink(int)}
      *
      * @param type the type of hyperlink to create
+     * @deprecated POI 3.15 beta 3
      */
-    public HSSFHyperlink( int type )
+    @Internal(since="3.15 beta 3")
+    protected HSSFHyperlink( int type )
+    {
+        this(HyperlinkType.forInt(type));
+    }
+    

+    /**
+     * Construct a new hyperlink
+     * 
+     * This method is internal to be used only by {@link HSSFCreationHelper#createHyperlink(int)}
+     *
+     * @param type the type of hyperlink to create
+     */
+    @Internal(since="3.15 beta 3")
+    protected HSSFHyperlink( HyperlinkType type )
     {
         this.link_type = type;
         record = new HyperlinkRecord();
         switch(type){
-            case LINK_URL:
-            case LINK_EMAIL:
+            case URL:
+            case EMAIL:
                 record.newUrlLink();
                 break;
-            case LINK_FILE:
+            case FILE:
                 record.newFileLink();
                 break;
-            case LINK_DOCUMENT:
+            case DOCUMENT:
                 record.newDocumentLink();
                 break;
             default:
@@ -94,19 +89,19 @@ public class HSSFHyperlink implements Hyperlink {
         link_type = getType(record);
     }
     
-    private int getType(HyperlinkRecord record) {
-        int link_type;
+    private static HyperlinkType getType(HyperlinkRecord record) {
+        HyperlinkType link_type;
         // Figure out the type
         if (record.isFileLink()) {
-            link_type = LINK_FILE;
+            link_type = HyperlinkType.FILE;
         } else if(record.isDocumentLink()) {
-            link_type = LINK_DOCUMENT;
+            link_type = HyperlinkType.DOCUMENT;
         } else {
             if(record.getAddress() != null &&
                     record.getAddress().startsWith("mailto:")) {
-                link_type = LINK_EMAIL;
+                link_type = HyperlinkType.EMAIL;
             } else {
-                link_type = LINK_URL;
+                link_type = HyperlinkType.URL;
             }
         }
         return link_type;
@@ -119,7 +114,7 @@ public class HSSFHyperlink implements Hyperlink {
             link_type = getType(record);
         }
         else {
-            link_type = other.getType();
+            link_type = other.getTypeEnum();
             record = new HyperlinkRecord();
             setFirstRow(other.getFirstRow());
             setFirstColumn(other.getFirstColumn());
@@ -275,9 +270,20 @@ public class HSSFHyperlink implements Hyperlink {
      * Return the type of this hyperlink
      *
      * @return the type of this hyperlink
+     * @see HyperlinkType#forInt
+     */
+    @Override
+    public int getType() {
+        return link_type.getCode();
+    }
+    
+    /**
+     * Return the type of this hyperlink
+     *
+     * @return the type of this hyperlink
      */
     @Override
-    public int getType(){
+    public HyperlinkType getTypeEnum() {
         return link_type;
     }
     
diff --git a/src/java/org/apache/poi/ss/usermodel/CreationHelper.java b/src/java/org/apache/poi/ss/usermodel/CreationHelper.java
index 749cacf0b7..25e1cdaae8 100644
--- a/src/java/org/apache/poi/ss/usermodel/CreationHelper.java
+++ b/src/java/org/apache/poi/ss/usermodel/CreationHelper.java
@@ -16,6 +16,8 @@
 ==================================================================== */
 package org.apache.poi.ss.usermodel;
 
+import org.apache.poi.common.usermodel.HyperlinkType;
+
 /**
  * An object that handles instantiating concrete
  *  classes of the various instances one needs for
@@ -42,8 +44,15 @@ public interface CreationHelper {
 
     /**
      * Creates a new Hyperlink, of the given type
+     * @deprecated POI 3.15 beta 3. Use {@link #createHyperlink(HyperlinkType)} instead.
      */
+    @Deprecated
     Hyperlink createHyperlink(int type);
+    
+    /**
+     * Creates a new Hyperlink, of the given type
+     */
+    Hyperlink createHyperlink(HyperlinkType type);
 
     /**
      * Creates FormulaEvaluator - an object that evaluates formula cells.