iText7 7.1.10  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 of 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" 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.

Class CompareTool.CompareResult, constructor CompareTool.CompareResult(int)

Creates new empty instance of CompareResult with given limit of difference messages. @param messageLimit maximum number of difference messages to be handled by this CompareResult.
Class CompareTool.CompareResult, Map getDifferences()

Returns map with ObjectPath as keys and difference descriptions as values. @return differences map which could be used to find in the document the objects that are different.
Class CompareTool.CompareResult, int getErrorCount()

Returns number of differences between two documents met detected during comparison. @return number of differences.
Class CompareTool.CompareResult, String getReport()

Converts this CompareResult into text form. @return text report of on the differences between two documents.
Class CompareTool.CompareResult, boolean isOk()

Is Verifies used to define if documents are considered equal after comparison. @return true if documents are equal, false otherwise.
Class CompareTool.ObjectPath

Class that helps to find two corresponding objects in the comparing compared documents and also keeps track of the already met in during comparing process parent indirect objects.

You could say that ObjectPath instance consists of two parts: direct path and indirect path. Direct path defines path to the currently comparing objects in relation to base objects. It could be empty, which would mean that currently comparing objects are base objects themselves. Base objects are the two indirect objects from the comparing documents which are in the same position in the pdf trees. Another part, indirect path, defines which indirect objects were met during comparison process to get to the current base objects. Indirect path is needed to avoid infinite loops during comparison.

Class CompareTool.ObjectPath, ObjectPath resetDirectPath(PdfIndirectReference, PdfIndirectReference)

Creates a new ObjectPath instance with two new given base objects, which are supposed to be nested in the base objects of the current instance of the ObjectPath. This method is used to avoid infinite loop in case of circular references in pdf documents objects structure.

Basically, this method creates copy of the current ObjectPath instance, but resets information of the direct paths, and also adds current ObjectPath instance base objects to the indirect references chain that denotes a path to the new base objects. @param baseCmpObject new base object in cmp document. @param baseOutObject new base object in out document. @return new ObjectPath instance, which stores chain of the indirect references which were already met to get to the new base objects.

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, however 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 is outDoc and cmpDoc are see last paragraph of the CompareTool class description. @param outDocument the a absolute PdfDocument path corresponding to the output file, which is to be compared to with cmp-file. @param cmpDocument the a absolute PdfDocument path corresponding to the cmp-file, which is to be compared to with output file. @return the report of on comparison of two files in the form of the custom class instance. See CompareResult for more info instance. @throws IOException IOException @see CompareResult

Class CompareTool, String compareByContent(String, String, String)

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 this overload, differenceImagePrefix value is generated using diff_%outPdfFileName%_ format.

For more explanations about what is outPdf and cmpPdf are see last paragraph of the CompareTool class description. @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. @return string containing text report of on 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 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 wasn weren't possible to be created. @see #compareVisually(String, String, String, String)

Class CompareTool, String compareByContent(String, String, String, String)

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 are see last paragraph of the CompareTool class description. @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 visual differences if there is are any; if it's set to null the prefix defaults to diff_%outPdfFileName%_ format. @return string containing text report of on 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 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 wasn weren't possible to be created. @see #compareVisually(String, String, String, String)

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

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 are see last paragraph of the CompareTool class description. @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 visual differences if there is are any; if it's set to null the prefix defaults to diff_%outPdfFileName%_ format. @param ignoredAreas a map with one-based page numbers as keys and lists of ignored rectangles as values. @return string containing text report of on 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 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. @see #compareVisually(String, String, String, String)

Class CompareTool, String compareByContent(String, String, String, String, Map>, byte[], byte[])

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 are see last paragraph of the CompareTool class description. @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 visual differences if there is are any; if it's set to null the prefix defaults to diff_%outPdfFileName%_ format. @param ignoredAreas a map with one-based page numbers as keys and lists of ignored rectangles as values. @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 string containing text report of on 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 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 wasn weren't possible to be created. @see #compareVisually(String, String, String, String)

Class CompareTool, String compareByContent(String, String, String, String, byte[], byte[])

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 are see last paragraph of the CompareTool class description. @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 visual differences if there is any; if it's set to null the prefix defaults to diff_%outPdfFileName%_ format. @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 string containing text report of on 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 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. @see #compareVisually(String, String, String, String)

Class CompareTool, CompareResult compareDictionariesStructure(PdfDictionary, PdfDictionary)

Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Both out and cmp PdfDictionary shall have indirect references.

By default page dictionaries are excluded from the comparison when met and are instead compared in a special manner, simply comparing their page numbers. This behavior can be disabled by calling .disableCachedPagesComparison().

For more explanations about what is outPdf and cmpPdf are see last paragraph of the CompareTool class description. @param outDict an indirect PdfDictionary from the output file, which is to be compared to cmp-file dictionary. @param cmpDict an indirect PdfDictionary from the cmp-file file, which is to be compared to output file dictionary. @return CompareResult instance containing differences between the two dictionaries, or {@code null} if dictionaries are equal.

Class CompareTool, CompareResult compareDictionariesStructure(PdfDictionary, PdfDictionary, Set)

Recursively compares structures of two corresponding dictionaries from out and cmp PDF documents. You can roughly imagine it as depth-first traversal of the two trees that represent pdf objects structure of the documents.

Both out and cmp PdfDictionary shall have indirect references.

By default page dictionaries are excluded from the comparison when met and are instead compared in a special manner, simply comparing their page numbers. This behavior can be disabled by calling .disableCachedPagesComparison().

For more explanations about what is outPdf and cmpPdf are see last paragraph of the CompareTool class description. @param outDict an indirect PdfDictionary from the output file, which is to be compared to cmp-file dictionary. @param cmpDict an indirect PdfDictionary from the cmp-file file, which is to be compared to output file dictionary. @param excludedKeys a Set of names that designate entries from {@code outDict} and {@code cmpDict} dictionaries which are to be skipped during comparison. @return CompareResult instance containing differences between the two dictionaries, or {@code null} if dictionaries are equal.

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 of on the differences in documents infos. @throws IOException
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. 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. @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 of on the differences in documents infos. @throws IOException
Class CompareTool, String compareLinkAnnotations(String, String)

Compares Checks if two documents has 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 of on the differences in documents links. @throws IOException
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 @throws ParserConfigurationException @throws SAXException

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 absolute path 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 @throws IOException

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 absolute path 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 @throws IOException

Class CompareTool, String compareXmp(String, String)

Compares xmp metadata of the two given PDF documents. @param outPdf the absolute path to the output file, which xmp is to be compared to cmp-file. @param cmpPdf the absolute path to the cmp-file, which xmp is to be compared to output file. @return text report of on the xmp differences, or null if there are no differences.
Class CompareTool, String compareXmp(String, String, boolean)

Compares xmp metadata of the two given PDF documents. @param outPdf the absolute path to the output file, which xmp is to be compared to cmp-file. @param cmpPdf the absolute path to the cmp-file, which xmp is to be compared to output file. @param ignoreDateAndProducerProperties true, if to ignore differences in date or producer xmp metadata properties. @return text report of on the xmp differences, or null if there are no differences.
Class CompareTool, CompareTool disableCachedPagesComparison()

Disables the default logic of pages comparison. This option makes sense only for CompareTool.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 have same page numbers in both documents. This behaviour is intended for the CompareTool.compareByContent 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 CompareTool.compareByCatalog 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). @return this CompareTool instance.

Class CompareTool, 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 affects only the comparison made performed by compareByContent methods! .compareByCatalog(PdfDocument, PdfDocument) doesn't compare encryption properties because encryption properties aren't part of the document's Catalog. @return this CompareTool instance.

Class CompareTool, ReaderProperties getCmpReaderProperties()

Gets ReaderProperties to be passed later to the PdfReader of the cmp document.

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

For more explanations about what is outDoc and cmpDoc are see last paragraph of the CompareTool class description. @return ReaderProperties instance which will to be later passed later to the cmp document PdfReader of the cmp document.
Class CompareTool, ReaderProperties getOutReaderProperties()

Gets ReaderProperties to be passed later to the PdfReader of the output document.

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

For more explanations about what is outDoc and cmpDoc are see last paragraph of the CompareTool class description. @return ReaderProperties instance which will to be later passed later to the output document PdfReader of the output document.
Class CompareTool, CompareTool setGenerateCompareByContentXmlReport(boolean)

Enables or disables the generation of the comparison report in the form of the an xml document.

IMPORTANT NOTE: this flag affect affects only the comparison made performed by compareByContent methods! @param generateCompareByContentXmlReport true to enable xml report generation, false - to disable. @return this CompareTool instance.