On this page

Kotlin

1 Introduction

This project provides various extensions and improvements to the Micronaut and Kotlin experience.

Tip	For more detailed information, see the dokka docs for the Micronaut Kotlin Modules.

2 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-kotlin/releases

3 Kotlin Runtime Support

The micronaut-kotlin-runtime dependency adds the following features:

Support for defining configuration with config4k.
A runtime dependency on jackson-module-kotlin

To enable the above features add the dependency to your build:

implementation("io.micronaut.kotlin:micronaut-kotlin-runtime")

<dependency>
    <groupId>io.micronaut.kotlin</groupId>
    <artifactId>micronaut-kotlin-runtime</artifactId>
</dependency>

Tip	Micronaut Kotlin Runtime API Documentation

Config4k Support

3.1 Config4k

Config4k is a type safe configuration format for Kotlin based on HOCON (Human-Optimized Config Object Notation). Configuration files are defined using the conf extension. The following an example configuration file:

An Example src/main/resources/application.conf

micronaut {
  server {
    port = 8081
  }
}

test-property = "bad-value"

custom {
  user = ${USER}
}

4 Ktor Support

Ktor is a Kotlin framework for building connected applications. The micronaut-ktor module includes support for using Ktor as the server instead of Micronaut’s native HTTP server.

This allows users familiar with Ktor to use Micronaut features such as Dependency Injection, AOP, configuration management and so on.

implementation("io.micronaut.kotlin:micronaut-ktor")

<dependency>
    <groupId>io.micronaut.kotlin</groupId>
    <artifactId>micronaut-ktor</artifactId>
</dependency>

Tip	Micronaut ktor API Documentation.

Tip	See the Example application which demonstrates how to setup a Micronaut Ktor application

4.1 The KtorApplication class

The entry point for a Micronaut Ktor application is an Application class. An example class can be seen below:

Example Application class

import io.ktor.server.netty.NettyApplicationEngine
import io.micronaut.ktor.KtorApplication
import io.micronaut.ktor.runApplication
import jakarta.inject.Singleton
import org.slf4j.LoggerFactory

@Singleton
class Application : KtorApplication<NettyApplicationEngine.Configuration>({ // 
    applicationEngineEnvironment { // 
        log = LoggerFactory.getLogger(Application::class.java)
    }

    applicationEngine { // 
        workerGroupSize = 10
    }
})

fun main(args: Array<String>) { // 
    runApplication(args)
}

The Application class extends io.micronaut.ktor.KtorApplication and declares the Ktor engine type, in this case Netty.
The applicationEngineEnvironment { … } block lets you customize Ktor environment settings used by the Micronaut integration, such as logging.
The applicationEngine { … } block configures engine-specific settings. In this example, the Netty engine configuration sets workerGroupSize to 10.
A main method is defined for running the application within a runnable JAR.

4.2 Defining Ktor Modules

To define Ktor modules you can create classes that subclass io.micronaut.ktor.KtorApplicationBuilder to install plugins or io.micronaut.ktor.KtorRoutingBuilder to configure routes.

For example, the following installs the Jackson plugin when ktor-serialization-jackson is on the classpath:

Installing Plugins

import com.fasterxml.jackson.databind.SerializationFeature
import io.ktor.server.application.install
import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
import io.ktor.serialization.jackson.jackson
import io.micronaut.ktor.KtorApplicationBuilder
import jakarta.inject.Singleton

@Singleton
class GreetingConfiguration : KtorApplicationBuilder({ // 
    install(ContentNegotiation) { // 
        jackson {
            enable(SerializationFeature.INDENT_OUTPUT)
        }
    }
})

The class subclasses KtorApplicationBuilder.
The ContentNegotiation plugin is installed and Jackson is configured.

To build application routes you can use the KtorRoutingBuilder:

Defining Routes

import io.ktor.server.application.call
import io.ktor.server.request.receive
import io.ktor.server.response.respond
import io.ktor.server.routing.*
import io.micronaut.ktor.KtorRoutingBuilder
import jakarta.inject.Singleton

@Singleton
class GreetingRoutes(private val greetingService: GreetingService) : KtorRoutingBuilder({ // 
    get("/") {
        call.respond(greetingService.greet())
    }

    post("/") {
        val name = call.receive<CustomGreetingRequest>().name

        call.respond(greetingService.greet(name))
    }
})

data class CustomGreetingRequest(val name: String)

The class subclasses KtorRoutingBuilder and uses dependency injection to reference GreetingService.
The routing DSL is used to build the application routes.

5 Kotlin Extension Functions

The micronaut-kotlin-extension-functions dependency adds a variety of convenience functions to make using Micronaut with Kotlin more user-friendly. For example, reified type parameters help alleviate the need for using ::class.java in many places where it would otherwise be required.

implementation("io.micronaut.kotlin:micronaut-kotlin-extension-functions")

<dependency>
    <groupId>io.micronaut.kotlin</groupId>
    <artifactId>micronaut-kotlin-extension-functions</artifactId>
</dependency>

Tip	Micronaut Kotlin Extension Functions API Documentation

Tip	See the guide for Using Kotlin Extension Functions in the Micronaut Framework to learn more.

Note	You will need to import the functions like this: `import io.micronaut.kotlin.FUNCTION_NAME`

Warning

Do be aware when defining extension functions in this project or your own, an extension that shadows a member function may have unexpected behavior, and does not throw a compiler error but rather warns. See this Kotlin discussion topic for the latest information.

5.1 Context Extensions

Tip	Context Extensions API Documentation

5.2 HTTP Extensions

Tip	Http Extensions API Documentation

BlockingHttpClient Extensions

Single Response Extensions

Test Demonstrating Single Response Client Extension usage

// Compare exchange usage
val exchangeOneConventional: HttpResponse<Hero> = client.exchange(HttpRequest.GET<Any>("/heroes/any"), Argument.of(Hero::class.java))
val exchangeOneReified: HttpResponse<Hero> = client.exchangeObject<Hero>(HttpRequest.GET("/heroes/any"))

// Compare retrieve usage
val retrieveOneConventional: Hero = client.retrieve(HttpRequest.GET<Any>("/heroes/any"), Argument.of(Hero::class.java))
val retrieveOneReified: Hero = client.retrieveObject<Hero>(HttpRequest.GET("/heroes/any"))

List Response Extensions

Test Demonstrating List Response Client Extension usage

// Compare exchange usage
val exchangeListConventional: HttpResponse<MutableList<Hero>> = client.exchange(HttpRequest.GET<Any>("/heroes/list"), Argument.listOf(Hero::class.java))
val exchangeListReified: HttpResponse<List<Hero>> = client.exchangeList<Hero>(HttpRequest.GET("/heroes/list"))

// Compare retrieve usage
val retrieveListConventional: MutableList<Hero> = client.retrieve(HttpRequest.GET<Any>("/heroes/list"), Argument.listOf(Hero::class.java))
val retrieveListReified: List<Hero> = client.retrieveList<Hero>(HttpRequest.GET("/heroes/list"))

HttpMessage Extensions

Test Demonstrating HttpMessage Extension usage

// Compare body member usage (Not exceptional path)
val exchangeOneConventionalBody: Hero? = exchangeOneConventional.body.getOrNull()
val exchangeOneReifiedBody: Hero? = exchangeOneReified.bodyOrNull

// Compare getBody() usage (Exceptional path)
val exchangeOneConventionalCustomException: HttpClientResponseException = assertThrows<HttpClientResponseException> {
    client.exchange(HttpRequest.GET<Any>("/heroes/conflict"), Argument.of(Hero::class.java))
}
val exchangeOneReifiedCustomException: HttpClientResponseException = assertThrows<HttpClientResponseException> {
    client.exchangeObject<Hero>(HttpRequest.GET("/heroes/conflict"))
}
val exchangeOneConventionalCustomExceptionBody: HeroJsonError? = exchangeOneConventionalCustomException.response.getBody(HeroJsonError::class.java).getOrNull()
val exchangeOneReifiedCustomExceptionBody: HeroJsonError? = exchangeOneReifiedCustomException.response.getBodyObject<HeroJsonError>()

5.3 Inject Extensions

Tip	Inject Extensions API Documentation

5.4 Runtime Extensions

Tip	Runtime Extensions API Documentation

An Example Application using the extension function.

object Application

fun main(args: Array<String>) {
    startApplication<Application>(*args) {
        packages("org.example.app")
        mapError<RuntimeException> { 500 }
    }
}

5.5 Scheduling Extensions

Tip	Scheduling Extensions API Documentation

5.6 JSON Extensions

Tip	Serde Extensions API Documentation

JsonMapper Extensions

The JsonMapper extension functions provide convenient ways to deserialize JSON from various sources using reified type parameters, eliminating the need to explicitly pass type information.

Deserialize from JsonNode

The readValueFromTree extension allows you to deserialize a JsonNode directly to a typed value without requiring explicit type arguments:

Test Demonstrating JsonNode deserialization

// Instead of:
val value: MyData = jsonMapper.readValueFromTree(node, Argument.of(MyData::class.java))

// You can use:
val value = jsonMapper.readValueFromTree<MyData>(node)

This is particularly useful when working with the JSON tree API for partial parsing or tree manipulation operations.

Deserialize from InputStream

The readValue extension for InputStream provides a clean way to parse JSON from a stream:

Parsing JSON from an InputStream

// Instead of:
val value: MyData = jsonMapper.readValue(inputStream, Argument.of(MyData::class.java))

// You can use:
val value = jsonMapper.readValue<MyData>(inputStream)

Deserialize from ByteArray

The readValue extension for ByteArray is convenient for parsing JSON from raw bytes:

Parsing JSON from a ByteArray

// Instead of:
val value: MyData = jsonMapper.readValue(jsonBytes, Argument.of(MyData::class.java))

// You can use:
val value = jsonMapper.readValue<MyData>(jsonBytes)

Deserialize from ReadBuffer

For Micronaut’s ReadBuffer type, the extension provides seamless deserialization:

Parsing JSON from a ByteBuffer

// Instead of:
val value: MyData = jsonMapper.readValue(buffer, Argument.of(MyData::class.java))

// You can use:
val value = jsonMapper.readValue<MyData>(buffer)

This is especially useful in server implementations that work directly with buffers.

Deserialize from String

The readValue extension for String is the most convenient for handling JSON text:

Parsing JSON from a String

// Instead of:
val value: MyData = jsonMapper.readValue(jsonString, Argument.of(MyData::class.java))

// You can use:
val value = jsonMapper.readValue<MyData>(jsonString)

Null Handling

All extension functions return a nullable type (T?) to properly handle cases where deserialization results in JSON null values.

Handling null values in deserialization

val possiblyNull: MyData? = jsonMapper.readValue<MyData>(jsonString)

if (possiblyNull != null) {
    // Process the deserialized value
    println(possiblyNull.name)
} else {
    // Handle null case
    println("JSON was null")
}

6 Breaking Changes

This section documents breaking changes for Kotlin and Ktor versions:

Micronaut Kotlin 5.1.1-SNAPSHOT

Micronaut Kotlin’s Ktor module is now based on Ktor 3.x and includes breaking changes relative to the previous Ktor 2-based integration.

Key changes include Ktor 3 environment and server bootstrap redesign, including the move from ApplicationEngineEnvironmentBuilder to ApplicationEnvironmentBuilder, the introduction of ServerConfig, and the change in embeddedServer() to return EmbeddedServer.

For more information, refer to the following Ktor guide:

Migrating Ktor applications: Migrating from 2.x to 3.x

7 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-kotlin