org.apache.pdfbox.pdmodel

## Class PDDocument

- java.lang.Object
- - org.apache.pdfbox.pdmodel.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.

Author:
  Ben Litchfield

### Constructor Summary

Constructors
Constructor and Description
`PDDocument()` Creates an empty PDF document.
`PDDocument(COSDocument doc)` Constructor that uses an existing document.
`PDDocument(COSDocument doc, org.apache.pdfbox.io.RandomAccessRead source)` Constructor that uses an existing document.
`PDDocument(COSDocument doc, org.apache.pdfbox.io.RandomAccessRead source, AccessPermission permission)` Constructor that uses an existing document.
`PDDocument(org.apache.pdfbox.io.RandomAccessStreamCache.StreamCacheCreateFunction streamCacheCreateFunction)` Creates an empty PDF document.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addPage(PDPage page)` This will add a page to the document.
`void` `addSignature(PDSignature sigObject)` Add parameters of signature to be created externally using default signature options.
`void` `addSignature(PDSignature sigObject, SignatureInterface signatureInterface)` Add a signature to be created using the instance of given interface.
`void` `addSignature(PDSignature sigObject, SignatureInterface signatureInterface, SignatureOptions options)` This will add a signature to the document.
`void` `addSignature(PDSignature sigObject, SignatureOptions options)` Add parameters of signature to be created externally.
`void` `close()` This will close the underlying COSDocument object.
`AccessPermission` `getCurrentAccessPermission()` Returns the access permissions granted when the document was decrypted.
`COSDocument` `getDocument()` This will get the low level document.
`PDDocumentCatalog` `getDocumentCatalog()` This will get the document CATALOG.
`Long` `getDocumentId()` Provides the document ID.
`PDDocumentInformation` `getDocumentInformation()` This will get the document info dictionary.
`PDEncryption` `getEncryption()` This will get the encryption dictionary for this document.
`PDSignature` `getLastSignatureDictionary()` This will return the last signature from the field tree.
`int` `getNumberOfPages()` This will return the total page count of the PDF document.
`PDPage` `getPage(int pageIndex)` Returns the page at the given 0-based index.
`PDPageTree` `getPages()` Returns the page tree.
`ResourceCache` `getResourceCache()` Returns the resource cache associated with this document, or null if there is none.
`List<PDSignature>` `getSignatureDictionaries()` Retrieve all signature dictionaries from the document.
`List<PDSignatureField>` `getSignatureFields()` Retrieve all signature fields from the document.
`float` `getVersion()` Returns the PDF specification version this document conforms to.
`PDPage` `importPage(PDPage page)` This will import and copy the contents from another location.
`boolean` `isAllSecurityToBeRemoved()` Indicates if all security is removed or not when writing the pdf.
`boolean` `isEncrypted()` This will tell if this document is encrypted or not.
`void` `protect(ProtectionPolicy policy)` Protects the document with a protection policy.
`void` `registerTrueTypeFontForClosing(org.apache.fontbox.ttf.TrueTypeFont ttf)` For internal PDFBox use when creating PDF documents: register a TrueTypeFont to make sure it is closed when the PDDocument is closed to avoid memory leaks.
`void` `removePage(int pageNumber)` Remove the page from the document.
`void` `removePage(PDPage page)` Remove the page from the document.
`void` `save(File file)` Save the document to a file using default compression.
`void` `save(File file, CompressParameters compressParameters)` Save the document using the given compression.
`void` `save(OutputStream output)` This will save the document to an output stream.
`void` `save(OutputStream output, CompressParameters compressParameters)` Save the document using the given compression.
`void` `save(String fileName)` Save the document to a file using default compression.
`void` `save(String fileName, CompressParameters compressParameters)` Save the document to a file using the given compression.
`void` `saveIncremental(OutputStream output)` Save the PDF as an incremental update.
`void` `saveIncremental(OutputStream output, Set<COSDictionary> objectsToWrite)` Save the PDF as an incremental update.
`ExternalSigningSupport` `saveIncrementalForExternalSigning(OutputStream output)` Save PDF incrementally without closing for external signature creation scenario.
`void` `setAllSecurityToBeRemoved(boolean removeAllSecurity)` Activates/Deactivates the removal of all security when writing the pdf.
`void` `setDocumentId(Long docId)` Sets the document ID to the given value.
`void` `setDocumentInformation(PDDocumentInformation info)` This will set the document information for this document.
`void` `setEncryptionDictionary(PDEncryption encryption)` This will set the encryption dictionary for this document.
`void` `setResourceCache(ResourceCache resourceCache)` Sets the resource cache associated with this document.
`void` `setVersion(float newVersion)` Sets the PDF specification version for this document.

### Methods inherited from class java.lang.Object

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

### 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(org.apache.pdfbox.io.RandomAccessStreamCache.StreamCacheCreateFunction streamCacheCreateFunction)

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

Parameters:
  `streamCacheCreateFunction` - a function to create an instance of a stream cache 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,
                      org.apache.pdfbox.io.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` - input representing the pdf

#### PDDocument

    public PDDocument(COSDocument doc,
                      org.apache.pdfbox.io.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` - input representing the pdf
  `permission` - the 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)
                      throws IOException

Add parameters of signature to be created externally using default signature options. See `saveIncrementalForExternalSigning(OutputStream)` method description on external signature creation scenario details.

Only one signature may be added in a document. To sign several times, load document, add signature, save incremental and close again.

Parameters:
  `sigObject` - is the PDSignatureField model
Throws:
  `IOException` - if there is an error creating required fields
  `IllegalStateException` - if one attempts to add several signature fields.

#### addSignature

    public void addSignature(PDSignature sigObject,
                             SignatureOptions options)
                      throws IOException

Add parameters of signature to be created externally. See `saveIncrementalForExternalSigning(OutputStream)` method description on external signature creation scenario details.

Only one signature may be added in a document. To sign several times, load document, add signature, save incremental and close again.

Parameters:
  `sigObject` - is the PDSignatureField model
  `options` - signature options
Throws:
  `IOException` - if there is an error creating required fields
  `IllegalStateException` - if one attempts to add several signature fields.

#### addSignature

    public void addSignature(PDSignature sigObject,
                             SignatureInterface signatureInterface)
                      throws IOException

Add a signature to be created using the instance of given interface.

Only one signature may be added in a document. To sign several times, load document, add signature, save incremental and close again.

Parameters:
  `sigObject` - is the PDSignatureField model
  `signatureInterface` - is an interface whose implementation provides signing capabilities. Can be null if external signing if used.
Throws:
  `IOException` - if there is an error creating required fields
  `IllegalStateException` - if one attempts to add several signature fields.

#### addSignature

    public void addSignature(PDSignature sigObject,
                             SignatureInterface signatureInterface,
                             SignatureOptions options)
                      throws IOException

This will add a signature to the document. If the 0-based page number in the options parameter is smaller than 0 or larger than max, the nearest valid page number will be used (i.e. 0 or max) and no exception will be thrown.

Only one signature may be added in a document. To sign several times, load document, add signature, save incremental and close again.

Parameters:
  `sigObject` - is the PDSignatureField model
  `signatureInterface` - is an interface whose implementation provides signing capabilities. Can be null if external signing if used.
  `options` - signature options
Throws:
  `IOException` - if there is an error creating required fields
  `IllegalStateException` - if one attempts to add several signature fields.

#### removePage

    public void removePage(PDPage page)

Remove the page from the document. Do not use this method if other pages link to this one or if your document has a structure tree for accessibility unless you are able to fix these as well. In such cases it is better to use the splitter() class which will do these fixes.

Parameters:
  `page` - The page to remove from the document.

#### removePage

    public void removePage(int pageNumber)

Remove the page from the document. Do not use this method if other pages link to this one or if your document has a structure tree for accessibility unless you are able to fix these as well. In such cases it is better to use the splitter() class which will do these fixes.

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.

Unlike `addPage()`, this method creates a new PDPage object. If your page has annotations, and if these link to pages not in the target document, then the target document might become huge. What you need to do is to delete page references of such annotations. See here for how to do this.

Inherited (global) resources are ignored because these can contain resources not needed for this page which could bloat your document, see PDFBOX-28 and related issues. If you need them, call `importedPage.setResources(page.getResources());`

This method should only be used to import a page from a loaded document, not from a generated document because these can contain unfinished parts, e.g. font subsetting information.

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. If it doesn't exist, an empty document info dictionary is created in the document trailer.

In PDF 2.0 this is deprecated except for two entries, /CreationDate and /ModDate. For any other document level metadata, a metadata stream should be used instead, see `PDDocumentCatalog.getMetadata()`.

Returns:
  The documents /Info dictionary, never null.

#### setDocumentInformation

    public void setDocumentInformation(PDDocumentInformation info)

This will set the document information for this document.

In PDF 2.0 this is deprecated except for two entries, /CreationDate and /ModDate. For any other document level metadata, a metadata stream should be used instead, see `PDDocumentCatalog#setMetadata(PDMetadata)`.

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

This will set the encryption dictionary for this document.

Parameters:
  `encryption` - The encryption dictionary(most likely a PDStandardEncryption object)

#### getLastSignatureDictionary

    public PDSignature getLastSignatureDictionary()

This will return the last signature from the field tree. Note that this may not be the last in time when empty signature fields are created first but signed after other fields.

Returns:
  the last signature as `PDSignatureField`.

#### getSignatureFields

    public List<PDSignatureField> getSignatureFields()

Retrieve all signature fields from the document.

Returns:
  a `List` of `PDSignatureField`s

#### getSignatureDictionaries

    public List<PDSignature> getSignatureDictionaries()

Retrieve all signature dictionaries from the document.

Returns:
  a `List` of `PDSignatureField`s

#### registerTrueTypeFontForClosing

    public void registerTrueTypeFontForClosing(org.apache.fontbox.ttf.TrueTypeFont ttf)

For internal PDFBox use when creating PDF documents: register a TrueTypeFont to make sure it is closed when the PDDocument is closed to avoid memory leaks. Users don't have to call this method, it is done by the appropriate PDFont classes.

Parameters:
  `ttf` - the TrueTypeFont to be registered

#### save

    public void save(String fileName)
              throws IOException

Save the document to a file using default compression.

Don't use the input file as target as this will produce a corrupted file.

If encryption has been activated (with `protect(ProtectionPolicy)`), do not use the document after saving because the contents are now encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

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 using default compression.

Don't use the input file as target as this will produce a corrupted file.

If encryption has been activated (with `protect(ProtectionPolicy)`), do not use the document after saving because the contents are now encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

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.

Don't use the input file as target as this will produce a corrupted file.

If encryption has been activated (with `protect(ProtectionPolicy)`), do not use the document after saving because the contents are now encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

Parameters:
  `output` - The stream to write to. It is recommended to wrap it in a `BufferedOutputStream`, unless it is already buffered.
Throws:
  `IOException` - if the output could not be written

#### save

    public void save(File file,
                     CompressParameters compressParameters)
              throws IOException

Save the document using the given compression.

Don't use the input file as target as this will produce a corrupted file.

If encryption has been activated (with `protect(ProtectionPolicy)`), do not use the document after saving because the contents are now encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

Parameters:
  `file` - The file to save as.
  `compressParameters` - The parameters for the document's compression.
Throws:
  `IOException` - if the output could not be written

#### save

    public void save(String fileName,
                     CompressParameters compressParameters)
              throws IOException

Save the document to a file using the given compression.

Don't use the input file as target as this will produce a corrupted file.

If encryption has been activated (with `protect(ProtectionPolicy)`), do not use the document after saving because the contents are now encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

Parameters:
  `fileName` - The file to save as.
  `compressParameters` - The parameters for the document's compression.
Throws:
  `IOException` - if the output could not be written

#### save

    public void save(OutputStream output,
                     CompressParameters compressParameters)
              throws IOException

Save the document using the given compression.

Don't use the input file as target as this will produce a corrupted file.

If encryption has been activated (with `protect(ProtectionPolicy)`), do not use the document after saving because the contents are now encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

Parameters:
  `output` - The stream to write to. It is recommended to wrap it in a `BufferedOutputStream`, unless it is already buffered.
  `compressParameters` - The parameters for the document's compression.
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 or a stream, not if the document was created in PDFBox itself. There must be a path of objects that have `COSUpdateInfo.isNeedToBeUpdated()` set, starting from the document catalog. For signatures this is taken care by PDFBox itself.

Other usages of this method are for experienced users only. You will usually never need it. It is useful only if you are required to keep the current revision and append the changes. A typical use case is changing a signed file without invalidating the signature.

If your modification includes annotations, make sure these link back to their page by calling `PDAnnotation.setPage(PDPage)`. Although this is optional, not doing it can cause trouble when PDFs get signed. (PDFBox already does this for signature widget annotations)

Another problem with page-based modifications can occur if the page tree isn't flat: there won't be a closed update path from the catalog to the page. To fix this, add code like this:

     COSDictionary parent = page.getCOSObject().getCOSDictionary(COSName.PARENT);
     while (parent != null)
     {
         parent.setNeedToBeUpdated(true);
         parent = parent.getCOSDictionary(COSName.PARENT);
     }

Don't use the input file as target as this will produce a corrupted file.

Parameters:
  `output` - stream to write to. It must never point to the source file or that one will be harmed!
Throws:
  `IOException` - if the output could not be written
  `IllegalStateException` - if the document was not loaded from a file or a stream.

#### saveIncremental

    public void saveIncremental(OutputStream output,
                                Set<COSDictionary> objectsToWrite)
                         throws IOException

Save the PDF as an incremental update. This is only possible if the PDF was loaded from a file or a stream, not if the document was created in PDFBox itself. This allows to include objects even if there is no path of objects that have `COSUpdateInfo.isNeedToBeUpdated()` set so the incremental update gets smaller. Only dictionaries are supported; if you need to update other objects classes, then add their parent dictionary.

This method is for experienced users only. You will usually never need it. It is useful only if you are required to keep the current revision and append the changes. A typical use case is changing a signed file without invalidating the signature. To know which objects are getting changed, you need to have some understanding of the PDF specification, and look at the saved file with an editor to verify that you are updating the correct objects. You should also inspect the page and document structures of the file with PDFDebugger.

If your modification includes annotations, make sure these link back to their page by calling `PDAnnotation.setPage(PDPage)`. Although this is optional, not doing it can cause trouble when PDFs get signed. (PDFBox already does this for signature widget annotations)

Don't use the input file as target as this will produce a corrupted file.

Parameters:
  `output` - stream to write to. It must never point to the source file or that one will be harmed!
  `objectsToWrite` - objects that must be part of the incremental saving.
Throws:
  `IOException` - if the output could not be written
  `IllegalStateException` - if the document was not loaded from a file or a stream.

#### saveIncrementalForExternalSigning

    public ExternalSigningSupport saveIncrementalForExternalSigning(OutputStream output)
                                                             throws IOException

Save PDF incrementally without closing for external signature creation scenario. The general sequence is:

        PDDocument pdDocument = ...;
        OutputStream outputStream = ...;
        SignatureOptions signatureOptions = ...; // options to specify fine tuned signature options or null for defaults
        PDSignature pdSignature = ...;

        // add signature parameters to be used when creating signature dictionary
        pdDocument.addSignature(pdSignature, signatureOptions);
        // prepare PDF for signing and obtain helper class to be used
        ExternalSigningSupport externalSigningSupport = pdDocument.saveIncrementalForExternalSigning(outputStream);
        // get data to be signed
        InputStream dataToBeSigned = externalSigningSupport.getContent();
        // invoke signature service
        byte[] signature = sign(dataToBeSigned);
        // set resulted CMS signature
        externalSigningSupport.setSignature(signature);

        // last step is to close the document
        pdDocument.close();

Note that after calling this method, only `close()` method may invoked for `PDDocument` instance and only AFTER `ExternalSigningSupport` instance is used.

Don't use the input file as target as this will produce a corrupted file.

Parameters:
  `output` - stream to write the final PDF. It must never point to the source file or that one will be harmed!
Returns:
  instance to be used for external signing and setting CMS signature
Throws:
  `IOException` - if the output could not be written
  `IllegalStateException` - if the document was not loaded from a file or a stream or signature options were not set.

#### getPage

    public PDPage getPage(int pageIndex)

Returns the page at the given 0-based index.

This method is too slow to get all the pages from a large PDF document (1000 pages or more). For such documents, use the iterator of `getPages()` instead.

Parameters:
  `pageIndex` - the 0-based page index
Returns:
  the page at the given index.
Throws:
  `IllegalStateException` - if the requested index isn't found or doesn't point to a valid page dictionary.
  `IndexOutOfBoundsException` - if the requested index is higher than the page count.

#### getPages

    public PDPageTree getPages()

Returns the page tree.

Returns:
  the page tree

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

#### close

    public void close()
               throws IOException

This will close the underlying COSDocument object.

Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Throws:
  `IOException` - If there is an error releasing resources.

#### protect

    public void protect(ProtectionPolicy policy)
                 throws IOException

Protects the document with a protection policy. The document content will be really encrypted when it will be saved. This method only marks the document for encryption. It also calls `setAllSecurityToBeRemoved(boolean)` with a false argument if it was set to true previously and logs a warning.

Do not use the document after saving, because the structures are encrypted. The same applies if your file was created from parts of another file and that one is to be used after saving.

Parameters:
  `policy` - The protection policy.
Throws:
  `IOException` - if there isn't any suitable security handler.
See Also:
  `StandardProtectionPolicy`, `PublicKeyProtectionPolicy`

#### 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. This is not the trailer document ID but the time used to create it. Use `COSDocument.getDocumentID()` for the trailer document ID. Read PDFBOX-1613 for more details about the purpose.

Returns:
  the document ID

#### setDocumentId

    public void setDocumentId(Long docId)

Sets the document ID to the given value. This is not the trailer document ID but the time used to create it. Use `COSDocument.setDocumentID(COSArray)` for the trailer document ID. Read PDFBOX-1613 for more details about the purpose.

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.

Returns:
  the resource cache of the document

#### setResourceCache

    public void setResourceCache(ResourceCache resourceCache)

Sets the resource cache associated with this document.

Parameters:
  `resourceCache` - A resource cache, or null.