Re-name some documentation directories, so they have better names now cover ole2 and ooxml (will need .htaccess redirect when putting live)

git-svn-id: https://svn.apache.org/repos/asf/poi/branches/ooxml@637603 13f79535-47bb-0310-9956-ffa450edef68
author: Nick Burch <nick@apache.org> 2008-03-16 15:59:27 +0000
committer: Nick Burch <nick@apache.org> 2008-03-16 15:59:27 +0000
commit: bfc60827c0c0fa5f8d2240941d95dbb0aba05e76 (patch)
tree: f5d76818953ac2a19ce369c9df24d7d0f22863d0 /src/documentation/content/xdocs/spreadsheet/eval.xml
parent: 703fdfabb62dee4cf7f4ccf18a4225a8a9271235 (diff)
download: poi-bfc60827c0c0fa5f8d2240941d95dbb0aba05e76.tar.gz
poi-bfc60827c0c0fa5f8d2240941d95dbb0aba05e76.zip
1 files changed, 248 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/spreadsheet/eval.xml b/src/documentation/content/xdocs/spreadsheet/eval.xml
new file mode 100644
index 0000000000..8d63512173
--- /dev/null
+++ b/src/documentation/content/xdocs/spreadsheet/eval.xml
@@ -0,0 +1,248 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+   ====================================================================
+   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.
+   ====================================================================
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Formula Evaluation</title>
+        <authors>
+			<person email="amoweb@yahoo.com" name="Amol Deshmukh" id="AD"/>
+        </authors>
+    </header>
+    <body>
+		<section><title>Introduction</title>
+			<p>The POI formula evaluation code enables you to calculate the result of 
+				formulas in Excels sheets read-in, or created in POI. This document explains
+				how to use the API to evaluate your formulas. 
+			</p>
+			<note> This code currently lives the scratchpad area of the POI SVN repository. 
+				Ensure that you have the scratchpad jar or the scratchpad build area in your
+				classpath before experimenting with this code. You are advised
+				to make use of a recent SVN checkout, as new functions are
+				being supported fairly frequently.
+			</note>
+		</section>
+
+		<anchor id="Status"/>
+		<section><title>Status</title>
+			<p>	The code currently provides implementations for all the arithmatic operators.
+				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>
+			<p> Note that user-defined functions are not supported, and is not likely to done
+				any time soon... at least, not till there is a VB implementation in Java!
+			</p>
+		</section>
+		<section><title>User API How-TO</title>
+			<p>The following code demonstrates how to use the HSSFFormulaEvaluator 
+				in the context of other POI excel reading code.
+			</p>
+			<p>There are several ways in which you can use the HSSFFormulaEvalutator API.</p>
+
+			<anchor id="Evaluate"/>
+			<section><title>Using HSSFFormulaEvaluator.<strong>evaluate</strong>(HSSFCell cell)</title>
+				<p>This evaluates a given cell, and returns the new value,
+				without affecting the cell</p>
+				<source>
+FileInputStream fis = new FileInputStream("c:/temp/test.xls");
+HSSFWorkbook wb = new HSSFWorkbook(fis);
+HSSFSheet sheet = wb.getSheetAt(0);
+HSSFFormulaEvaluator evaluator = new HSSFFormulaEvaluator(sheet, wb);
+
+// suppose your formula is in B3
+CellReference cellReference = new CellReference("B3"); 
+HSSFRow row = sheet.getRow(cellReference.getRow());
+HSSFCell cell = row.getCell(cellReference.getCol()); 
+
+evaluator.setCurrentRow(row);
+HSSFFormulaEvaluator.CellValue cellValue = evaluator.evaluate(cell);
+
+switch (cellValue.getCellType()) {
+	case HSSFCell.CELL_TYPE_BOOLEAN:
+    	System.out.println(cellValue.getBooleanValue());
+    	break;
+	case HSSFCell.CELL_TYPE_NUMERIC:
+    	System.out.println(cellValue.getNumberValue());
+    	break;
+	case HSSFCell.CELL_TYPE_STRING:
+    	System.out.println(cellValue.getStringValue());
+    	break;
+	case HSSFCell.CELL_TYPE_BLANK:
+    	break;
+	case HSSFCell.CELL_TYPE_ERROR:
+    	break;
+
+	// CELL_TYPE_FORMULA will never happen
+	case HSSFCell.CELL_TYPE_FORMULA: 
+    	break;
+}				
+				</source>
+				<p>Thus using the retrieved value (of type 
+					HSSFFormulaEvaluator.CellValue - a nested class) returned 
+					by HSSFFormulaEvaluator is similar to using a HSSFCell object 
+					containing the value of the formula evaluation. CellValue is 
+					a simple value object and does not maintain reference 
+					to the original cell.
+				</p>
+			</section>
+
+			<anchor id="EvaluateFormulaCell"/>
+			<section><title>Using HSSFFormulaEvaluator.<strong>evaluateFormulaCell</strong>(HSSFCell cell)</title>
+				<p><strong>evaluateFormulaCell</strong>(HSSFCell cell) 
+				will check to see if the supplied cell is a formula cell. 
+				If it isn't, then no changes will be made to it. If it is, 
+				then the formula is evaluated. The value for the formula
+				is saved alongside it, to be displayed in excel. The
+				formula remains in the cell, just with a new value</p>
+				<p>The return of the function is the type of the
+				formula result, such as HSSFCell.CELL_TYPE_BOOLEAN</p>
+				<source>
+FileInputStream fis = new FileInputStream("/somepath/test.xls");
+HSSFWorkbook wb = new HSSFWorkbook(fis);
+HSSFSheet sheet = wb.getSheetAt(0);
+HSSFFormulaEvaluator evaluator = new HSSFFormulaEvaluator(sheet, wb);
+
+// suppose your formula is in B3
+CellReference cellReference = new CellReference("B3"); 
+HSSFRow row = sheet.getRow(cellReference.getRow());
+HSSFCell cell = row.getCell(cellReference.getCol()); 
+evaluator.setCurrentRow(row);
+
+if (cell!=null) {
+	switch (<strong>evaluator.evaluateFormulaCell</strong>(cell)) {
+		case HSSFCell.CELL_TYPE_BOOLEAN:
+		    System.out.println(cell.getBooleanCellValue());
+		    break;
+		case HSSFCell.CELL_TYPE_NUMERIC:
+		    System.out.println(cell.getNumberCellValue());
+		    break;
+		case HSSFCell.CELL_TYPE_STRING:
+		    System.out.println(cell.getStringCellValue());
+		    break;
+		case HSSFCell.CELL_TYPE_BLANK:
+		    break;
+		case HSSFCell.CELL_TYPE_ERROR:
+		    System.out.println(cell.getErrorCellValue());
+		    break;
+		
+		// CELL_TYPE_FORMULA will never occur
+		case HSSFCell.CELL_TYPE_FORMULA: 
+		    break;
+	}
+}
+				</source>
+			</section>
+
+			<anchor id="EvaluateInCell"/>
+			<section><title>Using HSSFFormulaEvaluator.<strong>evaluateInCell</strong>(HSSFCell cell)</title>
+				<p><strong>evaluateInCell</strong>(HSSFCell cell) will check to
+				see if the supplied cell is a formula cell. If it isn't,
+				then no changes will be made to it. If it is, then the
+				formula is evaluated, and the new value saved into the cell,
+				in place of the old formula.</p>
+				<source>
+FileInputStream fis = new FileInputStream("/somepath/test.xls");
+HSSFWorkbook wb = new HSSFWorkbook(fis);
+HSSFSheet sheet = wb.getSheetAt(0);
+HSSFFormulaEvaluator evaluator = new HSSFFormulaEvaluator(sheet, wb);
+
+// suppose your formula is in B3
+CellReference cellReference = new CellReference("B3"); 
+HSSFRow row = sheet.getRow(cellReference.getRow());
+HSSFCell cell = row.getCell(cellReference.getCol()); 
+evaluator.setCurrentRow(row);
+
+if (cell!=null) {
+	switch (<strong>evaluator.evaluateInCell</strong>(cell).getCellType()) {
+		case HSSFCell.CELL_TYPE_BOOLEAN:
+		    System.out.println(cell.getBooleanCellValue());
+		    break;
+		case HSSFCell.CELL_TYPE_NUMERIC:
+		    System.out.println(cell.getNumberCellValue());
+		    break;
+		case HSSFCell.CELL_TYPE_STRING:
+		    System.out.println(cell.getStringCellValue());
+		    break;
+		case HSSFCell.CELL_TYPE_BLANK:
+		    break;
+		case HSSFCell.CELL_TYPE_ERROR:
+		    System.out.println(cell.getErrorCellValue());
+		    break;
+		
+		// CELL_TYPE_FORMULA will never occur
+		case HSSFCell.CELL_TYPE_FORMULA: 
+		    break;
+	}
+}
+				</source>
+			</section>
+
+			<anchor id="EvaluateAll"/>
+			<section><title>Re-calculating all formulas in a Workbook</title>
+				<source>
+FileInputStream fis = new FileInputStream("/somepath/test.xls");
+HSSFWorkbook wb = new HSSFWorkbook(fis);
+for(int sheetNum = 0; sheetNum &lt; wb.getNumberOfSheets(); sheetNum++) {
+	HSSFSheet sheet = wb.getSheetAt(sheetNum);
+	HSSFFormulaEvaluator evaluator = new HSSFFormulaEvaluator(sheet, wb);
+
+	for(Iterator rit = sheet.rowIterator(); rit.hasNext();) {
+		HSSFRow r = (HSSFRow)rit.next();
+		evaluator.setCurrentRow(r);
+
+		for(Iterator cit = r.cellIterator(); cit.hasNext();) {
+			HSSFCell c = (HSSFCell)cit.next();
+			if(c.getCellType() == HSSFCell.CELL_TYPE_FORMULA) {
+				evaluator.evaluateFormulaCell(c);
+			}
+		}
+	}
+}
+wb.write(new FileOutputStream("/somepath/changed.xls"));
+				</source>
+			</section>
+		</section>
+		
+		<anchor id="Performance"/>
+		<section><title>Performance Notes</title>
+			<ul>
+				<li>Generally you should have to create only one HSSFFormulaEvaluator 
+					instance per sheet, but there really is no overhead in creating 
+					multiple HSSFFormulaEvaluators per sheet other than that of the 
+					HSSFFormulaEvaluator object creation. 
+				</li>
+				<li>Also note that HSSFFormulaEvaluator maintains a reference to 
+					the sheet and workbook, so ensure that the evaluator instance 
+					is available for garbage collection when you are done with it 
+					(in other words don't maintain long lived reference to 
+					HSSFFormulaEvaluator if you don't really need to - unless 
+					all references to the sheet and workbook are removed, these 
+					don't get garbage collected and continue to occupy potentially 
+					large amounts of memory). 
+				</li>	
+				<li>CellValue instances however do not maintain reference to the 
+					HSSFCell or the sheet or workbook, so these can be long-lived 
+					objects without any adverse effect on performance.
+				</li>
+			</ul>
+		</section>
+	</body>
+</document>
author	Nick Burch <nick@apache.org>	2008-03-16 15:59:27 +0000
committer	Nick Burch <nick@apache.org>	2008-03-16 15:59:27 +0000
commit	bfc60827c0c0fa5f8d2240941d95dbb0aba05e76 (patch)
tree	f5d76818953ac2a19ce369c9df24d7d0f22863d0 /src/documentation/content/xdocs/spreadsheet/eval.xml
parent	703fdfabb62dee4cf7f4ccf18a4225a8a9271235 (diff)
download	poi-bfc60827c0c0fa5f8d2240941d95dbb0aba05e76.tar.gz poi-bfc60827c0c0fa5f8d2240941d95dbb0aba05e76.zip