From: Javen O'Neal <onealj@apache.org>
Date: Sun, 17 Jul 2016 20:25:37 +0000 (+0000)
Subject: bug 57919: add performance note to javadocs about using BufferedOutputStreams on... 
X-Git-Tag: REL_3_15_BETA3~75
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=bf531156451d31877e56e6625ed1db2e252346ea;p=poi.git

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
---

diff --git a/src/java/org/apache/poi/POIDocument.java b/src/java/org/apache/poi/POIDocument.java
index 27a3ca648d..ac04388da9 100644
--- a/src/java/org/apache/poi/POIDocument.java
+++ b/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.
      * 
diff --git a/src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java b/src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java
index 63640be85f..5c2e5df330 100644
--- a/src/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java
+++ b/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
      *
diff --git a/src/ooxml/java/org/apache/poi/POIXMLDocument.java b/src/ooxml/java/org/apache/poi/POIXMLDocument.java
index 7fa934c03c..55b1a4d186 100644
--- a/src/ooxml/java/org/apache/poi/POIXMLDocument.java
+++ b/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
      *
diff --git a/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java b/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java
index 17a5ac77c1..ed70d76414 100644
--- a/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java
+++ b/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