Note: this article is based on my Complete Kotlin Course lesson, which I highly encourage you to check out if you are looking for a comprehensive Kotlin guide.

If this is your first meeting with DSLs, then I would recommend you to check out my other article, in which I explain and show how to implement Kotlin DSL step-by-step.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

Uncontrolled Scope

But before we dive into the solution with Kotlin @DslMarker, let’s understand what problem it solves first.

So as the first step, let’s prepare a simple DSL with Board, Task, Author, and Comment classes:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  val tasks: MutableList<Task> = mutableListOf()

  fun task(init: Task.() -> Unit) {
    val task = Task().apply(init)
    tasks.add(task)
  }
}

class Task {
  var title: String = ""
  var description: String = ""
  val comments: MutableList<Comment> = mutableListOf()

  fun comment(init: Comment.() -> Unit) {
    val comment = Comment().apply(init)
    comments.add(comment)
  }
}

class Comment {
  var comment: String = ""
  var author: Author = Author()

  fun author(init: Author.() -> Unit) {
    val author = Author().apply(init)
    this.author = author
  }
}

class Author {
  var name: String = ""
}

fun board(init: Board.() -> Unit): Board =
  Board()
    .apply(init)

With the following Kotlin DSL implementation, we would expect that we could introduce different Boards, with Tasks inside them, which would have some Comments written by Authors.

But let’s take a look at the following code:

fun main() {
  val board = board {
    task {
      task {
        task {
          comment {
            task { }
            author {
              task { }
              comment {
                task { }
              }
            }
          }
        }
      }
    }
  }
}

Will it compile? Unfortunately, yes.

We invoke a task within a task, within a task, and so on. Moreover, we can invoke the task, or comment functions inside the author. 

And that’s because, by default, we can call the methods of every available receiver, which can lead to such situations. 

Kotlin @DslMarker To The Rescue

At this point, we already know what the issue is and what we will use to fix it.

But what exactly does the @DslMarker do in Kotlin?

Well, in practice, we use this annotation to introduce our new custom annotations. Then, we make use of them to mark classes and receivers, thus preventing receivers marked with the same annotation from being accessed inside one another.

This way, we won’t be able to access members of the outer receiver (like the task function, which is declared inside the Board class from the Task class instances).

Let’s consider the updated example:

@DslMarker
annotation class BoardDsl

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

@BoardDsl
class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  val tasks: MutableList<Task> = mutableListOf()

  fun task(init: Task.() -> Unit) {
    val task = Task().apply(init)
    tasks.add(task)
  }
}

@BoardDsl
class Task {
  var title: String = ""
  var description: String = ""
  val comments: MutableList<Comment> = mutableListOf()

  fun comment(init: Comment.() -> Unit) {
    val comment = Comment().apply(init)
    comments.add(comment)
  }
}

@BoardDsl
class Comment {
  var comment: String = ""
  var author: Author = Author()

  fun author(init: Author.() -> Unit) {
    val author = Author().apply(init)
    this.author = author
  }
}

@BoardDsl
class Author {
  var name: String = ""
}

fun board(init: Board.() -> Unit): Board =
  Board()
    .apply(init)

fun main() {
  val board = board {
    task {  // OK
      task {  // Does not compile
        task {  // Does not compile
          comment {  // OK
            task { }  // Does not compile
            author {  // OK
              task { }  // Does not compile
              comment {  // Does not compile
                task { }  // Does not compile
              }
            }
          }
        }
      }
    }
  }
}

Firstly, we introduce the @BoardDsl annotation, which uses the @DslMarker.

Following, we must annotate every class in our hierarchy with our new annotation- this way, we make the Kotlin compiler “aware” of the hierarchy in our DSL.

Lastly, we can clearly see that the code will not compile whenever we try to nest the unwanted type inside another.

Scope Control With Kotlin @DslMarker Summary

Basically, that’s all for this tutorial on how to control scope when implementing a Kotlin DSL using the @DslMarker summary.

If you enjoy such a short, practice-focused learning approach then do not forget to check out my course and let me know in the comments section.

If you’d like to learn a bit more about the annotation itself, then the documentation may be useful to you too.

The post Scope Control With @DslMarker Annotation. Kotlin DSLs. appeared first on Codersee blog- Kotlin on the backend.

Hi! 🙂 In this publication, we will learn how to implement statically-typed, type-safe Kotlin builders which we can use to implement our own DSLs.

Firstly, we will discuss what exactly DSLs are, their benefits, and why Kotlin is a good choice for creating them. Then, we will learn more about function literals with a receiver. And finally, we will put together all this knowledge and implement our own DSL.

Note: This article has been created based on my course Kotlin Handbook. Learn Through Practice. If you are looking for high-quality, step-by-step Kotlin learning path, then you should definitely check it out.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

2. What is a DSL?

A DSL is an acronym for Domain-Specific Language.

It’s nothing else than a specialized language designed to solve problems or tasks within a specific domain.

Unlike general-purpose languages (like Kotlin itself), which are designed for a wide range of applications, DSLs focus on easy-to-understand syntax tailored to a particular problem domain.

Great examples can be:

• HTML for creating web pages,
• Gradle for building automation,
• or SQL for querying databases.

3. The Purpose and Benefits of DSLs

The main purpose of DSLs is to help programmers to deal with complex hierarchical data structures in an easy way. 

So, a well-designed domain-specific language provides (among others) the following benefits: 

• expressiveness– helps us to express complex ideas and logic using a more concise and natural syntax,
• readability– the code we produce is simply easier to read and understand, 
• maintainability– a modular, and organized code structure makes it easier to maintain and extend our programs. 

4. Is Kotlin a Good Choice For DSLs?

Short answer- yes. 

Kotlin is designed to be a concise, readable, and expressive programming language. When we combine together properly named functions and function literals with receiver, we can implement truly type-safe Kotlin builders.

Additionally, lambda expressions, scoping literals, extension, or infix functions help us to organize everything in an even cleaner way.

If you are looking for real-life usage examples, then we can find type-safe builders for example, when configuring routes in Ktor, or in Gradle’s Kotlin DSL.

5. Function Literals with Receiver

With all of that being said, let’s start the practice part by explaining the concept of function literals with receiver.

In simple words, it is nothing else than a combination of lambda expression:

val hello: (String) -> String = { name -> "Hello, $name" }

fun main() {
  val greeting = hello("Pjoter")
  
  println(greeting)  // Hello, Pjoter
}

And extension function:

fun String.hello() : String = "Hello, $this"

fun main() {
  val greeting = "Pjoter".hello()
  
  println(greeting)  // Hello, Pjoter
}

Which combined together form:

val hello: String.() -> String = { "Hello, $this" }

fun main() {
  val greeting = "Pjoter".hello()
  
  println(greeting)  // Hello, Pjoter
}

In our example, the String object, for which we invoke the function is a receiver and it implicitly becomes this inside the function. This way, we can access all its members, like public fields, inside our function (even without this keyword).

Great, but how does this relate to creating DSLs in Kotlin?

Well, we can pass function literals with receiver as arguments to high-order functions (functions that take other functions as parameters).

I know, a mumbo jumbo, but everything will become clear by the end of this tutorial 😉

6. Implement Custom Kotlin DSL

6.1 Add High-Order Function

As the first step, let’s take a look at the example class:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
}

fun main() {
  val board = Board()
  board.title = "Important Tasks"
  board.color = BoardColor.GREEN
}

Nothing spectacular, right? Just a simple class with mutable properties.

So as the next step, let’s add a higher-order function, which expects the function literal with a receiver as an argument:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
}

fun board(init: Board.() -> Unit): Board {
  val board = Board()
  board.init()
  return board
}

fun main() {
  val board = board {
    title = "Important Tasks"
    color = BoardColor.GREEN
  }
}

The board function is pretty straightforward- firstly, we create a new Board instance, and then we invoke the init function on it. After that, we return the updated object instance.

When we look at the main function, we can see that the only thing we do is the board function invocation.

But there is no parenthesis- “()”- right?

Well, technically we could use them: board ( {/*some code*/ } ). But in Kotlin, when the last parameter of a function is a function, then a lambda expression passed as the corresponding argument can be placed outside the parentheses (docs). In our case- the function has only one parameter, so we don’t need parenthesis, at all.

6.2 Kotlin Type-Safe Builder

And although at this point our logic looks like overkill, life isn’t always that easy and we may need to add more hierarchy to our code.

Let’s consider the following code snippet:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Task {
  var title: String = ""
  var description: String = ""
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  var tasks: MutableList<Task> = mutableListOf()
}

fun main() {
  val taskOne = Task() 
  taskOne.title = "Task 1"
  taskOne.description = "Task 1 description"  
  
  val taskTwo = Task() 
  taskTwo.title = "Task 2"
  taskTwo.description = "Task 2 description"   
  
  val tasks = mutableListOf(taskOne, taskTwo)  
    
  val board = Board() 
  board.title = "Important Tasks"
  board.color = BoardColor.GREEN
  board.tasks = tasks	  
}

In this case, every Board object can contain multiple Tasks instances.

When we look at the main function, it’s pretty hard to see the hierarchy of objects at first glance.

And now, let’s analyze the Kotlin type-safe builder approach:

enum class BoardColor {
  BLACK, WHITE, GREEN, BLUE
}

class Task {
  var title: String = ""
  var description: String = ""
}

class Board {
  var title: String = ""
  var color: BoardColor = BoardColor.BLUE
  var tasks: MutableList<Task> = mutableListOf()
  
  fun task(init: Task.() -> Unit) {
    val task = Task()
    task.init()
    tasks.add(task)
  }
}

fun board(init: Board.() -> Unit): Board {
  val board = Board()
  board.init()
  return board
}

fun main() {
   val board = board {
     title = "Important Tasks"
     color = BoardColor.GREEN
    
     task {
       title = "Task 1"
       description = "Task 1 description"  
     }
    
     task {
       title = "Task 2"
       description = "Task 2 description" 
     }
  }  
}

We brought back the board function and implemented a new task method inside the Board.

When we implement our lambda inside the main function, we can access the task function, just like we access the title, or color property of the Board object.

To better visualize, let’s use the explicit this and parenthesis:

val board = board {
  this.title = "Important Tasks"
  this.color = BoardColor.GREEN
    
  this.task( {
    this.title = "Task 1"
    this.description = "Task 1 description"  
  } )
    
  this.task( {
    this.title = "Task 2"
    this.description = "Task 2 description" 
  } )
}  

To rephrase- the object, for which we invoke the function is a receiver and it implicitly becomes this inside the function.

So, our board function first creates a new object and then invokes passed lambda on it- which sets the title, color and invokes the task method twice.

On the other hand, the task function also creates a new, “plain” object and also invokes passed lambda on it- this time, setting the title and description values for it.

And basically, we’ve just created our first, simple Kotlin type-safe builder 🙂

7. Summary

In this article, we’ve learned not only how to create our custom Kotlin DSL, but also the key features which make this possible.

Of course, this is just an introduction, and if you are interested in learning more, for example about scope control, then let me know in the comments section 🙂

The post Kotlin Type-Safe Builders Explained. Implement Your Own DSL. appeared first on Codersee blog- Kotlin on the backend.

Hello ! 🙂 Continuing the DSL topic, I would like to show you how to expose a REST API using Spring Boot 3, Kotlin, bean definition, and router DSL.

In my previous article, I showed you how the router DSL works and how to expose endpoints manually without needing any web-related annotations, like @RequestMapping, @RestController, @RequestBody, etc…

But is it possible to eliminate the annotations when defining beans? Yes, and in this article, I will prove to you that it’s possible to expose a REST API without any annotations, like @Component or any specialization.

Video Tutorial

If you prefer video content, then check out my video:

If you find this content useful, please leave a subscription  😉

2. Project Setup

Firstly, let’s navigate to https://start.spring.io/ and generate a new project:

As we can see, in order to expose a REST API with Spring Boot 3 and Kotlin DSL, we don’t have to add any additional dependencies. The only one is the Spring Web, which lets us build web applications.

Following, please import the project to your favorite IDE (like IntelliJ).

3. Add Models

Nextly, let’s create the model package and add 3 data classes to our application:

• User, which will transfer the data between the app and the data source,
• UserDTO, which will be serialized to JSON responses,
• and ErrorResponse, shipping information about backend errors.

// User.kt
data class User(
  val id: Long? = null,
  val email: String,
  val name: String,
  val age: Int
)

// UserDTO.kt
data class UserDTO(
  val email: String,
  val name: String,
  val age: Int
)

// ErrorResponse.kt
data class ErrorResponse(
  val message: String
)

4. Implement a Repository

As the next step, let’s create a repository package.

[elementor-template id=”9007393″]

4.1 Add UserRepository Interface

Following, let’s introduce a UserRepository:

interface UserRepository {
  fun create(user: User): User
  fun findAll(): List<User>
  fun findById(id: Long): User?
  fun updateById(id: Long, user: User): User?
  fun deleteById(id: Long)
}

And although oftentimes I skip this part for the simplicity of my tutorials, you will later see that working with interfaces, rather than implementations gives us much more flexibility. And in real-life scenarios, we should consider using them.

4.2 Add Implementation

So nextly, let’s add the UserCrudRepository to the codebase:

class UserCrudRepository(
  private val dataSource: MutableMap<Long, User>
) : UserRepository {

  override fun create(user: User): User {
    val lastId = this.dataSource.keys.max()
    val incrementedId = lastId + 1
    val updatedUser = user.copy(id = incrementedId)

    this.dataSource[incrementedId] = updatedUser

    return updatedUser
  }

  override fun findAll(): List<User> =
    this.dataSource.values
      .toList()

  override fun findById(id: Long): User? =
    this.dataSource[id]

  override fun updateById(id: Long, user: User): User? =
    this.dataSource[id]
      ?.let { foundUser -> 
        val updatedUser = user.copy(id = foundUser.id)
        this.dataSource[id] = updatedUser
        updatedUser
      }

  override fun deleteById(id: Long) {
    this.dataSource.remove(id)
  }
}

As we can see, this class is just a dummy in-memory database, which will be operating on the dataSource map provided as a constructor argument.

4.3 Implement DataSource

With that being done, let’s create a new object called DataSource (can go to the config package):

object DataSource {

  val devDataSource: MutableMap<Long, User> = mutableMapOf(
    1L to User(1L, "email-1@gmail.com", "Name 1", 22),
    2L to User(2L, "email-2@gmail.com", "Name 2", 43),
    3L to User(3L, "email-3@gmail.com", "Name 3", 26),
    4L to User(4L, "email-4@gmail.com", "Name 4", 50)
  )

  val prodDataSource: MutableMap<Long, User> = mutableMapOf(
    1L to User(1L, "prod-email-1@gmail.com", "Name 1", 22),
    2L to User(2L, "prod-email-2@gmail.com", "Name 2", 43),
    3L to User(3L, "prod-email-3@gmail.com", "Name 3", 26),
    4L to User(4L, "prod-email-4@gmail.com", "Name 4", 50)
  )

}

Well, in our application we will be dealing with dummy data.

However, in real life instead of two maps implementations, we would rather have a few implementations of UserRepository, for example:

• one, in-memory, which could be used for local development and testing,
• the second, “real”, one, responsible for database connection.

Either way, the purpose of this tutorial is to learn a bit more about Kotlin with bean definition DSL, and this setup will be useful in our considerations.

5. Configure Routing

In order to expose REST endpoints with Kotlin route DSL, we need to add two things:

• UserHandler– which normally would be a UserController when working with annotations,
• custom RouteFunctionDSL– responsible for URL mappings.

5.1 Add UserHandler

Firstly, let’s add a handler package and implement the UserHandler:

class UserHandler(
  private val userRepository: UserRepository
) {

  fun createUser(
    request: ServerRequest
  ): ServerResponse {
    val userRequest = request.body(UserDTO::class.java)

    val createdUserResponse = userRepository.create(
      user = userRequest.toModel()
    )
      .toDTO()

    return ServerResponse.ok()
      .body(createdUserResponse)
  }

  fun findAllUsers(
    request: ServerRequest
  ): ServerResponse {
    val usersResponses = userRepository.findAll()
      .map(User::toDTO)

    return ServerResponse.ok()
      .body(usersResponses)
  }

  fun findUserById(
    request: ServerRequest
  ): ServerResponse {
    val id = request.pathVariable("id")
      .toLongOrNull()
      ?: return badRequestResponse("Invalid id")

    val userResponse = userRepository.findById(id)
      ?.toDTO()

    return userResponse
      ?.let { response ->
        ServerResponse.ok()
          .body(response)
      }
      ?: notFoundResponse(id)
  }

  fun updateUserById(
    request: ServerRequest
  ): ServerResponse {
    val id = request.pathVariable("id")
      .toLongOrNull()
      ?: return badRequestResponse("Invalid id")

    val userRequest = request.body(UserDTO::class.java)

    val updatedUser = userRepository.updateById(
      id = id,
      user = userRequest.toModel()
    )

    return updatedUser
      ?.let { response ->
        ServerResponse.ok()
          .body(response)
      }
      ?: notFoundResponse(id)
  }

  fun deleteUserById(
    request: ServerRequest
  ): ServerResponse {
    val id = request.pathVariable("id")
      .toLongOrNull()
      ?: return badRequestResponse("Invalid id")

    userRepository.deleteById(id)

    return ServerResponse.noContent()
      .build()
  }

  private fun badRequestResponse(reason: String): ServerResponse =
    ServerResponse.badRequest()
      .body(
        ErrorResponse(reason)
      )

  private fun notFoundResponse(id: Long): ServerResponse =
    ServerResponse.badRequest()
      .body(
        ErrorResponse("User with id: $id was not found.")
      )

}

private fun UserDTO.toModel(): User =
  User(
    email = this.email,
    name = this.name,
    age = this.age
  )

private fun User.toDTO(): UserDTO =
  UserDTO(
    email = this.email,
    name = this.name,
    age = this.age
  )

As we can see, the handler has only one parameter of the UserRepository  type. Thanks do that, we are not coupled with any implementation. Moreover, we gained flexibility and we can provide the implementation even on the fly when configuring beans.

Another interesting thing is the usage of ServerRequests and ServerResponses. When working with Spring Boot and Kotlin routes DSL, that’s how we deal with incoming requests and responses. And although for more details I redirect you to my previous article about this topic, I wanted to mention this because of one thing. As you can see- instead of throwing exceptions, which then Spring would translate to HTTP responses, we have the possibility to return our custom payload (and status codes, as well).

5.2 Implement Routing

Nevertheless, handler implementation is not sufficient. We have to instruct Spring about how HTTP requests should be handled.

To do so, let’s add the Routes.kt file inside the config package:

fun appRouter(userHandler: UserHandler) = router {
  "/api".nest {
    "/users".nest {
      POST(userHandler::createUser)
      GET(userHandler::findAllUsers)
      GET("/{id}", userHandler::findUserById)
      PUT("/{id}", userHandler::updateUserById)
      DELETE("/{id}", userHandler::deleteUserById)
    }
  }
}

The appRouter function has one parameter of the UserHandler type, which we then use to provide references to functions inside it.

It’s worth mentioning that function references in Kotlin are an interesting syntactic sugar. However, if you prefer not to use them, you can always simply make use of brackets:

POST { request -> userHandler.createUser(request) }

6. Kotlin Bean Definition DSL

With all of that being done, we can finally learn how the Kotlin bean definition DSL work with Spring Boot 3.

6.1 Implement BeansConfig

Firstly, let’s add a new file called BeansConfig.kt inside the config package:

val beans = beans {
  // beans definitions
}

The beans {} is nothing else than a function, which leverages the concept of type-safe builders.

Secondly, let’s add the BeansConfig class:

class BeansConfig : ApplicationContextInitializer<GenericApplicationContext> {

  override fun initialize(context: GenericApplicationContext) =
    beans.initialize(context)

}

In order to register the beans in our application context, we have to invoke the initialize().

Lastly, we need to make Spring aware of our initializer in application.yaml:

context:
  initializer:
    classes: com.codersee.kotlindsl.config.BeansConfig

6.2 Autowiring By Type

As the next step, let’s see how we can define UserHandler and router beans and instruct Spring to autowire by type:

bean<UserHandler>()
bean(::appRouter)

As we can see, we don’t even have to specify the types of particular parameters and Spring will take care of that automatically.

Moreover, with callable reference, we can define a bean with the appRouter top-level function.

6.3 Explicitly Specify Bean Type

Of course, if we would like to specify the type of the bean manually or wire by name, then we can do it, as well:

bean("myHandlerBean") {
  UserHandler(ref())
}
bean {
  appRouter(
    ref("myHandlerBean")
  )
}

And this time we simply make use of the ref function, which is responsible for getting a reference to beans by type (line 2), or by type and name (line 6).

6.4 Conditional Beans Based On Profile

Following, let’s see how we can differentiate the data source based on the profile property:

profile("dev") {
  bean {
    UserCrudRepository(devDataSource)
  }
}

profile("prod") {
  bean {
    UserCrudRepository(prodDataSource)
  }
}

With this approach, beans defined inside the profile() won’t be created unless the specified profile is active.

Of course, we can activate profiles, for example inside the application.yaml:

spring:
  profiles:
    active: dev

6.5 Define Additional Beans Properties

Following, let’s see how we can customize bean definitions:

bean(
  name = "userHandler",
  scope = BeanDefinitionDsl.Scope.SINGLETON,
  isLazyInit = true,
  isPrimary = true,
  isAutowireCandidate = true,
  initMethodName = "",
  destroyMethodName = "",
  description = "description",
  role = BeanDefinitionDsl.Role.APPLICATION
)

As we can see, all parameters of the bean function have default values assigned.

Nevertheless, if we would like to set any values explicitly, then we can do it with ease.

6.6 Reading Environment Variables

As the last thing, let’s see how we can read environment variables:

val someVariable = env.systemEnvironment["SOME_VARIABLE"]

The systemEnvironment is nothing else than a Map<String, Object> instance, which is a result of System.getenv() invocation.

7. Spring Boot 3 Kotlin DSL Summary

And that’s all for this tutorial about how to implement a REST API without annotations using Spring Boot 3, Kotlin bean definition, and router DSL.

I’m happy to hear your feedback– trust me, such a simple comment can motivate a lot and help me to work on my weaknesses 🙂

Of course, if you would like to see the source code for this article, then you can find it in this GitHub repository.

The post Spring Boot 3 With Kotlin DSL. REST API Without Annotations appeared first on Codersee blog- Kotlin on the backend.