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
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
-
-
Constructor Summary
Constructors Constructor Description POIFSFileSystem()
Constructor, intended for writingPOIFSFileSystem(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.io.InputStream stream)
Create a POIFSFileSystem from an InputStream.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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
close()
Closes the FileSystem, freeing any underlying files, streams and buffers.static POIFSFileSystem
create(java.io.File file)
Creates a newPOIFSFileSystem
in a newFile
.protected java.nio.ByteBuffer
createBlockIfNeeded(int offset)
Load the block at the given offset, extending the file if neededDirectoryEntry
createDirectory(java.lang.String name)
create a new DirectoryEntry in the root directoryDocumentEntry
createDocument(java.io.InputStream stream, java.lang.String name)
Create a new document to be added to the root directoryDocumentEntry
createDocument(java.lang.String name, int size, POIFSWriterListener writer)
create a new DocumentEntry in the root entry; the data will be provided laterDocumentInputStream
createDocumentInputStream(java.lang.String documentName)
open a document in the root entry's list of entriesDocumentEntry
createOrUpdateDocument(java.io.InputStream stream, java.lang.String name)
Set the contents of a document in the root directory, creating if needed, otherwise updatingprotected BATBlock.BATBlockAndIndex
getBATBlockAndIndex(int offset)
Returns the BATBlock that handles the specified offset, and the relative index within itint
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 chainprotected 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 entryjava.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 POIFSViewablejava.util.Iterator<java.lang.Object>
getViewableIterator()
Get an Iterator of objects, some of which may implement POIFSViewableboolean
isInPlaceWriteable()
Does the filesystem support an in-place write viawriteFilesystem()
? If false, only writing out to a brand new file viawriteFilesystem(OutputStream)
is supported.static void
main(java.lang.String[] args)
read in a file and write it back out againboolean
preferArray()
Give viewers a hint as to whether to call getViewableArray or getViewableIteratorprotected 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
-
-
-
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 datareadOnly
- 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 datareadOnly
- 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
-
getBlockAt
protected java.nio.ByteBuffer getBlockAt(int offset) throws java.io.IOException
Load the block at the given offset.- Specified by:
getBlockAt
in classBlockStore
- 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 classBlockStore
- 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 classBlockStore
-
getNextBlock
protected int getNextBlock(int offset)
Works out what block follows the specified one.- Specified by:
getNextBlock
in classBlockStore
-
setNextBlock
protected void setNextBlock(int offset, int nextBlock)
Changes the record of what block follows the specified one.- Specified by:
setNextBlock
in classBlockStore
-
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 classBlockStore
- 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 classBlockStore
- 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 obtainedname
- 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 DocumentEntrysize
- the size of the new DocumentEntrywriter
- 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 obtainedname
- 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 viawriteFilesystem()
? If false, only writing out to a brand new file viawriteFilesystem(OutputStream)
is supported.
-
writeFilesystem
public void writeFilesystem() throws java.io.IOException
Write the filesystem out to the open file. Will thrown anIllegalArgumentException
if opened from anInputStream
.- 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- 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 interfacePOIFSViewable
- 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 interfacePOIFSViewable
- 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 interfacePOIFSViewable
- 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 interfacePOIFSViewable
- 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 newPOIFSFileSystem
in a newFile
. UsePOIFSFileSystem(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 classBlockStore
-
getPropertyTable
@Internal public PropertyTable getPropertyTable()
-
getHeaderBlock
@Internal public HeaderBlock getHeaderBlock()
-
-