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 10:09:32 UTC
svn commit: r1590574 - in /poi/site: publish/poifs/how-to.html
src/documentation/content/xdocs/poifs/how-to.xml
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