1. Spring and Java

>> The Archaeologist’s Copilot [martinfowler.com]

Legacy systems don’t really come mapped. Not usually at least.

This writeup shows how a coding assistant can help investigate an unfamiliar codebase, reconstruct its architecture, and turn scattered evidence into useful documentation. A developer is a central part of this work.

Also worth reading:

• >> Making ServiceLoader usable: a provider factory [frankel.ch]
• >> Your Loom App Quietly Became a Thread Pool Again: A Field Guide to Virtual Thread Pinning [foojay.io]
• >> I Asked GitHub Copilot to Profile a Java App. It Found a Bug in My Heap Sizing, and Offered to Fix It [foojay.io]
• >> Guardrails with OPA Policies in Quarkus LangChain4j [quarkus.io]
• >> Temporal Is to Your Code What a Database Is to Your Data [foojay.io]
• >> When NOT TO USE Event-Driven Architecture (EDA) [foojay.io]
• >> “This Can’t Possibly Work”: What I Learned at a Temporal.io Workshop [foojay.io]

Webinars and presentations:

• >> Foojay Podcast #100: When a Podcaster Interviews Podcasters, and What They All Have in Common [foojay.io]
• >> Valhalla, Now! [nipafx.dev]
• >> Quarkus Insights #254: Domain-Driven Design and Hexagonal Architecture – Part 2 [quarkus.io]
• >> Spring Office Hours Podcast: S5E18 – The Latest from OpenAI, Anthropic and Spring AI 2.0 [spring.io]

Time to upgrade:

• >> BoxLang 1.15.0 Released: Blazing Fast Strings, Runtime Portability, and much more [foojay.io]
• >> Quarkus 3.37.3 – Maintenance release [quarkus.io]
• >> JHipster v9.2.0 [github.com/jhipster]
• >> Vert.x 5.1.5 and 4.5.30 [github.com/eclipse-vertx]
• >> Grails 7.2.1, 7.1.4, and 7.0.14 [github.com/apache]
• >> Micronaut Core 5.0.6, 5.1.6, and 3.10.10 [github.com/micronaut-projects]
• >> Piranha CMS Version 12.2 and Version 12.1 [github.com/PiranhaCMS]

2. Technical & Musings

>> Building Service Topology at Scale: Architecture, Challenges, and Lessons Learned [netflixtechblog.com]

This deep dive explains how Netflix builds a service-topology platform from multiple data sources, resolves conflicting signals, and turns the resulting graph into practical infrastructure. Interesting weekend read.

Also worth reading:

• >> Which Doc Format is Best for AI Specifications? [vanillajava.blog]
• >> The Tower Keeps Rising [pocoo.org]
• >> Okta SAML and Keycloak for ID-JAG Cross App Access [christianposta.com]
• >> DSLs Enable Reliable Use of LLMs [martinfowler.com]
• >> Choosing the right tool safety approach for coding agents [scottlogic.com]
• >> Measuring the Impact of Personalized Recommendations [medium.com]
• >> Adopting Agentic: Talks and Reflections from Our AI Engineering Event [scottlogic.com]

3. Pick of the Week

We’re now reaching the end of our Summer Sale:

>> Summer Sale – 30% Off in All Access

If you’re planning to join, now is a good time to get into the platform and start exploring.

       

1. Introduction

When we map entity relationships with Hibernate, a small mistake in a field declaration can prevent our application from booting up. A common example is the “org.hibernate.AnnotationException: Illegal attempt to map a non collection as a @OneToMany, @ManyToMany or @CollectionOfElements” error.

In this tutorial, we’ll look at why Hibernate throws this exception. Next, we’ll reproduce it with a simple mapping and walk through a couple of ways to fix it.

2. Understanding the Exception

Hibernate expects any field annotated with @OneToMany, @ManyToMany or @ElementCollection to be a collection-valued association. In practice, this means we must declare the field using one of the collection interfaces it recognizes:

• Collection or List: an ordered group that allows duplicate elements
• Set: a group that contains only unique elements
• Map: a set of key-value pairs, useful for associations based on keys

The reason for this requirement is that Hibernate manages these collections with its own implementation. When we persist an entity, Hibernate replaces that field value with a proxy that supports lazy loading and dirty checking. It can only do that if the field type is an interface it controls.

As such, when the annotation is used on a field that isn’t one of these interfaces, Hibernate can’t build that proxy. Therefore, it fails fast during startup and throws the AnnotationException.

3. Reproducing the Exception

Let’s reproduce the problem with a classic parent-child mapping. First, let’s define a Comment entity:

@Entity
public class Comment {
    @Id
    @GeneratedValue
    private Long id;
    private String text;
    // getters and setters
}

Now, let’s create a Post entity that owns many comments. Here, purposely declare the field with the concrete ArrayList type:

@Entity
public class Post {
    @Id
    @GeneratedValue
    private Long id;
    @OneToMany
    private ArrayList<Comment> comments = new ArrayList<>();
    // getters and setters
}

When Hibernate scans this mapping during building of the metadata at startup, it throws: org.hibernate.AnnotationException: Illegal attempt to map a non collection as a @OneToMany, @ManyToMany or @CollectionOfElements: com.baeldung.Post.comments

Note that newer Hibernate versions phrase the same message with @ElementCollection instead of the legacy @CollectionOfElements, but the cause is identical.

Even though ArrayList is technically a list, Hibernate rejects it because it’s a concrete class rather than a collection interface.

4. Fixing the Mapping

@Entity
public class Post {
    @Id
    @GeneratedValue
    private Long id;
    @OneToMany
    private List<Comment> comments = new ArrayList<>();
    // getters and setters
}

@Entity
public class Comment {
    @Id
    @GeneratedValue
    private Long id;
    @OneToMany
    private Post post;
}

@Entity
public class Comment {
    @Id
    @GeneratedValue
    private Long id;
    @ManyToOne
    private Post post;
}

       

1. Overview

Getting the current Java process ID helps with monitoring, logging, and system administration. Before Java 9, no standard API existed for this task. The platform has since filled this gap. Java 9 introduced the ProcessHandle API. Java 10 added getPid() to RuntimeMXBean. However, many older methods remain useful for specific scenarios.

In this tutorial, we’ll explore multiple ways to get the process ID of the current Java process.

2. The Pre-Java 9 Approach: Parsing the RuntimeMXBean Name

When using Java 8 or earlier, we can attempt to use ManagementFactory.getRuntimeMXBean().getName() to get the process ID. However, the string we get should be in the format PID@hostname. In this case, the PID is the numeric portion before the @ symbol.

So, let’s see how we can extract the PID from such a string:

import java.lang.management.ManagementFactory;
import java.lang.management.RuntimeMXBean;
public class ProcessIdUtil {
    
    public static String getProcessIdPreJava9() {
        String runtimeName = ManagementFactory.getRuntimeMXBean().getName();
        int index = runtimeName.indexOf('@');
        if (index < 1) {
            return null;
        }
        return runtimeName.substring(0, index);
    }
}

This approach has a significant limitation. According to the Java documentation, the returned name string can be any arbitrary string. The JVM implementation chooses what information to embed. While most JVMs include the PID in this format, we can’t guarantee it. This means the parsing approach may break on some JVM implementations or future versions.

3. Java 9+: ProcessHandle

Java 9 introduced the ProcessHandle interface as part of JEP 102 (Java Process API). It provides a direct, standardized way to access the native process ID. Moreover, we can access this interface from java.base with no extra dependencies.

The ProcessHandle.current() method returns a handle to the current process, and its pid() method returns the native process ID.

Let’s see this in action:

import java.lang.ProcessHandle;
    public static long getProcessIdJava9Plus() {
        return ProcessHandle.current().pid();
    }

The ProcessHandle API provides a type-safe long return value instead of a string and is part of the official Java standard library. This means we don’t need any external dependencies or vendor-specific hacks. Furthermore, the API is designed to be cross-platform.

4. Java 10+: RuntimeMXBean.getPid()

Later, Java 10 added a getPid() default method to the RuntimeMXBean interface. RuntimeMXBean.getPid() also returns the process ID directly as a long value without any string parsing.

Let’s see this in practice:

import java.lang.management.ManagementFactory;
import java.lang.management.RuntimeMXBean;
 
    public static long getProcessIdJava10Plus() {
        return ManagementFactory.getRuntimeMXBean().getPid();
    }

Here, we use one of the cleanest JMX-based approaches. This method is convenient because it uses the familiar ManagementFactory API. It’s also a default method, so it’s available on JVMs through the interface’s default implementation.

5. Creating a Version-Aware Utility

In practice, we can create a single utility method that works across different Java versions.

Let’s build a utility class that tries the most modern methods first and falls back to older ones as needed:

import java.lang.management.ManagementFactory;
import java.lang.management.RuntimeMXBean;
public class ProcessIdUtil {
    
    public static long getProcessId() {
        RuntimeMXBean runtimeMxBean = ManagementFactory.getRuntimeMXBean();
        
        if (isJavaVersionOrGreater(10)) {
            return runtimeMxBean.getPid();
        }
        
        if (isJavaVersionOrGreater(9)) {
            return ProcessHandle.current().pid();
        }
        
        String runtimeName = runtimeMxBean.getName();
        int index = runtimeName.indexOf('@');
        if (index > 0) {
            return Long.parseLong(runtimeName.substring(0, index));
        }
        
        throw new IllegalStateException("Cannot determine process ID");
    }
    
    private static boolean isJavaVersionOrGreater(int version) {
        String javaVersion = System.getProperty("java.version");
        if (javaVersion.startsWith("1.")) {
            javaVersion = javaVersion.substring(2);
        }
        int majorVersion = Integer.parseInt(javaVersion.split("\\.")[0]);
        return majorVersion >= version;
    }
}

In this code, we demonstrate version detection and graceful fallback. However, in modern Java development, we typically target a specific Java version. Put simply, the version-aware approach is most useful if we work with libraries that need to support multiple Java versions.

6. Conclusion

In this article, we explored different approaches to get the process ID in Java. Specifically, we saw how the  ManagementFactory.getRuntimeMXBean().getName() approach usually works for older Java versions, though it requires string parsing. Further, we also looked at the ProcessHandle.current().pid() method, which is a simple, type‑safe API in Java 9. Next, we tried RuntimeMXBean.getPid() from Java 10 – another convenient option. Finally, we created a version-aware way to provide a balance of compatibility and modern methods.

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

       

1. Overview

In this tutorial, we’ll look at several ways to log HTTP request and response bodies using a Spring MVC HandlerInterceptor without disrupting normal request handling.

In short, we’ll use a servlet filter, in particular the ContentCaching wrapper, to log details of a simple REST API.

2. Spring MVC Execution Chain

First, we need to learn about the stages of a request within the Spring MVC execution chain.

The chain starts with servlet filters, followed by the DispatcherServlet, the handler execution chain, and finally the HTTP message conversion layer.

We’re interested in the HandlerInterceptors, which are part of the handler execution chain.

2.1. Understanding HandlerInterceptor

After the request reaches the DispatcherServlet, Spring needs to resolve a handler and run the handler execution chain, which may include zero or more HandlerInterceptors. The chain contains preHandle(), then the controller and its related logic, followed by postHandle() and afterCompletion().

The behavior of postHandle() depends on the controller’s return type. When the controller returns a view, the response is still uncommitted, so postHandle() can still modify it. With @ResponseBody or ResponseEntity, however, the HTTP message converters write and commit the body before postHandle() runs, so the response is effectively read-only at that point.

2.2. Request and Response Bodies Are One-Shot

A characteristic of the Request and Response bodies is that both are represented as streams. Thus, once any component consumes the stream, it cannot be read again unless we explicitly save it in some buffer.

This is important because if a filter or interceptor reads the body before it reaches Spring’s HTTP Message conversion layer (HttpMessageConverter), the converter receives an empty stream, and @RequestBody deserialization fails:

Now we have all the elements to understand the underlying details and how Spring handles HTTP requests.

3. Example REST API

Let’s create a simple REST API that creates books using @RequestBody:

public record CreateBookRequest(String title, String author) { }
public record BookCreatedResponse(UUID id, String title, String author) { }
@RestController
@RequestMapping("/api/books")
public class BookController {
    @PostMapping
    public ResponseEntity<BookCreatedResponse> create(@RequestBody CreateBookRequest request) {
        BookCreatedResponse response = new BookCreatedResponse(
            UUID.randomUUID(),
            request.title(),
            request.author()
        );
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }
}

Now, the goal here is to log both the incoming CreateBookRequest and BookCreatedResponse records for every call with HTTP method, URI, and status.

4. ContentCaching Wrappers in a Filter

With Spring, we can use ContentCachingRequestWrapper and ContentCachingResponseWrapper to save the request and response content in a cache and expose it via getContentAsByteArray(). So even after we first read the stream, we don’t lose the content in subsequent layers.

To accomplish this, we’ll implement a servlet filter that gets registered to all requests by extending OncePerRequestFilter:

@Component
public class CachingHttpFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
      FilterChain filterChain) throws ServletException, IOException {
        ContentCachingRequestWrapper cachingRequest = new ContentCachingRequestWrapper(request);
        ContentCachingResponseWrapper cachingResponse = new ContentCachingResponseWrapper(response);
        try {
            filterChain.doFilter(cachingRequest, cachingResponse);
        } finally {
            cachingResponse.copyBodyToResponse();
        }
    }
}

Filters run before the DispatcherServlet, so we save everything before reaching the controller itself. Now let’s see how to use this cached value.

Notably, Spring already ships CommonsRequestLoggingFilter for request-side logging.

4.1. Logging Cached Bodies in HandlerInterceptor

To log the cached values, we implement HandlerInterceptor. Let’s build it step by step.

First, we declare the class and its logger:

@Component
public class HttpLoggingInterceptor implements HandlerInterceptor {
    private static final Logger log =
        LoggerFactory.getLogger(HttpLoggingInterceptor.class);
}

This is a Spring-managed component implementing HandlerInterceptor, so it can be registered later via WebMvcConfigurer.

Next, in preHandle(), we log only lightweight metadata — method and URI — and deliberately avoid touching the body stream, since the HttpMessageConverter hasn’t run yet and the cache isn’t populated:

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
  Object handler) {
    log.info("Incoming {} {}", request.getMethod(), request.getRequestURI());
    return true;
}

The right place to log the full request and response is afterCompletion(), because by that point, both the controller and the HttpMessageConverter have run, so the ContentCaching wrappers are fully populated:

@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
  Object handler, Exception ex) {
    String requestBody = extractRequestBody(request);
    String responseBody = extractResponseBody(response);
    log.info("HTTP {} {} status={} requestBody={} responseBody={}", request.getMethod(),
      request.getRequestURI(), response.getStatus(), requestBody, responseBody);
}

Finally, the helper methods read the cached bytes and convert them to a string. Both extract methods guard with an instanceof check. If we haven’t registered the filter or the wrapper isn’t present, they safely return an empty string. The encoding falls back to UTF-8 when the request or response doesn’t declare a charset:

private String getStringValueFromBuffer(byte[] buffer, String encoding) {
    if (buffer.length > 0) {
        try {
            return new String(buffer, encoding != null ? encoding : StandardCharsets.UTF_8.name());
        } catch (UnsupportedEncodingException ex) {
            return "[unknown-encoding]";
      }
    }
    return "";
}

We use this in the request extraction:

private String extractRequestBody(HttpServletRequest request) {
    if (request instanceof ContentCachingRequestWrapper wrapper) {
        byte[] buf = wrapper.getContentAsByteArray();
        return getStringValueFromBuffer(buf, request.getCharacterEncoding());
    }
    return "";
}

And we use it in the response extraction as well:

private String extractResponseBody(HttpServletResponse response) {
    if (response instanceof ContentCachingResponseWrapper wrapper) {
        byte[] buf = wrapper.getContentAsByteArray();
        return getStringValueFromBuffer(buf, response.getCharacterEncoding());
    }
    return "";
}

Notably, ContentCachingRequestWrapper doesn’t eagerly copy the request body. It only fills its cache when something actually reads the input stream, which happens when Spring’s HttpMessageConverter deserializes the @RequestBody.

4.2. Registering the HandlerInterceptor

Now the final thing left to do is to register this handler for all the incoming API calls:

@Configuration
public class WebConfig implements WebMvcConfigurer {
    private final HttpLoggingInterceptor loggingInterceptor;
    public WebConfig(HttpLoggingInterceptor loggingInterceptor) {
        this.loggingInterceptor = loggingInterceptor;
    }
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loggingInterceptor).addPathPatterns("/api/**");
    }
}

This configuration keeps logging separate from controller code and guarantees that all requests under /api/** pass through our HttpLoggingInterceptor.

4.3. Testing the Implementation

To verify our setup, we can write an integration test using MockMvc together with Spring Boot’s OutputCaptureExtension, which lets us assert against the log output produced during the test:

@SpringBootTest
@AutoConfigureMockMvc
@ExtendWith(OutputCaptureExtension.class)
class BookControllerLoggingUnitTest {
    @Autowired
    private MockMvc mockMvc;
    @Test
    void whenCreateBook_thenRequestAndResponseAreLogged(CapturedOutput output) throws Exception {
        String requestBody = """
          { "title": "Spring in Action", "author": "Craig Walls" }
        """;
        mockMvc.perform(post("/api/books")
          .contentType(MediaType.APPLICATION_JSON)
          .content(requestBody))
          .andExpect(status().isCreated());
        assertThat(output).contains("Incoming POST /api/books");
        assertThat(output).contains("HTTP POST /api/books status=201");
        assertThat(output).contains("\"title\":\"Spring in Action\"");
        assertThat(output).contains("\"author\":\"Craig Walls\"");
    }
}

5. Conclusion

In this article, we’ve seen how to log HTTP request and response bodies in a Spring MVC application without breaking @RequestBody deserialization.

We started by reviewing the request flow through the execution chain and the one-shot nature of HTTP body streams.

We then used ContentCachingRequestWrapper and ContentCachingResponseWrapper within a OncePerRequestFilter to buffer the request and response bodies, and finally read those buffers from a HandlerInterceptor in afterCompletion(), once the message converters had run and the response was complete.

As always, the source code for this article is available over on GitHub.

       

1. Overview

Tool-call reasoning improves the observability of AI agents by capturing the rationale behind LLM tool selection rather than simply recording which tool the model invokes.

Insight into agentic tool selection decisions helps developers debug agentic workflows, validate decision quality, and identify opportunities for prompt or tool design improvements. This transparency becomes increasingly important as agents grow more autonomous and interact with larger sets of tools.

In this tutorial, we’ll look at how the Embabel Agentic AI framework can be used to obtain this level of observability in our Java applications.

2. Tool Call Reasoning Using Spring AI

Before diving into how to use Embabel, let’s first consider how the problem is solved in the Spring AI Tool Argument Augmenter.

The Tool Argument Augmenter dynamically augments tool schemas with additional reasoning fields, such as innerThought or confidence. The result is improved observability into agent behavior without changing existing tool implementations.

In Spring AI, tools are defined using a JSON Schema that specifies the expected arguments. The LLM evaluates these schemas and decides which tool to invoke and which arguments to pass. Spring AI’s augmentation layer exploits this mechanism by extending the schema’s properties with additional properties visible to the model (i.e., schema augmentation).

An essential implementation feature is that the real tool definition, applied at the time of tool invocation, remains unchanged. The augmentation layer intercepts the tool-call payload, extracts the reasoning fields, removes them, and invokes the actual tool with only the expected arguments. The tool itself remains unaware of the augmentation.

The user receives tool-call reasoning details via a separate DTO (with properties innerThought and confidence).

2.1. Spring AI Solution Design Analysis

The design is strong in several areas.

First, it provides structured and machine-readable observability. Because reasoning fields are part of the schema, they are easier to evaluate, store, or feed into analytics pipelines.

Second, it remains largely non-invasive. Existing tools, including MCP tools and local @Tool methods, continue to work without modification.

Third, the solution leverages existing LLM capabilities instead of inventing proprietary reasoning APIs. Any model that supports structured tool calling can, in principle, support this approach.

However, the design also introduces trade-offs; a key limitation is that the exposed schema is no longer the actual contract. The LLM-facing schema contains fields that the underlying tool never actually accepts. Architecturally, this means that an augmented tool schema is not the same as the runtime tool method contract.

The approach introduces additional complexity through:

• Augmented DTOs
• Schema merging
• Augmented fields extraction
• Tool-wrapping infrastructure

This increases both conceptual overhead and coupling with Spring AI’s internal JSON Schema tool model.

3. Tool Call Reasoning Using a System Prompt

A simpler alternative is to define a standardized system-level protocol via prompting. When invoking a tool, the prompt should request the LLM to:

• Explain briefly why the tool is needed
• State what information is expected
• Provide a confidence level

This shifts reasoning capture from a schema-level contract to a prompt-level protocol—from structural enforcement to semantic guidance. In practice, schema augmentation enforces a hard contract (“fields must exist”), while prompting establishes a soft convention (“behave this way”).

Both approaches rely on model-generated explanations and therefore share the same variability in content and phrasing. The practical difference lies in output structure: schema augmentation enforces the presence of explicit fields, making explanations easier to capture and parse, whereas a prompt-based approach leaves them in semi-structured format.

The main advantage of the prompt-based approach is portability. Schema augmentation depends on framework-specific mechanisms (e.g., tool schema generation, callback providers, argument interception), whereas a system prompt relies only on a universal capability: sending instructions to the model. This makes it portable across other agentic frameworks such as Spring AI, LangChain4j, Semantic Kernel, OpenAI, Anthropic, and Google DeepMind.

Compared to the Spring AI augmentation approach, the prompt-based solution keeps the implementation simpler by avoiding synthetic schemas, augmentation DTOs, schema transformation, and custom tool-wrapping infrastructure.

Neither approach is universally superior—they embody different engineering trade-offs. In practice, a hybrid model often works best: use prompt-level protocols for general guidance and apply schema-level augmentation selectively where stronger guarantees are needed.

4. Tool Call Reasoning with Embabel

Embabel is an Agentic AI framework founded by Rod Johnson, creator of the Spring Framework. For introductory information about Embabel, please refer to the Baeldung article “Using the Embabel Agent Framework”. You can find the official Embabel documentation here, and more resources on Medium.

4.1. Quick Introduction to Embabel Modes

Embabel is a comprehensive framework for developing Agentic AI applications on the JVM. A key feature of Embabel is the employment of a fluent API with structured outputs in all modes – an important feature in the Agentic AI landscape for the JVM:

• Basic mode (without “thinking” or streaming)
• Thinking mode (details to follow)
• Streaming mode

We’ll explore the “thinking” mode, which serves as the foundation for the Tool Call Reasoning solution.

4.2. Embabel Agentic AI Dependencies

First, let’s define the major Embabel dependencies required for testing:

<!-- Embabel Agent Starter -->
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-openai</artifactId>
    <version>${embabel-agent.version}</version>
</dependency>
<!-- Embabel Agent Test Support -->
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-test-internal</artifactId>
    <version>${embabel-agent.version}</version>
    <scope>test</scope>
</dependency>

The embabel-agent-starter-openai dependency provides us with the core classes required to use OpenAI models with Embabel.

We also include embabel-agent-test-internal to allow us to use the AgentTestApplication test support class with our @SpringBootTest.

4.3. Thinking Mode Fluent API Concepts

Let’s introduce key concepts of the Embabel “thinking” mode fluent API:

ThinkingResponse<ParkingRecommendation> result = ai.withDefaultLlm()
  .withToolObject(tools)
  .withToolLoopInspectors(callbackTracker, loggingInspector)
  .withToolLoopTransformers(systemMessageTransformer)
  .thinking()
  .createObject(prompt, ParkingRecommendation.class);

Ai is a gateway to LLM connectivity; we can define the default Ai LLM in the configuration file or supply it explicitly.

ThinkingResponse is a wrapper object that includes a reference to the underlying business object, ParkingRecommendation, and so-called ThinkingBlocks with LLM reasoning.

withToolObject() is a reference to the ParkingTooling tool object (with details later in the article).

withToolInspectors() refers to optional callbacks, helpful for additional logging, metrics collection, etc. CallbackTracker collects statistics (counter of LLM calls, counter of tool calls, list of invoked tools), while ToolLoopLoggingInspector logs LLM and tool invocation details (for example: ToolLoopLoggingInspector – afterLlmCall: iteration=1, toolCalls=2, contentLength=1063, usage=prompt=834, completion=260)

withToolLoopTransformers()  demonstrates user-controlled conversation history management via ToolLoopTransformer. In this example, the transformer is configured with two system messages and always positions them at the top of the conversation history before LLM calls.

thinking() indicates a fluent API subtype as “thinking mode” and outputs ThinkingResponse, which wraps the business object, constructed by the API createObject().

Finally, the prompt variable contains our user message.

Thinking mode includes a few more APIs, including a very useful one, createObjectIfPossible(). In the scenario, if the LLM is not capable of creating the object, ThinkingResponse will still carry reasoning behind this fact.

4.4. Use Case

Our use case is an optimal parking solution finder subject to time and cost constraints. There would be three tools at our disposal:

• Free street parking locator
• Metered parking locator
• Garage reservation

The final thinking block explains the reasoning behind the recommendation, based on information gathered through probing multiple tools.

We will split the prompt into a generic, domain-neutral system message that can be used across a variety of business scenarios and a domain-specific user message.

Let’s specify the system message:

"""
CRITICAL WORKFLOW - Two-phase decision process:
=== PHASE 1: Tool Selection (First Response) ===
1. For EACH tool you plan to call, emit a SEPARATE <tool_use_reasoning> block:
    <tool_use_reasoning>
    Tool: [TOOL_NAME]
    Why THIS tool: [explain why this specific tool is needed]
    Information expected: [what this tool will reveal]
    Advantage over alternatives: [why this tool vs others]
    Confidence in this tool selection [confidence=0.XX]
    </tool_use_reasoning>
    Since you must call at least 2 tools, you must emit at least 2 separate blocks.
2. Call AT LEAST TWO tools to gather comprehensive information
    - You MUST call at least 2 tools to probe different aspects.
    - Tools are PROBES for information gathering, not final decisions.
    - Multiple probes provide better decision quality.
=== PHASE 2: Final Decision (After receiving tool results) ===
1. Emit final decision reasoning:
    <final_decision_reasoning>
    - What each tool probe revealed
    - How the probe results informed your analysis
    - Why you chose this option based on probe data and constraints
    Confidence: [confidence=0.XX]
    </final_decision_reasoning>
2. Then provide the final structured output
    - Your final recommendation should synthesize insights from multiple probes.
    - Never copy reasoning blocks into the final structured object.
REMINDER: One <tool_use_reasoning> block per tool call. At least 2 tools = at least 2 blocks.
Emit reasoning in BOTH phases.
"""

And let’s specify a user message:

"""
Scenario:
An advisor is driving to a client meeting in Midtown Manhattan.
Constraints:
- 30 minutes remain before the meeting starts
- arriving late is not acceptable
- the meeting is expected to last about 3 hours
Parking options:
- Street parking: free, but uncertain
- Metered parking: $5 per hour, typically limited to 2 hours
- Garage parking: $30 per hour, guaranteed availability
Important decision factors:
- available time before the meeting
- risk of arriving late
- trade-offs between street, metered, and garage parking
Recommend the best parking option.
Available tools: %s
"""

Next, we’ll supply the available tools.

4.5. Tool Definition

Let’s define the tool object:

static class ParkingTooling {
    @LlmTool(description = "Find free street parking. Uncertain and may take time.")
    public String findStreetParking(String location, int maxMinutes) {
        boolean found = ThreadLocalRandom.current().nextDouble() < 0.3; // low probability
        if (found) {
            return "Street parking found near " + location + " (free)";
        }
        return "No street parking found within " + maxMinutes + " minutes";
    }
    @LlmTool(description = "Find metered parking. Moderate cost and moderate availability. " +
        "May have time limits.")
    public String findMeterParking(String location, int maxMinutes) {
        boolean found = ThreadLocalRandom.current().nextDouble() < 0.6; // medium probability
        if (found) {
            return "Metered parking found near " + location + " ($5/hour, 2-hour limit)";
        }
        return "No metered parking found within " + maxMinutes + " minutes";
    }
    @LlmTool(description = "Reserve guaranteed garage parking near destination.")
    public String reserveGarage(String location) {
        return "Garage reserved near " + location + " ($30/hour, guaranteed)";
    }
}

Here, LlmTool is an Embabel tool annotation, which includes a tool description. Embabel allows us to expose tools to the LLM by implementing the Embabel Tool interface, or using annotated Java methods. Here, we see the latter approach.

4.6. Test Results Discussion

Our test ToolCallReasoningIntegrationTest invokes the LLM (which in turn invokes tools and summarizes tool selection recommendations) and logs results using custom logging functions.

We have a reportToolCallPattern() method that takes CallbackTracker as a parameter and logs tool pattern and statistics:

17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest - === TOOL CALL PATTERN ANALYSIS ===
Total LLM calls: 2
Unique tools: [findStreetParking, findMeterParking]
Total invocations: 2
Tool result callbacks: 2
Iterations with tool calls: 1
17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest - PATTERN: All 2 tools called in SAME iteration (parallel)
17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest - Thinking blocks captured: 3
17:26:33.876 [main] INFO  ToolCallReasoningIntegrationTest -   Block 1: tagType=TAG, tagValue=tool_use_reasoning, contentLength=481
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Tool: functions.findStreetParking
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Attributes: {confidence=0.85}
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -   Block 2: tagType=TAG, tagValue=tool_use_reasoning, contentLength=494
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Tool: functions.findMeterParking
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Attributes: {confidence=0.90}
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -   Block 3: tagType=TAG, tagValue=final_decision_reasoning, contentLength=755
17:26:33.877 [main] INFO  ToolCallReasoningIntegrationTest -     Attributes: {confidence=0.95}

Recommended: ParkingRecommendation[chosenOption=GARAGE, location=Midtown Manhattan, estimatedTotalCost=90, summary=Street parking is unavailable within 30 minutes and metered parking is limited to 2 hours, insufficient for a 3-hour meeting. Garage parking offers guaranteed availability and ensures timely arrival, making it the best option despite higher cost.]
Reasoning:
  ThinkingBlock(content=Tool: functions.findStreetParking
Why THIS tool: To check the availability and likelihood of finding free street parking near Midtown Manhattan within the 30-minute time constraint.
Information expected: Whether street parking is realistically available and how long it might take to find a spot.
Advantage over alternatives: Street parking is free and the cheapest option, but highly uncertain. Testing its feasibility is key before considering costlier options.
Confidence in this tool selection [confidence=0.9], tagType=TAG, tagValue=tool_use_reasoning)
  ThinkingBlock(content=Tool: functions.findMeterParking
Why THIS tool: To evaluate availability and feasibility of metered parking given the 2-hour limit and $5/hour cost within the 30-minute timeframe.
Information expected: Confirm if metered parking spots are available nearby and potential cost and time constraints.
Advantage over alternatives: Metered parking balances moderate cost and availability but with time limits, important to check if it fits the meeting duration.
Confidence in this tool selection [confidence=0.9], tagType=TAG, tagValue=tool_use_reasoning)
  ThinkingBlock(content=- The street parking probe revealed no available free street parking within the critical 30-minute arrival window, making this option too risky given the zero tolerance for lateness.
- Metered parking is available near the destination, but limited to 2 hours and costs $5/hour. This time limit is insufficient for the 3-hour meeting, so this option creates the risk of parking violation or disruption.
- Although not probed yet, garage parking guarantees availability and can cover the full 3-hour meeting, eliminating risk of lateness or parking issues at a higher cost ($30/hour).
- Given the importance of timely arrival and the meeting length, garage parking is the most reliable and suitable choice despite the cost premium.
Confidence: [confidence=0.95], tagType=TAG, tagValue=final_decision_reasoning)

Embabel returned a structured object of type ParkingRecommendation with all expected fields, including summary. 

Each ThinkingBlock includes an explanation of the tool selection, a tagType specifies the LLM reasoning format – in our case, this is XML TAG (could be PREFIX, or no tag), a tagValue=tool_use_reasoning, and a tagValue=final_decision_reasoning, which are the dynamic user-defined XML tags we specified in the system prompt. Please note two ThinkingBlocks, one for each tool call.

Finally, the ThinkingBlock with the recommendation was emitted, with placeholder confidence substituted, as expected.

The use of placeholders permits further automated processing for tool selection reasoning. The method extractAttributes() (please refer to the code linked to the article) scans a ThinkingBlock for attributes in [key=value] format and returns them as a Map of key-value pairs. For example, it converts text like [confidence=0.9] into an entry such as “confidence” -> 0.9.

Thus, Embabel’s thinking mode output is semi-structured.

5. Conclusion

In this article, we saw how Embabel provides a solution for tool selection reasoning by employing its “thinking” APIs.

While Spring AI provides out-of-the-box support for Tool Selection Reasoning, the solution has noticeable trade-offs. An alternative solution using Embabel is very simple and, unlike Spring AI, does not require hidden schema manipulations or the introduction of a custom DTO, and is fully built on the existing Embabel foundation APIs.

With Embabel, yet another solution using LLM Tool Loop callbacks is available, but it is outside the scope of this article.

The article code is available over on GitHub.

The author would like to thank Rod Johnson and Ajen Poutsma for their reviews and suggestions.

       

1. Overview

2. The HandlerInterceptor Interface

public interface FeatureFlagService {
    int rolloutPercentage();
}

public class DeliveryChargeInterceptor implements HandlerInterceptor {
    static final String USE_V2_ATTRIBUTE = "useV2";
    private final FeatureFlagService featureFlagService;
    private final SecureRandom random = new SecureRandom();
    private final Logger logger = LoggerFactory.getLogger(
      DeliveryChargeInterceptor.class
    );
    public DeliveryChargeInterceptor(FeatureFlagService featureFlagService) {
        this.featureFlagService = featureFlagService;
    }
    @Override
    public boolean preHandle(
      HttpServletRequest request,
      HttpServletResponse response,
      Object handler) throws Exception {
        if (handler instanceof HandlerMethod) {
            int rollout = featureFlagService.rolloutPercentage();
            boolean useV2 = rollout > 0 && random.nextInt(100) < rollout;
            request.setAttribute(USE_V2_ATTRIBUTE, useV2);
            logger.info(
              "Delivery charge feature: rollout={}%, useV2={}",
              rollout,
              useV2
            );
        }
        return true;
    }
}

@RestController
public class DeliveryChargesController {
    private final DeliveryChargeService deliveryChargeService;
    public DeliveryChargesController(DeliveryChargeService deliveryChargeService) {
        this.deliveryChargeService = deliveryChargeService;
    }
    @PostMapping("/delivery-charges/calculate")
    public double calculate(
      @RequestParam String postcode,
      HttpServletRequest request) {
        Boolean useV2 = (Boolean) request.getAttribute(
          DeliveryChargeInterceptor.USE_V2_ATTRIBUTE
        );
        if (Boolean.TRUE.equals(useV2)) {
            return deliveryChargeService.calculateV2(postcode);
        }
        return deliveryChargeService.calculateV1(postcode);
    }
}

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    private final FeatureFlagService featureFlagService;
    public WebMvcConfig(FeatureFlagService featureFlagService) {
        this.featureFlagService = featureFlagService;
    }
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new DeliveryChargeInterceptor(featureFlagService))
          .addPathPatterns("/delivery-charges/**");
    }
}

@WebMvcTest(controllers = DeliveryChargesController.class)
class DeliveryChargeInterceptorIntegrationTest {
    @Autowired
    private MockMvc mockMvc;
    @MockBean
    private DeliveryChargeService deliveryChargeService;
    @MockBean
    private FeatureFlagService featureFlagService;
}

@Test
void givenZeroRollout_whenCalculateDeliveryCharge_thenV1IsUsed() throws Exception {
    when(featureFlagService.rolloutPercentage()).thenReturn(0);
    when(deliveryChargeService.calculateV1("SW1A")).thenReturn(5.0);
    mockMvc.perform(post("/delivery-charges/calculate").param("postcode", "SW1A"))
      .andExpect(status().isOk())
      .andExpect(content().string("5.0"));
}

@Test
void givenFullRollout_whenCalculateDeliveryCharge_thenV2IsUsed() throws Exception {
    when(featureFlagService.rolloutPercentage()).thenReturn(100);
    when(deliveryChargeService.calculateV2("SW1A")).thenReturn(3.5);
    mockMvc.perform(post("/delivery-charges/calculate").param("postcode", "SW1A"))
      .andExpect(status().isOk())
      .andExpect(content().string("3.5"));
}

@Test
void givenPartialRollout_whenCalculateDeliveryCharge_thenBothVersionsAreUsed() throws Exception {
    when(featureFlagService.rolloutPercentage()).thenReturn(50);
    when(deliveryChargeService.calculateV1("SW1A")).thenReturn(5.0);
    when(deliveryChargeService.calculateV2("SW1A")).thenReturn(3.5);
    int v1Count = 0;
    int v2Count = 0;
    for (int i = 0; i < 20; i++) {
        String response = mockMvc.perform(
            post("/delivery-charges/calculate")
              .param("postcode", "SW1A")
          )
          .andExpect(status().isOk())
          .andReturn()
          .getResponse()
          .getContentAsString();
        if ("5.0".equals(response)) {
            v1Count++;
        } else if ("3.5".equals(response)) {
            v2Count++;
        }
    }
    assertThat(v1Count).isGreaterThan(0);
    assertThat(v2Count).isGreaterThan(0);
}

       

1. Spring and Java

Also worth reading:

• >> Nulling Out References Won’t Help Your Garbage Collector [foojay.io]
• >> Hardwood Promises High-Speed JVM Apache Parquet Processing with Zero Mandatory Dependencies [infoq.com]
• >> What’s New in actions/setup-java 5.4 and 5.5: Signature Verification, Kona JDK, and a Better Maven Experience [foojay.io]
• >> Demystifying Exposed: The Intelligent SQL Library for Kotlin [foojay.io]
• >> The Java Story: A Film About All of Us [foojay.io]
• >> Introducing the Kotlin Benchmark for AI Coding Agents [jetbrains.com]
• >> A New Home for Spring Cloud Contract: Transitioning to Stubborn.sh [spring.io]

Webinars and presentations:

• >> Episode 61 “Scripting JS and Python with Project Detroit” [AtA] [inside.java]
• >> A Bootiful Podcast: Spring Boot legend Moritz Halbritter on the latest and greatest in Spring Boot 4 and 4.1 [spring.io]
• >> Spring Office Hours Podcast: S5E17 – Spring Boot 4.1 with Phil Webb [spring.io]

Time to upgrade:

• >> Quarkus 3.37.2 – Maintenance release [quarkus.io]
• >> Vert.x 4.5.29 and 5.1.4 [github.com/eclipse-vertx]
• >> Zuul v4.0.0, v3.6.21, v3.6.20, and v3.6.19 [github.com/Netflix]
• >> Micronaut Core 5.1.5, 5.1.4, 5.0.5, and 4.10.26 [github.com/micronaut-projects]

2. Technical & Musings

Also worth reading:

• >> Two nasty surprises in Home Assistant’s config [frankel.ch]
• >> Better Models: Worse Tools [lucumr.pocoo.org]
• >> Airbnb Shares Architecture behind Sitar-Agent Dynamic Configuration Sidecar for Kubernetes Services [infoq.com]
• >> Experiences with local models for coding [martinfowler.com]
• >> Viability of local models for coding [martinfowler.com]
• >> GLM-5.2: Considerations for enterprise teams starting out with open-weight models [scottlogic.com]
• >> Auditable Agentic Orchestration: From Autonomous Systems to Governed Execution [scottlogic.com]

3. Pick of the Week

One more week:

>> The Summer Sale is Live

       

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.

       

Comments

• In reply to fantaman. Hey, Fantaman. Thanks for the ... by Ulisses Lima
• Wouldn't it make sense to also include the LLM answer in the ... by fantaman

 

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.