1. Overview

Kafka provides a high degree of flexibility in committing offsets for processed messages in the consumer. It includes synchronous, asynchronous, and auto-commit options.

While this reduces the complexity of the commit process, unexpected errors can still occur.

In this tutorial, we’ll learn about a commit offset-related failure in a Kafka consumer application. We’ll debug the root cause of the resulting CommitFailedException and implement a few solutions to avoid it where possible.

2. Implementing a Consumer Service to Demonstrate the Issue

Let’s build a simple consumer application that processes records sequentially.

We’ll implement the consume method in the KafkaConsumerService class:

public class KafkaConsumerService {
    private final KafkaConsumer<String, String> consumer;
    private final AtomicBoolean running = new AtomicBoolean(true);
    public void consume() {
        try {
            while (running.get()) {
                ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(100));
                if (records.isEmpty()) {
                    continue;
                }
                records.forEach(this::simulateDBCall);
                consumer.commitSync();
            }
        } catch (WakeupException ex) {
            if (running.get()) {
                log.error("Error in the Kafka Consumer with exception", ex);
                throw ex;
            }
        } finally {
            consumer.close();
        }
    }
}

In the code above, we process records sequentially and then commit the offset.

To simulate a database call, we’ll add a delay in the above simulateDBCall method:

private void simulateDBCall(ConsumerRecord<String, String> record) {
    try {
        log.info("Simulating a DB call - record key {} value {}", record.key(), record.value());
        Thread.sleep(150L);
    } catch (InterruptedException ex) {
        Thread.currentThread()
          .interrupt();
        throw new RuntimeException(ex);
    }
}

The delay will cause the consumer to wait around 150 ms before the next record.

3. Testing the Service

Next, let’s test the consumer service. Note that we use Testcontainers in our test harness to provide a local Kafka broker for testing; full details are available in the supporting GitHub repository linked at the end of this article.

First, we’ll include the consumer-related configs in the test class:

private static Properties getConsumerConfig() {
    Properties consumerProperties = new Properties();
    consumerProperties.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA_CONTAINER.getBootstrapServers());
    consumerProperties.put(ConsumerConfig.GROUP_ID_CONFIG, "consumer-app");
    consumerProperties.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
    consumerProperties.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
    consumerProperties.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
    consumerProperties.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "false");
    consumerProperties.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 1);
    consumerProperties.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 50);
    
    return consumerProperties;
}

In the config above, we’re polling for one record with a maximum poll interval of 50 ms and manually committing the offset.

We’ll implement a test case by producing, consuming a message, and verifying the offset:

@Test
void givenProducerMessageIsSent_whenConsumerIsRunning_thenConsumerOffsetIsCommitted() {
    KafkaConsumerService kafkaConsumerService = new KafkaConsumerService(getConsumerConfig(), "test-topic");
    Thread th = new Thread(kafkaConsumerService::consume);
    th.start();
    try (KafkaProducer<String, String> producer = new KafkaProducer<>(getProducerConfig())) {
        producer.send(new ProducerRecord<>("test-topic", "x1", "test"));
        producer.flush();
    }
    Awaitility.await()
      .atMost(30, TimeUnit.SECONDS)
      .pollInterval(2, TimeUnit.SECONDS)
      .untilAsserted(() -> {
          TopicPartition topicPartition = new TopicPartition("test-topic", 0);
          Map<TopicPartition, OffsetAndMetadata> committedOffsets;
          try (AdminClient adminClient = AdminClient.create(getAdminProps())) {
              ListConsumerGroupOffsetsResult result = adminClient.listConsumerGroupOffsets("consumer-app");
              committedOffsets = result.partitionsToOffsetAndMetadata()
                .get();
          }
          assertNotNull(committedOffsets);
          assertNotNull(committedOffsets.get(topicPartition));
          assertEquals(1L, committedOffsets.get(topicPartition)
            .offset());
      });
    kafkaConsumerService.shutdown();
}

Instead of offset committed, we’ll see the following error log with the test case also failing:

org.apache.kafka.clients.consumer.CommitFailedException: Offset commit cannot be completed since the consumer is not part of an active group for auto partition assignment; it is likely that the consumer was kicked out of the group.
	at org.apache.kafka.clients.consumer.internals.ConsumerCoordinator.sendOffsetCommitRequest(ConsumerCoordinator.java:1280)
	...
	at org.apache.kafka.clients.consumer.KafkaConsumer.commitSync(KafkaConsumer.java:918)
	at com.baeldung.kafka.commitfailure.sequential.KafkaConsumerService.consume(KafkaConsumerService.java:34)

From the log above, it’s obvious that the CommitFailedException was thrown while committing the offset in the consume method. Also, it says that the consumer is no longer part of the group. Kafka gives some hints in the class documentation on the possible reason.

4. Root Cause of the CommitFailedException

We can monitor and debug the root cause with multiple options, including container logs, CLI, and Kafka UI tools.

First, we’ll check the Kafka container logs for the error:

[2026-06-08 16:53:05,349] INFO [GroupCoordinator 1]: Preparing to rebalance group consumer-app in state PreparingRebalance with old generation 1 (__consumer_offsets-0) (reason: Removing member consumer-consumer-app-1-3792090b-be55-4e19-bdbd-a3c66b968168 on LeaveGroup; client reason: consumer poll timeout has expired.)
...
[2026-06-08 16:53:05,354] INFO [GroupCoordinator 1]: Member MemberMetadata(memberId=consumer-consumer-app-1-3792090b-be55-4e19-bdbd-a3c66b968168, groupInstanceId=None, clientId=consumer-consumer-app-1, clientHost=/172.17.0.1, sessionTimeoutMs=45000, rebalanceTimeoutMs=50, supportedProtocols=List(range, cooperative-sticky)) has left group consumer-app through explicit `LeaveGroup`; client reason: consumer poll timeout has expired...

We’ll also confirm the consumer group’s state using the kafka-consumer-groups command:

sh-4.4$ /usr/bin/kafka-consumer-groups --bootstrap-server localhost:9092 --describe --group consumer-app --state
Consumer group 'consumer-app' has no active members.
GROUP                     COORDINATOR (ID)          ASSIGNMENT-STRATEGY  STATE           #MEMBERS
consumer-app              8db993586dab:9092  (1)                         Empty           0

Based on the above logs and status, we can see that the consumer was removed due to a client-specific error: consumer poll timeout has expired.

Kafka has multiple ways to check if the consumer is healthy and running. This includes a background heartbeat check, which should run before the session timeout.

Additionally, Kafka expects the consumer to poll once within the specified max poll interval time period. If the consumer does not poll for any reason, it will be considered dead, and the partition will be reassigned to another consumer.

By further debugging and re-verifying the application logs, we observe that the record processing was clearly taking more time, and the consumer could not call the poll method within the specified MAX_POLL_INTERVAL_MS_CONFIG time period. Consequently, the consumer was removed by the Kafka group coordinator.

So, any further attempt to commit an offset failed with the error. It makes sense as the consumer is no longer the partition owner, and a commit can corrupt the offset state.

We’ll explore a few practical ways to prevent the error.

5. Approaches to Avoid the Problem

With the consumer polling understanding, we’ll try to solve it by analyzing the consumer code and configuration.

We may consider enabling auto-commit config, but that brings a possibility of data loss and irregular commit timing. Moreover, this approach does not ensure at-least-once processing.

Instead, we’ll explore some relevant manual commit solutions.

5.1. Tuning the Poll Duration and Batch Size

By debugging the code, we found that the actual processing time was significantly longer than the specified maximum poll interval.

We’ll increase the maximum poll interval config:

consumerProperties.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 1);
consumerProperties.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 300);

We can also fine-tune the batch size according to our batch processing timing and throughput requirements.

Let’s test the updated consumer and confirm that no CommitFailedException is thrown.

We should note that it’s good to set the poll interval to about 3 times the batch processing time to ensure a safe buffer.

While changing the poll interval works, we may still face the issue in more complex setups, such as processing involving database transactions or network calls.

5.2. Async Processing

If we’re processing records in the same thread that performs I/O operations, the above solution reduces throughput and increases latency.

In a production environment, we can’t guarantee a predictable database execution time, so configuring just the polling duration might be insufficient.

We can consider asynchronous processing of the records, so the consumer thread blocks for much shorter periods.

In Kafka, this can be done by processing the records asynchronously with virtual threads.

First, we’ll include a worker thread pool and a per-partition offset tracking map in the consumer service:

public class KafkaConsumerService {
    private final KafkaConsumer<String, String> consumer;
    private final AtomicBoolean running = new AtomicBoolean(true);
    private final ExecutorService workers;
    private final Map<TopicPartition, AtomicLong> committableOffsets = new ConcurrentHashMap<>();
    public KafkaConsumerService(Properties consumerProps, String topic) {
        this.consumer = new KafkaConsumer<>(consumerProps);
        consumer.subscribe(List.of(topic));
        workers = Executors.newVirtualThreadPerTaskExecutor();
    }
}

Next, we’ll update the consume method with async processing using the worker threads:

public void consume() {
    try {
        while (running.get()) {
            ConsumerRecords<String, String> records = consumer.poll(Duration.ofMillis(100));
            if (records.isEmpty()) {
                continue;
            }
            List<CompletableFuture<Void>> futures = processAsync(records);
            try {
                CompletableFuture.allOf(futures.toArray(CompletableFuture[]::new))
                  .orTimeout(700L, TimeUnit.MILLISECONDS)
                  .join();
            } catch (CompletionException ex) {
                log.error("Batch processing timed out or failed", ex);
            }
            commitOffsets();
        }
    } catch (WakeupException ex) {
        if (running.get()) {
            log.error("Error in the Kafka Consumer with exception", ex);
            throw ex;
        }
    } finally {
        commitOffsets();
        consumer.close();
    }
}

We’ll implement the processAsync method to asynchronously process the records:

private List<CompletableFuture<Void>> processAsync(ConsumerRecords<String, String> records) {
    return StreamSupport.stream(records.spliterator(), false)
      .map(record -> CompletableFuture.runAsync(() -> simulateDBUpdate(record), workers)
        .whenComplete((ignored, ex) -> {
            if (ex == null) {
                markComplete(record);
            } else {
                log.error("Failed offset and send to DLQ {} {} {}", 
                  record.offset(), record.key(), ex.getMessage());
            }
        })
        .exceptionally(ex -> null))
      .toList();
}

In the code above, the consumer waits for the workers to complete processing, then commits the processed offset. If any record fails during processing, we log the failure message and can send it to a Dead Letter Queue (DLQ) topic.

Next, let’s implement the markComplete method to update the processed record offset into the committableOffsets map:

private void markComplete(ConsumerRecord<String, String> record) {
    TopicPartition tp = new TopicPartition(record.topic(), record.partition());
    committableOffsets.computeIfAbsent(tp, k -> new AtomicLong(-1L))
      .accumulateAndGet(record.offset() + 1L, Math::max);
}

Finally, we’ll implement the commitOffsets method to commit the processed offset:

private void commitOffsets() {
    Map<TopicPartition, OffsetAndMetadata> toCommit = new HashMap<>();
    committableOffsets.forEach((tp, atomicOffset) -> {
        long val = atomicOffset.get();
        if (val != -1L) {
            toCommit.put(tp, new OffsetAndMetadata(val));
        }
    });
    if (toCommit.isEmpty()) {
        return;
    }
    consumer.commitSync(toCommit);
    toCommit.forEach((tp, meta) -> {
        AtomicLong ref = committableOffsets.get(tp);
        if (ref != null) {
            ref.compareAndSet(meta.offset(), -1L);
        }
    });
}

In the method above, we build the committed offset snapshot map for all the processed records and commit it. We also atomically mark the committed offset as completed.

Now, let’s configure the consumer with an increased batch size and max poll interval in the test class:

consumerProperties.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 30);
consumerProperties.put(ConsumerConfig.MAX_POLL_INTERVAL_MS_CONFIG, 1000);

Finally, we’ll implement a test case by producing and consuming multiple messages and verifying the offset:

@Test
void givenProducerMessagesAreSent_whenConsumerIsRunning_thenConsumerOffsetIsCommitted() {
    KafkaConsumerService kafkaConsumerService = new KafkaConsumerService(getConsumerConfig(), "test-topic");
    Thread th = new Thread(kafkaConsumerService::consume);
    th.start();
    try (KafkaProducer<String, String> producer = new KafkaProducer<>(getProducerConfig())) {
        for (int num = 0; num < 100; num++) {
            producer.send(new ProducerRecord<>("test-topic", "x1" + num, "test" + num));
        }
        producer.flush();
    }
    Awaitility.await()
      .atMost(30, TimeUnit.SECONDS)
      .pollInterval(2, TimeUnit.SECONDS)
      .untilAsserted(() -> {
          TopicPartition topicPartition = new TopicPartition("test-topic", 0);
          Map<TopicPartition, OffsetAndMetadata> committedOffsets;
          try (AdminClient adminClient = AdminClient.create(getAdminProps())) {
              ListConsumerGroupOffsetsResult result = adminClient.listConsumerGroupOffsets("consumer-app");
              committedOffsets = result.partitionsToOffsetAndMetadata()
                .get();
          }
          assertNotNull(committedOffsets);
          assertNotNull(committedOffsets.get(topicPartition));
          assertEquals(100L, committedOffsets.get(topicPartition)
            .offset());
      });
    kafkaConsumerService.shutdown();
}

By running the test above, we have successfully verified that the committed offset matches the total number of consumed messages.

5.3. Implementing a ConsumerRebalanceListener

We should note that it’s always good practice to implement ConsumerRebalanceListener in the consumer to commit any in-flight offset and clean any data.

Let’s implement the ConsumerRebalanceListener in the KafkaConsumer object in the KafkaConsumerService class:

consumer.subscribe(List.of(topic), new ConsumerRebalanceListener() {
    @Override
    public void onPartitionsRevoked(Collection<TopicPartition> partitions) {
        try {
            commitOffsets(partitions);
        } catch (Exception ex) {
            log.error("Commit failed during rebalance", ex);
        } finally {
            partitions.forEach(committableOffsets::remove);
        }
    }
    @Override
    public void onPartitionsAssigned(Collection<TopicPartition> partitions) {
        partitions.forEach(committableOffsets::remove);
    }
});

We’ll also need to implement the commitOffsets method to commit offsets for the specific partitions:

private void commitOffsets(Collection<TopicPartition> partitions) {
    Map<TopicPartition, OffsetAndMetadata> toCommit = new HashMap<>();
    partitions.forEach(tp -> {
        AtomicLong ref = committableOffsets.get(tp);
        if (ref != null) {
            long val = ref.get();
            if (val != -1L) {
                toCommit.put(tp, new OffsetAndMetadata(val));
            }
        }
    });
    if (toCommit.isEmpty()) {
        return;
    }
    consumer.commitSync(toCommit);
}

In the code above, we’re committing the offset by creating a snapshot map from the specific partition’s offset.

Now, let’s run the previous section’s test method to verify the offset for the updated consumer implementation:

13:01:21.571 [virtual-158] INFO  c.b.k.c.f.async.KafkaConsumerService - Simulating a db call - record key x199 value test99

From the test above, we confirm that all messages were processed and committed.

5.4. Best Practices

While we cannot prevent exceptions entirely, we can protect the system from any reprocessing duplication, data loss, or silent message drops.

We should implement idempotency on both the producer and the consumer, validate database constraints, and ensure side-effect-free reprocessing. Additionally, we should send the failed messages to a retry or DLQ topic.

6. Conclusion

In this article, we learned about one of the common offset commit-related exceptions in the Consumer application. We explored why the resulting CommitFailedException happens and how to prevent it. We also implemented a preventive solution by tuning the maximum poll interval and switching to asynchronous processing logic.

As always, the example code can be found over on GitHub.

       

1. Overview

Hibernate 7.2 introduces first-class regular expression support in HQL via the like regexp operator. Before this addition, matching a string column against a non-trivial pattern meant writing a native query. This new operator delegates regex matching to the database engine, avoiding native queries and post-filtering in Java.

In this tutorial, we’ll walk through a small Spring Boot example that demonstrates like regexp. We’ll look under the hood to understand how Hibernate translates it to SQL and what happens when the underlying database doesn’t support regex.

2. Preparing a Simple Spring Boot Example

Before we can demonstrate the like regexp operator, we need a tiny project to run queries against. We’ll set up the dependencies, an entity, some seed data, the application properties, and a Spring Data repository. For simplicity, we’ll not show all the code here.

2.1. Dependencies

Our project uses Spring Boot 3.3 as its parent. Spring Boot 3.3’s BOM pins Hibernate to 6.5, so we override the version and a couple of its transitive dependencies that Hibernate 7 requires newer versions of:

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.4.2.Final</version>
</dependency>
<dependency>
    <groupId>org.jboss.logging</groupId>
    <artifactId>jboss-logging</artifactId>
    <version>3.6.1.Final</version>
</dependency>
<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
    <version>3.2.0</version>
</dependency>

Beyond that, we pull in the usual spring-boot-starter-data-jpa and the H2 driver, as we’ll use the H2 in-memory database to keep the demo self-contained.

2.2. The Entity

We’ll keep things minimal with a single-column entity:

@Entity
public class Message {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String content;
    // constructors, getters ...
}

2.3. Seed Data

We load test data through Spring’s data.sql mechanism. The values are short phrases designed to exercise regex patterns:

INSERT INTO message (content) VALUES ('quick brown fox jumps over');
INSERT INTO message (content) VALUES ('hello world from spring boot');
INSERT INTO message (content) VALUES ('Order 1234 shipped on Monday');
INSERT INTO message (content) VALUES ('Please call 555 today');
INSERT INTO message (content) VALUES ('ERROR connection refused remotely');
INSERT INTO message (content) VALUES ('warning low disk space detected');

2.4. Application Properties

The test profile (application-test.yaml) wires up H2 and asks Spring to run data.sql after Hibernate creates the schema:

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    ...
  jpa:
    database-platform: org.hibernate.dialect.H2Dialect
    hibernate:
      ddl-auto: create-drop
    defer-datasource-initialization: true
    show-sql: true
    ...
  sql:
    init:
      mode: always

The defer-datasource-initialization: true setting ensures that data.sql runs after the schema is created. It’s also worth mentioning that we enabled show-sql option to log translated SQL. This helps us understand how the like regexp operator works. We’ll discuss it later.

2.5. The Repository

The repository is the part we’ll actually be exercising. It declares a pair of HQL queries using the new like regexp/not like regexp operators:

public interface MessageRepository extends JpaRepository<Message, Long> {
    @Query("select m from Message m where m.content like regexp :pattern")
    List<Message> findByContentMatchingRegex(@Param("pattern") String pattern);
    @Query("select m from Message m where m.content not like regexp :pattern")
    List<Message> findByContentNotMatchingRegex(@Param("pattern") String pattern);
}

As always, we’ll use unit tests to demonstrate how each operator behaves.

3. Demonstration

In our defined repository methods, the pattern parameter accepts a full regex pattern. To find every message that contains at least one digit, we use .*\d+.*:

@Test
void givenContainsDigitRegex_whenLikeRegexp_thenReturnsMatching() {
    List<Message> results = repository.findByContentMatchingRegex(".*\\d+.*");
    assertThat(results)
      .extracting(Message::getContent)
      .containsExactlyInAnyOrder(
        "Order 1234 shipped on Monday",
        "Please call 555 today");
}

Similarly, if we pass the same regex to the findByContentNotMatchingRegex() method, we’ll get all rows that don’t contain any digits.

@Test
void givenContainsDigitRegex_whenNotLikeRegexp_thenReturnsNonMatching() {
    List<Message> results = repository.findByContentNotMatchingRegex(".*\\d+.*");
    assertThat(results)
      .extracting(Message::getContent)
      .containsExactlyInAnyOrder(
        "quick brown fox jumps over",
        "hello world from spring boot",
        "ERROR connection refused remotely",
        "warning low disk space detected");
}

If we run these two tests, they will pass. The same pattern parameter drives both variants, so we don’t need a separate regex for each side of the predicate. Next, let’s understand how Hibernate’s like regexp operator works under the hood.

5. Under The Hood

Having seen the operator in action, let’s look at how Hibernate actually implements it and where the portability boundaries lie.

5.1. How like regexp Is Translated

When Hibernate parses m.content like regexp :pattern, it doesn’t translate to a LIKE statement at all. Instead, it routes the predicate through a Semantic Query Model (SQM) function that each dialect registers under the name regexp_like. The default H2Dialect maps regexp_like(x, y) to H2’s regexp_like(x, y) SQL function, so if we check the log output of the example test above, we can see the translated SQL:

select m1_0.id, m1_0.content
from message m1_0
where regexp_like(m1_0.content, ?)

In other words, like regexp is syntactic sugar at the HQL level, while the heavy lifting happens in the database. Other dialects bind the same SQM function to whatever native construct they support, such as REGEXP_LIKE in Oracle, the ~ operator in PostgreSQL, REGEXP in MySQL, and so on.

Some dialects, for example, SQL Server prior to 2025, have no native regular expression function at all. In that case, the dialect simply doesn’t register regexp_like, and any HQL using like regexp fails at SQL execution time because Hibernate emits a call to a function the database doesn’t know.

5.2. The Portability Caveat

Because each dialect delegates to the database’s native regex engine, the flavor of regex we can use is whatever the underlying database supports. Let’s see a few examples:

• H2 uses java.util.regex (Perl-compatible, Matcher.find() semantics — no implicit anchoring).
• PostgreSQL uses POSIX regular expressions, which differ in subtle ways. For example, it has no \d shorthand without the embedded (?x) flag.
• Oracle uses POSIX with a few extensions and does not support \d either. We must write [[:digit:]] or [0-9] instead.
• MySQL (8.x) uses ICU regex, again with its own quirks.

So while the HQL stays portable, the patterns we feed into like regexp generally don’t. For example, a regex tested against H2 may fail or behave differently when the application is pointed at Oracle. If our application targets multiple databases, we should stick to a conservative regex subset.

6. Conclusion

Hibernate 7.2’s like regexp operator lets us express regex predicates directly in HQL and have them pushed down to the database without resorting to native queries. The HQL surface is portable across dialects, but the actual regex flavor depends on the underlying database engine.

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

       

1. Introduction

Bean background initialization in the Spring Framework provides a way to initialize selected beans asynchronously during application context startup. Instead of blocking the startup process on every bean initialization, Spring initializes selected beans in the background and continues processing the remaining application context. This improves application startup time and reduces perceived latency in applications with expensive initialization logic.

In this tutorial, we’ll explore how Bean background initialization works using the Spring native bootstrap attribute. We’ll demonstrate how to configure it correctly, how Spring manages lifecycle consistency during asynchronous initialization, and how this approach improves startup performance in real-world applications that rely on heavy resources such as caches, external services, or computation-heavy components.

2. Why Background Initialization Matters in Spring

Spring initializes singleton beans during the ApplicationContext refresh phase in a strictly synchronous manner. During startup, the container manages the complete bean lifecycle and processes each bean in sequence:

1. bean instantiation
2. dependency injection
3. initialization callback execution
4. marking the bean as ready for use

This approach provides predictable and deterministic startup behavior by ensuring that each bean reaches a fully initialized state before the context refresh proceeds. However, it introduces performance constraints when beans execute expensive operations during initialization.

2.1. Synchronous Bean Initialization Model

Expensive initialization increases the duration of the ApplicationContext refresh phase by forcing the container to complete the lifecycle of each bean before moving forward. It reduces throughput in the bean creation pipeline and increases overall startup latency. As a result, even non-critical initialization logic delays the application from becoming available.

2.2. Single-Threaded Initialization Bottleneck

The default startup model executes all bean initialization on the same thread that drives the context refresh process. Consequently, Spring executes independent initialization tasks sequentially and prevents them from running concurrently. This limits startup throughput and prevents Spring from taking advantage of available parallelism during application bootstrap.

3. Background Initialization Mechanism

Spring introduces background initialization using the bootstrap attribute to reduce startup blocking caused by expensive singleton bean creation.

During application context refresh, Spring applies a modified execution strategy to selected beans:

• Async delegation: Spring delegates the initialization phase of selected beans to a container-managed executor (the bootstrap executor), enabling execution to occur on a separate thread without blocking the main refresh process.
• Dependency coordination: When another bean depends on a background-initialized bean through a non-lazy dependency, Spring suspends dependency resolution for that bean and waits for initialization to complete before injecting the bean.
• Lifecycle preservation: Spring preserves the standard lifecycle order.

This design ensures safe background execution while decoupling heavy initialization from the main startup thread, enabling earlier application readiness without affecting bean consistency.

4. Example Setup

This section introduces a product preload class that simulates an expensive startup workload in Spring applications. This can be cache warming, dataset loading, or external resource preparation, which typically increases application startup time.

Let’s define the class to demonstrate this behavior:

public class ProductCatalogInitializer {
    public ProductCatalogInitializer() {
        loadProducts();
    }
    private void loadProducts() {
        System.out.println("Starting product preload");
        try {
            Thread.sleep(5000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        System.out.println("Product preload completed");
    }
    public String getStatus() {
        return "Catalog ready";
    }
}

The loadProducts() method represents a long-running initialization task executed during bean creation. Spring runs this logic on the main startup thread, which blocks the ApplicationContext refresh until completion.

This component acts as the baseline for demonstrating how Spring shifts such initialization work to background execution using the bootstrap mechanism in the next section.

5. Background Initialization Using Bootstrap Mode

Spring applies background initialization at the bean definition level using the bootstrap attribute. Selected beans then get initialized concurrently without blocking the main startup thread.

5.1. Enabling Background Initialization

At this point, let’s create a configuration that marks ProductCatalogInitializer as a Spring-managed bean and enables background initialization using BACKGROUND bootstrap mode:

@Configuration
public class AppConfig {
    @Bean(bootstrap = Bean.Bootstrap.BACKGROUND)
    public ProductCatalogInitializer productCatalogInitializer() {
        return new ProductCatalogInitializer();
    }
}

Spring detects the BACKGROUND bootstrap mode and offloads bean initialization to a container-managed bootstrapExecutor, allowing it to run on a separate thread instead of blocking the main application context refresh. Hence, this mechanism relies on a configured bootstrap executor. Without it, Spring can’t execute background initialization, and the affected beans fall back to normal synchronous initialization during startup.

5.2. Bean Injection

A background-initialized bean can be injected into other Spring-managed components in the same way as any standard singleton bean, since background initialization doesn’t change the core dependency injection model.

In most cases, direct injection remains sufficient because Spring coordinates the lifecycle and ensures that the bean becomes fully available within the application context startup phase. However, in scenarios where access may occur before the initialization process has completed, Spring provides ObjectProvider as an optional mechanism for deferred retrieval of the bean at runtime.
To that end, let’s create a service that demonstrates the injection of a background-initialized bean:

@Service
public class ProductService {
    private final ObjectProvider<ProductCatalogInitializer>
            initializerProvider;
    public ProductService(
            ObjectProvider<ProductCatalogInitializer> initializerProvider) {
                this.initializerProvider = initializerProvider;
    }
    public void printStatus() {
        ProductCatalogInitializer initializer = initializerProvider.getObject();
        System.out.println("Bean status: " + initializer.getStatus());
    }
}

Now, the dependency isn’t resolved during bean creation. Instead, Spring retains the reference and defers resolution until getObject() is invoked. At that point, the actual bean instance is retrieved, so access occurs only after background initialization has completed, while the injection phase remains independent of startup timing.

5.3. Application Startup Behavior with Background Initialization

With BACKGROUND bootstrap mode enabled, Spring offloads selected bean initialization to a background thread, allowing the application context refresh to proceed without waiting for these beans. As a result, startup becomes non-blocking for the selected initialization workload, while execution continues in parallel.

Despite this, non-lazy background-initialized beans remain part of the Spring container lifecycle, and their completion is coordinated within the overall startup process.

5.4. Performance Impact

This behavior directly reduces startup latency. Spring moves heavy bean initialization off the main refresh thread. As a result, the application becomes operational earlier while background tasks continue executing in parallel. Beans that load large caches, establish connection pools, or run schema validation benefit the most.

6. Conclusion

In this article, we explored background initialization in the Spring Framework using the BACKGROUND bootstrap mode, which enables selected beans to initialize asynchronously during application context refresh.

The mechanism decouples expensive bean initialization from the main startup thread while preserving the Spring lifecycle semantics. Rather than launching uncontrolled threads, Spring keeps full awareness of bean dependencies. If a non-lazy bean depends on one that is still initializing in the background, Spring ensures it waits, preventing access to incomplete or half-built objects. In addition, using ObjectProvider helps delay bean retrieval until it is actually needed, adding an extra layer of safety for early-access scenarios.

This approach improves application startup responsiveness in systems with heavy initialization workloads by enabling parallel execution during context refresh. It maintains dependency safety and lifecycle consistency while reducing blocking on the main thread. Background initialization is best suited for non-critical beans such as cache warmers, external integrations, and data preloading components.

The code backing this article is available over on Github.

       

1. Introduction

In this tutorial, we’ll take a look at jCasbin – the Java official port of the popular Apache Casbin authorization library. We’ll see what it is, how to use it and what we can do with it.

2. What is jCasbin

jCasbin is the Java version of the powerful Casbin access control library. This allows us to easily answer questions about access to resources within our applications.

jCasbin, and the entire suite of Casbin libraries, work using a configuration model that allows us to describe the access control model we want to use – such as ACLs or RBAC – and a separate set of policy data applied to that configuration model.

Typically, this works by defining:

• Objects that we want to control access to.
• Subjects who want to access these objects.
• Actions that the objects want to perform.

However, jCasbin is flexible enough that we can use any structure we want, as long as we can model it correctly in our configuration and policy data.

3. Dependencies

Before using jCasbin, we need to include the latest version in our build, which is 1.99.0 at the time of writing.

If we’re using Maven, we can include this dependency in our pom.xml file:

<dependency>
    <groupId>org.casbin</groupId>
    <artifactId>jcasbin</artifactId>
    <version>1.99.0</version>
</dependency>

At this point, we’re ready to start using it in our application.

4. Creating an Enforcer

Once we have jCasbin in our application, we’re ready to use it. The central class for this is the Enforcer. Constructing this requires two data sources: our configuration model and our policy data. The easiest way to manage this is through passing in filenames:

Enforcer enforcer = new Enforcer("path/to/model.conf", "path/to/policy.csv");

However, having our policy data be a local file can be difficult. As such, jCasbin allows the use of Adapters here instead. These provide a means to load and manipulate the policy data from any data source we like. We also have a set of standard adapters that can be used for our application. These include familiar technologies such as JDBC, Hibernate, MongoDB and many others:

Adapter jdbcAdapter = new JDBCAdapter(dataSource);
Enforcer enforcer = new Enforcer("path/to/model.conf", jdbcAdapter);

Exactly how these adapters work depends on the adapter in question and is out of scope of this article.

When specifying policy data as a filename, this internally uses the FileAdapter instead. We can also use this to load files available from other sources by providing an InputStream:

FileAdapter fileAdapter = new FileAdapter(getClass().getResourceAsStream("/com/baeldung/jcasbin/policy.csv"));
Enforcer enforcer = new Enforcer("path/to/model.conf", fileAdapter);

In exactly the same way, we can provide our model data using a Model instance instead. This allows us to load our model data from alternative sources:

String content = new String(getClass().getClassLoader().getResourceAsStream("com/baeldung/jcasbin/model.conf").readAllBytes());
Model model = new Model();
model.loadModelFromText(content);
Enforcer enforcer = new Enforcer(model, "path/to/policy.csv");

Once we’ve created our Enforcer, we’re ready to start using it to check permissions.

5. Enforcing Permissions

Now that we’ve got our Enforcer, we can start checking permissions. We do this using the enforce() method. This typically involves passing in our subject, object, and action to check:

if (enforcer.enforce("alice", "data1", "read")) {
    // permit alice to read data1
} else {
    // deny the request
}

Note that the enforce() method actually takes an arbitrary set of objects, depending on how our configuration model is defined.

The exact way permission checking works then depends on both the structure of our configuration model and our policy data.

5.1. Access Control Lists

One of the easiest ways to configure jCasbin is through Access Control Lists (ACLs). A typical configuration model might look like this:

# Request definition
[request_definition]
r = sub, obj, act
# Policy definition
[policy_definition]
p = sub, obj, act
# Matchers
[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
# Policy effect
[policy_effect]
e = some(where (p.eft == allow))

Here, the request_definition section tells us what the shape of the data passed into enforcer.enforce() should be. It gives us names for the parameters we pass in – here, “sub”, “obj” and “act” are used as shorthand for “subject”, “object” and “action”.

The policy_definition section then uses the exact same names to map onto the policy data. If not specified, there’s also an implicit value called “eft” – short for “effect” – which defaults to “allow”.

The matchers section then explains how we can match policy rows to requests. In this case, we’re simply saying that every field must have exactly the same value.

Finally, the policy_effect section tells us how to determine the overall effect of our policy. The action is only allowed if this returns a positive match.

In this mode, our policy data is a straight list of subjects, objects and allowed actions – as defined by our policy_definition:

p, alice, data1, read
p, bob, data2, write

This indicates that the subject “alice” can perform the action “read” on the object “data1”, whereas the subject “bob” can perform the action “write” on the object “data2”.

assertTrue(enforcer.enforce("alice", "data1", "read"));
assertTrue(enforcer.enforce("bob", "data2", "write"));

Any other checks are rejected because they don’t match our configuration.

5.2. Super Users

Sometimes we might want super users – users who can do anything regardless of what the policy data specifies.

We express this in our configuration model by adjusting how the matchers section is defined:

[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act || r.sub == "root"

Here, in addition to the same matching as before, we also match when the subject has the exact value “root”, regardless of what the rest of the policy expression says. Using this, a subject of “root” will always pass every check regardless:

assertTrue(enforcer.enforce("root", "data2", "write"));

This introduces some risks into our permission checks, so we need to use it carefully.

5.3. Role-Based Access Control

Role-Based Access Control (RBAC) introduces an additional layer of indirection into our configuration model. In this case, we assign roles to users, and can define permissions based on roles.

We start by adding a role_definition section:

[role_definition]
g = _, _

This defines the g() function that we can use to define role membership.

We also need to update our matchers section to make use of this:

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

Instead of directly comparing the policy subjects with the request, this says they must match via the role definitions.

We can now make use of this within our policy data:

p, alice, data1, read
p, data2_admin, data2, read
p, data2_admin, data2, write
g, bob, data2_admin

All of our rows that start with p define how permissions are assigned, either directly to users or else to roles. Here we’re assigning one permission directly to the subject “alice”, and two permissions to the role “data2_admin”.

The rows starting with g – from our role_definition section above – define how role membership works. Here, we’re defining that the subject “bob” is assigned the role “data2_admin”. This then means that this subject implicitly has all of the permissions assigned to this role as well:

assertTrue(enforcer.enforce("bob", "data2", "write"));

We can also nest roles. That is, we can assign one role to another, generating an entire hierarchy of permissions:

g, superuser, data2_admin
g, carol, superuser

Here, the role “data2_admin” has been assigned to the role “superuser”, and the role “superuser” has been assigned to the subject “carol”. This means that this subject has all the permissions all the way up:

assertTrue(enforcer.enforce("carol", "data2", "read"));

We never gave “carol” permission on “data2” – either directly or indirectly. Instead, she inherited it through her role “superuser”.

6. Management API

In addition to checking permissions, we also have management APIs for working with our setup.

We do this from the same Enforcer instance that we’ve already been using.

6.1. Querying Subjects, Objects and Actions

The easiest thing we can do is query all the subjects and objects in our policy data. We do this using the getAllSubjects(), getAllObjects() and getAllActions() methods:

List<String> subjects = enforcer.getAllSubjects();
List<String> objects = enforcer.getAllObjects();
List<String> actions = enforcer.getAllActions();

We can also query the actions that any given subject can perform on any given object:

Set<String> subjects = enforcer.getPermittedActions("alice", "data1");

This works correctly for both ACL and RBAC setups, as well as for hierarchical roles.

6.2. Querying RBAC Roles

With an RBAC setup, we can also query exactly which roles are assigned to which subjects:

List<String> roles = enforcer.getRolesForUser("carol");
// superuser

This returns only the roles directly assigned, not those included in the configured hierarchy.

However, we can also query which roles are assigned to other roles in the same way:

List<String> roles = enforcer.getRolesForUser("superuser");
// data2_admin

This means we can traverse the hierarchy if needed.

6.3. Managing Permissions and Roles

We also have a set of methods we can use to directly manage the permissions and roles that subjects have.

We can directly add and remove permissions between a subject and an object:

enforcer.addPermissionForUser("alice", "data2", "read");
enforcer.deletePermissionForUser("alice", "data2", "read");

These apply directly once called, and permission checks take effect straight away.

When we’re working in RBAC mode, we can additionally add and remove roles from subjects:

enforcer.addRoleForUser("alice", "superuser");
enforcer.deleteRoleForUser("alice", "superuser");

We apply all of these changes in memory. We need to use the savePolicy() method to write them back to our backing store:

enforcer.savePolicy();

However, we can only do this if we’re using certain adapters. It also depends on how the data was loaded. For example, we can’t write back if we loaded from an InputStream.

7. Summary

In this article, we took a very quick look at jCasbin. There’s a lot more that we can do with this. Next time you need to manage access controls for your applications, why not give it a try?

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

       

1. Overview

The @EmbeddedTable annotation is a new Hibernate feature that simplifies the logic of mapping an embedded object to a secondary table.

In this short tutorial, we’ll shed light on the annotation and delve into its usage. First, we’ll start with some insight into the motivation behind @EmbeddedTable. Then, we’ll demonstrate how to use it in practice.

2. The Problem With Traditional Mapping

Before this new annotation, JPA provided multiple annotations to map a single entity into multiple tables. However, this traditional approach requires @SecondaryTable, @Embedded, @Embeddable, and multiple @AttributeOverride annotations to override each column individually. This can quickly become verbose as the number of columns grows.

Let’s say we have a single Person entity that stores personal and address information. Here, we assume that we want to store the address details in a separate secondary table.

First, let’s create the Address object we want to embed inside the Person entity:

@Embeddable
public class Address {
	
    private String street;
    private String city;
    private String code;
    // setters
    
}

Now, we create the Person entity:

@Entity
@SecondaryTable(name = "person_address")
public class Person {
    
    @Id
    private int id;
    
    @Column(name= "first_name")
    private String firstName;
    
    @Column(name = "last_name")
    private String lastName;
    
    @Embedded 
    private Address address;
    // setters
}

That’s not all, as mapping the Address fields to a secondary table requires the @AttributeOverride annotation for each field:

@Embedded 
@AttributeOverride(name = "street", column = @Column(table = "person_address")) 
@AttributeOverride(name = "city", column = @Column(table = "person_address"))
@AttributeOverride(name = "code", column = @Column(table = "person_address"))
private Address address;

This approach quickly becomes cumbersome and error-prone since missing a single override can silently map a column to the wrong table. So, this is where @EmbeddedTable comes into play.

3. Using @EmbeddedTable

Starting with Hibernate 7.2, we can implement the same mapping we did in the previous section far more concisely with @EmbeddedTable:

@EmbeddedTable(value = "person_address")
private Address address;

In a nutshell, Hibernate automatically maps every field of the embedded object Address to the specified secondary table person_address without overriding each one individually.

This is particularly useful when dealing with large embeddable objects containing several fields.

So, let’s add a test case to confirm that everything works:

@Test
void whenUsingEmbeddedTableThenMapIntoTwoSeparateTables() {
    Address address = new Address();
    address.setStreet("12 Av. Tamassint center");
    address.setCity("Tamassint");
    address.setCode("10000");
    Person person = new Person();
    person.setId(1);
    person.setFirstName("Azhrioun");
    person.setLastName("Abderrahim");
    person.setAddress(address);
    session.persist(person);
    session.flush();
    Object[] addressRow = (Object[]) session.createNativeQuery(
      "select street, city from person_address",
      Object[].class
    ).uniqueResult();
    assertEquals("12 Av. Tamassint center", addressRow[0]);
    assertEquals("Tamassint", addressRow[1]);
    Object[] personRow = (Object[]) session.createNativeQuery(
      "select first_name, last_name from person",
      Object[].class
    ).uniqueResult();
    assertEquals("Azhrioun", personRow[0]);
    assertEquals("Abderrahim", personRow[1]);
}

As expected, the test case runs successfully.

4. The Limitations

Although convenient, there are a couple of points worth keeping in mind when using @EmbeddedTable.

First, it’s a Hibernate-specific annotation and not part of the Jakarta Persistence specification. If portability across JPA providers matters, the @AttributeOverride annotation is always the safer choice.

Additionally, @EmbeddedTable is marked @Incubating, which means the API is still evolving and not yet considered stable and mature.

Typically, @EmbeddedTable is intended for top-level embedded objects. So, using it on nested objects isn’t supported yet.

5. Conclusion

In this short article, we explored the new Hibernate @EmbeddedTable annotation.

Along the way, we learned that it provides a cleaner alternative to multiple @AttributeOverride annotations when mapping embedded objects to secondary tables.

The full source is available over on GitHub.

       

1. Spring and Java

>> The Coming Loop [lucumr.pocoo.org]

A frame for the next phase of AI-assisted development – an agent harness, which generates, runs, inspects, corrects, and repeat quickly enough that the system becomes genuinely useful instead of just impressive. Anecdotally I’ve been running one for a few months now A good read.

Also worth reading:

• >> Self-Correcting Structured Output in Spring AI 2.0 [spring.io]
• >> Better Tools for Immutable Data [inside.java]
• >> Behind the Scenes: Block 450 JVM Repositories into Monorepo to Reduce Dependency Drift [infoq.com]
• >> Jurassic JDK: Migrate or Extinct [foojay.io]
• >> On programming languages, targets, and platforms [frankel.ch]
• >> Kotlin Toolchain 0.11: The Next Step for Amper [jetbrains.com]
• >> Pi4J Drivers: Simplifying Sensor and Hardware Integration in Java [foojay.io]
• >> Systematic AI Coding: My Takeaways from the Eclipse Foundation Workshop in Brussels [foojay.io]
• >> Backups with Restic: 2-year retrospective [advancedweb.hu]
• >> So You Want To Define a Well-Known URI [mnot.net]
• >> Working Effectively with Claude Code [scottlogic.com]
• >> Sustainable acceleration and the Agentic Software Development Life Cycle [scottlogic.com]
• >> How Netflix Simplified Batch Compute with Kueue [netflixtechblog.com]
• >> Toward More Controllable AI Video Editing: An Early Research Exploration at Netflix [netflixtechblog.com]

Webinars and presentations:

• >> Quarkus Unpacked: Insights from the Foojay Podcast [foojay.io]
• >> Episode 60 “How JEPs Drive Java’s Evolution” [AtA] [inside.java]
• >> A Bootiful Podcast: My friend Francesco Ciulla on developer advocacy and more [spring.io]

Time to upgrade:

• >> Spring Boot 3.5.16 available now [spring.io]
• >> Spring Data 2025.0.13 released [spring.io]
• >> Emergency releases to fix CVE-2026-50559 in all supported streams [quarkus.io]
• >> Quarkus 3.36.3, 3.33.2.1, 3.27.4.1, and 3.20.6.2 [github.com/quarkusio]
• >> Vert.x 5.1.3 [github.com/eclipse-vertx]
• >> Elasticsearch 8.19.17 and 9.3.6 [github.com/elastic]
• >> Zuul v3.6.16 and v3.6.15 [github.com/Netflix]
• >> Micronaut Core 5.1.2 [github.com/micronaut-projects]
• >> Helidon 3.2.18 [github.com/helidon-io]
• >> WildFly 40.0.1 is released! [wildfly.org]

2. Pick of the Week

>> Old Software Was Fast Because It Had No Choice [yusufaytas.com]

       

1. Overview

Modern web applications are increasingly integrating with Large Language Models (LLMs) to build solutions that go beyond simple question answering. To create AI agents capable of handling complex user requests, we often connect them to multiple Model Context Protocol (MCP) servers that provide them with specific capabilities via tools.

However, creating and running MCP servers can be overkill for lightweight and local automation tasks where we just need to expose a simple capability to a single agent.

Agent Skills is a specification that provides a structured way to locally define, package, and expose these capabilities to an AI agent.

In this tutorial, we’ll explore the Agent Skills capability in Spring AI. We’ll configure a custom skill and integrate it with a simple chatbot to summarize articles.

2. What are Agent Skills?

Agent Skills is an open specification for defining various capabilities that an AI agent can invoke. A skill is essentially a directory containing a SKILL.md file, which acts as its manifest, alongside any associated code like Python or Bash scripts, or additional resources that the skill relies on.

The SKILL.md file contains a frontmatter block with a name and description, followed by a set of natural language instructions that tell the agent how to use the skill.

When the agent receives a user request, it reads the descriptions of all available skills and decides if any is relevant. If yes, it then loads the relevant files into context and follows the instructions inside the matching skill to fulfill the request. And if no skill matches the request, the agent simply responds using its general capabilities without invoking any skill.

We’ll see an agent invoking our custom skill practically in action in the upcoming sections.

3. Setting up the Project

Before we dive into the implementation, we’ll need to include the necessary dependencies and configure our application correctly.

3.1. Dependencies

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

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

Here, we first import Spring AI’s OpenAI starter dependency, which we’ll use to interact with a chat model. Support for agent skills is available in Spring AI 2 and later, so we need to make sure we’re using the correct version.

Next, we import the agent-utils dependency from the Spring AI community, which enables us to add the agent skills capability to our chat models.

3.2. Configuring 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:
        options:
          model: gpt-5.5

We use the ${} property placeholder to load the value of our API Key from an environment variable.

Additionally, we specify OpenAI’s GPT 5.5 model using the gpt-5.5 model ID. Alternatively, we can use a different chat model that supports the agent skills specification, 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, allowing us to interact with the specified model.

4. Defining Our Custom Skill

Now let’s define a custom agent skill that can fetch an article from a URL and summarize it.

Agent skills follow a specific directory structure, so let’s set that up. We’ll start by creating an .openai/skills directory in our project’s root directory. We can define multiple subdirectories inside this, each representing a distinct agent skill.

Next, we’ll create an article-summarizer subdirectory to represent our custom skill inside .openai/skills and define our main SKILL.md file inside it:

---
name: article-summarizer
description: Summarizes articles into concise digests. Useful when user asks to summarize or get key points from an article.
---
# Article Summarizer
## Instructions
When summarizing an article:
1. If given a URL: Run `uv run scripts/fetch_article.py <url>` to retrieve the content.
2. Once content is available, extract the main thesis, few key points, and conclusion.
3. Structure the output as a TL;DR, key points, and a bottom line.

In the frontmatter block, we define the name and description of our skill. The description is especially important as the agent uses it to determine whether this skill is relevant for a given user request. Next, we define the instructions that tells the agent exactly what steps to follow when the skill is invoked, including which script to run and how to structure the final output.

Next, let’s create the fetch_article.py script inside a new scripts subdirectory that we reference in the instructions:

ARTICLE = """
... hardcoding sample article for demonstration
"""
print(ARTICLE)

Here, for our demonstration, we simply print a hardcoded article about MCP elicitations instead of actually making a web request. The AI model will run this script and read the standard output to get this article’s content regardless of the URL in the request .

Also, it’s important to note that we can define our scripts in any language of our choice. We just need to make sure that we pre-install the required runtimes for our agent to execute the necessary commands.

5. Creating a Simple Chatbot

With our configurations in place, let’s build a simple chatbot.

In Spring AI, the ChatClient class acts as the main entry point for interacting with our configured chat completion model. Let’s define its bean using the auto-configured ChatModel bean:

@Bean
ChatClient chatClient(ChatModel chatModel) {
    String skillsRootDirectory = ".openai/skills";
    return ChatClient
      .builder(chatModel)
      .defaultTools(
        SkillsTool.builder()
          .addSkillsDirectory(skillsRootDirectory)
          .build(),
        FileSystemTools.builder()
          .allowedDirectory(skillsRootDirectory)
          .build(),
        ShellTools.builder()
          .build()
      ).build();
}

In our bean definition, we first register our custom skills directory using SkillsTool, pointing it to the .openai/skills directory.

Secondly, we register FileSystemTools, which gives the agent the ability to read and write any files on the local filesystem. To restrict the tool’s operations to the configured skills directory, we use the allowedDirectory() method.

Finally, we register ShellTools, which allows the agent to execute shell commands, enabling it to run the Python script we’ve defined.

However, it’s important to note that ShellTools executes our scripts directly on the local machine without sandboxing. As such, we should carefully review the scripts we expose to our agent and consider containerizing our application to limit potential exposure.

Next, let’s inject the ChatClient bean in a controller class and expose a REST API:

@PostMapping("/chat")
ResponseEntity<ChatbotResponse> chat(@RequestBody ChatbotRequest chatbotRequest) {
    String answer = chatClient
      .prompt()
      .user(chatbotRequest.question)
      .call()
      .content();
    return ResponseEntity.ok(new ChatbotResponse(answer));
}
record ChatbotRequest(String question) {}
record ChatbotResponse(String answer) {}

Here, we simply pass the user’s question to the chatClient instance and return the LLM’s response. We’ll use this API endpoint to interact with our chatbot in the upcoming section.

6. Interacting With Our Chatbot

Now that we’ve built our implementation, let’s interact with our chatbot and test the agent skill capability.

We’ll use the HTTPie CLI to invoke the chatbot’s API endpoint:

http POST :8080/chat question="Can you summarize the following article: https://www.baeldung.com/sample-non-existing-article"

Here, we ask the chatbot to summarize a specific article by passing a URL in the question. We deliberately provide the URL of a non-existent article to verify that the chatbot summarizes the article we’ve hardcoded in our Python script.

Let’s see what we get as a response:

{
  "answer": "## TL;DR\nThis article explains how to implement MCP Elicitations in Spring AI, allowing MCP servers to request additional user information dynamically during tool execution.
    \n\n## Key Points\n- MCP Elicitations solve the problem of missing user information during MCP tool execution.
    \n- The tutorial demonstrates building an MCP server using Spring AI.
    \n- The MCP server exposes a tool that fetches author details and conditionally requests additional information.
    \n- The `elicit()` method is used to pause execution and gather required details from the user.
    \n- The article also demonstrates configuring an MCP client and integrating it with an Anthropic Claude model
    \n- Spring AI automatically creates MCP clients and tool callback providers from configuration.
    \n- An `@McpElicitation` handler is used on the client side to respond to elicitation requests.
    \n- The tutorial concludes with a working chatbot example and log outputs showing the complete elicitation flow.
    \n\n## Bottom Line\nMCP Elicitations enable interactive AI applications where tools can dynamically collect additional context from users during execution,
    making MCP-based systems more flexible and user-aware."
}

As we can see, the LLM summarizes our hardcoded article and the response is structured exactly as our skill’s instructions prescribed, with a TL;DR, a set of key points, and a bottom line.

Behind the scenes, the agent matched the user’s request to the article-summarizer skill based on its description, loaded the instructions into context using FileSystemTools, executed the fetch_article.py script via ShellTools to retrieve the article content, and then structured the response following the instructions in our SKILL.md file.

7. Conclusion

In this article, we’ve explored the concept of Agent Skills using Spring AI.

We started by understanding what Agent Skills are and how they help us in exposing reusable capabilities to an AI agent.

Then, we defined a custom article summarizer skill and wired it into a chatbot. Finally, we interacted with our chatbot to confirm that it correctly discovers and invokes our skill.

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

       

1. Introduction

In this tutorial, we’ll show how to extend the Spring Authorization Server to handle dynamic OAuth 2.0 scopes, which are required in advanced authentication/authorization use cases.

2. When to Use Dynamic Scopes?

OAuth2-based applications use scopes to request access tokens with a defined set of privileges, like reading fields from a user’s profile, performing an automation task, and so on. Usually, the scopes are fixed and known in advance both by the authorization server and the client application. In some scenarios, however, this is not the case.

For instance, suppose your client application needs an access token to execute a single operation, like a transfer request or updating sensitive information. One option is to implement a custom authorization scheme between the client and the resource server, but we’d be reinventing the wheel. From a security perspective, this is also not ideal, since it implies a bigger surface attack, as those protocols would need to be implemented across every resource server and client.

This is where dynamic scopes come into play. In a nutshell, a dynamic scope is one that a client can request, but it’s not known beforehand by the authorization server.

Usually, a dynamic scope requires some sort of validation service to exist, so it can be validated. In practical terms, this requires a consent repository to store the requested scope, which will be used to validate it and, if the end user grants it, to update its status.

When the client receives the access token, it will have the dynamic scope associated with it, allowing it to complete the desired operation.

3. Dynamic Scopes in Spring Authorization Server

The Spring Authorization Server, true to its roots, has a modular architecture, which allows us to replace many of its components with custom ones. We’ve already explored this characteristic to implement multitenancy support, a feature not available by default. In our case, these are the aspects we need to modify:

• Scope validation logic
• Consent Validation
• Consent page: optional, but usually required

Moreover, it’s a good idea to separate the Spring-specific code from the actual scope validation logic. We’ll create a DynamicScopeService for that purpose, leaving to a @Configuration class the task of creating an adapter between the expected method’s signature and the service.

Now, let’s move to the implementation.

4. Project Setup

Dynamic Scopes don’t need any extra dependencies besides those needed by the Spring Authorization Server itself:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security-oauth2-authorization-server</artifactId>
    <version>4.1.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security-oauth2-authorization-server-test</artifactId>
    <version>4.1.0</version>
    <scope>test</scope>
</dependency>

The latest versions of these dependencies are available on Maven Central:

• spring-boot-starter-security-oauth2-authorization-server
• spring-boot-starter-security-oauth2-authorization-server-test

5. Security Configuration

The Spring Authorization Server needs two security filter chains to operate:

• one for handling OAuth/OIDC protocol endpoints
• a “catch-all” chain that handles everything else, including user authentication

As usual in Spring Security, the built-in ones are only created when there are no application-defined chains available. In our case, we need to tweak just the first one, but by doing so, the auto-configuration for the catch-all chain will be disabled, so we’ll need to provide both.

5.1. Authorization Server Chain

This is the modified chain where we’ll add our customization logic:

@Bean
@Order(Ordered.HIGHEST_PRECEDENCE)
SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) {
    http.oauth2AuthorizationServer(authorizationServer -> {
        http.securityMatcher(authorizationServer.getEndpointsMatcher());
        authorizationServer
          .oidc(withDefaults())
          .authorizationEndpoint(ap -> {
              ap.consentPage("/consent");
              ap.authenticationProviders(providers -> {
                  providers.stream()
                    .filter(OAuth2AuthorizationCodeRequestAuthenticationProvider.class::isInstance)
                    .map(p -> (OAuth2AuthorizationCodeRequestAuthenticationProvider)p)
                    .findFirst()
                    .ifPresent(p -> {
                        p.setAuthenticationValidator(dynamicScopesAuthenticationValidator());
                        p.setAuthorizationConsentRequired(dynamicScopesConsentValidator());
                    });
              });
          });
    });
    http.authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated());
    http.oauth2ResourceServer(resourceServer -> resourceServer.jwt(withDefaults()));
    http.exceptionHandling(exceptions -> exceptions.defaultAuthenticationEntryPointFor(
      new LoginUrlAuthenticationEntryPoint("/login"), createRequestMatcher()));
    return http.build();
}

The scope validation takes place at the OAuth2AuthorizationCodeRequestAuthenticationProvider, which uses two collaborating objects to perform its task:

• An AuthenticationValidator to validate the submitted parameters
• A Predicate that decides whether to ask for consent

Since the authorization server uses multiple AuthenticationProviders in its implementation, we need to go through all of them until we find the proper one. All this happens in the authorizationEndpointCustomizer, which exposes the list of authentication providers.

The same customizer also allows us to set the URI for a custom consent page, which will be “/consent” in our case. We’ll come back to the consent page later in this tutorial.

5.2. “Catch-All” Chain

This chain, which has no securityMatcher() call in its DSL, will apply the following rules to incoming requests:

• Any request must be authenticated
• When receiving a non-authenticated request, use form-based login with default settings

@Bean
@Order(SecurityFilterProperties.BASIC_AUTH_ORDER)
SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) {
    http.authorizeHttpRequests(authorize -> {
        authorize.anyRequest().authenticated();
      })
      .formLogin(withDefaults());
    return http.build();
}

Here, we’re just replicating the default configuration. In a real-world scenario, we’d probably want to change some aspects of its properties. For instance, this is where we’d provide the URI for a custom login page, enable two-factor authentication, or add support for a federated identity provider.

6. Scope Validation

The dynamicScopesAuthenticationValidator() method creates an adapter that isolates the Spring Security aspects of the scope validation from the business logic.

In our tutorial, we’ll assume that the dynamic scope will be a string that starts with the “TX:” prefix, followed by a unique transaction identifier. When a client needs an access token with this scope, it must add it to the scope request parameter of an authentication request, as in this example:

https://idp/oauth2/authorize?scope=openid TX:1234&...other params omitted

The authentication provider will perform the standard validation steps and, eventually, will call our adapter to perform the validation logic:

private Consumer<OAuth2AuthorizationCodeRequestAuthenticationContext> dynamicScopesAuthenticationValidator() {
    return ctx -> {
        OAuth2AuthorizationCodeRequestAuthenticationToken auth = ctx.getAuthentication();
        var requestedScopes = new HashSet<>(auth.getScopes());
        if ( requestedScopes.isEmpty() ) {
            return;
        }
        var registeredClient = ctx.getRegisteredClient();
        var allowedScopes = registeredClient.getScopes();
        requestedScopes.removeIf(allowedScopes::contains);
        if (requestedScopes.isEmpty() ) {
            return;
        }
        // Now, let's validate the remaining scopes using the provided validation service
        try {
            if (!dynamicScopeService.validate(registeredClient.getId(), requestedScopes)) {
                throw new OAuth2AuthorizationCodeRequestAuthenticationException(
                  new OAuth2Error(OAuth2ErrorCodes.INVALID_SCOPE),
                  auth
                );
            }
        } catch (Exception ex) {
            throw new OAuth2AuthorizationCodeRequestAuthenticationException(
              new OAuth2Error(OAuth2ErrorCodes.SERVER_ERROR), 
              ex, 
              auth
            );
        }
    };
}

The adapter receives an OAuth2AuthorizationCodeRequestAuthenticationContext instance that contains information about the authorization request. Notice that, at this point, the end user is not yet known, so we can’t use it as part of this logic.

These are the steps performed by the adapter:

• Firstly, recover the requested scopes and client information from the context.
• Secondly, remove any static scopes from the list.
• If there are no dynamic scopes, return immediately
• Otherwise, pass the client identifier and dynamic scopes to the validation service

The validation service’s job is to return just a yes/no answer depending on whether the request should be authorized. Our implementation, available online, just checks for a valid pattern. A real-world one would perform more complex validation, such as querying a database and applying any rules required by the specific use case.

7. Consent Validation

The other tweak we’ve made to support dynamic scopes is to add custom logic to determine whether the authorization needs to ask for user consent before issuing an access token. This was done using the AuthenticationProvider’s setAuthorizationConsentRequentid() method, which accepts a Predicate argument.

This Predicate should return true when an authorization request needs user consent, and false otherwise. As we’ve done in the scope validation case, we’ll use an adapter to extract the client’s identifier and requested scopes from the OAuth2AuthorizationCodeRequestAuthenticationContext instance passed to the Predicate. Once the basic checks are done, we invoke the validation service to get a final decision about the consent:

private Predicate<OAuth2AuthorizationCodeRequestAuthenticationContext> dynamicScopesConsentValidator() {
    return ctx -> {
        var previousConsent = ctx.getAuthorizationConsent();
        if ( previousConsent == null ) {
            // First consent, so consent is required
            return true;
        }
        OAuth2AuthorizationCodeRequestAuthenticationToken auth = ctx.getAuthentication();
        var requestedScopes = new HashSet<>(auth.getScopes());
        if ( requestedScopes.isEmpty() ) {
            return false;
        }
        // Remove already consented scopes
        var alreadyConsented = new HashSet<>(previousConsent .getScopes());		
        requestedScopes.removeIf(alreadyConsented::contains);
        if (requestedScopes.isEmpty() ) {
            return false;
        }
        // Any remaining scopes are dynamic scopes or static ones with no previous consent
        return dynamicScopeService.isConsentNeeded(ctx.getRegisteredClient().getId(), requestedScopes);
    };
}

A key distinction of this validation is that it happens after a successful authentication. This means that the business logic can use any of the standard Spring Security methods to get information about the current user and use it as part of the decision logic.

8. Consent Page

This page will be displayed to the user after a successful authentication, right before issuing an authorization code to a client application.

From the user agent’s perspective, this page will be accessed through a redirect from the login page. The Location header will point to the configured URI along with the following query parameters:

• client_id: Client application’s identifier
• scope: Requested scopes
• state: Server-side state associated with the current authorization request.

Please note that the state parameter in this case has no relation to the one with the same name that’s included in the initial authorization URL created by the client!

Let’s implement a simple controller that takes these parameters, prepares a Model, and forwards the request to a view:

@Controller
public class ConsentController {
    private final RegisteredClientRepository registeredClientRepository;
    private final OAuth2AuthorizationConsentService authorizationConsentService;
    // ... constructor omitted
    @GetMapping("/consent")
    public String consent(Principal principal, Model model,
      @RequestParam(name = OAuth2ParameterNames.CLIENT_ID) String clientId,
      @RequestParam(name = OAuth2ParameterNames.SCOPE) String scope,
      @RequestParam(name = OAuth2ParameterNames.STATE) String state) {
        var client = registeredClientRepository.findByClientId(clientId);
        assert client != null;
        var currentConsent =  authorizationConsentService.findById(client.getId(), principal.getName());
        Set<String> authorizedScopes = currentConsent != null ? currentConsent.getScopes() : Set.of();
        // Remove already authorized scopes from the requested scopes and the special 'openid' scope.
        var neededScopes = Set.of(scope.split(" ")).stream()
          .filter(s -> !authorizedScopes.contains(s) && !OidcScopes.OPENID.equals(s))
          .toList();
        model.addAttribute("clientId", clientId);
        model.addAttribute(
          "clientName", 
          client.getClientName() != null ? client.getClientName() : client.getClientId()
        );
        model.addAttribute("scopes", neededScopes);
        model.addAttribute("state", state);
        model.addAttribute("authorizedScopes", authorizedScopes);
        return "consent";
   }
}

We’ve injected two services in this controller to look for additional information needed to build the view:

• registeredClientRepository: Allow us to retrieve detailed information for the client, given its identifier
• authorizationConsentService: Returns an OAuthAuthorizationConsent containing all consents given to a client by a user

We use those services to build a list of the newly required consents and store it in a Spring MVC Model.

Here, we could also query a business service to enrich the Model with details related to any requested dynamic scope. For instance, if our dynamic scope represents a transfer request, we could look up its details and include them in the model.

The view itself uses a Thymeleaf template to display the consent request and present to the user an option to accept or deny it. Note that the form’s submit target is, by default, protected with a CSRF token, so make sure to use the th:action=”@{/path}” syntax. Thanks to Thymeleaf’s Spring integration,  this will automatically include a hidden input field with the correct CSRF token value.

Last, but not least, note that the form’s action target should point to the server’s OAuth2 authorization endpoint. Later, if we decide to change this URI from the default value, we must make sure that this form points to the same place.

9. Testing

Now, let’s write a test to verify our customized authorization server’s behavior, at least for the “happy path” case. The full code is a bit long, so here we’ll just discuss the main caveats when implementing it.

The first thing is that, to validate end-to-end calls, it’s better to use an environment that’s close to the real one. This is why we use WebEnvironment.RANDOM_PORT, which starts a full servlet stack bound to a free local port. The port’s actual value is injected into the test using the @LocalPort annotation, so we can use it to build all request URLs.

Secondly, we need to be able to keep session cookies between requests sent throughout the authentication/authorization process. This means we need to configure a RestTestClient with a factory request with this support enabled.

In our case, there’s another issue. We can instruct a RestTestClient  to either follow all redirects or none. However, once configured, it’s not trivial to modify this behavior. We could opt to use manual redirect handling only, but that would require additional coding. Instead, we’ve opted to define two clients: one that follows redirects, and another that doesn’t. Both clients share the same CookieManager instance, so we can use either one in the test without getting into session-related issues:

@BeforeEach
void setupRestClient() {
    CookieManager cookieManager = new CookieManager();
    var followRedirectsHttpClient = HttpClient.newBuilder()
      .followRedirects(HttpClient.Redirect.ALWAYS)
      .cookieHandler(cookieManager)
      .build();
    var followRedirectsRequestFactory = new JdkClientHttpRequestFactory(followRedirectsHttpClient);
    restTestClient = RestTestClient
      .bindToServer(followRedirectsRequestFactory)
      .baseUrl("http://localhost:" + port)
      .build();
    var noRedirectsHttpClient = HttpClient.newBuilder()
      .followRedirects(HttpClient.Redirect.NEVER)
      .cookieHandler(cookieManager)
      .build();
    var noRedirectsRequestFactory = new JdkClientHttpRequestFactory(noRedirectsHttpClient);
    noRedirecRestTestClient = RestTestClient
      .bindToServer(noRedirectsRequestFactory)
      .baseUrl("http://localhost:" + port)
      .build();
}

Our “happy-path” test covers the following:

• Endpoint discovery
• Building an authorization request with a dynamic scope
• Submitting user credentials to the login form
• Submitting values in the consent form
• Using the generated authentication code to retrieve an access token
• Validate that the access token has the request dynamic scope associated with it

Those steps cover a complete authorization flow, producing an access token that we can use to send a request to a resource server.

10. Conclusion

In this tutorial, we’ve seen how we can modify the Spring Authorization Server’s default configuration to support dynamic scopes. This expands the range of use cases where we can use it, making it a suitable candidate for complex authorization-related scenarios.

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

       

1. Spring and Java

>> Tool Calling in Spring AI 2.0: A Composable, Agentic Architecture [spring.io]

Spring AI 2.0 is out this week (see below) and turns tool calling into a first-class element, making agent loops easier to observe, compose, and extend. A strong read for anyone building agentic systems on Spring who needs more than a black-box function call.

Also worth reading:

• >> Can Java Microservices Be As Fast As Go? A 2026 Benchmark Update [inside.java]
• >> Introducing Quarkus Data: One Gateway for Data Access [quarkus.io]
• >> double, BigDecimal, or Fixed-Point? [frankel.ch]
• >> Spring vs Quarkus vs Jooby vs Vert.x: Pick Your Next Java Framework [foojay.io]
• >> Spring Boot 4.1 Adds gRPC Auto-Configuration, SSRF Mitigation, and Kotlin 2.3 Support [infoq.com]
• >> Oracle’s OpenJDK Bans Generative AI Contributions While Oracle’s GraalVM Allows Them [infoq.com]
• >> How Agentic Coding Can Help You Migrate Java Applications Faster [inside.java]
• >> Simplifying Weak Reference Processing in ZGC [inside.java]
• >> Observing Apache NetBeans with OpenTelemetry and Dash0 [foojay.io]
• >> Ask a Lille Dev: What Java Developers Really Think About Quality, Frameworks, Communities, and Careers [foojay.io]
• >> The Differences Between Microservices and AI Agents [christianposta.com]
• >> Building Reliable Agentic AI Systems [martinfowler.com]
• >> Did AI Just Break Software Security For Ever? [foojay.io]
• >> Ponytail? YAGNI! And the Problem with Prompt Benchmarks [scottlogic.com]
• >> What a Good Transformation Looks Like [scottlogic.com]

Webinars and presentations:

• >> Foojay Podcast #98: The End of JNI Pain: How WebAssembly Is Quietly Replacing Native Libraries in Java [foojay.io]
• >> Practical Performance Tuning for Serverless Java on AWS [infoq.com]

Time to upgrade:

• >> Spring AI 2.0 is here! [spring.io]
• >> Spring Tools 5.2.0 released [spring.io]
• >> Spring AI 1.0.9, 1.1.8 available now [spring.io]
• >> Hibernate 8.0.0.Beta1 [in.relation.to]
• >> Quarkus 3.37.0 [github.com/quarkusio]
• >> Micronaut Core 5.1.1 [github.com/micronaut-projects]
• >> Helidon 4.5.0 [github.com/helidon-io]
• >> Grails 7.1.2 and 7.0.12 [github.com/apache]
• >> Zuul 3.6.14 [github.com/Netflix]
• >> A2A Jakarta 1.0.0.CR1 is released! [wildfly.org]

2. Pick of the Week

Paul Graham’s short essay is a crisp reminder that the most valuable ideas are often both broadly useful and genuinely surprising. It is a useful lens for technical work too: even a small amount of novelty can matter when it attaches to a big enough idea.

>> General and Surprising [paulgraham.com]

       

1. Overview

Manipulating Markdown content is a common programming task. CommonMark is a Java library that simplifies working with Markdown documents.

In this tutorial, we’ll learn how to manipulate Markdown content using the library. We’ll see how to parse Markdown into HTML and convert HTML back into Markdown. Finally, we’ll explore how to customize nodes for advanced processing.

2. commonmark-java Library

The commonmark-java library provides classes and interfaces for working with Markdown content based on the CommonMark specification. It allows us to parse Markdown into HTML and convert HTML back into Markdown. Additionally, it provides access to the Abstract Syntax Tree (AST), enabling further customization and processing.

To use the common-java library, let’s add the commonmark dependency to our pom.xml:

<dependency>
    <groupId>org.commonmark</groupId>
    <artifactId>commonmark</artifactId>
    <version>0.28.0</version>
</dependency>

The commark dependency provides classes such as Parser, HtmlRenderer, and MarkdownRenderer for Markdown processing and rendering.

Additionally, CommonMark provides extension dependencies for more advanced processing features. Examples include commonmark-ext-gfm-tables for GitHub Flavored Markdown tables and commonmark-ext-gfm-alerts for alert blocks.

3. Parsing and Rendering Markdown to HTML

Moving on, let’s see one of the most common uses of the library: parsing Markdown and rendering it as HTML.

First, let’s define a method named markDownToHtml():

public static String markDownToHtml(String markdown) {
    Parser parser = Parser.builder().build();
    Node document = parser.parse(markdown);
    HtmlRenderer renderer = HtmlRenderer.builder().build();
    return renderer.render(document);
}

Here, we create an instance of Parser to parse Markdown input into a document node. Next, we create an HtmlRenderer instance to render the parsed node as HTML.

A Node represents an element in the parsed Markdown document tree.

Then, let’s write a unit test to verify the result:

@Test
void givenMarkdownInput_whenConvertingToHtml_thenReturnRenderedHtml() {
    String html = markDownToHtml("Welcome to *Baeldung*");
    assertEquals("<p>Welcome to <em>Baeldung</em></p>\n", html);
}

In the code above, we pass a string containing Markdown syntax to markDownToHtml() method. Since Baeldung is wrapped in asterisks (*), the Markdown parser interprets it as emphasized text. Consequently, the renderer converts it to an HTML <em> element.

4. Processing Parsed Nodes

Furthermore, we can use a visitor to further process nodes in the parsed document tree. The library allows us to extend the AbstractVisitor class to process a node.

Let’s create a visitor class that counts every word in a sentence:

class WordCountVisitor extends AbstractVisitor {
    int wordCount = 0;
    @Override
    public void visit(Text text) {
        wordCount += text.getLiteral().split("\\w+").length;
        visitChildren(text);
    }
}

Next, let’s write a method that uses the visitor:

public static int processParsedNode(String markdown) {
    Parser parser = Parser.builder().build();
    Node node = parser.parse(markdown);
    WordCountVisitor visitor = new WordCountVisitor();
    node.accept(visitor);
    return visitor.wordCount;
}

In the method above, we create a WordCountVisitor object and pass it to the parsed node for processing.

Let’s write a unit test to confirm the method:

@Test
void givenMarkdownInput_whenProcessingParsedNode_thenReturnWordCount() {
    int wordCount = processParsedNode("Welcome to *Baeldung*");
    assertEquals(3, wordCount);
}

Here, we verify that the expected word count is equal to the actual word count.

5. Rendering HTML to Markdown

Furthermore, CommonMark also provides classes for rendering HTML-like document structures into Markdown format, making it a library for both HTML and Markdown processing.

Let’s see this in action by writing code that converts an HTML heading into a Markdown format:

public static String htmlToMarkDown(String htmlHeading) {
    Heading heading = new Heading();
    heading.setLevel(2);
    heading.appendChild(new Text(htmlHeading));
    Document document = new Document();
    document.appendChild(heading);
    MarkdownRenderer renderer = MarkdownRenderer.builder()
      .build();
    return renderer.render(document);
}

In the code above, we create a Heading object and set the level to 2, which represents an H2 heading. Next, we append a  Text object containing the heading content. Finally, we use the MarkdownRenderer builder to render the document as Markdown.

Next, let’s write a unit test to confirm the output:

@Test
void givenHeadingText_whenConvertingToMarkdown_thenReturnMarkdownHeading() {
    String markdown = htmlToMarkDown("Java Tutorial");
    assertEquals("## Java Tutorial\n", markdown);
}

In the code above, we verify that the renderer correctly converts the document structure into a valid Markdown output.

6. Customizing HTML Rendering

Furthermore, CommonMark allows us to customize rendered HTML attributes using the AttributeProvider interface.

Let’s see this in action by implementing a class custom image attribute provider:

public class ImageAttributeProvider implements AttributeProvider {
    @Override
    public void setAttributes(Node node, String tagName, Map<String, String> attributes) {
        if (node instanceof Image) {
            attributes.put("class", "border");
        }
    }
}

In the code above, we create a class named ImageAttributeProvider that implements the AttributeProvider interface. Inside the setAttributes() method, we check whether the current node is an instance of Image. If it is, we add a class attribute with the value “border“.

Next, let’s write a method that applies the custom attribute provider during HTML rendering:

public static String changingHtmlAttribute(String source) {
    Parser parser = Parser.builder()
      .build();
    Node node = parser.parse(source);
    HtmlRenderer renderer = HtmlRenderer.builder()
      .attributeProviderFactory(context -> new ImageAttributeProvider())
      .build();
    return renderer.render(node);
}

In the code above, we customize the HtmlRenderer with a custom attribute provider using the attributeProviderFactory() method. Using lambda expressions, we invoke our provider for each node, allowing us to customize the generated HTML attributes. Every rendered image element receives a class=”border” attribute.

Finally, let’s write a unit test to ascertain the customized output:

@Test
void givenImageMarkdown_whenRenderingHtml_thenAddCustomClassAttribute() {
    String html = changingHtmlAttribute("![text](/url.png)");
    assertEquals("<p><img src=\"/url.png\" alt=\"text\" class=\"border\" /></p>\n", html);
}

In the test above, we verify that the custom attribute provider successfully adds the border CSS class to rendered image elements.

7. Customizing Render Node

Moreover, the library allows us to customize how specific nodes are rendered by implementing the NodeRenderer interface.

Let’s create a custom renderer for IndentedCodeBlock nodes:

public class IndentedCodeBlockNodeRenderer implements NodeRenderer {
    private final HtmlWriter html;
    public IndentedCodeBlockNodeRenderer(HtmlNodeRendererContext context) {
        this.html = context.getWriter();
    }
    @Override
    public Set<Class<? extends Node>> getNodeTypes() {
        return Set.of(IndentedCodeBlock.class);
    }
    @Override
    public void render(Node node) {
        IndentedCodeBlock codeBlock = (IndentedCodeBlock) node;
        html.line();
        html.tag("pre");
        html.text(codeBlock.getLiteral());
        html.tag("/pre");
        html.line();
    }
}

In the code above, we implement the NodeRenderer interface and specify that the renderer handles IndentedCodeBlock nodes through the getNodeTypes() method.

Then, in the render() method, we manually generate the HTML output for the code block using HtmlWriter.

Next, let’s register the custom renderer with HtmlRenderer:

public static String customizingHtmlRendering(String source) {
    Parser parser = Parser.builder()
      .build();
    Node node = parser.parse(source);
    HtmlRenderer renderer = HtmlRenderer.builder()
      .nodeRendererFactory(IndentedCodeBlockNodeRenderer::new)
      .build();
    return renderer.render(node);
}

Here, we customize the renderer using the nodeRendererFactory() method. We invoke the custom node using a method reference. This allows the renderer to delegate matching nodes to our custom implementation during HTML generation

Let’s write a unit test to verify the customizingHtmlRendering() method:

@Test
void givenIndentedCodeBlock_whenRenderingHtml_thenUseCustomNodeRenderer() {
    String html = customizingHtmlRendering("Example:\n\n    code");
    assertEquals("<p>Example:</p>\n<pre>code\n</pre>\n", html);
}

Here, we verify that indented code blocks are rendered using our custom renderer implementation.

8. Conclusion

In this article, we learned how to use the CommonMark library to parse Markdown into HTML and convert HTML back into Markdown. Additionally, we saw how to customize HTML attributes and node rendering for more advanced processing scenarios.

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

       

1. Spring and Java

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

A tour of where JDK 26 makes Java faster in practice. It is especially handy because it groups the changes by where they show up in real apps: startup, allocation pressure, throughput, and carrier-thread scalability. Always great to see how quickly the JDK is evolving.

Also worth reading:

• >> Exploiting GPU Tensor Cores from Java using Babylon [inside.java]
• >> Why You Should Tune Code Before Your Garbage Collector [vanillajava.blog]
• >> Testing Java Memory Management with Chronicle-FIX using AI [vanillajava.blog]
• >> Your TLS Stack Is Lying to You About Zero-Copy [foojay.io]
• >> Why Spring Teams Don’t Need a Second Runtime for AI Agents [foojay.io]
• >> Spring Boot Migration and the CRA: When Good Enough Isn’t [foojay.io]
• >> JEP targeted to JDK 27: 538: PEM Encodings of Cryptographic Objects (3rd Preview) [inside.java]
• >> The Jqwik Anti-AI Affair [johanneslink.net]
• >> Codename One: Metal Default, A New Build Cloud, And A New Format [foojay.io]
• >> Negotiating Vendor Contracts [dandreamsofcoding.com]
• >> A Human-Augmenting Agentic Workflow for Causal Inference [netflixtechblog.com]
• >> Gaslighting Openness [lucumr.pocoo.org]
• >> The Technology Adoption Curve, Twenty Years On [infoq.com]
• >> Rethinking ‘Transformation’: From projects to long-term capability [scottlogic.com]

Webinars and presentations:

• >> JavaNext Language Features [inside.java]
• >> Quarkus Insights #250: What’s New with Quarkus Data [quarkus.io]

Time to upgrade:

• >> Spring Batch 6.0.4 and 5.2.6 available now [spring.io]
• >> Spring for GraphQL 1.4.6 and 2.0.4 released [spring.io]
• >> Spring gRPC 1.1.0 available now [spring.io]
• >> Spring Vault 4.0.3 and 3.2.1 available [spring.io]
• >> Quarkus 3.36.2 [github.com/quarkusio]
• >> Vert.x 5.1.2 [github.com/eclipse-vertx]
• >> Micrometer 1.17.0 [github.com/micrometer-metrics]
• >> Zuul 3.6.11 [github.com/Netflix]
• >> Oracle Java Extension for Visual Studio Code Version 26.0.0 Is Now Available [inside.java]

2. Pick of the Week

My first course focused on building with AI is out, and the series is getting started:

>> Foundations of AI Coding

       

1. Overview

Codename One is an open-source, commercially supported platform that lets Java and Kotlin developers build cross-platform applications from a single codebase, while integrating with modern Maven-based workflows.

Its cloud-based build model reduces much of the platform-specific setup required for native development, letting us target iOS, Android, JavaScript, Windows, and macOS from the same project.

In this tutorial, we’ll build a Java 17 app named Daily Routine. It manages daily activities, has language and appearance settings, searches for places through a REST API, and displays map previews.

2. Big Picture

Let’s first look at the workflow, the finished app, and the source code we use as a reference.

2.1. Understanding the Codename One Workflow

Codename One applications are Maven projects. During development, the fastest loop is usually local, i.e., we run the app in the simulator, edit Java or Kotlin code, update CSS, and run tests from the IDE or command line:

This workflow is also automation-friendly: Maven commands, simulator runs, tests, cloud builds, and real-device debugging can be driven from scripts, CI jobs, or AI agents. Java 17 projects generated by the Codename One Initializr include agent-facing guidance for realistic end-to-end app development with AI assistance.

2.2. Preview and Sources

Before setting up the project locally, let’s download the JavaScript port and open it as a local HTML file. This gives us a quick preview of the forms, navigation, activity editor, settings screen, place search, and map preview.

Let’s see an example with Firefox:

The app is intentionally more complete than a minimal example, as it includes several features:

• local JSON persistence
• service classes
• responsive styling
• localization
• REST integration
• diagnostics
• UI tests
• network error handling
• fallback logic

Rather than covering every part of the repository line by line, we use the complete source code as a reference while focusing on the main Codename One patterns.

2.3. Opening the Complete Sources From GitHub

When opening the sources from GitHub, IDE-specific actions may be missing because local IDE metadata usually isn’t committed.

When using IntelliJ IDEA, we can recreate the Codename One run configurations fairly easily:

mvn cn1:configure-intellij

This restores actions such as running the simulator, opening Codename One Settings, and updating Codename One. Other IDEs can still open the project as a Maven project, but may require running the needed Maven goals manually.

3. Setting Up the Project

Now, let’s generate a new project, inspect its structure, and run it locally.

3.1. Creating the Project With Codename One Initializr

In the Codename One Initializr, let’s use a simple configuration:

• Main class: DailyRoutine
• Package: com.baeldung.cn1tutorial
• Localization: Include resource bundles

The other defaults are fine. After clicking Generate Project, a multi-module Maven structure appears:

We write most of the application in the shared common module: UI forms, business logic, CSS, localization files, services, and tests. Platform-specific modules for iOS, Android, Java SE, and JavaScript are present, but we usually touch them only for native integration or platform-specific configuration.

The generated AGENTS.md file and .agent-skills directory are meant to guide AI agents, but they also help explain the project structure and workflow.

3.2. Opening the Project in IntelliJ IDEA

For this tutorial, we use IntelliJ IDEA, although the Maven structure works with other major Java IDEs.

We should open the project root, not only the common module, because the root pom.xml defines the full Maven reactor.

When we first open it, a warning informs us that the Java SDK isn’t configured:

Let’s select OpenJDK 17.

3.3. Running the App in the Simulator

For UI work, we can treat the simulator as a reliable preview of real devices, as long as we compare the same platform family and a reasonably matching skin. There are options to try orientation changes, skins, system font size, light and dark styles, and much more:

The first place to inspect if we notice any odd behavior is theme.css. Additionally, certain changes to the simulator settings require us to close and reopen the simulator, so the app can adapt properly.

4. Creating the App Skeleton

Now that the project runs, let’s replace the generated screen with the structure of Daily Routine.

4.1. The Application Lifecycle

The Initializr starts with a class that extends the Codename One Lifecycle class and overrides runApp(). The DailyRoutine class keeps that entry point, but adds the setup needed by the app.

In Codename One, a Form represents one screen:

public class DailyRoutine extends Lifecycle {
    private AppContext appContext;
    @Override
    public void init(Object context) {
        super.init(context);
        Toolbar.setGlobalToolbar(true);
        // Configure logging, error handling, toolbar behavior, and network defaults
        // Create repositories, services, localization, and shared application context
        // Load saved settings and activities
        // Apply the initial theme, language, and font scale
    }
    @Override
    public void runApp() {
        if (appContext == null) {
            return;
        }
        showHome();
    }
    @Override
    public void start() {
        super.start();
        Form current = CN.getCurrentForm();
        if (current != null) {
            // App-specific refresh logic omitted for brevity
        }
    }
    public void showHome() {
        new HomeForm(appContext).show();
    }
}

The lifecycle is easier to understand visually:

The base Lifecycle class provides the default behavior. We override only the hooks where the app needs extra setup, while calls such as super.init(context) and super.start() keep framework defaults in place.

4.2. Initializing Services and Shared State

Once super.init(context) has applied the lifecycle defaults, our init() method creates the objects that the rest of the app uses. Here, context is provided by Codename One itself; it’s not the AppContext that we create later for the forms.

This approach is a lightweight alternative to a dependency-injection framework: instead of making forms create repositories or know about application setup, we pass them an AppContext with the services, settings, localized text helpers, and navigation methods they need.

First, let’s create the persistence layer and the in-memory store:

ActivityRepository activityRepository = createActivityRepository();
SettingsRepository settingsRepository = createSettingsRepository();
ActivityStore activityStore = new ActivityStore(activityRepository);

ActivityRepository persists the activities, while SettingsRepository stores user preferences. ActivityStore keeps the current list of activities in memory and delegates loading and saving to the repository.

Next, let’s create the services used by the UI:

Resources themeResources = getTheme();
LocalizationService localizationService =
  createLocalizationService(themeResources);
PlaceSearchService placeSearchService = createPlaceSearchService();

getTheme() returns the resources already loaded by the Lifecycle base class. We discuss themes and CSS later; for now, the important point is that we pass theme resources to LocalizationService because the app localization bundles are stored there and then installed into UIManager. PlaceSearchService is the abstraction we later implement with the Geoapify REST API.

Then, let’s load the saved settings and assemble the shared application context:

AppSettings settings = settingsRepository.load();
appContext = createAppContext(
    activityStore,
    settingsRepository,
    localizationService,
    placeSearchService,
    settings
);

AppContext is the object we pass to the forms. It gives them access to shared state, services, localized text, settings, and navigation helpers, without making each form create those dependencies itself.

Finally, let’s apply the saved settings and load the activity list:

applySettings(settings, false);
activityStore.load();

This way, we keep startup code centralized in the lifecycle class, while the forms can focus on UI and user interaction.

4.3. Navigating Between Forms

A layered navigation structure may look more complex than directly creating forms everywhere, but it keeps the app easier to maintain and extend:

AppContext acts as a facade: forms call simple navigation methods, while DailyRoutine creates and shows destination forms. All screens inherit from BaseForm, so toolbar, back commands, and side-menu entries stay consistent.

5. Building Responsive Forms With Layouts and CSS

So, let’s look at the UI model: component trees, layout managers, UIIDs, and CSS.

5.1. Forms, Containers, and Layout Managers

Codename One UIs are easier to understand as component trees. Components live inside containers, and each container uses a layout manager to position its children.

The official Codename One tutorial on positioning components using layout managers gives a deeper explanation. For this app, the relation between the home screen and its component tree is fairly straightforward:

Each form has a title area and a content pane, and it can also expose overlay panes whose transparent background lets content underneath remain visible. The floating action button (FAB) is placed in the layered pane, so it floats above the activity list.

This hierarchy of components and overlapping layers is the basis for pixel-perfect designs in Codename One. Instead of hard-coding positions, we combine containers, layout managers, and CSS styling to adapt to device fragmentation: screen sizes, orientations, densities, safe areas, system font settings, and languages.

5.2. Styling Components With UIIDs and CSS

After defining the component hierarchy, we style components with UIIDs. A UIID is a style identifier assigned to a component, similar to a CSS class name.

The simulator’s Component Inspector helps us inspect the selected component’s class, UIID, layout, coordinates, padding, and margin. To open it, we right-click a component in the simulator and choose Inspect Component:

Here, the selected activity card has UIID ActivityCard and layout LayeredLayout. In Java, we assign the UIID to the card container:

Container card = new Container(new LayeredLayout());
card.setUIID("ActivityCard");

Then, CSS defines its visual appearance:

ActivityCard {
    background: #ffffff;
    background-color: #ffffff;
    color: #1f2933;
    border: 1px solid #d6dde7;
    border-radius: 3mm;
    font-family: "native:MainLight";
    font-size: 3mm;
    margin: 1.2mm 0 1.2mm 0;
    padding: 1.4mm;
}

Codename One CSS is intentionally close to web CSS, but has its own properties and conventions. Here, we use native fonts and dimensions in millimeters. The card appears pink in the screenshot because the Component Inspector highlights the selected component.

We can also define pressed and selected states and separate dark-mode rules:

ActivityCardPressed,
ActivityCard.pressed,
ActivityCard.selected {
    [...]
}
@media (prefers-color-scheme: dark) {
    ActivityCard {
        [...]
    }
    ActivityCardPressed,
    ActivityCard.pressed,
    ActivityCard.selected {
        [...]
    }
}

The UIID is the bridge between the component tree and the final appearance of the app.

5.3. Supporting Small Screens, Large Screens, and Font Scaling

If the user increases the system font size or changes the app font scale from the Settings form, labels may need more room, cards may become taller, and scrollable containers must absorb the extra content. This is useful on large screens, but can become problematic on small screens.

The complete source code includes defensive helpers for edge cases where single-line text doesn’t fit. These helpers can cap the font size so text stays within the available width. This is useful, but it adds complexity and should be evaluated on a case-by-case basis.

From this point on, we focus on the main Codename One patterns rather than implementation details. Daily Routine is the reference example, but the goal is to learn how to structure Codename One apps in general.

6. Building the Core Activity Workflow

The activity workflow gives us the core of the app: a model, a store, a list screen, an editor, and a details screen.

6.1. Modeling Activities

The central domain object is Activity, implemented as a Java record:

public record Activity(
        String id,
        String title,
        ActivityCategory category,
        LocalDate date,
        LocalTime time,
        String notes,
        boolean completed,
        PlaceInfo place,
        Instant updatedAt
) [...]

Categories are modeled with an enum. Each category has a storage code, a localization key, and a sort order:

public enum ActivityCategory {
    APPOINTMENT("appointment", "category.appointment", 0),
    ROUTINE("routine", "category.routine", 1),
    WORK("work", "category.work", 2),
    [...]
}

This keeps the model simple to persist, localize, and display.

6.2. Listing Activities on the Home Form

The home screen reads activities from ActivityStore and rebuilds the list when data changes.

Unlike a web page, a Codename One form doesn’t always update the visible UI immediately after we change the component hierarchy. This is a design choice that helps reduce unnecessary layout work, especially in complex component trees. The final call to revalidate() tells Codename One to lay out the updated listContainer again, so the changes are reflected on screen:

private void refreshList() {
    List<Activity> activities =
            context.getActivityStore().getActivitiesInInsertionOrder();
    listContainer.removeAll();
    for (Activity activity : activities) {
        listContainer.add(createCard(activity));
    }
    listContainer.revalidate();
}

The form doesn’t load JSON directly. Instead, it uses AppContext to access the current ActivityStore, keeping UI code focused on rendering and user interaction.

Each activity is displayed as a card:

private Container createCard(Activity activity) {
    Container card = new Container(new LayeredLayout());
    card.setUIID("ActivityCard");
    Container content = new Container(new BorderLayout());
    Container textColumn = new Container(BoxLayout.y());
    // Add icon, title, category, schedule, place, and status labels
    content.add(BorderLayout.CENTER, textColumn);
    card.add(content);
    Button overlay = createCardOverlayButton(
            "activityCard-" + activity.id(),
            () -> context.showActivityDetails(this, activity)
    );
    card.add(overlay);
    return card;
}

The card structure, CSS styling, and navigation follow the same pattern: component tree for structure, UIID for appearance, and AppContext for navigation.

6.3. Adding and Editing Activities

The editor form handles both new and existing activities. When saving, it validates required fields, builds an ActivityDraft, converts it into an Activity, and stores it:

private void saveActivity() {
    String title = titleField.getText() == null
            ? ""
            : titleField.getText().trim();
    if (title.length() == 0) {
        Dialog.show(
                context.text("validation.title"),
                context.text("validation.activity.title"),
                context.text("ok"),
                null
        );
        return;
    }
    ActivityDraft draft = new ActivityDraft();
    draft.setTitle(title);
    draft.setCategory(selectedCategory());
    draft.setNotes(notesArea.getText());
    draft.setCompleted(completedSwitch.isValue());
    draft.setPlace(selectedPlace);
    String id = existingActivity == null
            ? IdGenerator.newId()
            : existingActivity.id();
    context.getActivityStore().save(draft.toActivity(id));
    context.showHome();
}

The exact form has more fields, such as date and time. The pattern is that the form edits a temporary state, while the store receives a complete activity only when the user confirms.

6.4. Showing Activity Details

The details screen shows one activity and offers actions such as editing or toggling completion:

public void toggleCompleted() {
    context.getActivityStore().toggleCompleted(activityId);
    refresh();
}

Since Activity is immutable, the store toggles completion by creating a new instance and saving it.

The edit action uses the same navigation pattern:

public void editCurrentActivity() {
    context.showActivityForm(this, currentActivity());
}

At this point, the core workflow is complete: list, editor, and details form.

7. Saving and Testing Data Locally

The activity workflow now works, but data must survive restarts.

7.1. Persisting Activities as JSON

The UI doesn’t interact with files directly. It calls the store, and the store delegates persistence to ActivityRepository:

public class ActivityRepository {
    public List<Activity> loadActivities() throws IOException {
        String path = filePath();
        if (!FileSystemStorage.getInstance().exists(path)) {
            return new ArrayList<>();
        }
        String json = IOUtil.readUtf8File(path);
        return codec.decodeActivities(json);
    }
    public void saveActivities(List<Activity> activities) throws IOException {
        IOUtil.writeUtf8File(
            filePath(),
            codec.encodeActivities(activities)
        );
    }
}

The repository keeps forms independent from file storage, and its logic can be tested without involving forms or user interaction.

The JSON conversion is handled by a codec:

String json = codec.encodeActivities(activities);
List<Activity> activities = codec.decodeActivities(json);

Thus, the model stays independent, the repository owns persistence, and the UI works with domain objects.

7.2. Using the App Home Directory

Codename One provides an app-specific home directory for local files. The lifecycle creates the repositories, while each repository owns its storage path:

protected ActivityRepository createActivityRepository() {
    return new ActivityRepository();
}
protected SettingsRepository createSettingsRepository() {
    return new SettingsRepository();
}

The activity repository stores JSON under the app home directory:

public String filePath() {
    return appHomePath() + "activities.json";
}

The settings repository follows the same idea:

protected String filePath() {
    return CN.getAppHomePath() + "settings.json";
}

In the complete implementation, both repositories support a test-only override, so tests can write to a dedicated location.

This keeps persistence portable: the actual location differs between targets, but the app uses the same repository abstraction. In the simulator, the JSON files are easy to inspect and edit; on real devices and browser builds, storage is platform-specific and usually less convenient to inspect directly.

7.3. Testing the Repository

Codename One includes a testing API based on AbstractTest, usable through the simulator and device testing workflow.

Among the tests in the complete source code, one focused example verifies local persistence:

public class ActivityRepositoryRoundTripTest extends AbstractTest {
    @Override
    public boolean runTest() throws Exception {
        String path = FileSystemStorage.getInstance().getAppHomePath()
                + "tests/activity-round-trip-"
                + System.currentTimeMillis()
                + ".json";
        TestActivityRepository repository = new TestActivityRepository(path);
        List<Activity> activities = new ArrayList<>();
        Activity original = createActivity();
        activities.add(original);
        try {
            repository.saveActivities(activities);
            List<Activity> loaded = repository.loadActivities();
            assertEqual(1, loaded.size(), "Exactly one activity should be loaded");
            assertEqual(original, loaded.get(0), "The activity should survive a JSON round trip");
            return true;
        } finally {
            repository.reset();
        }
    }
}

TestActivityRepository redirects persistence to a test-specific file. Codename One also supports JUnit 5 for simulator-side tests on the JavaSE port, while AbstractTest remains the most portable option inside the Codename One runtime model.

8. Adding Place Autocomplete, REST, and Maps

Finally, we add place search and map display: a concise example of REST, JSON parsing, and embedded web content.

8.1. Searching Places With Geoapify

The editor lets the user search for a place and attach it to an activity. We use Geoapify because it provides autocomplete and map preview APIs, has a generous free tier, and enables the creation of a free API key without a credit card.

The complete source code includes a free example key, lightly obfuscated with XOR, so the demo can run out of the box. XOR isn’t security; it only avoids storing the key as plain text. For production, we should use a private key. Even better, the key shouldn’t live inside the app: the app should call the backend, and the backend should call Geoapify.

The form depends on a service interface, not on Geoapify directly:

public interface PlaceSearchService {
    SearchHandle search(
            AppContext context,
            String query,
            SuccessCallback<List<PlaceSuggestion>> onSuccess,
            FailureCallback<List<PlaceSuggestion>> onFailure
    );
    interface SearchHandle {
        void cancel();
    }
}

The implementation builds an autocomplete URL and submits a Codename One network request:

private String buildAutocompleteUrl(AppContext context, String query) {
    StringBuilder builder = new StringBuilder(
            "https://api.geoapify.com/v1/geocode/autocomplete?"
    );
    builder.append("text=").append(Util.encodeUrl(query));
    builder.append("&format=geojson");
    builder.append("&limit=").append(AppConfig.GEOAPIFY_RESULT_LIMIT);
    builder.append("&lang=").append(context.getSettings().languageCode());
    builder.append("&apiKey=").append(AppConfig.geoapifyApiKey());
    return builder.toString();
}

Again, the form depends on an application service, while provider-specific code stays in one place.

When working with callbacks and UI updates, we should also keep Codename One’s EDT (Event Dispatch Thread) in mind, so slow work, such as a network request, doesn’t block the interface.

8.2. Parsing the REST Response

Geoapify returns GeoJSON. The service extracts only the fields the app needs and creates PlaceSuggestion objects:

@SuppressWarnings("rawtypes")
private List<PlaceSuggestion> parseSuggestions(String json) throws IOException {
    JSONParser parser = new JSONParser();
    Map<String, Object> root = parser.parseJSON(new StringReader(json));
    List<PlaceSuggestion> suggestions = new ArrayList<>();
    List features = (List) root.get("features");
    // Read properties, geometry, and coordinates
    // Convert each feature into a PlaceSuggestion
    return suggestions;
}

The form receives domain objects, not raw JSON maps.

8.3. Showing a Map Preview With BrowserComponent

After the user selects a place, GeoapifyMapView checks whether a native browser component is available, then shows a Leaflet page:

browser = new BrowserComponent();
browser.setPinchToZoomEnabled(true);
browser.setNativeScrollingEnabled(true);
browser.setPage(buildMapHtml(place), null);
add(BorderLayout.CENTER, browser);

The page loads Leaflet, uses Geoapify map tiles, centers the map, and adds a marker:

private String buildMapHtml(PlaceInfo place) {
    String tileUrl = "https://maps.geoapify.com/v1/tile/"
            + AppConfig.GEOAPIFY_TILE_STYLE
            + "/{z}/{x}/{y}.png?apiKey="
            + AppConfig.geoapifyApiKey();
    return "<!doctype html><html><head>"
            + "<link rel=\"stylesheet\" "
            + "href=\"https://unpkg.com/leaflet@1.9.4/dist/leaflet.css\"/>"
            + "</head><body><div id=\"map\"></div>"
            + "<script src=\"https://unpkg.com/leaflet@1.9.4/dist/leaflet.js\"></script>"
            + "<script>"
            + "var map = L.map('map').setView(["
            + place.latitude() + "," + place.longitude() + "],"
            + AppConfig.MAP_ZOOM + ");"
            + "L.tileLayer('" + tileUrl + "').addTo(map);"
            + "L.marker([" + place.latitude() + ","
            + place.longitude() + "]).addTo(map);"
            + "</script></body></html>";
}

The rest of the app works with a normal Codename One component, while the embedded browser handles the map. If native browser support isn’t available, the complete source code falls back to a static Geoapify map image.

9. Conclusion

In this tutorial, we built a realistic Codename One application with Java 17 and Maven. Furthermore, we used the Daily Routine application to understand the main patterns behind Codename One development: lifecycle, shared context, navigation, forms, layout managers, UIIDs, CSS, persistence, testing, REST, and map previews.

The same design principle appeared repeatedly: keep forms focused on UI and user interaction, and move persistence, networking, localization, settings, and reusable logic into small services and repositories.

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

       

Comments

• In reply to Steve Hannah. Hey, Steve. Thanks for the ... by Ulisses Lima
• Holy cow. Great comprehensive tutorial, Francesco! An ... by Steve Hannah