Getting Started

Purpose

In this tutorial we will create a simple HTTP server that 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=archetype-http -DarchetypeVersion=3.1.0

The project will be automatically generated on your machine. Open WebApp 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. Check out branch v3.1. 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.1.0</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>datakernel-launchers-http</artifactId>
      <version>3.1.0</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, check out branch v3.1 and run the following script in project directory:

./install.sh

Next, configure your pom.xml file like in the example above. Make sure that your project SDK is set to 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);
	}
}

Let’s take a look at how it works.

First, we extend HttpHelloWorldExample from HttpServerLauncher to handle the management of the application’s lifecycle. In this example, the only important thing to know about the superclass is that it implements launch method for starting our server.

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

To define processing of received requests, we override the AsyncServlet.serve method with lambda. As you can see, we are using Promises 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, we define main method and launch our server with launch method. Here’s its step-by-step explanation: it injects dependencies, starts the application, runs it and, finally, stops it.

3. Run the app

Now, let’s test the application. First, 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.