bug# 45973: added factory method for FormulaEvaluator, also fixed unpaired tags in javadocs

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

src/documentation/content/xdocs/changes.xml

@@ -37,6 +37,7 @@
 
 		<!-- Don't forget to update status.xml too! -->
         <release version="3.5-beta4" date="2008-??-??">
+           <action dev="POI-DEVELOPERS" type="add">45973 - added CreationHelper.createFormulaEvaluator(), implemeted both for HSSF and XSSF</action>
            <action dev="POI-DEVELOPERS" type="fix">46182 - fixed Slideshow.readPictures() to skip pictures with invalid headers</action>
            <action dev="POI-DEVELOPERS" type="fix">46137 - Handle odd files with a ContinueRecord after EOFRecord</action>
            <action dev="POI-DEVELOPERS" type="fix">Fixed problem with linking shared formulas when ranges overlap</action>

src/documentation/content/xdocs/spreadsheet/eval.xml

@@ -32,10 +32,7 @@
 				formulas in Excels sheets read-in, or created in POI. This document explains
 				how to use the API to evaluate your formulas. 
 			</p>
-			<note>In versions of POI before 3.0.3, this code lived in the
-				scratchpad area of the POI SVN repository. If using an such an older
-				version of POI, ensure that you have the scratchpad jar or the 
-				scratchpad build area in your classpath before experimenting with this 
+			<note>.xlsx format is suported since POI 3.5, make sure yoy upgraded to that version before experimenting with this 
 				code. Users of all versions of POI may wish to make use of a recent 
 				SVN checkout, as new functions are currently being added fairly frequently.
 			</note>
@@ -47,7 +44,8 @@
 				It also provides implementations for approx. 100 built in 
 				functions in Excel. The framework however makes is easy to add 
 			 	implementation of new functions. See the <link href="eval-devguide.html"> Formula
-				evaluation development guide</link> for details. </p>
+        evaluation development guide</link>  and <link href="../apidocs/org/apache/poi/hssf/record/formula/functions/package-summary.html">javadocs</link> 
+        for details. </p>
             <p> Both HSSFWorkbook and XSSFWorkbook are supported, so you can 
                 evaluate formulas on both .xls and .xlsx files.</p>
 			<p> Note that user-defined functions are not supported, and is not likely to done
@@ -66,17 +64,16 @@
 				without affecting the cell</p>
 				<source>
 FileInputStream fis = new FileInputStream("c:/temp/test.xls");
-Workbook wb = new HSSFWorkbook(fis);
+Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("c:/temp/test.xls")
 Sheet sheet = wb.getSheetAt(0);
-FormulaEvaluator evaluator = new FormulaEvaluator(sheet, wb);
+FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator();
 
 // suppose your formula is in B3
 CellReference cellReference = new CellReference("B3"); 
 Row row = sheet.getRow(cellReference.getRow());
 Cell cell = row.getCell(cellReference.getCol()); 
 
-evaluator.setCurrentRow(row);
-FormulaEvaluator.CellValue cellValue = evaluator.evaluate(cell);
+CellValue cellValue = evaluator.evaluate(cell);
 
 switch (cellValue.getCellType()) {
     case Cell.CELL_TYPE_BOOLEAN:
@@ -119,23 +116,22 @@ switch (cellValue.getCellType()) {
 				formula result, such as Cell.CELL_TYPE_BOOLEAN</p>
         <source>
 FileInputStream fis = new FileInputStream("/somepath/test.xls");
-Workbook wb = new HSSFWorkbook(fis);
+Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls")
 Sheet sheet = wb.getSheetAt(0);
-FormulaEvaluator evaluator = new FormulaEvaluator(sheet, wb);
+FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator();
 
 // suppose your formula is in B3
 CellReference cellReference = new CellReference("B3"); 
 Row row = sheet.getRow(cellReference.getRow());
 Cell cell = row.getCell(cellReference.getCol()); 
-evaluator.setCurrentRow(row);
 
 if (cell!=null) {
-	switch (<strong>evaluator.evaluateFormulaCell</strong>(cell)) {
+    switch (evaluator.evaluateFormulaCell(cell)) {
         case Cell.CELL_TYPE_BOOLEAN:
             System.out.println(cell.getBooleanCellValue());
             break;
         case Cell.CELL_TYPE_NUMERIC:
-		    System.out.println(cell.getNumberCellValue());
+            System.out.println(cell.getNumericCellValue());
             break;
         case Cell.CELL_TYPE_STRING:
             System.out.println(cell.getStringCellValue());
@@ -163,23 +159,22 @@ if (cell!=null) {
 				in place of the old formula.</p>
 				<source>
 FileInputStream fis = new FileInputStream("/somepath/test.xls");
-Workbook wb = new HSSFWorkbook(fis);
+Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls")
 Sheet sheet = wb.getSheetAt(0);
-FormulaEvaluator evaluator = new FormulaEvaluator(sheet, wb);
+FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator();
 
 // suppose your formula is in B3
 CellReference cellReference = new CellReference("B3");
 Row row = sheet.getRow(cellReference.getRow());
 Cell cell = row.getCell(cellReference.getCol()); 
-evaluator.setCurrentRow(row);
 
 if (cell!=null) {
-	switch (<strong>evaluator.evaluateInCell</strong>(cell).getCellType()) {
+    switch (evaluator.<strong>evaluateInCell</strong>(cell).getCellType()) {
         case Cell.CELL_TYPE_BOOLEAN:
             System.out.println(cell.getBooleanCellValue());
             break;
         case Cell.CELL_TYPE_NUMERIC:
-		    System.out.println(cell.getNumberCellValue());
+            System.out.println(cell.getNumericCellValue());
             break;
         case Cell.CELL_TYPE_STRING:
             System.out.println(cell.getStringCellValue());
@@ -195,31 +190,27 @@ if (cell!=null) {
             break;
     }
 }
+
         </source>
 			</section>
 
 			<anchor id="EvaluateAll"/>
 			<section><title>Re-calculating all formulas in a Workbook</title>
 				<source>
+
 FileInputStream fis = new FileInputStream("/somepath/test.xls");
-Workbook wb = new HSSFWorkbook(fis);
+Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls")
+FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator();
 for(int sheetNum = 0; sheetNum &lt; wb.getNumberOfSheets(); sheetNum++) {
     Sheet sheet = wb.getSheetAt(sheetNum);
-	FormulaEvaluator evaluator = new FormulaEvaluator(sheet, wb);
-
-	for(Iterator rit = sheet.rowIterator(); rit.hasNext();) {
-		Row r = (Row)rit.next();
-		evaluator.setCurrentRow(r);
-
-		for(Iterator cit = r.cellIterator(); cit.hasNext();) {
-			Cell c = (Cell)cit.next();
+    for(Row r : sheet) {
+        for(Cell c : r) {
             if(c.getCellType() == Cell.CELL_TYPE_FORMULA) {
                 evaluator.evaluateFormulaCell(c);
             }
         }
     }
 }
-wb.write(new FileOutputStream("/somepath/changed.xls"));
         </source>
 			</section>
 		</section>

src/documentation/content/xdocs/status.xml

@@ -34,6 +34,7 @@
 	<!-- Don't forget to update changes.xml too! -->
     <changes>
         <release version="3.5-beta4" date="2008-??-??">
+           <action dev="POI-DEVELOPERS" type="add">45973 - added CreationHelper.createFormulaEvaluator(), implemeted both for HSSF and XSSF</action>
            <action dev="POI-DEVELOPERS" type="fix">46182 - fixed Slideshow.readPictures() to skip pictures with invalid headers</action>
      			 <action dev="POI-DEVELOPERS" type="fix">46137 - Handle odd files with a ContinueRecord after EOFRecord</action>
            <action dev="POI-DEVELOPERS" type="fix">Fixed problem with linking shared formulas when ranges overlap</action>

src/java/org/apache/poi/hssf/record/formula/functions/Countif.java

@@ -31,14 +31,14 @@ import org.apache.poi.hssf.record.formula.eval.StringEval;
 import org.apache.poi.hssf.record.formula.functions.CountUtils.I_MatchPredicate;
 
 /**
- * Implementation for the function COUNTIF<p/>
- * 
+ * Implementation for the function COUNTIF
+ * <p>
  *  Syntax: COUNTIF ( range, criteria )
  *    <table border="0" cellpadding="1" cellspacing="0" summary="Parameter descriptions">
  *      <tr><th>range&nbsp;&nbsp;&nbsp;</th><td>is the range of cells to be counted based on the criteria</td></tr>
  *      <tr><th>criteria</th><td>is used to determine which cells to count</td></tr>
  *    </table>
- * <p/>
+ * </p>
  * 
  * @author Josh Micich
  */

src/java/org/apache/poi/hssf/record/formula/functions/Errortype.java

@@ -25,13 +25,13 @@ import org.apache.poi.hssf.record.formula.eval.OperandResolver;
 import org.apache.poi.hssf.usermodel.HSSFErrorConstants;
 
 /**
- * Implementation for the ERROR.TYPE() Excel function.<p/>
- * 
+ * Implementation for the ERROR.TYPE() Excel function.
+ * <p>
  * <b>Syntax:</b><br/>
- * <b>ERROR.TYPE</b>(<b>errorValue</b>)<p/>
- * 
+ * <b>ERROR.TYPE</b>(<b>errorValue</b>)</p>
+ * <p>
  * Returns a number corresponding to the error type of the supplied argument.<p/>
- * 
+ * <p>
  *    <table border="1" cellpadding="1" cellspacing="1" summary="Return values for ERROR.TYPE()">
  *      <tr><td>errorValue</td><td>Return Value</td></tr>
  *      <tr><td>#NULL!</td><td>1</td></tr>
@@ -46,6 +46,7 @@ import org.apache.poi.hssf.usermodel.HSSFErrorConstants;
  * 
  * Note - the results of ERROR.TYPE() are different to the constants defined in 
  * <tt>HSSFErrorConstants</tt>.
+ * </p>
  *
  * @author Josh Micich
  */

src/java/org/apache/poi/hssf/record/formula/functions/Index.java

@@ -26,7 +26,8 @@ import org.apache.poi.hssf.record.formula.eval.RefEval;
 import org.apache.poi.hssf.record.formula.eval.ValueEval;
 
 /**
- * Implementation for the Excel function INDEX<p/>
+ * Implementation for the Excel function INDEX
+ * <p>
  * 
  * Syntax : <br/>
  *  INDEX ( reference, row_num[, column_num [, area_num]])</br>
@@ -38,7 +39,7 @@ import org.apache.poi.hssf.record.formula.eval.ValueEval;
  *      <tr><th>column_num</th><td>selects column within the array or area reference. default is 1</td></tr>
  *      <tr><th>area_num</th><td>used when reference is a union of areas</td></tr>
  *    </table>
- * <p/>
+ * </p>
  * 
  * @author Josh Micich
  */

src/java/org/apache/poi/hssf/record/formula/functions/Sumproduct.java

@@ -31,7 +31,7 @@ import org.apache.poi.hssf.record.formula.eval.ValueEval;
 
 
 /**
- * Implementation for the Excel function SUMPRODUCT<p/>
+ * Implementation for the Excel function SUMPRODUCT<p>
  * 
  * Syntax : <br/>
  *  SUMPRODUCT ( array1[, array2[, array3[, ...]]])
@@ -49,7 +49,7 @@ import org.apache.poi.hssf.record.formula.eval.ValueEval;
  * 			A<b>n</b><sub>(<b>i</b>,<b>j</b>)</sub>&nbsp;
  *    )&nbsp;
  *  ) 
- * 
+ * </p>
  * @author Josh Micich
  */
 public final class Sumproduct implements Function {

src/java/org/apache/poi/hssf/usermodel/HSSFCell.java

@@ -671,9 +671,7 @@ public class HSSFCell implements Cell {
      * get the value of the cell as a string - for numeric cells we throw an exception.
      * For blank cells we return an empty string.
      * For formulaCells that are not string Formulas, we return empty String
-     * @deprecated Use the HSSFRichTextString return
      */
-
     public String getStringCellValue()
     {
       HSSFRichTextString str = getRichStringCellValue();

src/java/org/apache/poi/hssf/usermodel/HSSFCreationHelper.java

@@ -44,4 +44,14 @@ public class HSSFCreationHelper implements CreationHelper {
 	public HSSFHyperlink createHyperlink(int type) {
 		return new HSSFHyperlink(type);
 	}
+
+    /**
+     * Creates a HSSFFormulaEvaluator, the object that evaluates formula cells.
+     *
+     * @return a HSSFFormulaEvaluator instance
+     */
+    public HSSFFormulaEvaluator createFormulaEvaluator(){
+        return new HSSFFormulaEvaluator(workbook);
+    }
+
 }

src/java/org/apache/poi/hssf/usermodel/HSSFFormulaEvaluator.java

@@ -28,6 +28,7 @@ import org.apache.poi.ss.formula.CollaboratingWorkbooksEnvironment;
 import org.apache.poi.ss.formula.WorkbookEvaluator;
 import org.apache.poi.ss.usermodel.Cell;
 import org.apache.poi.ss.usermodel.CellValue;
+import org.apache.poi.ss.usermodel.FormulaEvaluator;
 
 /**
  * Evaluates formula cells.<p/>
@@ -39,7 +40,7 @@ import org.apache.poi.ss.usermodel.CellValue;
  * @author Amol S. Deshmukh &lt; amolweb at ya hoo dot com &gt;
  * @author Josh Micich
  */
-public class HSSFFormulaEvaluator /* almost implements FormulaEvaluator */ {
+public class HSSFFormulaEvaluator implements FormulaEvaluator  {
 
     private WorkbookEvaluator _bookEvaluator;
 
@@ -111,6 +112,19 @@ public class HSSFFormulaEvaluator /* almost implements FormulaEvaluator */ {
     public void notifyDeleteCell(HSSFCell cell) {
         _bookEvaluator.notifyDeleteCell(new HSSFEvaluationCell(cell));
     }
+    public void notifyDeleteCell(Cell cell) {
+        _bookEvaluator.notifyDeleteCell(new HSSFEvaluationCell((HSSFCell)cell));
+    }
+
+    /**
+     * Should be called to tell the cell value cache that the specified (value or formula) cell
+     * has changed.
+     * Failure to call this method after changing cell values will cause incorrect behaviour
+     * of the evaluate~ methods of this class
+     */
+    public void notifySetFormula(Cell cell) {
+        _bookEvaluator.notifyUpdateCell(new HSSFEvaluationCell((HSSFCell)cell));
+    }
 
     /**
      * If cell contains a formula, the formula is evaluated and returned,

src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/Cell.java

@@ -183,6 +183,15 @@ public interface Cell {
 
     RichTextString getRichStringCellValue();
 
+    /**
+     * Get the value of the cell as a string - for numeric cells we throw an exception
+     * <p>
+     * For blank cells we return an empty string.
+     * For formulaCells that are not string Formulas, we return empty String
+     * </p>
+     */
+    String getStringCellValue();
+
     /**
      * set a boolean value for the cell
      *

src/ooxml/interfaces-jdk15/org/apache/poi/ss/usermodel/CreationHelper.java

@@ -44,4 +44,11 @@ public interface CreationHelper {
      * Creates a new Hyperlink, of the given type
      */
     Hyperlink createHyperlink(int type);
+
+    /**
+     * Creates FormulaEvaluator - an object that evaluates formula cells.
+     *
+     * @return a FormulaEvaluator instance
+     */
+    FormulaEvaluator createFormulaEvaluator();
 }

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCreationHelper.java

@@ -43,4 +43,14 @@ public class XSSFCreationHelper implements CreationHelper {
 	public XSSFHyperlink createHyperlink(int type) {
 		return new XSSFHyperlink(type);
 	}
+
+    /**
+     * Creates a XSSFFormulaEvaluator, the object that evaluates formula cells.
+     *
+     * @return a XSSFFormulaEvaluator instance
+     */
+    public XSSFFormulaEvaluator createFormulaEvaluator(){
+        return new XSSFFormulaEvaluator(workbook);
+    }
+
 }