<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by ThinkSystem on Medium]]></title>
        <description><![CDATA[Stories by ThinkSystem on Medium]]></description>
        <link>https://medium.com/@think.system?source=rss-b35815eadd55------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*h530R1FtGZcerT31weMy_A.png</url>
            <title>Stories by ThinkSystem on Medium</title>
            <link>https://medium.com/@think.system?source=rss-b35815eadd55------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 09:05:16 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@think.system/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Supercharge your logging MDC with Kotlin: Part 2. Spring Controllers.]]></title>
            <link>https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-2-spring-controllers-13ce4c612043?source=rss-b35815eadd55------2</link>
            <guid isPermaLink="false">https://medium.com/p/13ce4c612043</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[ThinkSystem]]></dc:creator>
            <pubDate>Tue, 04 Jun 2024 15:27:51 GMT</pubDate>
            <atom:updated>2024-06-04T15:47:20.266Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*qSLvdcNOP8Y3RaUz" /><figcaption>Photo by <a href="https://unsplash.com/@kolamdigital?utm_source=medium&amp;utm_medium=referral">Andy Hermawan</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>In the previous article, we improved Kotlin MDC to make it more convenient and safe. However, there is an issue with it — it isn’t compatible with Spring Controllers. Why is that so and what can we do about it? Read further to find out!</p><blockquote><strong>Note</strong>: This article covers only blocking code. Reactive code and coroutines have their own issues that should be targeted differently.</blockquote><h3>The problem with error handling</h3><p>Let’s take our MDC helper that we implemented in the <a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78">previous article</a> and use it in Spring Controller:</p><pre>@RestController<br>@RequestMapping(&quot;/dogs&quot;)<br>class DogController(service: DogService) {<br>  @PostMapping(&quot;/{id}/pet&quot;)<br>  fun pet(@PathVariable(&quot;id&quot;) id: DogId) = withMdc(&quot;dogId&quot; to id) {<br>    service.petDogById(id)<br>  }<br>}</pre><p>What if our method throws an exception? What response will be returned to our clients?</p><p>In many cases, this will not be all the code required. Very often it’s necessary to add error handling in order to wrap internal errors and return clear HTTP codes to the client.</p><p>A typical way to handle controller errors is by using <em>@ControllerAdvice</em>.</p><pre>@ControllerAdvice<br>class DogExceptionHandler {<br>  @ExceptionHandler<br>  fun handleNotFound(ex: DogNotFoundException): ResponseEntity&lt;String&gt; {<br>    logger.error(&quot;Unable to find dog&quot;, ex)<br>    return ResponseEntity(HttpStatus.NOT_FOUND)<br>  }<br><br>  @ExceptionHandler<br>  fun handleRuntime(ex: RuntimeException): ResponseEntity&lt;String&gt; {<br>    logger.error(&quot;Unexpected error&quot;, ex)<br>    return ResponseEntity(HttpStatus.INTERNAL_ERROR)<br>  }<br>}</pre><p>But if we check the logs carefully, we will notice that error logs don’t contain the MDC values.<br>In other words, if we call <em>POST /dogs/123/pet</em> and an exception is thrown, we will not see <em>dogId</em> in the logs.</p><pre>// This is what we expect to see<br>2024–02–28T12:00:00 [main] [dogId=123] Unable to find dog<br>EntityNotFoundException:<br> &lt;stacktrace&gt;<br>// But we actually will see this (note empty MDC)<br>2024–02–28T12:00:00 [main] [] Unable to find dog<br>EntityNotFoundException:<br> &lt;stacktrace&gt;</pre><p>Let’s check the details of the MDC scope and Spring Controller Advice flow to understand the reason for such behavior.</p><p>In general, MDC is defined on the thread level and is shared by any code executed by a particular thread. This causes the shuffle of the log context in the code executed by different endpoints when one thread processes first one endpoint and then switches to another (see <a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78">Part 1</a>). In order to solve this, we decided to implement a wrapper for all endpoints to clean up and set up MDC for each Controller method, i.e., to limit the MDC scope. So, now, the MDC scope is located inside the Controller, and everything works very well during successful execution.</p><p>But if the process catches an exception, it first cleans MDC (and consequently closes its context), then exits the Controller, and only after that does Spring pass the exception from Controller to Controller Advice (see Diagram 1). Unfortunately, the error handling code is outside the MDC scope.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AQNs6OiGYMj9RORo1SRm1g.png" /><figcaption>Diagram 1. Controller Advice is outside of MDC scope.</figcaption></figure><p>Of course, if we add error handling to Controller’s methods, then this problem wouldn’t occur. But that is a bad practice because it would lead to code duplication in each endpoint.</p><h3>Attempt 1: pass MDC within exceptions</h3><p>OK, so we don’t have access to the MDC scope in ControllerAdvice. But what do we have? We have access to the actual exceptions. Can we use the exceptions themselves to pass the context?</p><p>Yes, we can do this by adding extra fields to the exceptions. Let’s try to do it.</p><pre>class DogNotFoundException(<br>  message: String,<br>  val dogId: String,<br>) : RuntimeException(message)<br><br>@ControllerAdvice<br>class DogExceptionHandler {<br>  @ExceptionHandler<br>  fun handleNotFound(ex: DogNotFoundException): ResponseEntity&lt;String&gt; = withMdc(&quot;dogId&quot; to ex.dogId) {<br>    logger.error(&quot;Unable to find dog&quot;, ex)<br>    ResponseEntity(HttpStatus.NOT_FOUND)<br>  }<br>  // what to do with this one?<br>  @ExceptionHandler<br>  fun handleRuntime(ex: RuntimeException): ResponseEntity&lt;String&gt; {<br>    logger.error(&quot;Unexpected error&quot;, ex)<br>    return ResponseEntity(HttpStatus.INTERNAL_ERROR)<br>  }<br>}</pre><p>This is a draft attempt, but you already can see an inherent issue with this solution: you’ll need custom exceptions. In other words, you will have to wrap (by catch and rethrow) every non-custom exception from every library you have. Even IllegalArgumentException or ValidationException! This is definitely not a pleasant solution.</p><h3>Attempt 2: intercept requests and wrap MDC in Spring Filter</h3><p>In order to find alternatives, let’s take a step back. Our problem is that we don’t have access to the MDC scope in exception handling because the scope is already closed. We tried to save and pass the scope via exceptions, but it turns not to be a viable option.</p><p>But what if we try to <strong>extend</strong> the scope instead? We can use Spring Filter to intercept request processing flow and wrap <strong>entire</strong> processing with our MDC scope! Because Filter is higher on the stack than Controller and ControllerAdvice, we will be able first to initialize the log context, then move to Controller and execute the logic, after that handle errors in Controller Advice, and in the end return to Filter and clean up the context. Both logic and error handling will occur inside our log context (see Diagram 2). Awesome!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*izRaO-Tne-xr-em5ZMsD2A.png" /><figcaption>Diagram 2. Controller Advice is inside MDC scope.</figcaption></figure><pre>@Component<br>class MdcFilter : OncePerRequestFilter() {<br>  override fun doFilterInternal(<br>  request: HttpServletRequest,<br>  response: HttpServletResponse,<br>  filterChain: FilterChain<br>  ) {<br>    withMdc(/** what to put here? **/) {<br>      filterChain.doFilter(request, response)<br>    }<br>  }<br>}</pre><p>This way, we can access the same context in the Controller and in ControllerAdvice. But… how exactly can we set the MDC? How can we access the values that we need?</p><p>Actually, there are 4 ways to pass some information in the request:</p><ul><li>in headers</li><li>in query parameters</li><li>in path variables</li><li>in request body.</li></ul><p>The trick with handling requests in Spring Filter is that in this place, we don’t yet have any information as to which specific endpoint this request will be routed. However, query parameters, path variables, and request body differ depending on the endpoint that will process the request. And the same data might be located in different places at various endpoints. For example, record id can be passed as a path variable in PUT request and as part of the body in other endpoints.</p><p>Whereas the header usually contains some generic info that is the same for all endpoints. So, we can access header info in the Filter, and it doesn’t matter which endpoint processes the request. This means that in the Filter, we can reliably access only the headers to set up our log context. This is clearly not enough!</p><h3>Working solution: split MDC cleanup and setup between Spring Filter and Controllers</h3><p>The truth is that the best place to fill the context values is the Controller itself because we have access to all important parts of the requests. And it’s already pinpointed to a specific URL. Now we have a guarantee that the Controller method is already <em>within</em> the scope.</p><p>Wild idea: what if we <em>remove</em> our helper and set MDC directly?</p><pre>@PostMapping(&quot;/{id}/pet&quot;)<br>fun pet(@PathVariable(&quot;id&quot;) id: DogId) {<br>  MDC.put(&quot;dogId&quot;, id)<br>  service.petDogById(id)<br>}</pre><p>But… isn’t this something we want to avoid in the first place? There is a whole article (<a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78">Part 1</a>) explaining why we should <strong>not</strong> write the code like this!</p><p>Well, the answer is no. Firstly, it works differently here. The main issue with direct MDC manipulations is context cleanup, which we already handle in the Filter in this case. Secondly, our goal is not to avoid direct library calls but to make our day-to-day work more pleasant by making our code more readable and less error-prone.</p><p>It turns out the best way to solve the issues with error handling and the intricacies of context scope in Spring is by splitting the MDC wrapping logic between Filter and Controllers. This way, we can capture all requests and do all generic initialization and cleaning inside the Filter but set up all specific details depending on the URL inside Controllers, where we can access all these details. Now, our logging works correctly!</p><h3>MDC setup refactoring</h3><p>Ok, we already have a working solution, but if we examine it more closely, we will find that we can refactor it and improve its readability.</p><p>Let’s examine our controller again. This time, we’ll use another method with more parameters as an example so it’s easier to recognize a pattern. What’s wrong with this code? Can we improve something?</p><pre>// defined somewhere else<br>object LogConstants {<br>  // There are multiple places where we reference our MDC keys<br>  // So we use a constant to keep them unified and avoid mistakes<br>  const val BREED_ID = &quot;dogId&quot;<br>  const val FAVORITE_FOOD_ID = &quot;favoriteFoodId&quot;<br>}<br><br>typealias BreedId = String<br>// Let&#39;s make things more difficult - one of the ID&#39;s is Int<br>typealias FoodId = Int<br><br>@PostMapping(&quot;search&quot;)<br>fun search(<br>  @QueryParameter(&quot;breedId&quot;) breedId: BreedId,<br>  @QueryParameter(&quot;favoriteFood&quot;, required = false) favoriteFood: FoodId?<br>): List&lt;Dog&gt; {<br>  MDC.put(BREED_ID to breedId)<br>  MDC.put(FAVORITE_FOOD_ID to favoriteFood.toString())<br>  return dogRepository.findAll(prepareCriteria(breedId, favoriteFood))<br>}</pre><p>What we would like to achieve here is to minimize verbosity, improve expressiveness, and reduce error probability. In order to do that, let’s try to leave only meaningful parts of the code to visualize our end goal.</p><pre>@PostMapping(&quot;search&quot;)<br>fun search(<br>  @QueryParameter(&quot;breedId&quot;) breedId: BreedId,<br>  @QueryParameter(&quot;favoriteFood&quot;, required = false) favoriteFood: FoodId?<br>): List&lt;Dog&gt; {<br>  breedId(breedId) // just a method that accepts BreedId. As short as we can make it<br>  favoriteFood(favoriteFood) // this method accepts FoodId, no conversion needed<br>  return dogRepository.findAll(prepareCriteria(breedId, favoriteFood))<br>}</pre><p>But now it looks like we call some random methods. It’s not clear what these methods do and why we call them.<br>We can use static calls, like with ‘’’MDC.put’’’, or add something related to logs to the methods names. However, there is a more interesting option.</p><pre>@PostMapping(&quot;search&quot;)<br>fun search(<br>  @QueryParameter(&quot;breedId&quot;) breedId: BreedId,<br>  @QueryParameter(&quot;favoriteFood&quot;, required = false) favoriteFood: FoodId?<br>): List&lt;Dog&gt; {<br>  // we don&#39;t need to pass or store the context, therefore we can apply it on place instead of creating an instance<br>  LogContext {<br>    // now it&#39;s clear what these methods do - they set a log context!<br>    breedId(breedId)<br>    favoriteFood(favoriteFood)<br>  }<br>  return dogRepository.findAll(prepareCriteria(breedId, favoriteFood))<br>}</pre><p>It looks good, doesn’t it? And there is a way to implement such an API — Kotlin DSL. We won’t dive deep into the intricacies of Kotlin DSL because it won’t be possible to fit them into this article. Instead, we will show the implementation straight away.</p><pre>object LogContext {<br>  fun invoke(context: LogContextBuilder.() -&gt; Unit) {<br>    context.invoke(LogContextBuilder)<br>  }<br><br>  const val DOG_ID = &quot;dogId&quot;<br>  const val BREED_ID = &quot;breedId&quot;<br>  const val FAVORITE_FOOD_ID = &quot;favoriteFoodId&quot;<br>}<br><br>//domain specific<br>object LogContextBuilder {<br>  fun dogId(id: DogId?) = put(DOG_ID, id)<br>  fun breedId(id: BreedId?) = put(BREED_ID, id)<br>  fun favoriteFoodId(id: FoodId?) = put(FAVORITE_FOOD_ID, id)<br><br>  private fun put(key: String, value: String?) {<br>    value?.let { MDC.put(key, it) }<br>  }<br>}</pre><p>Here, we have defined our DSL — high-level code to manipulate log context. The key idea is that this code is tightly coupled with our domain or even the specific application. By defining dedicated helper functions (dogId, breedId, etc.), we’ve narrowed the allowed arguments by specific types (DogId, BreedId, etc.). We also have hidden MDC keys, so inserting another key by mistake is impossible. It makes our code less versatile but much more safe and readable.</p><p>If you are curious to learn more about Kotlin DSL — you can check the <a href="https://kotlinlang.org/docs/type-safe-builders.html">documentation</a>.</p><h3>Final solution</h3><p>And this is how our final result looks. As mentioned before, it consists of two parts. The first one is the initial context setup and MDC clean-up inside the helper.</p><pre>@Component<br>class MdcFilter : OncePerRequestFilter() {<br>  override fun doFilterInternal(<br>    request: HttpServletRequest,<br>    response: HttpServletResponse,<br>    filterChain: FilterChain<br>  ) {<br>    // Let&#39;s add USER_AGENT header to the MDC<br>    // We don&#39;t really need it for our logic, but it is handy to have in logs<br>    withMdc(LogContext.USER_AGENT to request.getHeader(Headers.USER_AGENT)) {<br>      filterChain.doFilter(request, response)<br>    }<br>  }<br>}</pre><p>One interesting remark to add. Although we use our previously developed helper method in Spring Filter, it is unnecessary because there is only one place to clean the context. Consequently, it also makes perfect sense to use try-catch directly here.</p><p>And the second essential part is the improved MDC setup using Kotlin DSL.</p><pre>@PostMapping(&quot;search&quot;)<br>fun search(<br>  @QueryParameter(&quot;breedId&quot;) breedId: BreedId,<br>  @QueryParameter(&quot;favoriteFood&quot;, required = false) favoriteFood: FoodId?<br>): List&lt;Dog&gt; {<br>  // Enrich the context in the controller<br>  LogContext {<br>    breedId(breedId)<br>    favoriteFood(favoriteFood)<br>  }<br><br>  return dogRepository.findAll(prepareCriteria(breedId, favoriteFood))<br>}</pre><h3>Use cases where the helper fits the best</h3><p>Well, finally, we’ve implemented a solution for Spring Controllers. But does this mean that all our efforts in <a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78">Part 1</a> are useless, and should we remove our helper?</p><p>Definitely not! There is only one case when we face an issue — in Spring Controllers. Our little helper fits perfectly in all other cases, such as scheduled jobs, event listeners, batch requests, etc.</p><p>Here are examples of some of these cases, like the helper used for scheduled jobs.</p><pre>@Scheduled(FOOD_CLEANUP_INTERVAL)<br>// This is not a controller, continue to use our helper<br>fun cleanupFood() = withMdc(JOB_NAME to &quot;cleanup_expired_food&quot;) {<br>  foodService.cleanupExpired()<br>}</pre><p>Or inside event listeners.</p><pre>fun donationEventListener(event: DonationEvent) = withMdc(EVENT_ID to event.id, EVENT_TYPE to &quot;donation&quot;) {<br>  celebrationService.celebrateDonation(event.amount)<br>}<br><br>fun puppiesEventListener(event: NewPuppiesEvent) = withMdc(EVENT_ID to event.id, EVENT_TYPE to &quot;new_puppies&quot;) {<br>  event.puppies.forEach { puppy -&gt;<br>    // Set specific ID for each celebration call<br>    // Here we add dogId to the context without overriding existing values <br>    withMdc(DOG_ID to puppy.id) {<br>      celebrationService.celebrateNewPuppie(event.puppy)<br>    }<br>  }<br>}</pre><h3>Conclusion</h3><p>It’s extremely difficult, and sometimes just impossible, to create a solution that handles all possible cases universally well. It’s much easier, however, to have multiple specialized solutions and combine them when needed. And this is what we practiced in this article.</p><p>Here we found out that the solution we implemented before doesn’t support correct error handling in Spring Controllers. And to fix this, we developed a new approach — split setup and clean-up logic between Spring Filters and Spring Controllers. We decided to catch all HTTP requests in Spring Filter and execute general initialization and clean up logic there. The setup code was added to Controllers. We enhanced this code with a specific DSL to improve readability and reduce error chance.</p><p>At the same time, the helper function written in <a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78">Part 1</a> remains totally correct for all other cases except Spring Controllers. It’s the best option to use in schedulers, event listeners, batch requests, and many other cases.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=13ce4c612043" width="1" height="1" alt=""><hr><p><a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-2-spring-controllers-13ce4c612043">Supercharge your logging MDC with Kotlin: Part 2. Spring Controllers.</a> was originally published in <a href="https://medium.com/javarevisited">Javarevisited</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Supercharge your logging MDC with Kotlin: Part 1]]></title>
            <link>https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78?source=rss-b35815eadd55------2</link>
            <guid isPermaLink="false">https://medium.com/p/6cb433b72c78</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[coding]]></category>
            <dc:creator><![CDATA[ThinkSystem]]></dc:creator>
            <pubDate>Mon, 15 Apr 2024 15:31:47 GMT</pubDate>
            <atom:updated>2024-04-16T10:08:48.745Z</atom:updated>
            <content:encoded><![CDATA[<h4>Enhance the reliability and conciseness of logging MDC with Kotlin features. See how writing your own helpers <br>improves the code quality.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*G6NrH4UN5XrND8IC" /><figcaption>Photo by <a href="https://unsplash.com/@kolamdigital?utm_source=medium&amp;utm_medium=referral">Andy Hermawan</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>If you’re using any JVM-based language, then you are likely familiar with logging MDC (Mapped Diagnostic Context) — a default solution for passing the logging context. However, while being widely used and well known, with good support from libraries and services (such as ELK stack), MDC still has some issues and rough edges. Let’s use Kotlin to make it safer and more convenient!</p><blockquote><strong><em>Note:</em></strong><em> This article covers only blocking code. Reactive code and coroutines have their own issues that should be targeted differently.</em></blockquote><h3>What all the fuss is about?</h3><p>But what exactly is wrong with MDC? Well, to explain it we need to take a step back.</p><p>If you didn’t have experience with logging MDC before, here’s what it looks like:</p><pre>fun petDogById(id: DogId) {<br>  MDC.put(&quot;dogId&quot;, id)<br>  val dog = repository.getById(id)<br>  petTheDog(dog)<br>}<br><br>private fun petTheDog(dog: Dog) {<br>  // no additional data passed<br>  logger.info(&quot;Dog &#39;{}&#39; has been pet&quot;, dog.name)<br>  // in log we will see something like this<br>  // 2024-02-28T12:00:00 [main] [dogId=123] Dog &#39;Hugo&#39; has been pet<br>}</pre><p>Looks good, right? You just set a context, and it is automatically passed to all subsequent logger calls. This works especially well for libraries.</p><p>But the issue comes from the same thing as the benefits. MDC is based on ThreadLocal, so the values are stored per thread and aren’t <strong>cleaned </strong>automatically. What does it mean? In almost all cases, you want to reuse threads by utilizing thread pools, so you will use the same thread over and over again.</p><p>For example, let’s look at the Spring HTTP endpoint implementation:</p><pre>@RestController<br>@RequestMapping(&quot;/dogs&quot;)<br>class DogController(service: DogService) {<br>  @PostMapping(&quot;/{id}/pet&quot;)<br>  fun pet(@PathVariable(&quot;id&quot;) id: DogId) {<br>     MDC.put(&quot;dogId&quot;, id)<br>     service.petDogById(id)<br>  }<br>}<br><br>@RestController<br>@RequestMapping(&quot;/food&quot;)<br>class FoodController(service: FoodService) {<br>  @PostMapping(&quot;/{id}/resupply&quot;)<br>  fun resupply(@PathVariable(&quot;id&quot;) id: FoodId) {<br>     MDC.put(&quot;foodId&quot;, id)<br>     service.resupplyDogFood(id)<br>  }<br>}</pre><p>Here we have two endpoints with totally independent logging context. However, the same thread may handle both endpoints and MDC values will ‘leak’ from one context to another.</p><pre>// first we call &#39;pet&#39; endpoint<br>2024-02-28T12:05:00 [main] [dogId=123] Dog &#39;Hugo&#39; has been pet<br>// then we call &#39;resupply&#39; endpoint<br>// it is possible that the same thread will process the call<br>2024-02-28T12:10:00 [main] [dogId=123, foodId=456] The food {id=456, name=Meat} has beed resupplied</pre><p>But we don’t want to see food logs when we search by DogId. It’s confusing and not convenient at all. To avoid such leaks we have to clean MDC at some point. And it’s much clearer and more reliable to remove MDC values when we no longer need them than to leave our application in a dirty state. In other words — clean after the actual logic, not before.</p><h3>Classic solution</h3><p>You may ask: “If we need to clear MDC, then why don’t we?” Well, below is the code we get if we implement it straightforwardly.</p><pre>fun petTheDogById(id: DogId) {<br>  val oldContext = MDC.copyOfContextMap()<br>  try{<br>    MDC.put(&quot;dogId&quot;, id)<br>    //--- only this part contains application logic <br>    val dog = repository.getById(id)<br>    petTheDog(dog)<br>    //---  <br>  } finally {<br>    MDC.setContextMap(oldContext)<br>  }<br>}</pre><p>The code no longer looks so good — it has become verbose and cumbersome. We have to use try-finally because any function can throw an exception. And we have to restore the old context instead of cleaning it because it can contain other values we would like to preserve (like requestId). Also, such code is error-prone, as someone can easily forget to restore the old context.</p><h3>Better way</h3><p>Let’s try to write something better.</p><p>What we need is to limit the scope of the new context. Our intention is to run some code with enriched context and then revert it to the old one. In other words, we want to wrap our code with some MDC logic. And the easiest way to wrap the code is to use lambda syntax.</p><pre>fun withMdc(key: String, value: String, wrappedCall: ()-&gt;Unit) {<br>  val oldContext = MDC.copyOfContextMap()<br>  try{<br>    MDC.put(key, value)<br>    wrappedCall() //&lt;- application logic was here<br>  } finally {<br>    MDC.setContextMap(oldContext)<br>  }<br>}<br><br>// utilize two Kotlin features:<br>// 1. simplified function definition with &#39;=&#39;<br>// 2. trailing lambdas can be moved outside of parenthesis<br>fun petTheDogById(id: DogId) = withMdc(&quot;dogId&quot;, id) {<br>    val dog = repository.getById(id)<br>    petTheDog(dog)<br>}</pre><p>Looks much better already!</p><h3>Multiple MDC values</h3><p>But what if we want to set more than one key? It will lead to ugly nested calls.</p><pre>fun feedTheDog(dogId: DogId, food: DogFood) = withMdc(&quot;dogId&quot; to dogId) {<br>    withMDC(&quot;foodId&quot; to food.id) {<br>        val dog = dogRepository.getById(dogId)<br>        feeder.feedTheDog(dog, food)<br>    }<br>}</pre><p>Let’s adjust our helper to handle multiple values.</p><p>The easiest way to pass multiple values is to use a Map since MDC is very similar to it.</p><pre>fun withMdc(values: Map&lt;String, String&gt;, wrappedCall: ()-&gt;Unit) {<br>    ...<br>}</pre><p>OK, but in this case we will have to create a Map every time and write the same code that doesn’t express any logic.</p><pre>fun feedTheDog(dogId: DogId, food: DogFood) = withMdc(mapOf(<br>    &quot;dogId&quot; to dogId,<br>    &quot;foodId&quot; to food.id<br>)) {<br>    val dog = dogRepository.getById(dogId)<br>    feeder.feedTheDog(dog, food)<br>}</pre><p>Yet we can pass multiple values to the mapOf function. Let&#39;s do the same for our helper!</p><pre>fun withMdc(vararg pairs: Pair&lt;String, String&gt;, wrappedCall: ()-&gt;Unit) {<br>  val oldContext = MDC.getCopyOfContextMap()<br>  try {<br>    pairs.forEach{ MDC.put(it.key, it.value) }<br>    wrappedCall()<br>  }<br>  finally {<br>    MDC.setContextMap(oldContext)<br>  }<br>}<br><br>fun feedTheDog(dogId: DogId, food: DogFood) = withMdc(<br>  &quot;dogId&quot; to dogId.toString(), // `to` is an extension function to create `Pair`<br>  &quot;foodId&quot; to food.id.toString()<br>){<br>  val dog = dogRepository.getById(dogId)<br>  feeder.feedTheDog(dog, food)<br>}</pre><p>Good, this is something we can work with.</p><h3>Return the result of the wrapped call</h3><p>What other common cases can we face? Obviously, sometimes we want to return the results of our code. However, the current implementation does not allow this.</p><pre>// This will produce a compilation error<br>fun goodBoyCheck(dogId: DogId): GoodBoyStatus = withMdc(&quot;dogId&quot;, dogId) {<br>    service.extractGoodBoyStatus(dogId)<br>}</pre><p>Luckily, returning the result is easy. Such a feature will make our helper much more versatile.</p><pre>// use a template here because we don&#39;t know the return type in advance<br>fun &lt;T&gt; withMdc(vararg pairs: &lt;String, String&gt;, wrappedCall: ()-&gt;T): T {<br>  val oldContext = MDC.getCopyOfContextMap()<br>  try {<br>    pairs.forEach{ MDC.put(it.key, it.value) }<br>    return wrappedCall() // and add a `return` here<br>  }<br>  finally {<br>    MDC.setContextMap(oldContext)<br>  }<br>}<br><br>// No error with new implementation!<br>fun goodBoyCheck(dogId: DogId): GoodBoyStatus = withMdc(&quot;dogId&quot;, dogId) {<br>    service.extractGoodBoyStatus(dogId)<br>}</pre><p>Handy indeed!</p><h3>Handle nullable values</h3><p>Another typical scenario is a nullable value. Kotlin has great compile-time support for nullability, but our implementation isn’t compatible with nullable values. Since we don’t want to see nulls in our MDC values, we’ll have to filter them out.</p><pre>fun search(breedId: BreedId, favoriteFood: FoodId?): List&lt;Dog&gt; {<br>    val logContext = listOf(<br>        &quot;breedId&quot; to breedId,<br>        &quot;favoriteFoodId&quot; to favoriteFood<br>    )<br>        .filter { it.second != null }<br>        // to avoid casting to List&lt;Pair&lt;String, String&gt;&gt;<br>        .map { it.first to it.second!! }<br>    return withMdc(*logContext.toTypedArray()) {<br>        dogRepository.findAll(prepareCriteria(breedId, favoriteFood))<br>    }<br>}</pre><p>Ugh! So much useless and verbose code! Let’s add a nullability check to make it clean and pretty again.</p><pre>fun &lt;T&gt; withMdc(vararg pairs: &lt;String, String?&gt;, wrappedCall: ()-&gt;T): T {<br>  val oldContext = MDC.getCopyOfContextMap()<br>  try {<br>    pairs<br>      // with this check we don&#39;t have to handle nullability in our main logic  <br>      .filter{ it.value != null }<br>      .forEach{ MDC.put(it.key, it.value) }<br>    return wrappedCall()<br>  }<br>  finally {<br>    MDC.setContextMap(oldContext)<br>  }<br>}<br><br>fun search(breedId: BreedId, favoriteFood: FoodId?): List&lt;Dog&gt; = withMdc(<br>    &quot;breedId&quot; to breedId,<br>    &quot;favoriteFoodId&quot; to favoriteFood<br>) {<br>   dogRepository.findAll(prepareCriteria(breedId, favoriteFood))<br>}</pre><p>Nice! Clear, short and reliable!</p><h3>Conclusion</h3><p>Here, we took a well-known logging MDC solution and tried to address its limitations. We applied some Kotlin features to improve it even more by making it less error-prone and verbose. And finally, it’s pleasant to read and easy to use!</p><p>Libraries can be hindered by their release cycle, backward compatibility requirements, or sheer lack of support, but this doesn’t mean you have to abide by the existing API. There is no ‘one size fits all’. So, don’t be afraid to create your own helpers. You can always figure out something that fits this specific project or your own preferences. After all, you are the developer.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6cb433b72c78" width="1" height="1" alt=""><hr><p><a href="https://medium.com/javarevisited/supercharge-your-logging-mdc-with-kotlin-part-1-6cb433b72c78">Supercharge your logging MDC with Kotlin: Part 1</a> was originally published in <a href="https://medium.com/javarevisited">Javarevisited</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When database integration beats microservices]]></title>
            <link>https://medium.com/javarevisited/when-database-integration-beats-microservices-e5c790778fa2?source=rss-b35815eadd55------2</link>
            <guid isPermaLink="false">https://medium.com/p/e5c790778fa2</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-design]]></category>
            <category><![CDATA[system-design-concepts]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[ThinkSystem]]></dc:creator>
            <pubDate>Fri, 22 Mar 2024 11:01:08 GMT</pubDate>
            <atom:updated>2024-03-22T15:08:43.864Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*8Ie18yu5hd7pLYy4" /><figcaption>Photo by <a href="https://unsplash.com/@senthil_moorthy?utm_source=medium&amp;utm_medium=referral">Senthil Kumar Moorthy</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>Don’t be afraid of anti-patterns</h3><p>Everyone knows that database integration is a bad thing. And everyone knows that it is an anti-pattern you should avoid by any means. The standard rule is that services shouldn’t integrate using a database as a connection point (even though sometimes it happens anyway). Well, we all know that following best practices is important. But unfortunately, we often tend to forget the real reasons why they are so good. In some situations, these reasons aren’t applicable.</p><p>In fact, sometimes you can use DB for integration, provided certain conditions are met. Let’s look at a case when database integration works much better than a classic microservice approach.</p><h3>Problem statement</h3><p>We will go straight to the use case and suggest we have a typical service that controls some data stored in DB and provides public API to CRUD the data via HTTP (data API further in the text). And we have a task to make some calculations based on this data periodically. Let’s say it is a periodic job we want to execute once an hour. This job is CPU-bound because we intend to do heavy calculations on large amounts of data by the number of records and fields involved. Although that could be the case for many things — validations, checksums, hashing, aggregations, statistics — we will take the calculation of aggregates as an example.</p><h3>Straightforward design options and their shortcomings</h3><h4>All-in-one service</h4><p>Ok, the first and most obvious solution that comes to mind is to gather both business and aggregation logic in one service. We will call it Data service. As for aggregation logic, we will need to schedule a job, or it will wait in an idle state for the start time. Data service connects to Data DB and consists of a data API implemented by business logic, aggregation job, and aggregation API (see Design 1). Main business logic is responsible for processing user requests, handling original data, and updating tables using the received information. Aggregation job is executed periodically. It reads all original data required for calculations, generates aggregates, and writes them to a separate table in the same Data DB.</p><figure><img alt="Design 1. All in one service." src="https://cdn-images-1.medium.com/max/1024/1*5BvkOpX8jEvH_bE9ygs4aw.png" /><figcaption>Design 1. All in one service.</figcaption></figure><p>Unfortunately, this solution has problems. Due to heavy calculations and a lot of processor capacity required, the nature of our aggregation task is very different from the usual processing of API requests. It turns out to be a bad idea because this way a CPU-bound task will consume all available resources, and <strong>users will experience delays and timeouts on their requests</strong> to our service.</p><p>You can try to launch additional or bigger instances to solve the issue, but it won’t help. The heavy task will consume all resources anyway, and we won’t have anything left to process our API requests. Even though we will calculate our background job faster, the latency issues with request processing will stay. And we aim to fix these issues, not speed up the job. It won’t give us anything. Also, this will result in <strong>cloud resources overbooking</strong>. It’s not a pleasant outcome, so let’s not do this.</p><h4>True microservices</h4><p>No big deal. Another great idea, then! The answer is straightforward. If a single service containing all the logic doesn’t work well, let’s do it in a true microservice way. We will do it nicely. Data service will work with original data and separate Aggregation service will produce aggregates. Each will work with its own isolated DB: Data service will store the data in Data DB, and Aggregation service will write aggregates to Aggregation DB. No service will interact directly with other service’s database. We will build a specific endpoint to fetch original data from DB in Data service.</p><p>However, it could be better again. Although everything looks good and classy at first glance (see Design 2), this system design has two major problems. The data consumption pattern of aggregation job differs greatly from that of all other Data service consumers. It requires a lot of data. So, we <strong>must unload almost all original data from Data service</strong> to Aggregation service. Firstly, we have a lot of extra work to build an additional API in Data service to provide original data and another API in Aggregation service to consume that data. Secondly, we need to transfer a large volume of data between two services, which will require a lot of resources — CPU and network capacity. And, in the end, data transfer will simply take a lot of time.</p><p>But that’s not all. Another problem is that we need to implement a new endpoint on Aggregation service side to provide aggregated data to consumers. It means that all consumers now <strong>need to integrate with two services instead of one</strong>.</p><p>Design 2 represents the resulting solution. Data service will have to provide API to get original data in addition to data API. On Aggregation service side, aggregation API will be implemented together with the background aggregation job, plus a new logic to load the original data. Aggregation job will do its work and store produced aggregates in a separate table in Aggregation DB.</p><figure><img alt="Design 2. Two microservices." src="https://cdn-images-1.medium.com/max/1024/1*etyo35K4Mdh4s7p7FDMRog.png" /><figcaption>Design 2. Two microservices.</figcaption></figure><h3>The plot thickens: it looks even worse when we try to fix it</h3><p>And now it starts getting tricky. It seems that the two most obvious solutions don’t work. Even the mighty microservices don’t help. But what can we do to improve the solution if, in this particular case, separation into microservices brings so significant cons? Can we avoid all these issues?</p><p>Yes, we can. We can create two services using DB as an integration point instead of transferring a large amount of data between two services and, therefore, between two databases. Namely, implement a famous anti-pattern. That is represented in Design 3. Here, Data service connects to its dedicated Data DB and implements data API and main business logic. At the same time, Aggregation service provides API to the clients, executes the job, and stores generated aggregates to DB. Aggregation service makes all the calls to Data DB directly and doesn’t need any endpoint to access the data. As a result, Data DB stores all original data, and Aggregation DB only aggregates.</p><figure><img alt="Design 3. Database integration anti-pattern." src="https://cdn-images-1.medium.com/max/1024/1*nct4NMT5U_QwkpE1o5jXdg.png" /><figcaption>Design 3. Database integration anti-pattern.</figcaption></figure><p>Even though this solution helps to prevent transferring enormous amounts of data between services, <strong>it is undoubtedly a database integration</strong>. And, of course, it became an anti-pattern for many reasons. Let’s refresh them briefly.</p><p><strong>Issue #1</strong>. We don’t know who our clients are and have no idea what they do because we don’t have a dedicated API to separate our service’s internal data structures. Therefore, we don’t have any control over which data the clients consume. Hence, we lose the critical ability to change the internal structure whenever we need refactoring, system design improvements, or adding new features.</p><p>In fact, this is true only when, by database integration, we suppose that the internal structure of our data is exposed. And that is usually implied by default. However, there are mechanisms to create an API in DB via SQL views and access rights. It’s more complicated than to create an API over HTTP. But the real reason is that application developers are usually not experts in the intricacies of setting DB access rights. Even though such an API is not the best decision and has some drawbacks, it is a much better solution than opening your system’s internals to all its clients.</p><p>But we won’t dive deeper into how to do it now. Unfortunately, developers usually neither create an API layer nor adjust it for user access when implementing database integration. And this is the real anti-pattern.</p><p><strong>Issue #2</strong>. Schema migrations are complex. Sometimes, we don’t know our clients (this follows from the previous point). And if we don’t know them, how can we notify all consumers about the subsequent changes? So that they will update their code in advance? Anyway, even if we know all our clients, it might be challenging to agree on changes in the schema between all the teams involved. And it’s tough to create a new version of API, unlike with application API. Changes that are improvements for original Data service or one of its consumers, can cause issues with the code of other consumers. So, negotiations between teams require a lot of time.</p><p><strong>Issue #3</strong>. Changing DB technology to fit your service’s needs or your team’s preferences is impossible. And if you agree to change it, everyone needs to change it, as the integration database links everyone together.</p><p>Fine, after we have gone through the cons of database integration, it is time to take the next step to simplify Design 3. Despite its benefits for data distribution, it makes API more complex for the clients as they are now located in different services. But there is no reason to keep the aggregation API in Aggregation service, even though we moved aggregation job there due to its background nature. We can make life easier for our clients and move it to Data service, which is already a public network service. This way, users will need to integrate with only one service. If aggregation API is located in Data service, storing the aggregates in Data DB is very reasonable. After the changes, we get Design 4. There is only one database via which all interactions between two services happen, and Aggregation service contains only aggregation job.</p><figure><img alt="Design 4. Enhanced database integration." src="https://cdn-images-1.medium.com/max/1024/1*DTikeTzn-Pt4_FBjyuhNLw.png" /><figcaption>Design 4. Enhanced database integration.</figcaption></figure><p>But… this is an even scarier version of “Database integration”! <strong>The coupling between services became even tighter</strong>. Now, Aggregation service not only reads from Data service DB but also writes there! It’s a mind blow during refactoring. As a developer, you’re trying to find the code in Data service that changes its data, but you can’t. It’s not there. Later, it turns out to be in another service. Another service touches the data with its “dirty hands”! This is a complete violation of loose coupling principles between two systems. That’s bad.</p><h3>A knight’s move: two services become one</h3><p>Can we turn the situation around? Can we escape this vicious circle and find a great solution that possesses all the pros of Design 4 but not its cons?</p><p>In fact, we can make a knight’s move and mitigate the cons of database integration. We will join the code of both Data and Aggregation services in one repository and take out their DAO code into a separate library shared between them. The shared DAO module will contain migrations with DB schemas, entities (data structures), repositories, and connection settings. Because we share DAO module on the code level, we guarantee that it will always be the same in the two services, and any significant change in it will be supported in both. Otherwise, the build will be broken. Also, we will configure our build to generate two artifacts (previously two services) to be deployed simultaneously.</p><p>In the article’s subsequent text, we will refer to the modules with deployment artifacts as applications (apps). This will help differentiate between a service with its own release cycle and a module with a deployment artifact.</p><p>Finally, we receive Design 5, where our two services become single with two applications connected via DB. The library module is used to get access to this DB. Aggregation app has become very simple and only has code related to aggregation and saving results.</p><figure><img alt="Design 5. One service, few modules." src="https://cdn-images-1.medium.com/max/1024/1*j2Obp_T5Q0fhuvKl6Ou32w.png" /><figcaption>Design 5. One service, few modules.</figcaption></figure><p>A critical condition for that scheme is that the two applications and DAO module must be developed and supported by one team and live in one repository. They must be versioned, released, and deployed together. That is the crucial difference from the services, which are often supported by separate teams and have their own release cycles.</p><p>Surprisingly, a service consisting of a few modules is a well-known and typical setup for many systems. And that is precisely the design we suggest as a solution to the problem at hand.</p><h3>Database integration wins</h3><p>But what was gained by this tricky move? Database integration is still there. Yes, we have a solution with a few modules integrated by DB. But wait with throwing stones at us a little bit. First, let’s return to the issues created by DB as a connection point and check them in our new design.</p><p><strong>Issue #1</strong>. Generally, database integration results in extreme complexity when changing the internal structures of tables.</p><p>But here, we have no external consumers. Aggregation app is the only consumer of original data, and it connects to DB only via DAO library. Our solution implies that all possible consumers of original data can access it only via DAO module. Suddenly, critical issue #1 is no longer valid for our case.</p><p><strong>Issue #2</strong>. Generally, database integration leads to very complex migrations.</p><p>Well, that’s also not true for our new solution. The strict synchronization of versions solves that. If we need to add a new migration in one application, we will implement it in DAO module, and it will automatically appear in the second application. This means we can ensure the DB schema is constantly updated to the latest version. If one module changes the schema, the second module will continue working correctly because we need to make any changes backward compatible to support rolling updates anyway (we suppose there are few instances of any service or application).</p><p>For example, we have two instances of a service, and we launch one with a new version and one with an old one. At the same time, the DB was already upgraded to the latest version, and the old-version instance works fine with it because, again, we must design any service to support backward-compatible schema migrations.</p><p><strong>Issue #3</strong>. It is impossible to change DB technology individually for each service.</p><p>It is obvious now that this issue does not apply to our multimodule service as we have only one service consisting of a few components. Thus, we can change DB technology for the entire service. We do not intend to use one technology for one application and another for the second. It’s also outside our plans to grow our service to contain many applications. And given the limited number of modules and the condition that all of them are supported by the same team, that issue isn’t a problem here. We will change the technology for all modules or leave it as it is.</p><p>Suddenly, after reviewing the initial issues, we discovered that we had addressed all of them in our module design. This is great, but there is more to come. Now, it’s time to consider the pros.</p><p>To start with, we save an enormous amount of time and effort because we <strong>don’t need to implement additional API and transfer all the data</strong> from one service to another. We also save on our decision to move aggregation API to Data app. Otherwise, we’d need to implement all endpoints, configuration, and security in a new application. And doing it from scratch requires a lot of work and a significant amount of code. Yet we already have Data app where all this is done for Data API, and we just reuse it.</p><p>Saving cloud resources is another advantage that might be even more impactful. As mentioned earlier, the aggregation job is a CPU-bound, heavy task. And we need powerful and expensive instances to run it. If we place API in the same application, we must keep these instances constantly running. Not all the instances, as it’s possible to scale them. But some percentage of containers should be up. However, without API, the app becomes just a job that can be executed on schedule. All the instances can be stopped after the calculations have been executed. At the same time, Data app (with all endpoints) always works and doesn’t use a lot of resources. So, Design 5 provides a <strong>much more efficient consumption of cloud resources</strong>. And if we consume fewer resources, it costs us less money. This is a significant pro.</p><p>So, we could implement everything very conventionally via two separate microservices and spend a lot of effort and resources on transferring data from one microservice to another. And all that only in order to do it as expected. However, we decided to think deeper and develop a better way to integrate the services (now the two components of one service). Using an approach that seemed illicit at the beginning.</p><h3>Any best practice has its limitations</h3><p>After careful examination of all the cons of database integration, we found a working solution for some, while others turned out not to play a role in our setup. As the database doesn’t play the role of a public API here, localizing access to it in the code and creating an abstraction layer is possible. We achieved this by developing a shared library to share schema changes between the two modules. As for the remaining issues, they are relevant only for cross-team communications. They aren’t applicable in our case because the project scope is not extensive, and we intend all modules to be supported by one team.</p><p>Overall, in this particular situation, database integration fits very well and has a lot of benefits over the microservice approach. It’s easier to develop, easier to maintain and cheaper to run. Of course, it’s not the only possible case. You can come up with others. The main thing is not to wave away a potential solution only because it is not a best practice.</p><p>Like with everything in life, there is no silver bullet. Each best practice solves some particular problems and has its area of applicability. In this case, creating microservices, even services, and building HTTP API brings more troubles than advantages. Instead, we take another practice that is recommended to avoid any possible way. We take it and pay attention to why it is considered so bad. We address some of its downsides, and others turn out to be irrelevant to this particular solution. As a result, we can now easily use this pattern, and it works wonderfully for our purposes.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e5c790778fa2" width="1" height="1" alt=""><hr><p><a href="https://medium.com/javarevisited/when-database-integration-beats-microservices-e5c790778fa2">When database integration beats microservices</a> was originally published in <a href="https://medium.com/javarevisited">Javarevisited</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why you shouldn’t use LocalDateTime (to avoid production issues)]]></title>
            <link>https://medium.com/javarevisited/why-you-shouldnt-use-localdatetime-to-avoid-production-issues-d2833fc7df41?source=rss-b35815eadd55------2</link>
            <guid isPermaLink="false">https://medium.com/p/d2833fc7df41</guid>
            <category><![CDATA[coding]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[datetime]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[ThinkSystem]]></dc:creator>
            <pubDate>Sat, 03 Feb 2024 10:21:27 GMT</pubDate>
            <atom:updated>2024-04-17T08:25:26.294Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*t33PJxlxBs_eST-xeY2D5Q.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/@jontyson?utm_source=medium&amp;utm_medium=referral">JonTyson</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><h3>Introduction</h3><p>On one unfortunate day, the alert is fired — there is a difference between data in two systems that should be in sync. You checked all the code that might be related, and everything looks good. However, the timestamps are indeed different. Or some users complain about incorrect history records order. Again, the code looks fine, and only some users are affected. Or maybe after some server maintenance, your data doesn’t look like the day before. You didn’t touch the code, and there are no changes in the database, but the system returns different results.</p><p>All of the above begins the tiresome and complex journey to find the root cause of these issues. And the reason is the same everywhere — incorrect choice of datetime variables in the code, to be more precise — using LocalDateTime as a default option.</p><p>Working correctly with time has always been <a href="https://gist.github.com/timvisee/fcda9bbdff88d45cc9061606b4b923ca">quite challenging</a> due to a number of hidden issues that you can experience after a successful release to production. There are a lot of things that can go wrong. Of course, there are some cases when LocalDateTime<strong> </strong>is helpful, but you have to choose it deliberately and for a reason, not just select it as a default and most straightforward option. This article is for Java/Kotlin developers. It explains the consequences of misusing LocalDateTime to store timestamps and provides a solution. Also, it contains an overview of all datetime types from the<strong> java.time</strong> package, together with use cases for each of them.</p><h3>Issues with LocalDateTime</h3><p>So, what is wrong with LocalDateTime?</p><p>Firstly, and most importantly, since it is Local, no time zone is stored in the value. In other words, there is no explicit time zone, so we must rely on an implicit one. Thus, our code <strong>depends on its environment</strong> or, if we are lucky, on the hardcoded constants (with the current time zone passed to the objects generating timestamps). The environment is generally considered unreliable and for a reason: server, client, and DB can have different time zones and even change them at some point. Imagine the following situation: we had a server in Warsaw’s data center that moved to another data center in Lisbon. The time zone changed, but the server domain name remained the same. For both developers and users, there was just a maintenance downtime. Nothing has changed from their perspective. But in fact, for server the environment changed, default time zone changed and all timestamps in the data generated without explicit time zone, will change. And that is the root cause of numerous possible issues.</p><p>At the same time, clients calling an API and receiving a response with LocalDateTime inside have to rely on the documentation to identify the time zone. If it is declared in this documentation. Unfortunately, often, it is not even mentioned there. If the latter is the case, it makes the<strong> </strong>API contract implicit; it is not enforced and, again, is subject to change at any time.</p><p>Secondly, another big problem is that you <strong>can not compare two LocalDateTime values</strong>. It doesn’t make much sense to compare time without a time zone, at least an implicit one. But even if you are sure you have two values in the same time zone, you still can not compare them because local time is not linear. As a matter of fact, things are much worse: it is not only possible to have duplicates, but time can even<strong> </strong>go backwards. And <a href="https://en.wikipedia.org/wiki/Daylight_saving_time">DST</a> is one of the examples of how such a situation can arise. <a href="https://en.wikipedia.org/wiki/Daylight_saving_time">DST</a> is a practice of setting clocks forward by one hour in spring and setting it back also by one hour in autumn to bring more daylight to working hours. It is used in many countries.</p><p>So, DST is not some hypothetical situation. It is what happens every year in many countries. Let’s take the winter shift on October 29th 2023, in the Europe/Amsterdam time zone as an example. Currently, local time is 02.55, which matches UTC 00:55. Five minutes later, at 03.00, the time shift is executed, and the clocks are set back by one hour. Thus, 10 minutes later, after 02.55, the local time is 02.05 (UTC 01:05). Fifty minutes later, the time is again 02.55 (UTC 01:55). And here we get two duplicates. Time is not unique anymore.</p><p>Consequently, if you can not compare timestamp values, you cannot also sort them. But this is required for many essential features such as providing a list of products, order history records, audit records, to search on some time interval, etc.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/431/1*6iyh5AkMV2eLXSbJF9X99Q.png" /><figcaption>Winter time shift on October 29th 2023, Europe/Amsterdam time zone.</figcaption></figure><p>Let’s think about it in a more picturesque way. Imagine the following situation: your handsome cat accidentally comes to your kitchen at 02.35 at night, looks at the clock on the kitchen’s wall, and starts doing his business with the food. At 03.00, you also come to the kitchen and set back the clocks by one hour. 40 minutes after your manipulations, the fat cat looks at the clocks again and sees 02.40. He is not able to understand if you changed the time or not. He sees the duplicate. He doesn’t know time zones very well and doesn’t know that clocks have shown the same time twice.<br>And so the cat is confused. For him, just 5 minutes had passed. But he is so hungry again!</p><h3>ZonedDateTime is not a solution</h3><p>How can we solve this problem? If the implicit time zone is a cause, should we make it explicit using ZonedDateTime?</p><p>Well, ZonedDateTime is significantly better because indeed it contains an explicit time zone. As a result, the API contract is clear now. Users don’t have to check the documentation to understand the time zone — in API, you return ZonedDateTime, which includes the timestamp and a time zone. Even better, there is no dependency on the environment anymore. Since the time zone is exposed in API, it is safe to change it. Therefore, you can choose whichever you want without unpleasant consequences, and backward compatibility will be preserved.</p><p>But unfortunately, ZonedDateTime is <strong>still non-linear</strong>. In the case of DST, the time zone remains the same, but the actual offset from UTC changes. In our first example, before the time shift, the local time has two hour offset from UTC, and after, there is a one hour offset. But even if we know the time zone, it will not help us to avoid getting a duplicate time. We still can’t compare two values, in this case, of the ZonedDateTime type.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/621/1*Sf88nkskn7d-uBX8bokGrA.png" /><figcaption>Change of offset during winter time shift.</figcaption></figure><p>Back to the clock on the wall example. Even if your cat knows the time zone, it will not help him understand that it is time to have the next snack.</p><h3>Maybe OffsetDateTime?</h3><p>Ok, there is another type, OffsetDateTime. Maybe it is a solution?</p><p>OffsetDateTime represents time with some defined offset from UTC. Yes, it is finally linear and safe to use in all cases: you can compare two variables of OffsetDateTime, store them and use them in API without any issues. It is even valid to compare two values with different offsets. However, unfortunately, it’s still too early to celebrate victory. The real problem lies in OffsetDateTime being very generic. It is very abstract and not tied to any real time zone, and it represents time with some defined offset from UTC. Time and time zone are geographical and political terms because they are tied to the borders of the countries or their subdivisions, and their decisions to follow one or another time zone. Time in any place in the world is defined by the government of the country where this place is located. On the other hand, an OffsetDateTime variable corresponds to some point in time not connected to a real time zone, country, or place in the world. For example, if we take OffsetDateTime with offset = +1, it will match wintertime in Europe/Amsterdam, but in summer, it will be incorrect for this location. It doesn’t make much sense. Theoretically, the Netherlands might decide to refuse DST a few years later, and after that, our variable will be incorrect.</p><p>After all, on the one hand, OffsetDateTime solves all the issues related to LocalDateTime and ZonedDateTime, but on the other, it <strong>does not match with any real time zone</strong>. Due to that, it introduces its own problems. So, maybe it’s better to use a type that always matches only one time zone? Ideally, the UTC zone as it is a basis for all time zones. And yes, it is a great idea and, luckily, such a type exists!</p><h3>Instant is your choice by default</h3><p>And finally, there is good news! You can use one type for timestamp everywhere without problems: <strong>Instant is your default option</strong>.</p><p>Basically, it is ZonedDateTime with a locked UTC time zone. UTC time zone will save us from all the pesky DST issues. When some event happens, it happens at the exact moment in all time zones. And Instant implements this idea: it represents a fixed moment on the timeline and is timezone-agnostic in the sense that it does not relate to the time zone term. There is no way to change the timezone. It just matches UTC. Instant is also fully compatible with OffsetDateTime/ZonedDateTime types both on the serialisation and database level. All of these types implement the same ISO-8601 datetime serialisation/deserialisation standard. Moreover, if you store in DB timestamp with timezone, it’s absolutely correct to refer to this timestamp using Instant/ZonedDateTime/OffsetDateTime in your code. No additional actions are required.</p><p>As a result, Instant solves all the issues introduced by LocalDateTime. It doesn’t depend on the environment due to the constant time zone, and the serialised timestamp contains the UTC zone in the API. Furthermore, it’s linear because there is no DST in UTC. Thus, it is safe to use Instant in any case.</p><p>All that doesn’t mean you should always use only Instant and nothing more. The idea is that Instant should be your default type. If it doesn’t suit your needs for some reason, then you can consider other types. Each of them is useful for its particular cases.</p><h3>What are valid use cases for ZonedDateTime?</h3><p>Well, first of all, it is used for integration and backward compatibility. For example, if you already provide some legacy API for other systems that expect to receive this type from your service or if you need to integrate with another system with tricky requirements. In these cases, you can always use ZonedDateTime to maintain compatibility. Another example is timezone-aware configuration for schedulers. Imagine you would like to start a promo campaign at a specific time. But in which time zone? With ZonedDateTime, you can explicitly define that it should be at 10:00 a.m. Amsterdam time because it’s a campaign in the Netherlands. You don’t need to think about DST in this case because it should be in the most straightforward format for people supporting this configuration, and you don’t care how this time matches UTC. The last case is when the business logic of your application/feature is heavily connected with timezones (calendar, task manager, time management tools).</p><h3>But can we ever use LocalDateTime?</h3><p>Of course, LocalDateTime was created for a reason. Again, it can be used for integration and backward compatibility, it always will be there. You can create a new version of API with Instant for more advanced consumers, and leave an old one with LocalDateTime for those you don’t want to change their logic.</p><p>Furthermore, we can use LocalDateTime for timezone-related configuration. For example, we have users distributed between multiple timezones and want to send them a promo notification. Obviously, we would prefer that our users will open this notification, but a chance of that is much higher if we send it at some reasonable time(like 10:00), not in the middle of the night. Consequently, our goal is that all our users will receive a promo at 10.00 a.m. in <strong>their</strong> time. Thus, they all will get it at a different moment on the timeline. And we can achieve this by defining a desired time as local time and sending notifications based on <strong>users</strong> timezone. This way all users will receive a push at 10:00 in <strong>their</strong> timezone. On the implementation side we will use LocalDateTime to store configuration settings, and convert it to ZonedDateTime based on the users timezones, for actual distribution.</p><p>And the most common case for LocalDateTime is formatting. LocalDateTime can be used in WEB UI or desktop/mobile applications, for reports. For these purposes when you don’t need to show the time zone for each timestamp. The user doesn’t want to see the time together with time zone, because he knows where he is located. Also, he doesn’t want to see it in UTC. He wants to see it in local time. On the client’s side, you can take the data received from the server, convert it to local time and display it to the user. And here LocalDateTime is the best option.</p><h3>OffsetDateTime?</h3><p>As for OffsetDateTime, the real need for this type appears only in highly specialised applications working with offsets.</p><h3>Conclusion</h3><p>One day, thoughtless use of the LocalDateTime type will lead to very unpleasant production issues. Yes, these issues might be pretty rare. However, for some applications, the reliability requirements are very high, and the consequences of unpredictable issues might be harrowing. Unfortunately, it’s complicated to predict what might happen, how critical the issue will be, and how extensive the scope of such an issue will be.</p><p>But you can easily avoid all the troubles and make your application much more reliable. To achieve that with no maintenance and minimal mental effort, you need to use Instant as a default type whenever you need to work with datetime.</p><p>And it is one of the tiny but extremely important bits that can help your application overcome the gap between “works almost all the time” and “works all the time”. Even if you are not writing a mission critical system, using the best practice will make life much easier in the future.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d2833fc7df41" width="1" height="1" alt=""><hr><p><a href="https://medium.com/javarevisited/why-you-shouldnt-use-localdatetime-to-avoid-production-issues-d2833fc7df41">Why you shouldn’t use LocalDateTime (to avoid production issues)</a> was originally published in <a href="https://medium.com/javarevisited">Javarevisited</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>