1. Introduction

The generative AI landscape is evolving rapidly, pushing framework maintainers to rethink how applications connect to diverse large language models (LLMs). With the release of Spring AI, Java developers gained a unified, portable interface to interact with cognitive services.

However, as the ecosystem matured, integrating multiple foundational models within a single runtime classpath introduced configuration conflicts. To solve this, Spring AI introduced major architectural updates. These include the specialized spring-ai-starter-model-google-genai starter module and an explicit model selection paradigm.

In this tutorial, we’ll explore how to integrate Google’s Gemini models into a Spring Boot application using the Gemini Developer API (via Google AI Studio). We’ll walk through a streamlined project setup, dive into text generation patterns using both low-level and high-level APIs, apply prompt templates, enable live web grounding, and stream tokens reactively with WebFlux.

2. Project Setup

To get started, we need a standard Spring Boot 3.x application. Because Spring AI modules are actively updated, it’s highly recommended to manage dependency versions using the Spring AI Bill of Materials (BOM).

2.1. Maven Dependencies

First, let’s configure the Spring AI Starter Google GenAI and Spring AI BOM in our pom.xml file. Since Spring AI artifacts are hosted in the Spring Milestones repository during release cycles, we ensure both the repository and dependency management blocks are properly declared:

<project>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>2.0.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-google-genai</artifactId>
        </dependency>
    </dependencies>
</project>

2.2. Activating the Chat Provider via spring.ai.model.chat

In the latest versions of Spring AI, dropping a starter module onto the classpath no longer automatically activates it. This prevents runtime configuration conflicts when your application references multiple LLM providers.

We must explicitly declare our active chat provider inside our application.properties file:

spring.ai.model.chat=google-genai
spring.ai.google.genai.chat.model=gemini-2.5-flash
spring.ai.google.genai.api-key=${SPRING_AI_GOOGLE_GENAI_API_KEY}

Obtain an API key from the Google AI Studio. Using this placeholder syntax explicitly documents the application’s external runtime dependency while preventing hardcoded secrets from leaking into our source control repository.

2.3. Environment Setup

We can satisfy the property placeholder defined above without writing any custom Java decryption or binding code. We’ll simply export the credentials directly into our environment. The auto-configuration engine will automatically resolve the placeholder value at startup:

export SPRING_AI_GOOGLE_GENAI_API_KEY="YourActualSecureGoogleAIStudioKeyHere"

Once this environment variable is set, Spring Boot seamlessly bridges the variable to the properties file placeholder, making the GoogleGenAiChatModel ready for injection.

3. Core Text and Content Generation Strategies

Spring AI gives us two primary abstraction layers for communicating with Gemini models: the foundational ChatModel bean and the highly configurable, fluent ChatClient API. We isolate our interaction logic into a dedicated service layer to follow enterprise design patterns and keep code clean. Then, we expose these capabilities through standard Spring REST controllers.

3.1. Injecting and Using GoogleGenAiChatModel

The GoogleGenAiChatModel represents the foundational, low-level client abstraction. It handles request serialization, HTTP execution against Google’s RPC endpoints, and raw response parsing.

Let’s look at our ChatService, where we inject this bean along with a ChatClient.Builder to initialize our operational layers:

@Service
public class ChatService {
    private final GoogleGenAiChatModel chatModel;
    private final ChatClient defaultChatClient;
    private final ChatClient fluentChatClient;
    public ChatService(GoogleGenAiChatModel chatModel, ChatClient.Builder chatClientBuilder) {
        this.chatModel = chatModel;
        this.defaultChatClient = chatClientBuilder.build();
        this.fluentChatClient = chatClientBuilder
          .defaultSystem("You are a concise technical writer summarizing software concepts.")
          .build();
    }
    public String simplifiedPrompt(String message) {
        return chatModel.call(message);
    }
}

When we invoke chatModel.call(message), the framework packages the raw string into a default prompt context. It then sends this to the configured model variant, extracts the text block from the response payload, and returns it. We expose this in our ChatController:

@RestController
public class ChatController {
    private final ChatService chatService;
    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }
    @GetMapping("/v1/chat/simple")
    public String simplifiedPrompt(@RequestParam(defaultValue = "Hello") String message) {
        return chatService.simplifiedPrompt(message);
    }
}

This establishes a simple string-in, string-out endpoint. It uses the lowest-level model client abstraction available to verify basic connectivity with the Gemini engine.

3.2. Constructing Prompts With the Fluent ChatClient API

While working directly with the model handles quick operations, production architectures favor the fluent ChatClient API. The ChatClient acts as a facade layer that simplifies prompt assembly and attaches default configuration baselines.

As shown in our service constructor, we pre-configured a specialized fluentChatClient with system instructions. Let’s add the corresponding execution method to ChatService:

public String fluentPrompt(String prompt) {
    return this.fluentChatClient.prompt()
      .user(prompt)
      .call()
      .content();
}

By routing requests through this pre-configured instance, every user query automatically appends the target system instructions before execution. We expose this endpoint in the controller:

@GetMapping("/v1/chat/fluent")
public String fluentPrompt(@RequestParam String prompt) {
    return chatService.fluentPrompt(prompt);
}

This allows us to encapsulate recurring personas or systemic behavior directly within the client wrapper instance. As a result, we don’t need to modify individual incoming text arguments manually.

3.3. Handling Dynamic Inputs via Prompt Templates

Hardcoding parameter logic directly inside strings leads to messy string concatenation and fragile codebases. Spring AI solves this with structured prompt templates, separating instructions from user variables.

Let’s implement a code review capability inside our ChatService using a multiline text block placeholder layout:

public String reviewCode(String language, String codeSnippet) {
    String template = """
            Analyze the following {language} code snippet for memory leaks or inefficiencies.
            Provide an optimized version.
            Code:
            {code}
            """;
    return this.defaultChatClient.prompt()
      .user(u -> u.text(template).params(Map.of("language", language, "code", codeSnippet)))
      .call()
      .content();
}

The client replaces the target tags ({language}, {code}) at runtime, formatting the text cleanly before submission. We expose this via a POST request wrapper in our controller:

@PostMapping("/v1/chat/review")
public String reviewCode(@RequestParam(defaultValue = "Java") String language, @RequestBody String codeSnippet) {
    return chatService.reviewCode(language, codeSnippet);
}

This pattern cleanly decouples structural prompt engineering boundaries from volatile business data, producing a highly reusable, parameter-driven invocation pattern.

3.4. Grounding Responses With Live Google Search Retrieval

LLMs naturally suffer from training cut-off windows and knowledge gaps regarding live, real-world developments. The Google GenAI module exposes an explicit grounding property to seamlessly connect our model with live Google Search indexing.

To activate live search grounding across our entire application, we need to toggle the grounding flag to true inside our configuration properties:

spring.ai.google.genai.chat.google-search-retrieval=true

When this property is enabled, queries regarding current events or breaking news are automatically grounded using fresh search results. Let’s write an endpoint to handle real-time informational requests:

public String searchGroundedPrompt(String currentEventQuery) {
    return this.defaultChatClient.prompt()
      .user(currentEventQuery)
      .call()
      .content();
}

We map this method to our HTTP layer inside our controller configuration:

@GetMapping("/v1/chat/grounded")
public String searchGroundedPrompt(@RequestParam String currentEventQuery) {
    return chatService.searchGroundedPrompt(currentEventQuery);
}

If we pass a request like “Who won the most recent football tournament match yesterday?”, the model uses live Google Search indexing to anchor its response in verified facts, drastically reducing hallucinations. This configuration bridges the gap between static training cutoffs and live, real-world events.

3.5. Processing Real-Time Streaming Responses With Flux

For user-facing interfaces, waiting for a long text block to fully generate on the server results in noticeable latency. Instead, we can stream chunks back to the user, token by token, using Spring Boot’s WebFlux integration.

Let’s add a streaming method to our ChatService that returns a reactive Flux<String> structure:

public Flux<String> streamChatTokens(String prompt) {
    return this.defaultChatClient.prompt()
      .user(prompt)
      .stream()
      .content();
}

We’ll create a specialized StreamingChatController to deliver these tokens cleanly over an open connection pipeline. This controller explicitly produces a text/event-stream media response:

@RestController
public class StreamingChatController {
    private final ChatService chatService;
    public StreamingChatController(ChatService chatService) {
        this.chatService = chatService;
    }
    @GetMapping(value = "/v1/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChatTokens(@RequestParam String prompt) {
        return chatService.streamChatTokens(prompt);
    }
}

When hitting this endpoint, consumers read token data reactively.  This establishes a non-blocking execution pipeline that builds an interactive, low-latency UI flow chunk by chunk.

4. Testing

Testing applications that rely on external generative AI endpoints requires a clear separation of concerns. Running tests shouldn’t trigger external network calls, hit rate limits, or exhaust API quotas during local compilation. To prevent this, we isolate our HTTP layer using Spring Boot’s slice testing along with @MockitoBean.

4.1. Unit Testing via WebLayer MockMvc Mocking

Since our implementation encapsulates all LLM communications within ChatService, we can completely mock this business component. This permits us to cleanly assert controller routing, request parameters, response body expectations, and stream-handling patterns.

Let’s write an isolated test using MockMvc to verify all text-based, template-driven, and reactive stream endpoints without triggering an actual network handshake. First, we set up our simple prompt test to verify basic GET parameter routing and raw response mapping:

@SpringBootTest(properties = {
    "spring.ai.model.chat=google-genai",
    "spring.ai.google.genai.chat.model=gemini-2.5-flash",
    "spring.ai.google.genai.api-key=test-key"
})
@AutoConfigureMockMvc
class ChatControllerUnitTest {
    @Autowired
    private MockMvc mockMvc;
    @MockBean
    private ChatService chatService;
    @Test
    void whenSimpleEndpointIsInvoked_thenReturnsMockedModelResponse() throws Exception {
        when(chatService.simplifiedPrompt(anyString())).thenReturn("Mocked Gemini Response");
        mockMvc.perform(get("/v1/chat/simple").param("message", "Hello"))
          .andExpect(status().isOk())
          .andExpect(content().string("Mocked Gemini Response"));
        verify(chatService).simplifiedPrompt("Hello");
    }
}

Next, we confirm that our fluent prompt endpoint forwards query parameters accurately to the underlying service. Then it returns the configured system-prompt-backed response:

@Test
void whenFluentEndpointIsInvoked_thenReturnsModelContent() throws Exception {
    when(chatService.fluentPrompt(anyString())).thenReturn("Fluent Response");
    mockMvc.perform(get("/v1/chat/fluent").param("prompt", "Explain DI"))
      .andExpect(status().isOk())
      .andExpect(content().string("Fluent Response"));
    verify(chatService).fluentPrompt("Explain DI");
}

For our template-driven endpoint, we validate that the controller correctly processes a multipart payload consisting of query parameters and a text/plain request body:

@Test
void whenReviewEndpointIsInvoked_thenReturnsModelContent() throws Exception {
    when(chatService.reviewCode(anyString(), anyString())).thenReturn("Optimized Code");
    mockMvc.perform(post("/v1/chat/review")
        .param("language", "Java")
        .contentType(MediaType.TEXT_PLAIN)
        .content("class A { }"))
      .andExpect(status().isOk())
      .andExpect(content().string("Optimized Code"));
    verify(chatService).reviewCode("Java", "class A { }");
}

We’ll now verify that search-grounded queries pass their parameters cleanly through the controller layer without parameter binding errors:

@Test
void whenGroundedEndpointIsInvoked_thenReturnsModelContent() throws Exception {
    when(chatService.searchGroundedPrompt(anyString())).thenReturn("Grounded Response");
    mockMvc.perform(get("/v1/chat/grounded").param("currentEventQuery", "latest match winner"))
      .andExpect(status().isOk())
      .andExpect(content().string("Grounded Response"));
    verify(chatService).searchGroundedPrompt("latest match winner");
}

Finally, we test our reactive endpoint to ensure Spring MVC properly negotiates the text/event-stream media type. It will also format the reactive Flux elements into standard Server-Sent Event (data:) frames:

@Test
void whenStreamEndpointIsInvoked_thenReturnsEventStreamContent() throws Exception {
    when(chatService.streamChatTokens(anyString()))
      .thenReturn(reactor.core.publisher.Flux.just("token-1", "token-2"));
    mockMvc.perform(get("/v1/chat/stream").param("prompt", "Stream tokens"))
      .andExpect(status().isOk())
      .andExpect(content().contentTypeCompatibleWith(MediaType.TEXT_EVENT_STREAM))
      .andExpect(content().string("data:token-1\n\ndata:token-2\n\n"));
    
    verify(chatService).streamChatTokens("Stream tokens");
}

By leveraging the modern @MockBean annotation, we inject our mock definitions directly into the application context wrapper, replacing the real bean configuration. This allows us to stub out standard synchronous operations as well as complex reactive Flux stream responses safely and reliably without network overhead.

5. Conclusion

In this tutorial, we configured a Spring Boot application using Spring AI’s updated spring-ai-starter-model-google-genai engine to interact directly with Google AI Studio.

We saw how explicitly defining spring.ai.model.chat=google-genai resolves modern multi-model classpath dependencies. From there, we established a clean architecture using a dedicated ChatService. We built out flexible prompt workflows with the fluent ChatClient API and isolated dynamic parameters using templates. Finally, we enabled live web grounding and streamed responsive outputs via WebFlux Flux.

As always, the complete code samples used in this article are available over on GitHub.

The post Introduction to Google GenAI Chat and Spring AI first appeared on Baeldung.

       

1. Overview

As AI agents become more capable, long-term memory has become just as important as reasoning. While mechanisms such as ChatMemory and Retrieval Augmented Generation (RAG) handle conversations and external knowledge, they don’t answer a different question: What should an agent permanently remember about a user or project?

Spring AI AutoMemoryTools addresses this by enabling agents to persist and recall long-term memories, such as user preferences and project-specific knowledge.

In this article, we’ll explore AutoMemoryTools, its architecture and components, and build a simple Spring Boot chatbot that demonstrates how it works.

2. Dependencies

Let’s start by defining the minimum dependencies possible for demonstrating the Spring AI AutoMemoryTools. We’ll need the spring-ai-starter-model-openai and spring-ai-agent-utils. The first is the starter for integrating any OpenAI-compatible API with Spring AI, and the latter contains the tools we’re exploring in this article. We can use the (current) latest versions:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-agent-utils</artifactId>
    <version>0.10.0</version>
</dependency>

3. Spring AI AutoMemoryTools

Spring AI AutoMemoryTools is a Spring AI Community library that implements long-term memory for AI agents. It uses tool calling and file-based persistence. It’s part of the Spring AI Agent Utils, similar to Agent Skills. It’s worth mentioning that it’s inspired heavily by Claude Code and saves developers from implementing common agent capabilities themselves.

Similar to MessageChatMemoryAdvisor (for conversation memory), Spring AI AutoMemoryTools also implements BaseChatMemoryAdvisor. This means it’s related to conversational memory, but it does not focus on the conversation part. Rather, aims to store information about concepts like user preferences, projects, feedback, and more.

3.1. Types of Memory

Let’s look at the types of memory the Spring AI AutoMemoryTools targets:

• User: Remembers who the user is and how to assist them best
• Feedback: Remembers how the user prefers the AI to behave
• Project: Remembers important project context and decisions
• Reference: Remembers where to find information in external systems.

As we’ll see later, these are best described in the AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md, which is part of the dependency resources. Another thing we’ll see is how we can override this PromptSystemSpec with a custom one. This would mean that these types of memory might no longer exist, unless we define them.

3.2. The Tools

Now, let’s go through the six distinct tools of AutoMemoryTools:

• MemoryView: Reads the contents of a memory file or lists the available memory files in a directory
• MemoryCreate: Creates a new memory file to persist long-term information
• MemoryStrReplace: Updates an existing memory by replacing an exact piece of text
• MemoryInsert: Inserts new content at a specific location within an existing memory file
• MemoryDelete: Removes a memory file or directory from persistent storage
• MemoryRename: Renames or relocates a memory file while preserving its contents.

3.3. Memory System Prompt

As we saw before, the AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md is part of the library. The library offers two different levels of abstraction. The first is sandboxed, a restricted environment that limits the agent’s access, using the Spring AI AutoMemoryTools. The other is the unrestricted use of FileSystemTools or ShellTools.

In practise, AutoMemoryTools is a specialized abstraction built on top of generic filesystem operations. The Agent can access and manage memory files within the designated memory directories like memory/user, memory/feedback, etc. But it should not have the privileges to do anything outside the memory directory. On the contrary, FileSystemTools and ShellTools are unrestricted unless the developer properly handles this matter.

3.4. How it Works – Bringing All Together

Now that we’ve covered the components, let’s see how a request flows through Spring AI AutoMemoryTools.

When a user sends a request, the LLM combines the Memory System Prompt with the user’s message to determine whether it should read from or write to memory. If needed, it invokes the AutoMemoryTools to manage Markdown files in the configured memory directory, as described by the default AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md.

After generating the response, the LLM may perform additional memory operations, such as invoking more tools or consolidating existing memory entries. Finally, it returns the response to the user.

4. Spring AI AutoMemoryTools Application

Bringing all together, let’s see this in action. We’ll see three scenarios of configuring a ChatClient to use the Spring AI AutoMemoryTools:

• All-defaults AutoMemoryToolsAdvisor (sandbox operation)
• Manual setup of AutoMemoryToolsAdvisor (sandbox operation)
• FileSystemTools and ShellTools (not sandboxed by default)

4.1. Default AutoMemoryToolsAdvisor Configuration

For the first scenario, we create an AutoMemoryToolsAdvisor with the default, minimum configuration needed:

@Configuration
class ChatClientConfiguration {
    @Value("${agent.memory.dir}")
    String memoryDirectory;
    ChatClient chatClient(ChatModel chatModel) {
        return ChatClient
          .builder(chatModel)
          .defaultAdvisors(
            AutoMemoryToolsAdvisor.builder()
              .memoriesRootDirectory(memoryDirectory)
              .build(),
            MessageChatMemoryAdvisor.builder(
              MessageWindowChatMemory.builder()
                .maxMessages(100)
                .build())
            .build(),
            ToolCallingAdvisor.builder()
              .disableInternalConversationHistory()
              .build())
          .build();
    }
}

This setup uses the default AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md and defines the memory types we explained earlier. We use the Advisor to intercept all message exchanges. The memoriesRootDirectory() method sets the memory directory, which is also the boundary of access for the Agent. Last, the MessageChatMemoryAdvisor is the known Advisor that handles the memory for the conversation aspect. We set a random value of 100 messages history.

4.2. Custom AutoMemoryTools Configuration

If we still want the sandboxed AutoMemoryTools but we have more system prompts to include, we can use a more custom approach:

@Configuration
class ChatClientConfiguration {
    // ...
    @Value("classpath:/prompts/AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md")
    Resource memorySystemPromptAutoMemoryTools;
    // ....
    @Bean
    ChatClient chatClientWithMoreSystemPrompt(ChatModel chatModel) {
        return ChatClient
          .builder(chatModel)
          .defaultSystem(p -> p
            .text(memorySystemPromptAutoMemoryTools)
            .param("MEMORIES_ROOT_DIERCTORY", memoryDirectory))
          .defaultTools(
            AutoMemoryTools.builder()
              .memoriesDir(memoryDirectory)
              .build(),
            TodoWriteTool.builder()
              .build())
          .defaultAdvisors(ToolCallingAdvisor.builder()
              .build())
          .build();
    }
}

Here, we do a similar setup as before, but we use the Tools instead. This way we can define the custom PromptSystemSpec, with the prompt in the .md file we provide. However, this prompt is the essence of AutoMemoryTools, where we should define memory types, how to store, and more. So, if we need to override it, better copy the default prompt and append the extra system prompts.

We should note that ChatMemory is not set here, but the TodoWriteTool is used. This has nothing to do with Spring AI AutoMemoryTools. It’s to show that we can have or not have more tools and advisors, depending on the Agent’s needs.

4.3. FileSystemTools and ShellTools

Last, we can have an unrestricted scenario, using FileSystemTools and ShellTools. For example, if the agent already has FileSystemTools or ShellTools for other tasks, there’s no need for AutoMemoryTools:

@Configuration
class ChatClientConfiguration {
    // ...
    @Value("classpath:/prompts/AUTO_MEMORY_FILESYSTEM_TOOLS_SYSTEM_PROMPT.md")
    Resource memorySystemPromptFilesystemTools;
    // ....
    @Bean
    ChatClient chatClientWithoutAutoMemoryTools(ChatModel chatModel) {
      return ChatClient
        .builder(chatModel)
        .defaultSystem(p -> p
          .text(memorySystemPromptFilesystemTools)
          .param("MEMORIES_ROOT_DIERCTORY", memoryDirectory))   // tells the agent where to write
          .defaultTools(
            ShellTools.builder()
              .build(),         // Bash — mkdir, ls, etc.
            FileSystemTools.builder()
              .build())    // Read, Write, Edit — memory file operations
          .defaultAdvisors(ToolCallingAdvisor.builder()
              .build())
        .build();
    }
}

The file AUTO_MEMORY_FILESYSTEM_TOOLS_SYSTEM_PROMPT.md can also be found in the library. For the demonstration, we can copy it over. Using this one, the same memory conventions apply: .md files, two-step save, etc. But the agent conventionally has full filesystem access and stays in the configured directory only.

The two tools are the ones the Agent needs to do all the file creation, removal, editing, etc, to keep the memory in the file system.

4.4. Other Project Files

For the demonstration, we’ll use spring-web-mvc, with a RestController:

@PostMapping("/chat-with-memory")
ResponseEntity<String> chat(@RequestBody String question, @RequestHeader("X-Conversation-ID") String conversationId) {
    String answer = chatClient
      .prompt()
      .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
      .user(question)
      .call()
      .content();
    return ResponseEntity.ok(answer);
}

As mentioned earlier, the conversationId is needed, since Spring AI AutoMemoryTools implements BaseChatMemoryAdvisor.

Let’s run the application using a local Ollama Qwen model:

First, we ask the Agent to save some info. Then we request this info, but notice the different conversationId! The Agent doesn’t know anything about session-1. Asking as session-2 again, the Agent remembers it.

Depending on our machine, the Agent interaction with the file system might be quite slow. We can also see the directories that the Agent created, along with the file content:

5. Conclusion

In this article, we went through Spring AI AutoMemoryTools. We covered the use cases and the basic definitions. Then we walked through the six operations and the three options to use them. Finally, we used Spring AI to demonstrate it in practise.

As always, the source code of the examples can be found over on GitHub.

The post Spring AI AutoMemoryTools first appeared on Baeldung.

       

1. Overview

We’re increasingly building AI agents that can handle a user’s entire request on their own. Instead of simply answering questions from what a Large Language Model (LLM) already knows, these agents reason through a problem, break it down into steps, call external tools, and even execute local scripts.

As these requests grow in complexity, packing every capability into a single agent becomes unmanageable. The natural fix is to create smaller agents, each specialized in one job. However, getting these agents to talk to each other is a challenge in itself, as they run as independent services built using different languages, frameworks, and LLMs.

The Agent2Agent (A2A) Protocol addresses this issue by defining a standard for agents to discover each other and communicate.

In this tutorial, we’ll practically explore the A2A protocol by implementing its client and server architecture using Spring AI.

2. Agent2Agent (A2A) Protocol 101

Before we dive into the implementation, let’s take a closer look at the protocol and the way two agents interact:

An agent acting as a server exposes its capabilities to the outside world, while an agent acting as a client consumes them.

Discovery happens through an Agent Card, which is a JSON document that a server publishes at a well-known URL. This card exposes the agent’s details, including the list of skills it offers. A client agent fetches this card first to learn what a remote agent can do and where to reach it.

The client sends a Message that describes the work to be done in plain natural language. The remote agent turns that message into a Task, processes it, and returns one or more Artifacts that carry the actual response content.

A2A is a complex and vast topic. We can refer to the official specification to learn more.

3. The Project We’re Building

To see the protocol in action, we’ll build a job screening system for recruiters:

As we can see, our system is made up of one orchestrator agent that acts as the A2A client and communicates with three specialized remote agents that act as A2A servers.

A recruiter submits a candidate’s details to a single REST endpoint. Behind the scenes, the orchestrator agent will break the request down and delegate each task to a specialized agent. Once every agent responds, the orchestrator will merge the individual verdicts into one short screening summary.

4. Creating an A2A Server

Since creating A2A servers follows the exact same structure, we’ll only walk through implementing the skills matcher agent.

The remaining two remote servers differ solely in their tools and prompts. To view the complete implementation of the project, we can refer to the repository backing this tutorial.

4.1. Dependencies and LLM Configuration

Let’s start by adding the necessary dependencies to our project’s pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-a2a-server-autoconfigure</artifactId>
    <version>0.3.0</version>
</dependency>

Here, we first import Spring AI’s OpenAI starter dependency, which we’ll use to interact with an LLM. Additionally, we import the A2A server autoconfigure dependency from the Spring AI community, which takes care of serving our agent card at startup and handling A2A requests.

Next, let’s configure our OpenAI API key and chat model in the application.yaml file:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-5.5

Here, we specify OpenAI’s GPT 5.5 model using the gpt-5.5 model ID. Alternatively, we can use a different chat model, as the specific AI model or provider is irrelevant for this demonstration.

With these two properties set, Spring AI automatically creates a bean of type ChatClient.Builder, which we’ll use in the upcoming section.

4.2. Creating a Tool and Registering It With ChatClient

Next, let’s configure the actual capability that our A2A server offers. We’ll create a SkillsMatcherTools class and define a tool that evaluates a candidate’s skills:

@Tool(
  name = "match-skills",
  description = "Compares a candidate's skills against a job's required skills and returns a fit score"
)
SkillsMatchResult matchSkills(
  @ToolParam(description = "Candidate skills, comma-separated") String candidateSkills,
  @ToolParam(description = "Required job skills, comma-separated") String requiredSkills
) {
    // ... rudimentary implementation
}
record SkillsMatchResult(
    int score,
    Verdict verdict,
    Set<String> matchedSkills,
    Set<String> missingSkills
) {}
enum Verdict {
    STRONG_MATCH,
    PARTIAL_MATCH,
    WEAK_MATCH
}

We annotate our method with the @Tool annotation and give it an explicit name along with a short description. Both of these values help the AI model decide if and when to invoke this tool. Similarly, we describe both method parameters with the @ToolParam annotation so that the LLM knows the format we expect the inputs to be in.

We’ve deliberately omitted the method implementation here, since it’s not important to our A2A understanding.

Next, let’s create a ChatClient bean and register our tool with it:

@Bean
ChatClient chatClient(
  ChatClient.Builder chatClientBuilder,
  SkillsMatcherTools skillsMatcherTools
) {
    return chatClientBuilder
      .defaultSystem("""
        You are a skills-matching assistant for recruiters.
        Use the match-skills tool to compare a candidate's skills
        against a job's required skills, then summarize the result.
        """)
      .defaultTools(skillsMatcherTools)
      .build();
}

Here, we use the ChatClient.Builder bean that Spring AI configures for us, along with the SkillsMatcherTools bean we defined above, to create a ChatClient bean. This class acts as our main entry point for interacting with the configured LLM.

Additionally, we define a system prompt defining the agent’s role, and then register our tool class using the defaultTools() method. This enables the model to call our tool method when it receives a matching request.

4.3. Defining an AgentExecutor to Handle A2A Requests

The ChatClient bean we’ve defined can only be used by components within our own application. To let other agents send us tasks, we need to define an AgentExecutor bean that handles incoming A2A requests:

@Bean
AgentExecutor agentExecutor(ChatClient chatClient) {
    return new DefaultAgentExecutor(chatClient, (client, requestContext) -> {
        String userMessage = DefaultAgentExecutor.extractTextFromMessage(requestContext.getMessage());
        return client
          .prompt()
          .user(userMessage)
          .call()
          .content();
    });
}

Here, we use the DefaultAgentExecutor class, passing it our ChatClient bean along with a handler function that defines how we want to respond. In the handler function, we extract the plain text of the incoming message and pass it to our LLM as a user prompt. The response from our chatClient bean is automatically wrapped into an artifact and sent back to the calling agent.

4.4. Describing Our Agent Using an AgentCard

Finally, we need to expose an Agent Card that accurately describes our agent:

@Bean
AgentCard agentCard(
  @Value("${server.host}") String host,
  @Value("${server.port}") int port
) {
    return new AgentCard.Builder()
      .name("Skills Matcher Agent")
      .description("Evaluates how well a candidate's skills match a job's required skills")
      .url(String.format("http://%s:%d/", host, port))
      .version("1.0.0")
      .capabilities(new AgentCapabilities
        .Builder()
        .streaming(false)
        .build())
      .defaultInputModes(List.of("text"))
      .defaultOutputModes(List.of("text"))
      .skills(List.of(new AgentSkill.Builder()
        .id("skills_matching")
        .name("Skills Matching")
        .description("Compares candidate skills to job requirements and scores the fit")
        .tags(List.of("hiring", "recruiting"))
        .build()))
      .protocolVersion("1.0.1")
      .build();
}

Here, we create an AgentCard bean and define the important properties of name, description, and skills. Client agents rely on these properties to decide whether a remote agent and the capabilities it offers are a good fit for a given task.

Similarly, we define the url property from the host and port of our running application, telling clients where to reach us. Additionally, we declare that our agent doesn’t support streaming and it exchanges plain text in both directions.

It’s worth noting that every property we set above is mandatory, and the builder rejects a card with any of them missing. With this bean defined, the auto-configuration serves our agent card at the .well-known/agent-card.json path.

5. Creating an A2A Client

With our specialized agents ready, we’ll build our A2A client, i.e., the job screening orchestrator that delegates the actual evaluation to them.

5.1. Dependencies

Our orchestrator is a separate application that also talks with an LLM. For this reason, we’ll need to import a chat model dependency and configure the API key and model properties, just like we did in our A2A server.

In addition to that, we need to add the A2A Java SDK to our pom.xml:

<dependency>
    <groupId>io.github.a2asdk</groupId>
    <artifactId>a2a-java-sdk-client</artifactId>
    <version>0.3.3.Final</version>
</dependency>

This SDK provides us the classes we need to fetch agent cards, open connections to remote agents, and send them messages.

We should note that we didn’t explicitly declare this dependency while building our A2A server, as the server autoconfigure dependency brings it in transitively. However, for an agent purely acting as a client, we’ll need to add this ourselves.

5.2. Discovering Remote Agents at Startup

Our orchestrator can only delegate work to agents it knows about, so let’s list their addresses in the application.yaml:

remote:
  agents:
    urls:
      - http://localhost:8081
      - http://localhost:8082
      - http://localhost:8083

Here, we configure the base URLs of our remote agents using a custom property. We need to make sure to update these values if the agents run on a different host or port.

Next, let’s create an AgentRegistry component that fetches agent cards from these URLs when the application starts:

private final Map<String, AgentCard> agentCards = new HashMap<>();
AgentRegistry(@Value("${remote.agents.urls}") List<String> agentUrls) {
    for (String url : agentUrls) {
        String path = new URI(url).getPath();
        AgentCard card = A2A.getAgentCard(url, path + ".well-known/agent-card.json", null);
        agentCards.put(card.name(), card);
    }
}

Here, we iterate over each configured URL inside the constructor and retrieve its agent card from the .well-known/agent-card.json path. Then, we store the resulting AgentCard instances in an in-memory map keyed by the agent’s name.

To expose the fetched agent cards to other components, let’s add a couple of helper methods to this class:

AgentCard get(String agentName) {
    return agentCards.get(agentName);
}
String describeAgents() {
    return agentCards
      .values()
      .stream()
      .map(card -> "- " + card.name() + ": " + card.description())
      .collect(Collectors.joining("\n"));
}

The get() method returns the card of a specific agent by its name. Meanwhile, the describeAgents() method renders the formatted summary of all available remote agents with their descriptions. We’ll use these helper methods in the upcoming sections to define additional components.

5.3. Communicating With Remote Agents

Our A2A client is now capable of discovering remote agents at startup. Next, let’s create a RemoteAgentClient component that actually communicates with these agents:

String sendMessage(String agentName, String task) {
    AgentCard agentCard = agentRegistry.get(agentName);
    CompletableFuture<String> response = new CompletableFuture<>();
    BiConsumer<ClientEvent, AgentCard> responseConsumer = (event, card) -> {
        TaskEvent taskEvent = (TaskEvent) event;
        response.complete(taskEvent.getTask()
          .getArtifacts()
          .stream()
          .map(Artifact::parts)
          .map(this::extractText)
          .collect(Collectors.joining("\n")));
    };
    Client client = Client.builder(agentCard)
      .clientConfig(new ClientConfig.Builder()
        .setAcceptedOutputModes(List.of("text"))
        .build())
      .withTransport(JSONRPCTransport.class, new JSONRPCTransportConfig())
      .addConsumers(List.of(responseConsumer))
      .streamingErrorHandler(response::completeExceptionally)
      .build();
    Message message = A2A.toUserMessage(task);
    client.sendMessage(message);
    return response.get(60, TimeUnit.SECONDS);
}
private String extractText(List<Part<?>> parts) {
    return parts
      .stream()
      .filter(TextPart.class::isInstance)
      .map(TextPart.class::cast)
      .map(TextPart::getText)
      .collect(Collectors.joining("\n"));
}

Here, we start by fetching the target agent’s card from our registry, as the SDK uses it to build a client.

Since the SDK returns responses asynchronously, we register a consumer that receives the completed task. Then, it pulls the text out of its artifacts, and passes it to our CompletableFuture response. Then, we convert the given task into an A2A message, send it to the remote agent, and wait for the response to complete.

Next, let’s expose this capability as a tool that our orchestrator’s LLM can call:

@Tool(
  name = "send-message-to-agent",
  description = "Sends a task to a remote agent and returns its response."
)
String sendMessageToAgent(
  @ToolParam(description = "Name of the remote agent") String agentName,
  @ToolParam(description = "The task to perform") String task
) {
    return remoteAgentClient.sendMessage(agentName, task);
}

This single tool is all the orchestrator needs to reach all our configured agents. The LLM will decide which agent to contact and what to ask it, simply by filling in the agentName and task parameters.

5.4. Building the Orchestrator ChatClient

With our discovery and communication logic in place, let’s create the ChatClient bean for our orchestrator agent:

@Bean
ChatClient chatClient(
  ChatClient.Builder chatClientBuilder,
  AgentRegistry agentRegistry,
  RemoteAgentTools remoteAgentTools
) {
    return chatClientBuilder
      .defaultSystem("""
        You are a job-screening orchestrator for recruiters.
        You do not evaluate candidates yourself. Instead, you delegate
        to the following remote agents:
        %s
        Once all agents have responded, combine their responses into a short screening summary.
        """.formatted(agentRegistry.describeAgents()))
      .defaultTools(remoteAgentTools)
      .build();
}

In our system prompt, we explicitly instruct the model not to evaluate candidates on its own. Instead, we inject the list of discovered agents using the describeAgents() method and ask it to delegate the individual evaluations to them.

Then, we register our tool, which gives the model the capability to actually reach these agents.

5.5. Exposing a REST API

Finally, let’s use the orchestrator ChatClient we’ve defined and expose a REST API endpoint to accept candidate screening requests:

@PostMapping("/screenings")
ScreeningResponse screenCandidate(@RequestBody ScreeningRequest screeningRequest) {
    String verdict = chatClient
      .prompt()
      .user(screeningRequest.toString())
      .call()
      .content();
    return new ScreeningResponse(verdict);
}
record ScreeningRequest(
  String name,
  String email,
  String jobTitle,
  String requiredSkills,
  String candidateSkills,
  int expectedSalary
) {}
record ScreeningResponse(
  String verdict
) {}

Our endpoint accepts a ScreeningRequest record holding everything our agents need, namely the candidate’s identity, the job details, and the expected salary.

We simply pass the record’s string representation to the model as a user prompt and return the resulting summary as a ScreeningResponse. This way, our orchestrator client receives the full candidate details and distributes the relevant data to each of our specialized agents.

6. Testing Our Implementation

With our architecture implemented, let’s start all our agents and test the job screening flow.

We’ll use the HTTPie CLI to invoke our screening endpoint:

http POST :8080/screenings \
  name="John Doe" \
  email="john.doe@baeldung.com" \
  jobTitle="Backend Developer" \
  requiredSkills="Java, Spring Boot, AWS, Kafka" \
  candidateSkills="Java, Spring Boot, Azure, Kafka" \
  expectedSalary:=110000 \
  | jq -r '.verdict'

Here, we submit sample data for a candidate and pipe the response through jq to print the verdict as readable text.

Let’s see what we get as a response:

Screening summary for John Doe (Backend Developer):
- Salary: Expected salary of $110,000 is within budget.
- Background check: Clear; no relevant flags found.
- Skills match: Strong match, 75% fit. Only missing AWS experience, though Azure experience may be transferable.
Overall: John Doe appears to be a good candidate to proceed with, with follow-up recommended on AWS/cloud experience.

As we can see, the orchestrator delegated the request to all three remote agents and consolidated their individual verdicts into a single summary.

7. Conclusion

In this article, we’ve understood what the Agent2Agent (A2A) protocol is and practically implemented it using Spring AI.

We started by building an A2A server, exposing its capability through an agent card. Next, we built an A2A client that acts as an orchestrator, dynamically discovering remote agents and delegating tasks to them. Finally, we tested the complete flow of our implementation and confirmed that our orchestrator combines the responses of all the specialized agents into one screening summary.

As always, all the code examples used in this article are available over on GitHub.

The post Exploring Agent2Agent Protocol (A2A) With Spring AI first appeared on Baeldung.

       

1. Spring and Java

>> The Self-Building Agent: a LangChain4j Experiment [infoq.com]

A interesting reveral of the typical agent tutorial by pointing an LLM at the LangChain4j documentation and having it design an agent. Meta yes, and worth a quick read.

Also worth reading:

• >> To Cache or Not to Cache Virtual Threads [quarkus.io]
• >> Pairing In-Process and Hosted Embeddings for Java MCP Tool Development [inside.java]
• >> New Between-Quarters Security Updates for Java: What CSPUs Mean for Your Release Pipeline [foojay.io]
• >> Reverse Engineering with Hibernate 7.4 and IntelliJ IDEA [jetbrains.com]
• >> Writing a Thymeleaf component library [wimdeblauwe.com]
• >> Quality Outreach Heads-up – JDK 28: jlink cacerts plugin [inside.java]
• >> KotlinLLM is Going Open Source [jetbrains.com]
• >> RFC 9880 and the IoT Validation Problem [frankel.ch]
• >> AI Found the Bugs. Who’s Patching Your EOL Java Code? [foojay.io]
• >> Secure Your APIs: OAuth2 and JWT for Beginners [jetbrains.com]

Webinars and presentations:

• >> Episode 63 “AI Solutions with Spring AI 2.0” [I/O] [inside.java]
• >> A Bootiful Podcast: Java Developer Advocate Billy Korando on Java 27 and Beyond [spring.io]
• >> Spring Office Hours Podcast: S5E19 – Docker, Compose, Testcontainers, Oh My! [spring.io]
• >> Clean Architecture for Serverless: Business Logic You Can Take Anywhere [infoq.com]

Time to upgrade:

• >> Quarkus 3.37.4 and 3.33.3 [quarkus.io]
• >> GraalVM Community 25 Innovation 2 [github.com/graalvm]
• >> Zuul 4.1.3 and 4.1.2 [github.com/Netflix]
• >> Micronaut Core 5.0.7 [github.com/micronaut-projects]

2. Technical & Musings

>> The Orchestrator’s Tax [martinfowler.com]

Insight into multi-agent coding setups. Exploratory rather than prescriptive, and better for it.

Also worth reading:

• >> Credential Brokering Patterns for AI Agents Part 1: Don’t Give the Agent the Keys [christianposta.com]
• >> The Rise of Open Weights; And the fall of commercial AI? [scottlogic.com]
• >> Throw, Result, or neither? [event-driven.io]
• >> Codeberg Divides [lucumr.pocoo.org]
• >> Shifting readiness left: What AI can (and can’t) do for organisational readiness [scottlogic.com]

3. Pick of the Week

>> First, ten [seths.blog]

The post Java Weekly, Issue 657 first appeared on Baeldung.

       

1. Introduction

When working with Apache Spark, we often encounter situations where a DataFrame becomes empty after applying transformations, filters, or joins.

Before triggering expensive actions or saving data to external storage, it’s a best practice to verify if the DataFrame contains any rows. While this may seem like a trivial check, different approaches trigger different Spark actions and can have a noticeable impact on performance, especially for large datasets.

In this tutorial, we’ll explore different ways to check whether a Spark DataFrame is empty.

2. Setup

First, let’s create the following sample DataFrame:

public static Dataset getDataFrame(SparkSession spark) {
    List<Row> players = List.of(
      RowFactory.create(1, "Messi", "Argentina"),
      RowFactory.create(2, "Ronaldo", "Portugal"),
      RowFactory.create(3, "Mbappe", "France"));
    return spark.createDataFrame(players, PLAYER_SCHEMA);
}

We’ll use this DataFrame throughout the examples.

3. Using the isEmpty() method

Since Spark 2.4.0, the easiest way to check whether a Dataset is empty is by using the isEmpty() method.

Let’s create an empty DataFrame by filtering for a country that doesn’t exist in the dataset.

Dataset<Row> englandPlayers = allPlayers.filter(col("country").equalTo("England"));
Assertions.assertTrue(englandPlayers.isEmpty());

Since there are no England players in the dataframe, the filter returns an empty dataframe and isEmpty() returns true.

4. Using the count() method

Another way to check for emptiness is by counting the number of rows in a DataFrame and checking if it’s zero:

Dataset<Row> englandPlayers = allPlayers.filter(col("country").equalTo("England"));
Assertions.assertEquals(0, englandPlayers.count());

Here, we invoked count() and verified that the number of rows is 0.

5. Using the takeAsList() Method

Another approach is to retrieve at most one row using takeAsList():

Dataset<Row> englandPlayers = allPlayers.filter(col("country").equalTo("England"));
Assertions.assertEquals(0, englandPlayers.takeAsList(1).size());

Here we called the takeAsList(1), which returns at most one row. We can then verify that the returned list is empty by checking whether its size is 0. Since only one row is requested, Spark can stop processing once it finds the first matching row, making this approach more efficient than counting every row.

Alternatively, we can also check if the list is empty instead of size():

Assertions.assertTrue(englandPlayers.takeAsList(1).isEmpty());

6. Comparing Methods for Performance

Although all of these approaches can determine whether a DataFrame is empty, they don’t have the same performance characteristics.The isEmpty() method is the recommended approach because it’s specifically designed for this purpose. Internally, Spark only needs to determine whether at least one row exists, allowing it to stop processing as soon as a row is found.

Similarly, takeAsList(1) requests only a single row. Once Spark retrieves the first row, it can terminate the scan, making this approach much more efficient than counting every row. In contrast, count() computes the total number of rows in the DataFrame. Since Spark must process the entire dataset to produce an exact count, this approach is considerably more expensive for large DataFrames.

In general, we should prefer isEmpty() whenever it’s available. If we’re working with an older Spark version that doesn’t support it, takeAsList(1).isEmpty() is a good alternative. We should reserve count() for situations where we also need the total number of rows.

7. Conclusion

In this article, we explored several ways to determine whether a Spark DataFrame is empty. We started with the isEmpty() method, which is the simplest and most expressive solution, and then looked at alternatives based on count() and takeAsList().

In most situations, isEmpty() is the preferred choice because it’s both expressive and efficient. For older Spark versions, takeAsList(1).isEmpty() provides a practical alternative, while count() is best reserved for cases where the total number of rows is also needed.

As always, the sample code used in this article is available over on GitHub.

The post Check if Spark Dataframe Is Empty first appeared on Baeldung.

       

1. Overview

An LLM can answer questions about documents’ content when they are in the context window. However, many real-world documents are stored in formats such as PDF, which may be difficult for AI applications to process directly. Docling converts these documents into a structured format that can be efficiently parsed.

In this tutorial, we’ll build a document processing system using Apache Camel, Docling, and LangChain4j. Also, we’ll define a simple question-answering API using an embedded Undertow server.

2. Problem Statement

Many real-world documents contain structural information such as headings, tables, and images, which is difficult to preserve during text extraction. As a result, AI pipelines may lose valuable context, reducing the quality of retrieval and accuracy of generated responses.

A structured representation helps address this problem by preserving the document’s organization and relationships. Structured formats such as Markdown, HTML, and JSON retain much of the document’s semantic structure, making them easier to process and interpret.

IBM Docling bridges this gap by converting unstructured or semi-structured documents into structured representations that downstream AI applications can efficiently consume. We can store the generated Markdown on disk. Later, an application can load it and include it in the prompt for the LLM. This avoids converting the same document for every request the application processes.

3. Project Setup

Let’s bootstrap a Java project using Apache Camel and LangChain4j.

3.1. Maven Dependencies

First, let’s add the camel-core, camel-main, and langchain4j dependencies to our pom.xml:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-core</artifactId>
    <version>4.20.0</version>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-main</artifactId>
    <version>4.20.0</version>
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>1.11.8</version>
</dependency>

The camel-core dependency provides classes such as RouteBuilder for defining a camel route using the Java DSL, camel-main provides a lightweight runtime for standalone Camel applications, and langchain4j provides the core APIs for interacting with LLMs.

Next, let’s add camel-docling, camel-langchain4j-chat, and langchain4j-open-ai dependencies to our pom.xml:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-docling</artifactId>
    <version>4.20.0</version>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-langchain4j-chat</artifactId>
    <version>4.20.0</version>
</dependency>

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.11.8</version>
</dependency>

Here, camel-docling integrates Apache Camel with a Docling server, allowing routes to submit documents for conversion into Docling’s structured document representation. Also, camel-langchain4j-chat enables Camel routes to send prompts to a LangChain4j chat model and process the generated response. The langchain4j-open-ai dependency provides the implementation needed to connect LangChain4j to OpenAI-compatible chat models.

All Apache Camel dependencies, including camel-docling, use the same version to ensure compatibility and avoid unexpected runtime errors.

Let’s also add the camel-undertow dependency to our pom.xml:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-undertow</artifactId>
    <version>4.20.0</version>
</dependency>

It enables Camel to expose HTTP endpoints using an embedded Undertow server.

Finally, let’s create a directory named document in the project’s root directory and place the policies.pdf file inside it.

3.2. Docker Compose File

The easiest way to run Docling locally is by using docling-serve, which exposes Docling’s document conversion capabilities through a REST API. For simplicity, we run docling-serve in a Docker container.

First, let’s create a new file docker-compose.yml in our project root directory and add the following configuration:

services:
  docling-serve:
    image: quay.io/docling-project/docling-serve:latest
    container_name: docling-serve
    ports:
      - "5001:5001"
    environment:
      - DOCLING_STORAGE_DIR=/data
      - DOCLING_PORT=5001
    volumes:
      - ./data/docling:/data
    restart: unless-stopped

The configuration starts a docling-serve container from the quay.io/docling-project/docling-serve image. If the image isn’t available locally, Docker automatically pulls it from the registry. It also maps port 5001 on the host to port 5001 inside the container, allowing our application to communicate with the Docling server.

Finally, let’s start the Docling server by running the following command:

$ docker compose up

3.3. Application Entry Point

Let’s create a CamelDoclingApplication class that serves as our application entry point:

public class CamelDoclingApplication {
    public static void main(String[] args) throws Exception {
        OpenAiChatModel model = OpenAiChatModel.builder()
          .baseUrl("http://langchain4j.dev/demo/openai/v1")
          .apiKey("demo")
          .modelName("gpt-4o-mini")
          .build();
        Main main = new Main();
        main.bind("chatModel", model);
        main.run(args);
    }
}

We create an OpenAiChatModel object configured to use the gpt-4o-mini model. Although OpenAI models normally require a valid API key, LangChain4j provides a public demo endpoint and API key for experimentation. We configure the client to use this endpoint by setting the baseUrl to the LangChain4j demo service. Alternatively, we could configure LangChain4j to communicate with a locally hosted model through Ollama or replace the demo endpoint with our own OpenAI API credentials.

The Main instance provides a lightweight runtime for standalone Camel applications. We bind the chat model to Camel’s registry under the name chatModel, that Camel components and routes can reference during message processing.

4. Converting a PDF Document to Markdown

Now that the Docling server is running, let’s create our first Camel route to convert policies.pdf into Markdown:

class ConversionRoute extends RouteBuilder {
    @Override
    public void configure() {
        from("file:documents?include=.*\\.(pdf|docx|pptx|html|md)&noop=true&idempotent=true")
          .routeId("document-analysis-workflow")
          .log("Processing document: ${header.CamelFileName}")
          .to("docling:CONVERT_TO_MARKDOWN?useDoclingServe=true&doclingServeUrl=http://localhost:5001&contentInBody=true")
          .setProperty("convertedMarkdown", body())
          .setHeader(Exchange.FILE_NAME, simple("${header.CamelFileName.replaceFirst('\\.[^.]+$', '')}.md"))
          .to("file:output") 
    }
}

Here, we monitor the documents directory for supported document types. The noop=true option leaves the original file in place after processing, while idempotent=true prevents the same file from being processed more than once. Note that the Camel file component already provides the information that the Docling component needs to process the document. Although we could explicitly replace the message body with the document’s path, doing so would be redundant because the conversion works correctly without it.

Next, the docling:CONVERT_TO_MARKDOWN endpoint sends the document to the locally running docling-serve instance, which converts it into Markdown and returns the generated content in the message body.

Finally, we store the converted Markdown as an exchange property, rename the output file by replacing its original extension with .md, and use the Camel file component to write it in the output directory.

If there are multiple documents in the documents directory, Camel processes each one independently and generates a corresponding Markdown file in the output directory.

Let’s run our application by registering ConversionRoute with the Camel runtime:

Main main = new Main();
main.bind("chatModel", model);
main.configure()
  .addRoutesBuilder(new ConversionRoute());
main.run(args);

Here, we register the ConversionRoute with Camel through the Main instance.

5. Passing the Markdown Document to LangChain4j

Now that we’ve converted the document to Markdown, let’s send it to our chat model and ask it to analyze the document:

class ConversionRoute extends RouteBuilder {
    @Override
    public void configure() {
        from("file:documents?include=.*\\.(pdf|docx|pptx|html|md)&noop=true&idempotent=true")
          .routeId("document-analysis-workflow")
          // ...
          .setBody(simple("""
              You are a helpful document analysis assistant. Please analyze
              the following document and provide:
              1. A brief summary (2-3 sentences)
              2. Key topics and main points
              3. Any important findings or conclusions
              Document content:
              ${exchangeProperty.convertedMarkdown}
              """))
          .to("langchain4j-chat:analysis?chatModel=#chatModel")
          .setHeader(
              Exchange.FILE_NAME,
              simple("${header.CamelFileName.replaceFirst('\\.[^.]+$', '')}-analysis.md")
          )
          .to("file:analysis");
    }
}

In this route, we construct a prompt that includes the Markdown generated by Docling and instruct the model to summarize and analyze the document. The ${exchangeProperty.convertedMarkdown} expression inserts the Markdown stored earlier in the route into the prompt before it’s sent to the model.

Next, the langchain4j-chat component sends the prompt to the chat model referenced by #chatModel. Camel resolves this reference from its registry, where we previously bound the OpenAiChatModel instance. The analysis in langchain4j-chat:analysis is the endpoint name. It’s primarily used to distinguish this endpoint from others.

Finally, we rename the output file by appending -analysis to the original filename and use the File component to write the model’s response to the analysis directory.

6. Interactive Q&A API

Now, it’s time to define a question-answering API that uses the converted Markdown document as its knowledge source.

Let’s create a Camel route that accepts a question through an HTTP endpoint:

public class QuestionAndAnswerRoute extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        from("undertow:http://0.0.0.0:8080/api/ask?httpMethodRestrict=POST").routeId("document-qa-api")
          .setProperty("question", bodyAs(String.class))
          .pollEnrich("file:output?fileName=policies.md&noop=true&idempotent=false")
          .setProperty("markdown", bodyAs(String.class))
          .setBody(simple("""
              You are a helpful document assistant.
              Answer ONLY using the document below.
              DOCUMENT
              =========
              ${exchangeProperty.markdown}
              QUESTION
              =========
              ${exchangeProperty.question}
              """))
          .to("langchain4j-chat:analysis?chatModel=#chatModel")
          .setHeader(Exchange.CONTENT_TYPE, constant("text/plain"));
    }
}

What happens here?

We expose the POST /api/ask endpoint through the embedded Undertow server. The request body contains the user’s question, which we store as an exchange property before replacing the message body later in the route.

The pollEnrich Enterprise Integration Pattern (EIP) reads the previously generated Markdown document from the output directory and places its contents into the current exchange. Rather than converting the PDF each time a request arrives, this route reads the Markdown file. This keeps the HTTP request lightweight by reusing the preprocessed document instead of invoking Docling for each question.

Also, we set idempotent=false so the File component can read the same Markdown file on every API request. By default, noop=true enables idempotent=true, which prevents the same file from being consumed more than once.

Then, we construct a prompt containing both the document and the user’s question before sending it to the langchain4j-chat component.

Finally, the model’s response is returned as the HTTP response body with a text/plain content type.

Let’s update our application entry point to register the QuestionAndAnswerRoute:

// ...
main.configure()
  .addRoutesBuilder(new QuestionAndAnswerRoute());
// ...

Once the application is up,  we can run the following curl command to send a question to the API:

curl -X POST \
  http://localhost:8080/api/ask \
  -H "Content-Type: text/plain" \
  -d "How many lifecycle stages does a task move through?"

Here’s an API response we can expect:

A task moves through four lifecycle stages: PENDING, IN_PROGRESS, REVIEW, and DONE.

The API successfully answers the question based on the document we supplied.

7. Conclusion

In this article, we learned how to integrate Apache Camel, Docling, and LangChain4j to build an intelligent document processing application. We used Docling to convert an unstructured document into a structured representation, orchestrated the conversion workflow with Apache Camel, and analyzed the converted content using an LLM through LangChain4j.

Additionally, we exposed a simple question-answer API that uses the converted document as context to generate grounded responses.

By converting documents into a structured representation once and reusing the generated Markdown for subsequent interactions, we simplify document processing workflows, avoid repeated conversions, and make it easier for LLMs to process the document content.

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

The post Building Intelligent Document Processing with Apache Camel, Docling and LangChain4j first appeared on Baeldung.

       

1. Introduction

In this article, we’re going to look at how to use Common Table Expressions (CTE) in Hibernate. We’ll see what a CTE is, what they’re used for, and how to use them in Hibernate queries.

Note that the introduction of CTE support is specific to Hibernate and HQL. This is not part of the standard JPA specification, and alternative implementations may not support CTE queries at all, or may support them in different ways.

2. What are Common Table Expressions

A Common Table Expression, or CTE, is a construct we can use within our queries to create a named result set that we can then refer to from within our main query.

At their simplest, we can treat these as equivalent to subqueries or joins:

-- Subquery
SELECT customer_id, total_spent
FROM (
    SELECT customer_id, SUM(amount) AS total_spent
    FROM orders
    GROUP BY customer_id
) customer_totals
WHERE total_spent > (
    SELECT AVG(total_spent)
    FROM (
        SELECT customer_id, SUM(amount) AS total_spent
        FROM orders
        GROUP BY customer_id
    ) customer_totals
);
-- CTE
WITH customer_totals AS (
    SELECT customer_id, SUM(amount) AS total_spent
    FROM orders
    GROUP BY customer_id
)
SELECT customer_id, total_spent
FROM customer_totals
WHERE total_spent > ( SELECT AVG(total_spent) FROM customer_totals );

These two SQL statements do the same thing. They each return the total spend of all customers who have spent more than the average amount. However, the CTE version works by defining a name, customer_totals, for our subquery and then allowing us to reference that name whenever we want. This is both easier to understand and more efficient for the database to execute.

3. Setting Up

Now that we know what CTEs are, we’re ready to start using them. Before we can do this, we need to do a little bit of setting up.

3.1. Dependencies

To use CTEs in Hibernate, we need to use version 6.2 or newer. The newest release at the time of writing is 7.4.4.Final:

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.4.4.Final</version>
</dependency>

If we’re getting Hibernate via Spring Boot, this means Spring Boot version 3.1 or newer is needed:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

Now we have our dependencies, let’s next consider what data we’ll be querying.

3.2. Database

For this article, we need to set up a database. Our table will look as follows:

CREATE TABLE employee (
    id         BIGINT PRIMARY KEY,
    name       VARCHAR(100)   NOT NULL,
    title      VARCHAR(100)   NOT NULL,
    department VARCHAR(50)    NOT NULL,
    salary     NUMERIC(10, 2) NOT NULL,
    manager_id BIGINT REFERENCES employee (id)
);

Note that the manager_id column references back to the same employee table. This allows us to store a hierarchical structure in a single table.

We then need some data in our database:

This gives us a set of employees that make a tree structure, rooted at “Alice”.

3.2. JPA Entity

Finally, since we’re going to be working with Hibernate, we also need a Hibernate entity to represent our data:

@Entity
@Table(name = "employee")
public class Employee {
    @Id
    private Long id;
    private String name;
    private String title;
    private String department;
    private BigDecimal salary;
    @ManyToOne
    @JoinColumn(name = "manager_id")
    private Employee manager;
}

The Employee entity gives us access to all of our data. As with our table structure, we’ve also got our reference back to the same entity. This time it’s in the form of a manager field that gives us the complete row.

4. Basic CTEs in Hibernate

Now that we’ve got our database and entity, we’re ready to query it.

As with SQL, Hibernate allows us to use the WITH clause in our HQL queries. This is used to define a new named result set that we can treat as any table or view within our main query.

For example:

List<Employee> employees = session.createQuery("""
    WITH engineers AS (
        SELECT e.id AS id
        FROM Employee e
        WHERE e.department = 'Engineering'
    )
    SELECT e
    FROM Employee e
    WHERE e.id IN (SELECT id FROM engineers)
    AND e.salary > 100000
    ORDER BY e.name ASC
""", Employee.class).getResultList();

We can consider this in two parts. Our WITH clause generates a new result set named engineers consisting of all of the IDs of employees in the “Engineering” department. Our main query then uses this in a sub-select to only return the Employee records that match.

Note that the return type from our WITH clause is always an AnonymousTupleType.This means that we can only include individual values in it, and not entire entities. We also need to give every value a distinct name with AS. We can then refer to these values by name in the main query.

Here, the engineers result set contains IDs 2, 4, 5, 7, 8, 9, and 12. Our IN clause then matches only those when selecting Employee entities, before further filtering by salary, to give an overall result of “Ben”, “David”, “Ella” and “Grace”.

We can also make our WITH clause more complicated, allowing us to resolve this complexity once and refer to it as needed in our main query:

List<Employee> employees = session.createQuery("""
    WITH dept_avg AS (
        SELECT e.department AS department, AVG(e.salary) AS avgSalary
        FROM Employee e
        GROUP BY e.department
    )
    SELECT e
    FROM Employee e
    JOIN dept_avg d ON e.department = d.department
    WHERE e.salary > d.avgSalary
    ORDER BY e.department, e.salary DESC
""", Employee.class).getResultList();

This time, our WITH clause is an aggregate query that will calculate the average salary for each department. On a very large table, this could be expensive. Writing it as a CTE separates the calculation from the main query, making the query easier to read and maintain. Depending on the database and its optimizer, the CTE may be materialized once or inlined into the main query, whichever produces the most efficient execution plan.

Here, our dept_avg result set will be as follows:

Our main query can then join to this by name, as if it were a table or view in the database. This then allows us to combine the data from our dept_avg result set with the data from our main Employee entity to match the rows that we’re interested in. In this case, “Ben”, “David”, “Ella”, “Carla” and “Frank”.

5. Recursive CTEs

The place that CTEs can become really powerful is when we want to do any graph-based queries. We can write our WITH clause to be recursive. We do this by splitting it into two parts with a UNION, and can then reference back to the same named WITH clause from within this second part:

For example, let’s start with a simple CTE query:

List<Employee> employees = session.createQuery("""
    WITH subordinates AS (
        SELECT e.id AS id FROM Employee e WHERE e.manager.id = 2
    )
    SELECT e
    FROM Employee e
    WHERE e.id IN (SELECT s.id FROM subordinates s)
    ORDER BY e.department, e.name
    """, Employee.class).getResultList();

On its own, this is an overly complicated way to return every Employee who has a manager ID of “2”. Running this as-is will return “David” and “Ella”.

However, we can extend the WITH clause to be recursive as follows:

List<Employee> employees = session.createQuery("""
    WITH subordinates AS (
        SELECT e.id AS id FROM Employee e WHERE e.manager.id = 2
    
        UNION
    
        SELECT e2.id AS id FROM Employee e2 JOIN subordinates s ON e2.manager.id = s.id
    )
    SELECT e
    FROM Employee e
    WHERE e.id IN (SELECT s.id FROM subordinates s)
    ORDER BY e.department, e.name
    """, Employee.class).getResultList();

All we’ve added here is the UNION and the second part of our WITH clause. This now selects every Employee whose manager ID is either “2” or is part of the already built list of IDs. This will then return “David”, “Ella”, “Grace”, “Hugo”, “Ivy” and “Liam”.

This query even reached as far as “Liam”, who is 3 steps away from our original ID, and it would continue as far as the data allowed it.

Note that by using UNION instead of UNION ALL, if we ever encounter a situation where the data is cyclical, we’ll only return each unique row once.

6. Summary

In this article, we’ve had a very brief look at using CTEs in Hibernate. We’ve seen what they are, how they work, and how we can use them. Next time you need queries like this, why not give it a go?

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

The post CTE Support in Hibernate first appeared on Baeldung.

       

1. Overview

The Apache Camel OpenAI component, introduced in Camel 4.17, enables integration of Java applications with OpenAI or OpenAI-compatible LLM (Large Language Model) servers such as Ollama or vLLM. Basically, it uses Camel routes for interaction with LLMs and handles message conversion between Camel Exchanges and OpenAI requests. It uses the OpenAI Java API library under the hood.

In this tutorial, we’ll discuss LLM integration with the Apache Camel OpenAI component and see several examples.

2. Maven Dependencies

We have to add the following Maven dependency to our pom.xml:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-openai</artifactId>
    <version>4.18.0</version>
</dependency>

3. Basic Interaction With an LLM

The component uses the standard Camel URI (Uniform Resource Identifier) format: openai:operation[?options]. The openai part of the URI is fixed.

The operation part corresponds to the URI’s path parameter. Two operations are supported: chat-completion and embeddings. chat-completion, which is of interest to us, generates chat responses using a model. The other operation, embeddings, is useful for creating vector embeddings, for example, in RAG (Retrieval-Augmented Generation) pipelines.

The options part corresponds to the URI’s query parameters. These are generally configuration options such as model choices, generation settings, and authentication parameters. For example, the model option specifies which LLM to use. We can also pass these options using message headers instead of the URI.

3.1. Chat Application

In this section, we’ll examine a simple chat application that interacts with an LLM. The application sends a prompt to the model and displays the model’s response.

Let’s start by using the Apache Camel’s Main class to configure, run, and handle the lifecycle of a standalone Apache Camel application:

Main main = new Main();
main.configure()
  .addRoutesBuilder(new ChatRoute());
main.start();

The addRoutesBuilder() method registers a custom routing class, ChatRoute, that implements the routing rules. The routing logic includes how Apache Camel takes a prompt, wraps it in an HTTP call to an LLM, and processes the response. The start() method of the Main class starts the runtime, instantiates the routes, and begins processing prompts.

Then, let’s send a message to an endpoint using the ProducerTemplate class:

ProducerTemplate template = main.getCamelContext()
    .createProducerTemplate();
String aiResponse = template.requestBody("direct:startChat", userPrompt, String.class);

We use the requestBody() method of ProducerTemplate to pass the prompt to the route. The first argument, “direct:startChat”, is the endpoint that the LLM exposes. direct: is an Apache Camel component providing synchronous invocation of routes. startChat is the name we give to the endpoint.

Our application uses this endpoint to communicate with the LLM. We pass the second argument, userPrompt, to the LLM and store its response in the variable aiResponse. The third argument, String.class, tells Apache Camel that we expect the response to be of type String. Therefore, the type of aiResponse is String.

3.2. The Routing Class

Next, let’s discuss the routing class. We extend the ChatRoute class from the RouteBuilder class to create routing rules using the Java DSL (Domain-Specific Language):

public class ChatRoute extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        onException(Exception.class).handled(true)
          .log(org.apache.camel.LoggingLevel.INFO, "OpenAI Error: ${exception.message}")
          .setBody(simple("OpenAI request failed."));
        from("direct:startChat")
          .setHeader(
            OpenAIConstants.SYSTEM_MESSAGE,
            constant("You are a helpful, brief IT support assistant."))
          .setHeader(OpenAIConstants.TEMPERATURE, constant(0.1))
          .setHeader(OpenAIConstants.MODEL, constant("gpt-4o-mini"))
          .to("openai:chat-completion")
          .log("AI Response: ${body}");
    }
}

We override the configure() method, which acts as the entry point. from(“direct:startChat”) defines a synchronous endpoint named startChat. As we saw in the previous subsection, applications can send user prompts to this endpoint by calling template.requestBody(“direct:startChat”, userPrompt, String.class).

The three setHeader() calls attach OpenAI-specific message headers by injecting the following key-value pairs:

• SYSTEM_MESSAGE sets the system prompt to “You are a helpful, brief IT support assistant.” and therefore defines the behavior and tone of the model.
• MODEL picks gpt-4o-mini as the target LLM.
• TEMPERATURE sets the sampling temperature to 1, thereby making the model more deterministic.

to(“openai:chat-completion”) is the actual call to the OpenAI component. It extracts the message body (i.e., the user prompt) and the headers, performs the OpenAI chat completion request, and waits for the response.

Instead of using message headers above, we can also use the Camel URI. For example, we can set the model and temperature options using the URI:

.to("openai:chat-completion?model=gpt-4o-mini&temperature=0.1")

Finally, log(“AI Response: ${body}”) prints the model’s response.

We must authenticate our application while making requests to OpenAI’s developer platform. One method for authentication is to set the confidential OpenAI API key to the OPENAI_API_KEY environment variable from the terminal we’ll run the application in Linux:

$ export OPENAI_API_KEY=<our_confidential_actual_key_here>

Let’s see the response of the LLM when we send the prompt, “Give me information about Baeldung”:

AI Response: Baeldung is a popular online platform that provides tutorials and articles primarily focused on Java, 
Spring Framework, and related technologies.
...
The content is well-structured and often includes practical examples, 
making it a valuable resource for both beginners and experienced developers.

The output shows that we received a successful response to our prompt. We abbreviated the response as it’s long.

4. Using Other OpenAI-Compatible Endpoints

The Apache Camel OpenAI component allows us to switch easily to other OpenAI-compatible endpoints using the baseUrl option. The endpoint can point to local or third-party providers. For example, we just need to change the router code as follows to use a local Ollama server:

.setHeader(OpenAIConstants.MODEL, constant("qwen3.5:9b"))
.to("openai:chat-completion?baseUrl=http://localhost:11434/v1")

The default value of baseUrl is https://api.openai.com/v1. We used the default OpenAI endpoint in the previous section. Therefore, we didn’t specify it explicitly. However, by setting baseUrl to http://localhost:11434/v1, we send the requests to the local Ollama server instead of OpenAI’s servers.

We also set the model to qwen3.5:9b in our example. Before sending prompts to the model, the model must have been run locally using the ollama run command. We don’t need to use a real API key while using Ollama locally. But an API key is still required. So we can set it to a dummy value for compatibility with OpenAI. But third-party providers over the cloud, like Ollama’s cloud service, require a real API key.

5. Keeping Conversational Memory

By default, conversational memory isn’t retained by the OpenAI component; i.e., OpenAI doesn’t remember the responses to previous prompts. For example, if we tell an LLM our name in one prompt and then ask for it in the next prompt, it will usually respond that it doesn’t know our name.

To maintain conversational memory with the OpenAI component, we need to make two changes to the previous example. Firstly, we must reuse the same Exchange object on the application side:

Exchange exchange = template.getCamelContext()
  .getEndpoint("direct:startChatWithMemory")
  .createExchange();
for (String prompt : prompts) {
    exchange.getMessage()
      .setBody(prompt);
    template.send("direct:startChatWithMemory", exchange);
                
aiResponses.add(exchange.getMessage()
  .getBody(String.class));

Once the Exchange object is created, namely exchange in the code snippet above, we use the same object in a for loop for processing the prompts. The prompts variable is a list of strings containing the prompts:

List<String> prompts = List.of("My name is Burak and I am a Java developer.", "What is my name and what do I do?"
);

The first prompt specifies the user’s name and job, and the second prompt asks them.

Secondly, we must set the conversationMemory option to true on the router side:

.to("openai:chat-completion?conversationMemory=true")

When we run the application, the response to the first prompt, “My name is Burak and I am a Java developer.”, is as follows:

Hi Burak! How can I assist you today with your Java development?

Let’s see the response to the second prompt, “What is my name and what do I do?”:

Your name is Burak, and you are involved in Java development. How can I assist you further?

Therefore, reusing the same Exchange object while setting the conversationMemory option to true enables us to persist storage between calls.

6. Providing Structured Output

The OpenAI component can also present the LLM’s response in a deterministic format. For example, we can map the response to a POJO (Plain Old Java Object), which can be directed safely to a database. Let’s discuss an example that returns a book’s name, author, and summary:

public static BookInfo runChat(String userPrompt) throws Exception {
    ...
    BookInfo bookInfo = template.requestBody("direct:startBookChat", userPrompt, BookInfo.class);
    return bookInfo;
    ...
}

The runChat() member function in the above code snippet takes a user prompt as a string and passes it to the router by calling the requestBody() method of ProducerTemplate. The third argument of requestBody(), BookInfo.class, specifies the response to be a BookInfo object. The BookInfo class consists of three public member variables:

public class BookInfo {
    public String name;
    public String author;
    public String summary;
}

We also need to update the router class:

from("direct:startBookChat")
  .setHeader(OpenAIConstants.SYSTEM_MESSAGE, constant("You are a helpful, brief book advisor."))
  .setHeader(OpenAIConstants.MODEL, constant("gpt-4o-mini"))
  .setHeader(OpenAIConstants.TEMPERATURE, constant(0.1))
  .to("openai:chat-completion?outputClass=com.baeldung.apachecamel.BookInfo")
  .unmarshal()
  .json(JsonLibrary.Jackson, BookInfo.class)
  .log("AI Response: ${body}");

Here, we use the outputClass option to instruct the LLM to respond in JSON format that matches the BookInfo schema. The next calls, unmarhal() and json(JsonLibrary.Jackson, BookInfo.class), use the Apache Camel JSON Jackson component. They convert the raw JSON string in the message body and deserialize it to BookInfo.

Let’s see an example of asking for the author and summary of a book, The Time Regulation Institute:

String userPrompt = "Can you provide the author and summary of the following book: The Time Regulation Institute";
BookInfo book = runChat(userPrompt);
LOGGER.info("Book: {}", book.name);
LOGGER.info("Author: {}", book.author);
LOGGER.info("Summary: {}", book.summary);

Here is the abbreviated output:

Book: The Time Regulation Institute
Author: Ahmet Hamdi Tanpınar
Summary: A satirical novel that explores the absurdities of modernity and the clash between 
tradition and progress in Turkish society, focusing on the establishment of a time regulation 
institute and its impact on the characters' lives.

The output shows that the response was successfully mapped to the Java class BookInfo.

7. Conclusion

In this article, we discussed LLM integration with the Apache Camel OpenAI component.

Firstly, we learned how to send prompts to an LLM using Camel routes and implemented a chat completion application based on them. Then, we saw how to change the OpenAI-compatible endpoint. We also learned to maintain conversational memory so that the model can remember previous prompts throughout a chat. Finally, we discussed formatting an LLM’s responses in a predefined format.

Besides the applications we discussed, there are other use cases. For example, we can process an LLM’s responses chunk by chunk rather than waiting for the full completion of a response. We have to set the streaming option to true. Another example is the support for multi-modal inputs. We can use text files and images with vision-capable models.

As usual, the complete source code for the examples is available over on GitHub.

The post LLM Integration With Apache Camel OpenAI Component first appeared on Baeldung.

       

1. Introduction

Every time we start a Java app, the JVM rebuilds the same classes from scratch, which shows up in the startup time. The Ahead-of-Time (AOT) cache lets us use caching to reuse the build’s output, so later runs start faster. In this tutorial, we’ll use the AOT cache on a sample app. We’ll build a cache for the app, confirm that the JVM really uses the AOT cache, and then train the cache. We’ll use JDK 26 for this tutorial.

2. What Is the Ahead-of-Time Cache in Java

The feature first arrived in JDK 24 through JEP 483, as the first piece of Project Leyden. JDK 25 added method profiles so the JIT can warm up sooner, and JDK 26 lifted the old garbage-collector limit through JEP 516. In the following sections we look at how the cache achieves what it claims. Let’s consider a small catalog service that we already have on hand: its code lives in one app.jar, packaged next to the handful of library JARs it depends on, and it boots through a com.example.App main class. We’ll build a cache for the app, confirm the JVM uses the cache, and then train well enough to see speed gains in its loading time.

2.1. How the Cache Speeds Up Startup

Normally the JVM reads, loads, and links each class as the app boots, and it repeats that work on every run. The cache changes this by saving those classes once, so that on the next run they come straight from disk instead of being rebuilt. Because our cache captures the work of one specific app, we reuse it whenever we run that same app. The speedup comes from moving the heavy lifting earlier, which leaves the classes ready the moment the program starts.

2.2. Training and Production Runs

Before we discuss the caching workflow, it helps to discuss two words we’ll lean on throughout: training and production. A training run is one we carry out deliberately, ahead of time, to watch the app and build the cache from what we observe, so it never serves real users. A production run, by contrast, is the real deployment that serves traffic, and it loads the finished cache to start faster.

2.2. The Three-Phase Workflow

The original workflow of the caching process runs in three phases, namely record, create, and run. Each step feeds the next. We start with the record phase. Here the JVM watches the app and writes what it sees to a configuration file. We switch it on with a flag and name the file through a configuration:

java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf \
  -cp app.jar com.example.App ...

As it runs, this phase notes which classes load and which methods turn hot, then stores those findings in app.aotconf. Once the file is created, the next step comes to effect. We feed the file into the create phase, which turns the recorded data into a real cache:

java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf \
  -XX:AOTCache=app.aot -cp app.jar

Once the cache exists, the run phase simply points at it and benefits from the faster start:

java -XX:AOTCache=app.aot -cp app.jar com.example.App ...

We observe here that since the classes are already prepared, this final run skips the work the first two phases did. In the three phases discussed above, the record and create steps make up the training side, while the run phase stands in for production.

3. How to Build the Cache

We should now focus on building the cache. Running the three phase workflow everytime is not very developer friendly. Also, it’s more than most apps need. In the following sections, we discuss how JDK 25 folded and converged the cache building steps.

3.1. Making the Cache in One Step

We hand a destination to -XX:AOTCacheOutput, and the JVM builds the cache for us. It shuts down and outputs it in the mentioned destination:

java -XX:AOTCacheOutput=app.aot \
  -cp app.jar com.example.App ...

If we’d rather keep the training command separate from deployment, JEP 514 offers a two-step variant that records once and then reuses the cache:

java -XX:AOTCacheOutput=app.aot \
  -cp app.jar com.example.App ...
java -XX:AOTCache=app.aot -cp app.jar com.example.App ...

For the majority of apps, this shorter path is what is used.

3.2. Splitting the Work for Small Machines

Convenient as the one-step path is, it comes with a memory bill. While it assembles the cache, the JVM spins up a second heap the same size as the training heap, so the peak demand climbs to roughly twice the size we set. With -Xms2g -Xmx2g, for instance, the machine needs about 4 GB before it finishes. That overhead is why the three-phase split still earns its place on small cloud servers. We can record on a modest instance that mirrors production, and then assemble the cache on a larger one where there’s room to spare. The recording stays faithful to the real environment, while the heavy assembly runs where memory is plentiful.

4. How to Shape the Cache Our App Needs

A cache only pays off when the training run and the production are in line. And this require a handful of conditions to be satisfied.

4.1. Keeping Training and Production aligned

Let’s see a few rules which ensure the training and production runs align:

• the JAR timestamps stay the same across training runs
• both runs use the same JDK, hardware, and OS
• the training run acts like the real one, so the busy paths match
• the classpath is a list of plain JARs, with no folders, wildcards, or nested JARs
• the production classpath holds at least what the training one holds
• no JVMTI agent adds to the boot or system class search at run time

Following the above, we should ideally see the deployment run produce the same result as training, and perhaps faster.

4.2. Checking That the Cache Is Valid

Rather than trusting the cache blindly, we can ask the JVM to treat a broken setup as a hard failure. Adding -XX:AOTMode=on does exactly that, turning a silent fallback into a clear error:

java -XX:AOTCache=app.aot -XX:AOTMode=on \
  -cp app.jar com.example.App ...

So if the cache goes missing, or one of the conditions above slips, the run stops instead of quietly dropping the speedup. It’s worth remembering, though, that the cache is valid for a single build only. A code change, a new or updated library, or a JDK upgrade each invalidate it. This means we regenerate the cache alongside every build. And when the expected gain fails to appear, we can trace what the cache loads by adding -Xlog:aot,class+path=info.

5. Tips for Good Training Runs

Of the three phases we’ve covered, the training run is the one that carries the real weight. The create and run phases are mostly mechanical: they package whatever the training run observed and replay it on startup, without judging whether that was the right thing to capture. So the cache is only ever as good as the run that built it. Let’s discuss a few tips for architecting a good training run.

5.1. Matching What Production Loads

There’s a natural trade-off between how realistic a training run is and how easy it is to stage. A true production run opens connections, queries the database, and writes logs, all of which are difficult to reproduce. Therefore a synthetic run that follows the same paths usually strikes the better balance. What matters most is overlap. The closer the training run loads the same classes as production, the better the startup we get. To see that overlap, we can list everything a run loads by adding -verbose:class when we launch it. A light smoke test gives us a tidy way to drive those results. It exercises a normal startup without pulling in heavy suites, which keeps the cache lean. We named it in BDD style while keeping the framework minimal:

class StartupSmokeTest {
    @Test
    void givenFreshApplication_whenMainPathRuns_thenCoreServicesInitialize() {
        App app = App.bootstrap();
        assertTrue(app.isReady());
        assertNotNull(app.catalogService());
    }
}

We rely on tests like this for the common startup paths. Also, we are deliberately leaving the stress and regression suites out of the training run.

5.2. Finding Hot Methods With JFR

Now and then a method matters at run time yet never surfaces during a shallow training run. The JDK Flight Recorder is how we catch those cases. We begin by enabling the class-load event, then record the app from the moment it starts. Let’s start by first enabling the event: jfr configure jdk.ClassLoad#enabled=true Now, let’s start the recording: java -XX:StartFlightRecording:settings=custom.jfc,duration=60s,filename=/tmp/AOT.jfr With a recording in hand, we can check the loaded classes and the hottest methods:

jfr print --events "jdk.ClassLoad" /tmp/AOT.jfr
jfr view hot-methods /tmp/AOT.jfr

If a hot method turns out to be missing, we extend the smoke test to walk through it. We start by leaning on a temporary folder, then a local network, or a mocked database wherever the path demands one.

6. Best Practices

A healthy cache really comes down to a few recurring habits and practices:

• Validity, since every rebuild or JDK upgrade calls for a fresh cache
• Portability, since the cache is bound to one JVM and platform
• Coverage, since the training run has to walk the normal startup paths
• Setup, since both the JAR and the cache should run with least privilege

7. Conclusion

In this tutorial, we followed the whole AOT cache promise. We built a cache both in a single step and across three phases. Additionally, we confirmed that the JVM was really using it, and then trained it with a light smoke test so it covered the paths that count. Taken together, these steps make the cache easy to add and just as easy to keep current.

The post A Guide to Ahead-of-Time Cache in the Java first appeared on Baeldung.

       

1. Overview

Large language models are stateless, so every request we send is independent unless we replay the earlier conversation ourselves. Spring AI has traditionally solved this with ChatMemory, but as conversations grow, naively replaying every message quickly overflows the model’s context window.

In this tutorial, we’ll explore Spring AI Session, an event-sourced short-term memory layer that stores conversation history and shrinks it intelligently when it gets too large. We’ll create and inspect sessions, plug memory into a ChatClient through an advisor, and review the available compaction strategies.

2. What Are Memory Sessions?

A session is a container for a single conversation, identified by an ID and optionally tied to a user. Instead of storing a flat list of messages, it records an ordered stream of SessionEvent objects, each wrapping a Message with a timestamp, a unique ID, and optional branch information.

The library groups these events into turns. A turn is one user message plus every assistant reply, tool call, and tool result that follows it, until the next user message. Turns are the atomic unit the library never breaks apart.

That last point is the key improvement over the older ChatMemory API. When history grows too large, Spring AI Session compacts it along turn boundaries rather than evicting the oldest individual messages. This way, we never end up with a dangling tool call whose result was dropped. For reference, a MessageWindowChatMemory capped at 20 messages becomes a TurnCountTrigger(20) paired with a sliding-window strategy.

Every event is immutable and timestamped. This lets the same session support more advanced scenarios, such as isolating the histories of cooperating agents through branch labels.

Sessions are currently incubating in the spring-ai-community project and are slated to replace ChatMemory in a future Spring AI release.

3. Setting Up the Project

The Session API requires Spring AI 2.x and Spring Boot 4.x. We add the core module, which ships the in-memory repository and all the compaction building blocks:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-session-management</artifactId>
    <version>0.5.0</version>
</dependency>

The latest version of spring-ai-session-management is available in the Maven Repository.

To talk to a model, we add a Spring AI chat starter. The session layer is provider-agnostic, so OpenAI, Anthropic, or a local model works just as well. Here, we use spring-ai-starter-model-google-genai with our Gemini API key:

spring.ai.google.genai.api-key=${GEMINI_API_KEY}
spring.ai.google.genai.chat.options.model=gemini-3.5-flash

For production, we’d typically swap the in-memory store for a relational one. Adding the spring-ai-starter-session-jdbc starter auto-configures a JDBC repository for PostgreSQL, MySQL, MariaDB, or H2. In this tutorial, we’ll stick with the in-memory repository to keep the examples self-contained.

4. Creating and Managing Sessions

A SessionService is the entry point for the whole API. We start by exposing it as a bean backed by an InMemorySessionRepository:

@Bean
public SessionService sessionService() {
    return DefaultSessionService.builder()
      .sessionRepository(InMemorySessionRepository.builder().build())
      .build();
}

Let’s create a session, append a couple of messages, and read them back as plain Spring AI messages:

@Test
void givenSession_whenAppendingMessages_thenStoredInOrder() {
    Session session = sessionService.create(CreateSessionRequest.builder()
      .userId("alice")
      .build());
    sessionService.appendMessage(session.id(), new UserMessage("What is Spring AI?"));
    sessionService.appendMessage(session.id(),
      new AssistantMessage("It's an application framework for AI engineering."));
    List<Message> messages = sessionService.getMessages(session.id());
    assertThat(messages).hasSize(2);
    assertThat(messages.get(0).getMessageType()).isEqualTo(MessageType.USER);
    assertThat(messages.get(1).getMessageType()).isEqualTo(MessageType.ASSISTANT);
}

For lower-level access, getEvents() returns the richer SessionEvent stream, including timestamps and metadata. The service also lets us look up a conversation later with findById() or list everything for a user through findByUserId(). Finally, we can set a time-to-live on CreateSessionRequest so stale sessions expire automatically.

5. Using the SessionMemoryAdvisor

Managing the service by hand is useful, but most applications want memory to work transparently, much like the advisors we lean on when building an AI assistant. The SessionMemoryAdvisor hooks the session into the ChatClient pipeline, loading history before each call and appending the new exchange afterward. It’s a standard Spring AI advisor.

5.1. Configuring the Advisor Bean

Now, let’s expose the advisor as a bean, attaching a compaction trigger and strategy:

@Bean
public SessionMemoryAdvisor sessionMemoryAdvisor(SessionService sessionService) {
    return SessionMemoryAdvisor.builder(sessionService)
      .defaultUserId("alice")
      .compactionTrigger(new TurnCountTrigger(20))
      .compactionStrategy(SlidingWindowCompactionStrategy.builder()
          .maxEvents(10)
          .build())
      .build();
}

This configuration keeps the ten most recent events and compacts once a session passes twenty turns.

5.2. Wiring It Into ChatClient

Next, we register the advisor as a default on a ChatClient, then identify the conversation with the session-ID parameter on each call:

@Component
public class ChatService {
    private final ChatClient chatClient;
    public ChatService(ChatModel chatModel, SessionMemoryAdvisor sessionMemoryAdvisor) {
        this.chatClient = ChatClient.builder(chatModel)
          .defaultAdvisors(sessionMemoryAdvisor)
          .build();
    }
    public String chat(String sessionId, String prompt) {
        return chatClient.prompt()
          .user(prompt)
          .advisors(a -> a.param(SessionMemoryAdvisor.SESSION_ID_CONTEXT_KEY, sessionId))
          .call()
          .content();
    }
}

The advisor stores every exchange under that session ID, so a follow-up question resolves against the earlier context. In the test below, we share a name in the first message, then ask for it back in a second one. The assertion confirms the reply still recalls the name, proving the session preserved context across the two turns:

@Test
void givenSessionId_whenChattingAcrossTurns_thenContextIsRemembered() {
    chatService.chat("session-abc", "My name is Yadier, remember it.");
    String response = chatService.chat("session-abc", "What is my name?");
    assertThat(response).containsIgnoringCase("Yadier");
    assertThat(sessionService.getMessages("session-abc")).hasSize(4);
}

The second call answers with the remembered name, which confirms the advisor replayed the first turn from the session before calling the model.

6. Compaction Strategies

A compaction trigger decides when to shrink history, while a strategy decides how. Besides TurnCountTrigger, we can trigger on estimated tokens with TokenCountTrigger, or combine conditions with CompositeCompactionTrigger.

6.1. Comparing the Strategies

The library ships four strategies, all of which respect turn boundaries:

The first three strategies drop older events outright, so they’re fast and free — a good default when we just need to cap history cheaply. Recursive summarization instead preserves the gist of what it removes, at the cost of an extra model call. In short, we reach for recursive summarization only when we need to recall older context, otherwise, the cheaper windowing strategies are enough.

6.2. Running Compaction Manually

The SessionMemoryAdvisor runs compaction automatically as a session grows, but we can also trigger it ourselves by calling compact() directly. That’s handy in tests or batch jobs where we decide exactly when history shrinks. Let’s use the SlidingWindowCompactionStrategy to keep only the most recent events, passing it and a trigger to compact(), which returns a CompactionResult describing what it archived:

@Test
void givenMultiTurnConversation_whenCompacting_thenOlderEventsAreArchived() {
    Session session = sessionService.create(CreateSessionRequest.builder()
      .userId("alice")
      .build());
    for (int turn = 1; turn <= 4; turn++) {
        sessionService.appendMessage(session.id(), new UserMessage("Question " + turn));
        sessionService.appendMessage(session.id(), new AssistantMessage("Answer " + turn));
    }
    CompactionResult result = sessionService.compact(session.id(),
      new TurnCountTrigger(2),
      SlidingWindowCompactionStrategy.builder()
        .maxEvents(4)
        .build());
    assertThat(result.eventsRemoved()).isPositive();
    assertThat(sessionService.getEvents(session.id())).hasSameSizeAs(result.compactedEvents());
}

First we build up four turns, then we compact the session. Finally, we verify that some events were removed and the stored history now matches the compacted result. The assertions confirm that older events were archived and that the session now holds only the compacted set.

6.3. Summarizing With an LLM

Recursive summarization is the one strategy that needs a ChatClient. The other three simply drop or window events, but this one asks a model to write a summary of the events it removes, then replaces them with a single synthetic summary event. That extra model call is the price for keeping older context available in condensed form:

@Test
void givenLongConversation_whenSummarizing_thenOlderEventsAreReplacedBySummary() {
    Session session = sessionService.create(CreateSessionRequest.builder()
      .userId("alice")
      .build());
    for (int turn = 1; turn <= 4; turn++) {
        sessionService.appendMessage(session.id(), new UserMessage("Question " + turn));
        sessionService.appendMessage(session.id(), new AssistantMessage("Answer " + turn));
    }
    ChatClient chatClient = ChatClient.builder(chatModel).build();
    CompactionResult result = sessionService.compact(session.id(),
      new TurnCountTrigger(2),
      RecursiveSummarizationCompactionStrategy.builder(chatClient)
        .maxEventsToKeep(4)
        .build());
    SessionEvent summary = result.compactedEvents().stream()
      .filter(SessionEvent::isSynthetic)
      .findFirst()
      .orElseThrow();
    assertThat(result.eventsRemoved()).isPositive();
    assertThat(summary.getMessage().getText()).isNotBlank();
}

The synthetic event in the compacted set is the model-generated summary, so the session keeps the gist of the dropped turns in condensed form.

7. Conclusion

In this article, we explored Spring AI’s short-term memory sessions. We saw how a SessionService stores conversations as turn-aware events. The SessionMemoryAdvisor makes that memory transparent to the ChatClient. Finally, pluggable triggers and strategies keep history within the model’s context window.

As the API graduates from incubation, it’s positioned to become the default replacement for ChatMemory, so investing in it now sets us up for the long term.

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

The post A Guide to Short-Term Memory Sessions in Spring AI first appeared on Baeldung.

       

1. Introduction

@SpringBootApplication
public class ApplicationStartupTrackingApplication {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(ApplicationStartupTrackingApplication.class);
        app.setApplicationStartup(new BufferingApplicationStartup(2048));
        app.run(args);
    }
}

4.2. Access via the Actuator Endpoint

One way to retrieve the recorded events is via an actuator endpoint. Specifically, we can enable the startup actuator in the application properties:

management.endpoints.web.exposure.include=startup

In case we have a Spring bean, we also make the necessary addition:

@Service
public class SpecialService {
}

If we access the actuator, we can see an entry for the service bean:

curl localhost:8080/actuator/startup | jq
{
  "duration": "PT0.000754S",
  "endTime": "2026-07-19T18:31:27.493778Z",
  "startTime": "2026-07-19T18:31:27.493024Z",
  "startupStep": {
    "id": 107,
    "name": "spring.beans.instantiate",
    "parentId": 4,
    "tags": [
      {
        "key": "beanName",
        "value": "specialService"
      }
    ]
  }
}

It’s important to note that the actuator only works with BufferingApplicationStartup. If we configure the application with any other implementation of the ApplicationStartup interface, we see an error message:

curl localhost:8080/actuator/startup | jq
{
  "timestamp": "2026-07-19T14:37:45.989Z",
  "status": 404,
  "error": "Not Found",
  "path": "/actuator/startup"
}

Furthermore, we can call the actuator endpoint with a GET or a POST request. In both cases, the response should be the same; however, GET returns a snapshot of the timeline, while POST returns the snapshot and also clears the buffer.

4.3. Access via the Application Context

In addition to using the actuator endpoint, we can programmatically access the timeline BufferingApplicationStartup provides. To do so, we access the configured BufferingApplicationStartup instance:

@Component
public class StartupTracker {
    private BufferingApplicationStartup startup;
    
    public StartupTracker(@Autowired ApplicationContext context) {
        startup = (BufferingApplicationStartup) (
            (ConfigurableApplicationContext) context).getApplicationStartup();
    }
    public List recorded() {
        List recordedEvents = new ArrayList<>();
        for(StartupTimeline.TimelineEvent event : startup.getBufferedTimeline().getEvents()) {
            for(StartupStep.Tag tag : event.getStartupStep().getTags()) {
                recordedEvents.add(
                    event.getStartupStep().getName() + "  " +
                        tag.getKey() + " " +
                        tag.getValue()
                );
            }
        }
        return recordedEvents;
    }
}

Thus, we have access to the deeper startup context.

4.4. Usage in Spring Boot Tests

This way, we can analyze the timeline and create a custom output format, filter certain events, and also test the implementation:

@SpringBootTest(useMainMethod = SpringBootTest.UseMainMethod.ALWAYS)
public class ApplicationTest {
    @Autowired
    private StartupTracker startupTracker;
    @Test
    void givenTheApplicationStarts_whenRetrieveRecordedEvents_ThenContainsCustomBeans() {
        Assertions.assertThat(startupTracker.recorded()).contains(
            "spring.beans.instantiate  beanName specialService",
            "spring.beans.instantiate  beanName startupTracker"
        );
    }
}

We can see that the list of events includes the two beans that we have created, SpecialService and StartupTracker.

Notably, we need to configure the test with SpringBootTest.UseMainMethod.ALWAYS. This ensures that we start the application via the main method and Spring Boot is configured to use BufferingApplicationStartup instead of the no-op implementation.

app.setApplicationStartup(new FlightRecorderApplicationStartup());

-XX:StartFlightRecording:filename=recording.jfr,duration=20s

The recommended way to customize the startup timeline is to add custom startup steps to the ApplicationStartup instance that we can retrieve from the application context. To demonstrate how to do that, let’s create a service class and add some custom steps:

@Service
public class SpecialService {
    private ApplicationStartup applicationStartup;
    public SpecialService(ApplicationContext context) {
        this.applicationStartup = ((ConfigurableApplicationContext) context).getApplicationStartup();
    }
    @PostConstruct
    public void init() {
        StartupStep startupStep1 = this.applicationStartup.start("com.baeldung.special.service");
        try {
            startupStep1.tag("init", "connect to databases");
            // some long-running initialization
        } finally {
            startupStep1.end();
        }
        StartupStep startupStep2 = this.applicationStartup.start("com.baeldung.special.service");
        try {
            startupStep2.tag("init", "connect to AI agent");
            // more long-running initialization
        } finally {
            startupStep2.end();
        }
    }
}

So, we can now see a step for the initialization of the SpecialService bean as the parent step (id=107) and the two additional steps (id=[108,109]) in the response of the actuator:

[
  {
    "duration": "PT0.000006S",
    "endTime": "2026-07-18T19:15:12.096227Z",
    "startTime": "2026-07-18T19:15:12.096221Z",
    "startupStep": {
      "id": 108,
      "name": "com.baeldung.special.service",
      "parentId": 107,
      "tags": [
        {
          "key": "init",
          "value": "connect to databases"
        }
      ]
    }
  },
  {
    "duration": "PT0.000002S",
    "endTime": "2026-07-18T19:15:12.096238Z",
    "startTime": "2026-07-18T19:15:12.096236Z",
    "startupStep": {
      "id": 109,
      "name": "com.baeldung.special.service",
      "parentId": 107,
      "tags": [
        {
          "key": "init",
          "value": "connect to AI agent"
        }
      ]
    }
  },
  {
    "duration": "PT0.000682S",
    "endTime": "2026-07-18T19:15:12.096328Z",
    "startTime": "2026-07-18T19:15:12.095646Z",
    "startupStep": {
      "id": 107,
      "name": "spring.beans.instantiate",
      "parentId": 4,
      "tags": [
        {
          "key": "beanName",
          "value": "specialService"
        }
      ]
    }
  }
]

The output shows metrics for both startup steps: connect to databases and connect to AI agent, as well as a step for the creation of the service itself spring.beans.instantiate. As seen earlier, we can also monitor these startup steps in the Java Flight Recorder or programmatically via the BufferingApplicationStartup.

public class CustomStartup implements ApplicationStartup {
    @Override
    public StartupStep start(String name) {
        return new CustomStartupStep(name);
    }
}

public class CustomStartupStep implements StartupStep {
    private String name;
    public CustomStartupStep(String name) {
        this.name = name;
    }
    @Override
    public String getName() {
        return name;
    }
    // Override other methods
}

Since it’s a rare scenario, we don’t discuss a complete implementation of a custom ApplicationStartup class. One reason to implement a custom startup logic is the possibility to observe the steps in real time during context creation. This way, if needed, we can take action immediately, for example, to send a message if a bean creation takes a long time, instead of waiting until the entire context is created.

The post Application Startup Tracking in Spring first appeared on Baeldung.

       

1. Overview

Apache Causeway is a framework for building domain-driven applications on top of Spring Boot. Instead of beginning with controllers and pages, we describe domain objects, their state, behavior, and business rules. Causeway turns that description into a metamodel at runtime.

After that, the Wicket viewer and RESTful Objects viewer use the same metamodel to provide a web UI and a hypermedia API. This makes Causeway particularly useful for internal management software, where broad coverage of the domain and fast feedback often matter more than a custom interface.

In this tutorial, we’ll use Apache Causeway 3.6.0, Java 21, and Maven to build a small asset management application. Specifically, we’ll model assets such as laptops, monitors, and phones, add lifecycle actions and business rules, run the generated UI, and invoke one of the generated REST endpoints.

2. Mental Model

The domain is the business area that the software addresses.

2.1. Domain

The domain model is the set of types, relationships, operations, and rules that represent that area.

In this case, the domain is the management of company hardware:

• which assets exist
• who has them
• which lifecycle transitions are valid

So, the main domain object here is Asset. Because instances are stored in a database, Asset is also a domain entity. A view model, by contrast, could represent temporary or calculated information without having a persistent identity. Causeway exposes scalar values such as type, serialNumber, status, and assignedTo as properties. A relationship to several other objects would be a collection.

Behavior appears as actions such as assignTo(), returnToInventory(), and retire(). Operations that don’t naturally belong to one asset, such as creating or finding assets, live in the Assets domain service. Causeway uses these domain members as the common vocabulary for both its UI and REST viewers.

2.2. Causeway vs. Traditional Spring MVC Application

In a traditional Spring MVC application, a request usually reaches a controller, which performs several actions:

• calls an application service
• prepares a model or DTO
• selects a view or produces a response

Even when the business logic is well isolated, each new use case generally needs explicit web-layer code.

Causeway changes the starting point. It introspects entities, domain services, annotations, and method signatures, and records them in its metamodel. The viewers render the properties, collections, actions, parameters, and validation messages that the metamodel describes. Therefore, we can add a basic use case without creating a matching controller, form, and template.

This doesn’t remove the rest of the application architecture. We still configure Spring modules, persistence, security, and menu layout, and we can place complex orchestration in application services when appropriate. Causeway reduces presentation-layer repetition by making the domain model drive the interaction.

2.3. When Causeway Is a Good Fit

This model works well for back-office tools, administration systems, internal management applications, and domain-heavy prototypes. Such systems often combine structured data with many business operations, so a consistent generated interface lets a team validate terminology, workflows, and rules early.

It’s a weaker fit when the primary requirement is a highly branded consumer experience, pixel-level interaction design, or a page flow that doesn’t map naturally to domain objects. In such cases, we can place a custom client in front of the Causeway APIs, but doing so sacrifices some of the development speed offered by the generic viewer.

The common-use-case documentation of the framework presents the same spectrum, from prototyping and generic line-of-business UIs to custom clients. The important decision is whether domain coverage or presentation control is the stronger requirement.

3. Building an Internal Asset Management Application

Let’s model an asset with several characteristics:

• type
• serial number
• status
• assignee (optional)

The normal asset lifecycle is AVAILABLE to ASSIGNED, then back to AVAILABLE, while an available asset can also become RETIRED.

A runnable Causeway application needs framework module imports, persistence, security, and menu configuration in addition to the central domain code. To follow along, let’s keep the complete project on GitHub open. The snippets that follow cover the decisions relevant to the tutorial, while the repository contains the supporting bootstrap and configuration files.

3.1. Project Setup

To begin with, we need JDK 21 and Maven 3.9.11. The Causeway application starter parent manages the compatible Spring Boot and framework dependency versions. In pom.xml, let’s add the web application bundle, both viewers, Simple Security, JPA with EclipseLink, and an H2 in-memory database:

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.apache.causeway.app</groupId>
        <artifactId>causeway-app-starter-parent</artifactId>
        <version>3.6.0</version>
        <relativePath/>
    </parent>
    <groupId>com.baeldung</groupId>
    <artifactId>apache-causeway</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <!-- The name and description are omitted. -->
    <dependencies>
        <dependency>
            <groupId>org.apache.causeway.mavendeps</groupId>
            <artifactId>causeway-mavendeps-webapp</artifactId>
            <type>pom</type>
        </dependency>
        <dependency>
            <groupId>org.apache.causeway.viewer</groupId>
            <artifactId>causeway-viewer-wicket-viewer</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.causeway.viewer</groupId>
            <artifactId>causeway-viewer-restfulobjects-jaxrsresteasy</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.causeway.security</groupId>
            <artifactId>causeway-security-simple</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.causeway.persistence</groupId>
            <artifactId>causeway-persistence-jpa-eclipselink</artifactId>
        </dependency>
        <dependency>
            <groupId>org.apache.causeway.viewer</groupId>
            <artifactId>causeway-viewer-wicket-applib</artifactId>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-instrument</artifactId>
        </dependency>
        <!-- JUnit, Mockito, and Causeway test dependencies are omitted. -->
    </dependencies>
    <!-- EclipseLink weaving and Spring Boot packaging plugins are omitted. -->
    <properties>
        <java.version>21</java.version>
        <maven.compiler.release>21</maven.compiler.release>
    </properties>
</project>

The web application bundle supplies the common runtime dependencies. The viewer artifacts add the generated Wicket interface and RESTful Objects API, while Simple Security and H2 keep this example self-contained.

Next, a small Spring configuration class identifies the application code:

@Configuration
@ComponentScan(basePackageClasses = Assets.class)
@EnableJpaRepositories(basePackageClasses = AssetRepository.class)
@EntityScan(basePackageClasses = Asset.class)
public class AssetManagementModule {
}

Let’s break it down:

• @ComponentScan discovers the domain service
• @EnableJpaRepositories enables the Spring Data repository
• @EntityScan registers the JPA entity

Then, we import this configuration together with the required Causeway modules in AppManifest:

@Configuration
@Import({
    CausewayModuleApplibMixins.class,
    CausewayModuleCoreRuntimeServices.class,
    CausewayModuleSecuritySimple.class,
    CausewayModulePersistenceJpaEclipselink.class,
    CausewayModuleViewerRestfulObjectsJaxrsResteasy.class,
    CausewayModuleViewerWicketApplibMixins.class,
    CausewayModuleViewerWicketViewer.class,
    AssetManagementModule.class
})
@PropertySource(CausewayPresets.NoTranslations)
public class AppManifest {
    // Password encoding and the demo-only SimpleRealm configuration are omitted
}

Importing a module makes its Spring beans and Causeway features available to the application.

The repository also configures H2, EclipseLink schema creation, the demo user, and the menu layout. In application.yml, we set causeway.applib.annotation.action.explicit to true, so only methods explicitly annotated with @Action become actions.

3.2. Creating the Asset Domain Entity

Let’s define the persistent type and give it a stable logical name:

@Entity
@Table(
    schema = "assets",
    name = "Asset",
    uniqueConstraints = @UniqueConstraint(
        name = "Asset__serialNumber__UNQ",
        columnNames = "serial_number"
    )
)
@EntityListeners(CausewayEntityListener.class)
@Named("assets.Asset")
@DomainObject
@DomainObjectLayout
public class Asset implements Comparable<Asset> {
    protected Asset() {
    }
    public Asset(final AssetType type, final String serialNumber) {
        this.type = type;
        this.serialNumber = serialNumber;
        this.status = AssetStatus.AVAILABLE;
    }
    // The identifier, version, comparison helpers, and members discussed below are omitted
}

So, let’s take a closer look at what the code means:

• The JPA annotations map the entity and enforce a database-level uniqueness constraint on serial_number.
• @Named supplies the logical identifier that Causeway uses independently of the Java package name.
• @DomainObject explicitly identifies the class as a Causeway domain object.
• CausewayEntityListener connects JPA lifecycle events to Causeway, including service injection and lifecycle notifications.
• The public constructor establishes the first lifecycle invariant: every new asset begins in the AVAILABLE status.

JPA maps the stored values, while Causeway recognizes the corresponding getters as properties. To be clear, let’s see the identity properties:

@Enumerated(EnumType.STRING)
@Column(name = "type", nullable = false, length = 20)
private AssetType type;
@PropertyLayout(fieldSetId = LayoutConstants.FieldSetId.IDENTITY, sequence = "1")
public AssetType getType() {
    return type;
}
@Column(name = "serial_number", nullable = false, length = 80)
private String serialNumber;
@Title(prepend = "Asset: ")
@Property(maxLength = 80)
@PropertyLayout(fieldSetId = LayoutConstants.FieldSetId.IDENTITY, sequence = "2")
public String getSerialNumber() {
    return serialNumber;
}
// Status and assignedTo are omitted here to focus on the identity properties

There are several important details:

• EnumType.STRING stores values such as LAPTOP instead of fragile ordinal numbers.
• @PropertyLayout groups and orders members in the generated UI.
• @Title makes the serial number part of the object’s display title.

The remaining properties hold an AssetStatus and an optional employee name.

3.3. Adding Domain Behavior With Actions

Notably, we don’t want callers to change lifecycle fields independently through setters. Instead, the entity exposes operations that update related state together.

First, the assignment action records an employee and changes the status:

@Action(semantics = SemanticsOf.IDEMPOTENT)
@ActionLayout(
    fieldSetId = LayoutConstants.FieldSetId.DETAILS,
    position = ActionLayout.Position.PANEL,
    describedAs = "Assigns an available asset to an employee"
)
public Asset assignTo(
    @Parameter(maxLength = 100)
    @ParameterLayout(named = "Employee") final String employee) {
    assignedTo = employee.trim();
    status = AssetStatus.ASSIGNED;
    return this;
}

Causeway renders assignTo() as an action and derives its prompt from the parameter metadata. By returning this, it tells the viewer to continue with the updated asset. The IDEMPOTENT semantic describes the intended invocation semantics, but it doesn’t make the Java implementation idempotent automatically.

The other lifecycle actions return an asset to inventory or retire it:

@Action(semantics = SemanticsOf.IDEMPOTENT)
@ActionLayout(
    fieldSetId = LayoutConstants.FieldSetId.DETAILS,
    position = ActionLayout.Position.PANEL,
    describedAs = "Returns an assigned asset to inventory"
)
public Asset returnToInventory() {
    assignedTo = null;
    status = AssetStatus.AVAILABLE;
    return this;
}
@Action(semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE)
@ActionLayout(
    fieldSetId = LayoutConstants.FieldSetId.DETAILS,
    position = ActionLayout.Position.PANEL,
    describedAs = "Permanently retires an asset"
)
public Asset retire() {
    assignedTo = null;
    status = AssetStatus.RETIRED;
    return this;
}

Specifically, returnToInventory() clears the assignee as it restores AVAILABLE. Retirement is deliberately explicit, and IDEMPOTENT_ARE_YOU_SURE asks the Wicket viewer for confirmation.

At this point the methods express the state changes, but we still need to control when each change is valid.

3.4. Adding Business Rules

Causeway associates supporting methods with domain members by naming convention. For example, disableAssignTo() controls the availability of assignTo(), while validate0AssignTo() validates parameter zero, which is the first parameter:

@MemberSupport
public String disableAssignTo() {
    return status == AssetStatus.AVAILABLE
        ? null
        : "Only available assets can be assigned";
}
@MemberSupport
public String validate0AssignTo(final String employee) {
    return employee == null || employee.isBlank()
        ? "Employee name is required"
        : null;
}
@MemberSupport
public String disableReturnToInventory() {
    return status == AssetStatus.ASSIGNED
        ? null
        : "Only assigned assets can be returned";
}
@MemberSupport
public String disableRetire() {
    if (status == AssetStatus.ASSIGNED) {
        return "Return the asset before retiring it";
    }
    return status == AssetStatus.RETIRED
        ? "The asset is already retired"
        : null;
}

Here, null result permits the interaction. A message disables or rejects it and gives the viewer or API client a reason. Consequently, only an available asset can be assigned, only an assigned asset can be returned, and an assigned asset must be returned before retirement.

@MemberSupport also lets Causeway validate that a supporting method still matches an existing domain member.

String parameters are mandatory by default, so the framework rejects an empty Employee field before calling the action. The validator additionally handles whitespace-only input. These checks apply to Causeway-managed interactions; a direct Java call to assignTo() remains an ordinary method call and doesn’t invoke the supporting methods automatically.

The business rules are part of the domain interaction, so both generated viewers can enforce them without duplicating conditions in a controller or page.

3.5. Creating an Asset Domain Service

Entity actions operate on one existing asset. Creation and queries belong in a domain service backed by a Spring Data JPA repository:

@Named("assets.Assets")
@DomainService
@Priority(PriorityPrecedence.EARLY)
public class Assets {
    private final RepositoryService repositoryService;
    private final AssetRepository assetRepository;
    @Inject
    public Assets(
        final RepositoryService repositoryService,
        final AssetRepository assetRepository) {
        this.repositoryService = repositoryService;
        this.assetRepository = assetRepository;
    }
    @Action(semantics = SemanticsOf.NON_IDEMPOTENT)
    @ActionLayout(promptStyle = PromptStyle.DIALOG_MODAL)
    public Asset create(
        @ParameterLayout(named = "Type") final AssetType type,
        @Parameter(maxLength = 80)
        @ParameterLayout(named = "Serial number") final String serialNumber) {
        return repositoryService.persist(new Asset(type, serialNumber.trim()));
    }
    @MemberSupport
    public String validate1Create(final String serialNumber) {
        if (serialNumber == null || serialNumber.isBlank()) {
            return "Serial number is required";
        }
        return assetRepository.findBySerialNumberIgnoreCase(serialNumber.trim()).isPresent()
            ? "An asset with this serial number already exists"
            : null;
    }
    // listAll() appears in the API section; findBySerialNumber() is in the complete project
}

@DomainService includes the service in the metamodel, @Named assigns the logical name used by the REST viewer, and @Priority places it early in Spring’s ordering.

RepositoryService persists a new entity through the Causeway abstraction, whereas AssetRepository provides application-specific queries.

The repository itself uses Spring Data-derived queries, so it doesn’t need an implementation class:

public interface AssetRepository extends JpaRepository<Asset, Long> {
    List<Asset> findAllByOrderBySerialNumberAsc();
    List<Asset> findBySerialNumberContainingIgnoreCaseOrderBySerialNumberAsc(
        String serialNumber
    );
    Optional<Asset> findBySerialNumberIgnoreCase(String serialNumber);
}

The method names describe the ordering, partial match, and case-insensitive exact match that Spring Data generates. This keeps persistence queries separate from the Causeway-facing service actions.

The supporting method name validate1Create() refers to parameter one, the second parameter of create(). It rejects blank serial numbers and existing case-insensitive duplicates before persistence. The database constraint additionally protects against concurrent exact-value duplicates. Enforcing case-insensitive uniqueness at the database level would require normalization, a suitable index, or a case-insensitive collation.

Finally, menubars.layout.xml explicitly places the three service actions in the Assets menu:

<!-- The menuBars root, namespaces, primary container, and non-Assets menus are omitted. -->
<mb3:menu>
    <mb3:named>Assets</mb3:named>
    <mb3:section>
        <mb3:serviceAction objectType="assets.Assets" id="create"/>
        <mb3:serviceAction objectType="assets.Assets" id="findBySerialNumber"/>
        <mb3:serviceAction objectType="assets.Assets" id="listAll"/>
    </mb3:section>
</mb3:menu>

The objectType value matches the logical name of the service, and each id matches an action method. @DomainService registers the service in the metamodel, each @Action exposes a method, and the layout file determines this menu grouping.

3.6. Entry Point

The application entry point activates the Causeway prototyping preset and then starts Spring Boot:

@SpringBootApplication
@Import(AppManifest.class)
public class AssetManagementApplication extends SpringBootServletInitializer {
    public static void main(final String[] args) {
        CausewayPresets.prototyping();
        SpringApplication.run(AssetManagementApplication.class, args);
    }
}

So, let’s run the application.

4. Running the Internal Asset Management Application

From the apache-causeway module, we can build and run the application:

mvn clean install
mvn spring-boot:run

Next, let’s open http://localhost:8080/wicket/ and sign in with the demo credentials admin and pass.

4.1. Demo Interaction

From the Assets menu, let’s choose Create, select Laptop, and enter LT-001. Causeway immediately renders the new object using its title, properties, field sets, and actions:

When we open Assign To and submit an empty employee, the mandatory parameter prevents the invocation, and the generated prompt displays the validation error:

After entering Alice, the action changes the asset to ASSIGNED. The same page now enables Return To Inventory and disables Assign To and Retire, reflecting the supporting methods without page-specific conditional code:

No asset-specific controller, form, or HTML template was required for this generic UI.

The prototyping preset, in-memory H2 database, automatic schema creation, and SimpleRealm credentials are appropriate only for this local example. A production application should use durable persistence, schema migrations, production security, and a production-ready Causeway configuration.

4.2. Generated API

The service marks its list operation as safe:

@Action(semantics = SemanticsOf.SAFE)
public List<Asset> listAll() {
    return assetRepository.findAllByOrderBySerialNumberAsc();
}

The RESTful Objects viewer maps this action to an authenticated GET. With the application still running, we can invoke it using the demo account:

$ curl -i -u admin:pass \
    -H 'Accept: application/json' \
    'http://localhost:8080/restful/services/assets.Assets/actions/listAll/invoke'

The URL contains the logical service name assets.Assets and the action identifier listAll. The verified invocation returns 200 OK and reaches the domain service rather than exposing AssetRepository directly.

The response isn’t a raw JSON array. It is a RESTful Objects DomainObjectList representation containing links, relation types, and media-type profiles that allow a client to navigate the domain.

This is useful for generic clients and integrations, but before treating it as a public, versioned API, we should deliberately restrict the exposed surface or define a client-specific representation.

5. Conclusion

In this article, we began with the Causeway domain-first mental model and built an internal asset management application. Specifically, we mapped a JPA entity, expressed lifecycle behavior as actions, enforced valid transitions with supporting methods, and added a domain service for creation and queries.

After that, we ran the generated Wicket UI and invoked the RESTful Objects API. Causeway is a strong option when a behavior-rich domain and rapid delivery of consistent management screens outweigh the need for a fully custom interface.

The complete source code is available over on GitHub.

The post Introduction to Apache Causeway first appeared on Baeldung.