poi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From n...@apache.org
Subject svn commit: r1590574 - in /poi/site: publish/poifs/how-to.html src/documentation/content/xdocs/poifs/how-to.xml
Date Mon, 28 Apr 2014 08:09:32 GMT
Author: nick
Date: Mon Apr 28 08:09:32 2014
New Revision: 1590574

URL: http://svn.apache.org/r1590574
Log:
NPOIFS replace contents documentation

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=1590574&r1=1590573&r2=1590574&view=diff
==============================================================================
--- poi/site/publish/poifs/how-to.html (original)
+++ poi/site/publish/poifs/how-to.html Mon Apr 28 08:09:32 2014
@@ -234,6 +234,10 @@ if (VERSION > 3) {
 <h3>The different ways of working with POIFS</h3>
 </div>
      
+<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>
@@ -497,9 +501,11 @@ 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)</p>
 	
-<a name="Preparation-N101F8"></a>
+<a name="Preparation-N101FB"></a>
 <div class="h2">
 <h2>Preparation</h2>
 </div>
@@ -520,7 +526,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();
@@ -534,15 +540,15 @@ 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();
      </pre>
 	  
 <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>
 	
 	
@@ -557,7 +563,7 @@ DirectoryEntry root = fs.getRoot();
         
 <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-N1021A"></a>
+<a name="Preparation-N1021D"></a>
 <div class="h2">
 <h2>Preparation</h2>
 </div>
@@ -708,6 +714,10 @@ reader.registerListener(myOtherPickyList
 <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">
+// Newer, lower memory footprint writing
+NPOIFSFileSystem fs = new NPOIFSFileSystem();
+
+// Older style writing
 POIFSFileSystem fs = new POIFSFileSystem();</pre>
       
 <a name="The+Naming+of+Names"></a>
@@ -745,7 +755,7 @@ POIFSFileSystem fs = new POIFSFileSystem
 	  
 <tr class="a">
 	    
-<td colspan="1" rowspan="1">CreateDocument(String name, InputStream stream)</td>
+<td colspan="1" rowspan="1">createDocument(String name, InputStream stream)</td>
 	    <td colspan="1" rowspan="1">
 	        Simple API.
 	    </td>
@@ -757,7 +767,7 @@ POIFSFileSystem fs = new POIFSFileSystem
 	  
 <tr class="b">
 	    
-<td colspan="1" rowspan="1">CreateDocument(String name, int size, POIFSWriterListener
writer)</td>
+<td colspan="1" rowspan="1">createDocument(String name, int size, POIFSWriterListener
writer)</td>
 	    <td colspan="1" rowspan="1">
 	        Decreased memory footprint (only very small documents are held in memory, and then
only for a short time).
 	    </td>
@@ -776,8 +786,13 @@ POIFSFileSystem fs = new POIFSFileSystem
 <p>Writing is initiated when the <span class="codefrag">POIFSFileSystem</span>
instance's <span class="codefrag">writeFilesystem()</span> method is called with
an <span class="codefrag">OutputStream</span> 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 <span class="codefrag">org.apache.poi.poifs.filesystem.POIFSWriterListener</span>
when it's time to write your document, just as the <span class="codefrag">POIFSReader</span>
calls your <span class="codefrag">POIFSReaderListener</span> when it's time to
read your document. Internally, when <span class="codefrag">writeFilesystem()</span>
is called, the final POIFS data structures are created and are written to the specified <span
class="codefrag">OutputStream</span>. When the file system needs to write a document
out that was created with the event-driven model, it calls the <span class="codefrag">POIFSWriterListener</span>
back, calling its <span class="codefrag">processPOIFSWriterEvent()</span> method,
passing an <span class="codefrag">org.apache.poi.poifs.filesystem.POIFSWriterEvent</span>
instance. This object contains the <span class="codefrag">POIFSDocumentPath</
 span> and name of the document, its size, and an open <span class="codefrag">org.apache.poi.poifs.filesystem.DocumentOutputStream</span>
to which to write. A <span class="codefrag">DocumentOutputStream</span> is a wrapper
over the <span class="codefrag">OutputStream</span> that was provided to the <span
class="codefrag">POIFSFileSystem</span> 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>
-      
-      
+   
+<p>If you are using a <span class="codefrag">NPOIFSFileSystem</span> loaded
from a <span class="codefrag">File</span>
+     with <span class="codefrag">readOnly</span> set to false, it is also possible
to do an in-place
+     write. Simply call <span class="codefrag">writeFilesystem()</span> to have
the (limited) in-memory
+     structures synced with the disk, then <span class="codefrag">close()</span>
to finish.</p>
+  
+  
 <a name="Creating+a+Directory"></a>
 <div class="h4">
 <h4>Creating a Directory</h4>
@@ -800,8 +815,8 @@ DirectoryEntry createdDir = existingDir.
 	  
 <tr class="b">
 	    
-<td colspan="1" rowspan="1">DirectoryEntry Method Signature</td>
-	    <td colspan="1" rowspan="1">POIFSFileSystem Method Signature</td>
+<td colspan="1" rowspan="1"><em>DirectoryEntry Method Signature</em></td>
+	    <td colspan="1" rowspan="1"><em>POIFSFileSystem Method Signature</em></td>
 	  
 </tr>
 	  
@@ -864,6 +879,70 @@ DirectoryEntry createdDir = existingDir.
 </ul>
       
       
+<a name="Changing+a+File%27s+contents"></a>
+<div class="h4">
+<h4>Changing a File's contents</h4>
+</div>
+        
+<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. One is using a <span class="codefrag">NDocumentOutputStream</span>,
+         the other is with <span class="codefrag">NPOIFSDocument.replaceContents</span>
+</p>
+        
+<p>If you have available to you an <span class="codefrag">InputStream</span>
to read the new
+         File contents from, then the easiest way is via 
+         <span class="codefrag">NPOIFSDocument.replaceContents</span>. You would
do something like:</p>
+
+<pre class="code">
+// Get the input stream from somewhere
+InputStream inp = db.getContentStream();
+
+// Open the POIFS File System, and get the entry of interest
+NPOIFSFileSystem fs = new NPOIFSFileSystem(new File(filename), false);
+DirectoryEntry root = fs.getRoot();
+DocumentEntry myDocE = (DocumentEntry)root.getEntry("ToChange");
+
+// Replace the contents
+NPOIFSDocument myDoc = new NPOIFSDocument(myDocE);
+myDoc.replaceContents(inp);
+
+// Save the changes to the file in-place
+fs.writeFileSystem();
+fs.close();
+</pre>
+         
+<p>Alternately, if you either have a byte array, or you need to write as
+          you go along, then the OutputStream interface provided by
+          <span class="codefrag">NDocumentOutputStream</span> will likely be
a better bet. Your code
+          would want to look somewhat like:</p>
+
+<pre class="code">
+// Open the POIFS File System, and get the entry of interest
+NPOIFSFileSystem fs = new NPOIFSFileSystem(new File(filename));
+DirectoryEntry root = fs.getRoot();
+DocumentEntry myDoc = (DocumentEntry)root.getEntry("ToChange");
+
+// Replace the contenst with a Write
+NDocumentOutputStream docOut = new NDocumentOutputStream(myDoc);
+myDocumentObject.writeTo(docOut);
+docOut.close();
+
+// Save the changes to a new file
+FileOutputStream out = new FileOutputStream("NewFile.ole2");
+fs.write(out);
+fs.close();
+out.close();
+</pre>
+         
+<p>For an example of an in-place change to one stream within a file, you
+          can see the example <em>TODO</em>
+</p>
+      
+      
 <a name="Renaming+a+File"></a>
 <div class="h4">
 <h4>Renaming a File</h4>

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=1590574&r1=1590573&r2=1590574&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 08:09:32 2014
@@ -242,7 +242,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. (Using
          NPOIFSFileSystem, whether File or InputStream based, should always
-         result in a lower memory footprint than POIFSFileSystem needed)
+         result in a lower memory footprint than POIFSFileSystem needed)</p>
 	<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
@@ -462,7 +462,51 @@ DirectoryEntry createdDir = existingDir.
       <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.
+         within a POIFS file system. One is using a <code>NDocumentOutputStream</code>,
+         the other is with <code>NPOIFSDocument.replaceContents</code></p>
+        <p>If you have available to you an <code>InputStream</code> to
read the new
+         File contents from, then the easiest way is via 
+         <code>NPOIFSDocument.replaceContents</code>. You would do something
like:</p>
+<source>
+// Get the input stream from somewhere
+InputStream inp = db.getContentStream();
+
+// Open the POIFS File System, and get the entry of interest
+NPOIFSFileSystem fs = new NPOIFSFileSystem(new File(filename), false);
+DirectoryEntry root = fs.getRoot();
+DocumentEntry myDocE = (DocumentEntry)root.getEntry("ToChange");
+
+// Replace the contents
+NPOIFSDocument myDoc = new NPOIFSDocument(myDocE);
+myDoc.replaceContents(inp);
+
+// Save the changes to the file in-place
+fs.writeFileSystem();
+fs.close();
+</source>
+         <p>Alternately, if you either have a byte array, or you need to write as
+          you go along, then the OutputStream interface provided by
+          <code>NDocumentOutputStream</code> will likely be a better bet. Your
code
+          would want to look somewhat like:</p>
+<source>
+// Open the POIFS File System, and get the entry of interest
+NPOIFSFileSystem fs = new NPOIFSFileSystem(new File(filename));
+DirectoryEntry root = fs.getRoot();
+DocumentEntry myDoc = (DocumentEntry)root.getEntry("ToChange");
+
+// Replace the contenst with a Write
+NDocumentOutputStream docOut = new NDocumentOutputStream(myDoc);
+myDocumentObject.writeTo(docOut);
+docOut.close();
+
+// Save the changes to a new file
+FileOutputStream out = new FileOutputStream("NewFile.ole2");
+fs.write(out);
+fs.close();
+out.close();
+</source>
+         <p>For an example of an in-place change to one stream within a file, you
+          can see the example <em>TODO</em></p>
       </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>



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


Mime
View raw message