bug 59804: indicate when features were @Internal-ized

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

diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java b/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java
index 6974360a7a9eda81a153c302691262c1a2607e8e..cbcfa70829814cb158df3bd82a79f9d79e2fe6df 100644 (file)
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java
@@ -151,7 +151,7 @@ public class HSSFCell implements Cell {
                        CellType type)
     {
         checkBounds(col);
-        _cellType     = CellType._UNINITIALIZED; // Force 'setCellType' to create a first Record
+        _cellType     = CellType._NONE; // Force 'setCellType' to create a first Record
         _stringValue  = null;
         _book    = book;
         _sheet   = sheet;
@@ -434,7 +434,7 @@ public class HSSFCell implements Cell {
                 throw new IllegalStateException("Invalid cell type: " + cellType);
         }
         if (cellType != _cellType &&
-            _cellType != CellType._UNINITIALIZED )  // Special Value to indicate an uninitialized Cell
+            _cellType != CellType._NONE )  // Special Value to indicate an uninitialized Cell
         {
             _sheet.getSheet().replaceValueRecord(_record);
         }
@@ -459,7 +459,7 @@ public class HSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum()
     {
@@ -1169,7 +1169,7 @@ public class HSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum() {
         if (_cellType != CellType.FORMULA) {

diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationCell.java b/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationCell.java
index 808655a5390f09e12a8d984f02b04cfb4310857d..d6f2d9b7b9760d1e6faee0f245872fbe84a1ca2d 100644 (file)
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationCell.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationCell.java
@@ -65,7 +65,7 @@ final class HSSFEvaluationCell implements EvaluationCell {
         * @deprecated POI 3.15 beta 3.
         * Will be deleted when we make the CellType enum transition. See bug 59791.
         */
-       @Internal
+       @Internal(since="POI 3.15 beta 3")
        @Override
        public CellType getCellTypeEnum() {
                return _cell.getCellTypeEnum();
@@ -109,7 +109,7 @@ final class HSSFEvaluationCell implements EvaluationCell {
         * @deprecated POI 3.15 beta 3.
         * Will be deleted when we make the CellType enum transition. See bug 59791.
         */
-       @Internal\r
+       @Internal(since="POI 3.15 beta 3")
        @Override
        public CellType getCachedFormulaResultTypeEnum() {\r
                return _cell.getCachedFormulaResultTypeEnum();\r

diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFFormulaEvaluator.java b/src/java/org/apache/poi/hssf/usermodel/HSSFFormulaEvaluator.java
index 139df673da000ae8cb3348a1935e849afd81385f..a6f39a5f0624a17faf7c6c9c64aabaf70f553f2a 100644 (file)
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFFormulaEvaluator.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFFormulaEvaluator.java
@@ -220,25 +220,26 @@ public class HSSFFormulaEvaluator implements FormulaEvaluator, WorkbookEvaluator
        
        /**
         * If cell contains formula, it evaluates the formula, and saves the result of the formula. The
-        * cell remains as a formula cell. If the cell does not contain formula, this method returns -1
-        * and leaves the cell unchanged.
+        * cell remains as a formula cell. If the cell does not contain formula, rather than throwing an
+        * exception, this method returns {@link CellType#_NONE} and leaves the cell unchanged.
         *
         * Note that the type of the <em>formula result</em> is returned, so you know what kind of
         * cached formula result is also stored with  the formula.
         * <pre>
-        * int evaluatedCellType = evaluator.evaluateFormulaCell(cell);
+        * CellType evaluatedCellType = evaluator.evaluateFormulaCell(cell);
         * </pre>
         * Be aware that your cell will hold both the formula, and the result. If you want the cell
         * replaced with the result of the formula, use {@link #evaluateInCell(org.apache.poi.ss.usermodel.Cell)}
         * @param cell The cell to evaluate
-        * @return -1 for non-formula cells, or the type of the <em>formula result</em>
+        * @return {@link CellType#_NONE} for non-formula cells, or the type of the <em>formula result</em>
+        * @since POI 3.15 beta 3
         * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
         */
        @Internal
        @Override
        public CellType evaluateFormulaCellEnum(Cell cell) {
                if (cell == null || cell.getCellTypeEnum() != CellType.FORMULA) {
-                       return CellType._UNINITIALIZED;
+                       return CellType._NONE;
                }
                CellValue cv = evaluateFormulaCellValue(cell);
                // cell remains a formula cell, but the cached value is changed

diff --git a/src/java/org/apache/poi/ss/format/CellFormat.java b/src/java/org/apache/poi/ss/format/CellFormat.java
index 30f0056238f3b1a6be90aab68cce084c42d8a94c..e47d40c4f1b06b96c751691cd9d38f9e937b42ed 100644 (file)
--- a/src/java/org/apache/poi/ss/format/CellFormat.java
+++ b/src/java/org/apache/poi/ss/format/CellFormat.java
@@ -439,7 +439,7 @@ public class CellFormat {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     public static CellType ultimateTypeEnum(Cell cell) {
         CellType type = cell.getCellTypeEnum();
         if (type == CellType.FORMULA)

diff --git a/src/java/org/apache/poi/ss/formula/eval/forked/ForkedEvaluationCell.java b/src/java/org/apache/poi/ss/formula/eval/forked/ForkedEvaluationCell.java
index d961439a35675b4f85caccc12199add373c4d2ab..0521e0889e9f0bee3d6e2e7b4804022a857530cf 100644 (file)
--- a/src/java/org/apache/poi/ss/formula/eval/forked/ForkedEvaluationCell.java
+++ b/src/java/org/apache/poi/ss/formula/eval/forked/ForkedEvaluationCell.java
@@ -118,7 +118,7 @@ final class ForkedEvaluationCell implements EvaluationCell {
         * @deprecated POI 3.15 beta 3.
         * Will be deleted when we make the CellType enum transition. See bug 59791.
         */
-       @Internal
+       @Internal(since="POI 3.15 beta 3")
        @Override
        public CellType getCellTypeEnum() {
                return _cellType;
@@ -170,7 +170,7 @@ final class ForkedEvaluationCell implements EvaluationCell {
         * @deprecated POI 3.15 beta 3.
         * Will be deleted when we make the CellType enum transition. See bug 59791.
         */
-       @Internal
+       @Internal(since="POI 3.15 beta 3")
        @Override
        public CellType getCachedFormulaResultTypeEnum() {
                return _masterCell.getCachedFormulaResultTypeEnum();

diff --git a/src/java/org/apache/poi/ss/usermodel/Cell.java b/src/java/org/apache/poi/ss/usermodel/Cell.java
index 68bc8f67e684c2921bd837cc818bb27c72e4c2c3..95840a6c011e60dc77f3cbed1dc98810846c8710 100644 (file)
--- a/src/java/org/apache/poi/ss/usermodel/Cell.java
+++ b/src/java/org/apache/poi/ss/usermodel/Cell.java
@@ -170,7 +170,7 @@ public interface Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     CellType getCellTypeEnum();
     
     /**
@@ -194,7 +194,7 @@ public interface Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     CellType getCachedFormulaResultTypeEnum();
 
     /**

diff --git a/src/java/org/apache/poi/ss/usermodel/CellType.java b/src/java/org/apache/poi/ss/usermodel/CellType.java
index 1d31b8473f369b68bc45b83a2da32a6b3ae22741..c8e81c9c1ad64569fd668176b79606ae5b2ff8dc 100644 (file)
--- a/src/java/org/apache/poi/ss/usermodel/CellType.java
+++ b/src/java/org/apache/poi/ss/usermodel/CellType.java
@@ -24,13 +24,20 @@ import org.apache.poi.util.Internal;
  * @since POI 3.15 beta 3
  */
 public enum CellType {
-    @Internal
-    _UNINITIALIZED(-1),
+    /**
+     * Unknown type, used to represent a state prior to initialization or the
+     * lack of a concrete type.
+     * For internal use only.
+     */
+    @Internal(since="POI 3.15 beta 3")
+    _NONE(-1),
 
-    /** Numeric cell type (whole numbers, fractional numbers, dates) */
+    /**
+     * Numeric cell type (whole numbers, fractional numbers, dates)
+     */
     NUMERIC(0),
     
-    /** String cell type */
+    /** String (text) cell type */
     STRING(1),
     
     /**

diff --git a/src/java/org/apache/poi/ss/usermodel/FormulaEvaluator.java b/src/java/org/apache/poi/ss/usermodel/FormulaEvaluator.java
index 89cc8daa3647ee067d928bfc327ba451beb558e0..be75ff9d559ef0cae2fc5f21a05bc2fb751eb595 100644 (file)
--- a/src/java/org/apache/poi/ss/usermodel/FormulaEvaluator.java
+++ b/src/java/org/apache/poi/ss/usermodel/FormulaEvaluator.java
@@ -126,7 +126,7 @@ public interface FormulaEvaluator {
      *      Note: the cell's type remains as CellType.FORMULA however.
      * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     CellType evaluateFormulaCellEnum(Cell cell);
 
     /**

diff --git a/src/java/org/apache/poi/ss/util/SheetUtil.java b/src/java/org/apache/poi/ss/util/SheetUtil.java
index 7cc7a10a8e6f3e4475ee9e31cd21934388847bd2..d64dbeba82ad579df87f61b1edc67064c5dc5847 100644 (file)
--- a/src/java/org/apache/poi/ss/util/SheetUtil.java
+++ b/src/java/org/apache/poi/ss/util/SheetUtil.java
@@ -93,8 +93,11 @@ public class SheetUtil {
         public int evaluateFormulaCell(Cell cell) {
             return cell.getCachedFormulaResultType();
         }
-        /** @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791. */
-        @Internal
+        /** 
+         * @since POI 3.15 beta 3
+         * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
+         */
+        @Internal(since="POI 3.15 beta 3")
         @Override
         public CellType evaluateFormulaCellEnum(Cell cell) {
             return cell.getCachedFormulaResultTypeEnum();

diff --git a/src/java/org/apache/poi/util/BitField.java b/src/java/org/apache/poi/util/BitField.java
index 92717e6d83676e4ca688d3a17b05341863335e41..012e6acf900d00378c7a07a5da2c4005e9ab911a 100644 (file)
--- a/src/java/org/apache/poi/util/BitField.java
+++ b/src/java/org/apache/poi/util/BitField.java
@@ -25,7 +25,7 @@ package org.apache.poi.util;
  * @author Marc Johnson (mjohnson at apache dot org)
  * @author Andrew C. Oliver (acoliver at apache dot org)
  */
-@Internal
+@Internal(since="POI 3.15 beta 3")
 public class BitField
 {
     private final int _mask;

diff --git a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFCell.java b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFCell.java
index 040bec06c6352fa2132b29504d24b687378d0572..6c6574443a179e1eadbac1de6649bff125ff034f 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFCell.java
+++ b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFCell.java
@@ -174,7 +174,7 @@ public class SXSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum()
     {
@@ -202,7 +202,7 @@ public class SXSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3.
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum()
     {

diff --git a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFEvaluationCell.java b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFEvaluationCell.java
index bdb9d64e985ebaeb08ac31049990283ae5544c0e..872bd7ba83053e4d67a22d554f53c5755a162787 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFEvaluationCell.java
+++ b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFEvaluationCell.java
@@ -67,7 +67,7 @@ final class SXSSFEvaluationCell implements EvaluationCell {
      * @deprecated POI 3.15 beta 3.
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum() {
         return _cell.getCellTypeEnum();
@@ -111,7 +111,7 @@ final class SXSSFEvaluationCell implements EvaluationCell {
      * @deprecated POI 3.15 beta 3.
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal\r
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum() {\r
         return _cell.getCachedFormulaResultTypeEnum();\r

diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java
index c28b0762a5925e3b7812d54398ba90aac7ad6dab..5fe8660b1d7239c168406ad8e9c27d0ead86a454 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java
@@ -134,12 +134,14 @@ public abstract class BaseXSSFFormulaEvaluator implements FormulaEvaluator, Work
      *  the result of the formula, use {@link #evaluate(org.apache.poi.ss.usermodel.Cell)} }
      * @param cell The cell to evaluate
      * @return The type of the formula result (the cell's type remains as CellType.FORMULA however)
+     *         If cell is not a formula cell, returns {@link CellType#_NONE} rather than throwing an exception.
+     * @since POI 3.15 beta 3
      * @deprecated POI 3.15 beta 3. Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     public CellType evaluateFormulaCellEnum(Cell cell) {
         if (cell == null || cell.getCellTypeEnum() != CellType.FORMULA) {
-            return CellType._UNINITIALIZED;
+            return CellType._NONE;
         }
         CellValue cv = evaluateFormulaCellValue(cell);
         // cell remains a formula cell, but the cached value is changed

diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
index 44432a8bf5b03329d27aae4f7187bf73ed6a8a77..b0287e05c8aa893b2b590dd5307a3c788cd58ff9 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java
@@ -682,7 +682,7 @@ public final class XSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCellTypeEnum() {
         if (isFormulaCell()) return CellType.FORMULA;
@@ -714,7 +714,7 @@ public final class XSSFCell implements Cell {
      * @deprecated POI 3.15 beta 3
      * Will be deleted when we make the CellType enum transition. See bug 59791.
      */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     @Override
     public CellType getCachedFormulaResultTypeEnum() {
         if (! isFormulaCell()) {

diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvaluationCell.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvaluationCell.java
index 97e92c3c8ee5e43dd1b8011990822dca93cd5f3d..9b67016341a69202e09fee25ac777415687b0770 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvaluationCell.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFEvaluationCell.java
@@ -68,7 +68,7 @@ final class XSSFEvaluationCell implements EvaluationCell {
         * @deprecated POI 3.15 beta 3.
         * Will be deleted when we make the CellType enum transition. See bug 59791.
         */
-       @Internal
+       @Internal(since="POI 3.15 beta 3")
        @Override
        public CellType getCellTypeEnum() {
                return _cell.getCellTypeEnum();
@@ -112,7 +112,7 @@ final class XSSFEvaluationCell implements EvaluationCell {
         * @deprecated POI 3.15 beta 3.
         * Will be deleted when we make the CellType enum transition. See bug 59791.
         */
-       @Internal\r
+       @Internal(since="POI 3.15 beta 3")
        @Override
        public CellType getCachedFormulaResultTypeEnum() {\r
                return _cell.getCachedFormulaResultTypeEnum();\r

diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFTable.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFTable.java
index d832f5bea28d8def88672c37d1b3902b753285d3..f989d65304eee94ba40a16fc9945dc1ac7991493 100644 (file)
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFTable.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFTable.java
@@ -117,7 +117,7 @@ public class XSSFTable extends POIXMLDocumentPart implements Table {
     /**
       * get the underlying CTTable XML bean
       */
-    @Internal
+    @Internal(since="POI 3.15 beta 3")
     public CTTable getCTTable() {
         return ctTable;
     }

diff --git a/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFBugs.java b/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFBugs.java
index 39096ecd51b70c9e9038ffaef6d0e289fa8b8e1e..9b3455e61326aca616a30c35ab178260bf9e9c7d 100644 (file)
--- a/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFBugs.java
+++ b/src/ooxml/testcases/org/apache/poi/xssf/usermodel/TestXSSFBugs.java
@@ -2959,7 +2959,7 @@ public final class TestXSSFBugs extends BaseTestBugzillaIssues {
         cell = row.getCell(1);
 
         assertEquals(CellType.BLANK, cell.getCellTypeEnum());
-        assertEquals(CellType._UNINITIALIZED, evaluator.evaluateFormulaCellEnum(cell));
+        assertEquals(CellType._NONE, evaluator.evaluateFormulaCellEnum(cell));
 
         // A3
         row = worksheet.getRow(2);