Baeldung https://www.baeldung.com Java, Spring and Web Development tutorials Fri, 30 Oct 2026 16:16:14 +0000 en-US hourly 1 https://www.baeldung.com/java-weekly-669 Java Weekly, Issue 669 https://feeds.feedblitz.com/~/972125879/0/baeldung https://feeds.feedblitz.com/~/972125879/0/baeldung#respond Fri, 30 Oct 2026 16:16:14 +0000 https://www.baeldung.com/?p=205316

Java 21 to 25 upgrades and lots of solid security releases. As expected after the weeks we've had :)

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

       
]]>

1. Spring and Java

>> Upgrading from Java 21 to 25: What Actually Breaks [foojay.io]

A walk through the upgrade traps between Java 21 and 25. Reproducible examples and a practical migration checklist, so a solid piece.

Also worth reading:

Webinars and presentations:

Time to upgrade:

2. Technical & Musings

>> Ontology-Driven Observability: Building an End-to-End Knowledge Graph at Netflix Scale [netflixtechblog.com]

An interesting look at the data modelling behind observability, and why giving tools a common understanding of your systems matters for incident investigation. Agentic or not.

Also worth reading:

3. Pick of the Week

>> Why is it so expensive to send an email? [evancz.dev]

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

       
]]> https://feeds.feedblitz.com/~/972125879/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2016/10/social-Weekly-Reviews-4-150x150.jpg https://www.baeldung.com/spring-ai-rag-query-transformation Query Transformation in Spring AI Modular RAG https://feeds.feedblitz.com/~/972117848/0/baeldung https://feeds.feedblitz.com/~/972117848/0/baeldung#respond Fri, 30 Oct 2026 11:51:20 +0000 https://www.baeldung.com/?p=205313

Learn how to set up query transformation in Spring AI for retrieval augmented generation.

The post Query Transformation in Spring AI Modular RAG first appeared on Baeldung.

       
]]>

1. Overview

Retrieval-Augmented Generation (RAG) queries relevant documents from a knowledge base, such as a vector database, and then feeds them to the LLM as part of the prompt so it can generate a more accurate response.

Spring AI provides a modular RAG architecture that divides RAG into four stages:

  • Pre-retrieval,
  • Retrieval,
  • Post-retrieval, and
  • Generation

In this tutorial, we’ll focus on query transformation in the pre-retrieval stage that processes the user query before retrieval.

2. Why Transform Queries?

Retrieving from a vector store is basically a similarity search over the datastore embeddings, with the query embedding as the search key.

Therefore, the relevance of the retrieved information depends on the query wording. For example, a query may be an inefficient search key due to:

  • Lack of clarity – a query may be ambiguous or too verbose and mention many concepts, many irrelevant to the search. In both cases, the query’s embedding is less aligned with relevant documents.
  • Language mismatch – a query in a different language from the stored documents may not produce a match even if the content is there. This gets worse if the embedding model wasn’t trained on the documents in the query’s language.
  • Missing context – A follow-up question within a long conversation, such as “And how does it support RAG?”, relies on previous messages. The user knows what “it” refers to, but the RAG system searches with the latest message only. Without the chat history, the query is ambiguous.

Query transformers use an LLM to rewrite queries before retrieval in a way we expect to improve the relevance of the retrieved data.

3. Setup

Let’s set up our project. First, we need the Spring AI RAG dependency to work with modular RAG:

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-rag</artifactId>
</dependency>

As every query transformer needs a chat model that connects to an LLM, we’ll use the Spring AI OpenAI dependency:

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

Now, let’s configure our OpenAI API key and the chat model in our application.yml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.0

A high temperature makes the model more creative, so the same user query can be transformed differently in each call. For that reason, the Spring AI documentation recommends using a low temperature such as 0.0 to get more deterministic results.

4. Modular RAG

In Spring AI, RetrievalAugmentationAdvisor ties the RAG stages together. Once we register it on a ChatClient, every prompt runs through the full pipeline, e.g.:

RetrievalAugmentationAdvisor ragAdvisor = RetrievalAugmentationAdvisor.builder()
  .queryTransformers(
    RewriteQueryTransformer.builder()
      .chatClientBuilder(chatClientBuilder)
      .build(),
    TranslationQueryTransformer.builder()
      .chatClientBuilder(chatClientBuilder)
      .targetLanguage("english")
      .build(),
    CompressionQueryTransformer.builder()
      .chatClientBuilder(chatClientBuilder)
      .build())
  .documentRetriever(VectorStoreDocumentRetriever.builder()
    .vectorStore(vectorStore)
    .topK(3)
    .build())
  .build();
ChatClient chatClient = chatClientBuilder.defaultAdvisors(ragAdvisor)
  .build();

Here, vectorStore is a VectorStore instance holding our embedded documents, e.g. backed by an Oracle vector database.

The builder of the RetrievalAugmentationAdvisor exposes at least one method for each RAG stage. In our example, we configure queryTransformers() for the pre-retrieval stage and the documentRetriever() method for the retrieval stage. Let’s focus on the former.

The queryTransformers() method accepts multiple query transformers. They implement the QueryTransformer interface and run in sequence, each one receiving the previous one’s output. Each transformer makes its own LLM call that requires a ChatClient.Builder.

Spring AI provides three query transformers. To demonstrate each transformer separately, we’ll implement a test method for each in our test class:

@SpringBootTest
class PreRetrievalQueryTransformerLiveTest {
    private static final Logger logger = LoggerFactory.getLogger(PreRetrievalQueryTransformerLiveTest.class);
    @Autowired
    private ChatClient.Builder chatClientBuilder;
}

Let’s check them out.

5. RewriteQueryTransformer

RewriteQueryTransformer filters out irrelevant information from a query. By keeping only the relevant parts, it produces a concise text that we expect to find better results. This transformer is useful when the user query is lengthy and unclear.

As an example, let’s show how it handles a verbose query:

@Test
void whenQueryIsVerbose_thenRewrite() {
    QueryTransformer queryTransformer = RewriteQueryTransformer.builder()
      .chatClientBuilder(chatClientBuilder)
      .build();
    String userQuery = "I'm studying machine learning and honestly the whole thing is confusing. What is an LLM anyway?";
    Query transformed = queryTransformer.transform(new Query(userQuery));
    logger.info("Rewrite: [{}] -> [{}]", userQuery, transformed.text());
}

We can see the following or similar log when executing the test:

Rewrite: [I'm studying machine learning and honestly the whole thing is confusing. What is an LLM anyway?] -> [What is an LLM in machine learning?]

The transformer identifies machine learning and LLM as important context to keep and discards the user’s introduction that is irrelevant for the search.

6. TranslationQueryTransformer

Embedding models work best for the languages they were trained on. For example, if most of the training data is in English, the model represents English texts more precisely than other written languages. Consequently, a query written in another language such as Chinese or French may align poorly with documents stored in English, even when they have the same meaning.

TranslationQueryTransformer solves this by translating the user’s query into the target language: the language of the documents in our datastore.

To see this, let’s add a new test method to send a Traditional Chinese query 什麼是向量資料庫？ asking “What is a vector database?” to the transformer:

@Test
void whenQueryIsInTraditionalChinese_thenTranslate() {
    QueryTransformer queryTransformer = TranslationQueryTransformer.builder()
      .chatClientBuilder(chatClientBuilder)
      .targetLanguage("english")
      .build();
    String userQuery = "什麼是向量資料庫？";
    Query transformed = queryTransformer.transform(new Query(userQuery));
    logger.info("Translation: [{}] -> [{}]", userQuery, transformed.text());
}

We specify the target language explicitly using the targetLanguage() method. The log shows the Chinese query has been translated correctly:

Translation: [什麼是向量資料庫？] -> [What is a vector database?]

If the query is already in the target language or in a language the LLM can’t recognize, it’s returned unchanged. For example, if we use a query in English, the output is identical:

Translation: [What is a vector database?] -> [What is a vector database?]

Similarly, a query with made-up words of an unknown language passes through unchanged as well:

Translation: [Gblorvak tensig quimbo darnel?] -> [Gblorvak tensig quimbo darnel?]

7. CompressionQueryTransformer

A user query usually refers to previous messages and doesn’t contain complete information on its own. For that reason, a single query in a chat may be ambiguous and not return anything useful from the vector store.

CompressionQueryTransformer solves this by compressing the conversation history and using it to rewrite the query to resolve possible ambiguities.

Unlike the previous two transformers, it requires the history of the Query, so must supply both the query text and the history:

@Test
void whenQueryIsFollowUpWithHistory_thenCompress() {
    QueryTransformer queryTransformer = CompressionQueryTransformer.builder()
      .chatClientBuilder(chatClientBuilder)
      .build();
    List<Message> history = List.of(
      new UserMessage("What is Spring AI?"),
      new AssistantMessage("Spring AI is an application framework that brings Spring's design principles to AI engineering."));
    
    String followUpQuery = "And how does it support RAG?";
    
    Query query = Query.builder()
      .text(followUpQuery)
      .history(history)
      .build();
    Query transformed = queryTransformer.transform(query);
    logger.info("Compression: [{}] -> [{}]", followUpQuery, transformed.text());
}

Here, we construct the conversation history explicitly as a list of messages. Executing the test should produce a log like this one:

Compression: [And how does it support RAG?] -> [How does Spring AI support Retrieval-Augmented Generation (RAG)?]

The original query was unclear on its own because of “it.” The transformer compresses it and the conversation history into a new query where the meaning of “it” is clear.

In a real application, a ChatClient doesn’t keep previous messages by default, so we need to register a chat memory advisor with the RAG advisor. Otherwise, the transformer receives no history to work with.

However, the chat history may not always be relevant as the user may switch the topic during conversation. Let’s run the same test again with an unrelated query:

String followUpQuery = "What's a good recipe for carbonara?";

The transformer should recognize the topic switch and not include anything from previous messages:

Compression: [What's a good recipe for carbonara?] -> [Can you provide a good recipe for carbonara?]

8. Query Transformer Considerations

All query transformers have these common characteristics:

  • They run sequentially, and each receives the previous one’s output.
  • Each transformer adds an LLM call.
  • Temperature needs to be low (e.g., 0.0) to ensure more deterministic results.

Because of additional LLM calls, the overall latency adds up. So, we should enable only the transformers we actually need:

  • RewriteQueryTransformer simplifies verbose and unclear queries to provide clarity.
  • TranslationQueryTransformer translates queries into the language of the database.
  • CompressionQueryTransformer compresses and merges a query with its history into a new query containing relevant context from the chat history.

9. Conclusion

In this article, we explained query transformation in the pre-retrieval stage of Spring AI’s modular RAG architecture.

Three QueryTransformer implementations that Spring AI provide transform queries to improve retrieval performance.

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

The post Query Transformation in Spring AI Modular RAG first appeared on Baeldung.

       
]]> https://feeds.feedblitz.com/~/972117848/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2021/08/Baeldung-Featured-Image-150x150.png https://www.baeldung.com/spring-boot-handle-forwarded-headers Handle Forwarded Headers in Spring Boot https://feeds.feedblitz.com/~/972117851/0/baeldung https://feeds.feedblitz.com/~/972117851/0/baeldung#respond Fri, 30 Oct 2026 11:42:54 +0000 https://www.baeldung.com/spring-boot-handle-forwarded-headers

Learn various strategies for handling forwarded headers in a Spring Boot application.

The post Handle Forwarded Headers in Spring Boot first appeared on Baeldung.

       
]]>

1. Overview

In modern web services, we integrate backend services with essential services such as API gateways, load balancers, and reverse proxies. As a resulr, our backend service is no longer aware of the client-specific network details, such as the client’s IP address, hostname, and protocol, due to the network hop.

We can overcome this visibility limitation by including the request details as HTTP forwarded headers.

In this tutorial, we’ll learn various strategies for handling forwarded headers in a Spring Boot application. We’ll also implement and test these approaches with a configured reverse proxy service.

2. What are Forwarded Headers?

Forwarded headers are HTTP headers that specify network-related metadata. The upstream services, while processing the request to the backend APIs, would attach the headers.

Traditionally, many web servers used the de facto standard X-Forwarded-* headers.

Below are the X-Forwarded-* header details:

  • X-Forwarded-For – To specify the originating client IP address
  • X-Forwarded-By – To include the proxy’s IP address for tracing
  • X-Forwarded-Host – To include the destination hostname as mentioned by the client
  • X-Forwarded-Port – It specifies the destination port that the client used to connect
  • X-Forwarded-Proto – To specify the protocol used, i.e http, https, ws, or wss
  • X-Forwarded-Prefix – To specify any path-prefix URL, e.g /myapp, which is not included in the backend URL

We can also use the RFC 7239 standard Forwarded header:

Forwarded: by=<identifier>; for=<identifier>; host=<host>; proto=<http/https>

The purpose of using forwarded headers can vary, such as enabling client IP-based rate limiting, auditing, sending HTTP URLs (HATEOAS), or returning an HTTP redirect response.

3. Set up the Example Application

Let’s implement a backend service with an endpoint. We’ll also expose the API through a reverse proxy service.

3.1. Maven Dependencies

We include the spring-boot-starter and spring-boot-starter-web dependencies:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>4.1.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

Next, we implement a REST API service.

3.2. Implement the API

We’ll use the RestController class. First, let’s define a test endpoint:

@GetMapping("/test")
public ResponseEntity<Void> test(HttpServletRequest request) {
    LOGGER.info("""
      scheme : {}
      Remote Host IP : {}
      Remote Port : {}
      Server Name : {}
      Server Port : {}
      Request URL : {}""", request.getScheme(), request.getRemoteHost(), request.getRemotePort(), request.getServerName(), request.getServerPort(),
        request.getRequestURL());
    return new ResponseEntity<>(HttpStatus.OK);
}

Here, we’re logging some of the network metadata present in the HttpServletRequest object.

3.3. Implement the Nginx Service

Now, let’s configure an Nginx service to serve as a reverse proxy for the backend service. We do it in the nginx.conf file:

worker_processes auto;
events {
    worker_connections 1024;
}
http {
    server {
        listen 443 ssl;
        server_name api.example.com;
        ssl_certificate     /etc/nginx/certs/api.example.com.crt;
        ssl_certificate_key /etc/nginx/certs/api.example.com.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        location /myapp/ {
            proxy_pass http://backend-app:8081/;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
        }
    }
}

We set the hostname api.example.com, the location /myapp/, and the TLS certificate. Note the trailing / in the proxy_pass is mandatory so that Nginx can replace the matching /myapp/ path when forwarding the request.

For testing purposes, we generate the self-signed certificate using the openssl command:

$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout nginx/certs/api.example.com.key \
  -out nginx/certs/api.example.com.crt \
  -subj "/CN=api.example.com"

Additionally, we need to map the hostname api.example.com to the localhost address.

3.4. Implement the Docker Services

Let’s implement the entire setup in the Docker environment.

First, we specify the application image using a Dockerfile:

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/spring-boot-5-0.0.1-SNAPSHOT.jar backend-app.jar
EXPOSE 8081
ENTRYPOINT ["java", "-jar", "backend-app.jar"]

Next, we stitch the above services together in the docker-compose.yml file:

services:
  backend-app:
    build:
      context: ../../../../../
      dockerfile: ./src/test/resources/docker/Dockerfile
    container_name: backend-app
    expose:
      - "8081"
  nginx:
    image: nginx:1.31.3-alpine
    container_name: nginx-proxy
    volumes:
      - ../../nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ../../nginx/certs:/etc/nginx/certs:ro
    ports:
      - "443:443"
    depends_on:
      - backend-app

In docker-compose.yml, we configure the backend endpoint to run on the Docker internal port 8081. The Nginx service is accessible over TLS on port 443.

4. Different Strategies in Spring Boot

While the upstream services should include the forwarded headers, we still need to process headers in the application.

Starting with version 2.2.0, Spring Boot supports three different strategies. The options include None, Native, and Framework approaches:

  • None means the application ignores the forwarded headers.
  • Native lets the web server handles the forwarded headers.
  • With Framework, the Spring framework processes these forwarded headers before serving the request.

This is configured using the forward-headers-strategy enum property.

The default strategy is None, except when Spring Boot detects that the application is running on a recognized cloud platform, which then enables the native strategy.

Before version 2.2.0, we could either ignore the forwarded headers or enable native support using the server.use-forward-headers boolean configuration.

5. Implement the Strategies

Let’s see these forwarded-headers strategies in action with Spring Boot support.

5.1. Forwarded Headers in Nginx

We need to include the forwarded headers in the Nginx service before implementing any strategy.

First, we define the forwarded_for and forwarded_by variables within the nginx http block:

map $remote_addr $forwarded_for {
    ~: "\"[$remote_addr]:$remote_port\"";
    default "\"$remote_addr:$remote_port\"";
}
map $server_addr $forwarded_by {
    ~:  "\"[$server_addr]:$server_port\"";
    default "\"$server_addr:$server_port\"";
}

The IP address and port are appended with a colon, thus supporting both IPv4 and IPv6 formats.

Now, we set the X-Forwarded-*, Forwarded, and Host headers using the proxy_set_header directive in the nginx.conf file:

location /myapp/ {
    proxy_pass http://backend-app:8081/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Prefix /myapp;
    
    proxy_set_header Forwarded "for=$forwarded_for;by=$forwarded_by;host=$host;proto=$scheme";
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

With the config above, the Nginx service will automatically include the forwarded headers.

Instead of overwriting the X-Forwarded-For value, we can append the proxy’s IP to preserve the trusted upstream service’s X-Forwarded-For header. We can append the header using the built-in proxy_add_x_forwarded_for variable:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

We should append it only if the XFF header comes from a trusted internal service. This will ensure the client cannot spoof the forwarded headers.

5.2. None

Let’s say we want to ignore and can’t trust forwarded headers. For example, the application may be directly exposed to the client, or the proxy does not handle the forwarded headers. In such use cases, we use the None strategy.

First, we configure the forward-headers-strategy as NONE in the application.yml file:

server:
  port: 8081
  forward-headers-strategy: NONE

For testing purposes, we run the above with the Nginx reverse proxy enabled. Then, we run the above Docker services with the docker compose command:

$ docker compose up --build

Finally, we execute the /myapp/test endpoint in the terminal:

$ curl -k https://api.example.com/myapp/test

We can confirm the request details in the Nginx log:

192.168.65.1 - - [26/Aug/2026:08:13:08 +0000] "GET /myapp/test HTTP/1.1" 200 0 "-" "curl/8.7.1"

Also, we need to verify the HttpServletRequest attributes in the application log:

2026-08-26T08:13:08.124Z  INFO 1 --- [backend-app] [nio-8081-exec-1] c.b.forwardheaders.TestController:
scheme : http
Remote Host IP : 172.21.0.3
Remote Port : 50754
Server Name : api.example.com
Server Port : 80
Request URL : http://api.example.com/test

The logs confirm that the scheme, remote IP, server port, and request URL are different from what the Nginx server received.

Additionally, let’s confirm the Nginx service’s IP address:

$ docker exec -it nginx-proxy /bin/sh 
/ # ifconfig
eth0      Link encap:Ethernet  HWaddr 2A:4C:7C:42:E0:87  
          inet addr:172.21.0.3  Bcast:172.21.255.255  Mask:255.255.0.0

The client IP address is 172.21.0.3, which is the Nginx service’s IP address. However, in the Nginx log, we see that the client IP address is 192.168.65.1, which is actually the Docker’s Desktop default gateway address. As expected, the forwarded headers were not processed by the backend service.

5.3. Native

With the Native strategy, Spring Boot delegates the processing of the forwarded headers to the underlying web server. The use case can be to audit, enable IP-based rate limiting, or provide an accessible redirect URL.

First, let’s configure the forward-headers-strategy as NATIVE and include the Tomcat-related remoteip configs:

server:
  port: 8081
  forward-headers-strategy: NATIVE
  tomcat:
    remoteip:
      remote-ip-header: X-Forwarded-For
      protocol-header: X-Forwarded-Proto
      host-header: X-Forwarded-Host
      port-header: X-Forwarded-Port
      trusted-proxies: 172\.(1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}

In the config above, we’re setting both the X-Forwarded-* names and the trusted-proxies IP range pattern. The remoteip configuration is optional, as the Tomcat server implements a sensible default.

Then, let’s enable the access logs on the server:

server:
  tomcat:
    accesslog:
      enabled: true
      request-attributes-enabled: true
      directory: /app/logs
      prefix: access_log
      suffix: .log
      pattern: '%h %l %u %t "%r" %s %b "%{X-Forwarded-Host}i" "%{X-Forwarded-For}i" "%{X-Forwarded-Proto}i"'
      rotate: false

Internally, the Tomcat server implements a valve called RemoteIpValve to handle the configured forwarded headers.

Finally, we execute the same test endpoint to verify the application logs:

2026-08-26T08:15:31.672Z  INFO 1 --- [backend-app] [nio-8081-exec-1] c.b.forwardheaders.TestController:
scheme : https
Remote Host IP : 192.168.65.1
Remote Port : 56444
Server Name : api.example.com
Server Port : 443
Request URL : https://api.example.com/test

The logs confirm the expected scheme, remote IP, server name, and server port.

However, the request URL did not include the /myapp prefix. The reason is that the RemoteIpValve implementation ignores the X-Forwarded-Prefix header.

Additionally, we verify the forwarded headers in the server access log inside the Docker environment:

$ docker exec -it backend-app /bin/sh
/app # tail -f ./logs/access_log.log
192.168.65.1 - - [26/Aug/2026:08:15:31 +0000] "GET /test HTTP/1.1" 200 - "api.example.com" "192.168.65.1" "https"

The Native approach works as expected, except the request URL is missing the prefix.

Here’s how the overall flow for the client’s request looks:

Forwarded Headers network flow diagram

Although we processed the forwarded headers correctly, we still need to include the prefix in the request URL.

5.4. Framework

In this approach, Spring Boot internally handles all forwarded headers, including the X-Forwarded-Prefix header. This will allow us to include the prefix in the URL.

We enable the forward-headers-strategy as FRAMEWORK in the application.yml file:

server:
  port: 8081
  forward-headers-strategy: FRAMEWORK

Internally, Spring Boot implements this strategy using the ForwardedHeaderFilter class.

Let’s execute the /myapp/test endpoint and verify the application logs:

2026-08-26T08:18:07.197Z  INFO 1 --- [backend-app] [nio-8081-exec-1] c.b.forwardheaders.TestController:
scheme : https
Remote Host IP : 192.168.65.1
Remote Port : 52414
Server Name : api.example.com
Server Port : 443
Request URL : https://api.example.com/myapp/test

We confirm the scheme, remote IP/port, server name/port, and request URL as expected. Also, the ForwardedHeaderFilter correctly extracts the remote IP and port based on the configured Forwarded header. By default, the remote IP and port are updated using the Forwarded: for header, if present. Otherwise, only the remote IP gets updated using the X-Forwarded-For header.

The above behavior was implemented in Spring Boot 2.4.0. Before Spring Boot 2.4.0/Spring Framework 5.3.0, the remote IP and port were left untouched.

We shouldn’t enable both the Framework and Native strategies, as it will cause duplicate processing.

6. Conclusion

In this article, we learned about the forwarded headers and why we need them.

We also demonstrated and tested three strategies provided by Spring Boot: None, Native, and Framework strategies with the forward-header-strategy configuration.

As always, the article code can be found over the GitHub.

The post Handle Forwarded Headers in Spring Boot first appeared on Baeldung.

       
]]> https://feeds.feedblitz.com/~/972117851/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2024/11/Spring-Boot-Featured-Image-03-150x150.jpg https://www.baeldung.com/spring-ai-safeguarding-llm-output Safeguarding LLM Output in Spring AI https://feeds.feedblitz.com/~/971759387/0/baeldung https://feeds.feedblitz.com/~/971759387/0/baeldung#respond Sun, 18 Oct 2026 17:55:03 +0000 https://www.baeldung.com/?p=205222

Learn to create a custom advisor that inspects the model's response before Spring AI ChatClient hands it back to the user.

The post Safeguarding LLM Output in Spring AI first appeared on Baeldung.

       
]]>

1. Overview

When we expose a large language model through our own API, our first instinct is to filter the prompts that users send. Spring AI ships a SafeGuardAdvisor for exactly that job. It blocks any prompt containing a forbidden term before the prompt reaches the model.

That covers only half of the problem. A perfectly innocent-looking prompt can still produce a response that we’d rather not return. The model answers from its own knowledge. The user never has to name the thing we’re trying to hide.

In this tutorial, we’ll close that gap with a custom advisor that inspects the model’s response before ChatClient hands it back. We’ll set up the input guard first, find the hole in it, then stack an output guard on top.

2. Setting Up the Project

A chat starter is the only dependency we need. Let’s add the Google GenAI one:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai</artifactId>
    <version>1.1.2</version>
</dependency>

The latest version of spring-ai-starter-model-google-genai is available in the Maven Repository. Advisors are model-agnostic, so any other chat starter works here just as well.

Next, we point the starter at our Gemini API key and pick a model:

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

Throughout the tutorial, we’ll build a Java coding assistant with one rule: it must never recommend the legacy date API over java.time.

3. Blocking Sensitive Prompts

SafeGuardAdvisor is Spring AI’s built-in answer to unwanted input. It scans the prompt for a list of sensitive words. When it finds one, it short-circuits the advisor chain. The model is never called, and the caller gets a canned response instead.

Let’s register one as a default advisor on our ChatClient, next to a system prompt that sets the assistant’s role:

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    SafeGuardAdvisor inputGuard = SafeGuardAdvisor.builder()
      .sensitiveWords(List.of("SimpleDateFormat", "java.util.Date"))
      .failureResponse("Use java.time instead.")
      .build();
    return builder.defaultSystem(SYSTEM_PROMPT)
      .defaultAdvisors(inputGuard)
      .build();
}

The advisor compares each word against the prompt with a plain substring check, so the match is case-sensitive and exact. It also scans the whole prompt, system message included. That has a catch. If our system prompt spelled out SimpleDateFormat, the guard would reject every request.

The guard now stops any question that names the legacy API before it reaches the model:

private static final String FAILURE_RESPONSE = "Use java.time instead.";
@Test
void givenLegacyApiPrompt_whenCallingTheModel_thenItIsBlocked() {
    String answer = chatClient.prompt()
      .user("How do I use SimpleDateFormat?")
      .call()
      .content();
    assertThat(answer).isEqualTo(FAILURE_RESPONSE);
}

The model is never invoked at all, which makes this the cheapest guardrail we can put in place.

4. Why Input Filtering Isn’t Enough

SafeGuardAdvisor only ever sees the prompt. A developer can ask about a class without ever typing its name. Asking “How did we parse date strings in Java 7?” matches nothing on our list, so it reaches the model. Since java.time didn’t exist before Java 8, it has only one honest answer:

In Java 7, date strings were parsed using the java.text.SimpleDateFormat
class by defining a format pattern to convert the string into a
java.util.Date object.

The guard held, and the legacy API came back anyway. Input filtering only matches what the user typed, and the model is under no obligation to stay inside that vocabulary. To catch this, we have to look at what comes back.

5. Creating the Output Advisor

Spring AI has no built-in advisor that filters response content, so we’ll write our own. It takes the same three settings as SafeGuardAdvisor, and we’ll build it in two steps: the class and its builder, then the filtering logic.

5.1. Skeleton and Builder

An advisor that inspects responses only needs the CallAdvisor interface, which Spring AI uses for non-streaming calls. Our class holds the three values the builder configures, and exposes two of them through the Advisor contract:

public class OutputSafeGuardAdvisor implements CallAdvisor {
    private List<String> sensitiveWords;
    private String failureResponse;
    private int order;
    private OutputSafeGuardAdvisor(
      List<String> sensitiveWords, String failureResponse, int order) {
        this.sensitiveWords = sensitiveWords;
        this.failureResponse = failureResponse;
        this.order = order;
    }
    public static Builder builder() {
        return new Builder();
    }
    @Override
    public String getName() {
        return getClass().getSimpleName();
    }
    @Override
    public int getOrder() {
        return order;
    }
}

The builder mirrors the one on SafeGuardAdvisor, so both advisors read the same way at the call site:

public static class Builder {
    private List<String> sensitiveWords = List.of();
    private String failureResponse
      = "Response contained forbidden content.";
    private int order = Ordered.LOWEST_PRECEDENCE - 1;
    public Builder sensitiveWords(String... sensitiveWords) {
        this.sensitiveWords = Arrays.asList(sensitiveWords);
        return this;
    }
    public Builder sensitiveWords(List<String> sensitiveWords) {
        this.sensitiveWords = sensitiveWords;
        return this;
    }
    public Builder failureResponse(String failureResponse) {
        this.failureResponse = failureResponse;
        return this;
    }
    public Builder order(int order) {
        this.order = order;
        return this;
    }
    public OutputSafeGuardAdvisor build() {
        return new OutputSafeGuardAdvisor(
          sensitiveWords, failureResponse, order);
    }
}

The varargs overload of sensitiveWords() is one SafeGuardAdvisor doesn’t offer. The default order deserves a closer look. Spring AI terminates the chain with an internal ChatModelCallAdvisor whose order is exactly Ordered.LOWEST_PRECEDENCE. An advisor that shares that value can be sorted behind the terminal one. The terminal advisor never delegates any further. Ours would silently never run.

Defaulting to Ordered.LOWEST_PRECEDENCE – 1 puts us last among the advisors that do execute. Spring AI’s own StructuredOutputValidationAdvisor leaves the same gap, defaulting to Ordered.LOWEST_PRECEDENCE – 2000.

5.2. Implementing adviseCall()

Unlike an input guard, an output advisor starts by letting the call through. We invoke the rest of the chain first, and only then inspect what came back:

@Override
public ChatClientResponse adviseCall(
  ChatClientRequest request, CallAdvisorChain chain) {
    ChatClientResponse response = chain.nextCall(request);
    ChatResponse chatResponse = response.chatResponse();
    if (chatResponse == null || chatResponse.getResults().isEmpty()) {
        return response;
    }
    List<Generation> results = chatResponse.getResults();
    List<Generation> filteredResults = results.stream()
      .map(this::filterGeneration)
      .toList();
    if (filteredResults.equals(results)) {
        return response;
    }
    ChatResponse filtered = new ChatResponse(
      filteredResults, chatResponse.getMetadata());
    return response.mutate()
      .chatResponse(filtered)
      .build();
}

A response with no ChatResponse or generations gives us nothing to inspect, so we hand it straight back. Otherwise, we map over every Generation and compare the filtered list against the original. Generation implements equals(), so that’s a value comparison, not an identity check, and when nothing changed we return the original response.

The replacement swaps the message but keeps the generation’s metadata, so the finish reason survives:

private Generation filterGeneration(Generation generation) {
    if (!containsSensitiveWord(generation.getOutput().getText())) {
        return generation;
    }
    return new Generation(
      new AssistantMessage(failureResponse), generation.getMetadata());
}
private boolean containsSensitiveWord(String text) {
    if (!StringUtils.hasText(text)) {
        return false;
    }
    return sensitiveWords.stream()
      .anyMatch(text::contains);
}

6. Registering the Advisor

Registering the output guard means adding it to the same defaultAdvisors() call:

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    SafeGuardAdvisor inputGuard = SafeGuardAdvisor.builder()
      .sensitiveWords(List.of("SimpleDateFormat", "java.util.Date"))
      .failureResponse("Use java.time instead.")
      .build();
    OutputSafeGuardAdvisor outputGuard = OutputSafeGuardAdvisor.builder()
      .sensitiveWords("DateFormat", "java.util.Date",
        "Calendar", "Timestamp")
      .failureResponse("Use java.time instead.")
      .build();
    return builder.defaultSystem(SYSTEM_PROMPT)
      .defaultAdvisors(inputGuard, outputGuard)
      .build();
}

The two guards deliberately watch different word lists. The output guard watches DateFormat rather than SimpleDateFormat, which also catches the parent class, and adds Calendar and Timestamp, the neighboring legacy types a model reaches for. Adding those to the input guard would be counterproductive: a developer asking about Calendar isn’t the problem, an answer that recommends it is.

We don’t set an order: SafeGuardAdvisor defaults to 0 and runs first, while our default puts the output guard last.

7. Testing the Guardrail

The advisor is a plain class, so we can exercise it without a model. Let’s start with the fixture:

private static final String FAILURE_RESPONSE = "Use java.time instead.";
private static final String LEAKED_ANSWER = "Java 7 used SimpleDateFormat.";
private static final String CLEAN_ANSWER = "LocalDate.now() returns today.";
private OutputSafeGuardAdvisor advisor = OutputSafeGuardAdvisor.builder()
  .sensitiveWords("SimpleDateFormat", "java.util.Date")
  .failureResponse(FAILURE_RESPONSE)
  .build();

Now we stub the chain with Mockito and feed it a generation that leaks:

@Test
void givenAnswerNamingLegacyApi_whenAdvisingCall_thenAnswerIsReplaced() {
    CallAdvisorChain chain = chainReturning(generation(LEAKED_ANSWER));
    ChatClientResponse response = advisor.adviseCall(request(), chain);
    assertThat(textOf(response)).isEqualTo(FAILURE_RESPONSE);
}

A clean answer takes the early return, so we get the very same instance back:

@Test
void givenCleanAnswer_whenAdvisingCall_thenItIsReturnedUntouched() {
    ChatClientResponse original = responseOf(generation(CLEAN_ANSWER));
    CallAdvisorChain chain = chainReturning(original);
    ChatClientResponse response = advisor.adviseCall(request(), chain);
    assertThat(response).isSameAs(original);
}

End to end, the question that defeated the input guard now comes back filtered:

@Test
void givenJava7Question_whenCallingTheModel_thenAnswerIsBlocked() {
    String answer = chatClient.prompt()
      .user("How did we parse date strings in Java 7?")
      .call()
      .content();
    assertThat(answer).isEqualTo(FAILURE_RESPONSE);
}

8. Limitations

Substring matching is blunt in both directions. It’s case-sensitive, so a stray capitalization slips through. It also has no notion of word boundaries. That’s why our list spells out java.util.Date rather than a bare Date. The shorter term would also reject a good answer built on LocalDate. Paraphrases defeat it outright.

It’s also a call-only guard. OutputSafeGuardAdvisor implements CallAdvisor but not StreamAdvisor, so a streamed response bypasses it. Filtering a stream is genuinely harder, because a sensitive word can straddle two chunks and the earlier ones have already reached the client.

For stronger guarantees, a moderation model is a better tool than a word list.

9. Conclusion

In this article, we built a custom Spring AI advisor that inspects the model’s response and replaces it when it contains something we’d rather not return. Pairing it with SafeGuardAdvisor covers both directions: one guard rejects the prompt, the other rejects the answer. Neither is complete on its own, but together they close the obvious gaps with very little code.

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

The post Safeguarding LLM Output in Spring AI first appeared on Baeldung.

       
]]> https://feeds.feedblitz.com/~/971759387/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2024/05/admin-ajax-2-150x150.png https://www.baeldung.com/java-weekly-668 Java Weekly, Issue 668 https://feeds.feedblitz.com/~/971746664/0/baeldung https://feeds.feedblitz.com/~/971746664/0/baeldung#respond Sun, 18 Oct 2026 07:13:23 +0000 https://www.baeldung.com/?p=205228

JDK 28 is shaping up nicely. And an interesting harness experiment.

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

       
]]>

1. Spring and Java

>> Are Harnesses Worth the Cost? [martinfowler.com]

Coding agents with and without a behavioral harness. An interesting experiment, where the harness makes a smaller model more reliable, but adds cost without improving a stronger model’s results.

>> Java – The Year of the Runtime! [inside.java]

Why Java’s runtime matters as AI agents take on more coding.

Also worth reading:

Webinars and presentations:

Time to upgrade:

2. Pick of the Week

>> How to Write an Effective Software Design Document [refactoringenglish.com]

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

       
]]> https://feeds.feedblitz.com/~/971746664/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2016/10/social-Weekly-Reviews-4-150x150.jpg https://www.baeldung.com/spring-ai-alibaba-graph-based-workflows Building Graph-Based Workflows With Spring AI Alibaba https://feeds.feedblitz.com/~/971204387/0/baeldung https://feeds.feedblitz.com/~/971204387/0/baeldung#respond Sat, 10 Oct 2026 01:04:27 +0000 https://www.baeldung.com/?p=205165

Learn how to use Spring AI Alibaba to implement and maintain your prompt orchestration logic.

The post Building Graph-Based Workflows With Spring AI Alibaba first appeared on Baeldung.

       
]]>

1. Overview

When building AI agents, a single prompt to an LLM is usually not enough. Solving complex tasks requires multiple steps, where the output of one step decides what happens next. However, it’s difficult to manually implement and maintain this orchestration logic.

In this tutorial, we’ll solve this problem using Spring AI Alibaba. We’ll use it to model an agentic workflow as a graph of steps, which decides its own path at runtime.

2. Graph-Based Workflows 101

A graph-based workflow breaks a complex task into smaller units of work and connects them to form a graph. Instead of hardcoding the order of execution, we just describe the possible paths. The workflow follows the appropriate path based on the data it has.

Such workflows consist of three main concepts:

  • State: the shared data that flows through the workflow.
  • Nodes: the individual units of work in our graph. They typically read the state, perform business logic, and update the state at the end.
  • Edges: the connections between the nodes. They control the order of execution by deciding which node to move to.

To see these concepts in action, we’ll build an excuse escalation workflow. First, an employee node invents an excuse for a given situation at work. Then, a manager node rates how believable the excuse is.

Next, an edge checks the manager’s rating. If the manager believes the excuse, the workflow ends. Otherwise, the flow loops back to the employee node, which refines the original excuse.

3. Configuring an LLM

Now, let’s set up our project. We’ll start by adding the necessary dependencies to our pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>2.0.1</version>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-graph-core</artifactId>
    <version>1.1.2.3</version>
</dependency>

Here, we first add Spring AI’s OpenAI starter dependency, which we’ll use to interact with an LLM. Next, we add the Spring AI Alibaba graph core dependency. This provides the classes we need to define our graph-based workflow.

To avoid version conflicts and compatibility issues between these dependencies, let’s also include the Spring AI Bill of Materials (BOM):

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>2.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

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

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

With these two properties set, Spring AI automatically creates a ChatClient.Builder bean. We’ll use it to interact with the specified model in our nodes.

4. Defining State Keys

The state of our workflow is a collection of key-value pairs. Before our nodes can read or write them, we need to declare these keys along with a strategy. These strategies control how the graph updates a value.

Let’s define these keys in a KeyStrategyFactory bean:

@Bean
KeyStrategyFactory excuseKeyStrategyFactory() {
    return () -> {
        Map<String, KeyStrategy> strategies = new HashMap<>();
        strategies.put("situation", new ReplaceStrategy());
        strategies.put("excuse", new ReplaceStrategy());
        strategies.put("managerReplies", new AppendStrategy());
        strategies.put("believability", new ReplaceStrategy());
        strategies.put("attempts", new ReplaceStrategy());
        return strategies;
    };
}

Here, the situation key holds the initial input of our workflow. The remaining keys represent the values our nodes will produce.

For most of them, we use the ReplaceStrategy, which overwrites the existing value with the new one. However, we use the AppendStrategy for the managerReplies key, which adds every new value to a list.

5. Implementing Nodes

With our state keys defined, let’s build the nodes of our graph. To create one, we implement the NodeAction interface and its apply() method. This method receives the current state in the form of an OverAllState instance. Then, after executing the business logic, we return a Map containing the updates we want to make to the state.

5.1. Inventing an Excuse

First, let’s create the node that plays the role of our employee:

@Component
class InventExcuseNode implements NodeAction {
    private static final String PROMPT_TEMPLATE = """
      You're an employee explaining why you missed something at work.
      You're a bad liar, but a creative one.
      You never take accountability or admit to lying.
      Situation: {situation}
      The excuse you already gave: {previousExcuse}
      How your manager responded: {managerReplies}
      Give a new excuse in at most two sentences. If you already gave one, do not
      abandon it. Keep the original story and add a further complication.
      Respond with only the excuse.
      """;
    private final ChatClient chatClient;
    InventExcuseNode(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }
}

In our new class, we define the LLM instructions in a prompt template. Additionally, we inject the ChatClient.Builder bean that Spring AI auto-configures and use it to build a ChatClient instance. Next, let’s implement the apply() method:

@Override
public Map<String, Object> apply(OverAllState state) {
    String situation = state.value("situation", String.class)
      .orElseThrow(IllegalStateException::new);
    String previousExcuse = state.value("excuse", "none yet");
    List<String> managerReplies = state.value("managerReplies", List.of());
    Integer attempts = state.value("attempts", 0);
    String excuse = chatClient
      .prompt()
      .user(user -> user.text(PROMPT_TEMPLATE)
        .param("situation", situation)
        .param("previousExcuse", previousExcuse)
        .param("managerReplies", managerReplies.isEmpty()
          ? "none yet"
          : String.join("\n", managerReplies)))
      .call()
      .content();
    return Map.of(
      "excuse", excuse,
      "attempts", attempts + 1
    );
}

Here, we read the current state using the value() method. We define default values for these keys, except for the situation key. Instead, we treat it as a mandatory input to start the workflow.

Then, we fill these values into the prompt template, call the LLM, and get the excuse using the content() method. Finally, we update the state with the new excuse along with the incremented attempt count.

5.2. Reacting as the Manager

Next, we need a manager node that rates the employee’s excuse. Let’s create a new ManagerReactsNode class and implement the apply() method:

private static final String PROMPT_TEMPLATE = """
  You are a tired engineering manager listening to an employee explain themselves.
  Situation: {situation}
  Their excuse: {excuse}
  Reply in one sentence and rate how believable the excuse is, from 0.0 to 1.0.
  """;
@Override
public Map<String, Object> apply(OverAllState state) {
    String situation = state.value("situation", String.class)
      .orElseThrow(IllegalStateException::new);
    String excuse = state.value("excuse", String.class)
      .orElseThrow(IllegalStateException::new);
    ManagerReaction managerReaction = chatClient
      .prompt()
      .user(user -> user.text(PROMPT_TEMPLATE)
        .param("situation", situation)
        .param("excuse", excuse))
      .call()
      .entity(ManagerReaction.class);
    return Map.of(
      "managerReplies", managerReaction.reply(),
      "believability", managerReaction.believability()
    );
}
record ManagerReaction(
  String reply,
  Double believability
) {}

Similar to our previous node, we read the current state, populate the prompt template, and invoke the LLM. However, instead of calling the content() method, we call the entity() method to get a structured output. Finally, we return the reply and the believability score as state updates.

6. Creating a Conditional Edge

Now, we need a way to connect the nodes we’ve implemented. Additionally, we need to write logic to decide whether the workflow should end or the employee should try again. To do this, we’ll create a conditional edge by implementing the EdgeAction interface:

@Component
class ExcuseDispatcher implements EdgeAction {
    private static final double BELIEVABILITY_THRESHOLD = 0.8;
    private static final int MAX_ATTEMPTS = 3;
    @Override
    public String apply(OverAllState state) {
        Double believability = state.value("believability", 0.0);
        Integer attempts = state.value("attempts", 0);
        if (isBelieved(believability) || attempts >= MAX_ATTEMPTS) {
            return "stop";
        }
        return "escalate";
    }
    static boolean isBelieved(Double believability) {
        return believability >= BELIEVABILITY_THRESHOLD;
    }
}

Here, we read the believability and attempts keys from the state. If the manager’s rating reaches our configured threshold, we return the stop label. Otherwise, we return the escalate label to give the employee another chance.

In the first condition, we also check if the employee has exhausted their maximum attempts. This is important to avoid an infinite loop in our workflow.

7. Assembling the Graph

With all our building blocks in place, let’s wire them together and expose a CompiledGraph bean:

@Bean
CompiledGraph excuseGraph(
  KeyStrategyFactory keyStrategyFactory,
  InventExcuseNode inventExcuseNode,
  ManagerReactsNode managerReactsNode,
  ExcuseDispatcher excuseDispatcher
) throws GraphStateException {
    StateGraph excuseGraph = new StateGraph(keyStrategyFactory)
      .addNode("invent_excuse", AsyncNodeAction.node_async(inventExcuseNode))
      .addNode("manager_reacts", AsyncNodeAction.node_async(managerReactsNode))
      .addEdge(StateGraph.START, "invent_excuse")
      .addEdge("invent_excuse", "manager_reacts")
      .addConditionalEdges(
        "manager_reacts",
        AsyncEdgeAction.edge_async(excuseDispatcher),
        Map.of(
          "escalate", "invent_excuse",
          "stop", StateGraph.END
        )
      );
    return excuseGraph.compile();
}

First, we create a StateGraph instance and pass it our KeyStrategyFactory bean. This helps the graph handle updates for each state key. Next, we register our two nodes using the addNode() method, giving each of them a unique name.

Then, we define the flow using the addEdge() method. We connect the START constant to our invent_excuse node, marking it as the entry point. From there, we connect invent_excuse to the manager_reacts node.

After that, we attach our excuseDispatcher to the manager_reacts node using the addConditionalEdges() method. The map we pass here links the labels our dispatcher returns to their target nodes. The escalate label loops back to the invent_excuse node. Meanwhile, the stop label moves to the END constant, which finishes the workflow.

8. Testing the Workflow

Now that we’ve assembled our graph, let’s see how the workflow behaves under different situations.

8.1. Exposing a REST API

First, let’s expose an API endpoint that allows us to initiate the workflow:

@PostMapping("/excuse")
ResponseEntity<ExcuseResponse> generateExcuse(@RequestBody ExcuseRequest request) {
    OverAllState finalState = excuseGraph
      .invoke(
        Map.of("situation", request.situation()),
        RunnableConfig.builder()
          .threadId(UUID.randomUUID().toString())
          .build())
      .orElseThrow();
    ExcuseResponse response = new ExcuseResponse(
      finalState.value("excuse", ""),
      finalState.value("managerReplies", List.of()),
      finalState.value("attempts", 0),
      ExcuseDispatcher.isBelieved(finalState.value("believability", 0.0)));
    return ResponseEntity.ok(response);
}
record ExcuseRequest(String situation) {}
record ExcuseResponse(
  String finalExcuse,
  List<String> managerReplies,
  Integer attempts,
  boolean believed
) {}

Here, we call the invoke() method on our injected CompiledGraph bean. We pass the situation from the request as the initial state. Additionally, we pass a RunnableConfig instance with a random threadId. This helps keep execution of concurrent requests separate from each other.

The invoke() method runs the graph from start to end and returns the final state. Then, we simply read values from this state and use them to prepare the API response.

8.2. Invoking the API Endpoint

Now, let’s use the HTTPie CLI to invoke our API endpoint:

http POST :8080/excuse situation="Employee was 30 seconds late to the daily standup"

Here, we enter a mundane situation. Let’s see what we get as a response:

{
    "attempts": 1,
    "believed": true,
    "finalExcuse": "Sorry, I was only 30 seconds late because my calendar reminder fired late while my laptop was still reconnecting to the meeting room.",
    "managerReplies": [
        "Understood—30 seconds is minor, but please make sure you join promptly next time."
    ]
}

As we can see, the manager believes the very first excuse, so the workflow ends after a single attempt. Consequently, the managerReplies list contains just one reply, since the loop never ran again.

Next, let’s try a situation that’s much harder to explain and see the API response:

http POST :8080/excuse situation="The employee didn't show up to work for 3 days without any notice. Yet, the employee uploaded pictures of them partying on their public instagram account."
{
    "attempts": 3,
    "believed": false,
    "finalExcuse": "The retreat’s emergency coordinator told us all communication had to go through their satellite system, but a solar flare knocked it offline and corrupted the evacuation logs. That also delayed the proof they promised to send confirming the phone confiscation, shuttle failure, and automated Instagram reposts.",
    "managerReplies": [
        "Frankly, this is difficult to believe, and disappearing for three days without finding any way to notify us is unacceptable.",
        "That explanation is extraordinarily unlikely, and we need to discuss your three-day absence and the conflicting Instagram activity immediately.",
        "That explanation strains credibility beyond reason; send the promised proof immediately, and we’ll discuss your three-day unreported absence."
    ]
}

Here, the manager doesn’t believe any of the excuses. Hence, the workflow loops until it reaches the maximum number of attempts.

9. Conclusion

In this article, we implemented a graph-based agentic workflow using Spring AI Alibaba.

We started by defining the state keys along with their strategies. Then, we implemented two LLM-powered nodes and a conditional edge that decides whether to loop or stop the workflow. Finally, we assembled everything into a graph and saw how the workflow adapts its path at runtime.

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

The post Building Graph-Based Workflows With Spring AI Alibaba first appeared on Baeldung.

       
]]> https://feeds.feedblitz.com/~/971204387/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2024/07/Java-Featured-10-150x150.jpg https://www.baeldung.com/java-weekly-667 Java Weekly, Issue 667 https://feeds.feedblitz.com/~/971192846/0/baeldung https://feeds.feedblitz.com/~/971192846/0/baeldung#respond Fri, 09 Oct 2026 15:26:39 +0000 https://www.baeldung.com/?p=205178

Spring + Jev, and the real use of unit testing.

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

       
]]>

1. Spring and Java

>> Spring AI Modular RAG and TypeSafe Jev: Retrieve More, Keep Only What Answers [spring.io]

A Spring AI’s RAG pipeline rewrites and expands a question into focused searches, then retrieves and joins matching chunks. TypeSafe Jev filters and reranks those results for answer evidence, while also screening retrieved text for prompt injection before it reaches the model. Interesting.

Also worth reading:

Webinars and presentations:

Time to upgrade:

2. Pick of the Week

>> Unit tests mark territory more than squash bugs [yosefk.com]

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

       
]]> https://feeds.feedblitz.com/~/971192846/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2016/10/social-Weekly-Reviews-4-150x150.jpg https://www.baeldung.com/java-spring-rest-docs-form-parameters Documenting Form Parameters With Spring REST Docs https://feeds.feedblitz.com/~/971064149/0/baeldung https://feeds.feedblitz.com/~/971064149/0/baeldung#respond Tue, 06 Oct 2026 15:29:15 +0000 https://www.baeldung.com/java-spring-rest-docs-form-parameters

Learn to document form parameters with Spring REST Docs and include their validation constraints in the documentation, too.

The post Documenting Form Parameters With Spring REST Docs first appeared on Baeldung.

       
]]>

1. Introduction

Form-encoded endpoints are common in login and subscription flows, but easy to misunderstand without precise request documentation. API consumers need to know which parameters are required, which are optional, which values are valid, and which extra parameters are intentionally ignored.

In this tutorial, we’ll document form parameters for a Spring MVC endpoint by using Spring REST Docs and MockMvc tests.

It’s important to note that although related, query parameters serve different use cases and are documented with different REST Docs snippets, so we won’t cover them here.

2. Why Document Form Parameters?

In form submissions, everything starts as key-value pairs. Without documentation, there is room for ambiguity:

  • Are all fields required?
  • Which values do constrained fields accept?
  • Are there ignorable parameters?

Spring MVC handles all this for us, but API consumers still need exact details. Spring REST Docs generates documentation snippets after a the test being documenteded passes.

It’s important to note that REST Docs doesn’t convert arbitrary assertions into documentation automatically. We still describe each parameter programmatically. The benefit we get is that we get the documentation only from the tests that pass and validate the behavior of the code.

Note that we’ll handle only form parameters in this article, not the query parameters:

  • Form parameters belong to a request body encoded as application/x-www-form-urlencoded
  • Query parameters are part of the URL, for example /newsletter/subscriptions?frequency=weekly. They serve different use cases and are documented with different REST Docs snippets.

3. Building a Form-Based Endpoint

Let’s build a small newsletter subscription API that receives form fields, validates the payload, and returns a JSON response.

Basically, our form model represents request fields from application/x-www-form-urlencoded data. Spring binds parameters to this object by matching parameter names to JavaBean property names.

So, let’s start with our subscription form. We use Bean Validation annotations to enforce required and constrained values:

public class SubscriptionForm {
    @Email
    @NotBlank
    private String email;
    @NotBlank
    private String name;
    @NotBlank
    @Pattern(regexp = "weekly|monthly")
    private String frequency;
    private List<String> topics;
    private boolean marketingAccepted;
    // standard getters and setters
}

The pattern for frequency explicitly states valid values. If a client sends a value that isn’t weekly or monthly, validation will fail before business logic runs. Note that Spring REST Docs doesn’t infer that constraint, so it doesn’t automatically add valid values to the resulting documentation.

4. Test Setup and Request Construction

The main idea of REST Docs is generating snippets from tested behavior. So, we use MockMvc with REST Docs configuration to create a request that includes all supported form fields.

4.1. Test Setup and Snippet Naming

Our test class uses @WebMvcTest, and we also need to specify the RestDocumentationExtension so JUnit can manage the RestDocumentationContext from Spring REST Docs:

@WebMvcTest
@ExtendWith(RestDocumentationExtension.class)
class NewsletterControllerDocumentationTest {
    @Autowired
    private MockMvc mockMvc;
    @BeforeEach
    void setUp(
      WebApplicationContext context, RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = webAppContextSetup(context)
          .apply(documentationConfiguration(restDocumentation))
          .alwaysDo(document("{method-name}"))
          .build();
    }
}

Our setUp() method prepares the context for each test:

  • apply(documentationConfiguration(restDocumentation)) attaches Spring REST Docs to the MockMvc instance built by webAppContextSetup(), so it captures requests and responses.
  • alwaysDo(document(“{method-name}”)) adds a default documentation generation action that runs for every mockMvc.perform() in our test. The {method-name} placeholder captures the current test method name.

When we want a fixed snippet directory name, we set an explicit identifier in the test itself, like document(“newsletter-subscribe”). That creates snippets under target/generated-snippets/newsletter-subscribe.

4.2. The Form Request

Let’s break down each part of the test, starting with a simple mock payload that includes the form fields. We use the param() method to send key-value pairs to an endpoint that accepts form payloads:

private MockHttpServletRequestBuilder postSubscription() {
    return post("/newsletter/subscriptions")
      .contentType(MediaType.APPLICATION_FORM_URLENCODED)
      .param("email", "api@baeldung.com")
      .param("name", "Baeldung API")
      .param("frequency", "weekly")
      .param("topics", "spring", "testing")
      .param("marketingAccepted", "true");
}

Note that we send topics twice with param(“topics”, “spring”, “testing”), which is how it handles multi-value form fields.

5. Documenting Form Parameters

Now, we’re ready for documentation.

5.1. Describing Form Parameters

We use formParameters() to document the form payload. We define a name and a description, using optional() for non-required parameters:

private FormParametersSnippet docFormParams() {
    return formParameters(
      parameterWithName("email").description("The subscriber email address"),
      parameterWithName("name").description("The display name of the subscriber"),
      parameterWithName("frequency").description("Delivery frequency: weekly or monthly"),
      parameterWithName("topics").optional()
        .description("One or more selected topic values"),
      parameterWithName("marketingAccepted").optional()
        .description("Whether marketing messages are accepted"));
}

If valid frequency values change, we need to remember to manually update the parameter description, as the @Pattern annotation doesn’t infer it.

Most importantly, optional() controls how Spring REST Docs documents a parameter. It doesn’t affect Bean Validation. Constraints such as @NotBlank apply independently when Spring validates the form object.

If we add or remove a required parameter, one of two things usually happens: either request validation behavior changes and the test fails, or descriptor matching fails because our documented parameters no longer match the request.

5.2. Dealing With Bean Validation Constraints

To avoid describing constraints manually, we can read validation metadata through ConstraintDescriptions and incorporate it into parameter descriptions by calling descriptionsForProperty().

Let’s create a helper method to get the constraint description for the SubscriptionForm class and frequency property:

private String constraintsFor(String property) {
    ConstraintDescriptions constraints = new ConstraintDescriptions(SubscriptionForm.class);
    List<String> frequencyConstraints = constraints.descriptionsForProperty("frequency");
}

Now, we can go back to docFormParams() and use our constraintsFor() method:

parameterWithName("frequency")
  .description("Delivery frequency. Constraints: " + constraintsFor("frequency")),

This is the description we get:

Delivery frequency. Constraints: Must match the regular expression `weekly|monthly`, Must not be blank

So, it includes descriptions for all validation annotations. If they change, the description changes, too.

5.3. Defining Ignored Parameters

Some clients send extra form values that we don’t want to include in our API documentation. For example, frontend tracking parameters are irrelevant to business logic. By default, REST Docs fails with a SnippetException if it finds any undocumented parameter, so we have to ignore them explicitly.

Let’s start by going back to postSubscription() and sending the trackingId parameter that we’ll ignore later:

private MockHttpServletRequestBuilder postSubscription() {
    return post("/newsletter/subscriptions")
      // previous parameters ...
      .param("trackingId", "campaign-42");
}

Now, in docFormParams(), we add trackingId as an ignored parameter:

private FormParametersSnippet docFormParams() {
    return formParameters(
      // earlier parameters ...
      parameterWithName("trackingId").ignored());
}

This way, the parameter can appear, but it isn’t part of the API docs we get in the end.

6. Executing the Test and Generating Snippets

Finally, let’s put all those parts together in a mock request:

@Test
void whenFormRequestIsValid_thenDocumentFormParameters() throws Exception {
    mockMvc.perform(postSubscription())
      .andExpect(status().isCreated())
      .andExpect(jsonPath("$.id").isNumber())
      .andDo(
        document("newsletter-subscribe", 
          docFormParams()));
}

This single test validates the endpoint and defines field-level documentation for all form parameters. Most importantly, it helps keep the contract in one place.

When we run our documented test, Spring REST Docs writes snippet files under target/generated-snippets/newsletter-subscribe, which was the name we chose with the document() method.

6.1. Generated Form Snippet

The generated snippet for our form POST test execution shows the parameters in a structured format, using the descriptions we provided with the parameterWithName() calls:

|===
|Parameter|Description
|`+email+`
|The subscriber email address
|`+name+`
|The display name of the subscriber
|`+frequency+`
|Delivery frequency: weekly or monthly
|`+topics+`
|One or more selected topic values
|`+marketingAccepted+`
|Whether marketing messages are accepted
|===

We can include this snippet in AsciiDoc pages during the Maven build using the Asciidoctor plugin.

The main advantage is that our snippets come from requests that actually ran in tests. If tested behavior or descriptors no longer match, tests or snippet generation fail, forcing us to update code and documentation together.

7. Strict vs Relaxed Parameter Documentation

By default, formParameters(…) is strict. This means undocumented parameters fail the snippet unless we mark them as ignored.

However, sometimes we want lighter constraints. For example, we may only care about documenting core fields while allowing additional keys in the request. In that case, we enter the relaxed mode via relaxedFormParameters() instead of formParameters(). Let’s write a new helper method with relaxedFormParameters():

private FormParametersSnippet docRelaxedCoreFormParams() {
    return relaxedFormParameters(
      parameterWithName("email").description("The subscriber email address"),
      parameterWithName("name").description("The display name of the subscriber"),
      parameterWithName("frequency").description("Delivery frequency: weekly or monthly"));
}

Here’s the accompanying test method:

@Test
void whenOnlyCoreFieldsMatter_thenDocumentWithRelaxedMode() throws Exception {
    mockMvc.perform(postSubscription())
      .andExpect(status().isCreated())
      .andDo(document("newsletter-subscribe-relaxed", docRelaxedCoreFormParams()));
}

It submits the form, checks if the return status is created, then generates the documentation snippets in the newsletter-subscribe-relaxed folder.

7.1. Quick Reference for Parameter Modes

Let’s review all parameter processing modes:

Mode How to use What happens
Required parameter parameterWithName(“email”) Must be present in the documented request
Optional parameter parameterWithName(“topics”).optional() We can omit it without snippet failure
Ignored parameter parameterWithName(“trackingId”).ignored() May be present but is excluded from published contract
Relaxed mode relaxedFormParameters(…) Tolerates undocumented parameters

In practice, we’ll use strict mode for stable contracts, add ignored() for known non-contract inputs, and switch to the relaxed mode only when we need additional flexibility.

8. Conclusion

In this article, we documented a form-encoded Spring MVC endpoint using Spring REST Docs and a test-first workflow. With Spring REST Docs, we document tested behavior and regenerate snippets as part of the test cycle, which helps avoid documentation drift over time.

We created a dedicated form model, validated input fields, and exposed a POST endpoint that consumes application/x-www-form-urlencoded requests. In the end, we used formParameters() to describe each key, including optional and ignored fields.

We covered required parameters, optional parameters, ignored parameters, and differences between strict and relaxed mode. Also, we saw how to define where REST Docs saves the documentation snippets.

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

The post Documenting Form Parameters With Spring REST Docs first appeared on Baeldung.

       
]]> https://feeds.feedblitz.com/~/971064149/0/baeldung/feed 0 https://www.baeldung.com/wp-content/uploads/2024/11/Spring-Featured-Image-11-150x150.jpg https://www.baeldung.com/java-weekly-666 Java Weekly, Issue 666 https://feeds.feedblitz.com/~/970894736/0/baeldung Fri, 02 Oct 2026 12:07:00 +0000 https://www.baeldung.com/?p=205124

Monoliths, Java 28 and performance. A good week.

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

      
]]>

1. Spring and Java

>> Performance Improvements in JDK 27 [inside.java]

JDK 27 brings performance goodness across the board. This tour highlights measured gains in areas such as HashMap operations, cryptography, and vectorization, with hardware nuance.

>> The Limitations of Running a Workload Generator In the Same JVM as the System-Under-Test [norlinder.nu]

A workload generator sharing the system-under-test’s JVM can stop scheduling requests during garbage-collection pauses and distort tail-latency measurements. An interesting read.

Also worth reading:

Webinars and presentations:

Time to upgrade:

2. Technical & Musings

>> Durable Execution Is a Property, Not a Product [foojay.io]

A benchmark compares replay-based workflow orchestration with checkpointed jobs. A solid read to understand when workflow engines’ replay and cross-service coordination justify that overhead.

Also worth reading:

3. Pick of the Week

>> Monolith First [martinfowler.com]

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

      
]]> https://www.baeldung.com/wp-content/uploads/2016/10/social-Weekly-Reviews-4-150x150.jpg https://www.baeldung.com/java-27-new-features New Features in Java 27 https://feeds.feedblitz.com/~/970740575/0/baeldung Tue, 29 Sep 2026 06:55:30 +0000 = Java 27]]> https://www.baeldung.com/java-27-new-features

Learn what's new in Java 27: which JEPS are final and which are still in preview.

The post New Features in Java 27 first appeared on Baeldung.

      
]]>

1. Overview

Oracle released version 27 of the Java platform.

Its predecessor, Java 26, brought HTTP/3 to the HTTP Client API and removed the Applet API. Java 27 has nine JEPS: four are final, and five remain in preview or incubation. No feature graduated from preview, and the four final JEPs are the ones we notice at runtime, not in our code.

In this tutorial, we’ll look at what changes without any code adjustments and what moved in the preview features.

2. New Defaults in the JVM Runtime

The following changes don’t require code adjustments or startup flags.

2.1. Compact Object Headers by Default

Java 25 introduced Compact Object Headers (JEP 519) as a full feature, disabled by default. Subsequent tests and reports showed it could reduce the memory footprint and allow for faster processing and garbage collection. Consequently, this feature is now enabled by default in Java 27.vWe can still disable it with -XX:-UseCompactObjectHeaders, but the old layout is planned for deprecation, so that’s a temporary workaround.

Enabling compact headers by default will have the biggest impact for applications that use many small objects, because the header is a fixed cost per object. The smaller the object, the larger the share it occupies. REST services built around DTOs and entities are typical examples.

Note that if we previously sized -Xmx or a container memory limit by measurement, those values are now too generous. Smaller headers mean the same workload holds a smaller live set. Nothing will break, but re-measuring lets us lower the limit and shrink the container. This turns into an actual cost saving.

2.2. G1 as the Default Garbage Collector Everywhere

Since Java 9, G1 has been the default garbage collector, except on machines with a single CPU or less than 1792 MB of memory, where the JVM uses the Serial GC. Java 27 removes that exception, following the G1 improvements in Java 26 (JEP 522).

In practice, this affects small containers: CI runners, sidecars, and serverless environments.

3. Security Enhancements

Two of the four final JEPs improve security, and both take effect without any change to our code.

3.1. Post-Quantum Hybrid Key Exchange for TLS 1.3

Java 27 combines the classical ECDHE key exchange with the quantum-resistant ML-KEM in TLS 1.3. Applications using javax.net.ssl negotiate this hybrid scheme automatically as soon as the peer supports it.

The enhancement targets attackers who record encrypted traffic today and plan on waiting for quantum computers to become able to decrypt it.

Combining the two schemes means that breaking one is not enough for an attack to succeed. However, ML-KEM is much newer than ECDHE and has seen far less cryptanalysis, so it’s added alongside the classical exchange rather than replacing it. Should it prove weak, the connection is no worse than today.

To see which scheme a connection actually negotiates, we can turn on the JSSE handshake log:

java -Djavax.net.debug=ssl,handshake -jar app.jar

In the logged messages, the named group is the key exchange both sides agree on. Java 27 supports three hybrid groups:

  • X25519MLKEM768
  • SecP256r1MLKEM768
  • SecP384r1MLKEM1024

A plain value such as x25519 means the peer doesn’t support any of them.

3.2. JFR In-Process Data Redaction

Java 27 masks sensitive values in JFR recordings inside the JVM, before they reach the recording file. Values that would previously appear in the recording now show up as [REDACTED].

This matters because recordings capture command-line arguments, environment variables, and system properties, where passwords and tokens are typically stored. Attaching one to a support ticket used to mean shipping those secrets along.

We should be aware that redaction is name-based. The JVM matches property, variable, and argument names against a list of glob patterns. The default settings cover names such as *password* or *token*, but we can add our own patterns with a JVM flag:

java -XX:FlightRecorderOptions:redact-key=*credential*,*secret* -jar app.jar

Here, redact-key applies to the names of system properties and environment variables. With the patterns above, the values of db.credential and client.secret will also be replaced in the recording, whereas a name such as auth.key still passes through. Command-line arguments are handled by a separate redact-argument option.

4. Still in Preview

Five features remain in preview or incubation. Most of them are resubmitted with minor refinements, and one has changes that break existing code.

4.1. Structured Concurrency

This preview brings code breaking changes in comparison to the sixth preview:

  • The joiners now throw ExecutionException instead of FailedException
  • Joiner gains a third type parameter for the exception type
  • awaitAll() is gone
  • onTimeout() becomes timeout()

Breaks that are due to the exception type will probably be the most common in practice, for example:

try (var scope = StructuredTaskScope.open()) {
    Subtask<User> user = scope.fork(() -> loadUser(id));
    Subtask<List<Order>> orders = scope.fork(() -> loadOrders(id));
    scope.join();
    return new Profile(user.get(), orders.get());
} catch (ExecutionException e) {
    throw new ProfileException(e.getCause());
}

Every catch clause written against the sixth preview has to be updated, and ExecutionException is checked, so the compiler will point them out.

4.2. Lazy Constants

A lazy constant holds a value that is computed on the first access and then behaves like a constant. The JVM can optimize them much like a final field, which plain lazy initialization behind a synchronized block doesn’t allow. The typical use is an expensive object we would rather not build during startup. For instance:

private static final LazyConstant<ExpensiveParser> PARSER = LazyConstant.of(ExpensiveParser::new);

The third preview removes isInitialized() and orElse(), two low-level methods that invite inspecting the initialization state, exactly what the abstraction is meant to hide.

In return, Set.ofLazy() arrives, so List, Set, and Map now all have lazy variants.

This is the only new API element in this release.

4.3. PEM Encodings of Cryptographic Objects

PEM is the text format that wraps Base64-encoded DER data between markers, and we use it for certificates, CRLs, and keys. Before this API, the JDK offered no standard way to read or write those data. We stripped the markers and decoded the Base64 by hand, or reached for a third-party library.

PEMEncoder and PEMDecoder handle both directions, and withEncryption(char[]) and withDecryption(char[]) cover password-protected private keys.

The third preview is mostly refinement:

  • DEREncodable becomes BinaryEncodable, a name that no longer ties the interface to DER.
  • X509Certificate and X509CRL now implement it. EncryptedPrivateKeyInfo gains methods for encrypting and decrypting keys directly.
  • A new CryptoException reports failures, and constructors taking Base64-encoded byte arrays were added.

4.4. Primitive Types in Patterns, instanceof, and switch

Pattern matching and switch have long worked on reference types but stopped at primitives. JEP 532 closes that gap: instanceof and switch accept primitive type patterns, and a pattern matches only when the value fits into the target type without loss.

So. the following sample is valid:

static String describe(int value) {
    return switch (value) {
        case byte b -> "fits in a byte: " + b;
        case short s -> "fits in a short: " + s;
        default -> "needs an int: " + value;
    };
}

Java 27 resubmits the feature unchanged from Java 26. It has been in preview since Java 23.

4.5. Vector API

The Vector API lets us express computations that the JIT compiles into the CPU’s vector instructions.

The API is still in incubation and unchanged from Java 26. The only difference is the bundled SLEEF library, which supplies the vector math intrinsics on ARM and RISC-V and moves from 3.6.1 to 3.9.0.

Twelve incubation rounds sound like a stalled feature, but the reason is a dependency. The API waits for the value types from Project Valhalla so that vector values can be flattened instead of allocated. JEP 401 has since been integrated into JDK 28 as a preview, so the next round may be the one that promotes the Vector API out of incubation.

5. Smaller Changes and Removals

Beyond the JEPs, Java 27 brings a number of smaller changes to the class library and tooling:

  • Math and StrictMath gain the inverse hyperbolic functions acosh(), asinh(), and atanh()
  • String.encodedLength(Charset) returns the byte length in a given charset without building the array
  • BigDecimal.rootn(int, MathContext) computes nth roots
  • DateTimeFormatter accepts short zone offsets such as +02
  • HashMap.putAll() is 66–86% faster when copying from another HashMap
  • jcmd VM.security_properties prints the effective security properties of a running JVM

The JVM Compiler Interface (JVMCI) has been removed. It was a socket for plugging an externally built JIT compiler into HotSpot, and its main user, the Graal compiler, already left the JDK in Java 17. The GraalVM distribution and Native Image are unaffected.

6. Feature Summary

Java 27 spreads its nine JEPs across three maturity levels, and only the final ones are active out of the box:

Feature JEP Status
Compact Object Headers by Default 534 Final
G1 as the Default Garbage Collector Everywhere 523 Final
Post-Quantum Hybrid Key Exchange for TLS 1.3 527 Final
JFR In-Process Data Redaction 536 Final
Lazy Constants 531 Preview
PEM Encodings of Cryptographic Objects 538 Preview
Primitive Types in Patterns, instanceof, and switch 532 Preview
Structured Concurrency 533 Preview
Vector API 537 Incubation

The preview features need –enable-preview at both compile and run time, and the compiler requires us to specify the release:

javac --enable-preview --release 27 Main.java
java --enable-preview Main

Note that the Vector API isn’t a preview feature but an incubating module, so it takes a different flag:

javac --add-modules jdk.incubator.vector Main.java
java --add-modules jdk.incubator.vector Main

Both kinds of API may change or disappear in the next release, meaning they belong in experiments rather than in production code.

7. Conclusion

Java 27 is a release we notice at runtime rather than in our code: smaller objects, one garbage collector everywhere, a quantum-resistant TLS handshake, and recordings that no longer leak credentials.

Nothing graduated from preview, so there’s no new production API to build on. But Java 29 will be the next LTS, and testing against 27 now lets us find the obsolete startup flags and the TLS handshakes that older network equipment rejects one release early, instead of all at once during the LTS upgrade.

The post New Features in Java 27 first appeared on Baeldung.

      
]]> https://www.baeldung.com/wp-content/uploads/2024/07/Java-Featured-11-150x150.jpg https://www.baeldung.com/java-weekly-665 Java Weekly, Issue 665 https://feeds.feedblitz.com/~/970561523/0/baeldung Sun, 27 Sep 2026 13:04:27 +0000 https://www.baeldung.com/?p=205082

Performance in Java is always getting better.

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

     
]]>

1. Spring and Java

>> Just-In-Time Compilation for Java Performance: Recent and Ongoing Improvements [inside.java]

The JVM’s JIT compilers keep adapting – a quick survey of recent performance improvements and the work underway around Valhalla, Leyden, and Panama.

A very useful look at where Java’s runtime speed comes from and where its compilers are headed.

>> Spring AI and TypeSafe Jev: Fast, Cheap, Structured Decisions [spring.io]

Sometimes an AI application needs a decision, not more text. Jev is for that 🙂 (when it opens up agian).

Also worth reading:

Webinars and presentations:

Time to upgrade:

2. Technical & Musings

>> Diagrams as Code: Mermaid Support on the new Foojay [foojay.io]

Foojay now renders Mermaid diagrams directly from fenced code blocks. Frank Delporte walks through sequence, class, state, ER, and Gantt examples, then covers theme-aware rendering, syntax checks, and accessibility. A practical way to keep diagrams for Java APIs and workflows in the same reviewable source as the article.

Also worth reading:

3. Pick of the Week

>> Build your Agentic Harness is Out

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

     
]]> https://www.baeldung.com/wp-content/uploads/2016/10/social-Weekly-Reviews-4-150x150.jpg https://www.baeldung.com/java-hibernate-find-annotation The @Find Annotation in Hibernate https://feeds.feedblitz.com/~/970277321/0/baeldung Sat, 26 Sep 2026 04:20:54 +0000 https://www.baeldung.com/java-hibernate-find-annotation

Learn about how to use the @Find annotation in Hibernate to generate a repository implementation using method query naming conventions.

The post The @Find Annotation in Hibernate first appeared on Baeldung.

     
]]>

1. Introduction

In this article, we’re going to look at how to use the @Find annotation in Hibernate. We’ll see what it is, what it’s used for, and how to use it.

2. Setting up Hibernate

Before we can use the @Find annotation, we need to set up Hibernate and our database.

2.1. Dependencies

To use @Find in Hibernate, we need to use version 6.3 or newer. The newest release at the time of writing is 7.4.6.Final:

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

We also need the Jakarta Data Core API. The newest release at the time of writing is 1.0.2:

<dependency>
    <groupId>jakarta.data</groupId>
    <artifactId>jakarta.data-api</artifactId>
    <version>1.0.2</version>
</dependency>

This gives us everything we need to write our repository code.

2.2. Hibernate Processor

In addition to the dependencies for writing our repositories, we need to configure the Hibernate Processor. This will generate concrete classes for our repository interfaces at compile time.

When using Hibernate 7, this is configured by adding an annotation processor to the maven-compiler-plugin:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.hibernate.orm</groupId>
                        <artifactId>hibernate-processor</artifactId>
                        <version>7.4.6.Final</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

This needs to match the version of the hibernate-core dependency we specified earlier.

Once the plugin is added, the Maven build will automatically generate additional classes for us, including Hibernate Metamodel classes for our entities, and concrete classes that implement our repository interfaces, as we’ll see later.

2.3. Database

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

CREATE TABLE authors (
  author_id   BIGINT PRIMARY KEY,
  name        TEXT NOT NULL
);
CREATE TABLE books (
  book_id     BIGINT PRIMARY KEY,
  title       TEXT NOT NULL,
  author_id   BIGINT NOT NULL,
  FOREIGN KEY (author_id) REFERENCES authors(author_id)
);

This gives us two tables – books and authors – such that there’s a foreign key between them.

We then need some data in our database:

INSERT INTO authors (author_id, name) VALUES
  (1, 'George Orwell'),
  (2, 'Haruki Murakami'),
  (3, 'Agatha Christie'),
  (4, 'Ursula K. Le Guin');
INSERT INTO books (book_id, title, author_id) VALUES
  (101, '1984', 1),
  (102, 'Animal Farm', 1),
  (103, 'Norwegian Wood', 2),
  (104, 'Kafka on the Shore', 2),
  (105, 'Murder on the Orient Express', 3),
  (106, 'And Then There Were None', 3),
  (107, 'The Left Hand of Darkness', 4);

2.4. JPA Entity

Finally, since we’ll be working with Hibernate, we also need Hibernate entities to represent our data.

First, our Author entity:

@Entity
@Table(name = "authors")
public class Author {
    @Id
    @Column(name = "author_id")
    private Long authorId;
    private String name;
    public Long getAuthorId() {
        return authorId;
    }
    public String getName() {
        return name;
    }
}

And then the Book entity:

@Entity
@Table(name = "books")
public class Book {
    @Id
    @Column(name = "book_id")
    private Long bookId;
    private String title;
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "author_id", nullable = false)
    private Author author;
    public Long getBookId() {
        return bookId;
    }
    public String getTitle() {
        return title;
    }
    public Author getAuthor() {
        return author;
    }
}

This references our Author entity so we can follow those links in our queries.

3. Repository Interfaces

Once everything is set up, we’re ready to start writing our repositories. These are written as Java interfaces and annotated with the @jakarta.data.repository.Repository annotation:

@Repository
public interface BookRepository {
}

On its own, this is enough for the Hibernate Processor to discover and generate a concrete implementation – in this case, called BookRepository_.

// Generated code
public class BookRepository_ implements BookRepository {
    protected StatelessSession session;
    public BookRepository_(StatelessSession session) {
        this.session = session;
    }
    public StatelessSession session() {
        return session;
    }
}

This generates an implementation constructed with a StatelessSession instance. We can then create instances of this as needed when we want to query our data.

3.1. Injecting an EntityManager

We often don’t want to create repository instances on demand. Instead, we’d like to create them once at the start of our application and then pass them around. For example, we might want to create them in our Spring context.

Fortunately, Hibernate supports this too. All we need to do is add a special method to our interface that returns an EntityManager:

@Repository
public interface AuthorRepository {
    EntityManager entityManager();
}

If we do this, Hibernate will construct an alternative form of our repository that is constructed using our EntityManager instead:

// Generated code
public class AuthorRepository_ implements AuthorRepository {
    protected EntityManager entityManager;
    public AuthorRepository_(EntityManager entityManager) {
        this.entityManager = entityManager;
    }
    @Override
    public EntityManager entityManager() {
        return entityManager;
    }
}

We can then safely construct this once and reuse it as much as needed.

4. Finding By Fields

Once we’ve got our repository, we need to be able to do something with it. We can add methods to find entities using the @Find  annotation, with special conventions for parameter names and return types.

@Repository
public interface BookRepository {
    @Find
    List<Book> getAllBooks();
}

Here we have a method called getAllBooks. The method name is unimportant. However, the fact that it returns a List<Book> means that the generated code will understand that we’re working with Book entities, and that we’re returning all of the ones that match our query.

This will equate to running the following query:

SELECT b1_0.book_id, b1_0.author_id, b1_0.title 
FROM books b1_0

We can go a step further with this by actually filtering our results:

@Find
Book getBookWithTitle(String title);

Again, the method title can be anything. However, the parameter name must exactly match a field in our Book entity. As such, Hibernate generates code that will filter by that field:

SELECT b1_0.book_id, b1_0.author_id, b1_0.title 
FROM books b1_0 
WHERE b1_0.title = ?

This time, we return only a single Book entity. As such, Hibernate knows to return a single matching entity. If there isn’t one, we’ll get an EmptyResultException thrown instead. Alternatively, if there are multiple records that match, we’ll get a NonUniqueResultException thrown.

5. Optional Results

Sometimes we want to search for a single record that may not exist. We can handle the EmptyResultException that gets thrown, but this isn’t ideal.

Hibernate supports a few ways to handle this automatically. The most obvious is to update our method to return Optional<Book> instead:

@Find
Optional<Book> getOptionalBookWithTitle(String title);

In this case, an unknown record returns Optional.empty() instead.

Alternatively, if we don’t want to deal with this, we can annotate our method with jakarta.annotation.Nullable.

@Find
@Nullable
Book getNullableBookWithTitle(String title);

This tells the generated code to return null instead of throwing an exception.

In both cases, the database queries are identical. The only difference is what the generated code does with the results after executing the query. Both cases also still throw a NonUniqueResultException if the query returns more than one result.

6. Finding By Nested Fields

So far we’ve seen how to find records based on data directly in that record. However, often we want to search based on related data too. Hibernate can do this based on how we name our method parameters. If we use a “$” symbol, this is interpreted as linking fields through related entities:

@Find
List<Book> getAllBooksByAuthorName(String author$name);

Here, our query will join from Book through the Book.author field, and then query based on Author.name:

SELECT b1_0.book_id, b1_0.author_id, b1_0.title 
FROM books b1_0 
  JOIN authors a1_0 ON a1_0.author_id = b1_0.author_id 
WHERE a1_0.name = ?

We can use this technique for as many steps as we want. However, we can only follow relationships that use @ManyToOne or @OneToOne. Relationships using @OneToMany or @ManyToMany won’t work since the generated query would need to link to multiple records.

7. Multiple Results

So far we’ve seen how to return either a single result or all matching results. However, sometimes we need more control. Hibernate can manage all of this for us.

7.1. Sorting

By default, queries that return lists of records return them in the order the database returns them. This can vary based on many factors, so we can’t rely on it for consistent ordering.

If we add the @OrderBy annotation to our method, Hibernate will sort our results by the specified fields:

@Find
@OrderBy("title")
List<Book> getAllBooks();

This equates to executing the following query:

SELECT b1_0.book_id, b1_0.author_id, b1_0.title 
FROM books b1_0 
ORDER BY b1_0.title

With the addition of the ORDER BY clause for consistent sorting.

If necessary, we can repeat the annotation to allow sorting by multiple fields:

@Find
@OrderBy("title")
@OrderBy("author$name")
List<Book> getAllBooks();

Note that we can also sort by fields on joined entities using exactly the same syntax as we saw earlier. Doing this generates a query like this:

SELECT b1_0.book_id, b1_0.author_id, b1_0.title 
FROM books b1_0 
  JOIN authors a1_0 ON a1_0.author_id = b1_0.author_id 
ORDER BY b1_0.title desc, a1_0.name

We can also specify the sort direction using the descending parameter. This defaults to false, but we can change this to indicate descending sorts:

@Find
@OrderBy(value = "title", descending = true)
List<Book> getAllBooks();

Unsurprisingly, we can mix all of this as needed, allowing for sorts on multiple fields in different directions.

We can also allow dynamic sorting by accepting a parameter of type Order<Book>.

@Find
List<Book> getAllBooks(Order<Book> sort);

This is generic over the entity that we’re working on. If we use the wrong generic type, Hibernate will throw an error at compile time. We can now call this and define the sorts at runtime:

List<Book> books = repository.getAllBooks(Order.by(
  Sort.asc("title"),
  Sort.desc("author.name")
));

Note that here we need to specify nested fields using dotted syntax instead of the “$” symbol, but otherwise it all works the same.

7.2. Pagination

In addition to sorting our results, we can also request specific pages of results. We can do this by adding a parameter of type PageRequest to our method:

@Find
@OrderBy("title")
List<Book> getBooksPage(PageRequest pageRequest);

We don’t technically need to enforce ordering on these queries, but it’s usually a good idea so results stay consistent across pages.

We can then call this specifying the desired page and page size:

List<Book> books = repository.getBooksPage(PageRequest.ofPage(1, 3, true));

Note that the page is 1-indexed, so this will return the first page of 3 records.

If we want to know more about the details of the page, we need to change our return type to Page<Book> instead of List<Book>:

@Find
@OrderBy("title")
Page<Book> getBooksPage(PageRequest pageRequest);

We now have access to not only the page contents, but also page details like the total number of elements and whether there are next and previous pages:

long total = books.totalElements();
if (books.hasNext()) {
    // Do something
}
if (books.hasPrevious()) {
    // Do something
}

Note that the third parameter to our PageRequest.ofPage() call tells Hibernate whether we want a total count of the elements across all pages. If we pass true, Hibernate executes an additional query to count matching elements. If we pass in false, Hibernate doesn’t execute this additional query, and the total number of elements won’t be available.

8. Summary

In this article, we’ve had a very brief look at using the @Find annotation in Hibernate. We’ve seen what it is, how it works, and how we can use it. Next time you need to generate repositories like this, why not give it a go?

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

The post The @Find Annotation in Hibernate first appeared on Baeldung.

     
]]> https://www.baeldung.com/wp-content/uploads/2024/11/Data-Featured-Image-06-150x150.jpg