Package de.redsix.pdfcompare

Class PdfComparator<T extends CompareResultImpl>

java.lang.Object

de.redsix.pdfcompare.PdfComparator<T>

Type Parameters:

T - Allows to specify different CompareResults.

public class PdfComparator<T extends CompareResultImpl>
extends Object

The PdfComparator is the entry point to use for comparing documents. It allows to specify which documents to compare and which additional features to apply, like ignores and passwords. One PdfCompare object is created for every comparison and they are not reused.

Field Summary

Fields

Modifier and Type	Field	Description
static int	MARKER_WIDTH

Constructor Summary

Constructors

Constructor	Description
PdfComparator(File expectedFile, File actualFile)	Compare two PDFs by providing two File objects for the expected PDF and the actual PDF.
PdfComparator(File expectedFile, File actualFile, T compareResult)	Compare two PDFs by providing two File objects for the expected PDF and the actual PDF.
PdfComparator(InputStream expectedPdfIS, InputStream actualPdfIS)	Compare two PDFs by providing two InputStream objects for the expected PDF and the actual PDF.
PdfComparator(InputStream expectedPdfIS, InputStream actualPdfIS, T compareResult)	Compare two PDFs by providing two InputStream objects for the expected PDF and the actual PDF.
PdfComparator(String expectedPdfFilename, String actualPdfFilename)	Compare two PDFs by providing two filenames for the expected PDF and the actual PDF.
PdfComparator(String expectedPdfFilename, String actualPdfFilename, T compareResult)	Compare two PDFs by providing two filenames for the expected PDF and the actual PDF.
PdfComparator(Path expectedPath, Path actualPath)	Compare two PDFs by providing two Path objects for the expected PDF and the actual PDF.
PdfComparator(Path expectedPath, Path actualPath, T compareResult)	Compare two PDFs by providing two Path objects for the expected PDF and the actual PDF.

Method Summary

Modifier and Type	Method	Description
static <T extends CompareResultImpl> PdfComparator	base64(String expectedPdfBase64, String actualPdfBase64)	Compare two PDFs, that are given as base64 encoded strings.
static <T extends CompareResultImpl> PdfComparator	base64(String expectedPdfBase64, String actualPdfBase64, T compareResult)	Compare two PDFs, that are given as base64 encoded strings.
T	compare()	Does the actual comparison of the given PDF documents.
T	getResult()
static ImageWithDimension	renderPageAsImage(org.apache.pdfbox.pdmodel.PDDocument document, org.apache.pdfbox.rendering.PDFRenderer expectedPdfRenderer, int pageIndex, Environment environment)
void	setEnvironment(Environment environment)	Deprecated. use withEnvironment(Environment) instead.
PdfComparator<T>	with(PageArea exclusion)	Deprecated. Use withIgnore(PageArea) instead.
PdfComparator<T>	withActualPassword(String password)
PdfComparator<T>	withEnvironment(Environment environment)	Allows to inject an Environment that can override environment settings.
PdfComparator<T>	withExpectedPassword(String password)
PdfComparator<T>	withIgnore(PageArea exclusion)	Allows to specify an area of a page that is excluded during the comparison.
PdfComparator<T>	withIgnore(File ignoreFile)	Reads a file with Exclusions.
PdfComparator<T>	withIgnore(InputStream ignoreIS)	Reads Exclusions from an InputStream.
PdfComparator<T>	withIgnore(String ignoreFilename)	Reads a file with Exclusions.
PdfComparator<T>	withIgnore(Path ignorePath)	Reads a file with Exclusions.

Methods inherited from class java.lang.Object

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

Field Detail

MARKER_WIDTH

public static final int MARKER_WIDTH

See Also:

Constant Field Values

Constructor Detail

PdfComparator

public PdfComparator(String expectedPdfFilename,
                     String actualPdfFilename)

Compare two PDFs by providing two filenames for the expected PDF and the actual PDF.

Parameters:

expectedPdfFilename - filename for the expected PDF

actualPdfFilename - filename for the actual PDF

PdfComparator

public PdfComparator(String expectedPdfFilename,
                     String actualPdfFilename,
                     T compareResult)

Compare two PDFs by providing two filenames for the expected PDF and the actual PDF.

Parameters:

expectedPdfFilename - filename for the expected PDF

actualPdfFilename - filename for the actual PDF

compareResult - the CompareResult to use during this compare. Allows to provide CompareResultImpl Subtypes with Swapping for example.

PdfComparator

public PdfComparator(Path expectedPath,
                     Path actualPath)

Compare two PDFs by providing two Path objects for the expected PDF and the actual PDF.

Parameters:

expectedPath - Path for the expected PDF

actualPath - Path for the actual PDF

PdfComparator

public PdfComparator(Path expectedPath,
                     Path actualPath,
                     T compareResult)

Compare two PDFs by providing two Path objects for the expected PDF and the actual PDF.

Parameters:

expectedPath - Path for the expected PDF

actualPath - Path for the actual PDF

compareResult - the CompareResult to use during this compare. Allows to provide CompareResultImpl Subtypes with Swapping for example.

PdfComparator

public PdfComparator(File expectedFile,
                     File actualFile)

Compare two PDFs by providing two File objects for the expected PDF and the actual PDF.

Parameters:

expectedFile - File for the expected PDF

actualFile - File for the actual PDF

PdfComparator

public PdfComparator(File expectedFile,
                     File actualFile,
                     T compareResult)

Compare two PDFs by providing two File objects for the expected PDF and the actual PDF.

Parameters:

expectedFile - File for the expected PDF

actualFile - File for the actual PDF

compareResult - the CompareResult to use during this compare. Allows to provide CompareResultImpl Subtypes with Swapping for example.

PdfComparator

public PdfComparator(InputStream expectedPdfIS,
                     InputStream actualPdfIS)

Compare two PDFs by providing two InputStream objects for the expected PDF and the actual PDF.

Parameters:

expectedPdfIS - InputStream for the expected PDF

actualPdfIS - InputStream for the actual PDF

PdfComparator

public PdfComparator(InputStream expectedPdfIS,
                     InputStream actualPdfIS,
                     T compareResult)

Compare two PDFs by providing two InputStream objects for the expected PDF and the actual PDF.

Parameters:

expectedPdfIS - InputStream for the expected PDF

actualPdfIS - InputStream for the actual PDF

compareResult - the CompareResult to use during this compare. Allows to provide CompareResultImpl Subtypes with Swapping for example.

Method Detail

base64

public static <T extends CompareResultImpl> PdfComparator base64(String expectedPdfBase64,
                                                                 String actualPdfBase64)

Compare two PDFs, that are given as base64 encoded strings.

Parameters:

expectedPdfBase64 - expected PDF in base64 encoded format

actualPdfBase64 - actual PDF in base64 encoded format

Returns:

A CompareResultImpl object, that contains the result of this compare.

base64

public static <T extends CompareResultImpl> PdfComparator base64(String expectedPdfBase64,
                                                                 String actualPdfBase64,
                                                                 T compareResult)

Compare two PDFs, that are given as base64 encoded strings.

Parameters:

expectedPdfBase64 - expected PDF in base64 encoded format

actualPdfBase64 - actual PDF in base64 encoded format

compareResult - the CompareResult to use during this compare. Allows to provide CompareResultImpl Subtypes with Swapping for example.

Returns:

A CompareResultImpl object, that contains the result of this compare.

setEnvironment

@Deprecated
public void setEnvironment(Environment environment)

Deprecated.

use withEnvironment(Environment) instead.

withEnvironment

public PdfComparator<T> withEnvironment(Environment environment)

Allows to inject an Environment that can override environment settings. SimpleEnvironment is particularly useful if you want to override some properties. If you want to specify your own config file, instead of the default application.conf in the root of the classpath, you an use a ConfigFileEnvironment.

Parameters:

environment - the environment so use

Returns:

this

Throws:

IllegalStateException - when withIgnore methods are called before this method.

withIgnore

public PdfComparator<T> withIgnore(String ignoreFilename)

Reads a file with Exclusions.

Parameters:

ignoreFilename - The file to read

Returns:

this

See Also:

withIgnore(Path)

withIgnore

public PdfComparator<T> withIgnore(File ignoreFile)

Reads a file with Exclusions.

Parameters:

ignoreFile - The file to read

Returns:

this

See Also:

withIgnore(Path)

withIgnore

public PdfComparator<T> withIgnore(Path ignorePath)

Reads a file with Exclusions.

It is possible to define rectangular areas that are ignored during comparison. For that, a file needs to be created, which defines areas to ignore. The file format is JSON (or actually a superset called HOCON) and has the following form:

 exclusions: [
     {
         page: 2
         x1: 300 // entries without a unit are in pixels, when Pdf is rendered at 300DPI
         y1: 1000
         x2: 550
         y2: 1300
     },
     {
         // page is optional. When not given, the exclusion applies to all pages.
         x1: 130.5mm // entries can also be given in units of cm, mm or pt (DTP-Point defined as 1/72 Inches)
         y1: 3.3cm
         x2: 190mm
         y2: 3.7cm
     },
     {
         page: 7
         // coordinates are optional. When not given, the whole page is excluded.
     }
 ]

Parameters:

ignorePath - The file to read

Returns:

this

withIgnore

public PdfComparator<T> withIgnore(InputStream ignoreIS)

Reads Exclusions from an InputStream.

Parameters:

ignoreIS - The file to read

Returns:

this

See Also:

withIgnore(Path)

withIgnore

public PdfComparator<T> withIgnore(PageArea exclusion)

Allows to specify an area of a page that is excluded during the comparison.

Parameters:

exclusion - An area of the document, that shall be ignored.

Returns:

this

with

@Deprecated
public PdfComparator<T> with(PageArea exclusion)

Deprecated.

Use withIgnore(PageArea) instead.

Allows to specify an area of a page that is excluded during the comparison.

Parameters:

exclusion - An area of the document, that shall be ignored.

Returns:

this

withExpectedPassword

public PdfComparator<T> withExpectedPassword(String password)

withActualPassword

public PdfComparator<T> withActualPassword(String password)

compare

public T compare()
          throws IOException,
                 RenderingException

Does the actual comparison of the given PDF documents. When errors occur during the rendering or diffing of pages, they are collected and added to a RenderingException as SuppressedExceptions.

Returns:

the CompareResult gives information about the comparison

Throws:

IOException - when an input file or stream can not be read

RenderingException - when errors during rendering or diffing of pages occurred

renderPageAsImage

public static ImageWithDimension renderPageAsImage(org.apache.pdfbox.pdmodel.PDDocument document,
                                                   org.apache.pdfbox.rendering.PDFRenderer expectedPdfRenderer,
                                                   int pageIndex,
                                                   Environment environment)
                                            throws IOException

Throws:

IOException

getResult

public T getResult()