poi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From n...@apache.org
Subject svn commit: r1754883 - in /poi/site: publish/faq.html src/documentation/content/xdocs/faq.xml
Date Tue, 02 Aug 2016 11:43:17 GMT
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


Mime
View raw message