Javalin 1.0.0 stable is ready! - Javalin: Simple REST APIs for Java and Kotlin

Introducing Javalin

Javalin is a very lightweight web framework for Kotlin and Java, inspired by Sparkjava and koa.js. Javalin is written in Kotlin with a few functional interfaces written in Java. This was necessary to provide an enjoyable and near identical experience for both Kotlin and Java developers.

Javalin is really more library than framework; you don’t need to extend or implement anything and there are very few “Javalin-concepts” you have to learn. Let’s look at some examples:

Hello World

fun main(args: Array<String>) {
    val app = Javalin.start(7000)
    app.get("/") { ctx -> ctx.result("Hello World") }
}

API structure and server config

val app = Javalin.create().apply {
    enableStaticFiles("/public")
    enableStandardRequestLogging()
    port(port)
}.start()

app.routes {
    path("users") {
        get(UserController::getAllUserIds)
        post(UserController::createUser)
        path(":user-id") {
            get(UserController::getUser)
            patch(UserController::updateUser)
            delete(UserController::deleteUser)
        }
    }
}

Filters and mappers

app.before("/some-path/*") { ctx ->  ... } // runs before requests to /some-path/*
app.before { ctx -> ... } // runs before all requests
app.after { ctx -> ... } // runs after all requests
app.exception(Exception.class) { e, ctx -> ... } // runs if uncaught Exception
app.error(404) { ctx -> ... } // runs if status is 404 (after all other handlers)

WebSockets

app.ws("/websocket") { ws ->
    ws.onConnect { session -> println("Connected") }
    ws.onMessage { session, message ->
        println("Received: " + message)
        session.remote.sendString("Echo: " + message)
    }
    ws.onClose { session, statusCode, reason -> println("Closed") }
    ws.onError { session, throwable -> println("Errored") }
}

Object mapping

var todos = arrayOf(...)
app.get("/todos") { ctx -> // map array of Todos to json-string
    ctx.json(todos)
}
app.put("/todos") { ctx -> // map request-body (json) to array of Todos
    todos = ctx.bodyAsClass(Array<Todo>::class.java)
    ctx.status(204)
}

Uploads

app.post("/upload") { ctx ->
    ctx.uploadedFiles("files").forEach { (contentType, content, name, extension) ->
        FileUtils.copyInputStreamToFile(content, File("upload/" + name))
    }
}

Kotlin and Java interoperability

The interoperability between Kotlin and Java is very important to Javalin. When moving a Javalin project from Java to Kotlin, you shouldn’t need to learn a new way of doing things. In the above examples you can switch between Kotlin and Java and see that everything is more or less the same, except for a few parens and semicolons. To maintain this consistent API for both languages is an important goal of the project.

Main features

• Lightweight - You don’t have to learn any advanced concepts to get started
• Consistent API - All handlers and mappers are void and operate on the Context (ctx)
• Almost identical API for both Kotlin and Java
• Not opinionated - A library rather than a framework (you never have to extend anything)
• Fully customizable embedded server (Jetty)
• JSON-object-mapping (via Jackson)
• Simple per-endpoint auth via AccessManager interface
• Simple static file handling
• Lifecycle events
• CookieStore - An easy way to serialize and store objects in cookies
• Template rendering (Velocity, Freemarker, Thymeleaf, Mustache)
• Markdown rendering

Get involved

If you want to contribute to the project, head on over to GitHub.

No breaking changes since 0.5.0

If you’re currently using a 0.5.X version of Javalin, upgrading to 1.0.0 should not break anything.