API Sample

Summary

This sample illustrates how the API (Application Programming Interface) can be used to run the DITA Comparison.

Depending on which product you have downloaded the sample directories will contain content for either the Java or .NET platforms (e.g. Java or C# source code). This documentation will discuss both APIs.

In both platforms there are four main API classes for accessing the comparison (.NET classes hava an additional 'DotNet' suffix):

DitaTopicCompareFor accessing the DITA topic comparison.
DitaMapfileCompareFor accessing the DITA map file comparison.
DitaMapTopicsetCompareFor accessing the DITA map based topic-set comparison.
DitaCompareFor accessing the map-file, map-topicset and topic comparisons, through a simplified interface.

Command-line Arguments

The samples for each platform support the use of a command-line argument from the entry-point class to control which DITA Compare API classes are used. The arguments used are included in the sample summary tables.

Java API

There are 5 Java classes in the Java API sample:

Sample ClassCorresponding API ClassCommand-line argument
TopicCompare.javaDitaTopicComparetopic
MapfileCompare.javaDitaMapfileComparemapfile
MapTopicsetCompare.javaDitaMapTopicsetCompare (1)mts
MapTopicsetCompareInPlace.javaDitaMapTopicsetCompare (2)mts-inplace
GeneralCompare.javaDitaCompare(empty)
Main.java(none - the main JAR class)(not-applicable)

Using Ant

This sample can be built and run via an Apache Ant build script, by issuing the following command: ant run The script runs the sample for each command-line argument. Further, Ant commands that are available are summarised in the following table.

ant cleanTo remove all files generated by the Ant script.
ant compileCompiles the four classes into the classes directory.
ant jarConstructs the api-sample.jar file from the compiled classes.

.NET API

This sample is a .NET console application, DitaFileCompareApi.

There are four C# classes:

Sample ClassCorresponding API ClassCommand-line argument
TopicCompare.csDitaTopicCompareDotNettopic
MapfileCompare.csDitaMapfileCompareDotNetmapfile
MapTopicsetCompare.csDitaMapTopicsetCompareDotNetmts | mts-inplace
GeneralCompare.csDitaCompareDotNet(empty)
Program.cs(none - the startup class)(not-applicable)

Using Visual Studio

To open and run the sample in Visual Studio, open the DitaFileCompareApi.csproj project file, select the project in Solution Explorer and press Run or <F5>. Note: command-line arguments can be set as Debug properties in the project properties dialog.

From the command line (without Visual Studio)

Invoke rundemo.bat from the command-line to build the DitaFileCompareApi project using msbuild. The resulting DitaFileCompareApi.exe is then executed along with any command-line arguments supplied when the batch file was invoked.