Patch 48284 - raise visibility of FormulaParseException

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

6 files changed, 86 insertions, 76 deletions

diff --git a/src/java/org/apache/poi/hssf/model/HSSFFormulaParser.java b/src/java/org/apache/poi/hssf/model/HSSFFormulaParser.java
index 026590d71d..d65943b564 100644
--- a/src/java/org/apache/poi/hssf/model/HSSFFormulaParser.java
+++ b/src/java/org/apache/poi/hssf/model/HSSFFormulaParser.java
@@ -20,6 +20,7 @@ package org.apache.poi.hssf.model;
 import org.apache.poi.hssf.record.formula.Ptg;
 import org.apache.poi.hssf.usermodel.HSSFEvaluationWorkbook;
 import org.apache.poi.hssf.usermodel.HSSFWorkbook;
+import org.apache.poi.ss.formula.FormulaParseException;
 import org.apache.poi.ss.formula.FormulaParser;
 import org.apache.poi.ss.formula.FormulaParsingWorkbook;
 import org.apache.poi.ss.formula.FormulaRenderer;
@@ -41,17 +42,18 @@ public final class HSSFFormulaParser {
 	}
 
 	/**
-	 * Convenience method for parsing cell formulas. see {@link #parse(String, HSSFWorkbook, int)}
+	 * Convenience method for parsing cell formulas. see {@link #parse(String, HSSFWorkbook, int, int)}
 	 */
-	public static Ptg[] parse(String formula, HSSFWorkbook workbook) {
+	public static Ptg[] parse(String formula, HSSFWorkbook workbook) throws FormulaParseException {
 		return parse(formula, workbook, FormulaType.CELL);
 	}
 
 	/**
 	 * @param formulaType a constant from {@link FormulaType}
 	 * @return the parsed formula tokens
+     * @throws FormulaParseException if the formula has incorrect syntax or is otherwise invalid
 	 */
-	public static Ptg[] parse(String formula, HSSFWorkbook workbook, int formulaType) {
+	public static Ptg[] parse(String formula, HSSFWorkbook workbook, int formulaType) throws FormulaParseException {
 		return parse(formula, workbook, formulaType, -1);
 	}
 
@@ -64,8 +66,9 @@ public final class HSSFFormulaParser {
 	 * the scope of the name will be ignored and  the parser will match named ranges only by name
 	 *
 	 * @return the parsed formula tokens
+     * @throws FormulaParseException if the formula has incorrect syntax or is otherwise invalid
 	 */
-	public static Ptg[] parse(String formula, HSSFWorkbook workbook, int formulaType, int sheetIndex) {
+	public static Ptg[] parse(String formula, HSSFWorkbook workbook, int formulaType, int sheetIndex) throws FormulaParseException {
 		return FormulaParser.parse(formula, createParsingWorkbook(workbook), formulaType, sheetIndex);
 	}
 
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java b/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java
index 701b7ce746..ad1c53545d 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFCell.java
@@ -81,7 +81,7 @@ public class HSSFCell implements Cell {
      */
     public static final int LAST_COLUMN_NUMBER  = SpreadsheetVersion.EXCEL97.getLastColumnIndex(); // 2^8 - 1
     private static final String LAST_COLUMN_NAME  = SpreadsheetVersion.EXCEL97.getLastColumnName();
-    
+
     public final static short        ENCODING_UNCHANGED          = -1;
     public final static short        ENCODING_COMPRESSED_UNICODE = 0;
     public final static short        ENCODING_UTF_16             = 1;
@@ -507,7 +507,7 @@ public class HSSFCell implements Cell {
     }
 
     /**
-     * set a string value for the cell. 
+     * set a string value for the cell.
      *
      * @param value value to set the cell to.  For formulas we'll set the formula
      * cached string result, for String cells we'll set its value. For other types we will
@@ -573,17 +573,6 @@ public class HSSFCell implements Cell {
         _stringValue.setUnicodeString(_book.getWorkbook().getSSTString(index));
     }
 
-    /**
-     * Sets formula for this cell.
-     * <p>
-     * Note, this method only sets the formula string and does not calculate the formula value.
-     * To set the precalculated value use {@link #setCellValue(double)} or {@link #setCellValue(String)}
-     * </p>
-     *
-     * @param formula the formula to set, e.g. <code>SUM(C4:E4)</code>.
-     *  If the argument is <code>null</code> then the current formula is removed.
-     * @throws IllegalArgumentException if the formula is unparsable
-     */
     public void setCellFormula(String formula) {
         int row=_record.getRow();
         short col=_record.getColumn();
@@ -918,8 +907,8 @@ public class HSSFCell implements Cell {
      */
     private static void checkBounds(int cellIndex) {
         if (cellIndex < 0 || cellIndex > LAST_COLUMN_NUMBER) {
-            throw new IllegalArgumentException("Invalid column index (" + cellIndex 
-                    + ").  Allowable column range for " + FILE_FORMAT_NAME + " is (0.." 
+            throw new IllegalArgumentException("Invalid column index (" + cellIndex
+                    + ").  Allowable column range for " + FILE_FORMAT_NAME + " is (0.."
                     + LAST_COLUMN_NUMBER + ") or ('A'..'" + LAST_COLUMN_NAME + "')");
         }
     }
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationWorkbook.java b/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationWorkbook.java
index 824fa46d80..7b55d81db7 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationWorkbook.java
+++ b/src/java/org/apache/poi/hssf/usermodel/HSSFEvaluationWorkbook.java
@@ -29,6 +29,7 @@ import org.apache.poi.ss.formula.EvaluationCell;
 import org.apache.poi.ss.formula.EvaluationName;
 import org.apache.poi.ss.formula.EvaluationSheet;
 import org.apache.poi.ss.formula.EvaluationWorkbook;
+import org.apache.poi.ss.formula.FormulaParseException;
 import org.apache.poi.ss.formula.FormulaParsingWorkbook;
 import org.apache.poi.ss.formula.FormulaRenderingWorkbook;
 import org.apache.poi.ss.formula.FormulaType;
@@ -129,7 +130,7 @@ public final class HSSFEvaluationWorkbook implements FormulaRenderingWorkbook, E
 			// to make sure that all formulas POI can evaluate can also be parsed.
 			try {
 				return HSSFFormulaParser.parse(cell.getCellFormula(), _uBook, FormulaType.CELL, _uBook.getSheetIndex(cell.getSheet()));
-			} catch (RuntimeException e) {
+			} catch (FormulaParseException e) {
 				// Note - as of Bugzilla 48036 (svn r828244, r828247) POI is capable of evaluating
 				// IntesectionPtg.  However it is still not capable of parsing it.
 				// So FormulaEvalTestData.xls now contains a few formulas that produce errors here.
diff --git a/src/java/org/apache/poi/ss/formula/FormulaParseException.java b/src/java/org/apache/poi/ss/formula/FormulaParseException.java
new file mode 100644
index 0000000000..4b1040f16d
--- /dev/null
+++ b/src/java/org/apache/poi/ss/formula/FormulaParseException.java
@@ -0,0 +1,33 @@
+/* ====================================================================
+   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.formula;
+
+/**
+ * This exception thrown when a supplied formula has incorrect syntax (or syntax currently not
+ * supported by POI).  It  is primarily used by test code to confirm specific parsing exceptions.
+ * Application code should also handle this exception if it potentially supplies formula text
+ * that is not guaranteed to be well-formed.
+ *
+ * @author Josh Micich
+ */
+public final class FormulaParseException extends RuntimeException {
+
+	FormulaParseException(String msg) {
+		super(msg);
+	}
+}
diff --git a/src/java/org/apache/poi/ss/formula/FormulaParser.java b/src/java/org/apache/poi/ss/formula/FormulaParser.java
index 0a7b56812e..adb4bd8779 100644
--- a/src/java/org/apache/poi/ss/formula/FormulaParser.java
+++ b/src/java/org/apache/poi/ss/formula/FormulaParser.java
@@ -24,7 +24,6 @@ import java.util.regex.Pattern;
 import org.apache.poi.hssf.record.UnicodeString;
 import org.apache.poi.hssf.record.constant.ErrorConstant;
 import org.apache.poi.hssf.record.formula.*;
-import org.apache.poi.hssf.record.formula.ValueOperatorPtg;
 import org.apache.poi.hssf.record.formula.function.FunctionMetadata;
 import org.apache.poi.hssf.record.formula.function.FunctionMetadataRegistry;
 import org.apache.poi.hssf.usermodel.HSSFErrorConstants;
@@ -42,6 +41,10 @@ import org.apache.poi.ss.SpreadsheetVersion;
  * <term> ::= <factor>  [ <mulop> <factor> ]*
  * <factor> ::= <number> | (<expression>) | <cellRef> | <function>
  * <function> ::= <functionName> ([expression [, expression]*])
+ * <p/>
+ * For POI internal use only
+ * <p/>
+ *
  *
  *  @author Avik Sengupta <avik at apache dot org>
  *  @author Andrew C. oliver (acoliver at apache dot org)
@@ -111,20 +114,6 @@ public final class FormulaParser {
 		}
 	}
 
-	/**
-	 * Specific exception thrown when a supplied formula does not parse properly.<br/>
-	 * Primarily used by test cases when testing for specific parsing exceptions.</p>
-	 *
-	 */
-	static final class FormulaParseException extends RuntimeException {
-		// This class was given package scope until it would become clear that it is useful to
-		// general client code.
-		public FormulaParseException(String msg) {
-			super(msg);
-		}
-	}
-
-
 	private final String _formulaString;
 	private final int _formulaLength;
 	/** points at the next character to be read (after the {@link #look} char) */
@@ -141,7 +130,7 @@ public final class FormulaParser {
 	private char look;
 
 	private FormulaParsingWorkbook _book;
-    private SpreadsheetVersion _ssVersion;
+	private SpreadsheetVersion _ssVersion;
 
 	private int _sheetIndex;
 
@@ -162,19 +151,11 @@ public final class FormulaParser {
 		_formulaString = formula;
 		_pointer=0;
 		_book = book;
-        _ssVersion = book == null ? SpreadsheetVersion.EXCEL97 : book.getSpreadsheetVersion();
-        _formulaLength = _formulaString.length();
+		_ssVersion = book == null ? SpreadsheetVersion.EXCEL97 : book.getSpreadsheetVersion();
+		_formulaLength = _formulaString.length();
 		_sheetIndex = sheetIndex;
 	}
 
-	public static Ptg[] parse(String formula, FormulaParsingWorkbook book) {
-		return parse(formula, book, FormulaType.CELL);
-	}
-
-	public static Ptg[] parse(String formula, FormulaParsingWorkbook workbook, int formulaType) {
-		return parse(formula, workbook, formulaType, -1);
-	}
-
 	/**
 	 * Parse a formula into a array of tokens
 	 *
@@ -186,7 +167,7 @@ public final class FormulaParser {
 	 * the scope of the name will be ignored and  the parser will match names only by name
 	 *
 	 * @return array of parsed tokens
-	 * @throws FormulaParseException if the formula is unparsable
+	 * @throws FormulaParseException if the formula has incorrect syntax or is otherwise invalid
 	 */
 	public static Ptg[] parse(String formula, FormulaParsingWorkbook workbook, int formulaType, int sheetIndex) {
 		FormulaParser fp = new FormulaParser(formula, workbook, sheetIndex);
@@ -702,7 +683,7 @@ public final class FormulaParser {
 			if (!isValidCellReference(rep)) {
 				return null;
 			}
-        } else if (hasLetters) {
+		} else if (hasLetters) {
 			if (!CellReference.isColumnWithnRange(rep.replace("$", ""), _ssVersion)) {
 				return null;
 			}
@@ -881,29 +862,29 @@ public final class FormulaParser {
 	 * @return <code>true</code> if the specified name is a valid cell reference
 	 */
 	private boolean isValidCellReference(String str) {
-        //check range bounds against grid max
-        boolean result = CellReference.classifyCellReference(str, _ssVersion) == NameType.CELL;
-
-        if(result){
-            /**
-             * Check if the argument is a function. Certain names can be either a cell reference or a function name
-             * depending on the contenxt. Compare the following examples in Excel 2007:
-             * (a) LOG10(100) + 1
-             * (b) LOG10 + 1
-             * In (a) LOG10 is a name of a built-in function. In (b) LOG10 is a cell reference
-             */
-            boolean isFunc = FunctionMetadataRegistry.getFunctionByName(str.toUpperCase()) != null;
-            if(isFunc){
-                int savePointer = _pointer;
-                resetPointer(_pointer + str.length());
-                SkipWhite();
-                // open bracket indicates that the argument is a function,
-                // the returning value should be false, i.e. "not a valid cell reference"
-                result = look != '(';
-                resetPointer(savePointer);
-            }
-        }
-        return result;
+		//check range bounds against grid max
+		boolean result = CellReference.classifyCellReference(str, _ssVersion) == NameType.CELL;
+
+		if(result){
+			/**
+			 * Check if the argument is a function. Certain names can be either a cell reference or a function name
+			 * depending on the contenxt. Compare the following examples in Excel 2007:
+			 * (a) LOG10(100) + 1
+			 * (b) LOG10 + 1
+			 * In (a) LOG10 is a name of a built-in function. In (b) LOG10 is a cell reference
+			 */
+			boolean isFunc = FunctionMetadataRegistry.getFunctionByName(str.toUpperCase()) != null;
+			if(isFunc){
+				int savePointer = _pointer;
+				resetPointer(_pointer + str.length());
+				SkipWhite();
+				// open bracket indicates that the argument is a function,
+				// the returning value should be false, i.e. "not a valid cell reference"
+				result = look != '(';
+				resetPointer(savePointer);
+			}
+		}
+		return result;
 	}
 
 
diff --git a/src/java/org/apache/poi/ss/usermodel/Cell.java b/src/java/org/apache/poi/ss/usermodel/Cell.java
index 0d581db352..17af1831d6 100644
--- a/src/java/org/apache/poi/ss/usermodel/Cell.java
+++ b/src/java/org/apache/poi/ss/usermodel/Cell.java
@@ -20,6 +20,8 @@ package org.apache.poi.ss.usermodel;
 import java.util.Calendar;
 import java.util.Date;
 
+import org.apache.poi.ss.formula.FormulaParseException;
+
 /**
  * High level representation of a cell in a row of a spreadsheet.
  * <p>
@@ -76,7 +78,7 @@ public interface Cell {
      * @see #getCellType()
      */
     public final static int CELL_TYPE_ERROR = 5;
-    
+
     /**
      * Returns column index of this cell
      *
@@ -158,7 +160,7 @@ public interface Cell {
      * data type is now something besides {@link Cell#CELL_TYPE_NUMERIC}.  POI
      * does not attempt to replicate this behaviour.  To make a numeric cell
      * display as a date, use {@link #setCellStyle(CellStyle)} etc.
-     * 
+     *
      * @param value the numeric value to set this cell to.  For formulas we'll set the
      *        precalculated value, for numerics we'll set its value. For other types we
      *        will change the cell to a numerics cell and set its value.
@@ -203,6 +205,7 @@ public interface Cell {
      */
     void setCellValue(String value);
 
+
     /**
      * Sets formula for this cell.
      * <p>
@@ -210,11 +213,11 @@ public interface Cell {
      * To set the precalculated value use {@link #setCellValue(double)} or {@link #setCellValue(String)}
      * </p>
      *
-     * @param formula the formula to set, e.g. <code>SUM(C4:E4)</code>.
+     * @param formula the formula to set, e.g. <code>"SUM(C4:E4)"</code>.
      *  If the argument is <code>null</code> then the current formula is removed.
-     * @throws IllegalArgumentException if the formula is unparsable
+     * @throws FormulaParseException if the formula has incorrect syntax or is otherwise invalid
      */
-    void setCellFormula(String formula);
+    void setCellFormula(String formula) throws FormulaParseException;
 
     /**
      * Return a formula for the cell, for example, <code>SUM(C4:E4)</code>