org.apache.pdfbox.pdmodel

Class PDDocument

java.lang.Object

org.apache.pdfbox.pdmodel.PDDocument

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

PreflightDocument

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, RandomAccessRead source) Constructor that uses an existing document.
PDDocument(COSDocument doc, RandomAccessRead source, AccessPermission permission) Constructor that uses an existing document.
PDDocument(MemoryUsageSetting memUsageSetting) Creates an empty PDF document.

Method Summary

Modifier and Type	Method and Description
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	addSignatureField(List<PDSignatureField> sigFields, SignatureInterface signatureInterface, SignatureOptions options) This will add a list of signature fields to the document.
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 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.
static PDDocument	load(byte[] input) Parses a PDF.
static PDDocument	load(byte[] input, String password) Parses a PDF.
static PDDocument	load(byte[] input, String password, InputStream keyStore, String alias) Parses a PDF.
static PDDocument	load(byte[] input, String password, InputStream keyStore, String alias, MemoryUsageSetting memUsageSetting) Parses a PDF.
static PDDocument	load(File file) Parses a PDF.
static PDDocument	load(File file, MemoryUsageSetting memUsageSetting) Parses a PDF.
static PDDocument	load(File file, String password) Parses a PDF.
static PDDocument	load(File file, String password, InputStream keyStore, String alias) Parses a PDF.
static PDDocument	load(File file, String password, InputStream keyStore, String alias, MemoryUsageSetting memUsageSetting) Parses a PDF.
static PDDocument	load(File file, String password, MemoryUsageSetting memUsageSetting) Parses a PDF.
static PDDocument	load(InputStream input) Parses a PDF.
static PDDocument	load(InputStream input, MemoryUsageSetting memUsageSetting) Parses a PDF.
static PDDocument	load(InputStream input, String password) Parses a PDF.
static PDDocument	load(InputStream input, String password, InputStream keyStore, String alias) Parses a PDF.
static PDDocument	load(InputStream input, String password, InputStream keyStore, String alias, MemoryUsageSetting memUsageSetting) Parses a PDF.
static PDDocument	load(InputStream input, String password, MemoryUsageSetting memUsageSetting) Parses a PDF.
void	protect(ProtectionPolicy policy) Protects the document with a protection policy.
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.
void	save(OutputStream output) This will save the document to an output stream.
void	save(String fileName) Save the document to a file.
void	saveIncremental(OutputStream output) Save the PDF as an incremental update.
ExternalSigningSupport	saveIncrementalForExternalSigning(OutputStream output) (This is a new feature for 2.0.3.
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(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)
                  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.

Parameters:

sigObject - is the PDSignatureField model

Throws:

IOException - if there is an error creating required 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.

Parameters:

sigObject - is the PDSignatureField model

options - signature options

Throws:

IOException - if there is an error creating required fields

addSignature

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

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

Parameters:

sigObject - is the PDSignatureField model

signatureInterface - is an 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. 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.

Parameters:

sigObject - is the PDSignatureField model

signatureInterface - is an 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 list of signature fields 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.

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. If you need them, call importedPage.setRotation(page.getRotation());

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

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 InvalidPasswordException,
                              IOException

Parses a PDF. Unrestricted main memory will be used for buffering PDF streams.

Parameters:

file - file to be loaded

Returns:

loaded document

Throws:

InvalidPasswordException - If the file required a non-empty password.

IOException - in case of a file reading or parsing error

load

public static PDDocument load(File file,
                              MemoryUsageSetting memUsageSetting)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF.

Parameters:

file - file to be loaded

memUsageSetting - defines how memory is used for buffering PDF streams

Returns:

loaded document

Throws:

InvalidPasswordException - If the file required a non-empty password.

IOException - in case of a file reading or parsing error

load

public static PDDocument load(File file,
                              String password)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF. Unrestricted main memory will be used for buffering PDF streams.

Parameters:

file - file to be loaded

password - password to be used for decryption

Returns:

loaded document

Throws:

InvalidPasswordException - If the password is incorrect.

IOException - in case of a file reading or parsing error

load

public static PDDocument load(File file,
                              String password,
                              MemoryUsageSetting memUsageSetting)
                       throws InvalidPasswordException,
                              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:

InvalidPasswordException - If the password is incorrect.

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. Unrestricted main memory will be used for buffering PDF streams.

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,
                              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 InvalidPasswordException,
                              IOException

Parses a PDF. The given input stream is copied to the memory to enable random access to the pdf. Unrestricted main memory will be used for buffering PDF streams.

Parameters:

input - stream that contains the document.

Returns:

loaded document

Throws:

InvalidPasswordException - If the PDF required a non-empty password.

IOException - In case of a reading or parsing error.

load

public static PDDocument load(InputStream input,
                              MemoryUsageSetting memUsageSetting)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF. Depending on the memory settings parameter the given input stream is either copied to main 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:

InvalidPasswordException - If the PDF required a non-empty password.

IOException - In case of a reading or parsing error.

load

public static PDDocument load(InputStream input,
                              String password)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF. The given input stream is copied to the memory to enable random access to the pdf. Unrestricted main memory will be used for buffering PDF streams.

Parameters:

input - stream that contains the document.

password - password to be used for decryption

Returns:

loaded document

Throws:

InvalidPasswordException - If the password is incorrect.

IOException - In case of a 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. Unrestricted main memory will be used for buffering PDF streams.

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 reading or parsing error.

load

public static PDDocument load(InputStream input,
                              String password,
                              MemoryUsageSetting memUsageSetting)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF. Depending on the memory settings parameter the given input stream is either copied to main 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:

InvalidPasswordException - If the password is incorrect.

IOException - In case of a 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 memory settings parameter the given input stream is either copied to 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:

InvalidPasswordException - If the password is incorrect.

IOException - In case of a reading or parsing error.

load

public static PDDocument load(byte[] input)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF. Unrestricted main memory will be used for buffering PDF streams.

Parameters:

input - byte array that contains the document.

Returns:

loaded document

Throws:

InvalidPasswordException - If the PDF required a non-empty password.

IOException - In case of a reading or parsing error.

load

public static PDDocument load(byte[] input,
                              String password)
                       throws InvalidPasswordException,
                              IOException

Parses a PDF. Unrestricted main memory will be used for buffering PDF streams.

Parameters:

input - byte array that contains the document.

password - password to be used for decryption

Returns:

loaded document

Throws:

InvalidPasswordException - If the password is incorrect.

IOException - In case of a reading or parsing error.

load

public static PDDocument load(byte[] input,
                              String password,
                              InputStream keyStore,
                              String alias)
                       throws IOException

Parses a PDF. Unrestricted main memory will be used for buffering PDF streams.

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:

InvalidPasswordException - If the password is incorrect.

IOException - In case of a reading or parsing error.

load

public static PDDocument load(byte[] input,
                              String password,
                              InputStream keyStore,
                              String alias,
                              MemoryUsageSetting memUsageSetting)
                       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

memUsageSetting - defines how memory is used for buffering input stream and PDF streams

Returns:

loaded document

Throws:

InvalidPasswordException - If the password is incorrect.

IOException - In case of a 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. It will be closed when done. It is recommended to wrap it in a BufferedOutputStream, unless it is already buffered.

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.

Parameters:

output - stream to write to. It will be closed when done. It should not point to the source file.

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

(This is a new feature for 2.0.3. The API for external signing might change based on feedback after release!)

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.

Parameters:

output - stream to write the final PDF. It should not point to the source file. It will be closed when the document is closed.

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

Parameters:

pageIndex - the page index

Returns:

the page at the given index.

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.

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.

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.

Returns:

the resource cache or null.

setResourceCache

public void setResourceCache(ResourceCache resourceCache)

Sets the resource cache associated with this document.

Parameters:

resourceCache - A resource cache, or null.