Package org.apache.poi

Class POIDocument

java.lang.Object

org.apache.poi.POIDocument

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

HPSFPropertiesOnlyDocument, HSSFWorkbook, POIReadOnlyDocument

public abstract class POIDocument
extends Object
implements Closeable

This holds the common functionality for all POI Document classes. Currently, this relates to Document Information Properties

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	POIDocument(DirectoryNode dir)	Constructs a POIDocument with the given directory node.
protected	POIDocument(POIFSFileSystem fs)	Constructs from the default POIFS

Method Summary

Modifier and Type	Method	Description
protected void	clearDirectory()	Clear/unlink the attached directory entry
void	close()	Closes the underlying POIFSFileSystem from which the document was read, if any.
void	createInformationProperties()	Will create whichever of SummaryInformation and DocumentSummaryInformation (HPSF) properties are not already part of your document.
DirectoryNode	getDirectory()
DocumentSummaryInformation	getDocumentSummaryInformation()	Fetch the Document Summary Information of the document
protected String	getEncryptedPropertyStreamName()
EncryptionInfo	getEncryptionInfo()
protected PropertySet	getPropertySet(String setName)	For a given named property entry, either return it or null if if it wasn't found
protected PropertySet	getPropertySet(String setName, EncryptionInfo encryptionInfo)	For a given named property entry, either return it or null if if it wasn't found
SummaryInformation	getSummaryInformation()	Fetch the Summary Information of the document
protected boolean	initDirectory()	check if we were created by POIFS otherwise create a new dummy POIFS for storing the package data
void	readProperties()	Find, and create objects for, the standard Document Information Properties (HPSF).
void	readProperties(boolean warnIfNull)	Find, and create objects for, the standard Document Information Properties (HPSF).
protected void	replaceDirectory(DirectoryNode newDirectory)	Replaces the attached directory, e.g.
protected void	validateInPlaceWritePossible()	Called during a write() to ensure that the Document (and associated POIFSFileSystem) was opened in a way compatible with an in-place write.
abstract void	write()	Writes the document out to the currently open File, via the writeable POIFSFileSystem it was opened from.
abstract void	write(File newFile)	Writes the document out to the specified new File.
abstract void	write(OutputStream out)	Writes the document out to the specified output stream.
protected void	writeProperties()	Writes out the updated standard Document Information Properties (HPSF) into the currently open POIFSFileSystem
void	writeProperties(POIFSFileSystem outFS)	Writes out the standard Document Information Properties (HPSF)
protected void	writeProperties(POIFSFileSystem outFS, List<String> writtenEntries)	Writes out the standard Document Information Properties (HPSF)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

POIDocument

protected POIDocument(DirectoryNode dir)

Constructs a POIDocument with the given directory node.

Parameters:

dir - The DirectoryNode where information is read from.

POIDocument

protected POIDocument(POIFSFileSystem fs)

Constructs from the default POIFS

Parameters:

fs - the filesystem the document is read from

Method Detail

getDocumentSummaryInformation

public DocumentSummaryInformation getDocumentSummaryInformation()

Fetch the Document Summary Information of the document

Returns:

The Document Summary Information or null if it could not be read for this document.

getSummaryInformation

public SummaryInformation getSummaryInformation()

Fetch the Summary Information of the document

Returns:

The Summary information for the document or null if it could not be read for this document.

createInformationProperties

public void createInformationProperties()

Will create whichever of SummaryInformation and DocumentSummaryInformation (HPSF) properties are not already part of your document. This is normally useful when creating a new document from scratch. If the information properties are already there, then nothing will happen.

readProperties

@Internal
public void readProperties()

Find, and create objects for, the standard Document Information Properties (HPSF). If a given property set is missing or corrupt, it will remain null;

readProperties

@Internal
public void readProperties(boolean warnIfNull)

Find, and create objects for, the standard Document Information Properties (HPSF). If a given property set is missing or corrupt, it will remain null.

Parameters:

warnIfNull - log a warning if any of the property sets come back as null. The directory is null when creating a new document from scratch

getPropertySet

protected PropertySet getPropertySet(String setName)
                              throws IOException

For a given named property entry, either return it or null if if it wasn't found

Parameters:

setName - The property to read

Returns:

The value of the given property or null if it wasn't found.

Throws:

IOException - If retrieving properties fails

getPropertySet

protected PropertySet getPropertySet(String setName,
                                     EncryptionInfo encryptionInfo)
                              throws IOException

For a given named property entry, either return it or null if if it wasn't found

Parameters:

setName - The property to read

encryptionInfo - the encryption descriptor in case of cryptoAPI encryption

Returns:

The value of the given property or null if it wasn't found.

Throws:

IOException - If retrieving properties fails

writeProperties

protected void writeProperties()
                        throws IOException

Writes out the updated standard Document Information Properties (HPSF) into the currently open POIFSFileSystem

Throws:

IOException - if an error when writing to the open POIFSFileSystem occurs

writeProperties

@Internal
public void writeProperties(POIFSFileSystem outFS)
                     throws IOException

Writes out the standard Document Information Properties (HPSF)

Parameters:

outFS - the POIFSFileSystem to write the properties into

Throws:

IOException - if an error when writing to the POIFSFileSystem occurs

writeProperties

protected void writeProperties(POIFSFileSystem outFS,
                               List<String> writtenEntries)
                        throws IOException

Writes out the standard Document Information Properties (HPSF)

Parameters:

outFS - the POIFSFileSystem to write the properties into

writtenEntries - a list of POIFS entries to add the property names too

Throws:

IOException - if an error when writing to the POIFSFileSystem occurs

validateInPlaceWritePossible

protected void validateInPlaceWritePossible()
                                     throws IllegalStateException

Called during a write() to ensure that the Document (and associated POIFSFileSystem) was opened in a way compatible with an in-place write.

Throws:

IllegalStateException - if the document was opened suitably

write

public abstract void write()
                    throws IOException

Writes the document out to the currently open File, via the writeable POIFSFileSystem it was opened from.

This will fail (with an IllegalStateException if the document was opened read-only, opened from an InputStream instead of a File, or if this is not the root document. For those cases, you must use write(OutputStream) or write(File) to write to a brand new document.

Throws:

IOException - thrown on errors writing to the file

IllegalStateException - if this isn't from a writable File

Since:

POI 3.15 beta 3

write

public abstract void write(File newFile)
                    throws IOException

Writes the document out to the specified new File. If the file exists, it will be replaced, otherwise a new one will be created

Parameters:

newFile - The new File to write to.

Throws:

IOException - thrown on errors writing to the file

Since:

POI 3.15 beta 3

write

public abstract void write(OutputStream out)
                    throws IOException

Writes the document out to the specified output stream. The stream is not closed as part of this operation. Note - if the Document was opened from a File rather than an InputStream, you must write out using write() or to a different File. Overwriting the currently open file via an OutputStream isn't possible. If stream is a FileOutputStream on a networked drive or has a high cost/latency associated with each written byte, consider wrapping the OutputStream in a BufferedOutputStream to improve write performance, or use write() / write(File) if possible.

Parameters:

out - The stream to write to.

Throws:

IOException - thrown on errors writing to the stream

close

public void close()
           throws IOException

Closes the underlying POIFSFileSystem from which the document was read, if any. Has no effect on documents opened from an InputStream, or newly created ones.

Once close() has been called, no further operations should be called on the document.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

getDirectory

@Internal
public DirectoryNode getDirectory()

clearDirectory

@Internal
protected void clearDirectory()

Clear/unlink the attached directory entry

initDirectory

@Internal
protected boolean initDirectory()

check if we were created by POIFS otherwise create a new dummy POIFS for storing the package data

Returns:

true if dummy directory was created, false otherwise

replaceDirectory

@Internal
protected void replaceDirectory(DirectoryNode newDirectory)
                         throws IOException

Replaces the attached directory, e.g. if this document is written to a new POIFSFileSystem

Parameters:

newDirectory - the new directory

Throws:

IOException

getEncryptedPropertyStreamName

protected String getEncryptedPropertyStreamName()

Returns:

the stream name of the property set collection, if the document is encrypted

getEncryptionInfo

public EncryptionInfo getEncryptionInfo()
                                 throws IOException

Returns:

the encryption info if the document is encrypted, otherwise null

Throws:

IOException - If retrieving the encryption information fails