Category: Functional Programming

Coping with Kotlin’s Scope Functions

Coping with Kotlin’s Scope Functions

Coping with Kotlin’s Scope Functions

Functions in Kotlin are very important and it’s much fun() to use them. One special collection of relevant functions can be described as “scope functions” and they are part of the Kotlin standard library: let, run, also, apply and with.
You probably already heard about them and it’s also likely that you even used some of them yet. Most people tend to have problems distinguishing all those functions, which is not very remarkable in view of the fact that their names may be a bit confusing. This post intends to demonstrate the differences between the available scope functions and also wants to discuss relevant use cases. Finally, an example will show how to apply scope functions and how they help to structure Kotlin code in a more idiomatic way.

Disclaimer: The topic of scope functions is under consideration in various StackOverflow posts very often, which I will occasionally refer to throughout this article.

The Importance of Functions

In Kotlin, functions are as important as integers or strings. Functions can exist on the same level as classes, may be assigned to variables and can also be passed to/returned from other functions. Kotlin makes functions “first-class citizens” of the language, which Wikipedia describes as follows:

A first-class citizen […] is an entity which supports all the operations generally available to other entities. These operations typically include being passed as an argument, returned from a function, modified, and assigned to a variable.

As already said, functions are as powerful and significant as any other type, e.g. Int. In addition to that, functions may appear as “higher-order functions”, which in turn is described as the following on Wikipedia:

In mathematics and computer science, a higher-order function (also functional, functional form or functor) is a function that does at least one of the following:
takes one or more functions as arguments (i.e., procedural parameters),
– returns a function as its result.

The boldly printed bullet point is the more important one for the present article since scope functions also act as higher-order functions that take other functions as their argument. Before we dive into this further, let’s observe a simple example of higher-order functions.

Higher-Order Function in Action

A simple higher-order function that’s commonly known in Kotlin is called repeat and it’s defined in the standard library:


inline fun repeat(times: Int, action: (Int) -> Unit)

As you can see, repeat takes two arguments: An ordinary integer times and also another function of type (Int) -> Unit. According to the previously depicted definition, repeat is a higher-order function since it “takes one or more functions as arguments”. In its implementation, the function simply invokes action as often as times indicates. Let’s see how repeat can be called from a client’s point of view:


repeat(3) { rep ->
    println("current repetition: $rep")
}

In Kotlin, lambdas can be lifted out of the parentheses of a function call if they act as the last argument to the function.

Note that if a function takes another function as the last parameter, the lambda expression argument can be passed outside the parenthesized argument list.

The official documentation is very clear about all lambda features and I highly recommend to study it.

In the shown snippet, a regular lambda, which only prints the current repetition to the console, is passed to repeat. That’s how higher-order function calls look like.

Function Literal with Receiver

Kotlin promotes yet another very important concept that makes functions even more powerful. If you’ve ever seen internal domain specific languages (DSL) in action, you might have wondered how they are implemented. The most relevant concept to understand is called function literal with receiver (also lambda with receiver). Since this feature is also vital for scope functions, it will be discussed next.

Function literals with receiver are often used in combination with higher-order functions. As shown earlier, functions can be made parameters of other functions, which happens by defining parameters with the function type syntax (In) -> Out. Now imagine that these function types can even be boosted by adding a receiver: Receiver.(In) -> Out. Such types are called function literal with receiver and are best understood if visualized as “temporary extension functions”. Take the following example:


inline fun createString(block: StringBuilder.() -> Unit): String {
    val sb = StringBuilder()
    sb.block()
    return sb.toString()
}

The function createString can be called a higher-order function as it takes another function block as its argument. This argument is defined as a function literal with receiver type. Now, let’s think of it as an extension function defined for StringBuilder that will be passed to the createString function. Clients will hand on arbitrary functions with the signature () -> Unit, which will be callable on instances of StringBuilder. That’s also shown in the implementation: An instance of StringBuilder is being created and block gets invoked on it. Eventually, the method transforms StringBuilder to an ordinaryString` and to the caller.

What does that mean for the client of such a method? How can you create and pass function literals with receiver to other functions? Since the receiver is defined as StringBuilder, a client will be able to pass lambdas to createString that make use of that receiver. The receiver is exposed as this inside the lambda, which means that clients can access visible members (properties, functions etc.) without additional qualifiers:


val s = createString { //here we're in the context of a `StringBuilder`
    append(4)
    append("hello")
}

The example shows that append, a function defined for the receiver StringBuilder, is being invoked without any qualifiers (e.g. it). The same is possible in the definition of extension functions, which is why I used it as an analogy earlier. The client defines a temporary extension function which gets invoked on the corresponding receiver within createString afterward. For another description of the concept, please consult the associated documentation. I also tried to answer a related StackOverflow question a while ago.

Scope Functions

Scope functions make use of the concepts described above. They are defined as higher-order functions, i.e. they take another function as their argument. These arguments may even appear as function literals with receiver in certain cases. Scope functions take an arbitrary object, the context object, and bring it to another scope. In that scope, the context object is either accessible as it (or custom name) or this, depending on the type of function. In the following, the functions let, run, also, apply and with will be introduced and explained.

[let]

Documentation: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/let.html


public inline fun <T, R> T.let(block: (T) -> R): R 

One of the most famous scope functions is certainly let. It’s inspired by functional programming languages like Haskell and is used quite often in the Kotlin language, too. Let’s inspect its signature:

  • Defined as an extension on T, the receiver/context object
  • Generic type R defines the function’s return value
  • Result R of block will be the result of let itself, i.e. it can be an arbitrary value
  • block argument with regular function type (T) -&gt; R
  • Receiver T is passed as argument to block

Use Cases

a. Idiomatic replacement for if (object != null) blocks

As you can read in the Kotlin Idioms section, let is supposed to be used to execute blocks if a certain object is not null.


val len = text?.let {
    println("get length of $it")
    it.length
} ?: 0

The nullable text variable is brought into a new scope by let if it isn’t null. Its value then gets mapped to its length. Otherwise, the null value is mapped to a default length 0 with the help of the Elvis operator. As you can see, the context object text gets exposed as it inside let, which is the default implicit name for single parameters of a lambda.

b. Map nullable value if not null

The let function is also often used for transformations, especially in combination with nullable types again, which is also defined as an idiom.


val mapped = value?.let { transform(it) } ?: defaultValue

c. Confine scope of variable/computation

If a certain variable or computation is supposed to be available only in a confined scope and should not pollute the outer scope, let again can be helpful:


val transform = "stringConfinedToLetScope".let {
    println("variable can be accessed in let: $it")
    "${it.length}$it"
}
//cannot access original string from here

The shown string "stringConfinedToLetScope" is made the context object of let, which uses the value for some simple transformation that is returned as the result of let. The outer scope only uses the transformed value and does not access the temporarily needed string. There’s no variable polluting the outer scope due to confining it to the relevant scope.

[run]

Documentation: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run.html


inline fun <T, R> T.run(block: T.() -> R): R

As an alternative to let, the run function makes use of a function literal with receiver as used for the block parameter. Let’s inspect its signature:

  • Defined as an extension on T, the receiver/context object
  • Generic type R defines the function’s return value
  • Result R of block will be the result of run itself, i.e. it can be an arbitrary value
  • block argument defined as function literal with receiver T.() -&gt; R

The run function is like let except how block is defined.

Use Cases

run can basically serve the same use cases as let, whereas the receiver T is exposed as this inside the lambda argument:

a. Idiomatic replacement for if (object != null) blocks


val len = text?.run {
    println("get length of $this")
    length //`this` can be omitted
} ?: 0

b. Transformation

It’s also good to use run for transformations. The following shows an example that is even more readable than with let since it accesses the context object’s functions without qualifiers:


val date: Int = Calendar.getInstance().run {
    set(Calendar.YEAR, 2030)
    get(Calendar.DAY_OF_YEAR) //return value of run
}

[also]

Documentation: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/also.html


inline fun  T.also(block: (T) -> Unit): T

The also function is the scope function that got lastly added to the Kotlin language, which happened in version 1.1. Let’s inspect its signature:

  • Defined as an extension on T, the receiver/context object
  • Returns the receiver object T
  • block argument with regular function type (T) -&gt; Unit
  • Receiver T is passed as argument to block

also looks like let, except that it returns the receiver T as its result.

Use Cases

a. Receiver not used inside the block

It might be desired to do some tasks related to the context object but without actually using it inside the lambda argument. An example can be logging. As described in the official Kotlin coding conventions, using also is the recommended way to solve scenarios like the one shown next:


val num = 1234.also { 
    log.debug("the function did its job!") 
}

In this case, the code almost reads like a normal sentence: Assign something to the variable and also log to the console.

b. Initializing an object

Another very common scenario that can be solved with also is the initialization of objects. As opposed to the two previously introduced scope functions, let and run, also returns the receiver object after the block execution. This fact can be very handy:


val bar: Bar = Bar().also {
    it.foo = "another value"
}

As shown, a Bar instance is created and also is utilized in order to directly initialize one of the instance’s properties. Since also returns the receiver object itself, the expression can directly be assigned to a variable of type Bar.

c. Assignment of calculated values to fields

The fact that also returns the receiver object after its execution can also be useful to assign calculated values to fields, as shown here:


fun getThatBaz() = calculateBaz().also { baz = it }

A value is being calculated, which is assigned to a field with the help of also. Since also returns that calculated value, it can even be made the direct inline result of the surrounding function.

[apply]

Documentation: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/apply.html


inline fun  T.apply(block: T.() -> Unit): T

The apply function is another scope function that was added because the community asked for it. Its main use case is the initialization of objects, similar to what also does. The difference will be shown next. Let’s inspect its signature first:

  • Defined as an extension on T, the receiver/context object
  • Returns the receiver object T
  • block argument defined as function literal with receiver T.() -&gt; R

The relation between apply and also is the same as between let and run: Regular lambda vs. Function literal with receiver parameter:

Relation (apply,also) == Relation (run,let)

Use Cases

a. Initializing an object

The ultimate use case for apply is object initialization. The community actually asked for this function in relatively late stage of the language. You can find the corresponding feature request here.


val bar: Bar = Bar().apply {
    foo1 = RED
    foo2 = "Foo"
}

Although also was already shown as a tool for solving these scenarios, it’s obvious that apply has a big advantage: There’s no need to use “it” as a qualifier since the context object, the Bar instance in this case, is exposed as this. The difference got answered in this StackOverflow post.

b. Builder-style usage of methods that return Unit

As described in the Kotlin Idioms section, apply can be used for wrapping methods that would normally result in Unit responses.


class FooBar(var a: Int = 0, var b: String? = null) {
    fun first(aArg: Int): FooBar = apply { a = aArg }
    fun second(bArg: String): FooBar = apply { b = bArg }
}
//caller
FooBar().first(10).second("foobarValue")

In the example, apply is used to wrap simple property assignments that would usually simply result in Unit. Since the class wants to expose a builder-style API to the client, this approach is very useful as the setter-like methods return the surrounding object itself.

[with]

Documentation: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/with.html


inline fun <T, R> with(receiver: T, block: T.() -> R): R

The with function is the last scope function that will be discussed here. It’s a very common feature in many even older languages like Visual Basic and Delphi.
It varies from the other four functions in that it is not defined as an extension function. Let’s inspect its signature:

  • Defined as an independent function that takes a receiver/context object T as its first argument
  • Result R of block will be the result of run itself, i.e. it can be an arbitrary value
  • block argument defined as function literal with receiver T.() -&gt; R

This function aligns with let and run in regards to its return value R. It’s often said to be similar to apply; the difference got described here. Another simple description of with can be found here (both StackOverflow).

Use Cases

a. Working with an object in a confined scope

Also defined as an idiom, with is supposed to be used when an object is only needed in a certain confined scope.

 
val s: String = with(StringBuilder("init")) {
    append("some").append("thing")
    println("current value: $this")
    toString()
}

The StringBuilder passed to with is only acting as an intermediate instance that helps in creating the more relevant String that gets created in with. It’s obvious that with is utilized for wrapping the calls to StringBuilder without exposing the instance itself to the outer scope.

b. Using member extensions of a class

Extension functions are usually defined on package level so that they can be imported and accessed from anywhere else with ease. It’s also possible to define these on class or object level, which is then called a “member extension function”. These kinds of extension functions can easily be used inside that class but not from outside. In order to make them accessible from anywhere outside the enclosing class, that class has to be brought “into scope”. The with function is very useful here:

 
object Foo {
    fun ClosedRange.random() =
        Random().nextInt(endInclusive - start) + start
}

// random() can only be used in context of `Foo`
with(Foo) {
    (0..10).random()
}

The shown object Foo defines a sweet member extension function random(), which can be used only in the scope of that object. With the help of with, this can easily be achieved. Note that this strategy is especially recommendable if particular extension functions are to be grouped meaningfully.

Comparison and Overview

After the five different scope functions have been discussed, it’s necessary to see them all next to each other:


//return receiver T
fun  T.also(block: (T) -> Unit): T //T exposed as it
fun  T.apply(block: T.() -> Unit): T //T exposed as this

//return arbitrary value R
fun <T, R> T.let(block: (T) -> R): R //T exposed as it
fun <T, R> T.run(block: T.() -> R): R //T exposed as this

//return arbitrary value R, not an extension function 
fun <T, R> with(receiver: T, block: T.() -> R): R //T exposed as this

The scope functions also and apply both return the receiver object after their execution. In apply, the block parameter is defined as a function literal with receiver and T gets exposed as this, whereas in also, it’s a regular function type and T gets exposed as it.

The scope functions let and run on the other hand both return an arbitrary result R, i.e. the result of the block itself. Again, run works with a function literal with receiver, whereas let uses the simple function type.

Last but not least, with is kind of a misfit amongst the scope functions since it’s not defined as an extension on T. It defines two parameters, one of which represents the receiver object of this scope function. Same as apply and run, with works with function literal with receiver.

returns receiver objectreturns arbitrary result
exposed as `it``also``let`
exposed as `this``apply``run` & `with`1

1Not an extension.

IDE Support

As of version 1.2.30, the IntelliJ IDEA Kotlin plugin offers intentions that can convert between let and run and also between also and apply calls. Read more about it here.

Example: Requesting a REST API

In this section, I’m going to show an example that applies the previously discussed scope functions on a pretty basic use case: Calling an HTTP REST endpoint. The goal is to provide functionality for requesting information about contributors of the jetbrains/kotlin GitHub project. Therefore we define the appropriate GitHub endpoint and a simplified representation of a Contributor that is annotated for Jackson:

  
const val ENDPOINT = "https://api.github.com/repos/jetbrains/kotlin/contributors"

@JsonIgnoreProperties(ignoreUnknown = true)
data class Contributor(
    val login: String, 
    val contributions: Int
)

The following shows the code that provides the desired functionality in its initial form:


object GitHubApiCaller {
    private val client = OkHttpClient()
    private var cachedLeadResults =
        mutableMapOf<String, Contributor>()
    private val mapper = jacksonObjectMapper()

    @Synchronized
    fun getKotlinContributor(name: String): Contributor {
        val cachedLeadResult = cachedLeadResults[name]
        if (cachedLeadResult != null) {
            LOG.debug("return cached: $cachedLeadResult")
            return cachedLeadResult
        }
        val request = Request.Builder().url(ENDPOINT).build()

        val response = client.newCall(request).execute()

        val responseAsString = response.use {
            val responseBytes = it.body()?.source()?.readByteArray()
            if (responseBytes != null) {
                String(responseBytes)
            } else throw IllegalStateException("No response from server!")
        }

        LOG.debug("response from git api: $responseAsString\n")

        val contributors =
             mapper.readValue<Array>(responseAsString)


        val match = contributors.first { it.login == name }
        this.cachedLeadResults[name] = match
        LOG.debug("found kotlin contributor: $match")
        return match
    }
}

The depicted snippet shows a singleton object GitHubApiCaller with an OkHttpClient (OkHttp), a Jackson mapper and a simple Map that’s used for caching results. The code of getKotlinContributor can be decomposed into the following sub-tasks:
* When the result is already cached, return it immediately and skip the rest
* Create a request object using the ENDPOINT
* Get the response by executing the request on the client
* Extract the JSON data from the response object (Error handling omitted)
* De-serialize the JSON to an Array
* Filter for the contributor that is searched for
* Cache the result and return it to the client

In my opinion, this code is very comprehensive and everybody is able to make use of it. Nevertheless, it can be taken as a good basis for a little refactoring.

Reviewing the Code

Let’s now try to find some appropriate use cases for scope functions in the previously shown function.

Refactoring No. 1

The first thing that we can improve is the if block in the very beginning:


val cachedLeadResult = cachedLeadResults[name]
if (cachedLeadResult != null) {
    println("return cached: $cachedLeadResult")
    return cachedLeadResult
}

As shown earlier, the let function is normally used for resolving these kinds of if blocks. Applied to the concrete example, we get the following:


return cachedLeadResults[name]?.let {
    LOG.debug("return cached: $it")
    it
}

The problem here is that let is defined with a generic return type R so that the it needs to be written at the end in order to make it the return value of the expression. Another obvious insufficiency is the missing else statement. The first problem can be addressed pretty easily. We just need to use a scope function that returns its receiver, i.e. the cached result, directly from the block. Additionally, it should still expose the receiver as it, which makes also the best suitable candidate:


@Synchronized
fun getKotlinContributor(name: String): Contributor {
    return cachedLeadResults[name]?.also {
        LOG.debug("return cached: $it")
    } ?: requestContributor(name)
}

The Elvis operator, shown before, is very often used for handling the else case, i.e. when the receiver is null. In order to make the code more readable, a private function requestContributor now handles the cache miss.

That’s it, the if block was replaced with an easy also invocation. A more idiomatic solution.

Refactoring No. 2

The next portion that is worth reconsidering contains an unnecessary local variable that represents the request object:


val request = Request.Builder().url(ENDPOINT).build()
val response = client.newCall(request).execute()

It’s literally only used for getting a response object from the client and could therefore simply be inlined. Alternatively, the shown actions can be thought of as a basic transformation, which we learned to express with the let function:


val response = 
    Request.Builder().url(ENDPOINT).build().let { client.newCall(it).execute() }

The request has been made the context object of let and directly gets executed in a straightforward transformation. It makes the local request variable obsolete without affecting readability negatively.

Refactoring No. 3

The following snippet points at another if (obj != null) block, which in this case can actually be solved with let:


// Before Refactoring
val responseAsString = response.use {
    val responseBytes = it.body()?.source()?.readByteArray()
    if (responseBytes != null) {
        String(responseBytes)
    } else throw IllegalStateException("No response from server!")
}

// With Scope Function
 val responseAsString = response.use {
    it.body()?.source()?.readByteArray()?.let { String(it) }
        ?: throw IllegalStateException("No response from server!")
}

Again, the Elvis operator handles the null scenario very nicely.

Refactoring No. 4

Moving on to the next two statements of the code, we observe that the responseAsString variable is being logged and finally used for the Jackson de-serialization. Let‘s group them together:


// Before Refactoring
LOG.debug("response from git api: $responseAsString\n")
val contributors =
     mapper.readValue<Array>(responseAsString)

// With Scope Function
val contributors = responseAsString.let {
    LOG.debug("response from git api: $it\n")
     mapper.readValue<Array>(it)
}

Refactoring No. 5

After the first few refactorings, the situation looks as follows: We have a response, a responseAsString and a contributors variable and still need to filter the Contributors for the desired entry. Basically, the whole requesting and response handling is not relevant for the last step of filtering and caching. We can smoothly group these calls and confine them to their own scope. Since these actions happen with the help of the OkHttpClient, it makes sense to make the client the context object of that scope:


private fun requestContributor(name: String): Contributor {
    val contributors =
        with(client) {
            val response =
                Request.Builder().url(ENDPOINT).build().let { newCall(it).execute() }

            val responseAsString = response.use {
                it.body()?.source()?.readByteArray()?.let { String(it) }
                        ?: throw IllegalStateException("No response from server!")
            }

            responseAsString.let {
                LOG.debug("response from git api: $it\n")
                 mapper.readValue<Array>(it)
            }
        }
    //...
}

There isn’t any new code here, the previous edits have simply be wrapped in a call of with and are therefore not visible to the surrounding scope (function requestContributors) anymore. It made sense to use with in this case since it exposes client as this and the newCall invocation can therefore omit its qualifier. As described earlier, with can have an arbitrary result R. In this case, the last statement inside the lambda, the result of the last let call, becomes that R.

Refactoring No. 6

Now a single variable contributors is available in the outer scope and we can apply the filtering:


 return contributors.first { it.login == name }.also {
    cachedLeadResults[name] = it
    LOG.debug("found kotlin contributor: $it")
}

The previous version of the above code consisted of four independent statements that are now grouped in a simple also call with the filtered Contributor as its receiver. That receiver is put in the cache and also logged for debugging purposes. Of course, since also returns its receiver directly, the whole statement can be made the return of the function.

The entire function looks like this:


private fun requestContributor(name: String): Contributor {
    val contributors =
        with(client) {
            val response =
                Request.Builder().url(ENDPOINT).build().let { newCall(it).execute() }

            val responseAsString = response.use {
                it.body()?.source()?.readByteArray()?.let { String(it) }
                        ?: throw IllegalStateException("No response from server!")
            }

            responseAsString.let {
                LOG.debug("response from git api: $it\n")
                 mapper.readValue<Array>(it)
            }
        }

    return contributors.first { it.login == name }.also {
        cachedLeadResults[name] = it
        LOG.debug("found kotlin contributor: $it")
    }
}

In my opinion, the code looks very well structured and still readable. Yet, I don’t want to encourage the readers to apply scope functions in every situation after reading this article. It’s very important to know that this set of functions is so powerful that they could even be used to chain an unlimited amount of expressions and make them a single expression. You don’t want to do that because it messes up the code very quickly. Try to find a balance here and don’t apply scope functions everywhere.

Conclusion

In this article, I discussed the powerful set of scope functions of the Kotlin standard library. Many situations can be solved in a very idiomatic way with the help of these functions and it’s vital to have a rough idea of the differences between them. Try to memorize that there are scope functions that can return arbitrary values (let, run, with) and those that return the receiver itself (apply, also). Then there are functions, which expose their receiver as it (let, also) and others, which expose their receiver as this (run, apply, with). The concluding example demonstrated how easily scope functions may be used for refactoring appropriate code sections according to the earlier learned concepts. You shouldn’t get the impression that every single opportunity should actually be embraced; it’s still necessary to reason about the application of scope functions. Also, you shouldn’t try to use all of the shown functions at any price since most of them can be used interchangeably sometimes. Try to find your own favorites 🙂

You can find the shown code examples in this GitHub Repo.

Feel free to contact me and follow on Twitter. Also, check out my Getting Started With Kotlin cheat sheet here.

If you want to read more about Kotlin’s beautiful features I highly recommend the book Kotlin in Action and my other articles to you.

Please follow and like this Blog 🙂
Kotlin Quick Reference – Getting Started with Kotlin

Kotlin Quick Reference – Getting Started with Kotlin

Introduction

Disclaimer: This reference has originally been published as a DZone Refcard.

Kotlin has become one of the most popular JVM languages in the past few months. One special reason is that it experienced a lot of attention in the Android community after Google made Kotlin an official language for Android development. Kotlin is being developed by JetBrains, who are responsible for the most famous IDEs out there, most notably IntelliJ IDEA. Nevertheless, it’s an open source language, which can be found on GitHub.

The language is said to be very concise, safe in terms of error frequency, interoperable with Java and also offers many features that enable functional programming, writing type-safe DSLs and much more. Beside the JVM, Kotlin can compile for most Android versions, down to machine code using LLVM and can also be transpiled to JavaScript.
Kotlin has already been adopted in many popular frameworks and tools such as Spring and Gradle. It continues to gain traction in multiple domains, and there has never been a better time to get started with Kotlin.

Where to Start Coding

When you want to start writing your first Kotlin code there are quite a few ways to do that. Apparently, the recommended way is to work with IntelliJ IDEA, which offers the best support. As an alternative, one could also start with the command line or use JetBrains’ Kotlin web IDE to do some Kotlin Koans. Whichever way you prefer, corresponding tutorials can be found here: kotlinlang.org/docs/tutorials/.

Basic Syntax

Kotlin was inspired by many modern programming languages like C#, Groovy, Scala and also Java. Even more, Kotlin can be seen as an extension to the Java language, making it better by adding functionality to existing standard classes (e.g. String, List) and of course by providing great features, which are in large part enabled by applying compiler-supported techniques. As in Java, Kotlin programs are entered via a main method, such as the following:

fun main(args: Array): Unit {
    val inserted = "Kotlin"
    println("Let's get started with $inserted")
}

What we can see in this snippet is:

  • Functions are initiated by the keyword fun, followed by a name
  • Parameters and also variables in Kotlin are declared by defining a name and a type, both separated by a colon as you can see in args: Array
  • The return type of the main is Unit, also prefaced by a colon. In case of a Unit return, which corresponds to Java’s void, the compiler does not require you to explicitly define the return type, so the part : Unit could be omitted
  • Kotlin does not require you to use semicolons for separating statements (in most cases)
  • Type inference is supported in many situations as shown with val inserted, which also could be declared with an explicit type as val inserted: String
  • String templates can be used, which means that it’s possible to include variables and even expressions in Strings directly using $varname or ${statement} syntax
  • main is declared without a wrapping class around it. Functions and variables in Kotlin may be declared at “top-level”, i.e directly inside a package
  • No visibility modifier is used here. Functions, classes, variables etc. are public by default. When different visibility is needed, choose from:
KeywordEffect on Top-Level declarations [1]Effect on Class Members
publicvisible everywherevisible everywhere if class is accessible
privatevisible inside the file onlyvisible inside the class only
protectedvisible in class and subclasses
internalvisible inside the same module [2]visible in the same module, if class is accessible

1: Functions, properties and classes, objects and interfaces can be declared on the “top-level”
2: A module is a set of Kotlin files compiled together: an IntelliJ IDEA module, a Maven project, a Gradle source set

  • Variables defined as val cannot be re-assigned, i.e. are read-only. Alternatively, if mutability is inevitable, var can be utilized, as shown in the next example:
var mutableVar = StringBuilder("first")
mutableVar = StringBuilder("second")
  • Constructor is invoked without the new keyword, which is omitted from kotlin

Control Flow: Conditions

In Kotlin you can make use of if, when, for and while for controlling the behavior of your code. Let’s look at conditions first.

If-Statement

val min: Int
if (x < y) {
    min = x
} else {
    min = y
}

It’s important to know, that many statements in Kotlin can also be used as expressions, which for instance makes a ternary operator obsolete and apparently shortens the code in most cases:

val min = if (x < y) x else y 

When-Statement

A when statement is very similar to switch operators and could, in theory, easily replace if-statements as they are much more powerful.

val y = when (x) {
    0 -> "is zero"
    1 -> "is one"
    2, 3 -> "two or three"
    is Int -> "is Int"
    is Double -> "is Double"
    in 0..100 -> "between 0 and 100"
    else -> "else block"
}

In a when statement, which can also be used as an expression, all branches are tried to match the input until one condition is satisfied. If no branch matches, the else is executed. As shown in the snippet, when branch conditions can be values, types, ranges and more.

Control Flow: Loops

For-Loop

In Kotlin, there’s no conventional for-loop, as you know it from C or Java. Instead, foreach loops are the default.

for (c in "charSequence") {
    println(c)
}

In many cases, looping with an index is necessary, which can easily be achieved with the indices property that is defined for arrays, lists and also CharSequences for example.

for (i in "charSequence".indices) {
    println("charSequence"[i])
}

Another way of iterating with indices is possible by using withIndix().

for ((i,c) in "charSequence".withIndex()) {
    println("$i: $c")
}

Last but not least, Kotlin has ranges, which can also be utilized for indexed iterations as the following shows:

(0 .. "charSequence".length-1).forEach {
    print("charSequence"[it])
}

The range in this example is expressed with the common .. syntax. To create a range which does not include the end element (s.length), the until function is used: (0 until s.length).

While-Loop

Constructs with while or do-while loops are straight-forward, all works as known from other common languages.

Basic Types

In Kotlin everything looks like an object to the user, even primitive types. This means, member functions can be called on every type, although some will be represented as JVM primitives at runtime.

Numbers

The default number types are: Double, Float, Long, Int, Short, Byte
* Underscores can be used to make large numbers more readable: val million = 1_000_000
* Number types offer conversion methods like toByte(): Byte, toInt(): Int , toLong(): Long
* Characters are no number type in Kotlin

Chars

A Char represents characters and cannot be treated as a number.
* They are declared within single quotes, e.g. '42'
* An explicit conversion from a Char to an Int can be accomplished with the toInt() method

Booleans

Booleans can have the two common values true and false
* They can be operated on with: ||, && and !

Strings

Strings are immutable sequences of characters.
* They offer an index operator [] for accessing characters at specified positions
* A string literal in Kotlin looks like "Hello World" or """Hello World with "another String" in it"""
* The latter is called raw string that can contain any character without needing to escape special symbols
* Strings in Kotlin may contain template expressions

Arrays

An array is represented by the class Array, which offers very useful methods to the client.
* Values can be obtained via get(index) or [index]
* Values can be set via set(index, value) or [index]=value
* Arrays are invariant, i.e. an Array cannot be assigned to a variable of type Array
* Special types for arrays of primitive types exist as IntArray or ShortArray for instance. Using those will reduce the boxing overhead.

Classes

A simple class can be declared like in this snippet:

class Person constructor(name: String) {}

The primary constructor is part of the class header, secondary constructors can be added in the class body. In the shown case, the constructor keyword could also be omitted, since it’s only mandatory if you want to add annotations or visibility modifiers (default: public).
Constructor parameters such as name can be used during the initialization of an object of this class. For this purpose, an init block would be necessary, because primary constructors can’t contain code directly. Constructor arguments can also be used in property initializers that are declared in the class body, as shown here.

class Person(name: String, age: Int) {
    init {
        println("new Person $name will be born.")
    }
    val ageProp = age
}

As mentioned, Kotlin classes can contain properties, which are accessed by simply calling obj.propertyName to get a property’s value and obj.propertyName = "newValue" to modify the value of a mutable (var) property. Declaring properties for classes can also be done in the primary constructor directly, which makes the code even more concise. Like in all methods, Kotlin supports default parameters for parameters, set with “=“.

class Person(val name: String, val age: Int = 50)

Same as with local variables, instead of val, a property can be declared mutable using var instead. Note that you don’t have to write an empty class body if no content is defined.

Special Classes

Besides ordinary classes, Kotlin knows a few special class declarations, which are worth knowing. The following will give a quick overview.

TypeExplanation
data classAdds standard functionality for toString, equals, hashCode etc.
sealed classRestricts class hierarchies to a set of subtypes. Useful with when
Nested classClasses can be created in other classes, also known as “inner class”
enum classCollect constants that can contain logic
object declarationsUsed to create Singletons of a type

Of course, Kotlin also supports inheritance through interfaces and abstract classes.

Function Types and Lambdas

In order to be able to understand idiomatic Kotlin code, it’s essential to recognize how function types and especially lambdas look like. Just as you can declare variables of type Int or String, it’s also possible to declare variables of function types, e.g. (String) -> Boolean.

val myFunction: (String) -> Boolean = { s -> s.length > 3 }
myFunction("HelloWorld")

The variable is declared as a function type that takes a String argument and returns a Boolean. The method itself is defined as a lambda enclosed in curly braces. In the shown lambda, the String parameter is declared and named before the -> symbol, whereas the body follows after it.

Lambda Special Syntax

The language designers decided on some special lambda features, which make the usage even more powerful.

  1. it: implicit name of single parameters

In many cases, lambdas are used with single parameters like in the previous example. In such situations, you don’t have to give the parameter an explicit name. Instead, the implicit name it can be used.

val myFunction: (String) -> Boolean = { it.length > 3 }
myFunction("HelloWorld")
  1. For unused parameters, use _

In some cases, it might be unnecessary to make use of every possible available parameter in a lambda. The compiler warns the developer about such unused variables, which can be avoided by naming it with an underscore.

val myFunction: (String, Int) -> Boolean = { s, _ -> s.length > 3 }
myFunction("HelloWorld", 42)

Higher-Order Functions

If a function takes another function as an argument or returns another function as its result, it’s called a higher-order function. Such functions are essential in Kotlin as many library functions rely on this concept. Let’s see an example.

fun main(args: Array) {
    myHigherOrderFun(2, { it.length > 2 })
}

fun myHigherOrderFun(iterations: Int, test: (String) -> Boolean){
    (0 until iterations).forEach {
        println("$it: ${test("myTestString")}")
    }
}

The function myHigherOrderFun defines two parameters, one of which is another function test. The function takes test and applies a String to it multiple times depending on what the first argument iterations is. By the way, the example uses a range to imitate an indexed for loop here.

The shown main function demonstrates the usage of a higher-order function by calling it with an anonymous function. The syntax looks a bit messy, which is why the language designers decided on a very important convention: If a lambda is the last argument to a function, it can be placed after the closing parentheses or, if it’s the only argument, the parentheses can be omitted completely like shown with forEach above. The following snippet demonstrates this convention applied to an invocation of myHigherOrderFun.

//Lambda after closing parentheses
myHigherOrderFun(2) {
    it.length>2
}

Top Features

There are some features in Kotlin, everybody should be familiar with. These are essential for many libraries, standard functions and also advanced features like Domain Specific Language support.

Null-Safety

The type system differentiates between nullable and non-null types. By default, a class like String cannot reference null, which raises the attention for null-related problems. As opposed to String, the type String? can hold null. This does not make a big difference on its own. Therefore, working with nullable types implies having to handle nullable values in a special way.

var b: String? = "couldBeNull"
b = null //okay

// 1. Access directly: does not compile, could throw NPE
// val len = b.length

//2. Use safe-operator
val len = b?.length

//3. Check nullability before accessing
if(b != null){
    b.length
}

It’s possible to check whether a variable is not null before accessing it. In such cases, the compiler permits the usage without special safety measures. Alternatively, b?.length expresses: call length on b if it’s not null, otherwise the expression returns null. The return is of type Int? because null may be returned. Chaining such calls is possible, which is very useful. Other operators used with nullable types are shown in the following overview.

| Operator | Use case | Example
| ——————- | —————————— | —————- |
| !! | Ignore warnings of compiler and overcome null checks. Use cautiously only. | val x: String? = "nullable"
x!!.length |
| ?: | The elvis operator is used to give an alternative for null results. | val x: String? = "nullable"
val len: Int = b?.length ?: 0
| as? | A safe cast tries to cast a variable in a type and results in null if the cast is not possible. | val i: Int? = s as? Int

Extensions

Another essential feature of Kotlin is extensions. An extension is used to extend a class with new functionality without having to inherit from that class. Extensions can have the form of properties and functions. The Kotlin standard library contains a lot of such extensions, like the following defined on String:

public fun String.substring(range: IntRange): String = substring(range.start, range.endInclusive + 1)

//usage
"myString".substring(0..3)

In this example String is the receiver of the defined substring(range: IntRange) function. An extension function can use visible members of its receiver without additional qualifiers since this refers to the receiver. In the snippet, String‘s standard method substring(startIndex: Int, endIndex: Int) is called in that way. The extension is called on a String as if it was a regular method.

It’s also possible to extend a class with properties. For example, Int can be extended with a property that represents its version of BigDecimal. This might be useful if otherwise, the constructor of BigDecimal had to be used many times.

val Int.bd
get() = BigDecimal(this)

val bd: BigDecimal = 5.bd

Extensions are mostly defined on top-level and can be used in other files after they have been imported explicitly.

Lambda with Receiver

Higher-order functions can be even more powerful if used with “lambdas with receiver”. It’s possible to call function literals with a specific receiver object, similar to the extension functions. As a result, members of the receiver can directly be accessed inside the lambda without having to use additional qualifiers. This feature is the foundation for Kotlin’s fantastic support for writing Type-Safe Builders, also known as Domain Specific Languages.

fun T.apply(block: T.() -> Unit): T {
    block()
    return this
}

This snippet shows a slightly simplified version of the apply function, which is part of Kotlin’s standard library. It’s an extension function on the generic type T, thus can be used with any object. The function takes a function literal with T as its receiver and executes the block before this (the receiver of apply) is being returned.

data class GuiContainer(var width: Int = 0, var height: Int = 0, var background: String = "red") {
    fun printMe() = println(this)
}

fun main(args: Array) {
    val container = GuiContainer().apply {
        width = 10
        height = 20
        background = "blueish"
        printMe()
    }
}

In this example, the data class GuiContainer is created with default parameters and then the apply method is called on it. It’s possible to set mutable properties and call methods of the receiver GuiContainer like shown with the invocation of printMe() in the end. Since apply returns the receiver after it completes, it can directly be assigned to a variable.

Idiomatic Kotlin

Kotlin tries to encourage particular coding idioms to be used. These are partially listed in the documentation and also in some community driven articles. The following will present some of these idioms by example.

  1. Use when as an expression if possible
fun analyzeType(obj: Any) =
    when(obj){
        is String -> "is String"
        else -> "no String"
    }
  1. Use elvis operator with throw and return to handle nullable values

class Person(val name: String?, val age: Int?) fun process(person: Person) { val pName = person.name ?: throw IllegalArgumentException("Name must be provided.") println("processing $pName") val pAge = person.age ?: return println("$pName is $pAge years old") }
  1. Make use of range checks
fun inLatinAlphabet(char: Char) = char in 'A'..'Z'
  1. Prefer default parameters to function overloads
fun greet(person: Person, printAge: Boolean = false) {
    println("Hello ${person.name}")
    if (printAge)
        println("${person.name} is ${person.age} years old")
}
  1. Use type aliases for function types
typealias StringPredicate = (String) -> Boolean

val pred: StringPredicate = {it.length > 3}
  1. Use data classes for multiple return values
data class Multi(val s: String, val i: Int)

fun foo() = Multi("one", 1)

fun main(args: Array){
    val (name, num) = foo()
}
  1. Prefer extension functions to utility-style functions
fun Person.greet(printAge: Boolean = false) {
    println("Hello $name")
    if (printAge)
        println("$name is $age years old")
}
  1. Use apply for object initialization
data class GuiContainer(var width: Int = 0, var height: Int = 0, var background: String = "red") {
    fun printMe() = println(this)
}

fun main(args: Array) {
    val container = GuiContainer().apply {
        width = 10
        height = 20
        background = "blueish"
        printMe()
    }
}
  1. Use compareBy for complex comparisons
fun sort(persons: List): List =
    persons.sortedWith(compareBy(Person::name, Person::age))
  1. Use mapNotNull to combine map and filter for non-null values
fun getPersonNames(persons: List): List =
    persons.mapNotNull { it.name }
  1. Use object to apply Singleton pattern
object PersonRepository{
    fun save(p: Person){}
//...
}

//usage
val p = Person("Paul", 40)
PersonRepository.save(p)
  1. Do not make use of !!
//Do not use !!, there's always a better solution
person!!.address!!.street!!.length
  1. Prefer read-only data structures
//Whenever possible, do not use mutable Data Structures

val mutableList: MutableList = mutableListOf(1, 2, 3)
mutableList[0] = 0

val readOnly: List = listOf(1, 2, 3)
readOnly[0] = 0 // Does not compile
  1. Use let to execute code if receiver is not null
fun letPerson(p: Person?) {
    p?.let {
        println("Person is not null")
    }
}

Resources

Language References:
Official Reference Documentation: https://kotlinlang.org/docs/reference/
GitHub repository: https://github.com/JetBrains/kotlin
Collection of Tools and Frameworks: https://kotlin.link
Operators and Keywords Overview: https://kotlinlang.org/docs/reference/keyword-reference.html

Community:
Slack: https://kotlinlang.slack.com
Twitter: https://twitter.com/kotlin
Newsletter: http://kotlinweekly.net
Discussion: https://discuss.kotlinlang.org

Blogs:
JetBrains: https://blog.jetbrains.com/kotlin/
Simon Wirtz: https://kotlinexpertise.com

Misc:
Kotlin in Action Book: Kotlin in Action
Books: https://kotlinlang.org/docs/books.html
Online IDE: https://try.kotlinlang.org

Please follow and like this Blog 🙂
The Power of Gradle Kotlin DSL

The Power of Gradle Kotlin DSL

-The following is based on Gradle 4.3.1-

A few weeks ago I started migrating most of my Groovy-based gradle.build scripts to Kotlin-backed gradle.build.kts scripts using the Kotlin DSL. Why would I do that? Kotlin is my language of choice and I love the idea of using a single language to do all my work. I never learned programming with Groovy and only know the bloody basics, which always makes me think: “This can’t be the best way to do things…”. Kotlin, on the other hand, is a language I use on a daily basis and therefore I know how to use the language appropriately. Additionally, Kotlin is a statically-typed language, whereas Groovy isn’t. IDEs are having hard times offering code completion and error detection at compile time when a Groovy build script is being edited. As for the Kotlin DSL, this isn’t true. Especially IntelliJ knows how to help us with Kotlin development, even in gradle.build.kts files. All these reasons made me take a deeper look at the new style Gradle offers.

Minor Impediments

It can sometimes be a bit tedious to rewrite your gradle.build into gradle.build.kts files, especially in the IDE with all its caches malfunctioning during that process. I often had to reopen my project or even reimport it before IntelliJ understood what was going on. It also often helps to use “Refresh all Gradle projects” button in the Gradle view.

Let’s take a look

The following snippet shows the first part of a working example. It was taken from one of my projects, which is a Kotlin web application based on the Vert.x toolkit. Learn more about the technology in this post I wrote earlier.

The script first defines a few global variables, mostly containing version numbers, which are used throughout the build file. Next, we can observe the plugins block that simply defines a few plugins used for the build. Most importantly, the Kotlin Gradle plugin for JVM applications is included, which we can do with the DSL-specific function kotlin(module: String), that takes its module argument and appends it to "org.jetbrains.kotlin.", which then is put into the id(plugin: String) method, the default api for applying plugins. Last but not least, we can see the listing of dependencies, which again provides a kotlin convenience method we can use to reduce redundant declarations. A similar approach can be seen with the definition of the io.vertx dependencies. In order to only once write the "io.vertx.vertx" String, which is part of every single Vert.x dependency, it’s used as a receiver of let. A first example of real idiomatic code within the build script.

//imports

//taken from the `plugins` defined later in the file
val kotlinVersion = plugins.getPlugin(KotlinPluginWrapper::class.java).kotlinPluginVersion
val kotlinCoroutinesVersion = "0.19.3"

val vertxVersion = "3.5.0" //
val nexusRepo = "http://x.x.x.x:8080/nexus/content/repositories/releases"

plugins {
    kotlin("jvm").version("1.2.0")
    application
    java
    `maven-publish`
}

dependencies {
    compile(kotlin("stdlib", kotlinVersion))
    compile(kotlin("reflect", kotlinVersion))
    compile("org.jetbrains.kotlinx:kotlinx-coroutines-core:$kotlinCoroutinesVersion")

    "io.vertx:vertx".let { v ->
        compile("$v-lang-kotlin:$vertxVersion")
        compile("$v-lang-kotlin-coroutines:$vertxVersion")
        compile("$v-web:$vertxVersion")
        compile("$v-mongo-client:$vertxVersion")
        compile("$v-health-check:$vertxVersion")
        compile("$v-web-templ-thymeleaf:$vertxVersion")
    }

    compile("org.slf4j:slf4j-api:1.7.14")
    compile("ch.qos.logback:logback-classic:1.1.3")
    compile("com.fasterxml.jackson.module:jackson-module-kotlin:2.9.0.pr3")

    testCompile(kotlin("test", kotlinVersion))
    testCompile(kotlin("test-junit", kotlinVersion))
    testCompile("io.vertx:vertx-unit:$vertxVersion")
    testCompile("org.mockito:mockito-core:2.6.2")
    testCompile("junit:junit:4.11")
}

// Part 2
}

The second part of the example project starts with defining repositories, which are used to find dependencies and plugins declared earlier. Again, we see an example of simplifying the code with the help of using the language: The custom Maven repositories are defined using the functional method forEach, and thus shortens the boilerplate. After that, the plugins are being configured, which for instance is necessary for enabling coroutine support or defining the application properties. Finally, we can observe a sequence of task configurations that control the behavior of single build steps, e.g. tests.

// ...Part 1

repositories {
    mavenCentral()
    jcenter()
    listOf("https://www.seasar.org/maven/maven2/",
            "https://plugins.gradle.org/m2/",
            nexusRepo).forEach {
        maven { url = uri(it) }
    }
}

kotlin {
    experimental.coroutines = Coroutines.ENABLE
}

application {
    group = "de.swirtz"
    version = "1.0.0"
    applicationName = "gradle-kotlindsl"
    mainClassName = "de.swirtz.ApplicationKt"
}

publishing {
    repositories {
        maven {
            url = uri(nexusRepo)
        }
    }
    if (!project.hasProperty("jenkins")) {
        println("Property 'jenkins' not set. Publishing only to MavenLocal")
    } else {
        (publications) {
            "maven"(MavenPublication::class) {
                from(components["java"])
            }
        }
    }
}

tasks {
    withType<KotlinCompile> {
        kotlinOptions.jvmTarget = "1.8"
    }

    withType<Test> {
        testLogging.showStandardStreams = true
    }

    withType<Jar> {
        manifest {
            attributes["Main-Class"] = application.mainClassName
        }
        from(configurations.runtime.map { if (it.isDirectory) it else zipTree(it) })
    }

    withType<GradleBuild> {
        finalizedBy("publishToMavenLocal")
    }
}

The Result

We’ve seen a rather simple build script written with the Gradle Kotlin DSL. I made use of a few idiomatic Kotlin functions in order to show the power of such .kts files. Especially for Kotlin developers, it can make much sense to completely switch to the shown approach. IntelliJ does support the creation of new build.gradle.kts files by default when you open the “New” option in “Project” view.

There will be situations, which make you want to ask somebody for help. I recommend reaching out directly in the corresponding Kotlin Slack channel: gradle.

I hope I could inspire you to give it a try! Good Luck 🙂

The whole script as a Gist

Please follow and like this Blog 🙂
Web Applications with Kotlin ktor

Web Applications with Kotlin ktor

Introduction

Disclaimer: This ktor article was originally published in the Dzone Web Development Guide, which can be downloaded here.

When Google made Kotlin an official language for Android a few months ago at Google I/O, the language gained a lot of popularity in the Android world quickly. On the server side though, Kotlin is not as broadly adopted yet and some people still seem to be cautious when backend services are involved. Other developers are convinced that Kotlin is mature enough and can safely be used for any server application in which Java could play a role otherwise.
If you want to develop web apps with Kotlin, you can choose from various web frameworks like Spring MVC/WebFlux, Vert.x, Vaadin and basically everything available for the JVM. Besides the mentioned frameworks there’s also a Kotlin specific library available for creating web applications, called ktor. After reading this article, you’ll know what ktor and its advantages are and how you can quickly develop a web application in Kotlin.

Ktor

The web application framework ktor, itself written in Kotlin, is meant to provide a tool for quickly creating web applications with Kotlin. The resulting software may be hosted in common servlet containers like Tomcat or standalone in a Netty for example. Whatever kind of hosting you choose, ktor is making heavy use of Kotlin Coroutines, so that it’s implemented 100% asynchronously and mainly non-blocking. ktor does not dictate which frameworks or tools to be used, so that you can choose whatever logging, DI, or templating engine you like. The library is pretty light-weight in general, still being very extensible through a plugin mechanism.
One of the greatest advantages attributed to Kotlin is its ability to provide type-safe builders, also known as Domain Specific Languages (DSL). Many libraries already provide DSLs as an alternative to common APIs, such as the Android lib anko, the Kotlin html builder or the freshly released Spring 5 framework. As we will see in the upcoming examples, ktor also makes use of such DSLs, which enable the user to define the web app’s endpoints in a very declarative way.

Example Application

In the following, a small RESTful (Not sure, if everyone will agree) web service will be developed with ktor. The service will use an in-memory repository with simple Person resources, which it exposes through a JSON API. Let’s look at the components.

Person Resource and Repository

According to the app’s requirements, a resource “Person” is defined as a data class and the corresponding repository as an object, Kotlin’s way of applying the Singleton pattern to a class.


data class Person(val name: String, val age: Int){
    var id: Int? = null
}

The resource has two simple properties, which need to be defined when a new object is constructed, whereas the id property is set later when stored in the repository.
The Person repository is rather unspectacular and not worth observing. It uses an internal data store and provides common CRUD operations.

Endpoints

The most important part of the web application is the configuration of its endpoints, exposed as a REST API. The following endpoints will be implemented:

EndpointHTTP MethodDescription
/personsGETRequests all Person resources
/persons/{id}GETRequests a specific Person resource by its ID
/personsDELETERequests all Person resources to be removed
/persons/{id}DELETERequests a specific Person resource to be removed by its ID
/personsPOSTRequests to store a new Person resource
/GETDelivers a simple HTML page welcoming the client

The application won’t support an update operator via PUT.

Routing with Ktor

Now ktor comes into play with its structured DSL, which will be used for defining the previously shown endpoints, a process often referred to as “routing”. Let’s see how it works:


fun Application.main() {
    install(DefaultHeaders)
    install(CORS) {
        maxAge = Duration.ofDays(1)
    }
    install(ContentNegotiation){
        register(ContentType.Application.Json, GsonConverter())
    }

    routing {
        get("/persons") {
            LOG.debug("Get all Person entities")
            call.respond(PersonRepo.getAll())
        }
    }
    // more routings
}

The fundamental class in the ktor library is Application, which represents a configured and eventually running web service instance. In the snippet, an extension function main() is defined on Application, in which it’s possible to call functions defined in Application directly, without additional qualifiers. This is done by invoking install() multiple times, a function for adding certain ApplicationFeatures into the request processing pipeline of the application. These features are optional and the user can choose from various types. The only interesting feature in the shown example is ContentNegotiation, which is used for the (de-)serialization of Kotlin objects to and from JSON, respectively. The Gson library is used as a backing technology.
The routing itself is demonstrated by defining the GET endpoint for retrieving all Person resources here. It’s actually straight-forward since the result of the repository call getAll() is just delegated back to the client. The call.respond() invocation will eventually reach the GsonSupport feature taking care of transforming the Person into its JSON representation. The same happens for the remaining four REST endpoints, which will not be shown explicitly here.

The HTML builder

Another cool feature of ktor is its integration with other Kotlin DSLs like the HTML builder, which can be found on GitHub. By adding a single additional dependency to a ktor app, this builder can be used with the extension function call.respondHtml(), which expects type-safe HTML code to be provided. In the following example, a simple greeting to the readers is included, which the web service exposes as its index page.


get("/") {
    call.respondHtml {
        head {
            title("ktor Example Application")
        }
        body {
            h1 { +"Hello DZone Readers" }
            p {
                +"How are you doing?"
            }
        }
    }
}

Starting the Application

After having done the configuration of a ktor application, there’s still a need to start it through a regular main method. In the demo, a Netty server is started standalone by doing the following:


fun main(args: Array) {
    embeddedServer(Netty, 8080, module = Application::main).start(wait = true)
}

The starting is made pretty simple by just calling the embeddedServer() method with a Netty environment, a port and the module to be started, which happens to be the thingy defined in the Application.main() extension function from the previously shown example.

Testing

A web framework or library is only applicable if it comes with integrated testing means, which ktor actually does. Since the GET routing for retrieving all Person resources was already shown, let’s have a look at how the endpoint can be tested.


@Test
fun getAllPersonsTest() = withTestApplication(Application::main) {
    val person = savePerson(gson.toJson(Person("Bert", 40)))
    val person2 = savePerson(gson.toJson(Person("Alice", 25)))
    handleRequest(HttpMethod.Get, "/persons") {
        addHeader("Accept", json)
    }.response.let {
        assertEquals(HttpStatusCode.OK, it.status())
        val response = gson.fromJson(it.content, Array::class.java)
        response.forEach { println(it) }
        response.find { it.name == person.name } ?: fail()
        response.find { it.name == person2.name } ?: fail()
    }
    assertEquals(2, PersonRepo.getAll().size)
}

This one is quite simple: Two resource objects are added to the repository, then the GET request is executed and some assertions are done against the web service response. The important part is withTestApplication(), which ktor offers through its testing module and makes it possible to directly test the Application.
The article presented basically everything worth knowing in order to get started with ktor web applications. For more details, I recommend the ktor homepage or the samples included in the ktor repository.

Takeaways

In this article we had a look at the Kotlin web service library ktor that provides simple tools for writing a light-weight web application in Kotlin very quickly. ktor makes heavy use of Kotlin’s beautiful features, especially DSLs, Coroutines and extension functions, all of which make the language and ktor itself so elegant. This mainly separates ktor from other powerful frameworks, which in fact can be used with Kotlin very smoothly, but, since not completely written in Kotlin, lack certain features you can find in ktor. It’s a great place to start with web applications because of its simplicity and ability to be extended with custom features if needed, following the principle “simple is easy, complex is available”.
The complete source code of the developed web application can be found on GitHub, it’s backed by a Gradle build.

Please follow and like this Blog 🙂
Kotlin Features I miss most in Java

Kotlin Features I miss most in Java

My Life as a Java Dev

Although I’m a big supporter of the Kotlin programming language, I still do a lot of Java programming on a daily basis for my employer. Since I’m aware of the great functionalities of Kotlin, I’m often struggling with Java as it has some “pitfalls”, requires additional boilerplate and misses many features.
In this post, I’d like to describe which Kotlin features I miss most when coding in Java.

new and Semicolon

Ever since I’m doing Kotlin, there are two things I always forget when coding in Java: the new keyword for constructor invocations and the annoying ; to complete statements. Kotlin doesn’t have new and even semicolons are optional. I really appreciate this decision because it reduces the “syntactic noise“.

Data classes

In Kotlin, data classes are used for simple data containers, representing JSON objects or returning compound objects from functions amongst other use cases. Of course, Java doesn’t support this special type of classes yet. As a result, I often have to implement my own data class, which means a lot of boilerplate in Java.

One special use case is compound objects returned from functions. For example, let’s imagine a function that needs to return two objects. In Kotlin we could use a data class, or simpler, a Pair directly. In Java, I tend to create a value object, which is a class with several final fields, each of which instantiated through the constructor. Similar to Kotlin, I don’t implement getters and setters, but use the class’s fields directly as public properties. Unfortunately, this is not what we learned as best practice and most Java code style checkers will complain about it. I do not see any encapsulation issues here and it’s the least verbose approach in Java. The following shows such a compound object, the inner class Multi. In Kotlin this would be a one-liner.

public class MultiReturn {

    public static void main(String[] args) {
        new MultiReturn().useMulti();
    }

    public void useMulti() {
        Multi multi = helper();
        System.out.println("Multi with " + multi.count + " and " + multi.name);
    }

    private Multi helper() {
        return new Multi(2, "test");
    }
    
    private static class Multi {
        private final int count;
        private final String name;

        public Multi(int count, String name) {
            this.count = count;
            this.name = name;
        }
    }
}

Local Functions

In many situations, we tend to create private methods that are only used inside another single method in order to make this one more readable. In Kotlin, we can use local functions, i.e. functions inside functions (inside functions…), which enables some kind of scope. For me, this is a much cleaner approach, because the function is only accessible inside the function that actually uses the local one. Let’s look at an example.


fun deployVerticles() {

    fun deploy(verticleClassName: String) {
        vertx.deployVerticle(verticleClassName, opt, { deploy ->
            LOG.info("$verticleClassName has been deployed? ${deploy.succeeded()}")
        })
    }

    deploy("ServiceVerticle")
    deploy("WebVerticle")
}

It’s taken from a sample vert.x application and defines a local function that is reused twice afterward. A great way to simplify your code.

Single Expression Functions

We can create single expression functions in Kotlin, i.e. functions without an actual body. Whenever a function contains only a single expression, it can be placed after a = sign following the function declaration:


fun trueOrFalse() = Random().nextBoolean()

In Java, on the other hand, we always have to use a function body enclosed in {}, which ranges over at least three lines. This is also “syntactic noise” I don’t want to see anymore. To be fair, Java 1.8 makes it possible to define lambdas which can also solve this, less readable though (Can also be applied to local functions):


public class SingleExpFun {

    private BooleanSupplier trueOrFalse = new Random()::nextBoolean;

    private boolean getNext(){
        return trueOrFalse.getAsBoolean();
    }
}

Default Parameters

One very annoying part of Java is the way methods have to be overloaded. Let’s see an example:

public class Overloade
    public static void main(String[] args) {
        Overloader o = new Overloader();
        o.testWithoutPrint(2);
        o.test(2);
    }

    public void test(int a, boolean printToConsole) {
        if (printToConsole) System.out.println("int a: " + a);
    }

    public void testWithoutPrint(int a) {
        test(a, false);
    }

    public void test(int a) {
        test(a, true);
    }

}

We can see a class with a method test(int, boolean) that is overloaded for the default case and also a convenience method is available. For more complex examples, it can lead to a lot of redundant code, which is simpler in Kotlin by using default parameters.


fun test(a: Int, printToConsole: Boolean = true) {
    if (printToConsole) println("int a: " + a)
}

fun testWithoutPrint(a: Int) = test(a, false)

fun main(args: Array) {
    testWithoutPrint(2)
    test(2)
}

Calling multiple methods on an object instance (with)

Obviously, Kotlin is more functional than Java. It makes use of higher-order functions in incredibly many situations and provides many standard library functions that can be used as such. One of my favorites is with, which I miss a lot whenever I can’t use Kotlin. The with function can be used to create scopes that actually increase the readability of code. It’s always useful when you sequentially call multiple functions on a single object.


class Turtle {
    fun penDown()
    fun penUp()
    fun turn(degrees: Double)
    fun forward(pixels: Double)
}

with(Turtle()) {
    penDown()
    for(i in 1..4) {
        forward(100.0)
        turn(90.0)
    }
    penUp()
}

The great thing is the usage of lambdas with receiver, which you can read about in one of my other posts.

Null-Safety

Whenever I work with nullable types since the time I started with Kotlin, I actually miss the type system’s tools to prevent null-related errors. Kotlin did a very good job by distinguishing nullable types from not-nullable ones. If you strictly make use of these tools, there is no chance you’ll ever see a NullpointerException at runtime.

Lambdas and Collection Processing

Kotlin places a lot of value on its lambdas. As shown in the with example earlier, there’s special syntax available for lambdas that makes its usage even more powerful. I want to underline that the way functions and especially lambdas are treated in the language makes it dramatically superior to Java. Let’s see a simple example of Java’s Streams, which were introduced along with lambdas in Java 1.8:

List list = people.stream().map(Person::getName).collect(Collectors.toList());

It’s a rather simple example of a Stream that is used to get a list of names from a list of persons. Compared to what we did before 1.8, this is awesome. Still, it’s too noisy compared to a real functional approach as pursued by Kotlin:

val list = people.map { it.name }

Or yet another example, in which salaries of employees are summed up to a total amount:

int total = employees.stream()
                      .collect(Collectors.summingInt(Employee::getSalary)));

So much simpler in Kotlin:

val total = employees.sumBy { it.salary }

The Kotlin examples show how simple it can be. Java isn’t a functional language and has a hard time trying to adopt functional features like lambdas and streams as we can easily observe in the snippets. It really sucks to go back to Java, if you ever experienced the beauty of Kotlin. Have you ever tried to use Eclipse after being familiar with IntelliJ? You know what I mean then.

Wrap-up

In this short post, I presented you my top Kotlin features I always miss when coding in Java. It’s just a selection of things, which will hopefully find their way into the Java language soon. But to be honest, there’s no reason to always wait for Java, when there already is a much sweeter language available… I want to point out, that starting with Kotlin really made me a much better programmer because I began wondering about certain features in both languages and also try to find ways to use Kotlin-dedicated things in Java by finding workarounds like arranging my code differently.

I’d be interested in the features you like most, feel free to comment.
Also, if you like, have a look at my Twitter account and follow if you’re interested in more Kotlin stuff 🙂 Thanks a lot.

If you want to read more about Kotlin’s beautiful features I recommend the book Kotlin in Action and my other articles to you.

Please follow and like this Blog 🙂
Kotlin Reified Types in Inline Functions

Kotlin Reified Types in Inline Functions

I’ve noticed that many people haven’t ever heard of reified types or have problems understanding what they are, and what they do. Therefore this little post is intended to bring some light into the darkness of Kotlin’s reified types.

Starting situation

fun <T> myGenericFun(c: Class<T>) 

In an ordinary generic function like myGenericFun you can’t access the type T because it’s, like in Java, erased at runtime and thus only available at compile time. Therefore, if you want to use the generic type as a normal Class in the function body you need to explicitly pass the class as a parameter like the parameter c in my example. That’s correct and works fine but makes it a bit unsightly for the caller.

Inlined function with reified to the rescue

If, on the other hand, you use an inline function with a reified generic type T, the value of T can be accessed even at runtime and thus you don’t need to pass the Class<T> additionally. You can work with T as if it was a normal Class, e.g. you might want to check whether a variable is an instance of T, which you can easily do like this: myVar is T.

An inline function with reified type looks like this:

inline fun <reified T> myGenericFun()

Be aware, that reified types can only be used in combination with inline functions. Such an inline function makes the compiler copy the function’s bytecode into every place where the function is being called (we say the function is being “inlined“). When you call an inline function with reified type, the compiler knows the actual type used as a type argument and modifies the generated bytecode to use the corresponding class directly. Therefore calls like myVar is T become myVar is String (if the type argument were String) in the bytecode and at runtime.

Reified in Action

Let’s have a look at an example, where reified is really helpful. We want to create an extension function for String called toKotlinObject, which tries to convert a JSON string to a Kotlin Object, specified by the function’s type T. We can use com.fasterxml.jackson.module.kotlin for this and the first approach is the following:

First approach without reified type

fun <T> String.toKotlinObject(): T {
      val mapper = jacksonObjectMapper()
                                    //does not compile!
      return mapper.readValue(this, T::class.java)
}

The readValue method takes a type that it’s supposed to parse the JsonObject to. If we try to get the Class of the type parameter T, the compiler complains: “Cannot use ‘T’ as reified type parameter. Use a class instead.”

Workaround with explicit Class parameter

fun <T: Any> String.toKotlinObject(c: KClass<T>): T {
    val mapper = jacksonObjectMapper()
    return mapper.readValue(this, c.java)
}

As a workaround, we pass the Class of T explicitly, which can directly be used as an argument to readValue. This works and is actually a common pattern in Java code for such scenarios. The function can be called like so:

data class MyJsonType(val name: String)

val json = """{"name":"example"}"""
json.toKotlinObject(MyJsonType::class)

The Kotlin way: reified

Using an inline function with reified type parameter T makes it possible to implement our function as follows:

inline fun <reified T: Any> String.toKotlinObject(): T {
    val mapper = jacksonObjectMapper()
    return mapper.readValue(this, T::class.java)
}

There’s no need to pass the Class of T additionally, T can be used as if it was an ordinary class. For the client the code looks like this:

json.toKotlinObject<MyJsonType>()

Important

Inline reified functions are not callable from Java code, whereas normal inline functions are. That’s probably the reason why not every type parameter used in inline functions is reified by default.

Conclusion

This was just a quick introduction to reified types. In my opinion the call to a function with reified types looks way better because we can make use of the <> syntax commonly used whenever generics are relevant. As a result, it’s more readable than the Java approach of passing a Class object as a parameter. All the dirty details can be read in this specification document.

If you want to read more about Kotlin’s beautiful features I recommend the book Kotlin in Action to you and also like to direct you to my other articles 🙂

Please follow and like this Blog 🙂
Spring WebFlux with Kotlin – Reactive Web

Spring WebFlux with Kotlin – Reactive Web

Spring 5.0 – even fancier

In this article I will show how Spring and Kotlin can be used together. If you’re not familiar with my recent articles, have a look at the other Kotlin related posts here. Besides Kotlin, I’ve always been interested in working with Spring ever since I started with Java back in 2011. I still like the framework although it’s getting bigger and bigger and you often don’t quite know which feature to choose amongst all the alternatives. As the framework itself is growing, the documentation, which is one of best you’ll ever get to see, also is.

The thing I like most about Spring is that you can focus on your business logic from day one and don’t have much technical, infrastructural stuff to set up before kicking off. Spring does that by encapsulating a lot of boilerplate that’s necessary for certain tasks and provides simple annotations we can apply in order to make use of these features. One of the most famous modules certainly is Spring Web MVC, which is widely used whenever it comes to web services on the JVM.

Reactive Programming – The non-blocking way

You might have noticed that Reactive Programming is getting more attention recently. There are many frameworks emerging that want to encourage this style of programming, namely RxJava, Vert.X or Akka for example. If you’ve never come across these, you can read my post on Kotlin with Vert.X as a first step.

Spring reactive

What does this have to do with Spring though? Well, of course, there’s yet another library for building reactive systems, which in fact is powered by Spring: [Project Reactor] https://projectreactor.io). Reactor is used in the current Spring Release 5.0, available since September 2017, which introduces a reactive web framework called WebFlux.
This fact on its own is a good reason for me to dive into it as it sounds fairly fantastic knowing Web MVC as Spring’s outstanding module already. But, there’s yet another great reason to take this expansion into account: Spring is greatly supporting Kotlin and even introduced Kotlin dedicated features with the recent major release 🙂 This was achieved by making use of extension functions in order to extend existing APIs and also by introducing Kotlin DSLs, a feature you can read about in my post on creating a DSL with Kotlin. One of these new DSLs goes hand in hand with Spring WebFlux: A functional DSL for describing the WebFlux-backed web service. This, in fact, is what I am going to present to you in a very short example up next…

WebFlux and Kotlin in Action

Let’s have a look at a very basic application using Spring WebFlux in a Kotlin application. The initial setup can easily be downloaded as a SpringBoot application from Spring Initializr, if you choose Kotlin as the programming language and also enable the “Reactive Web” dependency, which is available since SpringBoot 2.0.0.

spring boot initilizr

As soon as we’ve imported this project into our IDE, we can start with creating a reactive web service. For the sake of brevity, I chose a very simple, not very useful, example: An internally managed repository of simple Strings that is populated through the web interface and also is searchable from it. Thanks to Kotlin and also Spring, there’s not much code that has to be written:

Repo and Handler

@Component
class ReactiveHandler(val repo: StringRepo) {
    fun getText(search: String): Mono<String> =
        repo.get(search).toMono().map { "Result: $it!" }
    fun addText(text: String): Mono<String> =
        repo.add(text).toMono().map { "Result: $it!" }
    fun getAllTexts(): Flux<String> =
        repo.getAll().toFlux().map { "Result: $it" }
}

@Component
class StringRepo {
    private val entities = mutableListOf<String>()
    fun add(s: String) = entities.add(s)
    fun get(s: String) = entities.find { it == s } ?: "not found!"
    fun getAll() = listOf(entities)
}

We simply create a repository that maintains a list of Strings and another class ReactiveHandler, which is responsible for delegating to the repository and providing “reactive types” defined in Reactor. These are mandatory for WebFlux: Flux and Mono (Read about them here). Regardless of their intention, have a look at how they are created: toMono() and toFlux() are examples of extension functions added in Spring 5.0, a feature dedicated to Kotlin. The much more interesting part though is where the web routing is defined. This part in particular is where the already mentioned functional DSL comes into play. Let’s observe how it works.

Functional WebFlux DSL.

@Configuration
class RoutingConfiguration {

    @Bean
    fun routerFunction(handler: ReactiveHandler): RouterFunction<ServerResponse> = router {
        ("/reactive").nest {
            val searchPathName = "search"
            val savePathName = "save"
            GET("/{$searchPathName}") { req ->
                val pathVar = req.pathVariable(searchPathName)
                ServerResponse.ok().body(
                        handler.getText(pathVar)
                )
            }
            GET("/") {
                ServerResponse.ok().body(handler.getAllTexts())
            }
            PUT("/{$savePathName}") { req ->
                val pathVar = req.pathVariable(savePathName)
                ServerResponse.ok().body(
                        handler.addText(pathVar)
                )
            }
        }
    }
}

The router function is the entry point of the new DSL, which can be inspected on GitHub. The shown solution is just one out of many since the DSL provides more ways you can choose from. With my definition, the server starts a web service under “/reactive” and accepts two GET and one PUT request, each of which is delegated to the previously shown ReactiveHandler (see method parameter) before the results are put into a ServerResponse. Of course, you’d have to handle errors in a real-world scenario and “ok” wouldn’t be the only response.

Benefit

If you ask me, this approach is very clean structured and even provides the opportunity of using any Kotlin code for defining variables, loops, conditions, whatsoever inside the actual DSL code. Given that, you have a very powerful tool that can be utilized in a very natural programmatic way.

If your like to check this out, the code is available in this GitHub repository.

Wrap-up and Perspective

I’ve presented a small project that’s making use of Spring 5.0 and its new module WebFlux in combination with Kotlin. I think, the fact, that Spring officially uses and supports Kotlin is a very important one, I’d like to emphasize once again.

Kotlin – It’s not only Android!

We all know that Kotlin made its way into Android, which was possible because Google announced the official support a few months ago. On the server-side though, people and especially companies hesitate when it comes to Kotlin. They tend to have doubts as to whether Kotlin’s really mature enough already.
When you ask me, there’s no good reason for hesitation. Many projects use Kotlin already, frameworks support Kotlin and even extend their libraries with dedicated Kotlin features. Spring, as one of the most common Java frameworks, seems to think the same as they quickly adopted Kotlin as an alternative to Java and Groovy for SpringBoot applications. The most recent developments, which are part of Spring 5.0, are the next step, some of which we’ve observed in this little article. If you’re, same as me, interested in spreading Kotlin as an alternative to Java, talk about it and tell your colleagues about Spring’s support and what’s actually
happening 😉

Special Thanks

As you can read in this article, Spring’s introducing quite a few Kotlin features. There’s one guy, Sébastien Deleuze, who’s highly responsible for this development in the Spring Framework. He has also been a guest on talkingkotlin
already. It’s really great to have such influencers in the Kotlin community, many thanks! Keep up the great work.

If you like to have a look at my examples, the code is available here:
Git. Feel free to give any feedback, I’m always happy to help. Also, if you like, have a look at my Twitter account and follow if you’re interested in more Kotlin stuff 🙂 Thanks a lot.

Please follow and like this Blog 🙂
Creating your own DSL in Kotlin

Creating your own DSL in Kotlin

Motivation

If you’ve been following my recent posts about Kotlin, you’ve probably noticed me mentioning Domain Specific Languages (DSL) already. Kotlin as a programming language provides some powerful features that allow us to create those DSLs. One of these features, I also already introduced, is called Function Literals with Receiver, others are the invoke convention or infix notation.

In this article, a simple example of writing a DSL in Kotlin will be shown:
I’ve often been struggling with Java’s API for setting up SSL/TLS connections in scenarios where https communication is required for example. Just recently, I had to implement different kinds of these in one of our applications. Doing this, I once again felt like wanting to write a little library that can support me with that task, hiding away all the difficulties and of course the boilerplate.

Read More Read More

Please follow and like this Blog 🙂
Kotlin Operator Overloading – Working by Convention

Kotlin Operator Overloading – Working by Convention

Operator Overloading and Conventions in Kotlin

Introduction

Kotlin supports a technique called conventions, everyone should be familiar with. For example, if you define a special method plus in your class, you can use the + operator by convention, Kotlin’s approach to operator overloading.
In this article I want to show you which conventions can be used and will provide some Kotlin code demonstrating the concepts of course.

Read More Read More

Please follow and like this Blog 🙂
Kotlin Coroutines Guide

Kotlin Coroutines Guide

Concurrent Programming in Kotlin – Kotlin Coroutines

updated: 04/24/2018

Introduction and Motivation

In this article, I’d like to share my gathered insights on Kotlin Coroutines with you and hope to give a comprehensive overview. The shown code runs with Kotlin version 1.2.40 and kotlinx.coroutines version 0.22.5.
Kotlin coroutines are definitely one of the “bigger features” as indicated by the following quote, taken from JetBrains’ blog:

We all know that blocking is bad under a high load, that polling is a no-go, and the world is becoming more and more push-based and asynchronous. Many languages (starting with C# in 2012) support asynchronous programming through dedicated language constructs such as async/await keywords. In Kotlin, we generalized this concept so that libraries can define their own versions of such constructs, and async is not a keyword, but simply a function.
This design allows for integration of different asynchronous APIs: futures/promises, callback-passing, etc. It is also general enough to express lazy generators (yield) and cover some other use cases.

To put it simply, coroutines have been introduced in order to provide simple means for concurrent programming. Probably many of you have already worked with Java, its Threads and concurrency classes; I myself did this quite a lot and actually, I’m really convinced of its maturity.

Java Concurrency vs. Kotlin Coroutines

Tip
If you still catch yourself struggling with Threading and Concurrency in Java, I can recommend the book Java Concurrency in Practice to you.

Although Java’s solution is really well-engineered, it’s often difficult to utilize and (of course) very verbose. Another problem is, that Java doesn’t directly encourage non-blocking programming. You often find yourself starting threads without having in mind, that they’re very expensive and introduce blocking computations quickly (due to locks, sleeps, waits, etc.). Applying non-blocking patterns alternatively is really hard and error-prone.

Coroutines, on the other hand, are intended to be much easier and look like sequential code by hiding the complex stuff inside library functions. Yet, they provide a way to run asynchronous code without having to block threads, which provides new possibilities for applications [1]. Instead of blocking threads, computations are being suspended.
JetBrains tends to describe coroutines as “light-weight threads”; actually they are no Thread as we know them in Java. Compared to threads, coroutines are very cheap in the creation and the overhead introduced by threads isn’t around. One reason is, that they’re not directly mapped to native threads. As you will see, coroutines are executed in Threads managed by the library.
Another important difference is “limitation”: Threads are limited because they rely on available native threads, coroutines on the other side are almost free and thousands can be started at once.

Concurrent Programming Style

Different styles of asynchronous/concurrent programming styles exist in various languages, which for example are: callback-based (JavaScript), future/promise-based (Java, JavaScript), async/await-based (C#) and so on. All these concepts can be implemented with coroutines because Kotlin doesn’t dictate any style initially. Instead, all concepts are already, or at least could in future, (be) implemented using coroutines.
As one additional benefit, as opposed to e.g. callback-based programming, coroutines promote a sequential kind of asynchronous programming, i.e. although your coroutines may execute multiple parallel computations, your code still looks sequential and therefore acquainted.

The Concept of Kotlin Coroutines

The term and concept “Coroutine” is anything but new. According to the Wikipedia article, it was created in 1958 already. Many modern programming languages provide native support: C#, Go, Python, Ruby, etc. The implementation of coroutines, also in Kotlin, is often based on so-called “Continuations”, which are “an abstract representation of the control state of a computer program”. We’ll capture that in How does it work – Implementation of Coroutines again.

Getting Started – The Basics

There’s a comprehensive tutorial available on https://kotlinlang.com that describes how a project needs to be set up in order to work with coroutines. Please have a look there or just check out my Kotlin_Examples repository on GitHub.

Kotlin Coroutine Ingredients

As already hinted, the Kotlin coroutine library provides an understandable high-level API that lets us start quickly. One new modifier we need to learn is suspend, which is used to mark a method as “suspending”.
We’ll have a look at some easy examples using APIs from kotlinx.coroutines up next. But first, let’s learn what a suspending function is.

Suspending Functions

Coroutines rely on the keyword suspend, which is a modifier used in order to mark functions as “suspending” [2], i.e. that calls to such functions may suspend at any point. These can only be called from within coroutines, which in turn need at least one suspending function to be started.

suspend fun myMethod(p: String): Boolean {
    //...
}

As we can see in the example above, suspending functions look like regular functions plus the additional modifier. Keep in mind, that these methods can only be called from coroutines, other attempts will lead to compilation errors.

Coroutines can be thought of as a sequence of regular and suspending functions with an optional result being available after completion.

Hands-On

Let’s see some concrete coroutines in action. In a first example, the basics will be shown:

The first Coroutine

fun main(args: Array<String>) = runBlocking { //(1)
    val job = launch(CommonPool) { //(2)
        val result = suspendingFunction() //(3)
        print("$result")
    }
    print("The result: ")
    job.join() //(4)
}
>> prints "The result: 5"

In this example, two functions, (1) runBlocking and (2) launch, are used, which are examples of coroutine builders. Many different builders exist, each of which starts a coroutine with different purposes: launch (fire and forget), async (promise returned), runBlocking (blocks thread) and so on.

The inner coroutine started by (2) launch does the actual work: a (3) suspending function is called which might suspend at any time, the result is printed after completion. The main thread, after starting the coroutine, prints a String before the coroutine finishes.
Coroutines started by launch return a Job immediately, which can be used for canceling the computation or waiting for completion with (4) join() as we see here. Since calling join() may suspend, we need to wrap this call into another coroutine, which can often be achieved with runBlocking. This concrete coroutine builder (1)is designed to bridge regular blocking code to libraries that are written in suspending style, to be used in main functions and in tests” (Quoted API). If we removed the joining of the job, the program would stop before the coroutine can print the result.

Going deeper

A more lively example is the following: Imagine, you have to send an email from your application. Requesting the recipient address and rendering the message body are two very expensive tasks, which are independent of each other though. Being smart and using Kotlin, you want to make use of coroutines, performing both tasks in parallel, of course.
This is shown here:

email example async/await
suspend fun sendEmail(r: String, msg: String): Boolean { //(6)
    delay(2000)
    println("Sent '$msg' to $r")
    return true
}

suspend fun getReceiverAddressFromDatabase(): String { //(4)
    delay(1000)
    return "coroutine@kotlin.org"
}

suspend fun sendEmailSuspending(): Boolean {
    val msg = async(CommonPool) {             //(3)
        delay(500)
        "The message content"
    }
    val recipient = async(CommonPool) { 
        getReceiverAddressFromDatabase()  //(5)
    } 
    println("Waiting for email data")
    val sendStatus = async(CommonPool) {
        sendEmail(recipient.await(), msg.await()) //(7)
    }
    return sendStatus.await() //(8)
}

fun main(args: Array<String>) = runBlocking(CommonPool) { //(1)
    val job = launch(CommonPool) {
        sendEmailSuspending() //(2)
        println("Email sent successfully.")
    }
    job.join() //(9)
    println("Finished")
}

First, like already seen in the previous example, we use a (1) launch builder inside a runBlocking builder so that we can (9) wait for the coroutine’s completion. This isn’t new and neither is the (2) call to a suspending function sendEmailSuspending.
This method uses an (3) inner coroutine for getting the message content and (4) another suspend method getReceiverAddressFromDatabase for the address. Both tasks are executed in a separate coroutine build with (5) async. Note, that the calls to delay represent a non-blocking, coroutine suspending, alternative to Thread.sleep, which is used for mocking expensive computations here.

The async Coroutine Builder

The async builder is really simple and easy in its conception. As we know from many other languages, this method returns a promise, which is strictly speaking of type Deferred in Kotlin. All terms like promise, future, deferred or delay are often used interchangeably for describing the same concept: The async method promises to compute a value which we can wait for or request at any time.

We can see the “waiting” part of Kotlin’s Deferred objects in (7), where the suspending function (6) is called with the results of both prior computations. The method await() is called on instances of Deferred which suspends until the results become available [3]. The call to sendEmail is also wrapped in an async builder, for which completion we wait in (8) before returning its result.

What I didn’t explain: CoroutineContext

One important part of the above examples is the first parameter of the builder functions, which must be an instance of CoroutineContext. This context is what’s passed to a coroutine and provides access to the current Job (remember, this is what can be used outside a coroutine for cancellation or joining) for example.
Also, the current context may be utilized for launching inner coroutines, which has the effect that the sub-coroutine’s Job is a child of its surrounding one. That provides the possibility to cancel whole hierarchies of coroutines with a single cancellation request to the parent Job.
Different kinds of Elements are part of a CoroutineContext, one of which is CoroutineDispatcher.

In all examples shown, I used CommonPool, which is such a dispatcher. It makes sure, that the coroutines are executed in a thread pool managed by the framework. Alternatively, we could have used a confined thread, specially created, or implement our own pool for example. Contexts can even be combined easily using the overloaded + operator like so:

launch(CommonPool + CoroutineName("mycoroutine")){...}

Also, note that the CommonPool is the default dispatcher and it’s therefore defined as the default argument for the coroutine builder. We could have simply written launch { ... }, async { ... } and so on.

Shared Mutable State

Maybe, while reading the previous chapters, you have had concerns about synchronization between coroutines since I didn’t show mention any of this before. I, at least, had this concern because coroutines make use of thread pools (like CommonPool) to be dispatched in and therefore could work on shared state concurrently. It’s quite evident that synchronization is just as important as we know it from other languages like Java. We can make use of acquainted strategies like thread-safe data structures, confining execution to a single thread or using locks (see Mutex for further details).
Besides the common patterns, Kotlin coroutines encourage the use of a “share by communication”-style (see QA).

Concretely, an “actor” can be shared between coroutines. They can be used by coroutines, which may send/take messages to/from it. Let’s see how this works:

Actors

actor message passing example
sealed class CounterMsg {
    object IncCounter : CounterMsg() // one-way message to increment counter
    class GetCounter(val response: SendChannel<Int>) : CounterMsg() // a request with channel for reply.
}

fun counterActor() = actor<CounterMsg>(CommonPool) { //(1)
    var counter = 0 //(9) actor state, not shared
    for (msg in channel) { // handle incoming messages
        when (msg) {
            is CounterMsg.IncCounter -> counter++ //(4)
            is CounterMsg.GetCounter -> msg.response.send(counter) //(3)
        }
    }
}

suspend fun getCurrentCount(counter: SendChannel<CounterMsg>): Int { //(8)
    val response = Channel<Int>() //(2)
    counter.send(CounterMsg.GetCounter(response))
    val receive = response.receive()
    println("Counter = $receive")
    return receive
}

fun main(args: Array<String>) = runBlocking<Unit> {
    val counter = counterActor()

    launch(CommonPool) { //(5)
            while(getCurrentCount(counter) < 100){
                delay(100)
                println("sending IncCounter message")
                counter.send(CounterMsg.IncCounter) //(7)
            }
        }

    launch(CommonPool) { //(6)
        while ( getCurrentCount(counter) < 100) {
            delay(200)
        }
    }.join()
    counter.close() // shutdown the actor
}

This example shows the usage of an (1) Actor, which is a coroutine itself working on any context. The actor is holding the (9) relevant state of this sample application, which is counter. Another important feature, we haven’t considered so far, is a (2) Channel:of


Channels

Channels provide a way to transfer a stream of values, similar to what we know as BlockingQueue (enables producer-consumer pattern) in Java but without any blocking methods. Instead, send and receive are suspending functions used for providing and consuming objects from the channel, implemented with FIFO strategy, making them fair.


The actor is, by default, associated to such a channel, which can be used in other coroutines (7) for sending messages to it. In the example, the actor iterates over the stream of messages from its channel (for works with suspending calls) handling them according to their type: (4) IncCounter messages make the actor change its state by incrementing the counter while (3) GetCounter makes the actor return its counter state by sending an independent message to the GetCounter‘s SendChannel.
The first coroutine (5) in main, just for the sake of convenience, launches a task which sends (7) IncCounter messages to the actor as long as the counter is less than 100. The second (6) just waits until the counter reaches 100. Both coroutines make use of the suspending function (8) getCurrentCounter, which sends a GetCounter message to the actor and suspends by waiting on receive to return.

As we can see, the whole relevant state is confined to the specific actor coroutine. This solves the problem of shared mutable state.

More Features and Examples

If you really want to dive into coroutines and start working with it, I recommend the commonly known Kotlin documentation and especially want to suggest this fantastic guide.

How does it work – Implementation of Coroutines

I cannot go too much into detail here because this would exceed the post’s intention. I’m planning to write a follow-up with more detailed information on implementation, considering the generated bytecode of coroutines as well, in the next weeks.
For now, let’s limit the following description to a “bird’s eye view”-ish one.

Coroutines do not rely on features of the operating system or the JVM. Instead, coroutines and suspend functions are transformed by the compiler producing a state machine capable of handling suspensions in general and passing around suspending coroutines keeping their state. This is enabled by Continuations, which are added as a parameter to each and every suspending function by the compiler; this technique is called “Continuation-passing style”.
If you can’t wait to know any details, you need to read this explanation.

Pro Tips, with Roman Elizarov

I’ve been talking to Roman Elizarov from JetBrains on Slack recently, who’s highly responsible for Kotlin’s coroutines 😉 Let me share the gathered information with you:

Q: The first question I had: When am I supposed to use coroutines and are there any use cases that still require threads to be used?

A: Rule of thumb by Roman:
Coroutines are for asynchronous tasks that wait for something most of the time. Threads are for CPU-intensive tasks.

Q: I mentioned, that the phrase “light-weight thread” sounds kind of inappropriate to me as it obscures the fact, that coroutines rely on threads since they are executed in a pool of threads. In my opinion, coroutines are rather a “task” being executed, stopped etc.

A: Roman answered, that the phrase “light-weight threads” is rather superficial, and that “coroutines are in many ways like threads from user’s standpoint.”

Q: As a last question, I wanted to know about synchronization. If coroutines are alike threads, there must be the necessity of synchronizing shared state between different coroutines.

A: Roman told me, that known patterns of synchronization may be used, but it is recommended not to have any mutable shared state at all when we use coroutines. Instead, coroutines “encourage […​] to adopt “share by communication” style.

Conclusion

Coroutines once again demonstrate Kotlin’s magnificence. As opposed to Java, Kotlin encourages a totally different style of concurrent programming, which is non-blocking and naturally doesn’t make us start huge amounts of native threads.
In Java, it’s mostly normal to just start another thread or create new pools without having in mind, that this introduces a huge overhead and can even make our application slow due to blocking code for example. Coroutines, as an alternative, are said to be “light-weight threads”, which describes the fact, that they’re not mapped to native threads and therefore don’t drag along all the risks and problems we usually have to deal with (deadlocks, starvation e.g.). As we’ve seen, with coroutines, we normally don’t have to worry about blocking threads, synchronization is much more straightforward and not even necessary ideally as long as we pursue “share by communication”.

Coroutines also enable us to work with several different kinds of concurrent programming, each of which is either available in the library already (kotlinx.coroutine) or at least could be implemented easily.
Java developers, in particular, might most likely be acquainted with submitting tasks to a thread pool and waiting for results of futures then (ExecutorService), which we easily achieve by using async/await style. Yet, it’s not just an equal replacement, but a big improvement to what we know already.
Think about your concurrent Java code, all those checked exceptions, defensive locking strategies and a lot of boilerplate code. With coroutines, it’s normal to write code sequentially by calling suspend functions, communicating with other coroutines, waiting for results, canceling coroutines and more.

Perspective

Although I’m convinced that coroutines are truly fantastic, time will show whether it’s actually mature enough for highly concurrent applications. Many programmers will have to rethink and apply totally different concepts to their programs. I’m really curious about its future. As of now, coroutines are just experimental, which means JetBrains might adjust them in upcoming releases in order to adapt feedback from the community after playing around or even adopting coroutines in productive projects.

Please don’t hesitate to get in touch, feedback’s always appreciated 🙂 Also if you like, have a look at my [Twitter](https://twitter.com/s1m0nw1) and follow if you’re interested in more Kotlin stuff 🙂 Thanks a lot.If you want to read more about Kotlin’s beautiful features I highly recommend the book Kotlin in Action and my other articles to you.

 

Simon


1. Non-blocking programming became more and more popular in the last time because reactive programming gained influence.
2. Actually, it’s “possibly suspending” since such a function may suspend, but doesn’t have to.
3. Keep in mind, that Java’s Future blocks a thread as soon as we call get() on it.

 

Please follow and like this Blog 🙂

Enjoy this blog? Please spread the word :)