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.

Sooner or later, every developer will have to implement email-sending functionality in their application and it’s worth checking out various solutions, to pick the one that will best meet our needs.

And although the term “transactional emails” sounds complicated, in this tutorial I will prove how easily we can use them with Ktor and Kotlin.

Video Tutorial

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

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

Prerequisites

Before we start, let’s see what exactly we will need for this tutorial.

First of all, we will need a MailerSend account. The free version will be fair enough for the purpose of learning and even simple projects.

Note: the above link is a referral and if you will purchase any paid plan, I’ll get a small commission for that. To be clear: this fact affects the merits of this article in no way 🙂

Additionally, you will need to have a domain, which you can verify. This is necessary, in order to work with any transactional email providers.

Configure Domain in MailerSend

I won’t go into much detail in this paragraph, because DNS settings will be dependent on your domain registrar. Nevertheless, let’s take look at how to add a new domain to MailerSend.

So, assuming we created our account and verified the email along with their policies, we should see the following:

As the next step, let’s click the Start button next to the “Add a sending domain”:

Right here, let’s specify the domain name- test.codersee.com in my case- and confirm with the Add domain button.

Nextly, we should see the Domain verification modal:

As we can see, in order to verify our domain, we need to navigate to our domain registrar and modify the DNS settings using the values specified in the modal. When it’s done, let’s click the Check/Re-check now button.

Note: DNS propagation can take some time, so don’t worry if you see the error messages (just like above). In such a case, give it some time and please get back to this page. MailerSend will send you an e-mail when everything is verified, as well.

If everything succeeded, we should see the following page:

One important note before we head to the next part. At this point, we will be able to send emails only to addresses and domains we previously verified– the e-mail address we use for registration and all addresses in a verified domain in our case.

Nevertheless, if you would like to send emails outside the domain, you will need to get approval.

Generate API Key

In order to send transactional emails with MailerSend in our Ktor app, we will need to generate a new API key.

To do so, let’s navigate to our domains (Email -> Domains in the left sidebar) and click the manage button:

On this page, we can manage API tokens and configure plenty of other things, like webhooks or tracking.

Anyway, let’s click the Generate new token button:

As we can see, right here we can specify the name and access granted to the new token. And although for simplicity we will stick with “Full access”, in real-life scenarios we should always follow the principle of least privilege.

Finally, let’s click the Create token:

As can be seen, the API token was created successfully and it’s time to save the value.

Note: please persist this value securely and never share it with anyone!

Generate Ktor Project

With all of that being done in MailerSend, we can finally switch to the Ktor & Kotlin part of our tutorial about transactional emails.

As always, let’s navigate to https://start.ktor.io/ and specify desired project settings:

Following, let’s click the Add plugins (we don’t need anything else), generate the project, and import it to our IDE.

Nextly, let’s add the Ktor client and Jackson dependencies inside the build.gradle.kts:

implementation("io.ktor:ktor-client-core-jvm:$ktor_version")
implementation("io.ktor:ktor-client-okhttp:$ktor_version")

implementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
implementation("io.ktor:ktor-serialization-jackson:$ktor_version")

Of course, Jackson is not the only option here, and GSON, or kotlinx.serialization are well supported in Ktor, as well.

Configure Client

As the next step, let’s navigate to the application.conf file and add a custom MailerSend config:

mailersend {
  token = ${MAILERSEND_TOKEN}
  baseUrl = ${MAILERSEND_BASE_URL}
}

This way, we can pass the token and URL values securely through environment variables. And although the token will be unique, for the baseUrl, let’s set https://api.mailersend.com/v1/.

Nextly, let’s create the MailerSendClient.kt file and put the following:

fun Application.configureClient() {

  val token = environment.config.property("mailersend.token").getString()
  val baseUrl = environment.config.property("mailersend.baseUrl").getString()

  val mailerSendClient = HttpClient {
    install(ContentNegotiation) {
      jackson()
    }
  }

  runBlocking {
    // To be done in the next paragraphs
  }
}

As we can see, the above function reads configuration properties and installs the ContentNegotiation plugin using Jackson. Moreover, we’ve prepared the runBlocking block, where we will invoke our future functions.

Lastly, let’s navigate to the Application.kt file and make use of our config:

fun Application.module() {
  configureClient()
}

At this point, we can run our application and verify that it is working, as expected. If we forget to set environment variables correctly, we should see something like this:

Exception in thread “main” com.typesafe.config.ConfigException $ UnresolvedSubstitution: application.conf @ […] Could not resolve substitution to a value: ${MAILERSEND_BASE_URL}

Send Simple Email

With all of that done, we can finally start sending transactional emails. In this paragraph, we will learn how to send a simple email with MailerSend.

Implement EmailRequest

As the first step, let’s create a new data class called EmailRequest:

@JsonInclude(JsonInclude.Include.NON_NULL)
data class EmailRequest(
    val from: Recipient,
    val to: List<Recipient>,
    val subject: String,
    val text: String,
    val html: String,
    val variables: List<Variable>? = null
) {
    data class Recipient(
        val email: String,
        val name: String
    )

    data class Variable(
        val email: String,
        val substitutions: List<Substitution>
    ) {
        data class Substitution(
            @JsonProperty("var") val variable: String,
            val value: String
        )
    }
}

Basically, objects of this class will be serialized into JSONs when querying MailerSend API.

The @JsonInclude annotation states that if the value is set to null, then it should not be added to the JSON payload (so we won’t send "whatever": null) . Additionally, MailerSend requires us to send the “var” field inside the substitution. Nevertheless, var is a reserved keyword in Kotlin, so we have to make use of the @JsonProperty.

Use Ktor Client to Perform Requests

Following, let’s add a new function called sendSingleEmail:

suspend fun sendSingleEmail(
  mailerSendClient: HttpClient,
  url: String,
  token: String,
  emailRequest: EmailRequest
): HttpResponse =
    mailerSendClient.post(url) {
      headers {
        append(HttpHeaders.Authorization, "Bearer $token")
      }
      contentType(ContentType.Application.Json)
      setBody(emailRequest)
    }

As we can see, this one is responsible for sending POST requests to the passed URL with the Authorization header containing the Bearer token.

Moreover, the function takes the EmailRequest as an argument, which makes it reusable.

Send Transactional Client with Ktor Client

Lastly, let’s implement the sendSimpleMessage:

suspend fun sendSimpleMessage(
    mailerSendClient: HttpClient,
    baseUrl: String,
    token: String
) {
    val subject = "Hello from {\$company}!"
    val html = """
        Hello <b>{${'$'}name}</b>, nice to meet you!
    """.trimIndent()
    val text = """
        Hello {${'$'}name}, nice to meet you!
    """.trimIndent()

    val emailRequest = EmailRequest(
        from = EmailRequest.Recipient(
            email = "example@test.codersee.com",
            name = "Codersee"
        ),
        to = listOf(
            EmailRequest.Recipient(
                email = "example@test.codersee.com",
                name = "Pjoter"
            )
        ),
        subject = subject,
        html = html,
        text = text,
        variables = listOf(
            EmailRequest.Variable(
                email = "example@test.codersee.com",
                substitutions = listOf(
                    EmailRequest.Variable.Substitution(
                        variable = "company",
                        value = "Codersee"
                    ),
                    EmailRequest.Variable.Substitution(
                        variable = "name",
                        value = "Piotr"
                    )
                )
            )
        )
    )

    val response = sendSingleEmail(
        mailerSendClient = mailerSendClient,
        url = "$baseUrl/email",
        token = token,
        emailRequest = emailRequest
    )

    if (response.status == HttpStatusCode.Accepted)
        println("Email sent successfully.")
    else
        println("Error when sending email.")
}

And although the above code snippet consists of a lot of lines, it’s definitely easier than it looks.

Firstly, we prepare the EmailRequest instance, which after serialization, will become this JSON:

{
    "from": {
        "email": "example@test.codersee.com",
        "name": "Codersee"
    },
    "to": [
        {
            "email": "example@test.codersee.com",
            "name": "Pjoter"
        }
    ],
    "subject": "Hello from {$company}!",
    "html": "Hello <b>{$name}</b>, nice to meet you!"
    "variables": [
        {
            "email": "example@test.codersee.com",
            "substitutions": [
                {
                    "var": "company",
                    "value": "Codersee"
                },
                {
                    "var": "name",
                    "value": "Piotr"
                }
            ]
        }
    ]
}

Whereas most of the fields a pretty descriptive, let’s take a look at one, important thing- variables.

As we can see, we can inject variables into the email subject, or content by simply specifying them with a dollar sign inside curly braces, for example: {$someVariable}. This way, we can specify dynamic values for each recipient, like name and company in our example.

In the next lines, we simply send the request to the MailerSend API, and if the response status code is 202 Accepted, then the email was sent successfully:

Of course, in order to make it work, let’s invoke our function inside the configureClient:

runBlocking {
  sendSimpleMessage(mailerSendClient, baseUrl, token)
}

Send Emails With Templates

At this point, we already know how to send transactional emails with Ktor and MailerSend. Moreover, we’ve seen how to send HTML content, which is a great way to customize the template.

Nevertheless, if you’d like to learn how to make your life a bit easier and use a graphic builder for templates, then you’re gonna like this paragraph.

Prepare Template Using MailerSend Builder

As the first step, let’s navigate to the templates page: https://app.mailersend.com/templates.

Nextly, let’s click Create template button and select Drag & drop editor option:

This way, we’re redirected to the Template gallery, which contains ~50 predefined templates, which we can adjust to our needs. In this tutorial, we will select the Reset password:

After we click Choose, we’re redirected to the builder page, where we can make adjustments:

As we can see, when using the builder, we need to encapsulate variables with double curly brackets.

When we finish, let’s click the Save & Publish button and write down the Template ID on the next page- we will need it later.

Adjust EmailRequest Class

With that being done, let’s get back to the Ktor project and edit the EmailRequest class:

@JsonInclude(JsonInclude.Include.NON_NULL)
data class EmailRequest(
    val from: Recipient,
    val to: List<Recipient>,
    val subject: String,
    @JsonProperty("template_id") val templateId: String,
    val personalization: List<CustomPersonalization>
) {
    data class Recipient(
        val email: String,
        val name: String
    )

    data class CustomPersonalization(
        val email: String,
        val data: PersonalizationData
    ) {
        data class PersonalizationData(
            val name: String,
            @JsonProperty("my_super_generated_code") val code: String
        )
    }
}

This time, instead of specifying the content manually, we simply pass the template identifier and a list of personalizations.

In our case, the desired JSON looks, as follows:

{
  "from": {
    "email": "example@test.codersee.com",
    "name": "Codersee"
  },
  "to": [
    {
      "email": "example@test.codersee.com",
      "name": "Pjoter"
    }
  ],
  "subject": "Please Reset Your Password",
  "templateId": "v69oxl587pzl785k",
  "personalization": [
    {
       "email": "example@test.codersee.com",
       "data": {
         "name": "Pjoter",
         "code": "f7fcc37c-4b7a-4919-aa91-a5ac7edd55d7"
       }
     }
  ]
}

Implement Sending Functionality

With all of that prepared, let’s implement the sendMessageUsingTemplate:

suspend fun sendMessageUsingTemplate(
    mailerSendClient: HttpClient,
    baseUrl: String,
    token: String
) {
    val subject = "Please Reset Your Password"

    val emailRequest = EmailRequest(
        from = EmailRequest.Recipient(
            email = "example@test.codersee.com",
            name = "Codersee"
        ),
        to = listOf(
            EmailRequest.Recipient(
                email = "example@test.codersee.com",
                name = "Pjoter"
            )
        ),
        subject = subject,
        templateId = "v69oxl587pzl785k",
        personalization = listOf(
            EmailRequest.CustomPersonalization(
                email = "example@test.codersee.com",
                data = EmailRequest.CustomPersonalization.PersonalizationData(
                    name = "Pjoter",
                    code = UUID.randomUUID().toString()
                )
            )
        )
    )

    val response = sendSingleEmail(
        mailerSendClient = mailerSendClient,
        url = "$baseUrl/email",
        token = token,
        emailRequest = emailRequest
    )

    if (response.status == HttpStatusCode.Accepted)
        println("Email sent successfully.")
    else
        println("Error when sending email.")

As we can see, the logic itself remains almost exactly the same and the only thing, which changes, is the payload we send.

Lastly, let’s put the following in the configureClient and rerun the application:

runBlocking {
  sendSimpleMessage(mailerSendClient, baseUrl, token)
}

As a result, we should see the message “Email sent successfully.” and the following email in our inbox:

Handling ErrorsEmails With Templates

I simply couldn’t finish this article about sending transactional emails with Ktor and MailerSend without showing how to handle errors.

And although we try our best to avoid them, sooner or later they will pop up. Thankfully, MailerSend API informs us in a pretty neat way about any issues. For example:

{
    "message": "The template_id must be an integer. (and 2 more errors)",
    "errors": {
        "template_id": [
            "The template_id must be an integer."
        ],
        "to.0.email": [
            "The to.0.email field is required."
        ],
        "variables.0.email": [
            "The variables.0.email field does not exist in to.*.email."
        ]
    }
}

Create ErrorResponse

As the first step, let’s implement the ErrorResponse class:

data class ErrorResponse(
  val message: String,
  val errors: Map<String, List<String>>
)

We will use this simple data class to deserialize JSON response into the object.

Implement handleError

Nextly, let’s add the handleError function:

suspend fun handleError(response: HttpResponse) {
    val statusCode = response.status.value
    val errorBody =  response.body<ErrorResponse>()
    println("Email sending failed with status code $statusCode and message '${errorBody.message}'. Errors:")

    errorBody.errors.forEach { (fieldName, fieldErrors) ->
        println("  * field name: [$fieldName]. Messages:")
        fieldErrors.forEach { error -> println("    - $error") }
    }
}

As we can see, this function takes the HttpResponse from MailerSend API and parses the JSON into the ErrorResponse instance. Thanks to that we can iterate and display all the errors.

Of course, as the last step, we need to modify our conditional statement, to make use of this snippet:

if (response.status == HttpStatusCode.Accepted)
  println("Email sent successfully.")
else 
  println("Error when sending email.")

Sending Emails With Ktor And MailerSend Summary

And that’s all for this article about how to send transactional emails using Ktor, Kotlin, and MailerSend.

As always, you can find the source code in this GitHub repository.

Happy to hear your thoughts, feedback, or ideas in the comments 🙂

The post Sending Transactional Emails Using Ktor, Kotlin, and MailerSend appeared first on Codersee blog- Kotlin on the backend.

Hello! In this, short step-by-step guide, I will show you how to create a Spring Boot console app with Kotlin from scratch.

In this article, we will learn:

• ✅ What is the CommandLineRunner and how can it help us create a Spring Boot console app?
• ✅ How to implement an example Spring Boot console app with Kotlin

2. What is CommandLineRunner?

As the first step, let’s take a minute to understand what exactly CommandLineRunner is. As the documentation states:

Interface used to indicate that a bean should run when it is contained within a SpringApplication.

In simple terms, the CommanLineRunner is an interface, which contains one method- void run(String... args) throws Exception, which we can implement and which will be invoked automatically, without us having to do it manually.

Moreover, we can implement it multiple times and control the order of invocation using the @Order annotation or the Ordered interface.

3. Create Project From Scratch

With that being said, let’s generate a new Spring Boot Kotlin application. To do so, let’s navigate to the Spring Initializr page and specify the following settings:

Basically, I would just like to emphasize that we don’t need any additional dependencies and the rest is totally up to you (and that I’m using the particular versions in case anything is deprecated in the future).

And once you pick your desired settings, please hit the Generate button and import the project to your IDE.

4. Implement CommandLineRunner

Finally, let’s open up our IDE and implement two classes called WillBeInvokedFirst and WillBeInvokedSecond:

@Component
@Order(1)
class WillBeInvokedFirst : CommandLineRunner {

  override fun run(vararg args: String) {
    print("Hello, ")
  }
}

@Component
@Order(2)
class WillBeInvokedSecond : CommandLineRunner {

  override fun run(vararg args: String) {
    println("World!")
  }
}

As we can see, we have to do only three things to implement a command-line application:

• firstly, override the run method
• secondly, annotate our classes with @Component annotation- to mark them as candidates for auto-detection
• thirdly, specify the @Order annotation- this way we explicitly control, which run implementation is invoked first (lower value = higher priority)

Besides, no other changes are required. Nevertheless, please keep in mind that by default, the CommandlineApplication.kt file was added when creating a project:

@SpringBootApplication
class CommandlineApplication

fun main(args: Array<String>) {
  runApplication<CommandlineApplication>(*args)
}

Finally, if we run the application we should see the following output:

Hello, World!

5. Summary

And that would be all for this short article on how to create a Spring Boot console app with Kotlin. If you’d like to clone the project, then you can find it in this GitHub repository.

Let me know in the comments section if you enjoy such short articles solving particular problems. Of course as an addition to standard, long tutorials.

Finally, if you enjoyed this one, then you might be interested in other Spring Boot articles I created so far.

The post Spring Boot Console App With Kotlin appeared first on Codersee blog- Kotlin on the backend.

There is no doubt, that testing is really crucial in the development process of any project. It allows us to automate the process of checking the functionality, as well as improves the quality of the code.

One of the techniques commonly used in unit testing is mocking. To put it in simple terms, mock objects are the objects that simulate the behavior of real objects.

In this article, I’d like to show you how to use MockK– an open-source mocking library for Kotlin- with JUnit 5.

2. Prepare the Code For Testing

Before we will head to the testing part, let’s write the code, which we will be testing later:

class ExampleClass {

    fun multiplyByTen(number: Int) = 10 * number

    fun publicFunction() = privateFunction()

    private fun privateFunction() = "Returned value"
}

class Injected {
    fun multiplyByFive(number: Int) = 5 * number
}

class ExampleClassWithDependency {

    lateinit var injected: Injected

    fun returnInjectedValue(number: Int) = injected.multiplyByFive(number)
}

object ExampleObject {
    fun concat(one: String, two: String) = one + two
}

As you can see, we’ve created a few simple classes and one object. Just for the record, a Kotlin object is a special singleton class- a class that has got only one instance.

3. Imports

As the next step, let’s add the required dependencies to our project:

  
  implementation("io.mockk:mockk:1.10.2")
  testImplementation("org.junit.jupiter:junit-jupiter-api:5.7.0")
  testImplementation("org.junit.jupiter:junit-jupiter-engine:5.7.0")

3. Using MockK library

In this article, we will learn how to use a few simple features of the library. If you would like to learn more, I highly recommend checking out MockK’s Github repository.

3.1. Mocking

Firstly, let’s see how to specify what exactly should be returned by the function of the mocked class:

    @Test
    fun `Mock a class`() {
        val exampleClass = mockk()

        every { exampleClass.publicFunction() } returns "Mocked value"

        val result = exampleClass.publicFunction()

        assertEquals("Mocked value", result)
    }

With this code, the “Mocked value” String will be returned for each invocation of the publicFunction.

Nextly, let’s mock a property of the class:

    @Test
    fun `Mock a property of the class`() {
        val injected = mockk()
        val exampleClass = ExampleClassWithDependency()
        exampleClass.injected = injected

        every { injected.multiplyByFive(any()) } returns 7

        val result = exampleClass.returnInjectedValue(10)

        assertEquals(7, result)
    }

This time, our result will be 7, even though the original function should return 50.

3.2. Relaxed mock

What happens if we do not specify the behavior of the invoked function? Let’s check this code:

    @Test
    fun `Example of MockKException`() {
        val exampleClass = mockk()

        exampleClass.publicFunction()
    }

The test failed throwing MockKException informing us that no answer has been found for the function we were trying to test.

    @Test
    fun `Fix MockKException using relaxed mock`() {
        val exampleClass = mockk(relaxed = true)
        val defaultStringValue = ""

        assertEquals(defaultStringValue, exampleClass.publicFunction())
    }

To fix that, we can either specify explicitly the behavior or use a relaxed mock. A relaxed mock returns the default values for all the functions within the mocked class. As we can see above, the default String value returned by the function will be an empty String.

3.3. Using Annotations

If we would like to simplify the creation of the object, we can use annotations. As we are using JUnit5, we need to annotate our test class with @ExtendWith:

@ExtendWith(MockKExtension::class)
internal class ExampleClassTest

As the next step, let’s add two properties to it:

    @MockK
    lateinit var annotatedMock: Injected

    @InjectMockKs
    var annotatedClass = ExampleClassWithDependency()

And create a new test:

    @Test
    fun `Simplified property mock with annotation`() {
        every { annotatedMock.multiplyByFive(any()) } returns 7

        val result = annotatedClass.returnInjectedValue(10)

        assertEquals(7, result)
    }

With this approach, we eliminate the need to manually create the mock for each test.

3.4. Spy The Object

Sometimes, we would like to have the possibility to check the real behavior of the class, as well as a mocked one. For that case, we can use a spy:

    @Test
    fun `Spy a class`() {
        val exampleClass = spyk()

        assertEquals("Returned value", exampleClass.publicFunction())
    }

As we can see here, the function returns the value that has been implemented in our code.

3.5. Mock Private Function Behavior

In our class implementation, publicFunction returns the value from privateFunction. Let’s check, how we can specify the behavior of the private function:

@Test
fun `Mock a private function`() {
val exampleClass = spyk(recordPrivateCalls = true)

every { exampleClass["privateFunction"]() } returns "Mocked value"

assertEquals("Mocked value", exampleClass.publicFunction())
}

3.6. Mock an Object

As we’ve told in the beginning, the Kotlin object is a special singleton class. To mock it, we will use mockkObject:

    @Test
    fun `Mock an object`() {
        mockkObject(ExampleObject)

        every { ExampleObject.concat(any(), any()) } returns "Mocked value"

        val result = ExampleObject.concat("", "")
        assertEquals("Mocked value", result)
    }

Even though Kotlin allows us to have only one instance of the object class, the MockK library allows us to create multiple instances of its mocks:

 
    @Test
    fun `Multiple mocked instances of object`() {
        val firstMock = mockk()
        val secondMock = mockk()

        every { firstMock.concat(any(), any()) } returns "One"
        every { secondMock.concat(any(), any()) } returns "Two"

        val firstResult = firstMock.concat("", "")
        val secondResult = secondMock.concat("", "")

        assertEquals("One", firstResult)
        assertEquals("Two", secondResult)
    }

3.7. Capturing

In our previous examples, we didn’t care about what arguments were passed to the stubbed methods. A technique called capturing allows us to validate what arguments has been passed:

    @Test
    fun `Capture passed value`() {
        val exampleClassMock = mockk()
        val argumentSlot = slot()

        every { exampleClassMock.multiplyByTen(capture(argumentSlot)) } returns 5

        exampleClassMock.multiplyByTen(55)

        assertEquals(55, argumentSlot.captured)
    }

As we can see, the slot contains the captured value, which we have passed to our checked function.

3.8. Verification

If we would like to check how many times the function has been invoked, we can use verify:

    @Test
    fun `Verify calls`() {
        val exampleClassMock = mockk()

        every { exampleClassMock.multiplyByTen(any()) } returns 5

        exampleClassMock.multiplyByTen(10)
        exampleClassMock.multiplyByTen(20)

        verify(exactly = 2) { exampleClassMock.multiplyByTen(any()) }
        confirmVerified(exampleClassMock)
    }

In the above example, we’ve used the exactly parameter to verify that the behavior happened exactly 2 times. If we would specify another number, the test would fail and inform us, that the verification failed.

4. Summary

And that would be all for this article. We’ve learned how to use some basic features of the MockK library with JUnit5.

For the source code of the project, please visit our project on GitHub.

If you enjoyed this tutorial, I would be forever grateful if you would like to share some feedback with me through our page, group, or contact form. I highly appreciate all the comments and suggestions that I am getting from you.

The post A Guide to MockK: a Mocking Library for Kotlin appeared first on Codersee blog- Kotlin on the backend.