POIFSFileSystem (POI API Documentation)

java.lang.Object
- org.apache.poi.poifs.filesystem.BlockStore
- - org.apache.poi.poifs.filesystem.POIFSFileSystem

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, POIFSViewable

Direct Known Subclasses:

TempFilePOIFSFileSystem
```
public class POIFSFileSystem
extends BlockStore
implements POIFSViewable, java.io.Closeable
```
This is the main class of the POIFS system; it manages the entire life cycle of the filesystem.

This is the new NIO version, which uses less memory

Nested Class Summary
- Nested classes/interfaces inherited from class org.apache.poi.poifs.filesystem.BlockStore
  BlockStore.ChainLoopDetector

Field Summary

Fields
Modifier and Type Field and Description

protected DataSource _data

Fields
Modifier and Type	Field and Description
`protected DataSource`	`_data`

Constructor Summary

Constructors
Constructor and Description
`POIFSFileSystem()` Constructor, intended for writing
`POIFSFileSystem(java.io.File file)` Creates a POIFSFileSystem from a `File`.
`POIFSFileSystem(java.io.File file, boolean readOnly)` Creates a POIFSFileSystem from a `File`.
`POIFSFileSystem(java.nio.channels.FileChannel channel)` Creates a POIFSFileSystem from an open `FileChannel`.
`POIFSFileSystem(java.nio.channels.FileChannel channel, boolean readOnly)` Creates a POIFSFileSystem from an open `FileChannel`.
`POIFSFileSystem(java.nio.channels.FileChannel channel, boolean readOnly, boolean closeChannel)` Creates a POIFSFileSystem from an open `FileChannel`.
`POIFSFileSystem(java.io.InputStream stream)` Create a POIFSFileSystem from an `InputStream`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Closes the FileSystem, freeing any underlying files, streams and buffers.
`static POIFSFileSystem`	`create(java.io.File file)` Creates a new POIFSFileSystem in a new `File`.
`protected java.nio.ByteBuffer`	`createBlockIfNeeded(int offset)` Load the block at the given offset, extending the file if needed
`DirectoryEntry`	`createDirectory(java.lang.String name)` create a new DirectoryEntry in the root directory
`DocumentEntry`	`createDocument(java.io.InputStream stream, java.lang.String name)` Create a new document to be added to the root directory
`DocumentEntry`	`createDocument(java.lang.String name, int size, POIFSWriterListener writer)` create a new DocumentEntry in the root entry; the data will be provided later
`DocumentInputStream`	`createDocumentInputStream(java.lang.String documentName)` open a document in the root entry's list of entries
`protected void`	`createNewDataSource()`
`DocumentEntry`	`createOrUpdateDocument(java.io.InputStream stream, java.lang.String name)` Set the contents of a document in the root directory, creating if needed, otherwise updating
`protected BATBlock.BATBlockAndIndex`	`getBATBlockAndIndex(int offset)` Returns the BATBlock that handles the specified offset, and the relative index within it
`int`	`getBigBlockSize()`
`POIFSBigBlockSize`	`getBigBlockSizeDetails()`
`protected java.nio.ByteBuffer`	`getBlockAt(int offset)` Load the block at the given offset.
`protected int`	`getBlockStoreBlockSize()` Returns the size of the blocks managed through the block store.
`protected BlockStore.ChainLoopDetector`	`getChainLoopDetector()` Creates a Detector for loops in the chain
`protected int`	`getFreeBlock()` Finds a free block, and returns its offset.
`HeaderBlock`	`getHeaderBlock()`
`static int`	`getMaxRecordLength()`
`protected int`	`getNextBlock(int offset)` Works out what block follows the specified one.
`PropertyTable`	`getPropertyTable()`
`DirectoryNode`	`getRoot()` Get the root entry
`java.lang.String`	`getShortDescription()` Provides a short description of the object, to be used when a POIFSViewable object has not provided its contents.
`java.lang.Object[]`	`getViewableArray()` Get an array of objects, some of which may implement POIFSViewable
`java.util.Iterator<java.lang.Object>`	`getViewableIterator()` Get an Iterator of objects, some of which may implement POIFSViewable
`boolean`	`isInPlaceWriteable()` Does the filesystem support an in-place write via `writeFilesystem()` ? If false, only writing out to a brand new file via `writeFilesystem(OutputStream)` is supported.
`static void`	`main(java.lang.String[] args)` read in a file and write it back out again
`boolean`	`preferArray()` Give viewers a hint as to whether to call getViewableArray or getViewableIterator
`protected void`	`releaseBuffer(java.nio.ByteBuffer buffer)` Releases a mmap-ed buffer, which you are sure won't be used again
`static void`	`setMaxRecordLength(int length)`
`protected void`	`setNextBlock(int offset, int nextBlock)` Changes the record of what block follows the specified one.
`protected long`	`size()`
`void`	`writeFilesystem()` Write the filesystem out to the open file.
`void`	`writeFilesystem(java.io.OutputStream stream)` Write the filesystem out

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - _data
```
protected DataSource _data
```
- Constructor Detail
  - POIFSFileSystem
```
public POIFSFileSystem()
```
    Constructor, intended for writing
  - POIFSFileSystem
```
public POIFSFileSystem(java.io.File file)
                throws java.io.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 - the File from which to read the data
    
    Throws:
    
    java.io.IOException - on errors reading, or on invalid data
  - POIFSFileSystem
```
public POIFSFileSystem(java.io.File file,
                       boolean readOnly)
                throws java.io.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 - the File from which to read or read/write the data
    
    readOnly - whether the POIFileSystem will only be used in read-only mode
    
    Throws:
    
    java.io.IOException - on errors reading, or on invalid data
  - POIFSFileSystem
```
public POIFSFileSystem(java.nio.channels.FileChannel channel)
                throws java.io.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 - the FileChannel from which to read the data
    
    Throws:
    
    java.io.IOException - on errors reading, or on invalid data
    
    See Also:
    
    this constructor gives more control over whether to close the provided channel
  - POIFSFileSystem
```
public POIFSFileSystem(java.nio.channels.FileChannel channel,
                       boolean readOnly)
                throws java.io.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 - the FileChannel from which to read or read/write the data
    
    readOnly - whether the POIFileSystem will only be used in read-only mode
    
    Throws:
    
    java.io.IOException - on errors reading, or on invalid data
    
    See Also:
    
    this constructor gives more control over whether to close the provided channel
  - POIFSFileSystem
```
public POIFSFileSystem(java.nio.channels.FileChannel channel,
                       boolean readOnly,
                       boolean closeChannel)
                throws java.io.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 - the FileChannel from which to read or read/write the data
    
    readOnly - whether the POIFileSystem will only be used in read-only mode
    
    closeChannel - whether the provided FileChannel should be closed when close() is called, or when this constructor throws an exception
    
    Throws:
    
    java.io.IOException - on errors reading, or on invalid data
    
    Since:
    
    POI 5.1.0
  - POIFSFileSystem
```
public POIFSFileSystem(java.io.InputStream stream)
                throws java.io.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 - the InputStream from which to read the data
    
    Throws:
    
    java.io.IOException - on errors reading, or on invalid data
- Method Detail
  - setMaxRecordLength
```
public static void setMaxRecordLength(int length)
```
    Parameters:
    
    length - the max record length allowed for POIFSFileSystem
  - getMaxRecordLength
```
public static int getMaxRecordLength()
```
    Returns:
    
    the max record length allowed for POIFSFileSystem
  - createNewDataSource
```
protected void createNewDataSource()
```
  - getBlockAt
```
protected java.nio.ByteBuffer getBlockAt(int offset)
                                  throws java.io.IOException
```
    Load the block at the given offset.
    
    Specified by:
    
    getBlockAt in class BlockStore
    
    Throws:
    
    java.io.IOException
  - createBlockIfNeeded
```
protected java.nio.ByteBuffer createBlockIfNeeded(int offset)
                                           throws java.io.IOException
```
    Load the block at the given offset, extending the file if needed
    
    Specified by:
    
    createBlockIfNeeded in class BlockStore
    
    Throws:
    
    java.io.IOException
  - getBATBlockAndIndex
```
protected BATBlock.BATBlockAndIndex getBATBlockAndIndex(int offset)
```
    Returns the BATBlock that handles the specified offset, and the relative index within it
    
    Specified by:
    
    getBATBlockAndIndex in class BlockStore
  - getNextBlock
```
protected int getNextBlock(int offset)
```
    Works out what block follows the specified one.
    
    Specified by:
    
    getNextBlock in class BlockStore
  - setNextBlock
```
protected void setNextBlock(int offset,
                            int nextBlock)
```
    Changes the record of what block follows the specified one.
    
    Specified by:
    
    setNextBlock in class BlockStore
  - getFreeBlock
```
protected int getFreeBlock()
                    throws java.io.IOException
```
    Finds a free block, and returns its offset. This method will extend the file if needed, and if doing so, allocate new FAT blocks to address the extra space.
    
    Specified by:
    
    getFreeBlock in class BlockStore
    
    Throws:
    
    java.io.IOException
  - size
```
protected long size()
             throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - getChainLoopDetector
```
protected BlockStore.ChainLoopDetector getChainLoopDetector()
                                                     throws java.io.IOException
```
    Description copied from class: BlockStore
    
    Creates a Detector for loops in the chain
    
    Specified by:
    
    getChainLoopDetector in class BlockStore
    
    Throws:
    
    java.io.IOException
  - createDocument
```
public DocumentEntry createDocument(java.io.InputStream stream,
                                    java.lang.String name)
                             throws java.io.IOException
```
    Create a new document to be added to the root directory
    
    Parameters:
    
    stream - the InputStream from which the document's data will be obtained
    
    name - the name of the new POIFSDocument
    
    Returns:
    
    the new DocumentEntry
    
    Throws:
    
    java.io.IOException - on error creating the new POIFSDocument
  - createDocument
```
public DocumentEntry createDocument(java.lang.String name,
                                    int size,
                                    POIFSWriterListener writer)
                             throws java.io.IOException
```
    create a new DocumentEntry in the root entry; the data will be provided later
    
    Parameters:
    
    name - the name of the new DocumentEntry
    
    size - the size of the new DocumentEntry
    
    writer - the writer of the new DocumentEntry
    
    Returns:
    
    the new DocumentEntry
    
    Throws:
    
    java.io.IOException - if the writer exceeds the given size
  - createDirectory
```
public DirectoryEntry createDirectory(java.lang.String name)
                               throws java.io.IOException
```
    create a new DirectoryEntry in the root directory
    
    Parameters:
    
    name - the name of the new DirectoryEntry
    
    Returns:
    
    the new DirectoryEntry
    
    Throws:
    
    java.io.IOException - on name duplication
  - createOrUpdateDocument
```
public DocumentEntry createOrUpdateDocument(java.io.InputStream stream,
                                            java.lang.String name)
                                     throws java.io.IOException
```
    Set the contents of a document in the root directory, creating if needed, otherwise updating
    
    Parameters:
    
    stream - the InputStream from which the document's data will be obtained
    
    name - the name of the new or existing POIFSDocument
    
    Returns:
    
    the new or updated DocumentEntry
    
    Throws:
    
    java.io.IOException - on error populating the POIFSDocument
  - isInPlaceWriteable
```
public boolean isInPlaceWriteable()
```
    Does the filesystem support an in-place write via writeFilesystem() ? If false, only writing out to a brand new file via writeFilesystem(OutputStream) is supported.
  - writeFilesystem
```
public void writeFilesystem()
                     throws java.io.IOException
```
    Write the filesystem out to the open file. Will thrown an IllegalArgumentException if opened from an InputStream.
    
    Throws:
    
    java.io.IOException - thrown on errors writing to the stream
  - writeFilesystem
```
public void writeFilesystem(java.io.OutputStream stream)
                     throws java.io.IOException
```
    Write the filesystem out
    
    Parameters:
    
    stream - the OutputStream to which the filesystem will be written
    
    Throws:
    
    java.io.IOException - thrown on errors writing to the stream
  - close
```
public void close()
           throws java.io.IOException
```
    Closes the FileSystem, freeing any underlying files, streams and buffers. After this, you will be unable to read or write from the FileSystem.
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Throws:
    
    java.io.IOException
  - main
```
public static void main(java.lang.String[] args)
                 throws java.io.IOException
```
    read in a file and write it back out again
    
    Parameters:
    
    args - names of the files; arg[ 0 ] is the input file, arg[ 1 ] is the output file
    
    Throws:
    
    java.io.IOException
  - getRoot
```
public DirectoryNode getRoot()
```
    Get the root entry
    
    Returns:
    
    the root entry
  - createDocumentInputStream
```
public DocumentInputStream createDocumentInputStream(java.lang.String documentName)
                                              throws java.io.IOException
```
    open a document in the root entry's list of entries
    
    Parameters:
    
    documentName - the name of the document to be opened
    
    Returns:
    
    a newly opened DocumentInputStream
    
    Throws:
    
    java.io.IOException - if the document does not exist or the name is that of a DirectoryEntry
  - getViewableArray
```
public java.lang.Object[] getViewableArray()
```
    Get an array of objects, some of which may implement POIFSViewable
    
    Specified by:
    
    getViewableArray in interface POIFSViewable
    
    Returns:
    
    an array of Object; may not be null, but may be empty
  - getViewableIterator
```
public java.util.Iterator<java.lang.Object> getViewableIterator()
```
    Get an Iterator of objects, some of which may implement POIFSViewable
    
    Specified by:
    
    getViewableIterator in interface POIFSViewable
    
    Returns:
    
    an Iterator; may not be null, but may have an empty back end store
  - preferArray
```
public boolean preferArray()
```
    Give viewers a hint as to whether to call getViewableArray or getViewableIterator
    
    Specified by:
    
    preferArray in interface POIFSViewable
    
    Returns:
    
    true if a viewer should call getViewableArray, false if a viewer should call getViewableIterator
  - getShortDescription
```
public java.lang.String getShortDescription()
```
    Provides a short description of the object, to be used when a POIFSViewable object has not provided its contents.
    
    Specified by:
    
    getShortDescription in interface POIFSViewable
    
    Returns:
    
    short description
  - getBigBlockSize
```
public int getBigBlockSize()
```
    Returns:
    
    The Big Block size, normally 512 bytes, sometimes 4096 bytes
  - getBigBlockSizeDetails
```
public POIFSBigBlockSize getBigBlockSizeDetails()
```
    Returns:
    
    The Big Block size, normally 512 bytes, sometimes 4096 bytes
  - create
```
public static POIFSFileSystem create(java.io.File file)
                              throws java.io.IOException
```
    Creates a new POIFSFileSystem in a new File. Use POIFSFileSystem(File) to open an existing File, this should only be used to create a new empty filesystem.
    
    Parameters:
    
    file - The file to create and open
    
    Returns:
    
    The created and opened POIFSFileSystem
    
    Throws:
    
    java.io.IOException
  - getBlockStoreBlockSize
```
protected int getBlockStoreBlockSize()
```
    Description copied from class: BlockStore
    
    Returns the size of the blocks managed through the block store.
    
    Specified by:
    
    getBlockStoreBlockSize in class BlockStore
  - getPropertyTable
```
@Internal
public PropertyTable getPropertyTable()
```
  - getHeaderBlock
```
@Internal
public HeaderBlock getHeaderBlock()
```
  - releaseBuffer
```
protected void releaseBuffer(java.nio.ByteBuffer buffer)
```
    Description copied from class: BlockStore
    
    Releases a mmap-ed buffer, which you are sure won't be used again
    
    Specified by:
    
    releaseBuffer in class BlockStore
    
    Parameters:
    
    buffer - the buffer

Class POIFSFileSystem

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.poi.poifs.filesystem.BlockStore

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_data

Constructor Detail

POIFSFileSystem

POIFSFileSystem

POIFSFileSystem

POIFSFileSystem

POIFSFileSystem

POIFSFileSystem

POIFSFileSystem

Method Detail

setMaxRecordLength

getMaxRecordLength

createNewDataSource

getBlockAt

createBlockIfNeeded

getBATBlockAndIndex

getNextBlock

setNextBlock

getFreeBlock

size

getChainLoopDetector

createDocument

createDocument

createDirectory

createOrUpdateDocument

isInPlaceWriteable

writeFilesystem

writeFilesystem

close

main

getRoot

createDocumentInputStream

getViewableArray

getViewableIterator

preferArray

getShortDescription

getBigBlockSize

getBigBlockSizeDetails

create

getBlockStoreBlockSize

getPropertyTable

getHeaderBlock

releaseBuffer