org.apache.poi

## Class POIDocument

- java.lang.Object
- - org.apache.poi.POIDocument

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
  Direct Known Subclasses:
    HPSFPropertiesOnlyDocument, HSLFSlideShowImpl, HSSFWorkbook, HWPFDocumentCore, POIReadOnlyDocument

      public abstract class POIDocument
      extends java.lang.Object
      implements java.io.Closeable

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

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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 java.lang.String` | `getEncryptedPropertyStreamName()`
    `EncryptionInfo` | `getEncryptionInfo()`
    `protected PropertySet` | `getPropertySet(java.lang.String setName)` For a given named property entry, either return it or null if if it wasn't found
    `protected PropertySet` | `getPropertySet(java.lang.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
    `protected void` | `readProperties()` 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(java.io.File newFile)` Writes the document out to the specified new `File`.
    `abstract void` | `write(java.io.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
    `protected void` | `writeProperties(POIFSFileSystem outFS)` Writes out the standard Document Information Properties (HPSF)
    `protected void` | `writeProperties(POIFSFileSystem outFS, java.util.List<java.lang.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

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

    - #### getPropertySet

          protected PropertySet getPropertySet(java.lang.String setName)
                                        throws java.io.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:
        `java.io.IOException` - If retrieving properties fails

    - #### getPropertySet

          protected PropertySet getPropertySet(java.lang.String setName,
                                               EncryptionInfo encryptionInfo)
                                        throws java.io.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:
        `java.io.IOException` - If retrieving properties fails

    - #### writeProperties

          protected void writeProperties()
                                  throws java.io.IOException

      Writes out the updated standard Document Information Properties (HPSF) into the currently open POIFSFileSystem
      Throws:
        `java.io.IOException` - if an error when writing to the open `POIFSFileSystem` occurs

    - #### writeProperties

          protected void writeProperties(POIFSFileSystem outFS)
                                  throws java.io.IOException

      Writes out the standard Document Information Properties (HPSF)
      Parameters:
        `outFS` - the POIFSFileSystem to write the properties into
      Throws:
        `java.io.IOException` - if an error when writing to the `POIFSFileSystem` occurs

    - #### writeProperties

          protected void writeProperties(POIFSFileSystem outFS,
                                         java.util.List<java.lang.String> writtenEntries)
                                  throws java.io.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:
        `java.io.IOException` - if an error when writing to the `POIFSFileSystem` occurs

    - #### validateInPlaceWritePossible

          protected void validateInPlaceWritePossible()
                                               throws java.lang.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:
        `java.lang.IllegalStateException` - if the document was opened suitably

    - #### write

          public abstract void write()
                              throws java.io.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:
        `java.io.IOException` - thrown on errors writing to the file
        `java.lang.IllegalStateException` - if this isn't from a writable File
      Since:
        POI 3.15 beta 3

    - #### write

          public abstract void write(java.io.File newFile)
                              throws java.io.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:
        `java.io.IOException` - thrown on errors writing to the file
      Since:
        POI 3.15 beta 3

    - #### write

          public abstract void write(java.io.OutputStream out)
                              throws java.io.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:
        `java.io.IOException` - thrown on errors writing to the stream

    - #### close

          public void close()
                     throws java.io.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 `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.io.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)

      Replaces the attached directory, e.g. if this document is written to a new POIFSFileSystem
      Parameters:
        `newDirectory` - the new directory

    - #### getEncryptedPropertyStreamName

          protected java.lang.String getEncryptedPropertyStreamName()

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

    - #### getEncryptionInfo

          public EncryptionInfo getEncryptionInfo()
                                           throws java.io.IOException

      Returns:
        the encryption info if the document is encrypted, otherwise `null`
      Throws:
        `java.io.IOException` - If retrieving the encryption information fails

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