Bug 58915: Update javadoc for memory consumption and fix some other javadoc and compiler warnings

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1737024 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Dominik Stadler 2016-03-29 17:27:20 +00:00
parent 00e6abb6bc
commit ff68b433b8
1 changed files with 34 additions and 17 deletions

View File

@ -57,6 +57,19 @@ import org.apache.poi.xssf.usermodel.XSSFWorkbook;
/** /**
* Streaming version of XSSFWorkbook implementing the "BigGridDemo" strategy. * Streaming version of XSSFWorkbook implementing the "BigGridDemo" strategy.
* *
* This allows to write very large files without running out of memory as only
* a configurable portion of the rows are kept in memory at any one time.
*
* You can provide a template workbook which is used as basis for the written
* data.
*
* See https://poi.apache.org/spreadsheet/how-to.html#sxssf for details.
*
* Please note that there are still things that still may consume a large
* amount of memory based on which features you are using, e.g. merged regions,
* comments, ... are still only stored in memory and thus may require a lot of
* memory if used extensively.
*
* SXSSFWorkbook defaults to using inline strings instead of a shared strings * SXSSFWorkbook defaults to using inline strings instead of a shared strings
* table. This is very efficient, since no document content needs to be kept in * table. This is very efficient, since no document content needs to be kept in
* memory, but is also known to produce documents that are incompatible with * memory, but is also known to produce documents that are incompatible with
@ -96,7 +109,7 @@ public class SXSSFWorkbook implements Workbook {
private final SharedStringsTable _sharedStringSource; private final SharedStringsTable _sharedStringSource;
/** /**
* Construct a new workbook * Construct a new workbook with default row window size
*/ */
public SXSSFWorkbook(){ public SXSSFWorkbook(){
this(null /*workbook*/); this(null /*workbook*/);
@ -160,7 +173,7 @@ public class SXSSFWorkbook implements Workbook {
* without having a chance to specify any cells. * without having a chance to specify any cells.
* </p> * </p>
* *
* @param rowAccessWindowSize * @param rowAccessWindowSize the number of rows that are kept in memory until flushed out, see above.
*/ */
public SXSSFWorkbook(XSSFWorkbook workbook, int rowAccessWindowSize){ public SXSSFWorkbook(XSSFWorkbook workbook, int rowAccessWindowSize){
this(workbook,rowAccessWindowSize, false); this(workbook,rowAccessWindowSize, false);
@ -184,7 +197,7 @@ public class SXSSFWorkbook implements Workbook {
* without having a chance to specify any cells. * without having a chance to specify any cells.
* </p> * </p>
* *
* @param rowAccessWindowSize * @param rowAccessWindowSize the number of rows that are kept in memory until flushed out, see above.
* @param compressTmpFiles whether to use gzip compression for temporary files * @param compressTmpFiles whether to use gzip compression for temporary files
*/ */
public SXSSFWorkbook(XSSFWorkbook workbook, int rowAccessWindowSize, boolean compressTmpFiles){ public SXSSFWorkbook(XSSFWorkbook workbook, int rowAccessWindowSize, boolean compressTmpFiles){
@ -210,7 +223,7 @@ public class SXSSFWorkbook implements Workbook {
* </p> * </p>
* *
* @param workbook the template workbook * @param workbook the template workbook
* @param rowAccessWindowSize * @param rowAccessWindowSize the number of rows that are kept in memory until flushed out, see above.
* @param compressTmpFiles whether to use gzip compression for temporary files * @param compressTmpFiles whether to use gzip compression for temporary files
* @param useSharedStringsTable whether to use a shared strings table * @param useSharedStringsTable whether to use a shared strings table
*/ */
@ -251,18 +264,22 @@ public class SXSSFWorkbook implements Workbook {
* without having a chance to specify any cells. * without having a chance to specify any cells.
* </p> * </p>
* *
* @param rowAccessWindowSize * @param rowAccessWindowSize the number of rows that are kept in memory until flushed out, see above.
*/ */
public SXSSFWorkbook(int rowAccessWindowSize){ public SXSSFWorkbook(int rowAccessWindowSize){
this(null /*workbook*/, rowAccessWindowSize); this(null /*workbook*/, rowAccessWindowSize);
} }
public int getRandomAccessWindowSize() /**
{ * See the constructors for a more detailed description of the sliding window of rows.
*
* @return The number of rows that are kept in memory at once before flushing them out.
*/
public int getRandomAccessWindowSize() {
return _randomAccessWindowSize; return _randomAccessWindowSize;
} }
private void setRandomAccessWindowSize(int rowAccessWindowSize)
{ private void setRandomAccessWindowSize(int rowAccessWindowSize) {
if(rowAccessWindowSize == 0 || rowAccessWindowSize < -1) { if(rowAccessWindowSize == 0 || rowAccessWindowSize < -1) {
throw new IllegalArgumentException("rowAccessWindowSize must be greater than 0 or -1"); throw new IllegalArgumentException("rowAccessWindowSize must be greater than 0 or -1");
} }
@ -296,14 +313,12 @@ public class SXSSFWorkbook implements Workbook {
XSSFSheet getXSSFSheet(SXSSFSheet sheet) XSSFSheet getXSSFSheet(SXSSFSheet sheet)
{ {
XSSFSheet result=_sxFromXHash.get(sheet); return _sxFromXHash.get(sheet);
return result;
} }
SXSSFSheet getSXSSFSheet(XSSFSheet sheet) SXSSFSheet getSXSSFSheet(XSSFSheet sheet)
{ {
SXSSFSheet result=_xFromSxHash.get(sheet); return _xFromSxHash.get(sheet);
return result;
} }
void registerSheetMapping(SXSSFSheet sxSheet,XSSFSheet xSheet) void registerSheetMapping(SXSSFSheet sxSheet,XSSFSheet xSheet)
@ -311,6 +326,7 @@ public class SXSSFWorkbook implements Workbook {
_sxFromXHash.put(sxSheet,xSheet); _sxFromXHash.put(sxSheet,xSheet);
_xFromSxHash.put(xSheet,sxSheet); _xFromSxHash.put(xSheet,sxSheet);
} }
void deregisterSheetMapping(XSSFSheet xSheet) void deregisterSheetMapping(XSSFSheet xSheet)
{ {
SXSSFSheet sxSheet=getSXSSFSheet(xSheet); SXSSFSheet sxSheet=getSXSSFSheet(xSheet);
@ -326,6 +342,7 @@ public class SXSSFWorkbook implements Workbook {
_xFromSxHash.remove(xSheet); _xFromSxHash.remove(xSheet);
} }
private XSSFSheet getSheetFromZipEntryName(String sheetRef) private XSSFSheet getSheetFromZipEntryName(String sheetRef)
{ {
for(XSSFSheet sheet : _sxFromXHash.values()) for(XSSFSheet sheet : _sxFromXHash.values())
@ -334,6 +351,7 @@ public class SXSSFWorkbook implements Workbook {
} }
return null; return null;
} }
private void injectData(File zipfile, OutputStream out) throws IOException private void injectData(File zipfile, OutputStream out) throws IOException
{ {
ZipFile zip = ZipHelper.openZipFile(zipfile); ZipFile zip = ZipHelper.openZipFile(zipfile);
@ -629,7 +647,7 @@ public class SXSSFWorkbook implements Workbook {
} }
SXSSFSheet createAndRegisterSXSSFSheet(XSSFSheet xSheet) SXSSFSheet createAndRegisterSXSSFSheet(XSSFSheet xSheet)
{ {
SXSSFSheet sxSheet=null; final SXSSFSheet sxSheet;
try try
{ {
sxSheet=new SXSSFSheet(this,xSheet); sxSheet=new SXSSFSheet(this,xSheet);
@ -704,8 +722,7 @@ public class SXSSFWorkbook implements Workbook {
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public T next() throws NoSuchElementException { public T next() throws NoSuchElementException {
final XSSFSheet xssfSheet = it.next(); final XSSFSheet xssfSheet = it.next();
final T sxssfSheet = (T) getSXSSFSheet(xssfSheet); return (T) getSXSSFSheet(xssfSheet);
return sxssfSheet;
} }
/** /**
* Unexpected behavior may occur if sheets are reordered after iterator * Unexpected behavior may occur if sheets are reordered after iterator