<?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 Mridul Choudhary on Medium]]></title>
        <description><![CDATA[Stories by Mridul Choudhary on Medium]]></description>
        <link>https://medium.com/@myc5?source=rss-77580d871ef9------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*gCfsjc6AUk1lOL0JJYEZAw.jpeg</url>
            <title>Stories by Mridul Choudhary on Medium</title>
            <link>https://medium.com/@myc5?source=rss-77580d871ef9------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 09:11:03 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@myc5/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[The processor: OAuth refresh and idempotent persistence]]></title>
            <link>https://medium.com/@myc5/the-processor-oauth-refresh-and-idempotent-persistence-e9b91f3f8173?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/e9b91f3f8173</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[aws-lambda]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Thu, 05 Nov 2026 17:49:57 GMT</pubDate>
            <atom:updated>2026-11-05T17:49:57.058Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Series navigation:</strong><br><a href="https://medium.com/@myc5/the-architecture-and-the-why-a-strava-aws-webhook-pipeline-a94792892c9d?sharedUserId=myc5">Part 1: Architecture &amp; why</a><strong><br></strong><a href="https://medium.com/@myc5/the-ingest-edge-answering-strava-fast-and-never-retrying-yourself-into-a-corner-1fcaf644fd2a?sharedUserId=myc5">Part 2: The ingest edge</a> (<a href="https://github.com/Mridul047/athlenz-event-ingestor">Git</a>)<br><strong>Part 3: The processor (</strong><a href="https://github.com/Mridul047/athlenz-event-processor"><strong>Git</strong></a><strong>)</strong><br>Part 4: Onboarding &amp; the token contract (Git)</p><p>Part 2 ended with an event sitting on an SQS queue, tagged with an idempotency key. This is where the slow work finally happens. <br>The processor is another plain Java 21 Lambda (no framework) but this one is triggered by SQS and gets to take its time: resolve the athlete’s OAuth token, refresh it if needed, fetch the detailed activity from Strava, and persist a compact record. <br>Two problems dominate the design: tokens that expire, and a delivery guarantee that is only <em>at least once</em>. Here is how each is handled, straight from the code.</p><h3>Resolving a token, with a safety buffer</h3><p>Every activity fetch needs a valid access token for the owning athlete. <br>The service loads the stored token from DynamoDB and decides whether it is still good. The non-obvious choice is to treat a token that is merely <em>about</em> to expire as already expired, using a 60-second buffer (StravaOAuthService.java):</p><pre>private static final long EXPIRY_BUFFER_SECONDS = 60;<br>  <br>private boolean isExpired(AthleteToken token) {<br>    long nowEpochSeconds = clock.instant().getEpochSecond();<br>    return token.getExpiresAt() &lt;= nowEpochSeconds + EXPIRY_BUFFER_SECONDS;<br>  }</pre><p>The buffer exists so an in-flight API call does not fail with a token that expired between the check and the request, whether from clock skew or request latency. <br>If there are no stored tokens at all, the service throws NoSuchElementException — the athlete simply has not completed OAuth, which is the connector&#39;s job in Part 4.</p><p>When a refresh is needed, the service calls Strava’s token endpoint and writes the result back. Strava rotates refresh tokens, so the new refresh token must be persisted every time (StravaOAuthService.java):</p><pre> private String refreshAndStore(AthleteToken token) {<br>    StravaClientCredentials creds = credentialsProvider.get();<br>    StravaTokenResponse response =<br>        tokenClient.refresh(<br>            StravaTokenRefreshRequest.forRefresh(<br>                creds.clientId(), creds.clientSecret(), token.getRefreshToken()));<br><br>    token.setAccessToken(response.accessToken());<br>    // Strava rotates the refresh token; always persist the latest.<br>    token.setRefreshToken(response.refreshToken());<br>    token.setExpiresAt(response.expiresAt() != null ? response.expiresAt() : 0L);<br>    tokenStore.save(token);<br><br>    LOG.info(&quot;Refreshed and stored tokens for athlete {}&quot;, token.getAthleteId());<br>    return token.getAccessToken();<br>  }</pre><p>Forget to write back the rotated refresh token and the next refresh fails a subtle bug the comment guards against. The refresh request itself goes to Strava as application/x-www-form-urlencoded with grant_type=refresh_token, and a non-2xx response throws so the SQS message is retried later.</p><h3>Client credentials from Secrets Manager, cached</h3><p>The client ID and secret used in that refresh live in Secrets Manager, not in environment variables or code. They are fetched lazily on first use and cached for the lifetime of the execution environment (ClientCredentialsProvider.java):</p><pre>  public StravaClientCredentials get() {<br>    StravaClientCredentials cached = cache.get();<br>    if (cached != null) {<br>      return cached;<br>    }<br>    StravaClientCredentials loaded = load();<br>    // If two invocations race, either result is equally valid.<br>    cache.compareAndSet(null, loaded);<br>    return cache.get();<br>  }</pre><p>Caching avoids a Secrets Manager call on every invocation lower latency and cost while a fresh execution environment still picks up a rotated secret. Credential values are never logged.</p><h3>One activity event, end to end</h3><p>Putting those pieces together, here is what processing a single activity event looks like, including the token-valid versus needs-refresh branch and the duplicate-delivery branch:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_1V6DCk1x4G36bsSwL9kgw.png" /></figure><p>The fetch is a GET {baseUrl}/activities/{id} with an Authorization: Bearer &lt;token&gt; header. A 404 from Strava is logged specifically: it means the activity is not visible to this token commonly a private &quot;Only You&quot; activity when the token lacks activity:read_all, or a token that does not belong to the owner. <br>The JSON is parsed into a DetailedActivity model and mapped to a compact ActivityRecord carrying only the fields a reader would care about: id, name, type, sport type, distance, moving and elapsed time, elevation gain, start date, plus the idempotency key and a processed-at timestamp.</p><p>Those DetailedActivity models are not hand-written. They are generated at build time by the OpenAPI Generator from Strava&#39;s swagger spec, models only (generateApis is false), into the package com.strava.api.v3.model — the actual HTTP calls use the JDK&#39;s built-in client. It is a nice way to get typed, accurate models without owning the boilerplate.</p><h3>Idempotency: the headline decision</h3><p>SQS gives at-least-once delivery, so the same event can arrive more than once. Rather than track “have I seen this?” separately, the write itself is the dedupe. The record is keyed in DynamoDB by activityId (that is the @DynamoDbPartitionKey on ActivityRecord), and the conditional put uses the idempotency key only inside the condition (ActivityStore.java):</p><pre> public boolean saveIfNew(ActivityRecord record) {<br>    Expression condition =<br>        Expression.builder()<br>            .expression(&quot;attribute_not_exists(activityId) OR idempotencyKey &lt;&gt; :k&quot;)<br>            .expressionValues(<br>                Map.of(&quot;:k&quot;, AttributeValue.builder().s(record.getIdempotencyKey()).build()))<br>            .build();<br><br>    try {<br>      table.putItem(<br>          PutItemEnhancedRequest.builder(ActivityRecord.class)<br>              .item(record)<br>              .conditionExpression(condition)<br>              .build());<br>      return true;<br>    } catch (ConditionalCheckFailedException duplicate) {<br>      // Same delivery already persisted; safe to ignore.<br>      return false;<br>    }<br>  }</pre><p>The subtlety is worth spelling out, because it is easy to describe wrong. The table is keyed by activityId, not by the idempotency key.<br>The write is allowed when either no item exists for that activity id yet, or an item exists but with a <em>different</em> idempotency key for example a later &quot;update&quot; event for the same activity, which should overwrite. It is rejected only when an item with the <em>same</em> idempotency key already exists, which is a true duplicate delivery. <br>A rejected write throws ConditionalCheckFailedException, caught and treated as a harmless no-op. One conditional put gives me both overwrite-on-update and reject-on-replay.</p><h3>Partial-batch failures: retry only what failed</h3><p>The handler pulls up to 10 messages per batch and must not let one bad message sink the other nine. It processes each message independently and returns an SQSBatchResponse naming only the failures (WebhookWorkerHandler.java):</p><pre>for (SQSEvent.SQSMessage message : input.getRecords()) {<br>      String messageId = message.getMessageId();<br>      try {<br>        StravaWebhookEvent event =<br>            objectMapper.readValue(message.getBody(), StravaWebhookEvent.class);<br>        LOG.info(<br>            &quot;Processing message {}: athleteId={} activityId={} aspect={}&quot;,<br>            messageId,<br>            event.ownerId(),<br>            event.objectId(),<br>            event.aspectType());<br>        processor.process(event);<br>      } catch (IOException e) {<br>        // A message we cannot even parse will never succeed on retry. Log and<br>        // DO NOT add to failures, so it is not retried forever; it is<br>        // effectively dropped (and visible in logs).<br>        LOG.error(&quot;Dropping unparseable message {}&quot;, messageId, e);<br>      } catch (Exception e) {<br>        // Transient/processing failure: report it so SQS retries just this message.<br>        LOG.error(&quot;Failed to process message {}; will be retried&quot;, messageId, e);<br>        failures.add(<br>            SQSBatchResponse.BatchItemFailure.builder().withItemIdentifier(messageId).build());<br>      }<br>    }<br><br>    LOG.info(&quot;Batch complete: received={} failed={}&quot;, received, failures.size());<br>    return SQSBatchResponse.builder().withBatchItemFailures(failures).build();</pre><p>There are three distinct outcomes, and the difference between the two catch blocks is the whole point. An unparseable message will never succeed on retry, so it is logged and <em>not</em> added to the failure list effectively dropped, but visible in logs. A transient processing failure <em>is</em> added, so SQS redelivers just that message. This works because the event source mapping enables partial batch responses (template.yaml):</p><pre>Events:<br>        Queue:<br>          Type: SQS<br>          Properties:<br>            Queue: !Ref EventQueueArn<br>            BatchSize: 10<br>            FunctionResponseTypes:<br>              - ReportBatchItemFailures</pre><p>With ReportBatchItemFailures, SQS retries only the reported messages rather than the whole batch, and a message that keeps failing is redriven to the DLQ after the queue&#39;s maxReceiveCount of 5 (that queue, remember, is owned by the ingest stack). The flow:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C6uBgmqoUsn_ITlfiuCg_g.png" /></figure><p>That “activity &amp; not delete” gate lives in the processor, which skips anything there is nothing to fetch for (ActivityProcessor.java):</p><pre>if (!event.isActivity()) {<br>      LOG.info(&quot;Skipping non-activity event objectType={}&quot;, event.objectType());<br>      return;<br>    }<br>    if (StravaWebhookEvent.ASPECT_DELETE.equals(event.aspectType())) {<br>      LOG.info(&quot;Skipping delete event for activity {}&quot;, event.objectId());<br>      return;<br>    }</pre><h3>What this processor is not</h3><p>To keep the claims honest: the processor has no SnapStart — that is only on the ingestor, where the handshake deadline justifies it. It runs at 512 MB with a 30-second timeout. The only token-timing number in the code is the 60-second refresh buffer; there is no refresh-cadence or TTL tuning beyond that, and I am not going to invent any.</p><h3>Takeaways</h3><ul><li>Refresh tokens slightly early. A fixed buffer (here, 60 seconds) turns a class of clock-skew and latency failures into non-events, and rotated refresh tokens must always be written back.</li><li>Make the persistence layer carry idempotency. A single conditional put keyed by the resource, conditioned on the delivery key gives you both overwrite-on-update and reject-on-replay, which is exactly what at-least-once delivery demands.</li><li>Treat poison messages and transient failures differently. Drop what can never succeed; report what might, so ReportBatchItemFailures retries only the right messages and the DLQ catches the rest.</li><li>Generate external models from the provider’s spec instead of hand-rolling them, but keep the HTTP simple.</li></ul><p>Last stop: the connector, which is how an athlete’s tokens get into strava-state in the first place and the exact item contract this processor depends on.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e9b91f3f8173" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The ingest edge: answering Strava fast and never retrying yourself into a corner]]></title>
            <link>https://medium.com/@myc5/the-ingest-edge-answering-strava-fast-and-never-retrying-yourself-into-a-corner-1fcaf644fd2a?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/1fcaf644fd2a</guid>
            <category><![CDATA[aws-lambda]]></category>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Sun, 01 Nov 2026 17:21:30 GMT</pubDate>
            <atom:updated>2026-11-05T17:51:18.385Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Series navigation:</strong><br><a href="https://medium.com/@myc5/the-architecture-and-the-why-a-strava-aws-webhook-pipeline-a94792892c9d?sharedUserId=myc5">Part 1: Architecture &amp; why</a><strong><br>Part 2: The ingest edge (</strong><a href="https://github.com/Mridul047/athlenz-event-ingestor"><strong>Git</strong></a><strong>)</strong><br><a href="https://medium.com/@myc5/the-processor-oauth-refresh-and-idempotent-persistence-e9b91f3f8173?sharedUserId=myc5">Part 3: The processor</a> (<a href="https://github.com/Mridul047/athlenz-event-processor">Git</a>)<br>Part 4: Onboarding &amp; the token contract (Git)</p><p>Part 1 argued that whatever answers Strava must do almost nothing, because the validation handshake has to return within about 2 seconds. This post is the edge itself: a plain Java 21 Lambda, no framework, fronted by API Gateway, that handles two interactions on one URL and then gets out of the way. <br>The interesting decisions here are not about what the code does it is small but about what it deliberately refuses to do.</p><h3>Two interactions, one URL</h3><p>Strava uses the single callback URL for a GET validation handshake and ongoing POST event deliveries. The handler maps each HTTP method onto a transport-independent service so the logic can be unit tested without API Gateway types. <br>The GET path is the only place the shared secret is ever checked (WebhookService.java):</p><pre>  public WebhookResult validate(Map&lt;String, String&gt; query) {<br>    Map&lt;String, String&gt; q = query == null ? Map.of() : query;<br>    String mode = q.get(&quot;hub.mode&quot;);<br>    String token = q.get(&quot;hub.verify_token&quot;);<br>    String challenge = q.get(&quot;hub.challenge&quot;);<br><br>    if (!&quot;subscribe&quot;.equals(mode) || challenge == null || challenge.isBlank()) {<br>      LOG.info(&quot;Rejecting validation request: missing or invalid hub.mode/hub.challenge&quot;);<br>      return WebhookResult.badRequest();<br>    }<br><br>    if (!verifyToken.equals(token)) {<br>      // Do not log the expected or received token values.<br>      LOG.error(&quot;Rejecting validation request: verify token mismatch&quot;);<br>      return WebhookResult.forbidden();<br>    }<br><br>    LOG.info(&quot;Subscription validation handshake accepted&quot;);<br>    try {<br>      // {&quot;hub.challenge&quot;:&quot;&lt;challenge&gt;&quot;}<br>      String body = objectMapper.writeValueAsString(Map.of(&quot;hub.challenge&quot;, challenge));<br>      return WebhookResult.ok(body);<br>    } catch (Exception e) {<br>      throw new IllegalStateException(&quot;Failed to serialize validation response&quot;, e);<br>    }<br>  }</pre><p>A missing or malformed mode/challenge returns 400.<br>A token mismatch returns 403 so a third party cannot complete a subscription on my behalf.<br>A valid request echoes the challenge back as JSON with a 200. <br>Those status codes are the whole value vocabulary of the edge WebhookResult is a tiny record with factory methods ok(), ok(body), badRequest() (400), forbidden() (403), and methodNotAllowed() (405).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tv3w4mBy5rX4brUpMRgMHA.png" /></figure><p>One detail worth stating precisely: in code the verify token defaults to the literal &quot;local-dev-verify-token&quot; when STRAVA_VERIFY_TOKEN is unset, which is a convenience for local development. <br>In the deployed stack the value is always set from the StravaVerifyToken SAM parameter, so the default never applies in production.</p><h3>Why the POST path returns 200 even when it ignores you</h3><p>The delivery path is where the non-obvious decision lives. The temptation is to validate strictly and return a 4xx for anything you do not like. <br>That is exactly wrong for a webhook, because Strava treats a non-2xx as a failure and retries. <br>Return 400 for a malformed body and you have signed up for a retry storm of the same bad body. So the rule is: acknowledge almost everything with 200, and only enqueue the events I actually want (WebhookService.java):</p><pre>  public WebhookResult receive(String body) {<br>    if (body == null || body.isBlank()) {<br>      LOG.info(&quot;Received empty webhook body; acknowledging without processing&quot;);<br>      return WebhookResult.ok();<br>    }<br><br>    final StravaWebhookEvent event;<br>    try {<br>      event = objectMapper.readValue(body, StravaWebhookEvent.class);<br>    } catch (Exception e) {<br>      // Malformed body: ack anyway (200) to avoid Strava retry storms,<br>      // but log so we can investigate. A 4xx here would be retried.<br>      LOG.info(&quot;Received malformed webhook event; acknowledging without processing&quot;);<br>      return WebhookResult.ok();<br>    }<br><br>    if (event == null || event.objectType() == null || event.objectId() == null) {<br>      LOG.info(&quot;Received webhook event missing required fields; acknowledging without processing&quot;);<br>      return WebhookResult.ok();<br>    }<br><br>    if (!event.isActivity()) {<br>      LOG.info(&quot;Ignoring non-activity event: objectType={}&quot;, event.objectType());<br>      return WebhookResult.ok();<br>    }<br><br>    publisher.publish(event);<br>    LOG.info(<br>        &quot;Accepted activity event objectId={} ownerId={} aspect={}&quot;,<br>        event.objectId(),<br>        event.ownerId(),<br>        event.aspectType());<br>    return WebhookResult.ok();<br>  }</pre><p>Empty body, unparseable JSON, missing required fields, non-activity object each is acknowledged with a 200 and dropped. <br>Only events where isActivity() is true (that is, objectType equals &quot;activity&quot;) are published. <br>This is the ladder, straight from the ingestor README:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AgD3RjrdsH_GV-Y9fdkHJg.png" /></figure><h3>No framework, wired in a constructor</h3><p>There is no Micronaut or Spring here, no DI container. <br>The handler implements the Lambda RequestHandler directly against the API Gateway proxy types, and the expensive setup happens once in the constructor during the Lambda init phase, reused across warm invocations. The wiring looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*H6lGkkosnSZGJxwAqp7kTg.png" /></figure><p>Picking a publisher is a plain runtime if, decided once at construction, with no bean conditions (WebhookHandler.java):</p><pre>    WebhookEventPublisher publisher;<br>    if (queueUrl != null &amp;&amp; !queueUrl.isBlank()) {<br>      SqsClient sqsClient =<br>          SqsClientFactory.create(env.get(&quot;AWS_ENDPOINT_OVERRIDE&quot;), env.get(&quot;AWS_REGION&quot;));<br>      publisher = new SqsWebhookEventPublisher(sqsClient, objectMapper, queueUrl);<br>      LOG.info(&quot;Publishing webhook events to SQS&quot;);<br>    } else {<br>      publisher = new LoggingWebhookEventPublisher();<br>      LOG.info(&quot;No EVENT_QUEUE_URL configured; logging events instead of enqueuing&quot;);<br>    }</pre><p>When EVENT_QUEUE_URL is set, it builds a real SQS client and publishes; otherwise it logs, which is all local development needs. <br>The SDK client itself is built with UrlConnectionHttpClient rather than the default Apache client, for a smaller dependency footprint and faster startup the kind of choice that only matters because cold start is on the critical path.</p><h3>SnapStart for the cold-start problem</h3><p>The 2-second window is a real risk for a cold JVM, and the template attacks it structurally rather than hoping. IngestFunction runs at 1024 MB (Lambda scales CPU with memory, so more memory shortens init) and turns on SnapStart for published versions behind an auto-published alias (template.yaml):</p><pre>      SnapStart:<br>        ApplyOn: PublishedVersions<br>      AutoPublishAlias: live</pre><p>SnapStart snapshots the initialized execution environment and restores from it, so the first real request no longer pays the full JVM start, class-load, and client-construction cost. <br>I am claiming the mechanism, not a measured number there is no benchmarked cold-start figure in the repo, and I will not pretend otherwise.</p><h3>The idempotency key, set at the edge</h3><p>Every enqueued message carries an idempotencyKey so the downstream processor can dedupe without re-parsing the body. The key is deterministic, built from the event itself (StravaWebhookEvent.java):</p><pre>  public String idempotencyKey() {<br>    return objectType + &quot;#&quot; + objectId + &quot;#&quot; + aspectType + &quot;#&quot; + eventTime;<br>  }</pre><p>That value rides along as an SQS message attribute (SqsWebhookEventPublisher.java):</p><pre>SendMessageRequest request =<br>        SendMessageRequest.builder()<br>            .queueUrl(queueUrl)<br>            .messageBody(body)<br>            // Carry the idempotency key as an attribute so the processor<br>            // (and anyone inspecting the queue) can dedupe without<br>            // re-parsing the body.<br>            .messageAttributes(<br>                Map.of(<br>                    &quot;idempotencyKey&quot;,<br>                    MessageAttributeValue.builder()<br>                        .dataType(&quot;String&quot;)<br>                        .stringValue(event.idempotencyKey())<br>                        .build()))<br>            .build();</pre><p>A replay of the same event maps to the same key, which is what makes the processor’s conditional write in Part 3 safe.</p><h3>The DLQ, the visibility timeout, and an honest trust boundary</h3><p>The queue is defined with a redrive policy so a message that fails processing five times lands in a dead-letter queue instead of looping forever (template.yaml):</p><pre>      RedrivePolicy:<br>        deadLetterTargetArn: !GetAtt EventDlq.Arn<br>        maxReceiveCount: 5</pre><p>The EventDlq keeps messages for 14 days (MessageRetentionPeriod: 1209600). The EventQueue also sets VisibilityTimeout: 180 sized at roughly six times the processor&#39;s 30-second timeout, which is a consumer concern, not a producer one and DelaySeconds: 15, a short propagation delay so the processor&#39;s first fetch does not race Strava&#39;s API and get a spurious 404. That delay sits between ingest and the processor; it does not affect how fast ingest answers Strava.</p><p>On IAM, the function gets exactly one permission: SQSSendMessagePolicy scoped to EventQueue. An ingest producer needs nothing more.</p><p>Now the uncomfortable part. The GET handshake is verified with the token, but event POSTs are <strong>not</strong> authenticated.Strava sends no signature or per-event secret, so a caller cannot be cryptographically verified at the application layer:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9jTeT_k5qMPhp8odR_47kg.png" /></figure><p>The real boundary is downstream: the processor can only fetch data for athletes whose OAuth tokens are stored, so a forged event for an unknown athlete fails the token lookup and is redriven to the DLQ rather than fabricating activity data. <br>The README names edge hardening API Gateway throttling, WAF rate limiting, a secret path segment in the callback URL as recommended mitigations for forged-POST floods, not things the code implements today. I treat them as suggestions, not features.</p><h3>Takeaways</h3><ul><li>For a webhook, your HTTP status code is a control signal to the sender. Returning 200 for events you intend to ignore is what prevents retry storms; a 4xx would be retried.</li><li>Check the shared secret in exactly one place, the handshake and be clear-eyed that ongoing deliveries are unauthenticated. Put the real security boundary downstream where tokens gate access to data.</li><li>No framework is a legitimate choice when cold start is on the critical path: construct dependencies once in the init phase, pick a lean HTTP client, and lean on SnapStart plus memory to beat the window.</li><li>Set the idempotency key at the edge, where the event arrives, so the slow consumer can dedupe cheaply.</li></ul><p>Next: the processor, where the slow work finally happens. OAuth refresh, the Strava API call, and an idempotent write that makes at-least-once delivery safe.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1fcaf644fd2a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The architecture and the why: A Strava AWS webhook pipeline]]></title>
            <link>https://medium.com/@myc5/the-architecture-and-the-why-a-strava-aws-webhook-pipeline-a94792892c9d?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/a94792892c9d</guid>
            <category><![CDATA[aws-lambda]]></category>
            <category><![CDATA[event-driven-architecture]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Sat, 31 Oct 2026 18:20:18 GMT</pubDate>
            <atom:updated>2026-11-01T17:22:19.843Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Series navigation:</strong> <br><strong>Part 1: Architecture &amp; why <br></strong><a href="https://medium.com/@myc5/the-ingest-edge-answering-strava-fast-and-never-retrying-yourself-into-a-corner-1fcaf644fd2a?sharedUserId=myc5">Part 2: The ingest edge</a> (<a href="https://github.com/Mridul047/athlenz-event-ingestor">Git</a>)<br>Part 3: The processor (Git)<br>Part 4: Onboarding &amp; the token contract (Git)</p><p>I built a small pipeline that listens for Strava activity events and turns them into durable records in my own AWS account. Then the raw activities data can converted into Athelete Insights using AI model integration.<br>On paper it is a toy: an athlete (me) finishes a run, Strava calls a registered webhook, I store a summary of the activity. <br>In practice it forced a handful of decisions that only show up once you respect how the external service actually behaves. <br>This post is about those decisions, the shape of the system and why it is shaped that way. The three posts after it go deep on each moving part.</p><h3>The constraint that drives everything</h3><p>Strava delivers events over a single webhook callback URL, and it uses that one URL for two very different interactions. <br>First, a one-time validation handshake: Strava sends a GET with hub.mode=subscribe, a hub.verify_token I must check, and a hub.challenge I must echo back. <br>Then, for the life of the subscription, ongoing POST deliveries whenever an activity is created, updated, or deleted.</p><p>The handshake is where the constraint lives. As the ingestor’s own operational note puts it, the validation GET must return 200 and echo hub.challenge within roughly 2 seconds, and a cold Java Lambda can exceed that.<br>That single sentence shapes the whole system. Two seconds is not a lot of budget for a JVM that may be cold, and the real work I want to do per event resolve an OAuth token, maybe refresh it, call the Strava API, write to DynamoDB is nowhere near fast or reliable enough to attempt inside that window.</p><p>So the first architectural decision writes itself: <strong>whatever answers Strava must do almost nothing.</strong> The fast path acknowledges and gets out of the way. The slow path happens somewhere else, on its own schedule.</p><h3>Two Lambdas and a connector, with a queue in the middle</h3><p>Here is the whole system end to end. An ingest Lambda sits at the untrusted edge behind API Gateway and answers Strava. It validates the shape of each event and, for the ones worth keeping, drops a message on an SQS queue. <br>A separate processor Lambda consumes that queue and does the heavy, slow work out of band. <br>A third piece a Spring Boot connector is not in the request path at all; it handles OAuth onboarding and seeds the athlete tokens the processor later needs.</p><p>The ingestor README’s system-context diagram captures the request path:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JI2duRTrL8c0DVor0Z5-sg.png" /></figure><p>That diagram leaves out two things that matter for the full story: the connector and the DynamoDB tables. Here is the complete picture, with every component that actually exists in the three repos:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bqbcQDuHWLpIRLpJH2B4xw.png" /></figure><h3>Why a queue sits in the middle</h3><p>The queue is the decision I most want to defend, because “just call the processor directly” is the obvious alternative and it is wrong here.<br>The ingestor README gives three reasons, and all three hold up against the code:</p><ul><li><strong>Different latency profiles.</strong> Ingest must answer Strava within ~2 seconds; the processor can take its time behind the queue. Putting slow work in front of a hard external deadline is how you miss the deadline.</li><li><strong>Different dependencies.</strong> Ingest needs only SQS. The processor needs DynamoDB, Secrets Manager, and an HTTP client for the Strava API. Keeping them apart means the edge stays tiny and fast, and the dependency-heavy half can fail or get slow without taking the handshake down with it.</li><li><strong>Durability.</strong> If the processor is down or slow, events wait on the queue and are redriven to a dead-letter queue after repeated failures, rather than being lost. A synchronous call would have dropped them.</li></ul><p>The queue also creates a clean ownership boundary. The EventQueue and its dead-letter queue EventDlq are <strong>owned by the ingest stack and consumed by the processor stack </strong>the ingestor&#39;s SAM template defines them, and the processor takes the queue ARN in as a parameter rather than creating its own. <br>That has a practical consequence for operations: deploy order is ingest first, then processor, because the processor needs the queue the ingestor exports.</p><h3>Why a separate connector</h3><p>The processor can only fetch an athlete’s activities if it holds that athlete’s OAuth tokens. Those tokens come from a consent flow a user has to walk through once, which is a completely different kind of interaction from a webhook. <br>Rather than bolt an OAuth UI onto a Lambda, the onboarding lives in its own Spring Boot connector that runs on EC2/ECS. <br>Its one job is to get an athlete through Strava consent and write the resulting tokens into a shared DynamoDB table.</p><p>That table, strava-state, keyed by the numeric athleteId, is the real contract between the two halves of the system. <br>The connector only <strong>writes</strong> tokens; the processor only <strong>reads</strong> them. <br>Neither imports the other&#39;s code. They agree on a DynamoDB item shape and nothing else which is exactly the kind of loose coupling you want between a user-facing onboarding app and a machine-facing event pipeline.</p><h3>The thin edge, in one snippet</h3><p>If you want a single piece of code that captures the “do almost nothing” philosophy, it is the method dispatch inside the ingest handler. <br>The whole handler maps an API Gateway request onto two service calls and nothing more (WebhookHandler.java):</p><pre>    WebhookResult result =<br>        switch (method) {<br>          case &quot;GET&quot; -&gt; service.validate(request.getQueryStringParameters());<br>          case &quot;POST&quot; -&gt; service.receive(request.getBody());<br>          default -&gt; {<br>            LOG.error(&quot;Unsupported method: {}&quot;, method);<br>            yield WebhookResult.methodNotAllowed();<br>          }<br>        };</pre><p>GET validates the handshake, POST accepts an event; everything heavy is downstream. That is the architecture in miniature.</p><h3>What I deliberately left out</h3><p>I want to be honest about what this design does <em>not</em> claim. <br>There are no throughput, latency-SLO, or cost numbers here, because none are measured in the repos.<br>I am not going to invent them. The only time budget that genuinely drives the design is Strava’s ~2-second handshake window. <br>The security boundary is also narrower than it looks: the GET handshake is verified with a token, but event POSTs are not authenticated, because Strava sends no signature. <br>The practical defence is downstream a forged event for an athlete whose tokens I do not hold simply fails the token lookup and never fabricates data. Post 2 covers that trust boundary properly.</p><h3>Takeaways</h3><ul><li>Let the external service’s hardest constraint pick your architecture. Strava’s ~2-second handshake is the reason for everything else.</li><li>A queue between a fast edge and slow work buys you three things at once: independent latency, independent dependencies, and durability with a dead-letter path.</li><li>Make ownership explicit. One stack owns the queue, the other consumes it. Deploy order follows from that.</li><li>Couple components through a data contract, not shared code. <br>The strava-state table keyed by numeric athleteId is the entire interface between the connector that writes tokens and the processor that reads them.</li></ul><p>The next three posts follow the data through the system: <br>the ingest edge, the processor, the onboarding connector that feeds both.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a94792892c9d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Mastering Complex Queries: jOOQ vs Spring Data JPA Deep Dive (Part 2/4)]]></title>
            <link>https://medium.com/@myc5/mastering-complex-queries-jooq-vs-spring-data-jpa-deep-dive-part-2-4-fdcf0872d5c5?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/fdcf0872d5c5</guid>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[spring-data-jpa]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[jooq]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Thu, 21 May 2026 02:19:49 GMT</pubDate>
            <atom:updated>2026-05-21T02:19:49.458Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CwHfo-Sm60-_j80XXF8OQw.png" /></figure><p>In <a href="https://medium.com/@myc5/jooq-vs-spring-data-jpa-the-complete-guide-for-spring-boot-developers-part-1-4-ac534752b894"><em>Part 1</em></a>, we covered the fundamentals.<br>Now it’s time to get practical: <br><strong>How do you handle real-world query complexity with each approach?</strong></p><h3>Dynamic Queries: The Production Reality</h3><h4><strong>Scenario:</strong> As per the new requirement a user should be able to search a film with optional filters:</h4><ul><li>Filter by title (optional)</li><li>Filter by rating (optional)</li><li>Filter by release year (optional)</li><li>Sort by various fields</li></ul><p>This is one of the most common patterns in production and handling it elegantly is critical.</p><p><strong>Using Spring Data JPA: Specification API</strong></p><pre>// Specification classes for each filter<br>public class FilmSpecifications {<br>    <br>    public static Specification&lt;FilmEntity&gt; hasTitle(String title) {<br>        return (root, query, cb) -&gt; {<br>            if (title == null || title.isBlank()) {<br>                return null;<br>            }<br>            return cb.like(cb.lower(root.get(&quot;title&quot;)), &quot;%&quot; + title.toLowerCase() + &quot;%&quot;);<br>        };<br>    }<br>    <br>    public static Specification&lt;FilmEntity&gt; hasRating(String rating) {<br>        return (root, query, cb) -&gt; {<br>            if (rating == null) {<br>                return null;<br>            }<br>            return cb.equal(root.get(&quot;rating&quot;), rating);<br>        };<br>    }<br>    <br>    public static Specification&lt;FilmEntity&gt; releasedAfter(Integer year) {<br>        return (root, query, cb) -&gt; {<br>            if (year == null) {<br>                return null;<br>            }<br>            return cb.greaterThan(root.get(&quot;releaseYear&quot;), year);<br>        };<br>    }<br>}</pre><p><strong>Repository:</strong></p><pre>@Repository<br>public interface FilmRepository extends <br>JpaRepository&lt;FilmEntity, Integer&gt;, JpaSpecificationExecutor&lt;FilmEntity&gt; {<br>}</pre><p><strong>Service:</strong></p><pre>@Service<br>public class FilmService {<br>    <br>    private final FilmRepository repository;<br>    <br>    public List&lt;FilmEntity&gt; searchFilms(String title, String rating, Integer year) {<br>        Specification&lt;FilmEntity&gt; spec = Specification<br>                .where(FilmSpecifications.hasTitle(title))<br>                .and(FilmSpecifications.hasRating(rating))<br>                .and(FilmSpecifications.releasedAfter(year));<br>        <br>        return repository.findAll(spec);<br>    }<br>}</pre><p><strong>Issues:</strong></p><ul><li>String-based field names: root.get(&quot;title&quot;) - typos caught at runtime</li><li>Complex Criteria API boilerplate</li><li>Hard to debug generated SQL</li><li>Verbose for multiple filters</li></ul><p><strong>Using jOOQ : Conditional DSL</strong></p><p><strong>Approach 1: Ternary Conditions</strong></p><pre>@Service<br>public class FilmJooqService {<br>    <br>    private final DSLContext dsl;<br>    <br>    public List&lt;Film&gt; searchFilms(String title, String rating, Integer year) {<br>        return dsl.selectFrom(FILM)<br>                .where(DSL.trueCondition())  // Start with always-true<br>                .and(title != null ? FILM.TITLE.likeIgnoreCase(&quot;%&quot; + title + &quot;%&quot;) <br>                                   : DSL.noCondition())<br>                .and(rating != null ? FILM.RATING.eq(rating) <br>                                    : DSL.noCondition())<br>                .and(year != null ? FILM.RELEASE_YEAR.gt(year) <br>                                  : DSL.noCondition())<br>                .fetchInto(Film.class);<br>    }<br>}</pre><p><strong>Approach 2: Condition List (Much Cleaner)</strong></p><pre>public List&lt;Film&gt; searchFilms(String title, String rating, Integer year) {<br>    var conditions = new ArrayList&lt;Condition&gt;();<br>    <br>    if (title != null &amp;&amp; !title.isBlank()) {<br>        conditions.add(FILM.TITLE.likeIgnoreCase(&quot;%&quot; + title + &quot;%&quot;));<br>    }<br>    if (rating != null) {<br>        conditions.add(FILM.RATING.eq(rating));<br>    }<br>    if (year != null) {<br>        conditions.add(FILM.RELEASE_YEAR.gt(year));<br>    }<br>    <br>    return dsl.selectFrom(FILM)<br>            .where(conditions)  // Automatically combines with AND<br>            .fetchInto(Film.class);<br>}</pre><p><strong>Advantages:</strong></p><ul><li>Type-safe field references (FILM.TITLE, FILM.RATING)</li><li>Clear, readable code</li><li>Easy to debug (see actual SQL in logs)</li><li>No reflection or “magic”</li><li>IDE autocomplete works perfectly</li></ul><h4>Dynamic Sorting</h4><p><strong>Using Spring Data JPA:</strong></p><pre>public List&lt;FilmEntity&gt; searchFilms(String title, String rating, Integer year, <br>                                   String sortField, String direction) {<br>    Specification&lt;FilmEntity&gt; spec = /* ... */;<br>    <br>    Sort sort = Sort.by(<br>        &quot;desc&quot;.equalsIgnoreCase(direction) ? <br>        Sort.Direction.DESC : Sort.Direction.ASC,<br>        sortField  // ❌ String-based, runtime validation<br>    );<br>    <br>    return repository.findAll(spec, sort);<br>}</pre><p><strong>Using jOOQ:</strong></p><pre>public List&lt;Film&gt; searchFilms(String title, String rating, Integer year,<br>                             String sortField, String direction) {<br>    var conditions = new ArrayList&lt;Condition&gt;();<br>    // ... add conditions<br>    <br>    // Type-safe sort field mapping<br>    Field&lt;?&gt; orderField = switch (sortField) {<br>        case &quot;title&quot; -&gt; FILM.TITLE;<br>        case &quot;year&quot; -&gt; FILM.RELEASE_YEAR;<br>        case &quot;rating&quot; -&gt; FILM.RATING;<br>        default -&gt; FILM.FILM_ID;  // ✅ Compile-time validated<br>    };<br>    <br>    var orderBy = &quot;desc&quot;.equalsIgnoreCase(direction) <br>        ? orderField.desc() <br>        : orderField.asc();<br>    <br>    return dsl.selectFrom(FILM)<br>            .where(conditions)<br>            .orderBy(orderBy)<br>            .fetchInto(Film.class);<br>}</pre><h3>Multi-Table Joins &amp; The N+1 Problem</h3><h4>Scenario: Get customer rental history with film details:</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DUBvJZPRtkD7Ja4-Qgu4cw.png" /></figure><h4>Spring Data JPA: The N+1 Trap</h4><pre>@Entity<br>public class RentalEntity {<br>    @ManyToOne(fetch = FetchType.LAZY)<br>    @JoinColumn(name = &quot;inventory_id&quot;)<br>    private InventoryEntity inventory;<br>    <br>    @OneToOne(mappedBy = &quot;rental&quot;)<br>    private PaymentEntity payment;<br>}<br><br>// Usage<br>List&lt;RentalEntity&gt; rentals = rentalRepository.findByCustomerId(customerId);<br><br>for (RentalEntity rental : rentals) {<br>    String filmTitle = rental.getInventory().getFilm().getTitle();  // 🔥 N+1!<br>    BigDecimal amount = rental.getPayment().getAmount();            // 🔥 N+1!<br>}</pre><p><strong>What happens:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jK0RI_DvEnLnQQvrKmTyGQ.png" /></figure><p><strong>Approach 1: JPQL Fetch Join</strong></p><pre>@Query(&quot;&quot;&quot;<br>    SELECT r FROM RentalEntity r<br>    JOIN FETCH r.inventory i<br>    JOIN FETCH i.film f<br>    LEFT JOIN FETCH r.payment p<br>    WHERE r.customer.customerId = :customerId<br>    &quot;&quot;&quot;)<br>List&lt;RentalEntity&gt; findRentalsByCustomerWithDetails(@Param(&quot;customerId&quot;) Short customerId);</pre><p><strong>Result:</strong> 1 query, but:</p><ul><li>Returns entities (all columns fetched)</li><li>Still JPQL strings</li></ul><p><strong>Approach 2: DTO Projection</strong></p><pre>@Data<br>@AllArgsConstructor<br>public class RentalDetailDto {<br>    private Integer rentalId;<br>    private LocalDateTime rentalDate;<br>    private String customerName;<br>    private String filmTitle;<br>    private String rating;<br>    private BigDecimal paymentAmount;<br>}<br><br>@Query(&quot;&quot;&quot;<br>    SELECT new com.example.dto.RentalDetailDto(<br>        r.rentalId,<br>        r.rentalDate,<br>        c.firstName || &#39; &#39; || c.lastName,<br>        f.title,<br>        f.rating,<br>        p.amount<br>    )<br>    FROM RentalEntity r<br>    JOIN r.customer c<br>    JOIN r.inventory i<br>    JOIN i.film f<br>    LEFT JOIN r.payment p<br>    WHERE c.customerId = :customerId<br>    &quot;&quot;&quot;)<br>List&lt;RentalDetailDto&gt; findRentalDetails(@Param(&quot;customerId&quot;) Short customerId);</pre><p><strong>Issues:</strong></p><ul><li>Constructor must match query exactly</li><li>Fully qualified class name in string</li><li>Breaks if DTO constructor changes</li><li>Still JPQL syntax</li></ul><h4>jOOQ: Explicit Joins (No N+1 Possible)</h4><pre>@Data<br>@AllArgsConstructor<br>public class RentalDetailDto {<br>    private Integer rentalId;<br>    private LocalDateTime rentalDate;<br>    private String customerName;<br>    private String filmTitle;<br>    private String rating;<br>    private BigDecimal paymentAmount;<br>}<br><br>@Service<br>public class RentalService {<br>    <br>    public List&lt;RentalDetailDto&gt; getRentalDetails(Short customerId) {<br>        return dsl.select(<br>                    RENTAL.RENTAL_ID,<br>                    RENTAL.RENTAL_DATE,<br>                    CUSTOMER.FIRST_NAME<br>                        .concat(&quot; &quot;)<br>                        .concat(CUSTOMER.LAST_NAME)<br>                        .as(&quot;customer_name&quot;),<br>                    FILM.TITLE,<br>                    FILM.RATING,<br>                    PAYMENT.AMOUNT<br>                )<br>                .from(RENTAL)<br>                .join(CUSTOMER).on(RENTAL.CUSTOMER_ID.eq(CUSTOMER.CUSTOMER_ID))<br>                .join(INVENTORY).on(RENTAL.INVENTORY_ID.eq(INVENTORY.INVENTORY_ID))<br>                .join(FILM).on(INVENTORY.FILM_ID.eq(FILM.FILM_ID))<br>                .leftJoin(PAYMENT).on(RENTAL.RENTAL_ID.eq(PAYMENT.RENTAL_ID))<br>                .where(CUSTOMER.CUSTOMER_ID.eq(customerId))<br>                .fetchInto(RentalDetailDto.class);<br>    }<br>}</pre><p><strong>Generated SQL:</strong></p><pre>SELECT <br>    r.rental_id,<br>    r.rental_date,<br>    c.first_name || &#39; &#39; || c.last_name AS customer_name,<br>    f.title,<br>    f.rating,<br>    p.amount<br>FROM rental r<br>JOIN customer c ON r.customer_id = c.customer_id<br>JOIN inventory i ON r.inventory_id = i.inventory_id<br>JOIN film f ON i.film_id = f.film_id<br>LEFT JOIN payment p ON r.rental_id = p.rental_id<br>WHERE c.customer_id = ?</pre><p><strong>Advantages:</strong></p><ul><li><strong>Single query</strong> (N+1 impossible by design)</li><li>Type-safe join conditions</li><li>Compile-time validation of all table/column names</li><li>Auto-maps to DTO by field name</li><li>Clear SQL intent</li><li>DTO changes = compilation error if mapping breaks</li></ul><h4>Join Comparison</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hks6J45_pp5Jl3OTn1hXYw.png" /></figure><h3>Aggregations: Generating Revenue Reports</h3><h4><strong>Scenario:</strong> Get Monthly revenue report by film category:</h4><h4>Using Spring Data JPA:</h4><pre>@Query(&quot;&quot;&quot;<br>    SELECT <br>        c.name as categoryName,<br>        SUM(p.amount) as totalRevenue,<br>        COUNT(r.rentalId) as rentalCount<br>    FROM PaymentEntity p<br>    JOIN p.rental r<br>    JOIN r.inventory i<br>    JOIN i.film f<br>    JOIN f.filmCategories fc<br>    JOIN fc.category c<br>    GROUP BY c.categoryId, c.name<br>    ORDER BY SUM(p.amount) DESC<br>    &quot;&quot;&quot;)<br>List&lt;Object[]&gt; getCategoryRevenue();<br><br>// Usage - No type safety<br>List&lt;Object[]&gt; results = repository.getCategoryRevenue();<br>for (Object[] row : results) {<br>    String category = (String) row[0];      // ❌ Casting required<br>    BigDecimal revenue = (BigDecimal) row[1];<br>    Long count = (Long) row[2];<br>    // Error-prone if query changes<br>}</pre><p><strong>Issues:</strong></p><ul><li>Returns Object[] - no type safety</li><li>Fragile if query order changes</li><li>Runtime ClassCastException risk</li></ul><h4>Using jOOQ:</h4><pre>public record CategoryRevenue(<br>    String categoryName,<br>    BigDecimal totalRevenue,<br>    Integer rentalCount<br>) {}<br><br>@Service<br>public class ReportService {<br>    <br>    public List&lt;CategoryRevenue&gt; getCategoryRevenue() {<br>        return dsl.select(<br>                    CATEGORY.NAME,<br>                    sum(PAYMENT.AMOUNT).as(&quot;total_revenue&quot;),<br>                    count(RENTAL.RENTAL_ID).as(&quot;rental_count&quot;)<br>                )<br>                .from(PAYMENT)<br>                .join(RENTAL).on(PAYMENT.RENTAL_ID.eq(RENTAL.RENTAL_ID))<br>                .join(INVENTORY).on(RENTAL.INVENTORY_ID.eq(INVENTORY.INVENTORY_ID))<br>                .join(FILM).on(INVENTORY.FILM_ID.eq(FILM.FILM_ID))<br>                .join(FILM_CATEGORY).on(FILM.FILM_ID.eq(FILM_CATEGORY.FILM_ID))<br>                .join(CATEGORY).on(FILM_CATEGORY.CATEGORY_ID.eq(CATEGORY.CATEGORY_ID))<br>                .groupBy(CATEGORY.CATEGORY_ID, CATEGORY.NAME)<br>                .orderBy(sum(PAYMENT.AMOUNT).desc())<br>                .fetchInto(CategoryRevenue.class);<br>    }<br>}<br><br>// Usage - Type safe!<br>List&lt;CategoryRevenue&gt; report = service.getCategoryRevenue();<br>for (CategoryRevenue row : report) {<br>    String category = row.categoryName();     // ✅ Type-safe accessor<br>    BigDecimal revenue = row.totalRevenue();<br>    Integer count = row.rentalCount();<br>}</pre><p><strong>Advantages:</strong></p><ul><li>Type-safe result mapping</li><li>Java Records for immutable DTOs</li><li>Compilation fails if fields mismatch</li><li>Refactoring-safe</li></ul><h3>Window Functions: Ranking &amp; Analytics</h3><h4><strong>Scenario:</strong> Rank customers by total spending within each store</h4><h4>Using Spring Data JPA: Must Use Native SQL</h4><pre>@Query(value = &quot;&quot;&quot;<br>    SELECT <br>        c.customer_id,<br>        c.first_name,<br>        c.last_name,<br>        c.store_id,<br>        SUM(p.amount) as total_spent,<br>        RANK() OVER (<br>            PARTITION BY c.store_id <br>            ORDER BY SUM(p.amount) DESC<br>        ) as store_rank<br>    FROM customer c<br>    JOIN payment p ON c.customer_id = p.customer_id<br>    GROUP BY c.customer_id, c.first_name, c.last_name, c.store_id<br>    &quot;&quot;&quot;, nativeQuery = true)<br>List&lt;Object[]&gt; rankCustomersByStore();</pre><p><strong>Issues:</strong></p><ul><li>Native SQL = loses database portability</li><li>Returns Object[] - no type safety</li><li>JPQL doesn’t support window functions</li></ul><h4>Using jOOQ : First-Class Window Function Support</h4><pre>public record CustomerRanking(<br>    Short customerId,<br>    String firstName,<br>    String lastName,<br>    Short storeId,<br>    BigDecimal totalSpent,<br>    Integer storeRank<br>) {}<br><br>public List&lt;CustomerRanking&gt; rankCustomersByStore() {<br>    var totalSpent = sum(PAYMENT.AMOUNT).as(&quot;total_spent&quot;);<br>    <br>    return dsl.select(<br>                CUSTOMER.CUSTOMER_ID,<br>                CUSTOMER.FIRST_NAME,<br>                CUSTOMER.LAST_NAME,<br>                CUSTOMER.STORE_ID,<br>                totalSpent,<br>                rank().over(<br>                    partitionBy(CUSTOMER.STORE_ID)<br>                    .orderBy(totalSpent.desc())<br>                ).as(&quot;store_rank&quot;)<br>            )<br>            .from(CUSTOMER)<br>            .join(PAYMENT).on(CUSTOMER.CUSTOMER_ID.eq(PAYMENT.CUSTOMER_ID))<br>            .groupBy(<br>                CUSTOMER.CUSTOMER_ID,<br>                CUSTOMER.FIRST_NAME,<br>                CUSTOMER.LAST_NAME,<br>                CUSTOMER.STORE_ID<br>            )<br>            .fetchInto(CustomerRanking.class);<br>}</pre><p><strong>More Window Functions:</strong></p><pre>// Running total of payments per customer<br>var runningTotal = sum(PAYMENT.AMOUNT).over(<br>    partitionBy(PAYMENT.CUSTOMER_ID)<br>    .orderBy(PAYMENT.PAYMENT_DATE)<br>    .rowsBetweenUnboundedPreceding()<br>    .andCurrentRow()<br>).as(&quot;running_total&quot;);<br><br>// Moving average (last 3 payments)<br>var movingAvg = avg(PAYMENT.AMOUNT).over(<br>    partitionBy(PAYMENT.CUSTOMER_ID)<br>    .orderBy(PAYMENT.PAYMENT_DATE)<br>    .rowsBetween(2).preceding()<br>    .andCurrentRow()<br>).as(&quot;moving_avg&quot;);<br><br>// Lag function (previous payment amount)<br>var previousAmount = lag(PAYMENT.AMOUNT, 1).over(<br>    partitionBy(PAYMENT.CUSTOMER_ID)<br>    .orderBy(PAYMENT.PAYMENT_DATE)<br>).as(&quot;previous_amount&quot;);<br><br>dsl.select(<br>        PAYMENT.CUSTOMER_ID,<br>        PAYMENT.AMOUNT,<br>        runningTotal,<br>        movingAvg,<br>        previousAmount<br>    )<br>    .from(PAYMENT)<br>    .fetch();</pre><h3>Subqueries &amp; CTEs: Advanced Patterns</h3><h4><strong>Scenario:</strong> Find customers who spent more than average</h4><h4>Using Spring Data JPA</h4><pre>@Query(&quot;&quot;&quot;<br>    SELECT c<br>    FROM CustomerEntity c<br>    WHERE (<br>        SELECT COALESCE(SUM(p.amount), 0)<br>        FROM PaymentEntity p<br>        WHERE p.customerId = c.customerId<br>    ) &gt; (<br>        SELECT AVG(customerTotal.total)<br>        FROM (<br>            SELECT SUM(p2.amount) as total<br>            FROM PaymentEntity p2<br>            GROUP BY p2.customerId<br>        ) customerTotal<br>    )<br>    &quot;&quot;&quot;)<br>List&lt;CustomerEntity&gt; findHighSpenders();<br>// ❌ JPQL subquery support is limited and verbose</pre><h4>Using jOOQ: Subqueries</h4><pre>public List&lt;Customer&gt; findHighSpenders() {<br>    // Correlated subquery for customer total<br>    var customerTotal = dsl.select(sum(PAYMENT.AMOUNT))<br>            .from(PAYMENT)<br>            .where(PAYMENT.CUSTOMER_ID.eq(CUSTOMER.CUSTOMER_ID))<br>            .asField(&quot;customer_total&quot;);<br>    <br>    // Subquery for average total<br>    var avgTotal = dsl.select(avg(sum(PAYMENT.AMOUNT)))<br>            .from(PAYMENT)<br>            .groupBy(PAYMENT.CUSTOMER_ID)<br>            .asField();<br>    <br>    return dsl.select(CUSTOMER.fields())<br>            .from(CUSTOMER)<br>            .where(customerTotal.gt(avgTotal))<br>            .fetchInto(Customer.class);<br>}</pre><h4>Using jOOQ: CTEs (Common Table Expressions)</h4><p><strong>Better approach using WITH:</strong></p><pre>public List&lt;Customer&gt; findHighSpenders() {<br>    // Define CTE: customer totals<br>    var customerTotals = dsl.name(&quot;customer_totals&quot;).as(<br>        dsl.select(<br>                PAYMENT.CUSTOMER_ID,<br>                sum(PAYMENT.AMOUNT).as(&quot;total&quot;)<br>        )<br>        .from(PAYMENT)<br>        .groupBy(PAYMENT.CUSTOMER_ID)<br>    );<br>    <br>    // Calculate average from CTE<br>    var avgTotal = dsl.select(avg(customerTotals.field(&quot;total&quot;, BigDecimal.class)))<br>            .from(customerTotals)<br>            .asField();<br>    <br>    // Use CTE in main query<br>    return dsl.with(customerTotals)<br>            .select(CUSTOMER.fields())<br>            .from(CUSTOMER)<br>            .join(customerTotals).on(<br>                CUSTOMER.CUSTOMER_ID.eq(customerTotals.field(PAYMENT.CUSTOMER_ID))<br>            )<br>            .where(customerTotals.field(&quot;total&quot;, BigDecimal.class).gt(avgTotal))<br>            .fetchInto(Customer.class);<br>}</pre><p><strong>Generated SQL:</strong></p><pre>WITH customer_totals AS (<br>    SELECT customer_id, SUM(amount) AS total<br>    FROM payment<br>    GROUP BY customer_id<br>)<br>SELECT c.*<br>FROM customer c<br>JOIN customer_totals ct ON c.customer_id = ct.customer_id<br>WHERE ct.total &gt; (SELECT AVG(total) FROM customer_totals)</pre><h3>Pagination: OFFSET vs Seek</h3><h4>Traditional OFFSET Pagination:</h4><h4><strong>Using Spring Data JPA:</strong></h4><pre>Pageable pageable = PageRequest.of(page, size, Sort.by(&quot;title&quot;));<br>Page&lt;FilmEntity&gt; results = filmRepository.findAll(pageable);</pre><h4><strong>Using jOOQ:</strong></h4><pre>public List&lt;Film&gt; getFilms(int page, int size) {<br>    return dsl.selectFrom(FILM)<br>            .orderBy(FILM.TITLE)<br>            .limit(size)<br>            .offset(page * size)<br>            .fetchInto(Film.class);<br>}</pre><h4><strong>Problem with OFFSET:</strong></h4><pre>-- Page 1000 (size 20)<br>SELECT * FROM film ORDER BY title LIMIT 20 OFFSET 20000;<br>-- Database scans and SKIPS 20,000 rows!</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gFmU2vR0wCa3UWtf0LfOWA.png" /></figure><p><strong>The performance degrades as page number increases!</strong></p><h4>Seek Pagination (Keyset Pagination)</h4><h4><strong>Using jOOQ (Gives Much Better Performance):</strong></h4><pre>// Instead of page number, use last seen ID <br>public List&lt;Film&gt; getFilmsAfter(Integer lastFilmId, int size) {<br>    return dsl.selectFrom(FILM)<br>            .where(FILM.FILM_ID.gt(lastFilmId != null ? lastFilmId : 0))<br>            .orderBy(FILM.FILM_ID.asc())<br>            .limit(size)<br>            .fetchInto(Film.class);<br>}</pre><p><strong>Generated SQL:</strong></p><pre>SELECT * FROM film <br>WHERE film_id &gt; 1000 // Seek based <br>ORDER BY film_id <br>LIMIT 20;<br>-- Uses index, O(log n) instead of O(n)!</pre><p><strong>Benefits:</strong></p><ul><li>Constant performance regardless of offset</li><li>Works with any indexed column</li><li>Better for infinite scroll UIs</li></ul><p><strong>Spring Data JPA</strong> can do this as well but requires manual implementation.</p><h3>Key Takeaways</h3><ol><li><strong>Dynamic Queries:</strong> jOOQ’s conditional DSL is cleaner and type-safe vs JPA Specifications</li><li><strong>N+1 Problem:</strong> JPA makes it easy to accidentally create, jOOQ makes it impossible</li><li><strong>Complex Joins:</strong> jOOQ’s explicit joins are clearer and compile-time validated</li><li><strong>Analytics:</strong> Window functions require native SQL in JPA, but are first-class in jOOQ</li><li><strong>CTEs:</strong> Not supported in JPA directly, fully supported in jOOQ</li><li><strong>Performance:</strong> Seek pagination (jOOQ) beats OFFSET for large datasets</li></ol><h4>If you found this helpful, give it a clap 👏 and follow for Part 3!</h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fdcf0872d5c5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Build Robust APIs with Declarative Validation — From Built-in Constraints to Custom Validators]]></title>
            <link>https://medium.com/@myc5/build-robust-apis-with-declarative-validation-from-built-in-constraints-to-custom-validators-ab7d446c156b?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/ab7d446c156b</guid>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[bean-validation]]></category>
            <category><![CDATA[spring-boot]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Wed, 13 May 2026 13:10:32 GMT</pubDate>
            <atom:updated>2026-05-13T13:35:42.931Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*X1XmNbwuSxSK1p-e9vVERA.png" /></figure><p>Input validation is one of the most fundamental responsibilities of any backend service, yet it remains one of the most commonly mishandled aspects of API development.</p><p>Invalid data that slips past an API boundary can corrupt databases, trigger obscure runtime exceptions deep in business logic and open the door to injection attacks.</p><p>Bean Validation standardized through JSR 380 and now part of the Jakarta Validation specification provides a declarative, annotation-driven approach to enforcing data integrity directly on your domain objects.</p><p>In this guide, we will explore Bean Validation comprehensively using a mocked payment processing API built with Spring Boot.</p><h4>You will learn:</h4><ul><li>How does built-in constraint annotations work?</li><li>How to create powerful custom validators?</li><li>How to validate relationships between multiple fields using cross-field validators?</li><li>How to produce structured, client-friendly error responses that conform to RFC 7807 Problem Details?</li></ul><p>By the end, you will have the knowledge to build a validation layer that is expressive, maintainable and secure one that serves as your API’s first line of defense.<br> <br>The mocked payment API handles card payments, bank transfers via IBAN, and refund processing, making it an ideal vehicle for demonstrating every major Bean Validation capability.</p><h3>Bean Validation Fundamentals</h3><h4>How It Works in Spring Boot:</h4><p>Spring Boot integrates Bean Validation seamlessly through the spring-boot-starter-validation dependency, which bundles Hibernate Validator (the reference implementation of the Jakarta Validation specification).</p><p>When you annotate a controller method parameter with @Valid, Spring&#39;s argument resolver intercepts the incoming request body and passes it through the validation engine before your handler method executes.</p><p>The validation lifecycle proceeds as follows:</p><ul><li>Spring deserializes the JSON request body into a Java object.</li><li>The Bean Validation engine scans the object for constraint annotations, each annotation’s associated validator executes its isValid() method, and any violations are collected into a set.</li><li>If violations exist, Spring throws a MethodArgumentNotValidException rather than invoking your controller method.</li><li>This fail-fast approach ensures that invalid data never reaches your service layer.</li></ul><p>The key components in this architecture are:</p><ul><li><strong>Constraint annotations</strong> (metadata declaring rules)</li><li><strong>Constraint validators</strong> (implementations that enforce those rules)</li><li>The <strong>Validator engine</strong> (orchestrator that discovers and invokes validators)</li><li>The <strong>exception handler</strong> (translator that converts violations into HTTP error responses)</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O5xD7_kEuCiaDzlOPuzVrQ.png" /><figcaption><em>Figure 1: Bean Validation request flow showing Client → Controller → ValidationEngine → Service/ExceptionHandler paths</em></figcaption></figure><p>This separation of concerns is what makes Bean Validation so powerful: your controller stays lean, your validation rules live on the data class itself, and error translation happens in a single centralized handler.</p><h3>Built-in Validators Deep Dive</h3><p>Jakarta Validation provides a rich catalog of constraint annotations organized into several categories. Understanding what is available out of the box prevents you from writing unnecessary custom validators.</p><p><strong>Nullability Constraints</strong>: @NotNull ensures a field is present, while @NotBlank (for strings) additionally rejects empty strings and strings containing only whitespace. Use @NotBlank for string fields and @NotNull for objects and numbers.</p><p><strong>Numeric Constraints</strong>: @Positive, @PositiveOrZero, @Negative, @NegativeOrZero enforce sign rules. @Min and @Max set numeric bounds. @Digits(integer, fraction) controls precision—essential for monetary values where you must limit decimal places.</p><p><strong>String Constraints</strong>: @Size(min, max) restricts length. @Pattern(regexp) provides full regular expression matching for format enforcement. @Email validates email format.</p><p><strong>Range Constraints</strong>: @Min and @Max work on numeric types, while @DecimalMin and @DecimalMax support string representations of numbers.</p><p>Here is theProcessPaymentRequest DTO demonstrating multiple built-in validators working together:</p><pre>public class ProcessPaymentRequest {<br><br>    @NotNull(message = &quot;Amount is required&quot;)<br>    @Positive(message = &quot;Amount must be positive&quot;)<br>    @Digits(integer = 10, fraction = 2, message = &quot;Amount must have max 2 decimal places&quot;)<br>    private BigDecimal amount;<br><br>    @NotBlank(message = &quot;Currency is required&quot;)<br>    @ValidCurrency<br>    private String currency;<br><br>    @NotBlank(message = &quot;Description is required&quot;)<br>    @Size(max = 255, message = &quot;Description must not exceed 255 characters&quot;)<br>    private String description;<br><br>    @NotNull(message = &quot;Payment method is required&quot;)<br>    @Valid<br>    private PaymentMethodDto paymentMethod;<br><br>    @NotNull(message = &quot;Billing address is required&quot;)<br>    @Valid<br>    private BillingAddressDto billingAddress;<br>}</pre><p>Notice how each field stacks multiple annotations to express compound rules. The amount field, for instance must be non-null, positive and have at most two decimal places.</p><p>All expressed declaratively without a single line of imperative code. <br>Custom messages provide clarity for API consumers, making error responses immediately actionable.</p><h3>Creating Custom Validators</h3><p>Built-in annotations cover common scenarios, but real-world APIs inevitably need domain-specific validation. <br>Bean Validation’s extensibility model lets you create custom constraints that integrate seamlessly with the framework.</p><h4>Anatomy of a Custom Validator:</h4><p>Every custom validator consists of two components:</p><ul><li>An <strong>annotation</strong> that declares the constraint’s metadata.</li><li>And a <strong>validator class</strong> that implements the checking logic.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qahasNaH8PUVER-PMaOg-Q.png" /><figcaption><em>Figure 2: Architecture showing the relationship between annotation, validator class, and Bean Validation Engine</em></figcaption></figure><h4>Building @ValidIBAN: A Step-by-Step Tutorial:</h4><p>Let us build a validator that verifies International Bank Account Numbers using the <a href="https://randomlyiban.com/validation-guide">ISO 13616 MOD-97 </a>algorithm. <br>This is a non-trivial validation that demonstrates the full power of custom constraints.</p><p><strong>Step 1: Define the annotation.</strong></p><pre>@Documented<br>@Constraint(validatedBy = IBANValidator.class)<br>@Target({ElementType.FIELD, ElementType.PARAMETER})<br>@Retention(RetentionPolicy.RUNTIME)<br>public @interface ValidIBAN {<br>    String message() default &quot;Invalid IBAN format&quot;;<br>    Class&lt;?&gt;[] groups() default {};<br>    Class&lt;? extends Payload&gt;[] payload() default {};<br>}</pre><p>Three elements are mandatory for every constraint annotation: <br>message() provides the default violation message<br>groups() enables conditional validation (discussed later)<br>payload() allows attaching metadata such as severity levels.</p><p>The @Constraint meta-annotation links this annotation to its validator implementation and @Target controls where the annotation may be placed.</p><p><strong>Step 2: Implement the validator.</strong></p><pre>public class IBANValidator implements ConstraintValidator&lt;ValidIBAN, String&gt; {<br><br>    @Override<br>    public boolean isValid(String value, ConstraintValidatorContext context) {<br>        if (value == null) {<br>            return true; // Let @NotNull handle nullability<br>        }<br><br>        String iban = value.replace(&quot; &quot;, &quot;&quot;).toUpperCase();<br><br>        if (iban.length() &lt; 15 || iban.length() &gt; 34) {<br>            return false;<br>        }<br><br>        if (!iban.matches(&quot;^[A-Z]{2}[0-9]{2}[A-Z0-9]+$&quot;)) {<br>            return false;<br>        }<br><br>        return performMod97Check(iban);<br>    }<br><br>    private boolean performMod97Check(String iban) {<br>        String rearranged = iban.substring(4) + iban.substring(0, 4);<br><br>        StringBuilder numericString = new StringBuilder();<br>        for (char c : rearranged.toCharArray()) {<br>            if (Character.isLetter(c)) {<br>                numericString.append(c - &#39;A&#39; + 10);<br>            } else {<br>                numericString.append(c);<br>            }<br>        }<br><br>        BigInteger ibanNumber = new BigInteger(numericString.toString());<br>        return ibanNumber.mod(BigInteger.valueOf(97)).intValue() == 1;<br>    }<br>}</pre><p>Key design decisions in this implementation:</p><ul><li>Returning true for null values follows the Bean Validation convention that nullability should be controlled separately by @NotNull</li><li>Normalizing input (trimming spaces, uppercasing) makes the validator tolerant of formatting variations.</li><li>And the multi-stage approach (length check, format regex, then MOD-97) provides early exits for obviously invalid values before reaching the expensive BigInteger computation.</li></ul><p>The payment API also includes custom validators for:</p><ul><li>@ValidCurrency (ISO 4217 code verification against a known set)</li><li>@ValidCardNumber (Luhn algorithm)</li><li>@ValidBIC (SWIFT code format)</li><li>@ValidAmount (precision rules) — each following this same two-component pattern.</li></ul><h4>Nested Object Validation:</h4><p>Real-world DTOs are rarely flat. <br>Payment requests contain payment methods, which themselves contain card details or bank account information. Bean Validation’s @Valid annotation cascades validation into nested objects.</p><p>In classProcessPaymentRequest, the @Valid annotation on paymentMethod ensures that not only is the field non-null, but the PaymentMethodDto object itself is also validated:</p><pre>@NotNull(message = &quot;Payment method is required&quot;)<br>@Valid<br>private PaymentMethodDto paymentMethod;<br><br>@NotNull(message = &quot;Billing address is required&quot;)<br>@Valid<br>private BillingAddressDto billingAddress;</pre><p>The PaymentMethodDto carries its own validation annotations, including the custom validators:</p><pre>public class PaymentMethodDto {<br><br>    @NotNull(message = &quot;Payment method type is required&quot;)<br>    private PaymentMethodType type;<br><br>    @ValidCardNumber<br>    private String cardNumber;<br><br>    @Min(value = 1, message = &quot;Expiry month must be between 1 and 12&quot;)<br>    @Max(value = 12, message = &quot;Expiry month must be between 1 and 12&quot;)<br>    private Integer expiryMonth;<br><br>    @ValidIBAN<br>    private String iban;<br><br>    @ValidBIC<br>    private String bic;<br>}</pre><p>When a nested field fails validation, the error path includes the full property path (e.g., paymentMethod.cardNumber), giving API consumers precise information about where the problem occurred.</p><p>Without @Valid, the nested object would be treated as an opaque reference and its internal constraints would never fire.</p><h4>Cross-Field Validation:</h4><p>Some business rules cannot be expressed on a single field. <br>“Refund amount must not exceed the original transaction amount” requires comparing two fields against each other.</p><p>Bean Validation supports this through <strong>class-level constraint annotations</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1-7_VpYw7YkkIkdQUWRmPg.png" /><figcaption><em>Figure 3: Cross-field validation showing how a class-level validator accesses multiple fields</em></figcaption></figure><h4>Approach 1: Class-Level Validator (Recommended):</h4><p>The class-level validator pattern places the constraint annotation on the class declaration itself, giving the validator access to the entire object:</p><pre>@Documented<br>@Constraint(validatedBy = RefundValidator.class)<br>@Target({ElementType.TYPE})<br>@Retention(RetentionPolicy.RUNTIME)<br>public @interface ValidRefund {<br>    String message() default &quot;Refund amount cannot exceed original transaction amount&quot;;<br>    Class&lt;?&gt;[] groups() default {};<br>    Class&lt;? extends Payload&gt;[] payload() default {};<br>}</pre><p>Note @Target({ElementType.TYPE}) — this annotation applies to classes, not fields. The validator receives the entire RefundRequest object:</p><pre>public class RefundValidator implements ConstraintValidator&lt;ValidRefund, RefundRequest&gt; {<br><br>    @Override<br>    public boolean isValid(RefundRequest request, ConstraintValidatorContext context) {<br>        if (request == null) {<br>            return true;<br>        }<br><br>        if (request.getRefundAmount() == null || request.getOriginalAmount() == null) {<br>            return true; // Let field-level @NotNull handle these<br>        }<br><br>        return request.getRefundAmount().compareTo(request.getOriginalAmount()) &lt;= 0;<br>    }<br>}</pre><p>The DTO then wears the annotation at the class level:</p><pre>@ValidRefund<br>public class RefundRequest {<br>    @NotNull(message = &quot;Refund amount is required&quot;)<br>    @Positive(message = &quot;Refund amount must be positive&quot;)<br>    private BigDecimal refundAmount;<br><br>    @NotNull(message = &quot;Original amount is required&quot;)<br>    @Positive(message = &quot;Original amount must be positive&quot;)<br>    private BigDecimal originalAmount;<br>    // ...<br>}</pre><h4>Approach 2: @AssertTrue Helper Method:</h4><p>For simpler cross-field checks, you can use an @AssertTrue — annotated method directly on the DTO</p><pre>@AssertTrue(message = &quot;Refund amount cannot exceed original amount&quot;)<br>private boolean isRefundAmountValid() {<br>    if (refundAmount == null || originalAmount == null) return true;<br>    return refundAmount.compareTo(originalAmount) &lt;= 0;<br>}</pre><p>The class-level validator approach is preferred for complex logic, reusability across DTOs and cleaner separation of concerns. <br>The @AssertTrue approach works well for one-off checks that are simple enough to inline.</p><h3>Validation Groups</h3><p>Sometimes different API operations require different validation rules for the same DTO. Validation groups let you activate constraints selectively based on context.</p><p>Define marker interfaces representing each group:</p><pre>public interface OnCreate {}<br>public interface OnUpdate {}</pre><p>Then assign constraints to specific groups:</p><pre>@NotNull(groups = OnCreate.class, message = &quot;Amount required for new payments&quot;)<br>private BigDecimal amount;<br><br>@Null(groups = OnCreate.class, message = &quot;Transaction ID must not be provided for new payments&quot;)<br>@NotNull(groups = OnUpdate.class, message = &quot;Transaction ID required for updates&quot;)<br>private String transactionId;</pre><p>In your controller, use @Validated (Spring&#39;s extension of @Valid) to specify which group to activate:</p><pre>@PostMapping<br>public ResponseEntity&lt;?&gt; create(@Validated(OnCreate.class) @RequestBody PaymentRequest req) { ... }<br><br>@PutMapping(&quot;/{id}&quot;)<br>public ResponseEntity&lt;?&gt; update(@Validated(OnUpdate.class) @RequestBody PaymentRequest req) { ... }</pre><p>Groups provide conditional validation without duplicating DTOs, though for significantly different operations, separate request classes often remain clearer.</p><h3>Method-Level Validation</h3><p>Bean Validation extends beyond request bodies to path variables, query parameters and even method return values. <br>Spring activates this through the @Validated annotation at the class level.</p><pre>@RestController<br>@RequestMapping(&quot;/api/payments&quot;)<br>@Validated<br>public class PaymentController {<br><br>    @GetMapping(&quot;/{transactionId}&quot;)<br>    public ResponseEntity&lt;PaymentResponse&gt; getPayment(<br>            @PathVariable<br>            @NotBlank(message = &quot;Transaction ID is required&quot;)<br>            @Pattern(regexp = &quot;^txn_[a-zA-Z0-9]+$&quot;, message = &quot;Invalid transaction ID format&quot;)<br>            String transactionId) {<br>        PaymentResponse response = paymentService.getPaymentById(transactionId);<br>        return ResponseEntity.ok(response);<br>    }<br>}</pre><p>The @Validated annotation on the class enables method-level validation via a Spring AOP proxy. Without it, @NotBlank and @Pattern on path variables would be silently ignored.</p><p>When method-level validation fails, Spring throws a ConstraintViolationException (not MethodArgumentNotValidException), which is why your exception handler must handle both exception types.</p><h3>Exception Handling and Error Responses</h3><p>A validation layer is only as useful as the error responses it produces. <br>Two distinct exception types arise from Bean Validation in Spring:</p><ul><li><strong>MethodArgumentNotValidException</strong>: thrown when @Valid fails on a @RequestBody parameter.</li><li><strong>ConstraintViolationException</strong>: thrown when method-level validation (path variables, query parameters) fails.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4rdSdfVc4FqB1PdcEa0JZw.png" /><figcaption><em>Figure 4: Exception handling flow showing how different validation failures are processed</em></figcaption></figure><p>The GlobalExceptionHandler uses Spring&#39;s ProblemDetail class <br>(RFC 7807 implementation) to produce structured error responses:</p><pre>@RestControllerAdvice<br>public class GlobalExceptionHandler {<br><br>    @ExceptionHandler(MethodArgumentNotValidException.class)<br>    public ProblemDetail handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {<br>        ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(<br>            HttpStatus.BAD_REQUEST, &quot;Validation failed&quot;<br>        );<br><br>        Map&lt;String, List&lt;String&gt;&gt; errors = new HashMap&lt;&gt;();<br>        for (FieldError error : ex.getBindingResult().getFieldErrors()) {<br>            String fieldName = error.getField();<br>            String errorMessage = error.getDefaultMessage();<br>            errors.computeIfAbsent(fieldName, k -&gt; new ArrayList&lt;&gt;()).add(errorMessage);<br>        }<br><br>        problemDetail.setProperty(&quot;errors&quot;, errors);<br>        problemDetail.setProperty(&quot;timestamp&quot;, Instant.now());<br>        return problemDetail;<br>    }<br><br>    @ExceptionHandler(ConstraintViolationException.class)<br>    public ProblemDetail handleConstraintViolation(ConstraintViolationException ex) {<br>        ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(<br>            HttpStatus.BAD_REQUEST, &quot;Constraint violation&quot;<br>        );<br><br>        Map&lt;String, String&gt; errors = new HashMap&lt;&gt;();<br>        for (ConstraintViolation&lt;?&gt; violation : ex.getConstraintViolations()) {<br>            errors.put(violation.getPropertyPath().toString(), violation.getMessage());<br>        }<br><br>        problemDetail.setProperty(&quot;errors&quot;, errors);<br>        problemDetail.setProperty(&quot;timestamp&quot;, Instant.now());<br>        return problemDetail;<br>    }<br>}</pre><p>This produces a response like:</p><pre>{<br>  &quot;type&quot;: &quot;about:blank&quot;,<br>  &quot;title&quot;: &quot;Bad Request&quot;,<br>  &quot;status&quot;: 400,<br>  &quot;detail&quot;: &quot;Validation failed&quot;,<br>  &quot;errors&quot;: {<br>    &quot;amount&quot;: [&quot;Amount must be positive&quot;],<br>    &quot;currency&quot;: [&quot;Invalid ISO 4217 currency code&quot;]<br>  },<br>  &quot;time{<br>  &quot;type&quot;: &quot;about:blank&quot;,<br>  &quot;title&quot;: &quot;Bad Request&quot;,<br>  &quot;status&quot;: 400,<br>  &quot;detail&quot;: &quot;Validation failed&quot;,<br>  &quot;errors&quot;: {<br>    &quot;amount&quot;: [&quot;Amount must be positive&quot;],<br>    &quot;currency&quot;: [&quot;Invalid ISO 4217 currency code&quot;]<br>  },<br>  &quot;timestamp&quot;: &quot;2026-05-12T10:30:00Z&quot;<br>}</pre><p>Grouping errors by field name and supporting multiple messages per field means clients can display all relevant feedback simultaneously rather than forcing users to fix errors one at a time.</p><h3>Best Practices and Pitfalls</h3><h4>Security Considerations</h4><p><strong>Validate enum values explicitly.</strong> If your API accepts a string that maps to an enum, validate it against the known set rather than relying on Jackson deserialization errors. Deserialization exceptions leak internal class names and produce inconsistent error formats.</p><p><strong>Avoid exposing validation internals.</strong> Custom error messages should describe the constraint violation without revealing implementation details like table names, internal field names or algorithm specifics.</p><h4>Performance Tips</h4><p><strong>Order validations from cheapest to most expensive.</strong> The validation engine evaluates constraints in declaration order. Place @NotNull and simple format checks before expensive validators that perform computations or network calls.</p><p><strong>Avoid regex catastrophic backtracking.</strong> Complex regular expressions in @Pattern can be exploited for <a href="https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS"><em>ReDoS</em></a> attacks. Keep patterns simple and test them against pathological inputs.</p><p><strong>Return true for null in custom validators.</strong> This is not just convention, it allows @NotNull to be composed independently. If your validator rejects null, it becomes impossible to make the field optional in other contexts.</p><h4>Common Mistakes</h4><p><strong>Forgetting </strong>@Valid<strong> on nested objects.</strong> Without it, the nested object&#39;s constraints are invisible to the validation engine. This is the single most common Bean Validation bug.</p><p><strong>Using </strong>@Validated<strong> instead of </strong>@Valid<strong> on method parameters.</strong> While Spring&#39;s @Validated enables group support, it does not trigger cascading validation on @RequestBody. For request body validation, use @Valid.</p><p><strong>Missing </strong>@Validated<strong> on the controller class.</strong> Method-level validation (path variables, query params) requires the class-level @Validated annotation to activate Spring&#39;s validation proxy.</p><h4>Production Checklist</h4><ul><li>✅ All request DTOs have validation annotations</li><li>✅ Custom validators return true for null values</li><li>✅ GlobalExceptionHandler handles both MethodArgumentNotValidException and ConstraintViolationException</li><li>✅ Error responses use RFC 7807 format with grouped field errors</li><li>✅ Validation unit tests cover boundary cases</li><li>✅ Integration tests verify the full request-to-error-response pipeline</li></ul><h3>Conclusion and Key Takeaways</h3><p>Bean Validation in Spring Boot transforms input validation from scattered if-statements into a declarative, composable and testable layer. <br>|<br>Through this payment API, we have seen how built-in annotations handle common constraints, how custom validators encapsulate domain-specific rules like IBAN verification, how class-level annotations enable cross-field validation for business rules like refund limits and how a centralized exception handler produces consistent RFC 7807 error responses.</p><p>The key takeaways are:</p><ol><li><strong>Declarative over imperative</strong>: Express rules as annotations on the data class itself, keeping controllers and services focused on business logic.</li><li><strong>Compose constraints</strong>: Stack annotations, use @Valid for cascading and create custom validators for domain rules that built-in annotations cannot express.</li><li><strong>Fail fast and fail clearly</strong>: Validate at the API boundary, group errors by field and provide actionable messages.</li><li><strong>Test at both levels</strong>: Unit test validators in isolation for logic correctness and integration test with MockMvc for wiring correctness.</li><li><strong>Defense in depth</strong>: Bean Validation is your first line of defense, but it complements rather than replaces database constraints, business rule checks, and security controls deeper in the stack.</li></ol><p>👏 <strong>Found This Helpful?</strong><br>If this guide helped you understand Bean Validation better, give it a clap and share it with your team. Follow me for more deep dives into Spring Boot and API development.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ab7d446c156b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[jOOQ vs Spring Data JPA: The Complete Guide for Spring Boot Developers (Part 1/4)]]></title>
            <link>https://medium.com/@myc5/jooq-vs-spring-data-jpa-the-complete-guide-for-spring-boot-developers-part-1-4-ac534752b894?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/ac534752b894</guid>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[database]]></category>
            <category><![CDATA[spring-data-jpa]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[jooq]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Sun, 10 May 2026 15:54:45 GMT</pubDate>
            <atom:updated>2026-05-10T15:54:45.236Z</atom:updated>
            <content:encoded><![CDATA[<p><strong>Series Overview:</strong> This is Part 1 of a 4-part deep dive comparing jOOQ (Java Object Oriented Query) and Spring Data JPA for production Spring Boot applications.</p><ul><li><strong>Part 1 (This Article):</strong> Philosophy, Setup, Type Safety &amp; Decision Framework</li><li><strong>Part 2:</strong> Mastering Complex Queries &amp; Joins</li><li><strong>Part 3:</strong> PostgreSQL-Specific Features with jOOQ</li><li><strong>Part 4:</strong> Production Patterns: Transactions, Testing &amp; Monitoring</li></ul><p>When building database-driven applications in Spring Boot, one of your first architectural decisions is: <strong>How do I talk to my database?</strong></p><p>The two most popular choices are:</p><ul><li><strong>Spring Data JPA</strong> — The mature ORM that abstracts SQL</li><li><strong>jOOQ 3.21</strong> — The type-safe SQL builder that embraces SQL</li></ul><p>Both are production-ready, but they approach database interaction from fundamentally different philosophies. This series will help you understand when to use which one to use or how to use both together.</p><h4>What You’ll Learn in Part 1</h4><ol><li>The philosophical difference between ORM and SQL-first approaches</li><li>How to set up both technologies in Spring Boot</li><li>Why type safety matters and how each approach handles it</li><li>A decision framework for choosing the right tool</li></ol><p>I’ll use a <strong>real PostgreSQL DVD rental </strong><a href="https://github.com/gordonkwokkwok/DVD-Rental-PostgreSQL-Project"><strong>database</strong></a><strong> </strong>throughout this series.</p><h4>Table of Contents</h4><ul><li>The Fundamental Philosophical Difference</li><li>Setup &amp; Code Generation</li><li>Type Safety: Compile-Time vs Runtime</li><li>Decision Framework: When to Use Which</li><li>What’s Coming Next</li></ul><h4>The Fundamental Philosophical Difference</h4><blockquote>Spring Data JPA: Hide SQL Behind Objects</blockquote><p><strong>Philosophy:</strong> <em>“The database is an implementation detail. Work with objects, not tables.”</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ticMUfNuQiZ4eq-TmpeWyQ.png" /></figure><p><strong>How it works:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CjJBktNm1Ge-vGmU_WJzeQ.png" /></figure><p><strong>Key characteristics:</strong></p><ul><li>✅ Code-first: Your Java entities define the database schema</li><li>✅ Automatic CRUD operations generated from interfaces</li><li>✅ Built-in caching (L1 and optional L2)</li><li>✅ Lazy loading for relationships</li><li>✅ Portable across databases (MySQL, PostgreSQL, Oracle)</li><li>❌ SQL is hidden &amp; hard to optimize</li><li>❌ N+1 query problems can sneak in</li><li>❌ Runtime errors if schema diverges from entities</li></ul><blockquote>jOOQ: Embrace SQL with Type Safety</blockquote><p><strong>Philosophy:</strong> <em>&quot;SQL is powerful. Let&#39;s make it type-safe and keep full control.&quot;</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zVwMfnmSHGi7lqPn-bGyAA.png" /></figure><p><strong>How it works:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Oc5opWXaHrp6dpN9Fed7qw.png" /></figure><p><strong>Key characteristics:</strong></p><ul><li>✅ Database-first: Your schema defines the generated code</li><li>✅ Full SQL control with Java syntax</li><li>✅ Compile-time validation of everything</li><li>✅ No hidden queries or N+1 problems</li><li>✅ Direct access to database-specific features</li><li>❌ Requires code generation step</li><li>❌ No automatic caching (explicit Spring Cache needed)</li><li>❌ Less portable (code targets specific database)</li></ul><p><strong>The Core Trade-off:</strong></p><p><strong>Spring Data JPA</strong> optimizes for developer velocity and abstracts away SQL complexity.</p><p><strong>jOOQ</strong> optimizes for type safety, control and leveraging your database’s full power.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E-Ek0P7wtFudLZDgbnTHPw.png" /></figure><h4>Setup &amp; Code Generation</h4><p>Let’s walk through setting up both approaches using a real DVD rental database.</p><h4>Database Schema Overview</h4><p>The PostgreSQL database has these key tables:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*o4iuCN2EXT08t6NLiGUHdg.png" /></figure><h4>Spring Data JPA Setup</h4><p><strong>Step 1: Add Dependencies</strong></p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-data-jpa&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.postgresql&lt;/groupId&gt;<br>    &lt;artifactId&gt;postgresql&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.projectlombok&lt;/groupId&gt;<br>    &lt;artifactId&gt;lombok&lt;/artifactId&gt;<br>&lt;/dependency&gt;</pre><p><strong>Step 2: Configure Database</strong></p><pre># application.yaml<br>spring:<br>  datasource:<br>    url: jdbc:postgresql://localhost:5432/dvdrental<br>    username: postgres<br>    password: postgres<br>    <br>  jpa:<br>    database-platform: org.hibernate.dialect.PostgreSQLDialect<br>    hibernate:<br>      ddl-auto: validate  # Don&#39;t auto-generate schema<br>    show-sql: true</pre><p><strong>Step 3: Create Entity</strong></p><pre>@Entity<br>@Table(name = &quot;payment&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>public class PaymentEntity {<br>    <br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    @Column(name = &quot;payment_id&quot;)<br>    private Integer paymentId;<br>    <br>    @Column(name = &quot;customer_id&quot;, nullable = false)<br>    private Short customerId;<br>    <br>    @Column(name = &quot;staff_id&quot;, nullable = false)<br>    private Short staffId;<br>    <br>    @Column(name = &quot;rental_id&quot;)<br>    private Integer rentalId;<br>    <br>    @Column(name = &quot;amount&quot;, nullable = false)<br>    private BigDecimal amount;<br>    <br>    @Column(name = &quot;payment_date&quot;, nullable = false)<br>    private LocalDateTime paymentDate;<br>}</pre><p><strong>Step 4: Create Repository</strong></p><pre>@Repository<br>public interface PaymentRepository extends JpaRepository&lt;PaymentEntity, Integer&gt; {<br>    <br>    // Spring auto-generates implementation<br>    List&lt;PaymentEntity&gt; findByCustomerId(Short customerId);<br>    <br>    // Custom query with JPQL<br>    @Query(&quot;SELECT p FROM PaymentEntity p WHERE p.amount &gt; :minAmount&quot;)<br>    List&lt;PaymentEntity&gt; findPaymentsAboveAmount(@Param(&quot;minAmount&quot;) BigDecimal minAmount);<br>}</pre><p><strong>Step 5: Use in Service</strong></p><pre>@Service<br>public class PaymentService {<br>    <br>    private final PaymentRepository repository;<br>    <br>    public List&lt;PaymentEntity&gt; getCustomerPayments(Short customerId) {<br>        return repository.findByCustomerId(customerId);<br>    }<br>}</pre><p><strong>✅ Pros:</strong></p><ul><li>Quick setup and you’re querying the database</li><li>No code generation needed</li><li>Convention over configuration</li><li>Auto-implements CRUD</li></ul><p><strong>❌ Cons:</strong></p><ul><li>Manual entity creation (error-prone for large schemas)</li><li>Schema changes require manual entity updates</li><li>Column name typos caught at runtime</li></ul><h4>jOOQ Setup</h4><p><strong>Step 1: Add Dependencies</strong></p><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-jooq&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.postgresql&lt;/groupId&gt;<br>    &lt;artifactId&gt;postgresql&lt;/artifactId&gt;<br>&lt;/dependency&gt;</pre><p><strong>Step 2: Configure Code Generator Plugin</strong></p><pre>&lt;plugin&gt;<br>    &lt;groupId&gt;org.jooq&lt;/groupId&gt;<br>    &lt;artifactId&gt;jooq-codegen-maven&lt;/artifactId&gt;<br>    &lt;version&gt;3.21.3&lt;/version&gt;<br>    <br>    &lt;executions&gt;<br>        &lt;execution&gt;<br>            &lt;phase&gt;generate-sources&lt;/phase&gt;<br>            &lt;goals&gt;<br>                &lt;goal&gt;generate&lt;/goal&gt;<br>            &lt;/goals&gt;<br>        &lt;/execution&gt;<br>    &lt;/executions&gt;<br>    <br>    &lt;dependencies&gt;<br>        &lt;dependency&gt;<br>            &lt;groupId&gt;org.postgresql&lt;/groupId&gt;<br>            &lt;artifactId&gt;postgresql&lt;/artifactId&gt;<br>            &lt;version&gt;42.7.4&lt;/version&gt;<br>        &lt;/dependency&gt;<br>    &lt;/dependencies&gt;<br>    <br>    &lt;configuration&gt;<br>        &lt;jdbc&gt;<br>            &lt;driver&gt;org.postgresql.Driver&lt;/driver&gt;<br>            &lt;url&gt;jdbc:postgresql://localhost:5432/dvdrental&lt;/url&gt;<br>            &lt;user&gt;postgres&lt;/user&gt;<br>            &lt;password&gt;postgres&lt;/password&gt;<br>        &lt;/jdbc&gt;<br>        <br>        &lt;generator&gt;<br>            &lt;database&gt;<br>                &lt;name&gt;org.jooq.meta.postgres.PostgresDatabase&lt;/name&gt;<br>                &lt;inputSchema&gt;public&lt;/inputSchema&gt;<br>                &lt;includes&gt;.*&lt;/includes&gt;<br>            &lt;/database&gt;<br>            <br>            &lt;target&gt;<br>                &lt;packageName&gt;com.mycodethesaurus.jooq.generated&lt;/packageName&gt;<br>                &lt;directory&gt;target/generated-sources/jooq&lt;/directory&gt;<br>            &lt;/target&gt;<br>            <br>            &lt;generate&gt;<br>                &lt;pojos&gt;true&lt;/pojos&gt;<br>                &lt;daos&gt;true&lt;/daos&gt;<br>                &lt;fluentSetters&gt;true&lt;/fluentSetters&gt;<br>                &lt;javaTimeTypes&gt;true&lt;/javaTimeTypes&gt;<br>                &lt;springAnnotations&gt;true&lt;/springAnnotations&gt;<br>                &lt;records&gt;true&lt;/records&gt;<br>            &lt;/generate&gt;<br>        &lt;/generator&gt;<br>    &lt;/configuration&gt;<br>&lt;/plugin&gt;</pre><p><strong>Step 3: Generate Code</strong></p><pre>mvn clean generate-sources</pre><p><strong>Generated Structure:</strong></p><pre>target/generated-sources/jooq/<br>└── com/mycodethesaurus/jooq/generated/<br>    ├── Tables.java                  # All table constants<br>    ├── Keys.java                    # Primary/Foreign keys<br>    ├── Indexes.java                 # Database indexes<br>    └── tables/<br>        ├── Payment.java             # Table class (for queries)<br>        ├── pojos/<br>        │   └── Payment.java         # POJO class<br>        ├── records/<br>        │   └── PaymentRecord.java   # Mutable record<br>        └── daos/<br>            └── PaymentDao.java      # DAO with CRUD</pre><p><strong>Step 4: Configure Application</strong></p><pre># application.yaml<br>spring:<br>  datasource:<br>    url: jdbc:postgresql://localhost:5432/dvdrental<br>    username: postgres<br>    password: postgres<br>    <br>  jooq:<br>    sql-dialect: postgres</pre><p><strong>Step 5: Use in Service</strong></p><pre>import static com.mycodethesaurus.jooq.generated.Tables.PAYMENT;<br><br>@Service<br>public class PaymentJooqService {<br>    <br>    private final DSLContext dsl;<br>    <br>    public PaymentJooqService(DSLContext dsl) {<br>        this.dsl = dsl;<br>    }<br>    <br>    public List&lt;Payment&gt; findByCustomerId(Short customerId) {<br>        return dsl.selectFrom(PAYMENT)<br>                .where(PAYMENT.CUSTOMER_ID.eq(customerId))<br>                .fetchInto(Payment.class);<br>    }<br>    <br>    public List&lt;Payment&gt; findPaymentsAboveAmount(BigDecimal minAmount) {<br>        return dsl.selectFrom(PAYMENT)<br>                .where(PAYMENT.AMOUNT.gt(minAmount))<br>                .orderBy(PAYMENT.AMOUNT.desc())<br>                .fetchInto(Payment.class);<br>    }<br>}</pre><p><strong>✅ Pros:</strong></p><ul><li>Perfect for existing databases</li><li>Auto-generates POJOs, DAOs, Records</li><li>Schema changes automatically reflected after regeneration</li><li>Compile-time validation of everything</li></ul><p><strong>❌ Cons:</strong></p><ul><li>Requires build step (mvn generate-sources)</li><li>More initial setup</li><li>Database must exist before code generation</li></ul><h4>Setups Comparison</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2P1cknDw5YOYeyup328Khg.png" /></figure><h4>Type Safety: Compile-Time vs Runtime</h4><p>This is where jOOQ truly shines. Let’s see why with a real scenario.</p><h4>Scenario: DBA Renames a Column</h4><p>The DBA updates the QA db schema by renaming rental_date to rented_at for consistency before informing the dev team. What happens?</p><h4>Spring Data JPA: Runtime Failure</h4><pre>// Your entity (NOT automatically updated)<br>@Entity<br>@Table(name = &quot;rental&quot;)<br>public class RentalEntity {<br>    <br>    @Column(name = &quot;rental_date&quot;)  // ❌ Still references old column name<br>    private LocalDateTime rentalDate;<br>}<br><br>// Repository query<br>@Query(&quot;SELECT r FROM RentalEntity r WHERE r.rentalDate &gt; :date&quot;)<br>List&lt;RentalEntity&gt; findRecentRentals(@Param(&quot;date&quot;) LocalDateTime date);</pre><p><strong>What happens:</strong></p><p>1. ✅ Code compiles fine</p><p>2. ✅ Unit tests pass (if using H2 or mocks)</p><p>3. ❌ UAT deployment fails with error:</p><pre>org.postgresql.util.PSQLException: <br>ERROR: column &quot;rental_date&quot; does not exist</pre><p><strong>Detection:</strong> It happens at Runtime (Could be in production!)</p><h4>jOOQ: Compile-Time Failure</h4><pre>// After running: mvn generate-sources<br><br>public List&lt;Rental&gt; findRecentRentals(LocalDateTime date) {<br>    return dsl.selectFrom(RENTAL)<br>            .where(RENTAL.RENTAL_DATE.gt(date))  // ❌ COMPILE ERROR<br>            .fetchInto(Rental.class);<br>}</pre><p><strong>What happens:</strong></p><ol><li>Run mvn generate-sources</li><li>jOOQ generates new code with RENTAL.RENTED_AT</li><li><strong>Your code fails to compile</strong></li><li>IDE highlights the error immediately: Cannot resolve symbol &#39;RENTAL_DATE&#39;</li></ol><p><strong>Detection: </strong>It happens at Compile-time (Before deployment!)</p><p><strong>The fix:</strong></p><pre>// IDE auto-complete shows new field name<br>public List&lt;Rental&gt; findRecentRentals(LocalDateTime date) {<br>    return dsl.selectFrom(RENTAL)<br>            .where(RENTAL.RENTED_AT.gt(date))  // ✅ Fixed<br>            .fetchInto(Rental.class);<br>}</pre><h4>The Type Safety Flow</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PR1pkDcEJ-2ru0TxKxvpBQ.png" /></figure><h4>Real-World Impact</h4><p><strong>Scenario:</strong> Refactoring 50 queries after schema change</p><p><strong>Spring Data JPA:</strong></p><pre>1. Search codebase for &quot;rental_date&quot; string<br>2. Manually update each @Query annotation<br>3. Manually update entity mappings<br>4. Hope grep found everything<br>5. Write integration tests to verify<br>6. Deploy and pray</pre><p><strong>Time:</strong> 1–2 hours + testing<br><strong>Risk:</strong> High (easy to miss string references)</p><p><strong>jOOQ:</strong></p><pre>1. mvn generate-sources<br>2. Compilation fails with 50 errors<br>3. IDE &quot;Find Usages&quot; shows all references<br>4. Fix with auto-complete assistance<br>5. Compilation succeeds = done</pre><p><strong>Time:</strong> ~15–30 minutes<br><strong>Risk:</strong> Zero (can’t compile if wrong)</p><h4>Decision Framework: When to Use Which</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*l14sc74NQKUIOEcf0Hz_3w.png" /></figure><h4>The Hybrid Approach (Recommended!)</h4><p>Many production systems use both:</p><pre>@Service<br>public class OrderService {<br>    <br>    private final OrderRepository jpaRepository;  // JPA<br>    private final DSLContext dsl;                 // jOOQ<br>    <br>    // Use JPA for transactional writes<br>    @Transactional<br>    public Order createOrder(OrderRequest request) {<br>        OrderEntity order = new OrderEntity();<br>        order.setCustomerId(request.getCustomerId());<br>        order.setTotal(request.getTotal());<br>        return jpaRepository.save(order);  // ✅ JPA strengths<br>    }<br>    <br>    // Use jOOQ for complex reads<br>    public List&lt;OrderReport&gt; getMonthlyReport(int year, int month) {<br>        return dsl.select(<br>                    CUSTOMER.FIRST_NAME,<br>                    CUSTOMER.LAST_NAME,<br>                    count(PAYMENT.PAYMENT_ID).as(&quot;order_count&quot;),<br>                    sum(PAYMENT.AMOUNT).as(&quot;total_spent&quot;)<br>                )<br>                .from(CUSTOMER)<br>                .join(PAYMENT).on(CUSTOMER.CUSTOMER_ID.eq(PAYMENT.CUSTOMER_ID))<br>                .where(year(PAYMENT.PAYMENT_DATE).eq(year))<br>                .and(month(PAYMENT.PAYMENT_DATE).eq(month))<br>                .groupBy(CUSTOMER.CUSTOMER_ID)<br>                .fetchInto(OrderReport.class);  // ✅ jOOQ strengths<br>    }<br>}</pre><p><strong>Strategy:</strong></p><ul><li><strong>JPA for writes</strong> → Entity lifecycle, validation, cascading</li><li><strong>jOOQ for reads</strong> → Complex queries, reporting, analytics</li></ul><p><strong>Why this works:</strong></p><ul><li>Get JPA’s caching for repeated entity lookups</li><li>Get jOOQ’s type safety for complex queries</li><li>No N+1 problems (jOOQ queries are explicit)</li><li>Best tool for each job</li></ul><h3>What’s Coming Next ?</h3><p>In <strong>Part 2</strong> of this series, we’ll dive deep into query capabilities:</p><ul><li><strong>Dynamic Queries</strong> — Building queries with optional filters</li><li><strong>Complex Joins</strong> — Multi-table joins and the N+1 problem</li><li><strong>Aggregations &amp; GROUP BY</strong> — Revenue reports and analytics</li><li><strong>Window Functions</strong> — Advanced analytics (ranking, running totals)</li><li><strong>Subqueries &amp; CTE</strong>s — Nested queries and Common Table Expressions</li></ul><p>I’ll use the DVD rental database to show real usecase patterns for both approaches.</p><h3>Key Takeaways</h3><ol><li><strong>Spring Data JPA</strong> = Fast development, automatic caching, relationship management</li><li><strong>jOOQ 3.21</strong> = Type safety, SQL control, compile-time validation</li><li><strong>Type safety matters</strong> more than you think (especially during refactoring)</li><li><strong>Hybrid approach</strong> (JPA for writes, jOOQ for reads) works great in production</li><li><strong>Choose based on your needs</strong>, not ideology !</li></ol><h4><em>If you found this helpful, give it a clap 👏 and follow for Part 2!</em></h4><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ac534752b894" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The N+1 Query Problem in Spring Data JPA]]></title>
            <link>https://blog.stackademic.com/the-n-1-query-problem-in-spring-data-jpa-d87813dd1d52?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/d87813dd1d52</guid>
            <category><![CDATA[spring-data-jpa]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Sun, 10 Aug 2025 14:21:43 GMT</pubDate>
            <atom:updated>2025-08-13T06:58:21.073Z</atom:updated>
            <content:encoded><![CDATA[<p>The <strong>N+1 Query Problem</strong> is a common performance anti-pattern in Object-Relational Mapping (ORM) frameworks, particularly prevalent in Spring Data JPA applications.<br>It occurs when an application executes one query to retrieve N parent entities, followed by N additional queries to fetch associated child entities for each parent.</p><h4>Root Causes</h4><ol><li><strong>Lazy Loading Default Behavior</strong>: JPA’s default FetchType.LAZY for @OneToMany and @ManyToMany relationships</li><li><strong>Improper Query Design</strong>: Accessing related entities without proper fetch strategies</li><li><strong>Transaction Boundary Issues</strong>: Accessing lazy collections outside active transactions</li><li><strong>Lack of Query Optimization</strong>: Not utilizing JOIN operations or batch fetching</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*d0LnY0P307r1DIZhTmhbUw.png" /></figure><h4>E-commerce Domain Model Setup</h4><p>Let’s establish an e-commerce domain model to demonstrate the N+1 problem. <br>Here’s the ER diagram showing the entity relationships:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aJoPG-V-BmZU2LVw2V70RQ.png" /></figure><h4>Entity Relationship Summary</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L1p_xtFC2C5fVrN2vLCNeA.png" /></figure><p><strong>Now let’s look at the actual entity implementations:</strong></p><ol><li><strong>Customer Entity:</strong></li></ol><pre>@Entity<br>@Table(name = &quot;customers&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = &quot;orders&quot;)<br>@ToString(exclude = &quot;orders&quot;)<br>public class Customer {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @Column(nullable = false)<br>    private String name;<br>    <br>    @Column(nullable = false, unique = true)<br>    private String email;<br>    <br>    @OneToMany(mappedBy = &quot;customer&quot;, fetch = FetchType.LAZY)<br>    private List&lt;Order&gt; orders = new ArrayList&lt;&gt;();<br>    <br>    // Custom constructor for creating customer without orders<br>    public Customer(String name, String email) {<br>        this.name = name;<br>        this.email = email;<br>        this.orders = new ArrayList&lt;&gt;();<br>    }<br>}</pre><p><strong>2. Order Entity:</strong></p><pre>@Entity<br>@Table(name = &quot;orders&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = {&quot;customer&quot;, &quot;orderItems&quot;})<br>@ToString(exclude = {&quot;customer&quot;, &quot;orderItems&quot;})<br>public class Order {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @Column(name = &quot;order_date&quot;, nullable = false)<br>    private LocalDateTime orderDate;<br>    <br>    @Column(nullable = false)<br>    private BigDecimal totalAmount;<br>    <br>    @ManyToOne(fetch = FetchType.LAZY)<br>    @JoinColumn(name = &quot;customer_id&quot;, nullable = false)<br>    private Customer customer;<br>    <br>    @OneToMany(mappedBy = &quot;order&quot;, fetch = FetchType.LAZY, cascade = CascadeType.ALL)<br>    private List&lt;OrderItem&gt; orderItems = new ArrayList&lt;&gt;();<br>    <br>    // Custom constructor for creating order without items<br>    public Order(LocalDateTime orderDate, BigDecimal totalAmount, Customer customer) {<br>        this.orderDate = orderDate;<br>        this.totalAmount = totalAmount;<br>        this.customer = customer;<br>        this.orderItems = new ArrayList&lt;&gt;();<br>    }<br>}</pre><p><strong>3. Product Entity:</strong></p><pre>@Entity<br>@Table(name = &quot;products&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = &quot;category&quot;)<br>@ToString(exclude = &quot;category&quot;)<br>public class Product {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @Column(nullable = false)<br>    private String name;<br>    <br>    @Column(nullable = false)<br>    private BigDecimal price;<br>    <br>    @ManyToOne(fetch = FetchType.LAZY)<br>    @JoinColumn(name = &quot;category_id&quot;)<br>    private Category category;<br>    <br>    // Custom constructor for creating product with category<br>    public Product(String name, BigDecimal price, Category category) {<br>        this.name = name;<br>        this.price = price;<br>        this.category = category;<br>    }<br>}</pre><p><strong>4. OrderItem Entity:</strong></p><pre>@Entity<br>@Table(name = &quot;order_items&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = {&quot;order&quot;, &quot;product&quot;})<br>@ToString(exclude = {&quot;order&quot;, &quot;product&quot;})<br>public class OrderItem {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @ManyToOne(fetch = FetchType.LAZY)<br>    @JoinColumn(name = &quot;order_id&quot;, nullable = false)<br>    private Order order;<br>    <br>    @ManyToOne(fetch = FetchType.LAZY)<br>    @JoinColumn(name = &quot;product_id&quot;, nullable = false)<br>    private Product product;<br>    <br>    @Column(nullable = false)<br>    private Integer quantity;<br>    <br>    @Column(nullable = false)<br>    private BigDecimal unitPrice;<br>    <br>    // Custom constructor for creating order item<br>    public OrderItem(Order order, Product product, Integer quantity, BigDecimal unitPrice) {<br>        this.order = order;<br>        this.product = product;<br>        this.quantity = quantity;<br>        this.unitPrice = unitPrice;<br>    }<br>}</pre><p><strong>5. Category Entity:</strong></p><pre>@Entity<br>@Table(name = &quot;categories&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = &quot;products&quot;)<br>@ToString(exclude = &quot;products&quot;)<br>public class Category {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @Column(nullable = false)<br>    private String name;<br>    <br>    @OneToMany(mappedBy = &quot;category&quot;, fetch = FetchType.LAZY)<br>    private List&lt;Product&gt; products = new ArrayList&lt;&gt;();<br>    <br>    // Custom constructor for creating category without products<br>    public Category(String name) {<br>        this.name = name;<br>        this.products = new ArrayList&lt;&gt;();<br>    }<br>}</pre><h4>Demonstrating the N+1 Problem</h4><p>Here’s a typical service method that triggers the N+1 problem:</p><p><strong>1. OrderService Class:</strong></p><pre>@Service<br>@Transactional<br>public class OrderService {<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    // This method demonstrates the N+1 problem<br>    public List&lt;CustomerOrderSummary&gt; getCustomerOrderSummaries() {<br>        // 1 query to fetch all customers<br>        List&lt;Customer&gt; customers = customerRepository.findAll();<br>        <br>        List&lt;CustomerOrderSummary&gt; summaries = new ArrayList&lt;&gt;();<br>        <br>        for (Customer customer : customers) {<br>            // N additional queries - one for each customer&#39;s orders<br>            List&lt;Order&gt; orders = customer.getOrders(); // Lazy loading triggers here<br>            <br>            BigDecimal totalSpent = orders.stream()<br>                .map(Order::getTotalAmount)<br>                .reduce(BigDecimal.ZERO, BigDecimal::add);<br>                <br>            summaries.add(new CustomerOrderSummary(<br>                customer.getName(), <br>                customer.getEmail(),<br>                orders.size(), <br>                totalSpent<br>            ));<br>        }<br>        <br>        return summaries;<br>    }<br>}</pre><p><strong>2. CustomerOrderSummary Class:</strong></p><pre>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>public class CustomerOrderSummary {<br>    private String customerName;<br>    private String email;<br>    private int orderCount;<br>    private BigDecimal totalSpent;<br>}</pre><h4>Generated SQL Queries (The Problem)</h4><p>When the above service method executes with 100 customers, here’s what happens:</p><pre>-- Initial query (1 query)<br>SELECT c.id, c.name, c.email <br>FROM customers c;<br><br>-- Then N additional queries (100 queries for 100 customers)<br>SELECT o.id, o.order_date, o.total_amount, o.customer_id <br>FROM orders o <br>WHERE o.customer_id = 1;<br><br>SELECT o.id, o.order_date, o.total_amount, o.customer_id <br>FROM orders o <br>WHERE o.customer_id = 2;<br><br>SELECT o.id, o.order_date, o.total_amount, o.customer_id <br>FROM orders o <br>WHERE o.customer_id = 3;<br><br>-- ... 97 more similar queries<br><br>SELECT o.id, o.order_date, o.total_amount, o.customer_id <br>FROM orders o <br>WHERE o.customer_id = 100;</pre><p><strong>Result: 101 database queries instead of 1 optimized query!</strong></p><h4>Repository Interface (Problematic)</h4><p><strong>CustomerRepository Class:</strong></p><pre>public interface CustomerRepository extends JpaRepository&lt;Customer, Long&gt; {<br>    // This simple findAll() leads to N+1 problem when accessing orders<br>    List&lt;Customer&gt; findAll();<br>    <br>    // Other basic queries that may cause N+1 problems<br>    List&lt;Customer&gt; findByEmailContaining(String emailPart);<br>    <br>    Optional&lt;Customer&gt; findByEmail(String email);<br>}</pre><h4>Performance Impact Analysis</h4><p><strong>Metrics Comparison:<br></strong>Let’s analyze the performance impact with actual numbers:</p><p><strong>PerformaceAnalysisService class:</strong></p><pre>@Service<br>public class PerformanceAnalysisService {<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    public void analyzeN1Performance() {<br>        // Enable Hibernate SQL logging to see actual queries<br>        long startTime = System.currentTimeMillis();<br>        <br>        List&lt;Customer&gt; customers = customerRepository.findAll();<br>        System.out.println(&quot;Fetched &quot; + customers.size() + &quot; customers&quot;);<br>        <br>        int totalOrders = 0;<br>        for (Customer customer : customers) {<br>            totalOrders += customer.getOrders().size(); // N+1 problem occurs here<br>        }<br>        <br>        long endTime = System.currentTimeMillis();<br>        System.out.println(&quot;Total orders: &quot; + totalOrders);<br>        System.out.println(&quot;Execution time: &quot; + (endTime - startTime) + &quot;ms&quot;);<br>    }<br>}</pre><h4>Performance Results</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fu-XiQe-jWN3wslkTa2fdg.png" /></figure><h4>Solution Strategies</h4><p><strong>1. Eager Fetching with @EntityGraph<br>Repository Method with @EntityGraph:</strong></p><pre>public interface CustomerRepository extends JpaRepository&lt;Customer, Long&gt; {<br>    <br>    @EntityGraph(attributePaths = {&quot;orders&quot;})<br>    @Query(&quot;SELECT c FROM Customer c&quot;)<br>    List&lt;Customer&gt; findAllWithOrders();<br>    <br>    @EntityGraph(attributePaths = {&quot;orders&quot;, &quot;orders.orderItems&quot;, &quot;orders.orderItems.product&quot;})<br>    @Query(&quot;SELECT c FROM Customer c&quot;)<br>    List&lt;Customer&gt; findAllWithOrdersAndItems();<br>    <br>    // Named Entity Graph approach<br>    @EntityGraph(&quot;Customer.orders&quot;)<br>    List&lt;Customer&gt; findByEmailContaining(String emailPart);<br>}</pre><p><strong>Entity with NamedEntityGraph:</strong></p><pre>@Entity<br>@Table(name = &quot;customers&quot;)<br>@NamedEntityGraph(<br>    name = &quot;Customer.orders&quot;,<br>    attributeNodes = @NamedAttributeNode(&quot;orders&quot;)<br>)<br>@NamedEntityGraph(<br>    name = &quot;Customer.ordersWithItems&quot;,<br>    attributeNodes = @NamedAttributeNode(value = &quot;orders&quot;, subgraph = &quot;orders-subgraph&quot;),<br>    subgraphs = @NamedSubgraph(<br>        name = &quot;orders-subgraph&quot;,<br>        attributeNodes = {<br>            @NamedAttributeNode(&quot;orderItems&quot;),<br>            @NamedAttributeNode(value = &quot;orderItems&quot;, subgraph = &quot;items-subgraph&quot;)<br>        }<br>    ),<br>    subgraphs = @NamedSubgraph(<br>        name = &quot;items-subgraph&quot;, <br>        attributeNodes = @NamedAttributeNode(&quot;product&quot;)<br>    )<br>)<br>public class Customer {<br>    // Entity definition as before<br>}</pre><p><strong>Optimized Service Implementation:</strong></p><pre>@Service<br>@Transactional<br>public class OptimizedOrderService {<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    // Solution 1: Using @EntityGraph<br>    public List&lt;CustomerOrderSummary&gt; getCustomerOrderSummariesOptimized() {<br>        // Single query with JOIN to fetch customers and their orders<br>        List&lt;Customer&gt; customers = customerRepository.findAllWithOrders();<br>        <br>        return customers.stream()<br>            .map(customer -&gt; {<br>                BigDecimal totalSpent = customer.getOrders().stream()<br>                    .map(Order::getTotalAmount)<br>                    .reduce(BigDecimal.ZERO, BigDecimal::add);<br>                    <br>                return new CustomerOrderSummary(<br>                    customer.getName(),<br>                    customer.getEmail(),<br>                    customer.getOrders().size(),<br>                    totalSpent<br>                );<br>            })<br>            .collect(Collectors.toList());<br>    }<br>}</pre><p><strong>Generated SQL (Optimized with @EntityGraph):</strong></p><pre>-- Single optimized query with JOIN<br>SELECT c.id, c.name, c.email, <br>       o.id, o.order_date, o.total_amount, o.customer_id<br>FROM customers c <br>LEFT JOIN orders o ON c.id = o.customer_id;</pre><p><strong>2. JOIN FETCH in JPQL Queries<br>Repository with JOIN FETCH:</strong></p><pre>public interface CustomerRepository extends JpaRepository&lt;Customer, Long&gt; {<br>    <br>    @Query(&quot;SELECT DISTINCT c FROM Customer c LEFT JOIN FETCH c.orders&quot;)<br>    List&lt;Customer&gt; findAllWithOrdersJoinFetch();<br>    <br>    @Query(&quot;SELECT DISTINCT c FROM Customer c &quot; +<br>           &quot;LEFT JOIN FETCH c.orders o &quot; +<br>           &quot;LEFT JOIN FETCH o.orderItems oi &quot; +<br>           &quot;LEFT JOIN FETCH oi.product&quot;)<br>    List&lt;Customer&gt; findAllWithCompleteOrderData();<br>    <br>    @Query(&quot;SELECT c FROM Customer c &quot; +<br>           &quot;LEFT JOIN FETCH c.orders &quot; +<br>           &quot;WHERE c.email LIKE CONCAT(&#39;%&#39;, :emailPart, &#39;%&#39;)&quot;)<br>    List&lt;Customer&gt; findByEmailContainingWithOrders(@Param(&quot;emailPart&quot;) String emailPart);<br>    <br>    // Paginated JOIN FETCH (requires careful handling)<br>    @Query(value = &quot;SELECT DISTINCT c FROM Customer c LEFT JOIN FETCH c.orders&quot;,<br>           countQuery = &quot;SELECT COUNT(c) FROM Customer c&quot;)<br>    Page&lt;Customer&gt; findAllWithOrdersPaginated(Pageable pageable);<br>}</pre><p><strong>Service Implementation with JOIN FETCH:</strong></p><pre>@Service<br>@Transactional<br>public class JoinFetchOrderService {<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    public List&lt;CustomerOrderDetail&gt; getDetailedCustomerOrders() {<br>        // Single query with multiple JOINs<br>        List&lt;Customer&gt; customers = customerRepository.findAllWithCompleteOrderData();<br>        <br>        return customers.stream()<br>            .map(customer -&gt; {<br>                List&lt;OrderDetail&gt; orderDetails = customer.getOrders().stream()<br>                    .map(order -&gt; {<br>                        List&lt;String&gt; productNames = order.getOrderItems().stream()<br>                            .map(item -&gt; item.getProduct().getName())<br>                            .collect(Collectors.toList());<br>                        <br>                        return new OrderDetail(<br>                            order.getId(),<br>                            order.getOrderDate(),<br>                            order.getTotalAmount(),<br>                            productNames<br>                        );<br>                    })<br>                    .collect(Collectors.toList());<br>                    <br>                return new CustomerOrderDetail(<br>                    customer.getName(),<br>                    customer.getEmail(),<br>                    orderDetails<br>                );<br>            })<br>            .collect(Collectors.toList());<br>    }<br>}</pre><p><strong>3. Batch Fetching Configuration<br>Hibernate Configuration for Batch Fetching:</strong></p><pre>spring:<br>  jpa:<br>    properties:<br>      hibernate:<br>        default_batch_fetch_size: 16<br>        batch_fetch_style: DYNAMIC</pre><p><strong>Entity-Level Batch Size Configuration:</strong></p><pre>@Entity<br>@Table(name = &quot;customers&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = &quot;orders&quot;)<br>@ToString(exclude = &quot;orders&quot;)<br>public class Customer {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @Column(nullable = false)<br>    private String name;<br>    <br>    @Column(nullable = false, unique = true)<br>    private String email;<br>    <br>    @OneToMany(mappedBy = &quot;customer&quot;, fetch = FetchType.LAZY)<br>    @BatchSize(size = 25) // Fetch in batches of 25<br>    private List&lt;Order&gt; orders = new ArrayList&lt;&gt;();<br>}<br><br>@Entity<br>@Table(name = &quot;orders&quot;)<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>@EqualsAndHashCode(exclude = {&quot;customer&quot;, &quot;orderItems&quot;})<br>@ToString(exclude = {&quot;customer&quot;, &quot;orderItems&quot;})<br>public class Order {<br>    @Id<br>    @GeneratedValue(strategy = GenerationType.IDENTITY)<br>    private Long id;<br>    <br>    @Column(name = &quot;order_date&quot;, nullable = false)<br>    private LocalDateTime orderDate;<br>    <br>    @Column(nullable = false)<br>    private BigDecimal totalAmount;<br>    <br>    @ManyToOne(fetch = FetchType.LAZY)<br>    @JoinColumn(name = &quot;customer_id&quot;, nullable = false)<br>    private Customer customer;<br>    <br>    @OneToMany(mappedBy = &quot;order&quot;, fetch = FetchType.LAZY)<br>    @BatchSize(size = 50) // Fetch order items in batches of 50<br>    private List&lt;OrderItem&gt; orderItems = new ArrayList&lt;&gt;();<br>}</pre><p><strong>Service with Batch Fetching:</strong></p><pre>@Service<br>@Transactional<br>public class BatchFetchOrderService {<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    public List&lt;CustomerOrderSummary&gt; getCustomerSummariesWithBatching() {<br>        List&lt;Customer&gt; customers = customerRepository.findAll();<br>        <br>        // Orders will be fetched in batches instead of individual queries<br>        return customers.stream()<br>            .map(customer -&gt; {<br>                // This triggers batch fetching of orders<br>                List&lt;Order&gt; orders = customer.getOrders();<br>                <br>                BigDecimal totalSpent = orders.stream()<br>                    .map(Order::getTotalAmount)<br>                    .reduce(BigDecimal.ZERO, BigDecimal::add);<br>                    <br>                return new CustomerOrderSummary(<br>                    customer.getName(),<br>                    customer.getEmail(),<br>                    orders.size(),<br>                    totalSpent<br>                );<br>            })<br>            .collect(Collectors.toList());<br>    }<br>}</pre><p><strong>Generated SQL with Batch Fetching:</strong></p><pre>-- Initial query<br>SELECT c.id, c.name, c.email FROM customers c;<br><br>-- Instead of N queries, batch fetching generates fewer queries:<br>-- Batch 1 (for customer IDs 1-25)<br>SELECT o.id, o.order_date, o.total_amount, o.customer_id <br>FROM orders o <br>WHERE o.customer_id IN (1, 2, 3, ..., 25);<br><br>-- Batch 2 (for customer IDs 26-50)<br>SELECT o.id, o.order_date, o.total_amount, o.customer_id <br>FROM orders o <br>WHERE o.customer_id IN (26, 27, 28, ..., 50);<br><br>-- And so on...</pre><p><strong>4. Proper Lazy Loading Techniques<br>DTO Projection Approach:</strong></p><pre>// DTO for optimized data transfer<br>@Data<br>@NoArgsConstructor<br>@AllArgsConstructor<br>public class CustomerOrderSummaryDto {<br>    private String customerName;<br>    private String email;<br>    private Long orderCount;<br>    private BigDecimal totalSpent;<br>}<br><br>// Repository with native DTO projection<br>public interface CustomerRepository extends JpaRepository&lt;Customer, Long&gt; {<br>    <br>    @Query(&quot;SELECT new com.example.dto.CustomerOrderSummaryDto(&quot; +<br>           &quot;c.name, c.email, COUNT(o), COALESCE(SUM(o.totalAmount), 0)) &quot; +<br>           &quot;FROM Customer c LEFT JOIN c.orders o &quot; +<br>           &quot;GROUP BY c.id, c.name, c.email&quot;)<br>    List&lt;CustomerOrderSummaryDto&gt; findCustomerOrderSummaries();<br>    <br>    // Interface-based projections<br>    interface CustomerOrderProjection {<br>        String getName();<br>        String getEmail();<br>        Long getOrderCount();<br>        BigDecimal getTotalSpent();<br>    }<br>    <br>    @Query(&quot;SELECT c.name as name, c.email as email, &quot; +<br>           &quot;COUNT(o) as orderCount, COALESCE(SUM(o.totalAmount), 0) as totalSpent &quot; +<br>           &quot;FROM Customer c LEFT JOIN c.orders o &quot; +<br>           &quot;GROUP BY c.id, c.name, c.email&quot;)<br>    List&lt;CustomerOrderProjection&gt; findCustomerOrderProjections();<br>}</pre><p><strong>Service with DTO Projections:</strong></p><pre>@Service<br>@Transactional(readOnly = true)<br>public class ProjectionOrderService {<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    // Most efficient approach - single query with aggregation<br>    public List&lt;CustomerOrderSummaryDto&gt; getCustomerSummariesEfficient() {<br>        // Single query with GROUP BY and aggregation functions<br>        return customerRepository.findCustomerOrderSummaries();<br>    }<br>    <br>    public List&lt;CustomerOrderProjection&gt; getCustomerProjections() {<br>        return customerRepository.findCustomerOrderProjections();<br>    }<br>}</pre><h4>Best Practices and Recommendations</h4><p><strong>1. Query Strategy Selection Matrix</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_HrQtxFCoPpzkf8u_KPI8Q.png" /></figure><p><strong>2. Performance Optimization Checklist</strong></p><pre>@Component<br>public class QueryOptimizationChecker {<br>    <br>    // ✅ Good: Use @EntityGraph for predictable associations  <br>    @EntityGraph(attributePaths = {&quot;orders&quot;})<br>    List&lt;Customer&gt; findAllWithOrders();<br>    <br>    // ✅ Good: Use DTO projections for read-only operations<br>    @Query(&quot;SELECT new com.example.dto.CustomerSummary(c.name, COUNT(o)) &quot; +<br>           &quot;FROM Customer c LEFT JOIN c.orders o GROUP BY c.id&quot;)<br>    List&lt;CustomerSummary&gt; findCustomerSummaries();<br>    <br>    // ❌ Bad: Accessing lazy collections in loops<br>    public void badExample() {<br>        List&lt;Customer&gt; customers = customerRepository.findAll();<br>        for (Customer customer : customers) {<br>            customer.getOrders().size(); // N+1 problem!<br>        }<br>    }<br>    <br>    // ✅ Good: Fetch associations upfront<br>    public void goodExample() {<br>        List&lt;Customer&gt; customers = customerRepository.findAllWithOrders();<br>        for (Customer customer : customers) {<br>            customer.getOrders().size(); // No additional queries<br>        }<br>    }<br>}</pre><p><strong>3. Configuration Best Practices</strong></p><pre># application.yml - Production configuration<br>spring:<br>  jpa:<br>    show-sql: false  # Disable in production<br>    properties:<br>      hibernate:<br>        default_batch_fetch_size: 16<br>        batch_fetch_style: DYNAMIC<br>        jdbc:<br>          batch_size: 25<br>        order_inserts: true<br>        order_updates: true<br>        batch_versioned_data: true<br>        generate_statistics: false  # Disable in production<br>        <br># Development configuration<br>---<br>spring:<br>  profiles: dev<br>  jpa:<br>    show-sql: true<br>    properties:<br>      hibernate:<br>        format_sql: true<br>        use_sql_comments: true<br>        generate_statistics: true<br><br>logging:<br>  level:<br>    org.hibernate.SQL: DEBUG<br>    org.hibernate.stat: DEBUG</pre><p><strong>4. Testing N+1 Problem:</strong></p><pre>@SpringBootTest<br>@TestPropertySource(properties = {<br>    &quot;spring.jpa.show-sql=true&quot;,<br>    &quot;logging.level.org.hibernate.SQL=DEBUG&quot;<br>})<br>class N1QueryTest {<br>    <br>    @Autowired<br>    private TestEntityManager entityManager;<br>    <br>    @Autowired<br>    private CustomerRepository customerRepository;<br>    <br>    @Test<br>    void testN1Problem() {<br>        // Given: Create test data<br>        Customer customer1 = new Customer(&quot;John&quot;, &quot;john@example.com&quot;);<br>        Customer customer2 = new Customer(&quot;Jane&quot;, &quot;jane@example.com&quot;);<br>        <br>        entityManager.persistAndFlush(customer1);<br>        entityManager.persistAndFlush(customer2);<br>        <br>        Order order1 = new Order(LocalDateTime.now(), new BigDecimal(&quot;100&quot;), customer1);<br>        Order order2 = new Order(LocalDateTime.now(), new BigDecimal(&quot;200&quot;), customer2);<br>        <br>        entityManager.persistAndFlush(order1);<br>        entityManager.persistAndFlush(order2);<br>        entityManager.clear();<br>        <br>        // When: Execute query that might cause N+1<br>        List&lt;Customer&gt; customers = customerRepository.findAll();<br>        <br>        // This will trigger N+1 if not properly optimized<br>        int totalOrders = customers.stream()<br>            .mapToInt(c -&gt; c.getOrders().size())<br>            .sum();<br>            <br>        // Then: Verify expected behavior<br>        assertThat(totalOrders).isEqualTo(2);<br>    }<br>    <br>    @Test <br>    void testOptimizedQuery() {<br>        // Test the optimized version<br>        List&lt;Customer&gt; customers = customerRepository.findAllWithOrders();<br>        <br>        // Should not trigger additional queries<br>        int totalOrders = customers.stream()<br>            .mapToInt(c -&gt; c.getOrders().size())<br>            .sum();<br>            <br>        assertThat(totalOrders).isEqualTo(2);<br>    }<br>}</pre><h3>Conclusion</h3><p>The N+1 Query Problem is a critical performance issue that can severely impact any application in this case an e-commerce applications dealing with complex relationships between customers, orders, and products.</p><p>Understanding the root causes and implementing appropriate solutions is essential for building scalable applications.</p><h4>Key Takeaways:</h4><ol><li><strong>Identify Early</strong>: Use SQL logging and monitoring to detect N+1 problems during development</li><li><strong>Choose Appropriate Solutions</strong>: Match the solution strategy to your specific use case</li><li><strong>Test Performance</strong>: Always measure query performance with realistic data volumes</li><li><strong>Monitor in Production</strong>: Implement metrics and monitoring to catch performance regressions</li></ol><p><strong>Remember:</strong> The best solution depends on specific use case, data size, and performance requirements. Always profile and test the chosen approach with realistic data volumes to ensure optimal performance.</p><h3>A message from our Founder</h3><p><strong>Hey, </strong><a href="https://linkedin.com/in/sunilsandhu"><strong>Sunil</strong></a><strong> here.</strong> I wanted to take a moment to thank you for reading until the end and for being a part of this community.</p><p>Did you know that our team run these publications as a volunteer effort to over 3.5m monthly readers? <strong>We don’t receive any funding, we do this to support the community. ❤️</strong></p><p>If you want to show some love, please take a moment to <strong>follow me on </strong><a href="https://linkedin.com/in/sunilsandhu"><strong>LinkedIn</strong></a><strong>, </strong><a href="https://tiktok.com/@messyfounder"><strong>TikTok</strong></a>, <a href="https://instagram.com/sunilsandhu"><strong>Instagram</strong></a>. You can also subscribe to our <a href="https://newsletter.plainenglish.io/"><strong>weekly newsletter</strong></a>.</p><p>And before you go, don’t forget to <strong>clap</strong> and <strong>follow</strong> the writer️!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d87813dd1d52" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/the-n-1-query-problem-in-spring-data-jpa-d87813dd1d52">The N+1 Query Problem in Spring Data JPA</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[FasterXML Jackson API: A Comprehensive Overview]]></title>
            <link>https://blog.stackademic.com/fasterxml-jackson-api-a-comprehensive-overview-10b9362a14cb?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/10b9362a14cb</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Sat, 02 Aug 2025 09:08:46 GMT</pubDate>
            <atom:updated>2025-08-04T05:59:03.694Z</atom:updated>
            <content:encoded><![CDATA[<p>Jackson is one of the most popular and widely used Java libraries for processing JSON data. Created by FasterXML and maintained as an open-source project, it has become the de facto standard for JSON processing in Java applications.<br>This post provides a detailed overview of the Jackson API architecture, its core components, key features, and common usage patterns.</p><blockquote><strong>Jackson API Architecture</strong></blockquote><p>Jackson follows a modular architecture that is divided into several key components:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DrjDIaq1Wc3R9eVXx6EsoQ.png" /></figure><blockquote><strong>Core Modules</strong></blockquote><p>Jackson is organized into several key modules, each with a specific focus:</p><p>1. <strong>Jackson Core (jackson-core)</strong> — The foundational streaming API that provides low-level JSON processing capabilities</p><p>2. <strong>Jackson Annotations (jackson-annotations)</strong> — Annotations for customizing JSON serialization and deserialization</p><p>3. <strong>Jackson Databind (jackson-databind)</strong> — High-level data binding between Java objects and JSON</p><p>4. <strong>Jackson Modules</strong> — Extensions that add support for various data formats and features</p><blockquote><strong>Core Components</strong></blockquote><p><strong>1. Jackson Core (Streaming API)</strong></p><p>The Streaming API provides low-level JSON processing capabilities. It’s the foundation upon which other Jackson components are built.</p><p>Key classes:</p><ul><li>JsonFactory - Factory for creating parsers and generators</li><li>JsonParser - For reading JSON content token by token</li><li>JsonGenerator - For writing JSON content token by token</li></ul><p>Example:</p><pre>JsonFactory factory = new JsonFactory();<br>try (JsonParser parser = factory.createParser(jsonString)) {<br>    while (parser.nextToken() != null) {<br>        // Process JSON tokens<br>    }<br>}</pre><p><strong>2. Jackson Databind (ObjectMapper)</strong></p><p>ObjectMapper is the central component of Jackson Databind. It provides functionality for converting between Java objects and JSON.</p><p>Key capabilities:</p><ul><li>Serialize Java objects to JSON</li><li>Deserialize JSON to Java objects</li><li>Configure serialization/deserialization behavior</li><li>Handle complex object graphs</li><li>Support for polymorphic types</li></ul><p>Example:</p><pre>ObjectMapper mapper = new ObjectMapper();<br><br>// Serialization (Java object to JSON)<br>String json = mapper.writeValueAsString(myObject);<br><br>// Deserialization (JSON to Java object)<br>MyClass myObject = mapper.readValue(json, MyClass.class);</pre><p><strong>3. Jackson Annotations</strong></p><p>Jackson annotations provide a way to customize how Java objects are serialized to and deserialized from JSON.</p><p>Key annotations:</p><ul><li>@JsonProperty - Specify property name in JSON</li><li>@JsonIgnore - Exclude property from serialization/deserialization</li><li>@JsonFormat - Format dates and numbers</li><li>@JsonInclude - Control when properties are included (e.g., non-null)</li><li>@JsonSerialize / @JsonDeserialize - Specify custom serializers/deserializers</li></ul><p>Example:</p><pre>public class User {<br>    @JsonProperty(&quot;user_id&quot;)<br>    private long id;<br>    <br>    private String name;<br>    <br>    @JsonIgnore<br>    private String password;<br>    <br>    @JsonFormat(pattern = &quot;yyyy-MM-dd&quot;)<br>    private Date birthDate;<br>    <br>    // getters and setters<br>}</pre><p><strong>4. Tree Model (JsonNode)</strong></p><p>The Tree Model provides a way to represent JSON as a tree of nodes, similar to DOM for XML.</p><p>Key classes:</p><ul><li>JsonNode - Base class for all nodes in the tree</li><li>ObjectNode - Represents a JSON object</li><li>ArrayNode - Represents a JSON array</li></ul><p>Example:</p><pre>ObjectMapper mapper = new ObjectMapper();<br>JsonNode rootNode = mapper.readTree(jsonString);<br><br>String name = rootNode.get(&quot;name&quot;).asText();<br>int age = rootNode.get(&quot;age&quot;).asInt();<br><br>ArrayNode hobbiesNode = (ArrayNode) rootNode.get(&quot;hobbies&quot;);<br>for (JsonNode hobby : hobbiesNode) {<br>    System.out.println(hobby.asText());<br>}</pre><blockquote>Module Ecosystem</blockquote><p>Jackson has a rich ecosystem of modules that extend its functionality:</p><p><strong>1. Data Format Modules</strong></p><ul><li>jackson-dataformat-xml — XML support</li><li>jackson-dataformat-yaml — YAML support</li><li>jackson-dataformat-csv — CSV support</li><li>jackson-dataformat-protobuf — Protocol Buffers support</li><li>jackson-dataformat-avro — Avro support</li></ul><p><strong>2. Datatype Modules</strong></p><ul><li>jackson-datatype-jsr310 — Java 8 date/time support</li><li>jackson-datatype-joda — Joda-Time support</li><li>jackson-datatype-guava — Guava collections support</li></ul><p><strong>3. Language Modules</strong></p><ul><li>jackson-module-kotlin — Kotlin support</li><li>jackson-module-scala — Scala support</li></ul><p><strong>4. Other Modules</strong></p><ul><li>jackson-module-afterburner — Performance optimizations</li><li>jackson-module-parameter-names — Use parameter names as properties</li></ul><blockquote>Key Features</blockquote><p><strong>1. Data Binding</strong></p><p>Jackson’s data binding capability allows seamless conversion between Java objects and JSON. There are two types:</p><ul><li><strong>Simple Data Binding</strong>: Converting between JSON and Java Maps, Lists, Strings, Numbers, Booleans, and nulls.</li><li><strong>Full Data Binding</strong>: Converting between JSON and any Java bean or POJO.</li></ul><p><strong>2. Streaming API</strong></p><p>The streaming API provides efficient, low-level processing of JSON by reading and writing JSON content as a sequence of tokens.</p><p><strong>3. Tree Model</strong></p><p>The tree model allows working with JSON as a tree of nodes, enabling random access and manipulation of the JSON structure.</p><p><strong>4. Customization Options</strong></p><p>Jackson provides extensive customization options:</p><ul><li>Custom serializers and deserializers</li><li>Mix-in annotations</li><li>Object mapper configuration</li><li>PropertyNamingStrategy for automatic name transformations</li><li>Visibility settings for controlling which fields/methods are included</li></ul><p><strong>5. Polymorphic Type Handling</strong></p><p>Jackson supports serialization and deserialization of polymorphic types, allowing proper handling of inheritance hierarchies.</p><pre>@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = &quot;type&quot;)<br>@JsonSubTypes({<br>    @JsonSubTypes.Type(value = Dog.class, name = &quot;dog&quot;),<br>    @JsonSubTypes.Type(value = Cat.class, name = &quot;cat&quot;)<br>})<br>public abstract class Animal {<br>    private String name;<br>    // getters and setters<br>}</pre><p><strong>6. Lazy Loading and Partial Data Binding</strong></p><p>Jackson supports techniques for efficient handling of large data structures:</p><ul><li>Streaming for sequential processing</li><li>Lazy loading of nested objects</li><li>Partial data binding with @JsonView</li></ul><blockquote>Common Use Cases</blockquote><h4><strong>1. REST API Development</strong></h4><p>Jackson is commonly used in REST API development for converting between Java objects and JSON request/response bodies. It integrates seamlessly with frameworks like Spring MVC, JAX-RS, and others.</p><p><strong>Jackson Annotations for REST APIs:</strong></p><p><strong>A. Property Naming Control:<br>Use Case</strong>: Match JSON field names to API conventions (camelCase, snake_case, etc.)</p><pre>public class ProductDTO {<br>    // Rename Java property to match API naming convention<br>    @JsonProperty(&quot;product_id&quot;)<br>    private Long id;<br>    <br>    @JsonProperty(&quot;product_name&quot;)<br>    private String name;<br>    <br>    // Auto-convert all properties using a naming strategy (application-wide)<br>    // Configure in ObjectMapper: <br>    // objectMapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);<br>}</pre><p><strong>B. Controlling Field Visibility<br>Use Case</strong>: Selectively include/exclude fields in API responses</p><pre>public class UserProfile {<br>    // Include in responses, but ignore when parsing requests<br>    @JsonProperty(access = JsonProperty.Access.READ_ONLY)<br>    private LocalDateTime createdAt;<br>    <br>    // Field will be excluded from serialization<br>    @JsonIgnore<br>    private String internalNote;<br>    <br>    // Only include non-null fields in responses<br>    @JsonInclude(JsonInclude.Include.NON_NULL)<br>    private String optionalInfo;<br>    <br>    // Only include in responses if not empty<br>    @JsonInclude(JsonInclude.Include.NON_EMPTY)<br>    private List&lt;String&gt; tags;<br>}</pre><p><strong>C. Date and Time Formatting</strong><br><strong>Use Case</strong>: Format dates in API responses according to standards</p><pre>public class EventDTO {<br>    // Format dates according to ISO-8601 standard<br>    @JsonFormat(pattern = &quot;yyyy-MM-dd&#39;T&#39;HH:mm:ss.SSSZ&quot;, shape = JsonFormat.Shape.STRING)<br>    private LocalDateTime eventTime;<br>    <br>    // Format date only<br>    @JsonFormat(pattern = &quot;yyyy-MM-dd&quot;)<br>    private LocalDate eventDate;<br>    <br>    // Using timezone<br>    @JsonFormat(pattern = &quot;yyyy-MM-dd&#39;T&#39;HH:mm:ss&quot;, timezone = &quot;UTC&quot;)<br>    private Date creationDate;<br>}</pre><p><strong>D. Polymorphic Type Handling<br>Use Case</strong>: Working with inheritance and polymorphic types in APIs</p><pre>// Base class<br>@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = &quot;type&quot;)<br>@JsonSubTypes({<br>    @JsonSubTypes.Type(value = CreditCardPayment.class, name = &quot;credit_card&quot;),<br>    @JsonSubTypes.Type(value = PayPalPayment.class, name = &quot;paypal&quot;),<br>    @JsonSubTypes.Type(value = BankTransferPayment.class, name = &quot;bank_transfer&quot;)<br>})<br>public abstract class Payment {<br>    private BigDecimal amount;<br>    // Common fields and methods<br>}<br><br>// Concrete implementation<br>public class CreditCardPayment extends Payment {<br>    private String cardNumber;<br>    private String expiryDate;<br>    // Credit card specific fields<br>}</pre><p><strong>E. Custom Serialization and Deserialization<br>Use Case</strong>: Complex objects need custom JSON representation</p><pre>public class Order {<br>    // Custom serializer for complex types<br>    @JsonSerialize(using = MonetaryAmountSerializer.class)<br>    @JsonDeserialize(using = MonetaryAmountDeserializer.class)<br>    private MonetaryAmount total;<br>}<br><br>// Custom serializer implementation<br>public class MonetaryAmountSerializer extends JsonSerializer&lt;MonetaryAmount&gt; {<br>    @Override<br>    public void serialize(MonetaryAmount value, JsonGenerator gen, SerializerProvider provider) throws IOException {<br>        gen.writeStartObject();<br>        gen.writeNumberField(&quot;amount&quot;, value.getNumber().doubleValue());<br>        gen.writeStringField(&quot;currency&quot;, value.getCurrency().getCurrencyCode());<br>        gen.writeEndObject();<br>    }<br>}</pre><p><strong>F. Versioning and Backward Compatibility<br>Use Case</strong>: Supporting multiple API versions without breaking changes</p><pre>public class ProductV2 {<br>    private String name;<br>    private BigDecimal price;<br>    <br>    // Only include in API response for version 2 or higher<br>    @JsonView(Views.V2.class)<br>    private List&lt;String&gt; categories;<br>    <br>    // Added in V3, ignored in older versions<br>    @JsonView(Views.V3.class)<br>    private Map&lt;String, String&gt; attributes;<br>}<br><br>// Define view classes for different API versions<br>public class Views {<br>    public static class V1 {}<br>    public static class V2 extends V1 {}<br>    public static class V3 extends V2 {}<br>}<br><br>// In controller, specify which view to use<br>@GetMapping(&quot;/products/{id}/v2&quot;)<br>@JsonView(Views.V2.class)<br>public ProductV2 getProductV2(@PathVariable Long id) {<br>    return productService.findById(id);<br>}</pre><p><strong>G. Handling Bidirectional Relationships<br>Use Case</strong>: Preventing infinite recursion in object graphs</p><pre>public class Department {<br>    private String name;<br>    <br>    // Prevent infinite recursion by ignoring the back-reference<br>    @JsonManagedReference<br>    private List&lt;Employee&gt; employees;<br>}<br><br>public class Employee {<br>    private String name;<br>    <br>    // Back reference to parent - serialized as reference only<br>    @JsonBackReference<br>    private Department department;<br>}</pre><p><strong>H. Request Parameter Binding<br>Use Case</strong>: Binding JSON data to method parameters</p><pre>@RestController<br>public class OrderController {<br>    <br>    // @RequestBody uses Jackson to deserialize the request body<br>    @PostMapping(&quot;/orders&quot;)<br>    public ResponseEntity&lt;Order&gt; createOrder(@RequestBody @Valid OrderRequest request) {<br>        // Process order<br>        return ResponseEntity.ok(orderService.create(request));<br>    }<br>    <br>    // Unwrapping nested JSON objects<br>    @PostMapping(&quot;/orders/{id}/items&quot;)<br>    public ResponseEntity&lt;OrderItem&gt; addItem(<br>            @PathVariable Long id,<br>            @JsonUnwrapped @RequestBody OrderItemRequest itemRequest) {<br>        // Add item to order<br>        return ResponseEntity.ok(orderService.addItem(id, itemRequest));<br>    }<br>}</pre><p><strong>I. Custom Property Filtering<br>Use Case</strong>: Dynamic filtering of response fields based on context</p><pre>@JsonFilter(&quot;orderFilter&quot;)<br>public class Order {<br>    private Long id;<br>    private String customerName;<br>    private String address;<br>    private List&lt;OrderItem&gt; items;<br>    private String creditCardNumber;<br>}<br><br>// In controller, apply filter dynamically<br>@GetMapping(&quot;/orders/{id}&quot;)<br>public MappingJacksonValue getOrder(@PathVariable Long id) {<br>    Order order = orderService.findById(id);<br>    <br>    SimpleBeanPropertyFilter filter = SimpleBeanPropertyFilter<br>        .serializeAllExcept(&quot;creditCardNumber&quot;);<br>        <br>    FilterProvider filters = new SimpleFilterProvider()<br>        .addFilter(&quot;orderFilter&quot;, filter);<br>        <br>    MappingJacksonValue mapping = new MappingJacksonValue(order);<br>    mapping.setFilters(filters);<br>    <br>    return mapping;<br>}</pre><p><strong>J. Error Response Handling<br>Use Case</strong>: Consistent error response format</p><pre>// Custom error response class<br>public class ApiError {<br>    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = &quot;yyyy-MM-dd&#39;T&#39;HH:mm:ss.SSSZ&quot;)<br>    private LocalDateTime timestamp;<br>    <br>    private int status;<br>    <br>    @JsonProperty(&quot;error&quot;)<br>    private String error;<br>    <br>    @JsonProperty(&quot;message&quot;)<br>    private String message;<br>    <br>    @JsonInclude(JsonInclude.Include.NON_EMPTY)<br>    private List&lt;String&gt; details;<br>}<br><br>// In exception handler<br>@ExceptionHandler(Exception.class)<br>public ResponseEntity&lt;ApiError&gt; handleException(Exception ex) {<br>    ApiError error = new ApiError();<br>    error.setTimestamp(LocalDateTime.now());<br>    error.setStatus(HttpStatus.INTERNAL_SERVER_ERROR.value());<br>    error.setError(&quot;Internal Server Error&quot;);<br>    error.setMessage(ex.getMessage());<br>    <br>    return new ResponseEntity&lt;&gt;(error, HttpStatus.INTERNAL_SERVER_ERROR);<br>}</pre><h4>2. Configuration File Processing</h4><p>Jackson can be used to read and write configuration files in JSON format.</p><pre>ObjectMapper mapper = new ObjectMapper();<br>AppConfig config = mapper.readValue(new File(&quot;config.json&quot;), AppConfig.class);</pre><h4>3. Data Transformation</h4><p>Jackson can be used to transform data between different formats or structures.</p><pre>ObjectMapper mapper = new ObjectMapper();<br>JsonNode rootNode = mapper.readTree(jsonString);<br><br>// Transform data<br>ObjectNode transformedNode = mapper.createObjectNode();<br>transformedNode.put(&quot;fullName&quot;, rootNode.get(&quot;firstName&quot;).asText() + &quot; &quot; + rootNode.get(&quot;lastName&quot;).asText());<br>transformedNode.put(&quot;isAdult&quot;, rootNode.get(&quot;age&quot;).asInt() &gt;= 18);<br><br>String transformedJson = mapper.writeValueAsString(transformedNode);</pre><h4>4. Working with External APIs</h4><p>Jackson is often used to parse JSON responses from external APIs.</p><pre>HttpClient client = HttpClient.newHttpClient();<br>HttpRequest request = HttpRequest.newBuilder()<br>        .uri(URI.create(&quot;https://api.example.com/data&quot;))<br>        .build();<br><br>HttpResponse&lt;String&gt; response = client.send(request, HttpResponse.BodyHandlers.ofString());<br>ObjectMapper mapper = new ObjectMapper();<br>DataResponse data = mapper.readValue(response.body(), DataResponse.class);</pre><blockquote>Architecture Diagram</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zW6TlUkS1orP3-wl55jREA.png" /></figure><blockquote>Performance Considerations</blockquote><h4>Efficiency</h4><p>Jackson is designed to be highly efficient and performs well for most use cases. Some performance considerations include:</p><p><strong>1. Use Streaming API for large data sets</strong>: For processing very large JSON documents, the Streaming API is more memory-efficient than loading the entire document into memory.</p><p><strong>2. Reuse ObjectMapper</strong>: ObjectMapper creation is expensive, so create it once and reuse it throughout your application.</p><p><strong>3. Configure JSON parsing for efficiency</strong>: Disable unnecessary features you don’t need.</p><pre>ObjectMapper mapper = new ObjectMapper()<br>    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)<br>    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);</pre><p><strong>4. Consider afterburner module</strong>: For high-performance applications, the afterburner module can provide significant performance improvements.</p><pre>ObjectMapper mapper = new ObjectMapper()<br>    .registerModule(new AfterburnerModule());</pre><h4>Memory Usage</h4><p>For large JSON documents, memory usage can be a concern. Approaches to minimize memory usage:</p><ol><li>Use streaming parser for large documents</li><li>Process nested structures incrementally</li><li>Use filtering to process only the needed parts of a document</li></ol><blockquote>Best Practices</blockquote><h4>Configuration</h4><p><strong>1. Configure ObjectMapper globally</strong>: Create a single ObjectMapper instance configured according to your application’s needs.</p><pre>@Configuration<br>public class JacksonConfig {<br>    @Bean<br>    public ObjectMapper objectMapper() {<br>        return new ObjectMapper()<br>            .registerModule(new JavaTimeModule())<br>            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)<br>            .setSerializationInclusion(JsonInclude.Include.NON_NULL);<br>    }<br>}</pre><p><strong>2. Use appropriate inclusion settings: </strong>Use JsonInclude to control when properties are included in JSON output.</p><h4>Error Handling</h4><p><strong>1. Handle deserialization errors gracefully</strong>: Configure how Jackson should handle unknown properties or invalid values.</p><pre>mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);</pre><p><strong>2. Use exception handling for parse errors:</strong></p><pre>try {<br>    User user = mapper.readValue(json, User.class);<br>} catch (JsonProcessingException e) {<br>    // Handle parsing error<br>}</pre><h4>Security</h4><p><strong>1. Be careful with deserialization</strong>: Deserializing untrusted JSON can lead to security vulnerabilities. Consider:</p><ul><li>Using allowlist of classes that can be deserialized</li><li>Configuring polymorphic type handling carefully</li><li>Validating input before deserialization</li></ul><p><strong>2. Avoid exposing sensitive information</strong>: Use @JsonIgnore or filtering to prevent sensitive data from being serialized.</p><h4>Conclusion</h4><p>Jackson is a powerful and flexible Java library for working with JSON data. Its modular architecture, rich feature set, and extensive customization options make it suitable for a wide range of use cases, from simple data binding to complex data transformation tasks.</p><p>The key strengths of Jackson include:</p><ul><li>High performance and low memory footprint</li><li>Extensive customization options</li><li>Strong support for various data formats</li><li>Seamless integration with popular Java frameworks</li><li>Thread-safe components for concurrent applications</li><li>Rich ecosystem of modules for different use cases</li><li>Active development and community support</li></ul><p>Whether you’re developing RESTful web services, processing configuration files, working with external APIs, or integrating with other data processing frameworks, Jackson provides the tools you need to efficiently handle JSON data in your Java applications.</p><h3>Thank you for being a part of the community</h3><p><em>Before you go:</em></p><ul><li>Be sure to <strong>clap</strong> and <strong>follow</strong> the writer ️👏️<strong>️</strong></li><li>Follow us: <a href="https://x.com/inPlainEngHQ"><strong>X</strong></a> | <a href="https://www.linkedin.com/company/inplainenglish/"><strong>LinkedIn</strong></a> | <a href="https://www.youtube.com/@InPlainEnglish"><strong>YouTube</strong></a> | <a href="https://newsletter.plainenglish.io/"><strong>Newsletter</strong></a> | <a href="https://open.spotify.com/show/7qxylRWKhvZwMz2WuEoua0"><strong>Podcast</strong></a> | <a href="https://twitch.tv/inplainenglish"><strong>Twitch</strong></a></li><li><a href="https://differ.blog/"><strong>Start your own free AI-powered blog on Differ</strong></a> 🚀</li><li><a href="https://discord.gg/in-plain-english-709094664682340443"><strong>Join our content creators community on Discord</strong></a> 🧑🏻‍💻</li><li>For more content, visit <a href="https://plainenglish.io/"><strong>plainenglish.io</strong></a> + <a href="https://stackademic.com/"><strong>stackademic.com</strong></a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=10b9362a14cb" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/fasterxml-jackson-api-a-comprehensive-overview-10b9362a14cb">FasterXML Jackson API: A Comprehensive Overview</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Modern Java Concurrency: Revisiting CompletableFuture for Asynchronous Programming]]></title>
            <link>https://blog.stackademic.com/modern-java-concurrency-revisiting-completablefuture-for-asynchronous-programming-aae19b8244c9?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/aae19b8244c9</guid>
            <category><![CDATA[concurrency]]></category>
            <category><![CDATA[multithreading]]></category>
            <category><![CDATA[completablefuture]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Mon, 28 Jul 2025 04:30:42 GMT</pubDate>
            <atom:updated>2025-08-04T06:13:36.807Z</atom:updated>
            <content:encoded><![CDATA[<p>In the <a href="https://medium.com/@mridul.choudhary7/modern-java-concurrency-foundations-from-threads-to-the-executor-framework-86859e514125">previous article</a>, we explored the Executor Framework, Java’s foundational approach to task-based concurrency. <br>While the Executor Framework represented a significant improvement over direct thread management, we concluded by noting several limitations:</p><ol><li><strong>Limited Composability</strong>: Tasks can’t easily depend on each other</li><li><strong>Blocking Operations</strong>: Future.get() blocks the calling thread</li><li><strong>Error Handling</strong>: Exceptions are only thrown when retrieving results</li><li><strong>Manual Coordination</strong>: Combining multiple futures requires custom code</li></ol><p>Java 8 introduced the CompletableFuture class to address these limitations, representing a paradigm shift toward asynchronous, composable concurrency.<br>This article explores how CompletableFuture provides a more functional and flexible approach to managing asynchronous operations.</p><blockquote>CompletableFuture Fundamentals</blockquote><p><strong>The Relationship with Future &amp; CompletionStage:<br></strong>CompletableFuture implements both the Future interface and the CompletionStage interface, giving it a dual nature.</p><p>As a Future, it represents the result of an asynchronous computation. <br>As a CompletionStage, it represents a stage of a possibly asynchronous computation that can be composed with other stages.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F5LvAIRy5VngzkOzUjKU7A.png" /></figure><p><strong>Creating CompletableFuture Instances:<br></strong>There are several ways to create a CompletableFuture:</p><ol><li><strong>Empty future that can be completed later</strong>:</li></ol><pre>CompletableFuture&lt;String&gt; future = new CompletableFuture&lt;&gt;();<br>// Later:<br>future.complete(&quot;Result&quot;);</pre><p>2. <strong>Pre-completed future with a value</strong>:</p><pre>CompletableFuture&lt;String&gt; future = CompletableFuture.completedFuture(&quot;Instant result&quot;);</pre><p>3. <strong>Asynchronously with a Supplier</strong>:</p><pre>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; {<br>    // Perform computation<br>    return &quot;Computed result&quot;;<br>});</pre><p>4. <strong>Asynchronously with a Runnable (no result)</strong>:</p><pre>CompletableFuture&lt;Void&gt; future = CompletableFuture.runAsync(() -&gt; {<br>    // Perform operation<br>    System.out.println(&quot;Operation complete&quot;);<br>});</pre><p><strong>The Completion Stage Concept:</strong></p><p>The CompletionStage interface is the heart of what makes CompletableFuture powerful. It models a stage in an asynchronous computation that can be composed with other stages.</p><p>Think of it like a pipeline, where each stage represents an operation that will be performed when the previous stage completes:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rNozCwaRtFfJi_bOxT1_6g.png" /></figure><blockquote>Asynchronous Execution</blockquote><p><strong>Using supplyAsync() and runAsync():</strong></p><p>The supplyAsync() and runAsync() methods are the primary ways to start asynchronous computations:</p><pre>// For operations that return values<br>CompletableFuture&lt;User&gt; userFuture = CompletableFuture.supplyAsync(() -&gt; {<br>    // Simulate database call<br>    try {<br>        Thread.sleep(1000);<br>    } catch (InterruptedException e) {<br>        Thread.currentThread().interrupt();<br>    }<br>    return new User(&quot;user1&quot;, &quot;John Doe&quot;);<br>});<br><br>// For operations that don&#39;t return values<br>CompletableFuture&lt;Void&gt; notificationFuture = CompletableFuture.runAsync(() -&gt; {<br>    // Simulate sending notification<br>    System.out.println(&quot;Notification sent&quot;);<br>});</pre><p><strong>Working with Custom Executors:</strong></p><p>By default, CompletableFuture uses the common ForkJoinPool for asynchronous execution, but you can specify a custom Executor:</p><pre>ExecutorService customExecutor = Executors.newFixedThreadPool(10);<br><br>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; {<br>    return &quot;Custom executor result&quot;;<br>}, customExecutor);</pre><p>This allows you to control the thread pool characteristics based on the type of operations:</p><pre>// For CPU-intensive tasks<br>int processors = Runtime.getRuntime().availableProcessors();<br>ExecutorService computeExecutor = Executors.newWorkStealingPool(processors);<br><br>// For I/O-bound tasks<br>ExecutorService ioExecutor = Executors.newFixedThreadPool(50);<br><br>CompletableFuture&lt;Data&gt; cpuIntensiveTask = CompletableFuture.supplyAsync(<br>    () -&gt; performComputation(), computeExecutor);<br><br>CompletableFuture&lt;String&gt; ioTask = CompletableFuture.supplyAsync(<br>    () -&gt; fetchDataFromNetwork(), ioExecutor);</pre><p><strong>Non-blocking Operations:</strong></p><p>Unlike Future.get(), which blocks until the result is available, CompletableFuture provides non-blocking alternatives:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Dp3QF2EOlVp6ybYV1xb9dg.png" /></figure><pre>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; {<br>    // Long computation<br>    try {<br>        Thread.sleep(1000);<br>    } catch (InterruptedException e) {<br>        Thread.currentThread().interrupt();<br>    }<br>    return &quot;Result after 1 second&quot;;<br>});<br><br>// Instead of blocking with future.get():<br>future.thenAccept(result -&gt; System.out.println(&quot;Got result: &quot; + result));<br><br>// Continue with other operations immediately<br>System.out.println(&quot;Continuing without waiting&quot;);</pre><blockquote>Composition Patterns</blockquote><p>The real power of CompletableFuture lies in its composition abilities, which lets you build complex asynchronous workflows.</p><p><strong>Sequential Operations:</strong></p><p>You can chain operations that depend on the result of the previous operation:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*B0JDMTat7fEJmCY3OpU8YA.png" /></figure><pre>CompletableFuture&lt;User&gt; userFuture = getUserFromDatabase(userId);<br><br>// Transform the result<br>CompletableFuture&lt;UserDTO&gt; userDtoFuture = userFuture.thenApply(user -&gt;<br>    convertToDTO(user));<br><br>// Consume the result without returning a new value<br>userDtoFuture.thenAccept(userDto -&gt;<br>    System.out.println(&quot;User processed: &quot; + userDto.getName()));<br><br>// Run an action after completion, ignoring the result<br>userDtoFuture.thenRun(() -&gt;<br>    System.out.println(&quot;User processing workflow complete&quot;));</pre><p>Here’s a table comparing the key transformation methods:</p><pre>| Method      | Input                    | Output                   | Use Case                   |<br>|-------------|--------------------------|--------------------------|----------------------------|<br>| thenApply   | Result of previous stage | New CompletableFuture    | Transform a value          |<br>|             |                          | with transformed result  |                            |<br>| thenAccept  | Result of previous stage | CompletableFuture&lt;Void&gt;  | Consume a value, no return |<br>| thenRun     | None                     | CompletableFuture&lt;Void&gt;  | Action after completion    |</pre><p><strong>Conditional Composition:</strong></p><p>For more complex workflows where one asynchronous operation depends on the result of another, thenCompose provides a way to flatten nested CompletableFuture instances:</p><pre>CompletableFuture&lt;User&gt; userFuture = getUserFromDatabase(userId);<br><br>// Without thenCompose (creates CompletableFuture&lt;CompletableFuture&lt;Orders&gt;&gt;)<br>CompletableFuture&lt;CompletableFuture&lt;Orders&gt;&gt; nestedFuture = <br>    userFuture.thenApply(user -&gt; getOrdersForUser(user));<br><br>// With thenCompose (flattens to CompletableFuture&lt;Orders&gt;)<br>CompletableFuture&lt;Orders&gt; ordersFuture = <br>    userFuture.thenCompose(user -&gt; getOrdersForUser(user));</pre><p>The thenCompose method is similar to the flatMap operation in functional programming—it&#39;s designed for when your function returns another CompletableFuture.</p><p><strong>Parallel Execution:</strong></p><p>When you need to process multiple independent operations and then combine their results, CompletableFuture offers several methods:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ySdmKUfJng5LwchMY2bj0A.png" /></figure><pre>CompletableFuture&lt;UserProfile&gt; profileFuture = getUserProfile(userId);<br>CompletableFuture&lt;List&lt;Order&gt;&gt; ordersFuture = getUserOrders(userId);<br>CompletableFuture&lt;List&lt;Product&gt;&gt; recommendationsFuture = getRecommendedProducts(userId);<br><br>// Combine two futures<br>CompletableFuture&lt;UserDashboard&gt; dashboardFuture = profileFuture.thenCombine(<br>    ordersFuture,<br>    (profile, orders) -&gt; createDashboard(profile, orders)<br>);<br><br>// Wait for all futures to complete<br>CompletableFuture&lt;Void&gt; allFutures = CompletableFuture.allOf(<br>    profileFuture, ordersFuture, recommendationsFuture<br>);<br><br>// Process after all complete<br>CompletableFuture&lt;UserDashboard&gt; enhancedDashboardFuture = allFutures.thenApply(v -&gt; {<br>    // All futures are now complete<br>    UserProfile profile = profileFuture.join();  // Non-blocking equivalent of get()<br>    List&lt;Order&gt; orders = ordersFuture.join();<br>    List&lt;Product&gt; recommendations = recommendationsFuture.join();<br>    <br>    return createEnhancedDashboard(profile, orders, recommendations);<br>});<br><br>// Wait for any to complete<br>CompletableFuture&lt;Object&gt; anyFuture = CompletableFuture.anyOf(<br>    profileFuture, ordersFuture, recommendationsFuture<br>);</pre><p>Key parallel operations include:</p><pre>| Method      | Purpose                                    |<br>|-------------|--------------------------------------------|<br>| thenCombine | Combine results of two independent futures |<br>| allOf       | Wait for all futures to complete           |<br>| anyOf       | Wait for any future to complete            |</pre><blockquote>Error Handling</blockquote><p>One of the major improvements in CompletableFuture over Future is its comprehensive error handling.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O2Al49O5zcY5yGrob3FTEg.png" /></figure><p><strong>The exceptionally method:</strong></p><p>The exceptionally method allows you to provide a recovery value when an exception occurs:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YydSpBKSA1uWlJgNoaUs-A.png" /></figure><pre>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; {<br>    if (Math.random() &gt; 0.5) {<br>        throw new RuntimeException(&quot;Something went wrong&quot;);<br>    }<br>    return &quot;Success&quot;;<br>}).exceptionally(ex -&gt; {<br>    System.err.println(&quot;Error: &quot; + ex.getMessage());<br>    return &quot;Default value after error&quot;;<br>});</pre><p><strong>The handle method:</strong></p><p>The handle method is more versatile, allowing you to process both the success and failure cases:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*D1MtqgC2Seab24V2M2CISQ.png" /></figure><pre>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; {<br>    // Risky operation<br>    if (Math.random() &gt; 0.5) {<br>        throw new RuntimeException(&quot;Operation failed&quot;);<br>    }<br>    return &quot;Operation succeeded&quot;;<br>}).handle((result, ex) -&gt; {<br>    if (ex != null) {<br>        return &quot;Recovered from error: &quot; + ex.getMessage();<br>    } else {<br>        return &quot;Got result: &quot; + result;<br>    }<br>});</pre><p><strong>The whenComplete method for Side Effects:</strong></p><p>When you want to perform side effects without changing the result:</p><pre>CompletableFuture&lt;String&gt; future = CompletableFuture<br>    .supplyAsync(() -&gt; &quot;Result&quot;)<br>    .whenComplete((result, ex) -&gt; {<br>        if (ex != null) {<br>            System.err.println(&quot;Operation failed: &quot; + ex.getMessage());<br>        } else {<br>            System.out.println(&quot;Operation completed with: &quot; + result);<br>        }<br>    });</pre><p><strong>Propagation Patterns:</strong></p><p>Exception handling in chained CompletableFutures follows specific rules:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/509/1*Fod1Gf3r0azofc3FfEwXhg.png" /></figure><pre>CompletableFuture&lt;String&gt; future = CompletableFuture<br>    .supplyAsync(() -&gt; {<br>        // First stage fails<br>        throw new RuntimeException(&quot;First stage failed&quot;);<br>    })<br>    .thenApply(s -&gt; {<br>        // This will be skipped due to failure in the previous stage<br>        return s.toUpperCase();<br>    })<br>    .exceptionally(ex -&gt; {<br>        // This will handle the exception<br>        return &quot;Recovered&quot;;<br>    })<br>    .thenApply(s -&gt; {<br>        // This will receive the recovered value<br>        return s + &quot; and transformed&quot;;<br>    });</pre><blockquote><strong>Timeout Management</strong></blockquote><p>Managing timeouts is crucial for resilient applications. CompletableFuture provides methods to handle timeouts gracefully:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aUhpNtNdsfwf6mmUX4uzyg.png" /></figure><p><strong>Using orTimeout method:</strong></p><p>Java 9 introduced the orTimeout method, which completes the future exceptionally if it doesn&#39;t complete within the specified time:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yOOfXlbXGZIFe7WI2NVKpA.png" /></figure><pre>CompletableFuture&lt;String&gt; future = CompletableFuture<br>    .supplyAsync(() -&gt; {<br>        try {<br>            Thread.sleep(2000); // Simulate long operation<br>            return &quot;Result&quot;;<br>        } catch (InterruptedException e) {<br>            Thread.currentThread().interrupt();<br>            throw new RuntimeException(e);<br>        }<br>    })<br>    .orTimeout(1, TimeUnit.SECONDS) // Complete with TimeoutException if not done in 1 second<br>    .exceptionally(ex -&gt; {<br>        if (ex instanceof TimeoutException) {<br>            return &quot;Timeout occurred&quot;;<br>        }<br>        return &quot;Other error: &quot; + ex.getMessage();<br>    });</pre><p><strong>Using completeOnTimeout method:</strong></p><p>For providing default values on timeout:</p><pre>CompletableFuture&lt;String&gt; future = CompletableFuture<br>    .supplyAsync(() -&gt; {<br>        try {<br>            Thread.sleep(2000); // Simulate long operation<br>            return &quot;Result&quot;;<br>        } catch (InterruptedException e) {<br>            Thread.currentThread().interrupt();<br>            throw new RuntimeException(e);<br>        }<br>    })<br>    .completeOnTimeout(&quot;Default on timeout&quot;, 1, TimeUnit.SECONDS);</pre><p><strong>Cancellation Strategies:</strong></p><p>CompletableFuture can be cancelled, which will complete it exceptionally with a CancellationException:</p><pre>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; {<br>    try {<br>        Thread.sleep(10000); // Long operation<br>        return &quot;Result&quot;;<br>    } catch (InterruptedException e) {<br>        Thread.currentThread().interrupt();<br>        throw new RuntimeException(e);<br>    }<br>});<br><br>// Elsewhere in the application:<br>boolean mayInterruptIfRunning = true;<br>future.cancel(mayInterruptIfRunning);<br><br>// Check if cancelled<br>if (future.isCancelled()) {<br>    System.out.println(&quot;Future was cancelled&quot;);<br>}</pre><blockquote>Best Practices</blockquote><p><strong>Thread Pool Configuration for CompletableFuture:<br></strong>When working with CompletableFuture, careful thread pool configuration is crucial:</p><pre>// BAD: Using a single thread pool for everything<br>ExecutorService singlePool = Executors.newFixedThreadPool(10);<br><br>// BETTER: Separate pools for different types of operations<br>ExecutorService cpuBoundTasks = Executors.newFixedThreadPool(<br>    Runtime.getRuntime().availableProcessors());<br>    <br>ExecutorService ioBoundTasks = Executors.newFixedThreadPool(50);<br><br>// Use appropriate pool for the task type<br>CompletableFuture&lt;Data&gt; dataFuture = CompletableFuture.supplyAsync(<br>    () -&gt; readDatabaseData(), ioBoundTasks);<br>    <br>CompletableFuture&lt;ProcessedData&gt; processedFuture = dataFuture.thenApplyAsync(<br>    data -&gt; processData(data), cpuBoundTasks);</pre><blockquote>Common Pitfalls and Their Solutions</blockquote><ol><li><strong>Forgetting to handle exceptions</strong>:</li></ol><pre>// BAD: No exception handling<br>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; riskyOperation());<br><br>// GOOD: Handle exceptions<br>CompletableFuture&lt;String&gt; future = CompletableFuture.supplyAsync(() -&gt; riskyOperation())<br>    .exceptionally(ex -&gt; handleException(ex));</pre><p>2. <strong>Blocking inside async operations</strong>:</p><pre>// BAD: Blocking inside a CompletableFuture<br>CompletableFuture.supplyAsync(() -&gt; {<br>    try {<br>        return otherFuture.get(); // Blocking!<br>    } catch (Exception e) {<br>        throw new RuntimeException(e);<br>    }<br>});<br><br>// GOOD: Compose futures instead<br>CompletableFuture.supplyAsync(() -&gt; prepareData())<br>    .thenCompose(data -&gt; otherOperation(data));</pre><p>3. <strong>Ignoring returned futures</strong>:</p><pre>// BAD: Ignoring the returned future<br>void processAsync() {<br>    CompletableFuture.supplyAsync(() -&gt; process()); // Lost future!<br>}<br><br>// GOOD: Return or handle the future<br>CompletableFuture&lt;Result&gt; processAsync() {<br>    return CompletableFuture.supplyAsync(() -&gt; process());<br>}</pre><blockquote>Real-world Patterns</blockquote><p><strong>Service Orchestration:<br></strong>CompletableFuture excels at orchestrating calls to multiple services:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uRzQKXfMn5fbIsRroRKb9g.png" /></figure><pre>public class UserDashboardService {<br>    private final UserService userService;<br>    private final OrderService orderService;<br>    private final ProductService productService;<br>    private final ExecutorService executor;<br>    <br>    // Constructor and other methods omitted<br>    <br>    public CompletableFuture&lt;Dashboard&gt; getUserDashboard(String userId) {<br>        CompletableFuture&lt;User&gt; userFuture = CompletableFuture.supplyAsync(<br>            () -&gt; userService.getUser(userId), executor);<br>            <br>        CompletableFuture&lt;List&lt;Order&gt;&gt; ordersFuture = CompletableFuture.supplyAsync(<br>            () -&gt; orderService.getRecentOrders(userId), executor);<br>            <br>        CompletableFuture&lt;List&lt;Product&gt;&gt; recommendationsFuture = CompletableFuture.supplyAsync(<br>            () -&gt; productService.getRecommendations(userId), executor);<br>            <br>        return CompletableFuture.allOf(userFuture, ordersFuture, recommendationsFuture)<br>            .thenApply(v -&gt; {<br>                User user = userFuture.join();<br>                List&lt;Order&gt; orders = ordersFuture.join();<br>                List&lt;Product&gt; recommendations = recommendationsFuture.join();<br>                <br>                return new Dashboard(user, orders, recommendations);<br>            });<br>    }<br>}</pre><h4>Conclusion:</h4><p>CompletableFuture represents a significant evolution in Java&#39;s concurrency model, addressing the limitations of the Future interface with a rich API for composing asynchronous operations.</p><p>Its functional approach to transformations, error handling, and composition allows for more readable and maintainable concurrent code.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JsIgS5gYrE0WyMwo78Ktdw.png" /></figure><p>Key takeaways:</p><ul><li>CompletableFuture enables non-blocking, composable asynchronous operations</li><li>Its functional approach makes complex asynchronous workflows more readable</li><li>Comprehensive error handling improves reliability</li><li>Proper thread pool configuration is essential for optimal performance</li><li>It provides a bridge to more advanced concurrency models</li></ul><p>In the next article, we’ll explore Java’s virtual threads, which further simplify concurrent programming by making blocking operations efficient, allowing us to write code that’s both highly concurrent and easy to understand.</p><h4>References:</h4><ol><li>Java SE Documentation — java.util.concurrent.CompletableFuture</li><li>Java Concurrency in Practice by Brian Goetz</li></ol><h3>Thank you for being a part of the community</h3><p><em>Before you go:</em></p><ul><li>Be sure to <strong>clap</strong> and <strong>follow</strong> the writer ️👏️<strong>️</strong></li><li>Follow us: <a href="https://x.com/inPlainEngHQ"><strong>X</strong></a> | <a href="https://www.linkedin.com/company/inplainenglish/"><strong>LinkedIn</strong></a> | <a href="https://www.youtube.com/@InPlainEnglish"><strong>YouTube</strong></a> | <a href="https://newsletter.plainenglish.io/"><strong>Newsletter</strong></a> | <a href="https://open.spotify.com/show/7qxylRWKhvZwMz2WuEoua0"><strong>Podcast</strong></a> | <a href="https://twitch.tv/inplainenglish"><strong>Twitch</strong></a></li><li><a href="https://differ.blog/"><strong>Start your own free AI-powered blog on Differ</strong></a> 🚀</li><li><a href="https://discord.gg/in-plain-english-709094664682340443"><strong>Join our content creators community on Discord</strong></a> 🧑🏻‍💻</li><li>For more content, visit <a href="https://plainenglish.io/"><strong>plainenglish.io</strong></a> + <a href="https://stackademic.com/"><strong>stackademic.com</strong></a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aae19b8244c9" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/modern-java-concurrency-revisiting-completablefuture-for-asynchronous-programming-aae19b8244c9">Modern Java Concurrency: Revisiting CompletableFuture for Asynchronous Programming</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Modern Java Concurrency Foundations: From Threads to the Executor Framework]]></title>
            <link>https://blog.stackademic.com/modern-java-concurrency-foundations-from-threads-to-the-executor-framework-86859e514125?source=rss-77580d871ef9------2</link>
            <guid isPermaLink="false">https://medium.com/p/86859e514125</guid>
            <category><![CDATA[multithreading]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[concurrency]]></category>
            <dc:creator><![CDATA[Mridul Choudhary]]></dc:creator>
            <pubDate>Sat, 26 Jul 2025 08:03:33 GMT</pubDate>
            <atom:updated>2025-07-30T05:35:39.794Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong>Introduction</strong></blockquote><p>Concurrent programming has been a part of Java since its inception, but the approach to concurrency has evolved significantly over the years.</p><p>For developers coming from a background of directly managing Thread objects, the transition to modern concurrency APIs can represent a paradigm shift in how we think about parallel execution.</p><p>This article, the first in the series on modern Java concurrency, explores the foundation of Java’s current concurrency model: the Executor Framework.</p><blockquote><strong>The Evolution of Concurrency in Java</strong></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Y4I6DrUPuh1XJMzbaRgJKg.png" /></figure><blockquote>The Challenges of Traditional Threading</blockquote><p>In early Java applications, developers worked directly with Thread objects:</p><pre>// Traditional approach using Thread directly<br>Thread thread = new Thread(new Runnable() {<br>    @Override<br>    public void run() {<br>        System.out.println(&quot;Running in a separate thread&quot;);<br>    }<br>});<br>thread.start();</pre><p>This approach presented several challenges:</p><ol><li><strong>Resource Overhead</strong>: Each Thread object maps to an OS thread, consuming system resources</li><li><strong>Manual Management</strong>: Developers had to manually create, start, and coordinate threads</li><li><strong>Limited Control</strong>: No built-in mechanisms for thread pooling or work queuing</li><li><strong>Error-Prone</strong>: Easy to create race conditions, deadlocks, and resource leaks</li></ol><p>Let’s look at a more complex example highlighting these challenges:</p><pre>// Processing a collection of items with direct thread management<br>List&lt;String&gt; items = Arrays.asList(&quot;Item1&quot;, &quot;Item2&quot;, &quot;Item3&quot;, &quot;Item4&quot;, &quot;Item5&quot;);<br>List&lt;Thread&gt; threads = new ArrayList&lt;&gt;();<br><br>for (String item : items) {<br>    Thread thread = new Thread(() -&gt; processItem(item));<br>    threads.add(thread);<br>    thread.start();<br>}<br><br>// Wait for all threads to complete<br>for (Thread thread : threads) {<br>    try {<br>        thread.join();<br>    } catch (InterruptedException e) {<br>        Thread.currentThread().interrupt();<br>    }<br>}<br><br>private static void processItem(String item) {<br>    // Simulate processing<br>    try {<br>        System.out.println(&quot;Processing: &quot; + item);<br>        Thread.sleep(100);<br>        System.out.println(&quot;Completed: &quot; + item);<br>    } catch (InterruptedException e) {<br>        Thread.currentThread().interrupt();<br>    }<br>}</pre><p>This approach has several issues:</p><ul><li>It creates a new thread for each item, regardless of system capabilities</li><li>There’s no control over maximum concurrency</li><li>Resource usage is inefficient, especially with many items</li><li>Error handling is scattered and repetitive</li></ul><blockquote>The Shift to Task-Based Concurrency</blockquote><p>Java 5 (released in 2004) introduced the Executor Framework, representing a fundamental shift from thread-based to task-based concurrency.</p><p>This shift separated the task submission logic from the execution mechanics:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UED66UWzmnyjJBTdDkQ0fA.png" /></figure><pre>// Using Executor Framework<br>ExecutorService executor = Executors.newFixedThreadPool(3);<br><br>for (String item : items) {<br>    executor.submit(() -&gt; processItem(item));<br>}<br><br>executor.shutdown();<br>try {<br>    if (!executor.awaitTermination(800, TimeUnit.MILLISECONDS)) {<br>        executor.shutdownNow();<br>    } <br>} catch (InterruptedException e) {<br>    executor.shutdownNow();<br>    Thread.currentThread().interrupt();<br>}</pre><p>Key advantages of this approach:</p><ul><li>Thread reuse through pooling</li><li>Controlled concurrency (3 threads handling all tasks)</li><li>Separation of task submission from execution details</li><li>Centralized lifecycle management</li></ul><blockquote>Java’s Concurrency Evolution Timeline</blockquote><p>The evolution of Java concurrency capabilities has been continuous:</p><ul><li><strong>Java 1.0 (1996)</strong>: Basic Thread and Runnable</li><li><strong>Java 5 (2004)</strong>: Executor Framework, Future, BlockingQueue, Atomic variables</li><li><strong>Java 7 (2011)</strong>: Fork/Join framework, RecursiveTask, ThreadLocalRandom</li><li><strong>Java 8 (2014)</strong>: CompletableFuture, parallel streams, lambda integration</li><li><strong>Java 9 (2017)</strong>: Flow API (Reactive Streams), improvements to CompletableFuture</li><li><strong>Java 19–21 (2022–2023)</strong>: Virtual Threads (Project Loom), Structured Concurrency</li></ul><p>This evolution represents a progression from manual thread management to increasingly higher-level abstractions that make concurrent programming more accessible and less error prone.</p><blockquote>Understanding the Executor Framework Architecture</blockquote><p>At the heart of modern Java concurrency is the Executor Framework. A set of interfaces and classes that abstract the details of thread creation and management.</p><p>Let’s explore its core components:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xjL2fNVlP0Y0MznpiX1H-Q.png" /></figure><blockquote>Core Interfaces</blockquote><p><strong>Executor</strong>: The simplest interface, defining a single method:</p><pre>void execute(Runnable command);</pre><p>This represents the basic concept: execute a task.</p><p><strong>ExecutorService</strong>: Extends Executor with additional lifecycle and task submission methods:</p><pre>&lt;T&gt; Future&lt;T&gt; submit(Callable&lt;T&gt; task);<br>&lt;T&gt; Future&lt;T&gt; submit(Runnable task, T result);<br>Future&lt;?&gt; submit(Runnable task);<br>void shutdown();<br>List&lt;Runnable&gt; shutdownNow();<br>boolean isShutdown();<br>boolean isTerminated();<br>boolean awaitTermination(long timeout, TimeUnit unit);<br>// ...and more</pre><p><strong>ScheduledExecutorService</strong>: Extends ExecutorService with scheduling capabilities:</p><pre>ScheduledFuture&lt;?&gt; schedule(Runnable command, long delay, TimeUnit unit);<br>&lt;V&gt; ScheduledFuture&lt;V&gt; schedule(Callable&lt;V&gt; callable, long delay, TimeUnit unit);<br>ScheduledFuture&lt;?&gt; scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit);<br>ScheduledFuture&lt;?&gt; scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit);</pre><blockquote>The Executors Factory Class</blockquote><p>Most applications interact with the Executor Framework through the Executors factory class, which provides convenient methods for creating common executor service implementations:</p><pre>// Creating different types of executor services<br>ExecutorService singleThreadExecutor = Executors.newSingleThreadExecutor();<br>ExecutorService fixedThreadPool = Executors.newFixedThreadPool(4);<br>ExecutorService cachedThreadPool = Executors.newCachedThreadPool();<br>ScheduledExecutorService scheduledThreadPool = Executors.newScheduledThreadPool(2);</pre><blockquote>ThreadPoolExecutor</blockquote><p>Behind most executor services is the ThreadPoolExecutor class, which provides the core implementation of a thread pool.</p><p>While the factory methods are convenient, understanding ThreadPoolExecutor directly gives you more control:</p><pre>ThreadPoolExecutor executor = new ThreadPoolExecutor(<br>    2,                             // Core pool size<br>    5,                             // Maximum pool size<br>    60, TimeUnit.SECONDS,          // Keep-alive time for idle threads<br>    new ArrayBlockingQueue&lt;&gt;(100), // Work queue<br>    new CustomThreadFactory(),     // Thread factory<br>    new CustomRejectedExecutionHandler() // Rejection policy<br>);</pre><p>This configuration gives precise control over:</p><ul><li>Minimum number of threads to keep alive (core pool size)</li><li>Maximum number of threads allowed (maximum pool size)</li><li>How long excess idle threads wait before terminating</li><li>How tasks are queued when all threads are busy</li><li>How threads are created (thread factory)</li><li>What happens when the executor is saturated (rejection policy)</li></ul><blockquote>Thread Pool Types and Implementation Details</blockquote><p>The Executor Framework provides several thread pool implementations, each designed for specific use cases.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*q4_g_vH1I_UodFrS4yt_6Q.png" /></figure><p><strong>Fixed Thread Pool:</strong></p><p>A fixed thread pool maintains a fixed number of worker threads regardless of the workload. This provides a predictable level of concurrency.</p><pre>ExecutorService fixedPool = Executors.newFixedThreadPool(4);</pre><p>Implementation details:</p><ul><li>Core pool size equals maximum pool size</li><li>Threads remain alive indefinitely</li><li>Uses an unbounded LinkedBlockingQueue</li><li>Suitable for applications that need controlled parallelism</li></ul><p><strong>Use case</strong>: CPU-bound tasks where you want to limit concurrency to the number of available processors.</p><pre>int processors = Runtime.getRuntime().availableProcessors();<br>ExecutorService computePool = Executors.newFixedThreadPool(processors);</pre><p><strong>Cached Thread Pool:</strong></p><p>A cached thread pool dynamically adjusts its size based on workload:</p><pre>ExecutorService cachedPool = Executors.newCachedThreadPool();</pre><p>Implementation details:</p><ul><li>Core pool size is 0</li><li>Unbounded maximum pool size</li><li>60-second keep-alive time for idle threads</li><li>Uses SynchronousQueue (no actual queuing)</li><li>Creates new threads as needed, reuses idle ones</li></ul><p><strong>Use case</strong>: Many short-lived tasks, especially in I/O-bound applications.</p><p><strong>Single-Threaded Executor:</strong></p><p>Executes tasks sequentially with a single worker thread:</p><pre>ExecutorService singleThreadExecutor = Executors.newSingleThreadExecutor();</pre><p>Implementation details:</p><ul><li>One worker thread</li><li>Uses an unbounded LinkedBlockingQueue</li><li>Tasks execute in submission order (FIFO)</li></ul><p><strong>Use case</strong>: When tasks must execute sequentially, or for event handling that requires thread safety.</p><p><strong>Scheduled Thread Pool:</strong></p><p>Supports delayed and periodic task execution:</p><pre>ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(2);<br>// Run once after a delay<br>scheduler.schedule(<br>    () -&gt; System.out.println(&quot;Delayed task&quot;), <br>    10, TimeUnit.SECONDS<br>);<br>// Run repeatedly at fixed rate<br>scheduler.scheduleAtFixedRate(<br>    () -&gt; System.out.println(&quot;Periodic task&quot;), <br>    5, 10, TimeUnit.SECONDS<br>);<br>// Run repeatedly with fixed delay between completions<br>scheduler.scheduleWithFixedDelay(<br>    () -&gt; System.out.println(&quot;Repeated task&quot;),<br>    0, 1, TimeUnit.MINUTES<br>);</pre><p>Implementation details:</p><ul><li>Based on DelayedWorkQueue (priority queue)</li><li>Supports both one-time and recurring tasks</li><li>Time-based task scheduling</li></ul><p><strong>Use case</strong>: Maintenance operations, polling activities, or any scenario requiring time-based execution.</p><p><strong>Work-Stealing Pool:</strong></p><p>Introduced with the Fork/Join framework in Java 7 and made more accessible in Java 8:</p><pre>ExecutorService workStealingPool = Executors.newWorkStealingPool(4);</pre><p>Implementation details:</p><ul><li>Based on ForkJoinPool</li><li>Implements work-stealing algorithm</li><li>Worker threads that become idle attempt to “steal” work from other threads’ queues</li><li>Particularly effective for recursive divide-and-conquer tasks</li></ul><p><strong>Use case</strong>: Computationally intensive tasks that can be broken down into smaller subtasks.</p><p><strong>Custom Thread Pools:</strong></p><p>For specialized requirements, you can create custom thread pools:</p><pre>ThreadPoolExecutor customPool = new ThreadPoolExecutor(<br>    2,                                   // Core threads<br>    10,                                  // Max threads<br>    5, TimeUnit.MINUTES,                 // Keep alive time<br>    new ArrayBlockingQueue&lt;&gt;(1000),      // Work queue<br>    new ThreadPoolExecutor.CallerRunsPolicy() // Rejection policy<br>);</pre><p>This allows fine-tuning for specific application needs.</p><blockquote>Task Submission and Result Handling</blockquote><p>The Executor Framework supports different types of tasks and provides mechanisms for handling their results.</p><p><strong>Runnable vs Callable Tasks:</strong></p><p>Two primary task types are supported:</p><p><strong>Runnable</strong>: For tasks that don’t return results</p><pre>executor.execute(() -&gt; System.out.println(&quot;Simple task&quot;));</pre><p><strong>Callable: </strong>For tasks that return results or throw checked exceptions</p><pre>Future&lt;Integer&gt; future = executor.submit(() -&gt; {<br>    // Compute and return a result<br>    return computeValue();<br>});</pre><p><strong>Future Interface and Result Handling:</strong></p><p>The Future interface represents the result of an asynchronous computation:</p><pre>Future&lt;String&gt; future = executor.submit(() -&gt; {<br>    Thread.sleep(1000);<br>    return &quot;Task completed&quot;;<br>});<br><br>// Check if completed without blocking<br>if (future.isDone()) {<br>    // Handle completion<br>}<br><br>// Wait for completion with timeout<br>try {<br>    String result = future.get(2, TimeUnit.SECONDS);<br>    System.out.println(result);<br>} catch (TimeoutException e) {<br>    future.cancel(true); // Attempt to cancel if it takes too long<br>} catch (InterruptedException | ExecutionException e) {<br>    // Handle exceptions<br>}<br><br>// Check if cancelled<br>if (future.isCancelled()) {<br>    // Handle cancellation<br>}</pre><p>Key methods:</p><ul><li>get(): Blocks until the task completes</li><li>get(long, TimeUnit): Blocks with timeout</li><li>isDone(): Checks if completed</li><li>cancel(boolean): Attempts to cancel</li><li>isCancelled(): Checks if cancelled</li></ul><p><strong>Bulk Submission Operations:</strong></p><pre>List&lt;Callable&lt;String&gt;&gt; tasks = Arrays.asList(<br>    () -&gt; &quot;Task 1 Result&quot;,<br>    () -&gt; &quot;Task 2 Result&quot;,<br>    () -&gt; &quot;Task 3 Result&quot;<br>);<br><br>// Execute all tasks and get all results<br>List&lt;Future&lt;String&gt;&gt; futures = executor.invokeAll(tasks);<br>for (Future&lt;String&gt; future : futures) {<br>    System.out.println(future.get());<br>}<br><br>// Execute tasks and get the result of the first to complete<br>String fastestResult = executor.invokeAny(tasks);</pre><blockquote>Thread Pool Configuration Best Practices</blockquote><p>Properly configuring thread pools is crucial for application performance and stability.</p><p><strong>Sizing Thread Pools:</strong></p><p>Thread pool sizing depends on the nature of the tasks:</p><p><strong>CPU-bound tasks</strong>: Limit threads to the number of available processors</p><pre>int processors = Runtime.getRuntime().availableProcessors();<br>ExecutorService pool = Executors.newFixedThreadPool(processors);</pre><p><strong>I/O-bound tasks</strong>: Use more threads, as they spend time waiting</p><pre>// Common formula for I/O-bound tasks<br>int threads = Runtime.getRuntime().availableProcessors() * (1 + waitTime/cpuTime);</pre><p><strong>Mixed workloads</strong>: Consider separate pools for different task types</p><pre>ExecutorService cpuBoundPool = Executors.newFixedThreadPool(processors);<br>ExecutorService ioBoundPool = Executors.newCachedThreadPool();</pre><p><strong>Thread Factory Customization:</strong></p><p>Thread factories let you customize thread creation:</p><pre>ThreadFactory factory = new ThreadFactory() {<br>    private final AtomicInteger count = new AtomicInteger(0);<br>    <br>    @Override<br>    public Thread newThread(Runnable r) {<br>        Thread thread = new Thread(r);<br>        thread.setName(&quot;CustomWorker-&quot; + count.incrementAndGet());<br>        thread.setDaemon(true);<br>        thread.setPriority(Thread.NORM_PRIORITY);<br>        return thread;<br>    }<br>};<br><br>ExecutorService executor = Executors.newFixedThreadPool(10, factory);</pre><p>Benefits of custom thread factories:</p><ul><li>Meaningful thread names for debugging</li><li>Standardized thread configuration</li><li>Thread grouping</li><li>Uncaught exception handling</li></ul><p><strong>Rejection Policies:</strong></p><p>When a bounded work queue fills up, new tasks must be rejected. ThreadPoolExecutor provides several policies:</p><p><strong>AbortPolicy</strong> (default): Throws RejectedExecutionException</p><pre>new ThreadPoolExecutor.AbortPolicy()</pre><p><strong>CallerRunsPolicy</strong>: Executes the task in the caller’s thread</p><pre>new ThreadPoolExecutor.CallerRunsPolicy()</pre><p><strong>DiscardPolicy</strong>: Silently discards the task</p><pre>new ThreadPoolExecutor.DiscardPolicy()</pre><p><strong>DiscardOldestPolicy</strong>: Discards the oldest queued task and tries again</p><pre>new ThreadPoolExecutor.DiscardOldestPolicy()</pre><p><strong>Custom policy</strong>: Implement your own logic</p><pre>new RejectedExecutionHandler() {<br>    @Override<br>    public void rejectedExecution(Runnable r, ThreadPoolExecutor executor) {<br>        // Custom handling, e.g., log and retry with backoff<br>        logRejection(r);<br>        try {<br>            Thread.sleep(100);<br>            executor.submit(r);<br>        } catch (InterruptedException e) {<br>            Thread.currentThread().interrupt();<br>        }<br>    }<br>}</pre><blockquote>Monitoring and Management</blockquote><p>ThreadPoolExecutor provides methods for monitoring:</p><pre>ThreadPoolExecutor executor = (ThreadPoolExecutor) Executors.newFixedThreadPool(10);<br><br>// Get current pool size<br>int poolSize = executor.getPoolSize();<br><br>// Get active thread count<br>int activeCount = executor.getActiveCount();<br><br>// Get task count<br>long taskCount = executor.getTaskCount();<br><br>// Get completed task count<br>long completedTaskCount = executor.getCompletedTaskCount();<br><br>// Get queue size<br>int queueSize = executor.getQueue().size();</pre><p>For more complex monitoring, consider implementing a custom extension:</p><pre>public class MonitoredThreadPoolExecutor extends ThreadPoolExecutor {<br>    <br>    private final AtomicLong totalTaskTime = new AtomicLong(0);<br>    private final AtomicInteger totalTasks = new AtomicInteger(0);<br>    <br>    // Constructor matching the parent<br>    public MonitoredThreadPoolExecutor(int corePoolSize, int maximumPoolSize, <br>                                      long keepAliveTime, TimeUnit unit,<br>                                      BlockingQueue&lt;Runnable&gt; workQueue) {<br>        super(corePoolSize, maximumPoolSize, keepAliveTime, unit, workQueue);<br>    }<br>    <br>    @Override<br>    protected void beforeExecute(Thread t, Runnable r) {<br>        super.beforeExecute(t, r);<br>        // Attach execution start time to the thread<br>        t.setName(t.getName() + &quot;:task-start:&quot; + System.currentTimeMillis());<br>    }<br>    <br>    @Override<br>    protected void afterExecute(Runnable r, Throwable t) {<br>        try {<br>            String threadName = Thread.currentThread().getName();<br>            long startTime = extractStartTime(threadName);<br>            long taskDuration = System.currentTimeMillis() - startTime;<br>            <br>            totalTaskTime.addAndGet(taskDuration);<br>            totalTasks.incrementAndGet();<br>            <br>            if (t != null) {<br>                logger.error(&quot;Task failed with exception&quot;, t);<br>            }<br>        } finally {<br>            super.afterExecute(r, t);<br>        }<br>    }<br>    <br>    private long extractStartTime(String threadName) {<br>        // Extract start time from the thread name<br>        int index = threadName.lastIndexOf(&quot;:task-start:&quot;);<br>        if (index &gt; 0) {<br>            return Long.parseLong(threadName.substring(index + 12));<br>        }<br>        return 0;<br>    }<br>    <br>    public double getAverageTaskTime() {<br>        int count = totalTasks.get();<br>        return count &gt; 0 ? (double) totalTaskTime.get() / count : 0;<br>    }<br>}</pre><blockquote>Lifecycle Management</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RExvuzFToE3B-fAJ9jDunA.png" /></figure><blockquote>Graceful Shutdown Techniques</blockquote><p>The most common approach is the shutdown() followed by awaitTermination() pattern:</p><pre>executor.shutdown();  // Reject new tasks, but complete queued ones<br>try {<br>    // Wait for existing tasks to complete<br>    if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {<br>        // Force shutdown if tasks take too long<br>        executor.shutdownNow();<br>        // Wait again, giving tasks a chance to respond to interruption<br>        if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {<br>            System.err.println(&quot;Executor did not terminate&quot;);<br>        }<br>    }<br>} catch (InterruptedException e) {<br>    // Re-interrupt the current thread<br>    executor.shutdownNow();<br>    Thread.currentThread().interrupt();<br>}</pre><p>This approach provides a balance between allowing tasks to complete and ensuring the application can shut down in a reasonable time.</p><blockquote>Handling Unfinished Tasks</blockquote><p>Different scenarios require different timeout strategies:</p><p><strong>Production shutdown</strong>: Longer timeouts to allow tasks to complete</p><pre>if (!executor.awaitTermination(5, TimeUnit.MINUTES)) {<br>    executor.shutdownNow();<br>}</pre><p><strong>Testing environments</strong>: Shorter timeouts</p><pre>if (!executor.awaitTermination(1, TimeUnit.SECONDS)) {<br>    executor.shutdownNow();<br>}</pre><p><strong>Critical shutdown</strong>: Force immediate termination</p><pre>executor.shutdownNow();</pre><blockquote>Resource Management Considerations</blockquote><p><strong>Thread lifecycle hooks</strong>: Use try-with-resources when possible.</p><pre>try (ExecutorService executor = Executors.newFixedThreadPool(10)) {<br>    // Use the executor<br>} // Automatically calls shutdown()</pre><p><strong>Thread pools in container environments</strong>: Be conscious of the container’s resource limits.</p><p><strong>Application shutdown hooks</strong>: Register shutdown hooks for emergency cleanup.</p><pre>Runtime.getRuntime().addShutdownHook(new Thread(() -&gt; {<br>    System.out.println(&quot;Shutdown hook: cleaning up thread pools&quot;);<br>    executor.shutdownNow();<br>}));</pre><blockquote>Practical Example</blockquote><p><strong>Thread Pool Monitoring Implementation:</strong></p><pre>public class ThreadPoolMonitor {<br>    private final ThreadPoolExecutor executor;<br>    private final ScheduledExecutorService scheduler;<br>    private ScheduledFuture&lt;?&gt; monitoringTask;<br>    <br>    public ThreadPoolMonitor(ThreadPoolExecutor executor) {<br>        this.executor = executor;<br>        this.scheduler = Executors.newSingleThreadScheduledExecutor();<br>    }<br>    <br>    public void startMonitoring(long period, TimeUnit unit) {<br>        monitoringTask = scheduler.scheduleAtFixedRate(<br>            this::reportMetrics,<br>            0,<br>            period,<br>            unit<br>        );<br>    }<br>    <br>    private void reportMetrics() {<br>        int activeCount = executor.getActiveCount();<br>        int poolSize = executor.getPoolSize();<br>        int corePoolSize = executor.getCorePoolSize();<br>        int maxPoolSize = executor.getMaximumPoolSize();<br>        long taskCount = executor.getTaskCount();<br>        long completedTaskCount = executor.getCompletedTaskCount();<br>        int queueSize = executor.getQueue().size();<br>        <br>        String metrics = String.format(<br>            &quot;[ThreadPool Metrics] Active: %d/%d, Pool: %d (Core: %d, Max: %d), &quot; +<br>            &quot;Tasks: %d (Completed: %d), Queue: %d&quot;,<br>            activeCount, poolSize, poolSize, corePoolSize, maxPoolSize,<br>            taskCount, completedTaskCount, queueSize<br>        );<br>        <br>        System.out.println(metrics);<br>        <br>        // Optional: log or send to monitoring system<br>    }<br>    <br>    public void stopMonitoring() {<br>        if (monitoringTask != null) {<br>            monitoringTask.cancel(false);<br>        }<br>        scheduler.shutdown();<br>    }<br>}<br><br></pre><blockquote>Usage example:</blockquote><pre>ThreadPoolExecutor executor = new ThreadPoolExecutor(<br>    5, 10, 60, TimeUnit.SECONDS, new LinkedBlockingQueue&lt;&gt;(100)<br>);<br><br>ThreadPoolMonitor monitor = new ThreadPoolMonitor(executor);<br>monitor.startMonitoring(5, TimeUnit.SECONDS);<br><br>// Later when done<br>monitor.stopMonitoring();<br>executor.shutdown();</pre><blockquote>Transitioning to Modern APIs</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*t01Q9nVLxnGow8DwGB35vA.png" /></figure><ol><li><strong>Limited Composability</strong>: Tasks can’t easily depend on each other</li><li><strong>Blocking Operations</strong>: Future.get() blocks the calling thread</li><li><strong>Error Handling</strong>: Exceptions are only thrown when retrieving results</li><li><strong>Manual Coordination</strong>: Combining multiple futures requires custom code</li></ol><p>This is where CompletableFuture comes in, which we’ll explore in the next article:</p><pre>// Contrast these approaches:<br><br>// Executor approach<br>Future&lt;User&gt; userFuture = executor.submit(() -&gt; fetchUser(userId));<br>Future&lt;Order&gt; orderFuture = executor.submit(() -&gt; fetchOrder(orderId));<br><br>// Block to get results<br>User user = userFuture.get();<br>Order order = orderFuture.get();<br><br>// Process them sequentially<br>DeliveryInfo deliveryInfo = createDeliveryInfo(user, order);<br><br>// Versus CompletableFuture approach<br>CompletableFuture&lt;User&gt; userFuture = CompletableFuture.supplyAsync(() -&gt; fetchUser(userId));<br>CompletableFuture&lt;Order&gt; orderFuture = CompletableFuture.supplyAsync(() -&gt; fetchOrder(orderId));<br><br>CompletableFuture&lt;DeliveryInfo&gt; deliveryFuture = userFuture.thenCombine(<br>    orderFuture,<br>    (user, order) -&gt; createDeliveryInfo(user, order)<br>);</pre><p>The CompletableFuture version offers non-blocking composition, better error handling, and a more functional approach.</p><blockquote>Looking Ahead: Virtual Threads</blockquote><p>Java 19+ introduces virtual threads (Project Loom), further evolving Java’s concurrency model:</p><pre>// Traditional platform thread (maps to OS thread)<br>Thread platformThread = new Thread(() -&gt; processTask());<br>platformThread.start();<br><br>// Java 21 virtual thread<br>Thread virtualThread = Thread.startVirtualThread(() -&gt; processTask());<br><br>// Or using ExecutorService<br>try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {<br>    for (int i = 0; i &lt; 10000; i++) {  // Easily handle thousands of virtual threads<br>        executor.submit(() -&gt; processTask());<br>    }<br>}</pre><p>Virtual threads allow for a more direct programming model while maintaining high scalability.</p><h3>Conclusion:</h3><p>The Executor Framework represents Java’s first major step toward modern concurrency, providing a foundation of task-based execution that separates the what (tasks) from the how (thread management).</p><p>By understanding this foundation, you’re better prepared to leverage more advanced APIs like CompletableFuture.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L7qHkrjZywjVGlJPW5P_Kw.png" /></figure><p>Key takeaways:</p><ul><li>Thread pools efficiently reuse threads, reducing resource overhead</li><li>Different pool implementations serve different use cases</li><li>Proper configuration and lifecycle management are crucial</li><li>The Executor Framework provides a bridge from traditional threading to modern async patterns</li></ul><p>In the <a href="https://medium.com/@mridul.choudhary7/modern-java-concurrency-revisiting-completablefuture-for-asynchronous-programming-aae19b8244c9">next article</a>, we’ll explore CompletableFuture, which builds upon this foundation to provide a more functional and composable approach to asynchronous programming.</p><h3>References:</h3><ol><li>Java SE Documentation — java.util.concurrent package</li><li>Java Concurrency in Practice by Brian Goetz</li></ol><h3>Thank you for being a part of the community</h3><p><em>Before you go:</em></p><ul><li>Be sure to <strong>clap</strong> and <strong>follow</strong> the writer ️👏️<strong>️</strong></li><li>Follow us: <a href="https://x.com/inPlainEngHQ"><strong>X</strong></a> | <a href="https://www.linkedin.com/company/inplainenglish/"><strong>LinkedIn</strong></a> | <a href="https://www.youtube.com/@InPlainEnglish"><strong>YouTube</strong></a> | <a href="https://newsletter.plainenglish.io/"><strong>Newsletter</strong></a> | <a href="https://open.spotify.com/show/7qxylRWKhvZwMz2WuEoua0"><strong>Podcast</strong></a> | <a href="https://twitch.tv/inplainenglish"><strong>Twitch</strong></a></li><li><a href="https://differ.blog/"><strong>Start your own free AI-powered blog on Differ</strong></a> 🚀</li><li><a href="https://discord.gg/in-plain-english-709094664682340443"><strong>Join our content creators community on Discord</strong></a> 🧑🏻‍💻</li><li>For more content, visit <a href="https://plainenglish.io/"><strong>plainenglish.io</strong></a> + <a href="https://stackademic.com/"><strong>stackademic.com</strong></a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=86859e514125" width="1" height="1" alt=""><hr><p><a href="https://blog.stackademic.com/modern-java-concurrency-foundations-from-threads-to-the-executor-framework-86859e514125">Modern Java Concurrency Foundations: From Threads to the Executor Framework</a> was originally published in <a href="https://blog.stackademic.com/">Stackademic</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>