Apache POI - Common 5.3.0 · org.apache.poi.poifs.filesystem.POIFSFileSystem

Modifier and Type	Field and Description
private final List<BATBlock>	_bat_blocks
protected DataSource	_data
private HeaderBlock	_header
private POIFSMiniStore	_mini_store
private PropertyTable	_property_table
private DirectoryNode	_root
private final List<BATBlock>	_xbat_blocks
private POIFSBigBlockSize	bigBlockSize What big block size the file uses.
private static final int	DEFAULT_MAX_RECORD_LENGTH
private static final Logger	LOG
private static final int	MAX_ALLOCATION_SIZE
private static final int	MAX_BLOCK_COUNT Maximum number size (in blocks) of the allocation table as supported by POI.
private static int	MAX_RECORD_LENGTH

Access	Constructor and Description
private	POIFSFileSystem(boolean newFS)
public	POIFSFileSystem() Constructor, intended for writing
public	POIFSFileSystem(File the File from which to read the data file) Creates a POIFSFileSystem from a `File`.
public	POIFSFileSystem(File the File from which to read or read/write the data file, boolean whether the POIFileSystem will only be used in read-only mode readOnly) Creates a POIFSFileSystem from a `File`.
public	POIFSFileSystem(FileChannel the FileChannel from which to read the data channel) Creates a POIFSFileSystem from an open `FileChannel`.
public	POIFSFileSystem(FileChannel the FileChannel from which to read or read/write the data channel, boolean whether the POIFileSystem will only be used in read-only mode readOnly) Creates a POIFSFileSystem from an open `FileChannel`.
public	POIFSFileSystem(FileChannel the FileChannel from which to read or read/write the data channel, boolean whether the POIFileSystem will only be used in read-only mode readOnly, boolean whether the provided FileChannel should be closed when `close()` is called, or when this constructor throws an exception closeChannel) Creates a POIFSFileSystem from an open `FileChannel`.
private	POIFSFileSystem(FileChannel channel, File srcFile, boolean readOnly, boolean closeChannelOnError, boolean closeChannelOnClose)
public	POIFSFileSystem(InputStream the InputStream from which to read the data stream) Create a POIFSFileSystem from an `InputStream`.

Method Summary

Modifier and Type	Method and Description
pack-priv PropertyTable	_get_property_table() For unit testing only!
pack-priv void	addDirectory(final DirectoryProperty the DirectoryProperty being added directory) add a new DirectoryProperty to the FileSystem
pack-priv void	addDocument(final POIFSDocument the POIFSDocument being added document) add a new POIFSDocument to the FileSytem
public void	close() Implements java.io.Closeable.close. Closes the FileSystem, freeing any underlying files, streams and buffers.
private void	closeInputStream(InputStream the stream to be closed stream, boolean `false` if an exception is currently being thrown in the calling method success)
public static POIFSFileSystem	Returns: The created and opened POIFSFileSystem create(File The file to create and open file) Creates a new POIFSFileSystem in a new `File`.
private BATBlock	createBAT(int offset, boolean isBAT)
protected ByteBuffer	createBlockIfNeeded(final int offset) Implements abstract org.apache.poi.poifs.filesystem.BlockStore.createBlockIfNeeded. Load the block at the given offset, extending the file if needed
public DirectoryEntry	Returns: the new DirectoryEntry createDirectory(final String the name of the new DirectoryEntry name) create a new DirectoryEntry in the root directory
public DocumentEntry	Returns: the new DocumentEntry createDocument(final InputStream the InputStream from which the document's data will be obtained stream, final String the name of the new POIFSDocument name) Create a new document to be added to the root directory
public DocumentEntry	Returns: the new DocumentEntry createDocument(final String the name of the new DocumentEntry name, final int the size of the new DocumentEntry size, final POIFSWriterListener the writer of the new DocumentEntry writer) create a new DocumentEntry in the root entry; the data will be provided later
public DocumentInputStream	Returns: a newly opened DocumentInputStream createDocumentInputStream(final String the name of the document to be opened documentName) open a document in the root entry's list of entries
protected void	createNewDataSource()
public DocumentEntry	Returns: the new or updated DocumentEntry createOrUpdateDocument(final InputStream the InputStream from which the document's data will be obtained stream, final String the name of the new or existing POIFSDocument name) Set the contents of a document in the root directory, creating if needed, otherwise updating
protected BATBlock.BATBlockAndIndex	getBATBlockAndIndex(final int offset) Implements abstract org.apache.poi.poifs.filesystem.BlockStore.getBATBlockAndIndex. Returns the BATBlock that handles the specified offset, and the relative index within it
public int	Returns: The Big Block size, normally 512 bytes, sometimes 4096 bytes getBigBlockSize()
public POIFSBigBlockSize	Returns: The Big Block size, normally 512 bytes, sometimes 4096 bytes getBigBlockSizeDetails()
protected ByteBuffer	getBlockAt(final int offset) Implements abstract org.apache.poi.poifs.filesystem.BlockStore.getBlockAt. Load the block at the given offset.
protected int	getBlockStoreBlockSize() Implements abstract org.apache.poi.poifs.filesystem.BlockStore.getBlockStoreBlockSize. Returns the size of the blocks managed through the block store.
protected BlockStore.ChainLoopDetector	getChainLoopDetector() Implements abstract org.apache.poi.poifs.filesystem.BlockStore.getChainLoopDetector. Creates a Detector for loops in the chain
protected int	getFreeBlock() Implements abstract org.apache.poi.poifs.filesystem.BlockStore.getFreeBlock. Finds a free block, and returns its offset.
public HeaderBlock	getHeaderBlock()
public static int	Returns: the max record length allowed for POIFSFileSystem getMaxRecordLength()
pack-priv POIFSMiniStore	getMiniStore() Returns the MiniStore, which performs a similar low level function to this, except for the small blocks.
protected int	getNextBlock(final int offset) Implements abstract org.apache.poi.poifs.filesystem.BlockStore.getNextBlock. Works out what block follows the specified one.
public PropertyTable	getPropertyTable()
public DirectoryNode	Returns: the root entry getRoot() Get the root entry
public String	Returns: short description getShortDescription() Implements org.apache.poi.poifs.dev.POIFSViewable.getShortDescription. Provides a short description of the object, to be used when a POIFSViewable object has not provided its contents.
public Object[]	Returns: an array of Object; may not be null, but may be empty getViewableArray() Implements org.apache.poi.poifs.dev.POIFSViewable.getViewableArray. Get an array of objects, some of which may implement POIFSViewable
public Iterator<Object>	Returns: an Iterator; may not be null, but may have an empty back end store getViewableIterator() Implements org.apache.poi.poifs.dev.POIFSViewable.getViewableIterator. Get an Iterator of objects, some of which may implement POIFSViewable
public boolean	isInPlaceWriteable() Does the filesystem support an in-place write via `writeFilesystem()` ?
public static void	main(String[] names of the files; arg[ 0 ] is the input file, arg[ 1 ] is the output file args) read in a file and write it back out again
public boolean	Returns: true if a viewer should call getViewableArray, false if a viewer should call getViewableIterator preferArray() Implements org.apache.poi.poifs.dev.POIFSViewable.preferArray. Give viewers a hint as to whether to call getViewableArray or getViewableIterator
private void	readBAT(int batAt, BlockStore.ChainLoopDetector loopDetector)
private void	readCoreContents() Read and process the PropertiesTable and the FAT / XFAT blocks, so that we're ready to work with the file
protected void	releaseBuffer(ByteBuffer the buffer buffer) Implements abstract org.apache.poi.poifs.filesystem.BlockStore.releaseBuffer. Releases a mmap-ed buffer, which you are sure won't be used again
pack-priv void	remove(EntryNode to be removed entry) remove an entry
private static void	sanityCheckBlockCount(int block_count)
public static void	setMaxRecordLength(int the max record length allowed for POIFSFileSystem length)
protected void	setNextBlock(final int offset, final int nextBlock) Implements abstract org.apache.poi.poifs.filesystem.BlockStore.setNextBlock. Changes the record of what block follows the specified one.
protected long	size()
private void	syncWithDataSource() Has our in-memory objects write their state to their backing blocks
public void	writeFilesystem() Write the filesystem out to the open file.
public void	writeFilesystem(final OutputStream the OutputStream to which the filesystem will be written stream) Write the filesystem out

Field Detail

_bat_blocks	back to summary
private final List<BATBlock> _bat_blocks

_data	back to summary
protected DataSource _data

_header	back to summary
private HeaderBlock _header

_mini_store	back to summary
private POIFSMiniStore _mini_store

_property_table	back to summary
private PropertyTable _property_table

_root	back to summary
private DirectoryNode _root

_xbat_blocks	back to summary
private final List<BATBlock> _xbat_blocks

bigBlockSize	back to summary
private POIFSBigBlockSize bigBlockSize What big block size the file uses. Most files use 512 bytes, but a few use 4096

DEFAULT_MAX_RECORD_LENGTH	back to summary
private static final int DEFAULT_MAX_RECORD_LENGTH

LOG	back to summary
private static final Logger LOG

MAX_ALLOCATION_SIZE	back to summary
private static final int MAX_ALLOCATION_SIZE

MAX_BLOCK_COUNT back to summary

MAX_BLOCK_COUNT	back to summary
private static final int MAX_BLOCK_COUNT Maximum number size (in blocks) of the allocation table as supported by POI. This constant has been chosen to help POI identify corrupted data in the header block (rather than crash immediately with `OutOfMemoryError` ). It's not clear if the compound document format actually specifies any upper limits. For files with 512 byte blocks, having an allocation table of 65,335 blocks would correspond to a total file size of 4GB. Needless to say, POI probably cannot handle files anywhere near that size.

private static final int MAX_BLOCK_COUNT

Maximum number size (in blocks) of the allocation table as supported by POI.

This constant has been chosen to help POI identify corrupted data in the header block (rather than crash immediately with OutOfMemoryError ). It's not clear if the compound document format actually specifies any upper limits. For files with 512 byte blocks, having an allocation table of 65,335 blocks would correspond to a total file size of 4GB. Needless to say, POI probably cannot handle files anywhere near that size.

MAX_RECORD_LENGTH	back to summary
private static int MAX_RECORD_LENGTH

Constructor Detail

POIFSFileSystem	back to summary
private POIFSFileSystem(boolean newFS)

POIFSFileSystem	back to summary
public POIFSFileSystem() Constructor, intended for writing

POIFSFileSystem back to summary

POIFSFileSystem	back to summary
public POIFSFileSystem(File file) throws IOException Creates a POIFSFileSystem from a `File`. This uses less memory than creating from an `InputStream`. The File will be opened read-only Note that with this constructor, you will need to call `close()` when you're done to have the underlying file closed, as the file is kept open during normal operation to read the data out. Parameters file:File the File from which to read the data Exceptions IOException: on errors reading, or on invalid data

public POIFSFileSystem(File file) throws IOException

Creates a POIFSFileSystem from a File. This uses less memory than creating from an InputStream. The File will be opened read-only

Note that with this constructor, you will need to call close() when you're done to have the underlying file closed, as the file is kept open during normal operation to read the data out.

Parameters

file:File: the File from which to read the data

Exceptions

IOException:: on errors reading, or on invalid data

POIFSFileSystem back to summary

POIFSFileSystem	back to summary
public POIFSFileSystem(File file, boolean readOnly) throws IOException Creates a POIFSFileSystem from a `File`. This uses less memory than creating from an `InputStream`. Note that with this constructor, you will need to call `close()` when you're done to have the underlying file closed, as the file is kept open during normal operation to read the data out. Parameters file:File the File from which to read or read/write the data readOnly:boolean whether the POIFileSystem will only be used in read-only mode Exceptions IOException: on errors reading, or on invalid data

public POIFSFileSystem(File file, boolean readOnly) throws IOException

Creates a POIFSFileSystem from a File. This uses less memory than creating from an InputStream.

Note that with this constructor, you will need to call close() when you're done to have the underlying file closed, as the file is kept open during normal operation to read the data out.

Parameters

file:File: the File from which to read or read/write the data
readOnly:boolean: whether the POIFileSystem will only be used in read-only mode

Exceptions

IOException:: on errors reading, or on invalid data

POIFSFileSystem back to summary

POIFSFileSystem	back to summary
public POIFSFileSystem(FileChannel channel) throws IOException Creates a POIFSFileSystem from an open `FileChannel`. This uses less memory than creating from an `InputStream`. The stream will be used in read-only mode. Note that with this constructor, you will need to call `close()` when you're done to have the underlying Channel closed, as the channel is kept open during normal operation to read the data out. For legacy reasons, the channel is not closed if there is an error creating the POIFSFileSystem. Parameters channel:FileChannel the FileChannel from which to read the data Exceptions IOException: on errors reading, or on invalid data See Also `this constructor gives more control over whether to close the provided channel`

public POIFSFileSystem(FileChannel channel) throws IOException

Creates a POIFSFileSystem from an open FileChannel. This uses less memory than creating from an InputStream. The stream will be used in read-only mode.

Note that with this constructor, you will need to call close() when you're done to have the underlying Channel closed, as the channel is kept open during normal operation to read the data out. For legacy reasons, the channel is not closed if there is an error creating the POIFSFileSystem.

Parameters

channel:FileChannel: the FileChannel from which to read the data

Exceptions

IOException:: on errors reading, or on invalid data

POIFSFileSystem back to summary

POIFSFileSystem	back to summary
public POIFSFileSystem(FileChannel channel, boolean readOnly) throws IOException Creates a POIFSFileSystem from an open `FileChannel`. This uses less memory than creating from an `InputStream`. Note that with this constructor, you will need to call `close()` when you're done to have the underlying Channel closed, as the channel is kept open during normal operation to read the data out. For legacy reasons, the channel is not closed if there is an error creating the POIFSFileSystem. Parameters channel:FileChannel the FileChannel from which to read or read/write the data readOnly:boolean whether the POIFileSystem will only be used in read-only mode Exceptions IOException: on errors reading, or on invalid data See Also `this constructor gives more control over whether to close the provided channel`

public POIFSFileSystem(FileChannel channel, boolean readOnly) throws IOException

Creates a POIFSFileSystem from an open FileChannel. This uses less memory than creating from an InputStream.

Parameters

channel:FileChannel: the FileChannel from which to read or read/write the data
readOnly:boolean: whether the POIFileSystem will only be used in read-only mode

Exceptions

IOException:: on errors reading, or on invalid data

POIFSFileSystem back to summary

POIFSFileSystem	back to summary
public POIFSFileSystem(FileChannel channel, boolean readOnly, boolean closeChannel) throws IOException Creates a POIFSFileSystem from an open `FileChannel`. This uses less memory than creating from an `InputStream`. Note that with this constructor, you will need to call `close()` when you're done to have the underlying resources closed. The `closeChannel` parameter controls whether the provided channel is closed. Parameters channel:FileChannel the FileChannel from which to read or read/write the data readOnly:boolean whether the POIFileSystem will only be used in read-only mode closeChannel:boolean whether the provided FileChannel should be closed when `close()` is called, or when this constructor throws an exception Exceptions IOException: on errors reading, or on invalid data Since POI 5.1.0

public POIFSFileSystem(FileChannel channel, boolean readOnly, boolean closeChannel) throws IOException

Creates a POIFSFileSystem from an open FileChannel. This uses less memory than creating from an InputStream.

Note that with this constructor, you will need to call close() when you're done to have the underlying resources closed. The closeChannel parameter controls whether the provided channel is closed.

Parameters

channel:FileChannel: the FileChannel from which to read or read/write the data
readOnly:boolean: whether the POIFileSystem will only be used in read-only mode
closeChannel:boolean: whether the provided FileChannel should be closed when close() is called, or when this constructor throws an exception

Exceptions

IOException:: on errors reading, or on invalid data

Since

POI 5.1.0

POIFSFileSystem	back to summary
private POIFSFileSystem(FileChannel channel, File srcFile, boolean readOnly, boolean closeChannelOnError, boolean closeChannelOnClose) throws IOException Annotations @SuppressWarnings:java:S2095

POIFSFileSystem back to summary

POIFSFileSystem	back to summary
public POIFSFileSystem(InputStream stream) throws IOException Create a POIFSFileSystem from an `InputStream`. Normally the stream is read until EOF. The stream is always closed. Some streams are usable after reaching EOF (typically those that return `true` for `markSupported()`). In the unlikely case that the caller has such a stream and needs to use it after this constructor completes, a work around is to wrap the stream in order to trap the `close()` call. A convenience method ( `createNonClosingInputStream()`) has been provided for this purpose: InputStream wrappedStream = POIFSFileSystem.createNonClosingInputStream(is); HSSFWorkbook wb = new HSSFWorkbook(wrappedStream); is.reset(); doSomethingElse(is); Note also the special case of `ByteArrayInputStream` for which the `close()` method does nothing. ByteArrayInputStream bais = ... HSSFWorkbook wb = new HSSFWorkbook(bais); // calls bais.close() ! bais.reset(); // no problem doSomethingElse(bais); Parameters stream:InputStream the InputStream from which to read the data Exceptions IOException: on errors reading, or on invalid data

public POIFSFileSystem(InputStream stream) throws IOException

Create a POIFSFileSystem from an InputStream. Normally the stream is read until EOF. The stream is always closed.

Some streams are usable after reaching EOF (typically those that return true for markSupported()). In the unlikely case that the caller has such a stream and needs to use it after this constructor completes, a work around is to wrap the stream in order to trap the close() call. A convenience method ( createNonClosingInputStream()) has been provided for this purpose:

InputStream wrappedStream = POIFSFileSystem.createNonClosingInputStream(is);
HSSFWorkbook wb = new HSSFWorkbook(wrappedStream);
is.reset();
doSomethingElse(is);

Note also the special case of ByteArrayInputStream for which the close() method does nothing.

ByteArrayInputStream bais = ...
HSSFWorkbook wb = new HSSFWorkbook(bais); // calls bais.close() !
bais.reset(); // no problem
doSomethingElse(bais);

Parameters

stream:InputStream: the InputStream from which to read the data

Exceptions

IOException:: on errors reading, or on invalid data

Method Detail

_get_property_table	back to summary
pack-priv PropertyTable _get_property_table() For unit testing only! Returns the underlying properties table

addDirectory	back to summary
pack-priv void addDirectory(final DirectoryProperty directory) add a new DirectoryProperty to the FileSystem Parameters directory:DirectoryProperty the DirectoryProperty being added

addDirectory

public Class POIFSFileSystem

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail