iText7 7.1.12  Overview   Package   Class  Text Changes  Statistics  Help 
Generated by
JDiff
PREV PACKAGE    NEXT PACKAGE          FRAMES    NO FRAMES  

com.itextpdf.kernel.utils Documentation Differences

This file contains all the changes in documentation in the package com.itextpdf.kernel.utils as colored differences. Deletions are shown like this , and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a tag will cause all subsequent paragraphs to be displayed differently.
Class CompareTool

This class provides means to compare two PDF files both by content and visually and gives the report on 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 ITEXT_GS_EXEC" and " compareExec ITEXT_MAGICK_COMPARE_EXEC", which would contain the paths commands to the executables of execute correspondingly the 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.

Class CompareTool.CompareResult, void writeReportToXml(OutputStream)

Converts this CompareResult into xml form. @param stream output stream to which xml report will be written. @throws ParserConfigurationException ParserConfigurationException if a XML DocumentBuilder cannot be created which satisfies the configuration requested. @throws TransformerException if it is not possible to create an XML Transformer instance or an unrecoverable error occurs during the course of the transformation.
Class CompareTool, boolean compareArrays(PdfArray, PdfArray)

Simple method that compares two given PdfArrays by content. This is "deep" comparing, which means that all nested objects are also compared by content. @param outArray array to compare. @param cmpArray array to compare. @return true if arrays are equal by content, otherwise false. @throws IOException obsolete. Would be removed in 7.2.
Class CompareTool, CompareResult compareByCatalog(PdfDocument, PdfDocument)

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 CompareResult class instance, which could be used in code, whilst 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 outDoc and cmpDoc are see last paragraph of the CompareTool class description. @param outDocument a PdfDocument corresponding to the output file, which is to be compared with cmp-file. @param cmpDocument a PdfDocument corresponding to the cmp-file, which is to be compared with output file. @return the report on comparison of two files in the form of the custom class CompareResult instance. @throws IOException IOException obsolete. Would be removed in 7.2. @see CompareResult

Class CompareTool, boolean compareDictionaries(PdfDictionary, PdfDictionary)

Simple method that compares two given PdfDictionaries by content. This is "deep" comparing, which means that all nested objects are also compared by content. @param outDict dictionary to compare. @param cmpDict dictionary to compare. @return true if dictionaries are equal by content, otherwise false. @throws IOException obsolete. Would be removed in 7.2.
Class CompareTool, String compareDocumentInfo(String, String)

Compares document info dictionaries of two pdf documents. @param outPdf the absolute path to the output file, which info is to be compared to cmp-file info. @param cmpPdf the absolute path to the cmp-file, which info is to be compared to output file info. @return text report on the differences in documents infos. @throws IOException if PDF reader cannot be created due to IO issues
Class CompareTool, String compareDocumentInfo(String, String, byte[], byte[])

Compares document info dictionaries of two pdf documents.

This method overload is used to compare two encrypted PDF documents. Document passwords are passed with outPass and cmpPass parameters. @param outPdf the absolute path to the output file, which info is to be compared to cmp-file info. @param cmpPdf the absolute path to the cmp-file, which info is to be compared to output file info. @param outPass password for the encrypted document specified by the outPdf absolute path. @param cmpPass password for the encrypted document specified by the cmpPdf absolute path. @return text report on the differences in documents infos. @throws IOException if PDF reader cannot be created due to IO issues

Class CompareTool, String compareLinkAnnotations(String, String)

Checks if two documents have identical link annotations on corresponding pages. @param outPdf the absolute path to the output file, which links are to be compared to cmp-file links. @param cmpPdf the absolute path to the cmp-file, which links are to be compared to output file links. @return text report on the differences in documents links. @throws IOException if PDF reader cannot be created due to IO issues
Class CompareTool, boolean compareStreams(PdfStream, PdfStream)

Simple method that compares two given PdfStreams by content. This is "deep" comparing, which means that all nested objects are also compared by content. @param outStream stream to compare. @param cmpStream stream to compare. @return true if stream are equal by content, otherwise false. @throws IOException obsolete. Would be removed in 7.2.
Class CompareTool, String compareTagStructures(String, String)

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. @param outPdf the absolute path to the output file, which tags are to be compared to cmp-file tags. @param cmpPdf the absolute path to the cmp-file, which tags are to be compared to output file tags. @return text report of the differences in documents tags. @throws IOException IOException is thrown if any of the input files are missing or any of the auxiliary files that are created during comparison process weren't possible to be created. @throws ParserConfigurationException ParserConfigurationException if a XML DocumentBuilder cannot be created which satisfies the configuration requested. @throws SAXException if any XML parse errors occur.

Class CompareTool, String compareVisually(String, String, String, String)

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 the two documents an image file will be created in the folder specified by outPath parameter. 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. @param outPdf the absolute path to the output file, which is to be compared to cmp-file. @param cmpPdf the absolute path to the cmp-file, which is to be compared to output file. @param outPath the absolute path to the folder, which will be used to store image files for visual comparison. @param differenceImagePrefix file name prefix for image files with marked differences if there is any. @return string containing list of the pages that are visually different, or null if there are no visual differences. @throws InterruptedException InterruptedException if the current thread is interrupted by another thread while it is waiting for ghostscript or imagemagic processes, then the wait is ended and an InterruptedException is thrown. @throws IOException is thrown if any of the input files are missing or any of the auxiliary files that are created during comparison process weren't possible to be created.

Class CompareTool, String compareVisually(String, String, String, String, Map>)

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 parameter. 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. @param outPdf the absolute path to the output file, which is to be compared to cmp-file. @param cmpPdf the absolute path to the cmp-file, which is to be compared to output file. @param outPath the absolute path to the folder, which will be used to store image files for visual comparison. @param differenceImagePrefix file name prefix for image files with marked differences if there is any. @param ignoredAreas a map with one-based page numbers as keys and lists of ignored rectangles as values. @return string containing list of the pages that are visually different, or null if there are no visual differences. @throws InterruptedException InterruptedException if the current thread is interrupted by another thread while it is waiting for ghostscript or imagemagic processes, then the wait is ended and an InterruptedException is thrown. @throws IOException is thrown if any of the input files are missing or any of the auxiliary files that are created during comparison process weren't possible to be created.

Class CompareTool, boolean compareXmls(String, String)

Utility method that provides simple comparison of the two xml files. @param outXmlFile absolute path to the out xml file to compare. @param cmpXmlFile absolute path to the cmp xml file to compare. @return true if xml structures are identical, false otherwise. @throws ParserConfigurationException ParserConfigurationException if a XML DocumentBuilder cannot be created which satisfies the configuration requested. @throws SAXException SAXException if any XML parse errors occur. @throws IOException If any IO errors occur during reading XML files.
Class CompareTool, boolean compareXmls(byte[], byte[])

Utility method that provides simple comparison of the two xml files stored in byte arrays. @param xml1 first xml file data to compare. @param xml2 second xml file data to compare. @return true if xml structures are identical, false otherwise. @throws ParserConfigurationException ParserConfigurationException if a XML DocumentBuilder cannot be created which satisfies the configuration requested. @throws SAXException SAXException if any XML parse errors occur. @throws IOException If any IO errors occur during reading XML files.