Downloads
/
/
Tutorials

Hello World App

Introduction

In this tutorial you will:

  • Create your first KOS application

  • Configure this app in KOS Studio as a runnable "image"

  • Run this image using Studio’s built-in simulator

Preliminaries

Before beginning, you should have performed all three steps in the Get Started section.

Target Audience

All pages in this set of "T-1X" tutorials are for Java developers.

The source code for these Hello World tutorials is available on GitHub.

Create Maven Project

Perform the following steps to create your Maven project.

1) Create POM file

In a new directory named my-kos-app (or whatever you want), create a Maven project pom.xml file, then add the following snippet.

Starting 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 =============================================================== -->

    (1)
    <groupId>com.example</groupId>
    <artifactId>my-kos-app</artifactId>
    <version>1.2.3</version>

</project>
1 Enter your project’s required groupId, artifactId, and version, then any other optional fields such as name, description, etc.
Note

If you copy-and-paste any of these code snippets, you’ll need to manually remove the source code markers (1), (2), (3), etc.

Also, your IDE may complain about errors in your POM file. These should disappear once all sections are entered.

2) Add properties

Add a properties section to the POM file.

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

    <properties>
        <kos-bom.version>1.2.3</kos-bom.version> (1)
        <kos-kab-maven-plugin.version>1.4.5</kos-kab-maven-plugin.version>
        <java.version>17</java.version> (2)
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> (3)
        <lombok.version>1.18.28</lombok.version>
        <maven-assembly-plugin.version>3.6.0</maven-assembly-plugin.version>
    </properties>
1 Enter the KOS version you’re using.
2 KOS is built using Java version 17.
3 Specify file encoding to ensure the code builds the same on all systems.
Setting KOS version number

Remember to enter your desired KOS version into the <kos-bom.version> property.

3) Add dependency management

The KOS APIs are packaged into three separate libraries:

  • api-core (required)

  • api-dispense (optional)

  • api-freestyle (optional)

These libraries work together, and because of that, their individual versions must be matched. The kos-bom artifact, brought into the <dependencyManagement> section of the POM file, ensures that these versions are in sync:

Dependency management section
    <!-- ====== Dependency Management ================================================ -->

    <dependencyManagement>
        <dependencies>
            <!-- BOM for KOS SDK Code (core, dispense, freestyle) -->
            <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>

Note that the "type" is "pom" and the "scope" is "import".

4) Add dependencies

To add the actually dependencies, you specify one or more of the KOS APIs, but do not specify their versions, as those are defined in the kos-bom artifact. Here’s what it looks like to declare the api-core dependency:

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

    <dependencies>
        <dependency>
            <groupId>com.kosdev.kos.sdk.api</groupId>
            <artifactId>api-core</artifactId> (1)
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId> (2)
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
1 The core KOS SDK API.
2 Project Lombok library of annotations reduces boilerplate code, and is used throughout our examples.

5) Add repositories

Next, we must tell Maven where to find the KOS libraries. We do this in the repositories and pluginRepositories sections. Note that these reference the kosdevcode server ID from your settings.xml file.

Repositories sections
    <!-- ====== 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>

6) Add build

The "build" section describes how to turn your compiled Java code into the target KAB file.

KAB Files

You can learn more about KAB files on the Concept: KAB Files page. For now, just think of a KAB file as a collection of related files.
Build section
    <!-- ====== 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>
                    (1)
                    <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>
                    (2)
                    <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>
                    (3)
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>kabtool</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
1 The maven-assembly-plugin creates a JAR file that contains all third-party dependencies.
2 The maven-assembly-plugin uses the instructions in the assembly.xml file to create a ZIP file.
3 The kos-kab-maven-plugin turns that ZIP file into your application’s KAB file.
Maven Assembly Plugin

More information about the maven-assembly-plugin is found on the Apache website.

7) Assembly file

Create the following assembly.xml file in your project’s root directory. This file contains instructions for the maven-assembly-plugin referenced on the POM file.

Associated 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>

8) Descriptor file

Create the following descriptor.json file in your project’s root directory. It is referenced in the assembly.xml file.

The descriptor.json file
{
  "kos": {
    "app": {
      "appClass": "com.example.MyKosApp", (1)
      "appId": "system" (2)
    }
  }
}
1 Refers to your KOS application class, which we’ll create shortly.
2 For an app that extends SystemApplication (see next section), this must be "system".
Otherwise, it can be any name (alphanumeric and dash characters only).

Write Code

1) Create Java "App" class

  • Create a MyKosApp class that extends SystemApplication with config bean type BaseAppConfig

  • Choose a package name; we’re using com.example

  • Override the load() and start() methods

  • Other overridable methods include setConfig(), stop(), and unload()

  • Add Lombok’s @Slf4j annotation to the class which enables logging

  • Add a log statement to each method

It should look like this:

Initial contents of MyKosApp class
package com.example;

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

@Slf4j
public class MyKosApp extends SystemApplication<BaseAppConfig> {

    @Override
    public void load() {
        log.info("MyKosApp.load()");
    }

    @Override
    public void start() {
        log.info("MyKosApp.start()");
    }
}

2) Build the project

At this point you can build the code by running the following in the project directory:

$ mvn clean install

In the project’s target directory you will find a JAR file, a ZIP file, and a KAB file. This KAB file is what we’ll use in Studio.

The entire project directory should look like this:

java project directory
Figure 1. Java project directory

Run the Application

This section describes how to create, configure, and run the KOS application just written.

1) Create the image in Studio

Now that our Java application is written and bundled into a KAB file, we turn our attention to Studio.

a) Open the KOS Studio application

b) In the top-level menu bar, click on the "open image manager" button

studio app main window
Figure 2. Main window of KOS Studio

c) In this Images window, click on the "create new image" button

create new image button
Figure 3. Create a new executable image

d) In the popup dialog, enter a "Name" for this image, leave the "Parent Image" field blank, then click "Create":

create new image
Figure 4. Enter name for new image

e) Now the Images window shows an entry for the image you just created:

my hello world app image
Figure 5. My KOS App has been created

f) Close the Images window and return to the main Studio window.

main window showing new image
Figure 6. Main Studio window showing our newly created app
Image

In Studio, an image refers to a fully-configured KOS application that can be executed. It usually contains Java backend code, React frontend code, and configuration settings. In Studio, an image runs in either the built-in simulator or on a remote system.

2) Configuring the image

On the main Studio screen, click the gear icon associated with the image you just created, which opens up the configuration dialog:

configuration1
Figure 7. Image configuration

As you can see, there is a stack of six configuration items, also known as "cards":

  1. Sections

  2. File Mappings

  3. Layers

  4. Local Artifacts

  5. KOS Release

  6. Settings

The "KOS Release" item has red text, meaning that it needs attention.

Config Window

This configuration window is perhaps the most important part of KOS Studio. It gives you and your team the ability to create any number of runnable images, each with a wide variety of options. Much time will be devoted to using it.

3) Configure the KOS release

Our next step is to tell Studio which release of KOS we want to use, which will satisfy the current alert.

  • Click on the "KOS Release" card

  • Click on the "Configure new release" button

  • On the left-hand side, navigate and then select the desired KOS release

  • Give this selection a name and an optional note

configure release
Figure 8. Configure KOS release

  • Click the "Create" button

  • Then select the newly-created release

  • At this point, the "KOS Release" section is no longer red, meaning it is configured properly

  • Close the configuration window

4) Configure the local artifact

  • Re-open the configuration window by clicking the gear icon next to the "My KOS App" image name

  • Click on the "Local Artifacts" card

  • Click the "Select local artifact" button

  • Navigate to and select the KAB file created earlier by our Java code:

select local artifact
Figure 9. Configure local artifact

  • Click the OK button, where you should see:

local artifacts
Figure 10. Showing selected private local artifact

5) Add local artifact to section

  • Open the "Sections" card

  • Drag the "my-kos-app-1.2.3.kab" item from "Local Artifacts" to the kos.system "Section"

add section to image
Figure 11. Adding the local artifact to the kos.system section

  • Close the configuration window

6) Execute the image

To run your KOS application in Studio’s built-in simulator:

  • On the main Studio screen, find your "My KOS App" image entry

  • Ensure that "Simulator" is selected

  • Click the "run now" (right-arrow) icon

start simulator
Figure 12. Executing the image

The application first downloads all necessary artifacts, showing the status in the Connections window:

connections window
Figure 13. The connections window
Initial Execution

The first time you run an application it may take a while to download the required packages. Subsequent executions open much faster.

When downloading is finished, the application is started. You’ll see the simulator starting up:

simulator starting up
Figure 14. Simulator starting up

When the simulator has finished, you should see the following default application appear:

welcome to kos screen
Figure 15. Default KOS window

Congratulations, your first KOS application is running!

Summary

In this tutorial you:

  • Created your first KOS application

  • Configured it in Studio

  • Executed it on a Studio simulator

  • Viewed its output on-screen

Now that you’ve gotten a taste of Studio, take a look at the Introducing KOS Studio page.

When you’re ready, we build a REST Controller in the next tutorial.

Previous
Next
On this page
Related Articles
Expand your knowledge with these curated articles that complement your exploration of KOS.
REST Controller
todo - description
Read More
How To Debug Code
todo - description
Read More
API Endpoints
todo - description
Read More
Java Development
Seamlessly transition from Legacy+ systems to Freestyle microdosing and advanced distributed dispense systems.
Learn More
UI Development
Using KOS SDKs, integrating Consumer and Non-consumer facing UIs becomes seamless, giving you less hassle and more time to create.
Learn More
Video Library
Meet some of our development team, as they lead you through the tools, features, and tips and tricks of various KOS tools.
Learn More
Resources
Familiarize yourself with KOS terminology, our reference materials, and explore additional resources that complement your KOS journey.
Learn More
Copyright © 2024 TCCC. All rights reserved.