How to use Ktor comparison sample

There are lots of popular web frameworks which you can use with GroupDocs Comparison library. One of the most modern and powerful Kotlin frameworks is Ktor. This article describes example of using Ktor Framework together with modern and powerful GroupDocs.Comparison API for comparing Word, Excel, PowerPoint, Pdf documents, photos and much more. The example is completely free to use and available on GitHub

Which technologies will be used

  1. Kotlin - A modern programming language that makes developers happier. Fully compatible with Java libraries.
  2. Ktor - Modern, Open Source, free, and fun Web Framework.
  3. Netty - Embedded into Ktor version of web server.
  4. GroupDocs.Comparison API - modern comparison library for Java, Kotlin and .NET
  5. Koin - Smart Kotlin injection library
  6. Logback - Universal logging system

Common structure of the project

  • config - Kotlin classes for mapping application and comparer configurations
  • di - Koin dependency injection modules
  • manager - abstract layer for wide used operations
  • model - request/response Kotlin classes
  • modules - url mappings and controllers to process requests
  • status - handlers to process exceptions
  • usecase - business logic

Additional important files

In sources:

  • Application.kt - application entry point
  • Defaults.kt - default values to be used if they are not configured

In resources:

  • application.conf - application configuration
  • comparer.conf - sample configuration
  • logback.xml - configuration of logging system

Entry point or how to run the sample

Using IDE

The entry point of the application is in a file Application.kt. There is a main function that must be run to start the application. You can do it within your favourite IDE.

Using command line

To run the application, open command line in Ktor sample directory and run next command

The command will run application using gradle wrapper, that is in gradle directory. Open http://localhost:8080/comparer in web browser.

You can easily create archive for distribution. To do it, just build the application with the next command

After that, you can go to .\build\distributions\ directory and find next distribution files:

  • comparison-ktor-22.11.tar

There are two directories inside them, lib with all application libraries and bin with scripts to run the app

Key places inside the application

Mappings and controllers

Package mudules contains some amount of sub packages. Each of them is a single request. For example, lets review sub package compare. The package has two files:

  1. CompareModule.kt - contains url mapping, will be called when request to compare documents will be sent from browser

    All, the class does: catches request, extracts parameters, calls controller and returns response object

  2. CompareController.kt - combining usecases results and parameters creates response object. First of all, using PathManager it checks that request paths are inside allowed directories

    Then, the controller checks, are requested files supported by comparison application. For this purpose it uses special usecase, that is called AreFilesSupportedUseCase

    The next step is to create path to the file, in which will be saved the result document of the comparison process

    Temporary files are used to minimize usage of RAM. It is easy to change app so that it will not save any files. Temporary directory can be specified in comparer.conf. By default, system temp directory is used.

    Now, the controller uses CompareDocumentsUseCase to compare source and target documents and to save the result file. Also, the usecase returns list of changes, that will be set into response object later

    The next usecase, which is called RetrieveLocalFilePagesStreamUseCase, is used to get input stream for each page of the result document

    And the last step is to map groupdocs ChangeInfo objects into response models, which will be sent as a result

What is usecases and how to use them

In common - usecase is a single thin that can be done. Usually, it contains business logic, has only one aim and is easy to test. All usecases in the project are configured to be created by Koin. Some usecases have constructor parameters, which are injected when Koin will create instance of usecase. As an example, let’s overview CompareDocumentsUseCase

The usecase has invoke operator overridden, so that it can be called using it’s object as a function. The only aim of the usecase is to compare source and target documents and to write the result to provided output stream.

As a parameters it takes paths of source and target documents and output stream, in which the result should be saved. Optional parameters are passwords for each document.

To compare documents we use powerful and modern GroupDocs.Comparison for Java/Kotlin library. With the library the comparison process is very easy.

First step is to create object of Comparer class. Load options are used to provide password for the document. Also, with options you can configure Comparer to use first parameter not as path to the source document (streams are also available) but to use it as a source text for comparison process. Furthermore, there is an option to configure directories with specific fonts. Comparer implements Java Closeable interface, so it is very easy to free used memory.

Inside use block we call add method of comparer to add second document or text for comparing. The method takes the same LoadOptions parameter. Moreover, GroupDocs.Comparison API supports multi-document comparison, so that you can add more than one target document.

The last thin is to call compare method, that will start comparison process. As you can see, the method takes CompareOptions object as a second argument. Here are used just a few options. It is configured to show content, that was deleted in target document, to recognise and process styles changes and to provide coordinate of each change in the result document. There are much more options available. For example, you can enable generating summary page, change comparison sensitivity level, enable/disable each type of change, configure it’s style in result document and so on. More options you can find in the documentation. At the end of the apply block we use comparer.getChanges() method to get list of changes.

Dependency injection

One more important thing in the application is an object ModulesInjection. It is used to give Koin information about classes and interfaces, which it should create or inject. Here are controllers, usecases and managers. Adding any new class, that must be injected by Koin, it is highly important to specify it in one of modules here.

Get a Free API License

Lots of comparison settings, for example, generating summary page, sensitivity of comparison and so on, are available only with license. You can get a free temporary license in order to use the API without evaluation limitations.


The article describes GroupDocs.Comparison sample, that was implemented using Ktor web framework. There are more samples of using GroupDocs.Comparison for Java/Kotlin on our GitHub page. They are completely free and open to use them as a core of your own application for comparing photos, Excel, Word, code files, PowerPoint Presentations and much more supported file formats.

For more details, options, and examples, you can go through the documentation and GitHub repository. Reach us on the forum for your queries.

See also