DEV Community: Vinicius Carvalho

How I started Inference4j - an open source ML project in java with the help of Claude

Vinicius Carvalho — Wed, 04 Mar 2026 03:12:55 +0000

Introduction

A few weeks ago, I was researching how to run model inference in Java without integrating with an external API or loading a Python sidecar.

I stumbled upon ONNX runtime and was immediately hooked. A portable binary execution of a self-contained Neural Network Model.

When looking at benchmarks I was even more impressed — ONNX models seem to outperform PyTorch inference in most models I've tested.

There's even a nice Java wrapper.

However, it still requires users to know about tensor shapes, pre-processing steps, and post-processing steps.

Inference4j — Three Lines of Code Inference

So I thought, why not make it simple for Java developers and let them approach it from a use-case perspective?

Inference4j was born.

I'll spare you the details on how it works — I hope the docs make that clear enough.

The goal was simple:

Make inference a user-driven task. ImageClassifier, TextGenerator, ObjectDetector — these are the contracts users should interface with.
Run locally, not as a wrapper for API services.
Support ONNX's vast library of models.

Leveraging AI to Write an ML Framework

With this task at hand I started writing some of the interfaces. I knew I wanted operations to live at a use-case level, so I crafted the main interfaces first.

Next, I figured the lib should provide a pipeline interface that wraps things for users: (pre-process) → Inference → (post-process). Users shouldn't really care about what's under the hood — like how you need to pick the right scaling algorithm (Bicubic or Bilinear) for an image model. But at the same time, it had to be flexible and structured enough so that contributors could add more use cases via new models and pre/post processors.

When it came to actually implementing all of this, well, my time is really limited these days. That task would have probably set me back a few weeks, so instead I decided to use Claude to help me out.

Not hiding it, not trying to pretend I didn't use it — it was a massive accelerator for me, especially on tasks like configuring GitHub Actions or writing Python scripts (not my main language of choice). Those were created in minutes, not days.

Now, it made a ton of mistakes, needed a lot of gentle reminders not to violate good design principles or skip good software practices, but in most cases it was a life saver. The project would not have started without it.

I'd say I probably wrote about 35% of the code. All interfaces, design choices, and model selection were my inputs, but the bulk of implementation was Claude Code.

Don't Vibe Code, Learn From It

Now this is my biggest take, and also the most important part of this blog post.

I relied on Claude to help me write something like 90% of the tokenizer code. But in doing so, I also debugged each one of the tokenizers, learned about different strategies, and understood why each model chooses a different tokenizer for its encoder/decoder phase.

This was a gigantic learning experience — much richer than any Coursera course (and I've taken several courses in ML at this point), and much more insightful than just trying some Hugging Face model off the shelf. I was literally, at some points, debugging token IDs against the Python version to see if my tokenizer logic was correct.

Inverted Prompt Engineering

Early on I was using onnx-gen-ai for generative AI, but that became challenging as the runtime is still experimental and I was maintaining a Java build that Microsoft still doesn't publish.

So instead of asking Claude to write the auto-regressive loop that generative models need in order to produce new tokens, I asked it to explain to me, step by step, how the generative loop works — the KV cache, the logits, the sampling — and I wrote it myself.

And that was not only very insightful, it was fun. It gave me a sense of fulfillment that sometimes I feel AI agents take away from us. The agent was telling me what to do, not the other way around, and in the process I was learning what happens inside a generative loop.

This post was not about the library — although I hope you give it a try, open an issue, fix a bug, or contribute with a new model — but about the journey so far. And I'm excited about how much more can be done in this new era of software engineering we live in.

Using Computer Vision to extract sprite pixel art

Vinicius Carvalho — Wed, 27 May 2020 12:53:09 +0000

Introduction

Recently my 7yr old has been asking me to find some Mario Pixel Art for him to use as template to build minecraft structures.

If you Google it, this is probably the top result

There are quite a few like this one, high resolution and with guiding lines. Then one day your kid asks your for the Hammer Mario, that one was not easy to find.

My goal was to avoid having to use tools such as Gimp or TexturePacker to manipulate pixel art.

Another Google search and I found Mario Universe a website full of Mario Spritesheets.

A perfect Super Mario Bros 3 Spritesheet/Texture Atlas

But again, I don't want to cut each one of those sprites (187 in that picture alone). I wanted to automate all that.

This is the end goal result

Enter openCV

My first thought was to use openCV. I'm not familiar at all with it, I won't pretend I am. But I know it's a powerful toolkit that is used for instance to detect objects in frames. There must be an easy way to do that for simple sprites.

Another Google search and I bumped into this Stackoverflow thread: BINGO!

That is exactly what I was looking for. I had to tweak the parameters a bit, for example my structuring element size was reduced to be a 1px wide.

I needed pixel perfect matching for the images, using anything but would merge some sprites with their neighbors as a single rectangle.

Also, I wanted this to be in Kotlin, the Python code is easy enough to use. But I intend to build a small page for my kid to choose each sprite and print it, writing in Kotlin would be easier to me.

So here's the snippet I ended up writing to save the sprites from an input image:



fun extractSprites(file: File) {
        val parentFolder = file.parentFile
        val output = File(parentFolder, file.nameWithoutExtension)
        output.mkdirs()

        val bufferedImage = ImageIO.read(file)
        val image = Imgcodecs.imread(file.absolutePath)
        val gray = Mat()
        val thresh = Mat()
        val close = Mat()
        val dilate = Mat()
        val hierarchy = Mat()
        val contours = mutableListOf<MatOfPoint>()

        Imgproc.cvtColor(image, gray, Imgproc.COLOR_BGR2GRAY)
        Imgproc.adaptiveThreshold(gray, thresh, 255.0,
                Imgproc.ADAPTIVE_THRESH_GAUSSIAN_C,
                Imgproc.THRESH_BINARY_INV, 5, 1.0)
        val kernel = Imgproc.getStructuringElement(Imgproc.MORPH_RECT,
                Size(1.0,1.0))
        Imgproc.morphologyEx(thresh, close,  Imgproc.MORPH_CLOSE,
                kernel, Point(-1.0, -1.0), 2)
        Imgproc.dilate(close, dilate, kernel,
                Point(-1.0, -1.0), 1)
        Imgproc.findContours(dilate, contours, hierarchy,
                Imgproc.RETR_EXTERNAL, Imgproc.CHAIN_APPROX_SIMPLE)


        for ((index, it) in contours.withIndex()) {
            val rect = Imgproc.boundingRect(it)
            val sprite = bufferedImage.getSubimage(rect.x,
                    rect.y,
                    rect.width,
                    rect.height)
            val fileName = "${file.nameWithoutExtension}_$index"
            ImageIO.write(sprite, "png",
                    File(output, "${fileName}.${file.extension}"))

        }

    }

The result creates indexed images such as picture_<index>.<extension> on a folder with the same name as the source image.

Making those tiny images scalable

Now that I have an almost infinite supply of tiny 32x32 images, I had to find a way to scale them. Again the goal is to avoid using a tool, I wanted a website where my kid could go click on a pixel and get a full page print of it in high quality.

Well, turns out Scalable Vector Graphics or SVG for shorts exists for that. And they are nothing but a textual markup language. Converting an image into an SVG is very easy, no need for a tool or a framework for such simple task. All you need to do is read each pixel, and if the color of that pixel is not transparent write it as a <rect> element of an SVG document.



fun convertToSVG(image: BufferedImage, svgFolder: File, fileName: String) {
        val width = image.width
        val height = image.height
        val header = "<?xml version=\"1.0\" standalone=\"no\"?>\n<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\" \n  \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n<svg xmlns=\"http://www.w3.org/2000/svg\"\n     version=\"1.1\" width=\"$width\" height=\"$height\">\n";
        val svg = StringBuilder()
        svg.append(header)
        for(y in 0 until height){
            for(x in 0 until  width){
                val color = Color(image.getRGB(x, y), true)
                if(color.alpha != 0 ) {
                    val rgbColor = Integer.toHexString(color.rgb).substring(2)
                    svg.append("    <rect x=\"${x}px\" y=\"${y}px\" width=\"1px\" height=\"1px\" fill=\"#$rgbColor\"/>\n")
                }
            }
        }
        svg.append("</svg>")
        val output = File(svgFolder, "$fileName.svg")
        output.writeText(svg.toString())
    }

Original image scaled 20x

SVG version

Easy to see the difference right?

My next steps are to make all this consumable for my kid, a simple page where he can click on the sprite sheet, explode it and send to the printer in a large svg format with some guiding grids (pretty sure if there ain't any tool out there, adding those lines will be easy)

Hope you had as much fun reading this as I had writing it :)

Happy coding

GraalVM native, not quite there yet

Vinicius Carvalho — Tue, 19 May 2020 00:59:08 +0000

Introduction

I wrote a couple of posts around GraalVM here at dev.to: Building a native CLI with Kotlin and GraalVM and Building a native ktor application with GraalVM

There's a lot of articles out there praising GraalVM for how fast applications start, and how little memory footprint it uses, and it's all true. However you don't usually see people talking about the tradeoffs.

I recently started a micronaut application to connect to mysql and present data over a rest controller. A simple, yet a bit more than hello world type of app. I'll follow up with a full post and source code soon.

So if you just look in the speed improvements alone it's quite exciting:

Here's my app running as a jar

20:42:29.364 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 2085ms. 
Server Running: http://localhost:8080

And here it's running as a native image:

20:41:09.832 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 37ms. 
Server Running: http://localhost:8080

However building the app is nothing short of painful. There are a lot of gotchas when it comes to native apps. Tooling is improving for sure, but you still need to be very careful around reflection (in this matter, micronaut is such a bless compared to Spring for example).

Just look at how much memory this simple app needs to be compiled on my laptop (2017 MacBook Pro 16GB RAM):

[micronaut-graal:1288]    classlist:   9,486.18 ms,  1.47 GB
[micronaut-graal:1288]        (cap):   3,953.01 ms,  1.47 GB
[micronaut-graal:1288]        setup:   5,767.97 ms,  1.47 GB
[micronaut-graal:1288]   (typeflow): 161,511.61 ms, 12.77 GB
[micronaut-graal:1288]    (objects): 164,768.04 ms, 12.77 GB
[micronaut-graal:1288]   (features):   9,852.69 ms, 12.77 GB
[micronaut-graal:1288]     analysis: 352,973.84 ms, 12.77 GB
[micronaut-graal:1288]     (clinit):   7,207.49 ms, 12.78 GB
[micronaut-graal:1288]     universe:  24,093.15 ms, 12.78 GB
[micronaut-graal:1288]      (parse):  19,852.03 ms, 12.79 GB
[micronaut-graal:1288]     (inline):  23,210.25 ms, 12.79 GB
[micronaut-graal:1288]    (compile):  56,323.43 ms, 12.80 GB
[micronaut-graal:1288]      compile: 111,321.81 ms, 12.80 GB
[micronaut-graal:1288]        image:  12,677.21 ms, 12.80 GB
[micronaut-graal:1288]        write:   4,104.11 ms, 12.80 GB
[micronaut-graal:1288]      [total]: 521,240.14 ms, 12.80 GB

My goal with this app was to run it as a serverless app on Google Cloud Run. So I had to build a docker container and push it to gcr.io. And since I needed to build a linux image, not a OSX, I used Google Cloud Build, problem is that Cloud Build crashes with this, the regular instance can't handle 13GB of memory requested by a container, so I had to beef it up: gcloud builds submit --machine-type=n1-highcpu-32

Final thoughts

Before even writing about the application or how much speed I was able to squeeze out of a java app, I think its important to look on how much time you as developer will spend chasing reflection issues, or waiting for the compilation stages to finish.

GraalVM has a promising future, and I'm hopeful for that, just maybe not ready for prime time yet.

Happy coding

Cloud in a budget: Preemptible instances to the rescue

Vinicius Carvalho — Thu, 12 Mar 2020 02:22:24 +0000

Saving costs on cloud

For those on a tight budget,
Google Cloud Preemtible VMs is one of my favorite offerings.

Preemptible VMs are restarted (recycled) every 24 hours which make them a great fit for stateless workloads. The benefit of those VMs comes in pricing. Prices for a 24/7 VM running on us-central1:

Configuration	Regular	Preemptible
E2 4vCPUs 16GB RAM	$97.84	$29.35

As you can see, there's a huge cost saving in leveraging them. Consider the cost savings for your testing enviroments alone.

Wait what about serverless?

A lot of people may point out that you should use serverless for stateless workloads, since it's a managed offering.

And while that is indeed true for most cases, there are still several workloads that would not make sense on a serverless environment.

One of the main shortcomings of serverless offerings is the fact that you can't run long running processes.

Another issue is the fact that many serverless offerings would not allow you to customize the sandbox environment (Google Cloud run fixes this by letting you bring your own container with your pre packaged libraries, and lambda layers also help in that front).

Quasi-stateful machines

Ok, so preemtible VMs can't really run stateful workloads, but it doesn't mean you can't have state. That is possible by attaching a persistent disk to your instance.

The data on the boot disk gets discarded on every restart, but not the persistent disk.

GCE instances can run scripts during the startup and you can attach one or more disks to it. The script bellow would mount and format (if not already) any disk on /dev/sdb

#!/bin/bash

if sudo blkid /dev/sdb;then 
   exit
else 
   sudo mkfs.ext4 -m 0 -F -E lazy_itable_init=0,lazy_journal_init=0,discard /dev/sdb; \
   sudo mkdir -p /mnt/data
   sudo mount -o discard,defaults /dev/sdb /mnt/data
fi

Please be advised that a machine stop can lead to data corruption so be careful when using this approach *

Our cheap batch workload agent

Where I found this to be very useful was running some long running (2~3 hours a day jobs) where I could use some beefier machines for video encoding tasks.

As video encoding requires a good chunk of CPU and a bunch of libraries installed on the OS. Preemptible VMs were an easy choice. To give you an idea, running a node 4 hours would cost:

Configuration	Regular	Preemptible
E2 16vCPUs 64GB RAM	$65.22	$19.57

Not too bad right? We start and stop the VMs via cloud functions and cloud scheduler (there's a place for serverless too).

So if you are in a budget, consider using preemptible VMs if your architecture requires batching or stateless workloads.

Happy coding.

Simple load testing with Locust and Kubernetes

Vinicius Carvalho — Thu, 17 Oct 2019 13:12:30 +0000

The code for the manifest script can be found here

Every single time I need to run some load testing, I'm faced with analysis paralysis syndrome.

So after searching I bumped into locust.io, a python based distributed load testing framework.

I'm not a Python developer, but locust is simple enough that made me reconsider dumping gatling and give it a try. FWIW: Gatling is extremely powerful, but also quite more complex to work with.

Ok, time to wrap this on a container and run on kubernetes, luckily someone already did that: Distributed load testing using Kubernetes

But I was not ok with that solution, mostly because I had to build a new container for every test. The flow I was considering was a bit more like this:

Tests are saved to github
Images are immutable
Users create clusters and point to a specific test

The good thing is that achieving this is relatively easy, we can add an Init Container section to pull the tests from github:



 initContainers:
      - name: gitbox
        image: viniciusccarvalho/alpine-git
        command:
        - git
        - clone
        - "https://github.com/user/test-repository"
        - "/data/tests"
        volumeMounts:
        - name: workdir
          mountPath: "/data/"

So now when the locust container starts all the test resources should be available at the /data/ folder.

Automate all the things

To deploy a locust cluster we will need 4 kubernetes resources:

A master deployment
A worker deployment (with N number of replicas and pointing to the master service)
A master service (using ClusterIp so workers can access the master)
A Loadbalancer service for the master (optional) for accessing the endpoint

All those files would only differ on a few parts (the repo, the target file, the target host, and the name), so I decided to create a script that automatically creates those files.

You can pull it here

If you run the script with a -h you would get all the required parameters to create the artifacts:



python locust-deploy.py -h
usage: locust-deploy.py [-h] -n NAME -t TARGET_HOST -r REPO -f TEST_FILE
                        [-s SIZE] [-o OUTPUT]

Locust cluster manifest generator

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Name of the test cluster artifacts
  -t TARGET_HOST, --target_host TARGET_HOST
                        Target host to run tests against
  -r REPO, --repo REPO  Github repository containing the tests
  -f TEST_FILE, --test_file TEST_FILE
                        The locust file to be used, relative to the github
                        root path
  -s SIZE, --size SIZE  Number of workers pods to be created. Default to 1
  -o OUTPUT, --output OUTPUT
                        Manifest files output

And if you run it pointing to a location, say ~/tmp/locust-deployments you end up with:



 ls -la ~/tmp/locust-deployments
total 32
drwxr-xr-x   6 vinnyc  primarygroup   192 Oct 16 17:45 .
drwxr-xr-x  16 vinnyc  primarygroup   512 Oct 16 11:35 ..
-rw-r--r--   1 vinnyc  primarygroup   246 Oct 16 17:45 appengine-locust-master-service-lb.yaml
-rw-r--r--   1 vinnyc  primarygroup   352 Oct 16 17:45 appengine-locust-master-service.yaml
-rw-r--r--   1 vinnyc  primarygroup  1415 Oct 16 17:45 appengine-locust-master.yaml
-rw-r--r--   1 vinnyc  primarygroup  1285 Oct 16 17:45 appengine-locust-worker.yaml

After deploying those artifacts you will have a new locust cluster ready to be accessed on your LB public endpoint:

There you have it, a very simple, and easy to deploy 20 node swarm test cluster for you to use.

Happy coding

Don't let the shadow jar plugin shadow your application

Vinicius Carvalho — Thu, 12 Sep 2019 19:42:28 +0000

In my previous post, I shared a template for deploying a ktor application to Google App Engine.

As part of this process I was using the Shadow plugin.
Well it turns out, by default the plugin won't copy service files from java Serviceloader.

This lead to my application failing due SPI classes not being loaded. So if your app breaks by using the plugin just add this to your build.gradle

shadowJar {
    mergeServiceFiles()
}

Happy coding

Deploying fatjar Ktor applications on Google Cloud App Engine

Vinicius Carvalho — Wed, 11 Sep 2019 13:28:38 +0000

The original serverless platform

Google App Engine or GAE for short. Has always been an amazing service to run your web applications. Some highlights:

Supports multiple runtimes (java, python, go, php, ruby, nodejs )
Serverless execution mode, pay only for requests in flight
Offers free tier for some services
Support for versioning and traffic splitting
Task scheduling and queuing of background tasks
Many more, visit the official documentation for more information.

However for java developers there have always been a problem, you could only deploy war files, restricting you to the Servlet Spec.

Not anymore, starting with the java11 runtime, GAE now offers a way to run self contained jar files (Ktor, SpringBoot, Micronaut, Quarkus).

Introducing the Java11 runtime

Starting with the java11 runtime, you can now deploy a "fat jar" file and execute it instead of deploying a war file into a Jetty container.

All you need to do is create a new app.yaml file that contains the correct entrypoint command:

runtime: java11
instance_class: F2
entrypoint: 'java  -jar frontend-1.0-SNAPSHOT-all.jar'
service: default

You can pass any valid java argument to the JRE and if you would like to learn all the possible options of the yaml file, check the documentation

Skelleton project for ktor on GAE

Today I'll share my skelleton project for running ktor apps on GAE. Please feel free to clone it from here and use it as starting point.

Project layout

.
├── build.gradle
├── gradle
│   └── wrapper
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   ├── appengine
    │   ├── java
    │   ├── kotlin
    │   └── resources
    └── test
        ├── java
        ├── kotlin
        └── resources

I've always liked the standard gradle project layout. The only difference here is the appengine folder under our main directory. This contains the app.yaml deployment file.

Gradle configuration

First off, this project uses gradle 5.6. Your gradle/wrapper/gradle-wrapper.properties should look like this:

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-5.6-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

The build.gradle is generic enough that you can literally just copy and paste and use it for your project. As I mentioned before this is a template I use for all my projects.

buildscript {
    ext.kotlin_version = '1.3.50'
    ext.ktor_version = '1.2.4'
    repositories {
        mavenCentral()
        jcenter()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
        classpath 'com.github.jengelman.gradle.plugins:shadow:5.1.0'
        classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.+'
    }
}


apply plugin: 'kotlin'
apply plugin: 'application'
apply plugin: 'com.github.johnrengelman.shadow'
apply plugin: 'com.google.cloud.tools.appengine'

group 'io.igx.cloud'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

mainClassName = "io.ktor.server.netty.EngineMain"

repositories {
    mavenCentral()
    jcenter()
}


appengine {
    stage {
        artifact = "build/libs/$project.name-$project.version-all.jar"
    }
}

test {
    useJUnitPlatform()
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    implementation "io.ktor:ktor-server-core:$ktor_version"
    implementation "io.ktor:ktor-server-netty:$ktor_version"
    implementation "io.ktor:ktor-gson:$ktor_version"


    testImplementation "org.assertj:assertj-core:3.13.2"
    testImplementation "io.mockk:mockk:1.9.3"
    testImplementation "org.junit.jupiter:junit-jupiter:5.5.1"
    testImplementation 'org.koin:koin-test:2.0.1'

}

compileKotlin {
    kotlinOptions.jvmTarget = "1.8"
}
compileTestKotlin {
    kotlinOptions.jvmTarget = "1.8"
}

I'm using shadow plugin to create my fat jar. It integrates nicely on my application gradle phase and generates an artifact appending -all to its name.

I've also modified the appengine defaults to point to the new jar created via the shadow plugin.

And last, I added the gradle appengine plugin.

Very simple, but reusable and saves me a ton of time. To build/deploy

./gradlew clean build
./gradlew appengineDeploy

That's it, hope you enjoy it.

Happy coding

Building a native ktor application with GraalVM

Vinicius Carvalho — Thu, 11 Apr 2019 00:10:26 +0000

The source code for this post can be found on this github repo

Introduction

On my last post: Building a native cli with kotlin and graalvm, I've demonstrated how to build native cli application using graalvm. On this post we will build a web application using ktor.io and the GraalVM.

Requirements

GraalVM installed and $GRAALVM_BIN pointing to the binary folder of your install

Building it

Ktor supports several server options (Netty, Jetty, CIO). Netty is my favorite option for java applications, but it can be quite painful trying to get netty to work with GraalVM as explained here

So I tried the CIO server (leverages only kotlin code, and coroutines). I then found out that GraalVM does not support the bytecode generated by coroutines.

Fortunately after some googling I bumped into kraal which seems to solve the problem.

The example will use the Gradle Kotlin DSL, just create a new Gradle project on intellij and mark "use Kotlin DSL"

From there modify your build.gradle.kts to look like this:

import org.gradle.jvm.tasks.Jar
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    kotlin("jvm") version "1.3.21"
    id("com.hpe.kraal") version "0.0.15" // kraal version - for makeRelease.sh
}

group = "io.igx.kotlin"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
    jcenter()
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation("org.slf4j:slf4j-simple:1.7.26")
    implementation("io.ktor:ktor-server-cio:1.1.3")
    implementation("io.ktor:ktor-gson:1.1.3")
}

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions {
        jvmTarget = "1.8"
        // need use-experimental for Ktor CIO
        freeCompilerArgs += listOf("-Xuse-experimental=kotlin.Experimental", "-progressive")
        // disable -Werror with: ./gradlew -PwarningsAsErrors=false
        allWarningsAsErrors = project.findProperty("warningsAsErrors") != "false"
    }
}


val fatjar by tasks.creating(Jar::class) {

    from(kraal.outputZipTrees) {
        exclude("META-INF/*.SF")
        exclude("META-INF/*.DSA")
        exclude("META-INF/*.RSA")
    }

    manifest {
        attributes("Main-Class" to "io.igx.kotlin.ApplicationKt")
    }

    destinationDirectory.set(project.buildDir.resolve("fatjar"))
    archiveFileName.set("ktor-native.jar")
}

tasks.named("assemble").configure {
    dependsOn(fatjar)
}

As usual, just edit the group/Main-Class to match your own packaging structure.

Let's make sure our app outputs some JSON based on a domain class:

data class Driver(val id: Int, val firstName: String, val lastName: String, val nationality: String)

Your Application should look like this one:

fun main(args: Array<String>) {
    val server = embeddedServer(CIO, 8080, module = Application::module)
    server.start(wait = true)
}

fun Application.module() {
    install(CallLogging)
    install(ContentNegotiation) {
        gson {
            setPrettyPrinting()
        }
    }
    routing {
       get("/drivers"){
           call.respond(Driver(102, "Ayrton", "Senna", "Brazilian"))
       }
    }
}

Testing

run ./gradlew clean build and then java -jar build/fatjar/ktor-native.jar and your app should be app and running:

[DefaultDispatcher-worker-1] INFO ktor.application - No ktor.deployment.watch patterns specified, automatic reload is not active
[DefaultDispatcher-worker-1] INFO ktor.application - Responding at http://0.0.0.0:8080

Hit http://0.0.0.0:8080/drivers

{
"id": 102,
"firstName": "Ayrton",
"lastName": "Senna",
"nationality": "Brazilian"
}

Native image

As with our previous post, run the native-image command:

$GRAALVM_BIN/native-image  --report-unsupported-elements-at-runtime --jar build/fatjar/ktor-native.jar ktor-native --enable-url-protocols=http --no-server

run ./ktor-native, hit http://0.0.0.0:8080/drivers and you will get:

{}

Reflection issues

So, GraalVM needs a little help handling reflection as explained here.

Add the following file to the root of your project (reflection.json)


[
   {
    "name" : "io.igx.kotlin.model.Driver",
    "allDeclaredConstructors" : true,
    "allPublicConstructors" : true,
    "allDeclaredMethods" : true,
    "allPublicMethods" : true,
     "fields" : [
       { "name" : "id" },
       { "name" : "firstName" },
       { "name" : "lastName" },
       { "name" : "nationality" }
     ]
   },

  {
  "name" : "java.lang.Integer",
  "methods" : [{ "name" : "parseInt", "parameterTypes" : ["java.lang.String"]}]
}, {
  "name" : "java.lang.Long",
  "methods" : [{ "name" : "parseLong", "parameterTypes" : ["java.lang.String"]}]
}, {
  "name" : "java.lang.Boolean",
  "methods" : [{ "name" : "parseBoolean", "parameterTypes" : ["java.lang.String"]}]
}, {
  "name" : "java.lang.Byte",
  "methods" : [{ "name" : "parseByte", "parameterTypes" : ["java.lang.String"]}]
}, {
  "name" : "java.lang.Short",
  "methods" : [{ "name" : "parseShort", "parameterTypes" : ["java.lang.String"]}]
}, {
  "name" : "java.lang.Float",
  "methods" : [{ "name" : "parseFloat", "parameterTypes" : ["java.lang.String"]}]
}, {
  "name" : "java.lang.Double",
  "methods" : [{ "name" : "parseDouble", "parameterTypes" : ["java.lang.String"]}]
}
]

Run the native-image command again, but this time add the -H:ReflectionConfigurationFilesflag

~/java/graalvm-ce-1.0.0-rc13/Contents/Home/bin/native-image  --report-unsupported-elements-at-runtime -H:ReflectionConfigurationFiles=reflection.json  -jar build/fatjar/example.jar ktor-native --enable-url-protocols=http --no-server

Try it again and you will see the original results of your Driver JSON payload.

Final Thoughts

Dealing with reflection on GraalVM can be a bit challenging, luckily to us, several people on the industry like the folks at RedHat are trying to come up with frameworks such as quarkus.io to overcome this limitation.

I have no doubt that IDEs will soon catch up and be able to inspect the code and generate those reflection files for us.

Meanwhile enjoy your blazing fast ktor server running as a native image on your server.

Happy Coding!

Building a native CLI with Kotlin and GraalVM

Vinicius Carvalho — Mon, 08 Apr 2019 15:24:17 +0000

Building native code using java

GraalVM is an exciting new VM released by Oracle that enables creation of polyglot apps. Perhaps one of the most exciting new features is the native-image tool that compiles your bytecode into a single binary that can be executed on the target runtime without the need of a JVM.

But because it's now packaged as a single binary it means it also does not need to create a JVM in first place, and memory usage and the warmup period associated with JVM processes are long gone.

Just to give you an idea of what we are talking about, the app we will build today had the following results (java vs native versions)

Java: 0.97s user 0.10s system 131% cpu 0.808 total

Binary: 0.01s user 0.01s system 8% cpu 0.232 total

Command Line apps the missing use case of java

Now, there are a couple of frameworks out there like Quarkus and Micronaut that provides an easy way to migrate server side apps into native ones.

That's all great, but IMHO server side has never been the issue with java, once a JVM is warmed up and serving thousands of requests, it's very hard to beat it with the node/go versions. It's fast, it is stable, and once you hit a given threshold of users, the memory footprint is not that bad.

CLI apps on the other hand, were always a weak spot for java. No one wants to download a jar file, install (the right version) java, just to execute a few commands.

More often than not our teams need to write a CLI to integrate something, and java/kotlin have never been the choice. This is where go became king, and hopefully now with GraalVM things can change a bit.

So what are we building today?

I wanted to build a CLI to wrap a REST service. A lot of CLIs today work in this fashion: kubectl, gcloud, azure... So it seemed like a good start.

Our CLI app, which we will call f1, will be a wrapper for the Ergast motor racing API.

Requirements, limitations, where does it hurt?

Converting a java app into a native app can be a painful experience depending on what features of the JVM you use. Specially reflection, read this section on reflection if you want to understand more about it.

I tried my best to avoid reflection based frameworks when writing this article, it gets specially painful when you have to deal with JSON and kotlin data classes.

Dependencies:

Clikt - Kotlin based CLI parser and framework. No annotations, no reflections, less to worry when building your native app
Fuel - Kotlin http client library, with no reflections (like retrofit2) and others.
[Gson] - Google JSON library, I chose to write specific SerDes classes, it wasn't that bad, if you go the reflection route you may need to append classes to the reflect-config.json

Let's build it

All the code can be found on this github repo.

Start a new gradle kotlin project. I usually go with IntelliJ IDEA's new project wizard.

I rather create a fat jar so make sure your build.gradle looks something like this:

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
        classpath 'com.github.jengelman.gradle.plugins:shadow:4.0.3'
    }
}
apply plugin: 'java'
apply plugin: 'kotlin'
apply plugin: 'application'
apply plugin: "com.github.johnrengelman.shadow"

group 'io.igx.kotlin'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8


mainClassName = "io.igx.kotlin.ApplicationKt"

repositories {
    mavenCentral()
    jcenter()
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
    implementation 'com.github.ajalt:clikt:1.7.0'
    implementation 'com.github.kittinunf.fuel:fuel-gson:2.0.1'
    implementation 'de.vandermeer:asciitable:0.3.2'
    testCompile group: 'junit', name: 'junit', version: '4.12'
}

compileKotlin {
    kotlinOptions.jvmTarget = "1.8"
}
compileTestKotlin {
    kotlinOptions.jvmTarget = "1.8"
}

Modify your Application.kt file to have a simple print on it:

fun main(args: Array<String>) {
    println("Hello Native")
}

Important : Make sure you have the GraalVM installed, and that $GRAALVM_BIN is the folder where your install binaries are located.

Build your app ./gradlew build and now generate the native image by invoking the following command

$GRAALVM_BIN/native-image --report-unsupported-elements-at-runtime  -jar build/libs/f1-1.0-SNAPSHOT-all.jar f1 --no-server

You can check what each of those flags mean here

After the native-image tool finishes you should have an f1 binary. Just invoke it: ./f1 and you get a nice Hello Native output.

Creating the commands

What we need now is some commands that we want to translate into REST calls. Clikt we will create a main command F1 and nest two subcommands: Drivers and Circuits.

Create a Commands.kt file and add the following code:


class F1 : CliktCommand() {
    override fun run() = Unit
}

class DriverCommands : CliktCommand(name = "drivers") {

    val season: Int by option(help = "Season year").int().default(LocalDate.now().year)

    override fun run() {
       println("Fetching drivers of $season season")
    }

}

class CircuitCommands : CliktCommand(name="circuits") {
    val season: Int by option(help = "Season year").int().default(LocalDate.now().year)

    override fun run() {
       println("Fetching circuits of $season season")
    }

}

Change your `Application.kt` main method to:

kotlin
fun main(args: Array) {
F1().subcommands(DriverCommands(), CircuitCommands()).main(args)
}


Build the whole thing with `gradle` and run the `native-image` command again.

Try running ./f1 now and you will be greet with some nice default help message from clikt:

Usage: f1 [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit

Commands:
  drivers
  circuits

As you can see we have two registered commands, and running help on those:

./f1 drivers --help
Usage: f1 drivers [OPTIONS]

Options:
  --season INT  Season year
  -h, --help    Show this message and exit

Ok so we now have our skeleton for our CLI app, let's just add some content to it.

Handling JSON

As I said before, reflection is a bit painful with GraalVM. So I went for a method of writing my own JsonDeserializer for each of the domain objects of the remote API.

The ergast API has another problem, the way they represent wrapped json is not really friendly to java parsing (they pretty much mimic their XML representation), so customization for handling those wrappers would be needed anyways.

I've created a Domain.kt file where I put all the serialization logic:

data class Response(val series: String, val limit: Int, val offset:Int, val total:Int)
data class Driver(val driverId: String, val code: String?, val url: String? = "", val givenName: String, val familyName: String, val dateOfBirth: String?, val nationality: String?)
data class DriverResponse(val response: Response, val season: Int, val drivers: List<Driver>)

data class Location(val lat: Float?, val lon: Float?, val locality: String?, val country: String?)
data class Circuit(val circuitId: String, val url: String?, val name: String, val location: Location)
data class CircuitResponse(val response: Response, val season: Int, val circuits: List<Circuit>)

class CircuitDeserializer : JsonDeserializer<Circuit>{
    override fun deserialize(element: JsonElement?, typeOfT: Type?, context: JsonDeserializationContext?): Circuit {
        val json = element as JsonObject
        val jsonLocation = json.getAsJsonObject("Location")
        val location = Location(jsonLocation.get("lat")?.asFloat, jsonLocation.get("long")?.asFloat, jsonLocation.get("locality")?.asString, jsonLocation.get("country")?.asString)
        return Circuit(json.get("circuitId").asString, json.get("url")?.asString, json.get("circuitName").asString, location)
    }
}

class DriverDeserializer : JsonDeserializer<Driver> {
    override fun deserialize(element: JsonElement?, typeOfT: Type?, context: JsonDeserializationContext?): Driver {
        val json = element as JsonObject
        return Driver(json.get("driverId").asString, json.get("code")?.asString, json.get("url")?.asString, json.get("givenName").asString, json.get("familyName").asString, json.get("dateOfBirth")?.asString, json.get("nationality")?.asString)
    }

}

class CircuitResponseDeserializer : JsonDeserializer<CircuitResponse> {
    override fun deserialize(
        element: JsonElement?,
        typeOfT: Type?,
        context: JsonDeserializationContext?
    ): CircuitResponse {
        val wrapper = element as JsonObject
        val json = wrapper.getAsJsonObject("MRData")
        val response = json.toResponse()
        val table = json.get("CircuitTable").asJsonObject
        val season = table.get("season").asInt
        val circuitType = object : TypeToken<List<Circuit>>() {}.type
        return CircuitResponse(response, season, context!!.deserialize(table.get("Circuits").asJsonArray, circuitType))

    }

}

class DriverResponseDeserializer : JsonDeserializer<DriverResponse> {

    override fun deserialize(element:  JsonElement?, typeOfT: Type?, context: JsonDeserializationContext?): DriverResponse {

        val wrapper = element as JsonObject
        val json = wrapper.getAsJsonObject("MRData")
        val response = json.toResponse()

        val table = json.get("DriverTable").asJsonObject
        val season = table.get("season").asInt
        val driversType = object : TypeToken<List<Driver>>() {}.type

        return DriverResponse(response, season, context!!.deserialize(table.get("Drivers").asJsonArray, driversType))
    }

}

fun JsonObject.toResponse() : Response {
    return Response(this.get("series").asString, this.get("limit").asInt, this.get("offset").asInt, this.get("total").asInt)
}

And the final version of your Commands.kt should look like this:


class DriverCommands : CliktCommand(name = "drivers") {

    val season: Int by option(help = "Season year").int().default(LocalDate.now().year)

    override fun run() {
        val gson = GsonBuilder()
            .registerTypeAdapter(DriverResponse::class.java, DriverResponseDeserializer())
            .registerTypeAdapter(Driver::class.java, DriverDeserializer())
            .create()
        val responseString = Fuel.get("http://ergast.com/api/f1/$season/drivers.json").responseString().third.get()
        val driverResponse = gson.fromJson<DriverResponse>(responseString, DriverResponse::class.java)
        val table = AsciiTable()
        table.addRule()
        table.addRow(null, null, "$season season drivers").setTextAlignment(TextAlignment.CENTER)
        table.addRule()
        table.addRow("Driver name", "Date birth", "Nationality").setTextAlignment(TextAlignment.CENTER)
        table.addRule()
        driverResponse.drivers.forEach {driver ->
            table.addRow("${driver.givenName} ${driver.familyName}", driver.dateOfBirth, driver.nationality).setTextAlignment(TextAlignment.CENTER)

            table.addRule()
        }
        println(table.render())
    }

}

class CircuitCommands : CliktCommand(name="circuits") {
    val season: Int by option(help = "Season year").int().default(LocalDate.now().year)

    override fun run() {
        val gson = GsonBuilder()
            .registerTypeAdapter(CircuitResponse::class.java, CircuitResponseDeserializer())
            .registerTypeAdapter(Circuit::class.java, CircuitDeserializer())
            .create()
        val table = AsciiTable()
        table.addRule()
        table.addRow(null, null, "$season season circuits").setTextAlignment(TextAlignment.CENTER)
        table.addRule()
        table.addRow("Circuit", "Location", "Country").setTextAlignment(TextAlignment.CENTER)
        table.addRule()
        val responseString = Fuel.get("http://ergast.com/api/f1/$season/circuits.json").responseString().third.get()
        val circuitResponse = gson.fromJson<CircuitResponse>(responseString, CircuitResponse::class.java)
        circuitResponse.circuits.forEach {circuit ->
            table.addRow(circuit.name, circuit.location.locality, circuit.location.country).setTextAlignment(TextAlignment.CENTER)
            table.addRule()
        }
        println(table.render())
    }

}

First we prepare our Gson instance by registering the proper adapters
The AsciiTable is just a nice way to present the results
We get the response as string using Fuel and then map it to our Response type
Print the table.

Now build the project again using gradle but this time you need to modify the native-image command to enable the http protocol (disabled by default):

$GRAALVM_BIN/native-image  --report-unsupported-elements-at-runtime  -jar build/libs/f1-1.0-SNAPSHOT-all.jar f1 --enable-url-protocols=http --no-server

After building it try running the drivers command:


f1 ./f1 drivers
┌──────────────────────────────────────────────────────────────────────────────┐
│                             2019 season drivers                              │
├──────────────────────────┬─────────────────────────┬─────────────────────────┤
│       Driver name        │       Date birth        │       Nationality       │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Alexander Albon      │       1996-03-23        │          Thai           │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Valtteri Bottas      │       1989-08-28        │         Finnish         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│       Pierre Gasly       │       1996-02-07        │         French          │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│    Antonio Giovinazzi    │       1993-12-14        │         Italian         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Romain Grosjean      │       1986-04-17        │         French          │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│      Lewis Hamilton      │       1985-01-07        │         British         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Nico Hülkenberg      │       1987-08-19        │         German          │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│      Robert Kubica       │       1984-12-07        │         Polish          │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│       Daniil Kvyat       │       1994-04-26        │         Russian         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Charles Leclerc      │       1997-10-16        │       Monegasque        │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Kevin Magnussen      │       1992-10-05        │         Danish          │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│       Lando Norris       │       1999-11-13        │         British         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│       Sergio Pérez       │       1990-01-26        │         Mexican         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│      Kimi Räikkönen      │       1979-10-17        │         Finnish         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Daniel Ricciardo     │       1989-07-01        │       Australian        │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│      George Russell      │       1998-02-15        │         British         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│       Carlos Sainz       │       1994-09-01        │         Spanish         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│       Lance Stroll       │       1998-10-29        │        Canadian         │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│      Max Verstappen      │       1997-09-30        │          Dutch          │
├──────────────────────────┼─────────────────────────┼─────────────────────────┤
│     Sebastian Vettel     │       1987-07-03        │         German          │
└──────────────────────────┴─────────────────────────┴─────────────────────────┘

Closing thoughts

I'm truly excited to see that we can now build amazing CLI tooling with Java. I hope this post got you excited too. No need to split your team, or to ask them to learn a new language to write some cool tooling for your internal apis.

Happy coding!

Graceful shutdown of Ktor applications

Vinicius Carvalho — Tue, 02 Apr 2019 13:25:46 +0000

Cleaning up after you are finished

Cleaning up is something you are used to tell your kids multiple times a day, however not many of us remember to do this with our resources.

As I write more kotlin and ktor apps, one thing that bit me recently was the fact that I needed to clean up some temporary resources after my app was terminated (scaled down) by kubernetes.

In my scenario, I was creating some temporary Google Cloud Pubsub subscriptions on startup, and I had to delete them during a scale down operation.

Reading the ktor's docs I found that it has built-in support for application events. It should be easy right?

Starting with Ktor

The simplest way to kickstart a ktor project is by visiting http://start.ktor.io, following the same principles of spring starter, it generates a project with all the dependencies and even some basic configuration files for you.

IMPORTANT

One change I make to all my ktor projects is enabling the fat jar feature using the shadow plugin. I prefer this method to distribute my apps. Just modify your build.gradle buildscript and plugins sections as bellow:

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
        classpath 'com.github.jengelman.gradle.plugins:shadow:4.0.3'
    }
}

apply plugin: 'kotlin'
apply plugin: 'application'
apply plugin: "com.github.johnrengelman.shadow"

If you import your project on your IDE, your Main class should look something like this one (may differ depending on the features you chose at start).

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

@Suppress("unused") // Referenced in application.conf
@kotlin.jvm.JvmOverloads
fun Application.module(testing: Boolean = false) {
    install(ContentNegotiation) {
        jackson {
            enable(SerializationFeature.INDENT_OUTPUT)
        }
    }
    install(CallLogging) {
        level = Level.INFO
        filter { call -> call.request.path().startsWith("/") }
    }
    install(DefaultHeaders) {
        header("X-Engine", "Ktor") // will send this header with each response
    }
    routing {
        get("/") {
            call.respondText("HELLO WORLD!", contentType = ContentType.Text.Plain)
        }
        get("/json/jackson") {
            call.respond(mapOf("hello" to "world"))
        }
    }
}

You can now run ./gradlew build to package a fat jar on build/libs/<APPNAME>-<VERSION>-all.jar just run that jar file and you should see:

[main] INFO  Application - No ktor.deployment.watch patterns specified, automatic reload is not active
[main] INFO  Application - Responding at http://0.0.0.0:8080
[main] INFO  Application - Application started: io.ktor.application.Application@79517588

Enabling the lifecycle callbacks

As I said before we can subscribe for specific ApplicationEvents in our example let's watch ApplicationStarted and ApplicationStopped

If you change your main class to add two extra lines:

fun Application.module(testing: Boolean = false) {
    environment.monitor.subscribe(ApplicationStarted){
        println("My app is ready to roll")
    }
    environment.monitor.subscribe(ApplicationStopped){
        println("Time to clean up")
    }

And now you run it again:

[main] INFO  Application - No ktor.deployment.watch patterns specified, automatic reload is not active
[main] INFO  Application - Responding at http://0.0.0.0:8080
My app is ready to roll
[main] INFO  Application - Application started: io.ktor.application.Application@79517588

We can see that our callback has been called, but what happens when you terminate your process using a CTRL+C?

It turns out our callback does not get a chance to execute. So what went wrong?

Understanding how ktor bootstraps

Ktor has a couple of ways to bootstrap the server. The one used here uses EngineMain class as the entry point. This class will search for an application.conf file, in our example it looks like this:

ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
    application {
        modules = [ io.igx.kotlin.ApplicationKt.module ]
    }
}

The module section defines how we configure the server, but the start/stop behavior of it resides inside EngineMain.

The Netty version (I have not tried this with other servers implementations) does not wait for the application to terminate in case of SIGINT and therefore it's impossible for our subscriber to be invoked.

How to fix

Another way to bootstrap a server is by using an embeddedServer function. And this is what we are about to do in order to fix this issue.

fun main() {
    val server = embeddedServer(Netty, port = 8080){
        module()
    }.start(false)
    Runtime.getRuntime().addShutdownHook(Thread {
        server.stop(1, 5, TimeUnit.SECONDS)
    })
    Thread.currentThread().join()
}

Note that we reused all the module configuration from the generated Application file, but now we bootstrap the server manually and by adding a shutdown hook that invokes the stop method on the server we can gracefully wait for our subscriber to run.

Before packaging and running this version, don't forget to change the mainClassName attribute on your build.gradle file.

Now running and killing it with a SIGINT:

[main] INFO  ktor.application - No ktor.deployment.watch patterns specified, automatic reload is not active
[main] INFO  ktor.application - Responding at http://0.0.0.0:8080
My app is ready to roll
[main] INFO  ktor.application - Application started: io.ktor.application.Application@327514f
START all SERVERS
[Thread-1] INFO  ktor.application - Application stopping: io.ktor.application.Application@327514f
Time to clean up
[Thread-1] INFO  ktor.application - Application stopped: io.ktor.application.Application@327514f

As you can see from the Time to clean up message in the logs, our method was successfully invoked during termination.

Final thoughts

This very simple changed meant a lot to my use case, cleaning up resources was very important specially on an elastic environment that instances can come and go many times a day.

I've reached out to the ktor team asking for this to be incorporated on the EngineMain method, hope they will add this feature on the future.

Happy coding

Pipes and Filters in Kotlin

Vinicius Carvalho — Tue, 12 Mar 2019 18:31:36 +0000

Disclaimer: coroutines are still a new topic to me, many of the implementation ideas presented in this post could not be the best usage of it. You have been warned :)

Pipes and Filters

Pipes and Filters is a very common Integration Pattern. Entire frameworks such as the awesome Spring Integration have been built around it.

It's a simple concept, pipes connects endpoints much like you would use in a unix command ps | grep, this model allows endpoints to be independent of each other.

If you look into how Spring Integration achieves this, is by using a Channel abstraction

Well, it does so happens that kotlin coroutines also have a Channel implementation used to allow communication across coroutines.

So I was wondering if we could use it to create a very simple pipes and filters flow without leveraging any other external dependency.

The idea

Write something that allows leveraging channels as pipes to connect coroutine functions.
Leverage coroutine suspend features for concurrent execution, sometimes parallel withContext too :)
Write a simple DSL(ish) like source via fn via fn2 into fn4

It's not on the scope of this blog post to attempt to replicate all the features of a complete integration framework. No support for fanout via a publisher channel for example. No error handling or ack support.

How

So before diving into some code, I must confess that so far I have been always using GlobalScope.launch as the only way to launch my coroutines. And then I read the following blog posts below. If anything useful could come out of my blog today is those links for you:

We are starting with an assumption that the source will always be a Channel<T>, this is just to simplify things.

We have two pipes [via || into] and two top level endpoints: ChannelSink<T>, ChannelProcessor<T, R>

Let's look into our Sink first

class ChannelSink<T>(private val channel: Channel<T>, block:  (T) -> Unit) : CoroutineScope {
    private val job: Job = Job()
    override val coroutineContext: CoroutineContext
        get() = Dispatchers.Default + job
    init {
        launch {
            for(message in channel){
                block(message)
            }
        }
    }
}

Not too much going on here, our Sink reads messages from a channel (in a non blocking way using the launch builder). And then invokes the block function that would process the sink (invoke a rest endpoint, call a database, etc)

Our processor is a map style of function (T) -> (R)

class ChannelProcessor<T, R>(private val inputChannel: Channel<T>, block: (T) -> (R)) : CoroutineScope {
    private val job = Job()
    override val coroutineContext: CoroutineContext
        get() = Dispatchers.Default + job
    val outputChannel = Channel<R>()
    init {
        launch {
            for(message in inputChannel){
                outputChannel.send(block(message))
            }
        }
    }
}

Very similar to our Sink, but now we create an outputChannel that we write transformed messages using block(message)

And that's all the types we need. Now we need some plumbing code around our pipes [No pun intended]

Plumbing code (literally)

Ok so our "DSL" should be connecting the functions using channels as Pipes. So at the very beginning we said we want our sources to be Channels. So let's write two possible scenarios:

Source -> Processor
Source -> Sink

//Source -> Sink
infix fun <T> Channel<T>.into(block:  (T) -> Unit) : ChannelSink<T> {
    return ChannelSink(this, block)
}
//Source -> Processor
infix fun <T, R> Channel<T>.via(block: (T) -> R) : ChannelProcessor<T, R> {
    return ChannelProcessor(this, block)
}

our via/into functions pass the function receiver here (Channel) to the constructor of the ChannelSink/ChannelProcessor.

To daisy chain our processors now we need two extra functions:

infix fun <T, R> ChannelProcessor<T, R>.into(block: (R) -> Unit) : ChannelSink<R> {
    return ChannelSink(this.outputChannel, block)
}
infix fun <T, R, S> ChannelProcessor<T, R>.via( block: (R) -> S) : ChannelProcessor<R, S> {
    return ChannelProcessor(this.outputChannel, block)
}

Note that we daisy chain the channels by getting the outputChannel of a Processor and passing it as the inputChannel of the next Processor or the Sink.

Running it

First let's define some functions

//sink function
val fn: (Double) -> Unit = { i ->
   log("Received $i")
}
//first processor
val tn: (Int) -> (Int) = { i ->
       i * 2
}
//second processor
val tn2: (Int) -> Double = { i -> i * 3.0 }

Now let's get our producer channel ready

val source = Channel<Int>()
launch {
    with(source) {
        for (i in 0..size) {
            send(i)
        }
        close()
    }
}

And finally connect the pipes:

source via tn via tn2 into fn

And that's pretty much it, we can now use our channels with a pipes and filters syntax.

WAIT A MINUTE

Kotlin has support for Collection Streaming, why not just create a collection or a Sequence and use map and collect functions?

Looking at this code, you are absolutely right to spot that, and I'm truly sorry if I mad you read all that so far, but I wanted to make a point :)

Say we change our Processor and Sink code a little bit:

class ChannelProcessor<T, R>(private val inputChannel: Channel<T>, block: (T) -> (R)) : CoroutineScope {
    private val job = Job()
    override val coroutineContext: CoroutineContext
        get() = Dispatchers.Default + job
    val outputChannel = Channel<R>()
    init {
        launch {
            for(message in inputChannel){
                launch {  outputChannel.send(block(message)) }
            }
        }
    }
}

class ChannelSink<T>(private val channel: Channel<T>, block:  (T) -> Unit) : CoroutineScope {
    private val job: Job = Job()
    override val coroutineContext: CoroutineContext
        get() = Dispatchers.Default + job
    init {
        launch {
            for(message in channel){
                launch {
                    block(message)
                }
            }
        }
    }
}

Note that now, we launch a child coroutine for every function call, what this enables is that we could run all the steps in parallel.

Kotlin currently does not offer a standard way to run streams in parallel (unless you rely on java version). With this last change, the code runs concurrently. note this means sequencing of messages is affected.

To test this just try the updated code with this new scenario:

@ExperimentalCoroutinesApi
    @Test
    fun testAsyncProduce() {
        val size = 100
        val latch = CountDownLatch(size)
        runBlocking<Unit> {

            val source = Channel<Int>()
            launch {
                with(source) {
                    for (i in 0..size) {
                        send(i)
                    }
                    close()
                }
            }
            val fn: (Double) -> Unit = { i ->
                log("Received $i")
                latch.countDown()
            }
            val tn: (Int) -> (Int) = { i ->
                runBlocking {
                    if (i % 2 == 0) {
                        delay(10)
                    }
                    i * 2
                }
            }
            val tn2: (Int) -> Double = { i -> i * 3.0 }

            source via tn via tn2 into fn
        }
        latch.await()
    }

In this test, one of our functions will cause a delay on even numbers, but that will not cause a sequencial pause on the execution.

Those were just some thoughts I had while writing a code this week that had to deal with a simple pipeline and a sink to invoke a REST service. Put some of this in practice, but it's not to be taken as too serious.

Happy coding

Kotlin + Lego

Vinicius Carvalho — Wed, 20 Feb 2019 01:35:56 +0000

Introduction

One of my favorite hobbies is to build lego contraptions with my 6 year old. Specially using my mindstorm EV3 kit.

Over the last year we have been building robots using the standard EV3 studio on mac. But sometimes the bots get a bit too complex for block language.

I was used to write my bots in java, but since I made a promise to never write java and instead write kotlin code, I went and tried to setup an EV3 project using kotlin as the default language.

Goals

Create a maven based project (not dependent on a plugin to deploy)
Do not use eclipse (switched to intellij 5 years ago, never looked back)

Some background story

If you are here, I'm assuming you have already read how to install Lejos as well as how to configure your brick wifi.

And if you read the tutorials online, most of them point to the eclipse plugin and java projects, but those are two anti-goals of this post.

A warning on Java 8

The tutorials also refer to java7, and I tried to deploy using java8. Problem is that oracle no longer provide a jre8 for mindstorm, and you need to create your own using a tool called jrecreate. Creating it was actually easy, if you want to go that path, let me save you a few search minutes:

/jrecreate.sh --dest ejre8 --profile compact2 --vm client

Problem is, the lejos installer could not find my jre, no matter how hard I tried to rename it, repackage it, there seems to be an issue with how the tar.gz file is expected by the installer. So I just dropped it.

OpenSSL issues

Next on the list of issues. If you are running on a newer system you may bump into issues when trying to ssh into your brick, as the brick openssl server is using very old ciphers, so here's a combo that works fine to access it (again, saving you a few minutes of google search):

ssh -c aes256-cbc  -oKexAlgorithms=+diffie-hellman-group1-sha1 root@<brick-ip>

Preparing our project

Ok, so if you made this far, it seems that you are interested in getting an ev3 kotlin project.

An EV3 project its really just a regular maven project with one added library:

ev3classes.jar (located on your $EV3_HOME)

Of course, since we are talking about kotlin we will need the following libraries on our project too:

kotlin-stdlib
kotlin-stdlib-jdk7 (no JDK8 remember?)

Installing ev3classes.jar as a local maven dependency

In order to be able to use maven, and for you to be able to use the pom file of this tutorial as a template, first you need to install the ev3classes.jar as a maven dependency. Navigate to your $EV3_HOME/lib/ev3 and run the following command:

mvn install:install-file -Dfile=ev3classes.jar -DgroupId=lejos -DartifactId=ev3 -Dversion=0.9.1-beta -Dpackaging=ja

To package or not to package

Now, if you want to create a fat jar using maven application plugin, it's one way to go, but I really gave up on that idea. The brick is connected via bluetooth, and transferring a 2-3mb jar file is pretty annoying when you are deploying it multiple times, my projects are usually < 10kb in size when accounting just the project classes so here's what I've done.

I've copied all the base libraries (kotlin-stdlib, kotlin-stdlib-jdk7, ev3classes.jar) to my brick on the following location: /home/root/lejos/lib
Modified the maven-jar plugin to set the Class-Path of my project to refer those files
Built a slim file instead

If you are concerned about portability, self contained code, and all those beautiful things that you should care when working on a team or scalable project, it's your call, but to me, sub second scp beats all that :)

The pom.xml file

If you are ok with these trade-offs in portability, then this is the pom file you could use as a template for your next project. A few things to note:

Copy the libs to the brick folder, IMPORTANT
Make sure you update your BRICK_IP property
Don't forget to set the name of the main class: MAIN_CLASS
Set your own groupId/artifactId
Take note of the maven coordinates for ev3classes if you installed using different ones, update the section.
Remember you need to target 1.7 source code (maven compiler plugin only works on java 8, so set your project sdk to 8, but your target to 1.7)
Kotlin jvm target is only 1.6 or 1.8, make sure it's 1.6
Take a look on the ant-run section, it adds a package phase that after packaging your project it scp it to the brick.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>
    <properties>
        <kotlin.version>1.3.21</kotlin.version>
        <main.class>MAIN_CLASS</main.class>
        <ev3.lib>/home/root/lejos/lib</ev3.lib>
        <brick.host>BRICK_IP</brick.host>
        <brick.home>/home/root</brick.home>
        <brick.user>root</brick.user>
        <brick.debug.port>4000</brick.debug.port>
    </properties>
    <groupId>YOUR_GROUP_ID</groupId>
    <artifactId>YOUR_ARTIFACT_ID</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-stdlib-jdk7</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>lejos</groupId>
            <artifactId>ev3</artifactId>
            <version>0.9.1-beta</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-test</artifactId>
            <version>${kotlin.version}</version>
            <scope>test</scope>
        </dependency>

    </dependencies>


    <build>
        <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <source>1.7</source>
                    <target>1.7</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.jetbrains.kotlin</groupId>
                <artifactId>kotlin-maven-plugin</artifactId>
                <version>${kotlin.version}</version>
                <executions>
                    <execution>
                        <id>compile</id>
                        <phase>compile</phase>
                        <goals> <goal>compile</goal> </goals>
                        <configuration>
                            <sourceDirs>
                                <source>src/main/java</source>
                                <source>src/main/kotlin</source>
                            </sourceDirs>
                        </configuration>
                    </execution>
                    <execution>
                        <id>test-compile</id>
                        <phase>test-compile</phase>
                        <goals> <goal>test-compile</goal> </goals>
                    </execution>
                </executions>
                <configuration>
                    <jvmTarget>1.6</jvmTarget>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>2.6</version>
                <configuration>
                    <archive>
                        <manifestEntries>
                            <Class-Path>${ev3.lib}/ev3classes.jar ${ev3.lib}/kotlin-stdlib-jdk7.jar ${ev3.lib}/kotlin-stdlib.jar</Class-Path>
                        </manifestEntries>
                        <manifest>
                            <addClasspath>false</addClasspath>
                            <mainClass>${main.class}</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <version>1.8</version>
                <executions>
                    <execution>
                        <id>scp-to-remote</id>
                        <phase>package</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <target>
                                <scp localFile="${project.basedir}/target/${project.build.finalName}.jar"
                                     username="${brick.user}" verbose="true" remoteToFile="${brick.user}@${brick.host}:/home/lejos/programs/"
                                     password="" trust="true">
                                </scp>
                            </target>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>com.jcraft</groupId>
                        <artifactId>jsch</artifactId>
                        <version>0.1.53</version>
                    </dependency>
                    <dependency>
                        <groupId>ant</groupId>
                        <artifactId>ant-jsch</artifactId>
                        <version>1.6.5</version>
                    </dependency>
                </dependencies>
            </plugin>
        </plugins>
    </build>

</project>

Running it

If you run mvn package on the project it will build, set the right class-path and copy your file to the brick's program folder. You can now use the brick menu to select your program and execute it.

Hope this helps folks bashing their heads on getting a maven project setup for EV3.

Happy coding!