Package org.apache.pdfbox.multipdf

Class PDFMergerUtility

java.lang.Object

org.apache.pdfbox.multipdf.PDFMergerUtility

public class PDFMergerUtility
extends Object

This class will take a list of pdf documents and merge them, saving the result in a new document.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	PDFMergerUtility.AcroFormMergeMode	The mode to use when merging AcroForm between documents: PDFMergerUtility.AcroFormMergeMode.JOIN_FORM_FIELDS_MODE fields with the same fully qualified name will be merged into one with the widget annotations of the merged fields becoming part of the same field. Although the API is finalized processing of different form field types is still in development. Currently only (nested) text fields do work with intermediate nodes being existent.
static enum	PDFMergerUtility.DocumentMergeMode	The mode to use when merging documents: PDFMergerUtility.DocumentMergeMode.OPTIMIZE_RESOURCES_MODE Optimizes resource handling such as closing documents early.

Field Summary

Fields

Modifier and Type	Field	Description
private PDFMergerUtility.AcroFormMergeMode	acroFormMergeMode
private PDDocumentInformation	destinationDocumentInformation
private String	destinationFileName
private PDMetadata	destinationMetadata
private OutputStream	destinationStream
private PDFMergerUtility.DocumentMergeMode	documentMergeMode
private boolean	ignoreAcroFormErrors
private static final org.apache.commons.logging.Log	LOG	Log instance.
private int	nextFieldNum
private final List<Object>	sources

Constructor Summary

Constructors

Constructor	Description
PDFMergerUtility()	Instantiate a new PDFMergerUtility.

Method Summary

Modifier and Type	Method	Description
private void	acroFormJoinFieldsMode(PDFCloneUtility cloner, PDAcroForm destAcroForm, PDAcroForm srcAcroForm)
private void	acroFormLegacyMode(PDFCloneUtility cloner, PDAcroForm destAcroForm, PDAcroForm srcAcroForm)
void	addSource(File source)	Add a source file to the list of files to merge.
void	addSource(InputStream source)	Add a source to the list of documents to merge.
void	addSource(String source)	Add a source file to the list of files to merge.
void	addSources(List<InputStream> sourcesList)	Add a list of sources to the list of documents to merge.
void	appendDocument(PDDocument destination, PDDocument source)	append all pages from source to destination.
private void	cleanupFieldCOSDictionary(COSDictionary fieldCos)
private void	cleanupWidgetCOSDictionary(COSDictionary widgetCos, boolean removeDAEntry)
PDFMergerUtility.AcroFormMergeMode	getAcroFormMergeMode()	Get the merge mode to be used for merging AcroForms between documents PDFMergerUtility.AcroFormMergeMode
PDDocumentInformation	getDestinationDocumentInformation()	Get the destination document information that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting).
String	getDestinationFileName()	Get the name of the destination file.
PDMetadata	getDestinationMetadata()	Set the destination metadata that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting).
OutputStream	getDestinationStream()	Get the destination OutputStream.
PDFMergerUtility.DocumentMergeMode	getDocumentMergeMode()	Get the merge mode to be used for merging documents PDFMergerUtility.DocumentMergeMode
(package private) static Map<String,PDStructureElement>	getIDTreeAsMap(PDNameTreeNode<PDStructureElement> idTree)
(package private) static Map<Integer,COSObjectable>	getNumberTreeAsMap(PDNumberTreeNode tree)
private boolean	hasOnlyDocumentsOrParts(COSArray kLevelOneArray)
private boolean	isDynamicXfa(PDAcroForm acroForm)	Test for dynamic XFA content.
boolean	isIgnoreAcroFormErrors()	Indicates if acroform errors are ignored or not.
private void	legacyMergeDocuments(MemoryUsageSetting memUsageSetting)	Merge the list of source documents, saving the result in the destination file.
private void	mergeAcroForm(PDFCloneUtility cloner, PDDocumentCatalog destCatalog, PDDocumentCatalog srcCatalog)	Merge the contents of the source form into the destination form for the destination file.
void	mergeDocuments()	Deprecated. use mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting)
void	mergeDocuments(MemoryUsageSetting memUsageSetting)	Merge the list of source documents, saving the result in the destination file.
private void	mergeFields(PDFCloneUtility cloner, PDField destField, PDField srcField)
private void	mergeIDTree(PDFCloneUtility cloner, PDStructureTreeRoot srcStructTree, PDStructureTreeRoot destStructTree)
private void	mergeInto(COSDictionary src, COSDictionary dst, Set<COSName> exclude)	This will add all of the dictionaries keys/values to this dictionary, but only if they are not in an exclusion list and if they don't already exist.
private void	mergeKEntries(PDFCloneUtility cloner, PDStructureTreeRoot srcStructTree, PDStructureTreeRoot destStructTree)
private void	mergeLanguage(PDDocumentCatalog destCatalog, PDDocumentCatalog srcCatalog)
private void	mergeMarkInfo(PDDocumentCatalog destCatalog, PDDocumentCatalog srcCatalog)
private void	mergeOutputIntents(PDFCloneUtility cloner, PDDocumentCatalog srcCatalog, PDDocumentCatalog destCatalog)
private void	mergeRoleMap(PDStructureTreeRoot srcStructTree, PDStructureTreeRoot destStructTree)
private void	mergeViewerPreferences(PDDocumentCatalog destCatalog, PDDocumentCatalog srcCatalog)
private void	optimizedMergeDocuments(MemoryUsageSetting memUsageSetting)
void	setAcroFormMergeMode(PDFMergerUtility.AcroFormMergeMode theAcroFormMergeMode)	Set the merge mode to be used for merging AcroForms between documents PDFMergerUtility.AcroFormMergeMode
void	setDestinationDocumentInformation(PDDocumentInformation info)	Set the destination document information that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting).
void	setDestinationFileName(String destination)	Set the name of the destination file.
void	setDestinationMetadata(PDMetadata meta)	Set the destination metadata that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting).
void	setDestinationStream(OutputStream destStream)	Set the destination OutputStream.
void	setDocumentMergeMode(PDFMergerUtility.DocumentMergeMode theDocumentMergeMode)	Set the merge mode to be used for merging documents PDFMergerUtility.DocumentMergeMode
void	setIgnoreAcroFormErrors(boolean ignoreAcroFormErrorsValue)	Set to true to ignore acroform errors.
private void	updatePageReferences(PDFCloneUtility cloner, Map<Integer,COSObjectable> numberTreeAsMap, Map<COSDictionary,COSDictionary> objMapping)	Update the Pg and Obj references to the new (merged) page.
private void	updatePageReferences(PDFCloneUtility cloner, COSArray parentTreeEntry, Map<COSDictionary,COSDictionary> objMapping)
private void	updatePageReferences(PDFCloneUtility cloner, COSDictionary parentTreeEntry, Map<COSDictionary,COSDictionary> objMapping)	Update the Pg and Obj references to the new (merged) page.
private void	updateParentEntry(COSArray kArray, COSDictionary newParent, COSName newStructureType)	Update the P reference to the new parent dictionary.
private void	updateStructParentEntries(PDPage page, int structParentOffset)	Update the StructParents and StructParent values in a PDPage.

Methods inherited from class java.lang.Object

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

Field Details

LOG

private static final org.apache.commons.logging.Log LOG

Log instance.

sources

private final List<Object> sources

destinationFileName

private String destinationFileName

destinationStream

private OutputStream destinationStream

ignoreAcroFormErrors

private boolean ignoreAcroFormErrors

destinationDocumentInformation

private PDDocumentInformation destinationDocumentInformation

destinationMetadata

private PDMetadata destinationMetadata

documentMergeMode

private PDFMergerUtility.DocumentMergeMode documentMergeMode

acroFormMergeMode

private PDFMergerUtility.AcroFormMergeMode acroFormMergeMode

nextFieldNum

private int nextFieldNum

Constructor Details

PDFMergerUtility

public PDFMergerUtility()

Instantiate a new PDFMergerUtility.

Method Details

getAcroFormMergeMode

public PDFMergerUtility.AcroFormMergeMode getAcroFormMergeMode()

Get the merge mode to be used for merging AcroForms between documents PDFMergerUtility.AcroFormMergeMode

setAcroFormMergeMode

public void setAcroFormMergeMode(PDFMergerUtility.AcroFormMergeMode theAcroFormMergeMode)

Set the merge mode to be used for merging AcroForms between documents PDFMergerUtility.AcroFormMergeMode

setDocumentMergeMode

public void setDocumentMergeMode(PDFMergerUtility.DocumentMergeMode theDocumentMergeMode)

Set the merge mode to be used for merging documents PDFMergerUtility.DocumentMergeMode

getDocumentMergeMode

public PDFMergerUtility.DocumentMergeMode getDocumentMergeMode()

Get the merge mode to be used for merging documents PDFMergerUtility.DocumentMergeMode

getDestinationFileName

public String getDestinationFileName()

Get the name of the destination file.

Returns:

Returns the destination.

setDestinationFileName

public void setDestinationFileName(String destination)

Set the name of the destination file.

Parameters:

destination - The destination to set.

getDestinationStream

public OutputStream getDestinationStream()

Get the destination OutputStream.

Returns:

Returns the destination OutputStream.

setDestinationStream

public void setDestinationStream(OutputStream destStream)

Set the destination OutputStream.

Parameters:

destStream - The destination to set.

getDestinationDocumentInformation

public PDDocumentInformation getDestinationDocumentInformation()

Get the destination document information that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting). The default is null, which means that it is ignored.

Returns:

The destination document information.

setDestinationDocumentInformation

public void setDestinationDocumentInformation(PDDocumentInformation info)

Set the destination document information that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting). The default is null, which means that it is ignored.

Parameters:

info - The destination document information.

getDestinationMetadata

public PDMetadata getDestinationMetadata()

Set the destination metadata that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting). The default is null, which means that it is ignored.

Returns:

The destination metadata.

setDestinationMetadata

public void setDestinationMetadata(PDMetadata meta)

Set the destination metadata that is to be set in mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting). The default is null, which means that it is ignored.

Parameters:

meta - The destination metadata.

addSource

public void addSource(String source)
               throws FileNotFoundException

Add a source file to the list of files to merge.

Parameters:

source - Full path and file name of source document.

Throws:

FileNotFoundException - If the file doesn't exist

addSource

public void addSource(File source)
               throws FileNotFoundException

Add a source file to the list of files to merge.

Parameters:

source - File representing source document

Throws:

FileNotFoundException - If the file doesn't exist

addSource

public void addSource(InputStream source)

Add a source to the list of documents to merge.

Parameters:

source - InputStream representing source document

addSources

public void addSources(List<InputStream> sourcesList)

Add a list of sources to the list of documents to merge.

Parameters:

sourcesList - List of InputStream objects representing source documents

mergeDocuments

@Deprecated
public void mergeDocuments()
                    throws IOException

Deprecated.

use mergeDocuments(org.apache.pdfbox.io.MemoryUsageSetting)

Merge the list of source documents, saving the result in the destination file.

Throws:

IOException - If there is an error saving the document.

mergeDocuments

public void mergeDocuments(MemoryUsageSetting memUsageSetting)
                    throws IOException

Merge the list of source documents, saving the result in the destination file. The source list is not reset after merge. If you want to merge one document at a time, then it's better to use appendDocument(org.apache.pdfbox.pdmodel.PDDocument, org.apache.pdfbox.pdmodel.PDDocument).

Parameters:

memUsageSetting - defines how memory is used for buffering PDF streams; in case of null unrestricted main memory is used

Throws:

IOException - If there is an error saving the document.

optimizedMergeDocuments

private void optimizedMergeDocuments(MemoryUsageSetting memUsageSetting)
                              throws IOException

Throws:

IOException

legacyMergeDocuments

private void legacyMergeDocuments(MemoryUsageSetting memUsageSetting)
                           throws IOException

Merge the list of source documents, saving the result in the destination file.

Parameters:

memUsageSetting - defines how memory is used for buffering PDF streams; in case of null unrestricted main memory is used

Throws:

IOException - If there is an error saving the document.

appendDocument

public void appendDocument(PDDocument destination,
 PDDocument source)
                    throws IOException

append all pages from source to destination.

Parameters:

destination - the document to receive the pages

source - the document originating the new pages

Throws:

IOException - If there is an error accessing data from either document.

mergeViewerPreferences

private void mergeViewerPreferences(PDDocumentCatalog destCatalog,
 PDDocumentCatalog srcCatalog)

mergeLanguage

private void mergeLanguage(PDDocumentCatalog destCatalog,
 PDDocumentCatalog srcCatalog)

mergeMarkInfo

private void mergeMarkInfo(PDDocumentCatalog destCatalog,
 PDDocumentCatalog srcCatalog)

mergeKEntries

private void mergeKEntries(PDFCloneUtility cloner,
 PDStructureTreeRoot srcStructTree,
 PDStructureTreeRoot destStructTree)
                    throws IOException

Throws:

IOException

hasOnlyDocumentsOrParts

private boolean hasOnlyDocumentsOrParts(COSArray kLevelOneArray)

updateParentEntry

private void updateParentEntry(COSArray kArray,
 COSDictionary newParent,
 COSName newStructureType)

Update the P reference to the new parent dictionary.

Parameters:

kArray - the kids array

newParent - the new parent

newStructureType - the new structure type in /S or null so it doesn't get replaced

mergeIDTree

private void mergeIDTree(PDFCloneUtility cloner,
 PDStructureTreeRoot srcStructTree,
 PDStructureTreeRoot destStructTree)
                  throws IOException

Throws:

IOException

getIDTreeAsMap

static Map<String,PDStructureElement> getIDTreeAsMap(PDNameTreeNode<PDStructureElement> idTree)
                                              throws IOException

Throws:

IOException

getNumberTreeAsMap

static Map<Integer,COSObjectable> getNumberTreeAsMap(PDNumberTreeNode tree)
                                              throws IOException

Throws:

IOException

mergeRoleMap

private void mergeRoleMap(PDStructureTreeRoot srcStructTree,
 PDStructureTreeRoot destStructTree)

mergeOutputIntents

private void mergeOutputIntents(PDFCloneUtility cloner,
 PDDocumentCatalog srcCatalog,
 PDDocumentCatalog destCatalog)
                         throws IOException

Throws:

IOException

mergeAcroForm

private void mergeAcroForm(PDFCloneUtility cloner,
 PDDocumentCatalog destCatalog,
 PDDocumentCatalog srcCatalog)
                    throws IOException

Merge the contents of the source form into the destination form for the destination file.

Parameters:

cloner - the object cloner for the destination document

destAcroForm - the destination form

srcAcroForm - the source form

Throws:

IOException - If an error occurs while adding the field.

acroFormJoinFieldsMode

private void acroFormJoinFieldsMode(PDFCloneUtility cloner,
 PDAcroForm destAcroForm,
 PDAcroForm srcAcroForm)
                             throws IOException

Throws:

IOException

mergeFields

private void mergeFields(PDFCloneUtility cloner,
 PDField destField,
 PDField srcField)

cleanupFieldCOSDictionary

private void cleanupFieldCOSDictionary(COSDictionary fieldCos)

cleanupWidgetCOSDictionary

private void cleanupWidgetCOSDictionary(COSDictionary widgetCos,
 boolean removeDAEntry)

acroFormLegacyMode

private void acroFormLegacyMode(PDFCloneUtility cloner,
 PDAcroForm destAcroForm,
 PDAcroForm srcAcroForm)
                         throws IOException

Throws:

IOException

isIgnoreAcroFormErrors

public boolean isIgnoreAcroFormErrors()

Indicates if acroform errors are ignored or not.

Returns:

true if acroform errors are ignored

setIgnoreAcroFormErrors

public void setIgnoreAcroFormErrors(boolean ignoreAcroFormErrorsValue)

Set to true to ignore acroform errors.

Parameters:

ignoreAcroFormErrorsValue - true if acroform errors should be ignored

updatePageReferences

private void updatePageReferences(PDFCloneUtility cloner,
 Map<Integer,COSObjectable> numberTreeAsMap,
 Map<COSDictionary,COSDictionary> objMapping)
                           throws IOException

Update the Pg and Obj references to the new (merged) page.

Throws:

IOException

updatePageReferences

private void updatePageReferences(PDFCloneUtility cloner,
 COSDictionary parentTreeEntry,
 Map<COSDictionary,COSDictionary> objMapping)
                           throws IOException

Update the Pg and Obj references to the new (merged) page.

Parameters:

parentTreeEntry -

objMapping - mapping between old and new references

Throws:

IOException

updatePageReferences

private void updatePageReferences(PDFCloneUtility cloner,
 COSArray parentTreeEntry,
 Map<COSDictionary,COSDictionary> objMapping)
                           throws IOException

Throws:

IOException

updateStructParentEntries

private void updateStructParentEntries(PDPage page,
 int structParentOffset)
                                throws IOException

Update the StructParents and StructParent values in a PDPage.

Parameters:

page - the new page

structParentOffset - the offset which should be applied

Throws:

IOException

isDynamicXfa

private boolean isDynamicXfa(PDAcroForm acroForm)

Test for dynamic XFA content.

Parameters:

acroForm - the AcroForm

Returns:

true if there is a dynamic XFA form.

mergeInto

private void mergeInto(COSDictionary src,
 COSDictionary dst,
 Set<COSName> exclude)

This will add all of the dictionaries keys/values to this dictionary, but only if they are not in an exclusion list and if they don't already exist. If a key already exists in this dictionary then nothing is changed.

Parameters:

src - The source dictionary to get the keys/values from.

dst - The destination dictionary to merge the keys/values into.

exclude - Names of keys that shall be skipped.