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.

       

1. Spring and Java

>> Java – The Documentary [inside.java]

A cinematic look back at how Java got here, from Sun, through the strategic pivots that could easily have gone the other way, to a platform running on billions of devices.

>> In-House LLM Serving at Netflix [netflixtechblog.com]

Rather than consuming LLMs through hosted APIs, Netflix runs the whole stack in-house, and this write-up walks through the four decisions that shaped it. Not easily reproducible of course but still an interesting read.

Also worth reading:

• >> Security Baked Into the JVM: the Safe Codebase Audit Pipeline [frankel.ch]
• >> First Test of Java on Banana Pi (ARM and RISC-V), Plus a Blinking LED with Pi4J [foojay.io]
• >> Toward a Durable Spring PetClinic [foojay.io]
• >> How We Beat HotSpot Performance (By Cheating, But Not Like That) [foojay.io]
• >> Warm Up Fast, Run Lean: Vertical Scaling for Java on Kubernetes with Azul Prime and Kedify [foojay.io]
• >> Quality Outreach Heads-up – JDK 27: Default G1 in All Environments [inside.java]
• >> Identifying JDK Value Class Candidates [inside.java]
• >> Transitioning Java to more frequent security updates [oracle.com]
• >> Improving a Competitor’s Numbers (On Purpose) [quarkus.io]
• >> Patch Java classes at build time with Quarkus Shim [quarkus.io]
• >> The simplest interpreter: Write yourself a compiler, Part I and Arithmetic interpreter: Part II [nurkiewicz.com]
• >> OWASP Top 10 2025 [vojtechruzicka.com]

Webinars and presentations:

• >> Episode 62 “JDK 27 + Valhalla, Now! + Hackathon” [IJN] [inside.java]
• >> A Bootiful Podcast: Russ Miles on Safer, More Productive Interactions with AI [spring.io]
• >> From OTEL to SLMs: Distilling Frontier Model Behaviour from Production Telemetry [infoq.com]

Time to upgrade:

• >> BoxLang AWS, Azure, and Google Secrets Manager Module Released [foojay.io]
• >> Quarkus 3.38.0 and 3.27.5 [github.com/quarkusio]
• >> Vert.x 4.5.31 [github.com/eclipse-vertx]
• >> Elasticsearch 9.4.4, 9.3.8, and 8.19.19 [github.com/elastic]
• >> Zuul 4.1.1 and 4.1.0 [github.com/Netflix]
• >> Micronaut Core 5.1.10, 5.1.9, 5.1.8, and 5.1.7 [github.com/micronaut-projects]
• >> Helidon 4.5.1 and 3.2.19 [github.com/helidon-io]

2. Pick of the Week

>> The New Survey from SlashData is Out

And yes, as always, there’s a prize

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

       

1. Overview

While design tools and development aren’t always compatible, being able to programmatically generate schematic images and diagrams can be invaluable.

In this tutorial, we’ll explore a few approaches for generating UML diagrams from Java code. First, we’ll start with static analysis tools that scan source or bytecode to produce class and dependency diagrams automatically. Then, we’ll look at tools and frameworks that help us expose architectural boundaries in one way or another. Finally, we’ll explore an agent-based approach that uses an LLM to turn a code diff into a diagram and a human-readable summary.

To facilitate and expand the overall understanding, we’ll use these various approaches to generate different types of diagrams for a demo application. It’s built with a vertical slice architecture, modeling a domain that simulates a blogging platform like Baeldung itself.

2. Why UML Diagrams

Pull requests have been getting larger. AI-assisted coding tools make it easy to touch a dozen classes across several packages in a single commit. New interfaces extracted, dependencies rewired, responsibilities moved between layers — all generated in minutes rather than hours.

As a result, code review is increasingly becoming the bottleneck. Mainly, that’s because reviewers are expected to reconstruct the shape of a change from the diff alone. However, a diff that’s readable line by line doesn’t necessarily make the change easy to understand. Scrolling through additions and deletions gives little sense of which classes now depend on which. Also, components can often quietly cross a boundary they shouldn’t.

This is exactly the kind of problem diagrams are designed to solve. A good diagram can provide the reviewer with a structural summary before they read a single line of the methods section. It shows which components were added, which relationships changed, and where the blast radius of the change actually is. Generating that diagram from the before-and-after state of a change — or straight from the diff — turns a wall of text into something you can take in at a glance.

3. Static Code Analysis

The most deterministic way to get a diagram is to generate it directly from the code — no manual modeling, no LLM in the loop, just a tool that walks the class files or source tree and emits a diagram description. These tools work by parsing imports, package structure, and class relationships, then rendering the result as PlantUML or Mermaid.

IntelliJ IDEA ships with built-in diagram support that can visualize a package, a module, or the classes touched by a selected diff.

Let’s see the steps to generate a Java class diagram directly from a classic IDE:

1. Right-click the root directory of the project, or a Java package
2. Select Diagrams > Show Diagrams
3. Select Java Classes as the type of diagram we want to generate

This is all done in a single subwindow:

IntelliJ should now render the class diagram in a separate tab. The diagram is interactive rather than exported by default, but it can be saved as a .png, .svg, or .puml file via the toolbar’s export button:

Alternatively, we can use an IDE plugin such as PlantUML Parser, which lets us right-click any Java file or directory, select PlantUML Parser, and generate a .puml file directly:

Needless to say, there are plenty of other options too. Teams still relying on Eclipse have their own options too, with older plugins like AmaterasUML solving the same problem within that IDE.

Outside the IDE, Java2PlantUML takes a similar approach from the command line, scanning compiled bytecode or source and producing a .puml file, which makes it a good fit for CI pipelines.

4. Framework-Level Architecture Sources

Static analysis tools have no notion of intent — they see classes and packages, not architectural boundaries. Some frameworks, however, already know exactly where those boundaries are, because we declared them explicitly.

Rather than reverse-engineering structure from bytecode, we can treat these framework-level declarations as ground truth for diagrams. Some of these frameworks go a step further too, letting us highlight and even enforce those boundaries as part of the build itself.

Spring Modulith is a good example of this. Specifically, Spring Modulith lets us organize a Spring Boot application into explicit modules, one per top-level package, and verifies at build time that modules only interact through their public API:

class ModularityTests {
    ApplicationModules modules = ApplicationModules.of(Application.class);
    @Test
    void verifiesModularStructure() {
        modules.verify();
    }
    @Test
    void createModuleDocumentation() {
        new Documenter(modules).writeDocumentation();
    }
}

As we can see, apart from just verifying the structure of modules, we can also generate documentation directly from it. Running createModuleDocumentation(), produces a set of PlantUML diagrams in target/spring-modulith-docs:

Other frameworks such as Spring Cloud Stream enable us to declaratively define the flow of data through the application in a single, centralized configuration file. Since these bindings live in one place rather than scattered across annotations, we can easily read that file and generate a sequence or flow diagram in Mermaid or PlantUML to show how data moves between services.

While these frameworks help us document what’s happening inside a single service, they don’t tell us much about how that service talks to the outside world — that’s where contracts come in. Scanning contract files can be a good way to understand how different services connect. This includes OpenAPI and AsyncAPI docs, or Spring Cloud Contract and Pact contracts, if we implement contract testing.

5. Agent-in-the-Loop Generation

Static analysis and framework-level sources both have limitations. In essence, they can only describe structure that already exists in a machine-readable form. Neither can tell us why a change was made, or summarize it in plain language for the reviewer.

This is where an LLM-based agent fits in. Rather than parsing code deterministically, we can trigger a lightweight agent like Claude Haiku. It reads a diff directly and produces both a diagram and a short, human-readable summary of what changed. There are two natural places to wire this in.

The first is as a step in a CI pipeline, e.g., a GitHub Actions or GitLab CI job that runs on every pull request, diffs against the target branch, and posts the generated diagram and summary as a PR comment:

- name: Generate PR diagram and summary
  run: |
    git diff origin/main...HEAD > diff.patch
    claude -p "Given this diff, generate a Mermaid diagram of the
    affected components and a 2-3 sentence summary of the change." \
    diff.patch > pr-summary.md

On the other hand, we can also use a pre-commit hook that uses a local AI harness like Claude Code or the Copilot CLI, so the documentation is generated and committed alongside the change itself.

Let’s see a simplified version of such a hook, which we can save as .githooks/pre-commit:

#!/bin/bash
DOCS_FILE="docs/$(git branch --show-current | tr '/' '-').md"
DIFF=$(git diff --cached | head -c 4000)
[ -z "$DIFF" ] && exit 0
PROMPT="Generate a brief Markdown doc for this commit: a Summary,
Modified Components list, and a Mermaid Component Diagram.
Changes:
${DIFF}"
claude --model claude-haiku-4-5-20251001 -p "$PROMPT" --output-format text > "$DOCS_FILE" \
  && git add "$DOCS_FILE"

On every commit that touches the project, the hook performs several actions:

• diffs the staged changes
• asks Claude Haiku for a short summary and a Mermaid component diagram
• stages the resulting Markdown file alongside the commit

Let’s commit a few local changes to the codebase and see the pre-commit hook in action:

As expected, the model summarizes the changes and generates a simple diagram of the key components affected by the recent commit, making the reviewer’s job easier.

6. Conclusion

In this article, we explored a few ways to generate diagrams from Java code to make code review easier as diffs grow larger and harder to reason about from raw code alone. Initially, we started with static code analysis, using tools like the built-in IntelliJ diagram support, the PlantUML Parser plugin, and Java2 PlantUML to generate diagrams directly from source or bytecode.

After that, we looked at framework-level architecture sources, where tools like Spring Modulith and Spring Cloud Stream let us treat already-declared boundaries and data flows as ground truth for diagrams. Then, we also discussed how contracts like OpenAPI, AsyncAPI, or Pact can document the interactions between services.

Finally, we explored an agent-in-the-loop approach, triggering a lightweight AI agent from a CI pipeline or a pre-commit hook to turn a diff into a diagram and a human-readable summary.

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

The post Generating Diagrams From Java Code first appeared on Baeldung.

       

1. Overview

Large language models (LLMs) have emerged as a key component of modern applications. While the most capable models are proprietary and hosted in a cloud environment. Accessing these models requires an internet connection and sending our application data to external providers.

For applications that process privacy-sensitive information or need to operate offline, these requirements may not be acceptable. As a result, there is a growing demand for integrating local LLMs into applications.

In this tutorial, we’ll learn how to integrate Spring AI with LM Studio and configure Spring AI to communicate with locally hosted chat and embedding models.

2. LM Studio

LM Studio is an application that can download, manage, and host LLMs and embedding models in our local environment. Its graphical interface allows us to browse and download models from public repositories with ease:

Besides model management, it provides an API server that exposes the loaded models via REST-based APIs. This allows AI frameworks such as Spring AI to interact with local models.

There are other applications, such as Ollama, providing similar capabilities, but with different focuses:

In general, LM Studio offers a more user-friendly experience for exploring and experimenting with local models, while Ollama is optimized for command-line workflows.

3. Maven Dependency

LM Studio provides both OpenAI-compatible and Anthropic-compatible API endpoints.

To integrate with Spring AI, we could either pick the Spring AI OpenAI dependency or the Spring AI Anthropic dependency. However, Spring AI Anthropic does not support embedding models.

Therefore, we’ll adopt the Spring AI OpenAI dependency in this tutorial:

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

Note that Spring AI 2.0.0 is built on Spring Framework 7 and is intended for Spring Boot 4.

4. Configuration

Let’s configure our application.yml to adopt the local models in LM Studio:

spring:
  ai:
    openai:
      api-key: dummy
      base-url: http://localhost:1234/v1
      chat:
        model: google/gemma-4-e4b
      embedding:
        model: text-embedding-embeddinggemma-300m

There are several properties worth mentioning:

api-key: We don’t really need a real API key when connecting to the local model. Thus, we just need to fill in an arbitrary value.

base-url: We could find the base URL when we start the local server in LM Studio. If we use the Spring AI OpenAI dependency, remember to append /v1 to the base URL.

model: We only need to specify the model when multiple models are loaded in LM Studio. Otherwise, we can omit this model configuration.

5. Sample Endpoints

Now, let’s create two endpoints: One for the chat model and one for the embedding model.

The controller basically delegates the work to 2 services that work with the models:

@RequestMapping("/lm-studio")
public class LmStudioController {
    private final ChatService chatService;
    private final EmbeddingService embeddingService;
    public LmStudioController(ChatService chatService, EmbeddingService embeddingService) {
        this.chatService = chatService;
        this.embeddingService = embeddingService;
    }
    @PostMapping("/chat")
    @ResponseStatus(HttpStatus.OK)
    public String chat(@RequestBody String prompt) {
        return chatService.chat(prompt);
    }
    @PostMapping("/embeddings")
    @ResponseStatus(HttpStatus.OK)
    public EmbeddingResponse getEmbeddings(@RequestBody String text) {
        return embeddingService.getEmbeddings(text);
    }
}

The ChatService uses the ChatClient to send a prompt to the configured chat model:

@Service
public class ChatService {
    private final ChatClient chatClient;
    public ChatService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }
    public String chat(String prompt) {
        return chatClient.prompt()
          .user(userMessage -> userMessage.text(prompt))
          .call()
          .content();
    }
}

Likewise, the EmbeddingService sends the text to the configured embedding model:

@Service
public class EmbeddingService {
    private final EmbeddingModel embeddingModel;
    public EmbeddingService(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }
    public EmbeddingResponse getEmbeddings(String text) {
        EmbeddingRequest request = new EmbeddingRequest(List.of(text), null);
        return embeddingModel.call(request);
    }
}

6. Test Run

Before starting our Spring Boot application, make sure the LM Studio local server is running with both the chat model and embedding model loaded:

Now, let’s verify both the chat and embedding endpoints by initiating HTTP requests via curl.

First, we send a request to the chat endpoint:

curl -X POST http://localhost:8080/lm-studio/chat 
  -d "Tell me who you are"

The request is processed by the chat model currently loaded in LM Studio. In this example, we’ve loaded Google’s Gemma 4 model, so the endpoint returns the following response:

I am Gemma 4, a Large Language Model developed by Google DeepMind.

Next, we use the chat model response as the request payload for the embedding endpoint:

curl -X POST http://localhost:8080/lm-studio/embeddings 
  -d "I am Gemma 4, a Large Language Model developed by Google DeepMind."

The endpoint returns the embedding response. Since the full response is large, we’ll only show the model name and the first few elements:

{
  "metadata": {
    "model": "text-embedding-embeddinggemma-300m:2"
  },
  "result": {
    "index": 0,
    "output": [
      -0.07699633,
      -0.030751443,
      0.019093497,
      ...
    ]
  }
}

These results confirm that Spring AI successfully invokes the locally hosted chat model and the embedding model via LM Studio’s OpenAI-compatible API.

7. Conclusion

In this article, we learned how to integrate Spring AI with LM Studio to use a locally hosted chat model and embedding model. We configured Spring AI to work with the open-source models via LM Studio’s OpenAI-compatible API.

LM Studio is a perfect choice for running AI models without relying on a cloud provider. This approach keeps your data within the local environment and enables it to operate without an internet connection. These make it ideal for privacy-sensitive applications.

As always, the complete code examples are available over on GitHub.

The post Integrating Local LLMs with Spring AI Using LM Studio first appeared on Baeldung.

       

1. Overview

MySQL is one of the most common relational database systems. Consequently, integrating it with Java applications via the MySQL Connector/J JDBC driver is a fairly standard task. This enables working with the database directly from Java. Yet, even when handling pure text data, we might encounter errors such as java.sql.SQLException: Incorrect string value.

In this tutorial, we explain how to fix the Incorrect string value error in Java applications using MySQL. First, we explore what the exception means and why it occurs. Then, we examine configuration changes at different levels as a means to work around the problem. Finally, we provide other practical solutions such as MySQL schema updates, JDBC configuration, and server settings.

2. Understanding the Error

Before attempting to fix java.sql.SQLException: Incorrect string value, let’s understand how and when the error appears.

2.1. General Description

Initially, we can explore an example error text. To that end, let’s execute an INSERT or UPDATE operation with problematic characters:

java.sql.SQLException: Incorrect string value: '\x00\x00\x27\x4C' for column 'textcol'

In this case, we see that the textcol column can’t handle the string value \x00\x00\x27\x4C. In short, MySQL rejected the input. One of the main reasons for this is the fact that the column character set can’t represent the provided data.

2.2. Character Encoding Mismatch

So, the way that Java handles Unicode isn’t entirely compatible with the default or current MySQL character set.

Specifically, Java uses full UTF-8 encoding, where more than three bytes can represent a single character. On the other hand, the default utf8 character set in MySQL supports a maximum of 3 bytes per character. In this situation, if we try to store a 4-byte character, such as an emoji, within the database, we might encounter the exception in question.

For instance, let’s consider inserting a string containing an emoji into a table as a common action:

INSERT INTO messages (text) VALUES ('❌');

If the column uses utf8, MySQL rejects the value because of its inability to store 4-byte characters.

3. MySQL Character Set Configuration and Conversion

In short, the most reliable solution is often to configure MySQL, the database, and its components for full Unicode support.

3.1. Change utf8mb4 to utf8

MySQL provides the utf8mb4 character set, which supports all Unicode characters, including emojis and similar:

ALTER DATABASE mydb 
CHARACTER SET = utf8mb4 
COLLATE = utf8mb4_unicode_ci;

This command ensures the database itself can store 4-byte characters correctly.

3.2. Convert Tables

Existing tables may still use incompatible encodings, even after updating the database configuration:

ALTER TABLE xtab 
CONVERT TO CHARACTER SET utf8mb4 
COLLATE utf8mb4_unicode_ci;

Thus, we should update all tables with the new encoding.

3.3. Update Columns

In some cases, we might need to modify individual columns:

ALTER TABLE xtab 
MODIFY text_column TEXT 
CHARACTER SET utf8mb4;

To reiterate, the database, all tables, and each column must all use utf8mb4 exclusively.

4. JDBC Configuration Issues

Even after configuring MySQL correctly, we should set up the JDBC connection, so it also handles Unicode properly.

4.1. Configure Connection URL

The JDBC URL can include parameters to enforce Unicode behavior:

jdbc:mysql://localhost:3306/mydb
  ?useUnicode=true
  &characterEncoding=utf8

These options ensure that Java correctly encodes and transmits string data to MySQL.

4.2. Connector/J Behavior

Modern versions of Connector/J automatically negotiate character sets with the MySQL server. However, using older drivers or misconfigurations may still lead to encoding mismatches.

Therefore, explicitly setting encoding or upgrading the driver can help avoid inconsistencies.

5. Verifying MySQL Server Settings

In addition to schema and connection settings, server-level configuration plays a role in encoding behavior.

5.1. Check Character Set Variables

Let’s inspect the current MySQL character set configuration:

SHOW VARIABLES LIKE 'character_set%';

Ideally, the server, database, and connection should all use utf8mb4 to ensure compatibility.

5.2. Update MySQL Configuration

If necessary, we might need to update the MySQL configuration file to enforce the needed defaults:

[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

After making changes, we should restart the MySQL service for them to take effect. At this point, the server should only employ utf8mb4 as its encoding.

6. Common Pitfalls

Even after applying fixes, certain common mistakes can still trigger the java.sql.SQLException: Incorrect string value error.

6.1. Partial Configuration

Updating only one component can result in inconsistent behavior.

For example, fixing the database but not the tables may still cause failures. Even single columns can result in problems. Thus, all components must conform to the same encoding.

This process can be tedious, but it is required, as even a single misaligned component can break the character set negotiation.

6.2. New Database Components

Any new database component with the default encoding utf8 can break character support.

Thus, we should only create new tables and columns with the utf8mb4 encoding.

6.3. Outdated JDBC Driver

Older JDBC drivers may not fully support modern MySQL encoding behavior:

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

That’s because the above Maven artifact (with its groupId and artifactId) is outdated and superseded:

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>9.7.0</version>
</dependency>

Keeping dependencies up to date is one of the best ways to improve compatibility and stability. To find the latest artifacts, we can always go to MySQL Connector/J on the Maven Repository.

7. Summary

In this article, we explored how to diagnose and fix the java.sql.SQLException: Incorrect string value error in MySQL.

In summary, the problem is caused by character encoding mismatches, most commonly due to the limited utf8 implementation of MySQL. By switching to utf8mb4, aligning JDBC configuration, verifying server settings, and ensuring consistency across all layers, we can fully support Unicode and often eliminate this error.

The post How to Fix MySQL java.sql.SQLException: Incorrect string value first appeared on Baeldung.