Tag: java

From Java Builders to Kotlin DSLs

From Java Builders to Kotlin DSLs

From Java Builders to Kotlin DSLs

Introduction

DSLs – Domain Specific Languages – are an ever trending topic in Kotlin circles. They allow us to flex some of the most exciting language features while accomplishing more readable and maintainable solutions in our code.

Today I’d like to show you how to implement a certain kind of DSL – we’re going to be wrapping an existing Java Builder in Kotlin. No doubt you’ve come across the builder pattern in Java before, for example if you’re an Android developer, you must’ve used an AlertDialog.Builder, an OkHttpClient.Builder, or a Retrofit.Builder at some point. Wrapping a builder like this is a good exercise in just pure DSL design. All you have to worry about is designing the API you provide with your wrapper, since all the implementation for whatever your DSL provides its users is already done inside the builder!

Our example case

It just so happens that I’m the creator and maintainer of a library that does this very thing, and a small part of its implementation is what we’re going to be using as our example. The original library is the wonderful and hugely popular MaterialDrawer by Mike Penz, which allows you to create complex, good looking, and customized navigation drawers in your application, all via various Builder objects in Java, with no XML writing involved on your part. This is what my library, MaterialDrawerKt provides a convenient Kotlin DSL wrapper for.

The Builder API

Let’s take a look at the drawer we’re going to be creating in our example.

android_drawer

Here’s the code, using the builders in the original API:

DrawerBuilder()
        .withActivity(this)
        .withTranslucentStatusBar(false)
        .withDrawerLayout(R.layout.material_drawer_fits_not)
        .addDrawerItems(
                PrimaryDrawerItem()
                        .withName("Home")
                        .withDescription("Get started here!"),
                PrimaryDrawerItem()
                        .withName("Settings")
                        .withDescription("Tinker around")
        )
        .withOnDrawerItemClickListener { view, position, drawerItem ->
            when(position) {
                0 -> toast("Home clicked")
                1 -> toast("Settings clicked")
            }
            true
        }
        .withOnDrawerListener(object: Drawer.OnDrawerListener {
            override fun onDrawerSlide(drawerView: View?, slideOffset: Float) {
                // Empty
            }

            override fun onDrawerClosed(drawerView: View?) {
                toast("Drawer closed")
            }

            override fun onDrawerOpened(drawerView: View?) {
                toast("Drawer opened")
            }
        })
        .build()

In this code, we’ve…
– set the Activity we want the drawer to appear in,
– made some layout adjustments so that the drawer is below the ActionBar,
– created just two menu items with names and descriptions,
– set a listener where we can handle item selections by position, using a SAM conversion to implement a single method interface,
– added a listener to detect drawer movement, using an object expression, because the necessary interface has multiple methods.

We saw two different builders used here, namely, the DrawerBuilder and PrimaryDrawerItem classes. While their builder syntax actually looks pretty decent and readable, we’ll see that a DSL can do even better.

Note that you can check out the entire working demo project for this article on GitHub here. See the commit history to follow the article step by step as we build our DSL.

Creating instances

Let’s start small. We’ll want to create a drawer with a drawer {} call, let’s implement just that.

fun Activity.drawer(dummy: () -> Unit) {
    DrawerBuilder()
            .withActivity(this)
            .build()
}

We’ve defined our first function as an extension on Activity, so that it’s available when we’re in one, and it can access the Activity instance as this without us having to pass it in explicitly.

Now, we should add our PrimaryDrawerItem instances. This syntax would be nice for a start:

drawer {
    primaryItem()
    primaryItem()
}

To get this, we’ll need a primaryItem function that’s only available within the drawer block, and that somehow adds an item to the DrawerBuilder we’ve already created.

To be able to call methods on our DrawerBuilder instance before we build() it, we’ll introduce a new wrapper class that holds it:

class DrawerBuilderKt(activity: Activity) {
    val builder = DrawerBuilder().withActivity(activity)

    internal fun build() {
        builder.build()
    }
}

We’ll update our original drawer function to create an instance of this wrapper class. We’ll also modify its parameter – by making the setup function an extension on our own class, the client of the DSL will be placed in a new scope inside the lambda passed to the drawer function, where the methods of DrawerBuilderKt become available, as we’ll see in a moment.

fun Activity.drawer(setup: DrawerBuilderKt.() -> Unit) {
    val builder = DrawerBuilderKt(this)
    builder.setup()
    builder.build()
}

You might have spotted that we’ve marked our own build method internal – this is because the only call to it will be the one inside the drawer function. Hence, there’s no need to expose it to the clients of our library.

The visibility of builder is another story – we’ll have to keep this public so that our library stays extensible. We could make it internal for the purpose of us implementing wrappers around the built-in drawer items, but that would mean that nobody else could add their own custom drawer items to the DSL – something you could do with the original library. This is functionality we don’t want to strip from our clients.

Now we can finally add the primaryItem function we were planning earlier. To make this available inside the lambda passed to drawer, we could make it a member of the DrawerBuilderKt class. Modifying this class for every new drawer item type we add, however, seems like an odd thing to do. The various types of drawer items should in no way affect how the drawer itself works.

We can instead use the same mechanics as clients would use to create custom drawer items. We’ll get a neat, decoupled design by adding primaryItem as an extension function:

fun DrawerBuilderKt.primaryItem() {
    builder.addDrawerItems(PrimaryDrawerItem())
}

We can now add blank drawer items to our drawer!

Setting properties

Before we get to setting the name and description of our drawer items with the DSL, we have the properties of DrawerBuilder to take care of, as we’ve seen in the very first code snippet. This is the syntax we’ll create for these:

drawer {
    drawerLayout = R.layout.material_drawer_fits_not 
    translucentStatusBar = false
}

These, of course, will be properties on the DrawerBuilderKt class so that they’re available in the right scope.

Since the original builder doesn’t let us access the values we’ve set, what we’ll need to create are essentially write-only properties. These properties won’t have backing fields to store values, all they’ll do is forward the calls to the appropriate builder methods.

Unfortunately, Kotlin only has properties that can be both read and written (var) and read-only ones (val). We’ll solve this by using a var, and throwing an exception when someone tries to read these properties. We’ll also include Kotlin’s powerful @Deprecated annotation that lets us mark using the getters an error, so that clients are stopped from doing so at edit/compile time, rather than just getting the runtime exception:

class DrawerBuilderKt(activity: Activity) {
    ...

    var drawerLayout: Int
        @Deprecated(message = "Non readable property.", level = DeprecationLevel.ERROR)
        get() = throw UnsupportedOperationException("")
        set(value) {
            builder.withDrawerLayout(value)
        }
}

Alternatives for setting properties

Now, we can move on to customizing the drawer items themselves. The obvious solution here is to continue with the same syntax style as before:

drawer {
    primaryItem {
        name = "Home"
        description = "Get started here!"
    }
}

We know how to do this by creating a wrapper class around PrimaryDrawerItem, and then adding a couple non-readable properties, just like we did before. But let’s do something more interesting, and create this alternative syntax:

drawer {
    primaryItem(name = "Home", description = "Get started here!")
}

This is also pretty straightforward, we’re just calling a function that has two parameters, and using named parameters for readability. Let’s add these parameters to primaryItem then. We’ll also throw in default values so that they’re each optional:

fun DrawerBuilderKt.primaryItem(name: String = "", description: String = "") {
    val item = PrimaryDrawerItem()
            .withName(name)
            .withDescription(description)
    builder.addDrawerItems(item)
}

This, of course, isn’t a feasible method for adding dozens of properties to an item we’re constructing with our DSL, adding a wrapper around the PrimaryItemClass with separate write-only properties that can be set in a setup lambda is still the way to go for most things.

However, this is a nice way to lift some very basic or commonly set properties to a more prominent position in the code. Here’s what the DSL could look like with some more properties implemented:

primaryItem(name = "Games", description = "Ready, player one?") {
    iicon = FontAwesome.Icon.faw_gamepad
    identifier = 3
    selectable = false
}

Listeners

We know how to add properties to our DSL, now let’s see how we can go about listeners. We’ll start with the easy one, setting the OnDrawerItemClickListener to handle item clicks for a given position in the drawer. Here’s our goal:

drawer {
    onItemClick { position ->
        when (position) {
            0 -> toast("Home clicked")
            1 -> toast("Settings clicked")
        }
        true
    }
}

onItemClick will be a method in DrawerBuilderKt, and it will take a lambda parameter that can be called when the original listener fires:

class DrawerBuilderKt(activity: Activity) {
    ...

    fun onItemClick(handler: (view: View?, position: Int, drawerItem: IDrawerItem<*, *>) -> Boolean) {
        builder.withOnDrawerItemClickListener(handler)
    }
}

We’re making use of SAM conversion with the call to the withOnDrawerItemClickListener method of the builder here. The usual SAM conversion syntax would have us passing in a lambda that gets transformed to the OnDrawerItemClickListener interface, but instead, we’re going just a small step further, and we’re passing in the handler parameter which has the appropriate function type for a conversion.

We’ll simplify the above method a bit, by taking a lambda which only gets the position passed to it, as clients will usually only care about that parameter. We’re using SAM conversion again, this time with a regular lambda, because we want to ignore some parameters when calling our simpler handler parameter.

class DrawerBuilderKt(activity: Activity) {
    ...

    fun onItemClick(handler: (position: Int) -> Boolean) {
        builder.withOnDrawerItemClickListener { _, position, _ -> handler(position) }
    }
}

Of course, having only this version of the method would hide functionality of the original library, so in the real wrapper library, I’ve included both of these.

Complex listeners

Last but not least, let’s see what we can do about the OnDrawerListener in our example. This interface has three methods, so the previous, simple solution won’t work here. As always, let’s start with the syntax we want to achieve. Not that we’re only setting two of the three methods that the interface defines.

drawer {
    onClosed {
        toast("Drawer closed")
    }
    onOpened {
        toast("Drawer opened")
    }  
}

As you can see, it would be nice to be able to specify either one or multiple of the methods of the interface independently of each other. We know that we’ll want to define three methods to take the appropriate handler lambdas, very similarly to what we did before:

class DrawerBuilderKt(activity: Activity) {
    ...

    fun onOpened(handler: (drawerView: View) -> Unit) {
        // TODO implement
    }

    fun onClosed(handler: (drawerView: View) -> Unit) {
        // TODO implement
    }

    fun onSlide(handler: (drawerView: View, slideOffset: Float) -> Unit) {
        // TODO implement
    }
}

The question is how to pass these handlers to the builder we’re holding. We can’t make a withOnDrawerListener call in each of them and create an object that wraps just that one handler, as the object created there would always implement just one of the three methods.

What I came up with for this is an object property in our DrawerBuilderKt wrapper class that implements the OnDrawerListener interface, and delegates each of these calls to one of its properties.

class DrawerBuilderKt(activity: Activity) {
    ...

    private val onDrawerListener = object : Drawer.OnDrawerListener {
        var onSlide: ((View, Float) -> Unit)? = null

        override fun onDrawerSlide(drawerView: View, slideOffset: Float) {
            onSlide?.invoke(drawerView, slideOffset)
        }

        var onClosed: ((View) -> Unit)? = null

        override fun onDrawerClosed(drawerView: View) {
            onClosed?.invoke(drawerView)
        }

        var onOpened: ((View) -> Unit)? = null

        override fun onDrawerOpened(drawerView: View) {
            onOpened?.invoke(drawerView)
        }
    }
}

All our previous methods have to do then is to set these properties when they’re called:

class DrawerBuilderKt(activity: Activity) {
    ...

    fun onOpened(handler: (drawerView: View) -> Unit) {
        onDrawerListener.onOpened = handler
    }

    fun onClosed(handler: (drawerView: View) -> Unit) {
        onDrawerListener.onClosed = handler
    }

    fun onSlide(handler: (drawerView: View, slideOffset: Float) -> Unit) {
        onDrawerListener.onSlide = handler
    }
}

Of course, we’ll still have to pass this object to the builder at some point – we’ll do that after the setup lambda passed to drawer has already done its work, and it calls our DrawerBuidlerKt.build() method:

class DrawerBuilderKt(activity: Activity) {
    val builder = DrawerBuilder().withActivity(activity)

    internal fun build() {
        builder.withOnDrawerListener(onDrawerListener)
        builder.build()
    }

    ...
}

Result

As a reminder, here’s the builder code we started the article with:

DrawerBuilder()
        .withActivity(this)
        .withTranslucentStatusBar(false)
        .withDrawerLayout(R.layout.material_drawer_fits_not)
        .addDrawerItems(
                PrimaryDrawerItem()
                        .withName("Home")
                        .withDescription("Get started here!"),
                PrimaryDrawerItem()
                        .withName("Settings")
                        .withDescription("Tinker around")
        )
        .withOnDrawerItemClickListener { view, position, drawerItem ->
            when(position) {
                0 -> toast("Home clicked")
                1 -> toast("Settings clicked")
            }
            true
        }
        .withOnDrawerListener(object: Drawer.OnDrawerListener {
            override fun onDrawerSlide(drawerView: View?, slideOffset: Float) {
                // Empty
            }

            override fun onDrawerClosed(drawerView: View?) {
                toast("Drawer closed")
            }

            override fun onDrawerOpened(drawerView: View?) {
                toast("Drawer opened")
            }
        })
        .build()

And then here’s the final DSL we’ve put together:

drawer {
    drawerLayout = R.layout.material_drawer_fits_not
    translucentStatusBar = false

    primaryItem(name = "Home", description = "Get started here!")
    primaryItem(name = "Settings", description = "Tinker around")

    onItemClick { position ->
        when (position) {
            0 -> toast("Home clicked")
            1 -> toast("Settings clicked")
        }
        true
    }
    onClosed {
        toast("Drawer closed")
    }
    onOpened {
        toast("Drawer opened")
    }
}

I hope this serves as a good example of how much better looking and more expressive a DSL can be than builder style solutions. Another benefit is how much easier making changes in the DSL is, which of course becomes apparent when you’re actually making them (but worrying about placing commas in the right places, for example, is in the past).

Conclusion

Thank you for sticking with me for this entire journey. I hope you got a good feel for how to design your own DSLs (always write down your desired syntax first!), and how to structure your DSL implementations.

If you’re interested in more, I recommend checking out the source of the actual MaterialDrawerKt library, as it deals with many more advanced concepts that I couldn’t fit in this post. Among other things, it uses generics and inheritance heavily to deal with MaterialDrawer‘s complex hierarchy of built-in drawer item types, restricts function calls and property accesses to the appropriate levels of the DSL hierarchy, and much more. I might cover these in a future article.

Additionally, you can find another article covering the process of writing a DSL here, and another article about more general DSL design here.

But this is it for now, and with that, it’s now your time to go and start creating your own DSLs. Good luck!

Márton is a Kotlin enthusiast from Hungary, currently working as an Android developer at AutSoft, while still pursuing a master’s degree in computer engineering. Brags a lot about being ranked third in the top users list of the Kotlin tag on Stack Overflow.

Please follow and like this Blog 🙂
Kotlin Nullability Features

Kotlin Nullability Features

Null-Safe Programming – The Kotlin Way

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

In this article, we will review the problems that may be caused by null pointers and how to avoid them in Java. After that, the article demonstrates how Kotlin nullability features work and how they improve your code.

As Java developers, we’re very accustomed to NullPointerExceptions (NPE) that are thrown at the runtime of an application. This almost always happens unintentionally in consequence of a bug, which is based on unrecognized references to null. The null reference is often used to indicate absent values, which isn’t obvious to the programmer in many cases. Although Java relies on strong static typing, it doesn’t let you distinguish between reference types that can and cannot hold a null reference. Have a look at the following code example:

Device audio = new DeviceProvider().getAudioDevice();
String audioName = audio.getName();

The method getAudioDevice returns an object of type Device but might return null in order to denote the absence of that device on particular systems. Well documented methods will describe exactly that behavior, which still requires the developer to be very attentive. Not knowing about the possibility of a returned null reference is going to cause an awful NullPointerException in the subsequent call to getName. Wouldn’t it actually be nice if we were able to identify the method’s returned Device type as nullable (or non-nullable respectively) firsthand?

Null-Safety in Java

We have to find strategies that help us avoiding unwanted bugs due to NPEs. A common approach is to defensively check for null references and handle these cases in a way that makes more sense, such as providing default values or throwing more meaningful exceptions. Applying this to the previous example brings us to the following solution:

Device audio = new DeviceProvider().getAudioDevice();
String audioName;
if (audio != null) {
    audioName = audio.getName();
} else {
    throw new IllegalStateException("This system does not provide an audio device.");
}

Constructs like these are part of any Java project and the approach works well unless you forget to add checks for certain variables. It’s a fairly error-prone approach and doesn’t mitigate the fact that using null as a representative for absent things is risky.

Does Java offer any more sophisticated solutions to this problem? It does, at least in some situations. The Java SE 8 introduced the Optional type that acts as a “container object which may or may not contain a non-null value”. This sounds very promising and needs to be considered next.

Java SE 8 Optional

The Optional type is a container that wraps another object, which can theoretically be null. Code that works on instances of Optional needs to handle the possible nullability in a rather explicit way:

Optional audio = new DeviceProvider().getAudioDevice();
String audioName = audio
    .flatMap(Device::getName)
    .orElseThrow(() -> new IllegalStateException("This system does not provide an audio device."));

The getAudioDevice method was adjusted to return an Optional, which doubtlessly indicates to the client that the device can be absent. Instead of carelessly accessing that nullable type, the Optional type can be used for handling the possible nullability in various ways. These include providing default values and throwing exceptions with the help of simple methods like orElse and orElseThrow respectively. Furthermore, it literally forces the client to think about the potential null case.

Unfortunately, the whole Optional story already ends with this use case very suddenly. As stated by Java language architect Brian Goetz in this StackOverflow post, the Optional type was not intended as a “general purpose Maybe […] type” but a way to let libraries and APIs express the absence of a return type (as we saw in the previous example).

For further usage examples of Optional, you should find a suitable article in your preferred search engine.

After all, the Optional type is a great way to provide more explicit APIs that let the corresponding callers know exactly when null handling is required just by observing the method’s signature. Nevertheless, it’s not a holistic solution since it isn’t meant to replace each and every null reference in the source code. Aside from that, can you safely rely on method return types, which are not marked as Optional?

Kotlin Nullability: Null-Safety in Kotlin

After we have seen the rather unsafe null handling in the Java language, this section will introduce an alternative approach: The Kotlin programming language, as an example, provides very sophisticated means for avoiding NullPointerExceptions.

The language’s type system differentiates between nullable and non-nullable types and every class can be used in both versions. By default, a reference of type String cannot hold null, whereas String? allows it. This distinction on its own doesn’t make a very big difference obviously. Therefore, whenever you choose to work with nullable types, the compiler forces you to handle possible issues, i.e. potential NPEs, appropriately.

//declare a variable with nullable String type, it's OK to assign `null` to it
var b: String? = "possiblyNull"

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

// 2. Check nullability before access
if (b != null){
    b.length
}

// 3. Use safe operator
val len = b?.length

This code example shows different ways of working with nullable types (String? in this case). As demonstrated first, it’s not possible to access members of nullable types directly since this would lead to the same problems as in Java. Instead, traditionally checking whether that type is not null makes a difference. This action persuades the compiler to accept invocations on the variable (inside the if-block) as if it were not nullable. Note that this does not work with mutable vars because they could possibly be set to null from another thread between the check and first action in the block.
As an alternative to explicit checks, the safe call operator ?. can be used. The expression b?.length can be translated to “call length on b if b is not null, otherwise return null“. The return type of this expression is of type Int? because it may result in null. Chaining such calls is possible and very useful because it lets you safely omit a great number of explicit checks and makes the code much more readable:

person?.address?.city ?: throw IllegalStateException("No city associated to person.")

Another very useful operator is the elvis operator ?: that perfectly complements the safe call operator for handling else cases. If the left-hand expression is not null, the elvis operator returns it, otherwise, the right-hand expression will be called.

The last operator that you need to know is called not-null assertion operator !!. It converts any reference to a non-null type. This unchecked conversion may cause an NPE if that reference is null after all. The not-null assertion operator should only be used with care:

person!!.address!!.city //NPE will be thrown if person or address is null

In addition to the shown operators, the Kotlin library provides plenty of helpful functions like String?::IsNullOrEmpty(), String::toDoubleOrNull() and List::filterNotNull(), to name just a few. All of them support the developer in proper nullability handling and make NPEs almost impossible.

Interop between both languages

One of the key attributes of Kotlin is its fantastic interoperability with Java source code. You can easily mix both languages in a project and call Kotlin from Java and vice versa. How does that work in the case of null safety, though?

As learned earlier in this article, every Java reference can be null, which makes it hard for Kotlin to apply its safety principles to them meaningfully. A type coming from Java is called platform type, denoted with an exclamation mark, e.g. String!. For these platform types, the compiler isn’t able to determine whether it’s nullable or not due to missing information. As a developer, when a platform type is e.g. assigned to a variable, the correct type can be set explicitly. If you assign a platform type String! to a variable of the non-nullable type String, the compiler allows it and, as a consequence, safe access to that variable isn’t being enforced. Nevertheless, if that decision turns out to be wrong, i.e. a null reference is returned, NPEs will be thrown at runtime. Fortunately, there’s a solution that allows providing more information to the Kotlin compiler by applying certain annotations to the corresponding Java methods. This enables the compiler to determine actual nullability information and makes platform types unneeded.

Bottom Line

It’s important to understand that Kotlin does not try to avoid null references as such but raises the attention for null-related issues and especially NPEs enormously. If you take care of platform types and defensively decide to use them as nullable ones or apply the mentioned annotations to your Java libraries, you should be safe. NullPointerExceptions will be a thing of the past. As set out above, the Kotlin language provides many useful operators and other functions that simplify working with nullable types tremendously by making use of its clever type system. We can hope to see similar solutions in future Java versions soon.

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂
Run Kotlin Scripts (kts) from regular Kotlin Programs

Run Kotlin Scripts (kts) from regular Kotlin Programs

Run Kotlin Scripts from Kotlin Programs

This article presents a way to run Kotlin scripts from Kotlin programs in order to leverage the power of DSLs.

Kotlin can be used as a scripting language. Simply write top-level executable code inside a file with .kts extension and run it with the kotlinc as described in the documentation. That’s also the format of Gradle build files that are used in combination with the Gradle Kotlin DSL like this gradle.build.kts. Gradle shows a fantastic example of a domain specific language that can be written standalone in .kts files to be read by the gradle tool later on. When we try to find a way to do the same with custom DSLs (Tutorial can be found here), we first need to know how to run Kotlin scripts from Kotlin programs. The article reveals how to do so.

The Java Scripting API (JSR-223)

The Java Scripting API is a tool for using scripting engines (such as Nashorn) from Java code. It enables users to write customizable scripting code that can be picked up by the Java application at runtime. In a way, the API is a neat way of writing extensible applications.

As of Kotlin 1.1, the corresponding JSR-223 is supported for Kotlin Scripts, too. That means that it’s possible to run Kotlin scripts from regular Kotlin programs in order to make applications customizable through these scripts.

Using the Kotlin Script Engine

In order to use the mentioned Kotlin script engine, a file called javax.script.ScriptEngineFactory has to be placed inside META-INF/services of your application. It should contain the following entry: org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory.
After that, the javax.script.ScriptEngineManager will be able to find the corresponding engine when looked up via ScriptEngineManager().getEngineByExtension("kts"). This code now finds the Kotlin ScriptEngine implementation, an instance that can be used to evaluate String-based scripts such as "5 + 2", or directly read scripts from the file system. Here’s a short example:

with(ScriptEngineManager().getEngineByExtension("kts")) {
    eval("val x = 3")
    val res2 = eval("x + 2")
    assertEquals(5, res2)
}

You could also compile scripts and evaluate them later:

val script = compile("""listOf(1,2,3).joinToString(":")""")
assertEquals(listOf(1, 2, 3).joinToString(":"), script.eval())

Wrapping the glue code in a library

As shown, executing Kotlin scripts from Kotlin programs is pretty easy due to the Java scripting API implementation for Kotlin. Nevertheless, since it’s a bit cumbersome to integrate the support into an application, I wrote a tiny library that encapsulates the Scripting API glue code. It is called KtsRunner and can be found on GitHub.

The KtsRunner is a lightweight tool for executing Kotlin scripts from your custom applications. The API, as of the very first version, provides a slim KtsObjectLoader class whose usage is shown in the following example:

data class ClassFromScript(val x: String)
import de.swirtz.ktsobjectloader.ClassFromScript

ClassFromScript("I was created in kts")

The previous snippets show the definition of some arbitrary data class and the code that instantiates an object of it. The object instantiation is basically what we write into a .kts file.

val scriptReader = Files.newBufferedReader(Paths.get("path/classDeclaration.kts"))
val loadedObj: ClassFromScript = KtsObjectLoader().load<ClassFromScript>(scriptReader)
assertEquals("I was created in kts", loadedObj.x)

Using the KtsObjectLoader makes it simple to load the correspoding object of ClassFromScript from the script file. Alternatively, the script could also be provided as a String:

val scriptContent = "5 + 10"
val result: Int = KtsObjectLoader().load<Int>(scriptContent))
assertEquals(15, result)

Adequate Usage Scenario

As mentioned in the beginning, it can make sense to make your application customizable through external scripts, similar to how Gradle can be extended with any custom build script. Imagine an application that provides a test suite runtime. The actual test cases are provided by technical testers who write their test scripts using a domain specific language that is provided by the main application. Since you don’t want testers to add source files (defining new test cases) to your application all the time, the test case creation is made in independent .kts files in which the DSL is utilized by the testing team. The test suite main application can use the presented KtsRunner library for loading the test cases provided in .kts files and process them further afterward.

An example

A pretty popular DSL for Kotlin is kotlinx.html, a language for describing type-safe HTML. You let the client of your application provide some arbitrary HTML that you want to render at a later time. The HTML DSL code is provided as .kts script files and might look like this:

import kotlinx.html.*
import kotlinx.html.dom.create
import org.w3c.dom.Element
import java.io.OutputStream
import java.io.OutputStreamWriter
import javax.xml.parsers.DocumentBuilderFactory

val document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument()
document.create.html {
    head {
        title("Hello world")
    }
    body {
        h1("h1Class") {
            style = "background-color:red"
            +"My header1"
        }
        p("pClass") {
            +"paragraph1"
        }
    }
}

When executed, an instance of org.w3c.dom.Element is created that contains the described HTML code in an XML document:

<?xml version="1.0" encoding="UTF-8"?><html>
    <head>
        <title>Hello world</title>
    </head>
    <body>
        <h1 class="h1Class" style="background-color:red">My header1</h1>
        <p class="pClass">paragraph1</p>
    </body>
</html>

That’s straightforward but the interesting part is that the script should actually be executed from the main program. For this purpose, we add the KtsRunner to the application by adding a repository and the dependency itself to the Gradle build file:

maven { 
    setUrl("https://dl.bintray.com/s1m0nw1/KtsRunner")
}
dependencies {
    //...
    compile("de.swirtz:ktsRunner:0.0.x")
}  

The final code for loading the Element from the external script looks as follows:

KtsObjectLoader().load<Element>(script)

Simple, isn’t it? Unfortunately, the shown Scripting API implementation for Kotlin is rather slow and you’ll definitely notice some performance constraints. Altogether, the KtsRunner is a very tiny tool that only encapsulates the glue code for enabling Kotlin Scripting support in random applications. The library is published on bintray and can therefore easily be used from your own application.

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

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

Kotlin Features I miss most in Java – Kotlin vs Java

Let’s write an article that covers “Kotlin vs Java” topics – I want to tell you which Kotlin features I miss most when going back to 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.

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂
Create a DSL in Kotlin

Create a DSL in Kotlin

Kotlin as a programming language provides some very powerful features, which allow the creation of custom internal Domain Specific Languages (DSL).  One of these features, I also wrote about on this blog, is called Function Literals with Receiver, others are the invoke convention or infix notation. In this article, I will show how to create a Kotlin DSL by introducing a library that exposes a DSL as its API. I’ve often been struggling with Java’s API when I had to set up SSL/TLS connections in scenarios where I e.g. needed to implement HTTPS communication. I always felt like wanting to write a little library that can support me with this task, hiding away all the difficulties and of course the boilerplate needed for it.

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

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

Kotlin Operator Overloading – Working by Convention

Kotlin Operator Overloading and Conventions

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 Operator Overloading.
In this article, I want to show you which conventions you can use and I will also provide a few Kotlin code examples that demonstrate the concepts.

Read More Read More

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂
Kotlin on the JVM – Bytecode Generation

Kotlin on the JVM – Bytecode Generation

Kotlin on the JVM – How can it provide so many features?

Introduction

What exactly is a “JVM language”, what is Kotlin? Isn’t only Java meant to run on the JVM?
Kotlin provides many features that aren’t available in Java such as proper function types, extension functions and data classes. How is this even possible? I’ve taken a deeper look at how Kotlin works under the hood and what “JVM language” actually means. We’ll be having a look at Kotlin’s bytecode generation. If you also thought about these things already, this article should bring some light into the darkness 🙂

For a more detailed introduction to Kotlin’s features you can have a look at my Getting Started Guide.

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂
Kotlin Sealed Class – An Explanation

Kotlin Sealed Class – An Explanation

Today I came across the Kotlin Sealed Class which I had never heard of before. After some research, I found that this concept is nothing new and is also available in Scala for example. So, yet another Scala feature JetBrains considered relevant and suitable for Kotlin? I like that 🙂 Read this post if you’re interested in more Kotlin features.

Actually, this is a quite simple feature, which I’m going to explain in the following.

Kotlin Sealed Class – Feature Explanation

A sealed class can be subclassed and may include abstract methods, which means that sealed classes are abstract implicitly, although the documentation doesn’t clearly say so. To actually make a class “sealed” we have to put the sealed modifier before its name, as we can see here:

sealed class MyClass

Restriction

The important thing about sealed classes is that its subclasses must be declared in the same file as the sealed class itself.

Benefit

The feature allows us to define class hierarchies that are restricted in their types, i.e. subclasses. Since all subclasses need to be defined inside the file of the sealed class, there’s no chance of unknown subclasses which the compiler doesn’t know about.

Wait… Isn’t this what an enum actually is?

A Kotlin sealed class is some kind of extension of plain enums: As opposed to enums, subclasses of sealed classes can be instantiated multiple times and can actually contain state.

Use Case

The main advantage of sealed classes reveals itself if it’s used in when expressions. Let’s compare a normal class hierarchy to one of a sealed class handled in a when. First, we’ll create a hierarchy of Mammals and then put it in a method with a when:

open class Mammal(val name: String)
class Cat(val catName: String) : Mammal(catName)
class Human(val humanName: String, val job: String) : Mammal(humanName)
fun greetMammal(mammal: Mammal): String {
    when (mammal) {
        is Human -> return "Hello ${mammal.name}; You're working as a ${mammal.job}"
        is Cat -> return "Hello ${mammal.name}"
        else -> return "Hello unknown"
    }
}

The else is mandatory, otherwise, the compiler will complain. This is because it just cannot verify that all possible cases, i.e. subclasses, are covered here. It may be possible that a subclass Dog is available at any time which is unknown at compile time.

Sealed “to the rescue”

But what if we knew there wouldn’t be other Mammals in our application? We’d want to leave out the else block.

The problem of unknown subclasses can be avoided by sealed classes. Let’s modify the base class Mammal, its’ subclasses can remain the same.

sealed class Mammal(val name: String)

Now we can simply omit the else clause since the compiler can verify that all possible cases are covered because only the subclasses in the file of the sealed class exist, without exception. The method now looks as follows:

fun greetMammal(mammal: Mammal): String {
    when (mammal) {
        is Human -> return "Hello ${mammal.name}; You're working as a ${mammal.job}"
        is Cat -> return "Hello ${mammal.name}"
        // `else` clause not required, all the cases covered 
    }
}

That’s it. In conclusion really simple and handy, isn’t it? Have fun trying it yourself!

Finally, if you want to read about sealed class in Kotlin in more detail I recommend the book Kotlin in Action to you!

Simon


 

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂
Kotlin Generics and Variance (Compared to Java)

Kotlin Generics and Variance (Compared to Java)

This article covers the concepts of Generics and Variance in Kotlin and compares it to Java. Kotlin Generics differ from Java’s in how users can define their type of variance. As opposed to Java, Kotlin allows defining variance on declaration-site, whereas Java only knows use-site variance.

Kotlin Generics – What is Variance?

Many programming languages support the concept of subtyping, which allows implementing hierarchies that represent relationships like “A Cat IS-An Animal“. In Java, we can either use the extends keyword in order to change/expand behavior of an existing class (inheritance) or use implements to provide implementations for an interface. According to Liskov’s substitution principle, every instance of a class A can be substituted by instances of its subtype B. The word variance, often referred to in mathematics as well, is used to describe how subtyping in complex aspects like method return types, type declarations, generic types or arrays relates to the direction of inheritance of the involved classes. There are three terms we need to take into account: Covariance, Contravariance, and Invariance.

Read More Read More

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂
Java Oracle Certification

Java Oracle Certification

Java Oracle Certification – Should you consider it?

I took the OCA SE 7 Programmer I Certification exam two years ago in 2015, which I passed successfully with a score of 86%. This year I will be taking the second exam of this certification path called OCP SE 7 Programmer II. In this post, I want to reflect why taking these kind of exams isn’t a waste of time but can be a great advantage for you as a Java developer. Of course, being certified in whatever area will increase your chances of getting a better job because certificates represent some kind of guaranty of your skills to a company. No doubt about that.

Read More Read More

Simon is a software engineer based in Germany with 7 years of experience writing code for the JVM and also with JavaScript. He’s very passionate about learning new things as often as possible and a self-appointed Kotlin enthusiast.

Please follow and like this Blog 🙂