pashko/apache-poi
1
0
Fork 0
mirror of https://github.com/apache/poi.git synced 2026-02-27 20:40:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add some missing JavaDoc for WorkbookFactory and ExtractorFactory

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1895414 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Dominik Stadler 2021-11-30 06:19:51 +00:00
parent f57d8adee4
commit 5eb7b44d64
3 changed files with 87 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/BigGridDemo.java
View File

@ -70,7 +70,7 @@ import org.apache.poi.xssf.usermodel.XSSFWorkbook;
* to all rows in the document. Older rows that are no longer in the window
* become inaccessible, as they are written to the disk.
*
* @see <a href="https://poi.apache.org/spreadsheet/how-to.html#sxssf">SXSSF (Streaming Usermodel API)</a>.
* See <a href="https://poi.apache.org/spreadsheet/how-to.html#sxssf">SXSSF (Streaming Usermodel API)</a>.
*/
public final class BigGridDemo {
private static final String XML_ENCODING = "UTF-8";

97
poi/src/main/java/org/apache/poi/extractor/ExtractorFactory.java
View File

@ -138,18 +138,50 @@ public final class ExtractorFactory {
return (allPreferEventExtractors != null) ? allPreferEventExtractors : threadPreferEventExtractors.get();
}
/**
* Create an extractor that can be used to read text from the given file.
*
* @param fs The file-system which wraps the data of the file.
* @return A POITextExtractor that can be used to fetch text-content of the file.
* @throws IOException If reading the file-data fails
*/
public static POITextExtractor createExtractor(POIFSFileSystem fs) throws IOException {
return createExtractor(fs, getCurrentUserPassword());
}
/**
* Create an extractor that can be used to read text from the given file.
*
* @param fs The file-system which wraps the data of the file.
* @param password The password that is necessary to open the file
* @return A POITextExtractor that can be used to fetch text-content of the file.
* @throws IOException If reading the file-data fails
*/
public static POITextExtractor createExtractor(POIFSFileSystem fs, String password) throws IOException {
return createExtractor(fs.getRoot(), password);
}
/**
* Create an extractor that can be used to read text from the given file.
*
* @param input A stream which wraps the data of the file.
* @return A POITextExtractor that can be used to fetch text-content of the file.
* @throws IOException If reading the file-data fails
* @throws EmptyFileException If the given file is empty
*/
public static POITextExtractor createExtractor(InputStream input) throws IOException {
return createExtractor(input, getCurrentUserPassword());
}
/**
* Create an extractor that can be used to read text from the given file.
*
* @param input A stream which wraps the data of the file.
* @param password The password that is necessary to open the file
* @return A POITextExtractor that can be used to fetch text-content of the file.
* @throws IOException If reading the file-data fails
* @throws EmptyFileException If the given file is empty
*/
public static POITextExtractor createExtractor(InputStream input, String password) throws IOException {
final InputStream is = FileMagic.prepareToCheckMagic(input);
byte[] emptyFileCheck = new byte[1];
@ -175,10 +207,27 @@ public final class ExtractorFactory {
return wp(isOOXML ? FileMagic.OOXML : fm, w -> w.create(root, password));
}
/**
* Create an extractor that can be used to read text from the given file.
*
* @param file The file to read
* @return A POITextExtractor that can be used to fetch text-content of the file.
* @throws IOException If reading the file-data fails
* @throws EmptyFileException If the given file is empty
*/
public static POITextExtractor createExtractor(File file) throws IOException {
return createExtractor(file, getCurrentUserPassword());
}
/**
* Create an extractor that can be used to read text from the given file.
*
* @param file The file to read
* @param password The password that is necessary to open the file
* @return A POITextExtractor that can be used to fetch text-content of the file.
* @throws IOException If reading the file-data fails
* @throws EmptyFileException If the given file is empty
*/
@SuppressWarnings({"java:S2095"})
public static POITextExtractor createExtractor(File file, String password) throws IOException {
if (file.length() == 0) {
@ -225,6 +274,22 @@ public final class ExtractorFactory {
return createExtractor(root, getCurrentUserPassword());
}
/**
* Create the Extractor, if possible. Generally needs the Scratchpad jar.
* Note that this won't check for embedded OOXML resources either, use
* {@link org.apache.poi.ooxml.extractor.POIXMLExtractorFactory} for that.
*
* @param root The {@link DirectoryNode} pointing to a document.
* @param password The password that is necessary to open the file
*
* @return The resulting {@link POITextExtractor}, an exception is thrown if
* no TextExtractor can be created for some reason.
*
* @throws IOException If converting the {@link DirectoryNode} into a HSSFWorkbook fails
* @throws org.apache.poi.OldFileFormatException If the {@link DirectoryNode} points to a format of
* an unsupported version of Excel.
* @throws IllegalArgumentException If creating the Extractor fails
*/
public static POITextExtractor createExtractor(final DirectoryNode root, String password) throws IOException {
// Encrypted OOXML files go inside OLE2 containers, is this one?
if (root.hasEntry(DEFAULT_POIFS_ENTRY) || root.hasEntry(OOXML_PACKAGE)) {
@ -234,22 +299,22 @@ public final class ExtractorFactory {
}
}
/**
* Returns an array of text extractors, one for each of
* the embedded documents in the file (if there are any).
* If there are no embedded documents, you'll get back an
* empty array. Otherwise, you'll get one open
* {@link POITextExtractor} for each embedded file.
*
* @param ext The extractor to look at for embedded documents
*
* @return An array of resulting extractors. Empty if no embedded documents are found.
*
* @throws IOException If converting the {@link DirectoryNode} into a HSSFWorkbook fails
* @throws org.apache.poi.OldFileFormatException If the {@link DirectoryNode} points to a format of
* an unsupported version of Excel.
* @throws IllegalArgumentException If creating the Extractor fails
*/
/**
* Returns an array of text extractors, one for each of
* the embedded documents in the file (if there are any).
* If there are no embedded documents, you'll get back an
* empty array. Otherwise, you'll get one open
* {@link POITextExtractor} for each embedded file.
*
* @param ext The extractor to look at for embedded documents
*
* @return An array of resulting extractors. Empty if no embedded documents are found.
*
* @throws IOException If converting the {@link DirectoryNode} into a HSSFWorkbook fails
* @throws org.apache.poi.OldFileFormatException If the {@link DirectoryNode} points to a format of
* an unsupported version of Excel.
* @throws IllegalArgumentException If creating the Extractor fails
*/
public static POITextExtractor[] getEmbeddedDocsTextExtractors(POIOLE2TextExtractor ext) throws IOException {
if (ext == null) {
throw new IllegalStateException("extractor must be given");

5
poi/src/main/java/org/apache/poi/ss/usermodel/WorkbookFactory.java
View File

@ -167,6 +167,7 @@ public final class WorkbookFactory {
*
* @throws IOException if an error occurs while reading the data
* @throws EncryptedDocumentException If the Workbook given is password protected
* @throws EmptyFileException If the given data is empty
*/
public static Workbook create(InputStream inp) throws IOException, EncryptedDocumentException {
return create(inp, null);
@ -193,6 +194,7 @@ public final class WorkbookFactory {
*
* @throws IOException if an error occurs while reading the data
* @throws EncryptedDocumentException If the wrong password is given for a protected file
* @throws EmptyFileException If the given data is empty
*/
public static Workbook create(InputStream inp, String password) throws IOException, EncryptedDocumentException {
InputStream is = FileMagic.prepareToCheckMagic(inp);
@ -231,6 +233,7 @@ public final class WorkbookFactory {
*
* @throws IOException if an error occurs while reading the data
* @throws EncryptedDocumentException If the Workbook given is password protected
* @throws EmptyFileException If the given data is empty
*/
public static Workbook create(File file) throws IOException, EncryptedDocumentException {
return create(file, null);
@ -250,6 +253,7 @@ public final class WorkbookFactory {
*
* @throws IOException if an error occurs while reading the data
* @throws EncryptedDocumentException If the wrong password is given for a protected file
* @throws EmptyFileException If the given data is empty
*/
public static Workbook create(File file, String password) throws IOException, EncryptedDocumentException {
return create(file, password, false);
@ -271,6 +275,7 @@ public final class WorkbookFactory {
*
* @throws IOException if an error occurs while reading the data
* @throws EncryptedDocumentException If the wrong password is given for a protected file
* @throws EmptyFileException If the given data is empty
*/
public static Workbook create(File file, String password, boolean readOnly) throws IOException, EncryptedDocumentException {
if (!file.exists()) {