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 2016/08/02 11:43:17 UTC
svn commit: r1754883 - in /poi/site: publish/faq.html
src/documentation/content/xdocs/faq.xml
Author: nick
Date: Tue Aug 2 11:43:17 2016
New Revision: 1754883
URL: http://svn.apache.org/viewvc?rev=1754883&view=rev
Log:
Add an entry on reading and writing with files vs streams
Modified:
poi/site/publish/faq.html
poi/site/src/documentation/content/xdocs/faq.xml
Modified: poi/site/publish/faq.html
URL: http://svn.apache.org/viewvc/poi/site/publish/faq.html?rev=1754883&r1=1754882&r2=1754883&view=diff
==============================================================================
--- poi/site/publish/faq.html (original)
+++ poi/site/publish/faq.html Tue Aug 2 11:43:17 2016
@@ -359,6 +359,12 @@ if (VERSION > 3) {
What are the multi-threading guarantees that Apache POI makes
</a>
</li>
+<li>
+<a name="faq-N1023C-menu"></a><a href="#faq-N1023C">
+ What are the advantages and disadvantages of the different constructor and
+ write methods?
+ </a>
+</li>
</ol>
<a name="Answers"></a>
<div class="h3">
@@ -948,6 +954,59 @@ System.out.println("POI Scratchpad came
versions of Apache POI as we do not specifically test using the library
this way.</p>
+<a name="faq-N1023C"></a>
+<div class="h4">
+<h4>21.
+ What are the advantages and disadvantages of the different constructor and
+ write methods?
+ </h4>
+</div>
+
+<p>Across most of the UserModel classes (
+<a href="/apidocs/org/apache/poi/POIDocument.html">POIDocument</a>
+and
+<a href="/apidocs/org/apache/poi/POIXMLDocument.html">POIXMLDocument</a>),
+ you can open the document from a read-only <em>File</em>, a read-write <em>File</em>
+ or an <em>InputStream</em>. You can always write out to an <em>OutputStream</em>,
+ and increasing also to a <em>File</em>.
+ </p>
+
+<p>Opening your document from a <em>File</em> is suggested wherever possible.
+ This will always be quicker and lower memory then using an <em>InputStream</em>,
+ as the latter has to buffer things in memory.</p>
+
+<p>When writing, you can use an <em>OutputStream</em> to write to a new file, or
+ overwrite an existing one (provided it isn't already open!). On slow links / disks,
+ wrapping with a <em>BufferedOutputStream</em> is suggested. To write like this, use
+<a href="/apidocs/org/apache/poi/POIDocument.html#write(java.io.OutputStream)">write(OutputStream)</a>.
+ </p>
+
+<p>To write to the currently open file (an in-place write / replace), you need to
+ have opened your document from a <em>File</em>, not an <em>InputStream</em>. In
+ addition, you need to have opened from the <em>File</em> in read-write mode, not
+ read-only mode. To write to the currently open file, on formats that support it
+ (not all do), use
+<a href="/apidocs/org/apache/poi/POIDocument.html#write()">write()</a>.
+ </p>
+
+<p>You can also write out to a new <em>File</em>. This is available no matter how
+ you opened the document, and will create/replace a new file. It is faster and lower
+ memory than writing to an <em>OutputStream</em>. However, you can't use this to
+ replace the currently open file, only files not currently open. To write to a
+ new / different file, use
+<a href="/apidocs/org/apache/poi/POIDocument.html#write(java.io.File)">write(File)</a>
+
+</p>
+
+<p>More information is also available in the
+<a href="/spreadsheet/quick-guide.html#FileInputStream">HSSF and XSSF documentation</a>,
+ which largely applies to the other formats too.
+ </p>
+
+<p>Note that currenly (POI 3.15 beta 3), not all of the write methods are available
+ for the OOXML formats yet.
+ </p>
+
</div>
</div>
</div>
Modified: poi/site/src/documentation/content/xdocs/faq.xml
URL: http://svn.apache.org/viewvc/poi/site/src/documentation/content/xdocs/faq.xml?rev=1754883&r1=1754882&r2=1754883&view=diff
==============================================================================
--- poi/site/src/documentation/content/xdocs/faq.xml (original)
+++ poi/site/src/documentation/content/xdocs/faq.xml Tue Aug 2 11:43:17 2016
@@ -510,7 +510,7 @@ System.out.println("POI Scratchpad came
for details</p>
</answer>
</faq>
- <faq>
+ <faq>
<question>
Can I access/modify workbooks/documents/slideshows in multiple threads?
What are the multi-threading guarantees that Apache POI makes
@@ -531,5 +531,50 @@ System.out.println("POI Scratchpad came
versions of Apache POI as we do not specifically test using the library
this way.</p>
</answer>
- </faq>
+ </faq>
+ <faq>
+ <question>
+ What are the advantages and disadvantages of the different constructor and
+ write methods?
+ </question>
+ <answer>
+ <p>Across most of the UserModel classes (
+<link href="/apidocs/org/apache/poi/POIDocument.html">POIDocument</link>
+and
+<link href="/apidocs/org/apache/poi/POIXMLDocument.html">POIXMLDocument</link>),
+ you can open the document from a read-only <em>File</em>, a read-write <em>File</em>
+ or an <em>InputStream</em>. You can always write out to an <em>OutputStream</em>,
+ and increasing also to a <em>File</em>.
+ </p>
+ <p>Opening your document from a <em>File</em> is suggested wherever possible.
+ This will always be quicker and lower memory then using an <em>InputStream</em>,
+ as the latter has to buffer things in memory.</p>
+ <p>When writing, you can use an <em>OutputStream</em> to write to a new file, or
+ overwrite an existing one (provided it isn't already open!). On slow links / disks,
+ wrapping with a <em>BufferedOutputStream</em> is suggested. To write like this, use
+<link href="/apidocs/org/apache/poi/POIDocument.html#write(java.io.OutputStream)">write(OutputStream)</link>.
+ </p>
+ <p>To write to the currently open file (an in-place write / replace), you need to
+ have opened your document from a <em>File</em>, not an <em>InputStream</em>. In
+ addition, you need to have opened from the <em>File</em> in read-write mode, not
+ read-only mode. To write to the currently open file, on formats that support it
+ (not all do), use
+<link href="/apidocs/org/apache/poi/POIDocument.html#write()">write()</link>.
+ </p>
+ <p>You can also write out to a new <em>File</em>. This is available no matter how
+ you opened the document, and will create/replace a new file. It is faster and lower
+ memory than writing to an <em>OutputStream</em>. However, you can't use this to
+ replace the currently open file, only files not currently open. To write to a
+ new / different file, use
+<link href="/apidocs/org/apache/poi/POIDocument.html#write(java.io.File)">write(File)</link>
+ </p>
+ <p>More information is also available in the
+<link href="/spreadsheet/quick-guide.html#FileInputStream">HSSF and XSSF documentation</link>,
+ which largely applies to the other formats too.
+ </p>
+ <p>Note that currenly (POI 3.15 beta 3), not all of the write methods are available
+ for the OOXML formats yet.
+ </p>
+ </answer>
+ </faq>
</faqs>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@poi.apache.org
For additional commands, e-mail: commits-help@poi.apache.org