moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

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.

Browse Source 
Also adjust Javadoc somewhat.

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1681823 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Dominik Stadler 2015-05-26 19:30:21 +00:00
parent 9017803980
commit 03805d9e20
2 changed files with 129 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
src/ooxml/java/org/apache/poi/ss/usermodel/WorkbookFactory.java
View File

@ -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) {

16
src/ooxml/testcases/org/apache/poi/ss/TestWorkbookFactory.java
View File

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