Architecture

ANNIS is a web-based search and visualization architecture for multi-layer corpora. ANNIS consists of two major components: a backend service and a web front-end.

Backend Service

The service is part of the graphANNIS project and provides a REST API to query and manage corpora. GraphANNIS directly implements all needed functionality without the need of an external database. See the graphANNIS documentation for more information about the REST service.

Web Front-end

The ANNIS front-end is a web application implemented in Java and the Vaadin framework and runs in a normal browser (we recommend Mozilla Firefox). The server running the web-application communicates with the backend service via a REST interface. Per default, the web front-end includes a released version of the backend service and starts an instance of it. The front-end uses Spring Boot internally and bundles it own server, so you don't need a Tomcat or Jetty installation to run it.

Building

ANNIS uses Maven3 as build tool. Maven itself is based on Java and should run on every major operating system. You have to download and install the appropriate version for your operating system from http://maven.apache.org/download.html before you can build ANNIS. Maven will download all needed dependencies from central servers on the first build so you will need to have a working internet connection. The dependencies are cached locally once their are downloaded.

When you have downloaded or checked out the source of ANNIS the top-level directory of the source code is the parent project for all ANNIS sub-projects. If you want to build every project that is part of ANNIS just execute

cd <annis-sources>/
mvn install

This might take a while on the first execution. mvn clean will remove all compiled code if necessary.

If you only want to compile a sub-project execute mvn install in the corresponding sub-directory. Every folder with a sub-project will have a pom.xml file. These files configure the whole build process. The Maven documenation contains detailed explanations of the structure and possible content of the configuration files.

Some sub-projects don't provide a library but will produce a zip or tar/gz- file when they are compiled. These assembly steps (see Maven Assembly documentation) are automatically invoked on mvn install.

Using an IDE

While you can use any text editor of your choice to change ANNIS and compile it completely on the command line using Maven, a proper IDE will be a huge help for you. You can use any IDE which has a good support for Maven. The ANNIS main developers currently recommend Eclipse or Visual Studio Code for devlopment.

Running the service

The annis-gui project contains two build artifacts:

  • annis-gui-<version>-server.jar and
  • annis-gui-<version>-desktop.jar

You can execute both JAR-files to run the front-end and the embedded REST service.

cd <unzipped source>/annis-gui/
java -jar target/annis-gui-<version>-server.jar

The desktop variant will open a simple window with a link to the URL on which the service is listening.

After starting the service, you can access the site under http://localhost:5711/. The service can be stopped by pressing CTRL+C.

Making a new ANNIS release

Introduction

You must have mdBook installed to make a release. Otherwise the documentation can't be created.

Release Process

Initialization phase

  1. Start the release process by executing mvn gitflow:release-start for a regular release (branched from develop) or mvn gitflow:hotfix-start for a hotfix that is branched from master. The command will ask you for the new version number, use semantic versioning.
  2. Add new changelog entries, if some important information is missing add an entry to the changelog. When the changelog is up-to-date, execute
mvn -N keepachangelog:release cff:create cff:third-party-folder

and commit your changes. This will also update the citation file (CITATION.cff) and the contents of the THIRD-PARTY folder.

Testing cycle

  1. Build the complete project with tests.
mvn clean install
  1. Do manual tests. If you have to fix any bug document it in the issue tracker, update the changelog and start over at step 1. If no known bugs are left to fix go to the next section.

Finish phase

  1. Finish the release by executing either mvn gitflow:release-finish for regular releases or mvn gitflow:hotfix-finish for hotfixes.
  2. Release the staging repository to Maven Central with the Nexus interface: https://oss.sonatype.org/
  3. Create a new release on GitHub including the changelog. Upload the binaries from Maven repository to GitHub release as well.

A new version of the User and Developer Guide will be deployed by the GitHub Actions CI.

Create new query builder

A query builder is a class that

  1. implements the QueryBuilderPlugin interface
  2. has the @PluginImplementation annotation

When implementing the interface you have to provide a short name, a caption and a callback function that creates new Vaadin components. You get an object of the type QueryController which you can use to set new queries from your component.

A query builder plugin must be either registered in the addCustomUIPlugins() function of the SearchUI (if the plugin is part of the annis-gui project) or must be added to a JAR-file that is located at one of the following locations:

  • the plugins folder inside the deployed web application
  • the path defined in the ANNIS_PLUGINS environment variable

Please also note that it is possible to configure a default query builder for an instance. Further information can be found in the User Guide.