Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.poi.poifs.filesystem
Class NPOIFSFileSystem

    java.lang.Object
      org.apache.poi.poifs.filesystem.BlockStore
          org.apache.poi.poifs.filesystem.NPOIFSFileSystem

All Implemented Interfaces:
  java.io.Closeable, POIFSViewable

Direct Known Subclasses:
  POIFSFileSystem

    public class NPOIFSFileSystem

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
`NPOIFSFileSystem()` Constructor, intended for writing
`NPOIFSFileSystem(java.io.File file)` Creates a POIFSFileSystem from a `File`.
`NPOIFSFileSystem(java.io.File file, boolean readOnly)` Creates a POIFSFileSystem from a `File`.
`NPOIFSFileSystem(java.nio.channels.FileChannel channel)` Creates a POIFSFileSystem from an open `FileChannel`.
`NPOIFSFileSystem(java.nio.channels.FileChannel channel, boolean readOnly)` Creates a POIFSFileSystem from an open `FileChannel`.
`NPOIFSFileSystem(java.io.InputStream stream)` Create a POIFSFileSystem from an `InputStream`.

Method Summary
`void` | `close()` Closes the FileSystem, freeing any underlying files, streams and buffers.
`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
`static java.io.InputStream` | `createNonClosingInputStream(java.io.InputStream is)` Convenience method for clients that want to avoid the auto-close behaviour of the constructor.
`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()`
`NPOIFSMiniStore` | `getMiniStore()` Returns the MiniStore, which performs a similar low level function to this, except for the small blocks.
`protected int` | `getNextBlock(int offset)` Works out what block follows the specified one.
`NPropertyTable` | `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
`static boolean` | `hasPOIFSHeader(byte[] header8Bytes)` Deprecated. in 3.17-beta2, use `FileMagic.valueOf(InputStream)` == `FileMagic.OLE2` instead
`static boolean` | `hasPOIFSHeader(java.io.InputStream inp)` Deprecated. in 3.17-beta2, use `FileMagic.valueOf(InputStream)` == `FileMagic.OLE2` instead
`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` | `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`

Constructor Detail

### NPOIFSFileSystem

    public NPOIFSFileSystem()

  Constructor, intended for writing

### NPOIFSFileSystem

    public NPOIFSFileSystem(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

### NPOIFSFileSystem

    public NPOIFSFileSystem(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

### NPOIFSFileSystem

    public NPOIFSFileSystem(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

### NPOIFSFileSystem

    public NPOIFSFileSystem(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

### NPOIFSFileSystem

    public NPOIFSFileSystem(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

### createNonClosingInputStream

    public static java.io.InputStream createNonClosingInputStream(java.io.InputStream is)

  Convenience method for clients that want to avoid the auto-close behaviour of the constructor.

### hasPOIFSHeader

    @Deprecated
    @Removal(version="4.0")
    public static boolean hasPOIFSHeader(java.io.InputStream inp)
                                  throws java.io.IOException

  Deprecated. in 3.17-beta2, use `FileMagic.valueOf(InputStream)` == `FileMagic.OLE2` instead

  Checks that the supplied InputStream (which MUST support mark and reset) has a POIFS (OLE2) header at the start of it. If unsure if your InputStream does support mark / reset, use `FileMagic.prepareToCheckMagic(InputStream)` to wrap it and make sure to always use that, and not the original! After the method call, the InputStream is at the same position as of the time of entering the method.

  Parameters:
    `inp` - An InputStream which supports mark/reset
  Throws:
    `java.io.IOException`

### hasPOIFSHeader

    @Deprecated
    @Removal(version="4.0")
    public static boolean hasPOIFSHeader(byte[] header8Bytes)

  Deprecated. in 3.17-beta2, use `FileMagic.valueOf(InputStream)` == `FileMagic.OLE2` instead

  Checks if the supplied first 8 bytes of a stream / file has a POIFS (OLE2) header.

### 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`

### getMiniStore

    public NPOIFSMiniStore getMiniStore()

  Returns the MiniStore, which performs a similar low level function to this, except for the small blocks.

### 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`

### 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`
  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

### 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 NPropertyTable getPropertyTable()

### getHeaderBlock

    @Internal
    public HeaderBlock getHeaderBlock()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2017 The Apache Software Foundation or its licensors, as applicable.