These tutorials target Micronaut Framework 3. Read, Guides for Micronaut Framework 4.

Table of Contents

Using Kotlin Extension Functions in the Micronaut Framework

Take a tour of the extension functions in the Micronaut framework and learn to write your own

Authors: Will Buck

Micronaut Version: 3.9.2

1. Getting Started

In this guide, we will create a Micronaut application written in Kotlin.

2. What you will need

To complete this guide, you will need the following:

  • Some time on your hands

  • A decent text editor or IDE

  • JDK 1.8 or greater installed with JAVA_HOME configured appropriately

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Kotlin Extension Functions

Before we get started writing the application, let’s touch briefly on what extension functions are and why they’re useful.

4.1. What Are Extension Functions?

The Kotlin documentation explains that extension functions are "an ability to extend a class with new functionality without having to inherit from the class or use design patterns such as Decorator."

They’re useful for writing new functions for classes in a third-party library or quickly creating new methods for common use cases of a class you otherwise can’t edit directly.

For example, perhaps your application often needs to take a list and swap the index of two items in the list.

To define a swap method for any mutable list, you could write:

fun <T> MutableList<T>.swap(index1: Int, index2: Int) {
    val tmp = this[index1] // 'this' corresponds to the list
    this[index1] = this[index2]
    this[index2] = tmp
}

Then use it like it was a regular method of MutableList

val languages = mutableListOf('java', 'groovy', 'kotlin')

languages.swap(0, 2) // Will swap 'java' and 'kotlin' so kotlin comes first

4.2. Using Extension Functions in an Application

To show off the extension functions available for use in Micronaut applications (and how to write your own), we’ll build a simple application that

  • Consumes this fun dad joke API (I love a good dad joke) with an HTTP client

  • Schedules the joke to "be sent" to someone [we won’t actually be integrating a message sender for simplicity]

  • Writes our own extension function for the client (as if it was provided by a third party)

  • Puts everything together in a controller

  • Starts the application with the startApplication extension function

5. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=kotlin-extension-functions,reactor,graalvm,serialization-jackson \
    --build=gradle
    --lang=kotlin
If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add kotlin-extension-functions, reactor, graalvm, and serialization-jackson features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features and apply those changes to your application.

Setup IntelliJ IDEA to develop Micronaut Applications.

5.1. The Micronaut Kotlin Extension Functions

We’re using the Micronaut Kotlin extension function library which aids Kotlin developers in writing more idiomatic code in Micronaut.

You can see the dokka docs for the full list of functions here.

Big credit is due to Alejandro Gomez for allowing for the use of his initial collection of extension functions!

Let’s see these functions in action!

5.2. Application

Right away let’s modify the generated Application.kt to use the startApplication extension function

src/main/kotlin/example/micronaut/Application.kt
package example.micronaut

import io.micronaut.kotlin.runtime.startApplication (1)

object ApplicationKt { (2)
        @JvmStatic
        fun main(args: Array<String>) {
                startApplication<ApplicationKt>(*args) (3)
        }
}
1 Here we import the extension function
2 Since the extension function takes a type argument, we’ll define our Application as a Kotlin object, which is an easy shortcut for a singleton or place to put a static method like main. We’re naming it ApplicationKt simply because this guide’s build file is auto-generated, and we want to match the mainClass name it generates. Application alone would be a preferable name outside the context of this guide.
3 startApplication<ApplicationKt> here does the work of .build().mainClass(ApplicationKt::class.java).start(). Convenient!

5.3. DadJokeClient

Next we’ll build out our functionality. We’ll start by modelling the response types for the plain GET request for the Dad Joke API (that just return a random joke), as well as the paged results that are returned from the /search endpoint.

src/main/kotlin/example/micronaut/DadJoke.kt
package example.micronaut

import io.micronaut.serde.annotation.Serdeable

@Serdeable (1)
data class DadJoke(val id: String, val joke: String, val status: Int)
src/main/kotlin/example/micronaut/DadJokePagedResults.kt
package example.micronaut

import io.micronaut.serde.annotation.Serdeable

@Serdeable (1)
data class DadJokePagedResults(
    val current_page: Int,
    val limit: Int,
    val previous_page: Int,
    val next_page: Int,
    val total_jokes: Int,
    val total_pages: Int,
    val results: List<DadJoke>
)
1 We make both of these classes @Serdeable for compatibility with GraalVM, you can omit them if you do not plan to build a native executable

Then, we can create a standard Micronaut HTTP client for the DadJoke API endpoint, letting the @Client annotation implement the interface we define.

src/main/kotlin/example/micronaut/DadJokeClient.kt
package example.micronaut

import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Header
import io.micronaut.http.annotation.QueryValue
import io.micronaut.http.client.annotation.Client
import reactor.core.publisher.Mono

@Client("https://icanhazdadjoke.com/")
@Header(name = "Accept", value = "application/json")
interface DadJokeClient {

    @Get
    fun tellMeAJoke(): Mono<DadJoke>

    @Get("/search?term={searchTerm}")
    fun searchDadJokes(@QueryValue searchTerm: String): Mono<DadJokePagedResults>
}

Note that while we are creating this client for the purposes of this guide, often something like this comes from a third-party library. Perhaps you’re getting it from a public dependency you don’t have permission to edit, or from another team within your company that has different priorities from your own team.

It could also be that you simply have a specific use case for the client involving specific setup for your application that doesn’t belong in the client.

Let’s see how we can extend this client to suit our own use case.

5.4. DadJokeController

We’ll create a controller to utilize the client’s standard GET for a random joke.

src/main/kotlin/example/micronaut/DadJokeController.kt
package example.micronaut

import io.micronaut.http.MediaType.TEXT_PLAIN
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import jakarta.inject.Inject
import reactor.core.publisher.Mono

@Controller("/dadJokes")
class DadJokeController {

    @Inject
    lateinit var dadJokeClient: DadJokeClient

    @Get(uri = "/joke", produces = [TEXT_PLAIN])
    fun getAJoke(): Mono<String> {
        return Mono.from(dadJokeClient.tellMeAJoke()).map(DadJoke::joke)
    }

}

Now, say we have a particular way we want to use a client frequently, for example attaching common headers or filling in some parameters by default.

Let’s explore how we can extend the client for our benefit. We’ll define a method for the client to specifically look for jokes about dogs.

In your controller file, at the bottom, add this extension function definition:

src/main/kotlin/example/micronaut/DadJokeController.kt
fun DadJokeClient.getDogJokes(): Mono<List<DadJoke>> { (1)
    return Mono.from(this.searchDadJokes("dog")).map(DadJokePagedResults::results)
}
1 We define a getDogJokes method on the DadJokeClient. This method will be available anywhere within the example.micronaut package

While this is a simplified (and somewhat silly) example, you can imagine how with a more sophisticated API, this could be a very powerful tool to encapsulate common functionality and explicitly relate it to the appropriate class, rather than defining another class just to encapsulate this common routine.

We can then use this extension function within our controller by defining a /dogJoke endpoint

src/main/kotlin/example/micronaut/DadJokeController.kt
    @Get("/dogJokes")
    fun getDogJokes(): Mono<List<DadJoke>> {
        return dadJokeClient.getDogJokes() (1)
    }
1 Note how we can use this function as if it were defined on the client class itself.

Now we have our application!

5.5. Writing some tests

Lastly, let’s use a few more convenient functions included in micronaut-kotlin-extension-functions in our test

src/test/kotlin/example/micronaut/DadJokeTest.kt
package example.micronaut

import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.kotlin.context.createBean
import io.micronaut.kotlin.context.run
import io.micronaut.kotlin.http.retrieveList
import io.micronaut.kotlin.http.retrieveObject
import io.micronaut.runtime.server.EmbeddedServer
import org.junit.jupiter.api.Assertions.assertFalse
import org.junit.jupiter.api.Test

class DadJokeTest {

    @Test
    fun testDadJokeController() {
        val embeddedServer = run<EmbeddedServer>() (1)
        val client = embeddedServer.applicationContext.createBean<HttpClient>(embeddedServer.url).toBlocking() (2)

        // Test single object retrieve extension
        val anyJoke = client.retrieveObject<String>(HttpRequest.GET("/dadJokes/joke")) (3)
        assertFalse(anyJoke.isNullOrBlank())

        // Test list retrieve extension
        val dogJoke = client.retrieveList<DadJoke>(HttpRequest.GET("/dadJokes/dogJokes")) (3)
        assertFalse(dogJoke.isEmpty())
        assertFalse(dogJoke.first().joke.isNullOrBlank())

        client.close()
        embeddedServer.close()
    }
}
1 Here we have run<EmbeddedServer> as a little syntatic sugar for ApplicationContext.run(EmbeddedServer::class.java)
2 Same here for createBean<HttpClient>, we’re reducing our need to type ::class.java all over the place
3 retrieveObject and retrieveList give us nice shortcuts to reduce the need for Argument.of and Argument.listOf, in addition to reducing our ::class.java uses.

Now we can test everything out!

6. Testing the Application

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

7. Running the Application

To run the application, use the ./gradlew run command, which starts the application on port 8080.

8. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, the polyglot embeddable virtual machine, to generate a native executable of our Micronaut application.

Compiling native executables ahead of time with GraalVM improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

8.1. Native executable generation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 11
sdk install java 22.3.r11-grl
If you still use Java 8, use the JDK11 version of GraalVM.
Java 17
sdk install java 22.3.r17-grl

For installation on Windows, or for manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

After installing GraalVM, install the native-image component, which is not installed by default:

gu install native-image

To generate a native executable using Gradle, run:

./gradlew nativeCompile

The native executable is created in build/native/nativeCompile directory and can be run with build/native/nativeCompile/micronautguide.

It is possible to customize the name of the native executable or pass additional parameters to GraalVM:

build.gradle
graalvmNative {
    binaries {
        main {
            imageName.set('mn-graalvm-application') (1)
            buildArgs.add('--verbose') (2)
        }
    }
}
1 The native executable name will now be mn-graalvm-application
2 It is possible to pass extra arguments to build the native executable

Whether you run the application via Gradle or as a Native Executable, you should be able to get a good laugh by typing:

curl localhost:8080/dadJokes/joke`

or

curl localhost:8080/dadJokes/dogJokes`

Hopefully it brings a smile to your day!

9. Next steps

See all the useful libraries for Micronaut Kotlin developers in the Micronaut Kotlin documentation.

10. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.