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
+			<note>.xlsx format is suported since POI 3.5, make sure yoy upgraded to that version before experimenting with this 
-				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 
 				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);
+CellValue cellValue = evaluator.evaluate(cell);
-FormulaEvaluator.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(Row r : sheet) {
-
+        for(Cell c : r) {
-	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();
             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

@@ -31,7 +31,7 @@ public class XSSFCreationHelper implements CreationHelper {
      * Creates a new XSSFRichTextString for you.
      */
 	public XSSFRichTextString createRichTextString(String text) {
-        XSSFRichTextString rt =new XSSFRichTextString(text);
+        XSSFRichTextString rt = new XSSFRichTextString(text);
         rt.setStylesTableReference(workbook.getStylesSource());
         return rt;
 	}
@@ -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);
+    }
+
 }