Bugzilla 52204: Deprecated XSSFWorkbook(String path) constructor because it does not close underlying .zip file

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

2 files changed, 38 insertions, 1 deletions

diff --git a/src/ooxml/java/org/apache/poi/xssf/dev/XSSFSave.java b/src/ooxml/java/org/apache/poi/xssf/dev/XSSFSave.java
index 4b2fc3ca53..1660f452aa 100644
--- a/src/ooxml/java/org/apache/poi/xssf/dev/XSSFSave.java
+++ b/src/ooxml/java/org/apache/poi/xssf/dev/XSSFSave.java
@@ -17,6 +17,7 @@
 
 package org.apache.poi.xssf.dev;
 
+import org.apache.poi.openxml4j.opc.OPCPackage;
 import org.apache.poi.xssf.usermodel.XSSFWorkbook;
 
 import java.io.FileOutputStream;
@@ -30,13 +31,16 @@ import java.io.FileOutputStream;
 public final class XSSFSave {
     public static void main(String[] args) throws Exception {
         for (int i = 0; i < args.length; i++) {
-            XSSFWorkbook wb = new XSSFWorkbook(args[i]);
+            OPCPackage pkg = OPCPackage.open(args[i]);
+            XSSFWorkbook wb = new XSSFWorkbook(pkg);
 
             int sep = args[i].lastIndexOf('.');
             String outfile = args[i].substring(0, sep) + "-save.xls" + (wb.isMacroEnabled() ? "m" : "x");
             FileOutputStream out = new FileOutputStream(outfile);
             wb.write(out);
             out.close();
+
+            pkg.close();
         }
     }
 
diff --git a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
index 0f8d3d70d0..81e79ba51c 100644
--- a/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
+++ b/src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java
@@ -184,8 +184,41 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Iterable<X
     /**
      * Constructs a XSSFWorkbook object given a file name.
      *
+     * <p>
+     *  This constructor is deprecated since POI-3.8 because it does not close
+     *  the underlying .zip file stream. In short, there are two ways to open a OPC package:
+     * </p>
+     * <ol>
+     *     <li>
+     *      from file which leads to invoking java.util.zip.ZipFile(File file)
+     *      deep in POI internals.
+     *     </li>
+     *     <li>
+     *     from input stream in which case we first read everything into memory and
+     *     then pass the data to ZipInputStream.
+     *     </li>
+     * <ol>
+     * <p>    
+     *     It should be noted, that (2) uses quite a bit more memory than (1), which
+     *      doesn't need to hold the whole zip file in memory, and can take advantage
+     *      of native methods.
+     * </p>
+     * <p>
+     *   To construct a workbook from file use the
+     *   {@link #XSSFWorkbook(org.apache.poi.openxml4j.opc.OPCPackage)}  constructor:
+     *   <pre><code>
+     *       OPCPackage pkg = OPCPackage.open(path);
+     *       XSSFWorkbook wb = new XSSFWorkbook(pkg);
+     *       // work with the wb object
+     *       ......
+     *       pkg.close(); // gracefully closes the underlying zip file
+     *   </code></pre>     
+     * </p>
+     * 
      * @param      path   the file name.
+     * @deprecated
      */
+    @Deprecated
     public XSSFWorkbook(String path) throws IOException {
         this(openPackage(path));
     }