App Note Framework

Introduction

This application note explains how to get started with all of our KOS Java application notes. It creates the app note framework used in many other examples. The code for all app notes in this section are on GitHub (you must be signed into GitHub to view this code repository).

Prerequisites

There’s a lot of code (yeah!) in these application notes. As such, before beginning, you should have Studio installed and know how to create and run a simple KOS application. If you don’t, please follow the instructions on these pages first:

Set up your development environment: Get Started
Create your first KOS application: Hello World Tutorial

Overview

This application note gives the starting point for the remainder of the app notes in this site’s section. Some details are missing because they are given in the prerequisite Hello World tutorial.

App Notes

After creating the Java project described in this article you can check out the other app notes in any order.

Tip

To help with the learning process, we suggest that, as you follow along with each app note, you create code in your custom project. However, if you want a shortcut, you can simply pull the code down from the GitHub repo (see link at top of this page).

Create Common Files

There are six files used in every app note found in this chapter:

pom.xml
MyKosApp.java
Module.java
descriptor.json
assembly.xml
quickbuild.bat or quickbuild.sh

Follow the instructions in this section to create them.

1) POM file

In your favorite IDE, create a new Maven project with the following POM file contents:

Set the KOS version

Be sure to set the KOS version by filling in the KOS_VERSION placeholder in the POM file.

Important

The KOS version set in this POM file MUST MATCH that selected when creating your KOS Studio runnable image. If those do not match, then your KOS application will not run.

pom.xml file

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- ====== Basics =============================================================== -->

    <groupId>com.tccc.kos.examples</groupId>
    <artifactId>kos-java-examples-core</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <name>KOS api-core examples</name>

    <!-- ====== Properties =========================================================== -->

    <properties>
        <kos-bom.version>KOS_VERSION</kos-bom.version>
        <kos-kab-maven-plugin.version>1.2.3</kos-kab-maven-plugin.version>
        <java.version>17</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <apache-commons-lang3.version>3.13.0</apache-commons-lang3.version>
        <lombok.version>1.18.28</lombok.version>
        <maven-assembly-plugin.version>3.6.0</maven-assembly-plugin.version>
    </properties>

    <!-- ====== Dependency Management ================================================ -->

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.kosdev.kos.sdk.bom</groupId>
                <artifactId>kos-bom</artifactId>
                <version>${kos-bom.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- ====== Dependencies ========================================================= -->

    <dependencies>
        <dependency>
            <groupId>com.kosdev.kos.sdk.api</groupId>
            <artifactId>api-core</artifactId>
        </dependency>
        <dependency>
            <groupId>com.kosdev.kos.sdk.api</groupId>
            <artifactId>api-dispense</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>${apache-commons-lang3.version}</version>
        </dependency>
    </dependencies>

    <!-- ====== Code Repositories ==================================================== -->

    <repositories>
        <repository>
            <id>kosdevcode</id>
            <name>KOS Code Repository</name>
            <url>https://maven.pkg.github.com/kosdev-code/kos-maven</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
                <checksumPolicy>fail</checksumPolicy>
            </releases>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>always</updatePolicy>
                <checksumPolicy>fail</checksumPolicy>
            </snapshots>
        </repository>
    </repositories>

    <!-- ====== Plugin Repositories ================================================== -->

    <pluginRepositories>
        <pluginRepository>
            <id>kosdevcode</id>
            <name>KOS Plugin Repository</name>
            <url>https://maven.pkg.github.com/kosdev-code/kos-maven</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
                <checksumPolicy>fail</checksumPolicy>
            </releases>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>always</updatePolicy>
                <checksumPolicy>fail</checksumPolicy>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

    <!-- ====== Build ================================================================ -->

    <build>
        <plugins>
            <!-- Add the dependencies and then package the output into a ZIP file -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>${maven-assembly-plugin.version}</version>
                <executions>
                    <execution>
                        <id>make-jar-with-dependencies</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <configuration>
                            <descriptorRefs>
                                <descriptorRef>jar-with-dependencies</descriptorRef>
                            </descriptorRefs>
                        </configuration>
                    </execution>
                    <execution>
                        <id>make-zip-file</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <configuration>
                            <descriptors>
                                <descriptor>assembly.xml</descriptor>
                            </descriptors>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <!-- Convert the ZIP file to a KAB file -->
            <plugin>
                <groupId>com.kosdev.kos.maven</groupId>
                <artifactId>kos-kab-maven-plugin</artifactId>
                <version>${kos-kab-maven-plugin.version}</version>
                <executions>
                    <execution>
                        <id>make-kab-file</id>
                        <phase>package</phase>
                        <goals>
                            <goal>kabtool</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

2) MyKosApp class

Create the following main KOS application class:

MyKosApp class

package com.example;

import com.example.afirst.AFirstModule;
import com.tccc.kos.core.service.app.BaseAppConfig;
import com.tccc.kos.core.service.app.SystemApplication;
import lombok.extern.slf4j.Slf4j;

@Slf4j (1)
public class MyKosApp extends SystemApplication<BaseAppConfig> {

    private Module module;

    public void initModule() {
        module = new AFirstModule(); (2)
    }

    @Override
    public void load() {
        log.info("> ====== BEGIN =========================================");
        log.info("> MyKosApp.load()");
        initModule();
        getCtx().add(module);
        module.init(); (3)
    }

    @Override
    public void start() {
        log.info("> MyKosApp.start()");
        module.run(); (4)
        log.info("> ====== END ===========================================");
    }

    public static void main(String[] args) { (5)
    }
}

1	We use Lombok everywhere to simplify our examples
2	This is the only line in the `MyKosApp` class that changes from app note to app note. We’ll create this file later on this page.
3	The specific app note module is initialized
4	The specific app note module is executed
5	This dummy method only exists to give the IDE’s debug configuration a fake entry point

3) Module interface

The Module interface defines how a particular application note interfaces to the main KOS application:

Module interface

package com.example;

public interface Module {

    void init(BeanContext beanContext); (1)

    void run(); (1)
}

1	Every app note module in this series implements these methods

4) Descriptor file

Copy the following file into your project’s root directory:

descriptor.json file

{
  "kos": {
    "app": {
      "appClass": "com.example.MyKosApp", (1)
      "appId": "system" (2)
    }
  }
}

1	Your KOS application’s entry point
2	Indicates this is a KOS "system" app

5) Assembly file

Save here, copy the following file into your project’s root directory:

assembly.xml file

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.1.1"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.1.1 http://maven.apache.org/xsd/assembly-2.1.1.xsd">
    <id>app</id>
    <baseDirectory>/</baseDirectory>
    <formats>
        <format>zip</format>
    </formats>
    <files>
        <file>
            <source>descriptor.json</source>
            <outputDirectory>/</outputDirectory>
        </file>
        <file>
            <source>${project.build.directory}/${project.artifactId}-${project.version}-jar-with-dependencies.jar</source>
            <outputDirectory>lib</outputDirectory>
        </file>
    </files>
</assembly>

6) Quick build script

Copy one of the following files into your project’s root directory, based on your computer’s operating system:

quickbuild.bat file (for Windows systems)

mvn install --no-snapshot-updates -DskipTests -T4

quickbuild.sh file (for Mac and Linux systems)

#!/bin/bash
mvn install --no-snapshot-updates -DskipTests -T4

First App Note Code

In this first application note, we’re going to look at some KOS variables.

First app note module

Create the following class:

AFirstModule class

package com.example.afirst;

import com.example.Module;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

@Slf4j
public class AFirstModule implements Module {

    @Override
    public void init(BeanContext ctx) {
        log.info("> AFirstModule.init()");
    }

    @Override
    public void run() {
        log.info("> AFirstModule.run()");
    }
}

Project structure

Your project should look like this:

Figure 1. Project structure

You code should now compile, creating the kos-java-examples-core-1.0.0.kab output file.

Debug Program

Execute this program by performing these steps:

Using Studio, create an image for this project
Select the kos-java-examples-core-1.0.0.kab file as a local artifact
In the IDE, set up a debug configuration (see How To Debug Code)
Debug the application inside your IDE

Logs

You should see log output similar to the following:

AFirstModule output

> ====== BEGIN =========================================
> MyKosApp.load()
> AFirstModule.init()
> MyKosApp.start()
> AFirstModule.run()
> ====== END ===========================================

Debug variables

Now, set a breakpoint at one of the log statements and view the following variables:

Figure 2. KOS path manager

Figure 3. KOS core bean context

Figure 4. System app bean context

Note that KosCore.systemCtx.parentContent refers to the KosCore.ctx, meaning that the system application context can access the core context.

Summary

In this article, we set up the project that we’ll use in all future application notes in this chapter. You can now view the other app notes in any order you’d like.