org.apache.poi.poifs.filesystem

Class POIFSFileSystem

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

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.io.InputStream stream) Create a POIFSFileSystem from an InputStream.

Method Summary

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()
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
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.

Parameters:

channel - the FileChannel from which to read the data

Throws:

java.io.IOException - on errors reading, or on invalid data

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.

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

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

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