Add WorkbookFactory.create() with a flag to allow to open files read-only, keep the current way of opening read/write as default to not break existing code.

Also adjust Javadoc somewhat.

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

src/ooxml/java/org/apache/poi/ss/usermodel/WorkbookFactory.java

@@ -30,6 +30,7 @@ import org.apache.poi.hssf.record.crypto.Biff8EncryptionKey;
 import org.apache.poi.hssf.usermodel.HSSFWorkbook;
 import org.apache.poi.openxml4j.exceptions.InvalidFormatException;
 import org.apache.poi.openxml4j.opc.OPCPackage;
+import org.apache.poi.openxml4j.opc.PackageAccess;
 import org.apache.poi.poifs.crypt.Decryptor;
 import org.apache.poi.poifs.crypt.EncryptionInfo;
 import org.apache.poi.poifs.filesystem.DirectoryNode;
@@ -71,6 +72,14 @@ public class WorkbookFactory {
     /**
      * Creates a Workbook from the given NPOIFSFileSystem, which may
      *  be password protected
+     *
+     *  @param fs The {@link NPOIFSFileSystem} to read the document from
+     *  @param password The password that should be used or null if no password is necessary.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
+     *  @throws InvalidFormatException if the contents of the file cannot be parsed into a {@link Workbook}
      */
     private static Workbook create(NPOIFSFileSystem fs, String password) throws IOException, InvalidFormatException {
         DirectoryNode root = fs.getRoot();
@@ -119,8 +128,15 @@ public class WorkbookFactory {
 
     /**
      * Creates a XSSFWorkbook from the given OOXML Package
+     *
      * <p>Note that in order to properly release resources the
-     *  Workbook should be closed after use.
+     *  Workbook should be closed after use.</p>
+     *
+     *  @param pkg The {@link OPCPackage} opened for reading data.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
      */
     public static Workbook create(OPCPackage pkg) throws IOException {
         return new XSSFWorkbook(pkg);
@@ -129,14 +145,23 @@ public class WorkbookFactory {
     /**
      * Creates the appropriate HSSFWorkbook / XSSFWorkbook from
      *  the given InputStream.
+     *
      * <p>Your input stream MUST either support mark/reset, or
      *  be wrapped as a {@link PushbackInputStream}! Note that
      *  using an {@link InputStream} has a higher memory footprint
      *  than using a {@link File}.</p>
+     *
      * <p>Note that in order to properly release resources the
      *  Workbook should be closed after use. Note also that loading
      *  from an InputStream requires more memory than loading
      *  from a File, so prefer {@link #create(File)} where possible.
+     *
+     *  @param inp The {@link InputStream} to read data from.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
+     *  @throws InvalidFormatException if the contents of the file cannot be parsed into a {@link Workbook}
      *  @throws EncryptedDocumentException If the workbook given is password protected
      */
     public static Workbook create(InputStream inp) throws IOException, InvalidFormatException, EncryptedDocumentException {
@@ -150,10 +175,19 @@ public class WorkbookFactory {
      *  be wrapped as a {@link PushbackInputStream}! Note that
      *  using an {@link InputStream} has a higher memory footprint
      *  than using a {@link File}.</p>
+     *
      * <p>Note that in order to properly release resources the
      *  Workbook should be closed after use. Note also that loading
      *  from an InputStream requires more memory than loading
-     *  from a File, so prefer {@link #create(File)} where possible.
+     *  from a File, so prefer {@link #create(File)} where possible.</p>
+     *
+     *  @param inp The {@link InputStream} to read data from.
+     *  @param password The password that should be used or null if no password is necessary.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
+     *  @throws InvalidFormatException if the contents of the file cannot be parsed into a {@link Workbook}
      *  @throws EncryptedDocumentException If the wrong password is given for a protected file
      *  @throws EmptyFileException If an empty stream is given
      */
@@ -182,31 +216,70 @@ public class WorkbookFactory {
      *  the given File, which must exist and be readable.
      * <p>Note that in order to properly release resources the
      *  Workbook should be closed after use.
+     *
+     *  @param file The file to read data from.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
+     *  @throws InvalidFormatException if the contents of the file cannot be parsed into a {@link Workbook}
      *  @throws EncryptedDocumentException If the workbook given is password protected
      */
     public static Workbook create(File file) throws IOException, InvalidFormatException, EncryptedDocumentException {
         return create(file, null);
     }
+
     /**
      * Creates the appropriate HSSFWorkbook / XSSFWorkbook from
      *  the given File, which must exist and be readable, and
      *  may be password protected
      * <p>Note that in order to properly release resources the
      *  Workbook should be closed after use.
+     *
+     *  @param file The file to read data from.
+     *  @param password The password that should be used or null if no password is necessary.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
+     *  @throws InvalidFormatException if the contents of the file cannot be parsed into a {@link Workbook}
      *  @throws EncryptedDocumentException If the wrong password is given for a protected file
      *  @throws EmptyFileException If an empty stream is given
      */
     public static Workbook create(File file, String password) throws IOException, InvalidFormatException, EncryptedDocumentException {
+    	return create(file, password, false);
+    }
+
+    /**
+     * Creates the appropriate HSSFWorkbook / XSSFWorkbook from
+     *  the given File, which must exist and be readable, and
+     *  may be password protected
+     * <p>Note that in order to properly release resources the
+     *  Workbook should be closed after use.
+     *
+     *  @param file The file to read data from.
+     *  @param password The password that should be used or null if no password is necessary.
+     *  @param readOnly If the Workbook should be opened in read-only mode to avoid writing back
+     *  	changes when the document is closed.
+     *
+     *  @return The created Workbook
+     *
+     *  @throws IOException if an error occurs while reading the data
+     *  @throws InvalidFormatException if the contents of the file cannot be parsed into a {@link Workbook}
+     *  @throws EncryptedDocumentException If the wrong password is given for a protected file
+     *  @throws EmptyFileException If an empty stream is given
+     */
+    public static Workbook create(File file, String password, boolean readOnly) throws IOException, InvalidFormatException, EncryptedDocumentException {
         if (! file.exists()) {
             throw new FileNotFoundException(file.toString());
         }
 
         try {
-            NPOIFSFileSystem fs = new NPOIFSFileSystem(file);
+            NPOIFSFileSystem fs = new NPOIFSFileSystem(file, readOnly);
             return create(fs, password);
         } catch(OfficeXmlFileException e) {
             // opening as .xls failed => try opening as .xlsx
-            OPCPackage pkg = OPCPackage.open(file);
+            OPCPackage pkg = OPCPackage.open(file, readOnly ? PackageAccess.READ : PackageAccess.READ_WRITE);
             try {
                 return new XSSFWorkbook(pkg);
             } catch (IOException ioe) {

src/ooxml/testcases/org/apache/poi/ss/TestWorkbookFactory.java

@@ -70,6 +70,22 @@ public final class TestWorkbookFactory extends TestCase {
         // TODO: this re-writes the sample-file?! wb.close();
     }
 
+    public void testCreateReadOnly() throws Exception {
+        Workbook wb;
+
+        // POIFS -> hssf
+        wb = WorkbookFactory.create(HSSFTestDataSamples.getSampleFile(xls), null, true);
+        assertNotNull(wb);
+        assertTrue(wb instanceof HSSFWorkbook);
+        wb.close();
+
+        // Package -> xssf
+        wb = WorkbookFactory.create(HSSFTestDataSamples.getSampleFile(xlsx), null, true);
+        assertNotNull(wb);
+        assertTrue(wb instanceof XSSFWorkbook);
+        wb.close();
+    }
+
     /**
      * Creates the appropriate kind of Workbook, but
      *  checking the mime magic at the start of the