Apache POI - Common 5.3.0 · org.apache.poi.POIDocument

Modifier and Type	Field and Description
private DirectoryNode	directory The directory that our document lives in
private DocumentSummaryInformation	dsInf Holds further metadata on our document
private boolean	initialized
private static final Logger	LOG For our own logging use
private SummaryInformation	sInf Holds metadata on our document

Access	Constructor and Description
protected	POIDocument(DirectoryNode The `DirectoryNode` where information is read from. dir) Constructs a POIDocument with the given directory node.
protected	POIDocument(POIFSFileSystem the filesystem the document is read from fs) Constructs from the default POIFS

Method Summary

Modifier and Type	Method and Description
protected void	clearDirectory() Clear/unlink the attached directory entry
public void	close() Implements java.io.Closeable.close. Closes the underlying `POIFSFileSystem` from which the document was read, if any.
public void	createInformationProperties() Will create whichever of SummaryInformation and DocumentSummaryInformation (HPSF) properties are not already part of your document.
public DirectoryNode	getDirectory()
public DocumentSummaryInformation	Returns: The Document Summary Information or null if it could not be read for this document. getDocumentSummaryInformation() Fetch the Document Summary Information of the document
protected String	Returns: the stream name of the property set collection, if the document is encrypted getEncryptedPropertyStreamName()
public EncryptionInfo	Returns: the encryption info if the document is encrypted, otherwise `null` getEncryptionInfo()
protected PropertySet	Returns: The value of the given property or null if it wasn't found. getPropertySet(String The property to read setName) For a given named property entry, either return it or null if if it wasn't found
protected PropertySet	Returns: The value of the given property or null if it wasn't found. getPropertySet(String The property to read setName, EncryptionInfo the encryption descriptor in case of cryptoAPI encryption encryptionInfo) For a given named property entry, either return it or null if if it wasn't found
public SummaryInformation	Returns: The Summary information for the document or null if it could not be read for this document. getSummaryInformation() Fetch the Summary Information of the document
protected boolean	Returns: `true` if dummy directory was created, `false` otherwise initDirectory() check if we were created by POIFS otherwise create a new dummy POIFS for storing the package data
public void	readProperties() Find, and create objects for, the standard Document Information Properties (HPSF).
public void	readProperties(boolean log a warning if any of the property sets come back as null. The directory is null when creating a new document from scratch warnIfNull) Find, and create objects for, the standard Document Information Properties (HPSF).
private <T> T	readPropertySet(Class<T> clazz, String name, boolean warnIfNull)
protected void	replaceDirectory(DirectoryNode the new directory newDirectory) Replaces the attached directory, e.g. if this document is written to a new POIFSFileSystem
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.
public abstract void	write() Writes the document out to the currently open `File`, via the writeable `POIFSFileSystem` it was opened from.
public abstract void	write(File The new File to write to. newFile) Writes the document out to the specified new `File`.
public abstract void	write(OutputStream The stream to write to. 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
public void	writeProperties(POIFSFileSystem the POIFSFileSystem to write the properties into outFS) Writes out the standard Document Information Properties (HPSF)
protected void	writeProperties(POIFSFileSystem the `POIFSFileSystem` to write the properties into outFS, List<String> a list of POIFS entries to add the property names too writtenEntries) Writes out the standard Document Information Properties (HPSF)
private void	writePropertySet(String name, PropertySet ps, POIFSFileSystem outFS, List<String> writtenEntries)
private void	writePropertySet(String the (POIFS Level) name of the property to write name, PropertySet the PropertySet to write out set, POIFSFileSystem the `POIFSFileSystem` to write the property into outFS) Writes out a given PropertySet

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

directory	back to summary
private DirectoryNode directory The directory that our document lives in

dsInf	back to summary
private DocumentSummaryInformation dsInf Holds further metadata on our document

initialized	back to summary
private boolean initialized

LOG	back to summary
private static final Logger LOG For our own logging use

sInf	back to summary
private SummaryInformation sInf Holds metadata on our document

POIDocument	back to summary
protected POIDocument(DirectoryNode dir) Constructs a POIDocument with the given directory node. Parameters dir:DirectoryNode The `DirectoryNode` where information is read from.

POIDocument	back to summary
protected POIDocument(POIFSFileSystem fs) Constructs from the default POIFS Parameters fs:POIFSFileSystem the filesystem the document is read from

Method Detail

clearDirectory	back to summary
protected void clearDirectory() Clear/unlink the attached directory entry Annotations @Internal

clearDirectory

back to summary

protected void clearDirectory()

Clear/unlink the attached directory entry

Annotations

@Internal

close back to summary

close	back to summary
public void close() throws IOException Implements java.io.Closeable.close. 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. Annotations @Override Exceptions IOException: Doc from java.io.Closeable.close. if an I/O error occurs

public void close() throws IOException

Implements java.io.Closeable.close.

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.

Annotations

@Override

Exceptions

IOException:

Doc from java.io.Closeable.close.

if an I/O error occurs

createInformationProperties	back to summary
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.

getDirectory	back to summary
public DirectoryNode getDirectory() Annotations @Internal

getDocumentSummaryInformation	back to summary
public DocumentSummaryInformation getDocumentSummaryInformation() Fetch the Document Summary Information of the document Returns:DocumentSummaryInformation The Document Summary Information or null if it could not be read for this document.

getDocumentSummaryInformation

back to summary

public DocumentSummaryInformation getDocumentSummaryInformation()

Fetch the Document Summary Information of the document

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

getEncryptedPropertyStreamName	back to summary
protected String getEncryptedPropertyStreamName() Returns:String the stream name of the property set collection, if the document is encrypted

getEncryptionInfo	back to summary
public EncryptionInfo getEncryptionInfo() throws IOException Returns:EncryptionInfo the encryption info if the document is encrypted, otherwise `null` Exceptions IOException: If retrieving the encryption information fails

getPropertySet	back to summary
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:String The property to read Returns:PropertySet The value of the given property or null if it wasn't found. Annotations @SuppressWarnings:WeakerAccess Exceptions IOException: If retrieving properties fails

getPropertySet

back to summary

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:String: The property to read

Returns:PropertySet

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

Annotations

@SuppressWarnings:WeakerAccess

Exceptions

IOException:: If retrieving properties fails

getPropertySet	back to summary
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:String The property to read encryptionInfo:EncryptionInfo the encryption descriptor in case of cryptoAPI encryption Returns:PropertySet The value of the given property or null if it wasn't found. Annotations @SuppressWarnings:WeakerAccess Exceptions IOException: If retrieving properties fails

getPropertySet

back to summary

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:String: The property to read
encryptionInfo:EncryptionInfo: the encryption descriptor in case of cryptoAPI encryption

Returns:PropertySet

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

Annotations

@SuppressWarnings:WeakerAccess

Exceptions

IOException:: If retrieving properties fails

getSummaryInformation	back to summary
public SummaryInformation getSummaryInformation() Fetch the Summary Information of the document Returns:SummaryInformation The Summary information for the document or null if it could not be read for this document.

getSummaryInformation

back to summary

public SummaryInformation getSummaryInformation()

Fetch the Summary Information of the document

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

initDirectory back to summary

initDirectory	back to summary
protected boolean initDirectory() check if we were created by POIFS otherwise create a new dummy POIFS for storing the package data Returns:boolean `true` if dummy directory was created, `false` otherwise Annotations @SuppressWarnings:resource @Internal

protected boolean initDirectory()

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

Returns:boolean

true if dummy directory was created, false otherwise

Annotations

@SuppressWarnings:resource
@Internal

readProperties	back to summary
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; Annotations @Internal

readProperties

back to summary

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;

Annotations

@Internal

readProperties	back to summary
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:boolean log a warning if any of the property sets come back as null. The directory is null when creating a new document from scratch Annotations @Internal

readProperties

back to summary

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:boolean: log a warning if any of the property sets come back as null. The directory is null when creating a new document from scratch

Annotations

@Internal

readPropertySet	back to summary
private <T> T readPropertySet(Class<T> clazz, String name, boolean warnIfNull) Annotations @SuppressWarnings:unchecked

replaceDirectory	back to summary
protected void replaceDirectory(DirectoryNode newDirectory) throws IOException Replaces the attached directory, e.g. if this document is written to a new POIFSFileSystem Parameters newDirectory:DirectoryNode the new directory Annotations @Internal

replaceDirectory

back to summary

protected void replaceDirectory(DirectoryNode newDirectory) throws IOException

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

Parameters

newDirectory:DirectoryNode: the new directory

Annotations

@Internal

validateInPlaceWritePossible back to summary

validateInPlaceWritePossible	back to summary
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. Exceptions IllegalStateException: if the document was opened suitably

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.

Exceptions

IllegalStateException:: if the document was opened suitably

write back to summary

write	back to summary
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. Exceptions IOException: thrown on errors writing to the file IllegalStateException: if this isn't from a writable File Since POI 3.15 beta 3

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.

Exceptions

IOException:: thrown on errors writing to the file
IllegalStateException:: if this isn't from a writable File

Since

POI 3.15 beta 3

write back to summary

write	back to summary
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:File The new File to write to. Exceptions IOException: thrown on errors writing to the file Since POI 3.15 beta 3

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:File: The new File to write to.

Exceptions

IOException:: thrown on errors writing to the file

Since

POI 3.15 beta 3

write back to summary

write	back to summary
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:OutputStream The stream to write to. Exceptions IOException: thrown on errors writing to the stream

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:OutputStream: The stream to write to.

Exceptions

IOException:: thrown on errors writing to the stream

writeProperties back to summary

writeProperties	back to summary
protected void writeProperties() throws IOException Writes out the updated standard Document Information Properties (HPSF) into the currently open POIFSFileSystem Exceptions IOException: if an error when writing to the open `POIFSFileSystem` occurs

protected void writeProperties() throws IOException

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

Exceptions

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

writeProperties back to summary

writeProperties	back to summary
public void writeProperties(POIFSFileSystem outFS) throws IOException Writes out the standard Document Information Properties (HPSF) Parameters outFS:POIFSFileSystem the POIFSFileSystem to write the properties into Annotations @Internal Exceptions IOException: if an error when writing to the `POIFSFileSystem` occurs

public void writeProperties(POIFSFileSystem outFS) throws IOException

Writes out the standard Document Information Properties (HPSF)

Parameters

outFS:POIFSFileSystem: the POIFSFileSystem to write the properties into

Annotations

@Internal

Exceptions

IOException:: if an error when writing to the POIFSFileSystem occurs

writeProperties back to summary

writeProperties	back to summary
protected void writeProperties(POIFSFileSystem outFS, List<String> writtenEntries) throws IOException Writes out the standard Document Information Properties (HPSF) Parameters outFS:POIFSFileSystem the `POIFSFileSystem` to write the properties into writtenEntries:List<String> a list of POIFS entries to add the property names too Exceptions IOException: if an error when writing to the `POIFSFileSystem` occurs

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

Writes out the standard Document Information Properties (HPSF)

Parameters

outFS:POIFSFileSystem: the POIFSFileSystem to write the properties into
writtenEntries:List<String>: a list of POIFS entries to add the property names too

Exceptions

IOException:: if an error when writing to the POIFSFileSystem occurs

writePropertySet	back to summary
private void writePropertySet(String name, PropertySet ps, POIFSFileSystem outFS, List<String> writtenEntries) throws IOException

writePropertySet back to summary

writePropertySet	back to summary
private void writePropertySet(String name, PropertySet set, POIFSFileSystem outFS) throws IOException Writes out a given PropertySet Parameters name:String the (POIFS Level) name of the property to write set:PropertySet the PropertySet to write out outFS:POIFSFileSystem the `POIFSFileSystem` to write the property into Exceptions IOException: if an error when writing to the `POIFSFileSystem` occurs

private void writePropertySet(String name, PropertySet set, POIFSFileSystem outFS) throws IOException

Writes out a given PropertySet

Parameters

name:String: the (POIFS Level) name of the property to write
set:PropertySet: the PropertySet to write out
outFS:POIFSFileSystem: the POIFSFileSystem to write the property into

Exceptions

IOException:: if an error when writing to the POIFSFileSystem occurs

public abstract Class POIDocument

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail