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:

• >> Quality Outreach Heads-up – JDK 28: Rich JavaDoc Notes [inside.java]
• >> JEP targeted to JDK 28: 401: Value Objects (Preview) [inside.java]
• >> The quarkus.io site is now built with Quarkus Roq [quarkus.io]
• >> MCP goes stateless, and Quarkus already implements it [quarkus.io]
• >> Releasing Spring for Modern Challenges [spring.io]
• >> Leave the Class Path in the Rearview Mirror [netflixtechblog.com]
• >> Mirroring the JUnit repository to Codeberg [marcphilipp.de]

Webinars and presentations:

• >> Episode 70 “AOT Caching – Netflix’ Practice vs OpenJDK’s Theory” [I/O] [inside.java]
• >> Quarkus Insights #260: CLI and TUI Applications — A Terminal Renaissance in Java [quarkus.io]
• >> Spring Office Hours Podcast: S5E24 – Jev, Java and Spring [spring.io]
• >> A Bootiful Podcast: Spring Tools lead Martin Lippert [spring.io]

Time to upgrade:

• >> BoxLang 1.17.0 Released: Module Inception, CLI Checker, Jar Loading and much more! [foojay.io]
• >> Hibernate 8.0.0.Beta2 [in.relation.to]
• >> Helidon 27 Released [inside.java]
• >> Quarkus 3.39.5, 3.33.4, 3.33.3.3, and 3.27.5.3 [quarkus.io / github.com/quarkusio]
• >> What’s New in the September 2026 Azul Payara Release? [azul.com]
• >> Ktor 3.6.0 Is Now Available! [jetbrains.com]
• >> GraalVM Community 25 Innovation 4 (graal 25.4.4.1.1, jdk 25.0.4.1.1) [github.com/graalvm]
• >> JHipster 9.4.0 [github.com/jhipster]
• >> Vert.x 5.2.0 [github.com/eclipse-vertx]
• >> Elasticsearch 8.19.22 [github.com/elastic]
• >> Zuul 4.1.9, 4.1.8, and 4.1.5 [github.com/Netflix]
• >> Grails 7.2.4, 7.1.7, and 7.0.17 [github.com/apache]
• >> Micronaut Core 5.2.5, 5.2.4, 4.10.29, and 5.2.3 [github.com/micronaut-projects]

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:

• >> AI-assisted genealogy, a follow-up [frankel.ch]
• >> AsciiDoc Support on the new Foojay [foojay.io]
• >> Measuring the Sun’s oscillations with an amateur spectroheliograph [melix.github.io]
• >> I don’t like LLMs [martinfowler.com]
• >> Building the business case for agentic software development [scottlogic.com]
• >> Responsible Quality Engineering [satisfice.com]
• >> Introducing WildFly Themes — Community-Driven Planning for WildFly [wildfly.org]

3. Pick of the Week

>> Build your Agentic Harness is Out

The post Java Weekly, Issue 665 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.

       

1. Introduction

JDK 26 contains multiple resolved issues and over 1,000 enhancements. A major part of this work focuses on performance across the JDK libraries, garbage collectors, compiler, and runtime.

Some improvements require an API change or a JVM option. Others benefit existing applications as soon as they move to JDK 26. Together, these changes target faster startup, higher throughput, and better scalability.

In this tutorial, we’ll explore the most important performance improvements in JDK 26. We’ll also see how they affect application code and deployment choices.

2. JDK Library Improvements

We’ll start with the changes that very closely relate to application library code.

2.1. Lazy Constants

JEP 526 introduces Lazy Constants as a second preview. The LazyConstant API holds an immutable value that is computed only when it’s first requested.

Before JDK 26, delaying the creation of an expensive object often required a nullable field, a null check, and synchronization. For example, we could initialize a service only when it was first requested:

public final class Application {
    private static Service service;
    static synchronized Service service() {
        if (service == null) {
	    service = new Service();
	}
	return service;
    }
	private static final class Service {}
}

We can now express the same intent directly:

public final class Application {
    private static final LazyConstant<Service> SERVICE = LazyConstant.of(Service::new);
    static Service service() {
        return SERVICE.get();
    }
    private static final class Service {}
}

The first call to get() creates the service. Later calls return the same value. Initialization occurs at most once and remains safe when several threads race to access it. When a lazy constant is stored in a final field, the JVM can optimize repeated access in a way similar to a final constant. This gives us deferred work without permanently paying the usual synchronization cost.

Since this is a preview API, we need preview features at compile time and runtime:

javac --enable-preview --release 26 Application.java
java --enable-preview Application

2.2. Strings, Records, and Cryptography

JDK 26 reduces intermediate allocation and copying inside MemorySegment.getString(). This matters when an application frequently converts native or off-heap data into Java strings. Early benchmarks showed lower latency for all tested sizes, with the largest improvement for short strings.

Generated hashCode() methods for records now receive better type profiling. Record-heavy maps, sets, grouping operations, and deduplication can therefore gain throughput without source changes. The release also optimizes AES, ML-DSA, and elliptic-curve P-256 operations. These changes improve key setup, low-level arithmetic, and hardware-specific execution on supported processors.

There are smaller improvements as well. GZIPInputStream reads single compressed streams more efficiently, while Method.equals() it immediately succeeds when both references point to the same instance. The latter can help dynamic proxies, where method comparisons occur frequently during dispatch.

3. Garbage Collection and Startup Improvements

Garbage collection runs automatically, but it isn’t free. The JVM performs extra work whenever an application changes object references. It also prepares heap structures, classes, and commonly used objects during startup.

JDK 26 reduces both kinds of overhead. It makes G1 reference tracking less expensive, extends ahead-of-time caching to every garbage collector, and avoids preparing an unnecessarily large initial heap.

3.1. Lower G1 Synchronization Overhead

G1 divides the heap into many regions. During a collection, it can reclaim selected regions instead of processing the entire heap.

Objects in different regions can still reference one another. For example, an Order object in one region may reference a Customer object in another. G1 must remember this connection so that it doesn’t reclaim the customer while the order is still reachable.

G1 tracks these changes using a card table. The card table represents the heap as a collection of small areas called cards. When application code changes an object reference, a write barrier marks the corresponding card as dirty.

This write barrier runs for every relevant reference update:

order.setCustomer(customer);

Background refinement threads inspect dirty cards and record the references that cross region boundaries. Previously, application threads and refinement threads worked with the same card table. They needed additional synchronization to avoid interfering with one another. This synchronization made each write barrier more expensive. The cost became noticeable in applications that frequently create objects or update fields, such as caches, in-memory data stores, and request-processing systems.

JEP 522 introduces a second card table. Application threads write to the active table, while refinement threads process the other table. G1 swaps the tables when the active table needs refinement.

The two groups of threads can now perform most of their work independently. This reduces synchronization and makes object-reference updates cheaper. Published benchmarks showed throughput improvements of 5–15% in reference-heavy workloads. Workloads with fewer reference updates gained up to approximately 5%.

The second table requires additional native memory equal to roughly 0.2% of the heap. This is about 2 MB for every 1 GB of heap space. Applications already using G1 receive the improvement without code or configuration changes. However, the result depends on how frequently an application updates references. We should therefore verify the gain with a representative workload.

3.2. AOT Object Caching with Any GC

A Java application performs several operations before it can handle useful work. The JVM loads and links classes, verifies bytecode, and creates frequently used objects. Framework-based applications may repeat a large amount of this work on every start.

The ahead-of-time cache moves some of that work to an earlier training run. During training, the JVM records classes and heap objects used by the application. Later executions can load those prepared artifacts instead of creating everything again.

For example, the cache may contain Class objects together with their related strings and byte arrays. Reusing these objects can reduce both startup time and the time required to reach peak performance.

The difficulty is that garbage collectors don’t always represent object references in the same way. A cached object prepared for one collector may contain references that another collector can’t use directly. This previously limited AOT object caching to compatible garbage collectors.

JEP 516 adds a collector-independent representation for cached objects. Instead of storing references in a format tied to one collector, the cache can store objects in a form that the JVM converts while loading them. JDK 26 can therefore use two approaches. A GC-specific cache can be mapped directly into memory for a fast warm start. A GC-independent cache can be streamed into the heap and converted to the selected collector’s object format.

AOT object caching now works with every garbage collector, including ZGC. This allows applications to combine faster startup and warmup with ZGC’s low-pause behavior.

3.3. Smaller Default Initial Heap

The JVM also prepares an initial amount of heap memory at startup. We can set this value explicitly with -Xms or -XX:InitialHeapSize. When neither option is present, the JVM calculates a default.

Earlier releases based the default on 1.5625% of the machine’s physical memory. This is approximately one sixty-fourth of the available RAM.

Consequently, a high-memory server could receive a surprisingly large initial heap. On a machine with 256 GB of memory, 1.5625% represents roughly 4 GB before other JVM sizing rules are considered. A small service may not need anything close to that amount during startup. Preparing a larger heap involves additional initialization and metadata work. This can delay startup even though most of the initial space remains unused.

JDK 26 now uses MinHeapSize  as the default initial heap when no explicit size is configured. The JVM starts with a smaller heap and expands it as the application requires more memory.

This change reduces unnecessary startup work for applications that rely on the default heap settings. Applications that already provide –Xms or –XX:InitialHeapSize retain their configured behavior.

4. Compiler and Runtime Improvements

The C2 compiler can now optimize methods with very large parameter lists. Such methods previously remained on C1-compiled or interpreted paths. This change mainly helps generated code and frameworks that create unusually wide method signatures.

C2 also has a better cost model for SuperWord loop vectorization. Processing several values with SIMD instructions can be faster than scalar execution. However, packing, shuffling, and combining vectors also cost CPU time. The improved model helps C2 vectorize a loop only when the expected gain outweighs that extra work. No application changes are required.

Finally, virtual threads can unmount from their carrier threads while waiting for class initialization in common paths. Before JDK 26, this wait could pin a carrier and prevent it from running other virtual threads. The change improves scalability during bursts of class loading and reduces the risk of carrier starvation.

5. Measuring the Upgrade

Performance changes depend on allocation patterns, reference updates, startup behaviour, hardware, and the selected garbage collector. Therefore, an upgrade test should compare the same workload, JVM options, heap limits, and traffic profile on both JDK versions.

We can record Java Flight Recorder data during a representative run:

java -XX:StartFlightRecording=filename=jdk26.jfr,settings=profile \
	-jar application.jar

Useful comparisons include startup time, request throughput, allocation rate, GC pause distribution, and CPU consumption. For an AOT cache, the training workload should also cover the application’s normal startup path.

The best result is a repeatable improvement in the application’s own service-level metrics. A synthetic benchmark is useful for isolating a feature, but it doesn’t replace an end-to-end measurement.

6. Conclusion

In this article, we explored the main performance improvements in JDK 26. We looked at lazy constants, lower-allocation library code, G1’s reduced synchronization, broader AOT caching, smarter C2 decisions, and better virtual-thread behavior.

Most of these optimizations require little or no source change. By testing JDK 26 with production-like workloads, we can determine which improvements translate into meaningful gains for our applications.

The post Performance Improvements in JDK 26 first appeared on Baeldung.

       

1. Overview

When interacting with chatbots, we’re used to the plain text responses from Large Language Models (LLMs). However, when integrating these LLMs into our application, it becomes a problem to use these responses programmatically.

Spring AI solves this problem with its structured output support. Instead of dealing with raw strings, we can instruct the model to return data that maps directly to our Java classes, collections, and other types.

In this tutorial, we’ll explore receiving structured output from LLMs using Spring AI.

2. Setting up the Project

Before we dive into the implementation, let’s set up our project.

2.1. Configuring a Chat Model

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

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

Here, we import Spring AI’s OpenAI starter dependency, which we’ll use to interact with a chat model.

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 bean of type ChatModel, which we’ll use to build a ChatClient bean:

@Bean
ChatClient chatClient(ChatModel chatModel) {
    return ChatClient
      .builder(chatModel)
      .build();
}

The ChatClient class acts as the main entry point for interacting with our configured chat completion model.

2.2. Defining Our Domain Entity

Next, let’s define a domain entity that we’ll convert our model’s responses into:

record Recipe(
  String name,
  String cuisine,
  Difficulty difficulty,
  int prepTimeMinutes,
  List<Ingredient> ingredients,
  List<String> steps
) {
    record Ingredient(
      String name,
      String quantity
    ) {}
    enum Difficulty { EASY, MEDIUM, HARD }
}

Here we define a Recipe record with a nested Ingredient record and a Difficulty enum.

When defining domain entities, we should pick descriptive field names as it helps the LLM to populate them correctly. For ambiguous fields, we can annotate them with @JsonPropertyDescription to give the model additional context.

3. Converting the Response Into Our Domain Entity

With our setup in place, let’s use the ChatClient bean to ask the model for a recipe and convert its response into our record:

Recipe recipe = chatClient
  .prompt("Generate a recipe for a vegetarian lasagna.")
  .call()
  .entity(Recipe.class);
assertThat(recipe)
  .hasNoNullFieldsOrProperties()
  .satisfies(r -> assertThat(r.ingredients())
    .hasSizeGreaterThan(1)
  );

Here, we pass an instruction to generate a recipe and then invoke the entity() method with the Recipe class instead of calling content(), which would have given us a raw text response.

The entity() method hands us a fully populated Recipe instance, without us writing a single line of parsing logic. Behind the scenes, Spring AI performs the following steps:

• First, generates a JSON schema from the target type we pass in.
• Then, it appends this schema to our user prompt along with a set of format instructions.
• Finally, once the model replies, it deserializes the response text into an instance of our target type

4. Self-Correcting Structured Output

Even with a clear schema and formatting instructions in the prompt, a chat model can still return a response that doesn’t conform to it. Let’s look at some ways in which we can recover from such failures.

4.1. Client-Side Validation With validateSchema()

In the first approach, the response is validated on our side before deserialization:

Recipe recipe = chatClient
  .prompt("Generate a recipe for a high protein dessert.")
  .call()
  .entity(Recipe.class, spec -> spec.validateSchema());

Here, we pass an additional lambda to entity() and call the validateSchema() method.

With this enabled, Spring AI validates the model’s response against the generated JSON schema before deserializing it. In case of failure, it sends the validation errors back to the model. This process repeats until the output becomes valid or the retry limit is exhausted, which defaults to three.

Alternatively, we can register the StructuredOutputValidationAdvisor while building our ChatClient bean. Using this approach, we can override the default settings and apply the client-side validation to every call:

@Bean
ChatClient validatingChatClient(ChatModel chatModel) {
    return ChatClient
      .builder(chatModel)
      .defaultAdvisors(StructuredOutputValidationAdvisor.builder()
        .maxRepeatAttempts(5)
        .outputType(Recipe.class)
        .jsonMapper(JsonMapper.builder().build())
        .build())
      .build();
}

Here, we raise the retry limit to five and declare Recipe as the default output type. Additionally, we supply a custom JsonMapper instance that performs the validation and the deserialization tasks. Here, we simply configure one with the default settings, but we can customize as per requirements.

4.2. Server-Side Validation With useProviderStructuredOutput()

Alternatively, instead of validating the response ourselves, we can delegate the job to the model provider. Most modern providers such as OpenAI, Anthropic, Google, and Mistral accept a schema as part of the API request and guarantee that the response conforms to it.

We can use this capability through another method on the same lambda:

Recipe recipe = chatClient
  .prompt("Generate a recipe for a gluten-free breakfast.")
  .call()
  .entity(Recipe.class, spec -> spec.useProviderStructuredOutput());

With this enabled, Spring AI sends the schema to the provider as a dedicated API field instead of appending instructions to the user prompt.

However, before relying on this, we should confirm that both our model and our provider support it. We can even use it along with validateSchema() to have a more resilient setup.

5. Converting the Response Into a List

Sometimes we might want the model to return a collection of results instead of a single object:

List<Recipe> recipes = chatClient
  .prompt("Generate 3 recipes for vegetarian dishes.")
  .call()
  .entity(new ParameterizedTypeReference<List<Recipe>>() {});
assertThat(recipes)
  .hasSize(3)
  .allSatisfy(recipe -> assertThat(recipe)
    .hasNoNullFieldsOrProperties()
  );

Here, instead of passing a class to the entity() method, we pass a ParameterizedTypeReference instance. This wrapper preserves the generic type information about our Recipe record and allows Spring AI to generate a JSON schema accordingly.

Alternatively, when we only need a list of plain strings, we can pass a ListOutputConverter instance to the entity() method:

List<String> dishes = chatClient
  .prompt("List 5 popular vegetarian dishes.")
  .call()
  .entity(new ListOutputConverter());
assertThat(dishes)
  .hasSize(5)
  .allSatisfy(dish -> assertThat(dish)
    .isNotBlank()
  );

In this lightweight option, the converter asks the model for a simple comma separated list instead of JSON and then splits the reply into a List of String values.

6. Converting the Response Into a Map

In scenarios where we don’t know the shape of the response in advance, we can pass a MapOutputConverter instance to the entity() method:

Map<String, Object> nutritionFacts = chatClient
  .prompt("Provide the nutrition facts per serving for a vegetarian lasagna.")
  .call()
  .entity(new MapOutputConverter());
assertThat(nutritionFacts)
  .isNotEmpty()
  .allSatisfy((nutrient, value) -> {
    assertThat(nutrient).isNotBlank();
    assertThat(value).isNotNull();
  });

Here, we receive a Map with String keys and Object values. The converter instructs the model to reply with a JSON object. In the absence of a fixed schema, the model decides the keys to return.

However, this flexibility costs us type safety, so we should still prefer a dedicated domain entity whenever we know the structure we expect.

7. Converting Responses Manually Using ChatModel

Until now, we’ve let the ChatClient bean handle everything for us. However, when we work directly with the lower level ChatModel abstraction, the entity() method isn’t available to us.

In such cases, we can use the converter classes ourselves:

BeanOutputConverter<Recipe> outputConverter = new BeanOutputConverter<>(Recipe.class);
String response = chatModel
  .call("Generate a recipe for a vegetarian lasagna. " + outputConverter.getFormat());
Recipe recipe = outputConverter.convert(response);
assertThat(recipe)
  .hasNoNullFieldsOrProperties();

Here, we create a BeanOutputConverter instance for our Recipe record. This is the same converter Spring AI uses internally for our domain entities.

Then, we append the output of its getFormat() method to our prompt, which contains the generated JSON schema and formatting instructions. Finally, we pass the model’s response to its convert() method to obtain our Recipe instance.

This manual approach isn’t limited to domain entities. We can follow the exact same process for lists and maps as well. The only thing we need to change is the converter instance we create.

8. Creating a Custom Output Converter

So far, we’ve relied on the converters that Spring AI exposes, which address most of our requirements. However, we can implement a converter ourselves simply by implementing the StructuredOutputConverter interface:

class YamlOutputConverter<T> implements StructuredOutputConverter<T> {
    private final YAMLMapper yamlMapper = YAMLMapper.builder().build();
    private final Class<T> targetType;
    YamlOutputConverter(Class<T> targetType) {
        this.targetType = targetType;
    }
    @Override
    public String getFormat() {
        String schema = new BeanOutputConverter<>(targetType).getJsonSchema();
        return """
          Return a YAML response that matches this JSON schema: %s
          Do not include any explanations or markdown code fences.
          """.formatted(schema);
    }
    @Override
    public T convert(String source) {
        return yamlMapper.readValue(source, targetType);
    }
}

Here, we create a converter to work with YAML responses.

We reuse BeanOutputConverter to generate a JSON schema for the target type and write the instructions to append to the user prompt in the getFormat() method. Then, in convert(), we deserialize the model’s response into our target type using YAMLMapper.

Now, let’s verify that our converter deserializes a response correctly:

String yamlResponse = """
name: "Mediterranean Veggie Salad"
cuisine: "Mediterranean"
difficulty: "EASY"
prepTimeMinutes: 15
ingredients:
  - name: "Cucumber"
    quantity: "1 medium"
  - name: "Cherry tomatoes"
    quantity: "1 cup"
  - name: "Extra virgin olive oil"
    quantity: "2 tbsp"
steps:
  - "Step 1: Chop the cucumber and halve the cherry tomatoes."
  - "Step 2: Drizzle with olive oil and toss everything together."
""";
Recipe recipe = new YamlOutputConverter<>(Recipe.class)
  .convert(yamlResponse);
assertThat(recipe)
  .hasNoNullFieldsOrProperties();

Here, we pass a sample model response to the convert() method of our converter and confirm that the Recipe record gets populated.

To use it against a live model, we can simply pass an instance of YamlOutputConverter to the entity() method.

9. Conclusion

In this article, we’ve explored the structured output support in Spring AI.

We walked through converting a chat model’s response into a custom domain entity, a list, and a map. Additionally, we discussed the self-correcting features that help us recover when a model returns a response that doesn’t match our schema. Finally, we explored implementing a custom converter.

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

The post A Guide to Structured Output in Spring AI first appeared on Baeldung.

       

1. Overview

While unit and integration tests help developers verify that an application behaves as expected, they typically require programming knowledge to write and maintain. Acceptance tests, on the other hand, allow testers to verify an application’s behavior against its requirements without writing test code.

FitNesse is a popular acceptance testing framework for Java applications.

In this tutorial, we’ll see how to use FitNesse to write an acceptance test for a simple banking application.

2. Understanding the FitNesse Framework

FitNesse is an acceptance testing framework that can be used with Java applications. It provides a web-based wiki interface where we can create, edit, and run acceptance tests without writing them in a traditional programming language. FitNesse uses its own wiki-style syntax rather than standard Markdown.

Furthermore, it supports two test systems: Fit and Slim. Slim is a commonly used option in modern FitNesse tests. With Slim, FitNesse communicates with fixture code through the Slim protocol, allowing our Java code to be invoked as part of an acceptance test.

To use FitNesse, we can download its executable JAR and run it as a Java application. Alternatively, we can add FitNesse as a test dependency to a Maven or Gradle project when we want to manage it as part of the project’s build configuration.

3. Maven Dependency

Moving on, let’s add the fitnesse dependency to our pom.xml:

<dependency>
    <groupId>org.fitnesse</groupId>
    <artifactId>fitnesse</artifactId>
    <version>20260313</version>
    <scope>provided</scope>
</dependency>

The fitnesse dependency includes the FitNesse application and its embedded web server. Once we start FitNesse, it exposes a web interface that we can access from a browser to create and run acceptance tests.

4. Example Project

To demonstrate how it works, let’s create a simple banking application.

4.1. BankAccount Class

First, let’s create a class named BankAccount:

public class BankAccount {
    private double balance;
    public BankAccount(double initialBalance) {
        this.balance = initialBalance;
    }
    public void deposit(double amount) {
        balance += amount;
    }
    public void withdraw(double amount) {
        balance -= amount;
    }
    public double getBalance() {
        return balance;
    }
}

In the class above, we initialize the account with a balance provided through the constructor. Then, we define methods for depositing money, withdrawing money, and retrieving the current balance. For simplicity, we used the double type to represent monetary value.

4.2. BankAccountFixture Class

Next, let’s create a fixture class that exposes the banking operations to FitNesse:

public class BankAccountFixture {
    private BankAccount account;
    private double depositAmount;
    private double withdrawAmount;
    public void setInitialBalance(double balance) {
        account = new BankAccount(balance);
    }
    public void setDeposit(double amount) {   
        this.depositAmount = amount;
    }
    public void setWithdraw(double amount) {
        this.withdrawAmount = amount;
    }
    public void execute() {          
        if (depositAmount > 0) {
            account.deposit(depositAmount);
        }
        if (withdrawAmount > 0) {
            account.withdraw(withdrawAmount);
        }
    }
    public double balance() {
        return account.getBalance();
    }
}

The class above acts as a bridge between FitNesse and our BankAccount class. It exposes methods that FitNesse can invoke as part of an acceptance test.

The setInitialBalance(), setDeposit(), and setWithdraw() methods configure the test data, while execute() performs the requested operations on the account. Finally, the balance() method returns the resulting balance.

These operations represent the behavior that we want to verify through our acceptance tests.

5. Writing an Acceptance Test

To begin, let’s create a launcher class with a main() method to start the FitNesse server:

public class FitNesseLauncher {
    public static void main(String[] args) throws Exception {
        FitNesseMain.main(new String[] { "-p", "8080" });
    }
}

Next, let’s run the main() method and open the landing page by visiting it in our browser:

Here’s the default FitNesse landing page. Since we don’t need the default content for our example, let’s edit the page by clicking Edit and create our acceptance test:

Here, we delete the original content of the page and add our test. First, we configure FitNesse to use the Slim test system. Next, we add the directory containing our compiled Java classes to the FitNesse classpath. Then, we import the package containing our fixture.

Finally, we define the acceptance test using FitNesse’s wiki table syntax.

After clicking the Save button, here’s the new page:

The saved page now displays our acceptance test. However, the Test button isn’t enabled yet. Let’s configure the page properties to enable test execution.

To do this, let’s click on Tools and select Properties:

The page properties have different options. Under the Page type, let’s select Test and click the Save Properties button. After saving the properties, the Test button becomes available on the test page.

Next, let’s click Test to execute the acceptance test:

The test results show that all five assertions passed successfully, with 0 wrong assertions, 0 ignored assertions, and 0 exceptions. The resulting balances also match the expected values in each test case.

6. Conclusion

In this lesson, we learned how to use FitNesse to write and execute acceptance tests for a Java application. Also, we built a simple banking application and created a Slim fixture that allowed FitNesse to interact with the application’s business logic.

Additionally, we saw how to configure and start the FitNesse server, configure FitNesse to use the Slim test system, and add compiled Java classes to the FitNesse classpath.

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

The post Introduction to FitNesse – An Acceptance Testing Framework first appeared on Baeldung.

       

1. Introduction

We use clever engineering to deploy complex machine learning models into production. While model research, training, and fine-tuning are predominantly performed in Python with frameworks such as PyTorch or TensorFlow, enterprise backends are often built in Java. Hence, we need a robust, scalable serving infrastructure to bridge this gap.

NVIDIA’s Triton Inference Server is an open-source model serving software that standardizes model deployment and execution. It provides a unified architecture capable of hosting models trained in almost any framework, such as ONNX, TensorFlow, PyTorch, and NVIDIA’s highly optimized TensorRT. Triton provides us with dynamic batching, concurrent model execution, and memory management while exposing a clean API for client applications.

In this tutorial, we’ll learn to interact with Triton Inference Server using Java to demonstrate object detection on images. We begin by reviewing the available APIs, then set up a local Triton instance using Docker, and finally write a concise Java client to execute a pre-trained YOLO model.

2. Overview of the Java API

We have two primary pathways for integrating Triton with Java applications.

2.1. The In-Process Java API

The In-Process Java API utilizes Java Native Interface (JNI) bindings to communicate directly with the underlying libtritonserver C library. Here, we bypass network protocols to embed the Triton server instance directly within the JVM process. We use this approach for low-latency edge deployments or network-starved environments.

Some of the important classes in this API are:

• TritonServer that represents the embedded server instance.
• TritonModel that represents a loaded model ready for inference.
• TritonRequest and TritonResponse that help us pass tensors back and forth in memory.

2.2. The Java Client API (gRPC/HTTP)

For most enterprise microservice architectures, we have models hosted on centralized CPU or GPU clusters. In such cases, we use the Java Client API via gRPC to access the models. Under the hood, Triton exposes a robust protobuf definition that Java applications can compile into strongly-typed stubs.

The key classes of gRPC API are:

• ManagedChannel that represents the underlying gRPC connection pool to the Triton server.
• InferenceServerBlockingStub that holds the synchronous client stub generated from Triton’s protobuf definitions.
• ModelInferRequest that encapsulates our input tensors, shapes, and data types.
• ModelInferResponse that gives the output containing the computed predictions.
• InferTensorContents to safely pack raw primitive types (like floats or integers) into byte streams.

2.3. Official Repository

For more advanced use, NVIDIA provides an official repository containing utility wrappers under client/src/java. It offers a cleaner TritonClient class that abstracts away the boilerplate protobuf generation and supports asynchronous inference and shared-memory execution.  Apart from this, some of the other advanced Triton features include:

• Asynchronous Inference: Using gRPC’s asynchronous stubs to handle high-throughput, non-blocking requests.
• Shared Memory: Allowing Triton and the Java client to read/write from the same system memory (or CUDA memory) space, eliminating the serialization and network overhead of gRPC.
• String Tensors: Passing text data to NLP models like BERT or LLaMA.

In this article, we’ll focus on building the raw gRPC Java Client API, as it’s the most common integration pattern for custom enterprise environments.

3. Local Setup With Docker

We’ll show standard object detection using the YOLO pretrained model running the Triton Inference Server. To run our example locally, we’ll use Docker Desktop to run an active instance of Triton Inference Server.

3.1. Prerequisites

Here are the prerequisites to run this setup on a local CPU-based machine:

• Docker Desktop.
• Java 11 or higher.
• Maven for dependency management.
• Python 3.10 and above.

3.2. Complete Project Structure

Here’s the complete directory structure for this project:

triton-java-yolo/
├── python/
│   ├── export_model.py              # It exports YOLO to ONNX 
│   └── requirements.txt             # Python dependencies (torch, ultralytics, onnx)
│
├── model_repository/                # It's a directory mounted into Docker Triton
│   └── yolo_onnx/
│       ├── 1/
│       │   └── model.onnx           # Compiled ONNX CPU runtime engine file
│       └── config.pbtxt             # Triton model configuration
│
├── src/
│   ├── main/
│   │   ├── proto/                   # Triton gRPC Protobuf definitions
│   │   │   ├── grpc_service.proto
│   │   │   └── model_config.proto
│   │   ├── java/
│   │   │   └── com/baeldung/triton/
│   │   │       ├── client/
│   │   │       │   └── TritonClientManager.java   
│   │   │       ├── yolo/
│   │   │       │   ├── ImagePreprocessor.java    
│   │   │       │   ├── YoloPostprocessor.java     
│   │   │       │   └── YoloInferenceRunner.java   
│   │   │       └── App.java                       
│   │   └── resources/
│   │       └── sample.jpeg           # Sample input image for object detection
│   └── test/
│       └── java/
│           └── com/baeldung/triton/
│               └── TritonInferenceLiveTest.java
│
├── pom.xml                          # Maven build file with gRPC & Protobuf plugins

3.3. Building the Model

First, we create the file export_model.py:

from ultralytics import YOLO
model = YOLO("yolov8n.pt")
model.export(format="onnx", imgsz=640, dynamic=False)
print("Export complete: yolov8n.onnx generated.")

Then, we build our Python virtual environment and use it to run the file export_model.py:

python export_model.py

This’ll download the pretrained model and then generate the ONNX runtime yolov8n.onnx in our working directory:

Downloading https://github.com/ultralytics/assets/releases/download/v8.4.0/yolovDownloading https://github.com/ultralytics/assets/releases/download/v8.4.0/yolov8n.pt to 'yolov8n.pt': 100% ━━━━━━━━━━━━ 6.2MB 42.1MB/s 0.1s
Ultralytics 8.4.34 🚀 Python-3.12.5 torch-2.2.2 CPU (Intel Core i9-9880H 2.30GHz)
YOLOv8n summary (fused): 72 layers, 3,151,904 parameters, 0 gradients, 8.7 GFLOPs
PyTorch: starting from 'yolov8n.pt' with input shape (1, 3, 640, 640) BCHW and output shape(s) (1, 84, 8400) (6.2 MB)
ONNX: starting export with onnx 1.22.0 opset 17...

3.4. Creating the Model Repository

Triton loads models from a strictly formatted directory structure known as the model repository. So, we’ll create the model_repository directory structure and  move and rename the ONNX file:

cp yolov8n.onnx ../model_repository/yolo_onnx/1/model.onnx

Thereafter, we’ll update the file config.pbtxt:

name: "yolo_onnx"
backend: "onnxruntime"
max_batch_size: 0
input [
  {
    name: "images"
    data_type: TYPE_FP32
    dims: [ 1, 3, 640, 640 ]
  }
]
output [
  {
    name: "output0"
    data_type: TYPE_FP32
    dims: [ 1, 84, 8400 ]
  }
]

 3.5. Run Server

With the repository prepared, let’s launch Triton Inference Server using the Docker container and mount our model_repository directory:

docker run --platform linux/amd64 --rm \ -p 8000:8000 -p 8001:8001 -p 8002:8002 \ -v /absolute/path/to/model_repository:/models \ nvcr.io/nvidia/tritonserver:23.10-py3 \ tritonserver --model-repository=/models

Here, we use Port 8000 for HTTP REST requests, port 8001 for the gRPC endpoint in our Java application, and port 8002 for Prometheus metrics.

We can verify the container by looking at the logs:

=============================
== Triton Inference Server ==
=============================
NVIDIA Release 23.10 (build 72127154)
Triton Server Version 2.39.0
Copyright (c) 2018-2023, NVIDIA CORPORATION & AFFILIATES.  All rights reserved.
I0822 07:34:40.100142 1 server.cc:619] 
+-------------+-----------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Backend     | Path                                                            | Config                                                                                                                                                        |
+-------------+-----------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
| onnxruntime | /opt/tritonserver/backends/onnxruntime/libtriton_onnxruntime.so | {"cmdline":{"auto-complete-config":"true","backend-directory":"/opt/tritonserver/backends","min-compute-capability":"6.000000","default-max-batch-size":"4"}} |
+-------------+-----------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
I0822 07:34:40.100196 1 server.cc:662] 
+-----------+---------+--------+
| Model     | Version | Status |
+-----------+---------+--------+
| yolo_onnx | 1       | READY  |
+-----------+---------+--------+

3.6. Configure Protobufs

To run our Java client, we need to set up the gRPC proto and the Maven dependencies. First, we place the official Triton proto files (grpc_service.proto and model_config.proto from the Triton Server repo) inside src/main/proto/:

curl -L https://raw.githubusercontent.com/triton-inference-server/common/main/protobuf/grpc_service.proto -o src/main/proto/grpc_service.proto
curl -L https://raw.githubusercontent.com/triton-inference-server/common/main/protobuf/model_config.proto -o src/main/proto/model_config.proto

4. Java Client

Next, we build our Java application.

4.1. Maven Dependencies

First, we need to declare our Maven dependencies for this project. For gRPC, we’ll use the core libraries: grpc-netty-shaded, grpc-protobuf, and grpc-stub, alongside javax.annotation-api. To compile the .proto files into Java classes automatically, we choose the os-maven-plugin and the protobuf-maven-plugin.

Here is our dependencies:

<dependencies>
    <!-- gRPC & Protobuf Dependencies -->
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty-shaded</artifactId>
        <version>${grpc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-protobuf</artifactId>
        <version>${grpc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-stub</artifactId>
        <version>${grpc.version}</version>
    </dependency>
    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>

Next is our list of plugins:

<plugins>
    <!-- Compiles the .proto files in src/main/proto into Java classes -->
    <plugin>
        <groupId>org.xolstice.maven.plugins</groupId>
        <artifactId>protobuf-maven-plugin</artifactId>
        <version>0.6.1</version>
        <configuration>
            <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
            <pluginId>grpc-java</pluginId>
            <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>compile</goal>
                    <goal>compile-custom</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

4.2. Establishing the Connection

We initiate communication by creating a ManagedChannel and instantiating a blocking stub:

ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 8001)
  .usePlaintext() 
  .build();
GRPCInferenceServiceBlockingStub blockingStub = GRPCInferenceServiceGrpc.newBlockingStub(channel);

4.3. Verifying Server Health

It’s a best practice to query the server’s health status to ensure the model has been loaded successfully, so that we are good to send heavy inference requests:

public boolean isServerLive() {
    try {
        ServerLiveRequest request = ServerLiveRequest.newBuilder().build();
        ServerLiveResponse response = blockingStub.serverLive(request);
        return response.getLive();
    } catch (Exception e) {
        return false;
    }
}

4.4. Preparing the Input Tensor in Java

Here is the preprocessing logic using a standard BufferedImage:

InputStream is = ImagePreprocessor.class.getClassLoader().getResourceAsStream(resourcePath);
BufferedImage originalImage = ImageIO.read(is);
BufferedImage resizedImage = new BufferedImage(targetWidth, targetHeight, BufferedImage.TYPE_INT_RGB);
Graphics2D g = resizedImage.createGraphics();
g.drawImage(originalImage.getScaledInstance(targetWidth, targetHeight, Image.SCALE_SMOOTH), 0, 0, null);
g.dispose();

Before sending an image to the YOLOv8 model, we preprocess it to match the exact input shape and format as per the model configuration. Standard computer vision preprocessing involves resizing, normalizing, and reordering the color channels. YOLOv8 expects an input tensor of shape [1, 3, 640, 640]. This corresponds to a batch size of 1, 3 color channels (RGB), and a resolution of 640×640. Furthermore, the data must be in planar format (NCHW), in which we store all red pixels first, followed sequentially by all green and blue pixels. Finally, we extract and normalize the pixels into a float array tensorData:

int totalPixels = targetWidth * targetHeight;
float[] tensorData = new float[3 * totalPixels];
int rOffset = 0, gOffset = totalPixels, bOffset = 2 * totalPixels;
for (int y = 0; y < targetHeight; y++) {
    for (int x = 0; x < targetWidth; x++) { 
        int rgb = resizedImage.getRGB(x, y); 
        int r = (rgb >> 16) & 0xFF;
        int gVal = (rgb >> 8) & 0xFF;
        int b = rgb & 0xFF;
        int index = y * targetWidth + x;
        tensorData[rOffset + index] = r / 255.0f;
        tensorData[gOffset + index] = gVal / 255.0f;
        tensorData[bOffset + index] = b / 255.0f;
    }
}

4.5. Executing the Inference

With our input tensor ready, we now construct our ModelInferRequest.

The protobuf definitions suggest that output data can be extracted using outputTensor.getContents().getFp32ContentsList(), Triton optimizes performance by leaving this list empty for output responses, avoiding the massive performance penalty of deserializing hundreds of thousands of floats. Instead, Triton packs the underlying C++ memory buffer into the raw_output_contents field as a ByteString. We extract these bytes and wrap them in a Java ByteBuffer using Little Endian byte order to read the floats manually:

ModelInferRequest request = ModelInferRequest.newBuilder()
  .setModelName("yolo_onnx")
  .setModelVersion("1")
  .addInputs(inputTensor)
  .build();
ModelInferResponse response = blockingStub.modelInfer(request);
ByteString rawData = response.getRawOutputContents(0);
ByteBuffer buffer = rawData.asReadOnlyByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
List resultList = new ArrayList<>(buffer.capacity() / 4);
while (buffer.hasRemaining()) {
    resultList.add(buffer.getFloat());
}

4.6. Non-Maximal Suppression

YOLOv8 returns a massive matrix of shape [1, C, N] where C=84 (COCO dataset classes) and N>8000 (different anchor boxes across the image). So, it means that when an object is clearly visible, multiple overlapping anchor boxes will report a high-confidence detection for the same object.

To prevent our application from reporting multiple bounding boxes for a single object, we apply Non-Maximum Suppression (NMS). NMS isolates the highest-confidence bounding box for an object and suppresses (discards) any other boxes that overlap it significantly. We determine overlap using Intersection over Union (IoU). If a lower-confidence box overlaps the highest-confidence box by more than our threshold (e.g., 50%), it’s treated as a duplicate and removed:

if (current.classId == next.classId) {
    if (calculateIoU(current, next) > 0.5f) {
        suppressed[j] = true;
    }
}

4.7. Final Run

Now, we tie all our components together in the main application class. We begin by exporting our YOLO model. Then we preprocess our sample cat image. After that, we run the Inference over gRPC and finally post-process and print the detection:

mvn clean compile  
mvn exec:java -Dexec.mainClass="com.baeldung.triton.App"

It yields a clean, optimized output, accurately identifying objects in the image without duplicate bounding boxes:

Connecting to Triton Inference Server at localhost:8001
Triton Server is live and ready.
Building inference request for model: yolo_onnx
Sending inference request to Triton...
Received 705600 data points. Parsing bounding boxes...
Raw boxes found before NMS: 8
Detected [cat] (Confidence: 83.7%) at Box [xMin=2.0, yMin=53.2]
Final valid objects detected: 1

5. Testing

We need to start the Triton Inference Server Docker container and ensure it is running on localhost:8001 with our yolo_onnx model loaded to run the Live Inference test.

In our Live Inference test, we first preprocess our sample cat image. Then carry on the inference with the YOLO model, which natively outputs a matrix of [1, 84, 8400]. Moving further, we flatten it to 705,600 elements and then run the post-processor so the test logs print the NMS cat detection:

public void givenValidImage_whenRunningInference_thenReturnsDetections() throws Exception {
    float[] inputTensor = ImagePreprocessor.preprocessFromResources("sample.jpeg", 640, 640);
    YoloInferenceRunner runner = new YoloInferenceRunner(clientManager.getStub(), "yolo_onnx");
    List<Float> outputs = runner.runInference(inputTensor);
    assertFalse(outputs.isEmpty(), "Inference output should not be empty");
    
    assertEquals(705600, outputs.size(), 
      "Output tensor should contain exactly 705,600 float elements");
    YoloPostprocessor.parseAndPrint(outputs);
}

6. Conclusion

In this article, we’ve studied the Triton Inference Server and its integration with Java.

In a nutshell, we explored how Triton Inference Server provides a powerful bridge between the Python-dominated ML ecosystem and Java microservices. By using Docker, we set up a local testing environment, constructed the necessary protobuf-based gRPC requests, and successfully executed an object detection pass using an ONNX CPU runtime engine.

As ML models grow in size and complexity, utilizing dedicated inference servers like Triton ensures our Java applications remain responsive, scalable, and easy to maintain.

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

The post Introduction to Triton Java API first appeared on Baeldung.

       

1. Introduction

Spring Boot simplifies Java application development through auto-configuration, dependency management, embedded servers, and production-ready features. It builds on the Spring Framework, which provides features such as dependency injection, Spring MVC, and application configuration. As the Spring Framework evolves, developers may need to adopt newer framework versions to access security improvements, bug fixes, performance enhancements, and compatibility options for newer Java versions. However, upgrading requires more than changing a version number. Spring Boot manages several related dependencies, so developers must maintain compatibility between them.

In this tutorial, we’ll explore how to upgrade the Spring Framework version in a Spring Boot application safely and systematically. First, we’ll examine how Spring Boot manages Spring Framework dependencies and how to identify the versions used by an application. Then, we’ll follow the recommended approach of upgrading Spring Boot to obtain the required Spring Framework version. Also, we’ll use the Maven dependency tree and effective POM to investigate unexpected dependency versions and identify dependency-management conflicts. Finally, we’ll review compatibility requirements, migration changes, and best practices to help maintain application stability after the upgrade.

2. Spring Framework Version Management in Spring Boot

Spring Boot manages dependency versions for each release. This dependency management includes the Spring Framework modules used by the application. Therefore, applications can declare Spring dependencies without specifying their versions individually.

To begin, a Maven project can use the Spring Boot parent:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>YOUR_BOOT_VERSION</version>
    <relativePath/>
</parent>

The Spring Boot parent provides access to the Spring Boot dependency management, including the spring-boot-dependencies POM. This POM defines compatible versions for Spring Framework modules and other dependencies.

Therefore, a dependency such as spring-web can be declared without specifying its version explicitly:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
</dependency>

Maven then obtains the version from the Spring Boot dependency management. This approach keeps related Spring Framework modules aligned. It also avoids defining individual versions throughout the application.

The same mechanism applies when Spring Framework modules are included through a Spring Boot starter:

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

The starter brings in the required Spring dependencies, while Spring Boot supplies their managed versions. As a result, the application uses a consistent set of Spring Framework modules without defining each version manually.

Therefore, upgrading Spring Framework in a Spring Boot application requires understanding this dependency-management relationship. Since Spring Boot manages the framework version for each release, the recommended approach is to upgrade Spring Boot to a release that provides the required Spring Framework version.

3. Checking the Current Spring Framework Version

Before upgrading the Spring Framework, we should first identify the version currently used by the application. The Maven dependency tree can show the versions resolved during the build.

We can check them with the dependency:tree subcommand of mvn:

mvn dependency:tree -Dincludes=org.springframework

The output may contain several entries:

org.springframework:spring-core:jar:5.2.8.RELEASE
org.springframework:spring-web:jar:5.2.8.RELEASE 

Each entry identifies a Spring Framework module and the version Maven resolves for it. However, the version shown in the dependency tree may not come directly from the project pom.xml. Spring Boot can provide the version through its dependency management. Other imported BOMs or dependency-management configurations can also affect the final resolved version.

Therefore, checking the dependency tree gives us a clear starting point. Once we identify the current version, we can determine which Spring Boot release provides the required newer version. The next section explains this upgrade process.

4. Upgrading the Current Spring Framework Version

Once we know the current Spring Framework version and how it’s managed, the next step is to select a Spring Boot release that manages the required version.

Spring Boot manages a compatible set of dependency versions for each release. Therefore, moving to a newer Boot release updates the managed Spring Framework version along with its related dependencies.

4.1. Upgrade the Spring Boot Version

To upgrade Spring Boot, we only need to change the Boot version declared in the parent POM:

<version>NEW_BOOT_VERSION</version>

After this change, Maven uses the dependency-management configuration associated with the new Spring Boot release. Consequently, the application receives the Spring Framework version managed by that release. We don’t need to specify versions for individual Spring Framework modules because Spring Boot continues to manage them.

4.2. Verify the Resolved Version

After completing the upgrade, run the dependency tree again. Check the Spring Framework modules and their resolved versions. They should correspond to the dependency versions managed by the selected Spring Boot release.

This verification is important because changing the Boot version doesn’t guarantee that every dependency configuration in a complex project behaves as expected. Imported BOMs or internal libraries can influence the resolved version. If Maven resolves an unexpected Spring Framework version, we should inspect the effective project POM and dependency tree.

To that end, we continue with an explanation of how to trace such dependency-management issues.

5. Investigating Unexpected Dependency Versions

After upgrading Spring Boot, Maven should resolve the Spring Framework version managed by the selected Boot release. Complex projects can contain additional dependency-management configurations that affect the final resolved version. For example, the application may import another BOM or define its own dependency-management entries that override versions managed by Spring Boot. Dependencies may also introduce transitive Spring modules, which can influence dependency resolution.

The effective POM helps trace the source of an unexpected dependency version as it combines the inherited and imported dependency configuration.

Let’s begin by generating it:

mvn help:effective-pom

Then, we search for entries:

spring-boot-dependencies
spring-framework-bom

By examining the effective POM together with the dependency tree, we can determine which dependency-management configuration controls the resolved Spring Framework version and investigate possible overrides or conflicts.

6. Verifying the Upgrade

Upgrading Spring Boot changes the managed Spring Framework version and may affect application behavior. Therefore, the upgrade should be validated beyond dependency resolution.

6.1. Review Migration Changes

Newer Spring Framework releases may introduce API changes, deprecate existing features, or remove APIs that were previously available. Configuration behavior can also change between framework versions. Therefore, we should review the relevant migration documentation and update application code or configuration where necessary.

6.2. Third-Party Dependencies

The application may also depend on libraries that integrate with Spring Framework. These libraries may have their own compatibility requirements. After upgrading, we should test components such as security, database access, web endpoints, and other Spring-based integrations to ensure that they support the upgraded environment.

7. Best Practices

When upgrading the Spring Framework in a Spring Boot application, we should follow a few practices to keep the upgrade manageable and maintainable:

• Prefer upgrading Spring Boot: We should choose a Spring Boot release that manages the required Spring Framework version. This keeps related dependencies aligned.
• Avoid unnecessary overrides: We shouldn’t manually specify a Spring Framework version when the selected Spring Boot release already provides the required version.
• Keep Spring Framework modules aligned: We shouldn’t specify different versions for individual Spring Framework modules, as this can introduce compatibility problems.

By sticking to the suggestions above, we can mitigate many of the issues that still persist despite the automatic dependency management.

8. Conclusion

In this article, we explored how Spring Boot manages Spring Framework versions through its dependency-management system. Since Spring Boot provides compatible versions of Spring Framework modules, upgrading the Framework usually starts with selecting a Spring Boot release that manages the required version. This approach keeps the Framework modules aligned and avoids unnecessary dependency overrides.

Also, we used Maven to check the resolved Framework version and investigate unexpected dependency versions through the effective POM and dependency tree. Finally, we reviewed release changes, third-party dependencies, and application behavior after the upgrade. Together, these steps provide a structured way to upgrade the Spring Framework while keeping dependency resolution consistent and the application compatible.

The post Upgrading Spring Framework Version in Spring Boot first appeared on Baeldung.

       

1. Overview

Solon is an enterprise Java framework built independently of Spring.

In this tutorial, we’ll introduce Solon theoretically and in practice. First, we’ll start with a greeting endpoint and extend it into a REST API that stores tasks in an H2 database.

In particular, we’ll use Solon 4.1.0, Java 21, and Maven 3.9.16, with MyBatis-Flex 1.11.8 for persistence. Along the way, we’ll compare configuration, dependency injection, and HTTP handling with familiar Spring Boot concepts, then test the API through real HTTP requests.

2. What Is Solon

Solon separates its core application services from optional integrations. This gives us control over which features the application loads.

2.1. Core Principles and Architecture

The project emphasizes restrained design, efficiency, openness, and an extensible ecosystem. Its core provides dependency injection, aspect-oriented programming, and request routing. Plugins add capabilities such as database access and JSON serialization.

Solon doesn’t require a Servlet container or a Java EE application server. HTTP adapters connect its request abstractions to a server. The example here uses Smart-HTTP through the solon-web bundle, although Servlet adapters are also available.

2.2. The Solon Ecosystem

The main solon project is complemented by solon-cloud for distributed services and solon-ai for AI applications. There are also other related projects:

• solon-flow for workflows
• solon-expression for expression evaluation
• and solon-admin for application administration

The solon-java17 and solon-java25 projects host implementations targeting newer Java baselines. The wider plugin ecosystem includes MyBatis-Flex, JPA, Redis, Sa-Token, Nacos, and gateway integrations.

2.3. When Solon Is a Good Fit

Solon’s modular design makes it worth evaluating for microservices, serverless functions, and applications with constrained resources, including embedded or IoT workloads. Its AI modules also offer a starting point for applications that call language models.

These are candidates for evaluation, rather than performance guarantees. For a service with demanding concurrency requirements, we need to benchmark the actual workload with the required plugins.

Spring Boot may remain the more practical choice when a team already relies on its integrations and operating procedures. Adopting Solon means learning a different set of annotations, configuration conventions, and extension points.

3. First Application

Let’s create a Maven project with the standard src/main/java directory. Further, we place App in com.baeldung.solon and the controllers in its web subpackage.

3.1. Prerequisites

The test environment uses OpenJDK 21 and Maven 3.9.16. The POM excerpt we show assumes the Baeldung repository layout and its shared parent-modules POM.

So, let’s import solon-parent 4.1.0 as a BOM and add solon-web to pom.xml:

<parent>
    <groupId>com.baeldung</groupId>
    <artifactId>parent-modules</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</parent>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.noear</groupId>
            <artifactId>solon-parent</artifactId>
            <version>4.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.noear</groupId>
        <artifactId>solon-web</artifactId>
    </dependency>
</dependencies>
<properties>
    <java.version>21</java.version>
    <maven.compiler.parameters>true</maven.compiler.parameters>
</properties>

The BOM manages matching Solon dependency versions. The compiler retains method parameter names so Solon can bind request parameters by name. The web bundle brings in solon-lib, solon-server-smarthttp, and solon-serialization-snack4, among other plugins.

Solon declares support for Java 8 through Java 26, which can also make it relevant to legacy applications. However, individual integrations can require newer Java versions. This project specifically targets Java 21.

3.2. Hello World

Let’s add an entry point that starts the application and discovers components in its package and subpackages:

public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args);
    }
}

Spring Boot commonly combines SpringApplication.run() with @SpringBootApplication. Here, Solon.start() initializes the container and available plugins without that annotation.

Next, let’s expose a greeting that accepts an optional query parameter:

@Controller
public class DemoController {
    @Get
    @Mapping("/hello")
    public String hello(@Param(defaultValue = "World") String name) {
        return "Hello, " + name + "!";
    }
}

@Mapping defines the path, while @Get restricts the HTTP method. @Param supplies a default when name is absent. In particular, these annotations come from org.noear.solon.annotation.

For this endpoint, Solon writes the returned string to the response body as plain text. A comparable Spring REST endpoint typically uses @RestController with @GetMapping.

3.3. Running the Application

To run the entry point from Maven, let’s configure exec-maven-plugin 3.6.4 under build/plugins:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.6.4</version>
    <configuration>
        <mainClass>com.baeldung.solon.App</mainClass>
    </configuration>
</plugin>

With the plugin in place, we can compile and start the application:

mvn compile exec:java

From another terminal, let’s call the endpoint:

curl 'http://localhost:8080/hello?name=Baeldung'

Thus, the response confirms that the query parameter reaches the controller:

Hello, Baeldung!

Calling /hello without the parameter returns Hello, World!.

4. RESTful API Example

The API we’re constructing can create, list, update, and delete tasks. Specifically, each task has a generated ID, a title, and a completion flag.

4.1. Dependencies

Let’s add the MyBatis-Flex Solon plugin 1.11.8, HikariCP 7.1.0, and H2 2.5.250 to the dependencies:

<dependency>
    <groupId>com.mybatis-flex</groupId>
    <artifactId>mybatis-flex-solon-plugin</artifactId>
    <version>1.11.8</version>
</dependency>
<dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
    <version>7.1.0</version>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.5.250</version>
    <scope>runtime</scope>
</dependency>

Next, we continue with the configuration.

4.2. Configuration Properties

Solon reads application settings from src/main/resources/app.yml. So, let’s name the application, choose its port, and configure a HikariCP connection pool and mapper discovery:

solon.app:
  name: task-api
  group: examples
server.port: 8080
solon.dataSources:
  tasks!:
    class: com.zaxxer.hikari.HikariDataSource
    jdbcUrl: jdbc:h2:mem:tasks
    username: sa
    password: ""
    maximumPoolSize: 4
mybatisFlex:
  mapperLocations:
    - com.baeldung.solon.persistence

The ! suffix registers the datasource by type as well as by the name tasks. Here, we use that name when injecting it. The mapperLocations list identifies the package containing the mapper interface.

Settings from later configuration layers override earlier values for the same key. The six-layer configuration model places application files at the lowest priority:

For example, a startup argument overrides the port in app.yml:

mvn compile exec:java -Dexec.args="--server.port=8081"

The cloud layer only applies when the relevant plugins are configured. While Spring Boot users are familiar with externalized configuration, Solon uses app.properties or app.yml instead of the Spring Boot application.properties or application.yml.

Critically, the H2 database lives in memory only. Its contents disappear when the application stops.

4.3. Architectural Layers

Let’s organize the code around three responsibilities:

• TaskController handles HTTP requests and responses
• TaskService validates titles and coordinates database operations
• TaskMapper performs persistence operations through MyBatis-Flex

The Solon @Component annotation registers the service as a managed bean. Spring provides additional role-specific annotations, such as @Service and @Repository. However, neither framework requires this layered organization.

In addition, we can connect the objects with @Inject, which fills a role similar to that of Spring @Autowired.

4.4. Presentation Layer

A record defines the fields accepted in a request body:

public record TaskRequest(String title, Boolean completed) {
}

Using Boolean enables the completion flag to be null. Conversely, creating a task always sets it to false. On the other hand, updating a task treats an absent or null flag as false.

Let’s register a controller under /tasks and inject the service. Its creation endpoint binds JSON with @Body:

@Controller
@Mapping("/tasks")
public class TaskController {
    @Inject
    private TaskService taskService;
    @Post
    @Mapping
    public Task create(@Body TaskRequest request, Context context) {
        Task task = taskService.create(request.title());
        context.status(201);
        context.headerSet("Location", "/tasks/" + task.getId());
        return task;
    }
}

Returning a Task lets the Snack4 plugin serialize the response as JSON. Furthermore, the endpoint sets status 201 and a Location header pointing to the new resource.

Inside the same controller, the update method combines a path parameter with a JSON body:

@Put
@Mapping("/{id}")
public Task update(long id, @Body TaskRequest request) {
    return taskService.update(id, request.title(),
      Boolean.TRUE.equals(request.completed()));
}

Solon binds {id} to the parameter named id. The complete controller also provides several mappings:

• GET /tasks returns all tasks, ordered by ID
• GET /tasks/{id} returns one task
• DELETE /tasks/{id} deletes a task and returns 204 with an empty body

These are fairly standard endpoints, so the structure and framework remain the focus instead of the implementation.

4.5. Business Logic Layer

Let’s annotate TaskService with @Component. It receives a mapper and creates tasks within a transaction:

@Inject
TaskMapper taskMapper;
@Transaction
public Task create(String title) {
    Task task = new Task();
    task.setTitle(normalizeTitle(title));
    task.setCompleted(false);
    taskMapper.insert(task);
    return task;
}

Here, @Transaction comes from org.noear.solon.data.annotation. The persistence plugin integrates mapper operations with the Solon transaction management.

The normalizeTitle() helper strips surrounding whitespace and rejects blank titles or titles longer than 200 characters. Invalid input raises IllegalArgumentException.

Updates first load the existing task, preserving its ID. Missing tasks raise NoSuchElementException. Deletion checks the number of affected rows so deleting an unknown ID produces the same error.

The application ApiErrorFilter translates those exceptions into JSON responses with status 400 or 404. This keeps HTTP status handling out of the service.

4.6. Persistence Layer

The Task entity is a mutable POJO with standard getters and setters. In addition, its MyBatis-Flex mapping uses an automatically generated key:

@Table("tasks")
public class Task {
    @Id(keyType = KeyType.Auto)
    private Long id;
    private String title;
    private boolean completed;
    // getters and setters
}

MyBatis-Flex writes the generated ID back into the entity after insertion. Thus, the controller has the ID needed for the response and its Location header.

The mapper inherits the standard database operations:

public interface TaskMapper extends BaseMapper<Task> {
}

The plugin discovers this interface through the mybatisFlex.mapperLocations configuration and makes it available for injection. We don’t need to implement its insert, update, or delete methods.

4.7. Initializing the Database

Let’s save the table definition in src/main/resources/schema.sql:

CREATE TABLE IF NOT EXISTS tasks (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    title VARCHAR(200) NOT NULL,
    completed BOOLEAN NOT NULL DEFAULT FALSE
);

The DatabaseInitializer is another @Component. In this case, it receives the named datasource and executes a script in its @Init method:

@Inject("tasks")
private DataSource dataSource;
@Init
public void initialize() throws SQLException, IOException {
    String schema = ResourceUtil.getResourceAsString("schema.sql");
    try (Connection connection = dataSource.getConnection();
      Statement statement = connection.createStatement()) {
        statement.execute(schema);
    }
}

Solon invokes the initialization method after dependency injection. The schema is created explicitly by this component, and try-with-resources closes the JDBC resources afterward.

4.8. Trying the API

After restarting the completed application on port 8080, let’s create a task:

curl -i -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"Learn Solon"}'

On a fresh database, the response has status 201 Created, a Location: /tasks/1 header, and this JSON body:

{"id":1,"title":"Learn Solon","completed":false}

Using the returned ID, let’s read, update, and delete the task:

curl http://localhost:8080/tasks/1
curl -X PUT http://localhost:8080/tasks/1 \
  -H 'Content-Type: application/json' \
  -d '{"title":"Learn Solon REST APIs","completed":true}'
curl -i -X DELETE http://localhost:8080/tasks/1

The update returns the changed task. Deletion returns 204 No Content, and a subsequent read returns 404. A blank title produces 400 with a JSON error message.

4.9. API Testing

For automated tests, we add solon-test, which includes JUnit 5 in this Solon version:

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-test</artifactId>
    <scope>test</scope>
</dependency>

The example module uses JUnit 5.14.4 with Surefire 3.5.5 and inherits the test selection rules from the Baeldung shared parent POM.

Next, let’s enable the HTTP server and select the test environment:

@SolonTest(value = App.class, env = "test", enableHttp = true,
  delay = 0, debug = false)
public class TaskApiIntegrationTest {
    @Inject("${server.port}")
    private int port;
    @Inject
    private TaskService taskService;
}

Solon requires a public test class here. In the repository, app-test.yml selects a separate H2 database. The Maven integration profile reserves an available port and passes it as server.port.

The request() helper uses the JDK HttpClient to contact that port. This test therefore checks the actual HTTP response and the database state:

@Test
void givenBlankTitle_whenCreatingTask_thenReturnBadRequestWithoutPersisting() throws Exception {
    HttpResponse<String> response = request("POST", "/tasks", "{\"title\":\" \"}");
    assertEquals(400, response.statusCode());
    assertEquals("Title must not be blank",
      ONode.ofJson(response.body()).get("message").getString());
    assertTrue(taskService.findAll().isEmpty());
}

The integration suite also checks greetings, missing IDs, and a complete create-read-update-delete sequence. Let’s run unit tests and integration tests separately from the module directory:

mvn clean install -Pdefault
mvn clean install -Pintegration

Let’s see the integration report:

Tests run: 5, Failures: 0, Errors: 0, Skipped: 0

Thus, all tests pass without issues.

4.10. Transaction Rollback

Finally, let’s demonstrate @Rollback with a separate service-level test:

@Test
@Rollback
public void whenCreatingTaskWithinTransaction_thenReadUncommittedTask() {
    Task task = taskService.create("Temporary task");
    assertEquals("Temporary task", taskService.findById(task.getId()).getTitle());
}

The annotated method is public so the Solon proxy can intercept it. The @AfterEach hook checks that the database is empty before cleanup, verifying the rollback.

Notably, we don’t apply @Rollback to the test that exercises CRUD across multiple HTTP requests. When @Rollback is active, Solon installs an interceptor that rolls back the transaction of each HTTP request separately. A task created by one request is therefore unavailable to the next.

The HTTP workflow test therefore runs without @Rollback and uses explicit row cleanup before and after each test. Changes persist across requests within a test, while cleanup keeps tests isolated from one another.

5. Conclusion

In this article, we built and tested a Solon REST API with MyBatis-Flex and H2. Further, we saw how its annotations, configuration layers, and plugins supported request handling and persistence, including the difference between testing an HTTP workflow and verifying transaction rollback.

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

The post Introduction to Solon first appeared on Baeldung.

       

1. Spring and Java

>> The Arrival of Java 27! [inside.java]

Java 27 is here with a lot of goodies – post-quantum TLS, G1 as the default collector everywhere, compact object headers by default, and improvements across concurrency, JFR, and the Vector API.

Also worth reading:

• >> JDK 27 Security Enhancements [inside.java]
• >> Logpoints Walkthrough [jetbrains.com]
• >> Java 27 in IntelliJ IDEA [jetbrains.com]
• >> Java 21: the foundation for Quarkus 4 [quarkus.io]
• >> Interpreting Pangram [pocoo.org]
• >> Generating Java bytecode: Write yourself a compiler, Part V [nurkiewicz.com]
• >> P(doom) [pocoo.org]
• >> My Writing and GenAI [code-cop.org]
• >> Nail your narrative [martinfowler.com]
• >> Using multiple GitHub accounts on one machine [wimdeblauwe.com]

Webinars and presentations:

• >> Java 27 Launch Stream [inside.java]
• >> Java 27 Technically Within 2 Minutes [inside.java]
• >> Episode 69 “Declassifying Java 27” [IJN] [inside.java]
• >> Quarkus Insights #259: MCP Servers Without the Boilerplate — Introducing reShapr [quarkus.io]
• >> Spring Office Hours Podcast: S5E23 – Java 27 Release Party with Billy Korando [spring.io]
• >> A Bootiful Podcast: Netflix’s Paul Bakker [spring.io]

Time to upgrade:

• >> IntelliJ IDEA 2026.2.3 Is Out! [jetbrains.com]
• >> Quarkus 3.39.3 – Maintenance release [quarkus.io]
• >> A2A Jakarta 1.0.0.Final is released! [wildfly.org]
• >> Vert.x 4.5.34 [github.com/eclipse-vertx]
• >> Elasticsearch 9.5.4 and 9.4.7 [github.com/elastic]
• >> Zuul 4.1.7 and 4.1.4 [github.com/Netflix]
• >> Micronaut Core 5.2.2, 5.2.1, 5.1.15, 4.10.28, 3.10.12, and 5.2.0 [github.com/micronaut-projects]
• >> Helidon 4.5.5 and 3.2.21 [github.com/helidon-io]
• >> Apache Camel 4.22.1 [github.com/apache]
• >> Azul Payara Community 7.2026.9 [github.com/payara]

2. Pick of the Week

>> A faster way to convert a timestamp ➜ Hour, Min, Sec [benjoffe.com]

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

       

1. Overview

When working with large prompts, repeatedly sending the same context to the model can increase both latency and costs. This becomes especially noticeable when applications reuse large system instructions, documents, or conversation context across requests.

Prompt Caching in Spring AI with Anthropic addresses this by allowing frequently reused parts of a prompt to be cached and reused across requests, reducing the amount of work the model needs to process each time. This can improve response latency while lowering input-token costs.

In this tutorial, we’ll explain how prompt caching works, the limitations and requirements for different Claude models, and how to use it with Spring AI. We’ll also cover the main configuration options and practical considerations when applying caching in an application.

2. Dependencies

Let’s start by defining the minimum dependencies possible for demonstrating the Prompt Caching in Spring AI. We’ll only need spring-boot-starter-web and the spring-ai-starter-model-anthropic. The first is for the basic Spring Boot Application and auto-configuration. The latter contains the tools we’re exploring in this article, including Spring AI. The minimum version for Prompt Caching is 1.0.3, so we can go with:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.5.13</version>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-anthropic</artifactId>
    <version>2.0.1</version>
</dependency>

 3. Prompt Caching

Let’s start by understanding what Prompt Caching is. Prompt Caching allows Claude to reuse a previously processed prefix of a prompt instead of processing the same content from scratch on every request. This is particularly useful for large system instructions, tool definitions, documents, and other context that remains unchanged across requests.

The main benefit we get is reduced latency and input-token cost. Anthropic currently charges cache reads at 10% of the regular input-token price for most Claude models. While the initial cache write costs 25% more than the base input price for a 5-minute cache, the savings increase as the same prompt prefix is reused.

There are, however, some limitations to consider:

• the minimum cacheable prompt size depends on the model
• the cache uses a limited TTL
• we can define only up to four cache breakpoints
• changes we make to the cached prefix can invalidate the cache
• a cache entry is also only available after the first response begins, which matters when sending concurrent requests

Next, we need to understand the Prompt Caching Hierarchy for other concepts, like Strategies, to make sense. Prompt caching follows the hierarchy: tools → system → messages. Claude processes these sections in this order, and each level builds on the previous one.

Invalidation also follows this hierarchy. If we change the tools, this invalidates the tools cache and everything below it. If we change the system prompt, this leaves the tools cache intact but invalidates the system and message caches. When we change messages, only the message cache gets invalidated.

The idea is therefore simple: keep stable content as high in the hierarchy as possible and frequently changing content as low as possible. This allows the largest possible portion of the prompt to remain cached between requests.

4. Prompt Caching Strategies

The hierarchy and invalidation rules naturally lead to different caching strategies. The goal is to place cache breakpoints where they provide the most reuse while minimizing the amount of content that gets invalidated when something changes.

A cache breakpoint tells Anthropic where to create a cache entry. Each breakpoint caches the prompt content up to that point, following the request hierarchy of tools → system → messages. Anthropic currently allows a maximum of four cache breakpoints per request, so they should be placed deliberately rather than on every possible section.

Spring AI provides five Prompt Caching Strategies through AnthropicCacheStrategy:

The number and placement of breakpoints also affect invalidation. With a single breakpoint at the system message, for example, a change to the tools invalidates the whole cached prefix. With SYSTEM_AND_TOOLS, Spring AI places separate breakpoints after the tools and system message, allowing the tool cache to remain valid when only the system prompt changes.

Choosing the right strategy therefore depends on how stable each part of the request is. The more frequently a section changes, the more carefully its breakpoint should be separated from stable content.

5. Prompt Caching In Practice

Last, let’s put what we’ve learned so far into practice. First, we’ll apply the theory in a Spring Boot application, and then we’ll run some tests to see prompt caching in action.

5.1. Spring Boot Application with Prompt Caching

As we’ve seen before, we can use Spring properties to set up the model:

spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}
      chat:
        options:
          model: claude-sonnet-4-6
          max-tokens: 500
        cache-options:
          strategy: SYSTEM_ONLY

At this moment, claude-sonnet models before 3.5 are no longer available. We set 4-6 and max-tokens to 500 as a guardrail to control the cost, and we’ll use SYSTEM_ONLY as the strategy in our application. The minimum cacheable prompt for claude-sonnet-4-6 is 1024 tokens.

Then, all we need is a service using this model:

public class ChatWithPromptCachingService {
    private final ChatClient chatClient;
    // ... constructors, etc
    public ChatResponseWithMetadataDto chat(String userMessage, String systemPrompt) {
        ChatResponse response = chatClient
          .prompt()
          .system(systemPrompt)
          .user(userMessage)
          .call()
          .chatClientResponse()
          .chatResponse();
        if (response == null || response.getResult() == null) {
            throw new RuntimeException("Client response has no results");
        }
        return ChatResponseWithMetadataDto.fromChatResponse(response);
    }
}

The chat() method accepts a system prompt and a user message and requests our chat-client. Then, it returns the ChatResponseWithMetadataDto:

public record ChatResponseWithMetadataDto(
  String responseText,
  Integer promptTokens,
  Integer completionTokens,
  Long cacheReadInputTokens,
  Long cacheWriteInputTokens) {
    public static ChatResponseWithMetadataDto fromChatResponse(ChatResponse chatResponse) {
        // ... implementation of the mapper
    }
}

ChatResponseWithMetadataDto only holds the information we need: responseText, promptTokens, completionTokens, cacheReadInputTokens, and cacheWriteInputTokens.

5.2. Testing the Prompt Caching Application

To make sure that prompts are truly cached, let’s first have a test with strategy set to NONE and run the test:

@Test
void chat_whenPromptCachingDisabled_returnsResponse() {
    String chatMessage = "hello there";
    ChatResponseWithMetadataDto response = service.chat(chatMessage, PromptsUtils.LONG_SYSTEM_PROMPT);
    assertThat(response).isNotNull();
    assertThat(response.promptTokens()).isGreaterThan(1030);
    assertThat(response.cacheReadInputTokens()).isEqualTo(0);
    response = service.chat(chatMessage + " again", PromptsUtils.LONG_SYSTEM_PROMPT);
    assertThat(response).isNotNull();
    assertThat(response.promptTokens()).isGreaterThan(1030);
    assertThat(response.cacheReadInputTokens()).isEqualTo(0);
}

In this test, we request a dummy message and the default PromptsUtils.LONG_SYSTEM_PROMPT, which is just a bit longer than 1024 tokens. As expected, for caching strategy NONE, we see that the prompt tokens are a full 1030 tokens, and there is no cached token recorded.

Next, let’s try the same test with the default caching strategy of our application (SYSTEM_ONLY):

@Test
void chat_whenPromptCachingEnabled_returnsResponse() {
    String chatMessage = "hello there";
    UUID testId = UUID.randomUUID();
    ChatResponseWithMetadataDto response = service.chat(
      chatMessage,
      PromptsUtils.LONG_SYSTEM_PROMPT + "\nTEST_ID=" + testId);
    assertThat(response).isNotNull();
    assertThat(response.promptTokens()).isLessThan(50);
    assertThat(response.cacheWriteInputTokens()).isGreaterThan(1000);
    assertThat(response.cacheReadInputTokens()).isEqualTo(0);
    response = service.chat(chatMessage + " again", PromptsUtils.LONG_SYSTEM_PROMPT + "\nTEST_ID=" + testId);
    assertThat(response).isNotNull();
    assertThat(response.promptTokens()).isLessThan(50);
    assertThat(response.cacheWriteInputTokens()).isEqualTo(0);
    assertThat(response.cacheReadInputTokens()).isGreaterThan(1000);
}

Now we see Prompt Caching effects! In the first request, the response tells us that cacheWriteInputTokens is over 1000, which means it just wrote to the cache. Moreover, promptTokens is low, just the user message, and cacheReadInputTokens is 0 cause there was no cache hit.

In the second request, promptTokens is low, but this time cacheWriteInputTokens is 0 (no new tokens cached). CacheReadInputTokens is now over 1000, which shows there was a cache hit!

The prompt in this test also uses a TEST_ID to make sure no previous tests will affect the next execution. It’s a trick to use different caches between test executions.

6. Conclusion

In this article, we explained how Prompt Caching Support in Spring AI with Anthropic Claude works. We walked through how it works, configuration options, and the limitations. Then we saw the Prompt Caching Strategies. Finally, we used Spring AI to demonstrate it in practice.

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

The post Prompt Caching Support in Spring AI with Anthropic Claude first appeared on Baeldung.

       

1. Overview

Starting with version 9, Java places a strong emphasis on encapsulation. The major feature behind this is the Java Platform Module System (JPMS). It controls how our own packages are exposed and, at the same time, restricts access to Java’s internal classes. However, many libraries rely heavily on reflection to access private members. So we need ways to relax these restrictions in a controlled manner.

In this tutorial, we’ll learn how to avoid the InaccessibleObjectException when deserializing JSON with Gson. We’ll focus on modular projects and date handling.

2. Gson Status

Gson offers convenient tools for serializing objects to JSON and deserializing them back, and it relies on accessing private fields via reflection. With strong encapsulation in place, this no longer works seamlessly, either for our own objects or for Java’s internal classes. The latest Gson versions have made a small move towards public APIs, specifically for records and dates.

Gson is currently in maintenance mode. Therefore, we shouldn’t expect any new features, only bug fixes and security fixes.

3. Project Setup

Let’s examine the pom.xml we’ll use. We need Java 17 to demonstrate strong encapsulation and for its full support of records. Therefore, we set it in the properties section of pom.xml:

<maven.compiler.release>17</maven.compiler.release>

Next, let’s check the Gson version. We should use the latest one:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.14.0</version>
</dependency>

4. Gson and Java Modules

Let’s create a simple Java project named gson-module. We declare the gson.exception module in the module-info.java file:

module gson.exception {
    requires com.google.gson;
    requires org.slf4j;
    exports gson.exception;
}

With the requires statement, we state that our module needs Gson (and SLF4J for logging). Then, we make our own package gson.exception available to other modules with the exports statement.

Now let’s add some classes that describe a conference. The first is a good old POJO:

public class ConferencePojo {
    private String name;
    private int numberOfParticipants;
    // standard setters and getters
}

This object stores the name and number of participants of a conference. It has private fields and public getters and setters.

Next, we prepare an equivalent Java record:

public record ConferenceRecord(String name, int numberOfParticipants) {
}

With a record, we don’t need to declare the fields or write getters and setters.

4.1. Gson Failure With POJO

Gson easily deserializes a POJO such as ConferencePojo in a classpath project, but not in a module path one. To prove that, we’ll run the GsonModuleMain application inside our modular project. Let’s look at its main method:

public static void main(String[] args) {
    String moduleName = GsonModuleMain.class.getModule()
      .getName();
    if (moduleName == null) {
        log.info("Mode: [ Class Path ] (Class in the Unnamed Module)");
    } else {
        log.info("Mode: [ Module Path ] - Module name: " + moduleName);
    }
    Gson gson = new Gson();
    String json = "{\"name\":\"Java Conference\"}";
    try {
        ConferencePojo pojo = gson.fromJson(json, ConferencePojo.class);
        log.info("Deserialization successful! Object " + pojo);
    } catch (Exception e) {
        log.error("Expected exception caught!", e);
    }
}

At the beginning, we log whether the JVM actually loaded our class from the module path. Then we try to deserialize the POJO. Let’s examine the result:

10:40:06.766 [main] INFO gson.exception.GsonModuleMain -- Mode: [ Module Path ] - Module name: gson.exception
10:40:06.868 [main] ERROR gson.exception.GsonModuleMain -- Expected exception caught!
com.google.gson.JsonIOException: Failed making field 'gson.exception.ConferencePojo#name' accessible; either increase its visibility or write a custom TypeAdapter for its declaring type.
See https://github.com/google/gson/blob/main/Troubleshooting.md#reflection-inaccessible-to-module-gson
...
Caused by: java.lang.reflect.InaccessibleObjectException: Unable to make field private java.lang.String gson.exception.ConferencePojo.name accessible: module gson.exception does not "opens gson.exception" to module com.google.gson
...

Gson throws a JsonIOException caused by an InaccessibleObjectException. From the two messages, we learn what happened and get hints on how to solve the problem. In short, within a modular project, Gson can’t access the private fields of our class unless we let it.

4.2. Success With Records

With records, we’ll get a completely different result. Let’s use a JUnit 5 test to demonstrate it:

@Test
void givenModularAndExportedPackage_whenDeserializingRecord_thenSuccess() {
    String json = """
        {
            "name": "Java Conference",
            "numberOfParticipants": 150
        }
        """;
    Gson gson = new Gson();
    ConferenceRecord result = assertDoesNotThrow(() -> {
        return gson.fromJson(json, ConferenceRecord.class);
    });
    assertNotNull(result);
    assertEquals("Java Conference", result.name());
}

This time, Gson successfully deserializes the JSON and creates the record. Since version 2.10, Gson uses a record’s canonical constructor when instantiating the object, unlike classes, where Gson needs access to private fields.

5. How to Deserialize a POJO

If we still want to use a POJO, let’s follow the hints from the exception messages. We have four ways to fix this.

5.1. Make Fields Public

Let’s create a copy of ConferencePojo with public fields:

public class ConferencePojoPublic {
    public String name;
    public int numberOfParticipants;
}

Now Java lets Gson access the fields with reflection, and deserialization succeeds. However, we lose encapsulation this way.

5.2. opens to Expose Private Fields

To let Gson work with our private fields, we can open our package to it. Let’s create a new project, gson-module-opens, and look at its module-info.java file:

module gson.exception {
    requires com.google.gson;
    requires org.slf4j;
    opens gson.exception to com.google.gson;
    exports gson.exception;
}

With the statement opens gson.exception to com.google.gson, we allow Gson to access the private fields in the gson.exception package. Let’s run our GsonModuleMain application again:

19:08:55.369 [main] INFO gson.exception.GsonModuleMain -- Mode: [ Module Path ] - Module name: gson.exception
19:08:55.410 [main] INFO gson.exception.GsonModuleMain -- Deserialization successful! Object gson.exception.ConferencePojo@675d3402

This time, the program doesn’t throw an exception and deserializes the JSON successfully, even in the modular project.

5.3. Using the TypeAdapter Abstract Class

If we can’t use opens, we can extend Gson’s TypeAdapter abstract class for our POJO. All we need to do is implement its write and read methods. As we focus on deserialization, let’s look only at the read method:

@Override
public ConferencePojo read(JsonReader in) throws IOException {
    String name = null;
    int numberOfParticipants = 0;
    in.beginObject();
    while (in.hasNext()) {
        String key = in.nextName();
        if ("name".equals(key)) {
            name = in.nextString();
        } else if ("numberOfParticipants".equals(key)) {
            numberOfParticipants = in.nextInt();
        } else {
            in.skipValue();
        }
    }
    in.endObject();
    ConferencePojo result = new ConferencePojo();
    result.setName(name);
    result.setNumberOfParticipants(numberOfParticipants);
    return result;
}

The read method returns an instance of ConferencePojo. It loops over all the entries of the JsonReader and picks out the fields by their JSON names.

Note that we create the ConferencePojo object with its default constructor and fill it in with setters. This is the crucial point: to use a TypeAdapter, we need a public API for creating the object. In our case, that’s the setters, but a constructor, public fields, a factory, or a builder would work as well.

Now let’s test the adapter:

@Test
void whenAdapterForPojo_thenSuccess() {
    Gson gson = new GsonBuilder()
      .registerTypeAdapter(ConferencePojo.class, new ConferencePojoAdapter())
      .create();
    String json = """
        {
            "name": "Java Conference",
            "numberOfParticipants": 100
        }
        """;
    ConferencePojo result = gson.fromJson(json, ConferencePojo.class);
    assertNotNull(result);
    assertEquals("Java Conference", result.getName());
}

Note that we need to register the adapter with GsonBuilder.

5.4. The –add-opens Argument as a Last Resort

When we can’t modify the module’s source code, we still have one option left. We can open the package when the program starts by passing the –add-opens argument to the JVM. Let’s look at the argument for our gson-module project, which doesn’t open its package:

--add-opens gson.exception/gson.exception=com.google.gson

Starting from the left, we have the module name gson.exception, as declared in the module-info.java file. Next comes the package we want to open, gson.exception. Finally, we name the module we grant the access to, com.google.gson.

This is the launch-time equivalent of the opens statement, and with it, GsonModuleMain from gson-module deserializes the POJO successfully. However, we should treat it as a last resort, since the argument lives outside the code and we have to repeat it in every launch configuration. Our article on illegal reflective access covers the background in more detail.

6. Gson and Time

Besides problems with modular projects, we can run into the same exception when deserializing JSON into the date and time classes from the java.time API, such as LocalDate, Instant, or Duration. With strong encapsulation and an older Gson version, we get a JsonIOException with the message “Failed making field ‘java.time.LocalDate#year’ accessible”, again caused by an InaccessibleObjectException. This time, Gson tries to reach the private fields of a Java internal class. Moreover, we can’t solve this problem with the opens statement, as it can only open our own packages, not Java’s internals. However, Gson 2.14.0 has restored support for these classes.

6.1. LocalDate and Structured JSON

Let’s add a conferenceStart field in a new ConferencePojoWithDate class. We’re continuing in the gson-module-opens project, as the other fields are private:

public class ConferencePojoWithDate {
    private String name;
    private int numberOfParticipants;
    private LocalDate conferenceStart;
    // standard setters and getters
}

Now let’s prepare the JSON. We need to use a nested structure for conferenceStart:

{
    "name": "Java Conference",
    "numberOfParticipants": 500,
    "conferenceStart": {
        "year": 2026,
        "month": 8,
        "day": 17
    }
}

Note that the keys year, month, and day exactly match the names of the private fields of LocalDate. The same is true for the other time classes. For example, for Duration, the nested JSON provides the seconds and nanoseconds and looks like this:

"duration": {
    "seconds": 7200,
    "nanos": 0
}

Gson kept this naming convention for backward compatibility. It doesn’t (and isn’t allowed to) access the private fields of Java’s internal classes anymore. Instead, the authors implemented built-in TypeAdapters that use the public java.time API to transfer the data.

We should be especially careful to use the correct field names. If Gson doesn’t find a matching key in the JSON, it silently falls back to the default value of zero. For LocalDate, a zero month then triggers a completely different exception, a DateTimeException from the date validation in java.time.

Next, we can’t deserialize a date in ISO format out of the box. So, a plain string value such as the following fails with a JsonSyntaxException:

"conferenceStart":"2026-08-17"

To handle dates encoded as strings, we need to implement a custom TypeAdapter.

Finally, let’s emphasize that the same rules apply to records: we can deserialize nested time structures out of the box, and we need a TypeAdapter otherwise.

7. Conclusion

In this article, we looked at using Gson in modern, modular Java. We saw that it no longer works as easily as it did with Java 8 and the classpath.

We examined the problem in a modular project and looked at several ways to make Gson fit the rules of the JPMS. As our first measure, we made the class fields public. Next, we gave Gson access to private fields with the opens statement, or with the equivalent –add-opens JVM argument.

We then implemented a TypeAdapter that creates the object through its public API. We also saw that Gson works with records out of the box, using their canonical constructors.

Finally, we checked how Gson handles the classes from the java.time package. We noted that the newest version can deserialize nested time objects as expected again.

The bottom line is that we have two main ways to avoid the InaccessibleObjectException. The first is to open our code to Gson’s reflection, and with the opens statement, we can grant that access to Gson only. The second is to switch to records and stay within the rules of the JPMS. In addition, if we have a public API for creating the object, we can implement a TypeAdapter.

The post Gson Deserialization and the InaccessibleObjectException first appeared on Baeldung.

       

1. Introduction

Jackson is a Java library commonly used to convert between Java objects and JSON. During JSON deserialization, Jackson may throw an InvalidDefinitionException when it can’t determine how to create an instance of the target class. This can happen even when the JSON structure matches the class fields.

In this tutorial, we’ll reproduce the exception using Jackson 2.17.2 and explore several ways to resolve it.

2. Reproducing the Exception

Let’s start with an immutable Notification class that contains a parameterized constructor:

public class Notification {
    private final String message;
    private final int priority;
    public Notification(String message, int priority) {
        this.message = message;
        this.priority = priority;
    }
    // getters
}

Next, let’s try to deserialize a JSON object into the Notification class:

String json = "{\"message\":\"Server maintenance\",\"priority\":2}";
ObjectMapper mapper = new ObjectMapper();
mapper.readValue(json, Notification.class);

Although the JSON properties match the fields in Notification, Jackson can’t determine how they map to the constructor parameters. The constructor doesn’t specify which JSON property Jackson should use for each parameter.

As a result, deserialization fails with an InvalidDefinitionException:

Cannot construct instance of `com.baeldung.invaliddefinitionexception.Notification` (no Creators, like default constructor, exist): cannot deserialize from Object value (no delegate- or property-based Creator)

The exception indicates that Jackson needs a suitable mechanism to create the Notification instance. We can address this in several ways.

3. Adding a Default Constructor

One way to resolve the exception is to provide a no-argument constructor:

public class NotificationWithDefaultConstructor {
    private String message;
    private int priority;
    public NotificationWithDefaultConstructor() {
    }
    // getters and setters
}

By default, Jackson relies on a no-argument constructor to instantiate the target class. It can then populate the object’s properties during deserialization:

NotificationWithDefaultConstructor notification = objectMapper.readValue(json, NotificationWithDefaultConstructor.class);
assertEquals("Server maintenance", notification.getMessage());
assertEquals(2, notification.getPriority());

This approach works well for mutable classes, where Jackson can set the properties after creating the instance.

4. Defining a Property-Based Creator

For immutable classes, we can explicitly define how Jackson should use the parameterized constructor:

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
public class NotificationWithCreator {
    private final String message;
    private final int priority;
    @JsonCreator
    public NotificationWithCreator(
      @JsonProperty("message") String message, 
      @JsonProperty("priority") int priority) {
        this.message = message;
        this.priority = priority;
    }
    
    // getters
}

In this case, the @JsonCreator annotation tells Jackson to use the annotated constructor to create the object. The @JsonProperty annotations specify which JSON property corresponds to each constructor parameter.

With the constructor configured as a creator, we can deserialize the JSON while keeping the class immutable:

NotificationWithCreator notification = objectMapper.readValue(json, NotificationWithCreator.class);
assertEquals("Server maintenance", notification.getMessage());
assertEquals(2, notification.getPriority());

In addition, we should make sure to import the annotations from the com.fasterxml.jackson.annotation package, which Jackson 3.x also uses. Jackson won’t recognize creator annotations imported from the legacy org.codehaus.jackson package.

4.1. Factory Methods as Creators

Factory methods can also be creators. If Jackson doesn’t recognize our factory method as a creator, it will throw the same InvalidDefinitionException.

To resolve the issue, we annotate the method and its parameters in the same way as we do with parameterized constructors:

@JsonCreator
public static NotificationWithFactory create(
  @JsonProperty("message") String message,
  @JsonProperty("priority") int priority) {
    return new NotificationWithFactory(message, priority);
}

Now, this method can also act as a creator.

5. Discovering Constructor Parameter Names

Finally, instead of adding Jackson annotations to the target class, we can configure Jackson to discover constructor parameter names.

5.1. Using ParameterNamesModule

In Jackson 2.x, we can use ParameterNamesModule to discover constructor parameter names without adding @JsonProperty annotations:

ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new ParameterNamesModule());
Notification notification = mapper.readValue(json, Notification.class);
assertEquals("Server maintenance", notification.getMessage());
assertEquals(2, notification.getPriority());

We need to compile the class with the Java -parameters option so that the parameter names are available at runtime. In Jackson 3.x, this functionality is built into jackson-databind and enabled by default, so we don’t need to register a separate module.

5.2. Using ParanamerModule

Another option in Jackson 2.x is to use ParanamerModule. First, we need to add the jackson-module-paranamer dependency to our project:

<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-paranamer</artifactId>
    <version>${jackson.version}</version>
</dependency>

Next, we register ParanamerModule with the ObjectMapper:

ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new ParanamerModule());
Notification notification =
    mapper.readValue(json, Notification.class);
assertEquals("Server maintenance", notification.getMessage());
assertEquals(2, notification.getPriority());

Once registered, ParanamerModule gives Jackson the constructor parameter names, so it can match the message and priority to the corresponding JSON properties.

However, Paranamer is discontinued and supports Jackson 2.x only, which limits this approach for newer projects.

6. Conclusion

In this article, we reproduced a Jackson deserialization exception that occurs when Jackson can’t determine how to create the target object. We then explored several approaches to resolve it.

These include adding a default constructor, defining a property-based creator with @JsonCreator and @JsonProperty, and letting Jackson discover constructor parameter names. Static factory methods can also serve as creators.

The post Resolving Exception: Cannot Deserialize From Object Value (No Delegate- Or Property-Based Creator) first appeared on Baeldung.