1. Overview

When writing SQL queries, we often need to build the query dynamically. For instance, dynamic string building is usually required when writing logic for filters, runtime-specified sorts, and optional join operations.

In this tutorial, we’ll see how Java creates SQL strings. Notably, we’ll use the Baeldung Simple University Schema.

2. The Challenge of Dynamic Queries

Let’s suppose we’re building a student search feature. Consequently, a user can search for students using one or more optional filters:

• name
• student ID
• enrollment date
• others

Since filters may vary depending on search criteria, we need different or dynamic SQL queries.

If no filters are selected, we simply retrieve all students:

SELECT * FROM Student;

However, if we search only by name, the query becomes:

SELECT * FROM Student WHERE name LIKE ?;

If we search by both name and student ID, we need an additional condition:

SELECT * FROM Student WHERE name LIKE ? AND id = ?;

Finally, if all filters are provided, the query becomes:

SELECT * FROM Student WHERE name LIKE ? AND id = ?
AND enrollment_date = ?;

As the query grows, it becomes hard to maintain:

String sql = "SELECT s.id, s.name, s.national_id, s.birth_date, " 
  + "s.enrollment_date, s.graduation_date, s.gpa " 
  + "FROM students s " 
  + "WHERE s.gpa >= " + minGpa + " " 
  + "AND s.enrollment_date >= '" + enrollmentDate + "' " 
  + (includeGraduated ? "" : "AND s.graduation_date IS NULL ") 
  + "ORDER BY s.gpa DESC, s.name";

As a result, readability becomes a key issue.

3. Dynamic SQL Generation

When querying a database, users often sort the results with different filters. For example, they may choose to sort by name or date. Thus, we should be able to create an SQL query with dynamic parameters.

3.1. Using the StringBuilder Class

The StringBuilder class in Java enables changes to string objects that are normally immutable in the String class.

Thus, we can assemble SQL queries in steps:

StringBuilder sb = new StringBuilder("SELECT id, name FROM Student");
if (enrollmentDate != null) {
    sb.append(" WHERE enrollment_date = ?");
}
if (birthDate != null) {
    sb.append(" AND birth_date = ?");
}

Still, the above solution isn’t complete. For example, if the user provides a null value to enrollment_date, the WHERE clause doesn’t complete:

SELECT id, name FROM Student AND birth_date = ?

Thus, the resulting SQL becomes invalid.

3.2. Building Conditions Separately

Let’s consider another variant of the above code:

StringBuilder sb = new StringBuilder("SELECT id, name " + "FROM Student WHERE 1=1");
...

In this case, we start with a new clause WHERE 1=1, which is always true. So, we can now start every conditional statement with AND:

if (enrollmentDate != null) {
    sb.append(" AND enrollment_date = ?");
}
if (birthDate != null) {
    sb.append(" AND birth_date = ?");
}

The parameters are now dynamically added to the SQL query. Lastly, we can execute this query using PreparedStatement.

3.3. Execution Using PreparedStatement

Since we’ve used parameterized queries in the above code, we can use PreparedStatement to execute the query:

ps.setString(parameterIndex++, enrollmentDate);
ps.setString(parameterIndex++, birthDate);

In the above code, ps is the PreparedStatement object.

4. Using StringJoiner (Java 8)

The StringJoiner class in Java can join multiple strings. Thus, we can use it to connect multiple SQL strings:

String baseQuery = "SELECT * FROM Student";
StringJoiner whereClause = new StringJoiner(" AND ");
whereClause.add("name LIKE ?");
whereClause.add("id = ?");
whereClause.add("enrollment_date = ?");

In the above example, the search criteria (name, id, and enrollment_date) are dynamic and optional. As a result, we can dynamically build a SQL WHERE clause.

5. Conclusion

In this article, we went through building a SQL query string in Java. First, we saw how long queries become unmanageable. Then, we looked at how the StringBuilder and StringJoiner classes help build dynamic SQL queries.

The code backing this article is available over on GitHub.

       

1. Overview

With Spring AI, we can integrate LLMs into our Spring applications. This is helpful, for example, for processing unstructured data like wiki pages, emails, or chat messages by extracting structured information to store it in a database. However, LLM responses are not deterministic and so neither testable nor handable by our application code. The best way to implement a kind of quality gate for LLM responses is to use an LLM again for evaluation. This pattern is called LLM-as-a-judge.

In this tutorial, we’ll learn how to implement the LLM-as-a-Judge pattern in Spring AI.

2. Maven Dependencies

We add the Spring AI OpenAI starter to our pom.xml:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

The latest version of spring-ai-starter-model-openai is available on Maven Central.

3. The LLM-as-a-Judge Pattern

The LLM-as-a-Judge pattern is like a code review. A developer (the generator) writes code, and a senior engineer (the judge) reviews it and gives structured feedback. If the judge decides that the code doesn’t meet the requirements, the developer needs to improve it, and the judge then needs to review it again.

Applied to LLMs, the process is:

• The generator produces an initial answer to the user’s question
• The judge evaluates that answer against a rubric and returns a numeric score and written feedback
• If the score is too low, the generator receives the original question plus the judge’s critique and produces a refined answer.
• This will repeat until the answer meets the requirements. To avoid endless repetition in case of never reaching the needed quality, it’s a best practice to limit the number of loops.

This pattern improves output quality without model fine-tuning, without a human in the loop, and without changing a single line of calling code.

It’s most valuable wherever a weak answer has real consequences, e.g., customer support bots, where a vague answer to a billing question damages trust directly. In such cases, the pattern acts as an invisible quality gate between the model and the user.

3.1. Why Recursive Advisors Are the Right Fit

Advisors in Spring AI are interceptors that wrap the request/response cycle of a ChatClient. A CallAroundAdvisor can inspect a request before it reaches the model and modify the response before it reaches the caller, but it only ever makes one model call per invocation.

Recursive advisors go further: they hold an internal ChatClient reference and can make additional model calls from within the advisor itself.

We can apply that capability to a specific problem: using the second model call as a judge, not just an extension. The generate-judge-refine loop becomes a single, self-contained component that’s completely transparent to the caller.

The caller just invokes chatClient.prompt().user(“…”).call().content() as usual. The judge’s logic is invisible.

4. Implementing the LLM-as-a-Judge Advisor

Let’s build the feature in three parts: a value object for the verdict, a prompt template for the judge, and the advisor itself.

4.1. The Verdict Record

The judge returns a structured verdict. We model it as a simple Java record:

public record Verdict(double score, String feedback) {}

In our sample, the score is a value between 0.0 (poor) and 1.0 (excellent). The feedback explains what’s missing or weak, and it’s what we’ll feed back to the generator during refinement.

4.2. The Judge Prompt Template

The judge needs a clear, structured system prompt. For this, let’s define it as a constant inside the advisor:

private static final String JUDGE_SYSTEM_PROMPT = """
    You are a strict quality evaluator for AI-generated answers.
    
    Given a user question and an AI-generated answer, rate the answer quality.
    
    Use this rubric:
    - 1.0: Complete, accurate, and clearly explained
    - 0.7: Mostly correct but missing details or clarity
    - 0.4: Partially correct or overly vague
    - 0.0: Incorrect, irrelevant, or harmful
    
    Respond ONLY with a valid JSON object. Do not add any explanation outside the JSON.
    Format: {"score": <0.0 to 1.0>, "feedback": "<one concise sentence>"}
    """;

It’s important to declare an explicit rubric and a strict JSON output to get a parseable and consistent answer from the judge model.

4.3. The Advisor Class and Its Dependencies

The key design decision of a recursive advisor is that it holds its own ChatClient instance to make additional model calls independently of the advisor chain. We also inject the configurable quality thresholds:

public class LlmJudgeAdvisor implements CallAdvisor {
    private final ChatClient judgeClient;
    private final double scoreThreshold;
    private final int maxRefinements;
    public LlmJudgeAdvisor(
      ChatClient judgeClient,
      double scoreThreshold,
      int maxRefinements
    ) {
        this.judgeClient = judgeClient;
        this.scoreThreshold = scoreThreshold;
        this.maxRefinements = maxRefinements;
    }
    @Override
    public int getOrder() {
        return 0;
    }
    @Override
    public String getName() {
        return "LlmJudgeAdvisor";
    }
    // ...
}

The ChatClient.Builder receives the same auto-configured model settings as the rest of the application. We could wire a different, specialized judge model here. The official Spring AI docs recommend this specifically to avoid the model judging its own output too leniently.

4.4. Evaluating and Refining the Response

The adviseCall() method is the only entry point that the advisor chain calls. Rather than forwarding the request once, we call chain.copy(this).nextCall(request), which creates a sub-chain that includes our advisor again. That’s what enables the loop to re-evaluate and re-generate across multiple attempts:

@Override
public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) {
    for (int attempt = 1; attempt <= maxRefinements + 1; attempt++) { 
        ChatClientResponse response = chain.copy(this).nextCall(request);
        if (attempt > maxRefinements) {
          return response;
        }
        Verdict verdict = evaluate(request, response); 
        if (verdict.score() >= scoreThreshold) {
            return response;
        }
        request = addFeedback(request, verdict.feedback());
    }
    return chain.copy(this).nextCall(request);
}

The loop needs an explicit upper bound to avoid unbounded recursion. On the last allowed attempt, the method returns the response immediately, skipping the evaluation. There’s no point scoring an answer we can’t act on. Otherwise, if the score meets scoreThreshold, it returns early. If not, it augments the request with the judge’s feedback and continues to the next iteration.

4.5. Evaluating the Answer

The evaluate() method sends the original question and the generated answer to the judge model. We can use  .entity(…) to render the response JSON directly into our record, without any manual JSON parsing:

private Verdict evaluate(ChatClientRequest request, ChatClientResponse response) {
    String question = request.prompt().getUserMessage().getText();
    String answer = response.chatResponse().getResult().getOutput().getText();
    return judgeClient.prompt()
      .system(JUDGE_SYSTEM_PROMPT)
      .user("Question: " + question + "\n\nAnswer: " + answer)
      .call()
      .entity(Verdict.class);
}

Spring AI injects a JSON schema derived from the Verdict record into the model call and handles deserialization. This removes the need for any try-catch around JSON parsing and keeps the evaluation code focused on the prompt, not on format handling.

4.6. Augmenting the Request With Feedback

When the rating falls short, we don’t start over with the original prompt. Instead, let’s augment it, i.e., we append the judge’s critique to the user message so the model has full context for its next attempt. The addFeedback() helper does this using ChatClientRequest.mutate():

private ChatClientRequest addFeedback(ChatClientRequest original, String feedback) {
    Prompt augmented = original.prompt()
      .augmentUserMessage(msg -> msg.mutate()
          .text(msg.getText()
              + "\n\nYour previous answer was insufficient. Feedback: " + feedback
              + "\nPlease provide an improved answer.")
          .build());
    return original.mutate().prompt(augmented).build();
}

augmentUserMessage() gives us a mutable copy of the user message without touching the rest of the request. System prompt, tool definitions, and conversation history all stay intact. The updated ChatClientRequest is passed into the next loop iteration.

5. Configuring the Application

Let’s declare both beans in a single @Configuration class. The LlmJudgeAdvisor bean receives its own ChatClient instance, built from the same auto-configured ChatClient.Builder, along with the quality thresholds from application.properties:

@Configuration
public class ChatConfig {
    @Bean
    public ChatClient chatClient(
      ChatClient.Builder builder, 
      LlmJudgeAdvisor judgeAdvisor
    ) {
        return builder
          .defaultAdvisors(judgeAdvisor)
          .build();
    }
    @Bean
    public LlmJudgeAdvisor llmJudgeAdvisor(
      ChatClient.Builder builder,
      @Value("${judge.score-threshold:0.7}") double scoreThreshold,
      @Value("${judge.max-refinements:2}") int maxRefinements
    ) {
        return new LlmJudgeAdvisor(
          builder.build(),
          scoreThreshold,
          maxRefinements
        );
    }
}

We can then set the thresholds in application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4o-mini
judge.score-threshold=0.75
judge.max-refinements=2

A score threshold of 0.75 means the judge must rate the answer at least 75% quality before we accept it. Setting the number of maximum refinements to 2 caps the recursive loop at two improvement attempts, preventing runaway API usage.

6. Testing the Advisor

Let’s implement a @SpringBootTest with a single mocked ChatModel. Both the generator and the judge use the same underlying instance, so one mock covers the entire call sequence. No API key is needed.

The test stubs four sequential chatModel responses matching the expected flow:

@SpringBootTest
class LlmJudgeAdvisorTest {
    @MockitoBean
    ChatModel chatModel;
    @Autowired
    ChatClient chatClient;
    @Test
    void givenLowQualityAnswer_whenAdvisorRuns_thenAnswerIsRefined() {
        when(chatModel.call(any(Prompt.class)))
          .thenReturn(buildChatResponse("It runs Java."))
          .thenReturn(buildChatResponse("{\"score\": 0.3, \"feedback\": \"Too vague.\"}"))
          .thenReturn(buildChatResponse(
            "The JVM executes Java bytecode, manages memory, and enables platform independence."))
          .thenReturn(buildChatResponse("{\"score\": 0.9, \"feedback\": \"Complete and accurate.\"}"));
        String result = chatClient.prompt()
          .user("Explain what a JVM is.")
          .call()
          .content();
        assertThat(result).contains("bytecode");
    }
    private ChatResponse buildChatResponse(String content) {
        return new ChatResponse(List.of(new Generation(new AssistantMessage(content))));
    }
}

The four stubs map directly to the generate-evaluate-refine-evaluate cycle: call one is the weak generator response, call two is the judge’s low verdict, call three is the refined generator response, and call four is the judge’s passing verdict. The chatClient with the advisor is real. Only the model underneath is mocked. This means the full advisor logic runs as it would in production.

7. Conclusion

In this article, we implemented the LLM-as-a-Judge pattern in Spring AI using a recursive CallAdvisor. We saw how the generate-evaluate-refine loop maps naturally onto the advisor model: the first model call produces an answer, Spring AI’s structured output maps the judge’s response into a typed Verdict, and the loop augments the original request with feedback until the score is sufficient or the attempt limit is reached.

The result is a reusable component that improves output quality automatically and remains completely transparent to any caller using the ChatClient.

The code for this tutorial is available over on GitHub.

       

1. Spring and Java

>> A return to two-pizza culture [allthingsdistributed.com]

Revisiting Amazon’s two-pizza team idea as an operating model for fast, autonomous, accountable engineering. The practical point: team size, ownership, architecture, and feedback loops shape each other. A useful read.

Also worth reading:

• >> Security Baked Into the JVM: why fork Apache River and OpenJDK? [frankel.ch]
• >> This Dependency Update Looked Exactly Like an Account Takeover [foojay.io]
• >> 7 New Vulnerabilities in Jackson in One Day: This Is What AI-Assisted Security Research Looks Like [foojay.io]
• >> Endive 1.0 Is Here: Wasm on the JVM Ships Under the Bytecode Alliance [foojay.io]
• >> AI-Assisted Unused & Dead Code Removal [foojay.io]
• >> MongoDB-backed Spring Batch jobs and more in Spring Boot 4.1 [spring.io]
• >> CopyOnWriteArrayList.subList() ConcurrentModificationException [javaspecialists.eu]
• >> Scaling Java-Based Real-Time Systems: The Hidden Tradeoffs of Event-Driven Design [infoq.com]
• >> Eliya 25 Brings a JVM-Level Diagnostic Profile to OpenJDK 25 LTS [infoq.com]
• >> Open-Sourcing the LSP Client API in IntelliJ IDEA 2026.2 [jetbrains.com]
• >> Agentrification and the Agentrification Index [scottlogic.com]
• >> GenPage: Towards End-to-End Generative Homepage Construction at Netflix [netflixtechblog.com]

Webinars and presentations:

• >> SIMD Vectors in the HotSpot JVM – Auto Vectorization and the Vector API [inside.java]
• >> ZGC: A Decade of Redefining Java Performance [inside.java]
• >> A Bootiful Podcast: Sébastien Deleuze on the latest-and-greatest in Spring AI and Spring Framework [spring.io]

Time to upgrade:

• >> IntelliJ IDEA 2026.1.4 Is Out! [jetbrains.com]
• >> Quarkus 3.37.1 – Maintenance release [quarkus.io]
• >> GraalVM Community 25.1.3 [github.com/graalvm]
• >> Jetty 12.1.11 and 12.0.37 [github.com/jetty]
• >> Elasticsearch 8.19.18, 9.3.7, and 9.4.3 [github.com/elastic]
• >> Zuul v3.6.18 and v3.6.17 [github.com/Netflix]
• >> Grails 7.2.0, 7.1.3, and 7.0.13 [github.com/apache]
• >> Micronaut Core 5.1.3, 5.0.4, and 3.10.9 [github.com/micronaut-projects]
• >> Apache Camel 4.21.0, 4.18.3, and 4.14.8 [github.com/apache]

2. Pick of the Week

>> The Summer Sale is Live

       

1. Overview

When we build AI-integrated systems, we often provide our AI clients with a large number of tools. On every request, we send the definitions of all available tools to the LLM so it can decide which ones to use. As a result, we waste a significant number of tokens before the model even processes the user query.  In this article, we explore how we solve this issue using the Tool Search Tool. 

2. How the Tool Search Tool Works

Using the Tool Search Tool, we don’t send all the tool definitions with the context. We only expose tools when the model actually needs them. First, we index all registered tools at startup. We store them inside the ToolSearcher, but we do NOT send them to the LLM. Next, we send only the Tool Search Tool in the initial request. This keeps the prompt small and focused. When the model needs a capability, it calls the Tool Search Tool using a natural-language query.

We treat this as a discovery signal and trigger a search over the indexed tools using the configured strategy. Next, we return only the most relevant matches from the ToolSearcher and inject their definitions into the next LLM request, so the model sees a focused set of tools instead of the full registry.

Once the relevant tools are available, the model selects and calls the actual tool. We execute it and send the result back to the LLM, which then uses it to generate the final answer.

3. Building a Travel Assistant Example

Let’s build a travel assistant that helps users plan trips. We connect multiple tools such as flights, hotels, weather, and attractions. We use the Tool Search Tool approach to avoid sending all tools to the LLM upfront. Instead, we discover tools dynamically at runtime.

3.1. Dependencies

We start by adding tool search dependency support:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>tool-search-tool</artifactId>
    <version>${tool-search-tool.version}</version>
</dependency>

Also, let’s add the regex searcher dependency:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>tool-searcher-regex</artifactId>
    <version>${tool-search-tool.version}</version>
</dependency>

Using it, we’ll have a regex tool search strategy. The other available strategies can be found in the project repository.

3.2. Flight Tools

Let’s create a simple FlightTools. We’ll use this tool to retrieve available flight options. In addition, we’ll create a bunch of artificial tools to simulate context overloading:

public class FlightTools {
    @Tool(description = "Searches available flights between two cities")
    public List<FlightOption> searchFlights(String from, String to, String departureDate) {
        return List.of(
          new FlightOption(
            "Romania Airlines",
            from,
            to,
            departureDate,
            249.99
          )
        );
    }
}

Here we return a single flight option.

3.3. TokenCounterAdvisor

Now let’s create a simple TokenCounterAdvisor that counts the number of tokens used to produce the final result. We’ll use it to compare token usage between different setups, with and without tool search enabled:

public class TokenCounterAdvisor implements BaseAdvisor {
    private static final Logger log = LoggerFactory.getLogger(TokenCounterAdvisor.class);
    private final AtomicInteger totalTokenCounter = new AtomicInteger(0);
    @Override
    public String getName() {
        return "TokenCounterAdvisor";
    }
    @Override
    public int getOrder() {
        return Ordered.LOWEST_PRECEDENCE - 1;
    }
    @Override
    public ChatClientRequest before(ChatClientRequest chatClientRequest, AdvisorChain advisorChain) {
        return chatClientRequest;
    }
    @Override
    public ChatClientResponse after(ChatClientResponse chatClientResponse, AdvisorChain advisorChain) {
        var usage = chatClientResponse.chatResponse().getMetadata().getUsage();
        totalTokenCounter.addAndGet(usage.getTotalTokens());
        log.info("Total tokens spent: {}", totalTokenCounter.get());
        return chatClientResponse;
    }
}

Here we store the number of tokens in an AtomicInteger field and log this information during execution. We attach this advisor to the maximum order, so it runs at the end of the processing pipeline. As a result, it captures the total token usage after all other advisors complete.

3.4. Configuration

Next, we add the TravelAssistantConfig implementation:

@Configuration
public class TravelAssistantConfig {
    @Bean
    ToolSearcher toolSearcher() {
        return new RegexToolSearcher();
    }
    @Bean
    ToolSearchToolCallAdvisor toolSearchToolCallAdvisor(ToolSearcher toolSearcher) {
        return ToolSearchToolCallAdvisor.builder()
          .toolSearcher(toolSearcher)
          .maxResults(5)
          .build();
    }
    @Bean
    ChatClient chatClient(ToolSearchToolCallAdvisor toolSearchToolCallAdvisor, OpenAiChatModel model) {
        return ChatClient.builder(model)
          .defaultTools(
            new FlightTools(),
            new RandomTools()
          )
          .defaultAdvisors(toolSearchToolCallAdvisor, new TokenCounterAdvisor())
          .build();
    }
    @Bean
    ChatClient chatClientWithoutToolsSearch(OpenAiChatModel model) {
        return ChatClient.builder(model)
          .defaultTools(
            new FlightTools(),
            new RandomTools()
          )
          .defaultAdvisors(new TokenCounterAdvisor())
          .build();
    }
}

We configure a travel assistant that uses dynamic tool discovery instead of loading all tools into the LLM. Next, we set up a ToolSearcher with a RegexToolSearcher implementation. This allows us to match tools based on naming patterns and fast keyword-like queries. Then, we create a ToolSearchToolCallAdvisor and connect it to the searcher. After that, we build the ChatClient with the flight tools registered.

By design, we’ve added RandomTools, which includes many unrelated tool definitions.  However, we do not send these tool definitions to the LLM initially. Instead, we only index them in the system. Finally, we expose only the Tool Search Tool to the model at the start. The model then uses it to discover which tools it actually needs for a given request. Additionally, we’ve configured a separate ChatClient bean that doesn’t use the ToolSearchToolCallAdvisor.

3.5. Call the TravelAssistant

Finally, let’s create a ToolsSearchToolLiveTest with similar test cases for both clients:

@SpringBootTest
@ActiveProfiles("toolsearchtool")
class ToolsSearchToolLiveTest {
    @Autowired
    private ChatClient chatClient;
    @Autowired
    private ChatClient chatClientWithoutToolsSearch;
    @Test
    void shouldFindFlightsBetweenRomaniaAndCroatiaUsingToolsSearch() {
        String response = getClientResponseString(chatClient);
        assetClientResponse(response);
    }
    @Test
    void shouldFindFlightsBetweenRomaniaAndCroatiaWithoutToolsSearch() {
        String response = getClientResponseString(chatClientWithoutToolsSearch);
        assetClientResponse(response);
    }
    
    private static void assetClientResponse(String response) {
        assertThat(response).isNotBlank();
        assertThat(response).containsIgnoringCase("Croatia");
        assertThat(response).containsIgnoringCase("flight");
    }
    private String getClientResponseString(ChatClient chatClientWithoutToolsSearch) {
        return chatClientWithoutToolsSearch.prompt()
          .user("""
                  Find available flights from Romania to Croatia next week.
                  """)
          .call()
          .content();
    }
}

We’ve called our travel advisor clients with the same prompt and obtained the same verified results. Now, let’s compare the token usage in both of them:

[2026-05-24 11:39:07] [INFO] [c.b.s.t.TokenCounterAdvisor] - Total tokens spent: 974 //With tools search tool
[2026-05-24 11:39:10] [INFO] [c.b.s.t.TokenCounterAdvisor] - Total tokens spent: 3685 //Without tools search tool

As we can see, the difference in token usage is crucial. The more tools we have in our system, the greater the token savings the Tool Search Tool will provide.

4. Conclusion

In this article, we reviewed the Tool Search Tool and demonstrated how it helps reduce token usage in real scenarios. Using it, we can build large AI-integrated systems with hundreds of attached tools and use them efficiently, without wasting tokens. Additionally, we can explore other tool search strategies, such as vector search, or even build our own custom strategy to make tool discovery even more efficient.

As always, the code is available over on GitHub.

       

1. Introduction

Oracle released Java 26 in March, which offered meaningful features that boost performance, new APIs, and preview features that may become permanent features in future releases. This release primarily focused on improvements in areas like garbage collection, networking, startup performance, cryptography, and other language features.

In this tutorial, we’ll briefly talk about all key features introduced in Java 26.

2. Restricts Reflective Modification of final Fields

We create final variables to ensure developers that their values can’t be changed after initialization. This will help us create immutable objects and help the JVM perform certain optimizations. However, this can be breached using reflections.

There are libraries and frameworks that use reflections to modify final fields after an object has been created. This will invalidate the assumptions made by developers, and JVM optimizations may no longer hold true.

Starting from Java 26, the platform takes another step towards stronger encapsulation and integrity. When code tries to modify a final field using deep reflection, the JVM shows warnings indicating to the developer that the operation relies on a behavior that is being phased out. Even though this is currently not enforced, the direction is clear; future Java releases are expected to impose stronger restrictions.

This will impact certain serialization libraries, dependency injection frameworks, mocking tools, and legacy code that bypasses constructors to populate object state.

Developers should now start to audit and identify reflective writes to final fields and migrate toward supported alternatives such as constructors, builders, factory methods, or records or use framework-provided APIs designed for immutable objects.

3. Removal of Applet API

Applets were historically used to run Java applications in browsers. However, modern browsers don’t support applets due to performance, compatibility, and security concerns. This is considered an outdated technology, and this API has been marked deprecated since Java 9. Developers nowadays use much better alternatives like Swing/JavaFX for UI.

With Java 26, the applet API is no longer existent. This update helps Oracle keep Java streamlined and secured while also reducing the maintenance burden. Its removal will affect only very old legacy applications that still depend on it.

4. Ahead of Time Object Caching with Any GC

Java is known for building distributed cloud-native applications that are frequently deployed, scaled, started, and stopped. Oracle is working towards bringing enhancements that reduce the start-up overhead, which allows applications to reach their peak performance more quickly. In Java 26, Oracle introduced one such enhancement.

Java has Ahead of Time (AOT) object caching, which identifies the objects that are expensive to create during startup and stores them in a cache. When the application starts again, these objects are loaded directly from the cache instead of recreating them, thereby reducing the start-up overhead.

The benefits of Ahead of Time (AOT) are limited to specific GC configurations. However, in Java 26, this feature is available to any garbage collector, including low-latency collectors such as Z Garbage Collector (ZGC).

This enhancement allows developers to take advantage of AOT object caching without giving up their preferred garbage collector.

5. HTTP/3 for the HTTP Client API

Network resilience and latency are key factors for applications that communicate heavily over the network, like microservices, real-time applications, and cloud-native services. With Java 26, the HTTP Client API now supports HTTP/3, which is the latest version of the HTTP protocol.

While HTTP/1.1 and HTTP/2 were built on top of TCP, HTTP/3 uses the QUIC transport protocol, which runs on UDP and addresses some of the limitations of the TCP protocol. With TCP, a packet loss can delay all streams that are sharing the same connection, while QUIC allows streams to progress independently. QUIC achieves this by combining both transport and security handshakes to reduce the number of network round trips required before data starts flowing.

Another practical advantage is automatic protocol negotiation. If the target server supports HTTP/3, the client can use it. If not, it can seamlessly fall back to HTTP/2 or HTTP/1.1, ensuring compatibility with existing infrastructure.

With the introduction of HTTP/3, applications can now experience reduced latency and improved responsiveness. This is especially useful for real-time and cloud-native applications.

Let’s now take a look at a quick example:

@Test
void givenHttp3Client_whenSendingARequest_thenShouldReceiveSuccessfulResponse()
    throws IOException, InterruptedException {
    HttpClient client = HttpClient.newBuilder()
      .version(HttpClient.Version.HTTP_3)
      .build();
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://example.com"))
      .GET()
      .build();
    HttpResponse<String> response =
      client.send(request, HttpResponse.BodyHandlers.ofString());
    assertEquals(200, response.statusCode());
}

To use HTTP/3, we configure the HttpClient by specifying HttpClient.Version.HTTP_3 while building the client. We then create a simple GET request to https://example.com and send it synchronously using the send() method. Finally, we verify that the request completes successfully by asserting that the response status code is 200.

It’s worth noting that configuring the client for HTTP/3 doesn’t guarantee that the connection will use HTTP/3. If the target server doesn’t support HTTP/3, the client automatically falls back to an earlier HTTP version (HTTP/2 or HTTP/1.1), while still completing the request successfully.

6. G1 Garbage Collector Throughput Improvements

For quite some time, the Garbage First (G1) garbage collector has been Java’s default garbage collector. It offers an impressive blend of throughput, memory, and predictability of pause times.

A typical modern Java application will constantly create or update object references. G1 is responsible for tracking object reference changes to perform garbage collection. Ultimately, there is some overhead in this tracking, particularly in applications with high allocation rates or frequent object updates.

With Java 26, G1 now has a set of internal changes that improve the throughput of an application. One such change is reducing the need for mutator application threads and garbage collection (GC) threads to synchronize when tracking the changes of which object references have been changed.  Because of these improvements, application threads will synchronously wait less time related to GC and more time performing application logic.

7. PEM Encodings of Cryptographic Objects (Second Preview)

Applications that deal with security often need to handle certificates, public and private keys, and certificate chains. Cryptographic objects are usually stored and transmitted using PEM (Privacy Enhanced Mail). PEM is a text-based format that allows binary security data to be formatted in a compact manner.

Java developers have historically been required to deploy third-party libraries or write code of their own to read and write PEM files. This has made security-related applications both complex and cumbersome due to additional dependencies and code that serves little or no purpose.

Java 26 introduces the second preview of a newly proposed API to PEM format cryptographic objects that adds the capability to Java SE. Using the proposed API brings the capability to Java developers to read and write certificates and keys using the standard Java SDK instead of using libraries.

The proposed API enhances Java’s capability to integrate with standard security protocols and infrastructure. It also simplifies the management of certificates and keys. In addition, the API reduces the time and effort to write custom code for applications. Even if it is still a preview, it provides a more consistent and pragmatic approach to Java security.

8. Structured Concurrency (Sixth Preview)

Structured concurrency adds to Project Loom’s collection of tools to simplify concurrent programming in Java by proposing that multiple related tasks be treated as a unit of work, rather than requiring developers to manage multiple threads separately.

In traditional concurrent code, coordinating threads, handling failures, and cleaning up resources can become complex. Structured concurrency allows related tasks to run within the defined scope, and if one task fails, other related tasks will be cancelled automatically. This helps prevent wasted work.

Java 26 includes the sixth preview of Structured Concurrency, bringing further refinements based on real-world usage and community feedback as the feature moves closer to becoming a permanent part of the platform in the future.

9. Lazy Constants (Second Preview)

In a normal scenario, class constants are created when the class gets loaded, even though the application never uses them. This contributes to increased startup time and creation of unnecessary objects.

To address this, developers used to introduce their own code to create constants only when they were actually needed. Often this code is complex, less readable, and harder to maintain.

With lazy constants, this mechanism is now built in. Developers can now reap the benefits of lazy loading without having to introduce complex code. By creating objects only when they are first used, applications can now start faster and use fewer resources. Java 26 includes the second preview of this feature.

10. Vector API (Eleventh Incubator)

Vector API in Java 26 is an incubator feature, which allows developers to take advantage of SIMD (Single Instruction, Multiple Data).

Normally, a processor performs an operation on one value at a time. With SIMD, the same operation can be performed on multiple values at once. This helps applications achieve performance closer to native code while remaining portable across different CPU architectures.

This will significantly improve the performance for computation-heavy workloads such as scientific computing, data analytics, image processing, machine learning, and financial calculations.

11. Primitive Types in Patterns, instanceof, and switch (Fourth Preview)

Pattern matching makes code easier to read and reduces the need for manual type checks and casting. In previous releases, this is only supported for reference types.

However, with Java 26, this is also included for primitive types like int, long, float, and double. This allows developers to work with primitive values more naturally in pattern matching constructs, including switch statements and other pattern-based control flow.

12. Conclusion

We’ve seen various improvements and new features introduced in Java 26. While they are a mix of permanent and preview features, it’s evident that the Java community is moving towards making Java ideal for modern-day enterprise application development.

The source code for the examples can be found over on GitHub.

       

1. Overview

In this tutorial, we’ll explore the Java API for Apache Paimon, which is essential for managing the Paimon database from custom applications. We’ll use it to create a data lake with a table in HDFS storage and perform CRUD operations on it.

This open-source data lakehouse format provides a unified storage layer for real-time streaming, batch processing, and OLAP. It can serve as a message queue for a streaming application and as a HIVE table for a batch processing application. It supports building data lakes on a variety of storage systems, including object storage, HDFS, and local file systems. Furthermore, it integrates seamlessly with popular distributed data processing engines such as Apache Spark, Apache Flink, and Trino to build scalable data pipelines.

2. Prerequisites

Let’s start with Maven dependencies required in a Java application to integrate with Apache Paimon:

<dependency>
    <groupId>org.apache.paimon</groupId>
    <artifactId>paimon-bundle</artifactId>
    <version>1.4.1</version>
</dependency>

For our example, we’ll use HDFS as the storage, and hence, let’s include the runtime library for interacting with it:

<dependency>
    <groupId>org.apache.hadoop</groupId>
    <artifactId>hadoop-client-runtime</artifactId>
    <version>3.4.3</version>
</dependency>

3. Create Data Lake

Let’s consider a data lake to store IT infrastructure performance metrics collected by monitoring tools that poll devices. These metrics can quickly accumulate in volume, and data lakes such as Paimon can reliably store them for long periods.

Let’s define the data model:

Before ingesting monitoring data into Apache Paimon, we need to set up the storage layer by creating a catalog and defining the table schema. In Paimon, the catalog acts as the entry point to the data lake, while tables define how data is organized, typed, and versioned.

Moving on, let’s look at a simple utility class responsible for initializing the data lake and creating a metrics table:

public class PaimonDatabaseManager {
    public static Catalog createCatalog(String warehousePath) {
        CatalogContext context = CatalogContext.create(new Path(warehousePath));
        return CatalogFactory.createCatalog(context);
    }
    public static Identifier createTable(Catalog catalog) throws Exception {
        Schema schema = Schema.newBuilder()
          .column("device_id", DataTypes.STRING())
          .column("metrics_name", DataTypes.STRING())
          .column("metrics_value", DataTypes.DOUBLE())
          .column("source", DataTypes.STRING())
          .column("create_time", DataTypes.TIMESTAMP(3))
          .column("state", DataTypes.STRING())
          .primaryKey("device_id", "metrics_name", "create_time")  
          .build();
        Identifier tableId = Identifier.create("metric_db", "metrics");
        catalog.createDatabase("metric_db", true);
        catalog.createTable(tableId, schema, false);
        return tableId;
    }
}

In the class, PaimonDatabaseManager.createCatalog() creates a Catalog instance backed by the local filesystem, using a CatalogContext to configure the warehouse location. Finally, CatalogFactory.createCatalog() uses the context to create the Paimon database.

Furthermore, the PaimonDatabaseManager.createTable() method builds a Schema for the metrics table and uses an Identifier to register it under the metric_db database. The table schema includes typed columns and a composite primary key.

Now, we’ll use the PaimonDatabaseManager class in a program to create a Paimon database table:

void whenCallCreateTable_thenTableCreated() throws Exception {
    catalog = PaimonDatabaseManager.createCatalog(WAREHOUSE_PATH);
    assertNotNull(catalog);
    
    tableId = PaimonDatabaseManager.createTable(catalog);
    assertNotNull(tableId);
    assertTrue(catalog.listTables("metric_db").contains("metrics"));
}

In the program, we first call PaimonDatabaseManager.createCatalog(WAREHOUSE_PATH) to create a Paimon database catalog. The argument WAREHOUSE_PATH contains the path to a temporary directory created for the database. Next, we call PaimonDatabaseManager.createTable() to create a metrics table in the catalog. Finally, we invoke Catalog.listTables() to list all the tables in the metric_db database and confirm that it contains the metrics table. 

4. Insert Records in Table

In this section, we’ll learn about the API to insert metric records into the Paimon metric table:

public class PaimonTableDataManager {
    public static void insert(Catalog catalog, Identifier tableId, List metrics) throws Exception {
        Table table = catalog.getTable(tableId);
        BatchWriteBuilder builder = table.newBatchWriteBuilder();
        BatchTableWrite write = builder.newWrite();
        metrics.forEach(metric -> {
          try { 
              GenericRow row = createGenericRow(metric);
              write.write(row, 0);
          } catch (Exception e) {
              logger.error("Error writing metric", e);
          }
        });
        List messages = write.prepareCommit();
        BatchTableCommit commit = builder.newCommit();
        commit.commit(messages);
    }
}

First, we retrieve the Table object associated with the tableId from the Catalog object. Next, we get an instance of the BatchWriteBuilder class by invoking Table#newBatchWriteBuilder(). The builder object helps create a BatchTableWrite object that executes write operations on tables.

Further, we transform each metric record into a GenericRow object in the createGenericRow() method:

private static GenericRow createGenericRow(Metric metric) {
    GenericRow row = GenericRow.of(
      BinaryString.fromString(metric.getDeviceId()),
      BinaryString.fromString(metric.getMetricsName()),
      metric.getMetricsValue(),
      BinaryString.fromString(metric.getSource()),
      convertToTimestamp(metric.getCreateTime()),
      BinaryString.fromString(metric.getCreatedBy()),
      BinaryString.fromString(metric.getState())
    );
    return row;
}

During this process, each column value is converted to its corresponding Paimon-compatible data type, such as BinaryString and Timestamp.

After creating the GenericRow object in the insert method, BatchTableWrite.write() writes each row into the metrics table. Finally, the data is committed in a single batch outside the loop.

Let’s run the PaimonTableDataManager.insert() to insert some records into the metrics table:

void whenCallInsertRecords_thenRecordsInserted() throws Exception {
    assertTrue(catalog.listTables("metric_db").contains("metrics"));
    PaimonTableDataManager.insert(catalog, tableId, getMetrics());
}

First, with the assert method, we ensure that the metric table exists in the catalog. The arguments, catalog, and tableId hold the Catalog and table Identifier objects that we retrieved and stored while creating the metrics table. The getMetrics() method could be a service fetching the metric data from a monitoring tool. Moreover, for our example, we retrieve the synthetic data from a CSV file metrics.out:

device_id,metric_name,create_time,metric_value,source
dev_101,cpu_usage,2026-04-21 18:57:01,72.5,agent
dev_102,cpu_usage,2026-04-21 18:57:02,65.1,agent
dev_103,memory_usage,2026-04-21 18:57:03,58.3,agent
...

However, real-world applications usually poll monitoring tools at regular intervals to fetch the latest metrics. Finally, we invoke the insert method to create new records into the metrics table.

5. Query Records From Table

After the raw metrics are collected, they must be fetched from the database and then processed to derive actionable analytics. The API supports filter pushdown and column projections, helping enhance performance. Additionally, the API supports both batch reads and streaming data for analytics and real-time use cases.

Let’s use the Paimon Java API to implement a batch read operation:

public static List<Metric> fetchMetricsBySourceAndDateRange(Catalog catalog, Identifier tableId,
      String source, String startDate, String endDate) throws Exception {
    Table table = catalog.getTable(tableId);
    RowType rowType = table.rowType();
    PredicateBuilder predicateBuilder = new PredicateBuilder(rowType);
    int[] projection = new int[] {0, 1, 2, 3, 4};
    Predicate sourcePredicate = predicateBuilder.equal(3, BinaryString.fromString(source));
    Predicate dateRangePredicate = predicateBuilder.between(
      4, convertToTimestamp(startDate), convertToTimestamp(endDate)
    );
    Predicate predicate = PredicateBuilder.and(sourcePredicate, dateRangePredicate);
    ReadBuilder readBuilder = table.newReadBuilder().withFilter(predicate).withProjection(projection);
    List<Split> splits = readBuilder.newScan().plan().splits();
    TableRead read = readBuilder.newRead().executeFilter();
    RecordReader<InternalRow> reader = read.createReader(splits);
    List<Metric> results = new ArrayList<>();
    reader.forEachRemaining(internalRow -> {
        String deviceId = internalRow.getString(0).toString();
        String metricsName = internalRow.getString(1).toString();
        double metricsValue = internalRow.getDouble(2);
        String sourceValue = internalRow.getString(3).toString();
        Timestamp timestamp = internalRow.getTimestamp(4, 3);
        String createTime = ConvertTimestampToStr(timestamp); 
        Metric metric = new Metric(deviceId, metricsName, metricsValue, sourceValue, createTime, null);
        logger.info("Fetched Metric: {}", metric);
        results.add(metric);
    });
    return results;
}

The fetchMetricsBySourceAndDateRange() method queries the metrics tables to fetch metric data originating from a specific source within a given date range. In the method, the PredicateBuilder helps create Predicate objects with filter conditions on the source and create_time columns. The Table#newReadBuilder() creates a ReadBuilder object, and subsequently, ReadBuilder#withFilter() sets the necessary predicates. Additionally, we define a projection array to fetch only the required columns.

Moving on, the builder creates data splits that can be distributed across multiple threads or processes, enabling faster execution. The splits are comparable to partitions or data files corresponding to a table. Next, ReadBuilder#newRead() creates a TableRead object on which we invoke the executeFilter() method. After this, TableRead#createReader() creates a RecordReader for the generated splits. Multiple readers can process different splits concurrently, enabling scalable and efficient parallel reads. Finally, we call RecordReader#forEachRemaining() to iterate through the rows and fetch the metric attributes.

Now, let’s run the program to fetch a metric from a certain source and within a date range:

void whenCallReadRecords_thenRecordsRead() throws Exception {
    List<Metric> metrics = PaimonTableDataManager.fetchMetricsBySourceAndDateRange(
      catalog, tableId, "collector", "2026-04-21 18:58:19", "2026-04-21 18:58:30");
    assertFalse(metrics.isEmpty());
    assertTrue(metrics.size() == 4);
}

The program fetched four metric rows with the source collector and created between 2026-04-21 18:58:19 and 2026-04-21 18:58:30.

6. Update Table Records

There’s no particular Java API for updating records in a Paimon Table. However, when we perform a write operation, just like in the case of performing an insert on an existing record with the primary key, instead of a new row, the existing row gets updated.

To understand the update operation, we’ve defined the method in the PaimonTableDataManager class:

public static void updateMetricStateByDeviceIdMetricNameAndCreatedDate(Catalog catalog,
      Identifier tableId, String deviceId, String metricName, String newState, String createdDate)
    throws Exception {
    Metric metric = fetchMetricByDeviceIdMetricNameAndCreatedDate(
      catalog, tableId, deviceId, metricName, createdDate
    );
    Table table = catalog.getTable(tableId);
    BatchWriteBuilder builder = table.newBatchWriteBuilder();
    BatchTableWrite write = builder.newWrite();
    metric.setState(newState);
    write.write(createGenericRow(metric), 0);
    List<CommitMessage> messages = write.prepareCommit();
    BatchTableCommit commit = builder.newCommit();
    commit.commit(messages);
}

First, we fetch a metric record filtered by the primary key, composed of metric attributes such as device ID, metric name, and created date, by invoking the fetchMetricByDeviceIdMetricNameAndCreatedDate() method. The method is in the same line as the method described in the previous section, which queries records from the metric table.

Then, we update the Metric#state attribute with a new state. The remaining steps are largely similar to the insert method described earlier. However, instead of creating a new record, the existing metric’s state is updated with a new state.

Let’s execute updateMetricStateByDeviceIdMetricNameAndCreatedDate():

void whenCallUpdateRecord_thenRecordUpdated() throws Exception {
    Metric metric = PaimonTableDataManager
      .fetchMetricByDeviceIdMetricNameAndCreatedDate(
        catalog, tableId, 
        "dev_137", "cpu_usage",
        "2026-04-21 18:58:27"
    );
    assertNotNull(metric);
    assertEquals("active", metric.getState());
    PaimonTableDataManager.updateMetricStateByDeviceIdMetricNameAndCreatedDate(
        catalog, tableId, "dev_137",
            "cpu_usage", "inactive", 
            "2026-04-21 18:58:27"
    );
    metric = PaimonTableDataManager.fetchMetricByDeviceIdMetricNameAndCreatedDate(
        catalog, tableId, "dev_137", 
        "cpu_usage", "2026-04-21 18:58:27"
    );
    assertNotNull(metric);
    assertEquals("inactive", metric.getState());
}

We fetched a metric record by its composite primary key and updated its state to inactive. Later, we again fetched the record and confirmed that the state has been updated to inactive.

7. Delete Table Records

Moving on, Paimon Java API’s also supports the delete operation:

public static void deleteRecordsByDeviceIdMetricNameAndCreatedDate(Catalog catalog, 
    Identifier tableId, String deviceId, 
    String metricsName, String createdDate) throws Exception {
    Metric metric = PaimonTableDataManager
     .fetchMetricByDeviceIdMetricNameAndCreatedDate(
       catalog, tableId, deviceId, metricsName, createdDate
    );
    Table table = catalog.getTable(tableId);
    BatchWriteBuilder builder = table.newBatchWriteBuilder();
    BatchTableWrite write = builder.newWrite();
    GenericRow deleteRow = createGenericRow(metric);
    deleteRow.setRowKind(RowKind.DELETE);
    write.write(deleteRow, 0);
    List<CommitMessage> messages = write.prepareCommit();
    builder.newCommit().commit(messages);
}

First, we fetched a metric record by calling PaimonTableDataManager.fetchMetricByDeviceIdMetricNameAndCreatedDate(). The next set of steps is almost similar to the update method, except that we don’t modify any field in the metric record. Later, before invoking BatchTableWrite#write(), we flag the operation as delete by calling the method BatchTableWrite#setRowKind(RowKind.DELETE).

Let’s verify the deleteRecordsByDeviceIdMetricNameAndCreatedDate() method by executing it:

void whenCallDeleteRecord_thenRecordDeleted() throws Exception {
    Metric metric = PaimonTableDataManager.fetchMetricByDeviceIdMetricNameAndCreatedDate(
      catalog, tableId, 
      "dev_136", "disk_io", "2026-04-21 18:58:26"
    );
    assertNotNull(metric);
    PaimonTableDataManager.deleteRecordsByDeviceIdMetricNameAndCreatedDate(
      catalog, tableId, 
      "dev_136", "disk_io", "2026-04-21 18:58:26"
    );
    metric = PaimonTableDataManager.fetchMetricByDeviceIdMetricNameAndCreatedDate(
      catalog, tableId, "dev_136", "disk_io", "2026-04-21 18:58:26"
    );
    assertTrue(metric == null);
}

First, we fetch a metric record corresponding to a device by invoking PaimonTableDataManager.fetchMetricByDeviceIdMetricNameAndCreatedDate(). After ensuring the record isn’t null, we invoke the delete method. Finally, we query the metric table again and confirm that no such record is present in the Paimon DB.

8. Conclusion

In this article, we explored the core Java APIs for managing a Paimon database, including creating tables, performing batch insertions, updates, deletes, and executing filtered data queries. We used the local file system to create the Paimon DB, but the APIs are standard and effective irrespective of the chosen storage layer.

As usual, the source code can be found over on GitHub.

       

1. Overview

Kafka provides a high degree of flexibility in committing offsets for processed messages in the consumer. It includes synchronous, asynchronous, and auto-commit options.

While this reduces the complexity of the commit process, unexpected errors can still occur.

In this tutorial, we’ll learn about a commit offset-related failure in a Kafka consumer application. We’ll debug the root cause of the resulting CommitFailedException and implement a few solutions to avoid it where possible.

2. Implementing a Consumer Service to Demonstrate the Issue

Let’s build a simple consumer application that processes records sequentially.

We’ll implement the consume method in the KafkaConsumerService class:

public class KafkaConsumerService {
    private final KafkaConsumer<String, String> consumer;
    private final AtomicBoolean running = new AtomicBoolean(true);
    public void consume() {
        try {
            while (running.get()) {
                ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(100));
                if (records.isEmpty()) {
                    continue;
                }
                records.forEach(this::simulateDBCall);
                consumer.commitSync();
            }
        } catch (WakeupException ex) {
            if (running.get()) {
                log.error("Error in the Kafka Consumer with exception", ex);
                throw ex;
            }
        } finally {
            consumer.close();
        }
    }
}

In the code above, we process records sequentially and then commit the offset.

To simulate a database call, we’ll add a delay in the above simulateDBCall method:

private void simulateDBCall(ConsumerRecord<String, String> record) {
    try {
        log.info("Simulating a DB call - record key {} value {}", record.key(), record.value());
        Thread.sleep(150L);
    } catch (InterruptedException ex) {
        Thread.currentThread()
          .interrupt();
        throw new RuntimeException(ex);
    }
}

The delay will cause the consumer to wait around 150 ms before the next record.

3. Testing the Service

Next, let’s test the consumer service. Note that we use Testcontainers in our test harness to provide a local Kafka broker for testing; full details are available in the supporting GitHub repository linked at the end of this article.

First, we’ll include the consumer-related configs in the test class:

private static Properties getConsumerConfig() {
    Properties consumerProperties = new Properties();
    consumerProperties.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA_CONTAINER.getBootstrapServers());
    consumerProperties.put(ConsumerConfig.GROUP_ID_CONFIG, "consumer-app");
    consumerProperties.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
    consumerProperties.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
    consumerProperties.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
    consumerProperties.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "false");
    consumerProperties.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 1);
    consumerProperties.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 50);
    
    return consumerProperties;
}

In the config above, we’re polling for one record with a maximum poll interval of 50 ms and manually committing the offset.

We’ll implement a test case by producing, consuming a message, and verifying the offset:

@Test
void givenProducerMessageIsSent_whenConsumerIsRunning_thenConsumerOffsetIsCommitted() {
    KafkaConsumerService kafkaConsumerService = new KafkaConsumerService(getConsumerConfig(), "test-topic");
    Thread th = new Thread(kafkaConsumerService::consume);
    th.start();
    try (KafkaProducer<String, String> producer = new KafkaProducer<>(getProducerConfig())) {
        producer.send(new ProducerRecord<>("test-topic", "x1", "test"));
        producer.flush();
    }
    Awaitility.await()
      .atMost(30, TimeUnit.SECONDS)
      .pollInterval(2, TimeUnit.SECONDS)
      .untilAsserted(() -> {
          TopicPartition topicPartition = new TopicPartition("test-topic", 0);
          Map<TopicPartition, OffsetAndMetadata> committedOffsets;
          try (AdminClient adminClient = AdminClient.create(getAdminProps())) {
              ListConsumerGroupOffsetsResult result = adminClient.listConsumerGroupOffsets("consumer-app");
              committedOffsets = result.partitionsToOffsetAndMetadata()
                .get();
          }
          assertNotNull(committedOffsets);
          assertNotNull(committedOffsets.get(topicPartition));
          assertEquals(1L, committedOffsets.get(topicPartition)
            .offset());
      });
    kafkaConsumerService.shutdown();
}

Instead of offset committed, we’ll see the following error log with the test case also failing:

org.apache.kafka.clients.consumer.CommitFailedException: Offset commit cannot be completed since the consumer is not part of an active group for auto partition assignment; it is likely that the consumer was kicked out of the group.
	at org.apache.kafka.clients.consumer.internals.ConsumerCoordinator.sendOffsetCommitRequest(ConsumerCoordinator.java:1280)
	...
	at org.apache.kafka.clients.consumer.KafkaConsumer.commitSync(KafkaConsumer.java:918)
	at com.baeldung.kafka.commitfailure.sequential.KafkaConsumerService.consume(KafkaConsumerService.java:34)

From the log above, it’s obvious that the CommitFailedException was thrown while committing the offset in the consume method. Also, it says that the consumer is no longer part of the group. Kafka gives some hints in the class documentation on the possible reason.

4. Root Cause of the CommitFailedException

We can monitor and debug the root cause with multiple options, including container logs, CLI, and Kafka UI tools.

First, we’ll check the Kafka container logs for the error:

[2026-06-08 16:53:05,349] INFO [GroupCoordinator 1]: Preparing to rebalance group consumer-app in state PreparingRebalance with old generation 1 (__consumer_offsets-0) (reason: Removing member consumer-consumer-app-1-3792090b-be55-4e19-bdbd-a3c66b968168 on LeaveGroup; client reason: consumer poll timeout has expired.)
...
[2026-06-08 16:53:05,354] INFO [GroupCoordinator 1]: Member MemberMetadata(memberId=consumer-consumer-app-1-3792090b-be55-4e19-bdbd-a3c66b968168, groupInstanceId=None, clientId=consumer-consumer-app-1, clientHost=/172.17.0.1, sessionTimeoutMs=45000, rebalanceTimeoutMs=50, supportedProtocols=List(range, cooperative-sticky)) has left group consumer-app through explicit `LeaveGroup`; client reason: consumer poll timeout has expired...

We’ll also confirm the consumer group’s state using the kafka-consumer-groups command:

sh-4.4$ /usr/bin/kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group consumer-app --state
Consumer group 'consumer-app' has no active members.
GROUP                     COORDINATOR (ID)          ASSIGNMENT-STRATEGY  STATE           #MEMBERS
consumer-app              8db993586dab:9092  (1)                         Empty           0

Based on the above logs and status, we can see that the consumer was removed due to a client-specific error: consumer poll timeout has expired.

Kafka has multiple ways to check if the consumer is healthy and running. This includes a background heartbeat check, which should run before the session timeout.

Additionally, Kafka expects the consumer to poll once within the specified max poll interval time period. If the consumer does not poll for any reason, it will be considered dead, and the partition will be reassigned to another consumer.

By further debugging and re-verifying the application logs, we observe that the record processing was clearly taking more time, and the consumer could not call the poll method within the specified MAX_POLL_INTERVAL_MS_CONFIG time period. Consequently, the consumer was removed by the Kafka group coordinator.

So, any further attempt to commit an offset failed with the error. It makes sense as the consumer is no longer the partition owner, and a commit can corrupt the offset state.

We’ll explore a few practical ways to prevent the error.

5. Approaches to Avoid the Problem

With the consumer polling understanding, we’ll try to solve it by analyzing the consumer code and configuration.

We may consider enabling auto-commit config, but that brings a possibility of data loss and irregular commit timing. Moreover, this approach does not ensure at-least-once processing.

Instead, we’ll explore some relevant manual commit solutions.

5.1. Tuning the Poll Duration and Batch Size

By debugging the code, we found that the actual processing time was significantly longer than the specified maximum poll interval.

We’ll increase the maximum poll interval config:

consumerProperties.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 1);
consumerProperties.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 300);

We can also fine-tune the batch size according to our batch processing timing and throughput requirements.

Let’s test the updated consumer and confirm that no CommitFailedException is thrown.

We should note that it’s good to set the poll interval to about 3 times the batch processing time to ensure a safe buffer.

While changing the poll interval works, we may still face the issue in more complex setups, such as processing involving database transactions or network calls.

5.2. Async Processing

If we’re processing records in the same thread that performs I/O operations, the above solution reduces throughput and increases latency.

In a production environment, we can’t guarantee a predictable database execution time, so configuring just the polling duration might be insufficient.

We can consider asynchronous processing of the records, so the consumer thread blocks for much shorter periods.

In Kafka, this can be done by processing the records asynchronously with virtual threads.

First, we’ll include a worker thread pool and a per-partition offset tracking map in the consumer service:

public class KafkaConsumerService {
    private final KafkaConsumer<String, String> consumer;
    private final AtomicBoolean running = new AtomicBoolean(true);
    private final ExecutorService workers;
    private final Map<TopicPartition, AtomicLong> committableOffsets = new ConcurrentHashMap<>();
    public KafkaConsumerService(Properties consumerProps, String topic) {
        this.consumer = new KafkaConsumer<>(consumerProps);
        consumer.subscribe(List.of(topic));
        workers = Executors.newVirtualThreadPerTaskExecutor();
    }
}

Next, we’ll update the consume method with async processing using the worker threads:

public void consume() {
    try {
        while (running.get()) {
            ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(100));
            if (records.isEmpty()) {
                continue;
            }
            List<CompletableFuture<Void>> futures = processAsync(records);
            try {
                CompletableFuture.allOf(futures.toArray(CompletableFuture[]::new))
                  .orTimeout(700L, TimeUnit.MILLISECONDS)
                  .join();
            } catch (CompletionException ex) {
                log.error("Batch processing timed out or failed", ex);
            }
            commitOffsets();
        }
    } catch (WakeupException ex) {
        if (running.get()) {
            log.error("Error in the Kafka Consumer with exception", ex);
            throw ex;
        }
    } finally {
        commitOffsets();
        consumer.close();
    }
}

We’ll implement the processAsync method to asynchronously process the records:

private List<CompletableFuture<Void>> processAsync(ConsumerRecords<String, String> records) {
    return StreamSupport.stream(records.spliterator(), false)
      .map(record -> CompletableFuture.runAsync(() -> simulateDBUpdate(record), workers)
        .whenComplete((ignored, ex) -> {
            if (ex == null) {
                markComplete(record);
            } else {
                log.error("Failed offset and send to DLQ {} {} {}", 
                  record.offset(), record.key(), ex.getMessage());
            }
        })
        .exceptionally(ex -> null))
      .toList();
}

In the code above, the consumer waits for the workers to complete processing, then commits the processed offset. If any record fails during processing, we log the failure message and can send it to a Dead Letter Queue (DLQ) topic.

Next, let’s implement the markComplete method to update the processed record offset into the committableOffsets map:

private void markComplete(ConsumerRecord<String, String> record) {
    TopicPartition tp = new TopicPartition(record.topic(), record.partition());
    committableOffsets.computeIfAbsent(tp, k -> new AtomicLong(-1L))
      .accumulateAndGet(record.offset() + 1L, Math::max);
}

Finally, we’ll implement the commitOffsets method to commit the processed offset:

private void commitOffsets() {
    Map<TopicPartition, OffsetAndMetadata> toCommit = new HashMap<>();
    committableOffsets.forEach((tp, atomicOffset) -> {
        long val = atomicOffset.get();
        if (val != -1L) {
            toCommit.put(tp, new OffsetAndMetadata(val));
        }
    });
    if (toCommit.isEmpty()) {
        return;
    }
    consumer.commitSync(toCommit);
    toCommit.forEach((tp, meta) -> {
        AtomicLong ref = committableOffsets.get(tp);
        if (ref != null) {
            ref.compareAndSet(meta.offset(), -1L);
        }
    });
}

In the method above, we build the committed offset snapshot map for all the processed records and commit it. We also atomically mark the committed offset as completed.

Now, let’s configure the consumer with an increased batch size and max poll interval in the test class:

consumerProperties.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 30);
consumerProperties.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 1000);

Finally, we’ll implement a test case by producing and consuming multiple messages and verifying the offset:

@Test
void givenProducerMessagesAreSent_whenConsumerIsRunning_thenConsumerOffsetIsCommitted() {
    KafkaConsumerService kafkaConsumerService = new KafkaConsumerService(getConsumerConfig(), "test-topic");
    Thread th = new Thread(kafkaConsumerService::consume);
    th.start();
    try (KafkaProducer<String, String> producer = new KafkaProducer<>(getProducerConfig())) {
        for (int num = 0; num < 100; num++) {
            producer.send(new ProducerRecord<>("test-topic", "x1" + num, "test" + num));
        }
        producer.flush();
    }
    Awaitility.await()
      .atMost(30, TimeUnit.SECONDS)
      .pollInterval(2, TimeUnit.SECONDS)
      .untilAsserted(() -> {
          TopicPartition topicPartition = new TopicPartition("test-topic", 0);
          Map<TopicPartition, OffsetAndMetadata> committedOffsets;
          try (AdminClient adminClient = AdminClient.create(getAdminProps())) {
              ListConsumerGroupOffsetsResult result = adminClient.listConsumerGroupOffsets("consumer-app");
              committedOffsets = result.partitionsToOffsetAndMetadata()
                .get();
          }
          assertNotNull(committedOffsets);
          assertNotNull(committedOffsets.get(topicPartition));
          assertEquals(100L, committedOffsets.get(topicPartition)
            .offset());
      });
    kafkaConsumerService.shutdown();
}

By running the test above, we have successfully verified that the committed offset matches the total number of consumed messages.

5.3. Implementing a ConsumerRebalanceListener

We should note that it’s always good practice to implement ConsumerRebalanceListener in the consumer to commit any in-flight offset and clean any data.

Let’s implement the ConsumerRebalanceListener in the KafkaConsumer object in the KafkaConsumerService class:

consumer.subscribe(List.of(topic), new ConsumerRebalanceListener() {
    @Override
    public void onPartitionsRevoked(Collection<TopicPartition> partitions) {
        try {
            commitOffsets(partitions);
        } catch (Exception ex) {
            log.error("Commit failed during rebalance", ex);
        } finally {
            partitions.forEach(committableOffsets::remove);
        }
    }
    @Override
    public void onPartitionsAssigned(Collection<TopicPartition> partitions) {
        partitions.forEach(committableOffsets::remove);
    }
});

We’ll also need to implement the commitOffsets method to commit offsets for the specific partitions:

private void commitOffsets(Collection<TopicPartition> partitions) {
    Map<TopicPartition, OffsetAndMetadata> toCommit = new HashMap<>();
    partitions.forEach(tp -> {
        AtomicLong ref = committableOffsets.get(tp);
        if (ref != null) {
            long val = ref.get();
            if (val != -1L) {
                toCommit.put(tp, new OffsetAndMetadata(val));
            }
        }
    });
    if (toCommit.isEmpty()) {
        return;
    }
    consumer.commitSync(toCommit);
}

In the code above, we’re committing the offset by creating a snapshot map from the specific partition’s offset.

Now, let’s run the previous section’s test method to verify the offset for the updated consumer implementation:

13:01:21.571 [virtual-158] INFO  c.b.k.c.f.async.KafkaConsumerService - Simulating a db call - record key x199 value test99

From the test above, we confirm that all messages were processed and committed.

5.4. Best Practices

While we cannot prevent exceptions entirely, we can protect the system from any reprocessing duplication, data loss, or silent message drops.

We should implement idempotency on both the producer and the consumer, validate database constraints, and ensure side-effect-free reprocessing. Additionally, we should send the failed messages to a retry or DLQ topic.

6. Conclusion

In this article, we learned about one of the common offset commit-related exceptions in the Consumer application. We explored why the resulting CommitFailedException happens and how to prevent it. We also implemented a preventive solution by tuning the maximum poll interval and switching to asynchronous processing logic.

As always, the example code can be found over on GitHub.

       

1. Overview

Hibernate 7.2 introduces first-class regular expression support in HQL via the like regexp operator. Before this addition, matching a string column against a non-trivial pattern meant writing a native query. This new operator delegates regex matching to the database engine, avoiding native queries and post-filtering in Java.

In this tutorial, we’ll walk through a small Spring Boot example that demonstrates like regexp. We’ll look under the hood to understand how Hibernate translates it to SQL and what happens when the underlying database doesn’t support regex.

2. Preparing a Simple Spring Boot Example

Before we can demonstrate the like regexp operator, we need a tiny project to run queries against. We’ll set up the dependencies, an entity, some seed data, the application properties, and a Spring Data repository. For simplicity, we’ll not show all the code here.

2.1. Dependencies

Our project uses Spring Boot 3.3 as its parent. Spring Boot 3.3’s BOM pins Hibernate to 6.5, so we override the version and a couple of its transitive dependencies that Hibernate 7 requires newer versions of:

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.4.2.Final</version>
</dependency>
<dependency>
    <groupId>org.jboss.logging</groupId>
    <artifactId>jboss-logging</artifactId>
    <version>3.6.1.Final</version>
</dependency>
<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <version>3.2.0</version>
</dependency>

Beyond that, we pull in the usual spring-boot-starter-data-jpa and the H2 driver, as we’ll use the H2 in-memory database to keep the demo self-contained.

2.2. The Entity

We’ll keep things minimal with a single-column entity:

@Entity
public class Message {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String content;
    // constructors, getters ...
}

2.3. Seed Data

We load test data through Spring’s data.sql mechanism. The values are short phrases designed to exercise regex patterns:

INSERT INTO message (content) VALUES ('quick brown fox jumps over');
INSERT INTO message (content) VALUES ('hello world from spring boot');
INSERT INTO message (content) VALUES ('Order 1234 shipped on Monday');
INSERT INTO message (content) VALUES ('Please call 555 today');
INSERT INTO message (content) VALUES ('ERROR connection refused remotely');
INSERT INTO message (content) VALUES ('warning low disk space detected');

2.4. Application Properties

The test profile (application-test.yaml) wires up H2 and asks Spring to run data.sql after Hibernate creates the schema:

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    ...
  jpa:
    database-platform: org.hibernate.dialect.H2Dialect
    hibernate:
      ddl-auto: create-drop
    defer-datasource-initialization: true
    show-sql: true
    ...
  sql:
    init:
      mode: always

The defer-datasource-initialization: true setting ensures that data.sql runs after the schema is created. It’s also worth mentioning that we enabled show-sql option to log translated SQL. This helps us understand how the like regexp operator works. We’ll discuss it later.

2.5. The Repository

The repository is the part we’ll actually be exercising. It declares a pair of HQL queries using the new like regexp/not like regexp operators:

public interface MessageRepository extends JpaRepository<Message, Long> {
    @Query("select m from Message m where m.content like regexp :pattern")
    List<Message> findByContentMatchingRegex(@Param("pattern") String pattern);
    @Query("select m from Message m where m.content not like regexp :pattern")
    List<Message> findByContentNotMatchingRegex(@Param("pattern") String pattern);
}

As always, we’ll use unit tests to demonstrate how each operator behaves.

3. Demonstration

In our defined repository methods, the pattern parameter accepts a full regex pattern. To find every message that contains at least one digit, we use .*\d+.*:

@Test
void givenContainsDigitRegex_whenLikeRegexp_thenReturnsMatching() {
    List<Message> results = repository.findByContentMatchingRegex(".*\\d+.*");
    assertThat(results)
      .extracting(Message::getContent)
      .containsExactlyInAnyOrder(
        "Order 1234 shipped on Monday",
        "Please call 555 today");
}

Similarly, if we pass the same regex to the findByContentNotMatchingRegex() method, we’ll get all rows that don’t contain any digits.

@Test
void givenContainsDigitRegex_whenNotLikeRegexp_thenReturnsNonMatching() {
    List<Message> results = repository.findByContentNotMatchingRegex(".*\\d+.*");
    assertThat(results)
      .extracting(Message::getContent)
      .containsExactlyInAnyOrder(
        "quick brown fox jumps over",
        "hello world from spring boot",
        "ERROR connection refused remotely",
        "warning low disk space detected");
}

If we run these two tests, they will pass. The same pattern parameter drives both variants, so we don’t need a separate regex for each side of the predicate. Next, let’s understand how Hibernate’s like regexp operator works under the hood.

5. Under The Hood

Having seen the operator in action, let’s look at how Hibernate actually implements it and where the portability boundaries lie.

5.1. How like regexp Is Translated

When Hibernate parses m.content like regexp :pattern, it doesn’t translate to a LIKE statement at all. Instead, it routes the predicate through a Semantic Query Model (SQM) function that each dialect registers under the name regexp_like. The default H2Dialect maps regexp_like(x, y) to H2’s regexp_like(x, y) SQL function, so if we check the log output of the example test above, we can see the translated SQL:

select m1_0.id, m1_0.content
from message m1_0
where regexp_like(m1_0.content, ?)

In other words, like regexp is syntactic sugar at the HQL level, while the heavy lifting happens in the database. Other dialects bind the same SQM function to whatever native construct they support, such as REGEXP_LIKE in Oracle, the ~ operator in PostgreSQL, REGEXP in MySQL, and so on.

Some dialects, for example, SQL Server prior to 2025, have no native regular expression function at all. In that case, the dialect simply doesn’t register regexp_like, and any HQL using like regexp fails at SQL execution time because Hibernate emits a call to a function the database doesn’t know.

5.2. The Portability Caveat

Because each dialect delegates to the database’s native regex engine, the flavor of regex we can use is whatever the underlying database supports. Let’s see a few examples:

• H2 uses java.util.regex (Perl-compatible, Matcher.find() semantics — no implicit anchoring).
• PostgreSQL uses POSIX regular expressions, which differ in subtle ways. For example, it has no \d shorthand without the embedded (?x) flag.
• Oracle uses POSIX with a few extensions and does not support \d either. We must write [[:digit:]] or [0-9] instead.
• MySQL (8.x) uses ICU regex, again with its own quirks.

So while the HQL stays portable, the patterns we feed into like regexp generally don’t. For example, a regex tested against H2 may fail or behave differently when the application is pointed at Oracle. If our application targets multiple databases, we should stick to a conservative regex subset.

6. Conclusion

Hibernate 7.2’s like regexp operator lets us express regex predicates directly in HQL and have them pushed down to the database without resorting to native queries. The HQL surface is portable across dialects, but the actual regex flavor depends on the underlying database engine.

As always, the full source code is available over on GitHub.

       

1. Introduction

Bean background initialization in the Spring Framework provides a way to initialize selected beans asynchronously during application context startup. Instead of blocking the startup process on every bean initialization, Spring initializes selected beans in the background and continues processing the remaining application context. This improves application startup time and reduces perceived latency in applications with expensive initialization logic.

In this tutorial, we’ll explore how Bean background initialization works using the Spring native bootstrap attribute. We’ll demonstrate how to configure it correctly, how Spring manages lifecycle consistency during asynchronous initialization, and how this approach improves startup performance in real-world applications that rely on heavy resources such as caches, external services, or computation-heavy components.

2. Why Background Initialization Matters in Spring

Spring initializes singleton beans during the ApplicationContext refresh phase in a strictly synchronous manner. During startup, the container manages the complete bean lifecycle and processes each bean in sequence:

1. bean instantiation
2. dependency injection
3. initialization callback execution
4. marking the bean as ready for use

This approach provides predictable and deterministic startup behavior by ensuring that each bean reaches a fully initialized state before the context refresh proceeds. However, it introduces performance constraints when beans execute expensive operations during initialization.

2.1. Synchronous Bean Initialization Model

Expensive initialization increases the duration of the ApplicationContext refresh phase by forcing the container to complete the lifecycle of each bean before moving forward. It reduces throughput in the bean creation pipeline and increases overall startup latency. As a result, even non-critical initialization logic delays the application from becoming available.

2.2. Single-Threaded Initialization Bottleneck

The default startup model executes all bean initialization on the same thread that drives the context refresh process. Consequently, Spring executes independent initialization tasks sequentially and prevents them from running concurrently. This limits startup throughput and prevents Spring from taking advantage of available parallelism during application bootstrap.

3. Background Initialization Mechanism

Spring introduces background initialization using the bootstrap attribute to reduce startup blocking caused by expensive singleton bean creation.

During application context refresh, Spring applies a modified execution strategy to selected beans:

• Async delegation: Spring delegates the initialization phase of selected beans to a container-managed executor (the bootstrap executor), enabling execution to occur on a separate thread without blocking the main refresh process.
• Dependency coordination: When another bean depends on a background-initialized bean through a non-lazy dependency, Spring suspends dependency resolution for that bean and waits for initialization to complete before injecting the bean.
• Lifecycle preservation: Spring preserves the standard lifecycle order.

This design ensures safe background execution while decoupling heavy initialization from the main startup thread, enabling earlier application readiness without affecting bean consistency.

4. Example Setup

This section introduces a product preload class that simulates an expensive startup workload in Spring applications. This can be cache warming, dataset loading, or external resource preparation, which typically increases application startup time.

Let’s define the class to demonstrate this behavior:

public class ProductCatalogInitializer {
    public ProductCatalogInitializer() {
        loadProducts();
    }
    private void loadProducts() {
        System.out.println("Starting product preload");
        try {
            Thread.sleep(5000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        System.out.println("Product preload completed");
    }
    public String getStatus() {
        return "Catalog ready";
    }
}

The loadProducts() method represents a long-running initialization task executed during bean creation. Spring runs this logic on the main startup thread, which blocks the ApplicationContext refresh until completion.

This component acts as the baseline for demonstrating how Spring shifts such initialization work to background execution using the bootstrap mechanism in the next section.

5. Background Initialization Using Bootstrap Mode

Spring applies background initialization at the bean definition level using the bootstrap attribute. Selected beans then get initialized concurrently without blocking the main startup thread.

5.1. Enabling Background Initialization

At this point, let’s create a configuration that marks ProductCatalogInitializer as a Spring-managed bean and enables background initialization using BACKGROUND bootstrap mode:

@Configuration
public class AppConfig {
    @Bean(bootstrap = Bean.Bootstrap.BACKGROUND)
    public ProductCatalogInitializer productCatalogInitializer() {
        return new ProductCatalogInitializer();
    }
}

Spring detects the BACKGROUND bootstrap mode and offloads bean initialization to a container-managed bootstrapExecutor, allowing it to run on a separate thread instead of blocking the main application context refresh. Hence, this mechanism relies on a configured bootstrap executor. Without it, Spring can’t execute background initialization, and the affected beans fall back to normal synchronous initialization during startup.

5.2. Bean Injection

A background-initialized bean can be injected into other Spring-managed components in the same way as any standard singleton bean, since background initialization doesn’t change the core dependency injection model.

In most cases, direct injection remains sufficient because Spring coordinates the lifecycle and ensures that the bean becomes fully available within the application context startup phase. However, in scenarios where access may occur before the initialization process has completed, Spring provides ObjectProvider as an optional mechanism for deferred retrieval of the bean at runtime.
To that end, let’s create a service that demonstrates the injection of a background-initialized bean:

@Service
public class ProductService {
    private final ObjectProvider<ProductCatalogInitializer>
            initializerProvider;
    public ProductService(
            ObjectProvider<ProductCatalogInitializer> initializerProvider) {
                this.initializerProvider = initializerProvider;
    }
    public void printStatus() {
        ProductCatalogInitializer initializer = initializerProvider.getObject();
        System.out.println("Bean status: " + initializer.getStatus());
    }
}

Now, the dependency isn’t resolved during bean creation. Instead, Spring retains the reference and defers resolution until getObject() is invoked. At that point, the actual bean instance is retrieved, so access occurs only after background initialization has completed, while the injection phase remains independent of startup timing.

5.3. Application Startup Behavior with Background Initialization

With BACKGROUND bootstrap mode enabled, Spring offloads selected bean initialization to a background thread, allowing the application context refresh to proceed without waiting for these beans. As a result, startup becomes non-blocking for the selected initialization workload, while execution continues in parallel.

Despite this, non-lazy background-initialized beans remain part of the Spring container lifecycle, and their completion is coordinated within the overall startup process.

5.4. Performance Impact

This behavior directly reduces startup latency. Spring moves heavy bean initialization off the main refresh thread. As a result, the application becomes operational earlier while background tasks continue executing in parallel. Beans that load large caches, establish connection pools, or run schema validation benefit the most.

6. Conclusion

In this article, we explored background initialization in the Spring Framework using the BACKGROUND bootstrap mode, which enables selected beans to initialize asynchronously during application context refresh.

The mechanism decouples expensive bean initialization from the main startup thread while preserving the Spring lifecycle semantics. Rather than launching uncontrolled threads, Spring keeps full awareness of bean dependencies. If a non-lazy bean depends on one that is still initializing in the background, Spring ensures it waits, preventing access to incomplete or half-built objects. In addition, using ObjectProvider helps delay bean retrieval until it is actually needed, adding an extra layer of safety for early-access scenarios.

This approach improves application startup responsiveness in systems with heavy initialization workloads by enabling parallel execution during context refresh. It maintains dependency safety and lifecycle consistency while reducing blocking on the main thread. Background initialization is best suited for non-critical beans such as cache warmers, external integrations, and data preloading components.

The code backing this article is available over on Github.

       

1. Introduction

In this tutorial, we’ll take a look at jCasbin – the Java official port of the popular Apache Casbin authorization library. We’ll see what it is, how to use it and what we can do with it.

2. What is jCasbin

jCasbin is the Java version of the powerful Casbin access control library. This allows us to easily answer questions about access to resources within our applications.

jCasbin, and the entire suite of Casbin libraries, work using a configuration model that allows us to describe the access control model we want to use – such as ACLs or RBAC – and a separate set of policy data applied to that configuration model.

Typically, this works by defining:

• Objects that we want to control access to.
• Subjects who want to access these objects.
• Actions that the objects want to perform.

However, jCasbin is flexible enough that we can use any structure we want, as long as we can model it correctly in our configuration and policy data.

3. Dependencies

Before using jCasbin, we need to include the latest version in our build, which is 1.99.0 at the time of writing.

If we’re using Maven, we can include this dependency in our pom.xml file:

<dependency>
    <groupId>org.casbin</groupId>
    <artifactId>jcasbin</artifactId>
    <version>1.99.0</version>
</dependency>

At this point, we’re ready to start using it in our application.

4. Creating an Enforcer

Once we have jCasbin in our application, we’re ready to use it. The central class for this is the Enforcer. Constructing this requires two data sources: our configuration model and our policy data. The easiest way to manage this is through passing in filenames:

Enforcer enforcer = new Enforcer("path/to/model.conf", "path/to/policy.csv");

However, having our policy data be a local file can be difficult. As such, jCasbin allows the use of Adapters here instead. These provide a means to load and manipulate the policy data from any data source we like. We also have a set of standard adapters that can be used for our application. These include familiar technologies such as JDBC, Hibernate, MongoDB and many others:

Adapter jdbcAdapter = new JDBCAdapter(dataSource);
Enforcer enforcer = new Enforcer("path/to/model.conf", jdbcAdapter);

Exactly how these adapters work depends on the adapter in question and is out of scope of this article.

When specifying policy data as a filename, this internally uses the FileAdapter instead. We can also use this to load files available from other sources by providing an InputStream:

FileAdapter fileAdapter = new FileAdapter(getClass().getResourceAsStream("/com/baeldung/jcasbin/policy.csv"));
Enforcer enforcer = new Enforcer("path/to/model.conf", fileAdapter);

In exactly the same way, we can provide our model data using a Model instance instead. This allows us to load our model data from alternative sources:

String content = new String(getClass().getClassLoader().getResourceAsStream("com/baeldung/jcasbin/model.conf").readAllBytes());
Model model = new Model();
model.loadModelFromText(content);
Enforcer enforcer = new Enforcer(model, "path/to/policy.csv");

Once we’ve created our Enforcer, we’re ready to start using it to check permissions.

5. Enforcing Permissions

Now that we’ve got our Enforcer, we can start checking permissions. We do this using the enforce() method. This typically involves passing in our subject, object, and action to check:

if (enforcer.enforce("alice", "data1", "read")) {
    // permit alice to read data1
} else {
    // deny the request
}

Note that the enforce() method actually takes an arbitrary set of objects, depending on how our configuration model is defined.

The exact way permission checking works then depends on both the structure of our configuration model and our policy data.

5.1. Access Control Lists

One of the easiest ways to configure jCasbin is through Access Control Lists (ACLs). A typical configuration model might look like this:

# Request definition
[request_definition]
r = sub, obj, act
# Policy definition
[policy_definition]
p = sub, obj, act
# Matchers
[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
# Policy effect
[policy_effect]
e = some(where (p.eft == allow))

Here, the request_definition section tells us what the shape of the data passed into enforcer.enforce() should be. It gives us names for the parameters we pass in – here, “sub”, “obj” and “act” are used as shorthand for “subject”, “object” and “action”.

The policy_definition section then uses the exact same names to map onto the policy data. If not specified, there’s also an implicit value called “eft” – short for “effect” – which defaults to “allow”.

The matchers section then explains how we can match policy rows to requests. In this case, we’re simply saying that every field must have exactly the same value.

Finally, the policy_effect section tells us how to determine the overall effect of our policy. The action is only allowed if this returns a positive match.

In this mode, our policy data is a straight list of subjects, objects and allowed actions – as defined by our policy_definition:

p, alice, data1, read
p, bob, data2, write

This indicates that the subject “alice” can perform the action “read” on the object “data1”, whereas the subject “bob” can perform the action “write” on the object “data2”.

assertTrue(enforcer.enforce("alice", "data1", "read"));
assertTrue(enforcer.enforce("bob", "data2", "write"));

Any other checks are rejected because they don’t match our configuration.

5.2. Super Users

Sometimes we might want super users – users who can do anything regardless of what the policy data specifies.

We express this in our configuration model by adjusting how the matchers section is defined:

[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act || r.sub == "root"

Here, in addition to the same matching as before, we also match when the subject has the exact value “root”, regardless of what the rest of the policy expression says. Using this, a subject of “root” will always pass every check regardless:

assertTrue(enforcer.enforce("root", "data2", "write"));

This introduces some risks into our permission checks, so we need to use it carefully.

5.3. Role-Based Access Control

Role-Based Access Control (RBAC) introduces an additional layer of indirection into our configuration model. In this case, we assign roles to users, and can define permissions based on roles.

We start by adding a role_definition section:

[role_definition]
g = _, _

This defines the g() function that we can use to define role membership.

We also need to update our matchers section to make use of this:

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

Instead of directly comparing the policy subjects with the request, this says they must match via the role definitions.

We can now make use of this within our policy data:

p, alice, data1, read
p, data2_admin, data2, read
p, data2_admin, data2, write
g, bob, data2_admin

All of our rows that start with p define how permissions are assigned, either directly to users or else to roles. Here we’re assigning one permission directly to the subject “alice”, and two permissions to the role “data2_admin”.

The rows starting with g – from our role_definition section above – define how role membership works. Here, we’re defining that the subject “bob” is assigned the role “data2_admin”. This then means that this subject implicitly has all of the permissions assigned to this role as well:

assertTrue(enforcer.enforce("bob", "data2", "write"));

We can also nest roles. That is, we can assign one role to another, generating an entire hierarchy of permissions:

g, superuser, data2_admin
g, carol, superuser

Here, the role “data2_admin” has been assigned to the role “superuser”, and the role “superuser” has been assigned to the subject “carol”. This means that this subject has all the permissions all the way up:

assertTrue(enforcer.enforce("carol", "data2", "read"));

We never gave “carol” permission on “data2” – either directly or indirectly. Instead, she inherited it through her role “superuser”.

6. Management API

In addition to checking permissions, we also have management APIs for working with our setup.

We do this from the same Enforcer instance that we’ve already been using.

6.1. Querying Subjects, Objects and Actions

The easiest thing we can do is query all the subjects and objects in our policy data. We do this using the getAllSubjects(), getAllObjects() and getAllActions() methods:

List<String> subjects = enforcer.getAllSubjects();
List<String> objects = enforcer.getAllObjects();
List<String> actions = enforcer.getAllActions();

We can also query the actions that any given subject can perform on any given object:

Set<String> subjects = enforcer.getPermittedActions("alice", "data1");

This works correctly for both ACL and RBAC setups, as well as for hierarchical roles.

6.2. Querying RBAC Roles

With an RBAC setup, we can also query exactly which roles are assigned to which subjects:

List<String> roles = enforcer.getRolesForUser("carol");
// superuser

This returns only the roles directly assigned, not those included in the configured hierarchy.

However, we can also query which roles are assigned to other roles in the same way:

List<String> roles = enforcer.getRolesForUser("superuser");
// data2_admin

This means we can traverse the hierarchy if needed.

6.3. Managing Permissions and Roles

We also have a set of methods we can use to directly manage the permissions and roles that subjects have.

We can directly add and remove permissions between a subject and an object:

enforcer.addPermissionForUser("alice", "data2", "read");
enforcer.deletePermissionForUser("alice", "data2", "read");

These apply directly once called, and permission checks take effect straight away.

When we’re working in RBAC mode, we can additionally add and remove roles from subjects:

enforcer.addRoleForUser("alice", "superuser");
enforcer.deleteRoleForUser("alice", "superuser");

We apply all of these changes in memory. We need to use the savePolicy() method to write them back to our backing store:

enforcer.savePolicy();

However, we can only do this if we’re using certain adapters. It also depends on how the data was loaded. For example, we can’t write back if we loaded from an InputStream.

7. Summary

In this article, we took a very quick look at jCasbin. There’s a lot more that we can do with this. Next time you need to manage access controls for your applications, why not give it a try?

As always, all the code from this article is available over on GitHub.

       

1. Overview

The @EmbeddedTable annotation is a new Hibernate feature that simplifies the logic of mapping an embedded object to a secondary table.

In this short tutorial, we’ll shed light on the annotation and delve into its usage. First, we’ll start with some insight into the motivation behind @EmbeddedTable. Then, we’ll demonstrate how to use it in practice.

2. The Problem With Traditional Mapping

Before this new annotation, JPA provided multiple annotations to map a single entity into multiple tables. However, this traditional approach requires @SecondaryTable, @Embedded, @Embeddable, and multiple @AttributeOverride annotations to override each column individually. This can quickly become verbose as the number of columns grows.

Let’s say we have a single Person entity that stores personal and address information. Here, we assume that we want to store the address details in a separate secondary table.

First, let’s create the Address object we want to embed inside the Person entity:

@Embeddable
public class Address {
	
    private String street;
    private String city;
    private String code;
    // setters
    
}

Now, we create the Person entity:

@Entity
@SecondaryTable(name = "person_address")
public class Person {
    
    @Id
    private int id;
    
    @Column(name= "first_name")
    private String firstName;
    
    @Column(name = "last_name")
    private String lastName;
    
    @Embedded 
    private Address address;
    // setters
}

That’s not all, as mapping the Address fields to a secondary table requires the @AttributeOverride annotation for each field:

@Embedded 
@AttributeOverride(name = "street", column = @Column(table = "person_address")) 
@AttributeOverride(name = "city", column = @Column(table = "person_address"))
@AttributeOverride(name = "code", column = @Column(table = "person_address"))
private Address address;

This approach quickly becomes cumbersome and error-prone since missing a single override can silently map a column to the wrong table. So, this is where @EmbeddedTable comes into play.

3. Using @EmbeddedTable

Starting with Hibernate 7.2, we can implement the same mapping we did in the previous section far more concisely with @EmbeddedTable:

@EmbeddedTable(value = "person_address")
private Address address;

In a nutshell, Hibernate automatically maps every field of the embedded object Address to the specified secondary table person_address without overriding each one individually.

This is particularly useful when dealing with large embeddable objects containing several fields.

So, let’s add a test case to confirm that everything works:

@Test
void whenUsingEmbeddedTableThenMapIntoTwoSeparateTables() {
    Address address = new Address();
    address.setStreet("12 Av. Tamassint center");
    address.setCity("Tamassint");
    address.setCode("10000");
    Person person = new Person();
    person.setId(1);
    person.setFirstName("Azhrioun");
    person.setLastName("Abderrahim");
    person.setAddress(address);
    session.persist(person);
    session.flush();
    Object[] addressRow = (Object[]) session.createNativeQuery(
      "select street, city from person_address",
      Object[].class
    ).uniqueResult();
    assertEquals("12 Av. Tamassint center", addressRow[0]);
    assertEquals("Tamassint", addressRow[1]);
    Object[] personRow = (Object[]) session.createNativeQuery(
      "select first_name, last_name from person",
      Object[].class
    ).uniqueResult();
    assertEquals("Azhrioun", personRow[0]);
    assertEquals("Abderrahim", personRow[1]);
}

As expected, the test case runs successfully.

4. The Limitations

Although convenient, there are a couple of points worth keeping in mind when using @EmbeddedTable.

First, it’s a Hibernate-specific annotation and not part of the Jakarta Persistence specification. If portability across JPA providers matters, the @AttributeOverride annotation is always the safer choice.

Additionally, @EmbeddedTable is marked @Incubating, which means the API is still evolving and not yet considered stable and mature.

Typically, @EmbeddedTable is intended for top-level embedded objects. So, using it on nested objects isn’t supported yet.

5. Conclusion

In this short article, we explored the new Hibernate @EmbeddedTable annotation.

Along the way, we learned that it provides a cleaner alternative to multiple @AttributeOverride annotations when mapping embedded objects to secondary tables.

The full source is available over on GitHub.

       

1. Spring and Java

>> The Coming Loop [lucumr.pocoo.org]

A frame for the next phase of AI-assisted development – an agent harness, which generates, runs, inspects, corrects, and repeat quickly enough that the system becomes genuinely useful instead of just impressive. Anecdotally I’ve been running one for a few months now A good read.

Also worth reading:

• >> Self-Correcting Structured Output in Spring AI 2.0 [spring.io]
• >> Better Tools for Immutable Data [inside.java]
• >> Behind the Scenes: Block 450 JVM Repositories into Monorepo to Reduce Dependency Drift [infoq.com]
• >> Jurassic JDK: Migrate or Extinct [foojay.io]
• >> On programming languages, targets, and platforms [frankel.ch]
• >> Kotlin Toolchain 0.11: The Next Step for Amper [jetbrains.com]
• >> Pi4J Drivers: Simplifying Sensor and Hardware Integration in Java [foojay.io]
• >> Systematic AI Coding: My Takeaways from the Eclipse Foundation Workshop in Brussels [foojay.io]
• >> Backups with Restic: 2-year retrospective [advancedweb.hu]
• >> So You Want To Define a Well-Known URI [mnot.net]
• >> Working Effectively with Claude Code [scottlogic.com]
• >> Sustainable acceleration and the Agentic Software Development Life Cycle [scottlogic.com]
• >> How Netflix Simplified Batch Compute with Kueue [netflixtechblog.com]
• >> Toward More Controllable AI Video Editing: An Early Research Exploration at Netflix [netflixtechblog.com]

Webinars and presentations:

• >> Quarkus Unpacked: Insights from the Foojay Podcast [foojay.io]
• >> Episode 60 “How JEPs Drive Java’s Evolution” [AtA] [inside.java]
• >> A Bootiful Podcast: My friend Francesco Ciulla on developer advocacy and more [spring.io]

Time to upgrade:

• >> Spring Boot 3.5.16 available now [spring.io]
• >> Spring Data 2025.0.13 released [spring.io]
• >> Emergency releases to fix CVE-2026-50559 in all supported streams [quarkus.io]
• >> Quarkus 3.36.3, 3.33.2.1, 3.27.4.1, and 3.20.6.2 [github.com/quarkusio]
• >> Vert.x 5.1.3 [github.com/eclipse-vertx]
• >> Elasticsearch 8.19.17 and 9.3.6 [github.com/elastic]
• >> Zuul v3.6.16 and v3.6.15 [github.com/Netflix]
• >> Micronaut Core 5.1.2 [github.com/micronaut-projects]
• >> Helidon 3.2.18 [github.com/helidon-io]
• >> WildFly 40.0.1 is released! [wildfly.org]

2. Pick of the Week

>> Old Software Was Fast Because It Had No Choice [yusufaytas.com]