Package org.apache.poi.poifs.filesystem

Class POIFSFileSystem

    • Constructor Detail

      • 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:
        this constructor gives more control over whether to close the provided channel

      • 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:
        this constructor gives more control over whether to close the provided channel

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

      • 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 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:
        IOException

      • 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

      • 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

      • 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

      • releaseBuffer

        protected void releaseBuffer​(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