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

src/documentation/content/xdocs/status.xml

@@ -34,6 +34,7 @@
 
     <changes>
         <release version="3.8-beta5" date="2011-??-??">
+           <action dev="poi-developers" type="fix">52204 - Deprecated XSSFWorkbook(String path) constructor because it does not close underlying .zip file</action>
            <action dev="poi-developers" type="fix">46288 - fixed refcount of Fill pictures in HSLF </action>
            <action dev="poi-developers" type="add">51961 - support compression of temp files in SXSSF </action>
            <action dev="poi-developers" type="add">52268 - support cloning sheets with drawings in XSSF </action>

src/examples/src/org/apache/poi/xssf/usermodel/examples/CustomXMLMapping.java

@@ -16,6 +16,7 @@
 ==================================================================== */
 package org.apache.poi.xssf.usermodel.examples;
 
+import org.apache.poi.openxml4j.opc.OPCPackage;
 import org.apache.poi.xssf.extractor.XSSFExportToXml;
 import org.apache.poi.xssf.usermodel.XSSFWorkbook;
 import org.apache.poi.xssf.usermodel.XSSFMap;
@@ -28,7 +29,8 @@ import java.io.ByteArrayOutputStream;
 public class CustomXMLMapping {
 
     public static void main(String[] args) throws Exception {
-        XSSFWorkbook wb = new XSSFWorkbook(args[0]);
+        OPCPackage pkg = OPCPackage.open(args[0]);
+        XSSFWorkbook wb = new XSSFWorkbook(pkg);
 
         for (XSSFMap map : wb.getCustomXMLMappings()) {
             XSSFExportToXml exporter = new XSSFExportToXml(map);
@@ -38,5 +40,6 @@ public class CustomXMLMapping {
             String xml = os.toString("UTF-8");
             System.out.println(xml);
         }
+        pkg.close();
     }
 }

src/examples/src/org/apache/poi/xssf/usermodel/examples/EmbeddedObjects.java

@@ -32,7 +32,8 @@ import java.io.InputStream;
  */
 public class EmbeddedObjects {
     public static void main(String[] args) throws Exception {
-        XSSFWorkbook workbook = new XSSFWorkbook(args[0]);
+        OPCPackage pkg = OPCPackage.open(args[0]);
+        XSSFWorkbook workbook = new XSSFWorkbook(pkg);
         for (PackagePart pPart : workbook.getAllEmbedds()) {
             String contentType = pPart.getContentType();
             // Excel Workbook - either binary or OpenXML
@@ -66,5 +67,6 @@ public class EmbeddedObjects {
                 InputStream inputStream = pPart.getInputStream();
             }
         }
+        pkg.close();
     }
 }

src/examples/src/org/apache/poi/xssf/usermodel/examples/IterateCells.java

@@ -23,13 +23,15 @@ import org.apache.poi.ss.usermodel.Sheet;
 import org.apache.poi.ss.usermodel.Cell;
 import org.apache.poi.ss.usermodel.Row;
 
+import java.io.FileInputStream;
+
 /**
  *  Iterate over rows and cells
  */
 public class IterateCells {
 
     public static void main(String[] args) throws Exception {
-        Workbook wb = new XSSFWorkbook(args[0]);
+        Workbook wb = new XSSFWorkbook(new FileInputStream(args[0]));
         for (int i = 0; i < wb.getNumberOfSheets(); i++) {
             Sheet sheet = wb.getSheetAt(i);
             System.out.println(wb.getSheetName(i));

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();
         }
     }
 

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));
     }