bug 57919: add performance note to javadocs about using BufferedOutputStreams on Document.write(OutputStream) if underlying resource is high latency

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1753112 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/poi/POIDocument.java

@@ -313,6 +313,11 @@ public abstract class POIDocument implements Closeable {
      * Note - if the Document was opened from a {@link File} rather
      *  than an {@link InputStream}, you <b>must</b> write out to
      *  a different file, overwriting via an OutputStream isn't possible.
+     *  
+     * If {@code stream} is a {@link java.io.FileOutputStream} on a networked drive
+     * or has a high cost/latency associated with each written byte,
+     * consider wrapping the OutputStream in a {@link java.io.BufferedOutputStream}
+     * to improve write performance.
      * 
      * @param out The stream to write to.
      * 

src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java

@@ -1327,6 +1327,11 @@ public final class HSSFWorkbook extends POIDocument implements org.apache.poi.ss
      * Method write - write out this workbook to an {@link OutputStream}.  Constructs
      * a new POI POIFSFileSystem, passes in the workbook binary representation  and
      * writes it out.
+     * 
+     * If {@code stream} is a {@link java.io.FileOutputStream} on a networked drive
+     * or has a high cost/latency associated with each written byte,
+     * consider wrapping the OutputStream in a {@link java.io.BufferedOutputStream}
+     * to improve write performance.
      *
      * @param stream - the java OutputStream you wish to write the XLS to
      *

src/ooxml/java/org/apache/poi/POIXMLDocument.java

@@ -214,6 +214,11 @@ public abstract class POIXMLDocument extends POIXMLDocumentPart implements Close
      * Note - if the Document was opened from a {@link File} rather
      *  than an {@link InputStream}, you <b>must</b> write out to
      *  a different file, overwriting via an OutputStream isn't possible.
+     *  
+     * If {@code stream} is a {@link java.io.FileOutputStream} on a networked drive
+     * or has a high cost/latency associated with each written byte,
+     * consider wrapping the OutputStream in a {@link java.io.BufferedOutputStream}
+     * to improve write performance.
      * 
      * @param stream - the java OutputStream you wish to write the file to
      *

src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java

@@ -79,7 +79,7 @@ import org.apache.poi.util.Internal;
  */
 public final class HWPFDocument extends HWPFDocumentCore
 {
-    static final String PROPERTY_PRESERVE_BIN_TABLES = "org.apache.poi.hwpf.preserveBinTables";
+    /*package*/ static final String PROPERTY_PRESERVE_BIN_TABLES = "org.apache.poi.hwpf.preserveBinTables";
     private static final String PROPERTY_PRESERVE_TEXT_TABLE = "org.apache.poi.hwpf.preserveTextTable";
 
     private static final String STREAM_DATA = "Data";
@@ -583,6 +583,11 @@ public final class HWPFDocument extends HWPFDocumentCore
 
   /**
    * Writes out the word file that is represented by an instance of this class.
+   * 
+   * If {@code stream} is a {@link java.io.FileOutputStream} on a networked drive
+   * or has a high cost/latency associated with each written byte,
+   * consider wrapping the OutputStream in a {@link java.io.BufferedOutputStream}
+   * to improve write performance.
    *
    * @param out The OutputStream to write to.
    * @throws IOException If there is an unexpected IOException from the passed