Skip to content

How do I implement a new Qanary component using Java?

Jump to bottom
Dennis Schiese edited this page Mar 11, 2024 · 9 revisions

Create a Qanary Component from the provided Maven Archetype

Qanary is a methodology following the idea of a lean architecture of Question Answering systems and easy reuse of Question Answering services (c.f., see our publication for details). We call these services Qanary components. Here, we will create a Java component implemented using the Spring Boot framework using the Apache Maven Archetype mechanism.

To implement a Qanary component, there are just some simple requirements (you might also implement by yourself). However, a complete automated generation of a Qanary component written in Java can be triggered using the Qanary Maven Archetype in the project folder qanary_component-archetype/.

If you plan to implement a new Java component using the Qanary methodology, then you might use the provided Maven archetype (it generates a project skeleton) using the following steps.

Steps

Step 1

The easiest start is to use the prepared Maven archetype on your development machine. For this, first, you need to establish the foundations by building the required packages on your local machine by following the following steps (requirements: Java/JDK 17+ and Apache Maven 3+ installed):^1

git clone https://github.com/WDAqua/Qanary.git
cd Qanary
mvn install -Ddockerfile.skip -Dgpg.skip

This will install the Qanary core components in your local Maven repository, including the Maven archetype qa.qanarycomponent-archetype for creating new Qanary components. You will get an output similar to this:

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] qanary-component-archetype 1.5.0 ................... SUCCESS [  9.926 s]
[INFO] qa.commons 3.11.3 .................................. SUCCESS [02:29 min]
[INFO] qald.evaluator 1.0.6 ............................... SUCCESS [ 11.799 s]
[INFO] qa.pipeline 3.8.4 .................................. SUCCESS [ 27.511 s]
[INFO] qa.component 3.9.3 ................................. SUCCESS [  4.542 s]
[INFO] qanary-component-parent 0.1.2 ...................... SUCCESS [  0.001 s]
[INFO] mvn.reactor 0.1.1-SNAPSHOT ......................... SUCCESS [  0.602 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  03:24 min
[INFO] Finished at: 2024-02-28T15:25:20+01:00
[INFO] ------------------------------------------------------------------------

It is important to recognize the version of qanary-component-archetype. Here it is 1.5.0. If you have several Qanary Maven Archetype versions installed on your machine, then you will need this version later.

Step 2

In order to create a new wrapper for your Qanary component, execute the following command in your own project folder:

mvn archetype:generate \
       -DarchetypeGroupId=eu.wdaqua.qanary.component \
       -DarchetypeArtifactId=qa.qanarycomponent-archetype \
       -DarchetypeVersion=<current-archetype-version> \
       -DgroupId=eu.wdaqua.qanary.component \
       -DartifactId=<your-project-name> \
       -Dversion=<your-project-version> \
       -Dpackage=<your-source-package> \
       -Dclassname=<your-component-name> \
       -DinteractiveMode=false

Instead of current-archetype-version insert the current version of the archetype if you have several versions installed on your machine (as mentioned earlier). Otherwise, you can delete this line.

Example

The following command will generate a project in the folder qanary_component-mycomponent which is a class MyComponent in the package eu.wdaqua.qanary.mypackage that uses the Qanary Maven archetype:

mvn archetype:generate \
       -DarchetypeGroupId=eu.wdaqua.qanary.component \
       -DarchetypeArtifactId=qa.qanarycomponent-archetype \
       -DarchetypeVersion=1.5.0 \
       -DgroupId=eu.wdaqua.qanary.component \
       -DartifactId=qanary-component-TYPE-xyz \
       -Dversion=0.1.0 \
       -Dpackage=eu.wdaqua.qanary.component.mypackage \
       -Dclassname=MyComponent \
       -DinteractiveMode=false

Here, the typical name of an artifactId was used: qanary-component-TYPE-xyz. Where after the prefix qanary-component the type (purpose) of the component is mentioned, e.g., NED (Named Entity Disambiguator), QB (Query Builder), QE (Query Executor), etc. The last part (here: xyz) is the specific name of the component.

Notes
  • The value of artifactId will directly be used as folder name, too. However, as Maven Artifact IDs need to be written in lower case (see Maven Naming Conventions for details), it is automatically transformed to lowercase.
  • While receiving the message (...) org.apache.maven.archetype.exception.InvalidPackaging: Unable to add module to the current project as it is not of packaging type 'pom' you might not have switched to a specific project folder.

The example will create the following structure:

.
├── Dockerfile
├── pom.xml
├── README.md
└── src
    ├── main
    │   ├── java
    │   │   └── eu
    │   │       └── wdaqua
    │   │           └── qanary
    │   │               └── component
    │   │                   └── mypackage
    │   │                       ├── Application.java
    │   │                       └── MyComponent.java
    │   └── resources
    │       ├── banner.custom-template.txt
    │       ├── component-description.custom-template.ttl
    │       ├── config
    │       │   └── application.properties
    │       ├── queries
    │       │   ├── fetchRequiredAnnotations.rq
    │       │   ├── README.md
    │       │   └── storeComputedAnnotations.rq
    │       ├── README.md
    │       └── templates
    │           └── description.custom-template.html
    └── test
        └── java
            └── eu
                └── wdaqua
                    └── qanary
                        └── component
                            └── mypackage
                                └── QanaryServiceControllerTest.java

19 directories, 14 files

This code out of the box will give you a Qanary component (i.e., a Web service) with a RESTful interface aligned to the Qanary methodology. While being executed, it automatically registers itself at the configured Qanary pipeline component, so that your Question Answering system access it automatically.

Follow the instructions inside the code and configuration files.

Step 3

Configure your new Qanary component. Implement your intended functionality within the creation Qanary component. Build the Qanary component using mvn clean install inside the created folder.

Configuration

The general configuration file for any component is application.properties. Important variables are the following:

  • server.port, defining at what port the web service starts
  • spring.application.name, defining the recognizable name of your Qanary component that will be seen/used in the Qanary pipeline
  • spring.boot.admin.url, defines where the web service tries to register itself to a Qanary pipeline,
    • e.g., while having started a Qanary pipeline locally from the provided implementation, you might define spring.boot.admin.url=http://localhost:8080

You have to change the variables accordingly. You can look at any other component that was already implemented -- however, a good example would be this very simple exemplary component. A good choice is to take a component that has the same or similar functionality as you plan for your own Qanary component.

Implementation Methodology

See the helping notes inside the created Qanary component to get a better impression of how to implement your intended functionality.

For implementing a Qanary component using Python, see this tutorial.

Clone this wiki locally