Coder Legion - Recent posts tagged java

Reliable Event-Driven Architecture in Spring Boot: Outbox, Inbox, Retries, and Idempotency

Thu, 29 Oct 2026 00:07:44 +0000

Why publishing an event is only the beginning of building a reliable distributed system.

Building an event-driven application with Spring Boot is relatively straightforward.

You create a Kafka producer, publish an event, implement a consumer, and process the message.

Everything works beautifully during development.

Then production introduces the situations your happy-path tests never covered.

What happens when the database transaction commits, but Kafka is unavailable? What happens when the consumer processes an event successfully but crashes before acknowledging it? What happens when two application instances attempt to process the same message?

These aren't unusual edge cases. They're fundamental challenges of distributed systems.

And solving them requires more than adding a retry annotation.

Let's explore the reliability boundaries behind a production-ready event-driven architecture.

1. The dual-write problem

Imagine a payment service that must perform two operations:

Save a payment in PostgreSQL.
Publish a PaymentCompleted event to Kafka.

A straightforward implementation might look like this:

@Transactional
public void completePayment(Payment payment) {
    paymentRepository.save(payment);
    kafkaTemplate.send(
        "payment.completed",
        new PaymentCompleted(payment.getId())
    );
}

The code looks reasonable, but there's a serious problem.

The database transaction and Kafka publication do not share a single atomic transaction.

Several outcomes are possible:

The database commits, but the event is never published.
Kafka accepts the event, but the database transaction rolls back.
Publication times out, leaving the application uncertain whether Kafka received the event.

Adding retries doesn't eliminate the fundamental inconsistency.

The problem is not whether Kafka is reliable. The problem is coordinating two independent systems.

The transactional outbox

The transactional outbox pattern changes the transaction boundary.

Instead of publishing directly to Kafka, the application writes an outbox record within the same database transaction as the business operation.

Payment Service
      |
      v
Database Transaction
      |
      +-- Save Payment
      |
      +-- Save Outbox Event
      |
      v
    Commit
      |
      v
Outbox Publisher
      |
      v
    Kafka

Either the payment and outbox event are committed together, or neither is committed.

A separate publisher retrieves pending outbox records and delivers them to Kafka.

This solves the atomicity problem between the business state and the durable intent to publish.

It does not guarantee that an event will be published exactly once.

That distinction matters.

2. Why the outbox still needs idempotency

Consider this sequence:

The outbox publisher sends an event to Kafka.
Kafka successfully accepts it.
The application crashes before marking the outbox record as published.
The publisher restarts and sends the event again.

Kafka may now contain two copies of the same logical event.

This is a normal consequence of at-least-once delivery.

The correct response is not to assume duplicates can always be prevented.

Instead, design consumers that can safely tolerate them.

3. The transactional inbox

An inbox provides a durable record of incoming events that have already been processed.

Each event should carry a stable identifier, such as an event ID generated when the logical event is created.

When the consumer receives a message, it checks whether that event has already been processed.

A simplified model looks like this:

Kafka Event
     |
     v
Consumer
     |
     v
Database Transaction
     |
     +-- Claim Event ID in Inbox
     |
     +-- Apply Business Changes
     |
     +-- Mark Inbox Completed
     |
     v
   Commit

The important part is the transaction boundary.

The inbox record and the business changes must participate in the same transaction when using the same transactional database.

Otherwise, a consumer can record an event as completed even though its business operation failed.

A subtle but important case

Suppose a consumer receives PaymentCompleted, updates an invoice, and produces InvoicePaid.

Now the reliability boundary becomes:

Inbox + Business State + Outbox

All three should be committed atomically.

Incoming Event
      |
      v
Database Transaction
      |
      +-- Inbox Claim
      |
      +-- Update Invoice
      |
      +-- Create Outbox Event
      |
      v
    Commit
      |
      v
Outbox Publisher
      |
      v
Outgoing Event

This is one of the most useful patterns for building dependable event-driven workflows.

The inbox protects the incoming side. The outbox protects the outgoing side.

Neither eliminates the need for careful business-level idempotency, especially when external side effects are involved.

4. Retries are a lifecycle, not just an annotation

Retries are often introduced with a simple configuration:

@Retryable(
    retryFor = TransientException.class,
    maxAttempts = 3
)

For short-lived operations, that can be perfectly reasonable.

But what happens when a dependency is unavailable for 30 minutes? What happens when the application restarts? What happens when an event requires operator intervention?

An in-memory retry loop cannot reliably manage every long-running failure scenario.

For durable asynchronous processing, retries should be modeled as persistent state.

A typical lifecycle might look like this:

PENDING
   |
   v
PROCESSING
   |
   +---- Success ----> COMPLETED
   |
   +---- Retryable failure
   |           |
   |           v
   |      RETRY_SCHEDULED
   |           |
   |           v
   |        PENDING
   |
   +---- Terminal failure
               |
               v
             FAILED

Each attempt can record useful information:

Attempt count
Next eligible execution time
Last failure category
Processing status
Relevant timestamps

Exponential backoff with jitter helps avoid repeatedly overwhelming an unhealthy dependency.

But retry policies should distinguish transient failures from permanent ones.

Retrying an invalid business request a thousand times won't make it valid.

5. Multi-instance processing changes everything

A background publisher may work perfectly when there's only one application instance.

Then the service is scaled to three pods.

All three publishers query the same pending records.

Without coordination, multiple instances may attempt to publish or process the same work concurrently.

One common PostgreSQL technique is:

SELECT id
FROM outbox_event
WHERE status = 'PENDING'
ORDER BY created_at
FOR UPDATE SKIP LOCKED
LIMIT 100;

SKIP LOCKED allows concurrent workers to skip rows already locked by another transaction.

This can improve coordination between workers, but it's not a complete delivery protocol.

The design must still consider:

How work is claimed and how long claims remain valid
Transaction duration and lock ownership
Recovery after a worker crashes
Retry scheduling and fairness
Ordering requirements
Duplicate delivery

For example, holding database locks across a slow network call can increase contention and create unnecessarily long transactions.

A robust implementation may use short claim transactions, explicit processing ownership, and recovery mechanisms rather than keeping database transactions open while publishing.

Concurrency control and delivery guarantees are related, but they are not interchangeable.

6. Exactly-once is not an end-to-end promise

It's tempting to describe an event-driven system as exactly-once.

But exactly-once semantics depend on the boundaries being discussed.

Kafka transactions can provide guarantees for supported Kafka operations. A PostgreSQL transaction can atomically update records within PostgreSQL.

Neither automatically makes a database update, Kafka publication, HTTP request, and external payment operation one globally atomic action.

A more useful engineering goal is:

At-least-once delivery with effectively-once business outcomes wherever possible.

That typically requires durable event identities, transactional inbox processing, idempotent business operations, and explicit handling of external side effects.

For payment systems, this distinction is particularly important.

Processing the same event twice must not mean charging a customer twice.

7. Observability is part of reliability

A system that retries failures silently can appear healthy while accumulating thousands of unprocessed events.

Operational visibility should answer questions such as:

How many events are pending?
How old is the oldest unpublished event?
How many retries are scheduled?
Which events are permanently failing?
Are workers making progress?
Are duplicates being detected?
Is event processing latency increasing?

Metrics, structured logs, tracing, and operator-facing failure information are not optional extras for a production system.

They help distinguish a temporary delay from a workflow that has stopped making progress.

A reliable system should make failure visible and recovery understandable.

8. Putting these patterns together

A practical architecture combines several responsibilities:

Business Operation
       |
       v
Transactional Outbox
       |
       v
Durable Publisher
       |
       v
Message Broker
       |
       v
Transactional Inbox
       |
       v
Business Processing
       |
       +-- State Changes
       |
       +-- Optional New Outbox Events
       |
       v
Commit

Around that flow, we need retry policies, concurrency coordination, idempotency, recovery, and observability.

Each component solves a different failure mode.

The outbox prevents losing the intent to publish when business data commits.

The inbox protects consumers from repeated processing.

Retries help transient failures recover.

Concurrency controls coordinate multiple workers.

Observability makes the system operable.

None of these patterns should be treated as magic.

Their value comes from understanding exactly which failure boundary each one protects.

9. Why I built NERV Event

After working with event-driven enterprise applications, I wanted these reliability concerns to be reusable rather than repeatedly implemented in individual services.

That led to NERV Event, an open-source Java and Spring Boot library focused on patterns such as transactional outbox, inbox processing, retries, and idempotency.

The goal isn't to hide distributed-systems complexity behind annotations.

It's to provide reusable infrastructure while keeping the reliability model explicit.

GitHub: https://github.com/czetsuyatech/nerv-event

The library is one possible implementation of these ideas. The architectural principles are useful regardless of which framework or library you choose.

Final thoughts

Publishing an event is easy.

Building a system that behaves predictably when databases, brokers, application instances, and downstream dependencies fail is much harder.

Reliable event-driven architecture begins with a simple question:

What happens if the application crashes at this exact point?

Ask that question at every transaction boundary, every message acknowledgment, and every external call.

The answers will reveal where durability, idempotency, retries, and recovery are actually needed.

I'd be interested to hear how other teams approach this: Do you use a transactional inbox alongside your outbox, or do you handle consumer idempotency directly in your business tables?

Originally published on CzetsuyaTech. Explore more articles on Java, Spring Boot, distributed systems, and software architecture there.

Oracle Plans Post-Quantum TLS for Java 8 and 11 in Late 2027, and Wants Testers Now

Tue, 27 Oct 2026 23:35:19 +0000

Security teams are starting to ask a question platform teams don't like: what's our plan for post-quantum encryption? For shops still running Java 8 or 11, the answer has mostly been a shrug.

At Oracle AI World in Las Vegas this week, I got a firmer one. I sat down with Georges Saab, senior vice president of Oracle's Java Platform Group; Donald Smith, vice president of product management for Java Platform; and Bernard Traversat, vice president of software development for the Java Platform Group. I asked about the schedule for hybrid post-quantum key exchange in TLS 1.3.

The feature is generally available in JDK 27. It arrived in JDK 25 with the October critical patch update. I laid out what comes next as I understood it: Java 21 and 17 in the first half of 2027, Java 11 and 8 in the second half. The team confirmed that was right.

Those are half-year windows, not release dates. And there is a condition attached.

Customers have been asking Oracle for post-quantum support as fast as possible. Now that it ships, the team wants them to use it. Many reply that they'd rather have it backported first. Oracle's answer is to test what already exists.

Smith said the key to stability is "just getting people using what we have, even though it's only in the latest."

There is a chicken-and-egg problem. The specification was only finalized in February, so many of the endpoints a Java client talks to don't support the hybrid exchange yet. Smith called the backport itself the hard part. For the next two to three months, the team is focused on stability so the backport starts from solid ground.

Feedback comes from two places. One is customers. The other is a group in OpenJDK that works with major third-party library projects, including Apache and Eclipse, and with the OpenSSL community.

Performance is the other worry. Java 8 shipped years before TLS 1.3 was final, and the team had to backport it. That taught them the backport has to be stable and fast on old hardware. A team tracks performance benchmarks on every release, including the new algorithms, he said. He gave no numbers.

If you run Java 8 or 11, waiting for the backport and then starting your testing is the slow path. Point a JDK 25 or 27 client at your post-quantum-capable endpoints, such as a gateway or proxy, and report what breaks. Oracle says it needs that feedback.

Backports aren't the only way out. Saab said he now regularly meets teams where most workloads are on Java 21.

He described the upgrade ladder this way. Going from 8 to 11 is the hardest step. Each step after that gets easier. "21 to 25 super easy," he said. The platform has been changed so that code survives upgrades better than it used to.

When teams do get stuck, the cause is usually outside the JDK. One is third-party libraries that nobody maintains. The other is the oldest problem: "when people used APIs that were not part of the public API," Saab said.

For finding those problems, Traversat pointed to Oracle's Java Management Service. It analyzes the APIs an application uses and reports deprecated APIs, changed behavior, and JVM argument changes between versions, such as 11 to 17 or 25. After that, he said, you still run the testing you use to certify the application.

I also asked how a team should verify code that an AI agent has refactored. Smith was direct: "I don't have a swift answer for that one." Saab said migration tooling is being built by other people. His team has helped groups inside Oracle migrate, to learn what the JDK could do better. Would the JDK team build migration tools itself? "I'm not saying we will never do that," he said.

So if you plan to use agents on a legacy Java codebase, the tools will come from outside the JDK. Verification still falls to your test suite.

The other date on your calendar is the patch schedule. Oracle announced in the spring that it is moving to monthly security updates across the company, not just for Java. Smith said the Java team will phase this in. "Next year we'll probably do 10 security updates and then it'll be every month thereafter," he said.

AI is part of the reason. "It's clear that AI has increased the rate at which you find vulnerabilities," Smith said. He added that it has also improved the team's ability to fix them.

He worried at first that system administrators would push back. They haven't. "The feedback is like nobody is surprised by this," he said. Some organizations will still have to adapt. A team on a quarterly change window is the obvious example.

Two items have no dates: non-hybrid key exchange and Merkle certificates. Smith said the work follows the IETF specifications and he wasn't sure enterprises could plan around it. His advice was to follow OpenJDK development. The issue trackers are open, and code already exists.

That caution is deliberate. "Never get ahead of the spec," Smith said. He pointed to the original java.util.Date as the example. An early implementation gained traction, it wasn't the best design, and the proper replacement took 10 to 15 years to arrive. Traversat added that anything shipped in the platform has to be supported for years, so Oracle moves conservatively.

For Java teams, the planning date is the second half of 2027 for Java 8 and 11. The work that decides whether that date holds starts now, and Oracle is asking for your help.

Polar Bear Cache: Local Caching Without Repeated Remote Calls

Mon, 26 Oct 2026 10:07:01 +0000

Shared storage provides the source of truth. Local caches provide speed. Events help keep cache state in sync.

Project: Polar Bear Cache — GitHub repository

In my previous discussions about microservices, I explored how shared storage and event-driven synchronization can work together to manage distributed session state.

This time, I want to focus on another part of the problem: caching frequently accessed data across multiple service instances.

The Problem: Faster Reads, Distributed Cache Invalidation

In a microservices architecture, multiple service instances often need the same data, especially data that is read frequently but updated relatively infrequently.

A distributed cache can reduce database load, but accessing it still involves network round trips and potentially serialization and deserialization overhead.

So, what if each service instance could keep frequently accessed data in its own local cache, while receiving notifications when that data changes elsewhere?

That is the idea behind Polar Bear Cache, an open-source Java caching library designed to work with Spring's familiar cache annotations.

The Design: Local Cache + Event-Driven Invalidation

Each service instance maintains its own local cache. When data changes, an event service can notify other instances that specific cache entries need to be invalidated.

The key principle is simple:

Broadcast invalidation events, not the entire cached data.

Polar Bear Cache integrates with Spring's cache annotations:

@Cacheable — Returns a cached value when available, or executes the underlying method to load it when the value is missing.
@CachePut — Updates the local cache and, when event-service integration is configured, notifies other instances to invalidate the corresponding entry.
@CacheEvict — Evicts cached data locally and, when event-service integration is configured, notifies other instances to invalidate their corresponding entries.

For example, when a product is updated:

The application updates the source of truth and its local cache.
It publishes a cache-invalidation event through the event service.
Other service instances receive the event and evict the corresponding local entry.
Their next read loads the data again from the source of truth.

This allows repeated reads to stay local in the common case, while cross-instance communication is used to coordinate invalidation when data changes.

When Does This Approach Make Sense?

This design is particularly suitable for:

Read-heavy workloads with relatively infrequent updates.
Applications running multiple service instances, each with its own local cache.
Use cases where brief delays in cache invalidation are acceptable.

There is an important trade-off: event-driven invalidation is asynchronous. Between a data update and the time other instances process the invalidation event, stale data may still be served.

Polar Bear Cache does not guarantee strong consistency across service instances.

Depending on the application, you may also need to consider event-delivery reliability, duplicate events, cache expiration, and recovery strategies when a service instance misses an event.

The goal is not to eliminate every consistency trade-off, but to make local caching practical in distributed applications without requiring every read to go through a remote cache.

Why “Polar Bear”?

The name comes from a somewhat optimistic engineering idea:

Local caching
→ Fewer remote cache requests and network round trips
→ Potentially more throughput from the same resources
→ Potentially fewer servers needed for a given workload
→ Lower energy consumption and greenhouse gas emissions
→ Maybe we can help save polar bears. 🐻❄️🧊

Of course, the actual impact depends on workload characteristics, infrastructure, and deployment choices. Performance improvements do not automatically translate into lower energy consumption, but I like the idea that better resource efficiency could benefit both applications and the environment.

I'd Love to Hear Your Thoughts

I'm interested in how other engineers approach local caching in distributed systems.

How do you handle cache invalidation across service instances?
Do you prefer event-driven invalidation, short TTLs, versioned keys, or a combination?
What failure scenarios would you consider essential to address in this design?

If you're interested in the implementation, feedback and technical discussion are very welcome.

Less remote access, more ice. 🐻❄️🧊

Java #Spring #Microservices #Caching #DistributedSystems #OpenSource

Sync Session: Rethinking Session Management in Microservices

Mon, 26 Oct 2026 09:17:47 +0000

Sync Session: Rethinking Session Management in Microservices

Project: Sync Session on GitHub

Shared storage provides the source of truth. Local caches provide performance. Events synchronize session state across service instances.

Since I started working with microservices in 2016, I have continuously explored and refined different approaches to session management.

One question has remained particularly important to me:

How can every service independently verify a user's session without turning authentication into a bottleneck?

The Challenge: Security vs. Performance

In a microservices architecture, services frequently communicate with one another. From a zero-trust perspective, a service should not blindly trust a userId simply because another service included it in a request.

Instead, each service should validate the session and enforce the appropriate authorization rules.

However, querying a shared database every time a service needs to validate a session can increase latency and database load, especially when requests pass through multiple services.

This creates a practical engineering challenge: how do we preserve session validity and revocation capabilities while reducing the cost of repeated remote access?

That question led me to develop Sync Session, an open-source session management library for Spring Boot.

The Design

The design combines four main components:

RDBMS as shared storage: The persistent source of truth for session state.
Local cache: Each service instance maintains a local copy of session data to reduce repeated database queries.
Event service: Session changes trigger events that allow other service instances to invalidate their corresponding local cache entries.
Session ID propagation: The session ID can be passed through a cookie or HTTP header, depending on the application's request flow.

The session itself is intentionally kept small. Rather than embedding a large amount of user data and permissions into the session, the application uses a protected session ID to retrieve the associated authenticated identity.

User information and authorization data remain under the responsibility of the relevant systems, where they can be updated independently.

This separation helps avoid relying on outdated user information stored in a session and supports centralized session revocation.

What Does This Approach Support?

The project aims to address several practical requirements:

Distributed session management across multiple service instances.
Sliding session expiration, allowing the expiration time to be extended according to the configured policy.
Administrative session revocation, enabling an administrator to force a user to log out.
Synchronization of session invalidation across service instances.
Reduced database access through local caching.

The key idea is that services can validate sessions locally in the common case, while shared storage and event-driven invalidation help coordinate changes.

Performance Reference

In my MySQL load tests, I measured the following results under a workload involving 100 threads and 1 million sessions:

Operation	Measured throughput
Session creation	~15,533 operations/sec
Local cache access	~20.01 million operations/sec
Direct database queries	~69,278 operations/sec

All 1 million session creation operations completed successfully in this test, with no reported failures.

Under these particular test conditions, local cache access achieved approximately 289 times the throughput of direct database queries.

These numbers are reference measurements from my test environment, not universal performance guarantees. The results depend on hardware, database configuration, query patterns, cache implementation, concurrency, and the exact benchmark methodology.

The comparison also measures different access paths, so it should not be interpreted as an end-to-end authentication benchmark.

Consistency and Security Trade-offs

Local caching introduces an important limitation: event-driven invalidation is asynchronous.

When a session is revoked, another service instance may still have a cached copy until it processes the invalidation event. Event delivery failures or temporary network partitions can extend this window.

For security-sensitive systems, this behavior needs to be considered explicitly. Depending on the threat model, additional safeguards may be necessary, such as bounded cache lifetimes, reliable event delivery, recovery mechanisms, or synchronous validation for particularly sensitive operations.

Likewise, validating a session is not the same as authorizing every operation. Services must still enforce their own authorization requirements, and internal service communication must be authenticated appropriately.

The goal is not to claim that local caching removes every security or consistency challenge. It is to explore a practical balance between independent session validation, efficient reads, and distributed session invalidation.

A Design Principle Worth Discussing

The principle behind Sync Session can be summarized as:

Shared storage for correctness. Local cache for performance. Events for synchronization.

This is not the only valid architecture, and it may not be appropriate for every workload. I am sharing it because session management is a recurring challenge in distributed systems, and I believe the trade-offs deserve discussion beyond the implementation of any single library.

I'd especially like to hear from engineers who have built authentication infrastructure at scale:

How do you handle session revocation across multiple service instances?
Would you accept a short invalidation delay, or require immediate revocation for every request?
How do you balance database load, cache consistency, and security requirements?
What failure scenarios would you consider essential to address in this design?

I'm happy to discuss the implementation, benchmark methodology, and architectural trade-offs.

LangGraph4j Annotations: Organize Graph Behavior with Action Catalogs

Fri, 23 Oct 2026 08:50:30 +0000

From graph lambdas to action catalogs

When building a workflow with LangGraph4j, I usually start with a few nodes and straightforward transitions. As the workflow grows, the graph definition can become crowded with action implementations, configuration access, and routing logic.

Moving those actions into separate classes helps. The new annotations provide a convenient way to organize them: ordinary Java methods become node actions and edge conditions, grouped into an Action Catalog.

Available from LangGraph4j 1.9.6, @NodeAction and @EdgeCondition belong to langgraph4j-core, in the org.bsc.langgraph4j.annotation package. This guide follows the official annotations documentation.

What an Action Catalog contains

An Action Catalog is a Java class implementing the ActionCatalog marker interface. Its public annotated methods describe the available behavior:

@NodeAction identifies work that produces updates to graph state.
@EdgeCondition identifies a routing decision, optionally accompanied by state updates.

ActionCatalogRepository.of(catalog) discovers those methods, including inherited public methods, and adapts them into actions that LangGraph4j can execute.

The catalog owns behavior; the StateGraph definition owns the connections. Registering a catalog does not automatically create a workflow. We still choose which actions become nodes, where execution starts, and how each routing result maps to a destination.

Both annotations support two optional attributes:

Attribute	Purpose
`name`	Lookup name in the repository. An empty or blank value uses the Java method name.
`description`	Descriptive metadata; it does not control execution or routing.

An explicit name is useful when the catalog should expose a stable action name even if its Java method is renamed. Give overloaded annotated methods distinct names. Keep names unique within the node actions and within the edge conditions; these are separate lookup maps.

An example

Let's build a small document workflow: prepare some text, decide whether review is requested, and optionally mark it as reviewed. We intentionally keep it simple so no LLM or external service is needed than we can focus on how the catalog connects to the graph.

Define the catalog

We create a new DocumentCatalog class assuming it uses the standard AgentState, so there is no custom state class to introduce first.

public final class DocumentCatalog implements ActionCatalog {
    // Trims the supplied text and records the executing graph node.
    @NodeAction(name = "prepare", description = "Prepare the document text")
    public Map<String, Object> prepareDocument(
            AgentState state, RunnableConfig config) {
        // Missing text is allowed in this example and becomes an empty document.
        String text = state.<String>value("text").orElse("");

        // Return updates for the engine to merge before it evaluates routing.
        return Map.of("text", text.strip(), "preparedBy", config.nodeId());
    }

    // Selects a review route and records the decision without mutating state.
    @EdgeCondition(description = "Review only when requested")
    public Command route(AgentState state) {
        // Omitted needsReview means this example can finish after preparation.
        boolean needsReview = state.<Boolean>value("needsReview").orElse(false);
        String route = needsReview ? "reviewRequired" : "complete";

        // These are routing keys; the graph maps them to node IDs or END.
        return new Command(route, Map.of("reviewDecision", route));
    }

    // Marks the document as reviewed; this example performs no human interaction.
    @NodeAction
    public Map<String, Object> review(AgentState state) {
        return Map.of("reviewed", true);
    }
}

There are some details to notice here.

The @NodeAction annotated methods returns a partial state update as required by LangGraph4j node actions classic.
The @EdgeCondition annotated methods return a Command as required by LangGraph4j classic edge conditions.
The method prepareDocument is registered as prepare because it has an explicit annotation name. The other methods use their Java names: route and review.
The route returns a Command that lets the condition record reviewDecision as well as select the next route.
The review action is deliberately a local marker. A real Human-in-the-Loop review would also need the appropriate interruption, persistence, and resume behavior.

Resolve the catalog and connect the graph

Let's build the DocumentWorkflow class alongside the catalog:

public final class DocumentWorkflow {
    // Builds the workflow and prints the final state for an input requiring review.
     public static void main(String[] args) throws Exception {
        // Register before resolving names; actions execute on this catalog instance.
        final var repository = ActionCatalogRepository.of(new DocumentCatalog());

        // Define the topology explicitly, mapping each possible routing result.
        final var graph = new StateGraph<>(AgentState::new)
                .add(repository.node("prepare"))
                .add(repository.node("review"))
                .addEdge(START, "prepare")
                .add(repository.edge("prepare", "route",
                        EdgeMappings.builder()
                                .to( "review", "reviewRequired" )
                                .toEND( "complete" )
                                .build()))
                .addEdge("review", END)
                .compile(); // Resolve action factories before executing the graph.

        // A fresh invocation requests review and supplies the text to prepare.
        graph.stream(
                    GraphInput.args(Map.of(
                            "text", "  A document to review.  ",
                            "needsReview", true)),
                    RunnableConfig.empty())
            .reduce( (a,b) -> b )
            .thenAccept( System.out::println );

    }

}

There are some details to notice here.

repository.node("prepare") and repository.node("review") supplies a complete graph node whose ID and action lookup name are the same.
Similarly, repository.edge(...) supplies a complete conditional edge. Both work with the StateGraph.add(...) methods.

This gives us a small example to make in evidence how graph definition change using annotations.

Reuse an action under another node ID

Sometimes, a graph reuses an action while assigning a specific name to the role it plays within a particular workflow. The repository.nodeAction(...) method is provided specifically for this purpose; it retrieves the action factory without assigning a node ID.

// Alternative preparation node: graph identity differs from the catalog lookup name.
var workflow = new StateGraph<>(AgentState::new)
        .addNode("prepareIncomingDocument", repository.nodeAction("prepare"))
        .addEdge(START, "prepareIncomingDocument")
        .addEdge("prepareIncomingDocument", END);

This fragment replaces the earlier definition and uses the same repository. After compilation, prepareIncomingDocument node would contain prepare action bound with prepareDocument method in action catalog.

That distinction is useful when an action appears in several workflows, or more than once within a graph. Catalog names identify reusable behavior; graph node IDs identify its position in a particular workflow.

The official guide also discusses a singular edgeAction(...) accessor with details on its usage

Other supported method shapes

The example uses synchronous methods, but catalogs also support asynchronous work and node construction during compilation:

Method role	Supported return types
Runtime node action	`Map<String, Object>` or `CompletableFuture<Map<String, Object>>`
Runtime edge condition	`String`, `Command`, or a `CompletableFuture` of either
Compile-time node method	`NodeActionWithConfig<State>` or `AsyncNodeActionWithConfig<State>`

Runtime methods can receive your AgentState subclass, RunnableConfig, both in either order, or neither. Include only what the method needs. A returned future must complete before its updates or routing result can be applied; returning a future does not itself schedule background work.

A compile-time node method instead takes one CompileConfig argument. It runs when the graph creates its action during compilation and returns the action to execute later. This is useful when action construction depends on compilation settings. Edge conditions do not support compile-time configuration.

See the signature examples for the complete forms.

For a small workflow, a single catalog keeps related actions and conditions together. As the application grows, I would split catalogs by responsibility: document preparation in one, review policy in another, and delivery in a third. Each can have its own repository, with their actions connected in the same explicit graph definition.

The repository uses the catalog instance you supply. That means constructor injection works naturally: create the catalog with its service clients, repositories, or model dependencies before registering it. The annotations do not require a dependency injection framework.

Keep per-run values in graph state or execution configuration. A catalog shared across concurrent runs also shares its fields and dependencies, so mutable collaborators need suitable concurrency handling. The stateless catalog in this example avoids that concern.

Catalog methods can be called directly in ordinary Java tests.

Common mistakes to catch early

Use public annotated methods, with one graph annotation per method. Repository discovery will not pick up private methods. Unsupported runtime parameter types are rejected during repository creation, while unsupported results fail when the action executes; compile-time node results are checked during compilation.

Looking up an unknown action through node, nodeAction, or edge throws IllegalArgumentException. Explicit duplicate names are also rejected; make method-derived names unique rather than relying on overload discovery order.

Exceptions thrown by runtime methods, and exceptional future completions, propagate through graph execution. Annotations provide adaptation, so application error handling still belongs in the actions or the surrounding execution code. The validation reference covers these failure cases.

For an existing graph, a practical migration is to move a related group of actions into a catalog, register it, and replace their inline implementations with repository lookups. The edges and routing mappings can remain explicit throughout that refactoring.

Conclusion

The approach of organizing actions into catalogs helps maintain a clear structure as your workflow grows. It encourages modularity, reusability, and easier testing, while keeping the graph definitions explicit and manageable.
In the future action catalogs could feed advanced workflow designer tools, enabling more declarative automation and orchestration capabilities.
I'm interested in how this approach fits larger workflows. Try it grouping a set of related actions in LangGraph4j, share your feedback, and... happy AI coding! 👋

Why Does a Backend API Become Slow, and How Can We Fix It?

Wed, 21 Oct 2026 03:36:54 +0000

As a backend developer, I spend a lot of time thinking about what happens behind the scenes when someone uses an application. A user clicks a button, submits a form, or requests some information, and the backend has to process that request and return a response.

Everything looks simple when an application is small. But as the number of users and the amount of data increase, things can change quickly. An API that used to respond almost instantly may suddenly take several seconds to return the same information.

So, what actually makes a backend API slow, and how can we fix it?

The Problem: An API That Takes Too Long to Respond

Imagine you're building an e-commerce application using Java and Spring Boot. The application has an API that returns a list of products.

At first, the API works perfectly. It fetches product information from the database and returns the result to the frontend.

But after the application grows, users begin to complain that the product page takes too long to load.

There could be several reasons behind this problem:

The database is executing inefficient queries.
The API is retrieving more data than the frontend needs.
The application is making unnecessary database calls.
Multiple operations are being performed when they are not required.
The server is struggling to handle too many requests at once.

The first mistake would be to start changing the code without understanding the actual cause.

Before optimizing an API, we need to identify where the time is being spent.

Step 1: Measure the API Performance

The first thing I would do is measure the response time.

Instead of guessing, I would check application logs, database query execution times, and performance metrics to understand whether the delay comes from the database, application logic, or another part of the system.

For example, if an API takes 1,500 milliseconds to respond, I would investigate how much time is spent executing the database query and how much is spent processing the result.

This gives us a starting point.

In a Spring Boot application, tools such as Spring Boot Actuator and Micrometer can help expose useful application metrics. Database query logging and profiling can also help identify expensive operations.

The goal is simple: find the bottleneck before trying to fix it.

Step 2: Improve Database Queries

One common problem is retrieving unnecessary data.

Suppose the frontend only needs a product's name, price, and image URL. There is no reason to fetch every column from the database if the application doesn't need them.

A basic SQL query might look like this:

SELECT *
FROM products;

A more focused query would be:

SELECT name, price, image_url
FROM products;

This can reduce the amount of data transferred and processed, particularly when the table contains many columns or large fields.

Indexes can also improve performance when queries frequently filter or search by specific columns. However, indexes should be chosen based on actual query patterns because unnecessary indexes increase storage use and can slow down writes.

Small database improvements can make a noticeable difference when an API is called frequently.

Step 3: Avoid Unnecessary Database Calls

Another issue I would investigate is whether the application is making too many database queries.

For example, imagine an API returns 100 products. If the application executes one query to fetch the products and then another query for each product's category, it could make 101 queries instead of a smaller number of well-designed queries.

This is a common example of the N+1 query problem.

With Java and Spring Data JPA, the solution might involve a carefully designed fetch strategy, a projection, or a query that retrieves the required information together.

The right approach depends on the relationships between the entities and the data the endpoint actually needs.

I would also avoid blindly using eager loading everywhere, because loading too much related data can create a different performance problem.

Step 4: Return Only the Data the Client Needs

A backend API should have a clear responsibility: provide the information the client needs to complete a task.

Returning thousands of records in a single response is rarely a good choice when the user only needs to view a small portion of them.

Pagination can help.

For example, a Spring Data repository can support paginated queries:

Page<Product> findAll(Pageable pageable);

A service or controller can then request a specific page rather than loading every product at once.

For larger datasets, cursor-based pagination may be more suitable than offset-based pagination, depending on the use case.

The important thing is to make sure the API remains efficient as the dataset grows.

Step 5: Use Caching When It Makes Sense

Sometimes the same information is requested repeatedly even though it rarely changes.

Product categories, public configuration, and other relatively stable data may be good candidates for caching.

Spring provides caching support through annotations such as @Cacheable.

For example:

@Cacheable("productCategories")
public List<Category> getCategories() {
    return categoryRepository.findAll();
}

After the first successful lookup, subsequent calls can reuse the cached result, depending on the configured cache provider and cache rules.

However, caching is not a solution for every slow API. We need to consider expiration, invalidation, memory usage, and whether users might receive outdated information.

For frequently changing or sensitive data, caching requires additional care.

Step 6: Test the Changes

After making improvements, I would test the API again using the same conditions as before.

I would compare:

Average response time.
Higher-percentile latency, such as p95.
Database query count and execution time.
Error rates.
Resource usage under concurrent requests.

A change that makes one request faster but causes errors under heavy traffic is not a successful optimization.

Performance testing tools can help simulate multiple users and reveal problems that may not appear during ordinary development.

I would also keep automated tests in place to ensure that performance improvements don't accidentally change the API's expected behavior.

What I Learned From This Approach

The biggest lesson is that backend performance is not just about writing shorter code or choosing a faster programming language.

A well-designed API depends on several things working together: efficient database queries, sensible data retrieval, appropriate caching, reliable application logic, and good monitoring.

Java and Spring Boot provide useful tools for building APIs, but the framework cannot automatically make every design decision efficient.

As developers, we still need to understand what the application is doing and why a particular operation is taking too long.

I would rather spend time identifying the actual bottleneck than introduce unnecessary complexity in the name of optimization.

Final Thoughts

Building a backend API that works is one challenge. Keeping it reliable and responsive as the application grows is another.

When an API becomes slow, I think the best approach is to measure first, identify the problem, make a focused change, and test the result.

Good backend development is not only about making an application work today. It's about making sure it continues to work well as more users depend on it.

I'm interested in how other Java developers approach API performance. When you notice a slow endpoint in your application, what's the first thing you investigate: database queries, application logic, or something else?

The Order Was Saved. The Kafka Event Might Never Arrive.

Tue, 13 Oct 2026 17:20:19 +0000

A customer clicks Place order. Your API returns success. The order row is in the database. But the service that processes orders never sees an event.

This is not a hypothetical edge case invented by Kafka. It is a failure window in a common Spring Boot pattern: save to a database, then publish to a broker as a second operation. I found the pattern while reviewing my own event-driven order processing capstone. This is a code review of a learning project, not a claim that a production outage occurred.

The lesson applies well beyond orders. If your API writes data and then emits an event for fraud checks, notifications, inventory, or analytics, a successful HTTP response can tell less of the story than you think.

The four lines that made me stop

My order service saves a new order, then calls a producer:

CustomerOrder order = orderRepository.save(new CustomerOrder(...));
producer.publish(new OrderEvent(order.getId(), ...));
return toResponse(order);

The producer uses Spring Kafka like this:

public void publish(OrderEvent event) {
    kafkaTemplate.send("order-events", String.valueOf(event.orderId()), event);
}

That send returns a future. In this implementation, the future is ignored. The method can move on to the HTTP response without observing whether Kafka acknowledged the record. More fundamentally, the database write and Kafka publish are two separate operations. A process crash can occur between them even if you wait for the send result.

The code is perfectly useful for demonstrating an event-driven flow. It is not enough by itself to promise that every saved order will produce a durable event.

Where the gap opens

There are at least two ways to lose the intended handoff:

Crash after the database commit, before the send. The order exists, but no event was requested.
Asynchronous send failure after the method proceeds. The producer future completes with an error, but this code does not inspect it.

The reverse uncertainty also matters: Kafka may accept an event while the client never receives the HTTP response. A retry from the client can create another order unless the API has a separate request-idempotency rule.

I already had retries and a dead-letter topic on the consumer side of the capstone. Those help when an event reaches Kafka and processing fails. They cannot recover an event that was never published. This distinction is easy to miss when a demo looks healthy end to end.

First, choose what a successful response means

An API contract should say what has actually happened. For an asynchronous workflow, a successful create response may mean the order and the intent to process it have been stored. It should not imply that downstream processing is complete.

A practical state model might be:

CREATED → PROCESSING → APPROVED or REJECTED
                       ↘ NEEDS_ATTENTION

A GET endpoint lets the caller check the current state. An order stuck in CREATED for too long should be visible to monitoring and operators, not quietly forgotten.

The transactional outbox fix

A transactional outbox makes the event intent part of the same database transaction as the order. The API writes two rows: the business record and an outbox record containing an event ID, aggregate ID, event type, and payload. Either both rows commit or neither does.

A separate relay publishes committed outbox rows to Kafka. That relay can poll the table or use change-data capture. Debezium's outbox event router is one established implementation of the latter approach.

The core application code becomes conceptually:

@Transactional
public OrderResponse createOrder(CreateOrderRequest request) {
    CustomerOrder order = orderRepository.save(toEntity(request));
    outboxRepository.save(OutboxEvent.orderCreated(order));
    return toResponse(order);
}

This is illustrative replacement code, not a feature already implemented in my capstone. The important part is the transaction boundary around both inserts. The relay is responsible for eventual delivery after commit.

The outbox does not turn the whole system into exactly-once delivery. A relay may publish an event and crash before recording that it published it. It will publish again after restart. Consumers therefore need to handle duplicates, usually by recording a stable event ID and making the business effect idempotent.

Two IDs solve two different retry problems

It helps to keep these IDs distinct:

Request ID: supplied or assigned at the API edge so a repeated Place order request does not create a second order.
Event ID: stored with the outbox record so repeated event delivery does not apply the same downstream action twice.

Kafka producer idempotence is useful for producer retries, but it does not make a database transaction and a broker publish atomic. Nor does it replace consumer-side deduplication across relay restarts. Each layer protects a different boundary.

The test I would add before calling this production-ready

I would make failure injection part of the acceptance test:

Create an order while the broker is unavailable.
Confirm that the order and its outbox event are committed together.
Restore the broker and confirm that the relay publishes the event.
Force the relay to retry, then confirm the consumer applies the event only once.
Check that the order eventually leaves CREATED, or raises an alert if it does not.

In the current direct-send design, a broker failure or crash can leave an order without a durable event intent. The test should make that gap visible. In the outbox design, the same test checks the recovery path rather than just the happy path.

What I would monitor

A reliable event-driven API needs signals beyond HTTP success rate:

Age of the oldest unpublished outbox row
Number of publish failures and relay retries
Consumer lag and dead-letter count
Duplicate event count
Orders stuck in CREATED or PROCESSING
Time from order creation to final state

These metrics turn “the dashboard never updated” into an observable state with an owner and a recovery path.

The takeaway

My capstone taught me a useful production lesson: an event-driven workflow is only as reliable as the boundary between its database and its broker. Consumer retries are valuable, but they start too late to repair a missing publish. Save the business record and the event intent together, deliver at least once, deduplicate downstream, and monitor the gap between creation and completion.

If you have built a database-to-Kafka flow, where do you persist the intent to publish? I would be interested to hear how your team tests that failure window.

References

Most Developers Are Building AI Agents Wrong: MCP Is the Missing Contract

Sun, 11 Oct 2026 07:48:38 +0000

AI agents are easy to demo and difficult to trust.

A developer can connect a language model to a few tools in an afternoon. The first demo looks impressive: the agent reads a request, calls an API, checks a database, and returns an answer.

Then production arrives.

The agent calls the wrong tool. It sends an incomplete payload. It retries a payment operation. It exposes information from another tenant. Nobody can explain why it made a decision.

The problem is not always the language model. The deeper problem is that many teams are building agents without a clear contract between the model, the tools, the data, and the people responsible for the outcome.

That is where the Model Context Protocol, or MCP, becomes important.

An AI agent is more than a chatbot

A useful enterprise agent usually has five parts:

A model that reasons about the request
Instructions that define its role and limits
Tools that allow it to read or change systems
Memory or context that helps it understand the task
Guardrails that control what it is allowed to do

A chatbot mainly generates text. An agent can take actions.

That difference changes the engineering problem completely. If an agent only produces an explanation, an inaccurate response may be corrected by a human. If an agent can approve a refund, change a production configuration, or submit a healthcare request, an inaccurate response becomes an operational incident.

The agent must therefore be treated like a distributed system with an unreliable reasoning component.

The tool boundary is the real architecture

Many early agent implementations expose tools with a name, description, and input schema. That is not enough for production.

A safe tool contract must answer several questions:

Which user or tenant is the agent allowed to access?
Which values are valid?
Does the operation require approval?
Is the operation idempotent?
What happens if the network times out after success?
How is the action audited?

A tool description is not a security policy. It is only the beginning of a contract.

Why MCP matters

MCP provides a standard way for AI applications to discover and use external tools and resources. Instead of building a different integration for every model and every application, teams can expose capabilities through a consistent protocol.

That standardization is valuable, but it does not automatically make an integration safe.

MCP should be treated as an interoperability layer, not as permission to give an agent unrestricted access to a system.

A production MCP tool should define:

A clear business purpose
Read or write classification
Authentication and authorization requirements
Tenant and data-scope restrictions
Input validation
Idempotency behavior
Timeout and retry rules
Rate limits
Audit events
Human approval requirements
A safe failure response

The most important design principle is simple:

The model may request an action, but the platform must decide whether that action is allowed.

A safer agent flow

A reliable enterprise agent should follow a controlled sequence:

User request -> identity verification -> permitted context -> model plan -> policy evaluation -> human approval when required -> MCP tool execution -> result validation -> audit event -> user response

The model should not directly own the complete workflow. It should operate inside one.

For example, an agent may propose: Cancel this payment.

The policy layer should check whether the user is authenticated, whether the payment belongs to the user organization, whether it is still cancellable, whether the amount exceeds an approval threshold, whether the request was already processed, and whether the downstream tool is healthy.

Only after these checks should the action reach the payment service.

MCP and Spring Boot

A practical Java implementation can place an agent gateway in front of domain services.

The gateway can provide:

Spring Security authentication
OAuth2 or JWT validation
Tool-level authorization
Request and response schemas
Correlation IDs
Rate limiting
OpenTelemetry traces
Approval workflow integration
Central audit logging

The domain service should still enforce its own business rules. Never assume that because a request came from an AI gateway, it is trustworthy.

A safe execution model is: validate the user, evaluate policy, validate the tool input, enforce idempotency, call the domain service, validate the result, and record an audit event.

The model can select a tool. It should not bypass the same controls that apply to a human-operated API.

Read tools and write tools are not equal

Read-only tools may retrieve an invoice, search a knowledge base, or check an order status. Write tools may create a payment, update a customer, delete a document, or deploy software.

These categories should have different controls. A read tool may require normal user authorization. A high-impact write tool may require explicit confirmation, a second approver, a transaction limit, a dry-run mode, or a compensating action.

Do not hide a write operation behind a friendly name such as manage account. Use names that reveal the action and its risk: create refund, disable user, or deploy release.

Clear names help models, developers, reviewers, and security teams understand what is happening.

The biggest MCP security risks

MCP-based systems introduce familiar security risks in a new form.

Excessive permissions

An agent receives access to more data and tools than it needs. If the model or server is compromised, the blast radius becomes large.

Prompt injection

Untrusted content inside a document, webpage, or ticket attempts to influence the agent instructions. Retrieved content must be treated as data, not as a higher-priority instruction.

Confused deputy problems

The agent uses its own powerful credentials to perform an action on behalf of a user who does not have that permission.

Tool poisoning

A malicious or poorly maintained tool provides misleading descriptions, hidden side effects, or unsafe defaults.

Data leakage

The agent combines information from different users, tenants, or conversations and includes it in a response.

The solution is not one magic prompt. It is layered security: least privilege, isolation, validation, monitoring, and clear ownership.

Observability is not optional

Traditional application monitoring asks what request failed, which service was slow, and what status code was returned.

Agent observability needs additional questions:

What was the original user intent?
What context was retrieved?
Which tools were considered?
Which tool was selected?
What policy decision was made?
How many retries occurred?
Was human approval requested?
What data was returned to the user?

Every agent action should have a correlation ID that follows the request across the model gateway, MCP server, domain service, database, and audit system.

Without this trail, debugging becomes guesswork.

Start with narrow agents

The best first production agent is rarely a general-purpose assistant with access to the entire company.

Start with one bounded workflow:

Search internal documentation
Summarize support tickets
Validate an invoice
Classify incoming documents
Explain a failed transaction
Draft, but do not send, a customer response

Measure accuracy, latency, cost, refusal quality, tool-selection errors, and security violations. Then expand carefully.

A narrow agent with clear boundaries can create more business value than a general agent that appears intelligent but cannot be trusted.

The future of agents is controlled autonomy

AI agents will become more capable, but capability alone is not the goal.

The goal is controlled autonomy: systems that can complete useful work while remaining observable, explainable, reversible, and accountable.

MCP can help create a common interface between agents and the software world. But the protocol is only one layer. The real production architecture still needs identity, policy, security, resilience, testing, and human judgment.

The strongest agent teams will not ask only, What can the model do? They will also ask, What should the model be allowed to do, under which conditions, and how can we prove what happened?

That is the difference between an impressive demo and an enterprise system.

Final checklist

Before exposing an MCP tool to an AI agent, verify:

Is the tool purpose narrow and explicit?
Is access scoped to the authenticated user and tenant?
Are inputs validated independently of the model?
Are write actions idempotent?
Are high-risk actions reversible or approval-gated?
Are prompts and retrieved documents treated as untrusted data?
Are tool calls, policy decisions, and outputs audited?
Can the team trace a failed decision?
Is there a rate limit and emergency disable mechanism?
Does the system fail safely when the model is wrong?

If the answer to several of these questions is no, the agent is not ready for production.

It is ready for a better architecture.

A production agent architecture

flowchart LR
    U[User request] --> G[Agent gateway]
    G --> P[Policy and identity checks]
    P --> M[Model plan]
    M --> C[MCP server]
    C --> D[Domain service]
    D --> A[Audit and observability]
    A --> R[Validated response]

The model proposes the next action, but the gateway, policy layer, MCP server, and domain service each enforce their own boundary. This layered design prevents one incorrect model decision from becoming an uncontrolled production change.

Reference

Model Context Protocol official documentation

From Writing Web Novels to Shipping Software — Nocklock’s Developer Journey

Thu, 08 Oct 2026 13:10:12 +0000

From Writing Web Novels to Shipping Software — Nocklock’s Developer Journey

“I think AI is most useful when it extends my thinking rather than replacing it.”

Nocklock didn't originally become a developer because programming was a lifelong childhood dream.

It started for a much more practical reason: making a living.

A few years ago, before AI became deeply integrated into everyday software development, Nocklock was looking for a practical way into the industry. In Korea, Java and Spring were widely used in enterprise and public-sector development, making them a natural choice.

But programming eventually became interesting for a reason that had little to do with career practicality.

Before becoming a developer, Nocklock had commercially published two web novels.

That experience would unexpectedly influence the way he thinks about software.

Writing fiction means creating a world, defining its rules, and allowing characters to interact within those rules.

Software isn't so different.

Programming languages have rules. Networks have rules. Data has structure. Business logic creates constraints. Developers build systems and user flows inside those constraints.

The connection between writing and programming gave Nocklock a different way of thinking about development.

Instead of seeing software only as code, he began seeing it as a system of possibilities.

And that perspective continues to influence how he builds today.

Programming Started as a Practical Choice

Nocklock's initial decision to learn programming was pragmatic.

Java and Spring offered a realistic path into professional software development, particularly within Korea's enterprise and public-sector technology landscape.

But choosing a technology for practical reasons doesn't necessarily mean remaining interested for practical reasons.

As Nocklock gained experience, he discovered that programming gave him something he had already experienced through writing:

the ability to create systems governed by rules.

When writing a novel, he might ask:

What if I were the character?

What if the situation were different?

What would happen if the rules changed?

He now brings similar questions into software development.

When building something, he tries to imagine different situations and perspectives.

What if he were the user?

What if the user knew nothing about the subject?

What if the environment were different?

What if an assumption turned out to be wrong?

That habit of questioning has become part of how he approaches development.

Learning by Shipping

One of Nocklock's strongest beliefs is reflected directly in his profile:

learning by shipping.

He discovered why this approach worked for him while studying for Korea's Engineer Information Processing qualification.

Much of the preparation involved studying and memorizing theory.

But he noticed something interesting.

He could forget information he had memorized for an exam.

Yet he could still remember errors he had encountered while working, why they happened, and how he eventually solved them.

The difference was experience.

Knowledge connected to a real problem stayed with him.

That realization changed how he approached learning.

When he encountered an AI development competition, he began building rather than waiting until he had learned everything he thought he needed to know.

He learned what was necessary while developing the project.

He made mistakes.

He investigated them.

He fixed them.

And eventually, he shipped.

That's what learning by shipping means to him.

It doesn't mean abandoning study.

It means turning knowledge into experience.

Security Lens: When the MVP Became Real

One of the clearest examples of this philosophy was Security Lens.

The original idea sounded relatively straightforward.

A user would upload an image, OCR would extract information, the system would identify potential privacy risks, and the user would receive useful results.

But building the real product exposed a much messier reality.

Real files and images didn't always behave as expected.

OCR accuracy wasn't always reliable.

Unexpected problems kept appearing.

And once the core functionality finally worked, Nocklock realized something important:

The main feature working didn't mean the product was finished.

It meant the next phase had started.

There were still improvements to make, problems to investigate, and a deadline approaching.

That experience changed his understanding of what it means to ship software.

Building the main feature is only one milestone.

Shipping means confronting the difference between:

the product you imagined

and

the product that actually exists.

The README Became a Product Review

Nocklock initially thought writing the README would simply mean documenting what he had already built.

Instead, documentation exposed problems in the product itself.

During development, he had often moved quickly from one problem to the next.

Get something working.

Move forward.

Solve the next issue.

Keep building.

But when he tried to explain the project clearly, he started noticing gaps.

Sometimes he would describe a feature and suddenly question whether the feature was necessary at all.

That changed the purpose of the README.

It was no longer just documentation.

It became a way of reviewing the product.

Writing forced him to examine:

The project structure
Individual features
Development decisions
The reasoning behind those decisions
Whether certain features were actually necessary

In that sense, documentation became another form of development.

Sometimes explaining what you built reveals whether you should have built it in the first place.

A New Laptop Revealed Hidden Complexity

Another unexpected lesson came from something much more ordinary:

setting up a new laptop.

Moving from an established development environment to a clean machine exposed how much invisible state had accumulated over time.

JDK versions.

PATH settings.

Git configuration.

IDE settings.

Build synchronization.

Environment variables.

Small setup decisions that had gradually become invisible.

On the old machine, those things simply worked.

On the new one, they didn't.

Suddenly, when something behaved unexpectedly, Nocklock had to ask:

Is this a problem with my code?

Is it the build state?

The JDK?

The IDE?

The environment configuration?

That experience led to an important realization:

The development environment is part of the system too.

A clean machine can reveal what you genuinely understand and what your previous environment had quietly been doing for you.

Debugging Doesn't Stop at the Code

Deployment reinforced the same lesson.

Local development can feel comfortable.

Then the application gets deployed.

Suddenly, ports, environment variables, runtime differences, external services, configuration and hidden assumptions all become part of the problem.

Nocklock experienced this while deploying Security Lens to Railway.

It also helped him understand why tools such as Docker became so important.

Docker doesn't eliminate every deployment problem.

But making the runtime environment reproducible can remove a significant category of differences between machines.

As a result, his approach to debugging has expanded.

He doesn't look only at the code anymore.

He also considers:

Configuration
Runtime
Environment
External dependencies
Deployment conditions
Assumptions connecting those pieces

Sometimes the bug isn't in the code.

Sometimes the code is behaving exactly as written inside an environment you misunderstood.

Why Java and Spring Still Matter

Nocklock originally chose Java and Spring because they were practical.

After working with them professionally, however, he developed a different appreciation for the ecosystem.

What stands out to him is its maturity and structure.

Backend services can quickly become complicated.

They may involve:

Business logic
Databases
APIs
Security
External integrations
Multiple requirements
Different environments

In that situation, conventions and proven patterns can become extremely valuable.

Spring provides abstractions that help developers build quickly while still leaving a deeper ecosystem underneath those abstractions to understand.

But Nocklock doesn't believe Java or Spring should automatically be used for every problem.

The technology should fit the problem.

That idea connects directly to one of his broader principles:

follow the problem, not a fixed stack.

AI Should Extend Thinking, Not Replace It

Nocklock's approach to AI is deliberately different from simply asking an AI model to write everything.

His first step isn't:

“Write this for me.”

Instead, he tries to explain what he's curious about, why he's curious about it, and how he thinks the pieces might connect.

Then he asks AI to help explain the subject.

Only after understanding the direction does he use AI for implementation, code review, identifying mistakes or suggesting improvements.

That distinction matters to him.

AI can provide an enormous amount of knowledge.

Its ability to interact with tools and take action is also growing quickly.

But Nocklock wants the important questions, judgment and decisions to remain his responsibility.

The ideal relationship isn't human versus AI.

It's human thinking enhanced by AI.

AI becomes a multiplier for understanding rather than a substitute for understanding.

Following the Problem Instead of the Stack

Nocklock doesn't want technology to be the starting point of a project.

He starts with the problem.

What is being built?

How quickly does it need to be built?

What constraints exist?

What can realistically be maintained?

What can be verified?

Sometimes Java and Spring are the right choice because they are familiar and fit the requirements.

Sometimes another technology is better.

AI has made experimenting with unfamiliar technologies easier, but that doesn't mean every new technology deserves to be added to a project.

In fact, sometimes following the problem means deliberately choosing something familiar and boring.

That's an important distinction.

Being flexible doesn't mean constantly chasing new technology.

It means choosing technology based on what the problem actually requires.

The Cost of Moving Too Fast

One mistake Nocklock continues to notice in himself is focusing heavily on implementation and assuming the structure can always be cleaned up later.

Security Lens made this particularly obvious.

Because of the competition deadline, he often solved the next problem in front of him and moved on.

That approach helped maintain momentum.

But later, while documenting the project, he could see where the structure had become messy.

He could also see that some features probably didn't need to exist.

The lesson wasn't that moving quickly was wrong.

It was that speed doesn't remove the cost of decisions.

It simply delays when you see that cost.

Today, Nocklock tries to create small moments during development where he can step outside the code and ask:

Does what I'm building still make sense?

That pause can prevent a lot of future cleanup.

What He's Exploring Next

Nocklock's interests are increasingly moving toward the intersection of:

Backend development.

AI.

Security.

Real products.

Security Lens began as a tool for detecting privacy risks in files before they are uploaded.

Working on it opened up broader questions about digital content.

How do we know whether an image or piece of content is authentic?

Where did it come from?

Was it generated or modified by AI?

Can AI-generated media be used to imitate another person?

These questions have made areas such as content provenance and identity risk particularly interesting to him.

At the same time, he remains interested in building smaller experimental products.

The goal is to test an idea quickly, receive real feedback and then decide whether the idea deserves further investment.

Build Something Smaller

When asked what advice he would give other developers, Nocklock's answer is straightforward:

Build something smaller than the thing you originally wanted to build.

It's easy to remain in preparation mode.

There is always another:

Course
Framework
Tutorial
Concept
Technology

that could be learned first.

But developers don't need to understand everything before starting.

Build something small enough to finish.

Let it break.

Deploy it.

Let another person use it.

Then examine what goes wrong.

Those problems will often tell you what you genuinely need to learn next.

For Nocklock, one real error that requires investigation can teach more than memorizing ten definitions.

Experience creates context.

Context makes knowledge stick.

Becoming More Than a Framework Developer

Nocklock doesn't want to become a developer defined by a single framework.

Java and Spring are an important foundation, but his longer-term goal is broader.

He wants to become someone who can move comfortably between:

Engineering
AI
Product thinking
Deployment
Problem solving
Communication

He wants to understand a problem, choose appropriate tools, build the system, deploy it, explain it clearly and improve it based on what actually happens.

In other words:

Not simply someone who writes code.

Someone who can take an idea and keep working on it until it becomes something another person can actually use.

From Writing Stories to Building Systems

There is an interesting connection running through Nocklock's entire journey.

Before software, there was storytelling.

He created fictional worlds, defined their rules and imagined what could happen inside them.

Then came programming.

Different syntax.

Different constraints.

Different tools.

But a surprisingly similar creative process.

Software also involves defining rules, creating systems and imagining what happens when different pieces interact.

Today, AI adds another layer to that process.

It can help him explore unfamiliar concepts, test ideas and move faster.

But he still wants to be the person asking the questions.

The person deciding what matters.

The person choosing what to build.

And ultimately, the person responsible for shipping it.

Knowing What Not to Build

When Nocklock first started programming, he thought becoming a better developer mostly meant knowing more.

More syntax.

More frameworks.

More technologies.

His perspective has changed.

Technical knowledge still matters.

But software development is also about understanding the problem, questioning assumptions, debugging beyond the code, communicating decisions, working within constraints and actually shipping something people can use.

He has also learned that knowing what not to build can be just as important as knowing how to build something.

Code remains at the center of the work.

But it isn't the whole job anymore.

The Developer Journey Continues

Nocklock's journey began with a practical career decision.

It developed through Java and Spring.

It was shaped by an earlier life as a published web novelist.

It accelerated through learning by shipping.

Security Lens taught him the difference between building an MVP and actually shipping a product.

Documentation taught him to question his own decisions.

Deployment taught him that the environment is part of the system.

AI taught him another way to learn and work.

And his current interests are taking him toward the intersection of backend engineering, AI, security and real-world products.

His philosophy can be summed up simply:

Start with the problem.

Build something small.

Let reality test it.

Learn from what breaks.

Ship it.

Then do it again.

About Nocklock

Nocklock is a developer building useful things with Java, Spring and AI.

His approach centers on learning by shipping, documenting what works and following the problem rather than committing to a fixed technology stack.

His current interests include backend development, AI, security, content provenance and experimental product development.

View Nocklock's profile on CoderLegion

Visit Nocklock's website

CoderLegion Developer Stories

Real developers. Real journeys. Real experiences.

Developer Stories at CoderLegion gives developers a place to share how they think, what they build, the problems they encounter and what they learn along the way.

Interview & Story by Mehadi Hasan

A New Laptop Exposed the Hidden State in My Development Environment

Sat, 03 Oct 2026 05:41:23 +0000

I recently moved my development setup to a new LG gram Pro 17.

At first, I was mostly distracted by the laptop itself.

It's a 17-inch machine, but it doesn't really feel like one when you pick it up.

The screen is huge compared to what I was used to, and the weight was honestly the first thing that surprised me.

Then I opened it and tried to get back to work.

That was when the more interesting part started.

My old development environment had disappeared.

Not my code.

My environment.

On my previous machine, Java was already installed.

Git worked.

IntelliJ knew my projects.

Dependencies were already downloaded.

Environment variables existed.

Some configuration files had probably been sitting there for months without me thinking about them.

I could open a project and start coding.

It felt simple.

A new laptop made me realize that it was only simple because I had already solved all of those problems sometime in the past.

A fresh machine removes the invisible parts

I started rebuilding everything.

Windows updates.

JDK 17.

Git.

IntelliJ.

Project SDK.

Then I cloned one of my existing Spring Boot projects.

None of this was new to me.

I've installed Java before.

I've configured IntelliJ before.

I've run Spring Boot projects more times than I can count.

But doing it all again from zero made something visible that I normally don't notice.

A development machine accumulates state.

Over time, that state becomes invisible.

You stop remembering which environment variable you added.

You forget which local file exists only on your machine.

You don't think about which JDK your IDE is pointing to because it has been correct for months.

You just work.

Until you move to another machine.

Installing the tools wasn't the real test

At some point I had Java installed.

Git was working.

IntelliJ was open.

Technically, I had a development environment.

But I didn't really consider the setup finished.

I had one condition:

Can one of my existing Spring Boot projects actually run here?

So I opened an old project.

The IDE indexed it.

Dependencies were resolved.

The project built.

Then I ran the application.

The server started.

That was the moment the new machine felt ready.

Not when IntelliJ opened.

Not when java -version worked.

Not when Git cloned the repository.

When the application actually ran.

Because a real application depends on much more than the editor where you write the code.

"Works on my machine" has another side

We usually talk about "works on my machine" when deployment breaks.

But moving to a new laptop made me realize there is a smaller version of the same problem inside development itself.

If a project only works because my old machine has the right combination of hidden configuration, cached dependencies, local files, and environment variables...

how reproducible is my development environment really?

I'm not saying every local setup needs to be fully automated.

Mine isn't.

But I do think I should be able to answer a basic question:

What does this project actually need in order to run somewhere else?

A new laptop is surprisingly good at testing that.

This felt familiar

I ran into almost the same problem while building and deploying small Spring Boot MVPs.

The main feature worked.

The API responded.

The UI behaved correctly.

On localhost, everything looked fine.

Then deployment started exposing assumptions.

Ports.

Environment variables.

Build configuration.

External services.

Things that my local machine had quietly been handling for me.

That's when I started thinking of building and shipping as two different skills.

I eventually turned the checklist I was using into a small guide called Ship Your Spring Boot MVP.

It focuses on the things I kept checking before calling a project ready to leave localhost:

clean builds
configuration
environment variables
deployment checks
evidence that the application actually works outside the development machine

If that's a problem you're working through too:

Ship Your Spring Boot MVP

I didn't make it because deploying Spring Boot is mysterious.

I made it because I kept realizing how easy it is to confuse "the feature works" with "the product is ready to ship."

The laptop itself still needs more testing

As for the gram Pro 17, I'm still not ready to call this a full developer review.

The machine I'm using has a Core Ultra 7 and 32GB of RAM.

So far, I really like the screen size and the weight.

But what I actually care about comes next.

I want to spend real development time with:

IntelliJ
Spring Boot
Docker
a database
browser tabs
documentation
all the other things I somehow leave open at the same time

I want to see the thermals.

I want to see the battery life.

And I want to know whether carrying a 17-inch laptop every day still feels like a good idea after the novelty wears off.

So the hardware review can wait.

For now, the more interesting thing wasn't the new laptop.

It was seeing my old development environment without all of its accumulated history.

The laptop was new.

The code wasn't.

But starting from an empty machine made me see how much invisible context had been sitting between the two.

How Java Developers Build Scalable Applications and Backend Systems

Fri, 02 Oct 2026 04:00:39 +0000

As a Java developer, I enjoy building applications that solve real problems, handling complex logic, and exploring how software works behind the scenes. Java is a powerful programming language that helps developers create everything from small applications to large backend systems used by businesses every day.

But how does the work of a Java developer actually happen? It involves much more than writing code. It requires understanding problems, designing solutions, managing data, testing functionality, and making sure applications work reliably as they grow.

Understanding the Problem Before Writing Code

Every application starts with a problem or an idea. Before writing Java code, I need to understand what the application should do, who will use it, and what features are required.

For example, if I am building an online shopping application, I need to think about user registration, product management, shopping carts, payments, and order tracking.

Breaking a large problem into smaller tasks makes development easier and helps create a clear plan for implementation.

Building the Backend with Java

The backend is the part of an application that handles business logic, processes requests, communicates with databases, and returns responses to users.

Java is useful for backend development because it supports object-oriented programming, strong type checking, and a large ecosystem of development tools and libraries.

For example, when a user logs into an application, the backend receives the login request, validates the submitted information, checks the stored user data, and returns an appropriate response.

Frameworks such as Spring Boot help Java developers build REST APIs, organize application logic, manage dependencies, and connect different parts of a system.

Connecting Applications to Databases

Most applications need to store and retrieve information. This is where databases become important.

A Java application might use MySQL or PostgreSQL to store user accounts, product information, transactions, or other business data.

Using tools such as Spring Data JPA and Hibernate, developers can work with database records through Java objects while still understanding the SQL queries and database operations involved.

For example, when a customer places an order, the application may validate the order, save its details, update inventory, and return a confirmation.

Handling these operations correctly is important because a small database error can affect the entire application.

Designing Scalable Backend Systems

Scalability means an application can handle increasing workloads as the number of users or requests grows.

Imagine a small application that works perfectly when 100 people use it. What happens when thousands of users start accessing it simultaneously?

Developers need to consider database performance, efficient algorithms, caching, connection management, and application architecture.

Depending on the requirements, a Java application might use Redis for caching, message queues for background processing, or multiple application instances to handle incoming requests.

Scalability does not always mean using microservices or adding more servers. Sometimes, improving a database query or removing an unnecessary operation is enough to make a significant difference.

Solving Complex Problems Through Debugging

One of the most important parts of software development is debugging.

An application may fail because of incorrect business logic, unexpected input, database connection problems, or communication failures between services.

Instead of fixing errors randomly, I try to understand what caused the problem, reproduce it, examine logs, and test possible solutions.

Writing unit tests and integration tests also helps identify problems early and reduces the risk of breaking existing functionality when new features are added.

Every bug provides an opportunity to understand the system more deeply and improve the quality of the code.

Learning and Exploring Software Architecture

Technology continues to evolve, so learning is an important part of being a Java developer.

I enjoy exploring software architecture, design patterns, REST APIs, performance optimization, and tools that make applications easier to maintain.

For example, separating an application into controller, service, and repository layers can help organize responsibilities and make the code easier to test.

As projects become more complex, understanding how different components communicate becomes just as important as knowing the programming language itself.

What Makes Development Meaningful?

For me, software development is about turning ideas into working solutions. Writing code is only one part of the process. Understanding the problem, making thoughtful technical decisions, testing the result, and improving the system are equally important.

I believe that becoming a better Java developer requires consistent practice, curiosity, and a willingness to learn from mistakes.

My goal is to keep improving my Java development skills, build reliable and scalable backend applications, and explore better ways to solve real-world problems through software.

Every project brings a new challenge, and every challenge offers an opportunity to learn something valuable.

eSIMQR Travel eSIM Store

Thu, 01 Oct 2026 01:33:25 +0000

A self-hosted eSIM commerce stack for operators and agencies

Travel eSIM businesses often stitch together a storefront, supplier APIs, payment gateways, reseller spreadsheets and a separate admin panel. eSIMQR packages those workflows into one self-hosted platform that teams can deploy and customize.

The customer-facing storefront supports multilingual destination and plan discovery, checkout, payment and QR-code delivery. Behind it, operators can manage supplier catalogues, pricing rules, orders, refunds and reporting from one administration workspace. Agencies can also provide resellers with partner pricing, prepaid wallets and their own portal instead of handling every transaction manually.

What is included

Travel eSIM storefront with QR-code delivery
Reseller portal with partner pricing and prepaid wallets
Admin tools for catalogues, orders, pricing and refunds
Supplier plugins for Airalo, eSIM Access, eSIM Go and YonoSIM
Stripe, PayPal, Paddle and Airwallex payment plugins
Java 21, Spring Boot and Docker deployment files
Editable source code and test integrations

The project is intended for teams that want to own their customer experience and infrastructure rather than depend entirely on a hosted white-label service. The codebase can be adapted for a direct-to-consumer shop, an agency reseller programme or an internal eSIM sales operation.

View the full package, screenshots and technical details on Codester.

I Built the MVP. Then I Realized Shipping Was a Different Skill.

Thu, 24 Sep 2026 13:44:30 +0000

I Built the MVP. Then I Realized Shipping Was a Different Skill.

A few days ago, I wrote about something I had learned the hard way:

Building the MVP first and writing the README later made me realize how much I had assumed.

I thought that was mostly a documentation problem.

It wasn't.

The deeper problem was that building something and shipping something are two different skills.

The MVP was working

I recently built Security Lens, a Spring Boot-based privacy risk analyzer for images and documents.

The basic flow was working:

Image Upload
      ↓
OCR
      ↓
Personal Information Detection
      ↓
EXIF Metadata Analysis
      ↓
Risk Scoring
      ↓
LLM-assisted Analysis
      ↓
Risk Explanation

It could detect things such as:

phone numbers
email addresses
EXIF GPS information
capture timestamps
device metadata

and turn the results into a simple privacy risk score.

At that point, I had something that worked.

I thought I was almost done.

I wasn't.

"It works" was only the beginning

Once I tried to actually ship the project, a different set of questions appeared.

Not:

Does this method work?

But:

Which exact version is deployed?

What happens if an environment variable is missing?

Did I actually verify the production configuration?

What if the database or external integration behaves differently from localhost?

What evidence do I have that the deployed application is healthy?

Can I roll back?

Those questions were not really about writing more code.

They were about operating the thing I had already written.

Deployment exposed assumptions

Localhost is forgiving.

Your machine already has:

your environment variables
your tools
your configuration
your ports
your dependencies
your development habits

Production does not care about any of that.

It only gets what you actually configured.

While working through deployment, I ran into issues around ports, environment setup, AI integration, and the difference between an implementation that works locally and one that can actually run as a product.

That changed how I looked at "done."

AI made this even more interesting

I use AI tools heavily while building.

They are extremely useful.

But I also noticed a dangerous pattern.

It is very easy to ask:

"Is this production-ready?"

and get an answer that sounds convincing.

The problem is that confidence is not evidence.

So I started using a different rule:

If the evidence is missing, the result is NOT VERIFIED.

Instead of asking AI to make the release decision for me, I ask it to help inspect:

configuration
logs
build output
deployment settings
security assumptions
missing evidence

The AI can be a reviewer.

It should not silently become the owner of the release decision.

That became a checklist

While repeatedly asking myself the same deployment questions, I started writing them down.

Eventually, those notes became a small public project:

Spring Boot Release Checklist

It focuses on things like:

clean builds
expected tests
configuration and secrets
database connectivity
external integrations
production smoke tests
rollback points
evidence-first AI review

The main idea is simple:

A successful deployment is not the same as a verified release.

Then I noticed something else

The checklist helped me catch blockers.

But I still wanted a better way to answer:

What did I actually verify?

Where is the evidence?

What still remains uncertain?

Should I ship this version?

That eventually became a more structured release workflow with interactive checks, evidence fields, AI review prompts, and ship / no-ship decisions.

I ended up turning it into a 58-page deployment runbook.

That was another new experience for me.

For the first time, I was not only building software.

I was taking something I had learned while building software and turning it into something another developer could actually use.

Shipping forced me to learn things coding alone did not

The interesting part was not setting up a product page.

It was everything around it.

I had to think about:

what the product actually solves
how to explain it in one sentence
what should remain free
what someone would reasonably pay for
how a buyer receives the files
how the download flow works
what happens after payment
how the public GitHub repository connects to the full version

None of these problems required a complicated algorithm.

But they still required engineering decisions.

My definition of "done" is changing

Before:

Feature works
→ done

Now:

Feature works
→ build succeeds
→ configuration is verified
→ deploy
→ production smoke test
→ evidence recorded
→ rollback understood
→ documentation updated
→ then maybe done

It is slower.

But it feels much closer to building something real.

One more thing I learned

I used to think "shipping" was mostly the final step after development.

Now I think it changes how you develop from the beginning.

When you know you will actually deploy something, you think differently about:

configuration
secrets
observability
failure cases
reproducibility
documentation
users

The project stops being just code.

It becomes a system someone else has to trust.

What's next

I am continuing to improve Security Lens and experimenting with the same workflow on other small products.

The Security Lens source code remains private, but I created a public technical case study here:

Security Lens — Technical Case Study

And the lightweight Spring Boot release workflow is available here:

Spring Boot Release Checklist

For me, the biggest lesson so far is simple:

Coding makes the product possible. Shipping makes it real.

Still learning.
Still shipping.

I Built the MVP First. Then I Wrote the README.

Thu, 24 Sep 2026 13:42:28 +0000

I did this in the wrong order.

At least, that was my first thought.

I was building a small project that checks images and documents for privacy risks. The backend came first, then the API, then a frontend that finally made it feel like an actual service.

Somewhere along the way, I realized something.

I had built quite a lot before properly organizing the requirements and documentation.

Normally, I would expect the order to look more like this:

requirements → design → implementation → testing → documentation

Mine looked closer to this:

build → break something → fix it → build more → test it → finally organize everything

Not exactly textbook development.

But writing the documentation afterwards turned out to be more useful than I expected.

The README became a way to inspect the project

At first, I thought I was just writing down what I had already built.

Instead, I kept finding things that were unclear.

What does this API actually guarantee?

What configuration is required before running the project?

What happens when an external dependency is unavailable?

Which parts have actually been tested?

Would someone other than me know how to start this project?

These are simple questions.

They become much harder to ignore when you have to explain the project in plain English.

And that was probably the most useful part.

Documentation stopped being something I needed to finish after development.

It became another form of testing.

AI made building faster, but that created a different problem

I also used AI quite heavily while building.

ChatGPT, Claude, and coding tools made it much easier to move from an idea to working code.

That part was great.

But faster implementation also meant I could move past decisions without really stopping to organize them.

A configuration works, so I move on.

An endpoint returns the right response, so I move on.

Docker starts successfully, so I move on.

Then deployment comes.

Suddenly all the small things I skipped become visible again.

Environment variables.

Ports.

Database configuration.

Build commands.

Health checks.

Logs.

Security settings.

Things that looked like small details on localhost started feeling much more important once I tried to get the application outside my own machine.

That was the point where I started thinking less about:

“Does this code work?”

and more about:

“Is this actually ready to leave localhost?”

There is a bigger difference between those two questions than I expected.

A working MVP is not the same as a shippable MVP

I used to think of an MVP mainly in terms of features.

If the core function works, the MVP works.

I still think that is partly true.

But there is another stage after that.

The application has to survive being run somewhere other than your laptop.

Someone needs to know how to configure it.

You need to know when it has failed.

Secrets should not be sitting in the repository.

The build should be reproducible.

The production environment should not depend on something you happened to configure manually three days ago and already forgot about.

None of these things are particularly exciting.

They are also exactly the things I kept running into.

So I started writing them down.

Not as another tutorial.

Just as a checklist I wanted for myself the next time I reached this stage.

That checklist became its own project

Eventually those notes turned into a small release workflow.

I made a lightweight version public on GitHub:

Spring Boot Release Checklist

It is a practical pre-release checklist for Spring Boot MVPs moving from localhost to production.

The idea is simple:

before calling an MVP ready, go through the things that are easy to miss when most of your attention has been on making the feature work.

I later expanded the same idea into a more structured 58-page deployment runbook, but the GitHub checklist remains the lightweight public version.

I did not originally plan to make a product out of it.

It came from repeatedly asking myself the same question while building:

“What am I forgetting before I ship this?”

I still don't think building first is the correct order

I would not turn this into advice like:

“Forget requirements. Just start coding.”

That would be the wrong lesson.

If anything, doing it backwards showed me why the earlier steps exist.

But there was something valuable about documenting a project after I had actually struggled with it.

The checklist was no longer theoretical.

Every item reminded me of something I had needed, forgotten, broken, or had to go back and check.

Maybe next time my process will be a little cleaner.

Probably not perfectly clean.

And that's fine.

I'm still learning by making things.

I keep more notes about development, AI tools, deployment, and the things that break along the way on the Nocklock blog.

You can also see the projects I'm building on GitHub

Spring Boot 4 + Spring AI + Langfuse: Tracing LLM Calls and Tool Calling

Wed, 23 Sep 2026 21:53:21 +0000

Part 2: Spring AI + Langfuse: Tracing Streaming with ObservationFilter

In this post, we will look at how to connect Spring AI with Langfuse and get complete tracing for LLM calls, tool calling, prompts, and responses.

Below is a demo project built with Spring Boot and Spring AI: an HTTP request invokes an LLM, WeatherTools is used when needed to fetch weather data from the internet, and traces, prompts, and responses are sent to Langfuse through OpenTelemetry and CallAdvisor.

Langfuse is a platform for monitoring and evaluating AI applications. The experience is very similar to LangSmith: you can trace LLM calls, inspect inputs and outputs, track latency and cost, and compare prompts and models. Langfuse also has an open-source version and can be self-hosted, which makes it a good choice for teams that need more control over their data and infrastructure.

The main dependencies in build.gradle:

dependencyManagement {
    imports {
        mavenBom 'org.springframework.ai:spring-ai-bom:2.0.0'
    }
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:4.1.0'
    implementation 'org.springframework.boot:spring-boot-starter-opentelemetry:4.1.0'
    implementation 'org.springframework.ai:spring-ai-starter-model-openai:2.0.0'

    compileOnly 'io.opentelemetry:opentelemetry-exporter-otlp:1.62.0'

    testImplementation 'org.springframework.boot:spring-boot-starter-test:4.1.0'
}

Application Configuration

In application.properties, configure OpenAI, Spring AI observability, and the Langfuse OTLP endpoint:

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-5
spring.ai.tools.observations.include-content=true
spring.ai.chat.client.observations.log-prompt=true
spring.ai.chat.client.observations.log-completion=true
spring.ai.chat.observations.log-prompt=true
spring.ai.chat.observations.log-completion=true

management.otlp.metrics.export.enabled=false
management.tracing.sampling.probability=1.0
management.tracing.export.otlp.enabled=${LANGFUSE_TRACING_ENABLED:false}
management.opentelemetry.tracing.export.otlp.endpoint=${LANGFUSE_OTLP_ENDPOINT:http://localhost:3000/api/public/otel}
management.opentelemetry.tracing.export.otlp.transport=http

langfuse.public-key=${LANGFUSE_PUBLIC_KEY:}
langfuse.secret-key=${LANGFUSE_SECRET_KEY:}

Since Langfuse is used for tracing, it is better to disable OTLP metric export. Otherwise, the application may try to send metrics to the same endpoint and get a ConnectException.

management.otlp.metrics.export.enabled=false

Controller

LangfusePromptTracingAdvisor adds the prompt and response to the Langfuse trace.

@RestController
class HelloAiController {

    private final ChatClient chatClient;
    private final WeatherTools weatherTools;

    HelloAiController(
            ChatClient.Builder chatClientBuilder,
            WeatherTools weatherTools,
            LangfusePromptTracingAdvisor langfusePromptTracingAdvisor
    ) {
        this.chatClient = chatClientBuilder
                .defaultAdvisors(langfusePromptTracingAdvisor)
                .build();

        this.weatherTools = weatherTools;
    }

    @GetMapping("/ai")
    String ai(
            @RequestParam(defaultValue = "Say hello in one short sentence")
            String message
    ) {
        return this.chatClient.prompt()
                .user(message)
                .tools(this.weatherTools)
                .call()
                .content();
    }
}

Tools

The tool uses Open-Meteo to find the coordinates of a city and retrieve the current weather for those coordinates.

@Component
class WeatherTools {

    private final RestClient restClient;

    WeatherTools(RestClient.Builder restClientBuilder) {
        this.restClient = restClientBuilder.build();
    }

    @Tool(description = "Get current weather for a city using live internet weather data")
    String getCurrentWeather(
            @ToolParam(description = "City name, for example Berlin or New York")
            String city
    ) {
        GeocodingResponse geocoding = this.restClient.get()
                .uri(
                        "https://geocoding-api.open-meteo.com/v1/search"
                                + "?name={city}&count=1&language=en&format=json",
                        city
                )
                .retrieve()
                .body(GeocodingResponse.class);

        if (geocoding == null
                || geocoding.results() == null
                || geocoding.results().isEmpty()) {
            return "Weather is unavailable: city not found: " + city;
        }

        Location location = geocoding.results().getFirst();

        ForecastResponse forecast = this.restClient.get()
                .uri(
                        "https://api.open-meteo.com/v1/forecast"
                                + "?latitude={latitude}"
                                + "&longitude={longitude}"
                                + "&current=temperature_2m,relative_humidity_2m,"
                                + "wind_speed_10m,weather_code",
                        location.latitude(),
                        location.longitude()
                )
                .retrieve()
                .body(ForecastResponse.class);

        if (forecast == null || forecast.current() == null) {
            return "Weather is unavailable for " + location.name();
        }

        CurrentWeather current = forecast.current();

        return "Current weather in %s, %s: %.1f C, humidity %d%%, "
                + "wind %.1f km/h, weather code %d."
                .formatted(
                        location.name(),
                        location.country(),
                        current.temperature2m(),
                        current.relativeHumidity2m(),
                        current.windSpeed10m(),
                        current.weatherCode()
                );
    }

    private record GeocodingResponse(List<Location> results) {
    }

    private record Location(
            String name,
            String country,
            double latitude,
            double longitude
    ) {
    }

    private record ForecastResponse(CurrentWeather current) {
    }

    private record CurrentWeather(
            @tools.jackson.annotation.JsonProperty("temperature_2m")
            double temperature2m(),

            @tools.jackson.annotation.JsonProperty("relative_humidity_2m")
            int relativeHumidity2m(),

            @tools.jackson.annotation.JsonProperty("wind_speed_10m")
            double windSpeed10m(),

            @tools.jackson.annotation.JsonProperty("weather_code")
            int weatherCode()
    ) {
    }
}

Sending Traces to Langfuse Through OpenTelemetry

Spring Boot sends traces through the spring-boot-starter-opentelemetry dependency. Langfuse requires Basic Authentication using the public and secret keys. The required environment variables are:

export LANGFUSE_TRACING_ENABLED=true
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...

A separate configuration adds the required HTTP headers:

@Configuration
class LangfuseTracingConfig {

    @Bean
    OtlpHttpSpanExporterBuilderCustomizer langfuseOtlpHeaders(
            @Value("${langfuse.public-key:}") String publicKey,
            @Value("${langfuse.secret-key:}") String secretKey
    ) {
        return builder -> {
            if (!StringUtils.hasText(publicKey)
                    || !StringUtils.hasText(secretKey)) {
                return;
            }

            String token = Base64.getEncoder()
                    .encodeToString(
                            (publicKey + ":" + secretKey)
                                    .getBytes(StandardCharsets.UTF_8)
                    );

            builder.addHeader("Authorization", "Basic " + token);
            builder.addHeader("x-langfuse-ingestion-version", "4");
        };
    }
}

Adding Prompts to Langfuse

Spring AI does not put the prompt and completion into the Langfuse input and output fields in the required format. To solve this, we use the standard Spring AI CallAdvisor mechanism.

@Component
class LangfusePromptTracingAdvisor implements CallAdvisor {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public ChatClientResponse adviseCall(
            ChatClientRequest chatClientRequest,
            CallAdvisorChain callAdvisorChain
    ) {
        var span = Span.current();

        String input = serializePrompt(chatClientRequest);

        span.setAttribute("langfuse.observation.type", "generation");
        span.setAttribute("input.value", input);
        span.setAttribute("langfuse.observation.input", input);

        ChatClientResponse chatClientResponse =
                callAdvisorChain.nextCall(chatClientRequest);

        String output =
                serializeResponse(chatClientResponse.chatResponse());

        span.setAttribute("output.value", output);
        span.setAttribute("langfuse.observation.output", output);

        return chatClientResponse;
    }

    @Override
    public String getName() {
        return "Langfuse Prompt Tracing Advisor";
    }

    @Override
    public int getOrder() {
        return ToolCallingAdvisor.DEFAULT_ORDER + 100;
    }

    private String serializePrompt(ChatClientRequest request) {
        var messages = request.prompt()
                .getInstructions()
                .stream()
                .map(message -> Map.of(
                        "role", message.getMessageType().getValue(),
                        "content", ofNullable(message.getText()).orElse("")))
                .toList();
        return toJson(messages);
    }

    private String serializeResponse(ChatResponse response) {
        return ofNullable(response).map(ChatResponse::getResult)
                .map(Generation::getOutput)
                .map(output -> toJson(

                        Map.of("role", output.getMessageType().getValue(),
                                "content", ofNullable(output.getText()).orElse(""),
                                "hasToolCalls", response.hasToolCalls())

                ))
                .orElse("");
    }

    private String toJson(Object value) {
        try {
            return this.objectMapper.writeValueAsString(value);
        }
        catch (JsonProcessingException ex) {
            return String.valueOf(value);
        }
    }
}

According to the Spring AI documentation, ToolCallingAdvisor manages the tool-calling loop itself, while getOrder() determines the advisor's position in the chain. Setting it to ToolCallingAdvisor.DEFAULT_ORDER + 100 places our advisor inside the tool-calling loop, so it runs on every iteration and can observe the original request, the model response that decides to call a tool, the following request containing the tool result, and the final model response.

What You Will See in Langfuse

Example request to the application:

curl "http://localhost:8080/ai?message=What%20is%20the%20weather%20in%20Berlin?"

Langfuse should display a trace with spans.

Generation spans will contain attributes such as:

langfuse.observation.type=generation
langfuse.observation.input=...
langfuse.observation.output=...
input.value=...
output.value=...

When the following option is enabled, Spring AI exports tool call arguments and results:

spring.ai.tools.observations.include-content=true

Production Considerations

Prompts, completions, and tool results may contain sensitive data. Traces are also typically stored longer than the application's runtime memory. For production, it is worth adding content truncation, sanitization, secret removal, and PII filtering.

Combining Spring AI Advisors with Langfuse through OTLP provides transparent tracing of LLM calls, prompts, responses, tool calls, and intermediate steps.

Android CI/CD for Beginners — Part 1: Introduction

Tue, 22 Sep 2026 17:12:07 +0000

Stop building everything manually. Learn how modern Android teams automate their development workflow

This series is designed to provide a complete understanding of CI/CD for Android development. In Part 1, we’ll introduce the fundamentals of CI/CD, explore what it is, why it matters, and how it’s used in Android app development.

CI/CD (Continuous Integration and Continuous Delivery/Deployment) is a set of practices that automate repetitive tasks in the software development process, such as building, testing, and releasing applications.

Instead of manually performing these tasks every time you make a change, a CI/CD pipeline executes them automatically whenever predefined events occur, such as pushing code to a Git repository.

How can CI/CD automate tasks in Android development?
CI/CD automates many of the repetitive tasks involved in the Android development lifecycle. Instead of running these steps manually every time you make a change, they can be executed automatically whenever code is pushed to your repository.

With a CI/CD pipeline, your Android app can be automatically:

Built using Gradle.
Analyzed for code quality with Android Lint.
Tested by running unit and instrumentation tests.
Packaged into a signed or unsigned APK or Android App Bundle (AAB).
Distributed to testers or prepared for release to the Google Play Store.
You might be wondering: Why do we need to automate these tasks?

In real-world Android projects, multiple developers often work on the same codebase. Every new feature, bug fix, or improvement is usually submitted as a pull request (PR).

Before those changes are merged, the team needs to ensure they meet the project’s quality standards and don’t introduce bugs or break existing functionality.

Manually building the app, running lint checks, executing tests, and verifying every pull request can quickly become repetitive and time-consuming, especially as the project grows.

This is where CI/CD becomes valuable. Whenever a pull request is opened or updated, a CI pipeline can automatically build the app, run lint checks, execute unit and instrumentation tests, and report whether all checks have passed.

If any step fails, developers are notified immediately, allowing issues to be fixed before the changes are merged.

Once all the automated checks succeed, the CD pipeline can take over by generating an APK or App Bundle and distributing it to testers or preparing it for release.

This eliminates many manual steps, speeds up the development process, and helps maintain a stable and reliable codebase.

Common CI/CD Terminology
Before we start building our first CI/CD pipeline, it’s important to understand some common terms you’ll encounter throughout this series. These concepts are not exclusive to Android development, they’re used across many CI/CD platforms. We’ll explore how these ideas come together in practice in the upcoming sections.

Pipeline
A pipeline is the complete automated process that runs after a specific event, such as pushing code to a Git repository or opening a pull request. A pipeline can build your app, run tests, generate an APK, and even distribute it to testers — all without manual intervention.

Think of a pipeline as a sequence of automated tasks executed in a predefined order.

Workflow
In GitHub Actions, a pipeline is defined using a workflow. A workflow is a YAML (.yml or .yaml) file stored inside the .github/workflows directory of your project.

It describes what should happen, when it should happen, and how it should be executed.

A repository can contain multiple workflows, each responsible for different tasks. For example, one workflow may run tests for every pull request, while another creates a release build whenever a new version is published.

Event (Trigger)
A workflow doesn’t run on its own — it needs an event, also known as a trigger.

Common triggers include:

Pushing code to a branch (push)
Opening or updating a pull request (pull_request)
Manually starting a workflow (workflow_dispatch)
Creating a release (release)
Whenever one of these events occurs, GitHub Actions starts the corresponding workflow.

Runner
A runner is the machine responsible for executing your workflow.

GitHub provides hosted runners running Linux, Windows, and macOS. For Android projects, Linux runners are commonly used because they provide a fast and cost-effective environment for building Android applications.

You can also configure your own self-hosted runner if you need custom hardware or software.

Job
A job is a collection of related tasks executed on the same runner.

For example, one job might build the Android app, while another runs unit tests. Multiple jobs can run sequentially or in parallel, depending on how the workflow is configured.

Step
A step is a single task inside a job.

Examples of steps include:

Checking out the repository
Setting up Java
Installing Android dependencies
Running Gradle commands
Uploading the generated APK
A job is simply a sequence of steps executed one after another.

Action
An Action is a reusable piece of automation that performs a specific task.

Instead of writing everything from scratch, you can use actions created by GitHub or the community.

For example:

actions/checkout downloads your repository onto the runner.
actions/setup-java installs and configures Java.
actions/upload-artifact uploads build outputs such as APKs or test reports.
Actions make workflows shorter, cleaner, and easier to maintain.

Artifact
An artifact is a file generated during a workflow that you want to keep after the workflow finishes.

In Android projects, common artifacts include:

APK files
Android App Bundles (AAB)
Lint reports
Unit test reports
Code coverage reports
Artifacts can be downloaded later for testing, debugging, or distribution.

GitHub Actions
Throughout this series, we’ll use GitHub Actions as our CI/CD platform.

GitHub Actions is GitHub’s built-in automation service that allows you to create workflows using YAML files. It automatically responds to events in your repository, runs your workflows on runners, and reports the results all directly within GitHub.

Now that you’re familiar with these core concepts, we’ll start creating our first Android CI workflow in the next part of this series.

That all it for now…
Lets stop here for now as this is already too much if your just starting out

Now that you understand the purpose of CI/CD and the terminology behind it, it’s time to build your first pipeline.

In Part 2, we’ll set up GitHub Actions, create our first workflow, and automatically build an Android application whenever code is pushed to GitHub.

👋Bye!!!

Faker Doesn't Know Your Entities Are Related, So I Built Something That Does

Tue, 22 Sep 2026 11:22:33 +0000

You've added a second entity to the schema, wired up a @ManyToOne, and gone back to your seed script to generate fifty more rows. Ninety seconds later, the app refuses to start: unique constraint violation, somewhere inside a loop you wrote three weeks ago at 11pm. You fix it. You restart. A different field breaks a different constraint.

This is the exact moment every Spring Boot developer eventually meets the real limit of tools like Faker. They're brilliant at generating a name, an email, an address. They have no idea the Payment sitting in front of them needs a Counterparty to already exist.

So you do what everyone does: hand-write the wiring. Create parents first. Hold onto their generated IDs. Wire them into children. Hope you didn't just violate a @NotNull somewhere in the process. It works, for a while. Then the schema changes, and the script quietly stops matching reality until the next 3am debugging session finds out the hard way.

I hit this enough times that I stopped patching the script and looked at the actual problem: the information needed to seed this correctly already exists. It's sitting right there in the entity, in the annotations you already wrote. @ManyToOne, @NotNull, @Column(unique = true), JPA already knows the shape of your data. Nothing should need to be told that twice.

That became SynthForge.

The core idea

Instead of writing a script that generates data, you annotate the entity:

@Entity @Seed(count = 50)
public class Counterparty { /* fields only */ }

@Entity @Seed(count = 200)
public class Payment {
    @ManyToOne(optional = false) private Counterparty counterparty;
}

Start the app in a dev profile. Both tables populate, correctly ordered, on every restart. No seed method. No calling code, anywhere. The entity is the seed script.

What's actually happening underneath

Entity scanning. SynthForge reads JPA-managed attributes through the jakarta.persistence.metamodel.Metamodel API, not raw reflection. That distinction matters more than it sounds: only real persistent fields ever get touched, nothing that merely resembles one.

Relationship ordering. From the owning-side @ManyToOne/@OneToOne relationships, it builds a dependency graph and topologically sorts it. Parent rows exist before a child is ever generated to reference them. This is precisely where hand-written scripts fail first: the moment a second level of nesting shows up, manual ID-tracking becomes its own source of bugs, the thing you're debugging instead of your actual feature.

Constraint-aware generation. @NotNull, @Size, @Email, and a set of field-name heuristics (email, iban, amount, country) drive realistic values through Datafaker. Hit a @Column(unique = true) field, and instead of a constraint violation forty rows in, you get a bounded retry loop.

Idempotent restarts. A table that already has rows gets skipped. Restart against a persistent database as many times as you want; nothing duplicates.

"Isn't this just Instancio?"

Fair question, and worth answering directly rather than dodging it. Instancio, and its instancio-jpa extension, gives you an API to call from inside a test: build a graph, persist it, for that one test. It's genuinely good at that job.

SynthForge isn't called from anywhere. Annotate the entity, start the app in an enabled profile, and the database is already populated before your code runs a single line. Different tool, because it solves a different moment: application startup, not a single test method.

Where it stands

Live on Maven Central:

<dependency>
    <groupId>io.github.thembatman0</groupId>
    <artifactId>synthforge-spring</artifactId>
    <version>0.1.0</version>
</dependency>

Repo: github.com/ThembaTman0/synthforge

It won't fix your architecture and it won't make decisions for you. But the next time you add a foreign key at 11pm, there's a decent chance it means you get to go to bed instead.

Why your Java 21 Virtual Threads might freeze under load (and how to spot pinning)

Tue, 22 Sep 2026 07:31:36 +0000

A lot of teams migrated to Java 21 and flipped spring.threads.virtual.enabled=true, expecting instant scaling without the reactive boilerplate.

And for basic I/O, it works great. But once high concurrency hits, some services start seeing unexplained HTTP timeouts and latency spikes, even though CPU and memory metrics look totally calm.

The culprit is usually Carrier Thread Pinning.

Project Loom mounts virtual threads onto underlying OS platform threads (Carrier Threads, managed by an internal ForkJoinPool). When a virtual thread hits a blocking network call, Loom unmounts it so the carrier can pick up other work.

Where it breaks: If a virtual thread enters a synchronized block or method and blocks inside on I/O, the JVM cannot unmount it. The virtual thread stays "pinned" to its carrier thread. If your server has 8 cores, 8 pinned threads waiting on slow external APIs will freeze your entire carrier pool—even if you have 50,000 other virtual threads ready to run.

Quick mitigation:

Replace synchronized with ReentrantLock around any blocking I/O (j.u.c primitives support clean unmounting).

Test locally with -Djdk.tracePinnedThreads=short to dump offending methods to stdout.

Keep an eye on third-party JDBC drivers and legacy SDKs that still use monitor locks on socket reads.

I wrote an open-source diagnostics tool and Spring Boot Actuator endpoint to track pinning ratios and pool saturation in real time (LoomDoctor), and put together an interactive simulator if you want to test how carrier starvation happens under load: https://frodygr.github.io/playground/#loomdoctor

Have you hit carrier pinning in your Java 21 deployments yet? How did your team catch it?

Spring Boot Authentication Boilerplate: From JWT Basics to Production-Ready Auth

Sun, 20 Sep 2026 16:50:00 +0000

Starting a new Spring Boot project usually feels great.

You create the project, add a few dependencies, write your first controller...

Then authentication enters the chat.

Suddenly you're configuring:

Spring Security
JWT access tokens
refresh tokens
roles and permissions
password hashing
exception handling
database migrations

Three hours later, your original feature still has exactly zero lines of code.

Congratulations. You built authentication again.

The auth code isn't the interesting part

Most applications need roughly the same authentication foundation.

Return an access token.

Refresh it safely.

Protect endpoints.

Check roles.

Logout.

Maybe add passkeys, OAuth, account recovery, or multiple sessions later.

None of this is particularly unique to your SaaS, internal tool, API, or side project.

But we keep rebuilding it.

I was doing the same thing with my Spring Boot projects, so I eventually turned that repeated setup into AuthKit.

AuthKit Lite

AuthKit Lite is the free and open-source version.

It gives you a working Spring Boot authentication foundation with:

JWT access tokens
rotating refresh tokens
Spring Security
role-based authorization
BCrypt passwords
optional WebAuthn passkeys
Flyway migrations
H2 for instant local testing
MySQL support
integration tests
a browser-based API testing page

The goal is simple:

Clone → run → test the APIs → start building your application.

git clone https://github.com/buildbasekit/AuthKit-Lite.git
cd AuthKit-Lite
./mvnw spring-boot:run

Then open:

http://localhost:8080/api-test

No Docker ceremony.

No spending your evening creating JWT filters for the 17th time.

No pretending you'll "clean up the auth code later."

You can find AuthKit Lite here:

https://buildbasekit.com/boilerplates/authkit-lite/

When Lite isn't enough

Basic authentication is enough for many projects.

But production applications often grow into things like:

email verification
password recovery
multiple user sessions
session revocation
refresh-token replay protection
OAuth2 / OIDC
account linking
magic links
passkeys
account lifecycle handling

That is where AuthKit Pro comes in.

It takes the same idea further: provide the authentication foundation while keeping the application-specific business logic in your application.

The important part for me was avoiding a giant framework that tries to own the entire application.

Auth should be infrastructure.

Not your new hobby.

AuthKit Pro is here:

https://buildbasekit.com/boilerplates/authkit-pro

Lite or Pro?

The easiest way to think about it:

AuthKit Lite

Use it when you need a clean Spring Boot authentication starting point or want to understand and extend the implementation yourself.

It's free and open source.

AuthKit Pro

Use it when the project needs more complete authentication flows and production-focused session and account lifecycle features.

Both are source-code foundations.

You still own the application.

You can change the architecture.

You can remove features.

You can add your own authorization rules.

And your business logic doesn't have to live inside somebody else's authentication service.

Why a boilerplate?

I'm not trying to eliminate authentication decisions.

You still need to decide things like:

token lifetimes
authorization rules
production secrets
rate limiting
monitoring
application-specific permissions

A boilerplate just means you don't have to start those decisions from an empty SecurityConfig.java.

That's the part I wanted to solve.

Because there are much more interesting bugs waiting for us in the actual product.

AuthKit Lite — Free & Open Source

https://buildbasekit.com/boilerplates/authkit-lite/

AuthKit Pro — Production-Focused

https://buildbasekit.com/boilerplates/authkit-pro

Built with Spring Boot and Spring Security.

If you're building Spring Boot APIs, I'd also be interested to know:

Do you rebuild authentication for every project, maintain your own starter, or use an external identity provider?

LangGraph4j 1.9.0: What's new and the roadmap

Sat, 19 Sep 2026 13:05:32 +0000

LangGraph4j 1.9.0 is out!

LangGraph4j 1.9.0 is out! With the 1.8.x release stream now in LTS, development moves forward on 1.9 with improvements to streaming, persistence, and the infrastructure for building agents in Java.

This release is an important step toward workflows that are easier to follow while they run and easier to inspect after they finish. A node can now report progress output before returning its result, checkpoint savers have a richer execution lifecycle, and Studio gets an UI refresh.

Let's look at what changes for an application built on 1.8.x, with particular attention to custom output from nodes and checkpoint management. The official migration guide provides details API reference for the changes discussed here.

Emit custom output while a node is running

Imagine a node that retrieves documents, processes them, and prepares a response. The caller may want to show progress throughout that work. Waiting for the final node output gives the user minimal information about what is happening in the meantime.

In 1.9, a node action can emit its own typed NodeOutput values through the active graph execution stream (graph.stream(...)). They arrive alongside the usual START, node, and END outputs, before the node has necessarily finished.

The mechanism is straightforward:

Define a subclass of NodeOutput carrying the information you want to expose.
Obtain a dispatcher from the node's RunnableConfig.
Dispatch custom outputs during execution.
Handle those types when consuming the graph stream.

Here is a small example.

public final class ProgressOutput extends NodeOutput<AgentState> {
    private final String message;

    public ProgressOutput(String node, AgentState state, String message) {
        super(node, state);
        this.message = message;
    }

    public String message() {
        return message;
    }
}

Inside the node, the dispatcher publishes a message while the returned map still provides the normal state update:

AsyncNodeActionWithConfig<AgentState> process = (state, config) -> {
    var dispatcher = config.<AgentState, ProgressOutput>customDispatcher();

    dispatcher.dispatchAsync(
        new ProgressOutput(config.nodeId(), state, "Processing documents"));

    // Perform the node's work here.

    return completedFuture(Map.of("result", "Documents processed"));
};

Once this action is registered in a compiled graph, the caller can recognize its progress messages:

graph.stream(GraphInput.noArgs(), RunnableConfig.empty()).forEachAsync( output -> {
        if (output instanceof ProgressOutput progress) {
            System.out.println(progress.message());
        } else {
            System.out.println("Graph step: " + output.node());
        }
    });

This gives us a useful channel for progress notifications, intermediate results, and application-specific events. Dispatching a custom output does not update graph state. If a value must influence routing, be available to later nodes, or become part of a persisted result, include it in the node's returned state update.

There are two dispatch options. dispatchSync(...) waits until the stream accepts the value and can throw InterruptedException; dispatchAsync(...) submits without waiting. The dispatcher is available during node execution in an active graph stream, including the supported hook context. Keep its use within that lifecycle: accessing it outside has an unpredicable result.

Custom events are intended for graph.stream(...) consumers; they do not change the result returned by graph.invoke(...). See the custom-output tutorial for the complete contract and a hook-based example.

The streaming engine behind it

This capability comes with a refactoring of the internal streaming engine around AsyncGeneratorFlow from async-generator 5.0 project.

Ordinary iteration over stream() remains source-compatible. Applications extending directly streaming generators, supplying a BlockingQueue, or depending on AsyncGenerator.WithResult need migration work.

Note: 👀

This refactoring is a groundwork for Reactor Flow support in a future LangGraph4j 2.0; that support is a future direction.

Checkpoint Savers: A richer execution lifecycle

Checkpoint persistence is central to long-running agents and Human-in-the-Loop workflows. In 1.9, the changes cover what happens when execution finishes, how released runs can be retrieved, how subgraph savers participate, and how interruptions and failures are recorded. These are the checkpoint changes I would review first when upgrading an existing application.

Completed runs release their thread by default

With a checkpoint saver configured, a graph that completes normally now releases its active thread automatically. Depending on the saver, release archives or tags its checkpoints and removes the active checkpoint set.

This matters if your application completes a graph, updates the same active thread's state, and executes it again. To retain the previous lifecycle, explicitly disable automatic release when compiling:

var compileConfig = CompileConfig.builder()
    .checkpointSaver(saver)
    .releaseThread(false) // backward compatible option
    .build();

var graph = workflow.compile(compileConfig);

An interruption or an exception does not automatically release the thread. Interrupted runs remain available for Human-in-the-Loop continuation, and failed runs remain available for the application's recovery strategy. graph.updateState(...) continues to work in those situations as before.

The practical upgrade check is to examine what your code does after successful completion. Any inspection, replay, resume, or manual-release logic that assumes an active checkpoint set needs attention.

Experimental versioning for released runs

Checkpoint tags gain optional version information. BaseCheckpointSaver.Tag exposes threadId(), version() as an Optional<Integer>, checkpoints(), and lastCheckpoint().

Two lookup methods make released runs accessible:

Optional<Tag> tag(RunnableConfig config, Integer version) throws Exception;

Optional<Tag> lastTag(RunnableConfig config) throws Exception;

The version argument to tag(...) is nullable. lastTag(...) retrieves the latest tag regardless of whether it is versioned.

GraphResult.asLastCheckpointStateData() now obtains its data through Tag.lastCheckpoint(), preserving its observable result. This is useful continuity for callers retrieving the final checkpoint state while the underlying release model evolves.

Parent and Subgraph savers work together

Subgraphs increasingly carry real agent behavior, so their persistence lifecycle must follow the parent execution.

BaseCheckpointSaver now supports putSubGraphSaver(...) to register a subgraph saver and listSubGraphSaver(...) to retrieve registrations associated with a parent configuration. SubCompiledGraphNodeAction registers its saver with the parent; AbstractCheckpointSaver.release(...) then cascades release to the registered subgraph threads.

If you implement a custom saver, AbstractCheckpointSaver provides a reference implementation of the registration mechanism. Review that lifecycle when adapting your implementation, especially if your agents contain nested compiled graphs.

Interruption and Error Metadata

The saver contract also exposes explicit lifecycle hooks:

void registerInterruption(
    RunnableConfig config,
    InterruptionMetadata interruptionMetadata) throws Exception;

Tag releaseCheckpointsOnError(
    RunnableConfig config,
    Throwable error) throws Exception;

These allow a saver to retain interruption information and distinguish an error release from normal completion. InterruptionMetadata now also exposes the interruption reason. That gives later analysis more context about why an execution stopped.

The error-release hook does not change the default described above: an exception leaves the thread available, and the caller chooses its recovery or release strategy.

Note: 👀

To avoid leaving lots of unfinished records in the checkpoint persistence layer, we recommend calling saver.releaseOnError(RunnableConfig, Throwable) within exception handling logic. We are currently considering automating this in a future release by having the graph execution engine invoke the method whenever an error occurs.

The in-memory, file-system, Redis, Postgres, Oracle, MySQL, CockroachDB, DynamoDB, and Hazelcast savers have been aligned with this contract through default implementations. The amount of information retained remains a concern of the specific saver implementation.

SQLite and PostgreSQL V2 savers

Both relational integrations add implementations backed by versioned SQL resources:

Integration	New implementation	Existing implementation
SQLite	`SQLiteSaverV2`	`SQLiteSaver`, for the V1 schema
PostgreSQL	`PostgresSaverV2`	`PostgresSaver`, for the V1 schema

The V2 implementations align with the updated release, error, and interruption contract. The original classes remain available for their V1 schemas. Treat adoption of a V2 saver as a persistence change to review against your existing database.

Other changes worth knowing before upgrading

Explicit Graph Inputs

GraphInput becomes the preferred API for expressing whether an execution is starting or resuming:

graph.stream(GraphInput.args(Map.of("input", "Hello")), config);
graph.stream(GraphInput.resume(), config);
graph.stream(GraphInput.resume(Map.of("approval", "APPROVED")), config);

Use GraphInput.noArgs() for a new execution without arguments. The older map-based stream and invoke overloads remain available in 1.9, but are deprecated for removal. Moving away from a null map makes the intended operation explicit.

Diagnostics and State Serialization

RunnableConfig.nodePath() supplies the current node path for regular nodes and subgraphs, replacing the older partial graphPath() usage. A node can also intentionally interrupt execution by raising GraphInterruptException.

State cloning remains enabled by default. RunnableConfig.builder().disableCloneState() opts out, which can help during early development with objects that are not yet serializable. Exposed state may then reflect later mutations, so consider how consumers retain or modify it.

StateSerializer.declareTransientAttributes(...) excludes named attributes from serialized data and restores them from the same serializer's in-memory transient storage. Those values do not survive a restart, a different process, or a new serializer instance. Keep anything needed for durable resume in persisted state. GsonStateSerializer is deprecated for removal; move toward Jackson-based serialization.

Agent infrastructure

The experimental core skills API introduces SkillSource, SkillPath, and SkillParser.

Spring AI builds on this with SubAgent, CustomSubAgent, SkilledReactSubAgent, and SkillResource, making compiled agents reusable as tools. I covered the pattern in Skill-Based Sub-Agents with LangGraph4j and Spring AI.

LangGraph4j Studio gets a visual refresh

Studio 1.8

Studio 1.9

In the new Studio the active node receives a blue highlight and a loading indicator, making execution easier to follow at a glance.

LangGraph4j DSL

The release also adds langgraph4j-dsl, whose JsonDslGenerator exports graphs, including parallel nodes and nested subgraphs, as JSON:

String json = compiledGraph.reduce(new JsonDslGenerator<>());

This representation has been used for the Studio refactoring toward React Flow library.

What's Next for LangGraph4j

The next phase of development will focus on three areas. These are roadmap priorities, with scope and delivery to evolve as implementation progresses.

Persist more of the execution context

I want to improve graph execution-context persistence so that it supports monitoring and post-processing analysis more effectively. The checkpoint lifecycle work in 1.9 is a step in that direction: understanding completed, interrupted, and failed runs is essential when agentic workflows move into production.

The aim is to make retained execution information more useful for understanding behavior and for subsequent analysis and processing.

Redesign parallel node execution

Another priority is to redesign the parallel-node implementation, removing current limitations and improving efficiency. As workflows grow, parallel branches need to become easier to compose and manage.

This is upcoming work. Applications using 1.9 should continue to account for the currently documented parallel-execution limitations.

Improve built-in Agents for Spring AI and LangChain4j

Finally, I want to enhance the built-in agent infrastructure for both Spring AI and LangChain4j. The skills and sub-agent work demonstrates how much can be built on top of graph execution; the goal is to make those building blocks more useful and easier to compose across both integrations.

Try the Release

Update the LangGraph4j BOM to 1.9.0 to keep module versions aligned:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.bsc.langgraph4j</groupId>
      <artifactId>langgraph4j-bom</artifactId>
      <version>1.9.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Conclusions

For an existing 1.8.x application, start with the migration guide, review thread release and stored checkpoint compatibility, then exercise interruption, resume, and completion paths with your chosen saver.

I'm interested in feedback from real workflows, especially around custom progress output and checkpoint management. Check out LangGraph4j, try the release, and let me know what would help your next agentic application. If you find the project useful, leave a star ⭐️ and... happy AI coding! 👋

Write a java program to count the letters, spaces, numbers and other characters of an input string.

Thu, 03 Sep 2026 12:40:15 +0000

First take the input form the user as a string
copy that string into a character array
write logic for checking each character of character array is a letter/number/space/other-character
print all the updated values of variables

Note :- There is pre-built fuctions to copy all characters of string into a character array which is :
char name_of_character_array[ ] = name_of_string.toCharArray and There are also pre-bilut functions are there to check weather character is letter/number/space in an array which are : Character.isLetter(ch[i]) , Character.isDigit(ch[i]) , Character.isSpaceChar(ch[i]) respectively

768. Max Chunks To Make Sorted II

Mon, 10 Aug 2026 17:51:40 +0000

Problem
You are given an integer array arr.

We split arr into some number of chunks (i.e., partitions), and individually sort each chunk. After concatenating them, the result should equal the sorted array.

Return the largest number of chunks we can make to sort the array.

Example 1:

Input: arr = [5,4,3,2,1]
Output: 1
Explanation:
Splitting into two or more chunks will not return the required result.
For example, splitting into [5, 4], [3, 2, 1] will result in [4, 5, 1, 2, 3], which isn't sorted.
Example 2:

Input: arr = [2,1,3,4,4]
Output: 4
Explanation:
We can split into two chunks, such as [2, 1], [3, 4, 4].
However, splitting into [2, 1], [3], [4], [4] is the highest number of chunks possible.

Constraints:

1 <= arr.length <= 2000
0 <= arr[i] <= 108

Discussion

This can be solved by traversing the array twice. The first time we put the elements in a min-heap/priority queue. This ensures that we have a list of the elements sorted in ascending order. Then we create 3 integer variables. One stores the sum of the sorted elements in the heap and is named sum. The second stores the total of the elements traversed in the array and is named total. The third stores the maximum number of chunks and is named answer.

We then traverse the array for the second time. We pull the topmost element from the heap and add it to sum. We add the element at the current index in the array and add to total. If the values are equal, we increment answer. Once we have traversed the array, we return the value of answer.

Solution

Java

class Solution {
    public int maxChunksToSorted(int[] arr) {
     PriorityQueue<Integer> pq=new PriorityQueue<>();
     int total=0;
     int sum=0;
     int answer=0;
     for(int i=0;i<arr.length;i++)pq.offer(arr[i]);
     for(int i=0;i<arr.length;i++){
      sum+=pq.poll();
      total+=arr[i];
      if(sum==total)answer++;  
     }
     return answer;
    }
}

Cannot make a static reference to the non static method

Thu, 02 Jul 2026 05:34:59 +0000

"Cannot make a static reference to the non-static method" is an error message that may appear in Java when attempting to call a non-static method from a static context. In this article, we will explore the meaning of the error message, its causes, and how to resolve it.

Difference between static and non-static methods

Static methods, also known as class methods, are methods that are associated with a class rather than an instance of the class. These methods can be called directly on the class, without the need to create an instance of the class first. They do not have access to the non-static members (instance variables or methods) of the class, but they can access the static members. A common use case for static methods is utility methods, such as mathematical operations or string manipulation.

On the other hand, non-static methods, also known as instance methods, are methods that are associated with an instance of a class. These methods can only be called on an instance of the class, and they have access to both the static and non-static members of the class. A common use case for non-static methods is methods that perform operations on the instance variables of the class, such as getting or setting their values.

To define a static method in Java, the keyword static is added before the return type of the method. For example:


public static int addTwoNumbers(int a, int b) {
    return a + b;
}

On the other hand, non-static method does not have the keyword static before the return type of the method. For example:


public int addTwoNumbers(int a, int b) {
    return a + b;
}

Note the main difference between static and non-static methods in Java is that static methods are associated with the class and can be called directly on the class, while non-static methods are associated with an instance of the class and can only be called on an instance of the class.

Why the error?

The error message "Cannot make a static reference to the non-static method" occurs when a non-static method is called directly from a static context, such as a static method or the main method. This is because a non-static method belongs to an instance of a class, and a static context does not have access to an instance.

Here is an example of code that will produce the error message:


class MyClass {
    public void nonStaticMethod() {
        System.out.println("This is a non-static method.");
    }

    public static void main(String[] args) {
        nonStaticMethod(); // Error: Cannot make a static reference to the non-static method nonStaticMethod()
    }
}

In the example above, the nonStaticMethod() is being called directly from the main method, which is a static context. To fix this error, you can either make the nonStaticMethod() static or create an instance of the class and call the nonStaticMethod() on that instance.

How to fix the error

Here is an example of how to fix the error by making the nonStaticMethod() static:


class MyClass {
    public static void nonStaticMethod() {
        System.out.println("This is a non-static method.");
    }

    public static void main(String[] args) {
        nonStaticMethod(); // This will now work
    }
}

And here is an example of how to fix the error by creating an instance of the class:

It is important to note that the error message "Cannot make a static reference to the non-static method" is not limited to the main method. It can also occur when a non-static method is called directly from a static method or a static block of code.


class MyClass {
    public void nonStaticMethod() {
        System.out.println("This is a non-static method.");
    }

    public static void main(String[] args) {
        MyClass myObj = new MyClass();
        myObj.nonStaticMethod(); // This will now work
    }
}

Assigning a Non-Static Variable to a Static Variable

It is not possible to assign a non-static variable to a static variable because they have different contexts, and the reference would not match. However, since static properties can be accessed directly without creating an object of the class, you can create an object of the class and use it to access the non-static variables. Then, you can use this reference to assign the variable to static fields or use it in static methods.


public class Main {
    // create a static variable
    static String staticVariable = "Static Variable";
    //create none static variable
    String nonStaticVariable = "Non Static Variable";

    public static void main(String args[]) {
        // Create an object of the class
        Main main_obj = new Main();

        // Assign the non-static variable to the static variable
        main_obj.staticVariable = main_obj.nonStaticVariable;

        // print the static variable
        System.out.println(main_obj.staticVariable);
        // output:
        //Non Static Variable
    }
}

The code creates a static variable called staticVariable and a non-static variable called nonStaticVariable. In the main method, an object of the class is created, and the value of the non-static variable is assigned to the static variable. The static variable is then printed, which should output Non Static Variable.

Conclusion

In conclusion, "Cannot make a static reference to the non-static method" is an error message that occurs when a non-static method is called directly from a static context. To fix this error, you can either make the non-static method static or create an instance of the class and call the non-static method on that instance. Understanding the difference between static and non-static methods and the scope of each will help avoid this error in your code.

References

Oracle Java Tutorials - Class Members: https://docs.oracle.com/en/java/javase/14/docs/specs/jls/se14/html/jls-8.html#jls-8.3
Oracle Java Tutorials - Creating and Using Methods: https://docs.oracle.com/en/java/javase/14/docs/specs/jls/se14/html/jls-8.html#jls-8.4
Oracle Java Tutorials - Understanding Class Members: https://docs.oracle.com/en/java/javase/14/docs/specs/jls/se14/html/jls-8.html#jls-8.3
Oracle Java Tutorials - Understanding Instance and Class Variables: https://docs.oracle.com/en/java/javase/14/docs/specs/jls/se14/html/jls-8.html#jls-8.3.1

AI Agents Are Now Handling Java Migrations - Here's What That Means for You

Wed, 01 Jul 2026 10:07:51 +0000

Legacy software migrations used to be the kind of project that kept CTOs up at night. But AI agents are starting to take on work that once required months and expensive specialists - and it's worth understanding what's actually happening.

The Real Cost of Living With Old Code
If you've ever worked near a software team managing a legacy Java codebase, you know the tension. The application works - sort of. But it runs on an older framework version that the vendor no longer fully supports. Security patches are slow to arrive. New developers struggle to onboard because the patterns are outdated. And every time someone suggests migrating to a modern framework version, the room goes quiet.

The hesitation is understandable. A typical enterprise Java migration - say, moving from an older version of Spring Boot to a current one, or shifting from a legacy Jakarta EE setup - involves hundreds or thousands of files. Dependency trees have to be untangled. APIs that changed between versions need to be mapped and rewritten. Tests have to be updated. It's painstaking, detail-oriented work that traditionally required experienced engineers who knew both the old and new frameworks deeply.

For small businesses or lean product teams, this kind of project often just gets deferred indefinitely. The cost in time and money is too high relative to other priorities. So the technical debt compounds, quietly making every future feature harder to build.

What AI Agents Actually Do Differently
There's an important distinction worth drawing here between an AI chatbot and an AI agent. When you use a chatbot to help with code, you're having a conversation - you paste in a snippet, it suggests a fix, you apply it manually and move on. Useful, but still mostly you doing the work.

An AI agent is different. It can take a goal, break it into subtasks, execute those subtasks across multiple files and systems, check its own work, and iterate - often without needing you to hold its hand at every step. Applied to a codebase migration, that means an agent can scan the entire project, identify deprecated API calls, apply the correct replacements according to the new framework's documentation, update configuration files, and run tests to verify nothing broke - all in sequence.

What makes this newly viable is a combination of factors: better reasoning in large language models, improved tool-use capabilities that let agents interact with file systems and code execution environments, and growing investment in benchmarking frameworks that measure how well agents actually perform on real migration tasks. Researchers and engineering teams are now building structured evaluations - essentially standardized test suites - so we can measure whether an agent truly migrated code correctly, not just whether it looks plausible on the surface.

Real Example - Step by Step
Let's say you're a product manager at a mid-sized company. Your engineering team maintains a Spring Boot 2.x application that needs to move to Spring Boot 3.x to maintain security compliance. There are roughly 400 Java files involved. Your lead developer estimates it's a 6-to-8-week project done manually, and the team is already stretched.

Here's roughly how an AI agent-assisted migration plays out in practice:

Step 1 - Discovery. The agent is pointed at the repository. It scans every file, catalogs all dependencies listed in the build file (Maven or Gradle), and flags every API call or annotation that changed between versions. This produces a migration map.

Step 2 - Planning. The agent ranks changes by complexity - straightforward dependency version bumps versus more involved refactors where the underlying API signature changed significantly. It creates a work queue.

Step 3 - Execution. Starting with the lower-risk changes, the agent rewrites code file by file. It handles things like namespace changes (a significant one in Spring Boot 3.x was the move from javax to jakarta packages), updated annotation patterns, and deprecated method replacements.

Step 4 - Verification. The agent runs the existing test suite after each batch of changes. Where tests fail, it examines the failure, determines whether the issue is in the migration logic or in the test itself, and attempts a fix.

Step 5 - Handoff. The agent produces a summary report: what was changed, what it couldn't resolve automatically, and what needs human review. Your engineer reviews the flagged items - a much smaller task than doing the whole migration from scratch.

What took weeks manually might realistically take a long weekend of compute time, with your engineer spending a day reviewing edge cases rather than doing the bulk migration themselves.

How to Apply This Today
You don't need to be a developer to start thinking about this strategically. Here's what you can do right now:

If you're evaluating vendors or tools: Look for solutions that can show you benchmark results on standardized migration tasks - not just demos on clean toy examples. The quality gap between agents is significant, and real evaluation data matters.

Start small. Even a modest pilot - migrating one module or one service - gives your team confidence in the process and surfaces the edge cases before you commit to something larger.

Key Takeaways
Legacy migration projects are a major source of deferred technical debt, especially for smaller teams
AI agents differ from chatbots by executing multi-step tasks autonomously across entire codebases
Benchmarking frameworks are emerging to measure agent migration quality on real, standardized tasks
A human engineer's role shifts from doing the migration to reviewing the agent's output - a much faster process
Even non-technical stakeholders can drive this conversation by asking the right questions of their engineering teams
What's your experience with this? Drop a comment below - I read every one.

Sources referenced: ScarfBench: Benchmarking AI Agents for Enterprise Java Framework Migration - Hugging Face Blog

Counting Characters in a String using Java/ Poor Deleted

Sat, 20 Jun 2026 01:33:03 +0000

Introduction:

In this article, we will discuss how to write a Java program to count the letters, spaces, numbers, and other characters in an input string. We will explore different methods of solving this problem and provide tips and guidelines for writing efficient and accurate code.

1. What is the problem?

The problem is to write a Java program that takes an input string and counts the number of letters, spaces, numbers, and other characters in the string.

2. Why does this problem occur?

This problem occurs because it is often necessary to analyze and understand the structure of a given text or string. This can be useful in various applications such as text processing, natural language processing, and data analysis.

3. How to resolve:

- Solution 1:Using a for loop and if-else statements:

The first solution to this problem is to use a for loop to iterate through each character in the input string and use if-else statements to check if the character is a letter, space, number, or other character.

One way to count the number of letters, spaces, numbers and other characters in a string is by using a for loop to iterate over each character in the string. For each character, we can check its ASCII value and increment the count of the corresponding category. For example, if the ASCII value of a character is between 65 and 90 or 97 and 122, we can increment the count of letters. Similarly, if the ASCII value is 32, we can increment the count of spaces. If the ASCII value is between 48 and 57, we can increment the count of numbers. And for all other characters, we can increment the count of other characters.


public static void countCharacters(String input) {
    int letter = 0, space = 0, num = 0, other = 0;
    for (int i = 0; i < input.length(); i++) {
        char ch = input.charAt(i);
        if (Character.isLetter(ch)) {
            letter++;
        } else if (Character.isSpaceChar(ch)) {
            space++;
        } else if (Character.isDigit(ch)) {
            num++;
        } else {
            other++;
        }
    }
    System.out.println("Letters: " + letter);
    System.out.println("Spaces: " + space);
    System.out.println("Numbers: " + num);
    System.out.println("Other: " + other);
}

In this solution, we first initialize four variables to store the count of letters, spaces, numbers, and other characters. Then, we use a for loop to iterate over each character in the input string. For each character, we use the Character class's isLetter(), isSpaceChar(), and isDigit() methods to check if the character is a letter, space, or digit, respectively. If the character is a letter, we increment the count of letters. If the character is a space, we increment the count of spaces. If the character is a digit, we increment the count of numbers. And for all other characters, we increment the count of other characters. Finally, we print out the count of each category. This solution is a simple and easy to understand, but it has a time complexity of O(n), where n is the length of the input string, as we need to iterate over each character in the string..

Solution 2: Using an enhanced for loop

One way to solve the problem of counting the number of letters, spaces, numbers, and other characters in a given input string is by using an enhanced for loop. An enhanced for loop is a simpler version of a traditional for loop that is used to iterate through the elements of an array or collection.


public static void countCharacters(String input) {
    int letter = 0, space = 0, num = 0, other = 0;
    for (char ch : input.toCharArray()) {
        if (Character.isLetter(ch)) {
            letter++;
        } else if (Character.isSpaceChar(ch)) {
            space++;
        } else if (Character.isDigit(ch)) {
            num++;
        } else {
            other++;
        }
    }
    System.out.println("Letters: " + letter);
    System.out.println("Spaces: " + space);
    System.out.println("Numbers: " + num);
    System.out.println("Other: " + other);
}

This solution is similar to solution 1, but instead of using a traditional for loop, it uses an enhanced for loop to iter

- Solution 3: Using a HashMap

Another way to count the number of occurrences of each character in a string is to use a HashMap. A HashMap is a data structure that stores key-value pairs, where the key is the character and the value is the number of occurrences of that character.

To implement this solution, we will first create an empty HashMap and then iterate through the string, adding each character to the HashMap and incrementing the count of that character if it already exists. Once the iteration is complete, we can then iterate through the HashMap and print out the character and its count.

Here is an example implementation of this solution:


        import java.util.HashMap;
    
    public class CharacterCount {
        public static void main(String[] args) {
            String input = "This is a sample string";
            HashMap charCount = new HashMap<>();
    
            for (int i = 0; i < input.length(); i++) {
                char c = input.charAt(i);
                if (charCount.containsKey(c)) {
                    charCount.put(c, charCount.get(c) + 1);
                } else {
                    charCount.put(c, 1);
                }
            }
    
            for (char c : charCount.keySet()) {
                System.out.println(c + ": " + charCount.get(c));
            }
        }
    }

This solution has the advantage of being more efficient than the previous solution, as it only needs to iterate through the string once, whereas the previous solution needed to iterate through the string twice. Additionally, the HashMap allows for easy retrieval of the count for a specific character, which can be useful in certain situations.

- Solution 3: Using Regular Expression

Here is a sample Java program that uses regular expressions to count the number of letters, spaces, numbers, and other characters in an input string:


     import java.util.regex.Matcher;
    import java.util.regex.Pattern;
    import java.util.Scanner;
    
    public class CharacterCounter {
        public static void main(String[] args) {
            Scanner sc = new Scanner(System.in);
            System.out.print("Enter a string: ");
            String input = sc.nextLine();
    
            int letterCount = 0;
            int spaceCount = 0;
            int numCount = 0;
            int otherCount = 0;
    
            // Define regular expressions for letters, spaces, numbers, and other characters
            String letterRegex = "[a-zA-Z]";
            String spaceRegex = "\\s";
            String numRegex = "\\d";
            String otherRegex = "[^a-zA-Z\\s\\d]";
    
            // Create pattern objects
            Pattern letterPattern = Pattern.compile(letterRegex);
            Pattern spacePattern = Pattern.compile(spaceRegex);
            Pattern numPattern = Pattern.compile(numRegex);
            Pattern otherPattern = Pattern.compile(otherRegex);
    
            // Create matcher objects
            Matcher letterMatcher = letterPattern.matcher(input);
            Matcher spaceMatcher = spacePattern.matcher(input);
            Matcher numMatcher = numPattern.matcher(input);
            Matcher otherMatcher = otherPattern.matcher(input);
    
            // Count the number of matches for each regular expression
            while (letterMatcher.find()) {
                letterCount++;
            }
            while (spaceMatcher.find()) {
                spaceCount++;
            }
            while (numMatcher.find()) {
                numCount++;
            }
            while (otherMatcher.find()) {
                otherCount++;
            }
    
            // Print the results
            System.out.println("Letters: " + letterCount);
            System.out.println("Spaces: " + spaceCount);
            System.out.println("Numbers: " + numCount);
            System.out.println("Other: " + otherCount);
        }
    }

This program prompts the user to enter a string and uses four regular expressions to match letters, spaces, numbers, and other characters in the input string. The program uses the 'Matcher' class to find all occurrences of each regular expression in the input string, and uses a while loop to count the number of matches for each regular expression. Finally, the program prints the results to the console.

It's worth mentioning that there are other ways like using String.replaceAll() to count the characters and loops as well , but using regular expression is more efficient and flexible.

4. Conclusion:

In conclusion, writing a program to count the letters, spaces, numbers and other characters of an input string in Java is a common task that can be achieved through various methods. By understanding the problem, its causes and the available solutions, it is possible to write an efficient and accurate program. The solutions discussed in this article include using a for loop, HashMap. Each of these solutions has its own advantages and disadvantages and can be used depending on the specific requirements of the task. Ultimately, by understanding and practicing these solutions, programmers can improve their skills and become more proficient in Java programming.

CodeRef - Smart Java Analyzer with ML Engine

Tue, 09 Jun 2026 08:37:00 +0000

How a Single IntelliJ Plugin Cut Our Code Review Rework by 60% — A 6-Month Honest Review

Developer's IntelliJ IDEA workspace with CodeRef's analysis report open in the bottom panel, showing zero critical issues on a Spring Boot service class after automatic refactoring.

I'm a backend engineer on a team of eight. We build microservices in Spring Boot, and like most Java teams, we use SonarQube in our CI pipeline to enforce code quality gates. It's a solid tool and we rely on it.

But there was always a gap in our workflow — the feedback only arrived after pushing code. I'd get a SonarQube report 12 minutes later telling me I introduced a cognitive complexity violation on line 47. By then I've already moved on to the next ticket. The quality gate was working, but the feedback loop was slow.

Six months ago, a colleague dropped a link to CodeRef in our team Slack channel. "Try this, it catches stuff before you even commit." I installed it expecting another linter that I'd disable within a week.

I haven't disabled it. Here's why.

Week 1: The Instant Feedback Loop Changes Everything

The first thing that hit me was speed. I opened a service class I'd been working on, and within seconds the Report tab at the bottom of my IDE lit up with findings — not after a CI pipeline, not after a PR review, but right there while I was still writing the method.

CodeRef analysis appearing within seconds of opening a Java file, with the Report tab showing three findings: a cognitive complexity violation, a missing @Transactional annotation, and field injection flagged for constructor migration.

That first day, it caught three things in a class I was about to push:

A @Transactional annotation on a private method — Spring proxies don't intercept private methods, so the annotation was doing absolutely nothing. This had been in production for two sprints. Traditional static analysis tools don't typically flag this because it's a framework-specific pattern that requires understanding Spring's proxy mechanism.
An Optional.get() without an isPresent() check — I knew better, but I was moving fast and missed it. Classic.
Field injection on three @Autowired fields — not a bug, but CodeRef flagged it with a clear explanation of why constructor injection is preferred for testability.

What made this powerful was the timing. Having analysis run inside the IDE meant I fixed all three before committing. No CI round-trip. No PR comment. No context-switching back to code I wrote an hour ago. By the time our CI pipeline ran its quality gate, the code was already clean.

Week 3: The Auto-Fixers Saved Me Hours

I'll be honest — I almost ignored the "Refactored Code" tab for the first two weeks. I assumed it would be naive find-and-replace suggestions.

Then I had a 45-line method that CodeRef flagged for cognitive complexity (S3776). Out of curiosity, I clicked the tab. It had extracted two nested blocks into well-named private methods, preserved the logic perfectly, and presented the result as a clean diff.

I copied it over. It compiled. Tests passed. What would have been a 15-minute manual refactor took 30 seconds.

CodeRef's Refactored Code tab showing a side-by-side diff where a 45-line method with nested conditionals has been split into three focused methods, with the extracted methods named after their business logic.

Since then, the fixers I use constantly:

Try-with-resources conversion — I have a codebase with legacy try-finally blocks everywhere. CodeRef converts them one click at a time. I've cleaned up about 30 so far during regular feature work, no dedicated refactoring sprint needed.
Constructor injection migration — We decided as a team to move away from @Autowired field injection. Instead of a bulk find-and-replace that would break things, I let CodeRef migrate each class as I touch it. It adds the final field, creates the constructor parameter, and removes the annotation.
String concatenation in loops — It found three StringBuilder opportunities in our batch processing code. The performance improvement was measurable in our metrics dashboard.

The key insight: the fixes aren't suggestions, they're working code. I review the diff, apply it, and move on. The plugin does the mechanical refactoring so I can focus on the logic.

Month 2: Test Generation Accelerated Our Coverage Push

Our team had a quarterly goal to get test coverage from 54% to 75%. Everyone was dreading the "write tests for existing code" phase.

CodeRef's test generation changed the math on that effort entirely.

For a @RestController with five endpoints, it generated a complete @WebMvcTest class with MockMvc setup, mock dependencies, and test methods for each mapping — including exception cases. Was it perfect? No. I adjusted assertions and added edge cases specific to our business logic. But the scaffolding was correct and the boilerplate was done.

CodeRef's Test Cases tab showing a generated @WebMvcTest class for an OrderController, with MockMvc injection, mocked OrderService, and test methods for GET /orders, POST /orders, and GET /orders/{id} including 404 handling.

For @Service classes, it set up MockitoExtension with the right @Mock and @InjectMocks fields by reading the constructor parameters. For our @Repository classes, it generated @DataJpaTest with TestEntityManager.

What used to take 20–30 minutes per class (setting up the test class, figuring out which mocks to wire, writing the first few test methods) now takes 5 minutes of review and customization.

We hit 78% coverage three weeks ahead of schedule. I'm not going to attribute that entirely to CodeRef — the team put in real work on the complex test scenarios. But eliminating the boilerplate setup meant we spent our time on the tests that actually matter.

Month 3: The ML Engine Started Earning Its Keep

For the first two months, I occasionally dismissed findings that weren't relevant to our codebase. A TODO comment warning on a ticket-tracked TODO. A magic number flag on a well-known HTTP status code. The usual noise.

Around week 10, I noticed something: those warnings stopped appearing. CodeRef's ML engine had been quietly learning from my dismissals and started suppressing similar false positives.

I checked the ML insights panel — it had suppressed 23 findings that week that matched patterns I'd previously dismissed. Every single suppression was correct.

This is the feature that turned CodeRef from "good tool" to "tool I'd fight to keep." Every other linter I've used has a static configuration — you either suppress a rule globally or you deal with the noise. CodeRef learns what matters to you and adjusts. The signal-to-noise ratio gets better every week.

The severity re-ranking was a subtler benefit. Our team cares deeply about resource leaks (we had a production incident caused by an unclosed database connection), so I always prioritized those fixes. After a few weeks, CodeRef started bumping resource-related findings to Critical automatically. It understood our priorities without me writing a config file.

Month 5: Spring-Specific Rules Caught Two Production Bugs Before They Shipped

This is the story I tell when people ask if CodeRef is worth the Pro license.

Bug #1: Self-invocation bypassing @Transactional

We had a service method that called another method in the same class, both annotated with @Transactional. The inner call wasn't going through the Spring proxy, so it was running without a transaction boundary. In our test environment with small datasets, this was invisible. In production with concurrent writes, it would have caused data inconsistency.

CodeRef flagged it as S5962 (Spring proxy self-invocation bypass) with a clear explanation of why the proxy doesn't intercept internal calls. I refactored it to use a separate service class. Total time to fix: 10 minutes.

Bug #2: @ConfigurationProperties without @Validated

A configuration class was binding external properties without validation. One of the properties was a connection timeout that defaulted to zero when not set. In our staging environment, the property was always present. In a new deployment environment that was being provisioned, it wasn't — and zero meant "no timeout," which meant threads hanging indefinitely.

CodeRef flagged the missing @Validated annotation (S5975). I added it along with @NotNull and @Positive constraints. The new environment launched without issues.

Neither of these would have been caught by PMD or SpotBugs alone. They require understanding Spring's proxy mechanism and configuration binding behavior. This is what framework-aware analysis means in practice.

Month 6: Project-Wide Analysis for Sprint Planning

We recently started using CodeRef's project-wide scan before sprint planning. The scan runs across the entire Maven project and produces an aggregate report with per-file severity distribution.

What makes this useful alongside our CI quality gates is the developer experience:

Runs locally in the IDE — no context-switching to a browser dashboard, results in about 90 seconds for our 200-file project
ML-enhanced results — the bug risk score highlights files that are structurally complex and frequently modified, so we know where to focus review effort
Actionable next steps — every finding has an auto-fixer or test generation strategy attached, so the scan feeds directly into hands-on-keyboard work

We've started allocating 10% of each sprint to "CodeRef hygiene" — picking the highest-risk files from the scan and applying auto-fixes. It's not glamorous work, but the trend lines on our defect rate speak for themselves.

CodeRef project-wide analysis showing a file list sorted by bug risk score, with the top three files highlighted in red, severity distribution chart showing a 40% reduction in Critical findings over the past three sprints, and per-file issue counts with auto-fixable percentages.

The Numbers After 6 Months

I tracked some metrics because I knew people would ask:

Table showing 6-month impact metrics: code review rework dropped from ~12 to ~5 per sprint (-60%), time to detect issues from 47 minutes to under 10 seconds, test coverage from 54% to 81%, production bugs from 2-3 per quarter to 0, manual refactoring time from ~6 hours to ~1.5 hours per sprint, and issues caught before CI from ~0% to ~85%

The ROI calculation was straightforward enough that our engineering manager approved Pro licenses for the entire team without a formal business case.

What I Wish Were Better

It's not a perfect tool, and I'd rather give an honest review than a sales pitch:

Large files (800+ lines) take a noticeable pause — the three-engine parallel analysis is fast, but on a god class it can take 5–8 seconds. Not a dealbreaker, but noticeable.
The ML engine needs 50 interactions to activate — for the first few weeks, you're getting raw unfiltered results. I wish there were a way to bootstrap it with team-level patterns from day one.
No Kotlin support yet — we have a few Kotlin modules and those don't get analyzed. The roadmap mentions it, so I'm hopeful.
Test generation is scaffolding, not magic — the generated tests are structurally correct and save significant time, but you still need to write the meaningful assertions. That's probably the right tradeoff, but set your expectations accordingly.

Who Should Consider This

If you're on a Java team that:

Uses Spring Boot, JPA, or Apache Camel
Wants code quality feedback at write-time to complement your CI quality gates
Has a test coverage goal and needs to eliminate boilerplate
Wants framework-aware analysis that understands Spring proxies, JPA lifecycle, and Camel routing
Wants a tool that gets smarter over time instead of requiring more configuration

Then CodeRef is worth a serious evaluation. It works well on its own, and it works even better as an early-feedback layer alongside your existing CI pipeline. Install the free tier, run it on your most problematic service class, and see what it finds. That's what convinced me.

Diagram showing CodeRef in the developer workflow: code is analyzed instantly in the IDE at write-time, issues are fixed before commit, and the CI pipeline quality gate sees cleaner code with fewer failures.

Six months in, CodeRef has become an essential part of my daily workflow. The earlier I catch an issue, the cheaper it is to fix — and catching it while I'm still in the method is about as early as it gets. If you've tried CodeRef, I'd love to hear how it's working for your team.

Java #SpringBoot #CodeQuality #DeveloperProductivity #IntelliJIDEA #SoftwareEngineering #DevTools #CodeReview #TestAutomation #JetBrains

What slowed your progress more: bad code or slow feedback?

Mon, 08 Jun 2026 15:58:59 +0000

Think about the last time you were stuck on a frustrating frontend problem. You were trying to get a complex CSS grid to align properly, or debugging a tricky JavaScript interaction.

Did you struggle because your logic was inherently flawed, or did you struggle because every time you made a tiny adjustment, it took five seconds for your online code editor or local environment to refresh the view?

I strongly believe that a slow feedback loop is the silent killer of developer productivity. When we have to wait to see the results of our code, we lose our train of thought. We stop experimenting. We get frustrated.

I’ve been building NitroIDE specifically to act as an instant frontend playground to eliminate this waiting period, but it made me wonder about the broader community's experience.

When you reflect on your own workflow, how much time do you think you lose simply waiting for your tools to render your changes? Do you feel like your current setup encourages rapid prototyping, or does it make you hesitant to experiment? Let's discuss.

Asking the user for input until they give a valid response java

Wed, 03 Jun 2026 12:26:01 +0000

As a Java developer, you will often find yourself in situations where you need to ask the user for input and validate it before moving forward in your program. Whether it's asking for a number within a certain range, a valid email address, or any other type of input, it's essential to ensure that the user's input is valid before proceeding.In this article, we will explore how to repeatedly ask the user for input until they give a valid response using Java. We will look at examples of how to accomplish this task using while loops, the Scanner class, and regular expressions. Whether you're a beginner or an experienced Java developer, this article will provide you with the tools you need to ensure that your program only receives valid input from the user. So let's dive in and learn how to ask the user for input until they give a valid response in Java!

The Scanner class

The Scanner class in Java is used to read input from various sources, such as the keyboard, files, and network sockets. Some of the useful methods it contains are:

nextLine(): Reads the next line of input as a String. Example usage:

Scanner scanner = new Scanner(System.in);
System.out.println("Enter your name:");
String name = scanner.nextLine();
System.out.println("Hello, " + name + "!");

nextInt(): Reads the next token of input as an int. Example usage

Scanner scanner = new Scanner(System.in);
System.out.println("Enter an integer:");
int num = scanner.nextInt();
System.out.println("You entered: " + num);

nextDouble(): Reads the next token of input as a double. Example usage:

Scanner scanner = new Scanner(System.in);
System.out.println("Enter a decimal number:");
double num = scanner.nextDouble();
System.out.println("You entered: " + num);

nextBoolean(): Reads the next token of input as a boolean. Example usage:

Scanner scanner = new Scanner(System.in);
System.out.println("Are you a student? (true/false)");
boolean isStudent = scanner.nextBoolean();
System.out.println("You are a student: " + isStudent);

hasNext(): Returns true if the scanner has another token in its input. Example usage:

Scanner scanner = new Scanner(System.in);
while (scanner.hasNext()) {
    System.out.println(scanner.next());
}

hasNextLine(): Returns true if the scanner has another line of input. Example usage:

Scanner scanner = new Scanner(System.in);
while (scanner.hasNextLine()) {
    System.out.println(scanner.nextLine());
}

next(): Reads the next token of input as a String. Example usage:

Scanner scanner = new Scanner("Hello, world!");
System.out.println(scanner.next()); // Output: "Hello,"

useDelimiter(String pattern): Specifies a delimiter to be used by the scanner to separate input tokens. Example usage:

Scanner scanner = new Scanner("Hello, world!");
scanner.useDelimiter(" ");
System.out.println(scanner.next()); // Output: "Hello,"

close(): Closes the scanner and releases any resources associated with it. Example usage:

Scanner scanner = new Scanner(System.in);
// Do some scanning here...
scanner.close();

Note It is important to note that when a Scanner is closed, it can no longer be used, and attempting to do so will result in an IllegalStateException.

Examples of input validation

In Java, you can use a while loop to repeatedly ask the user for input until they give a valid response. You can use the Scanner class to read input from the user and check if it is valid using an if statement. Here is an example of how you might ask the user for an integer input and check if it is within a certain range:

import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        Scanner scanner = new Scanner(System.in);

        int input;
        while (true) {
            System.out.println("Enter an integer between 1 and 10:");
            input = scanner.nextInt();
            if (input >= 1 && input

Another example of asking user for input and validating it until a valid input is given is for a string input, such as an email address:

import java.util.Scanner;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Main {
    public static void main(String[] args) {
        Scanner scanner = new Scanner(System.in);
        String email;
        final String EMAIL_REGEX = "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}$";
        
        while (true) {
            System.out.println("Enter an email address:");
            email = scanner.nextLine();
            Pattern pattern = Pattern.compile(EMAIL_REGEX);
            Matcher matcher = pattern.matcher(email);
            if(matcher.matches()){
                break;
            }
            System.out.println("Invalid email. Please try again.");
        }
        System.out.println("Thank you for entering a valid email.");
    }
}

Note in the above example we used a regular expression to validate the email address, which is a powerful tool for validating different inputs.

A simple guessing game

In this section, we are going to create a simple guessing game to illustrate a practical approach of using input validation.

import java.util.Scanner;

public class GuessingGame {
    public static void main(String[] args) {
        Scanner scanner = new Scanner(System.in);
        int secretNumber = (int) (Math.random() * 100) + 1; // Generates a random number between 1 and 100
        int guess;

        System.out.println("I'm thinking of a number between 1 and 100. Can you guess what it is?");
        do {
            while (!scanner.hasNextInt()) {
                System.out.println("Invalid input. Please enter a number:");
                scanner.next();
            }
            guess = scanner.nextInt();
            if (guess < secretNumber) {
                System.out.println("Too low. Try again:");
            } else if (guess > secretNumber) {
                System.out.println("Too high. Try again:");
            }
        } while (guess != secretNumber);

        System.out.println("Congratulations! You guessed the number!");
        scanner.close();
    }
}

In this example, the program generates a random number between 1 and 100, and then prompts the user to guess what the number is. The program uses a do-while loop to repeatedly ask the user for input until they guess the correct number. The scanner.hasNextInt() method is used to check if the user's input is a valid integer, and if not, the program prompts the user to enter a valid number. Once the user enters the correct number, the loop exits, and the program prints a message congratulating the user for guessing the number.

Note It is important to close the scanner object after you have finished using it to release the associated resources and avoid memory leaks

Conclusion

In conclusion, asking the user for input and validating it is an essential task for any Java developer. By using while loops, the Scanner class, and regular expressions, you can repeatedly ask the user for input until they give a valid response. The examples provided in this article demonstrate how to accomplish this task for both integer and string input, but the principles can be applied to any type of input. It's important to note that validation of user input is a crucial step in ensuring the integrity of your program and protecting it from potential errors or malicious attacks. By following the techniques discussed in this article, you'll be well on your way to creating robust and secure Java programs that only accept valid input from the user.

References

The Java Scanner class documentation: https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/util/Scanner.html
Oracle's Java tutorial on regular expressions: https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/util/regex/Pattern.html

How to Fix Gradle Error: Unsupported class file major version (React Native & Expo)

Wed, 03 Jun 2026 08:49:58 +0000

If your React Native or Expo Android compilation suddenly crashes with a massive terminal stack trace pointing to an "unsupported class file major version" or claims a class file has the wrong version (e.g., wrong version 65.0, should be 61.0), your environment is caught in a silent version mismatch.

This error almost always triggers right after you upgrade your Expo SDK, bump your React Native core version, or update Android Studio.

Here is exactly why this happens, how to decode the cryptic internal version numbers, and how to get your build compiling cleanly.

Why Did This Happen Suddenly?

When React Native or Expo upgrades their framework architecture, they also upgrade the required version of the Android Gradle Plugin (AGP) inside your project.

Each version of AGP requires a strict minimum version of the Java Development Kit (JDK) to run the compilation pipeline. If your system's global terminal runtime environment or your IDE is still pointing to an older Java runtime, the build engine throws an immediate exception during the semantic analysis phase.

The Version Decoder Cheat Sheet

Java’s compiler doesn't map version numbers logically to their public marketing names. When the Gradle stack trace throws a decimal number at you, use this index to figure out what version your code is demanding:

Class file major version 66.0 = Requires Java 22
Class file major version 65.0 = Requires Java 21 (Common in newer 2025/2026 native modules)
Class file major version 61.0 = Requires Java 17 (The baseline standard for modern React Native)
Class file major version 55.0 = Requires Java 11 (Legacy)

If your terminal says wrong version 65.0, should be 61.0, your build script encountered a dependency compiled for JDK 21, but your system is executing the build toolchain using JDK 17.

Step 1: Find the Exact Path to Your Target JDK

Before making adjustments, you need to locate where the correct JDK version is actually installed on your machine.

On macOS

If you use Homebrew or standard installers, your JDK runtimes are stored under the virtual machine path. You can list all installed environments by running:
/usr/libexec/java_home -V

Copy the path to the required version. It will look similar to this:
/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home

On Windows

By default, standard Java installers or Android Studio bundle their JDK environments inside program directories. Check these common locations:

C:\Program Files\Java\jdk-17\
C:\Program Files\Android\Android Studio\jbr\ (Android Studio's embedded Java runtime)

Step 2: Apply the Explicit Project Override (Recommended)

Instead of fighting global system environment variables that might break older projects on your machine, you can force this specific React Native project to use the correct runtime directory.

Navigate to your project's native android folder: cd android
Open the gradle.properties file.
Add the following property at the bottom, supplying the absolute path you copied in Step 1:

org.gradle.java.home=/Insert/Your/Actual/Target/JDK/Path/Here

(Note: Windows users must escape backslashes in this file, format it like: C:\\Program Files\\Java\\jdk-17)

Step 3: Align Android Studio with Your Terminal

A massive source of frustration is when the project builds fine in the terminal via CLI, but crashes the second you open it in Android Studio (or vice versa). You must align the IDE's build path:

Open your project folder inside Android Studio.
Navigate to Settings (or Preferences on macOS) > Build, Execution, Deployment > Build Tools > Gradle.
Locate the Gradle JDK dropdown menu.
Change it from the default system runtime to match the exact version your project requires (e.g., JDK 17 or JDK 21).
Click Apply and hit Sync Project with Gradle Files.

Step 4: Clear the Aggressive Build Cache

Gradle caches compilation footprints deeply. If you change your Java version without clearing the cache, Gradle will try to read the old, mismatched class files and throw the same error again.

Wipe the execution deck completely by running these commands in your root directory:

Clean the native android directories

cd android
./gradlew clean

Return to root and clear bundler caches

cd ..
npx react-native start --clear

Once the development server reboots and paths match up seamlessly across your terminal, properties file, and IDE, run your run command (npx react-native run-android or npx expo run:android) and the version mismatch error will be gone.

Fixing Gradle TLS handshake_failure on Maven Central (Android Builds)

Tue, 02 Jun 2026 15:56:09 +0000

If your Android native build is constantly failing with a TLS handshake error when trying to download dependencies from Maven Central, the root cause might be an invisible environment variable polluting your Java settings.

The most frustrating part of this error is that your local internet connection is usually completely fine.

The Quick Diagnosis

Open your terminal and test the connection directly to the Maven repository using curl:

curl -I https://repo1.maven.org/maven2/

If curl connects successfully and returns an HTTP 200, but your Gradle build still throws a Received fatal alert: handshake_failure, your network is not the problem. Gradle itself is failing to establish the secure line.

The Root Cause

An environment variable called GRADLE_OPTS is likely injecting broken SSL or JSSE flags into your build process. Specifically, flags like -Djavax.net.ssl.trustStoreType=WINDOWS-ROOT force Gradle to look at system-specific certificate stores that conflict with standard Java behavior, breaking the handshake completely.

The Fix

To resolve this permanently, you need to wipe out the polluted configuration so Gradle can fall back to its clean JDK defaults.

Open your system Environment Variables settings.
Check both the User variables and the System/Machine variables.
Look for GRADLE_OPTS.
Delete the variable entirely from both locations.
Close your IDE, restart your terminal, and run your build again.

Once those injected flags are gone, Gradle will use standard JDK defaults, and your dependency downloads will start succeeding immediately.

I've been spending a lot of my spare time building out a diagnostic tool over at FixMyError to map out environment bugs like this automatically. I just put a live, free sandbox preview on the homepage if you want to see how the engine breaks down terminal stack traces before you ever make an account.

The Easiest Way to Integrate pawaPay in Your Java Spring Boot App

Mon, 01 Jun 2026 10:08:14 +0000

Building a high-throughput mobile money gateway is often romanticized as a simple REST API integration. The reality, however, is a brutal landscape of undocumented MNO network drops, complex cryptographic signature requirements, and terrifying double-spend vulnerabilities. When development teams attempt to hand-roll these integrations using standard Java HTTP clients like OkHttp or RestTemplate, they inadvertently construct a fragile house of cards. They pull highly sensitive environment secrets directly into the JVM heap to manually compute Signature-Input headers, exposing their financial infrastructure to memory scraping and reverse-engineering. Furthermore, relying on blocking I/O to wait for unpredictable African telecom networks guarantees that thread pools will eventually exhaust, triggering cascading outages across the entire application architecture.

This is the integration illusion. You think you are building a simple payment gateway, but you are actually attempting to build a secure, fault-tolerant, state-managing cryptographic vault from scratch.

We recognized that engineering teams do not have months to waste debugging manual boilerplate. You need speed, concurrency, and ironclad security from day one. To solve this, we engineered the pawaPay Java SDK—a completely new paradigm for mobile money integration that shifts the heavy lifting away from your application logic and into a compiled, memory-safe environment. By adopting this architecture, you can execute non-blocking, asynchronous mobile money deposits and payouts in under five minutes.

Step One: Securing the Artifact

The foundation of a secure integration begins with your dependency management. We distribute the official package directly through Maven Central, ensuring you receive cryptographically verified, unaltered binaries. You can view the live artifact registry at https://central.sonatype.com/artifact/com.katorymnd/pawapay-java-sdk to verify the latest release versions.

To bring the native power of the SDK into your project, simply declare it within your pom.xml configuration file.

<dependency>
    <groupId>com.katorymnd</groupId>
    <artifactId>pawapay-java-sdk</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Once synced, you are no longer just importing a library; you are embedding a highly optimized Java Native Interface (JNI) vault engineered in Rust. This core will handle all payload serialization and cryptographic signing entirely outside of the standard Java memory space, neutralizing standard de-compilation threats immediately.

Step Two: Zero-Trust Configuration

We engineer under the assumption that application state can be volatile, which is why we enforce a strict, zero-trust initialization process. There are no fallback secrets, and there are no dummy variables allowed. Your master API tokens and your specific Katorymnd license key must be injected via strict environment variables. If these are missing or malformed, the SDK aborts the boot sequence instantly to protect your system from executing unauthenticated requests.

To wire this into a Spring Boot application, you construct a dedicated @Configuration class. This class uses our Config.Builder to construct the environment parameters and boot the ApiClient securely.

import com.katorymnd.pawapay.sdk.api.ApiClient;
import com.katorymnd.pawapay.sdk.config.Config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PawaPayGatewayConfig {

    @Bean
    public ApiClient pawaPayClient() {
        String apiKey = System.getenv("PAWAPAY_API_TOKEN");
        String licenseKey = System.getenv("KATORYMND_PAWAPAY_SDK_LICENSE_KEY");

        Config config = new Config.Builder()
            .apiKey(apiKey)
            .environment("production")
            .timeout(30000)
            .build();

        return new ApiClient(config, licenseKey, true, "v2");
    }
}

By defining the ApiClient as a Spring Bean, you ensure the native vault is loaded exactly once during the application lifecycle. The vault establishes the secure connection pool, locks in the hardware anchoring, and remains resident in memory, ready to process thousands of concurrent requests without the overhead of re-initialization.

Step Three: The Reactive Endpoint

The true architectural elegance of this integration reveals itself at the routing layer. Because the SDK was built specifically for modern, high-throughput environments, every core method returns a CompletableFuture. This maps natively to Project Reactor, allowing you to build completely non-blocking Spring WebFlux endpoints.

When a payload arrives, your application threads do not wait. The request is handed to the native core, and the thread is immediately liberated back to the pool to handle other users.

import com.katorymnd.pawapay.sdk.api.ApiClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;

import java.util.Map;

import static org.springframework.web.reactive.function.server.RequestPredicates.POST;
import static org.springframework.web.reactive.function.server.RouterFunctions.route;

@Configuration
public class DepositController {

    @Bean
    public RouterFunction<ServerResponse> handleDeposit(ApiClient pawaPayClient) {
        return route(POST("/api/v2/payments/deposit"), request -> 
            request.bodyToMono(Map.class)
                .flatMap(payload -> Mono.fromFuture(
                    pawaPayClient.initiateDepositV2(
                        payload.get("transactionId").toString(),
                        payload.get("amount").toString(),
                        payload.get("currency").toString(),
                        payload.get("phone").toString(),
                        payload.get("provider").toString(),
                        "Spring WebFlux Integration",
                        null, null, null
                    )
                ))
                .flatMap(response -> ServerResponse.ok().bodyValue(response))
                .onErrorResume(error -> ServerResponse.badRequest().bodyValue(Map.of("error", error.getMessage())))
        );
    }
}

In just three steps, you have bypassed weeks of manual REST implementation. You possess an endpoint that can absorb massive MNO latency spikes without crashing your server, backed by a cryptographic engine that mathematically guarantees your payload integrity.

Validating the Architecture

Before writing a single line of your own code, you can visually verify this exact execution flow. We have exposed our internal, Javalin-based disposable execution environment to the public. By visiting the live playground at https://katorymnd.dev/pawapay-demo/java/, you can input your sandbox tokens and watch the native core process deposits, handle automated config syncs, and securely fetch MNO availability in real-time. It provides a transparent, terminal-level view of the exact security validations happening beneath the surface of the SDK.

Transitioning to Enterprise Production

While the artifact is freely available on Maven Central for integration testing, deploying this architecture into a live financial environment requires absolute operational certainty. For businesses processing real capital, we offer the Premium License infrastructure detailed at https://katorymnd.com/pawapay-payment-sdk/java.

Securing a premium license unlocks critical production features, including custom domain locking to prevent your API keys from being used outside of authorized IP addresses, emergency technical support SLAs, and architectural consultation for your specific database synchronization strategy. It is the definitive path for teams that refuse to compromise on gateway resilience.

Stop wrestling with clunky HTTP clients and vulnerable cryptographic libraries. Cut the boilerplate, implement the native SDK, and secure your mobile money infrastructure today.

Are developers underestimating the browser?

Sun, 31 May 2026 15:34:40 +0000

Think about your current frontend workflow. We constantly upgrade our libraries, our bundlers, and our deployment pipelines. We swap out transpilers to save fractions of a second.

But when was the last time we stopped to appreciate the sheer engineering magnitude of the browser itself?

The modern browser is a heavily optimized, JIT-compiled, hardware-accelerated powerhouse. Yet, when we reach for a web IDE or a live code editor to quickly test a concept, the platforms we use often feel sluggish. They are wrapped in layers of unnecessary abstraction.

I’ve been building NitroIDE to try and solve this by creating an online IDE that acts as a direct interface to the browser's native power, rather than fighting it. But I want to know what the community thinks.

Why do we accept heavy, bloated development environments when the underlying engine (the browser) is incredibly fast? Have we lost sight of building lightweight, efficient tools in favor of adding more complexity? Thoughts?

Public key retrieval is not allowed / Needs improvement

Mon, 25 May 2026 04:13:39 +0000

Today, in this article we will discuss the error message "Public key retrieval is not allowed". This error message is indicating that the system is configured to disallow the retrieval of a public key. This is likely a security measure to prevent unauthorized access to sensitive information. It is recommended to check with the administrator or technical support for further assistance.

What does error "Public key retrieval is not allowed" mean? #

The error message "Public key retrieval is not allowed" usually occurs when an application or service is trying to access a public key from the server it is trying to connect to, but the operation is not allowed due to security or access control measures that prevent the retrieval of the public key.

In cryptography, public keys are used for encryption and digital signatures, while private keys are used for decryption and signing. When you attempt to connect to a server, the system must first retrieve the server's public key to establish a secure connection. If the server's public key cannot be retrieved, the system may not be able to establish a secure connection, and the error message "Public key retrieval is not allowed" will be displayed.

The cause of this error can vary. This may happen be due to a firewall, network restriction, or a policy set by the system administrator. To resolve this issue, you may need to contact your system administrator or network administrator to request access to the public key or check the firewall or network configurations.

Why is the Error Generated? #

The "Public key retrieval is not allowed" error message can occur due to various causes. Some of the most common causes are:

Firewall restriction: Your system may not be able to retrieve the server's public key if the connection is being blocked by a firewall. The firewall may be configured to block connections to the server or to block the retrieval of the public key.
For example; you are trying to connect to a server over a secure connection using SSL/TLS, but the firewall is blocking the connection.
Network restriction: The system may not be able to retrieve the server's public key if there are restrictions in place on the network that prevent the retrieval. This could be due to a policy set by the network administrator or due to a misconfiguration of the network.
Say, you try to retrieve the public key of a server that is located in a different country, but the connection is blocked by the network administrator due to security policies. Then you will receives the error message "Public key retrieval is not allowed."
Access control measures: The server may have security measures in place that prevent unauthorized access to the public key. This could be due to a policy set by the system administrator or due to security software installed on the server e.g. you are trying to connect to a server that has security measures in place to prevent unauthorized access to the public key.
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class MySQLConnectionExample {

  public static void main(String[] args) {
    try {
      // Load the MySQL Connector/J driver
      Class.forName("com.mysql.cj.jdbc.Driver");

      // Establish a connection to the MySQL server
      Connection conn = DriverManager.getConnection(
        "jdbc:mysql://localhost:3306/test_db?useSSL=true",
        "username",
        "password"
      );

      System.out.println("Connected to the MySQL server successfully!");

      // Close the connection
      conn.close();
    } catch (SQLException | ClassNotFoundException e) {
      System.out.println("An error occurred while connecting to the MySQL server: " + e.getMessage());
    }
  }
}
```
In this example, we first load the MySQL Connector/J driver using the Class.forName method. Then, we use the DriverManager.getConnection method to establish a connection to the MySQL server. The connection URL includes the useSSL=true parameter, which indicates that we want to use SSL/TLS to secure the connection. We also specify the username and password to use when connecting to the server.
Here when the client is unable to retrieve the public key an error occurs, an exception will be thrown and an error message will be displayed.
IP/domain restrictions: The server may be configured to only allow public key retrieval from specific IP addresses or domains. If you are not on the approved list, it may not be able to retrieve the public key.
An example is that you are trying to connect to a server that is configured to only allow public key retrieval from specific IP addresses or domains and your system is not on the approved list, so the will receive the error.
Incorrect server configuration: The server may be misconfigured, which could prevent the retrieval of the public key. This could be due to an error in the server's settings or due to an incorrect configuration of the server's software. For example, you try to connect to a server that is misconfigured, which prevents the retrieval of the public key.
Certificate issues: The server may have an expired or revoked certificate, which could prevent the retrieval of the public key. In this case, the system may not be able to establish a secure connection with the server. For example, you will try to connect to a server that has an expired or revoked certificate, which prevents the retrieval of the public key.

Note It is important to understand the cause of the "Public key retrieval is not allowed" error in order to resolve it effectively. Depending on the cause, you may need to make apply the appropiate solution.

How to Solve the Error? #

The possible solutions for the causes of the "Public key retrieval is not allowed" error message are as follows:

Firewall restriction: To resolve this issue, you can check the firewall configuration and ensure that the connection to the server is not being blocked. You may also need to open specific ports or add an exception to the firewall to allow the connection.
Network restriction: To resolve this issue, you may need to contact the network administrator and request that the restriction be lifted or that the necessary changes be made to the network configuration.

Access control measures: To resolve this issue, you may need to request access to the public key from the system administrator or the security software provider. The system administrator may need to change the security measures in place to allow you to retrieve the public key. Like, the error in previous coding example occurs due to useSSL=true parameter. Therefore, we change it to useSSL=false as done below.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class MySQLConnectionExample {

  public static void main(String[] args) {
    try {
      // Load the MySQL Connector/J driver
      Class.forName("com.mysql.cj.jdbc.Driver");

      // Establish a connection to the MySQL server
      Connection conn = DriverManager.getConnection(
        "jdbc:mysql://localhost:3306/test_db?useSSL=false",
        "username",
        "password"
      );

      System.out.println("Connected to the MySQL server successfully!");

      // Close the connection
      conn.close();
    } catch (SQLException | ClassNotFoundException e) {
      System.out.println("An error occurred while connecting to the MySQL server: " + e.getMessage());
    }
  }
}

If you change the value of useSSL in the connection string from true to false, then the connection will no longer attempt to use SSL encryption. This change can resolve the "Public key retrieval is not allowed" error if the issue was caused by a problem with the server's SSL certificate.

IP/domain restrictions: To resolve this issue, one may need to check the server configuration and ensure that your IP address or domain is on the approved list. If the IP address or domain is not on the approved list, you may need to request that it be added.
Incorrect server configuration: To resolve this issue, you may need to check the server configuration and make any necessary changes to ensure that the server is configured correctly. You may also need to check the server software and ensure that it is installed and configured correctly.
Certificate issues: To resolve this issue, you may need to check the server certificate and ensure that it is valid and up-to-date. If the certificate is expired or revoked, you may need to request a new certificate from a trusted certificate authority.

The Conclusion

In conclusion, the "Public key retrieval is not allowed" error message indicates that the your are unable to retrieve the server's public key, which is required to establish a secure connection using SSL/TLS. This error can be caused by various factors, including firewall restrictions, network restrictions, access control measures, IP/domain restrictions, incorrect server configuration, and certificate issues. To resolve the issue you may need to check for the cause of the error in your specific situation and apply the suitable solution.

The References

Some resources for reference or further information are given below:

MySQL Connector/J documentation:
https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-using-ssl.html
Java API documentation:
https://docs.oracle.com/en/java/javase/14/docs/api/java.sql/java/sql/Driver.html
MySQL official forums:
https://forums.mysql.com/

IBM Bob Turned a 30-Day Java Upgrade Into a 3-Day Sprint

Tue, 19 May 2026 15:44:59 +0000

Java modernization is one of those tasks that sits in the backlog for years. Everyone knows it needs to happen. Nobody wants to be the team that breaks production by doing it.

Blue Pearl, a South African IT consultancy, was in exactly that position. Their flagship product, Blue App, is a talent-matching platform used by roughly 26,000 consultants and freelancers, as well as their enterprise clients. The application was built in Java 11 back in 2020, and by the time the team got serious about modernizing it, the codebase had accumulated years of technical debt.

The list was long: outdated API calls, more than 50 outdated dependencies, known CVEs, no automated test coverage, and an infrastructure design that no longer matched what the platform actually needed. A traditional modernization effort would have required 30-plus person-days of dedicated engineering work — and carried a serious risk of regression on a platform that nearly 30,000 users depended on.

They used IBM Bob instead. The project took three days.

What the Team Actually Did

Before writing a single line of new code, the Blue Pearl team spent about three hours building context. They fed Bob architecture diagrams, AWS workflow documentation, endpoint definitions, inter-service dependencies, and data flow maps. They also included input from actual platform users about what they needed from the application.

That upfront work mattered. Bob used it to produce a full dependency map of the codebase, surface deprecated API calls, highlight outdated libraries, and flag integration points that had never been formally documented.

From there, Bob guided the team through the full transformation:

Migration from Java 11 to Java 21 LTS
Adoption of modern Java features, including records, sealed classes, pattern matching, and virtual threads
Spring Boot and Hibernate updates to Java 21-compatible releases
Namespace migration from javax to jakarta
Restructured services with cleaner interfaces and reduced coupling

Security was part of the same pass, not a separate effort. Bob helped strengthen authentication and authorization logic, standardize input validation, and map sensitive data flows. It also flagged the lack of observability as an architectural risk and recommended adding structured JSON logging, distributed tracing with Micrometer and OpenTelemetry, and health check endpoints across service boundaries.

The Results

When the dust settled, Blue Pearl had a platform that passed scans from Semgrep, Snyk, and SonarQube on the first attempt. Post-deployment results:

Zero CVE-bearing dependencies
92% regression test coverage, up from zero
Zero production incidents after deployment
100% functional equivalence with the legacy system
Estimated 15% JVM performance improvement

No customer complaints. No rollbacks. The team immediately moved on to UI improvements and new features rather than cleaning up backend issues.

How Bob Handled the Heavy Lifting

One thing worth understanding is how Bob approaches this task technically. It doesn't rely on a single model. Bob dynamically routes each task to a suitable model based on accuracy, performance, and cost, drawing from a mix of frontier models, including Anthropic Claude, Mistral, and IBM Granite, as well as specialized fine-tuned models for code reasoning and security analysis.

Simpler completions go to lighter models. More complex analysis and transformation tasks go to more capable ones. The goal is better output at lower cost — and the developer doesn't have to manage any of that routing manually.

The Pattern That Made It Work

Bob didn't replace engineering judgment on this project. The pattern that worked was: context first, Bob second, senior developer validation third. Every recommendation Bob made was reviewed by a senior developer before implementation. Testing and internal UAT were followed before anything went to production.

That's an important detail for anyone evaluating AI-assisted modernization. Bob accelerated the discovery, planning, and transformation phases. But experienced engineers stayed accountable for what shipped.

Why This Matters for Your Backlog

Most development teams have at least one version of this problem sitting somewhere. A legacy Java app. An undocumented codebase. A modernization project that's been "almost ready to start" for two years.

The Blue Pearl project is a useful proof point — not because the numbers are impressive, but because the approach is repeatable. Context in, Bob analyzes and recommends, and the senior engineer validates. The dependency mapping that would have taken multiple sprints was done in hours. The automated test baseline that didn't exist now provides a regression safety net for every future change.

That shifts where engineering effort actually goes. Less time on code archaeology and regression anxiety. More time on product work that users notice.

IBM Bob is now available at bob.ibm.com, with a 30-day free trial for teams who want to see what it can do with their own codebase.

How many constructors can a class have? (Java)

Mon, 18 May 2026 06:21:29 +0000

A class in Java is a blueprint for creating objects that defines the properties and behaviors of the objects. When a new object is created from a class, it is called an instance of that class. Java provides a special method called a constructor to initialize the values of the object's attributes when it is created. A constructor is called automatically when a new object is created, and it is used to set the initial values of the object's attributes.

In this article, we will discuss how many constructors a class can have in Java and reasons why we need multiple constructors.

How many constructors can a class have?
Why do we need multiple constructors?
Conclusion
Reference

1. How many constructors can a class have? #

In Java, a class can have multiple constructors, with each constructor having a different number or type of parameters. But what is limit for the number of constructors a class can have? The simple answer is there's no limit.

The Java documentation does not impose any specific limit on the number of constructors a class can have. It states that "a constructor is a special type of method that is used to initialize objects," and there is no mention of any specific limit on the number of constructors a class can have.

FAQ Q: Is it true that due to technical limit (not according to Java docs), Java class can only have a maximum of 65535 constructor?
A: No, it is not true. The Java documentation does not impose any specific limit on the number of constructors a class can have. Thus, it is possible to have an unlimited number of constructors in a Java class.

The specific limit on the number of constructors a class can have, which many people thought that exist, is actually the limit of the size of a method.

Note The Java Virtual Machine (JVM) has a limit on the size of a method, including constructors, which is 65535 bytes.

However, this limit is imposed on the compiled code, not on the number of constructors a class can have. It is unlikely that a single constructor would reach this limit, and even if it did, it could be refactored into smaller methods to avoid the limit.

In conclusion, a class in Java can have multiple constructors with different parameters. The Java documentation does not impose any limit on the number of constructors a class can have, and the JVM limit on the size of a method is unlikely to affect the number of constructors a class can have.

2. Why do we need multiple constructor? #

The purpose of having multiple constructors is to provide the programmer with the ability to initialize an object in different ways, depending on the requirements of the program.

Suppose you have a class Person and you want to create an object of this class to represent a person's information. The person's information can be their name, age, and address. However, in some cases, you might only have the person's name and age. In this scenario, you need two constructors: one that takes two parameters (name and age) and another that takes three parameters (name, age, and address).

To declare multiple constructors in a class, you simply provide several constructors with different parameter lists. Each constructor must have a unique set of parameters. When you create a new object of the class, Java will call the constructor that matches the number and type of parameters that you provide.

The ability to have multiple constructors provides greater flexibility when creating objects and makes it easier to write clean and maintainable code. However, it's important to consider the complexity that comes with having too many constructors.

3. Conclusion#

In this article, we have discussed about how many constructors a class can have in Java and the reasons of having multiple constructors in a class. If you have any questions or comments, feel free to leave them below. Have a nice day!

4. Reference#

For further information, please visit:

Constructor in Java: https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Constructor.html
Java documentation has no specific limit of number of construtors: https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/lang/Class.html
JVM has a limit on the size of a method: https://docs.oracle.com/en/java/javase/14/docs/specs/jvms/se14/html/jvms-4.html#jvms-4.10

Actual and formal argument lists differ in length

Thu, 14 May 2026 05:55:50 +0000

Today, we're going to discuss a compilation error in Java: "Actual and formal argument lists differ in length". This error is produced when the number of arguments passed in doesn't match the number of parameters defined in the method or constructor. In this study blog, we'll explore what's "Actual and formal argument lists differ in length", why it happens and how to resolve it.

What is "Actual and formal argument lists differ in length" #

First, let's understand what is actual argument and formal argument.

Formal argument: The arguments we define for a method or constructor.
Actual argument: The arguments we pass into a method or constructor.

Let's see an example:


  public static void main(String[] args) {
        int num_1 = 10;
        int num_2 = 20;
        int sum = addition(num_1, num_2);
        }
    
     public static int addition(int a, int b){
        return a + b;
    }

From the above example, a and b is the formal arguments while num_1 and num_2 is the actual arguments that we pass into the method addition.

Now, we've understood the difference between actual argument and formal argument. Let's see another example:


        public static void main(String[] args) {
        int num_1 = 10;
        int num_2 = 20;
        int sum = addition(num_1);
        }
    
     public static int addition(int a, int b){
        return a + b;
    }

The compilation error occurs:


  method addition in class NewMain cannot be applied to given types;
  required: int,int
  found:    int
  reason: actual and formal argument lists differ in length

Here, we pass in only one actual argument, num_1 but the method, addition actually defines two formal arguments, a and b to work. Let's see another example:


        public static void main(String[] args) {
        int num_1 = 10;
        int num_2 = 20;
        int num_3 = 30;
        int sum = addition(num_1, num_2, num_3);
        }
    
     public static int addition(int a, int b){
        return a + b;
    }

The compilation error also occurs:


  method addition in class NewMain cannot be applied to given types;
  required: int,int
  found:    int,int,int
  reason: actual and formal argument lists differ in length

Here, we pass in three actual arguments, num_1, num_2, and num_3 while the method, addition only need two formal arguments to work.

So far we've discovered this problem in the method invocation. Let's see some examples of constructor:


public class Student {
    private String first_Name;
    private String last_Name;
    
    public Student(String first_Name, String last_Name){
        this.first_Name = first_Name;
        this.last_Name = last_Name;
    }
}

Here, we declare a class, Student, where we need first_Name and last_Name arguments in the constructor to create an instance of Student.


Student student = new Student("Alex");

Here is the compilation error:


constructor Student in class Student cannot be applied to given types;
required: String,String
found:    String
reason: actual and formal argument lists differ in length

Let's move on to the next section to see why it occurs.

Causes #

From the above examples, we can see that this compilation error occurs when the number of actual arguments we pass into the method or constructor doesn't match the number of formal arguments we define for the method or constructor. As long as there's mismatch between the number of actual arguments and the number of formal arguments, this error will always be produced. Don't fret; it can be simply solved, let's move on to the next section:

Solution #

You may guess the solution. Yes, you just need to remember the main concept while defining and using the methods / constructors:

The actual and formal argument lists should always be same in length

What means? Before using the methods or constructors, you should check the number of formal arguments defined for a method or constructor. When you want to invoke a method or initiate an instance of object using constructor, make sure the number of actual arguments passed in is same as the number of formal arguments.


public static void main(String[] args) {
        int num_1 = 10;
        int num_2 = 20;
        int num_3 = 30;
        int sum = addition(num_1, num_2, num_3);
        System.out.println(sum);
        }
    
     public static int addition(int a, int b, int c){
        return a + b + c;
    }

This is the output:

We can either increase / decrease the number of formal arguments defined or the number of actual arguments passed in. Just to make sure both are having the same length.

Tip For a Class, if you didn't override its constructor, the constructor has no any formal arguments


public class Student {
    private String first_Name;
    private String last_Name;

    public String getFirst_Name() {
        return first_Name;
    }

    public void setFirst_Name(String first_Name) {
        this.first_Name = first_Name;
    }

    public String getLast_Name() {
        return last_Name;
    }

    public void setLast_Name(String last_Name) {
        this.last_Name = last_Name;
    }
}

I define a class, Student without overriding its default constructor.


Student student = new Student();

The compilation error will not occur and we can assign value to the variable, student using setter method in the class.

The Conclusion #

Thanks for sticking with this blog until the end. In this lesson, we've learned about what's "Actual and formal argument lists differ in length" in Java. Besides, we've known what is the causes of this compilation error and how to solve it simply. Just to remind again, we should always make sure the formal arguments and actual arguments have the same length. Otherwise, this error will be thrown during compilation.

The Reference #

You may go through this reference for more information:

Constructors: https://docs.oracle.com/javase/tutorial/java/javaOO/constructors.html

The Ecosystem Conductor: Orchestrating Market Orders with Kafka, RabbitMQ and Spring Boot

Wed, 13 May 2026 00:55:31 +0000

Hey folks!

We've reached one of the most important posts in the My Broker B3 series. Up until now we built each piece of the ecosystem separately — the price synchronizer, the matching engine, the financial custody, the asset catalog. Now it's time to build the service that connects all of it: the Broker Order API.

This is the conductor of the ecosystem. When a user wants to buy or sell a stock, this is where everything begins — and where the results come back to.

What is the Order API?

The trading-broker-order is the entry point for the broker's transactional flow. It has a clear responsibility: orchestrate the complete lifecycle of an order, from the user's intent to the final execution confirmation.

To do this, it communicates with four other ecosystem services:

Asset API (REST/Feign) — validates whether the ticker exists and is active
Wallet API (REST/Feign) — validates whether the user has sufficient balance
B3 Matching Engine (RabbitMQ) — sends the order for execution
Broker Wallet (Kafka) — notifies the ecosystem about each status change

️ The Complete Order Flow

Before diving into the code, here's the end-to-end flow:

[User]
    │
    │  POST /api/v1/orders
    │  { userId, ticker, quantity, price, side: "BUY" }
    ▼
[trading-broker-order]
    │
    ├─ 1. Validate ticker  → GET trading-asset/assets/{ticker} (Feign/REST)
    │
    ├─ 2. Validate balance → GET trading-wallet/summary (Feign/REST)
    │
    ├─ 3. Persist order → MySQL (status: PENDING)
    │
    ├─ 4. Send to B3 → RabbitMQ (mq-broker-to-b3)
    │
    ├─ 5. Notify ecosystem → Kafka (order-events-v1, status: PENDING)
    │
    └─ Returns created order → HTTP 201

         ─ ─ ─ (B3 processes the order) ─ ─ ─

[b3-matching-engine]
    │
    │  RabbitMQ (mq-b3-to-broker)
    │  { orderId, status: FILLED/REJECTED, executedPrice }
    ▼
[trading-broker-order]
    │
    ├─ 6. Update status → MySQL (FILLED or REJECTED)
    │
    └─ 7. Notify ecosystem → Kafka (order-events-v1, final status)
              │
              ├─ trading-broker-wallet consumes → blocks/settles/refunds balance
              └─ other future consumers

Two distinct communication channels, two Kafka publish moments, and the wallet reacting to each state change. Let's see how each part was implemented.

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.3.5	Service core
MySQL + Flyway	Order persistence
Spring Kafka	Lifecycle event publishing
Spring AMQP	Integration with Matching Engine via RabbitMQ
Spring Cloud OpenFeign	REST calls to Asset API and Wallet API
SpringDoc OpenAPI	Swagger UI documentation

️ Implementation Pillars

1. The Domain Model — Order

The Order entity represents the state of an order at any point in its lifecycle:

@Entity
@Table(name = "orders")
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String userId;
    private String ticker;

    @Column(nullable = false, precision = 19, scale = 4)
    private BigDecimal quantity;

    @Column(nullable = false, precision = 19, scale = 4)
    private BigDecimal price;

    // Null while PENDING — only set after B3 feedback
    @Column(precision = 19, scale = 4)
    private BigDecimal executedPrice;

    @Enumerated(EnumType.STRING)
    private OrderSide side;   // BUY | SELL

    @Enumerated(EnumType.STRING)
    private OrderStatus status; // PENDING | FILLED | REJECTED | CANCELLED

    @CreationTimestamp
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;
}

An important design detail: executedPrice is intentionally nullable. When the order is created, we don't yet know the execution price — that only comes as a response from the Matching Engine. Forcing nullable = false here would be a domain modeling error.

The entity also carries the mapToEvent() method that serializes the current state into a Kafka event:

public OrderEventDTO mapToEvent() {
    return OrderEventDTO.builder()
            .orderId(this.getId())
            .userId(this.getUserId())
            .ticker(this.getTicker())
            .quantity(this.getQuantity())
            .price(this.getPrice())
            .executedPrice(this.getExecutedPrice())
            .side(this.getSide().name())
            .status(this.getStatus().name())
            .eventTimestamp(LocalDateTime.now())
            .build();
}

2. Ticker Validation — Asset Feign Client

Before validating balance or persisting anything, we need to ensure the requested ticker actually exists and is available for trading. A user submitting an order for XPTO999 should get a clear error immediately — not a silent rejection from B3 two hops later.

@FeignClient(name = "trading-broker-asset", url = "${app.services.asset-url}")
public interface AssetClient {

    @GetMapping("/api/v1/assets/{ticker}")
    AssetDTO getByTicker(@PathVariable("ticker") String ticker);
}

The validation in OrderService:

private void validateTicker(String ticker) {
    try {
        var asset = assetClient.getByTicker(ticker.toUpperCase());
        if (!"ACTIVE".equalsIgnoreCase(asset.status())) {
            throw new RuntimeException("Asset is not available for trading: " + ticker);
        }
        log.info("Ticker {} validated — status: {}", ticker, asset.status());
    } catch (FeignException.NotFound e) {
        throw new RuntimeException("Asset not found or inactive: " + ticker);
    } catch (FeignException e) {
        log.error("Asset service unavailable during ticker validation: {}", e.getMessage());
        throw new RuntimeException("Asset service unavailable. Please try again later.");
    }
}

Why catch FeignException separately from FeignException.NotFound? A 404 from the asset service means the ticker doesn't exist — a business error that should fail fast. Any other FeignException (connection refused, timeout, 5xx) means the asset service is unavailable — a different kind of failure that warrants a different message to the user.

3. Balance Validation — Wallet Feign Client

For buy orders (BUY), we need to ensure the user has available balance. We use Spring Cloud OpenFeign to query the Wallet API declaratively:

@FeignClient(name = "trading-broker-wallet", url = "${app.services.wallet-url}")
public interface WalletClient {

    @GetMapping("/api/v1/wallet/{userId}/summary")
    WalletSummaryDTO getWalletSummary(@PathVariable String userId);
}

The validation happens after ticker validation:

private void validateBalance(OrderRequestDTO request) {
    BigDecimal totalOrderValue = request.getPrice().multiply(request.getQuantity());
    var walletSummary = walletClient.getWalletSummary(request.getUserId());

    if (walletSummary.getAvailableBalance().compareTo(totalOrderValue) < 0) {
        throw new RuntimeException("Insufficient balance. Available: "
                + walletSummary.getAvailableBalance()
                + " | Required: " + totalOrderValue);
    }
}

Why Feign and not RestTemplate? OpenFeign eliminates HTTP boilerplate — the interface is sufficient. The URL is injected via application.yaml, making environment changes straightforward without recompiling.

4. The Creation Flow — OrderService

The placeOrder() is the heart of the service. It orchestrates five steps in sequence within a transaction:

@Transactional
public Order placeOrder(OrderRequestDTO request) {
    log.info("Processing new {} order for user: {}", request.getSide(), request.getUserId());

    // 1. Validate ticker exists and is ACTIVE in asset catalog
    validateTicker(request.getTicker());

    // 2. Validate balance for BUY orders via Wallet API
    if (request.getSide() == OrderSide.BUY) {
        validateBalance(request);
    }

    // 3. Persist order with PENDING status
    Order order = Order.builder()
            .userId(request.getUserId())
            .ticker(request.getTicker().toUpperCase())
            .quantity(request.getQuantity())
            .price(request.getPrice())
            .side(request.getSide())
            .status(OrderStatus.PENDING)
            .build();

    order = orderRepository.save(order);

    // 4. Send to B3 via RabbitMQ
    b3MessageProducer.sendToB3(mapToB3Message(order));

    // 5. Publish PENDING event to Kafka for wallet and other consumers
    orderEventProducer.sendOrderEvent(order.mapToEvent());

    return order;
}

Why validate ticker before balance? It's cheaper to fail fast on a non-existent ticker (one network call) than to validate balance first and then discover the ticker is invalid. Order of validations matters for UX and for minimizing unnecessary load on downstream services.

Design decision: The Kafka event is published with PENDING status right after creation. This allows trading-broker-wallet to immediately block the balance, without waiting for B3's result. This is the essence of eventual consistency — each service reacts to the event in its own time.

5. B3 Integration — RabbitMQ

Communication with the Matching Engine uses RabbitMQ for a specific reason: delivery guarantee. Even if the Matching Engine is temporarily unavailable, the message stays in the queue and is processed when it comes back.

Infrastructure configuration

All RabbitMQ infrastructure is declared as Spring beans — ensuring queues, exchanges and bindings exist before any message flows:

@Bean
public DirectExchange brokerExchange() {
    return new DirectExchange(exchangeName);
}

@Bean
public Queue orderOutQueue() {
    return QueueBuilder.durable(queueIn)
            .withArgument("x-dead-letter-exchange", "dlx.broker.orders")
            .withArgument("x-dead-letter-routing-key", "dlq-broker-to-b3")
            .build();
}

@Bean
public Binding orderOutBinding() {
    return BindingBuilder.bind(orderOutQueue())
            .to(brokerExchange())
            .with(routingKey);
}

The dead letter withArgument ensures messages that fail are redirected to the DLQ instead of simply being discarded.

Producer — sending to B3

public void sendToB3(B3OrderRequestDTO message) {
    log.info("Sending order {} to B3 via exchange: {} | routing-key: {}",
            message.getOrderId(), exchange, routingKey);
    rabbitTemplate.convertAndSend(exchange, routingKey, message);
}

Important decision: the message is sent to the exchange with the routing key, not directly to the queue. This respects the RabbitMQ routing model and allows adding new consumers without changing the producer.

Consumer — receiving B3 feedback

@RabbitListener(queues = "${app.rabbitmq.queue-out}")
public void receiveFeedback(B3OrderResponseDTO response) {
    log.info("Feedback received from B3 for order: {} | Status: {}",
            response.getOrderId(), response.getStatus());
    try {
        orderStatusService.updateOrderStatus(response);
    } catch (Exception e) {
        log.error("Failed to update status for order {}: {}",
                response.getOrderId(), e.getMessage(), e);
        throw e; // RabbitMQ applies retry/DLQ policy
    }
}

The throw e is intentional: rethrowing the exception allows RabbitMQ to apply its retry policy instead of silently discarding the message.

6. Status Update — OrderStatusService

When B3 feedback arrives, OrderStatusService updates the order state and publishes the second Kafka event:

@Transactional
public void updateOrderStatus(B3OrderResponseDTO response) {
    Order order = orderRepository.findById(Long.valueOf(response.getOrderId()))
            .orElseThrow(() -> new RuntimeException("Order not found: " + response.getOrderId()));

    order.setStatus(OrderStatus.valueOf(response.getStatus()));
    order.setExecutedPrice(response.getExecutedPrice());

    orderRepository.save(order);

    // Notify ecosystem with final status — wallet settles or refunds
    orderEventProducer.sendOrderEvent(order.mapToEvent());
}

This second Kafka event closes the loop: trading-broker-wallet consumes it and executes the settlement (FILLED) or refund (REJECTED) of the balance blocked in the previous step.

REST API

Method	Endpoint	Description
POST	`/api/v1/orders`	Place a new buy or sell order
GET	`/api/v1/orders/{id}`	Get order details by ID
GET	`/api/v1/orders/user/{userId}`	List all orders for a user

Swagger UI: http://localhost:8088/swagger-ui.html

✅ Validating the Execution

With the application running locally:

✅ Flyway validated the orders table schema
✅ Tomcat started on port 8088
✅ RabbitMQ connected with exchange, queues and DLQ declared
✅ Swagger UI with 3 documented endpoints
✅ AssetClient validating ticker before any persistence
✅ WalletClient validating balance for BUY orders

The Complete Ecosystem

With trading-broker-order ready, we have the first end-to-end flow working:

[User] → [Order API] → [Asset API]  (ticker validation)
                    → [Wallet API]  (balance validation)
                    → [B3 Matching Engine] (execution)
                    → [Kafka] → [Wallet API] (custody)

From the user's click to the updated wallet balance, through ticker and balance validation, RabbitMQ routing, price matching against Redis, and eventual consistency via Kafka.

Got any questions about the design decisions or the inter-service orchestration? Drop them in the comments!

About the Series

⬅️ Previous Post: Financial Custody: Managing Balance and Portfolio with Eventual Consistency

Series Index: Series Roadmap

Links:

Financial Custody: Managing Balance and Portfolio with Eventual Consistency

Tue, 12 May 2026 20:43:57 +0000

Hey folks!

Continuing the My Broker B3 series, we've reached one of the most business-logic-rich services in the ecosystem: the Broker Wallet API.

In previous posts we built the B3 infrastructure (market price sync and matching engine). Now we enter the financial core of the broker. This service is the guardian of the investor's money and assets — it needs to be correct above all else.

What is the Wallet API?

The trading-broker-wallet is the financial custody service of the ecosystem. Its responsibility is to react to order lifecycle events and ensure the user's money and assets are managed correctly at each step.

It doesn't receive direct buy commands — it listens to Kafka events and acts according to each order's status:

Kafka: order-events-v1
         │
    ┌────┴────────────────────────┐
    │                             │
 PENDING                       FILLED / REJECTED
    │                             │
 reserveBalance()          settleOrder() / refundBalance()
    │                             │
 Blocks balance            Settles or refunds

Why is the Wallet so Critical?

Imagine the following scenario without proper custody:

User has R$ 1,000 available
Places a buy order for R$ 800
Before the order is processed, places another order for R$ 500
Both orders are executed → user ends up with negative balance

The wallet solves this with the concept of blocked balance: the moment an order enters as PENDING, the value is immediately reserved. The available balance is always balance - blockedBalance.

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.5.11	Service core
MySQL + Flyway	Operational persistence and versioning
Spring Kafka	Order event consumption
Spring Data Redis	Real-time prices for portfolio valuation
SpringDoc OpenAPI	Swagger UI documentation

️ The Data Model

Before diving into the logic, it's important to understand the three entities that support the service:

Account
├── userId (UNIQUE)
├── balance          ← total balance (includes blocked amount)
├── blockedBalance   ← amount reserved for PENDING orders
└── currency

Account (1) ──▶ (N) Position
                     ├── ticker
                     ├── quantity
                     └── averagePrice

WalletTransaction (audit log)
├── orderId
├── userId
├── transactionType  ← RESERVE | SETTLEMENT | REFUND
└── amount

The blockedBalance is the central piece of custody. The balance never goes below zero — only blockedBalance goes up and down as orders progress through their lifecycle.

The Order Lifecycle in the Wallet

Step 1 — PENDING: Reserving the Balance

When an order is created, it arrives as PENDING. The wallet must immediately block the maximum amount that could be debited (quantity × limit price):

@Transactional
public void reserveBalance(OrderEventDTO event) {
    BigDecimal amountToReserve = event.getPrice().multiply(event.getQuantity());

    Account account = accountRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new RuntimeException("Account not found for user: " + event.getUserId()));

    // Available = balance - blockedBalance
    BigDecimal availableBalance = account.getAvailableBalance();

    if (availableBalance.compareTo(amountToReserve) < 0) {
        throw new RuntimeException("Insufficient balance to reserve funds.");
    }

    // Only blockedBalance increases — total balance stays intact
    account.setBlockedBalance(account.getBlockedBalance().add(amountToReserve));
    accountRepository.save(account);

    // Audit record
    walletTransactionRepository.save(WalletTransaction.builder()
            .userId(event.getUserId())
            .orderId(event.getOrderId())
            .transactionType(TransactionType.RESERVE)
            .amount(amountToReserve)
            .build());
}

Important point: the total balance doesn't change at this step. Only blockedBalance increases. The money is still in the account — it's just reserved.

Step 2a — FILLED: Settling the Order

The order was executed by the Matching Engine. Now the money actually leaves. But here's a subtlety: the executed price may differ from the reserved price.

Example: user placed a buy order with a limit of R$ 30.00, but the market executed at R$ 29.50. The reserved amount was R$ 300 (10 shares × R$ 30), but the actual executed amount was R$ 295 (10 × R$ 29.50). The R$ 5.00 difference automatically becomes available again.

@Transactional
public void settleOrder(OrderEventDTO event) {
    BigDecimal totalReserved = event.getPrice().multiply(event.getQuantity());
    BigDecimal totalExecuted = event.getExecutedPrice().multiply(event.getQuantity());

    Account account = accountRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new RuntimeException("Account not found"));

    // Release the initial block
    BigDecimal newBlockedBalance = account.getBlockedBalance().subtract(totalReserved);
    account.setBlockedBalance(newBlockedBalance.compareTo(BigDecimal.ZERO) < 0
            ? BigDecimal.ZERO
            : newBlockedBalance);

    // Debit the actual executed amount from total balance
    account.setBalance(account.getBalance().subtract(totalExecuted));
    accountRepository.save(account);

    // Update asset position
    updatePosition(event, account);
}

Step 2b — REJECTED: Refunding the Balance

The order was rejected (price outside market range, ticker not found in Redis, etc.). The blocked money becomes available again:

@Transactional
public void refundBalance(OrderEventDTO event) {
    BigDecimal amountToRefund = event.getPrice().multiply(event.getQuantity());

    Account account = accountRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new RuntimeException("Account not found for refund"));

    // Only subtract from blockedBalance — total balance was never touched
    if (account.getBlockedBalance().compareTo(amountToRefund) >= 0) {
        account.setBlockedBalance(account.getBlockedBalance().subtract(amountToRefund));
    } else {
        log.warn("Refund amount exceeds blocked balance for order {}", event.getOrderId());
        account.setBlockedBalance(BigDecimal.ZERO);
    }

    accountRepository.save(account);
}

Weighted Average Price Calculation

When a purchase is settled, we need to update the user's position in that asset. The weighted average price ensures that purchases made at different times are correctly reflected:

New Average Price = (Current Cost + New Cost) / (Current Qty + New Qty)

private void updatePosition(OrderEventDTO event, Account account) {
    Position position = positionRepository
            .findByAccountIdAndTicker(account.getId(), event.getTicker())
            .orElse(Position.builder()
                    .account(account)
                    .ticker(event.getTicker())
                    .quantity(BigDecimal.ZERO)
                    .averagePrice(BigDecimal.ZERO)
                    .build());

    boolean isSell = "SELL".equalsIgnoreCase(event.getSide());

    if (isSell) {
        BigDecimal newQuantity = position.getQuantity().subtract(event.getQuantity());
        if (newQuantity.compareTo(BigDecimal.ZERO) <= 0) {
            positionRepository.delete(position);
            return;
        }
        position.setQuantity(newQuantity);
        // Average price stays the same on sell
    } else {
        // BUY: recalculate weighted average price
        BigDecimal currentCost = position.getAveragePrice().multiply(position.getQuantity());
        BigDecimal newCost = event.getExecutedPrice().multiply(event.getQuantity());
        BigDecimal totalQuantity = position.getQuantity().add(event.getQuantity());
        BigDecimal newAveragePrice = currentCost.add(newCost)
                .divide(totalQuantity, 4, RoundingMode.HALF_UP);

        position.setQuantity(totalQuantity);
        position.setAveragePrice(newAveragePrice);
    }

    positionRepository.save(position);
}

Practical example:

Purchase 1: 10 PETR4 shares at R$ 30.00 → average price = R$ 30.00
Purchase 2: 5 PETR4 shares at R$ 33.00 → average price = (300 + 165) / 15 = R$ 31.00

Critical Bugs Fixed

During the code review, I identified issues that would cause silent failures in production:

1. Guaranteed NPE on first deposit
New account created without initializing blockedBalance. The first call to getAvailableBalance() would throw NullPointerException.

// ❌ Before
Account.builder()
    .balance(BigDecimal.ZERO)
    // blockedBalance missing → NPE

// ✅ After
Account.builder()
    .balance(BigDecimal.ZERO)
    .blockedBalance(BigDecimal.ZERO)

2. Withdraw validated total balance, not available balance
Allowed withdrawing money that was blocked in pending orders:

// ❌ Before — allows withdrawing reserved funds
if (account.getBalance().compareTo(amount) < 0)

// ✅ After — validates only what's available
if (account.getAvailableBalance().compareTo(amount) < 0)

3. SELL increased position instead of decreasing it
The updatePosition() method always added quantity, completely ignoring the side field. Selling 10 shares would add 10 to the position.

4. Kafka consumer silently swallowed exceptions
Errors were logged but the offset was committed — the message was discarded without retry. Now the consumer rethrows the exception so Kafka can apply its retry policy correctly.

Idempotency

To prevent duplicates in case of Kafka reprocessing, we added a database constraint:

-- V4 migration
ALTER TABLE wallet_transactions
    ADD CONSTRAINT uq_order_transaction UNIQUE (order_id, transaction_type);

If the same PENDING event arrives twice, the second insert will fail with a constraint violation — preventing the balance from being blocked twice for the same order.

REST API

Method	Endpoint	Description
POST	`/api/v1/wallet/{userId}/deposit`	Deposit funds
POST	`/api/v1/wallet/{userId}/withdraw`	Withdraw available funds
GET	`/api/v1/wallet/{userId}/summary`	Summary: balance + positions + total equity
GET	`/api/v1/wallet/{userId}/positions`	List asset positions
GET	`/api/v1/wallet/{userId}/transactions`	Transaction history

Swagger UI: http://localhost:8085/swagger-ui.html

✅ Validating the Execution

With the application running locally:

✅ Flyway applied all 4 migrations successfully
✅ Hibernate validated the schema
✅ Kafka consumer connected and subscribed to order-events-v1
✅ Consumer group trading-broker-wallet synced
✅ Swagger UI with 5 documented endpoints at http://localhost:8085/swagger-ui.html

What's Next?

With the Wallet ready to react to order events, the next step is building the trading-broker-order — the orchestrator that will manage the complete order lifecycle:

Receive buy/sell intent via REST
Validate the ticker against trading-broker-asset
Save the order as PENDING and publish to Kafka
Send the order to the Matching Engine via RabbitMQ
Consume the result and update the final status

Once that service is ready, we'll have the first complete end-to-end flow: from the user's click all the way to the updated wallet balance.

Got any questions about the custody logic or the PENDING → FILLED → REJECTED cycle? Drop them in the comments!

About the Series

⬅️ Previous Post: The Heart of B3: Building the Matching Engine with RabbitMQ and Redis

Series Index: Series Roadmap

Links:

Spring Boot Large File Upload: Limits, Streaming, and Production Best Practices

Tue, 12 May 2026 07:14:52 +0000

File uploads look simple until someone uploads a 2GB video.

Then suddenly your backend starts behaving differently:

memory usage spikes
requests take forever
uploads fail halfway
server threads stay blocked
users retry the same upload again

A small file upload API and a production-ready large file upload API are not the same thing.

If you're building file upload functionality in Spring Boot, simply increasing the max upload limit is not enough.

Let's look at how to handle large file uploads properly.

Why large file uploads become a backend problem

For small files, basic multipart upload works fine.

For larger files, several issues appear quickly:

1. Memory pressure

A common mistake is loading the uploaded file entirely into memory.

Example:

byte[] bytes = file.getBytes();

Looks harmless.

But if users upload 500MB or 2GB files, this becomes dangerous fast.

That single line can destroy your application's memory stability.

2. Long request lifecycle

Large uploads naturally take longer.

That means:

open HTTP connections for longer periods
higher timeout risk
blocked request threads
poor user experience if retries happen

3. Storage bottlenecks

Saving directly to local disk may work in development.

In production:

multiple instances may not share storage
containers may lose uploaded files
disk space becomes a hidden failure point

4. Broken validation strategy

If validation happens too late, you waste resources processing invalid uploads.

Examples:

unsupported file types
oversized payloads
corrupted uploads

Reject bad uploads early.

How large file uploads should work

A cleaner production flow looks like this:

Client sends multipart upload request
Server validates request constraints
File is streamed instead of fully loaded
Storage layer handles persistence
API returns upload metadata

Simple architecture.

Big difference in reliability.

Configure upload limits first

Start by defining upload constraints.

spring.servlet.multipart.max-file-size=1GB
spring.servlet.multipart.max-request-size=1GB

This protects your application from uncontrolled uploads.

Without limits:

accidental abuse becomes easy
memory pressure becomes unpredictable
infrastructure costs can spike

Limits are not optional.

The biggest mistake: loading entire files into memory

This pattern is dangerous:

byte[] bytes = file.getBytes();

Also risky:

String content = new String(file.getBytes());

Why?

Because the whole file gets loaded into memory before processing.

For large uploads, this is exactly what you want to avoid.

Instead, stream the content.

Better approach: stream the upload

Use InputStream instead of loading everything at once.

Example:

@PostMapping("/upload")
public ResponseEntity<String> upload(
        @RequestParam("file") MultipartFile file
) throws IOException {

    if (file.isEmpty()) {
        return ResponseEntity.badRequest().body("File is empty");
    }

    Path destination = Paths.get("/uploads/" + file.getOriginalFilename());

    try (InputStream inputStream = file.getInputStream()) {
        Files.copy(inputStream, destination);
    }

    return ResponseEntity.ok("Upload successful");
}

Why this is better:

lower memory usage
safer under larger payloads
simpler production behavior
predictable resource consumption

Separate upload logic from storage logic

Do not put everything inside the controller.

Bad:

@PostMapping("/upload")
public ResponseEntity<?> upload(MultipartFile file) {
    // validation
    // storage logic
    // business rules
    // response mapping
}

Cleaner structure:

controller handles request
service handles workflow
storage layer handles persistence

Example:

@RestController
@RequiredArgsConstructor
public class FileUploadController {

    private final FileUploadService fileUploadService;

    @PostMapping("/upload")
    public ResponseEntity<String> upload(
            @RequestParam MultipartFile file
    ) {
        fileUploadService.upload(file);
        return ResponseEntity.ok("Uploaded");
    }
}

Service:

@Service
@RequiredArgsConstructor
public class FileUploadService {

    private final StorageService storageService;

    public void upload(MultipartFile file) {
        storageService.store(file);
    }
}

This becomes much easier to maintain later.

Storage strategy matters

Local storage is okay for prototypes.

Production systems often need better options:

Local disk

Good for:

prototypes
internal tools
single-instance deployments

Bad for:

autoscaling environments
Docker/Kubernetes deployments
distributed systems

Cloud object storage

Examples:

AWS S3
Cloudflare R2
MinIO
Google Cloud Storage

Better for:

scalability
durability
shared access across instances
predictable infrastructure behavior

Validate before expensive processing

Check uploads early.

Minimum checks:

if (file.isEmpty()) {
    throw new IllegalArgumentException("Empty file");
}

Size:

if (file.getSize() > MAX_UPLOAD_SIZE) {
    throw new IllegalArgumentException("File too large");
}

Content type:

if (!allowedTypes.contains(file.getContentType())) {
    throw new IllegalArgumentException("Unsupported file type");
}

Do this before storage work starts.

Common production mistakes

Loading everything into memory

Classic performance killer.

No upload size limits

This creates operational risk immediately.

Using local storage inside containers

Looks fine in dev.

Breaks badly in production.

No timeout awareness

Large uploads take time.

Your infrastructure must account for that.

Mixing upload and business logic

Creates messy controllers and painful maintenance.

Production checklist

Before shipping large upload support:

upload size limits configured
streaming instead of full buffering
validation before processing
storage abstraction in place
timeout settings reviewed
failure handling implemented
infrastructure storage strategy chosen

If this list is incomplete, the implementation is not production-ready.

Final thoughts

Large file uploads are not complicated.

But careless implementations become expensive fast.

The winning approach is simple:

set hard limits
stream uploads
validate early
separate responsibilities
choose proper storage

That gets you a stable upload API.

Built a similar production-ready upload architecture recently while working on Spring Boot backend tooling at BuildBaseKit.

LLM Observability tool

Mon, 11 May 2026 06:50:41 +0000

I just created an open source LLM observability named "TraceLM" that can track the following activities:

token cost
token length
latency information etc

The following tool can be found here:

https://github.com/unnivm/tracelm-java-agent

This tools offers a very cool dashboard to track the above information. The user is required to login to access this dashboard.

This tool currently supports only Java based applications as it is basically working based on instrumentation technique. But, this tool will be extended ti support other programming languages as well.

This project is under development and am going to add more features to to so that the idea is to make it an enterprise ready product.

The Heart of B3: Building the Matching Engine with RabbitMQ, Redis and Spring Boot

Sun, 10 May 2026 21:29:07 +0000

Hello everyone!

Continuing the My Broker B3 series, we've reached one of the most anticipated components of the ecosystem: the B3 Matching Engine API.

In the previous post, we built b3-market-sync-api which synchronizes real prices from brapi.dev and stores them in Redis. Now it's time to use that data — this is the service that simulates the stock exchange itself, deciding whether a buy or sell order will be executed or rejected based on the prices we just put in cache.

️ What is the Matching Engine?

In the real world, when you place a buy order through your broker, it gets sent to B3, which checks whether there's a counterpart willing to trade at that price. This process is called matching.

In our simulator, the b3-matching-engine-api reproduces this logic in a simplified way:

Intake: Receives the order from the broker via RabbitMQ (queue mq-broker-to-b3)
Price: Fetches the current asset price from Redis (market:price:{TICKER}) — data injected by the Market Sync we built previously
Decision: Applies the matching rule
Persistence: Records the result in PostgreSQL
Notification: Returns the result to the broker via RabbitMQ (queue mq-b3-to-broker)

[Broker] ──RabbitMQ──▶ [mq-broker-to-b3] ──▶ [Matching Engine]
                                                      │
                                             Redis: market:price:{TICKER}
                                             (fed by Market Sync ⬆️)
                                                      │
                                         ┌────────────┴────────────┐
                                      FILLED                   REJECTED
                                         │                         │
                                   PostgreSQL                 PostgreSQL
                                         │                         │
                               [mq-b3-to-broker] ◀────────────────┘
                                         │
                                      [Broker]

MVP Focus

Before diving into the code, same disclaimer as previous posts: we're building the foundation. The goal is to have an end-to-end flow working with enough robustness to validate the POC.

In this phase, I prioritized:

End-to-end flow working correctly
Proper failure handling (no orders silently disappearing)
Dead Letter Queue for messages that fail during processing
REST API for querying execution history
Swagger documentation

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.5	Service core
Spring RabbitMQ	Order intake and result notification
Spring Data Redis	Real-time price lookup
Spring Data JPA + PostgreSQL	Execution persistence
Flyway	Database schema versioning
SpringDoc OpenAPI	Swagger UI documentation

️ Implementation Pillars

1. RabbitMQ Configuration

A critical lesson learned here: never rely on queues already existing in the broker. If the application starts before RabbitMQ has the queues created, the consumer fails on startup.

The solution is to declare all infrastructure beans directly in Spring — it ensures queues, exchanges and bindings exist before any message is processed:

@Bean
public DirectExchange exchange() {
    return new DirectExchange(exchangeName);
}

@Bean
public Queue queueIn() {
    return QueueBuilder.durable(queueIn)
            .withArgument("x-dead-letter-exchange", dlxName)
            .withArgument("x-dead-letter-routing-key", dlqName)
            .build();
}

@Bean
public Binding bindingQueueIn(Queue queueIn, DirectExchange exchange) {
    return BindingBuilder.bind(queueIn).to(exchange).with(routingKey);
}

Note the withArgument calls — they configure the Dead Letter Queue directly in the main queue declaration. Any message that fails processing is automatically redirected.

2. The Matching Logic

The heart of the service. The rule is straightforward:

BUY: If the price the user accepts to pay >= market price → FILLED
SELL: If the price the user wants to receive <= market price → FILLED
Otherwise → REJECTED

private static boolean isCanExecute(OrderEventDTO order, BigDecimal marketPrice) {
    if (SideStatus.BUY.name().equalsIgnoreCase(order.getSide())) {
        return order.getPrice().compareTo(marketPrice) >= 0;
    } else if (SideStatus.SELL.name().equalsIgnoreCase(order.getSide())) {
        return order.getPrice().compareTo(marketPrice) <= 0;
    }
    return false;
}

3. Failure Handling — No Silent Order Loss

A silent bug I identified: when the ticker wasn't in Redis, the method simply returned without doing anything. The broker would wait for a response that never came.

The fix was simple but critical — any failure must notify the broker:

if (marketDataOpt.isEmpty()) {
    log.warn("Price for ticker {} not found in Redis. Rejecting order {}",
             order.getTicker(), order.getOrderId());
    OrderResponseEvent response = new OrderResponseEvent(
        order.getOrderId(), ExecutionStatus.REJECTED.name(), BigDecimal.ZERO);
    orderProducer.sendToBroker(response);
    return;
}

This is exactly why we built b3-market-sync-api first. If Redis doesn't have the price, the order is immediately rejected — correct and predictable behavior.

4. Transactional Guarantee

Another critical point: persisting to PostgreSQL and publishing to RabbitMQ are two distinct operations. If the database saves but the publish fails, the execution is recorded but the broker is never notified — silent inconsistency.

The solution was adding @Transactional to the method that orchestrates both operations:

@Transactional
private void saveAndNotify(OrderEventDTO order, BigDecimal price, ExecutionStatus status) {
    // 1. Persists in PostgreSQL
    OrderExecution execution = OrderExecution.builder()
            .orderId(order.getOrderId())
            .ticker(order.getTicker())
            .side(SideStatus.valueOf(order.getSide()))
            .quantity(order.getQuantity())
            .executedPrice(price)
            .status(status)
            .build();
    repository.save(execution);

    // 2. Notifies the Broker
    OrderResponseEvent response = new OrderResponseEvent(
        order.getOrderId(), status.name(), price);
    orderProducer.sendToBroker(response);
}

5. Dead Letter Queue

For messages that fail in the consumer (unexpected processing error), we configured a full DLQ setup:

@Bean
public DirectExchange deadLetterExchange() {
    return new DirectExchange(dlxName);
}

@Bean
public Queue deadLetterQueue() {
    return QueueBuilder.durable(dlqName).build();
}

@Bean
public Binding bindingDlq(Queue deadLetterQueue, DirectExchange deadLetterExchange) {
    return BindingBuilder.bind(deadLetterQueue)
            .to(deadLetterExchange)
            .with(dlqName);
}

In the consumer, we rethrow the exception so RabbitMQ knows the message failed and routes it to the DLQ:

@RabbitListener(queues = "${app.rabbitmq.queue-in}")
public void receiveOrder(OrderEventDTO event) {
    log.info("New order received: ID {} | Ticker {} | Side {}",
            event.getOrderId(), event.getTicker(), event.getSide());
    try {
        matchingService.process(event);
    } catch (Exception e) {
        log.error("Failed to process order {}: {}", event.getOrderId(), e.getMessage(), e);
        throw e; // RabbitMQ routes to DLQ
    }
}

6. REST API + Swagger

Since the service exposes query endpoints, I configured Swagger UI from the start:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("B3 Matching Engine API")
                    .version("1.0.0")
                    .description("Simulates the B3 stock exchange matching engine..."));
}

Available endpoints:

Method	Endpoint	Description
GET	`/api/v1/executions`	List all executions
GET	`/api/v1/executions/order/{orderId}`	Find by order ID
GET	`/api/v1/executions/ticker/{ticker}`	Find by ticker
GET	`/api/v1/executions/status/{status}`	Find by status

✅ Validating the Execution

With the application running locally, all components started correctly:

✅ Flyway applied the order_executions table migration
✅ Hibernate validated the schema
✅ RabbitMQ connected with queues and DLQ declared
✅ Tomcat running on port 8091
✅ Swagger UI accessible at http://localhost:8091/swagger-ui.html

What's Next?

With b3-market-sync-api feeding Redis and b3-matching-engine-api ready to process orders, the entire B3 side is operational.

The next step is building the broker-order-api — the orchestrator on the broker side that will manage the complete order lifecycle:

Receive the buy/sell intent from the user
Validate the ticker via REST against broker-asset-api
Save the order as PENDING
Publish the event to Kafka
Send the order to the Matching Engine via RabbitMQ
Consume the feedback and update the final status

Once that service is ready, we'll have the first complete end-to-end flow running in the ecosystem.

Got any questions about the matching logic or RabbitMQ DLQ configuration? Drop them in the comments!

About the Series

⬅️ Previous Post: Syncing the Real Market: Consuming Brapi and Feeding Redis with Spring Boot

Series Index: Series Roadmap

Links:

Reason and Solutions for Java uses unchecked or unsafe operations:

Sun, 10 May 2026 11:22:40 +0000

As a developer working with Java, you have surely met this warning before: "uses unchecked or unsafe operations". In this blog, we'll discover what is "uses unchecked or unsafe operations" and how to resolve it.

What is Java warning: uses unchecked or unsafe operations

"Uses unchecked or unsafe operations" is a compilation warning that occurs when Java compiler is compiling our codes but it finds some codes which are lack of error checking or having unsafe operation. However, it's just an warning rather than error. It means that your codes will still run successfully and display the desired output.

Examples of Java uses unchecked or unsafe operations


  public static void main(String[] args) {
        ArrayList students = new ArrayList();
        students.add("Alex");
        students.add("Cindy");
        students.add("Benjamin");
        for(int i = 0; i < students.size(); i++){
            System.out.println(students.get(i));
        }
        }

This is the output:



Note: C:\Users\MC\Documents\NetBeansProjects\LabViva\src\labviva\NewMain.java uses unchecked or unsafe operations.

Note: Recompile with -Xlint:unchecked for details.

compile-single:

run-single:

Alex

Cindy

Benjamin

Look, we've got the desired output, as we print each student in the ArrayList, students. However, you may also notice the warning: uses unchecked or unsafe operations. Note: Recompile with -Xlint:unchecked for details.

Causes of Java warning: uses unchecked or unsafe operations

Basically, it occurs when we use raw types of collections rather than paramaterized types, Which is also known as generics of collections. This is due to the reason that specifying the raw types of collections in hazardous as it might produce unexpected error during runtime, such as ClassCastException. For example:


public static void main(String[] args) {
       ArrayList numbers = new ArrayList();
       numbers.add(1);
       numbers.add(2);
       numbers.add("Cindy");
       for(int i = 0; i < numbers.size() - 1; i++){
           System.out.println((int)numbers.get(i) + (int)numbers.get(i + 1));
       }
       }

This is the output:


Note: C:\Users\MC\Documents\NetBeansProjects\LabViva\src\labviva\NewMain.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
compile-single:
run-single:
3
Exception in thread "main" java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Integer (java.lang.String and java.lang.Integer are in module java.base of loader 'bootstrap')

Here, we're trying to cast the value, "Cindy" to an integer value for addition opearation, which is invalid and hazardous. This error happens because we're using the raw ArrayList! We accidentally insert a String value into the ArrayList of Integer type.

So now, how can we differentiate the raw collections and generic collections?

Examples:


ArrayList students = new ArrayList();

This is the raw types of ArrayList without any type specifier.


ArrayList students = new ArrayList();

The ArrayList, students has the type specifier, which is , but it doesn't include it at the end of the constructor.

Both of the examples above will render the compilation error: "Uses unchecked or unsafe operations" because the Java compiler refers to the ArrayList raw type rather than generic types.

This is the generic collections:


ArrayList students = new ArrayList();

or like this:


ArrayList students = new ArrayList<>();

Tip After specifying the generic types, ArrayList at the front, we can substitute the parameterized type of construtor with empty diamond, <> as the compiler may recognize the generic data type and do the type inference automatically.

Solution to Java warning: uses unchecked or unsafe operations

The solution is pretty simple and straightforward. You should always use generic collections rather than raw collections! It's always the best to specify the data type of the collections so that the Java compiler can check across the collections to make sure it stores a list of values with same data type to avoid any unintentional error.


 public static void main(String[] args) {
        ArrayList students = new ArrayList<>();
        students.add("Alex");
        students.add("Cindy");
        students.add("Benjamin");
        for(int i = 0; i < students.size(); i++){
            System.out.println(students.get(i));
        }
        }

This is the output:


Alex
Cindy
Benjamin
BUILD SUCCESSFUL (total time: 1 second)

You may notice that the compile warning: "Uses unchecked or unsafe operations" has gone.

After specifying the generic type, if you add a value with data type different from that generic type, you would get the compile error.


    public static void main(String[] args) {
        ArrayList students = new ArrayList<>();
        students.add("Alex");
        students.add("Cindy");
        students.add(1);
        for(int i = 0; i < students.size(); i++){
            System.out.println(students.get(i));
        }
        }

This is the compile error:


incompatible types: int cannot be converted to String

This is because the value, 1 has Integer data type, which is incompatible to the generic type, of the collection.

Tip If you want to know why and where the compile error happens, you can recompile your projects using the -Xlint:unchecked command.

For Apache Netbeans, go to Your Project -> Properties -> Compiling -> Additional Compilation Options, and paste -Xlint:unchecked. When you run the codes:


    public static void main(String[] args) {
        ArrayList students = new ArrayList();
        students.add("Alex");
        students.add("Cindy");
        students.add("Benjamin");
        for(int i = 0; i < students.size(); i++){
            System.out.println(students.get(i));
        }
        }

This is the output:


C:\Users\MC\Documents\NetBeansProjects\LabViva\src\labviva\NewMain.java:21: warning: [unchecked] unchecked call to add(E) as a member of the raw type ArrayList
        students.add("Alex");
  where E is a type-variable:
    E extends Object declared in class ArrayList
C:\Users\MC\Documents\NetBeansProjects\LabViva\src\labviva\NewMain.java:22: warning: [unchecked] unchecked call to add(E) as a member of the raw type ArrayList
        students.add("Cindy");
  where E is a type-variable:
    E extends Object declared in class ArrayList
C:\Users\MC\Documents\NetBeansProjects\LabViva\src\labviva\NewMain.java:23: warning: [unchecked] unchecked call to add(E) as a member of the raw type ArrayList
        students.add("Benjamin");
  where E is a type-variable:
    E extends Object declared in class ArrayList
3 warnings
compile-single:
run-single:
Alex
Cindy
Benjamin
BUILD SUCCESSFUL (total time: 1 second)

Then, you can notice what of your codes produce this compile warnings.

Note You can also use @SuppressWarnings("unchecked") to hide this warning. However, it's inadvisable because we should always use generic collections rather than raw collections. Hiding this warning will cause you to not realise when you're using raw collections.


    @SuppressWarnings("unchecked")
    public static void main(String[] args) {
        ArrayList students = new ArrayList();
        students.add("Alex");
        students.add("Cindy");
        students.add("Benjamin");
        for(int i = 0; i < students.size(); i++){
            System.out.println(students.get(i));
        }
        }

This is the output:


Alex
Cindy
Benjamin
BUILD SUCCESSFUL (total time: 1 second)

The compilation warning: "uses unchecked or unsafe operations" is now hidden rather than solved.

That's all about Java uses unchecked or unsafe operations and the way to solve it. Hope it helps, Thanks! :)

Syncing the Real Market: Consuming Brapi and Feeding Redis with Spring Boot

Sun, 10 May 2026 11:03:34 +0000

Hello everyone!

Continuing the My Broker B3 series, today we'll talk about an essential component on the B3 side of our simulator: the B3 Market Sync API.

Before building the engine that decides whether an order gets executed or rejected, we need to ensure it has access to real market prices. That's exactly what b3-market-sync-api does: fetches real asset prices from brapi.dev and stores them in Redis, ready for real-time consumption.

️ What is the Market Sync?

This microservice has a single, well-defined responsibility: to be the market data producer of the ecosystem. It operates completely asynchronously and independently — no other service needs to call it directly.

The flow is simple and elegant:

[brapi.dev] ◀── Feign Client ── [MarketSyncScheduler]
                                         │
                              market:price:{TICKER}
                                         │
                                      [Redis]
                                         │
                              [B3 Matching Engine] (next post)

MVP Focus

The goal here is clear: have real prices available in Redis with low latency. The Matching Engine we'll build in the next post won't query a database or make HTTP calls to get prices — it goes straight to Redis. This ensures the matching decision happens in microseconds.

In this phase, I prioritized:

Scheduled sync with market hours guard
Redis cache with TTL to prevent stale data
External API rate limit protection
Critical bug fixes found during code review
REST API for querying cached prices
Swagger documentation

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.5.11	Service core
Spring Cloud OpenFeign	Declarative HTTP client for brapi.dev
Spring Data Redis	High-performance cache
Spring Scheduling	Periodic synchronization
Jackson JSR310	Java 8 Date/Time serialization support
SpringDoc OpenAPI	Swagger UI documentation

️ Implementation Pillars

1. Feign Client — Consuming Brapi

Spring Cloud OpenFeign lets you declare an HTTP client as a simple interface, with no boilerplate code:

@FeignClient(name = "brapiClient", url = "${app.brapi.url}")
public interface BrapiClient {

    @GetMapping("/quote/{ticker}")
    BrapiResponseDTO getQuote(
        @PathVariable String ticker,
        @RequestParam String token
    );
}

The URL and token are injected via application.yaml, keeping the code clean and environment-configurable.

2. Scheduler with Market Hours Guard

The heart of the service is a scheduled job that fires every 30 minutes. But before any API call, it checks whether the market is open:

@Scheduled(fixedRateString = "${app.sync.interval:1800000}")
public void sync() {
    if (!isMarketOpen()) {
        log.info("Sync aborted: market is closed (outside trading hours or weekend).");
        return;
    }
    // ... fetch and store prices
}

private boolean isMarketOpen() {
    ZonedDateTime now = ZonedDateTime.now(ZoneId.of("America/Sao_Paulo"));
    DayOfWeek day = now.getDayOfWeek();
    int hour = now.getHour();

    if (day == DayOfWeek.SATURDAY || day == DayOfWeek.SUNDAY) {
        return false;
    }

    // B3 trading hours: 10:00 to 18:00 (Sao Paulo time)
    return hour >= 10 && hour < 18;
}

Important detail: we use ZonedDateTime with America/Sao_Paulo explicitly. Inside a Docker container, the JVM may default to UTC — which would make the market hours guard behave incorrectly. We also pass -Duser.timezone=America/Sao_Paulo in the Dockerfile ENTRYPOINT to ensure the JVM honors the correct timezone:

ENTRYPOINT ["java", "-Duser.timezone=America/Sao_Paulo", "-jar", "app.jar"]

3. Redis Cache with Correct TTL

The MarketDataService stores each quote in Redis with a standardized key and 5-minute TTL:

private static final Duration CACHE_TTL = Duration.ofMinutes(5);

public void saveToCache(BrapiResultDTO quote) {
    String key = CACHE_KEY_PREFIX + quote.getTicker();
    // TTL of 5 minutes — if sync stops, stale prices expire quickly
    // preventing the Matching Engine from using outdated data
    redisTemplate.opsForValue().set(key, quote, CACHE_TTL);
    log.info("Ticker {} updated in cache: R$ {}", quote.getTicker(), quote.getRegularMarketPrice());
}

The TTL is fundamental: if the service goes down, prices expire in 5 minutes. The Matching Engine then fails to find the price in Redis and rejects orders — correct and predictable behavior, much better than using hours-old prices.

4. Epoch Timestamp Deserialization

A subtle bug I found: brapi.dev returns the regularMarketTime field as a Unix epoch (integer), but Jackson was trying to deserialize it as LocalDateTime (ISO string). This causes silent deserialization failure.

The solution was a custom deserializer:

public class EpochToLocalDateTimeDeserializer extends StdDeserializer<LocalDateTime> {

    private static final ZoneId SAO_PAULO = ZoneId.of("America/Sao_Paulo");

    @Override
    public LocalDateTime deserialize(JsonParser parser, DeserializationContext context)
            throws IOException {
        long epoch = parser.getLongValue();
        return LocalDateTime.ofInstant(Instant.ofEpochSecond(epoch), SAO_PAULO);
    }
}

And annotating it on the DTO:

@JsonDeserialize(using = EpochToLocalDateTimeDeserializer.class)
private LocalDateTime regularMarketTime;

5. Rate Limit Protection

Since we use the brapi.dev free plan, we added a delay between calls to avoid throttling:

for (String ticker : brapiProperties.getTickers()) {
    try {
        BrapiResponseDTO response = brapiClient.getQuote(ticker.trim(), brapiProperties.getToken());
        if (nonNull(response.getResults()) && !response.getResults().isEmpty()) {
            marketDataService.saveToCache(response.getResults().getFirst());
        }
        // Small delay between calls to avoid hitting rate limit on free plan
        Thread.sleep(200);
    } catch (Exception e) {
        log.error("Failed to sync ticker {}: {}", ticker, e.getMessage());
    }
}

The per-ticker try/catch is essential — if one asset fails, the loop continues for the rest.

6. REST API + Swagger

Although the Matching Engine consumes prices directly from Redis, we added REST endpoints to make debugging and observability easier:

Method	Endpoint	Description
GET	`/api/v1/quotes`	List prices for all configured tickers
GET	`/api/v1/quotes/{ticker}`	Get price for a specific ticker

Documented via Swagger UI at http://localhost:8096/swagger-ui.html.

Security — Token Out of Code

A critical issue I fixed: the brapi.dev token was hardcoded as a default value in application.yaml:

# ❌ Before — token exposed in public repository
token: ${BRAPI_TOKEN:mFk9YRLijAtxsP5y1XxxxX}

# ✅ After — no fallback, variable is required
token: ${BRAPI_TOKEN}

Never expose credentials as default values in public repositories. The application now fails on startup if the variable is not provided — correct behavior.

✅ Validating the Execution

With the application running locally:

✅ Tomcat started on port 8096
✅ Application initialized in under 3 seconds
✅ Scheduler fired and logged: Sync aborted: market is closed (outside trading hours or weekend)
✅ Swagger UI accessible at http://localhost:8096/swagger-ui.html

What's Next?

With b3-market-sync-api up and feeding Redis with real prices, we have the foundation the next service needs to work. In the next post we'll build the B3 Matching Engine — the engine that will consume these prices and decide whether the broker's orders are executed or rejected.

Got any questions about the Redis integration or the market hours guard? Drop them in the comments!

About the Series

⬅️ Previous Post: From Stream to Database: Processing Market Data with Spring Boot, Redis and Flyway

➡️ Next Post: The Heart of B3: Building the Matching Engine with RabbitMQ and Redis (coming soon)

Series Index: Series Roadmap

Links:

From Stream to Database: Processing Market Data with Spring Boot, Redis, and Flyway

Fri, 08 May 2026 20:51:06 +0000

Hey folks!

Continuing the My Broker B3 series, today we build trading-broker-asset — the Java service that consumes the quotes published to Kafka by trading-broker-market-data and transforms them into structured data in MySQL, with high-performance caching in Redis.

If the Python service is the collector, this one is the processor.

️ This Service's Role in the Ecosystem

[trading-broker-market-data]
         │
         │ Kafka: trading-assets-market-data-v1
         ▼
[trading-broker-asset]
         │
    ┌────┴────┐
    ▼         ▼
  MySQL     Redis
(assets)  market:price:{TICKER}
              │
    [b3-matching-engine]   (reads from here)
    [trading-broker-order] (validates ticker from here)

Two critical consumers depend on the data this service maintains: the Matching Engine (for price decisions) and the Order API (to validate whether a ticker exists and is active).

MVP Focus

In this phase, I prioritized:

Robust Kafka consumer with error handling
Asset upsert: creates on first event, updates on subsequent ones
Redis cache with 10-minute TTL
REST API for catalog queries
Status filter: only ACTIVE assets are returned

️ Tech Stack

Technology	Usage
Java 21 + Spring Boot 3.5.11	Service core
Spring Kafka	Quote event consumption
MySQL + Flyway	Versioned asset catalog
Spring Data Redis	Real-time price cache
SpringDoc OpenAPI	Swagger UI documentation

️ Implementation Pillars

1. The Database Schema (Flyway)

CREATE TABLE assets (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    ticker VARCHAR(20) NOT NULL UNIQUE,
    name VARCHAR(200),
    current_price DECIMAL(19, 4),
    last_update DATETIME,
    status ENUM('ACTIVE', 'INACTIVE') NOT NULL DEFAULT 'ACTIVE',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Why Flyway? Schema versioning ensures that any environment (local, CI, production) has exactly the same database structure, without surprises.

2. The Kafka Consumer

@KafkaListener(
        topics = "trading-assets-market-data-v1",
        groupId = "trading-broker-asset"
)
public void consume(AssetMarketDataDTO dto) {
    log.info("Market data received for ticker: {}", dto.getTicker());
    try {
        assetService.updateAsset(dto);
    } catch (Exception e) {
        log.error("Failed to process market data for ticker {}: {}",
                dto.getTicker(), e.getMessage(), e);
        // Rethrow so Kafka can apply retry policy instead of silently discarding
        throw e;
    }
}

Why rethrow the exception? If processing fails silently, the offset is committed and the message is discarded — the asset is never updated. Rethrowing lets Kafka apply its retry policy.

3. The Asset Upsert

@Transactional
public void updateAsset(AssetMarketDataDTO dto) {
    Asset asset = assetRepository.findByTicker(dto.getTicker())
            .orElse(Asset.builder()
                    .ticker(dto.getTicker())
                    .status(AssetStatus.ACTIVE)
                    .build());

    asset.setName(dto.getName());
    asset.setCurrentPrice(dto.getPrice());
    // Uses real market timestamp from event — not LocalDateTime.now()
    asset.setLastUpdate(dto.getUpdatedAt() != null ? dto.getUpdatedAt() : LocalDateTime.now());

    assetRepository.save(asset);

    // Update Redis cache after persisting
    marketPriceCacheService.updatePrice(dto.getTicker(), dto.getPrice());
}

Important decision: we use the real updatedAt from the Kafka event, not LocalDateTime.now(). This ensures lastUpdate in the database reflects when the price was generated by the market, not when it was processed by the service.

4. Redis Cache with TTL

private static final Duration CACHE_TTL = Duration.ofMinutes(10);

public void updatePrice(String ticker, BigDecimal price) {
    String key = "market:price:" + ticker;
    // TTL of 10 minutes — prevents stale prices for inactive or delisted assets
    redisTemplate.opsForValue().set(key, price.toString(), CACHE_TTL);
}

Why TTL? If an asset is deactivated or delisted, its price will expire from Redis in 10 minutes. Without TTL, the Matching Engine could use prices for assets that no longer exist.

5. Status Filter in Queries

public List<AssetDTO> findAllActive() {
    // Query directly by status — not findAll() + filter in memory
    return assetRepository.findAllByStatus(AssetStatus.ACTIVE).stream()
            .map(AssetDTO::fromEntity)
            .toList();
}

public Optional<AssetDTO> findByTicker(String ticker) {
    // Only returns ACTIVE assets — inactive returns 404
    return assetRepository.findByTickerAndStatus(ticker.toUpperCase(), AssetStatus.ACTIVE)
            .map(AssetDTO::fromEntity);
}

When trading-broker-order validates a ticker before creating an order, it calls GET /api/v1/assets/{ticker}. If the asset is inactive, it gets a 404 and the order is rejected. Correct and predictable.

REST API

Method	Endpoint	Description
GET	`/api/v1/assets`	List all active assets
GET	`/api/v1/assets/{ticker}`	Find asset by ticker (404 if inactive)

Swagger UI: http://localhost:8083/swagger-ui.html

✅ Validating the Execution

With the application running and trading-broker-market-data publishing to Kafka:

✅ Consumer connected to the trading-assets-market-data-v1 topic
✅ Assets being created/updated in MySQL in real time
✅ Redis being updated with TTL after each event
✅ Logs showing Updating ticker PETR4 with price R$ 47.37

What's Next?

With the asset catalog working, the next step is b3-market-sync-api — which synchronizes prices directly to the B3's Redis — followed by b3-matching-engine-api, which uses those prices to execute orders.

About the Series

⬅️ Previous Post: Tooling Tips: MongoDB and Kafka

➡️ Next Post: Syncing the Real Market: Consuming Brapi and Feeding Redis with Spring Boot

Series Index: Series Roadmap

Links:

Building a Microservices Ecosystem: Stock Brokerage Simulator (My Broker B3)

Fri, 01 May 2026 13:50:40 +0000

Hey folks!

I'm starting a series of articles to document the development of My Broker B3 — a personal project where I apply advanced software engineering concepts, distributed systems and messaging to simulate the real-world operation of a stock brokerage integrated with B3 (the Brazilian stock exchange).

The goal isn't to build a production system, but rather a POC (Proof of Concept) that validates real-time order processing, financial custody management and market data orchestration using an event-driven architecture.

️ The Ecosystem Overview

The project was designed following the microservices philosophy with a hybrid stack — each service uses the technology that best fits its function:

                    [broker-gateway-api]
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   [broker-order-api] [broker-wallet] [broker-asset]
          │                │
     RabbitMQ           Kafka (order-events-v1)
          │
   [b3-matching-engine]
          │
       Redis ◀── [b3-market-sync-api] ◀── [brapi.dev]

The Services

Broker Side

Service	Language	Responsibility
`broker-identity-api`	Java	Authentication, JWT, user management
`broker-gateway-api`	Java	API Gateway, routing, JWT validation
`broker-order-api`	Java	Order lifecycle orchestration
`broker-wallet-api`	Java	Financial custody, balance and positions
`broker-asset-api`	Java	Asset catalog and internal market data
`broker-market-data-api`	Python	Quote ingestion from Brapi → MongoDB + Kafka
`broker-report-api`	Java	Reports and history

B3 Side (Simulator)

Service	Language	Responsibility
`b3-matching-engine-api`	Java	Order execution, price matching
`b3-market-sync-api`	Java	Price synchronization to Redis

⚙️ Communication Strategy

One of the most important decisions in the project was choosing when to use synchronous communication and when to use asynchronous. The rule was simple: if the response is needed now to continue the flow, use REST. If it can wait, use messaging.

Synchronous (REST/Feign)

broker-order-api → broker-asset-api: validates ticker before creating order
broker-order-api → broker-wallet-api: validates balance before processing buy
broker-identity-api → broker-wallet-api: creates wallet account on registration

Asynchronous (RabbitMQ)

broker-order-api → b3-matching-engine-api: sends orders for execution
b3-matching-engine-api → broker-order-api: execution feedback (FILLED/REJECTED)

Asynchronous (Kafka)

broker-market-data-api → topic assets-market-data-v1 → broker-asset-api
broker-order-api → topic order-events-v1 → broker-wallet-api

Persistence Strategy

Each service uses the database that best fits its nature:

Technology	Service(s)	Why
MySQL	identity, wallet, order, asset	Transactional data with strong consistency
PostgreSQL	b3-matching-engine	B3 core with execution history
MongoDB	broker-market-data	Quote history — flexible schema
Redis	broker-asset, b3-matching-engine	Real-time price cache for fast decisions

The Order Flow — End to End

To materialize the architecture, here's what happens when a user places a buy order:

1. POST /api/v1/orders
        │
        ├─ Validate balance → broker-wallet-api (REST)
        ├─ Persist PENDING → MySQL
        ├─ Publish PENDING → Kafka (broker-wallet blocks balance)
        └─ Send to B3 → RabbitMQ

2. B3 processes, looks up price in Redis
        │
        ├─ FILLED/REJECTED → RabbitMQ → broker-order-api
        ├─ Update status → MySQL
        └─ Publish final status → Kafka (broker-wallet settles/refunds)

From the user's click to the updated wallet balance, through validation, price matching and eventual consistency.

What You'll Find in the Series

Each post documents the construction of a service, focusing on technical decisions, problems encountered and how they were solved:

Overview ← you are here
Infrastructure — Docker Compose with 12+ containers
broker-market-data-api — Python, Brapi, MongoDB, Kafka
b3-market-sync-api — Price synchronization to Redis
b3-matching-engine-api — The B3 execution engine
broker-asset-api — Asset catalog and cache
broker-wallet-api — Financial custody
broker-order-api — The order conductor
broker-identity-api — Authentication and JWT
broker-gateway-api — API Gateway

Feel free to leave feedback or questions in the comments!

About the Series

Series Index: Series Roadmap

Links:

Skill-Based Sub-Agents with LangGraph4j and Spring AI

Thu, 30 Apr 2026 21:42:33 +0000

Combine Tools & Skill to create Agent

Modern agentic systems usually expose two strong but separate abstractions:

Tools, which give an LLM executable capabilities
Skills, which package reusable instructions for a narrow task

This article shows how to combine both ideas in [LangGraph4j] so that a skill is not just prompt text, but a fully operational sub-agent exposed as a tool. The result is a practical pattern for building modular multi-agent systems in Java with [Spring AI] and [LangGraph4j], while keeping each agent focused, reusable, and low in context cost.

Starting from a standard ReACT agent, the approach implemented is quite simple.

Load a SKILL.md file
Read its front matter to define the tool contract ( name and argument description)
Use the skill body as the sub-agent system prompt
Restrict the sub-agent to only the tools declared by the skill
Register the sub-agent in a parent ReAct agent as if it were a normal tool

In other words, a skill becomes an executable tool-backed agent.

Why This Pattern Matters

The standard ReAct pattern already gives an LLM a strong execution model: reason, choose a tool, inspect the result, and continue until the task is complete. That model is useful because the LLM does not need to commit to a fixed plan up front. It can adapt after every tool call.

The next step is to let a tool itself be implemented by another agent.

Once that happens, the parent agent is no longer forced to know every operational detail. It only needs to know:

which specialized capability exists
when to invoke it
what input to pass

The specialized logic is delegated to a narrower agent with its own instructions and its own restricted toolset. This gives us a clean sub-agent architecture without inventing a new orchestration primitive. We reuse the same tool-calling semantics that ReAct agents already understand well.

Why Reusing Tool Semantics Is Powerful

One of the most valuable properties of LLM-based agents is their ability to build and revise a tool execution plan while reasoning over intermediate results. ReAct made this practical by combining thought, action, and observation in a loop.

When a tool call can transparently invoke another agent, we preserve that planning model instead of replacing it.

The parent agent can:

decide that a specialized capability is needed
provide only the task-relevant context
wait for a result exactly as it would for a standard tool

The child agent can:

run its own reasoning loop
invoke its own allowed tools
return a compact outcome to the parent

This gives hierarchical coordination without exposing the full inner workflow to the parent prompt.

Minimizing Context and Token Usage

This pattern also improves context discipline.

Without sub-agents, a single generalist agent often needs:

every tool definition
all operating instructions for every domain
every procedural rule in one large system prompt

That quickly becomes expensive and unreliable.

With skill-based sub-agents:

the parent only sees high-level capabilities
each child sees only the instructions relevant to its task
each child receives only the tools it is allowed to use

This narrower context has practical benefits:

fewer tokens sent to the model
lower prompt interference between unrelated domains
clearer tool choice
better modularity as the system grows

The allowed-tools skill property plays an important role here anabling tool filtering. It turns tool access into an explicit design decision instead of an accidental side effect of what happened to be registered globally.

Reference implementation

I've started implementation in the new [LangGraph4j] release stream 1.9 currently in active development. The implementation is centered on [`SkilledReactSubAgent`], which turns a markdown skill into both:

a compiled LangGraph4j sub-graph
a Spring AI tool (i.e. ToolCallback)

That means the same component can participate in the graph as an agent and present itself to the parent LLM as a callable tool.

In particular the flow is:

Parse the SKILL.md
Extract name and description from front matter
Optionally filter tools using allowed-tools
Use the markdown body as the sub-agent instructions
Compile the agent
Wrap it into a function tool whose input is a single context field

The important design choice is that the tool definition is derived from the skill metadata, while the agent behavior is derived from the skill content.

Skill Format

The supported skill format is

name:
description: |

    <multi line description>

allowed-tools:

### From Skill to Tool-Backed Agent The conversion happens in `SkilledReactSubAgent.Builder#build(...)`. This is the crucial bridge where: * the skill metadata defines the external API * the skill body defines the internal operating behavior * the allowed tools define the sub-agent execution boundary The resulting agent is then wrapped as a Spring AI function tool. > From the parent agent point of view, this is just another tool. Internally, it is a complete ReAct-capable agent workflow. ## Examples ### Purchase Assistant Agent This is an agent that allow to select a produdct from a reference marketplace and purchase it. Below the simplified component diagram. ![](https://bsorrentino.github.io/bsorrentino/assets/langgraph-java/sub-agents/PurchaseAssistantAgent1.png) ### Marketplace Skill

---
name: agent-marketplace
description: |
    marketplace agent, ask for information about products. This is agent that provides the information on the product marketplace.
    required data are:
    * product name
allowed-tools: searchByProduct
---

## Retrieve product information
We need all information about about the product of interest in particular is mandatory to have
* product name

with such information we have to invoke tool `searchByProduct` and return the result

### Payment Skill

---
name: agent-payment
description: |
    payment agent, this is the agent that provides payment service.
    required data are:
    * Product name
    * Product price
    * Product currency
    * the International Bank Account Number (IBAN) - optional

allowed-tools:
    - submit-payment
    - retrieve-iban
---

## submit a payment for purchasing a specific product
We need all information about purchasing to allow the payment

* Product name
* Product price
* Product price currency
* International Bank Account Number (IBAN)

With such information you must invoke tool `submit-payment` and return the result of the payment transaction plus the IBAN.
If IBAN is not provided invoke tool `retrieve-iban` to retrieve the required IBAN.

Observing the skills above they define three different concerns: * `name`: the tool name exposed to the parent agent * `description`: the tool description shown to the model * `allowed-tools`: the only tools available inside the sub-agent Everything after the front matter becomes the sub-agent system prompt. > Again, this is a strong separation of concerns. The parent agent sees a concise tool contract, while the child agent receives richer operating instructions. ## Finally the code Below a representative code snippet that show how wires two skill-based sub-agents into a parent agent: ```java var subAgentMarketplace = SkilledReactSubAgent.builder() .chatModel(chatModel) .tools(Marketplace.tools()) .build(compileConfig, SkillSource.of(Paths.get("skills/agent-marketplace/"))); var subAgentPayment = SkilledReactSubAgent.builder() .chatModel(chatModel) .tools(Payment.tools()) .build(compileConfig, SkillSource.of(Paths.get("skills/agent-payment/"))); var purchaseAssistantAgent = AgentExecutorEx.builder() .chatModel(chatModel) .tool(subAgentMarketplace) .tool(subAgentPayment) .build(compileConfig); var input = """ search for product 'X'. If found proceed to payment with IBAN US82WEST1234567890123456 to purchase it """; var result = purchaseAssistantAgent.invoke( GraphInput.args( Map.of("messages", new UserMessage(input) )), runnableConfig); ``` This composition is interesting because the purchase agent (the parent) does not need detailed knowledge of: * how product lookup works * how payment submission works * when IBAN retrieval is required Those rules are delegated to the sub agents themselves. That is a simple but good example of behavioral encapsulation. The parent agent only decides to involve marketplace agent to retrieve product and after that to involve payment agent to purchase. This is a very basic but representative example, it is useful because it shows the intended layering: * the user gives a single business request * the parent agent decomposes the work * specialized sub-agents execute their own logic * the final answer comes back through the normal tool-response path > Interesting note that each sub agent, potentially, can relies on different LLM chat model so we can further optimize overall agent execution process Below a more detailed componet diagram generated by [LangGraph4j] itself. ![](https://bsorrentino.github.io/bsorrentino/assets/langgraph-java/sub-agents/PurchaseAssistantAgent.png) From this diagram it is quite clear that the sub agents are nothing but sub-graphs ## Design Advantages This approach has several practical advantages. 1. **Reuse Existing Agent Patterns** There is no need to invent a separate orchestration protocol for sub-agents. A sub-agent is exposed as a tool, so the parent agent can use standard ReAct behavior without extra prompting complexity. 2. **Better Modularity** Each skill owns: * its tool-facing identity * its internal instructions * its allowed tool boundary That makes the system easier to evolve than a single monolithic agent prompt. 3. **Smaller and Cleaner Context** The child agent receives only what it needs. This reduces token usage and lowers the risk that unrelated instructions distort tool choice or task execution. 4. **Safer Capability Scoping** By filtering tools from `allowed-tools`, the framework prevents a child agent from accidentally seeing tools outside its intended domain. 5. **Better Reusability** A skill can be packaged, versioned, and reused across different parent agents. The same marketplace or payment skill can participate in many workflows as long as the tool contract remains stable. ## Tradeoffs and Implementation Considerations This pattern is strong, but it is not free of tradeoffs. 1. **The Parent Must Summarize Well** Because the child receives a single `context` field, the parent agent needs to pass the relevant facts clearly. If critical information is omitted, the child may need extra recovery steps or may fail to act. 2. **Tool Descriptions Matter More** Since the parent sees the child as a tool, the `name` and `description` fields in the skill front matter become part of the routing surface for the LLM. Weak metadata will reduce invocation quality. 3. **Prompt Boundaries Need Discipline** The skill body is effectively the child system prompt. If it is vague, contradictory, or overloaded, the benefits of modularity disappear. Skills need to stay focused. 4. **Observability Is Important** Nested agents can make execution harder to inspect if tracing is weak. LangGraph4j's graph structure and step streaming help here, but production systems should still invest in logging and traceability. ## Why LangGraph4j Fits This Well [LangGraph4j] is a good fit for this pattern because it already models agent workflows as explicit graphs and integrates naturally with Spring AI tool abstractions. That matters for two reasons: * the sub-agent is not just prompt composition; it is a compiled graph with state and execution hooks * the parent integration remains ergonomic because Spring AI already treats capabilities as tools * [LangGraph4j] support interruptions in subgraph enabling **Human In The Loop** also when involving sub agents So the implementation is not forcing two incompatible ideas together. It is aligning: * LangGraph4j graph execution * Spring AI tool calling * markdown-defined skills into a single reusable agent-building pattern. ## Conclusion Turning a skill into a sub-agent is a small change with a large impact. It lets us: * preserve the strengths of the ReAct loop * delegate specialized behavior cleanly * reduce context size * constrain tool access per domain * build multi-agent systems out of reusable skill modules The idea is implemented in a compact and pragmatic way: a `SKILL.md` file becomes the source of both the sub-agent prompt and the tool contract exposed to the parent agent. For Java teams building agentic applications with Spring AI and LangGraph4j, this is a practical pattern for moving from a single large agent toward a modular multi-agent design without abandoning the tool semantics that current LLMs already handle well. The implementation is in progress on release `1.9-SNAPSHOT` in develop branch of [LangGraph4j] repository but the first result are very promising. Hope this could help and encourage usage of [LangGraph4j] for your next Agentic Workflow. Checkout project, try it and let me know your feedback and... happy AI coding! [LangGraph4j]: https://github.com/langgraph4j/langgraph4j [Spring AI]: https://spring.io/projects/spring-ai

Defending the JVM in the Agentic Era

Wed, 29 Apr 2026 21:03:53 +0000

The current AI discourse is obsessed with 'Software Hope' — the belief that probabilistic wrappers can accurately govern the world's most critical enterprise logic.

They cannot.

For those of us in the engine room, the industrial floor still runs on the JVM. The requirement for deterministic, high-throughput execution has not changed. If anything, the arrival of autonomous agents has made the 'Iron Truth' of Java more critical than ever.

Transformation is not about a code rewrite. It is about a hard handshake between legacy logic and agentic intent. To survive the Agentic Era, enterprise architecture must define exactly how the hardware fuses with the JVM. We call this the welding seam.

The Identity Fallacy

We are currently repeating the most expensive mistake in systems architecture by governing autonomous agents using security models designed for human browsers. We assume a valid IAM role or JWT equals safe intent.

It does not. Identity is an entry requirement; authority is a physical constraint. A hallucinating model with valid production credentials is just an automated insider threat.

The Sovereign Witness

Governance should not live in the Java code itself, nor should it rely on soft API gateways. It must live upstream, inside a 'Sovereign Vault' — a Trusted Execution Environment (TEE) like Intel SGX or TDX.

We are moving toward the Agentic Strangler pattern. We wrap the Java monolith in a hardware-enforced façade. Here is exactly how the data crosses the boundary using our architectural primitives.

The Execution Primitives

Instead of relying on middleware to guess intent, we manage the physical state of the AI model before granting the right to act.

Sankalpa — The cryptographic vow binding the agent's identity, intent, and time.
Sakshi — The decoupled Hardware Witness operating securely inside the TEE airlock. It mathematically evaluates the Sankalpa against the Sovereign Mandate and the real-time empirical state of the model.
Pramana — The Admissible Proof generated by the witness, cryptographically sealing the real-time empirical state.
Mudra — The single-use execution seal, typically manifested as an ephemeral mTLS certificate.

Deterministic Execution

The Java monolith is configured to physically reject any API call that lacks the Mudra. If the hardware witness detects constraint decay or unauthorized intent, the TEE physically starves the payload. The instruction never reaches the JVM.

When you align the reasoning truth with a hardware witness, you move past the failure points of standard RBAC. You get an integration layer that does not just connect — it physically enforces.

Java is not the relic. It is the substrate.

Stop auditing the vibes of the model. Secure the silicon that runs the core.

Stop Rewriting CI/CD: Reusable GitHub Actions for Maven Projects

Tue, 28 Apr 2026 01:40:16 +0000

Stop Rewriting CI/CD Pipelines for Every Maven Project

If you’ve worked on multiple Java projects, you’ve probably run into this:

Every repository has its own version of a CI/CD pipeline.

Slightly different YAML.
Slightly different setup steps.
Slightly different ways of doing the same thing.

And somehow… none of them are reusable.

The Real Problem

It’s not that CI/CD is hard.

It’s that it’s repetitive.

You end up doing the same things over and over:

Set up Java
Cache Maven dependencies
Run tests
Build artifacts
Handle versioning
Publish or release

Then copy that workflow into another repo…
…and tweak it just enough to break consistency.

This is exactly the kind of problem automation should solve — yet we keep duplicating it.

A Different Approach

Instead of treating each pipeline as a one-off YAML file, I started thinking:

What if CI/CD steps were modular and reusable — just like code?

That’s where NERV-Actions came from.

https://github.com/your-repo-link

What NERV-Actions Is

NERV-Actions is a collection of reusable GitHub Actions designed for Maven-based projects.

The idea is simple:

Break CI/CD into small, composable actions
Reuse them across repositories
Keep pipelines consistent without rewriting everything

Instead of this:

# repeated in every repo
- uses: actions/setup-java@v4
- run: mvn clean install

You plug in reusable building blocks that already handle those concerns.

Why This Matters

Reusable workflows aren’t just about convenience — they solve real scaling problems.

When you define things once and reuse them:

You reduce duplication
You avoid inconsistencies across repos
You make updates easier (change once, apply everywhere)
You spend less time debugging YAML

Design Philosophy

I didn’t try to build a one-size-fits-all pipeline.

Instead, NERV-Actions focuses on:

Composable units → mix only what you need
Sensible defaults → minimal setup required
Consistency → same patterns across projects
Extensibility → override when necessary

It’s closer to building blocks than a framework.

Example Use Case

For a typical Maven project, your pipeline usually boils down to:

Run tests
Build artifacts
Publish packages
Create releases

With reusable actions, you don’t redefine these steps every time — you just assemble them.

Why Not Just Copy-Paste?

Because copy-paste doesn’t scale.

It works for 2–3 repos.
It breaks down at 10+.

Suddenly:

Fixes don’t propagate
Pipelines drift
Debugging becomes inconsistent

Reusable actions solve that by centralizing the logic.

Still Evolving

This isn’t meant to be a perfect CI/CD solution.

It’s a practical attempt to reduce the friction I kept running into across projects.

If you’re dealing with the same repetition in GitHub Actions, this might be useful:

https://github.com/czetsuyatech/nerv-actions

Curious About Your Setup

Are you:

copying workflows between repos?
using reusable workflows heavily?
or building your own internal action libraries?

Would be interesting to hear how others are handling this.

nerv-audit

Sat, 18 Apr 2026 04:52:03 +0000

We needed an audit trail Envers couldn’t handle — so I built one

“Who changed this record?”
“What was the previous value?”
“When did it happen?”

Simple questions… until you actually need answers in production.

The problem we kept running into

In one of our systems, audit logs weren’t just “nice to have” — they were critical.

We needed:

Field-level change tracking
Historical queries (point-in-time views)
Reliable audit trails across services

So naturally, we tried Hibernate Envers.

At first, it worked.

Until it didn’t.

Where things started breaking

As the system grew, we hit real limitations:

Querying audit history became painful
Custom audit logic was hard to extend
Cross-service audit consistency was messy
Performance started becoming a concern

We weren’t just storing audit logs anymore —
we needed to use them as a first-class feature.

That’s where Envers started to feel like a constraint.

The turning point

At some point, we had two options:

Keep patching around the limitations
Build something that actually fits our needs

We chose the second.

What we built

We created nerv-audit — a modular audit framework designed for real-world backend systems.

Instead of treating auditing as a side-effect, we designed it as a core part of the architecture.

Key ideas:

Structured audit work units (not just snapshots)
Flexible query model for history retrieval
Clean separation between capture, storage, and querying
Extensible by design

A quick example

Instead of digging through raw audit tables, you can query changes like this:

AuditQuery query = AuditQuery.builder()
    .entity("User")
    .field("email")
    .changed()
    .build();

List<AuditResult> results = auditService.execute(query);

Now you’re not just storing history —
you’re actually asking questions from it.

What I learned building this

A few things became very clear:

Audit logs become product features faster than expected
If querying is painful, the audit system is incomplete
“Just use Envers” works… until scale and complexity kick in
Designing audit as a domain, not a utility, changes everything

⚠️ About the project

The project is structured in modules:

nerv-audit-core → full engine (commercial)
nerv-audit-lite / examples → publicly available

I decided to keep the core commercial, but still share:

Public modules
Examples
Integration ideas

Explore it here

If you’re dealing with similar problems, you might find this useful:

https://github.com/czetsuyatech/nerv-audit

Final thought

Most systems don’t think about audit logs until something breaks.

By then, it’s already too late.

If your system will ever need to answer:

“What changed, and why?”

…it’s worth designing for it early.

Stop Rebuilding the Same Spring Boot Setup Every Time

Tue, 14 Apr 2026 04:40:51 +0000

If you’ve built more than one Java backend, you’ve probably done this:

setup auth again
configure roles and permissions
handle multi-tenancy
wire up basic APIs
fix the same production issues later

And suddenly a week is gone.

I’m currently working on BuildBaseKit, focused on solving exactly this.

The idea is simple:

give developers a production-ready Spring Boot starting point
not just demos, but something you can actually build on

Right now I’m validating it with real use cases like:

file servers
Discord bots
internal tools

Curious to hear from others here:

What’s the one thing you always end up rebuilding in every backend?

Coder Legion - Recent posts tagged java

Reliable Event-Driven Architecture in Spring Boot: Outbox, Inbox, Retries, and Idempotency

1. The dual-write problem

The transactional outbox

2. Why the outbox still needs idempotency

3. The transactional inbox

A subtle but important case

4. Retries are a lifecycle, not just an annotation

5. Multi-instance processing changes everything

6. Exactly-once is not an end-to-end promise

7. Observability is part of reliability

8. Putting these patterns together

9. Why I built NERV Event

Final thoughts

Oracle Plans Post-Quantum TLS for Java 8 and 11 in Late 2027, and Wants Testers Now

Polar Bear Cache: Local Caching Without Repeated Remote Calls

The Problem: Faster Reads, Distributed Cache Invalidation

The Design: Local Cache + Event-Driven Invalidation

When Does This Approach Make Sense?

Why “Polar Bear”?

I'd Love to Hear Your Thoughts

Java #Spring #Microservices #Caching #DistributedSystems #OpenSource

Sync Session: Rethinking Session Management in Microservices

Sync Session: Rethinking Session Management in Microservices

The Challenge: Security vs. Performance

The Design

What Does This Approach Support?

Performance Reference

Consistency and Security Trade-offs

A Design Principle Worth Discussing

LangGraph4j Annotations: Organize Graph Behavior with Action Catalogs

From graph lambdas to action catalogs

What an Action Catalog contains

An example

Define the catalog

Resolve the catalog and connect the graph

Reuse an action under another node ID

Other supported method shapes

Organize catalogs around related behavior

Common mistakes to catch early

Conclusion

Why Does a Backend API Become Slow, and How Can We Fix It?

The Problem: An API That Takes Too Long to Respond

Step 1: Measure the API Performance

Step 2: Improve Database Queries

Step 3: Avoid Unnecessary Database Calls

Step 4: Return Only the Data the Client Needs

Step 5: Use Caching When It Makes Sense

Step 6: Test the Changes

What I Learned From This Approach

Final Thoughts

The Order Was Saved. The Kafka Event Might Never Arrive.

The four lines that made me stop

Where the gap opens

First, choose what a successful response means

The transactional outbox fix

Two IDs solve two different retry problems

The test I would add before calling this production-ready

What I would monitor

The takeaway

References

Most Developers Are Building AI Agents Wrong: MCP Is the Missing Contract

An AI agent is more than a chatbot

The tool boundary is the real architecture

Why MCP matters

A safer agent flow

MCP and Spring Boot

Read tools and write tools are not equal

The biggest MCP security risks

Excessive permissions

Prompt injection

Confused deputy problems

Tool poisoning

Data leakage

Observability is not optional

Start with narrow agents

The future of agents is controlled autonomy

Final checklist

A production agent architecture

Reference