Hello world application

The code for this tutorial is available on GitHub

https://github.com/ADAMMA-CDHI-ETH-Zurich/CLAIDTutorial01

This tutorial will teach you how to set up a simple CLAID hello world application, consisting of one Module that will print "Hello world" upon initialization. The following picture shows what will be achieved in this tutorial.

Prerequisites

Please make sure you have completed the previous part of this tutorial and CLAID was installed successfully. Furthermore, make sure that the ModuleAPI package was installed.

Installing the JavaCLAID package

Java support is added to CLAID applications via a separate package called JavaCLAID. This package works for building standalone Java applications, e.g. on a regular PC (Windows, macOS and Linux), or for building Android applications. In this tutorial, we only cover the first case. Building Android applications with CLAID is discussed in a separate tutorial. Make sure you install the package "JavaCLAID" either using the claid manager, or manually.

Installing the JavaCLAID package

Installation with CLAID manager Linux & MacInstallation with CLAID manager WindowsManual installation

If you have set up the requirements for the CLAID manager tool during tutorial series 01, you can use it to install the package easily:

claid install JavaCLAID

If you have set up the requirements for the CLAID manager tool during tutorial series 01, you can use it to install the package easily: Please do not use powershell, as the syntax of using the CLAID manager with powershell is slightly different.

%claid% install JavaCLAID

Clone the JavaCLAID repository into the "packages" folder of the CLAID installation directory:

git clone https://github.com/ADAMMA-CDHI-ETH-Zurich/JavaCLAID $CLAID_PATH/packages/JavaCLAID

Note: Under Windows, replace $CLAID_PATH with %CLAID_PATH%
If you want to install other packages manually, make sure to change the link to the github repository as well as the path $CLAID_PATH/packages/PACKAGE_NAME to match your required package name.

Creating a new Java application using CLAID

In the following, we provide step-by-step explanations on how to create a new java application using CLAID. If you want to learn how to integrate CLAID into existing applications, please click here.

1^st Creating the project

Please create a new directory in your desired location and give it any name, for example "MyCLAIDApp". We call this directory the project directory. Now, we need to populate the folder with the required files. This can be done easily with the claid manager tool using the instructions below. Alternatively, you can simply clone our template repository, which contains the files required for a simple Java application (CMake and Java source files). We recommend to open the project directory in Visual Studio Code, and use the terminal window provided by VS Code (note: make sure that under Windows you open a regular terminal window, not powershell).

Create files and see expected folder structure.

Using CLAID managerWithout CLAID managerExpected folder structure

Open a terminal or anaconda prompt in your project directory and run the following command:

Linux & macOS:

    claid create java_application here

Windows (do not use powershell):

    %claid% create java_application here

Please do not use powershell under windows, as the syntax shown above does not work with powershell.

Instead of "here", you can also specify the full path to your project directory.

Clone our template repository and extract the files into your project directory.

2^nd Adding code

After having set up the general project structure, we will now implement our first CLAID Module. This Module has the purpose of printing "Hello world" to the console after being loaded by the CLAID runtime. Please see the corresponding Java code in the following, and be sure to check out the detailed step-by-step explanation below. In general, we recommend defining each Module in it's own separate file.

Code for your first CLAID application

MyModule.javaMain.java

Add this code to MyModule.java in the java directory.

package HelloWorld;

import JavaCLAID.Module;

// When creating a Module, inheriting from Module is mandatory.
class MyModule extends Module;
{
    void initialize()
    {
        System.out.println("Hello world");
    }
};

Add this code to Main.java in the src directory.

import JavaCLAID.CLAID;

public class Main 
{
    static
    {
        System.loadLibrary("JavaCLAID");
    }

    public static void main(String[] args)
    {
        CLAID.addModule(new MyModule());
        CLAID.start();
    }
}

Step-by-step explanation of code

MyModule.javaMain.java

package HelloWorld;

Marks this class as part of the package "HelloWorld".

import JavaCLAID.Module;

This imports the Module class, which is part of JavaCLAID. It provides all the functionalities required to implement Modules, for example Communication.

class MyModule extends Module

By this, we create a new class "MyModule" which inherits from Module. Therefore, MyModule is a CLAID Module which can communicate with other Modules.

void initialize()

This function will be called when the Module is started by CLAID.

System.out.println("Hello world");

This will print "Hello world" to the terminal.

import JavaCLAID.CLAID;

This imports the functionalities provided to Java by JavaCLAID. This allows you to start and stop CLAID, add Modules and load XML configurations.

public class Main 

This adds a new class called "Main", which will be the main entry point into our applications. You can also choose a different name if you want, but make sure to rename the file Main.java accordingl aswell.

static
{
    System.loadLibrary("JavaCLAID");
}

This loads the JavaCLAID shared library, allowing Java programs to use functionality provided by CLAID. Details about JavaCLAID can be found in the section "Building JavaCLAID" below.

public static void main(String[] args)
{
    CLAID.addModule(new MyModule());
    CLAID.start();
}

The main function is the main entry point of the application. Here, we create a new instance of our custom Module "MyModule" and add it to CLAID. Afterward, we start CLAID, which in return will call the initialize function of MyModule.

Including required packages

In order to use CLAID in Java, you have to compile the CLAID source code into a shared library, which can then be loaded by the Java application at runtime. To build this shared library, we use CMake and specify the build instructions in a file called CMakeLists.txt. This file should be existing in your project directory at this point. During compilation, this file includes another file called "CLAIDPackageList.txt", where you can specify CLAID packages to include. If you want to include packages, e.g. for data collection or machine learning deployment into your application, you first have to install required packages, e.g., using the claid manager, and then add them to the CLAIDPackageList.txt using the corresponding include statement:

CLAID_Include(PackageName)

For this tutorial, we require two CLAID-packages. First, ModuleAPI, which implements the basic functionality of CLAID. Second, the JavaCLAID package, which adds support for Java to CLAID. Please add the following two lines to the CLAIDPackageList.txt:

CLAID_Include(ModuleAPI)
CLAID_Include(JavaCLAID)

Building the JavaCLAID library

You can now build the JavaCLAID shared library, which then can be used from a java application. Usually, you only have to do this only once in the beginning, but please note, that whenever you want to include or exclude CLAID packages, or add new functionality or make changes to an existing package, you have rebuild this library accordingly. You can easily build it using the CLAID manager, or manually using cmake and make. In this tutorial, we show both options, however in subsequent tutorials we will only use the CLAID manager for building applications.

Using CLAID manager (cross-platform)LinuxMacWindows

On Linux & macOS:

claid build

On Windows (do not use PowerShell !):

%claid% build

Please open a terminal in the project directory (e.g., right click in the directory and choose open with). Afterwards, execute the following commands:

cmake .
make -j

Please open a terminal in the project directory. Afterwards, execute the following commands:

cmake .
make -j

Please open the windows commandline (or PowerShell) in the project directory. You can also use shift + Right click in the directory, to open the commandline directly in this directory.

Afterwards, enter the following commands:

cmake .
cmake --build . 

Running the Java application.

Open the project directory in a Java IDE of your choice. We recommend either using eclipse or Visual Studio Code. For the latter, make sure to install the VS Code java package.

If your build failed, check here for a list of common issues.

Test