Getting Started

Purpose

In this tutorial we will create a simple HTTP server which sends a “Hello World!” greeting. Using DataKernel Launchers, particularly HttpServerLauncher, you can write a full-functioning server in around 10 lines of code.

What you will need:

To proceed with this guide you have three options:

Use Archetypes

Simply enter the following command in the terminal:

mvn archetype:generate \
        -DarchetypeGroupId=io.datakernel                  \
        -DarchetypeArtifactId=datakernel-http-archetype   \
        -DarchetypeVersion=3.0.0-beta1                    \
        -DgroupId=org.example                             \
        -DartifactId=dkapp                                \
        -DmainClassName=MyFirstDkApp 

The project will be automatically generated on your machine. Open MyFirstDkClass and run its main method. Then open your favourite browser and go to localhost:8080.

Working Example

Clone DataKernel locally and import it as a Maven project. Before running the example, build the project (Ctrl + F9 for IntelliJ IDEA).

Then open HttpHelloWorldExample class, which is located at datakernel -> examples -> tutorials -> getting-started and run its main() method. Open your favourite browser and go to localhost:8080.

Step-by-step guide

1. Configure the project

First, create a folder for application and build an appropriate project structure:

getting-started
└── pom.xml
└── src
    └── main
        └── java
            └── HttpHelloWorldExample.java

Next, you need to integrate DataKernel in your project. There are two ways to do it:

1. Add Maven dependency to your project.

Configure your pom.xml file in the following way:

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

  <groupId>io.datakernel</groupId>
  <artifactId>getting-started</artifactId>
  <version>3.0.0-beta1</version>

  <name>Examples : Tutorials : Getting-Started</name>

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>io.datakernel</groupId>
      <artifactId>http-launchers</artifactId>
      <version>3.0.0-beta1</version>
    </dependency>
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <version>1.2.3</version>
    </dependency>
  </dependencies>

</project>
2. Clone DataKernel and install it.

Another way to integrate DataKernel is to clone DK, import it as a Maven project and run the following script in project directory:

./install.sh

Next, configure your pom.xml file in the following way.

Make sure that your project SDK is set 1.8+.

2. Write HttpHelloWorldExample class

After you integrate DataKernel in your project in one of the suggested ways, write down the following code to HttpHelloWorldExample.java:

public final class HttpHelloWorldExample extends HttpServerLauncher {
	@Provides
	AsyncServlet servlet() {
		return request -> HttpResponse.ok200().withPlainText("Hello World");
	}

	public static void main(String[] args) throws Exception {
		Launcher launcher = new HttpHelloWorldExample();
		launcher.launch(args);
	}
}

First, we extend HttpHelloWorldExample from HttpServerLauncher, which will help to manage application lifecycle. The only thing we should know about this launcher is that it implements launch() method which starts our server.

Next, provide an AsyncServlet which receives HttpRequest from clients, creates HttpResponse and sends it. @Provides annotation means that this method is available for binding as root HTTP endpoint listener (it must happen when dependency injection process is active).

Override AsyncServlet.serve using lambda. This method defines processing of received requests. As you can see, we are using Promise here, creating a promise of HttpResponse with code 200 and “Hello World!” body. DataKernel is fully asynchronous, so our HTTP Servlets are asynchronous too.

Finally, define main method to launch our server with launch method. This method launches server in the following steps: injects dependencies, starts application, runs it and finally stops it.

3. Run the app

Let’s now test the application. Run HttpHelloWorldExample.main(), then open your favourite browser and go to localhost:8080. You will receive a Hello World! message processed by the server. Congratulations, you’ve just created your first DataKernel application!

What’s next?

To make DataKernel more developer-friendly, we’ve created dozens of tutorials and examples of different scales, representing most of the framework’s capabilities. Click “Next” to get to the next tutorial. You can also explore our docs first.