Java API Guide

ConversionQA provides a Java API that allows users to integrate the ConversionQA product into their application.

Getting Started

To use the ConversionQA Java API, you need to add the provided jar file as a dependency to your Java project.

deltaxml-conversion-qa-x.y.z.jar

(replace x.y.z with the major.minor.patch version number of your release e.g. deltaxml-conversion-qa-1.2.3.jar)

In your Java source file, import classes from the package named:

com.deltaxml.conversionqa

Licensing

The product has two methods of specifying the license location; automatic and manual. Please also see the Licensing Guide for full details of DeltaXML licensing, including license types and their usage.

Automatically Locate License

To allow ConversionQA to try to locate a license file automatically, you do not have to call any specific method, instead simply construct a ConversionChecker object and use it.

ConversionQA will then look for and select the first license file it finds that matches the filename “deltaxml-conversion-qa.lic" in the following places in the order listed: -

1. The same directory as the jar or exe/dll files in your installation

2. Your home directory

3. As a resource on your java classpath

Manually Set License

Use the method AddLicenseFile on the ConversionChecker class to manually specify the license file name and location. This allows you to choose where the license file is located and to give it a different name if desired.

ConversionChecker conversionChecker = new ConversionChecker();
conversionChecker.addLicenseFile(new File("insert_your_path/deltaxml-conversion-qa.lic"));

Redistribution Licensing

A Redistribution (OEM) license allows ConversionQA to be embedded in a specified application which is then licensed to end users. The terms of this Redistribution license will depend on the nature of the application and the volume of end users to whom it will be deployed. The Redistribution license is integrated at compile time into the application.

To embed your redistribution license in your java source code, you will be given a code snippet containing the redistributable license contents as an array of longs, and you pass the array into the setRedistributionLicenseContent method.

long[] licenseKey = < !insert license key here! >
ConversionChecker conversionChecker = new ConversionChecker();
conversionChecker.setRedistributionLicenseContent(licenseKey);

The ConversionQA Checker Class

ConversionChecker is the public class that you must instantiate to control ConversionQA.

ConversionChecker conversionChecker = new ConversionChecker();

Once you have created a ConversionChecker object, you then call methods to set the inputs, run the ConversionQA check, and finally fetch the result.

Inputs

ConversionQA supports a number of input formats. See the Input Types guide page for full details of each available format.

ConversionQA currently supports three formats of input which are listed below with the corresponding java class which you use to pass into the checkConversion method of ConversionChecker.

The following snippet shows an example of checking the conversion between a Word document and an XML file.

File fileA = new File(your_dir, "document.docx");
File fileB = new File(your_dir, "document.xml");

DocxInput inputA = new DocxInput(fileA);
XMLInput inputB = new XMLInput(fileB);

ConversionChecker conversionChecker = new ConversionChecker();
ConversionCheckerResult result = conversionChecker.checkConversion(inputA, inputB);

Result Directory and Result Prefix

Use the method setResultLocation on the ConversionChecker class to manually specify the result directory location where you wish your result to be written to otherwise the result will be written to the working directory. Additionally, you can use the method setResultPrefix to specify a prefix for your result file name. This allows you to choose a unique identifier for each result file.

conversionChecker.setResultLocation(new File("insert_your_dir_path"));

conversionChecker.setResultPrefix("prefix_here");

Getting the Result

The checkConversion method will return an object of type ConversionCheckerResult.

The ConversionCheckerResult class consists of two methods to check the conversion result.

isContentEqual

The ConversionCheckerResult.isContentEqual method returns a boolean value that represents the equality of the input documents. If the content of the two input documents is equal it returns true, and if the content of the two input documents is not equal it returns false.

getChangeReport

The ConversionCheckerResult.getChangeReport method returns a File object that holds the location of the output change report HTML file.

Progress Reporting

ConversionQA can report the progress through the stages of checking the conversion quality.

To use this functionality, you write a class that implements the ConversionCheckerProgressListener interface, and then pass an instantiation of your class into the addConversionCheckerProgressListener method of the ConversionChecker class.