Getting Started with the Java API

Setup

To use the Java API, make sure you have Java SE version 8 (or later) installed. If you do not already have Java installed, you can download it from Oracle.
DITA Merge is packaged as a zip file. Unzip this and it will contains various JARs, described below, and if you have an evaluation release there should be a license file as well. If you have purchased DITA Merge, follow the instructions in the Licensing Guide to setup your license file.
Include deltaxml-dita-merge-x.y.z.jar on your classpath in the same way you would with any other Java library. If you leave the JARs all together in the same directory, this will be sufficient to run DITA Merge. If you plan on moving JARs around, you may need to modify your classpath to explicitly include the others.

x.y.z represents the major.minor.patch version number of your release.

deltaxml-dita-merge-x.y.z.jar	This JAR contains the main DITA Merge API classes and associated resources (such as Java filters).
deltaxml.jar	DITA Merge is build on top of XML Compare and requires its JAR to work.
resolver.jar	This modified version of the Apache catalog resolver is needed when using catalogs through the deltaxml-dita-merge-x.y.z.jar API. Please see Catalog Resolver Customizations for further details of the modifications we have made.
flexlm.jar EccpressoAll.jar	These JAR files are required for the Flexera based licensing capabilities introduced in DITA Merge 2.2 and later releases. They should always be included on the classpath.
saxon9pe.jar xercesImpl.jar xml-apis.jar icu4j.jar fastutil-8.4.2.jar	These JAR files are required by the client applications and are mandatory with merge packages. They must be included on the classpath.
gson-2.8.5.jar	This JAR file is required when Usage Logging is enabled.
istack-commons-runtime-3.0.12.jar, javax.activation-1.2.0.jar, jaxb-api-2.3.1.jar, jaxb-runtime-2.3.6.jar	These JAR files are required when Usage Logging is enabled and you’re using Java 11+

Running a Merge

To run a concurrent merge from the Java API, it's this easy, as long as you remember to change the x_y_z version when you are using a different release:

JAVA

// Setup Input and Output files
File base = new File("../DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits.xml");
File edit1 = new File("../DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-anna.xml");
File edit2 = new File("../DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-ben.xml");
File out = File.createTempFile("dita-merge-example-", ".xml");

// Create merger object
ConcurrentMerge cm = new ConcurrentMerge();

try {
	// Set the common ancestor
	cm.setAncestor(base, "base");

	// Add the other versions
	cm.addVersion(edit1, "edit1");
	cm.addVersion(edit2, "edit2");

	// Run the "extraction" to output the merged result
	cm.extractAll(out);
} catch (FileNotFoundException | DifferingOrderedAttributesException |
		 DifferentRootElementException | LicenseException | UnorderedDuplicateKeysException |
		 UnorderedElementContainingPCDATAException | InvalidInputException e) {
	e.printStackTrace();
}

If you're doing a three-way concurrent merge (i.e. merging two files, with a common ancestor) it's even easier with ThreeWayMerge:

JAVA

// Setup Input and Output files
File base = new File("../DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits.xml");
File edit1 = new File("../DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-anna.xml");
File edit2 = new File("../DeltaXML-DITA-Merge-x_y_z_j/samples/data/four-edits-ben.xml");
File out = File.createTempFile("dita-merge-example-", ".xml");

// Create merger object
ThreeWayMerge twm = new ThreeWayMerge();

try {
	// Run merge with the inputs and output
	twm.merge(base, edit1, edit2, out);
} catch (FileNotFoundException | DoctypeChangeException | DifferingOrderedAttributesException |
		 DifferentRootElementException | LicenseException | UnorderedDuplicateKeysException |
    	 UnorderedElementContainingPCDATAException | InvalidInputException e) {
	e.printStackTrace();
}

Note: using the merge(...) shortcut method doesn't set the version names. If that is necessary, use the standard setAncestor(...) and addVersion(...) methods. For more details on versions and their names see the page Specifying Merge Versions.

Further Info

For further info, see our Javadoc and Samples and Guides for information on the various ways you can configure your merge.