Long story short, we will see:

• how to prepare a GraphQL schema,
• what imports are necessary to utilize suspended functions,
• how to expose queries, mutations, and map schema with annotated controllers,
• exception handling with GraphQlExceptionHandler

Create Project

As the first step, let’s prepare a brand new project.

To do so, let’s navigate to the Spring Initializr page and select the following imports:

The project metadata are totally up to you, but when it comes to the dependencies, we must select the Spring Reactive Web and Spring for GraphQL.

Thanks to the first one, Spring Boot configures a reactive web stack based on Project Reactor and Netty instead of Tomcat. And given we want to work with GraphQL and Kotlin coroutines, then this is a must-have for us.

The second provides support for Spring applications built on GraphQL Java. Moreover, it is the successor of the GraphQL Java Spring project from the GraphQL Java team.

Lastly, let’s download the zip package, extract and import it to our IDE.

Define GraphQL Schema

What is GraphQL Schema?

If you have ever worked with GraphQL before, then you know that compared to the REST, everything starts with schema definition.

If you haven’t, then GraphQL schema is a file typically written with Schema Definition Language (SDL) that describes how our API clients can interact with our server. To be more specific, inside it, we define the structure of returned data, as well as how consumers can fetch or send us the payloads.

And even though it may sound like a GraphQL substitute for OpenAPI specs, it is something more. In REST, OpenAPI docs are a nice addition to our project. In GraphQL, our services continuously utilize the schema definition to validate and execute requests against it.

And if you would like to learn more about GraphQL schema, then check out the official documentation later. But for now, let’s focus on the Spring / GraphQL / Kotlin combination 😉

schema.graphql in Spring

As the first step, let’s head to the resources > graphql directory in our project, and let’s insert the schema.graphql file:

type Query {
  article(id: ID!): Article
  articles: [Article!]!
}

type Mutation {
  createArticle(input: CreateArticleInput!): Article!
  addComment(articleId: ID!, input: AddCommentInput!): Comment
}

input CreateArticleInput {
  title: String!
  content: String!
  userId: ID!
}

input AddCommentInput {
  userId: String!
  content: String!
}

type User {
  id: ID!
  name: String!
}

type Article {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
  createdAt: String!
}

type Comment {
  id: ID!
  content: String!
  author: User
}

In Spring Boot, this file is registered automatically as our schema definition.

And as we can see, we defined 5 things:

• queries– how a client reads data. Every GraphQL schema must support them,
• mutations– how a client modifies data,
• inputs– used to pass structured arguments to our mutations and queries,
• types– establishing the structure of data we return,
• scalars– like String, or ID (but also Int, Float, Boolean), describing returned fields.

Moreover, we can see the exclamation mark- !. In contrast to Kotlin, in GraphQL, we must explicitly define non-nullable types. Meaning, that [Comment] describes a nullable array of nullable Comment type (Array<Comment?>?), whereas [Comment!]! is a not null array with not null items.

Spring GraphQL Schema Inspection

Following, let’s rerun our application.

As a result, we should get the following in logs:

o.s.b.a.g.GraphQlAutoConfiguration: GraphQL schema inspection:
Unmapped fields: {Query=[article, articles], Mutation=[createArticle, addComment]}
Unmapped registrations: {}
Unmapped arguments: {}
Skipped types: []

As we can see, Spring Boot verifies the schema we defined every time we start the application. And the above message simply says that we do not have handler methods for our definition.

Let’s fix that then 😉

Create Models

As the next step, let’s add Kotlin data classes to our Spring Boot project. They will be later used to serialize and deserialize data defined in our GraphQL schema.

To do so, let’s add the Models.kt:

data class User(
    val id: String,
    val name: String,
)
data class Article(
    val id: String,
    val title: String,
    val content: String,
    val authorId: String,
    val createdAt: String,
)
data class Comment(
    val id: String,
    val content: String,
    val articleId: String,
    val userId: String,
)
data class CreateArticleInput(
    val title: String,
    val content: String,
    val userId: String,
)
data class AddCommentInput(
    val content: String,
    val userId: String,
)

As we can see, nothing spectacular here. The only interesting fact is that the ID is serialized in the same way as a String.

QueryMapping as suspend fun

Following, let’s learn how the Spring for GraphQL works with Kotlin coroutines.

According to the documentation:

Kotlin coroutine and Flow are adapted to Mono and Flux.

Which means that whenever we use the Spring WebFlux, Spring automatically converts our suspended functions Mono and functions that return Flow to Flux .

Implement Article Service

Before we head to the GraphQL part, let’s make some small preparations.

Let’s insert the ArticleService:

@Component
object ArticleService {
    private val articles = mutableListOf(
        Article(
            id = "article-id-1",
            title = "article-title-1",
            content = "article-content-1",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-2",
            title = "article-title-2",
            content = "article-content-2",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-3",
            title = "article-title-3",
            content = "article-content-3",
            authorId = "user-id-3",
            createdAt = LocalDateTime.now().toString()
        ),
    )
    suspend fun findArticleById(id: String): Article? {
        delay(100)
        return articles.firstOrNull { it.id == id }
    }
}

As we can see, we use my favorite, in-memory database called mutable list (😉) and expose findArticleById – a suspended function.

This function will either find the desired article by ID or return a null value.

Add ArticleController

With that done, let’s add the ArticleController:

@Controller
class ArticleController(
    private val articleService: ArticleService,
) {
    @QueryMapping
    suspend fun article(@Argument id: String): Article? =
        articleService.findArticleById(id)
}

As we can see, thanks to the Spring GraphQL, we can leverage the annotation-based approach.

Firstly, we must annotate our class with the @Controller annotation. Then, all the methods inside it annotated with @SchemaMapping annotation will become handlers.

And @QueryMapping, @MutationMapping, or @SubscriptionMapping are nothing else than meta annotations (annotated with @SchemaMapping). This way, we achieve a more readable code.

Additionally, in Spring, we use the @Argument annotation to bind GraphQL input arguments to our Kotlin instances.

Enable GraphiQL & Test

Nextly, let’s turn on the GraphiQL– the IDE for testing GraphQL APIs (like Postman, Bruno, or Insomnia).

To do so, let’s navigate to the resources directory and change the application.properties into the application.yaml file:

spring:
  application:
    name: graphsandbox
  graphql:
    graphiql:
      enabled: true

Then, let’s open up the browser, go to http://localhost:8080/graphiql, and put the following:

query SomeRandomQuery {
  article(id: "article-id-1") {
    id
    title
  }
}

As we can see, the query name is up to us, but inside it, we must define which of the “exposed” queries we would like to use. As the input parameter, we pass the String value- article-id-1– and lastly, we define what fields we would like to get in response (that’s what the whole GraphQL is a about, right?😉).

So, as the next step, let’s run the query and check out the result:

{
  "errors": [
    {
      "message": "INTERNAL_ERROR for f337f3f3-5",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "article"
      ],
      "extensions": {
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": {
    "article": null
  }
}

Unfortunately, that is not what we expected.

Moreover, when we check out logs, we should see this:

s.g.e.ExceptionResolversExceptionHandler : Unresolved NoClassDefFoundError for executionId f337f3f3-5
java.lang.NoClassDefFoundError: org/springframework/data/util/KotlinReflectionUtils
	at org.springframework.graphql.data.method.InvocableHandlerMethodSupport.invokeSuspendingFunction(InvocableHandlerMethodSupport.java:141) ~[spring-graphql-1.3.4.jar:1.3.4]
	at org.springframework.graphql.data.method.InvocableHandlerMethodSupport.doInvoke(InvocableHandlerMethodSupport.java:108) ~[spring-graphql-1.3.4.jar:1.3.4]

Fix Spring GraphQL Coroutines Issue

As we could see, the issue is caused by the missing dependency, and we can easily fix that.

To do so, let’s open up the build.gradle.kts and add the following dependency:

implementation("org.springframework.data:spring-data-commons")

Then, let’s sync the gradle project and rerun the application.

After we run the test again, we should see the following:

{
  "data": {
    "article": {
      "id": "article-id-1",
      "title": "article-title-1"
    }
  }
}

Splendid! Everything works perfectly fine😉

Spring GraphQL with Kotlin Flow

With that done, let’s learn how to work with Kotlin Flow and Spring GraphQL.

As the first step, let’s insert a new function to our ArticleService:

fun findAllArticles(): Flow<Article> = articles.asFlow()

This way, we produce a cold flow from our list of articles.

Then, let’s add a new handler:

@QueryMapping
fun articles(): Flow<Article> =
    articleService.findAllArticles()

Nothing new this time. Just like previously, we add a new function marked with @QueryMapping.

When we run the following query in GraphiQL:

query AnotherOne {
  articles {
    id
    title
    createdAt
  }
}

We should see the exact result:

{
  "data": {
    "articles": [
      {
        "id": "article-id-1",
        "title": "article-title-1",
        "createdAt": "2025-04-12T13:06:29.142469200"
      },
      {
        "id": "article-id-2",
        "title": "article-title-2",
        "createdAt": "2025-04-12T13:06:29.142469200"
      },
      {
        "id": "article-id-3",
        "title": "article-title-3",
        "createdAt": "2025-04-12T13:06:29.142469200"
      }
    ]
  }
}

@SchemaMapping

One of the greatest thing in GraphQL is the possibility to return the related data in one, single query. And if you remember our schema definition, our API should allow us to do that.

To be more specific, each article can have the author, multiple comments, and each comment also has its author.

But when we test that functionality right now:

query AnotherOne {
  articles {
    id
    title
    createdAt
    author {
      id
      name
    }
    
    comments {
      id
      content
      author {
        name
      }
    }
  }
}

The only thing we will get in response will be a looooong list of errors:

{
  "errors": [
    {
      "message": "The field at path '/articles[0]/author' was declared as a non null type, but the code involved in retrieving data has wrongly returned a null value.  The graphql specification requires that the parent field be set to null, or if that is non nullable that it bubble up null to its parent and so on. The non-nullable type is 'User' within parent type 'Article'",
      "path": [
        "articles",
        0,
        "author"
      ],
      "extensions": {
        "classification": "NullValueInNonNullableField"
      }
    }
... other errors

Of course, with Spring we can easily fix it, but we will need small preparation first.

Update Service

Firstly, let’s get back to our service and update it:

@Component
object ArticleService {
    private val articles = mutableListOf(
        Article(
            id = "article-id-1",
            title = "article-title-1",
            content = "article-content-1",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-2",
            title = "article-title-2",
            content = "article-content-2",
            authorId = "user-id-2",
            createdAt = LocalDateTime.now().toString()
        ),
        Article(
            id = "article-id-3",
            title = "article-title-3",
            content = "article-content-3",
            authorId = "user-id-3",
            createdAt = LocalDateTime.now().toString()
        ),
    )
    private val users = mutableListOf(
        User(id = "user-id-1", name = "user-name-1"),
        User(id = "user-id-2", name = "user-name-2"),
        User(id = "user-id-3", name = "user-name-3"),
    )
    private val comments = mutableListOf(
        Comment(id = "comment-id-1", content = "comment-content-1", articleId = "article-id-1", userId = "user-id-3"),
        Comment(id = "comment-id-2", content = "comment-content-2", articleId = "article-id-2", userId = "user-id-3"),
        Comment(id = "comment-id-3", content = "comment-content-3", articleId = "article-id-2", userId = "user-id-2"),
        Comment(id = "comment-id-4", content = "comment-content-4", articleId = "article-id-3", userId = "user-id-3"),
    )
    
    suspend fun findArticleById(id: String): Article? {
        delay(100)
        return articles.firstOrNull { it.id == id }
    }
    fun findAllArticles(): Flow<Article> = articles.asFlow()
    suspend fun findUserById(id: String): User? {
        delay(100)
        return users.firstOrNull { it.id == id }
    }
    fun findCommentsByArticleId(id: String): Flow<Comment> =
        comments.filter { it.articleId == id }.asFlow()
}

As we can see, we added two more “tables” along with simple functions to obtain data from them.

Update @Controller

Then, let’s update our controller class:

@SchemaMapping
suspend fun author(article: Article): User =
    articleService.findUserById(article.authorId)!!
@SchemaMapping
suspend fun author(comment: Comment): User =
    articleService.findUserById(comment.userId)!!
@SchemaMapping
fun comments(article: Article): Flow<Comment> =
    articleService.findCommentsByArticleId(article.id)

As we can see, this time we leverage the @SchemaMapping annotation for our handlers. Pretty similar to what we did already.

The interesting part here is the parameters. Every handler takes the parent type as an argument. Meaning, that for the article -> author parent-child relationship, we define the function that takes the article instance as an argument. And that’s it!

Of course, please the double exclamation (!!) should not land in the real, production-ready code😉

Anyway, when we rerun our test now, we will see the following:

{
  "data": {
    "articles": [
      {
        "id": "article-id-1",
        "title": "article-title-1",
        "createdAt": "2025-04-12T13:21:17.584507600",
        "author": {
          "id": "user-id-2",
          "name": "user-name-2"
        },
        "comments": [
          {
            "id": "comment-id-1",
            "content": "comment-content-1",
            "author": {
              "name": "user-name-3"
            }
          }
        ]
      }
... more thingies 

And that’s what we expected. Awesome!

GraphQL Mutations

When we run the application right now, we see that we still miss two things that we defined- mutations.

So, before we add a new handler, let’s implement the following function in our service:

suspend fun createArticle(input: CreateArticleInput): Article {
    delay(100)
    return Article(
        id = UUID.randomUUID().toString(),
        title = input.title,
        content = input.content,
        authorId = input.userId,
        createdAt = LocalDateTime.now().toString(),
    ).also { articles.add(it) }
}

As can be seen, we take the input, create a new Article instance, and insert that to the list.

With Kotlin also ,we can return at the same time the created instance and achieve a slightly cleaner code. To be even fancier, we could use a reference here: .also(articles::add) 😉

Then, let’s add the appropriate handler to our controller:

@MutationMapping
suspend fun createArticle(@Argument input: CreateArticleInput): Article =
    articleService.createArticle(input)

As we can see, just like with @QueryMapping, this time, we mark the handler with @MutationMapping and our argument with @Argument. Nothing else is necessary to make our mutation work.

So, given that, let’s rerun the app and test our functionality:

mutation someMutation {
  createArticle(
    input: {
      title: "Awesome codersee Kotlin article", 
      content: "Some content", 
      userId: "user-id-3"
    }
  ) {
    id
    title
    content
    author {
      id
      name
    }
  }
}

As a result, we should get the following:

{
  "data": {
    "createArticle": {
      "id": "0e51a902-835b-4e55-9b4a-f2dccd242ea7",
      "title": "Awesome codersee Kotlin article",
      "content": "Some content",
      "author": {
        "id": "user-id-3",
        "name": "user-name-3"
      }
    }
  }
}

Wonderful! We can see that with GraphQL mutations, we can not only create/modify things on our server. With this one query, we can also retrieve the data and the dependent objects😮

Error Handling in Spring GraphQL

As the last step, let’s add one more mutation to learn more about error handling.

First, let’s add the new custom exception ot our codebase in Models.kt:

data class GenericNotFound(val msg: String) : RuntimeException(msg)

Then, let’s implement the following function in ArticleService:

suspend fun addComment(id: String, input: AddCommentInput): Comment {
        delay(100)
        users.firstOrNull { it.id == input.userId }
            ?: throw GenericNotFound("User not found")
        return articles.firstOrNull { it.id == id }
            ?.let {
                Comment(
                    id = UUID.randomUUID().toString(),
                    articleId = id,
                    content = input.content,
                    userId = input.userId,
                ).also { comments.add(it) }
            }
            ?: throw GenericNotFound("Article not found")
    }

This time, we can see a more production-ready code.

If we want to add a comment to the article, we must first check if both the desired author and article exist, right?

If that is not the case, then we throw our custom exception.

Following, let’s add a new mutation handler:

@MutationMapping
suspend fun addComment(
    @Argument id: String,
    @Argument input: AddCommentInput,
): Comment =
    articleService.addComment(id, input)

Now, when we rerun the app and execute the following test:

mutation anotherMutation {
  addComment(
    articleId: "non-existing"
    input: {userId: "user-id-1", content: "My comment"}
  ) {
    id
    content
  }
}

We will see the following error:

{
  "errors": [
    {
      "message": "INTERNAL_ERROR for f62a4c7e-1",
      "locations": [
        {
          "line": 52,
          "column": 3
        }
      ],
      "path": [
        "addComment"
      ],
      "extensions": {
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": {
    "addComment": null
  }
}

And this is not what we wanted, right?

GraphQlExceptionHandler and ControllerAdvice

One of the solutions we can have in such a situation is a combination of ControllerAdvice and GraphQlExceptionHandler.

If you would like to learn more about ControllerAdvice and RestControllerAdvice, then check out my other article.

So, as the next step, let’s add the GlobalExceptionHandler class to the project:

@ControllerAdvice
class GlobalExceptionHandler {
    @GraphQlExceptionHandler
    fun handleGenericNotFound(ex: GenericNotFound): GraphQLError =
        GraphQLError.newError()
            .errorType(ErrorType.DataFetchingException)
            .message(ex.msg)
            .build()
}

As we can see, inside it, we implement a function that takes the GenericNotFound as an argument. This way, whenever our custom exception is thrown, Spring will return the GraphQLError instance with our config instead.

As a result, when we retest the application, we should get the following JSON:

{
  "errors": [
    {
      "message": "Article not found",
      "locations": [],
      "extensions": {
        "classification": "DataFetchingException"
      }
    }
  ],
  "data": {
    "addComment": null
  }
}

Spring GraphQL with Kotlin Coroutines Summary

And that’s all for this article on how to work with Kotlin coroutines and Flows in the Spring Boot GraphQL project.

As always, you can find the source code in my GitHub repostory.

The post Spring for GraphQL with Kotlin Coroutines appeared first on Codersee blog- Kotlin on the backend.

Of course, I highly encourage you to take a look at other articles in this series, too:

• #1 Spring Boot with AWS S3, S3Client, and Kotlin
• #2 (This article)
• #3 Test Spring Boot AWS S3 with Localstack and Testcontainers

Video Tutorial

If you prefer video content, then check out my video that covers all three articles:

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

What is S3Template?

Before we get our hands dirty with the code, let’s take a second to understand better with S3Template is and how it can make our lives easier when integrating a Spring Boot app with S3.

Let me quote the S3Template documentation here:

Higher level abstraction over S3Client providing methods for the most common use cases.

So, if you have already worked with, or you have seen my previous article with S3Client, then you saw that simple operations require some boilerplate. And that is exactly what S3Template solves.

And as a note from my end, I just wanted to note S3Template handles only some subset of S3Client operations, so in our projects those two will rather coexist, instead of being each others alternatives.

AWS S3Template Operations

With all of that said, let’s get to work.

Let’s add the controller package and BucketController class to it. We will use it to expose a bunch of endpoints triggering various operations on S3 buckets and files.

When it comes to the operations- we will use the same ones as in the previous article, and as the last one, I will show you how to serialize and deserialize objects with AWS S3 and S3Template.

List All Buckets

Although the S3Template does not expose any method that would help us with this task, I wanted to mention it as we discussed it in the previous tutorial.

Additionally, this is a great example of S3Client and S3Template co-existence:

@RestController
@RequestMapping("/buckets")
class BucketController(
  private val s3Template: S3Template,
  private val s3Client: S3Client,
) {

  @GetMapping
  fun listBuckets(): List<String> {
    val response = s3Client.listBuckets()

    return response.buckets()
      .mapIndexed { index, bucket ->
        "Bucket #${index + 1}: ${bucket.name()}"
      }
  }
}

As we can see, not too much S3Template could improve here, so I bet this is the reason why it was not introduced.

New S3 Bucket

Nextly, let’s take a look at how we can create a brand new bucket:

@PostMapping
fun createBucket(@RequestBody request: BucketRequest) {
  s3Template.createBucket(request.bucketName)
}

data class BucketRequest(val bucketName: String)

As we can see, no additional request classes- the only thing we need is the bucket name.

Of course, let’s rerun our application and verify if everything is working:

curl --location --request POST 'http://localhost:8080/buckets' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bucketName": "codersee-awesome-bucket"
}'

As a result, we should get 200 OK without a response body.

Upload File to S3 Bucket

Nextly, let’s take a look at how to upload a new file to S3.

We have a few options, among which the store function is the easiest:

@PostMapping("/{bucketName}/objects")
fun createObject(@PathVariable bucketName: String, @RequestBody request: ObjectRequest) {
  s3Template.store(bucketName, request.objectName, request.content)
}

data class ObjectRequest(val objectName: String, val content: String)

As we can see, this function takes three arguments:

• the bucket name,
• filename,
• and the content to upload (to be specific Object object)

Alternatively, we could use the upload function, which allows us to send InputStream instance and metadata:

@Override
public S3Resource upload(
  String bucketName, 
  String key, 
  InputStream inputStream,
  @Nullable ObjectMetadata objectMetadata
) 

Lastly, let’s verify that everything is fine with the following curl:

curl --location --request POST 'http://localhost:8080/buckets/codersee-awesome-bucket/objects' \
--header 'Content-Type: application/json' \
--data-raw '{
    "objectName": "file-example.txt",
    "content": "My file content"
}'

If everything worked, then a new file should be present in our bucket 🙂

List Files From The Bucket

Nextly, let’s see how we can list the bucket content with S3Template:

@GetMapping("/{bucketName}/objects")
fun listObjects(@PathVariable bucketName: String): List<String> =
  s3Template.listObjects(bucketName, "")
    .map { s3Resource -> s3Resource.filename }

We can clearly see that this is not rocket science 😉

Nevertheless, it is worth mentioning that this time we get the S3Resource instance and instead of the key() we use it getFilename method.

And just like previously, let’s see the endpoint in action:

curl --location --request POST 'http://localhost:8080/buckets/codersee-awesome-bucket/objects' \
--header 'Content-Type: application/json' \
--data-raw '{
    "objectName": "file-example.txt",
    "content": "My file content"
}'

# Response status: 200 OK
# Response body: 
[
    "file-example.txt"
]

Download a File

So what about fetching files from the S3 bucket?

With S3Template, it’s a piece of cake:

@GetMapping("/{bucketName}/objects/{objectName}")
fun getObject(@PathVariable bucketName: String, @PathVariable objectName: String): String =
  s3Template.download(bucketName, objectName).getContentAsString(UTF_8)

We specify the bucket name and the object name, and as a result, we get the S3Resource that exposes a bunch of methods. Among others, the getContentAsString that is pretty descriptive 😉

Similarly, let’s hit the endpoint:

curl --location --request GET 'http://localhost:8080/buckets/codersee-awesome-bucket/objects/file-example.txt'

# Response status: 200 OK
# Response body: 
"My file content"

Delete the Bucket

Last before least, let’s take a look at how we can get rid of the bucket:

@DeleteMapping("/{bucketName}")
fun deleteBucket(@PathVariable bucketName: String) {
  s3Template.listObjects(bucketName, "")
    .forEach { s3Template.deleteObject(bucketName, it.filename) }

  s3Template.deleteBucket(bucketName)
}

And just like in the previous article- we must ensure the bucket does not contain any objects.

To do so, we list out objects by specifying the bucket name and objects prefix (as we don’t have any, we pass an empty String). Then, for each object, we use its key to delete it. And lastly, we simply invoke the deleteBucket by passing the name of a bucket to delete.

Of course, let’s verify this logic, too:

curl --location --request DELETE 'http://localhost:8080/buckets/codersee-awesome-bucket'

If we run this command and the S3 bucket exists, then we should see 200 OK and our bucket will disappear.

Serialize/Deserialize objects

As the last thing, let’s take a look at how easily we can persist objects using the combination of store and read functions:

@PostMapping("/{bucketName}/objects")
fun createExampleObject(@PathVariable bucketName: String): Example {
  val example = Example(id = UUID.randomUUID(), name = "Some name")

  s3Template.store(bucketName, "example.json", example)

  return s3Template.read(bucketName, "example.json", Example::class.java)
}

data class Example(val id: UUID, val name: String)

As we can see, we made a small update to our POST /{bucketName}/objects endpoint logic.

Basically, the first part is exactly the same, we use the store again to push the file to the bucket.

Nevertheless, instead of the download we saw previously, we use the read function that uses the S3ObjectConverter that will automatically deserialize the JSON into the Example class instance.

And for the last time, let’s hit our API:

curl --location --request POST 'http://localhost:8080/buckets/codersee-awesome-bucket/objects' \
--data-raw ''

# Response status: 200 OK 
# Response body: 
{
    "id": "3eacd8a3-48b2-4756-86db-e4c9f4e291da",
    "name": "Some name"
}

And as we can see, the output confirms that everything is working fine.

Summary

And that’s all for this article on how to make our lives easier in Spring Boot with S3Template.

I hope you enjoyed it, and again wanted to invite you to take a look at other content of this series:

• #1 Spring Boot with AWS S3, S3Client, and Kotlin
• #2 (This article)
• #3 Test Spring Boot AWS S3 with Localstack and Testcontainers

Lastly, just wanted to show that you can find the source code in this GitHub repository and that you can join my newsletter to stay up-to-date with Kotlin on the backend.

The post Spring Boot with Kotlin, AWS S3, and S3Template appeared first on Codersee blog- Kotlin on the backend.

Moreover, we will take a quick look into the Spring Boot Actuator and how it can help us, so, to let’s not waste our time and let’s get to work! 🙂

Video Tutorial

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

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

Datadog

If you came here directly, then I bet you already know what Datadog is and what purpose it will serve in your project.

However, for those who hear about it for the first time, let me give you a really short intro.

Long story short- Datadog is an integrated platform for monitoring & security. It provides tools for monitoring applications, databases, distributed tracing, logs management, and many many more. In other words, makes all the things that are not so cool, but necessary in production-ready environments, a bit less painful 😉

However, what is the most important for us today- it provides tools to collect metrics from our applications so that later we can make use of them.

But, what are they?

What Are Metrics?

According to the Datadog documentation:

Metrics are numerical values that can track anything about your environment over time.

And I must admit- I love this definition for its completeness in its simplicity.

Because basically, metric is everything in our system that we can assign a number to and track. From Garbage Collector stats, JVM memory, CPU, and request latency, to the average cart size. Literally everything.

And in this tutorial, we will see how to send metrics collected automatically by our Spring Boot app to DataDog.

Create New Project

As the first step, let’s navigate to the Spring Initializr page, select the following and import the project to our IDE:

Apart from versions and metadata, we can see that we added two dependencies: Spring Web and Spring Boot Actuator.

The first one is quite obvious, but in terms of metrics Spring Boot Actuator provides dependency management and auto-configuration for Micrometer – a vendor-neutral application observability facade.

With that, Spring Boot takes care of configuring MeterRegistry and the only thing we need to do is to add the micrometer-registry-{system} dependency to the build.gradle.kts :

implementation("io.micrometer:micrometer-registry-datadog")

Note: we could achieve exactly the same using the Spring Initializr page and searching for the Datadog dependency, but I wanted to emphasize the fact, that other vendors, like Elastic, or OpenTelemetry can be added in the same manner.

Verify and Expose Metrics Endpoint

After we import our project, let’s run it, and let’s take a look at the endpoints exposed by default by Spring Boot Actuator:

curl --location --request GET 'http://localhost:8080/actuator' 

As a result, we should see the following:

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        }
    }
}

And the first lesson is that the metrics endpoint is not exposed by default.

So to change that, let’s navigate to the application.yaml and add the following:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health

After that, let’s rerun the application.

As a result, this time, we should see that two new endpoints are present:

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "health-path": {
            "href": "http://localhost:8080/actuator/health/{*path}",
            "templated": true
        },
        "metrics-requiredMetricName": {
            "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
            "templated": true
        },
        "metrics": {
            "href": "http://localhost:8080/actuator/metrics",
            "templated": false
        }
    }
}

The last one- /actuator/metrics– simply displays a list of available meter names, and when we invoke it, we should see the following JSON response:

{
    "names": [
        "application.ready.time",
        "application.started.time",
        "disk.free",
        "disk.total",
        "executor.active",
        "executor.completed",
        "executor.pool.core",
        "executor.pool.max",
        "executor.pool.size",
        "executor.queue.remaining",
        "executor.queued",
        "http.server.requests",
        "http.server.requests.active",
        "jvm.buffer.count",
        "jvm.buffer.memory.used",
        "jvm.buffer.total.capacity",
        "jvm.classes.loaded",
        "jvm.classes.unloaded",
        "jvm.compilation.time",
        "jvm.gc.concurrent.phase.time",
        "jvm.gc.live.data.size",
        "jvm.gc.max.data.size",
        "jvm.gc.memory.allocated",
        "jvm.gc.memory.promoted",
        "jvm.gc.overhead",
        "jvm.gc.pause",
        "jvm.info",
        "jvm.memory.committed",
        "jvm.memory.max",
        "jvm.memory.usage.after.gc",
        "jvm.memory.used",
        "jvm.threads.daemon",
        "jvm.threads.live",
        "jvm.threads.peak",
        "jvm.threads.started",
        "jvm.threads.states",
        "logback.events",
        "process.cpu.time",
        "process.cpu.usage",
        "process.start.time",
        "process.uptime",
        "system.cpu.count",
        "system.cpu.usage",
        "tomcat.sessions.active.current",
        "tomcat.sessions.active.max",
        "tomcat.sessions.alive.max",
        "tomcat.sessions.created",
        "tomcat.sessions.expired",
        "tomcat.sessions.rejected"
    ]
}

In simple words, this is the list of all metrics collected at this point by our Spring Boot application. And yes- we will be able to export them to Datadog.

Nevertheless, let’s verify what the second endpoint- /actuator/metrics/{requiredMetricName}– does.

To do that, let’s make a GET request and specify any metric name:

curl --location --request GET 'http://localhost:8080/actuator/metrics/process.cpu.usage'

This time, the endpoint will return metric details along with the current value:

{
    "name": "process.cpu.usage",
    "description": "The \"recent cpu usage\" for the Java Virtual Machine process",
    "measurements": [
        {
            "statistic": "VALUE",
            "value": 0.038209510879134205
        }
    ],
    "availableTags": []
}

Create Datadog Account

Excellent! At this point, we are sure that our Spring Boot app collects metrics, so it’s time to proceed with the Datadog part.

If you haven’t done it yet, then let’s create a trial account together.

Let’s navigate to the https://www.datadoghq.com/ and click the “Free trial” button:

Following, let’s fill out the signup form:

And with that done, when we confirm our e-mail address, we will land on this page:

As we can see, the above page contains a bunch of guides on how to set up the agent.

And although we are not interested in any of those, this page has one, valuable information for us- the API key.

Note: I think that readers of this blog are well aware of that, but for my own peace of mind- API keys are vulnerable data, so you must be cautious with them! 🙂

At this point, please copy this value and we will use it in the proceeding steps.

Configure App To Send Metrics

When we have our Datadog account ready, we can finally configure our app.

API Key

Firstly, let’s get back to our Spring Boot project and update the application.yaml :

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE

Of course, we must replace the YOUR_KEY_VALUE with the actual API key.

Update Datadog URI

If you are using Datadog US (the option you could select when signing up), then that’s pretty much it and you can restart the application.

By default, metrics are sent to the Datadog US site (api.datadoghq.com). If your Datadog project is hosted on one of the other sites, or you need to send metrics through a proxy, configure the URI accordingly.

So given the above, if we use another region, then we need to add one more line:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE 
        uri: https://api.datadoghq.eu

Update Metrics Upload Interval

Following, let’s see how easily we can update the interval, in which data are sent to Datadog:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE 
        uri: https://api.datadoghq.eu
        step: 10s

The default value is 30 seconds. And to change that, the only thing we need to do is to add the step value.

Set Spring Logging Level to DEBUG

As the last thing, which technically is not directly related to sending metrics, I would like to add the following to the root of our application.yaml file:

logging:
  level:
    root: DEBUG

This way we set the logging level in our Spring Boot application to DEBUG.

Why? It will be useful in a moment when we will be testing our implementation.

Testing

With all of that done, we can finally verify that everything is working properly.

Verify Spring Boot Sends Data to Datadog

Firstly, let’s rerun our application and take a look at the logs.

If we see the following:

i.m.datadog.DatadogMeterRegistry         : successfully sent 78 metrics to datadog

Then data are successfully sent to the Datadog API.

Let’s leave it running for some time (like 2 minutes, or something), so that we have actual data later to work with 🙂

Review Metrics in Datadog

After that time, the only thing left is to take a look at metrics in Datadog.

If we haven’t closed the Datadog “Agent Setup” page, then it should automatically close and redirect us to the dashboard.

However, if that didn’t happen, then no worries, we can simply navigate to the metrics summary page:

On this page, we can see all the metrics that have been gathered so far. Long story short, this page contains meta-information about metrics themselves, like tags, etc.

I strongly recommend you spend here some time and figure out different options.

And if we would like to take a look at the actual values, then let’s navigate to the metrics explorer:

I know, the image is quite small (the “Open Image in New Tab” option will help here 😉 ). However, the only thing we need to do here is to specify the metric name in the left upper part and the period we would like to view in the right upper part.

After that, we will see the above chart.

And basically, that’s how metrics work with Spring Boot and Datadog, but please don’t close this article yet, I wanted to show you two, interesting things that may be useful to you in real life.

Sending Custom Tags

Tags are nothing else, than additional metadata you can send with metrics.

Why are they useful? Well, thanks to them we can later differentiate different metrics. For example, we can send a tag with the application name, so that later we will group metrics by microservices, or environment value, like dev, staging, or prod.

In Spring Boot, we have several ways to achieve that. And probably the easiest way is to (again) update the application.yaml:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        api-key: YOUR_KEY_VALUE 
        uri: https://api.datadoghq.eu
        step: 10s
  metrics:
    tags:
      application: "my-app-one"

As we can see, we can add a custom tag by using metrics.tags and specifying that as a key-value pair. In our case- the application tag has the my-app-one value.

This approach is not only straightforward but also quite flexible. We could always put a placeholder for the environment variable instead of the hardcoded value.

Anyway, when we rerun our application and let Spring send some metrics to the Datadog, we will see that from now on we can filter values using the “from” field:

Again, the “Open Image in New Tab” may be helpful here 😉

Turn Off Metrics Export

As the last thing, let’s take a look at how we can instruct our Spring app to stop sending metrics to Datadog.

Again, let’s navigate to the application.yaml file and set the enabled flag to false:

management:
  endpoints:
    web:
      exposure:
        include: metrics, health
  datadog:
    metrics:
      export:
        enabled: false
        api-key: YOURE_KEY_VALUE
        uri: https://api.datadoghq.eu
        step: 10s

Of course, we can use an environment variable placeholder (like ${DATADOG_ENABLED}) and turn on/off export in different environments.

Summary

That’s all for this tutorial on how to send Spring Boot metrics to Datadog.

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

Have a great day and don’t forget to leave a comment! 😀

The post Sending Spring Boot Metrics to Datadog appeared first on Codersee blog- Kotlin on the backend.

As an example, we will implement a simple logic responsible for querying the GitHub API using coroutines. Nevertheless, I am pretty sure you will be able to easily adjust this article to your needs. (of course, if you are here only for the WireMock part, then I recommend skipping to the “WebClient Integration Testing With WireMock” chapter).

Lastly, I just wanted to add that you can use this testing approach regardless of whether you are using WebClient, Retrofit, Ktor Client, or any other HTTP client.

Video Tutorial

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

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

Which WebClient Testing Strategy Is The Best?

But before we head to the practice part, let’s try to answer the above question.

Quick answer- there is no such thing as the best testing strategy.

And for the longer answer, let’s take a look at the visualization of the testing pyramid first:

The tests are ordered based on their scope and execution time. The closer we are to the top, the longer the tests take, but they also give us more confidence.

• unit tests form the base, as they are quick to run and pinpoint specific code issues,
• integration tests come next, validating the interactions between units,
• E2E tests, with a broader scope, are placed at the top.

So long story short, although the e2e tests give us the most confidence, we cannot rely only on them, because the feedback loop would take way too long. And this would affect the development process.

So usually, we make concessions and introduce more integration and unit tests.

But which of these two should we pick for the WebClient?

In my opinion- integration tests.

Whenever we are talking about logic responsible for communicating with external API, we must make sure that:

• we query the appropriate URL,
• we pass the necessary headers with appropriate values,
• request/response bodies are properly serialized/deserialized,
• and many, many more.

With unit testing, the amount of mocking here would be so significant that I would question whether we need such a test at all.

Moreover, in Spring we can write integration tests for WebClient with WireMock at almost no effort.

Set Up GitHub API Key

With that said, let’s set up the API key we will use to query the GitHub API.

Note: technically, the endpoint we will use does not require any token. However, for the learning purposes I want to show you how to deal with passing bearer tokens, too 🙂

As the first step, let’s navigate to the tokens tab in GitHub settings and click the “Generate new token (classic)”:

On the next page, let’s specify the name, expiration, and desired scopes:

If you don’t know what scopes you will need, please follow the principle of lowest privilege. At the end of the day, we can generate a new token at some point in the future when the requirements change.

When we are ready, let’s hit the generate button copy the token value, and store it securely. We will not see it again!

Query The Api With WebClient

Before we implement the WireMock tests, let’s prepare a simple project responsible for querying the external API with WebClient. So, even if you are here only for the WireMock part, I encourage you to briefly check this paragraph to be on the same page 😉

Long story short, we will implement WebClient with coroutines that will query the “List repositories for a user” endpoint. For more details about it, check out the GitHub API documentation, please.

Generate New Project

As the first step, let’s navigate to the https://start.spring.io/ page and generate a fresh Spring Boot project:

In general, the most important thing is that we will use Kotlin and Spring Reactive Web this time. Versions and metadata are totally up to you.

Of course, let’s click the “Generate” button, download the ZIP file, and import that to our IDE. Personally, I am using IntelliJ IDEA and if you would like to learn more about its setup, then check out my video on how to install IntelliJ for Kotlin development.

Update Application Properties

As the next step, let’s navigate to the resources package and update the application.yaml file:

api:
  github:
    key: ${GITHUB_API_TOKEN:123}
    url: ${GITHUB_API_BASE_URL:http://localhost:8090}
    version: ${GITHUB_API_VERSION:2022-11-28}

Above we can see our custom properties.

We will source values for our GitHub key, URL, and version from environment variables.

Not only is this approach secure (hardcoding the key with token value would be the worst thing you could do), but also flexible (we can pass different values depending on the environment we are running our app in).

WebClient Configuration

Following, let’s configure a WebClient bean that we will use whenever we want to call the GitHub API.

Firstly, let’s add the config package and put the GitHubApiProperties data class in there:

@ConfigurationProperties("api.github")
data class GitHubApiProperties(
    val url: String,
    val key: String,
    val version: String,
)

In my opinion, the @ConfigurationProperties annotation is the cleanest way to inject values from properties. As we can see above, the prefix and field names simply reflect the structure from the previous step.

With that done, let’s add the GitHubApiConfig in the same package:

@Configuration
@EnableConfigurationProperties(GitHubApiProperties::class)
class GitHubApiConfig(
    private val gitHubApiProperties: GitHubApiProperties,
) {
    @Bean
    fun webClient(builder: WebClient.Builder): WebClient =
        builder
            .baseUrl(gitHubApiProperties.url)
            .defaultHeader("Authorization", "Bearer ${gitHubApiProperties.key}")
            .defaultHeader("X-GitHub-Api-Version", gitHubApiProperties.version)
            .defaultHeader("Accept", "application/vnd.github+json")
            .build()
}

Quite a few things are happening here, so let’s dive into each one.

Firstly, we annotate the class with @Configuration and @EnableConfigurationproperties. The second annotation is necessary to for the previous steps to work.

Then, we inject the GitHubApiProperties instance and use its values to configure a new WebClient bean. This configuration is quite straightforward. We set the base URL and a bunch of headers that will be sent with every request: the authorization token, GH API version, and the accept header (those two are specific to the GitHub API, so let’s focus on that too much).

Prepare Model Classes

With that done, let’s prepare a bunch of data classes that we will need to deserialize JSON responses from the API (+ one exception class). If you would like to add other fields, please check out the documentation link I shared with you before.

As the first step, let’s add the model package and the PageableGitHubResponse:

data class PageableGitHubResponse<T>(
    val items: List<T>,
    val hasMoreItems: Boolean,
)

The API endpoints allow us to get only a chunk of data using the page and per_page parameters. And this class can be reused whenever we’re using a paginated endpoint.

As the next step, let’s implement the GitHubRepoResponse along with GitHubOwnerResponse:

data class GitHubRepoResponse(
    val fork: Boolean,
    val name: String,
    val owner: GitHubOwnerResponse,
)

data class GitHubOwnerResponse(
    val login: String,
)

As I mentioned at the beginning of this paragraph, we need those two in order to deserialize the actual JSON response payload.

Lastly, let’s add the UpstreamApiException:

import org.springframework.http.HttpStatusCode

data class UpstreamApiException(
    val msg: String,
    val statusCode: HttpStatusCode,
) : RuntimeException(msg)

This way, we will be able to throw custom exceptions. Such an exception could be handled later, for example with @RestControllerAdvice.

Make Use Of WebClient

Finally, let’s combine all of that together.

So, let’s add the api package and implement the GitHubApi class:

@Component
class GitHubApi(
  private val webClient: WebClient,
) {

  suspend fun listRepositoriesByUsername(
    username: String,
    page: Int,
    perPage: Int,
  ): PageableGitHubResponse<GitHubRepoResponse>? =
    webClient.get()
      .uri("/users/$username/repos?page=$page&per_page=$perPage")
      .awaitExchangeOrNull(::mapToPageableResponse)
}

Don’t worry about the mapToPageableResponse, we will add it in a moment.

But before that, let’s analyze the above code.

Firstly, we annotate the class as the @Component to make it a Spring bean and inject the WebClient instance we configured earlier. We don’t have other WebClient instances, so there is no need to use @Qualifier or anything like that.

Following, we add the listRepositoriesByUsername function that lets us pass the username along with page and perPage. This way, we make this function reusable and allow the invoker to decide how to tackle the pagination.

Additionally, we mark it as a suspend function because the awaitExchangeOrNull is a suspend function. However, if you are interested in this topic, then I refer you to my other article about WebClient with coroutines.

Lastly, let’s add the missing code:

private suspend inline fun <reified T> mapToPageableResponse(clientResponse: ClientResponse): PageableGitHubResponse<T>? {
  val hasNext = checkIfMorePagesToFetch(clientResponse)

  return when (val statusCode = clientResponse.statusCode()) {
    HttpStatus.OK ->
      PageableGitHubResponse(
        items = clientResponse.awaitBody<List<T>>(),
        hasMoreItems = hasNext,
      )

    HttpStatus.NOT_FOUND -> null

    else -> throw UpstreamApiException(
      msg = "GitHub API request failed.",
      statusCode = statusCode,
    )
  }
}

fun checkIfMorePagesToFetch(clientResponse: ClientResponse) =
  clientResponse.headers()
    .header("link")
    .firstOrNull()
    ?.contains("next")
    ?: false

Long story short, the above code works as follows:

1. Firstly, we take the response and check if there are more pages. How? Well, without going into details, GitHub API returns the link header. And if its value contains the rel="next", it means that there are more pages to fetch.
2. Finally, we check the status code. If it is 200 OK, we simply read the JSON value. When we get 404 Not Found, we return null (we can expect this status code when we pass a non-existing username, and in my opinion, this case is not exceptional). And whenever we receive another status code, we simply throw the UpstreamApiException.

WebClient Integration Testing With WireMock

Excellent, at this point we have (almost) everything we need to test our WebClient implementation with WireMock.

We will see only a few example test cases that you will be able to easily adapt according to your needs:

• 200 OK response with an empty list, 200 OK with items, and more pages, and 200 OK with items and no more pages to fetch
• 404 Not Found,
• 401 Unauthorized

When you will be implementing your own integration tests, this is the moment when you should do the homework and analyze the API you are working with. What are the possible happy paths? How should your code behave in case of any error status code? What if we add some latency? And many, many more 🙂

Additional Dependencies

At this point, we defined our test cases, so we are ready to get our hands dirty.

So, let’s start by adding the necessary dependencies:

testImplementation("org.springframework.cloud:spring-cloud-contract-wiremock:4.1.1")
testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")

As we can see, the first one- the Spring Cloud Contract WireMock module- allows us to use WireMock in our app, whereas the kotlinx-coroutines-test is necessary due to our coroutines WebClient implementation.

Add Expected JSON Files

So, if we know what test cases we would like to test, we should prepare the example JSON API responses.

Personally, whenever working with WireMock I am a big fan of externalizing the expected JSON files. We put them inside the /test/resources directory and refer to them later in the tests. This way, we can improve the readability of the test classes. Of course, unless we want to prepare JSON responses dynamically.

In our case, we could simply invoke the GitHub API and persist responses for different cases. This way, we prepare the following files and put them inside the /test/resources/responses/external/github:

• list_github_repositories_200_OK_empty_list.json
• list_github_repositories_200_OK_page_1.json
• list_github_repositories_401_UNAUTHORIZED.json
• list_github_repositories_404_NOT_FOUND.json

You can find all of these files in my GH repo here.

The example for 401 Unauthorized looks as follows:

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

Prepare Util Function

As the last thing before we implement our test class, let’s add the util function inside the util package (of course, in tests).

This function will be responsible for reading JSON files inside the test resources as String values:

import org.springframework.core.io.ClassPathResource

fun getResponseBodyAsString(path: String): String =
    ClassPathResource(path).getContentAsString(
        Charsets.UTF_8,
    )

Implement GitHubApiTest Class

Finally, let’s start implementing the GitHubApiTest class:

private const val TEST_KEY = "TEST_KEY"
private const val TEST_PORT = 8082
private const val TEST_VERSION = "2022-11-28"

@AutoConfigureWireMock(port = TEST_PORT)
@TestPropertySource(
  properties = [
    "api.github.url=http://localhost:${TEST_PORT}",
    "api.github.key=$TEST_KEY",
    "api.github.version=$TEST_VERSION",
  ],
)
@SpringBootTest(
  webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
)
class GitHubApiTest {
  @Autowired
  private lateinit var wireMockServer: WireMockServer

  @Autowired
  private lateinit var gitHubApi: GitHubApi

  private val page = 1
  private val perPage = 2
  private val username = UUID.randomUUID().toString()

}

Conceptually, everything starts with the @SpringBootTest and @AutoConfigureWireMock annotations.

We use the @SpringBootTest annotation in Spring Boot integration tests. This way a new ApplicationContext will be created. In our case, we set the webEnvironment with RANDOM_PORT value, so that a reactive context listening on the random port is created.

Additionally, we combine that together with @AutoConfigureWireMock and fixed test port. This way a WireMock server will be started as a part of Application Context.

Lastly, we do 3 things:

1. We use the @TestPropertySource to pass values for properties.
2. We inject the WireMockServer and GitHubApi instances that we will work with later. Please note that we can do that just like we would do with a standard, non-test, Spring component.
3. We prepare some dummy data for page, perPage, and username values we will need for testing.

As a note of comment from my side- this “skeleton” is useful whenever working with WebClient and WireMock.

Test 404 Not Found API Response Case

Wonderful!

As the first test, let’s start with the 404 Not Found case. Usually, we will start with happy path cases, but for learning purposes, this one is the shortest case 😉

@Test
fun `Given 404 NOT FOUND response When fetching repository by username Then should return null`() = runTest {
  // Given
  wireMockServer.stubFor(
    WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
      .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
      .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
      .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
      .willReturn(
        WireMock.aResponse()
          .withStatus(HttpStatus.NOT_FOUND.value())
          .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
          .withBody(
            getResponseBodyAsString("/responses/external/github/list_github_repositories_404_NOT_FOUND.json"),
          ),
      ),
  )

  // When
  val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

  // Then
  Assertions.assertNull(result)
}

We mark our test with the @Test (JUnit 5), specify the meaningful name for the test (with awesome Kotlin backticks), and wrap our test with runTest. The last one is necessary as we are working with coroutines and invoke the suspended function. Long story short, in JVM it will behave just like runBlocking (but it will skip delays).

Next comes the WireMock part. And to be even more specific- stubbing.

Stubbing is nothing else than “the ability to return canned HTTP responses for requests matching criteria” (from docs). Simply said, whenever an outgoing request that matches our criteria is made, a mocked response configured in willReturn is returned.

So, as we can see, the above logic will work only when:

• the GET request is made,
• URL matches,
• Headers sent have appropriate values

And this part already tests our logic. Pretty neat, isn’t it? 🙂

Lastly, we simply invoke the function and assert that null is returned. Which confirms that everything is working fine.

Test 401 Unauthorized

As we already started with error cases, let’s verify that whenever the endpoint returns 401 Unauthorized, the UpstreamApiException is thrown:

@Test
fun `Given 401 UAUTHORIZED response When fetching repository by username Then should throw UpstreamApiException`() = runTest {
  // Given
  wireMockServer.stubFor(
    WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
      .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
      .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
      .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
      .willReturn(
        WireMock.aResponse()
          .withStatus(HttpStatus.UNAUTHORIZED.value())
          .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
          .withBody(
            getResponseBodyAsString("/responses/external/github/list_github_repositories_401_UNAUTHORIZED.json"),
          ),
      ),
  )

  // When
  val exception = assertThrows<UpstreamApiException> {
    gitHubApi.listRepositoriesByUsername(username, page, perPage)
  }

  // Then
  assertNotNull(exception)

  assertEquals("GitHub API request failed.", exception.msg)
  assertEquals(HttpStatus.UNAUTHORIZED, exception.statusCode)
}

As we can see, the logic responsible for stubbing only slightly changed.

The interesting part here is the assertThrows, which not only makes sure that the exception of an appropriate type is thrown but also returns it. This way we can make additional assertions.

Verify 200 OK With Empty List

Following, let’s cover the empty list case:

@Test
fun `Given 200 OK response with empty list When fetching repository by username Then should return repository with correct properties and has next false`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="prev","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_empty_list.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items = emptyList<GitHubRepoResponse>(),
        hasMoreItems = false,
      )

    assertEquals(expected, result)
  }

This time, we assign the returned value to the result and compare that with the expected.

Check 200 OK With Has Next True

Last before least, let’s make sure that we got the expected objects in a list and that the logic responsible for the link header check returns true:

@Test
fun `Given 200 OK response with payload When fetching repository by username Then should return repository with correct properties and has next true`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="next","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_page_1.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items =
        listOf(
          GitHubRepoResponse(
            fork = false,
            name = "controlleradvice-vs-restcontrolleradvice",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
          GitHubRepoResponse(
            fork = false,
            name = "freecodecamp-spring-boot-kotlin-excel",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
        ),
        hasMoreItems = true,
      )

    assertEquals(expected, result)
  }

Test 200 OK With Has Next False

And finally, let’s double-check the flag logic:

@Test
fun `Given 200 OK response with payload When fetching repository by username Then should return repository with correct properties and has next false`() =
  runTest {
    // Given
    val linkHeader = """<https://api.github.com/user/64011387/repos?page=3&per_page=2>; rel="prev","""

    wireMockServer.stubFor(
      WireMock.get(WireMock.urlEqualTo("/users/$username/repos?page=$page&per_page=$perPage"))
        .withHeader("Authorization", WireMock.equalTo("Bearer $TEST_KEY"))
        .withHeader("X-GitHub-Api-Version", WireMock.equalTo(TEST_VERSION))
        .withHeader("Accept", WireMock.equalTo("application/vnd.github+json"))
        .willReturn(
          WireMock.aResponse()
            .withStatus(HttpStatus.OK.value())
            .withHeader(HttpHeaders.CONTENT_TYPE, "application/json; charset=utf-8")
            .withHeader(HttpHeaders.LINK, linkHeader)
            .withBody(
              getResponseBodyAsString("/responses/external/github/list_github_repositories_200_OK_page_1.json"),
            ),
        ),
    )

    // When
    val result = gitHubApi.listRepositoriesByUsername(username, page, perPage)

    // Then
    val expected =
      PageableGitHubResponse(
        items =
        listOf(
          GitHubRepoResponse(
            fork = false,
            name = "controlleradvice-vs-restcontrolleradvice",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
          GitHubRepoResponse(
            fork = false,
            name = "freecodecamp-spring-boot-kotlin-excel",
            owner = GitHubOwnerResponse(login = "codersee-blog"),
          ),
        ),
        hasMoreItems = false,
      )

    assertEquals(expected, result)
  }

Integration Tests With WireMock And WebClient Summary

And basically, that’s all for this tutorial on how to perform integration testing for Spring WebClient that invokes external REST APIs with WireMock and JUnit 5.

I hope you enjoyed this one and I recommend you check out my other articles related to Spring Framework.

The post Integration Tests for WebClient with WireMock appeared first on Codersee blog- Kotlin on the backend.

In this article, I will show you four ideas on how to solve this issue.

Please keep in mind that all of them are workarounds, and if you came up with something even better, then do not forget to share in the comments🙂

Video Tutorial

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

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

Problem

To be on the same page, let’s take a quick look at a simple Spring Boot configuration with @ConfigurationProperties.

Firstly, let’s navigate to the application.yaml file:

example:
  some-property: ${SOME_VARIABLE}

As we can see, we defined a new property inside our config file for which the value should be set from the environment variable named SOME_VARIABLE.

Following, let’s introduce the @ConfigurationProperties class:

@ConfigurationProperties(prefix = "example")
data class ExampleConfigurationProperties(
  val someProperty: String
)

With this code, we expect that Spring Framework will read all properties defined in the configuration file and inject values into the matching properties.

Note: Spring recognizes the kebab case (some-property) and matches it with the property using camel case (someProperty)

After that, we need to explicitly inform Spring about our configuration properties class:

@Configuration
@EnableConfigurationProperties(ExampleConfigurationProperties::class)
class Config

Lastly, we must add a class, which injects the ExampleConfigurationProperties and prints out the value of someProperty:

@Component
class SomeComponent(
  private val properties: ExampleConfigurationProperties
) {

  @PostConstruct
  fun init() {
    println(properties.someProperty)
  }

}

Finally, when we run our application without the SOME_VARIABLE environment variable missing, we will see the following output:

${SOME_VARIABLE}

A bit counterintuitive, right?

It would seem pretty obvious, that if we declare someProperty as a non-nullable String and environment variable is missing, our Spring Boot app should fail to start.

Unfortunately, that’s not the case when using @ConfigurationProperties and Spring will default the String value to the name of placeholder.

Moreover, at the moment of writing, there is no built-in way we could enforce that.

Solution With Spring Validation

As a first solution (or rather workaround), let’s add the spring-boot-starter-validation to our project:

implementation("org.springframework.boot:spring-boot-starter-validation")

Nextly, let’s instruct Spring that it should default to the blank String value whenever our environment variable is missing:

example:
  some-property: ${SOME_VARIABLE:}

After that let’s modify our configuration properties class:

import jakarta.validation.constraints.NotBlank
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.validation.annotation.Validated

@ConfigurationProperties(prefix = "example")
@Validated
data class ExampleConfigurationProperties(
  @field:NotBlank val someProperty: String
)

As we can see, with a combination of @Validated and @NotBlank, we ask Spring Framework to check if the value is not null and contains at least one non-whitespace character.

Note: in Kotlin, we must use the @field: to annotate Java field.

If you would like to learn this, and many more then check out my Kotlin course.

Finally, when we try to run our application, we will see the following:

***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target org.springframework.boot.context.properties.bind.BindException: Failed to bind properties under 'example' to com.codersee.properties.ExampleConfigurationProperties failed:

    Property: example.someProperty
    Value: ""
    Origin: class path resource [application.yaml] - 2:18
    Reason: must not be blank


Action:

Update your application's configuration


Process finished with exit code 1

And maybe this solution is nott ideal, but it does its job.

And it is neat. Not only does the application not start, but also whenever the environment variable for our @ConfigurationProperties is missing, we will see a meaningful message that will speed up the debugging process.

Custom ApplicationRunner Idea

Another solution for our problem does not require any additional dependencies added to our project.

Let’s take a look at the following implementation of ApplicationRunner:

import org.springframework.boot.ApplicationArguments
import org.springframework.boot.ApplicationRunner
import org.springframework.stereotype.Component

@Component
class MyApplicationRunner : ApplicationRunner {

  companion object {
    private val requiredVariables = setOf(
      "SOME_VARIABLE"
    )
  }

  override fun run(args: ApplicationArguments) {
    requiredVariables.forEach {
      System.getenv(it)
        ?: throw MissingEnvVariableException(it)
    }
  }

}

class MissingEnvVariableException(variableName: String) :
  RuntimeException("Application failed to start. Missing environment variable: $variableName")

This time, we introduce our set of required environment variables and check if they are present.

Whenever it’s missing, we throw the MissingEnvVariableException and prevent the app from starting:

java.lang.IllegalStateException: Failed to execute ApplicationRunner
	at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:765) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.callRunners(SpringApplication.java:752) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:319) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1306) ~[spring-boot-3.1.3.jar:3.1.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1295) ~[spring-boot-3.1.3.jar:3.1.3]
	at com.codersee.properties.PropertiesApplicationKt.main(PropertiesApplication.kt:13) ~[main/:na]
Caused by: com.codersee.properties.MissingEnvVariableException: Application failed to start. Missing environment variable: SOME_VARIABLE
	at com.codersee.properties.MyApplicationRunner.run(MyApplicationRunner.kt:19) ~[main/:na]
	at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:762) ~[spring-boot-3.1.3.jar:3.1.3]
	... 5 common frames omitted


Process finished with exit code 1

This solution gives us a bit more control and allows us to customize the behavior better.

Would we like to log an error, or maybe send an alert request? No problem. With a few lines of code, we can easily achieve that.

Nevertheless, with this approach, we introduce a new, separate place in the code we need to remember every time we want to add a new environment variable. And this might be easily forgotten in bigger projects.

Fix With @Conditional

As the next step, let’s take a look at the approach with @Conditional annotation, which slightly reduces the chance of forgetting about additional checks.

Firstly, let’s add a new class called RequiredEnvVariablesCondition:

class RequiredEnvVariablesCondition : Condition {

  private val logger: Logger = LogManager.getLogger(this::class.java)

  companion object {
    private val requiredVariables = setOf(
      "SOME_VARIABLE"
    )
  }

  override fun matches(context: ConditionContext, metadata: AnnotatedTypeMetadata): Boolean {
    val isEnvVariableMissing = requiredVariables
      .any { envVariableName ->
        val isMissing = System.getenv(envVariableName) == null

        if (isMissing)
          logger.error("Variable $envVariableName is missing!")

        isMissing
      }

    return !isEnvVariableMissing
  }

}

As we can see, this logic is pretty similar to what we’ve done previously.

Every time the environment variable is missing, we log an error message and return false from the overridden matches function.

So with that done, we can annotate our config class with @Conditional:

import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Conditional
import org.springframework.context.annotation.Configuration

@Configuration
@EnableConfigurationProperties(ExampleConfigurationProperties::class)
@Conditional(RequiredEnvVariablesCondition::class)
class Config

This time, we will get the following output if we try to run the app without passing the environment variable:

2023-09-14T07:20:58.813+02:00 ERROR 16188 --- [           main] c.c.p.RequiredEnvVariablesCondition      : Variable SOME_VARIABLE is missing!

***************************
APPLICATION FAILED TO START
***************************

Description:

Parameter 0 of constructor in com.codersee.properties.SomeComponent required a bean of type 'com.codersee.properties.ExampleConfigurationProperties' that could not be found.


Action:

Consider defining a bean of type 'com.codersee.properties.ExampleConfigurationProperties' in your configuration.


Process finished with exit code 1

(Bonus) Use @Value Instead

There’s no doubt that @ConfigurationProperties helps us write cleaner code and better organize configuration in our codebase. Moreover, we can effortlessly add new values to the project with this approach.

However, in some cases, we should consider using @Value annotation instead:

package com.codersee.properties

import jakarta.annotation.PostConstruct
import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Component

@Component
class SomeComponent(
  @Value("\${example.some-property}") private val someProperty: String
) {

  @PostConstruct
  fun init() {
    println(someProperty)
  }
}

This time, we can completely get rid of @Configuration and @ConfigurationProperties classes.

Instead of injecting a whole configuration object, we focus on the desired config value.

And whenever it’s missing, we get the following output out of the box:

Error starting ApplicationContext. To display the condition evaluation report re-run your application with 'debug' enabled.
2023-09-14T07:16:43.532+02:00 ERROR 18412 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'someComponent' defined in file: Unexpected exception during bean creation
...
Caused by: java.lang.IllegalArgumentException: Could not resolve placeholder 'SOME_VARIABLE' in value "${SOME_VARIABLE}"
...
Process finished with exit code 1

As we can see, our Spring Boot app won’t start if the environment variable is missing and we will get a meaningful message.

But again, we should use @Value wisely and most of the time @ConfigurationProperties can be a better approach.

Summary

And that’s all for this article on how to fail a Spring Boot app on missing environment variables.

As I mentioned in the beginning- these are just a few ideas that came to my mind. If you figure out some other way, then please share them in the comments section below.

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

Thank you for reading, and see you next time! 🙂

The post Fail Spring Boot App on Missing Environment Variables 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.

Hello friend! 🙂 Welcome to my next practical tutorial, in which I will show you how to expose web endpoints using Spring Boot 3 and Kotlin router DSL (aka- functional style).

Basically, the Kotlin router DSL comes in 3 variants:

• WebMvc.fn DSL using router { } – which we can use when working with a “standard” MVC Spring Project,
• WebFlux.fn Reactive DSL with router { } – used when working with a reactive-stack framework- Spring Webflux,
• WebFlux.fn Coroutines DSL with coRouter { } – as the name suggests- the one we will use when working with coroutines.

And although in this article, we will make use of the coroutine-based REST API implemented in “Reactive REST API With Spring, Kotlin, and Coroutines“, the knowledge you’re gonna gain today is universal and will work regardless of the implementation.

Video Tutorial

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

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

2. Project Configuration

As I mentioned in the introduction, we will reuse the already implemented API and rewrite the @RestController approach using the Spring Boot Kotlin DSL router.

[elementor-template id=”9007393″]

So, as the first step, let’s clone this GitHub repository.

When we navigate to the controller package, we will see that the project contains 3 controllers:

• UserController
• SearchController
• CompanyController

And for the purpose of this tutorial, we will focus on the API responsible for users management:

@RestController
@RequestMapping("/api/users")
class UserController(
    private val userService: UserService
) {

  @PostMapping
  suspend fun createUser(@RequestBody userRequest: UserRequest): UserResponse =
    userService.saveUser(
        user = userRequest.toModel()
    )
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

  @GetMapping
  suspend fun findUsers(
    @RequestParam("name", required = false) name: String?
  ): Flow {
    val users = name?.let { userService.findAllUsersByNameLike(name) }
      ?: userService.findAllUsers()

    return users.map(User::toResponse)
  }

  @GetMapping("/{id}")
  suspend fun findUserById(
    @PathVariable id: Long
  ): UserResponse =
    userService.findUserById(id)
      ?.let(User::toResponse)
      ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

  @DeleteMapping("/{id}")
  suspend fun deleteUserById(
    @PathVariable id: Long
  ) {
    userService.deleteUserById(id)
  }

  @PutMapping("/{id}")
  suspend fun updateUser(
    @PathVariable id: Long,
    @RequestBody userRequest: UserRequest
  ): UserResponse =
    userService.updateUser(
      id = id,
      requestedUser = userRequest.toModel()
    )
      .toResponse()
}

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

fun User.toResponse(): UserResponse =
  UserResponse(
    id = this.id!!,
    email = this.email,
    name = this.name,
    age = this.age
  )

3. Convert UserController To Handler

Before we will start working with Spring Boot Kotlin DSL, let’s make a few adjustments.

Firstly, let’s add a new package called handler.

Then, let’s remove all annotations inside the class and mark the UserHandler with @Component:

@Component
class UserHandler(
    private val userService: UserService
) {

  suspend fun createUser(userRequest: UserRequest): UserResponse =
    userService.saveUser(
      user = userRequest.toModel()
    )
      ?.toResponse()
      ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

  suspend fun findUsers(
    name: String?
  ): Flow {
    val users = name?.let { userService.findAllUsersByNameLike(name) }
      ?: userService.findAllUsers()

    return users.map(User::toResponse)
  }

  suspend fun findUserById(
    id: Long
  ): UserResponse =
    userService.findUserById(id)
      ?.let(User::toResponse)
      ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

  suspend fun deleteUserById(
    id: Long
  ) {
    userService.deleteUserById(id)
  }

  suspend fun updateUser(
    id: Long,
    userRequest: UserRequest
  ): UserResponse =
    userService.updateUser(
      id = id,
      requestedUser = userRequest.toModel()
    )
      .toResponse()
}

4. Implement Coroutines router with Kotlin DSL

With all of that being done, let’s create a new class Config inside the config package:

@Configuration
class Config {

  @Bean
  fun router(
    userHandler: UserHandler
  ) = coRouter {
    accept(MediaType.APPLICATION_JSON).nest {

      "/api/users".nest {
        POST("", userHandler::createUser)
        GET("", userHandler::findUsers)
        GET("/{id}", userHandler::findUserById)
        DELETE("/{id}", userHandler::deleteUserById)
        PUT("/{id}", userHandler::updateUser)
      }

    }
  }

}

As I mentioned in the beginning when working with coroutines, we will create a RouterFunction using coRouter{ }. Nevertheless, when working with MVC or Spring WebFlux, then the choice would be the router {}.

As we can see, the nest {} function allows us to structure routing in a neat and readable manner.

Let’s take a look at the following example:

"/api/v1".nest {
  "/whatever".nest {
    "/sub-whatever".nest {
      // whatever
    }
  }
}

"/api/v2".nest {
  // another handlers
}

This way, we can manage versioning in one place.

Nevertheless, let’s get back to our user handlers:

POST("", userHandler::createUser)
GET("", userHandler::findUsers)
GET("/{id}", userHandler::findUserById)
DELETE("/{id}", userHandler::deleteUserById)
PUT("/{id}", userHandler::updateUser)

At this point, our application won’t compile, because of one, important thing- handler functions must take only one parameter of the ServerRequest type.

So in order to fix the app, we will have to update our Spring controller for functional routing.

5. Update POST Endpoint

So as the first step, let’s make the necessary adjustments to the createUser:

suspend fun createUser(request: ServerRequest): ServerResponse {
  val userRequest = request.awaitBody(UserRequest::class)

  val savedUserResponse = userService.saveUser(
    user = userRequest.toModel()
  )
    ?.toResponse()
    ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

  return ServerResponse.ok()
    .bodyValueAndAwait(savedUserResponse)
}

// Before:


@PostMapping
suspend fun createUser(@RequestBody userRequest: UserRequest): UserResponse =
  userService.saveUser(
    user = userRequest.toModel()
  )
    ?.toResponse()
    ?: throw ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error during user creation.")

As we can see, instead of binding the JSON payload to the UserRequest instance with an annotation, we have to do it manually with .awaitBody().

Whatsoever, the return type changes to ServerResponse, which we have to create manually.

And although the final choice is up to you, instead of throwing the ResponseStatusException, we can compose the HTTP error response on our own:

suspend fun createUser(request: ServerRequest): ServerResponse {
  val userRequest = request.awaitBody(UserRequest::class)

  return userService.saveUser(
    user = userRequest.toModel()
  )
    ?.toResponse()
    ?.let { response ->
      ServerResponse.ok()
        .bodyValueAndAwait(response)
    }
    ?: ServerResponse.status(HttpStatus.INTERNAL_SERVER_ERROR)
      .buildAndAwait()
}

6. Migrate GET All Users

Nextly, let’s migrate the findUsers() function and learn how to read query parameters:

suspend fun findUsers(
  request: ServerRequest
): ServerResponse {
  val users = request.queryParamOrNull("name")
    ?.let { name -> userService.findAllUsersByNameLike(name) }
    ?: userService.findAllUsers()

  val usersResponse = users.map(User::toResponse)

  return ServerResponse.ok()
    .bodyAndAwait(usersResponse)
}

// Before:

@GetMapping
suspend fun findUsers(
  @RequestParam("name", required = false) name: String?
): Flow {
  val users = name?.let { userService.findAllUsersByNameLike(name) }
    ?: userService.findAllUsers()

  return users.map(User::toResponse)
} 

This time, in order to read a particular query parameter, we can use the queryParamOrNull(String). However, the ServerRequest interface comes with two, additional functions, which we could use here:

• queryParam(String), which returns the Optional,
• and queryParams() returning an instance of MultiValueMap<String, String> with all parameters.

And just, like previously we compose a ServerResponse instance, but this time using the bodyAndAwait(), which takes a Flow as an argument.

7. GET User By Id

As the next example in our Spring Boot Kotlin DSL project, let’s rewrite the findUserById() and see how we can read a path variable:

suspend fun findUserById(
  request: ServerRequest
): ServerResponse {
  val id = request.pathVariable("id").toLong()

  val userResponse = userService.findUserById(id)
    ?.let(User::toResponse)
    ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

  return ServerResponse.ok()
    .bodyValueAndAwait(userResponse)
}

// Before:

@GetMapping("/{id}")
suspend fun findUserById(
  @PathVariable id: Long
): UserResponse =
  userService.findUserById(id)
    ?.let(User::toResponse)
    ?: throw ResponseStatusException(HttpStatus.NOT_FOUND, "User with id $id was not found.")

As we can see, in order to read the path variable, we have to use the pathVariable(String) (or alternatively, pathVariables()). Unfortunately, this function cannot be parametrized and we have to take care of Long conversions manually.

8. DELETE Endpoint

Following, let’s update the deleteUserById():

suspend fun deleteUserById(
  request: ServerRequest
): ServerResponse {
  val id = request.pathVariable("id").toLong()

  userService.deleteUserById(id)

  return ServerResponse.noContent()
    .buildAndAwait()
}

// Before: 

@DeleteMapping("/{id}")
suspend fun deleteUserById(
  @PathVariable id: Long
) {
  userService.deleteUserById(id)
}

And this time, instead of returning anything in the response payload, we make use of the noContent() along with buildAndAwait() to return a bodiless entity.

9. User Update With PUT

Lastly, let’s make the necessary adjustments to the updateUser():

suspend fun updateUser(
  request: ServerRequest
): ServerResponse {
  val id = request.pathVariable("id").toLong()
  val userRequest = request.awaitBody(UserRequest::class)

  val userResponse = userService.updateUser(
    id = id,
    requestedUser = userRequest.toModel()
  ).toResponse()

  return ServerResponse.ok()
    .bodyValueAndAwait(userResponse)
}

// Before:

@PutMapping("/{id}")
suspend fun updateUser(
  @PathVariable id: Long,
  @RequestBody userRequest: UserRequest
): UserResponse =
  userService.updateUser(
    id = id,
    requestedUser = userRequest.toModel()
  )
    .toResponse()

As we can see, nothing new shows up in this example.

10. Testing And Homework

With all of that being done, we can finally run our application and verify whether handlers are working, as expected.

Your homework will be to:

1. Test whether the routing works fine after we converter our Spring controller to the functional style.
2. Refactor the CompanyController and SearchController classes in a similar manner.

As a bonus, right here you can find a Postman collection, which you can use for testing.

Note: If you would like to see the solution, then check out the router-dsl branch in my GitHub repo.

11. Spring Boot 3 With Kotlin DSL Summary

And that’s all for this tutorial, in which we have learned how to expose web endpoints using Spring Boot 3 and Kotlin router DSL (aka- functional style).

Hope you enjoyed this content, and if so, then please reach out in the comments section.

Have a great week!

The post Spring Boot 3 Kotlin Router DSL appeared first on Codersee blog- Kotlin on the backend.

Hello friend! In this post, I would like to show you how to solve a pretty common issue when mapping Postgres jsonb to Jackson JsonNode in Spring Data JPA.

If you are not a regular reader of my blog, then I’m pretty sure that you wanted to map a PostgreSQL jsonb field in your Spring Boot with Spring Data JPA application to Jsonnode and you saw something like that:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name ‘entityManagerFactory’ defined in class path resource [org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaConfiguration.class]: Could not determine recommended JdbcType for `com.fasterxml.jackson.databind.JsonNode`

If that’s the case, then you’ve come to the right place. 😁

2. Quick Setup

Before we learn how to solve the issue with Postgres jsonb mapping to JsonNode, let’s take a minute to reproduce the error.

Note: If you would like to cut straight to the point and see how to implement a mapper, then you can skip this part and navigate directly to chapter 3.

2.1. PostgreSQL Table With jsonb column

Firstly, we need to have a PostgreSQL table with jsonb column:

As we can see, it’s just a dummy table called some_table, which contains 4 example columns.

And to be on the same it page, I created it and populated with the following SQL script:

create table some_table(
  id serial not null primary key,
  string_column text not null,
  integer_column smallint not null,
  jsonb_column jsonb not null
);

insert into 
  some_table(string_column, integer_column, jsonb_column)
values
  ('value-1', 1, '{ "some_field": "some_value"}'),
  ('value-2', 2, '{ "another_field": "some_value_2"}');

[elementor-template id=”9007393″]

2.2. Spring Boot and Dependencies

Nextly, let’s create an example Spring Boot project. As always, we can do that with the Spring Initializr page.

Please configure it according to your needs, but do not forget to add the PostgreSQL Driver and Spring Data JPA dependencies. Additionally, we will need to enrich the project with Jackson Databind:

implementation("org.springframework.boot:spring-boot-starter-data-jpa")
implementation("com.fasterxml.jackson.core:jackson-databind:2.14.1")
runtimeOnly("org.postgresql:postgresql")

2.3. application.yaml

With that being done, let’s specify the connection details:

spring:
  datasource:
    url: "jdbc:postgresql://localhost:5432/postgres"
      username: postgres
      password: postgres

2.4. Implement Entity

As the next step, let’s open up the project and add the SomeEntity data class:

@Entity
@Table(name = "some_table")
data class SomeEntity(
  @Id
  val id: Long? = null,
  val stringColumn: String,
  val integerColumn: Int,
  val jsonbColumn: JsonNode
)

As we can see, we use the @Entity annotation to mark the class as the entity and @Table to explicitly provide Spring with the table name. Moreover, the necessary @Id annotation specifies the primary key of our entity and the jsonbColumn will contain the value of the Postgres jsonb column mapped to JsonNode.

2.5. Create JPA repository

With that being done, let’s add the SomeEntityRepository interface:

interface SomeEntityRepository : CrudRepository<SomeEntity, Long>

This time, the only thing we have to do is to extend the CrudRepository interface, which comes with a basic CRUD operations.

2.6. Create JPA repository

Lastly, let’s add the logic, which will be run when the application starts:

@Component
class MyRunner(
  private val repository: SomeEntityRepository
) : CommandLineRunner {

  override fun run(vararg args: String?) {
    repository.findAll()
      .forEach(::println)
  }
}

As we can see, a repository instance will be injected into this simple component. Moreover, we implement the run method of CommandLineRunner, which instructs Spring Boot to run after the app starts (if you would like to learn more about it, then check out my article about the Spring Boot console app).

Finally, we want to print out all entities, nevertheless, such a stack trace appears to our eyes:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'entityManagerFactory' defined in class path resource [org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaConfiguration.class]: Could not determine recommended JdbcType for `com.fasterxml.jackson.databind.JsonNode`
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1751) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(AbstractAutowireCapableBeanFactory.java:599) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBean(AbstractAutowireCapableBeanFactory.java:521) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractBeanFactory.lambda$doGetBean$0(AbstractBeanFactory.java:326) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.DefaultSingletonBeanRegistry.getSingleton(DefaultSingletonBeanRegistry.java:234) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:324) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:200) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.context.support.AbstractApplicationContext.getBean(AbstractApplicationContext.java:1130) ~[spring-context-6.0.2.jar:6.0.2]
at org.springframework.context.support.AbstractApplicationContext.finishBeanFactoryInitialization(AbstractApplicationContext.java:905) ~[spring-context-6.0.2.jar:6.0.2]
at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:584) ~[spring-context-6.0.2.jar:6.0.2]
at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:730) ~[spring-boot-3.0.0.jar:3.0.0]
at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:432) ~[spring-boot-3.0.0.jar:3.0.0]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:308) ~[spring-boot-3.0.0.jar:3.0.0]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1302) ~[spring-boot-3.0.0.jar:3.0.0]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1291) ~[spring-boot-3.0.0.jar:3.0.0]
at com.codersee.jsonbtojsonnode.JsonbToJsonNodeApplicationKt.main(JsonbToJsonNodeApplication.kt:14) ~[main/:na]
Caused by: org.hibernate.type.descriptor.java.spi.JdbcTypeRecommendationException: Could not determine recommended JdbcType for `com.fasterxml.jackson.databind.JsonNode`
at org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType.getRecommendedJdbcType(UnknownBasicJavaType.java:37) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.boot.model.process.internal.InferredBasicValueResolver.from(InferredBasicValueResolver.java:222) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.mapping.BasicValue.buildResolution(BasicValue.java:507) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.mapping.BasicValue.resolve(BasicValue.java:315) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.mapping.BasicValue.resolve(BasicValue.java:305) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.boot.internal.InFlightMetadataCollectorImpl.lambda$processValueResolvers$4(InFlightMetadataCollectorImpl.java:1767) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at java.base/java.util.ArrayList.removeIf(ArrayList.java:1682) ~[na:na]
at java.base/java.util.ArrayList.removeIf(ArrayList.java:1660) ~[na:na]
at org.hibernate.boot.internal.InFlightMetadataCollectorImpl.processValueResolvers(InFlightMetadataCollectorImpl.java:1766) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.boot.internal.InFlightMetadataCollectorImpl.processSecondPasses(InFlightMetadataCollectorImpl.java:1752) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.boot.model.process.spi.MetadataBuildingProcess.complete(MetadataBuildingProcess.java:300) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl.metadata(EntityManagerFactoryBuilderImpl.java:1350) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.hibernate.jpa.boot.internal.EntityManagerFactoryBuilderImpl.build(EntityManagerFactoryBuilderImpl.java:1421) ~[hibernate-core-6.1.5.Final.jar:6.1.5.Final]
at org.springframework.orm.jpa.vendor.SpringHibernateJpaPersistenceProvider.createContainerEntityManagerFactory(SpringHibernateJpaPersistenceProvider.java:66) ~[spring-orm-6.0.2.jar:6.0.2]
at org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean.createNativeEntityManagerFactory(LocalContainerEntityManagerFactoryBean.java:376) ~[spring-orm-6.0.2.jar:6.0.2]
at org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.buildNativeEntityManagerFactory(AbstractEntityManagerFactoryBean.java:409) ~[spring-orm-6.0.2.jar:6.0.2]
at org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.afterPropertiesSet(AbstractEntityManagerFactoryBean.java:396) ~[spring-orm-6.0.2.jar:6.0.2]
at org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean.afterPropertiesSet(LocalContainerEntityManagerFactoryBean.java:352) ~[spring-orm-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.invokeInitMethods(AbstractAutowireCapableBeanFactory.java:1797) ~[spring-beans-6.0.2.jar:6.0.2]
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1747) ~[spring-beans-6.0.2.jar:6.0.2]
... 15 common frames omitted

3. Map Postgres jsonb to JsonNode

So at this point, we can see that Spring “Could not determine recommended JdbcType for `com.fasterxml.jackson.databind.JsonNode`“.

One of the possible solutions is to implement a custom AttributeConverter and mark it with @Converter annotation:

@Converter(autoApply = true)
class MyConverter : AttributeConverter<JsonNode, String> {

  private val mapper = ObjectMapper()

  override fun convertToDatabaseColumn(node: JsonNode): String {
    return node.asText()
  }

  override fun convertToEntityAttribute(data: String): JsonNode {
    return mapper.readTree(data)
  }
}

As we can see, the AttributeConverter interface comes with two methods: convertToDatabaseColumn and convertToEntityAttribute, which will be invoked when mapping between the entity and the database.

Additionally, we have set the autoApply to true (the default is false) to inform the persistence provider that it should use this converter to map between Postgres jsonb and JsonNode. Without it, we would have to explicitly annotate the desired field:

@Convert(converter = MyConverter::class)
val jsonbColumn: JsonNode

Of course, the choice is up to you and may vary depending on your project, but most of the time you would like to choose the first solution.

Finally, if we run the application, we should see that everything is working, as expected and logs contain the following lines:

SomeEntity(id=1, stringColumn=value-1, integerColumn=1, jsonbColumn={"some_field":"some_value"})
SomeEntity(id=2, stringColumn=value-2, integerColumn=2, jsonbColumn={"another_field":"some_value_2"})

4. Summary

And that’s all for this short, hands-on article on how to map Postgres jsonb to JsonNode. As always, you can find the source code in this GitHub repository.

As always, happy to hear your thoughts on how would you solve this issue.

The post Postgres jsonb to Jackson JsonNode With Spring Data JPA appeared first on Codersee blog- Kotlin on the backend.

In this article, which is a continuation of a Flyway series we will learn how to add Flyway to an existing Spring Boot Project.

If you are not sure what this tool can bring to your project, then check out my first post on Flyway with Spring Boot, where you can find all the necessary information.

2. Project Setup

This time, we won’t spend time preparing a sample project (well, if you are here then there’s a 95% chance that you already have some project).

Nevertheless, if you don’t have one, but still would like to learn how to add a flyway to an existing Spring Boot project, then no worries. You can find an example project in this GitHub repository.

Note: If you use the project from the linked repository, then please run the script.sql file (can be found in /resources/sql directory) against your database, before you start the application.

3. Strategy For Adding Flyway To Existing Spring Boot Project

Before we start anything, I just wanted to emphasize that we should always create a backup, before performing any operations on our databases. Regardless of how widely used, or well-tested the tool is, something can always go wrong and we have to be ready to roll out plan B.

3.1 Add Flyway Dependency

As the first thing (after the backup!), let’s add the necessary dependency to our Spring Boot project.

For gradle, it will look as follows:

implementation 'org.flywaydb:flyway-core:9.8.3'

On the other hand, when working with Maven, we need to add these lines:

<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
  <version>9.8.3</version>
</dependency>

3.2 Verify Spring Boot App

Nextly, let’s run our Spring Boot application and verify, whether anything changed:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'flywayInitializer' defined in class path resource [org/springframework/boot/autoconfigure/flyway/FlywayAutoConfiguration$FlywayConfiguration.class]: Found non-empty schema(s) "custom_schema" but no schema history table. Use baseline() or set baselineOnMigrate to true to initialize the schema history table.
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1751) ~[spring-beans-6.0.2.jar:6.0.2]

As we can clearly see, Flyway throws a pretty descriptive message:

Found non-empty schema(s) “custom_schema” but no schema history table. Use baseline() or set baselineOnMigrate to true to initialize the schema history table.

And basically, this error clearly states what we need to do when adding a Flyway to an existing project. But before that, we have to take care of a couple of things.

3.3 Generate Production Database DDL

Firstly, we have to generate an SQL script containing the DDL our production database, including:

• procedures
• views,
• triggers etc…

I won’t go into details here, because DDL script generation depends on the database you are using. Nevertheless, it can be done pretty easily with tools like DataGrip, DBeaver, or pg_dump.

And when the SQL script with DDL is ready, let’s save it in the Flyway migrations directory (in Spring Boot the default one is resources/db/migration). Of course, we have to remember about the Flyway files naming convention, so the file name should be something, like V1__my_custom_init_script.sql.

3.4 Clear Irrelevant Data

If you have only one database instance in your project, then feel free to skip this point. Otherwise, we have to make sure that the generated DDL script will work in every other environment. And we can achieve it in two ways:

• if we don’t care about the data in other environments- then we can run the Flyway clean command.
• however, if we do actually care about the data in our non-production environments, then there’s no other choice than to manually verify and align other database structures with the main one.

The choice here is yours and will depend on many factors, like the importance of test data, amount of environments, etc.

Nevertheless, if you would like to clean your database before adding a Flyway to your existing project, then you can do that with the following:

flyway -defaultSchema="custom_schema" \
  -url="jdbc:postgresql://{URL}:{PORT}/{DB_NAME}" \
  -cleanDisabled="false" \
  -user="{USERNAME}" \
  clean

Please keep in mind that with this command, we will be prompted to enter the password manually (and alternatively, we can pass the -password flag).

3.5 Add Flyway To Existing Spring Boot Project

Finally, with all that being done, we can return to the Spring Boot project and make the necessary changes.

Let’s navigate to the application.yaml file and insert these settings:

spring:
  flyway:
    baselineOnMigrate: true
    defaultSchema: "custom_schema" # not necessary, but most likely you'll want to point to a specific schema

As we can see, with baselineOnMigrate set to true, we instruct Flyway to automatically call baseline when migration is executed against a non-empty schema. Additionally, we set the defaultSchema value, but this is totally optional.

As a result, the flyway_schema_history table is added to our schema:

and populated with precisely one record.

Please remember that the baselineOnMigrate set to true is only required once- when we do the initial deployment and can be removed after that.

3.6 Add Flyway Using Commands

Basically, with all of the above being done we are finished and can enjoy the benefits of Flyway in our project.

However, if you would like to learn how to add Flyway to an existing project using CLI, then you can do exactly the same with the following command:

flyway -defaultSchema="custom_schema" \ 
-url="jdbc:postgresql://{HOST}:{PORT}/{DB_NAME}" \
-user="USERNAME" \
-baselineOnMigrate="true" \
-locations="filesystem:." migrate

Or, alternatively, run baseline only:

flyway -defaultSchema="custom_schema" \ 
-url="jdbc:postgresql://{HOST}:{PORT}/{DB_NAME}" \
-user="USERNAME" \
-locations="filesystem:." baseline

And then the migrate command:

flyway -defaultSchema="custom_schema" \ 
-url="jdbc:postgresql://{HOST}:{PORT}/{DB_NAME}" \
-user="USERNAME" \
-locations="filesystem:." migrate

These commands might be useful if you would like to extract migrations to a separate directory (and/or repository).

4. Add Flyway To An Existing Spring Boot Project Summary

And that would be all in this article about how to add Flyway to an existing Spring Boot project. If you’d like to get to know Flyway better, then I highly encourage you to visit their documentation.

Let me know in the comments section in case of any questions 🙂

The post Add Flyway To An Existing Spring Boot Project appeared first on Codersee blog- Kotlin on the backend.