poi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From n...@apache.org
Subject svn commit: r1425256 - in /poi/site: publish/spreadsheet/quick-guide.html src/documentation/content/xdocs/spreadsheet/quick-guide.xml
Date Sat, 22 Dec 2012 08:30:02 GMT
Author: nick
Date: Sat Dec 22 08:30:02 2012
New Revision: 1425256

URL: http://svn.apache.org/viewvc?rev=1425256&view=rev
Log:
Provide advice on File vs InputStream

Modified:
    poi/site/publish/spreadsheet/quick-guide.html
    poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml

Modified: poi/site/publish/spreadsheet/quick-guide.html
URL: http://svn.apache.org/viewvc/poi/site/publish/spreadsheet/quick-guide.html?rev=1425256&r1=1425255&r2=1425256&view=diff
==============================================================================
--- poi/site/publish/spreadsheet/quick-guide.html (original)
+++ poi/site/publish/spreadsheet/quick-guide.html Sat Dec 22 08:30:02 2012
@@ -235,6 +235,10 @@ if (VERSION > 3) {
 </li>
                     
 <li>
+<a href="#FileInputStream">Files vs InputStreams</a>
+</li>
+                    
+<li>
 <a href="#Alignment">Aligning cells</a>
 </li>
                     
@@ -519,6 +523,61 @@ if (VERSION > 3) {
     fileOut.close();
                     </pre>
                 
+
+                
+<a name="FileInputStream"></a>
+                <a name="Files+vs+InputStreams"></a>
+<div class="h2">
+<h2>Files vs InputStreams</h2>
+</div>
+                  
+<p>When opening a workbook, either a .xls HSSFWorkbook, or a .xlsx
+                    XSSFWorkbook, the Workbook can be loaded from either a <em>File</em>
+                    or an <em>InputStream</em>. Using a <em>File</em>
object allows for
+                    lower memory consumption, while an <em>InputStream</em> requires
more
+                    memory as it has to buffer the whole file.</p>
+                  
+<p>If using <em>WorkbookFactory</em>, it's very easy to use one or
+                    the other:</p>
+                  
+<pre class="code">
+  // Use a file
+  Workbook wb = WorkbookFactory.create(new File("MyExcel.xls"));
+
+  // Use an InputStream, needs more memory
+  Workbook wb = WorkbookFactory.create(new FileInputStream("MyExcel.xlsx"));
+                  </pre>
+                  
+<p>If using <em>HSSFWorkbook</em> or <em>XSSFWorkbook</em>
directly,
+                   you should generally go through <em>NPOIFSFileSystem</em>
or
+                   <em>OPCPackage</em>, to have full control of the lifecycle
(including
+                   closing the file when done):</p>
+                  
+<pre class="code">
+  // HSSFWorkbook, File
+  NPOIFSFileSytem fs = new NPOIFSFileSystem(new File("file.xls"));
+  HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot());
+  ....
+  fs.close();
+
+  // HSSFWorkbook, InputStream, needs more memory
+  NPOIFSFileSytem fs = new NPOIFSFileSystem(myInputStream);
+  HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot());
+
+  // XSSFWorkbook, File
+  OPCPackage pkg = OPCPackage.open(new File("file.xlsx"));
+  XSSFWorkbook wb = new XSSFWorkbook(pkg);
+  ....
+  pkg.close();
+
+  // XSSFWorkbook, InputStream, needs more memory
+  OPCPackage pkg = OPCPackage.open(myInputStream);
+  XSSFWorkbook wb = new XSSFWorkbook(pkg);
+  ....
+  pkg.close();
+                  </pre>
+                
+
                 
 <a name="Alignment"></a>
                 <a name="Demonstrates+various+alignment+options"></a>
@@ -1673,7 +1732,7 @@ Examples:
                 
                 
 <a name="Outlining"></a>
-                <a name="Outlining-N103A6"></a>
+                <a name="Outlining-N103E0"></a>
 <div class="h2">
 <h2>Outlining</h2>
 </div>
@@ -1720,7 +1779,7 @@ Examples:
         
         
 <a name="Images"></a>
-        <a name="Images-N103C3"></a>
+        <a name="Images-N103FD"></a>
 <div class="h3">
 <h3>Images</h3>
 </div>

Modified: poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml?rev=1425256&r1=1425255&r2=1425256&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml (original)
+++ poi/site/src/documentation/content/xdocs/spreadsheet/quick-guide.xml Sat Dec 22 08:30:02
2012
@@ -41,6 +41,7 @@
                     <li><link href="#Iterator">Iterate over rows and cells</link></li>
                     <li><link href="#CellContents">Getting the cell contents</link></li>
                     <li><link href="#TextExtraction">Text Extraction</link></li>
+                    <li><link href="#FileInputStream">Files vs InputStreams</link></li>
                     <li><link href="#Alignment">Aligning cells</link></li>
                     <li><link href="#Borders">Working with borders</link></li>
                     <li><link href="#FillsAndFrills">Fills and color</link></li>
@@ -201,6 +202,52 @@
     fileOut.close();
                     </source>
                 </section>
+
+                <anchor id="FileInputStream"/>
+                <section><title>Files vs InputStreams</title>
+                  <p>When opening a workbook, either a .xls HSSFWorkbook, or a .xlsx
+                    XSSFWorkbook, the Workbook can be loaded from either a <em>File</em>
+                    or an <em>InputStream</em>. Using a <em>File</em>
object allows for
+                    lower memory consumption, while an <em>InputStream</em> requires
more
+                    memory as it has to buffer the whole file.</p>
+                  <p>If using <em>WorkbookFactory</em>, it's very easy
to use one or
+                    the other:</p>
+                  <source>
+  // Use a file
+  Workbook wb = WorkbookFactory.create(new File("MyExcel.xls"));
+
+  // Use an InputStream, needs more memory
+  Workbook wb = WorkbookFactory.create(new FileInputStream("MyExcel.xlsx"));
+                  </source>
+                  <p>If using <em>HSSFWorkbook</em> or <em>XSSFWorkbook</em>
directly,
+                   you should generally go through <em>NPOIFSFileSystem</em>
or
+                   <em>OPCPackage</em>, to have full control of the lifecycle
(including
+                   closing the file when done):</p>
+                  <source>
+  // HSSFWorkbook, File
+  NPOIFSFileSytem fs = new NPOIFSFileSystem(new File("file.xls"));
+  HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot());
+  ....
+  fs.close();
+
+  // HSSFWorkbook, InputStream, needs more memory
+  NPOIFSFileSytem fs = new NPOIFSFileSystem(myInputStream);
+  HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot());
+
+  // XSSFWorkbook, File
+  OPCPackage pkg = OPCPackage.open(new File("file.xlsx"));
+  XSSFWorkbook wb = new XSSFWorkbook(pkg);
+  ....
+  pkg.close();
+
+  // XSSFWorkbook, InputStream, needs more memory
+  OPCPackage pkg = OPCPackage.open(myInputStream);
+  XSSFWorkbook wb = new XSSFWorkbook(pkg);
+  ....
+  pkg.close();
+                  </source>
+                </section>
+
                 <anchor id="Alignment"/>
                 <section><title>Demonstrates various alignment options</title>
                     <source>



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org


Mime
View raw message