com.itextpdf.kernel.utils

Class CompareTool

java.lang.Object

com.itextpdf.kernel.utils.CompareTool

public class CompareTool
extends Object

This class provides means to compare two PDF files both by content and visually and gives the report of their differences.

For visual comparison it uses external tools: Ghostscript and ImageMagick, which should be installed on your machine. To allow CompareTool to use them, you need to pass either java properties or environment variables with names "gsExec" and "compareExec", which would contain the paths to the executables of correspondingly Ghostscript and ImageMagick tools.

CompareTool class was mainly designed for the testing purposes of iText in order to ensure that the same code produces the same PDF document. For this reason you will often encounter such parameter names as "outDoc" and "cmpDoc" which stand for output document and document-for-comparison. The first one is viewed as the current result, and the second one is referred as normal or ideal result. OutDoc is compared to the ideal cmpDoc. Therefore all reports of the comparison are in the form: "Expected ..., but was ...". This should be interpreted in the following way: "expected" part stands for the content of the cmpDoc and "but was" part stands for the content of the outDoc.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	CompareTool.CompareResult Class containing results of the comparison of two documents.
class	CompareTool.CompareToolExecutionException
class	CompareTool.ObjectPath Class that helps to find two corresponding objects in the comparing documents and also keeps track of the already met in comparing process parent indirect objects.

Constructor Summary

Constructors

Constructor and Description
CompareTool() Creates an instance of the CompareTool.

Method Summary

Modifier and Type	Method and Description
boolean	compareArrays(PdfArray outArray, PdfArray cmpArray) Simple method that compares two given PdfArrays by content.
boolean	compareBooleans(PdfBoolean outBoolean, PdfBoolean cmpBoolean) Simple method that compares two given PdfBooleans.
CompareTool.CompareResult	compareByCatalog(PdfDocument outDocument, PdfDocument cmpDocument) Compares two PDF documents by content starting from Catalog dictionary and then recursively comparing corresponding objects which are referenced from it.
String	compareByContent(String outPdf, String cmpPdf, String outPath, String differenceImagePrefix) Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them.
String	compareByContent(String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, byte[] outPass, byte[] cmpPass) This method overload is used to compare two encrypted PDF documents.
String	compareByContent(String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, Map<Integer,List<Rectangle>> ignoredAreas) Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them.
String	compareByContent(String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, Map<Integer,List<Rectangle>> ignoredAreas, byte[] outPass, byte[] cmpPass) This method overload is used to compare two encrypted PDF documents.
boolean	compareDictionaries(PdfDictionary outDict, PdfDictionary cmpDict) Simple method that compares two given PdfDictionaries by content.
String	compareDocumentInfo(String outPdf, String cmpPdf) Compares document info dictionaries of two pdf documents.
String	compareDocumentInfo(String outPdf, String cmpPdf, byte[] outPass, byte[] cmpPass) This method overload is used to compare two encrypted PDF documents.
String	compareLinkAnnotations(String outPdf, String cmpPdf) Compares if two documents has identical link annotations on corresponding pages.
boolean	compareNames(PdfName outName, PdfName cmpName) Simple method that compares two given PdfNames.
boolean	compareNumbers(PdfNumber outNumber, PdfNumber cmpNumber) Simple method that compares two given PdfNumbers.
boolean	compareStreams(PdfStream outStream, PdfStream cmpStream) Simple method that compares two given PdfStreams by content.
boolean	compareStrings(PdfString outString, PdfString cmpString) Simple method that compares two given PdfStrings.
String	compareTagStructures(String outPdf, String cmpPdf) Compares tag structures of the two PDF documents.
String	compareVisually(String outPdf, String cmpPdf, String outPath, String differenceImagePrefix) Compares two documents visually.
String	compareVisually(String outPdf, String cmpPdf, String outPath, String differenceImagePrefix, Map<Integer,List<Rectangle>> ignoredAreas) Compares two documents visually.
boolean	compareXmls(byte[] xml1, byte[] xml2) Utility method that provides simple comparison of the two xml files stored in byte arrays.
boolean	compareXmls(String xmlFilePath1, String xmlFilePath2) Utility method that provides simple comparison of the two xml files.
String	compareXmp(String outPdf, String cmpPdf) Compares xmp metadata of the two given PDF documents.
String	compareXmp(String outPdf, String cmpPdf, boolean ignoreDateAndProducerProperties) Compares xmp metadata of the two given PDF documents.
CompareTool	disableCachedPagesComparison() Disables the default logic of pages comparison.
CompareTool	enableEncryptionCompare() Enables the comparison of the encryption properties of the documents.
ReaderProperties	getCmpReaderProperties() Documents for comparison are opened in reader mode.
ReaderProperties	getOutReaderProperties() Documents for comparison are opened in reader mode.
CompareTool	setCompareByContentErrorsLimit(int compareByContentMaxErrorCount) Sets the maximum errors count which will be returned as the result of the comparison.
CompareTool	setGenerateCompareByContentXmlReport(boolean generateCompareByContentXmlReport) Enables or disables the generation of the comparison report in the form of the xml document.

Methods inherited from class java.lang.Object

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

Constructor Detail

CompareTool

public CompareTool()

Creates an instance of the CompareTool.

Method Detail

compareByCatalog

public CompareTool.CompareResult compareByCatalog(PdfDocument outDocument,
                                                  PdfDocument cmpDocument)
                                           throws IOException

Compares two PDF documents by content starting from Catalog dictionary and then recursively comparing corresponding objects which are referenced from it. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

The main difference between this method and the compareByContent(String, String, String, String) methods is the return value. This method returns a CompareTool.CompareResult class instance, which could be used in code, however compareByContent methods in case of the differences simply return String value, which could only be printed. Also, keep in mind that this method doesn't perform visual comparison of the documents.

For more explanations about what is outDoc and cmpDoc see last paragraph of the CompareTool class description.

Parameters:

outDocument - the absolute path to the output file, which is to be compared to cmp-file.

cmpDocument - the absolute path to the cmp-file, which is to be compared to output file.

Returns:

the report of comparison of two files in the form of the custom class instance. See CompareTool.CompareResult for more info.

Throws:

IOException

disableCachedPagesComparison

public CompareTool disableCachedPagesComparison()

Disables the default logic of pages comparison. This option makes sense only for compareByCatalog(PdfDocument, PdfDocument) method.

By default, pages are treated as special objects and if they are met in the process of comparison, then they are not checked as objects, but rather simply checked that they has same page numbers in both documents. This behaviour is intended for the compareByContent(java.lang.String, java.lang.String, java.lang.String, java.lang.String) set of methods, because in them documents are compared in page by page basis. Thus, we don't need to check if pages are of the same content when they are met in comparison process, we are sure that we will compare their content or we have already compared them.

However, if you would use compareByCatalog(com.itextpdf.kernel.pdf.PdfDocument, com.itextpdf.kernel.pdf.PdfDocument) with default behaviour of pages comparison, pages won't be checked at all, every time when reference to the page dictionary is met, only page numbers will be compared for both documents. You can say that in this case, comparison will be performed for all document's catalog entries except /Pages (However in fact, document's page tree structures will be compared, but pages themselves - won't).

Returns:

this CompareTool instance.

setCompareByContentErrorsLimit

public CompareTool setCompareByContentErrorsLimit(int compareByContentMaxErrorCount)

Sets the maximum errors count which will be returned as the result of the comparison.

Parameters:

compareByContentMaxErrorCount - the errors count.

Returns:

this CompareTool instance.

setGenerateCompareByContentXmlReport

public CompareTool setGenerateCompareByContentXmlReport(boolean generateCompareByContentXmlReport)

Enables or disables the generation of the comparison report in the form of the xml document.
IMPORTANT NOTE: this flag affect only the comparison made by compareByContent methods!

Parameters:

generateCompareByContentXmlReport - true to enable xml report generation, false - to disable.

Returns:

this CompareTool instance.

enableEncryptionCompare

public CompareTool enableEncryptionCompare()

Enables the comparison of the encryption properties of the documents. Encryption properties comparison results are returned along with all other comparison results.
IMPORTANT NOTE: this flag affect only the comparison made by compareByContent methods!

Returns:

this CompareTool instance.

getOutReaderProperties

public ReaderProperties getOutReaderProperties()

Documents for comparison are opened in reader mode. This method is intended to alter ReaderProperties which are used to open output document. This is particularly useful for comparison of encrypted documents.

For more explanations about what is outDoc and cmpDoc see last paragraph of the CompareTool class description.

Returns:

ReaderProperties instance which will be later passed to the output document PdfReader.

getCmpReaderProperties

public ReaderProperties getCmpReaderProperties()

Documents for comparison are opened in reader mode. This method is intended to alter ReaderProperties which are used to open cmp document. This is particularly useful for comparison of encrypted documents.

For more explanations about what is outDoc and cmpDoc see last paragraph of the CompareTool class description.

Returns:

ReaderProperties instance which will be later passed to the cmp document PdfReader.

compareVisually

public String compareVisually(String outPdf,
                              String cmpPdf,
                              String outPath,
                              String differenceImagePrefix)
                       throws InterruptedException,
                              IOException

Compares two documents visually. For the comparison two external tools are used: Ghostscript and ImageMagick. For more info about needed configuration for visual comparison process see CompareTool class description.
During comparison for every page of two documents an image file will be created in the folder specified by outPath absolute path. Then those page images will be compared and if there are any differences for some pages, another image file will be created with marked differences on it.

Parameters:

outPdf - the absolute path to the output file, which is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which is to be compared to output file.

outPath - the absolute path to the folder, which will be used to store image files for visual comparison.

differenceImagePrefix - file name prefix for image files with marked differences if there is any.

Returns:

string containing list of the pages that are visually different, or null if there are no visual differences.

Throws:

InterruptedException

IOException

compareVisually

public String compareVisually(String outPdf,
                              String cmpPdf,
                              String outPath,
                              String differenceImagePrefix,
                              Map<Integer,List<Rectangle>> ignoredAreas)
                       throws InterruptedException,
                              IOException

Compares two documents visually. For the comparison two external tools are used: Ghostscript and ImageMagick. For more info about needed configuration for visual comparison process see CompareTool class description.
During comparison for every page of two documents an image file will be created in the folder specified by outPath absolute path. Then those page images will be compared and if there are any differences for some pages, another image file will be created with marked differences on it.
It is possible to ignore certain areas of the document pages during visual comparison. This is useful for example in case if documents should be the same except certain page area with date on it. In this case, in the folder specified by the outPath, new pdf documents will be created with the black rectangles at the specified ignored areas, and visual comparison will be performed on these new documents.

Parameters:

outPdf - the absolute path to the output file, which is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which is to be compared to output file.

outPath - the absolute path to the folder, which will be used to store image files for visual comparison.

differenceImagePrefix - file name prefix for image files with marked differences if there is any.

ignoredAreas - a map with one-based page numbers as keys and lists of ignored rectangles as values.

Returns:

string containing list of the pages that are visually different, or null if there are no visual differences.

Throws:

InterruptedException

IOException

compareByContent

public String compareByContent(String outPdf,
                               String cmpPdf,
                               String outPath,
                               String differenceImagePrefix)
                        throws InterruptedException,
                               IOException

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Unlike compareByCatalog(PdfDocument, PdfDocument) this method performs content comparison page by page and doesn't compare the tag structure, acroforms and all other things that doesn't belong to specific pages.
When comparison by content is finished, if any differences were found, visual comparison is automatically started. For more info see compareVisually(String, String, String, String).

For more explanations about what is outPdf and cmpPdf see last paragraph of the CompareTool class description.

Parameters:

outPdf - the absolute path to the output file, which is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which is to be compared to output file.

outPath - the absolute path to the folder, which will be used to store image files for visual comparison.

differenceImagePrefix - file name prefix for image files with marked visual differences if there is any.

Returns:

string containing text report of the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

Throws:

InterruptedException

IOException

compareByContent

public String compareByContent(String outPdf,
                               String cmpPdf,
                               String outPath,
                               String differenceImagePrefix,
                               byte[] outPass,
                               byte[] cmpPass)
                        throws InterruptedException,
                               IOException

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Unlike compareByCatalog(PdfDocument, PdfDocument) this method performs content comparison page by page and doesn't compare the tag structure, acroforms and all other things that doesn't belong to specific pages.
When comparison by content is finished, if any differences were found, visual comparison is automatically started. For more info see compareVisually(String, String, String, String).

For more explanations about what is outPdf and cmpPdf see last paragraph of the CompareTool class description.

Parameters:

outPdf - the absolute path to the output file, which is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which is to be compared to output file.

outPath - the absolute path to the folder, which will be used to store image files for visual comparison.

differenceImagePrefix - file name prefix for image files with marked visual differences if there is any.

outPass - password for the encrypted document specified by the outPdf absolute path.

cmpPass - password for the encrypted document specified by the cmpPdf absolute path.

Returns:

string containing text report of the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

Throws:

InterruptedException

IOException

compareByContent

public String compareByContent(String outPdf,
                               String cmpPdf,
                               String outPath,
                               String differenceImagePrefix,
                               Map<Integer,List<Rectangle>> ignoredAreas)
                        throws InterruptedException,
                               IOException

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Unlike compareByCatalog(PdfDocument, PdfDocument) this method performs content comparison page by page and doesn't compare the tag structure, acroforms and all other things that doesn't belong to specific pages.
When comparison by content is finished, if any differences were found, visual comparison is automatically started. For more info see compareVisually(String, String, String, String, Map).

For more explanations about what is outPdf and cmpPdf see last paragraph of the CompareTool class description.

Parameters:

outPdf - the absolute path to the output file, which is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which is to be compared to output file.

outPath - the absolute path to the folder, which will be used to store image files for visual comparison.

differenceImagePrefix - file name prefix for image files with marked visual differences if there is any.

ignoredAreas - a map with one-based page numbers as keys and lists of ignored rectangles as values.

Returns:

string containing text report of the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

Throws:

InterruptedException

IOException

compareByContent

public String compareByContent(String outPdf,
                               String cmpPdf,
                               String outPath,
                               String differenceImagePrefix,
                               Map<Integer,List<Rectangle>> ignoredAreas,
                               byte[] outPass,
                               byte[] cmpPass)
                        throws InterruptedException,
                               IOException

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters.

Compares two PDF documents by content starting from page dictionaries and then recursively comparing corresponding objects which are referenced from them. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Unlike compareByCatalog(PdfDocument, PdfDocument) this method performs content comparison page by page and doesn't compare the tag structure, acroforms and all other things that doesn't belong to specific pages.
When comparison by content is finished, if any differences were found, visual comparison is automatically started. For more info see compareVisually(String, String, String, String, Map).

For more explanations about what is outPdf and cmpPdf see last paragraph of the CompareTool class description.

Parameters:

outPdf - the absolute path to the output file, which is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which is to be compared to output file.

outPath - the absolute path to the folder, which will be used to store image files for visual comparison.

differenceImagePrefix - file name prefix for image files with marked visual differences if there is any.

ignoredAreas - a map with one-based page numbers as keys and lists of ignored rectangles as values.

outPass - password for the encrypted document specified by the outPdf absolute path.

cmpPass - password for the encrypted document specified by the cmpPdf absolute path.

Returns:

string containing text report of the encountered content differences and also list of the pages that are visually different, or null if there are no content and therefore no visual differences.

Throws:

InterruptedException

IOException

compareDictionaries

public boolean compareDictionaries(PdfDictionary outDict,
                                   PdfDictionary cmpDict)
                            throws IOException

Simple method that compares two given PdfDictionaries by content. This is "deep" comparing, which means that all nested objects are also compared by content.

Parameters:

outDict - dictionary to compare.

cmpDict - dictionary to compare.

Returns:

true if dictionaries are equal by content, otherwise false.

Throws:

IOException

compareStreams

public boolean compareStreams(PdfStream outStream,
                              PdfStream cmpStream)
                       throws IOException

Simple method that compares two given PdfStreams by content. This is "deep" comparing, which means that all nested objects are also compared by content.

Parameters:

outStream - stream to compare.

cmpStream - stream to compare.

Returns:

true if stream are equal by content, otherwise false.

Throws:

IOException

compareArrays

public boolean compareArrays(PdfArray outArray,
                             PdfArray cmpArray)
                      throws IOException

Simple method that compares two given PdfArrays by content. This is "deep" comparing, which means that all nested objects are also compared by content.

Parameters:

outArray - array to compare.

cmpArray - array to compare.

Returns:

true if arrays are equal by content, otherwise false.

Throws:

IOException

compareNames

public boolean compareNames(PdfName outName,
                            PdfName cmpName)

Simple method that compares two given PdfNames.

Parameters:

outName - name to compare.

cmpName - name to compare.

Returns:

true if names are equal, otherwise false.

compareNumbers

public boolean compareNumbers(PdfNumber outNumber,
                              PdfNumber cmpNumber)

Simple method that compares two given PdfNumbers.

Parameters:

outNumber - number to compare.

cmpNumber - number to compare.

Returns:

true if numbers are equal, otherwise false.

compareStrings

public boolean compareStrings(PdfString outString,
                              PdfString cmpString)

Simple method that compares two given PdfStrings.

Parameters:

outString - string to compare.

cmpString - string to compare.

Returns:

true if strings are equal, otherwise false.

compareBooleans

public boolean compareBooleans(PdfBoolean outBoolean,
                               PdfBoolean cmpBoolean)

Simple method that compares two given PdfBooleans.

Parameters:

outBoolean - boolean to compare.

cmpBoolean - boolean to compare.

Returns:

true if booleans are equal, otherwise false.

compareXmp

public String compareXmp(String outPdf,
                         String cmpPdf)

Compares xmp metadata of the two given PDF documents.

Parameters:

outPdf - the absolute path to the output file, which xmp is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which xmp is to be compared to output file.

Returns:

text report of the xmp differences, or null if there are no differences.

compareXmp

public String compareXmp(String outPdf,
                         String cmpPdf,
                         boolean ignoreDateAndProducerProperties)

Compares xmp metadata of the two given PDF documents.

Parameters:

outPdf - the absolute path to the output file, which xmp is to be compared to cmp-file.

cmpPdf - the absolute path to the cmp-file, which xmp is to be compared to output file.

ignoreDateAndProducerProperties - true, if to ignore differences in date or producer xmp metadata properties.

Returns:

text report of the xmp differences, or null if there are no differences.

compareXmls

public boolean compareXmls(byte[] xml1,
                           byte[] xml2)
                    throws ParserConfigurationException,
                           SAXException,
                           IOException

Utility method that provides simple comparison of the two xml files stored in byte arrays.

Parameters:

xml1 - first xml file data to compare.

xml2 - second xml file data to compare.

Returns:

true if xml structures are identical, false otherwise.

Throws:

ParserConfigurationException

SAXException

IOException

compareXmls

public boolean compareXmls(String xmlFilePath1,
                           String xmlFilePath2)
                    throws ParserConfigurationException,
                           SAXException,
                           IOException

Utility method that provides simple comparison of the two xml files.

Parameters:

xmlFilePath1 - absolute path to the first xml file to compare.

xmlFilePath2 - absolute path to the second xml file to compare.

Returns:

true if xml structures are identical, false otherwise.

Throws:

ParserConfigurationException

SAXException

IOException

compareDocumentInfo

public String compareDocumentInfo(String outPdf,
                                  String cmpPdf,
                                  byte[] outPass,
                                  byte[] cmpPass)
                           throws IOException

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters.

Compares document info dictionaries of two pdf documents.

Parameters:

outPdf - the absolute path to the output file, which info is to be compared to cmp-file info.

cmpPdf - the absolute path to the cmp-file, which info is to be compared to output file info.

outPass - password for the encrypted document specified by the outPdf absolute path.

cmpPass - password for the encrypted document specified by the cmpPdf absolute path.

Returns:

text report of the differences in documents infos.

Throws:

IOException

compareDocumentInfo

public String compareDocumentInfo(String outPdf,
                                  String cmpPdf)
                           throws IOException

Compares document info dictionaries of two pdf documents.

Parameters:

outPdf - the absolute path to the output file, which info is to be compared to cmp-file info.

cmpPdf - the absolute path to the cmp-file, which info is to be compared to output file info.

Returns:

text report of the differences in documents infos.

Throws:

IOException

compareLinkAnnotations

public String compareLinkAnnotations(String outPdf,
                                     String cmpPdf)
                              throws IOException

Compares if two documents has identical link annotations on corresponding pages.

Parameters:

outPdf - the absolute path to the output file, which links are to be compared to cmp-file links.

cmpPdf - the absolute path to the cmp-file, which links are to be compared to output file links.

Returns:

text report of the differences in documents links.

Throws:

IOException

compareTagStructures

public String compareTagStructures(String outPdf,
                                   String cmpPdf)
                            throws IOException,
                                   ParserConfigurationException,
                                   SAXException

Compares tag structures of the two PDF documents.
This method creates xml files in the same folder with outPdf file. These xml files contain documents tag structures converted into the xml structure. These xml files are compared if they are equal.

Parameters:

outPdf - the absolute path to the output file, which tags are to be compared to cmp-file tags.

cmpPdf - the absolute path to the cmp-file, which tags are to be compared to output file tags.

Returns:

text report of the differences in documents tags.

Throws:

IOException

ParserConfigurationException

SAXException