Hello World in Kompics

This section describes the simplest possible Kompics program, the well-known Hello World.

A proper introduction can be found in the Kompics Tutorial.

Maven Setup

Set up a new maven project and follow the instructions in Repositories and Getting Started to include the necessary dependencies. For this simple example the kompics-core module will be sufficient.

The resulting pom.xml might look something like:

<?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/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>se.sics.test</groupId>
    <artifactId>hello-world</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>

    <name>HelloWorld</name>
    <description>
        Kompics Hello World
    </description>
        
    <properties>
        <java.compiler.version>1.7</java.compiler.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <kompics.version>1.0.0</kompics.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>se.sics.kompics</groupId>
            <artifactId>kompics-core</artifactId>
            <version>${kompics.version}</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
            <version>1.2.3</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <inherited>true</inherited>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.1</version>
                <configuration>
                    <encoding>${project.build.sourceEncoding}</encoding>
                    <source>${java.compiler.version}</source>
                    <target>${java.compiler.version}</target>
                    <debug>true</debug>
                    <optimize>true</optimize>
                    <showDeprecations>true</showDeprecations>
                </configuration>
            </plugin>
            
        </plugins>
    </build>

    <repositories>
        <repository>
            <id>sics-release</id>
            <name>SICS Release Repository</name>
            <url>http://kompics.sics.se/maven/repository</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>sics-snapshot</id>
            <name>SICS Snapshot Repository</name>
            <url>http://kompics.sics.se/maven/snapshotrepository</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>
</project>

Hello World Component

This very simple component contains but a single handler, which is executed when a Start event is triggered on the control port. Start events are part of Kompic’s component lifecycle and always need to be triggered on a component exactly once to get it to handle events. A component that is never started is considered paused and will queue up events on its ports, but never execute them.

package se.sics.test;

import se.sics.kompics.ComponentDefinition;
import se.sics.kompics.Handler;
import se.sics.kompics.Start;
import se.sics.kompics.Kompics;

public class HelloComponent extends ComponentDefinition {
	{
		Handler<Start> startHandler = new Handler<Start>() {
			@Override
			public void handle(Start event) {
				System.out.println("Hello World!");
				Kompics.asyncShutdown();
			}
		};
		subscribe(startHandler, control);
	}
}

Warning

Do not forget to subscribe Kompics handlers to ports! It is the most common mistake, and it is very easy to overlook when debugging.

Main

The Main.java is very simple and only starts the Kompics framework by calling Kompics.createAndStart with the class of the root component. It also automatically sends a Start event to the component once the constructor has finished.

package se.sics.test;

import se.sics.kompics.Kompics;

public class Main {
	public static void main(String[] args) throws InterruptedException {
		Kompics.createAndStart(HelloComponent.class);
		Kompics.waitForTermination();
	}
}

Compiling and Running

To compile the source code use:

mvn clean compile

To run the project from within maven:

mvn exec:java -Dexec.mainClass="se.sics.test.Main"

This is all. Say hello to Kompics ;)

Logging

Kompics has built-in logging support, which adds context information to the logging output, such as what state the component is in and what its unique id is. You can access the provided SLF4J logger via the logger field.

In order to make use of these features, a mapped diagnostic context (MDC) capable logging backend is required, such as Logback Classic, for example, which is imported in the pom.xml file.

Logback requires a configuration file to work. Adding a simple src/main/resources/logback.xml file to the project will configure the logging system, in this case such that all MDC information is printed:

<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} %highlight(%-5level) %logger{1} [%thread] %X %n    - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

It is also possible to add custom context information to a particular component, by using either ComponentDefinition.loggingCtxPut(String, String) for potentially transient values, or ComponentDefinition.loggingCtxPutAlways(String, String) for context values that definitely span the life-time of the component.

Download

You can download the whole maven project here.