To get started we setup a project, run a webserver and provide a simple API
Project available in GitHub: https://github.com/Lois9Y/namecloud/tree/part_1
Prerequisites
- IntelliJ IDEA
- JDK 1.8
Project Setup
- Create a new Gradle project in your IntelliJ IDE.
- Make sure to set your Project SDK to the correct JDK (in this case 1.8.0_111)
- And declare Java and Kotlin as Additional Libraries and Frameworks
build.gradle
The full build.gradle
for Part 1 can be found at: https://github.com/Lois9Y/namecloud/blob/part_1/build.gradle
We will dive into more specifics below.
If set up correctly, your project comes with a basic build.gradle
file which already includes your basic kotlin dependency as well as applying the java
and kotlin
plugins on your project, but since we are trying out new stuff we restructure the file using the plugins DSL for Gradle 2.1. More info on this here: https://docs.gradle.org/current/userguide/plugins.html
The plugins DSL allows for reduction of „version spam“ in your projects dependencies, more on this later. we can delete the buildscript
block of our build.gradle
as long as we insert the following plugin
block:
Now we can drop the version definitions of these plugins from our dependencies block:
Now need to dive into some Kotlin specific stuff:
By default all classes in Kotlin are declared final
, to use a keyword from classic Java. This interferes with some functions of the Spring framework. We can easily take care of this using the kotlin-spring
plugin provided by Jetbrains:
and add the kotlin reflection library (required to open annotated classes)
for more information on this topic read: https://kotlinlang.org/docs/reference/compiler-plugins.html#kotlin-spring-compiler-plugin
Spring Boot
Spring Boot comes with a gradle plugin which takes care of spring dependencies for us.
To include simply add the plugin inside build.gradle
as follows:
and add our web starter dependency:
Our first API endpoint
Let’s see if everything works as expected.
We start out by creating the source folder structure in our project root.
$ mkdirs -p src/main/kotlin/
and add the package to the newly created folder (in our case at.nineyards.blog.namecloud
)
inside the package Add a new Kotlin File/class and name it App.kt
This file will be our entry point.
Since Kotlin supports top level functions we can get our webserver started with as little effort as:
Notice, that the main()
function is not a method of our App
class, but a top-level function instead.
Hit Build, Run App.kt and your webserver will start up at http://localhost:8080
open http://localhost:8080
in your browser and you will find the standard Whitelabel Error Page (since no endpoint is defined for /
)
Now lets define a simple /hello endpoint.
Use whatever structure you like to create a Controller class (Personally i keep all my controllers in a subpackage of the App package), and create a new Kotlin Class name HelloController containing the very simple functionality:
Now we annotate the class to let Spring know what we want it to do:
- @RestController: This class shall be treated as a Controller
- @RequestMapping: This function shall act as an endpoint
rebuild – run and visit http://localhost:8080/hello
If everything is up and running your server will now talk to you.
Testing
An API without tests is no API at all. In this section add a first test to our project to show in principle, how to test our previously created endpoint.
we start by replacing the testCompile
line in the dependecies
block of our previous build.gradle
:
(Notice, once again we do not require a version number, due to the Spring Boot plugin taking care of that)
Create the appropriate file structure inside our /src
folder
$ mkdirs -p /src/test/kotlin
Once again create your package (in this case at.nineyards.blog.namecloud
) and create a new Kotlin File/Class named HelloTest.kt
In this file we create our first test as follows:
Let’d dive into some of these annotations:
- @SpringBootTest with RANDOM_PORT: Provides a real servlet environment. Embedded servlet containers are started and listening on a random port.
- @Autowired: going into this too much would exceed this context of this exercise. We invite you to learn about Spring auto-wiring elsewhere, for our context, its only important that this gives us a minimal REST client to test our endpoints.
Build -> Run HelloTest.kt -> if everything shows up green we are good 😉
This concludes part 1 of our little series. Check back next time when we add MongoDB support to our web server.
kr,
Lois
