org.apache.poi.poifs.filesystem
Class NPOIFSFileSystem

java.lang.Object
  extended by org.apache.poi.poifs.filesystem.BlockStore
      extended by org.apache.poi.poifs.filesystem.NPOIFSFileSystem
All Implemented Interfaces:
java.io.Closeable, POIFSViewable

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


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.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.
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.
 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.
 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 getViewableIterator()
          Get an Iterator of objects, some of which may implement POIFSViewable
static boolean hasPOIFSHeader(java.io.InputStream inp)
          Checks that the supplied InputStream (which MUST support mark and reset, or be a PushbackInputStream) has a POIFS (OLE2) header at the start of it.
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.
 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 the data
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. 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.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

public static boolean hasPOIFSHeader(java.io.InputStream inp)
                              throws java.io.IOException
Checks that the supplied InputStream (which MUST support mark and reset, or be a PushbackInputStream) has a POIFS (OLE2) header at the start of it. If your InputStream does not support mark / reset, then wrap it in a PushBackInputStream, then be sure to always use that, and not the original!

Parameters:
inp - An InputStream which supports either mark/reset, or is a PushbackInputStream
Throws:
java.io.IOException

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

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

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


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