Package com.tom_roush.pdfbox.pdmodel

Class PDDocument

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    public class PDDocument
extends Object
implements Closeable
    This is the in-memory representation of the PDF document. The #close() method must be called once the document is no longer needed.

    • Constructor Detail

      • PDDocument

        public PDDocument()
        Creates an empty PDF document. You need to add at least one page for the document to be valid.

      • PDDocument

        public PDDocument​(boolean useScratchFiles)
        Creates an empty PDF document. You need to add at least one page for the document to be valid.
        Parameters:
        useScratchFiles - enables the usage of a scratch file if set to true

      • PDDocument

        public PDDocument​(MemoryUsageSetting memUsageSetting)
        Creates an empty PDF document. You need to add at least one page for the document to be valid.
        Parameters:
        memUsageSetting - defines how memory is used for buffering PDF streams

      • PDDocument

        public PDDocument​(COSDocument doc)
        Constructor that uses an existing document. The COSDocument that is passed in must be valid.
        Parameters:
        doc - The COSDocument that this document wraps.

      • PDDocument

        public PDDocument​(COSDocument doc,
                  RandomAccessRead source)
        Constructor that uses an existing document. The COSDocument that is passed in must be valid.
        Parameters:
        doc - The COSDocument that this document wraps.
        source - the parser which is used to read the pdf

      • PDDocument

        public PDDocument​(COSDocument doc,
                  RandomAccessRead source,
                  AccessPermission permission)
        Constructor that uses an existing document. The COSDocument that is passed in must be valid.
        Parameters:
        doc - The COSDocument that this document wraps.
        source - the parser which is used to read the pdf
        permission - he access permissions of the pdf

    • Method Detail

      • addPage

        public void addPage​(PDPage page)
        This will add a page to the document. This is a convenience method, that will add the page to the root of the hierarchy and set the parent of the page to the root.
        Parameters:
        page - The page to add to the document.

      • addSignature

        public void addSignature​(PDSignature sigObject,
                         SignatureInterface signatureInterface)
                  throws IOException
        Add a signature.
        Parameters:
        sigObject - is the PDSignatureField model
        signatureInterface - is a interface which provides signing capabilities
        Throws:
        IOException - if there is an error creating required fields

      • addSignature

        public void addSignature​(PDSignature sigObject,
                         SignatureInterface signatureInterface,
                         SignatureOptions options)
                  throws IOException
        This will add a signature to the document.
        Parameters:
        sigObject - is the PDSignatureField model
        signatureInterface - is a interface which provides signing capabilities
        options - signature options
        Throws:
        IOException - if there is an error creating required fields

      • addSignatureField

        public void addSignatureField​(List<PDSignatureField> sigFields,
                              SignatureInterface signatureInterface,
                              SignatureOptions options)
                       throws IOException
        This will add a signature field to the document.
        Parameters:
        sigFields - are the PDSignatureFields that should be added to the document
        signatureInterface - is a interface which provides signing capabilities
        options - signature options
        Throws:
        IOException - if there is an error creating required fields

      • removePage

        public void removePage​(PDPage page)
        Remove the page from the document.
        Parameters:
        page - The page to remove from the document.

      • removePage

        public void removePage​(int pageNumber)
        Remove the page from the document.
        Parameters:
        pageNumber - 0 based index to page number.

      • importPage

        public PDPage importPage​(PDPage page)
                  throws IOException
        This will import and copy the contents from another location. Currently the content stream is stored in a scratch file. The scratch file is associated with the document. If you are adding a page to this document from another document and want to copy the contents to this document's scratch file then use this method otherwise just use the addPage method.
        Parameters:
        page - The page to import.
        Returns:
        The page that was imported.
        Throws:
        IOException - If there is an error copying the page.

      • getDocument

        public COSDocument getDocument()
        This will get the low level document.
        Returns:
        The document that this layer sits on top of.

      • getDocumentInformation

        public PDDocumentInformation getDocumentInformation()
        This will get the document info dictionary. This is guaranteed to not return null.
        Returns:
        The documents /Info dictionary

      • setDocumentInformation

        public void setDocumentInformation​(PDDocumentInformation info)
        This will set the document information for this document.
        Parameters:
        info - The updated document information.

      • getDocumentCatalog

        public PDDocumentCatalog getDocumentCatalog()
        This will get the document CATALOG. This is guaranteed to not return null.
        Returns:
        The documents /Root dictionary

      • isEncrypted

        public boolean isEncrypted()
        This will tell if this document is encrypted or not.
        Returns:
        true If this document is encrypted.

      • getEncryption

        public PDEncryption getEncryption()
        This will get the encryption dictionary for this document. This will still return the parameters if the document was decrypted. As the encryption architecture in PDF documents is plugable this returns an abstract class, but the only supported subclass at this time is a PDStandardEncryption object.
        Returns:
        The encryption dictionary(most likely a PDStandardEncryption object)

      • setEncryptionDictionary

        public void setEncryptionDictionary​(PDEncryption encryption)
                             throws IOException
        This will set the encryption dictionary for this document.
        Parameters:
        encryption - The encryption dictionary(most likely a PDStandardEncryption object)
        Throws:
        IOException - If there is an error determining which security handler to use.

      • getLastSignatureDictionary

        public PDSignature getLastSignatureDictionary()
                                       throws IOException
        This will return the last signature.
        Returns:
        the last signature as PDSignatureField.
        Throws:
        IOException - if no document catalog can be found.

      • getSignatureFields

        public List<PDSignatureField> getSignatureFields()
                                          throws IOException
        Retrieve all signature fields from the document.
        Returns:
        a List of PDSignatureFields
        Throws:
        IOException - if no document catalog can be found.

      • getSignatureDictionaries

        public List<PDSignature> getSignatureDictionaries()
                                           throws IOException
        Retrieve all signature dictionaries from the document.
        Returns:
        a List of PDSignatureFields
        Throws:
        IOException - if no document catalog can be found.

      • load

        public static PDDocument load​(File file)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              boolean useScratchFiles)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        useScratchFiles - enables the usage of a scratch file if set to true
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              MemoryUsageSetting memUsageSetting)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        memUsageSetting - defines how memory is used for buffering PDF streams
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              String password)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        password - password to be used for decryption
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              String password,
                              boolean useScratchFiles)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        password - password to be used for decryption
        useScratchFiles - enables the usage of a scratch file if set to true
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              String password,
                              MemoryUsageSetting memUsageSetting)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        password - password to be used for decryption
        memUsageSetting - defines how memory is used for buffering PDF streams
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              String password,
                              InputStream keyStore,
                              String alias)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              String password,
                              InputStream keyStore,
                              String alias,
                              boolean useScratchFiles)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        useScratchFiles - enables the usage of a scratch file if set to true
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(File file,
                              String password,
                              InputStream keyStore,
                              String alias,
                              MemoryUsageSetting memUsageSetting)
                       throws IOException
        Parses a PDF.
        Parameters:
        file - file to be loaded
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        memUsageSetting - defines how memory is used for buffering PDF streams
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input)
                       throws IOException
        Parses a PDF. The given input stream is copied to the memory to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              boolean useScratchFiles)
                       throws IOException
        Parses a PDF. Depending on the parameter useScratchFiles the given input stream is either copied to the memory or to a temporary file to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        useScratchFiles - enables the usage of a scratch file if set to true
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              MemoryUsageSetting memUsageSetting)
                       throws IOException
        Parses a PDF. Depending on the parameter useScratchFiles the given input stream is either copied to the memory or to a temporary file to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        memUsageSetting - defines how memory is used for buffering input stream and PDF streams
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              String password)
                       throws IOException
        Parses a PDF. The given input stream is copied to the memory to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        password - password to be used for decryption
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              String password,
                              InputStream keyStore,
                              String alias)
                       throws IOException
        Parses a PDF. The given input stream is copied to the memory to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              String password,
                              boolean useScratchFiles)
                       throws IOException
        Parses a PDF. Depending on the parameter useScratchFiles the given input stream is either copied to the memory or to a temporary file to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        password - password to be used for decryption
        useScratchFiles - enables the usage of a scratch file if set to true
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              String password,
                              MemoryUsageSetting memUsageSetting)
                       throws IOException
        Parses a PDF. Depending on the parameter useScratchFiles the given input stream is either copied to the memory or to a temporary file to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        password - password to be used for decryption
        memUsageSetting - defines how memory is used for buffering input stream and PDF streams
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              String password,
                              InputStream keyStore,
                              String alias,
                              boolean useScratchFiles)
                       throws IOException
        Parses a PDF. Depending on the parameter useScratchFiles the given input stream is either copied to the memory or to a temporary file to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        useScratchFiles - enables the usage of a scratch file if set to true
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(InputStream input,
                              String password,
                              InputStream keyStore,
                              String alias,
                              MemoryUsageSetting memUsageSetting)
                       throws IOException
        Parses a PDF. Depending on the parameter useScratchFiles the given input stream is either copied to the memory or to a temporary file to enable random access to the pdf.
        Parameters:
        input - stream that contains the document.
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        memUsageSetting - defines how memory is used for buffering input stream and PDF streams
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(byte[] input)
                       throws IOException
        Parses a PDF.
        Parameters:
        input - byte array that contains the document.
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(byte[] input,
                              String password)
                       throws IOException
        Parses a PDF.
        Parameters:
        input - byte array that contains the document.
        password - password to be used for decryption
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • load

        public static PDDocument load​(byte[] input,
                              String password,
                              InputStream keyStore,
                              String alias)
                       throws IOException
        Parses a PDF.
        Parameters:
        input - byte array that contains the document.
        password - password to be used for decryption
        keyStore - key store to be used for decryption when using public key security
        alias - alias to be used for decryption when using public key security
        Returns:
        loaded document
        Throws:
        IOException - in case of a file reading or parsing error

      • save

        public void save​(String fileName)
          throws IOException
        Save the document to a file.
        Parameters:
        fileName - The file to save as.
        Throws:
        IOException - if the output could not be written

      • save

        public void save​(File file)
          throws IOException
        Save the document to a file.
        Parameters:
        file - The file to save as.
        Throws:
        IOException - if the output could not be written

      • save

        public void save​(OutputStream output)
          throws IOException
        This will save the document to an output stream.
        Parameters:
        output - The stream to write to.
        Throws:
        IOException - if the output could not be written

      • saveIncremental

        public void saveIncremental​(OutputStream output)
                     throws IOException
        Save the PDF as an incremental update. This is only possible if the PDF was loaded from a file. Use of this method is discouraged, use saveIncremental(OutputStream) instead.
        Parameters:
        output - stream to write
        Throws:
        IOException - if the output could not be written
        IllegalStateException - if the document was not loaded from a file.

      • getPage

        public PDPage getPage​(int pageIndex)
        Returns the page at the given index.
        Parameters:
        pageIndex - the page index
        Returns:
        the page at the given index.

      • getNumberOfPages

        public int getNumberOfPages()
        This will return the total page count of the PDF document.
        Returns:
        The total number of pages in the PDF document.

      • getCurrentAccessPermission

        public AccessPermission getCurrentAccessPermission()
        Returns the access permissions granted when the document was decrypted. If the document was not decrypted this method returns the access permission for a document owner (ie can do everything). The returned object is in read only mode so that permissions cannot be changed. Methods providing access to content should rely on this object to verify if the current user is allowed to proceed.
        Returns:
        the access permissions for the current user on the document.

      • isAllSecurityToBeRemoved

        public boolean isAllSecurityToBeRemoved()
        Indicates if all security is removed or not when writing the pdf.
        Returns:
        returns true if all security shall be removed otherwise false

      • setAllSecurityToBeRemoved

        public void setAllSecurityToBeRemoved​(boolean removeAllSecurity)
        Activates/Deactivates the removal of all security when writing the pdf.
        Parameters:
        removeAllSecurity - remove all security if set to true

      • getDocumentId

        public Long getDocumentId()
        Provides the document ID.
        Returns:
        the dcoument ID

      • setDocumentId

        public void setDocumentId​(Long docId)
        Sets the document ID to the given value.
        Parameters:
        docId - the new document ID

      • getVersion

        public float getVersion()
        Returns the PDF specification version this document conforms to.
        Returns:
        the PDF version (e.g. 1.4f)

      • setVersion

        public void setVersion​(float newVersion)
        Sets the PDF specification version for this document.
        Parameters:
        newVersion - the new PDF version (e.g. 1.4f)

      • getResourceCache

        public ResourceCache getResourceCache()
        Returns the resource cache associated with this document, or null if there is none.

      • setResourceCache

        public void setResourceCache​(ResourceCache resourceCache)
        Sets the resource cache associated with this document.
        Parameters:
        resourceCache - A resource cache, or null.