Package 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:
Closeable, AutoCloseable, POIFSViewable
Direct Known Subclasses:
TempFilePOIFSFileSystem
public class POIFSFileSystem extends BlockStore implements POIFSViewable, 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

  • Constructor Details

    • POIFSFileSystem

      public POIFSFileSystem()
      Constructor, intended for writing

    • POIFSFileSystem

      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 - the File from which to read the data
      Throws:
      IOException - on errors reading, or on invalid data

    • POIFSFileSystem

      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 - the File from which to read or read/write the data
      readOnly - whether the POIFileSystem will only be used in read-only mode
      Throws:
      IOException - on errors reading, or on invalid data

    • POIFSFileSystem

      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 - the FileChannel from which to read the data
      Throws:
      IOException - on errors reading, or on invalid data
      See Also:

    • POIFSFileSystem

      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 - the FileChannel from which to read or read/write the data
      readOnly - whether the POIFileSystem will only be used in read-only mode
      Throws:
      IOException - on errors reading, or on invalid data
      See Also:

    • POIFSFileSystem

      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 - 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:
      IOException - on errors reading, or on invalid data
      Since:
      POI 5.1.0

    • POIFSFileSystem

      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 - the InputStream from which to read the data
      Throws:
      IOException - on errors reading, or on invalid data

  • Method Details

    • 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

    • createDocument

      public DocumentEntry createDocument(InputStream stream, String name) throws 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:
      IOException - on error creating the new POIFSDocument

    • createDocument

      public DocumentEntry createDocument(String name, int size, POIFSWriterListener writer) throws 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:
      IOException - if the writer exceeds the given size

    • createDirectory

      public DirectoryEntry createDirectory(String name) throws IOException
      create a new DirectoryEntry in the root directory
      Parameters:
      name - the name of the new DirectoryEntry
      Returns:
      the new DirectoryEntry
      Throws:
      IOException - on name duplication

    • createOrUpdateDocument

      public DocumentEntry createOrUpdateDocument(InputStream stream, String name) throws 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:
      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 IOException
      Write the filesystem out to the open file. Will thrown an IllegalArgumentException if opened from an InputStream.
      Throws:
      IOException - thrown on errors writing to the stream

    • writeFilesystem

      public void writeFilesystem(OutputStream stream) throws IOException
      Write the filesystem out
      Parameters:
      stream - the OutputStream to which the filesystem will be written
      Throws:
      IOException - thrown on errors writing to the stream

    • close

      public void close() throws 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 AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • main

      public static void main(String[] args) throws 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:
      IOException

    • getRoot

      public DirectoryNode getRoot()
      Get the root entry
      Returns:
      the root entry

    • createDocumentInputStream

      public DocumentInputStream createDocumentInputStream(String documentName) throws 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:
      IOException - if the document does not exist or the name is that of a DirectoryEntry

    • getViewableArray

      public 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 Iterator<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 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(File file) throws 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:
      IOException

    • getPropertyTable

      @Internal public PropertyTable getPropertyTable()

    • getHeaderBlock

      @Internal public HeaderBlock getHeaderBlock()