You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@poi.apache.org by ni...@apache.org on 2014/04/28 08:36:01 UTC

svn commit: r1590557 - in /poi/site: publish/poifs/how-to.html src/documentation/content/xdocs/poifs/how-to.xml

Author: nick
Date: Mon Apr 28 06:36:01 2014
New Revision: 1590557

URL: http://svn.apache.org/r1590557
Log:
Begin POIFS documentation updates

Modified:
    poi/site/publish/poifs/how-to.html
    poi/site/src/documentation/content/xdocs/poifs/how-to.xml

Modified: poi/site/publish/poifs/how-to.html
URL: http://svn.apache.org/viewvc/poi/site/publish/poifs/how-to.html?rev=1590557&r1=1590556&r2=1590557&view=diff
==============================================================================
--- poi/site/publish/poifs/how-to.html (original)
+++ poi/site/publish/poifs/how-to.html Mon Apr 28 06:36:01 2014
@@ -227,12 +227,52 @@ if (VERSION > 3) {
 </table>
       
     
+
+    
+<a name="The+different+ways+of+working+with+POIFS"></a>
+<div class="h3">
+<h3>The different ways of working with POIFS</h3>
+</div>
+     
+<ul>
+      
+<li>
+<a href="#reading">Reading a File System</a>
+</li>
+      
+<li>
+<a href="#reading_poifsfilesystem">Conventional Reading with 
+           POIFSFileSystem</a>
+</li>
+      
+<li>
+<a href="#reading_npoifsfilesystem">NIO Reading using 
+           NPOIFSFileSystem</a>
+</li>
+      
+<li>
+<a href="#reading_event">Event-Driven Reading</a>
+</li>
+      
+<li>
+<a href="#writing">Writing a File System</a>
+</li>
+      
+<li>
+<a href="#modifying">Modifying a File System</a>
+</li>
+     
+</ul>
+    
+
     
 <a name="Reading+a+File+System"></a>
 <div class="h3">
 <h3>Reading a File System</h3>
 </div>
       
+<a name="reading"></a>
+      
 <p>This section covers reading a file system. There are two ways to read a file system; these techniques are sketched out in the following table, and then explained in greater depth in the sections following the table.</p>
       
 <table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -295,11 +335,14 @@ if (VERSION > 3) {
 </tr>
       
 </table>
-      
-<a name="Conventional+Reading"></a>
+
+    
+<a name="Conventional+Reading+with+POIFSFileSystem"></a>
 <div class="h4">
-<h4>Conventional Reading</h4>
+<h4>Conventional Reading with POIFSFileSystem</h4>
 </div>
+    
+<a name="reading_poifsfilesystem"></a>
         
 <p>In this technique for reading, the entire file system is loaded into memory, and the entire directory tree can be walked by an application, reading specific documents at the application's leisure.</p>
 	
@@ -436,12 +479,14 @@ DocumentInputStream stream = new Documen
 </pre>
 	  
 	
-      
-      
+  
+    
 <a name="NIO+Reading+using+NPOIFSFileSystem"></a>
 <div class="h4">
 <h4>NIO Reading using NPOIFSFileSystem</h4>
 </div>
+      
+<a name="reading_npoifsfilesystem"></a>
         
 <p>In this technique for reading, certain key structures are loaded 
          into memory, and the entire directory tree can be walked by the
@@ -454,7 +499,7 @@ DocumentInputStream stream = new Documen
          budget on memory use of up to 20% of the file size when using a File,
          or up to 120% of the file size when using an InputStream.</p>
 	
-<a name="Preparation-N101C8"></a>
+<a name="Preparation-N101F8"></a>
 <div class="h2">
 <h2>Preparation</h2>
 </div>
@@ -501,15 +546,18 @@ DirectoryEntry root = fs.getRoot();
       a POIFSFileSytem one.</p>
 	
 	
-      
+
+   
 <a name="Event-Driven+Reading"></a>
 <div class="h4">
 <h4>Event-Driven Reading</h4>
 </div>
+      
+<a name="reading_event"></a>
         
 <p>The event-driven API for reading documents is a little more complicated and requires that your application know, in advance, which files it wants to read. The benefit of using this API is that each document is in memory just long enough for your application to read it, and documents that you never read at all are not in memory at all. When you're finished reading the documents you wanted, the file system has no data structures associated with it at all and can be discarded.</p>
 	
-<a name="Preparation-N101E7"></a>
+<a name="Preparation-N1021A"></a>
 <div class="h2">
 <h2>Preparation</h2>
 </div>
@@ -648,12 +696,15 @@ reader.registerListener(myOtherPickyList
 	
       
     
+
     
 <a name="Writing+a+File+System"></a>
 <div class="h3">
 <h3>Writing a File System</h3>
 </div>
       
+<a name="writing"></a>
+      
 <p>Writing a file system is very much like reading a file system in that there are multiple ways to do so. You can load an existing file system into memory and modify it (removing files, renaming files) and/or add new files to it, and write it, or you can start with a new, empty file system:</p>
       
 <pre class="code">
@@ -778,12 +829,15 @@ DirectoryEntry createdDir = existingDir.
 </table>
       
     
+
     
 <a name="Modifying+a+File+System"></a>
 <div class="h3">
 <h3>Modifying a File System</h3>
 </div>
       
+<a name="modifying"></a>
+      
 <p>It is possible to modify an existing POIFS file system, whether it's one your application has loaded into memory, or one which you are creating on the fly.</p>
       
 <a name="Removing+a+Document"></a>

Modified: poi/site/src/documentation/content/xdocs/poifs/how-to.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/poifs/how-to.xml?rev=1590557&r1=1590556&r2=1590557&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/poifs/how-to.xml (original)
+++ poi/site/src/documentation/content/xdocs/poifs/how-to.xml Mon Apr 28 06:36:01 2014
@@ -75,7 +75,25 @@
         </table>
       </section>
     </section>
+
+    <section><title>The different ways of working with POIFS</title>
+     <p>The POIFS API provides ways to read, modify and write files and streams
+         that employ a POIFS-compatible data structure to organize their content.
+         The following use cases are covered:</p>
+     <ul>
+      <li><link href="#reading">Reading a File System</link></li>
+      <li><link href="#reading_poifsfilesystem">Conventional Reading with 
+           POIFSFileSystem</link></li>
+      <li><link href="#reading_npoifsfilesystem">NIO Reading using 
+           NPOIFSFileSystem</link></li>
+      <li><link href="#reading_event">Event-Driven Reading</link></li>
+      <li><link href="#writing">Writing a File System</link></li>
+      <li><link href="#modifying">Modifying a File System</link></li>
+     </ul>
+    </section>
+
     <section><title>Reading a File System</title>
+      <anchor id="reading" />
       <p>This section covers reading a file system. There are two ways to read a file system; these techniques are sketched out in the following table, and then explained in greater depth in the sections following the table.</p>
       <table>
         <tr>
@@ -124,7 +142,9 @@
 	  </td>
 	</tr>
       </table>
-      <section><title>Conventional Reading</title>
+
+    <section><title>Conventional Reading with POIFSFileSystem</title>
+    <anchor id="reading_poifsfilesystem" />
         <p>In this technique for reading, the entire file system is loaded into memory, and the entire directory tree can be walked by an application, reading specific documents at the application's leisure.</p>
 	<section><title>Preparation</title>
 	  <p>Before an application can read a file from the file system, the file system needs to be loaded into memory. This is done by using the <code>org.apache.poi.poifs.filesystem.POIFSFileSystem</code> class. Once the file system has been loaded into memory, the application may need the root directory. The following code fragment will accomplish this preparation stage:</p>
@@ -209,8 +229,9 @@ DocumentInputStream stream = new Documen
 </source>
 	  </section>
 	</section>
-      </section>
-      <section><title>NIO Reading using NPOIFSFileSystem</title>
+  </section>
+    <section><title>NIO Reading using NPOIFSFileSystem</title>
+      <anchor id="reading_npoifsfilesystem" />
         <p>In this technique for reading, certain key structures are loaded 
          into memory, and the entire directory tree can be walked by the
          application, reading specific documents at leisure.</p>
@@ -219,7 +240,9 @@ DocumentInputStream stream = new Documen
          instance from an input stream, then the whole contents must be 
          buffered into memory to allow random access. As such, you should
          budget on memory use of up to 20% of the file size when using a File,
-         or up to 120% of the file size when using an InputStream.</p>
+         or up to 120% of the file size when using an InputStream. (Using
+         NPOIFSFileSystem, whether File or InputStream based, should always
+         result in a lower memory footprint than POIFSFileSystem needed)
 	<section><title>Preparation</title>
 	  <p>Before an application can read a file from the file system, the 
        file system needs to be opened and core parts processed. This is done
@@ -236,7 +259,7 @@ try
 }
 catch (IOException e)
 {
-    // an I/O error occurred, or the InputStream did not provide a compatible
+    // an I/O error occurred, or the File did not provide a compatible
     // POIFS data structure
 }
 DirectoryEntry root = fs.getRoot();
@@ -250,17 +273,19 @@ try
 }
 catch (IOException e)
 {
-    // an I/O error occurred, or the InputStream did not provide a compatible
-    // POIFS data structure
+    // an I/O error occurred, or the InputStream did not provide
+    // a compatible POIFS data structure
 }
 DirectoryEntry root = fs.getRoot();
      </source>
 	  <p>Assuming no exception was thrown, the file system can then be read.</p>
-	  <p>One the NPOFSFileSytem is open, you can manipulate it just like
+	  <p>One the NPOIFSFileSytem is open, you can manipulate it just like
       a POIFSFileSytem one.</p>
 	</section>
 	</section>
-      <section><title>Event-Driven Reading</title>
+
+   <section><title>Event-Driven Reading</title>
+      <anchor id="reading_event" />
         <p>The event-driven API for reading documents is a little more complicated and requires that your application know, in advance, which files it wants to read. The benefit of using this API is that each document is in memory just long enough for your application to read it, and documents that you never read at all are not in memory at all. When you're finished reading the documents you wanted, the file system has no data structures associated with it at all and can be discarded.</p>
 	<section><title>Preparation</title>
 	  <p>The preparation phase involves creating an instance of <code>org.apache.poi.poifs.eventfilesystem.POIFSReader</code> and to then register one or more <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code> instances with the <code>POIFSReader</code>.</p>
@@ -339,9 +364,15 @@ reader.registerListener(myOtherPickyList
 	</section>
       </section>
     </section>
+
     <section><title>Writing a File System</title>
+      <anchor id="writing" />
       <p>Writing a file system is very much like reading a file system in that there are multiple ways to do so. You can load an existing file system into memory and modify it (removing files, renaming files) and/or add new files to it, and write it, or you can start with a new, empty file system:</p>
       <source>
+// Newer, lower memory footprint writing
+NPOIFSFileSystem fs = new NPOIFSFileSystem();
+
+// Older style writing
 POIFSFileSystem fs = new POIFSFileSystem();</source>
       <section><title>The Naming of Names</title>
         <p>There are two restrictions on the names of files in a file system that must be considered when creating files:</p>
@@ -359,7 +390,7 @@ POIFSFileSystem fs = new POIFSFileSystem
 	    <td><em>Disadvantages</em></td>
 	  </tr>
 	  <tr>
-	    <td>CreateDocument(String name, InputStream stream)</td>
+	    <td>createDocument(String name, InputStream stream)</td>
 	    <td>
 	        Simple API.
 	    </td>
@@ -368,7 +399,7 @@ POIFSFileSystem fs = new POIFSFileSystem
 	    </td>
 	  </tr>
 	  <tr>
-	    <td>CreateDocument(String name, int size, POIFSWriterListener writer)</td>
+	    <td>createDocument(String name, int size, POIFSWriterListener writer)</td>
 	    <td>
 	        Decreased memory footprint (only very small documents are held in memory, and then only for a short time).
 	    </td>
@@ -382,8 +413,12 @@ POIFSFileSystem fs = new POIFSFileSystem
 	<p>Unlike reading, you don't have to choose between the in-memory and event-driven writing models; both can co-exist in the same file system.</p>
 	<p>Writing is initiated when the <code>POIFSFileSystem</code> instance's <code>writeFilesystem()</code> method is called with an <code>OutputStream</code> to write to.</p>
 	<p>The event-driven model is quite similar to the event-driven model for reading, in that the file system calls your <code>org.apache.poi.poifs.filesystem.POIFSWriterListener</code> when it's time to write your document, just as the <code>POIFSReader</code> calls your <code>POIFSReaderListener</code> when it's time to read your document. Internally, when <code>writeFilesystem()</code> is called, the final POIFS data structures are created and are written to the specified <code>OutputStream</code>. When the file system needs to write a document out that was created with the event-driven model, it calls the <code>POIFSWriterListener</code> back, calling its <code>processPOIFSWriterEvent()</code> method, passing an <code>org.apache.poi.poifs.filesystem.POIFSWriterEvent</code> instance. This object contains the <code>POIFSDocumentPath</code> and name of the document, its size, and an open <code>org.apache.poi.poifs.filesystem.DocumentOutputStream</code> to which to write. A <code>Docum
 entOutputStream</code> is a wrapper over the <code>OutputStream</code> that was provided to the <code>POIFSFileSystem</code> to write to, and has the responsibility of making sure that the document your application writes fits within the size you specified for it.</p>
-      </section>
-      <section><title>Creating a Directory</title>
+   <p>If you are using a <code>NPOIFSFileSystem</code> loaded from a <code>File</code>
+     with <code>readOnly</code> set to false, it is also possible to do an in-place
+     write. Simply call <code>writeFilesystem()</code> to have the (limited) in-memory
+     structures synced with the disk, then <code>close()</code> to finish.</p>
+  </section>
+  <section><title>Creating a Directory</title>
         <p>Creating a directory is similar to creating a document, except that there's only one way to do so:</p>
 	<source>
 DirectoryEntry createdDir = existingDir.createDirectory(name);</source>
@@ -392,8 +427,8 @@ DirectoryEntry createdDir = existingDir.
         <p>As with reading documents, it is possible to create a new document or directory in the root directory by using convenience methods of POIFSFileSystem.</p>
 	<table>
 	  <tr>
-	    <td>DirectoryEntry Method Signature</td>
-	    <td>POIFSFileSystem Method Signature</td>
+	    <td><em>DirectoryEntry Method Signature</em></td>
+	    <td><em>POIFSFileSystem Method Signature</em></td>
 	  </tr>
 	  <tr>
 	    <td>createDocument(String name, InputStream stream)</td>
@@ -410,7 +445,9 @@ DirectoryEntry createdDir = existingDir.
 	</table>
       </section>
     </section>
+
     <section><title>Modifying a File System</title>
+      <anchor id="modifying" />
       <p>It is possible to modify an existing POIFS file system, whether it's one your application has loaded into memory, or one which you are creating on the fly.</p>
       <section><title>Removing a Document</title>
         <p>Removing a document is simple: you get the <code>Entry</code> corresponding to the document and call its <code>delete()</code> method. This is a boolean method, but should always return <code>true</code>, indicating that the operation succeeded.</p>
@@ -422,6 +459,11 @@ DirectoryEntry createdDir = existingDir.
 	  <li>The directory is the root directory. You cannot remove the root directory.</li>
 	</ul>
       </section>
+      <section><title>Changing a File's contents</title>
+        <p><em>Changing a file's contents is only possible with NPOIFSFileSystem</em></p>
+        <p>There are two ways available to change the contents of an existing file
+         within a POIFS file system.
+      </section>
       <section><title>Renaming a File</title>
         <p>Regardless of whether the file is a directory or a document, it can be renamed, with one exception - the root directory has a special name that is expected by the components of a major software vendor's office suite, and the POIFS API will not let that name be changed. Renaming is done by acquiring the file's corresponding <code>Entry</code> instance and calling its <code>renameTo</code> method, passing in the new name.</p>
 	<p>Like <code>delete</code>, <code>renameTo</code> returns <code>true</code> if the operation succeeded, otherwise <code>false</code>. Reasons for failure include these:</p>



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