czetsuyatech

Handling Long-Running Transactions in Spring Boot with NERV Event

2026-09-16T10:12:40.520+08:00

What happens when an event-driven application needs to perform an operation that can take 30 minutes?

This question came up while integrating NERV Event into a realistic payment workflow.

A payment request arrives. We need to persist it, submit it to a third-party payment system, wait for validation, update our local payment state, and eventually publish the result.

The complication is that the third-party system may take 30 minutes — or potentially much longer — before producing a final result.

At first, this sounds like a transaction-management problem:

Which Spring transaction propagation should we use for the 30-minute operation?

But that's not really the right question.

The better question is:

How do we make a 30-minute business process durable without keeping a database transaction, Java thread, or event handler alive for 30 minutes?

The answer changes the architecture considerably.

A 30-minute payment isn't a 30-minute transaction.

It's a durable workflow containing several very short transactions.

1. Why a 30-Minute Database Transaction Is the Wrong Model

Consider the naive implementation:

@Transactional
public void processPayment(PaymentRequest request) {

    Payment payment = repository.save(...);

    PaymentResult result =
        paymentGateway.validate(request);

    payment.complete(result);

    eventPublisher.publish(...);
}

If paymentGateway.validate() takes 30 minutes, the transaction potentially spans the entire external operation:

BEGIN TRANSACTION
      |
      +-- INSERT payment
      |
      +-- Call payment gateway
      |       |
      |       +-- wait...
      |       +-- wait...
      |       +-- 30 minutes
      |
      +-- UPDATE payment
      |
      +-- INSERT Outbox event
      |
COMMIT

This can create several operational problems:

long-held database connections;
long-lived locks;
connection-pool pressure;
larger contention windows;
transaction timeouts;
more complicated failure recovery;
and poor scalability under concurrent workloads.

More importantly, the transaction does not give us the guarantee we might think it does.

Our local database cannot roll back an operation that already succeeded inside an external payment system.

A Spring database transaction does not turn an external HTTP request into part of the same ACID transaction.

So holding the transaction open for 30 minutes gives us significant cost without providing distributed atomicity.

2. The First Improvement: Short Transactions Around External Work

A better first step is to separate local database work from the external operation.

SHORT TX
+--------------------------+
| Create payment           |
| status = VALIDATING      |
|                          |
| COMMIT                   |
+--------------------------+
             |
             v
       NO TRANSACTION
+--------------------------+
| Third-party validation   |
|                          |
| 30+ minutes              |
+--------------------------+
             |
             v
SHORT TX
+--------------------------+
| Update payment           |
| SUCCESS / FAILED         |
|                          |
| Insert Outbox event      |
|                          |
| COMMIT                   |
+--------------------------+

In Spring, an orchestrator could explicitly refuse to participate in a transaction:

@Service
@RequiredArgsConstructor
public class PaymentService {

    private final PaymentTransactionService txService;
    private final PaymentGatewayClient gateway;

    @Transactional(
        propagation = Propagation.NEVER
    )
    public void processPayment(
        PaymentRequest request) {

        Long paymentId =
            txService.create(request);

        PaymentValidationResult result =
            gateway.validate(
                paymentId,
                request);

        txService.complete(
            paymentId,
            result);
    }
}

The database operations can then use short independent transactions:

@Transactional(
    propagation = Propagation.REQUIRES_NEW
)
public Long create(PaymentRequest request) {

    Payment payment = new Payment();

    payment.setStatus(
        PaymentStatus.VALIDATING);

    return repository
        .save(payment)
        .getId();
}

while the external integration explicitly avoids transaction participation:

@Transactional(
    propagation = Propagation.NOT_SUPPORTED
)
public PaymentValidationResult validate(...) {

    return paymentGatewayApi.validate(...);
}

This gives us a useful transaction policy:

Component	Propagation	Purpose
Long-running orchestrator	`NEVER`	Prevent the workflow from inheriting a transaction
Database operation	`REQUIRES_NEW`	Short, isolated database transaction
External gateway	`NOT_SUPPORTED`	Keep remote I/O outside database transactions

This solves the long database transaction.

But for a 30-minute operation, it still isn't enough.

3. The Reliability Gap

Suppose the payment workflow starts from a PaymentRequested event consumed through NERV Event.

NERV Event 2.1 atomically commits local Inbox handler effects together with the Inbox transition to PROCESSED.

We might therefore implement:

@NervEventHandler
public void handle(PaymentRequested event) {

    payment.setStatus(
        PaymentStatus.VALIDATION_PENDING);
}

NERV then commits:

BEGIN TRANSACTION

    payment = VALIDATION_PENDING

    Inbox(PaymentRequested)
        = PROCESSED

COMMIT

So far, this is correct.

The problem appears afterward.

Suppose we start a detached worker:

Inbox = PROCESSED
       |
       v
Gateway validation
       |
       | 30 minutes
       v
Gateway = SUCCESS
       |
       v
completePayment()
       |
       X
Database failure

We now have:

Inbox
    = PROCESSED

Local Payment
    = VALIDATION_PENDING

Payment Gateway
    = SUCCESS

Outbox
    = NOTHING

And this is the important part:

NERV Inbox will not retry PaymentRequested.

It shouldn't.

The original event was already processed successfully.

The problem is that we allowed the transition from Inbox processing to long-running work to become an in-memory handoff.

4. Every Important Handoff Must Be Durable

The Inbox handler should not merely update:

payment = VALIDATION_PENDING

It should also durably schedule the next step before the Inbox event becomes PROCESSED.

NERV Event already gives us a natural mechanism for this:

the transactional Outbox.

The Inbox transaction becomes:

BEGIN TRANSACTION

    payment =
        VALIDATION_PENDING

          +

    Outbox =
        StartPaymentValidation

          +

    Inbox(PaymentRequested) =
        PROCESSED

COMMIT

Now we have a much stronger invariant:

PaymentRequested can never become PROCESSED without durably scheduling the next step of the payment workflow.

If the transaction fails, all three changes roll back.

NERV can retry the Inbox event.

If the transaction succeeds, the next workflow step exists durably in the Outbox.

5. Publishing the Next Workflow Step

Conceptually, our Inbox handler now looks like:

@NervEventHandler
public void handle(PaymentRequested event) {

    Payment payment =
        repository.findById(
            event.paymentId())
            .orElseThrow();

    payment.setStatus(
        PaymentStatus.VALIDATION_PENDING);

    eventPublisher.publish(
        new EventPublication(
            "START_PAYMENT_VALIDATION",
            event.paymentId().toString(),
            event.paymentId().toString()
        )
    );
}

Because the handler executes inside the NERV Inbox transaction, the business-state change and Outbox insertion participate in the same local transaction as Inbox completion.

The resulting flow becomes:

PaymentRequested
       |
       v
+------------------------------+
| NERV Inbox Transaction       |
|                              |
| Payment                      |
|   -> VALIDATION_PENDING       |
|                              |
| Outbox                       |
|   + StartPaymentValidation   |
|                              |
| Inbox                        |
|   -> PROCESSED                |
+------------------------------+
       |
       v
     COMMIT
       |
       v
 NERV Outbox Dispatcher
       |
       v
StartPaymentValidation

We've now made the transition to the next workflow step durable.

6. But Don't Move the 30-Minute Transaction to Another Consumer

At this point it is tempting to create another NERV Inbox handler:

@NervEventHandler
public void validate(
    StartPaymentValidation event) {

    paymentGateway.validate(event);

    // potentially 30+ minutes
}

But that recreates the original problem somewhere else.

The NERV Inbox transaction would remain active while the handler waits for the payment gateway.

We haven't solved the long-running transaction.

We've only moved it.

Long-running external work should not execute inside a transactional event handler.

7. Treat the Payment Gateway as an Asynchronous Process

If a payment provider genuinely takes 30 minutes to determine a result, the integration should ideally be modeled asynchronously.

Instead of:

POST payment
     |
     | block for 30 minutes
     |
     v
return result

prefer:

Submit Validation
       |
       v
Gateway accepts request
       |
       v
Persist external reference
       |
       v
Return

The provider processes the payment independently.

The result arrives later through:

a webhook;
a callback;
a status API;
or durable polling.

Now no application thread needs to wait for 30 minutes.

8. Callback-Based Payment Completion

If the gateway supports callbacks, the architecture becomes:

PaymentRequested
       |
       v
NERV Inbox
       |
       | SHORT TX
       v
VALIDATION_PENDING
       +
Outbox StartValidation
       +
Inbox PROCESSED
       |
       v
     COMMIT
       |
       v
NERV Outbox
       |
       v
Validation Worker
       |
       | NO LONG DB TX
       v
Submit to Gateway
       |
       v
Gateway Processing
       |
       | 30+ minutes
       v
Webhook / Callback
       |
       v
SHORT TRANSACTION
       |
       +-- Payment = SUCCESS / FAILED
       |
       +-- Outbox = PaymentCompleted
       |
       v
     COMMIT
       |
       v
NERV Outbox
       |
       v
Kafka / SQS

The 30-minute period exists entirely outside a local database transaction.

And more importantly, the application does not need to remain alive for those 30 minutes.

9. What If the Gateway Doesn't Support Callbacks?

Then we can use durable polling.

After submitting the payment, persist:

payment.status =
    VALIDATION_PENDING

gatewayRequestId =
    ABC123

nextCheckAt =
    2026-09-16T10:30:00Z

A worker later finds records whose nextCheckAt has arrived:

VALIDATION_PENDING
       |
       v
nextCheckAt reached
       |
       v
GET gateway/status/ABC123
       |
       +-- PENDING
       |      |
       |      v
       |  update nextCheckAt
       |
       +-- SUCCESS
       |      |
       |      v
       |  complete payment
       |
       +-- FAILED
              |
              v
          fail payment

Each database update is a short transaction.

No thread sleeps for 30 minutes.

No database transaction waits for 30 minutes.

And application restarts do not destroy the workflow because the current state is persisted.

10. The Hardest Failure Window

Now consider the most interesting failure:

Payment Gateway
       |
       v
SUCCESS
       |
       v
Local completion TX
       |
       +-- payment = SUCCESS
       |
       +-- Outbox PaymentCompleted
       |
       X
Database failure
       |
       v
ROLLBACK

Locally, the transaction correctly rolls everything back:

Payment
    = VALIDATION_PENDING

Outbox
    = NOTHING

But the external system already says:

Payment Gateway
    = SUCCESS

Our database transaction cannot undo that.

This is the fundamental consistency boundary between our application and the external payment provider.

11. Idempotency and Reconciliation Close the Gap

The external payment request should use a stable idempotency identifier whenever the provider supports one.

For example:

paymentId
    |
    v
Idempotency-Key
    |
    v
Payment Gateway

We should also retain the provider's external transaction reference:

Payment
-------------------------
id
status
idempotencyKey
gatewayTransactionId
validationStartedAt
validationCompletedAt
nextCheckAt

If our local completion transaction fails, we don't blindly create another payment.

Instead, we reconcile:

Local Payment
    = VALIDATION_PENDING
          |
          v
Query Gateway
using gatewayTransactionId
          |
          v
Gateway says SUCCESS
          |
          v
REQUIRES_NEW
+---------------------------+
| payment = SUCCESS         |
|                           |
| gatewayRef = ABC123       |
|                           |
| Outbox                    |
|   + PaymentCompleted      |
|                           |
| COMMIT                    |
+---------------------------+

If that transaction fails again, reconciliation can retry again.

The external payment is not duplicated because we're referring to the same logical operation.

12. NERV Event Handles the Local Atomicity Boundary

Once we know the external result, NERV Event gives us a strong local guarantee.

The final transaction contains:

BEGIN TRANSACTION

    payment.status =
        SUCCESS

          +

    payment.gatewayRef =
        ABC123

          +

    Outbox =
        PaymentCompleted

COMMIT

This means we cannot commit:

Payment = SUCCESS

without also durably recording:

PaymentCompleted

for eventual delivery.

If Kafka or SQS is unavailable afterward, that is no longer the payment transaction's problem.

The Outbox record already exists.

NERV Event can retry delivery independently.

Payment SUCCESS
       |
       v
Outbox PaymentCompleted
       |
       | broker unavailable
       X
       |
       | retry
       | retry
       v
Kafka / SQS

13. Three Different Failure Boundaries, Three Different Mechanisms

This payment workflow reveals an important architectural principle.

There isn't one reliability mechanism that solves every failure.

There are several boundaries:

Boundary	Failure	Mechanism
Inbox + local handler effects	Handler or DB failure	NERV Inbox transaction + retry
Workflow step handoff	Application crashes after Inbox completion	Transactional Outbox
Application + payment gateway	Unknown or externally committed result	Idempotency + reconciliation
Payment state + completion event	Local DB failure	Database transaction + NERV Outbox
Outbox + Kafka/SQS	Broker unavailable	NERV durable dispatch + retry

Trying to solve all of these with one giant transaction is both unrealistic and unnecessary.

14. The Complete Durable Payment Workflow

Putting everything together gives us:

PaymentRequested
       |
       v
+-------------------------------+
| NERV Inbox TX                 |
|                               |
| Payment                       |
|   -> VALIDATION_PENDING        |
|                               |
| Outbox                        |
|   + StartPaymentValidation    |
|                               |
| Inbox                         |
|   -> PROCESSED                 |
+-------------------------------+
       |
       v
     COMMIT
       |
       v
+-------------------------------+
| NERV Outbox                   |
|                               |
| durable delivery              |
+-------------------------------+
       |
       v
StartPaymentValidation
       |
       v
+-------------------------------+
| Submit to Payment Gateway     |
|                               |
| idempotencyKey = paymentId    |
|                               |
| NO LONG DB TRANSACTION        |
+-------------------------------+
       |
       v
 Gateway processing
       |
       | 30+ minutes
       |
       +----------------------+
       |                      |
       v                      v
    callback             durable polling
       |                      |
       +----------+-----------+
                  |
                  v
          Gateway Result
                  |
                  v
+--------------------------------+
| SHORT COMPLETION TX            |
|                                |
| Payment = SUCCESS / FAILED     |
|                                |
| Save gateway reference         |
|                                |
| Outbox                         |
|   + PaymentCompleted           |
+--------------------------------+
                  |
                  v
                COMMIT
                  |
                  v
+--------------------------------+
| NERV Outbox                    |
|                                |
| Kafka / SQS                    |
+--------------------------------+

Notice what is missing from this architecture:

There is no 30-minute database transaction.

There isn't even necessarily a 30-minute Java method.

Instead, we have a sequence of durable state transitions.

15. Transaction Boundaries Should Follow Consistency Boundaries

This is the broader lesson.

A Java method might represent one business operation:

processPayment()

but that does not mean one database transaction should span the entire business operation.

The transaction boundary should follow what the local database can actually guarantee atomically.

For example:

Local state
    +
Outbox event
    =
one transaction

and:

Inbox completion
    +
local handler effects
    +
next durable workflow step
    =
one transaction

But:

Local database
    +
30-minute remote operation

is not one useful ACID boundary.

Transaction boundaries should follow consistency boundaries, not method boundaries.

16. This Pattern Isn't Just for Payments

The same architecture applies whenever external work is slow, unpredictable, or asynchronous:

payment authorization;
fraud analysis;
identity verification;
document processing;
AI inference;
large file processing;
third-party provisioning;
shipping operations;
external approval workflows;
and long-running integrations.

The common structure is:

SHORT TX
    |
    v
DURABLE STATE
    |
    v
DURABLE HANDOFF
    |
    v
EXTERNAL WORK
    |
    v
RECONCILIATION
    |
    v
SHORT TX
    |
    v
DURABLE EVENT

The Bigger Lesson

When we talk about reliable event-driven systems, it's easy to focus entirely on whether messages are delivered.

But reliable delivery is only part of the problem.

We also need to ask:

What happens if the application crashes between workflow steps?
What happens if the external operation succeeds but our database fails?
What happens if we don't know whether the external operation succeeded?
What happens if Kafka is unavailable after the payment commits?
What happens if the application restarts during the 30-minute wait?

A reliable design needs an answer for each boundary.

Short Transactions
        +
Durable State
        +
Durable Handoffs
        +
NERV Inbox / Outbox
        +
External Idempotency
        +
Reconciliation
        =
Reliable Long-Running Workflows

And that brings us back to the central idea:

A 30-minute payment isn't a 30-minute transaction. It's a durable workflow composed of several very short transactions.

NERV Event doesn't try to make a remote payment provider part of your local database transaction.

Instead, it helps make the boundaries where strong guarantees are possible durable, atomic, retryable, and observable.

For real-world distributed systems, that's the guarantee that matters.

Try NERV Event

NERV Event is an open-source Spring Boot library for building reliable event-driven applications using transactional Outbox and Inbox patterns.

It provides infrastructure for:

transactional Outbox publishing;
durable Inbox consumption;
atomic Inbox handler processing;
idempotent event processing;
automatic retries and failure tracking;
multi-instance-safe claiming;
aggregate-aware ordering;
Kafka integration;
Amazon SQS integration;
scheduler resilience;
and operational inspection.

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

If you're building long-running workflows with Spring Boot, I'd be interested to hear how you're handling durable handoffs, external idempotency, and reconciliation — particularly for payments and other slow third-party operations.

If NERV Event is useful to you, consider starring the repository. Feedback, issues, and contributions are always welcome.

NERV — Next-Generation Engineering for Runtime Velocity

Production-ready infrastructure for Java engineers building reliable enterprise systems.

Hardening Event-Driven Systems: Lessons from NERV Event 2.1

2026-09-14T12:04:25.000+08:00

Building an event-driven library is one thing. Putting it inside a realistic application is another.

While integrating NERV Event into a full payment showcase, several edge cases surfaced that were easy to overlook when looking at the Outbox and Inbox patterns individually.

None of them changed the fundamental architecture. The Outbox still provides durable publication. The Inbox still provides durable consumption, retries, and idempotency.

But they exposed something more important: production reliability lives in the boundaries between those mechanisms.

Those findings became the focus of NERV Event 2.1.

This release strengthens four areas:

atomic Inbox processing;
fail-fast Outbox configuration;
aggregate-aware event ordering;
runtime portability for polling.

Let's look at why each one matters — and what these changes taught us about building reliable event-driven systems.

1. The Inbox Transaction Boundary Matters

Consider a consumer processing an event:

Inbox Event
    |
    v
Handler
    |
    +--> Update local database
    |
    v
Mark Inbox PROCESSED

At first glance, this looks correct.

But there is a dangerous failure window if the handler's database transaction commits independently from the Inbox state transition.

Imagine the following sequence:

1. Claim Inbox event
2. Execute handler
3. Commit handler database changes
4. Application crashes
5. Inbox record is still not PROCESSED
6. Event is retried
7. Handler executes again

The Inbox correctly believes the event still requires processing.

The business database, however, has already been changed.

The result can be duplicate local effects.

The NERV Event 2.1 Transaction Model

NERV Event 2.1 closes this failure window.

Local handler database effects and the Inbox transition to PROCESSED now execute within the same transaction.

Claim event
    |
    v
BEGIN TRANSACTION
    |
    +--> Execute handler
    |
    +--> Update business data
    |
    +--> Mark Inbox PROCESSED
    |
COMMIT

If anything fails:

BEGIN TRANSACTION
    |
    +--> Execute handler
    |
    +--> FAILURE
    |
ROLLBACK

Both the business changes and Inbox completion are rolled back.

Only after that rollback does NERV Event record the retry or failure metadata through a separate transactional boundary.

This gives us an important invariant:

Local handler effects and successful Inbox completion either commit together or do not commit at all.

What This Does Not Solve

This guarantee applies to transactional work performed against the local database.

It cannot magically make an external system part of that database transaction.

If a handler performs:

Inbox Handler
    |
    +--> Local PostgreSQL update
    |
    +--> External payment API

the HTTP request cannot simply be rolled back because the database transaction failed afterward.

External side effects therefore still require idempotency.

This distinction is important:

Atomic transactions protect local effects. Idempotency protects effects outside the transaction boundary.

Reliable consumer processing needs both.

2. Silent Outbox Misconfiguration Is a Reliability Problem

Another issue appeared while configuring the showcase.

Imagine an application that can successfully write events into its Outbox, but has no functional dispatcher capable of delivering them.

The application starts normally.

Business transactions succeed.

Outbox records accumulate.

And nothing gets published.

This is one of the more dangerous infrastructure failures because the system can appear healthy while event delivery is effectively disabled.

Fail Fast Instead

NERV Event 2.1 validates active Outbox publication during application startup.

Publication is considered active when the application indicates publishing intent through mechanisms such as:

nerv.event.outbox.enabled=true

RetryPolicy

custom OutboxDispatcher

configured outbound destinations

If publication is active but there is no functional dispatcher, startup fails with an actionable configuration error.

That changes the failure model from:

Production traffic
    |
    v
Outbox grows
    |
    v
Events are never delivered
    |
    v
Someone eventually notices

into:

Application startup
    |
    v
Configuration validation
    |
    v
FAIL FAST

For infrastructure configuration, finding the problem before production traffic reaches the application is considerably safer than silently accepting a non-functional configuration.

What About Consumer-Only Applications?

Fail-fast validation introduced another design question.

Some applications use NERV Event only for Inbox consumption.

Requiring every consumer-only application to add:

nerv.event.outbox.enabled=false

would make an otherwise backward-compatible upgrade unnecessarily disruptive.

NERV Event 2.1 therefore distinguishes between having the library installed and actually expressing publication intent.

Consumer-only applications continue to start without additional configuration.

Explicitly disabling the Outbox remains available, but isn't required merely because NERV Event is present.

The result is both:

backward compatibility and fail-fast publication safety.

3. Kafka Keys Alone Don't Guarantee Application-Level Ordering

The largest new capability in NERV Event 2.1 is aggregate-aware ordering.

Consider an Order aggregate producing:

OrderCreated
PaymentAuthorized
OrderConfirmed

These events have a natural sequence.

But with multiple Outbox workers, retrieving records in database order alone does not guarantee that they will actually reach the broker in that same order.

Worker A might claim:

OrderCreated

while Worker B claims:

PaymentAuthorized

If Worker B publishes first, downstream consumers could observe:

PaymentAuthorized
OrderCreated

The database rows were ordered correctly.

The actual dispatch was not.

"Just Use a Kafka Key"

Kafka developers will immediately recognize one part of the solution:

Events belonging to the same aggregate should use the same Kafka record key.

That's necessary.

But it isn't sufficient.

Kafka can preserve ordering within a partition, but the Outbox dispatcher still controls the order in which records are handed to Kafka.

If two concurrent workers effectively perform:

send(event2)
send(event1)

using the same Kafka key doesn't magically reverse those calls.

The ordering guarantee therefore has to begin before the broker.

4. Introducing `orderingKey`

NERV Event 2.1 introduces an optional orderingKey throughout the publication pipeline.

Conceptually:

EventPublication.builder()
    .type("ORDER_UPDATED")
    .payload(payload)
    .orderingKey(orderId)
    .build();

The ordering identity travels through the full pipeline:

Application
    |
    v
EventPublication
    |
    v
Outbox Persistence
    |
    v
Claiming
    |
    v
Dispatcher
    |
    v
Transport
    |
    +--> Kafka
    |
    +--> SQS

The ordering key is persisted in the Outbox so retries continue using the same ordering identity.

It is deliberately optional.

Existing applications do not need to provide one, and unkeyed events retain their existing concurrent dispatch behavior.

5. Ordering Starts in the Outbox

The interesting part isn't adding another property to the publication API.

The important change is how Outbox records are claimed.

NERV Event now ensures that events sharing the same ordering key are claimed and dispatched sequentially.

Conceptually:

Order A / Event 1 --┐
Order A / Event 2 --+-- sequential
Order A / Event 3 --┘

Order B / Event 1 --┐
Order B / Event 2 --+-- sequential
Order B / Event 3 --┘

But Order A and Order B remain independent:

             +-- Order A events -- sequential
Workers -----+
             +-- Order B events -- sequential

This distinction matters.

We could preserve ordering by forcing everything through a single global worker:

ALL EVENTS
    |
    v
single queue
    |
    v
single worker

But that would sacrifice much of the scalability gained through concurrent Outbox dispatch.

Instead, serialization occurs at the ordering-key level.

Events belonging to the same aggregate remain ordered while unrelated aggregates can continue progressing concurrently.

This protection also applies across batches and application replicas.

Adding more NERV Event instances should increase concurrency between independent ordering keys without allowing two instances to reorder events belonging to the same key.

6. Transport-Specific Ordering

Once the Outbox establishes the ordering boundary, each transport can map that identity onto the guarantees offered by the underlying broker.

Kafka

For Kafka, orderingKey becomes the Kafka record key.

orderingKey
    |
    v
Kafka record key
    |
    v
partition selection

Events sharing an ordering key therefore follow Kafka's key and partition ordering semantics.

Amazon SQS FIFO

For SQS FIFO queues, the ordering key becomes:

MessageGroupId = orderingKey

NERV Event also uses:

MessageDeduplicationId = eventId

This maps aggregate ordering naturally onto SQS FIFO message groups while retaining event-level deduplication identity.

Amazon SQS Standard

SQS Standard queues do not provide FIFO ordering guarantees.

NERV Event therefore does not pretend otherwise.

An event may still carry an ordering key at the publication level, but choosing SQS Standard does not transform the underlying transport into an ordered queue.

A useful abstraction should provide stronger guarantees where possible without hiding the limitations of the infrastructure underneath it.

7. Minimal Runtime Images Expose Hidden Dependencies

The showcase also uncovered a smaller issue with an important lesson.

Polling previously relied on a random-generator implementation whose provider was not guaranteed to be available in minimal Java runtime images.

On a normal development JDK, this is easy to miss.

Inside a deliberately reduced production runtime, it becomes a deployment failure.

For NERV Event 2.1, that dependency has been replaced with:

ThreadLocalRandom

from java.base.

For polling jitter and backoff behavior, requiring an additional random provider was adding deployment complexity without providing a meaningful architectural benefit.

Using a standard Java runtime facility removes that unnecessary dependency and makes NERV Event friendlier to minimal runtime images.

There is a broader lesson here:

The deployment environment is part of the architecture.

A library that works perfectly inside a developer's full JDK can still contain assumptions that surface only once the application is packaged for production.

8. Database Compatibility

Supporting durable aggregate ordering requires preserving the ordering key with the event itself.

NERV Event 2.1 therefore adds the PostgreSQL migration:

006-add-outbox-ordering-key.sql

The new Outbox column is nullable.

That is intentional because ordering remains opt-in.

Existing Outbox records remain valid, and applications that do not require aggregate ordering do not need to change how they publish events.

Existing two-argument EventPublication construction also remains supported.

This allows the new capabilities to ship as a backward-compatible 2.1.0 minor release rather than requiring a new major version.

9. The Showcase Was the Important Test

The most interesting part of these changes isn't any individual feature.

It's where the problems were discovered.

The basic Outbox pattern was already working.

The basic Inbox pattern was already working.

Retries were working.

Kafka was working.

SQS was working.

The edge cases appeared when those components were combined inside a realistic application with:

transactional business logic;
multiple services;
concurrent processing;
multiple application replicas;
Kafka and SQS transports;
real failure scenarios;
and production-style deployment constraints.

This is exactly why I wanted a full NERV showcase rather than another isolated example application.

Examples demonstrate APIs.

Realistic showcases challenge architectural guarantees.

10. The Bigger Lesson

An Outbox isn't reliable merely because events are stored before publication.

An Inbox isn't reliable merely because consumed event IDs are persisted.

Kafka ordering isn't guaranteed merely because a message has a key.

And an application isn't correctly configured merely because Spring Boot managed to start.

The guarantees have to survive the boundaries between those components.

That is what NERV Event 2.1 focuses on:

Durability
    +
Atomicity
    +
Idempotency
    +
Ordering
    +
Fail-fast configuration
    =
Predictable event processing

The goal isn't to eliminate failure.

Distributed systems will fail.

The goal is to make those failures:

explicit instead of silent;
recoverable instead of destructive;
observable instead of hidden;
deterministic instead of surprising.

That's the direction NERV Event continues to take: providing Spring applications with event-delivery infrastructure whose behavior remains understandable not only when everything works, but especially when it doesn't.

Try NERV Event

NERV Event is an open-source Spring Boot library for building reliable event-driven applications using transactional Outbox and Inbox patterns.

It provides infrastructure for:

transactional Outbox publishing;
durable Inbox consumption;
idempotent event processing;
automatic retries and failure tracking;
multi-instance-safe event claiming;
aggregate-aware event ordering;
Kafka integration;
Amazon SQS integration;
scheduler resilience;
and operational inspection APIs.

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

If you're building event-driven Spring Boot systems, I'd especially like to hear how you're handling ordering, consumer transaction boundaries, and multi-instance Outbox dispatch in production.

If NERV Event is useful to you, consider starring the project on GitHub. Feedback, issues, and contributions are always welcome.

NERV — Next-Generation Engineering for Runtime Velocity

Production-ready infrastructure for Java engineers building reliable enterprise systems.

Building a Production-Ready Persistence Layer in Spring Boot

2026-09-11T06:59:02.131+08:00

Building a Production-Ready Persistence Layer in Spring Boot

Spring Data JPA makes persistence remarkably easy to get started with.

Define an entity, create a repository, extend JpaRepository, and you already have CRUD operations, pagination, sorting, and a powerful query abstraction.

public interface CustomerRepository
    extends JpaRepository<Customer, Long> {
}

For a small application, this may be all you need.

But as a Spring Boot application grows, persistence requirements rarely remain that simple.

You start adding audit fields to entities. Search endpoints require increasingly complex filters. Repository interfaces accumulate query methods. Specifications appear in multiple places. Different services implement pagination and filtering differently.

Eventually, the problem is no longer:

How do I persist an entity?

It becomes:

How do I build a persistence layer that remains consistent, reusable, and maintainable as the application grows?

That is the problem a production-ready persistence foundation should solve.

The Persistence Layer Grows Faster Than You Expect

Consider a typical Spring Boot application.

You might begin with a repository like this:

public interface CustomerRepository
    extends JpaRepository<Customer, Long> {

  List<Customer> findByStatus(CustomerStatus status);
}

Then another requirement appears.

List<Customer> findByStatusAndCountry(
    CustomerStatus status,
    String country);

Then another.

List<Customer> findByStatusAndCountryAndType(
    CustomerStatus status,
    String country,
    CustomerType type);

Soon the API needs optional filters:

GET /customers
    ?status=ACTIVE
    &country=PH
    &type=PREMIUM

Each parameter may or may not be present.

Creating a repository method for every possible combination quickly becomes impractical.

At the same time, other concerns start appearing across your entities:

createdAt
updatedAt
createdBy
updatedBy

Pagination needs to behave consistently.

Sorting needs validation.

Specifications need common utilities.

Some queries should return full entities, while others only need a subset of fields.

None of these problems is particularly difficult on its own.

The problem is that they appear repeatedly.

Repetition Is Often a Sign of Missing Infrastructure

A common response is to create utility classes whenever duplication appears.

One helper for specifications.

Another for pagination.

A base entity for auditing.

Some repository helpers.

A few mapper utilities.

This works initially.

But across multiple applications or microservices, these implementations tend to evolve independently.

One service handles auditing one way.

Another uses a slightly different base entity.

Another builds specifications directly inside its service layer.

Another exposes entities from repository queries because creating a proper projection feels like too much work.

The individual decisions may all be reasonable.

The inconsistency is the problem.

A persistence foundation should establish a small set of conventions that application code can build upon.

Not a framework that replaces Spring Data JPA.

Not another abstraction hiding Hibernate.

Just enough reusable infrastructure to remove repetitive persistence plumbing.

Start with Consistent Entity Models

Most business entities need some common persistence metadata.

For example:

@MappedSuperclass
public abstract class AuditableModel {

  @CreatedDate
  private Instant createdAt;

  @LastModifiedDate
  private Instant updatedAt;

  @CreatedBy
  private String createdBy;

  @LastModifiedBy
  private String updatedBy;
}

Then business entities can focus on business data:

@Entity
public class Customer extends AuditableModel {

  @Id
  @GeneratedValue
  private Long id;

  private String name;

  private String country;

  @Enumerated(EnumType.STRING)
  private CustomerStatus status;
}

The important part is not saving four fields.

The important part is establishing a predictable model across the application.

When every persisted entity follows the same conventions, infrastructure becomes easier to build around it.

Operations teams know where to find creation and modification information.

Developers do not need to reinvent auditing for every entity.

Support investigations become easier because persistence metadata is consistent.

Consistency is one of the less glamorous benefits of shared infrastructure, but in production systems it is often one of the most valuable.

Dynamic Queries Should Be Composable

Repository query methods are excellent when the query is fixed.

For example:

Optional<Customer> findByExternalId(String externalId);

There is nothing wrong with this.

Problems begin when repository methods are used to represent every possible combination of optional search parameters.

This:

findByStatusAndCountryAndType(...)

eventually becomes:

findByStatusAndCountryAndTypeAndCreatedAtBetween(...)

and then multiple variations of the same method appear because some filters are optional.

For dynamic search requirements, queries should instead be composed from individual conditions.

Spring Data JPA already provides an excellent abstraction for this:

Specification<T>

A condition can be represented independently:

Specification<Customer> hasStatus(CustomerStatus status)

Another condition can handle country:

Specification<Customer> hasCountry(String country)

And another can represent customer type:

Specification<Customer> hasType(CustomerType type)

These can then be composed:

Specification<Customer> specification =
    Specification.where(hasStatus(status))
        .and(hasCountry(country))
        .and(hasType(type));

Now the query structure follows the actual search model rather than the number of possible parameter combinations.

This becomes especially useful when building REST APIs with optional filtering.

Specifications Should Be Reusable Too

Using Specification solves the query-combination problem, but large applications can still accumulate repetitive specification code.

You repeatedly write predicates for:

equality
IN
ranges
dates
strings
null checks
relationships

At that point, the same principle applies again.

The application should define what it wants to filter.

The persistence infrastructure should handle the repetitive mechanics of building those predicates.

The goal is not to hide JPA.

It is to keep application-specific query logic readable.

A specification should tell you something meaningful about the domain:

CustomerSpecifications.activeCustomers()

or:

CustomerSpecifications.createdBetween(from, to)

rather than forcing every developer to repeatedly reconstruct the same Criteria API plumbing.

Don't Load an Entire Entity When You Don't Need It

Another persistence problem appears when reads become more complex.

Suppose a Customer entity eventually contains dozens of fields and several relationships.

A search endpoint might only need:

id
name
status
country
createdAt

Returning the complete entity is unnecessary.

It can also create additional problems:

unnecessary data retrieval
accidental lazy loading
larger persistence contexts
unwanted entity serialization
tighter coupling between APIs and database models

This is where projections become valuable.

For example:

public interface CustomerSummary {

  Long getId();

  String getName();

  CustomerStatus getStatus();

  String getCountry();

  Instant getCreatedAt();
}

The persistence layer can retrieve the representation required by the use case rather than always materializing the complete entity.

This also reinforces an important architectural principle:

A persisted entity is not automatically the correct model for every read operation.

Entities, DTOs, and projections serve different purposes.

A good persistence foundation should make those distinctions easy to maintain.

Pagination and Sorting Are Infrastructure Concerns

Pagination looks simple:

PageRequest.of(page, size)

But APIs eventually need consistent behavior around:

default page size
maximum page size
allowed sorting fields
sort direction
multiple sort fields
invalid parameters

If every endpoint independently interprets these rules, subtle inconsistencies appear.

One API may treat page numbering as zero-based.

Another may expose one-based pagination.

One endpoint may allow arbitrary sorting.

Another validates fields.

A reusable persistence layer gives applications a common foundation for these mechanics while leaving business-specific decisions in the application.

Again, the objective is not more abstraction.

It is less repetition.

A Persistence Library Should Work With Spring Data, Not Against It

There is a danger when creating reusable infrastructure.

It is easy to keep adding abstractions until developers can no longer recognize the framework underneath them.

A persistence library should not require developers to forget how Spring Data JPA works.

If a developer knows:

JpaRepository

JpaSpecificationExecutor

Specification

Pageable

those concepts should remain useful.

The library should provide reusable building blocks around those APIs rather than replacing them with an entirely different persistence model.

This matters for another reason: debugging.

When something goes wrong in production, developers should be able to follow the execution path from the application to Spring Data to Hibernate to the database.

Infrastructure that removes boilerplate is useful.

Infrastructure that hides behavior is much harder to support.

This Is Why I Built NERV Persistence

These are the problems that led to nerv-persistence.

NERV Persistence is an open-source persistence foundation for Spring Boot applications built on top of Spring Data JPA.

It provides reusable building blocks for concerns that tend to appear repeatedly in real applications, including:

common persistence models
auditable entities
reusable specification infrastructure
dynamic querying
projections
repository conventions
consistent persistence patterns

The intention is deliberately conservative.

NERV Persistence does not try to replace Spring Data JPA or Hibernate.

It builds on them.

Application developers should still recognize the underlying Spring concepts and be able to use them directly when necessary.

The library simply provides a common foundation so every application does not have to rebuild the same persistence infrastructure from scratch.

Where NERV Persistence Fits

A typical Spring Boot application might look something like this:

Application
    |
    +-- REST / API
    |
    +-- Application Services
    |
    +-- DTOs / Mappers
    |
    +-- Domain Logic
            |
            v
    NERV Persistence
            |
            +-- Persistence Models
            +-- Specifications
            +-- Query Infrastructure
            +-- Projections
            +-- Repository Foundation
                    |
                    v
            Spring Data JPA
                    |
                    v
                Hibernate
                    |
                    v
                Database

NERV Persistence sits close to the persistence boundary.

It should not contain your business rules.

It should not determine your domain model.

And it should not force every service to use identical database structures.

Instead, it standardizes the technical concerns that are genuinely reusable.

Why This Matters More in Microservices

Persistence duplication becomes particularly noticeable in a microservice architecture.

Imagine several services:

customer-service
payment-service
order-service
subscription-service
notification-service

Each service owns its database and domain model.

That independence is important.

But independence does not mean every service needs a different implementation of:

auditing
pagination
specifications
query helpers
repository conventions

These are infrastructure concerns.

A shared persistence foundation allows teams to standardize them while keeping domain-specific persistence inside each service.

The distinction is important:

Share infrastructure conventions, not domain models.

A Customer entity should not become a shared library just because several services know what a customer is.

But the infrastructure used to audit, query, paginate, and persist entities can often be shared safely.

Production-Ready Doesn't Mean Complicated

A production-ready persistence layer does not need hundreds of abstractions.

In fact, the opposite is often true.

Good persistence infrastructure should make the common path boring:

define entity
    ↓
define repository
    ↓
compose query
    ↓
retrieve the required model
    ↓
map to application response

The complexity should remain visible only when the use case actually requires it.

That is the philosophy behind NERV Persistence and, more broadly, the NERV libraries.

Build reusable infrastructure around problems that repeatedly appear in production systems, while keeping the underlying technology understandable and debuggable.

What's Next?

This article provides the broader architecture behind NERV Persistence.

In the next articles, we'll go deeper into individual persistence problems, including:

dynamic queries without repository method explosion
composable Spring Data JPA specifications
auditable base entities
projections and efficient read models
reusable pagination, sorting, and filtering
entity vs DTO vs projection
designing base JPA entities without over-abstracting
reusable repository infrastructure
consistent persistence patterns across Spring Boot services

Each topic will focus on the engineering problem first and then show how it can be implemented using Spring Data JPA and NERV Persistence.

NERV Persistence

nerv-persistence is part of the NERV open-source ecosystem — Next-Generation Engineering for Runtime Velocity — a collection of Spring libraries focused on reusable infrastructure for production applications.

If you're building Spring Boot applications and repeatedly implementing the same persistence infrastructure across projects or services, NERV Persistence is intended to provide a reusable starting point.

Explore the project on GitHub:
https://github.com/czetsuyatech/nerv-persistence

More NERV libraries and engineering articles:
https://www.czetsuyatech.com/

Transactional Outbox Pattern with Spring Boot: Reliable Event Publishing Without Dual Writes

2026-09-05T22:40:02.000+08:00

Event-driven architecture looks straightforward at first.

A service updates its database, publishes an event to Kafka, and another service reacts to it.

Payment Service
    |
    +-- Save payment
    |
    +-- Publish PaymentCompleted
              |
              v
            Kafka

But there is a reliability problem hidden in those two operations.

What happens if the database transaction succeeds, but publishing the event fails?

Your payment exists, but the rest of the system never hears about it.

And if publishing succeeds first but the database transaction later fails, consumers may receive an event describing something that never actually happened.

This is the dual-write problem.

The transactional outbox pattern is one of the most practical ways to solve it.

The Dual-Write Problem

Consider a typical Spring service:

@Transactional
public void completePayment(Payment payment) {
    paymentRepository.save(payment);

    kafkaTemplate.send(
        "payments",
        new PaymentCompletedEvent(payment.getId())
    );
}

It looks reasonable.

The problem is that two different systems participate in this method:

the application database
Kafka

The database transaction does not automatically include Kafka.

Several failure scenarios are therefore possible.

Database succeeds, Kafka fails

Database
Payment = COMPLETED  ✓

Kafka
PaymentCompleted     ✗

The local state says the payment completed, but downstream services never receive the event.

Kafka succeeds, database fails

Depending on when and how publishing occurs, the opposite problem can also happen.

Kafka
PaymentCompleted     ✓

Database
Payment = COMPLETED  ✗

A consumer may now process an event representing state that was never committed.

Trying to coordinate these operations manually quickly becomes complicated.

What we really want is a simple guarantee:

If the business transaction commits, the intention to publish its event must commit with it.

That is where the outbox comes in.

The Transactional Outbox

Instead of publishing directly to Kafka inside the business transaction, we store the event in the same database transaction as the business data.

     DATABASE TRANSACTION
        ┌─────────────────────────────┐
        │                             │
        │  Update Payment             │
        │         +                   │
        │  Insert Outbox Event        │
        │                             │
        └──────────────┬──────────────┘
                       │
                    COMMIT
                       │
                       v
                 Outbox Dispatcher
                       │
                       v
                     Kafka

Now the database determines the atomic boundary. Either both records commit:

Payment       ✓
Outbox Event  ✓

or neither does:

Payment       ✗
Outbox Event  ✗

Kafka no longer needs to participate in the business transaction.

What Goes Into the Outbox?

An outbox table normally contains enough information to publish the event later.

Conceptually, a record could look like:

event_id       = 01J...
event_type     = PaymentCompleted
source         = payment-service
payload        = {...}
content_type   = application/json
status         = PENDING
created_at     = ...

The important part is that the payload and its delivery state are persisted.

I particularly prefer keeping the payload readable rather than hiding it behind opaque serialization.

When something goes wrong in production, being able to inspect the exact event that was supposed to leave the service is extremely useful.

The outbox isn't merely a delivery mechanism.

It becomes part of your operational history.

Publishing the Event

A separate dispatcher polls pending outbox records.

For example:

PENDING
   |
   v
PROCESSING
   |
   +--------------------+
   |                    |
   v                    v
PUBLISHED           retryable failure
                        |
                        v
                     PENDING
                        |
                     retry later

After a configurable number of attempts, permanently failing events can transition to:

FAILED

This separation is important.

Your business transaction is responsible for recording what happened.

The dispatcher is responsible for delivering that information.

Those are different responsibilities and should fail independently.

Why Not Just Retry Kafka Inside the Transaction?

A common first solution is to retry publishing:

@Transactional
public void completePayment(Payment payment) {
    paymentRepository.save(payment);

    retryTemplate.execute(context ->
        kafkaTemplate.send("payments", event)
    );
}

Retries can help with temporary failures.

But they do not remove the fundamental coupling.

Imagine Kafka is unavailable for several minutes.

Should your payment transaction remain open while the application repeatedly attempts to contact Kafka?

Probably not.

Long-running transactions consume database resources, increase lock duration, and couple business availability to messaging availability.

With an outbox:

Payment transaction
      |
      +---- commits quickly
      |
      v
Outbox

Kafka unavailable
      |
      +---- dispatcher retries independently

The business operation can succeed even while the broker is temporarily unavailable.

At-Least-Once Delivery Changes the Problem

There is an important consequence.

An outbox dispatcher can usually provide at-least-once delivery, not magically guaranteed exactly-once business processing.

Consider this sequence:

1. Dispatcher publishes event to Kafka
2. Kafka accepts the event
3. Application crashes
4. Outbox record was not yet marked PUBLISHED
5. Application restarts
6. Dispatcher publishes the event again

The same event may be delivered twice.

That is not necessarily a bug.

It is a consequence of choosing reliability over silently losing messages.

The architecture therefore becomes:

Transactional Outbox
        +
At-Least-Once Delivery
        +
Idempotent Consumer

This is why the inbox pattern naturally complements the outbox pattern.

We'll cover that separately.

Multiple Application Instances

Production systems rarely run a single instance.

Imagine three pods:

        OUTBOX
                 |
        +--------+--------+
        |        |        |
       Pod A    Pod B    Pod C

Without coordination, multiple pods could select the same pending events.

One common approach is database-level locking.

Conceptually:

SELECT ...
FROM outbox
WHERE status = 'PENDING'
FOR UPDATE SKIP LOCKED;

Suppose the outbox contains:

Pod A may lock:

1 2 3

while Pod B skips those locked rows and receives:

4 5 6

This allows multiple workers to process the outbox concurrently without waiting on the same rows.

The exact implementation depends on the database and persistence strategy, but the principle is important:

Scaling the dispatcher horizontally should not mean publishing every event multiple times.

What About CDC?

Polling isn't the only way to implement an outbox.

Another common architecture uses Change Data Capture:

Application
     |
     v
Database Outbox
     |
     v
    CDC
     |
     v
   Kafka

Tools such as Debezium can stream database changes instead of having application workers poll the table.

CDC can be an excellent choice at larger scale or when an organization already operates the necessary infrastructure.

But it introduces another operational component.

Application-level polling has different advantages:

simpler infrastructure
easier local development
easier debugging
broker independence
application-controlled retry behavior

Neither approach is universally better.

The important architectural idea is not the polling mechanism.

It is the transactional boundary provided by the outbox.

Making This Reusable

After implementing this pattern several times, a lot of infrastructure starts repeating:

Outbox persistence
Event serialization
Dispatch scheduling
Retry handling
Concurrency
Failure states
Metrics
Kafka integration
SQS integration
Operational endpoints

Business applications shouldn't need to rebuild all of that every time they need reliable event delivery.

That is one of the reasons I built NERV Event.

With NERV Event, the goal is to keep the application focused on expressing the event while the library handles the delivery lifecycle.

Conceptually:

eventPublisher.publish(
    "PaymentCompleted",
    paymentCompletedEvent
);

Behind that operation is the infrastructure required to persist and eventually dispatch the event reliably.

The architecture becomes:

Business Service
      |
      v
  NERV Event
      |
      v
Transactional Outbox
      |
      v
Dispatcher
      |
   +--+--+
   |     |
 Kafka  SQS

The application owns the business event.

The infrastructure owns its reliable delivery.

Reliability Doesn't End at the Producer

The transactional outbox solves an important problem:

How do I make sure an event isn't lost after my business transaction commits?

But once that event reaches another service, a new set of problems begins.

What if the consumer processes the same event twice?

What happens if processing succeeds but acknowledgement fails?

How do we retry safely?

How do we know whether an event has already been processed?

Those are consumer-side reliability problems.

And that is where the Inbox Pattern comes in.

In the next article, we'll look at Inbox Pattern and Idempotent Consumers and build the other half of reliable event delivery.

NERV Event

NERV Event is an open-source event reliability framework for Spring Boot designed around transactional outbox/inbox processing, retries, idempotency, Kafka and SQS integration, and production operations.

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

The broader introduction to the architecture is covered in:

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

This series goes deeper into each of the reliability problems individually.

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

2026-09-01T13:46:17.000+08:00

Introduction

Event-driven architecture looks simple at first.

Your application performs a business operation, publishes an event to Kafka or SQS, and another service consumes it.

For example:

@Transactional
public void createOrder(CreateOrderCommand command) {
  Order order = orderRepository.save(...);

  kafkaTemplate.send(
      "orders",
      new OrderCreatedEvent(order.getId())
  );
}

The order is saved, an OrderCreatedEvent is published, and other services can react to it.

But there is a problem hiding in those few lines.

What happens if the database transaction succeeds, but publishing the event fails?

And on the other side:

What happens if the consumer receives the same event twice?

These two questions lead to some of the most important patterns in reliable event-driven systems: the Transactional Outbox, Inbox, Idempotent Consumer, and Durable Retry patterns.

Let's build the architecture step by step and see what changes when these patterns have to work in a real Spring Boot application running across multiple instances

The Dual-Write Problem

Imagine an order service that needs to do two things:

Save an order to PostgreSQL.
Publish OrderCreated to Kafka.

Conceptually:

Database ──────> COMMIT ✓
                   |
Kafka ─────────> PUBLISH ✗

The database and Kafka are two independent systems. A successful database commit does not guarantee a successful Kafka publish. Consider this sequence:

1. INSERT order
2. COMMIT
3. Publish OrderCreated
4. Application crashes

If the application crashes between steps 2 and 3, the order exists but the event doesn't.

Other services may never know that the order was created.

Reversing the operations doesn't solve the problem either:

1. Publish OrderCreated
2. INSERT order
3. Database transaction fails

Now consumers may receive an event for an order that doesn't exist.

This is the classic dual-write problem.

The Transactional Outbox Pattern

Instead of trying to atomically update the database and message broker, we make the event part of the same database transaction as the business operation.

             Database Transaction
        ┌─────────────────────────────┐
        │                             │
Request ──> Business Data             │
        │       +                     │
        │   Outbox Event              │
        │                             │
        └────────── COMMIT ───────────┘
                       |
                       v
                Outbox Dispatcher
                       |
                       v
                  Kafka / SQS

When an order is created, we persist both the business data and the event:

ORDER
  +
OUTBOX EVENT

inside the same database transaction.

Either both are committed or neither is committed.

A separate dispatcher then finds pending outbox records and publishes them to the broker.

A simplified lifecycle might look like this:

PENDING
   |
   v
PROCESSING
   |
   +──── success ────> PUBLISHED
   |
   └──── failure ────> RETRY / FAILED

This removes the dangerous database-and-broker dual write from the business transaction.

But it also gives us something extremely valuable in production:

persistent delivery state.

Your Outbox Should Be Debuggable

Reliability isn't only about retrying failed operations.

When something goes wrong in production, someone eventually needs to answer:

What happened to this event?

A useful outbox record should contain enough information to answer that question:

eventId
eventType
source
correlationId
payload
status
attempts
createdAt
availableAt
publishedAt
lastError

Instead of searching through distributed logs hoping to reconstruct what happened, an engineer can inspect the actual delivery state:

SELECT *
FROM event_outbox
WHERE status = 'FAILED';

This leads to an important principle:

Reliability mechanisms should also improve debuggability.

If an event cannot be delivered, that failure should be visible and inspectable.

Publishing Reliably Is Only Half the Problem

Suppose our outbox works perfectly.

Every event eventually reaches Kafka.

We still aren't finished.

Most event-driven architectures use at-least-once delivery. That means the same event may be delivered more than once.

Producer
   |
   v
Kafka
   |
   +──── OrderCreated #123 ────> Consumer
   |
   +──── OrderCreated #123 ────> Consumer

A consumer might successfully process an event but crash before acknowledging it. The broker can then deliver it again.

If processing means sending an email, the customer might receive two emails.

If processing means performing a financial operation, the consequences can be much worse.

A reliable consumer therefore needs to assume:

Every event can arrive more than once.

The Inbox Pattern

The Inbox Pattern provides a durable record of received events.

Before processing an event, the consumer registers its unique event ID.

Broker
   |
   v
Inbox Registration
   |
   +── event already exists ──> DUPLICATE
   |
   └── new event
          |
          v
       RECEIVED
          |
          v
      PROCESSING
        /     \
       v       v
 PROCESSED   FAILED

If the same eventId arrives again, the consumer knows that it has already seen the event.

The event ID becomes an idempotency boundary.

Instead of depending on exactly-once delivery, we design the consumer so duplicate delivery does not result in duplicate business effects.

The Inbox Is More Than a Deduplication Table

A minimal inbox could contain nothing more than processed event IDs.

For production systems, however, it can provide something much more useful:

a durable history of event processing.

Consider storing:

eventId
eventType
source
correlationId
payload
status
attempts
receivedAt
processedAt
availableAt
lastError

Now imagine someone reports:

Order 123 was created, but the downstream action never happened.

You can inspect the inbox.

Was the event received?

Was processing started?

Did processing fail?

How many times was it attempted?

When is the next retry?

What was the last error?

Those questions become much easier to answer when processing state is explicit.

Retries Should Survive Application Restarts

Spring provides excellent retry mechanisms.

For example:

@Retryable
public void handle(OrderCreatedEvent event) {
  ...
}

This can be perfectly appropriate for short-lived transient failures.

But event processing introduces another question:

What happens if the JVM dies?

Event processing fails
        |
        v
Retry scheduled in memory
        |
        v
Application restarts

If retry state exists only in memory, it disappears with the process.

For durable event processing, retry state can instead be persisted:

FAILED
   |
   | availableAt <= now
   v
PROCESSING
   |
   +──── success ────> PROCESSED
   |
   └──── failure ────> FAILED
                         |
                         + attempts++
                         + availableAt = next retry

A scheduler periodically finds events whose retry time has arrived and attempts them again.

Because the state lives in the database, restarting the application doesn't destroy the retry information.

Use Backoff Instead of Hammering a Failing Dependency

Retrying immediately and continuously can make an outage worse.

Suppose a downstream service is unavailable.

Thousands of failed events retrying as quickly as possible simply add more pressure to an already failing system.

A better strategy is exponential backoff:

Attempt 1 → immediate
Attempt 2 → +1 second
Attempt 3 → +2 seconds
Attempt 4 → +4 seconds
Attempt 5 → +8 seconds

Eventually, the configured retry limit is exhausted.

At that point, the event can remain explicitly marked as failed:

status = FAILED
availableAt = null

Automatic processing stops, but the event doesn't disappear.

It remains available for investigation and operational recovery.

What About Dead-Letter Queues?

Dead-letter queues are valuable, particularly for broker-level failures.

But a broker DLQ doesn't necessarily have to become the application's primary record of processing failure.

There is a useful distinction:

Broker concern               Application concern

Delivery failure             Processing failure
Malformed message            Business handler failure
Transport problem            Retry exhaustion
        |                            |
        v                            v
       DLQ                         INBOX

The two mechanisms can coexist.

A database-backed inbox gives the application direct visibility into its own processing state, while a DLQ remains available for appropriate broker and transport-level failures.

Then You Deploy Multiple Pods

Everything becomes more interesting once the application runs more than one instance.

                 OUTBOX
                     |
               pending event
                     |
          ┌──────────┴──────────┐
          v                     v
        Pod A                 Pod B
     Dispatcher             Dispatcher

Both instances may discover the same pending event.

Without concurrency control, both may attempt to process it.

Production implementations therefore need a concept of claiming or locking.

For example:

status
lockOwner
lockedAt

An instance claims records transactionally before processing them.

Other instances can then determine that those records are already being processed.

But this creates another question:

What happens if a pod claims an event and then dies?

The system needs a deterministic mechanism for recovering stale claims after an appropriate timeout.

At this point, the outbox is no longer just a database table plus a scheduled query.

It has become infrastructure.

Even the Scheduler Can Fail

There is another failure mode that is surprisingly easy to overlook.

Suppose the dispatcher completes successfully and schedules its next execution:

Dispatcher completes
        |
        v
schedule(nextRun)
        |
        X
TaskScheduler rejects the task

If the scheduler continues reporting itself as running, the application has entered a dangerous state.

Everything appears healthy.

But no future dispatch will happen.

Events can quietly accumulate in the outbox.

A reliable scheduler therefore benefits from an explicit lifecycle:

STOPPED
   |
   v
STARTING
   |
   v
RUNNING
   |
   +──── scheduling failure ────> FAILED

A useful invariant is:

A scheduler must not report itself as running if no task is scheduled and no work is currently executing.

Scheduling infrastructure itself needs observable failure semantics.

Observability Is Part of Reliability

Imagine receiving a production incident at 2 AM:

We created the order, but the downstream system didn't process it.

Ideally, you should be able to follow the event:

Order
  |
  v
Outbox Event
  |
  +── created
  +── claimed
  +── publish attempts
  +── published
  |
  v
Broker
  |
  v
Inbox Event
  |
  +── received
  +── processing attempts
  +── failure reason
  +── retry schedule
  +── processed

Correlation metadata should connect the pieces.

Payloads should be readable.

State transitions should be explicit.

Failures should remain inspectable.

Logs should explain what the infrastructure is doing without becoming the only source of truth.

A reliable system isn't only one that recovers from failures. It is one that helps engineers understand those failures.

From Architecture to Implementation: NERV Event

These are the problems I wanted to solve consistently across Spring Boot applications.

None of the individual patterns are new.

Transactional outbox is well understood. Idempotent consumers are well understood. Retries, locking, and message brokers are well understood.

The difficulty is making all of them work together consistently in a production application.

That led me to build NERV Event: an open-source event infrastructure library for Spring Boot.

At a high level, the architecture looks like this:

             Spring Boot Application
                         |
              ┌──────────┴──────────┐
              |                     |
              v                     v
           OUTBOX                  INBOX
              |                     ^
              v                     |
        Outbox Dispatcher           |
              |                     |
              v                     |
         Kafka / AWS SQS ───────────┘

NERV Event brings together:

Transactional outbox persistence
Durable inbox processing
Idempotent event consumption
Persistent retries
Exponential retry policies
Multi-instance-safe processing
Kafka integration
AWS SQS integration
Scheduler lifecycle and failure visibility
Event retention
Operational inspection
Correlation metadata
Human-readable persisted payloads

The goal isn't to hide event-driven architecture behind magic.

The goal is to make its behavior predictable, observable, and easy to debug.

Explore NERV Event

NERV Event is open source and available on GitHub.

Source code, documentation, configuration, and examples:

NERV Event on GitHub:
https://github.com/czetsuyatech/nerv-event

If you're building event-driven Spring Boot services, you can also use the project as a reference architecture even if you don't adopt the library itself.

I'll be writing more about the individual pieces behind NERV Event—including transactional publishing, inbox processing, Kafka and SQS integration, retries, multi-pod deployment, and operational tooling—in future articles.

Final Thoughts

Adding Kafka or SQS to a Spring Boot application doesn't automatically make the application reliably event-driven.

The difficult parts exist around the broker:

Business Transaction
        |
        v
Transactional Outbox
        |
        v
Reliable Delivery
        |
        v
At-Least-Once Messaging
        |
        v
Inbox + Idempotency
        |
        v
Durable Processing
        |
        v
Retries + Recovery
        |
        v
Observability

Each layer addresses a different failure mode.

And in distributed systems, those failure modes aren't theoretical. Processes restart. Networks fail. Messages are redelivered. Dependencies become unavailable. Schedulers stop. Multiple instances compete for the same work.

The goal isn't to pretend those failures won't happen.

The goal is to design the system so that when they do happen:

state is preserved, recovery is predictable, and engineers can understand exactly what happened.

That's the philosophy behind NERV Event.

NERV Event

Open-source event infrastructure for reliable Spring Boot applications.

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

Stop Copying Exception Handlers Between Spring Boot Projects

2026-07-06T18:49:23.000+08:00

If you've built more than one Spring Boot application, you've probably experienced this.

You start with a few REST endpoints and a simple @RestControllerAdvice.

@RestControllerAdvice 
public class GlobalExceptionHandler {
    @ExceptionHandler(UserNotFoundException.class) 
    public ResponseEntity < ? > handle(UserNotFoundException ex) {
      // ... 
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity < ? > handle(MethodArgumentNotValidException ex) {
      // ... 
    }
}

Everything looks fine.

Then the application grows.

You introduce custom business exceptions. Validation errors need a different response format. Another microservice returns completely different error payloads. Feign clients need their own error decoder. Kafka consumers have another way of reporting failures.

Before long, your application no longer has one exception handling strategy—it has several.

I've seen this happen in multiple Spring Boot projects over the years.

Ironically, while the business logic was always different, the exception handling infrastructure was almost identical.

I found myself copying the same classes from project to project:

Global exception handlers
Error response models
Error codes
Validation handlers
Feign decoders
Utility classes
Configuration

Every new project started with the same foundation.

Eventually I stopped and asked myself:

Why am I rebuilding this every single time?

That question became nerv-exception.

What I Wanted to Build

I wasn't trying to create another framework.

Spring Boot is already an excellent framework.

Instead, I wanted a reusable library that provides a solid foundation for one specific concern:

Consistent exception handling.

The library should be:

Production-ready
Modular
Lightweight
Easy to customize
Easy to integrate
Easy to remove if needed

Introducing nerv-exception

nerv-exception is a modular Spring Boot library that standardizes exception handling across your application.

Instead of rebuilding the same infrastructure, you simply add the starter.

<dependency> 
	<groupId>com.czetsuyatech</groupId> 
	<artifactId>nerv-exception-spring-boot-starter</artifactId> 
	<version>1.0.0</version> 
</dependency>

The library provides:

Standardized API error responses
RFC 7807 Problem Details support
Centralized error codes
Global exception handling
Bean Validation integration
Spring Boot auto-configuration
Feign client integration
Event and Kafka support

Designed to Be Modular

One thing I dislike about many libraries is that they force you to adopt everything.

I wanted the opposite.

The project is divided into focused modules.

nerv-exception-api
nerv-exception-core
nerv-exception-spring-web
nerv-exception-spring-boot-starter
nerv-exception-spring-feign
nerv-exception-event
nerv-exception-spring-kafka

Applications can depend on only the modules they need.

Consistent Error Responses

One of the biggest benefits is consistency.

Instead of every controller returning a different error payload, clients receive predictable responses.

For example, a "User Not Found" error can be represented using RFC 7807 Problem Details.

  {
  "type": "https://example.com/problems/user-not-found",
  "title": "User not found",
  "status": 404,
  "detail": "User 123 was not found.",
  "instance": "/users/123"
}

Consistent responses make APIs easier to consume, easier to document, and easier to troubleshoot.

Real Examples Matter

Documentation is important.

But I believe runnable code is even more valuable.

That's why I also created the nerv-examples repository, which contains complete Spring Boot applications demonstrating how to integrate the library in real projects.

Rather than reading isolated snippets, you can clone the repository, run the application, and explore the implementation yourself.

Why Open Source?

Throughout my career, open source libraries have saved me thousands of hours.

This project is my opportunity to give something back.

If nerv-exception saves another developer from copying the same exception handlers into yet another Spring Boot project, then it has accomplished exactly what I hoped.

Try It Yourself

GitHub: https://github.com/czetsuyatech/nerv-exception
Example Applications: https://github.com/czetsuyatech/nerv-examples

Available on Maven Central

<dependency> 
	<groupId>com.czetsuyatech</groupId> 
	<artifactId>nerv-exception-spring-boot-starter</artifactId> 
	<version>1.0.0</version> 
</dependency>

If you have ideas, questions, or suggestions, I'd love to hear them. Feedback from the community is one of the best ways to improve an open source project.

Happy coding!

Reusable GitHub Actions for Maven Projects — Stop Rewriting CI/CD Pipelines

2026-04-19T20:06:00.000+08:00

If you’ve worked on multiple Java projects, you’ve probably noticed something frustrating:

Every repository has its own version of a CI/CD pipeline.

Slightly different. Slightly broken. Slightly outdated.

And every time you start a new project, you end up:

Copying an old GitHub Actions workflow
Tweaking it to make it work
Fixing versioning logic
Relearning release steps
Debugging the same issues again

It’s repetitive, inconsistent, and honestly… a waste of time.

🚨 The Real Pain Points

After going through this multiple times, a few patterns became obvious:

1. No Standardization

Each project defines CI/CD differently.
→ Hard to maintain across teams

2. Versioning is Messy

Manual version bumps, forgotten tags, inconsistent releases.
→ Leads to broken or confusing releases

3. Releases Are Too Manual

Even with automation, there’s still too much friction.
→ Slows down delivery

4. Pipelines Don’t Scale

What works for one repo doesn’t work for ten.
→ No easy way to reuse workflows

💡 The Solution: nerv-actions

Instead of rewriting pipelines every time, I built nerv-actions — a set of reusable GitHub Actions workflows for Maven projects.

The idea is simple:

Define CI/CD once. Reuse it everywhere.

⚙️ What It Does

Analyze commit history
Determine semantic version
Update Maven project version
Build and test
Publish artifacts
Create GitHub Release

All automated. No manual steps.

🔥 What This Fixes

✅ Consistent pipelines across all repositories
✅ Automatic semantic versioning
✅ Fully automated releases
✅ Reusable workflows

You stop thinking about CI/CD… and it just works.

📦 Minimal Setup

jobs:
  cd:
    uses: czetsuyatech/nerv-actions/.github/workflows/cd.yml@main
    with:
      javaVersion: '25'
    secrets:
      githubAppId: ${{ secrets.NERV_RELEASE_APP_ID }}
      githubAppPrivateKey: ${{ secrets.NERV_RELEASE_APP_PRIVATE_KEY }}
      githubToken: ${{ secrets.GH_PKG_TOKEN }}

That’s it.

🧩 When You Start Scaling

The reality is, most teams don’t stay in a single stack.

Eventually, you’ll need:

Node.js pipelines
Go releases
Container builds
Cross-repository orchestration

To support this, I built nerv-actions Pro.

👉 Request access to Pro workflows: czetsuya@gmail.com

🛠️ Need Help Setting This Up?

If you want to skip the trial-and-error, I also offer services to:

Design CI/CD pipelines for your architecture
Implement GitHub Actions workflows
Set up automated releases
Optimize performance and reliability

The goal: a clean, scalable pipeline without the headaches.

👉 Request consulting: your-email@example.com

💭 Final Thought

CI/CD shouldn’t be something every project reinvents.

Once standardized, it becomes:

Predictable
Maintainable
Scalable

That’s what nerv-actions is aiming for.

🔗 Project Link

Spring Boot Audit Trail Made Easy: Introducing nerv-audit (Hibernate Envers + JPA)

2026-04-07T22:17:00.000+08:00

If you're building a Spring Boot application, sooner or later you'll need a reliable audit trail.

Whether it's for:

Compliance (finance, healthcare, enterprise systems)
Debugging production issues
Tracking data changes
User activity monitoring

The problem?

Building audit logging properly is harder than it looks.

That’s why I built nerv-audit — a production-ready audit trail library for Spring Boot using Hibernate Envers.

What is nerv-audit?

nerv-audit is a modular audit logging framework for:

Spring Boot
JPA / Hibernate
Hibernate Envers

It provides:

Automatic audit tracking
Queryable audit history
Flexible audit strategies (vertical and horizontal)
A plug-and-play Spring Boot starter

👉 Designed for real-world systems—not tutorials.

Why You Need an Audit Trail in Spring Boot

Many developers search for:

“How to implement audit logging in Spring Boot”
“Hibernate Envers example”
“Track entity changes in JPA”

But most solutions:

Only log changes
Don’t support querying
Are hard to maintain

A proper audit system should:

Track who changed what and when
Support filtering and history queries
Be consistent across services

That’s exactly what nerv-audit solves.

Key Features of nerv-audit

✅ 1. Hibernate Envers Integration (Done Right)

Instead of manually wiring Envers, nerv-audit:

Auto-configures listeners
Provides extension points
Standardizes audit table handling

✅ 2. Vertical vs Horizontal Audit Strategies

Choose how you store audit data:

Horizontal Audit (Snapshot-based)

One row per revision
Full entity state

Vertical Audit (Change-based)

One row per field change
Tracks:

old value
new value
changed field

👉 Best for:

Debugging
Compliance
Change tracking systems

✅ 3. Queryable Audit API (Spring Boot REST)

Unlike most audit setups, nerv-audit lets you query audit logs via API.

Example:

GET /nerv-audit/vertical/UserEntity?id=101&updatedBy=admin

Supports:

Filtering by user
Field-level filtering
Date ranges
Pagination & sorting

✅ 4. Modular Architecture for Scalability

Built as a multi-module Maven project:

nerv-audit-api → contracts & DTOs
nerv-audit-core → Envers logic
nerv-audit-lite → simplified version
nerv-audit-spring-boot-starter → auto-config

Perfect for:

Microservices
Internal platforms
Enterprise systems

✅ 5. Lite vs Pro Editions

Lite (Free)

Create operation auditing
Basic setup
Lightweight integration

Pro

Full CRUD auditing (create, update, delete)
List tracking
REST API
Advanced filtering

How to Add Audit Logging in Spring Boot (Quick Start)

1. Add Dependency

<dependency>
  <groupId>com.czetsuyatech

<artifactId>nerv-audit-spring-boot-starter </dependency>

2. Enable Audit API

nerv:
  audit:
    web:
      enabled: true

3. Start Tracking Entity Changes

Just annotate your entities with:

@Audited

Done. You now have:

Audit tracking
Queryable history
Production-ready setup

Use Cases: When to Use nerv-audit

This library is ideal if you are building:

🔹 Enterprise Applications

Financial systems
ERP platforms
Internal tools

🔹 SaaS Platforms

User activity tracking
Data history
Debugging production issues

🔹 Regulated Systems

Compliance logging
Audit trails for legal requirements

nerv-audit vs Custom Audit Implementation

Feature	Custom Build	nerv-audit
Envers setup	Manual	Auto configured
Audit querying	Hard	Built-in API
Maintainability	Low	High
Time to implement	Weeks	Minutes

Built for Production (Not Just Tutorials)

Most audit examples online are:

Simplified
Incomplete
Not scalable

nerv-audit is different.

It’s built with:

Real production constraints
Clean architecture
Extension points for customization
Focus on long-term maintainability

Future Roadmap (SEO Boost Section 🚀)

Planned features:

Multi-tenant audit support
Kafka integration (event-driven audit)
SIEM integrations
Advanced analytics

About the Author

I build:

Spring Boot backend systems
Internal developer platforms
Production-grade reusable libraries

If your team needs:

Audit systems
Backend architecture
Platform engineering

Let’s work together.

Final Thoughts: Stop Rebuilding Audit Systems

If you're searching for:

“Spring Boot audit logging best practices”
“Hibernate Envers production setup”
“JPA entity change tracking”

Then nerv-audit is exactly what you need.

👉 It saves time
👉 It standardizes auditing
👉 It works in production

Try nerv-audit Today

Start adding audit trails to your Spring Boot app in minutes.

https://github.com/czetsuyatech/nerv-audit

How to Log Method Execution Time in Spring Boot Using AOP

2025-11-04T09:24:00.000+08:00

Overview

Monitoring method execution time is one of the easiest yet most effective ways to understand your application’s performance. In this guide, we’ll explore how to use Spring Boot with Aspect-Oriented Programming (AOP) to log method execution times cleanly—without cluttering your business logic. By leveraging the @Aspect annotation, we can intercept method calls, measure how long they take, and log this information for performance analysis. This approach is flexible, reusable, and perfect for tracking performance bottlenecks in large-scale applications. Let’s dive in and build a lightweight execution time logger using Spring AOP.

Aspect Annotation

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TrackExecutionTime {
 //
}

Aspect Interceptor

@Aspect
@Component
@Slf4j
public class ExecutionTimeAspect {

  @Around("@annotation(com.dcx.nba.actions.annotations.TrackExecutionTime)")
  public Object logExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {

    long startTime = System.currentTimeMillis();

    Object result = joinPoint.proceed();

    long endTime = System.currentTimeMillis();
    long executionTime = endTime - startTime;

    log.info("{} executed in {}ms", joinPoint.getSignature().toShortString(), executionTime);

    return result;
  }
}

Annotation Usage

This method runs via scheduler and computes the total elapsed time during the execution

@Override
@TrackExecutionTime
@SchedulerLock(name = JOB_NAME)
@Scheduled(cron = "${app.schedulers.update-action-status.cron}")
public void scheduleUpdateStatus() {
}

Secure React and Spring Boot with Microsoft Entra SSO and Bearer Token Authentication

2025-07-13T19:31:00.000+08:00

Introduction

Implementing secure, seamless login across a modern full-stack application is essential—but it doesn’t have to be complicated. In this guide, we’ll walk through how to integrate Microsoft Entra (formerly Azure AD) for Single Sign-On (SSO) in a React frontend and Spring Boot backend. The Spring Boot application acts as a resource server, validating JWT bearer tokens issued by Entra. Beyond authentication, we’ll also demonstrate how to map Microsoft Entra groups to internal application roles, dynamically fetched from your own database. Whether you're building internal tools or enterprise-grade platforms, this setup gives your app robust security, fine-grained access control, and a smooth user experience across services.

Problem

You need SSO in your frontend to allow users to login to your system and authorize the call of backend endpoints by sending the bearer token. In the backend we will get the user group attached to the currently log user and fetch the corresponding internal permissions which we will add as roles to the JWT.

Our schema will look like:

Prerequisites for this Exercise

Microsoft Entrata account (https://entra.microsoft.com)
Familiar with React
Experience in Spring REST programming

Microsoft Entrata

If you haven't sign up yet visit Microsoft Entrata website and register a new account. After a successful registration you should be logged and redirect to the dashboard page where you can get the tenant id. Take a note because we will use it in the client and backend configuration later.

App Registration

Inside Entrata, under Manage / App Registrations click New Registrations. For this exercise since we will be doing the authentication in the frontend we need to register an app of type SPA. Don't forget to fill-in the redirect URI.

Take note of the Application (client) ID.

Expose an API

Now we need to add a scope that we will use during login. This will allow us to use the MS Graph version 2. Without a defined scope Entrata will use version 1 which will throw an error during JWT validation in the backend.

Update Token Version in the Manifest

In the left menu, find the Manifest.

In the JSON document, find the requestedAccessTokenVersion and set its value to 2.

Note that the change takes time to propagate.

Now, our Entrata app is ready for integration.

React SPA Client Application

This exercise will use a SPA project provided by Microsoft available at https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial/tree/main/2-Authorization/1-call-api-react/SPA. It uses MSAL library to authenticate the users and access secured APIs by acquiring security tokens from Microsoft Entrata.

SPA Modifications

We need to do several updates on the project.

Open authConfig.js.

Replace the clientId with the value of Application (client) Id that we have generated when we register the app in Entrata.

Update the value of authority using the Directory / Tenant Id.

Then to enable Graph V2 when signing in, we need to request access to the scope which we defined earlier.

In the same file authConfig.js, at the end of the file.

The SPA is now ready to login via SSO using Microsoft Entrata.

Backend Spring Service

We will start with an empty Spring Boot project and add each piece.

Maven Dependencies

We need to have at least the following. This project will exchange Entrata group mapping it to an internal role map to permissions as shown in the diagram above. The permissions will be used as roles.

Convert Entrata Group to Internal Roles

In this step, we will be using our internal tables where roles and permissions are stored. The Entrata group's UUID is searched in the auth_role table and the role's permissions are added as authorities to the JWT token.

This converter is used as the AuthenticationConverter when setting up the oauth2ResourceServer in the securityFilterChain. Furthermore, we need to set the resourceserver's issuer-uri in the application yml file. This URL will be used when validating the token.

Testing

To test the integration we will be creating a new controller with PreAuthorize annotated endpoints validating the authority bound to the JWT token.

To enable the method level security we need to annotate a configuration class with @EnableMethodSecurity.

Development and Support

The Spring project used in this tutorial is available at https://github.com/czetsuyatech/spring-ms-entrata-oauth.

Unlock the full coding experience! As a GitHub Sponsor, you gain exclusive access to the code behind this article—start learning and building today!

I'm available for contracting services and support. You can reach me at: https://www.czetsuyatech.com/p/consultation-services.html.

Spring Data JPA: Creating Dynamic Search Filters with Specifications

2025-03-04T15:27:00.000+08:00

1. Introduction

In this article, I will share an implementation that utilizes a common base class to streamline the process of implementing search functionality in Spring Data JPA using Specifications. By creating a reusable base class, you can efficiently manage and extend your search logic across multiple entities. This approach reduces redundancy and promotes cleaner, more maintainable code while allowing for dynamic query creation based on varying search criteria. Whether you're dealing with simple or complex filtering requirements, this solution will simplify your data querying layer in Spring applications.

2. Supported Operations

The following operations are supported:

greater than
less than
greater than or equal
less than or equal
equal
isnull
like

These operation will be listed as enum for easier reference.

3. Base Model

We will use a user entity to demonstrate the filter.

package com.czetsuyatech.persistence.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Table;
import lombok.Data;

@Table(name = "user_profile")
@Entity
@Data
public class UserEntity extends BaseEntity {

  @Column(name = "first_name")
  private String firstName;

  @Column(name = "last_name")
  private String lastName;

  @Column(name = "role")
  private String role;

  @Column(name = "age")
  private int age;
}

4. Class / Flow Diagram

As we can see above we will need a query builder that accepts UserSpecification and UserFields to generate the user entity specification that we need to feed to the UserRepository extending SliceJpaRepository, which is implemented by SimpleSliceJpaRepositoryImpl.

5. Repositories and Services

5.1 Anatomy of the user repository

@Repository
public interface UserRepository extends SliceJpaRepository<UserEntity, Long> {

}

@NoRepositoryBean
public interface SliceJpaRepository<ENTITY, ID extends Serializable> extends JpaRepository<ENTITY, ID>,
    JpaSpecificationExecutor<ENTITY>, JpaSpecificationExecutorWithProjection<ENTITY> {

  Slice<ENTITY> findAllSlice(@Nullable Specification<ENTITY> specification, Pageable pageable);
}

5.2 Query Builder

The query builder accepts the available filterable parameters of the user entity and the specification which define how we are going to implement the filter using criteria builder.

public enum UserSearchFields {

  FIRSTNAME {
    @Override
    public String toString() {
      return "firstName";
    }
  },
  LASTNAME {
    @Override
    public String toString() {
      return "lastName";
    }
  },
  ROLE {
    @Override
    public String toString() {
      return "role";
    }
  },
  AGE {
    @Override
    public String toString() {
      return "age";
    }
  }
}

@AllArgsConstructor
public class UserSpecification implements Specification<UserEntity> {

  private transient SearchCriteria criteria;

  @Override
  public Predicate toPredicate(Root<UserEntity> root, CriteriaQuery<?> query, CriteriaBuilder criteriaBuilder) {

    UserSearchFields key = UserSearchFields.valueOf(StringUtils.upperCase(criteria.getKey()));
    RelationalOperators operator = RelationalOperators.getOperator(criteria.getOperation());
    Object value = criteria.getValue();
    Expression<?> expression = root.<String>get(key.toString());

    Predicate predicate = null;

    switch (operator) {
      case LIKE -> predicate = buildLike(key, value, expression, criteriaBuilder);
      case EQUAL -> predicate = buildEqual(key, value, expression, criteriaBuilder);
      case GREATER, GREATER_THAN_EQUAL -> predicate = buildGreater(key, value, expression, criteriaBuilder);
      case LESS, LESS_THAN_EQUAL -> predicate = buildLess(key, value, expression, criteriaBuilder);
      default -> throw new IllegalStateException("Unexpected value: " + operator);
    }

    return predicate;
  }

  private Predicate buildLess(UserSearchFields key, Object value, Expression<?> expression,
      CriteriaBuilder criteriaBuilder) {

    return criteriaBuilder.lessThanOrEqualTo((Expression<Integer>) expression, Integer.parseInt(value.toString()));
  }

  private Predicate buildGreater(UserSearchFields key, Object value, Expression<?> expression,
      CriteriaBuilder criteriaBuilder) {

    return criteriaBuilder.greaterThanOrEqualTo((Expression<Integer>) expression, Integer.parseInt(value.toString()));
  }

  private Predicate buildEqual(UserSearchFields key, Object value, Expression<?> expression,
      CriteriaBuilder criteriaBuilder) {

    return criteriaBuilder.equal(expression, value);
  }

  private Predicate buildLike(UserSearchFields key, Object value, Expression<?> expression,
      CriteriaBuilder criteriaBuilder) {

    return criteriaBuilder.like((Expression<String>) expression,
        value.toString() + SpecificationConstant.LIKE_WILDCARD);
  }
}

5.3 The user service that invokes the repository.

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {

  private final UserRepository userRepository;
  private final UserMapper userMapper;

  @Transactional(readOnly = true)
  @Override
  public Slice<UserDTO> findUsers(String searchParams, Pageable pageable) {

    try {
      Specification<UserEntity> specResult = QueryBuilder.build(searchParams, UserSpecification.class,
          UserSearchFields.class);

      return userRepository.findAllSlice(specResult, pageable).map(userMapper::userToUserDTO);

    } catch (Exception e) {
      e.printStackTrace();
    }

    return new SliceImpl<>(Collections.emptyList());
  }
}

6. Controller

And this is how we are going to call the service from the controller.

@RequestMapping("/users")
@RestController
@RequiredArgsConstructor
@Slf4j
public class UserController {

  private final UserService userService;

  @GetMapping
  public ResponseEntity<Slice<UserDTO>> findUsers(@RequestParam(name = "search", required = false) String search,
      @PageableDefault Pageable pageable) {

    log.debug("Search: " + search);

    return ResponseEntity.ok(userService.findUsers(search, pageable));
  }
}

7. Postman Tests

8. Development and Support

Unlock the full coding experience! As a GitHub Sponsor, you gain exclusive access to the code behind this article—start learning and building today!

I'm available for contracting services and support. You can reach me at: https://www.czetsuyatech.com/p/consultation-services.html.

How to Handle Daylight Saving Time Conversion in Java

2024-12-07T08:27:00.000+08:00

Learn how to handle daylight saving time (DST) conversions in Java with clear, practical code examples. This guide focuses on using the right classes and methods to accurately convert dates and times across DST boundaries. Perfect for developers looking to simplify time zone management in their applications.

Code

Version 1

public class TimeZoneConversion {
    public static void main(String[] args) {
        // Example UTC date-time
        // String utcDateTimeStr = "2024-11-01T00:00:00";
		String utcDateTimeStr = "2024-03-24T00:00:00";
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss");
 
        // Parse UTC date-time
        LocalDateTime utcDateTime = LocalDateTime.parse(utcDateTimeStr, formatter);
 
        // Convert to UTC ZonedDateTime
        ZonedDateTime utcZonedDateTime = utcDateTime.atZone(ZoneId.of("UTC"));
 
        // Convert to Netherlands time zone
        ZonedDateTime netherlandsTime = utcZonedDateTime.withZoneSameInstant(ZoneId.of("Europe/Amsterdam"));
 
        // Format and print the result
        System.out.println("UTC Time: " + utcZonedDateTime);
        System.out.println("Netherlands Time: " + netherlandsTime.format(formatter));
    }
}

Version 2

public class TimeZoneConversion {
    public static void main(String[] args) {
		TimeZone tz = TimeZone.getTimeZone("Europe/Amsterdam");
		TimeZone.setDefault(tz);
		Calendar cal = Calendar.getInstance(tz, Locale.ITALIAN);
		DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm", Locale.ITALIAN);
		Date dateBeforeDST = df.parse("2018-03-25 01:55");
		cal.setTime(dateBeforeDST);
		cal.add(Calendar.MINUTE, 10);

		System.out.println(cal.get(Calendar.ZONE_OFFSET));
		System.out.println(cal.get(Calendar.DST_OFFSET));
	}
}

How to Create a Jasper Report from an XML Datasource: A Step-by-Step Guide

2024-06-09T16:37:00.000+08:00

1. Introduction

JasperReports is an open-source Java reporting tool that allows developers to create sophisticated reports for display, printing, or exporting into a variety of formats such as PDF, HTML, CSV, and others. It's widely used in Java-based applications for generating pixel-perfect reports with rich content like charts, tables, and images. JasperReports provides a flexible and customizable framework for designing and generating reports from various data sources, including databases, XML files, and custom data sources. It's often integrated into Java web applications and enterprise systems for generating dynamic and professional-looking reports.

2. Use Case

In this article, we will take a look at how Opencell an open-source billing platform integrates Jasper reports to generate its invoicing documents.

The goal of this exercise is to:

Generate a financial document (invoice) using Jasper reports.
Use a custom font.
Use an XML document.

Using XML as a data source in JasperReports can be ideal for several reasons:

Flexibility: XML is a highly flexible data format that can represent structured data in a hierarchical manner. This makes it suitable for a wide range of data sources, including relational databases, web services, and custom data structures.
Platform-agnostic: XML is platform-independent, meaning it can be easily generated and consumed by different programming languages and technologies. This makes it a versatile choice for integrating with various systems and applications.
Ease of Integration: Many applications and systems already generate or consume XML data, so using XML as a data source can simplify integration with existing infrastructure.
Customizability: XML allows developers to define custom data structures and schemas tailored to their specific reporting needs. This enables precise control over the data consumed by JasperReports and the structure of the resulting reports.
Separation of Concerns: Using XML as a data source promotes a clean separation between data and presentation layers. This separation allows for easier maintenance, scalability, and reuse of report templates across different datasets.
Performance: When properly optimized, XML processing can offer good performance characteristics for report generation. Techniques such as indexing, caching, and streaming can be employed to efficiently handle large XML datasets.

Overall, XML serves as a versatile and effective data source for JasperReports, offering flexibility, interoperability, and ease of integration with diverse data sources and systems.

3. Coding

We'll develop a Java application to produce a PDF invoice by utilizing a Jasper template sourced from an XML data provider.

3.1 XML Datasource

Our XML document is generated from Opencell that contains customer and usage information.

  <invoice customerAccountCode="CA_2000000021" customerId="CUST_2000000021" id="101"
    invoiceCounter="00000027" number="INV00000027" templateName="invoice" type="INV">
  <header>
    <provider code="CT" description="CZETSUYATECH">
      <bankCoordinates>
        <ics>FRXXZZZ123456</ics>
        <iban>FR763000600001123456790189</iban>
        <bic>CTDEFRPPCCT</bic>
      </bankCoordinates>
    </provider>
    <customer brand="" category="CLIENT" code="CUST_2000000021" externalRef1="" externalRef2=""
        id="565" jobTitle="" registrationNo="" sellerCode="CZETSUYATECH" vatNo="">
      <address>
        <address1/>
        <address2/>
        <address3/>
        <city/>
        <postalCode/>
        <state/>
        <country/>
        <countryName/>
      </address>
      <contact/>
    </customer>
    <seller code="CZETSUYATECH" description="CZETSUYATECH">
      <address>
        <address1/>
        <address2/>
        <address3/>
        <city/>
        <postalCode/>
        <state/>
        <country/>
        <countryName/>
      </address>
      <contact/>
    </seller>
    <customerAccount accountTerminated="false" code="CA_2000000021" currency="EUR"
        description="Edward's Account" externalRef1="" externalRef2="" id="566" jobTitle=""
        language="English" vatNo="xxx">
      <contact email="czetsuya@gmail.com" fax="" mobile="" phone="(303) 829-5342"/>
      <paymentMethod type="CHECK"/>
      <name>
        <quality/>
        <name>Edward's Account</name>
      </name>
      <address>
        <address1>1234 Balamb Garden</address1>
        <address2/>
        <address3/>
        <city>Los Banos</city>
        <postalCode>4030</postalCode>
        <state/>
        <country>PH</country>
        <countryName>Philippines</countryName>
      </address>
    </customerAccount>
    <billingAccount billingCycleCode="MONTHLY_POST_PAID" code="BA_2000000021"
        description="BA_2000000021" endPeriod="31/05/2024" externalRef1="" externalRef2="" id="567"
        jobTitle="" startPeriod="09/05/2024">
      <billingCycle code="MONTHLY_POST_PAID" description="Monthly Invoice Cycle" id="6">
      </billingCycle>
      <email>czetsuya@gmail.com</email>
      <name>
        <quality/>
        <name>Edward's Account</name>
      </name>
      <address>
        <address1>1234 Balamb Garden</address1>
        <address2/>
        <address3/>
        <city>Los Banos</city>
        <postalCode>4030</postalCode>
        <state/>
        <country>PH</country>
        <countryName>Philippines</countryName>
      </address>
      <message/>
      <billTo>
        <![CDATA[Edward's Account<br/>1234 Balamb Garden<br/>Los Banos, Laguna 4030<br/>PH]]>
      </billTo>
      <fees/>
      <charges licensePlate="NLEDW_LE2021"
          urlImage="https://czetsuyatech.com/PHEDW_LE2021.latest.jpg">
        <charge amount="-161.000000000000" date="05/28/24 19:45" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
        <charge amount="161.000000000000" date="5/9/24 9:29 AM" description="GoPlus"
            transactionId="566170"/>
        <charge amount="161.000000000000" date="5/10/24 7:52 AM" description="GoPlus"
            transactionId="566171"/>
      </charges>
      <topups/>
    </billingAccount>
    <invoiceDate>13/05/2024</invoiceDate>
    <dueDate>13/06/2024</dueDate>
    <paymentMethod>CHECK</paymentMethod>
    <comment>
    </comment>
    <categories>
      <category code="CLASSIC_USAGE" label="Service Usage">
        <amountWithoutTax>322.000000000000</amountWithoutTax>
        <subCategories>
          <subCategory amountWithoutTax="322.000000000000" code="CLASSIC_USAGE"
              label="Service Usage" taxCode="TAX_00" taxPercent="0.000000000000"/>
        </subCategories>
      </category>
    </categories>
    <discounts/>
    <locale>en-US</locale>
  </header>
  <amount>
    <currency>EUR</currency>
    <amountWithoutTax>322.000000000000</amountWithoutTax>
    <amountWithTax>322.000000000000</amountWithTax>
    <netToPay>322.000000000000</netToPay>
    <taxes total="0.000000000000">
      <tax code="TAX_00" id="1">
        <name>0 Percent Tax</name>
        <percent>0.000000000000</percent>
        <amount>0.000000000000</amount>
        <amountHT>322.000000000000</amountHT>
      </tax>
    </taxes>
  </amount>
  <detail>
    <userAccounts>
      <userAccount code="UA_2000000021" description="UA_2000000021" id="568" jobTitle="">
        <customFields>
          <customField code="CUSTOMER_NUMBER" description="Customer Number">1190017814</customField>
          <customField code="ACCOUNT_NUMBER" description="Account Number">2000000021</customField>
        </customFields>
        <subscriptions>
          <subscription code="SUBS_2000000021_NLEDW_LE2021_1590017830"
              description="SUBS_2000000021_NLEDW_LE2021_1590017830" id="309" offerCode="GoPlus">
            <subscriptionDate>13/10/2023</subscriptionDate>
            <endAgreementDate/>
          </subscription>
        </subscriptions>
        <name>
          <quality/>
          <firstName>Ed</firstName>
          <name/>
        </name>
        <address>
          <address1/>
          <address2/>
          <address3/>
          <city/>
          <postalCode/>
          <state/>
          <country/>
          <countryName/>
        </address>
        <categories>
          <category code="CLASSIC_USAGE" label="Service Usage">
            <amountWithoutTax>322.000000000000</amountWithoutTax>
            <subCategories>
              <subCategory amountWithoutTax="322.000000000000" code="CLASSIC_USAGE"
                  label="Service Usage" taxCode="TAX_00" taxPercent="0.000000000000">
                <line code="GoPlus_CT"
                    param1="fad4c36b-215a-308d-a19d-b6074543d414:fad4c36b-215a-308d-a19d-b6074543d414"
                    param2="1" param3="566170">
                  <walletOperation code="GoPlus_CT" periodEndDate="" periodStartDate=""/>
                  <paramExtra>USAGE</paramExtra>
                  <pricePlan code="GoPlus_CT" description="Price Plan for GoPlus CT"/>
                  <label>
                    GoPlus||EUR|1.0|0.00|161.00|161.00|0E-12|161.000000000000|161.000000000000|USE_TRX_PRICE
                  </label>
                  <unitAmountWithoutTax>161.000000000000</unitAmountWithoutTax>
                  <amountWithoutTax>161.000000000000</amountWithoutTax>
                  <quantity>1.000000000000</quantity>
                  <usageDate>09/05/2024</usageDate>
                  <edr accessCode="AP_2000000021_NLEDW_LE2021" dateParam1="" dateParam2=""
                      dateParam3="" dateParam4="" dateParam5="" decimalParam1="161.000000000000"
                      decimalParam2="" decimalParam3="" decimalParam4="" decimalParam5=""
                      eventDate="2024-05-09T09:29:46" originBatch="API_192.168.67.123"
                      originRecord="opencell.admin_1715247534640"
                      parameter1="fad4c36b-215a-308d-a19d-b6074543d414:fad4c36b-215a-308d-a19d-b6074543d414"
                      parameter2="1" parameter3="566170" parameter4="CHARGE_GoPlus_CT"
                      parameter5="VTOLL" parameter6="NLEDW_LE2021" parameter7=""
                      parameter8="USE_TRX_PRICE" parameter9="" quantity="1.000000000000"
                      rejectReason="" status="RATED"
                      subscription="SUBS_2000000021_NLEDW_LE2021_1590017830"/>
                </line>
                <line code="GoPlus_CT"
                    param1="fad4c36b-215a-308d-a19d-b6074543d414:fad4c36b-215a-308d-a19d-b6074543d414"
                    param2="1" param3="566171">
                  <walletOperation code="GoPlus_CT" periodEndDate="" periodStartDate=""/>
                  <paramExtra>USAGE</paramExtra>
                  <pricePlan code="GoPlus_CT" description="Price Plan for GoPlus CT"/>
                  <label>
                    GoPlus||EUR|1.0|0.00|161.00|161.00|0E-12|161.000000000000|161.000000000000|USE_TRX_PRICE
                  </label>
                  <unitAmountWithoutTax>161.000000000000</unitAmountWithoutTax>
                  <amountWithoutTax>161.000000000000</amountWithoutTax>
                  <quantity>1.000000000000</quantity>
                  <usageDate>10/05/2024</usageDate>
                  <edr accessCode="AP_2000000021_NLEDW_LE2021" dateParam1="" dateParam2=""
                      dateParam3="" dateParam4="" dateParam5="" decimalParam1="161.000000000000"
                      decimalParam2="" decimalParam3="" decimalParam4="" decimalParam5=""
                      eventDate="2024-05-10T07:52:12" originBatch="API_192.168.67.60"
                      originRecord="opencell.admin_1715327638732"
                      parameter1="fad4c36b-215a-308d-a19d-b6074543d414:fad4c36b-215a-308d-a19d-b6074543d414"
                      parameter2="1" parameter3="566171" parameter4="CHARGE_GoPlus_CT"
                      parameter5="VTOLL" parameter6="NLEDW_LE2021" parameter7=""
                      parameter8="USE_TRX_PRICE" parameter9="" quantity="1.000000000000"
                      rejectReason="" status="RATED"
                      subscription="SUBS_2000000021_NLEDW_LE2021_1590017830"/>
                </line>
              </subCategory>
            </subCategories>
          </category>
        </categories>
      </userAccount>
      <userAccount description="-">
        <categories/>
      </userAccount>
    </userAccounts>
  </detail>
  <offers>
    <offer code="GoPlus" description="GoPlus" id="1">
      <customFields>
        <customField code="CF_SHARED" description="Offer Shared">INDIVIDUAL</customField>
      </customFields>
    </offer>
  </offers>
  <services>
    <service code="CT" description="CT" offerCode="GoPlus"/>
  </services>
  <priceplans>
    <priceplan code="GoPlus_CT" description="Price Plan for GoPlus CT">
    </priceplan>
  </priceplans>
  <orders/>
  <qrCode
      value="xxx"/>
  <invoiceQRCodeEmail
      value="xxx"/>
  <summary currentBalance="-644.00" outstandingBalance="0.00" previousBalance="0.00"
      totalAmountDue="322.00"/>
</invoice>

As we can see the root of our document is "invoice" .

3.2 Jasper Dependencies

<dependency>
  <groupId>net.sf.jasperreports</groupId>
  <artifactId>jasperreports</artifactId>
  <version>6.21.0</version>
</dependency>
<dependency>
  <groupId>jaxen</groupId>
  <artifactId>jaxen</artifactId>
  <version>1.2.0</version>
</dependency>
<dependency>
  <groupId>org.apache.groovy</groupId>
  <artifactId>groovy</artifactId>
  <version>4.0.21</version>
</dependency>
<dependency>
  <groupId>net.sf.jasperreports</groupId>
  <artifactId>jasperreports-fonts</artifactId>
  <version>6.20.0</version>
</dependency>

3.3 Java Code

package com.czetsuyatech;

import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.StringWriter;
import java.net.URLClassLoader;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import net.sf.jasperreports.engine.DefaultJasperReportsContext;
import net.sf.jasperreports.engine.JRException;
import net.sf.jasperreports.engine.JRParameter;
import net.sf.jasperreports.engine.JRPropertiesUtil;
import net.sf.jasperreports.engine.JasperExportManager;
import net.sf.jasperreports.engine.JasperFillManager;
import net.sf.jasperreports.engine.JasperPrint;
import net.sf.jasperreports.engine.JasperReport;
import net.sf.jasperreports.engine.data.JRXmlDataSource;
import net.sf.jasperreports.engine.util.JRLoader;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.xml.sax.SAXException;

public class InvoiceReportGenerator {

  private final String jasperReportsPath;
  private ClassLoader cl;
  private String INVOICE_TAG_NAME = "invoice";

  public InvoiceReportGenerator(String jasperReportsPath, URLClassLoader cl) {

    this.jasperReportsPath = jasperReportsPath;
    this.cl = cl;
  }

  public void generate(String jasperPath, String xmlDataSource)
      throws IOException, ParserConfigurationException, SAXException, TransformerException, JRException {

    File jasperFile = new File(jasperReportsPath, jasperPath);
    String pdfFullFilename = jasperReportsPath + "/output.pdf";
    File invoiceXmlFile = new File(jasperReportsPath, xmlDataSource);
    Map<String, Object> parameters = getParameters();

    InputStream reportTemplate = new FileInputStream(jasperFile);
    Node invoiceNode = getInvoiceNode(invoiceXmlFile);

    JRXmlDataSource dataSource = new JRXmlDataSource(getJasperReportContext(invoiceNode), "/" + INVOICE_TAG_NAME);

    Map<String, JasperReport> jasperReportMap = new HashMap<>();

    String fileKey = jasperFile.getPath() + jasperFile.lastModified();
    JasperReport jasperReport = jasperReportMap.get(fileKey);
    if (jasperReport == null) {
      jasperReport = (JasperReport) JRLoader.loadObject(reportTemplate);
      jasperReportMap.put(fileKey, jasperReport);
    }

    DefaultJasperReportsContext context = DefaultJasperReportsContext.getInstance();
    JRPropertiesUtil.getInstance(context).setProperty("net.sf.jasperreports.xpath.executer.factory",
        "net.sf.jasperreports.engine.util.xml.JaxenXPathExecuterFactory");

    JasperPrint jasperPrint = JasperFillManager.fillReport(jasperReport, parameters, dataSource);

    JasperExportManager.exportReportToPdfFile(jasperPrint, pdfFullFilename);
  }

  private Node getInvoiceNode(File invoiceXmlFile)
      throws TransformerException, ParserConfigurationException, IOException, SAXException {

    DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
    DocumentBuilder db = dbf.newDocumentBuilder();
    dbf.setNamespaceAware(true);
    Document xmlDocument = db.parse(invoiceXmlFile);
    xmlDocument.getDocumentElement().normalize();
    Node invoiceNode = xmlDocument.getElementsByTagName(INVOICE_TAG_NAME).item(0);
    Transformer trans = TransformerFactory.newInstance().newTransformer();
    trans.setOutputProperty(OutputKeys.INDENT, "yes");
    StringWriter writer = new StringWriter();
    trans.transform(new DOMSource(xmlDocument), new StreamResult(writer));

    return invoiceNode;
  }

  private ByteArrayInputStream getJasperReportContext(Node invoiceNode) throws TransformerException {

    return new ByteArrayInputStream(getNodeXmlString(invoiceNode).getBytes(
        StandardCharsets.UTF_8));
  }

  private Map<String, Object> getParameters() {

    return new HashMap<>() {{
      put(JRParameter.REPORT_CLASS_LOADER, cl);
    }};
  }

  protected String getNodeXmlString(Node node) throws TransformerException {

    TransformerFactory transFactory = TransformerFactory.newInstance();
    Transformer transformer = transFactory.newTransformer();
    StringWriter buffer = new StringWriter();
    transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");
    transformer.transform(new DOMSource(node), new StreamResult(buffer));

    return buffer.toString();
  }
}

4. Resources

The complete source code is available at GitHub: https://github.com/czetsuyatech/jasperreports-xml-datasource

5. Development and Support

Unlock the full coding experience! As a GitHub Sponsor, you gain exclusive access to the code behind this article—start learning and building today!

I'm available for contracting services and support. You can reach me at: https://www.czetsuyatech.com/p/consultation-services.html.

Hands-on Coding: Spring Boot Common Exceptions Handling

2024-04-20T18:03:00.000+08:00

Overview

What is an exception?

An exception is an unexpected event, behavior, or state during software execution. In Java, it is a subclass of java.lang.Throwable.

In this diagram where a user withdraws money from an account the system throws an exception when the amount is less than or equal to the account balance.

Exception Class Diagram

In this diagram, we can see two types of Throwable.

Exception - recoverable
Error - unrecoverable

Exception VS RuntimeException

Exception - we need to declare the thrown exception in the method signature

public String readFromInputStream(InputStream inputStream) throws IOException {
  StringBuilder resultStringBuilder = new StringBuilder();
  try (BufferedReader br = new BufferedReader(new InputStreamReader(inputStream))) {
    String line;
    // BufferedReader.readLine throws IOException
    while ((line = br.readLine()) != null) {
      resultStringBuilder.append(line).append("\n");
    }
  }
  return resultStringBuilder.toString();
}

RuntimeException - there is no need to add the exception in the method signature

public void rtException() {
  int arr[] = null; // null array
  System.out.println("NullPointerException: " + arr.length);
}

In the calling block, we can catch the exception that was thrown.

try {
  readFromInputStream(is);
  rtException()
  
} catch (IOException ioe) {
  //
} catch (NullPointerException npe) {
  //  
}

Pre-Spring Boot 3

Before Spring Boot 3 there are several approaches on how we handle the exceptions. This article is opinionated so I will just list them for reference.

@ExceptionHandler annotation inside a controller
Implement HandlerExceptionResolver or extend AbstractHandlerExceptionResolver
Extending ResponseStatusException
Zalando exception handling library

Microservice

Microservice is a software architecture that builds products as collections of small services. Often, these services are powered by Spring Boot, and they interact with each other via HTTP calls through REST endpoints. Before Spring Boot 3, developers often used Zalando to wrap and handle exceptions, but Spring patched this gap and now provides an elegant solution.

https://microservices.io/patterns/microservices.html

In this diagram, we can see that the API gateway calls other services. And internal services can also call each other. During these calls it’s possible to encounter exceptions. That’s why it’s important to have a common library that we can add as a dependency and customize the errors based on the domain.

Commons Web Exceptions

Commons Web Exceptions is a project I created in Spring Boot 3, it is built around:

RestControllerAdvice - for centralizing the exceptions
ResponseEntityExceptionHandler - for providing the basic exception information structure
ErrorResponseException - for initializing an exception

In this image, all the classes and enums inside the blue block are part of the commons web exceptions library that we can use and extend in our service.

NativeWebExceptionEnumCodes - is an enum where native exceptions such as BAD_REQUEST, and INVALID_FORMAT are defined. In here, we can also add the class name of an exception in case we want to provide a specific code. Eg. HTTP_REQUEST_METHOD_NOT_SUPPORTED_EXCEPTION.
AbstractWebExceptions - is a container for all the native and service-defined exceptions that we can register by extending this class.
WebBaseException - a model class that extends ErrorResponseException. It provides the basic structure of the exception.
AbstractWebExceptionHandler - which extends the ResponseEntityExceptionHandler class. It gives us default handlers for the most common exceptions such as HttpRequestMethodNotSupportedException, HttpMediaTypeNotSupportedException, and HttpMediaTypeNotAcceptableException. In this class, we override some methods that will allow us to provide custom decorations to our exceptions. For example, when handling the invalid method argument exception we can list the errors (eg notNull) in the custom property "ERRORS".

Usage

In this section, I will provide some examples of how we can use this library.

Initializing the Library

Before we can define our custom exception handlers, we should extend the necessary base classes first.

1. Define the service's exception codes as enum. For example, in one of the services I have in Hivemaster, a custom Keycloak project that provides a multi-tenant feature.

@Getter
public enum AppExceptionCodes {

  USER_CREATION_FAILED("A1001", "Use creation failed"),
  USER_EID_NOT_FOUND("A1002", "User EID not found"),
  USER_EMAIL_NOT_FOUND("A1003", "User email not found"),
  USER_PHONE_NOT_FOUND("A1004", "User phone not found"),
  ORGANIZATION_NOT_FOUND("A1005", "Organization not found");

  private String code;
  private String message;

  AppExceptionCodes(String code, String message) {
    this.code = code;
    this.message = message;
  }

  public static Map<String, String> getMapValues() {

    Map<String, String> map = new LinkedHashMap<>();
    for (AppExceptionCodes errCode : values()) {
      map.put(errCode.getCode(), errCode.getMessage());
    }

    return map;
  }
}

2. Register the exception codes by extending the class AbstractWebExceptionCodes, so that they can be accessed by the commons-exception project.

@Component
public class WebExceptions extends AbstractWebExceptions {

  @Value("${spring.application.name}")
  private String serviceName;

  public WebExceptions() {

    super(HttpStatus.OK);

    registerExceptionMap(AppExceptionCodes.getMapValues());
  }

  @Override
  public String getServiceName() {
    return serviceName;
  }
}

3. Extend the WebBaseException class. So that we can handle business exceptions specific to the service. This class extends ErrorResponseException and RuntimeException which should be extended by the service exception classes. This will allow us to override the decoration that happens on the base WebBaseException class.

public class WebException extends WebBaseException {

  public WebException(HttpStatusCode status, String code) {
    this(status, code, null);
  }

  public WebException(HttpStatusCode status, String code, String message) {
    super(status, code, message);
  }
}

4. Extend the base exception handler AbstractWebExceptionHandler, which provides custom error handling and decoration for exceptions like method argument, runtime, invalid format, etc.

@Slf4j
@RestControllerAdvice
@RequiredArgsConstructor
public class WebExceptionHandler extends AbstractWebExceptionHandler {

  private final WebExceptions webExceptions;

  @Override
  public String getServiceName() {
    return webExceptions.getServiceName();
  }
}

5. And finally, import the library into your project.

@EnableConfigurationProperties
@SpringBootApplication
@Import({WebExceptionHandlerConfig.class})
public class Application {}

Use Cases

Once all of these are done, we can now begin customizing our exceptions.

1. Handling native exceptions such as method invalid argument.

Here are the possible results that we may get:

Using custom assertion

{
    "type": "http://localhost:8080/errors/S404",
    "title": "Bad Request",
    "status": 400,
    "detail": "Validation failed for fields (object:userV1, field:emailOrPhoneOnly, message:AssertTrue)",
    "instance": "/api/native-exceptions/method-arguments",
    "code": "S404",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:41:21.660650900Z",
    "errors": [
        "object:userV1, field:emailOrPhoneOnly, message:AssertTrue"
    ]
}

Missing field

{
    "type": "http://localhost:8080/errors/S404",
    "title": "Bad Request",
    "status": 400,
    "detail": "Validation failed for fields (object:userV1, field:organization, message:NotNull)",
    "instance": "/api/native-exceptions/method-arguments",
    "code": "S404",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:43:25.418080500Z",
    "errors": [
        "object:userV1, field:organization, message:NotNull"
    ]
}

Invalid format

{
    "type": "http://localhost:8080/errors/S401",
    "title": "Bad Request",
    "status": 400,
    "detail": "Invalid format for (field: birthdate, value: xxx, type: Instant)",
    "instance": "/api/native-exceptions/method-arguments",
    "code": "S401",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:43:44.065740700Z",
    "errors": [
        "field:birthdate, value:xxx, type:Instant"
    ]
}

Invalid date

{
    "type": "http://localhost:8080/errors/S404",
    "title": "Bad Request",
    "status": 400,
    "detail": "Validation failed for fields (object:userV1, field:birthdate, message:Past)",
    "instance": "/api/native-exceptions/method-arguments",
    "code": "S404",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:44:28.829450600Z",
    "errors": [
        "object:userV1, field:birthdate, message:Past"
    ]
}

Missing resource

{
    "type": "http://localhost:8080/errors/S405",
    "title": "Not Found",
    "status": 404,
    "detail": "No static resource native-exceptions/resource-not-found.",
    "instance": "/api/native-exceptions/resource-not-found",
    "code": "S405",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:44:44.294238700Z",
    "errors": []
}

Unsupported method

{
    "type": "http://localhost:8080/errors/S402",
    "title": "Method Not Allowed",
    "status": 405,
    "detail": "Method 'PUT' is not supported.",
    "instance": "/api/native-exceptions/method-arguments",
    "code": "S402",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:45:00.240704900Z",
    "errors": []
}

Forbidden

{
    "type": "http://localhost:8080/errors/S501",
    "title": "Forbidden",
    "status": 403,
    "instance": "/api/native-exceptions/forbidden",
    "code": "S501",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:45:20.566494300Z",
    "errors": []
}

Exception defined in our service exception enum which could be business, application, or entity.

{
    "type": "http://localhost:8080/errors/A1001",
    "title": "Use creation failed",
    "status": 400,
    "instance": "/api/service-exceptions/users/exceptions",
    "code": "A1001",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:55:49.061434900Z",
    "errors": []
}

Custom exception

{
    "type": "http://localhost:8080/errors/B1001",
    "title": "Business exception",
    "status": 400,
    "detail": "Custom exception message",
    "instance": "/api/service-exceptions/users/custom-exceptions",
    "code": "B1001",
    "service": "commons-web-exception-client",
    "timestamp": "2024-04-20T09:56:30.612646200Z",
    "errors": []
}

Git Repository

Once again the repositories are available in GitHub.

Development and Support

Unlock the full coding experience! As a GitHub Sponsor, you gain exclusive access to the code behind this article—start learning and building today!

I'm available for contracting services and support. You can reach me at: https://www.czetsuyatech.com/p/consultation-services.html.

Hands on Coding: Spring Logging for Beginners

2024-04-06T17:36:00.000+08:00

1. Overview

Logging is a vital aspect of programming for both beginners and experts, often underestimated but crucial for understanding application behavior. Strategic placement of logging statements aids in debugging and comprehending program execution, especially in production environments.

This tutorial is hands-on so I'll just paste the reference for you: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.logging

2. Hands-On Coding

Logging is available out-of-the-box from Spring, but we can customize its level, format, etc as defined in the document above.

I created a Spring Boot project to capture the behavior of the logging levels that you can use as a reference as you code.

2.1 Common Logging Interface

Let's introduce an interface that we will implement with different logging-level classes. The method logLevels will print all the logs applicable to a particular package.

package com.czetsuyatech.logger;

import org.slf4j.Logger;

public interface LoggerComponent {

  default void logLevels() {
    System.out.println(getClass().getPackageName() + ": " + "-".repeat(50));

    getLogger().info("Hello World");
    getLogger().debug("Hello World");
    getLogger().warn("Hello World");
    getLogger().trace("Hello World");
    getLogger().error("Hello World");
  }

  Logger getLogger();
}

2.2 Configure Package Names

We will define the following packages.

debug
error
info
trace
warn

For each package, we need to define a concrete class of interface LoggerComponent

For example, in the debug we will have something like:

@Component
@Slf4j
public class DebugLogger implements LoggerComponent {

  @Override
  public Logger getLogger() {
    return log;
  }
}

2.3 Spring Boot Application Class

We will inject the instances of LoggerComponent in a list so that we can iterate through each component. We will call the logLevels method to print the log.

@SpringBootApplication
@RequiredArgsConstructor
public class Application {

  private final List<LoggerComponent> loggers;

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

  @EventListener
  public void onStartup(ContextRefreshedEvent event) {

    loggers.stream().forEach(LoggerComponent::logLevels);
  }
}

2.4 Spring Configuration File

And finally, we will configure the log level per package.

logging:
  level:
    root: info
    com.czetsuyatech.logger.info: info
    com.czetsuyatech.logger.debug: debug
    com.czetsuyatech.logger.warn: warn
    com.czetsuyatech.logger.trace: trace
    com.czetsuyatech.logger.error: error

We should have the following logs in our console which should pretty much explain the logging behavior. For example, error level only prints errors, while debug prints info, warn, and error as well.

3. When to Use Each Logger

There is no standard on how and when to use the different logging levels. In my own experience, this is how I use them. Coupled with proper package structure, so I can control the logging level of a particular process.

Info

- Informational messages without state such as component startup and configuration settings.

Warn

- Informational state that can be ignored by the system.

- Example: An unknown status of an entity.

Debug

- Informational events with state that are useful for developers. I use this in public methods.

- Example: Controller endpoints and service methods.

Trace

- Informational events with state that are useful for developers. I use this in private methods.

- Example: Private methods in a service.

Error

- Event that causes the application to get into an error state. Recoverable.

- Example: Unable to communicate to an external service. Having a mechanism to retry sending the message.

Fatal

- Event that causes the application to get into an error state. Unrecoverable.

- Example: Database instance going down.

4. Code Repository

The code is available at https://github.com/czetsuya/lab-spring-logging.

Hands on Coding: Spring Metrics with Prometheus for Beginner

2024-04-06T10:53:00.000+08:00

1. Overview

Welcome to our hands-on guide where we'll delve into the world of monitoring Spring Boot applications using Prometheus and Grafana. In today's fast-paced digital landscape, ensuring the smooth operation and performance of our applications is paramount. With the powerful combination of Prometheus and Grafana, we can gather insightful metrics and visualize them in a meaningful way, allowing us to monitor and optimize our Spring Boot applications effectively.

In this guide, we'll walk through the process step-by-step, covering everything you need to know to set up basic monitoring for your Spring Boot 3 application with Docker.

2. Spring Boot 3 Application

The Spring Boot project contains the basic configuration needed for demonstration.

2.1 Dependencies

We need the actuator to expose the Spring metrics and use the micrometer registry to convert it to Prometheus.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

2.2 Configuration

In this section, we allow health and Prometheus endpoints from the actuator. By default, the actuator endpoint is/actuator, which lists all the enabled endpoints.

logging:
  level:
    root: info

server:
  port: 8080

spring:
  application:
    name: lab-spring-prometheus

management:
  endpoints:
    web:
      exposure:
        include: health, prometheus
  endpoint:
    health:
      show-details: always
  prometheus:
    metrics:
      export:
        enabled: true

3. Prometheus

In Prometheus configuration, we need to specify the metrics path and set some labels that we will need in our Grafana dashboard later.

Note: If you want to scrape data from a Spring Boot app that runs on your IDE, you must change the targets to host.docker.internal. Don't forget to update the extra_hosts in the docker-compose file as well.

scrape_configs:
  - job_name: 'lab-spring-prometheus'
    metrics_path: '/actuator/prometheus'
    scrape_interval: 5s
    static_configs:
      #      - targets: [ 'host.docker.internal:8080' ]
      - targets: [ 'spring-app:8080' ]
        labels:
          namespace: czetsuyatech
          application: 'lab-spring-prometheus'

4. Grafana

4.1 Spring Boot Statistics

If you want a Spring Boot statistics dashboard out of the box you may check the following plugin in Grafana's marketplace. Or simply, import them.

19004 - https://grafana.com/grafana/dashboards/19004-spring-boot-statistics/
11378 - https://grafana.com/grafana/dashboards/11378-justai-system-monitor/

For Grafana, we can start with a basic data source configuration. This points to the Prometheus URL we define in docker-compose. Note that you can also do this in the Grafana user interface.

Grafana's default username and password is "admin".

apiVersion: 1
datasources:
  - name: Lab Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true

5. Docker Configuration

5.1 Dockerfile

We are loading the Spring Boot jar to our docker container. Make sure to build the project first in your IDE, so that the jar is generated.

FROM eclipse-temurin:17-jdk-alpine
VOLUME /tmp
COPY ./target/*.jar app.jar
ENTRYPOINT ["java","-jar","/app.jar"]

5.2 Docker Compose File

This configuration runs our Spring boot app, Prometheus, and Grafana in docker with a common network. Thus, each service can access each other using the service name. If you want to access a non-docker component, let's say the Spring Boot app, you need to do the necessary configuration with the host.

version: '3.8'

networks:
  backend:

services:
  spring-app:
    build:
      dockerfile: docker/Dockerfile
      context: ../
    ports:
      - "8080:8080"
    networks:
      - backend

  prometheus:
    image: prom/prometheus:v2.51.1
    container_name: lab-prometheus
    restart: no
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
    networks:
      - backend
#    extra_hosts:
#      - 'host.docker.internal:host-gateway'

  grafana:
    image: grafana/grafana
    container_name: lab-grafana
    restart: no
    ports:
      - "3000:3000"
    volumes:
      - ./grafana/datasources:/etc/grafana/provisioning/datasources
    networks:
      - backend

To run, simply go to docker folder of this project and execute: docker-compose up --build

6. GitHub Repository

The code is available in GitHub including the docker-compose file.

https://github.com/czetsuyatech/lab-spring-prometheus

7. Development and Support

Unlock the full coding experience! As a GitHub Sponsor, you gain exclusive access to the code behind this article—start learning and building today!

I'm available for contracting services and support. You can reach me at: https://www.czetsuyatech.com/p/consultation-services.html.

How to Transfer Money from Coins PH to Binance

2024-03-24T09:27:00.000+08:00

1. Introduction

Worried about the risk of falling victim to scams while engaging in peer-to-peer (P2P) transactions for buying and selling coins? While there are several strategies to mitigate this risk, it's important to note that transfer fees can often be costly. One platform I've found to have reasonable transfer fees is ARBITRUM. For this exercise, let's consider transferring a USDT coin from Coins PH to Binance.

For this exercise, you need a Binance and Coins PH accounts.

2. Preferring for Transfer - Binance

We need to get the USDT wallet address in preparation for the transfer.

2.1 From the menu, select Spot.

2.2 Find the USDT coin, click the "..." menu, and select "Deposit."

2.3 Select the ARBITRUM network and copy the deposit address.

3. Making the Transfer in Coins PH

3.1 Go to your account portfolio. Find USDT and select Send USDT.

3.2 Select the Arbitrum network to match what we selected from Binance.

3.3 Specify the amount that you want to send.

3.4 You will be presented with a list of checklists, once verified press "I Understand".

3.5 In the next screen, you will be asked to confirm your transaction details.

3.6 The next step would be for you to validate the transaction by entering the security code sent via email.

3.7 The transaction will be processed, and you should receive a successful message after a minute or two.

This process works the opposite way (Binance -> Coins PH).

4. Disclaimer

The transaction fee is subject to change without prior notice. Therefore, verifying the current rate beforehand and conducting a test transfer before proceeding with a large amount is essential.

Hands-On Coding: Exploring Hyperparameters for Programmers

2024-03-07T08:44:00.000+08:00

Introduction

In this article, we will explore different techniques for finding the optimal hyperparameter values from a given set of parameters in a grid. Particularly we will look at RandomizedSearchCV, GridSearchCV, and BayesSearchCV.

In this blog you will learn:

How to initialize the parameter grid.
How to find the optimal hyperparameters based on a given technique.
How to build a model (XGBClassifier) to use the hyperparameters.
How to score the performance of the model.

RandomizedSearchCV

param_grid = {
    "gamma": [0, 0.1, 0.2, 0.5, 1, 1.5, 2, 3, 6, 12, 20],
    "learning_rate": [0.01, 0.02, 0.03, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 0.8],
    "max_depth": [1, 2, 3, 4, 5, 6, 8, 12],
    "n_estimators": [25, 50, 65, 80, 100, 115, 200]
}

grid_search = RandomizedSearchCV(estimator=classifier_0, param_distributions=param_grid, scoring=scoring)

GridSearchCV

param_grid = {
    "gamma": [0, 0.1, 0.2, 0.5, 1, 1.5, 2, 3, 6, 12, 20],
    "learning_rate": [0.01, 0.02, 0.03, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 0.8],
    "max_depth": [2, 3, 4, 5, 6, 8, 12],
    "n_estimators": [25, 50, 65, 80, 100, 115, 200]
}

grid_search = GridSearchCV(estimator=classifier_0, param_grid=param_grid, scoring=scoring)

BayesSearchCV

param_bayes = {
    'gamma': Categorical(param_grid['gamma']),
    'learning_rate': Categorical(param_grid['learning_rate']),
    'max_depth': Categorical(param_grid['max_depth']),
    'n_estimators': Categorical(param_grid['n_estimators'])
}

grid_search = BayesSearchCV(estimator=classifier_0, search_spaces=param_bayes, scoring=scoring, n_jobs=-1, cv=10)

Finding the Best HyperParameters

best_model = grid_search.fit(X_train, y_train)
hyperparams = best_model.best_params_

Building and Scoring the Classifier using the HyperParameters

# Fitting the Model
ne = hyperparams['n_estimators']
lr = hyperparams['learning_rate']
md = hyperparams['max_depth']
gm = hyperparams['gamma']
print("Recommended Params >>", f"ne: {ne},", f"lr: {lr}", f"md: {md}", f"gm: {gm}")

# Build Classification Model
classifier_1 = XGBClassifier(
    base_score=0.5,
    colsample_bylevel=1,
    colsample_bynode=1,
    objective=objective,
    booster="gbtree",
    eval_metric=eval_metric_list,
    n_estimators=ne,
    learning_rate=lr,
    max_depth=md,
    gamma=gm,
    subsample=0.8,
    colsample_bytree=1,
    random_state=1
)

# Fit Model
eval_set = [(X_train, y_train)]
classifier_1.fit(
    X_train,
    y_train,
    eval_set=eval_set,
    verbose=False
)

# Get predictions for training data
train_yhat = classifier_1.predict(X_train)
print("Training Preds: \n", train_yhat[:5])

# Set K-Fold Cross Validation Levels
cv = RepeatedStratifiedKFold(n_splits=5, n_repeats=3, random_state=1)

# Training Results
train_results = cross_val_score(classifier_1, X_train, y_train, scoring=scoring, cv=cv, n_jobs=1)

# Brief Review of Training Results
print("Average Accuracy K-Fold: ", round(train_results.mean(), 2))
print("Std Deviation K-Fold: ", round(train_results.std(), 2))
print("Precision Score 0: ", round(precision_score(y_train, train_yhat, average=None)[0], 3))
print("Precision Score 1: ", round(precision_score(y_train, train_yhat, average=None)[1], 3))

Performance

Machine: Laptop

Processor: AMD Ryzen 7

OS: Windows

DataFrame Shape: (7282, 17)

Technique	Time (s)	Avg Accuracy K-Fold	Std Deviation K-Fold	Precision Score: 0	Precision Score: 1
RandomizedSearchCV	17.02	0.54	0.07	0.576	0.601
BayesSearchCV	105.39	0.52	0.05	0.589	0.568
GridSearchCV	9413.60	0.53	0.06	0.605	0.623

Understanding How Scope Affects Values in Your Spring REST Controller

2024-03-02T11:29:00.000+08:00

Below we explore how a scope annotation affects an instance value in a Spring REST controller.

Each controller is annotated with scope.

@RestController
@Scope([SCOPE_VALUE])
public class XXXScopeController {}

How to Convert Vertically Stored Asset Data into Columnar Format for Cointegration Analysis

2024-02-24T17:05:00.000+08:00

Introduction

This piece of code fetches asset information from a table stored vertically.

Dependencies

Install the following package.

conda install pandas
conda install numpy as np
conda install mysql-connector-python
conda install sqlalchemy
conda install pymysql

Hands-on Coding

Connect to the database

def query_df(query):
    try: 
        engine_uri = f"mysql+pymysql://db_user:db_pass_123@localhost:3306/tradewise_pse"
        db_conn = create_engine(engine_uri)        
        df_result = pd.read_sql(query, db_conn)    
        return df_result
        
    except Exception as e:    
        print(str(e))

Fetching the Dataset

if not load_existing:
    sql_distinct_tickers = "select ticker from candlestick where event_time='2023-12-29' and ticker not like '^%%'"
    df_tickers = query_df(sql_distinct_tickers)
    
    df = pd.DataFrame(index=['event_time'])
    
    ### Get the candlesticks
    for ticker in df_tickers['ticker']:
        sql_ticker_col = "select event_time, close from candlestick where ticker='{0}'"
        df_temp = query_df(sql_ticker_col.format(ticker))
        df_temp.set_index('event_time', inplace=True)
        df_temp.rename(columns={'close': ticker}, inplace=True)        
        df = df.add(df_temp, fill_value=0)
        
    df.to_csv(file_name)

Load the dataset from file

df = pd.read_csv(file_name, index_col=0)
df.drop(index=df.index[-1],axis=0, inplace=True)

Drop NA

df.dropna(axis=1, inplace=True)

Print the dataset

print(f"Shape: {df.shape}")
print(f"Null values: {df.isnull().values.any()}")
df

Save to a file

df.to_csv(file_name)

This procedure is in preparation for cointegration testing.

Learn to Incorporate Rolling Hurst Values into Your DataFrame

2024-02-24T16:38:00.000+08:00

The hurst function.

def hurst(ts, min_lag=1, max_lag=7):
    lags = range(min_lag, max_lag)
    tau = [np.sqrt(np.std(np.subtract(ts[lag:], ts[:-lag]))) for lag in lags]
    poly = np.polyfit(np.log(lags), np.log(tau), 1)
    return poly[0]*2.0

Adding to our DataFrame

The hurst value is computed with the last 14 close values.

df['Hurst'] = df['close'].rolling(14).apply(hurst, raw=True)
df[10:20]

Implementing Glowroot: A Hands-On Tech Review for Application Monitoring Mastery

2024-02-01T15:48:00.000+08:00

1. Introduction

In the realms of information technology and systems management, Application Performance Management (APM) involves monitoring and overseeing the performance and availability of software applications. APM aims to identify and diagnose intricate application performance issues to uphold a predefined level of service.

Glowroot is an open-source APM that facilitates a quicker resolution of application performance issues by helping us pinpoint the root causes. It supports applications running from Java 6 onwards.

2. Key Features

Response Time Breakdown Charts: Visualizes the breakdown of response times for better analysis.
Response Time Percentile Charts: Offers percentile charts to understand response time distribution.
SQL Capture and Aggregation: Captures and aggregates SQL queries for in-depth analysis.
Service Call Capture and Aggregation: Gathers and aggregates data on service calls for comprehensive insights.
MBean Attribute Capture and Charts: Monitors and charts MBean attributes for performance evaluation.
Configurable Alerting: Allows users to configure alerts based on specific criteria.
Historical Rollup: Provides historical data rollup at different intervals (1m, 5m, 30m, 4h) with configurable retention settings.
Full Support for Async Requests: Supports asynchronous requests that span multiple threads.
Responsive UI with Mobile Support: User-friendly and responsive interface with mobile support for accessibility.
Optional Central Collector: Offers the flexibility of an optional central collector for centralized data management.
Supports Multiple Application Servers: Wildfly, JBoss EAP, Tomcat, TomEE, Jetty, Glassfish, Payara, WebLogic, WebSphere

3. Central Collector

The central collector collects runtime information from the registered services and offers a GUI for easy viewing. https://github.com/glowroot/glowroot/wiki/Central-Collector-Installation

3.1 Installation

You can follow the steps above for running the GlowRoot central collector either as a standalone or as a docker image. For this section, I'll share how it can be run locally.

Here's my docker-compose file for running glowroot-central with cassandra. Override username, password, and contactPoints in glowroot-central.properties.

  version: '3.8'

networks:
  tradewise-network:

services:
  cassandra:
    image: cassandra:latest
    container_name: cassandra
    restart: unless-stopped
    ports:
      - "9042:9042"
    networks:
      - tradewise-network

  glowroot-central:
    image: glowroot/glowroot-central:0.14.1
    container_name: glowroot-central
    restart: unless-stopped
    volumes:
      - ./glowroot-central.properties:/usr/share/glowroot-central/glowroot-central.properties
    depends_on:
      - cassandra
    ports:
      - "4000:4000"
      - "8181:8181"
    networks:
      - tradewise-network

4. Instrumentation

There are 4 ways in which we can integrate GlowRoot into our services https://glowroot.org/instrumentation.html. For this exercise, we will focus on using the agent API.

4.1 Editing the pom.xml File

In our Spring Boot project's pom.xml file, add the GlowRoot agent configuration.

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-resources-plugin</artifactId>
	<executions>
		<execution>
			<id>glowroot-plugins</id>
			<phase>validate</phase>
			<goals>
				<goal>copy-resources</goal>
			</goals>
			<configuration>
				<outputDirectory>target/glowroot-plugins/</outputDirectory>
				<resources>
					<resource>
						<directory>glowroot-plugins</directory>
						<filtering>false</filtering>
					</resource>
				</resources>
			</configuration>
		</execution>
	</executions>
</plugin>

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-dependency-plugin</artifactId>
	<version>${maven-dependency-plugin.version}</version>
	<executions>
		<execution>
			<id>copy-glowroot-jar</id>
			<phase>prepare-package</phase>
			<goals>
				<goal>copy</goal>
			</goals>
		</execution>
	</executions>
	<configuration>
		<artifactItems>
			<artifactItem>
				<groupId>org.glowroot</groupId>
				<artifactId>glowroot-agent</artifactId>
				<version>${glowroot-agent.version}</version>
				<type>jar</type>
				<overWrite>false</overWrite>
				<outputDirectory>${project.build.directory}</outputDirectory>
				<destFileName>glowroot.jar</destFileName>
			</artifactItem>
		</artifactItems>
	</configuration>
</plugin>

4.2 Preparing the Dockerfile

We need to add the GlowRoot files in the docker image.

# Base Image
FROM eclipse-temurin:17-jdk-alpine
LABEL author=CzetsuyaTech
LABEL maintainer=CzetsuyaTech

# Configuration
WORKDIR /

RUN addgroup --system czetsuyatech && \
    adduser --system czetsuyatech --ingroup czetsuyatech && \
    mkdir -p /glowroot /glowroot/tmp /glowroot/logs /glowroot/plugins && \
    echo '{ "web": { "bindAddress": "0.0.0.0" } }' > /glowroot/admin.json && \
    chown czetsuyatech:czetsuyatech -R /glowroot && \
    chmod -R 777 /glowroot

USER czetsuyatech
ADD --chown=czetsuyatech:czetsuyatech target/glowroot.jar /glowroot
ADD --chown=czetsuyatech:czetsuyatech target/glowroot-plugins /glowroot/plugins

# Service
ADD --chown=czetsuyatech:czetsuyatech target/*.jar app.jar

# Start
ENV JAVA_JAR "/app.jar"
ENV JAVA_OTHERS "-Xshare:off"
ENV JAVA_OPTS ${JAVA_OPTS}
ENV JAVA_MEM ${JAVA_MEM}

RUN echo "exec java $JAVA_MEM $JAVA_OPTS $JAVA_OTHERS -jar $JAVA_JAR"
ENTRYPOINT exec java $JAVA_MEM $JAVA_OPTS $JAVA_OTHERS -jar $JAVA_JAR

4.3 Running the Spring Boot Service

To enable instrumentation in our instance, we need to specify the javaagent property. And to send information to the central collector we need to specify the central collector and give our instance an agent id.

JAVA_OPTS=-javaagent:glowroot/glowroot.jar -Dglowroot.collector.address=localhost:8181 -server -Dglowroot.agent.id=TradewiseAI

5. GUI

5.1 Usage

5.2 Transactions

5.2.1 Web

To assess our REST Endpoints' performance, we access the "Web" section. In the provided example:

By choosing "Response Time," we can identify which HttpRequests and JDBC Queries are taking longer in the REST Endpoints.
Opting for "Slow Traces" allows us to pinpoint the specific endpoint that consumes more time.
Selecting "Queries" reveals insights into the queries made, indicating that using the count query is more resource-intensive compared to the select query. This information aids in optimizing and refining the performance of REST Endpoints.

5.2.2 Background

To analyze our background performance, we navigate to the "Background" section. In the given example:

Choosing "Response Time" allows us to identify which Job and Hibernate Queries are consuming more time in the background processes.
Opting for "Slow Traces" reveals that some calls take more time, providing insights into areas that may require attention.
Selecting "Queries" and filtering by the select query, we observe that it is called more frequently and takes longer, particularly when filtered by status. This information helps in understanding and addressing potential bottlenecks in the background processes.

5.2.3 Startup

To assess our startup performance, we can utilize the "Startup" section. In the provided example:

By choosing "Response Time," we can identify which startup and filter init processes consume more time.
Opting for "Slow Traces" reveals the duration it takes for the context to initialize fully.
Selecting "Queries" provides insights into the database queries. Some queries will be more resource intensive, with fewer calls but longer duration. This information aids in pinpointing specific areas for optimization within the startup processes.

5.3 Errors

5.3.1 Web

To visualize errors in our REST endpoints, we can navigate to the "Web" section. In the following example:

Choosing "Error Messages" reveals errors of type XXXException.
Opting for "Error Traces" provides details on the errors.
Clicking on a specific error allows us to view the detailed trace, aiding in the understanding and resolution of the issue.

5.4 JVM

In our services' JVM, we can monitor and analyze memory status. This allows us to gain insights into the memory usage patterns, allocations, and overall health of the Java Virtual Machine, aiding in the effective management and optimization of our services.

5.5 MBeanTree

The MBeanTree functionality in Glowroot proves invaluable in monitoring instance creation. For instance, to track thread-related metrics and identify potential Thread Leaks, users can navigate to the java.lang section, specifically under Threading. This allows for a detailed examination of thread-related information, aiding in the identification and resolution of potential thread-related issues, such as Thread Leaks.

6. Recommendation

In a typical product infrastructure, Glowroot serves as our APM tool in each microservice. All microservices are instrumented to gather and transmit data to Glowroot, enhancing our understanding of system behavior. We've chosen Glowroot based on various criteria, including its license-free nature, alignment with the Java ecosystem, and straightforward instrumentation for microservices, ensuring a simple ramp-up and configuration process.

Navigating the Code: A Guide to Environment Variables, Configuration, and Feature Flags

2023-12-14T08:00:00.000+08:00

Determining the optimal location for storing essential information crucial for an application's functionality necessitates thoughtful planning. This guide aims to assist you in making informed decisions about where to store crucial data. Here, the term "application" encompasses any software created with code and deployed on various platforms and runtimes, irrespective of the underlying software architecture.

A fundamental principle is to avoid hard-coding any values within your application. Instead, adopt the practice of retrieving all configuration settings from a distinct storage system, separate from the deployment environment. This approach allows for seamless modifications to configuration settings even after the application has been deployed, eliminating the need for redeployment. This separation ensures greater flexibility and facilitates the adjustment of critical parameters without disrupting the operational state of your deployed application.

When considering the storage location for key/value pairs, it's crucial to evaluate the volatility of each pair—how frequently and by whom it might undergo changes. Reflect on the dynamic nature of the data and the responsibilities associated with its modification. This thoughtful approach will guide you in choosing an appropriate storage solution that aligns with the specific needs and characteristics of each key/value pair. By understanding the frequency and ownership of potential changes, you can make informed decisions that optimize the efficiency and maintainability of your data storage strategy.

Environment Variables

Environment variables, characterized by their infrequent changes, typically occur only once per deployment. Common examples include sensitive information like usernames and passwords for databases, which are often stored securely in a Vault. Additionally, environment variables encompass essential details required for the system's initialization, such as environment specifics and the connection details for the application configuration store, which hosts additional settings. By utilizing environment variables for these foundational aspects, you ensure a secure and stable system setup while centralizing critical configuration information.

Application Configuration

Application configuration, in contrast to environment variables, operates independently of deployments. It encompasses supplementary settings for the system that have the potential to change between deployments at runtime. This flexibility allows for real-time adjustments to the application's behavior and features, accommodating evolving requirements without the need for redeployment. By leveraging application configuration for these dynamic settings, you establish a modular and adaptable structure, enhancing the responsiveness of your system to changing runtime conditions.

Runtime User Settings

Runtime user settings represent the most volatile category, as users can alter any key/value pair at any given moment. Therefore, the system must be designed to accommodate this high level of dynamism. Options for handling such volatility include implementing robust real-time validation mechanisms and ensuring the integrity and security of user-initiated changes. Additionally, the system should provide an intuitive user interface for managing these settings, enabling seamless customization while maintaining overall system stability and security.

Here are three options for handling configuration updates:

Re-read Configuration All the Time: Continuously monitor and re-read the configuration, ensuring that the system remains up-to-date with any changes. This approach provides real-time responsiveness to modifications but may impose a continuous processing overhead.
Re-read Configuration at Set Intervals (e.g., Every 15 Minutes): Implement a periodic schedule to re-read the configuration at predefined intervals, such as every 15 minutes. This approach balances responsiveness with reduced processing overhead, making it suitable for scenarios where near-real-time updates are acceptable.
Receive Push Notifications When New Application Configuration Is Available: Set up a push notification mechanism to alert the system when new application configuration becomes available. This approach minimizes the need for continuous or scheduled re-reading, optimizing efficiency by updating the system only when changes occur. However, it requires a reliable notification infrastructure. Choosing among these options depends on the specific requirements of your system, considering factors such as the criticality of real-time updates, resource constraints, and the overall responsiveness desired for configuration changes.

Navigating Software and Systems Architecture: A Curated Collection of Resources

2023-12-11T18:18:00.000+08:00

These books serve as valuable references for building software systems:

Martin Fowler: Patterns of Enterprise Application Architecture

Robert C. Martin: Clean Architecture: A Craftsman's Guide to Software Structure and Design

Martin Kleppmann: Designing Data-Intensive Applications: The Big Ideas Behind Reliable, Scalable, and Maintainable Systems

Len Bass, Paul Clements, Rick Kazman: Software Architecture in Practice

Gregor Hope: Enterprise Integration Patterns

Erich Gamma: Design Patterns

Chris Richardson: Microservice Patterns

Mark Richards: Fundamentals of Software Architecture

Mark Masse: REST API Design Rulebook: Designing Consistent RESTful Web Service Interfaces and here

Matthew Skelton: Team Topologies

Svyatoslav Kotusev: The Practice of Enterprise Architecture: A Modern Approach to Business and IT Alignment

Websites

https://microservices.io - online version of Chris Richardsons' book
https://www.enterpriseintegrationpatterns.com/patterns/messaging - online version of Gregor Hopes book

Personalized Spring Boot Startups: Custom Banners and Build Information

2023-09-07T20:42:00.000+08:00

1. Overview

By default, when a Spring Boot application starts, it displays a banner. In this article, we will explore the process of creating a custom banner and utilizing it within Spring Boot applications.

2. Creating a Banner

Before we begin, it's essential to generate the custom banner, which will appear during the application startup process. You can choose to create the custom banner from scratch or leverage various tools designed for this purpose.

In this example, we are generating CzetsuyaTech's logo from https://devops.datenkollektiv.de/banner.txt/index.html.

Create a new file "banner.txt" inside the resources folder and copy and paste this content. This will print a colored banner with application information.

${AnsiColor.BLUE}  _____ ${AnsiColor.WHITE}         _                          ${AnsiColor.BLUE} _______       ${AnsiColor.WHITE}  _
${AnsiColor.BLUE} / ____|${AnsiColor.WHITE}        | |                         ${AnsiColor.BLUE}|__   __|      ${AnsiColor.WHITE} | |
${AnsiColor.BLUE}| |     ${AnsiColor.WHITE} _______| |_ ___ _   _ _   _  __ _  ${AnsiColor.BLUE}   | |${AnsiColor.WHITE}  ___  ___| |__
${AnsiColor.BLUE}| |     ${AnsiColor.WHITE}|_  / _ \ __/ __| | | | | | |/ _` | ${AnsiColor.BLUE}   | |${AnsiColor.WHITE} / _ \/ __| '_ \
${AnsiColor.BLUE}| |____ ${AnsiColor.WHITE} / /  __/ |_\__ \ |_| | |_| | (_| | ${AnsiColor.BLUE}   | |${AnsiColor.WHITE}|  __/ (__| | | |
${AnsiColor.BLUE} \_____/${AnsiColor.WHITE}/___\___|\__|___/\__,_|\__, |\__,_| ${AnsiColor.BLUE}   |_|${AnsiColor.WHITE} \___|\___|_| |_|
${AnsiColor.BLUE}        ${AnsiColor.WHITE}                        __/ |
${AnsiColor.BLUE}        ${AnsiColor.WHITE}                       |___/
${AnsiColor.BRIGHT_GREEN}#application.title# v#application.version#
Build: #build.time#
Powered by Spring Boot ${spring-boot.version}

3. Replacing the Variable Information in the Banner.

To replace the build information in the banner, we will use the replacer plugin.

<plugin>
	<groupId>com.google.code.maven-replacer-plugin</groupId>
	<artifactId>replacer</artifactId>
	<version>1.5.3</version>
	<executions>
	  <execution>
		<phase>prepare-package</phase>
		<goals>
		  <goal>replace</goal>
		</goals>
	  </execution>
	</executions>
	<configuration>
	  <file>target/classes/banner.txt</file>
	  <replacements>
		<replacement>
		  <token>#application.title#</token>
		  <value>${project.artifactId}</value>
		</replacement>
		<replacement>
		  <token>#application.version#</token>
		  <value>${project.version}</value>
		</replacement>
		<replacement>
		  <token>#build.time#</token>
		  <value>${maven.build.timestamp}</value>
		</replacement>
	  </replacements>
	</configuration>
</plugin>

4. Summary

In this short article, we have shown how you can set a customized banner for your Spring application.

czetsuyatech

Handling Long-Running Transactions in Spring Boot with NERV Event

1. Why a 30-Minute Database Transaction Is the Wrong Model

2. The First Improvement: Short Transactions Around External Work

3. The Reliability Gap

4. Every Important Handoff Must Be Durable

5. Publishing the Next Workflow Step

6. But Don't Move the 30-Minute Transaction to Another Consumer

7. Treat the Payment Gateway as an Asynchronous Process

8. Callback-Based Payment Completion

9. What If the Gateway Doesn't Support Callbacks?

10. The Hardest Failure Window

11. Idempotency and Reconciliation Close the Gap

12. NERV Event Handles the Local Atomicity Boundary

13. Three Different Failure Boundaries, Three Different Mechanisms

14. The Complete Durable Payment Workflow

15. Transaction Boundaries Should Follow Consistency Boundaries

16. This Pattern Isn't Just for Payments

The Bigger Lesson

Try NERV Event

Hardening Event-Driven Systems: Lessons from NERV Event 2.1

1. The Inbox Transaction Boundary Matters

The NERV Event 2.1 Transaction Model

What This Does Not Solve

2. Silent Outbox Misconfiguration Is a Reliability Problem

Fail Fast Instead

What About Consumer-Only Applications?

3. Kafka Keys Alone Don't Guarantee Application-Level Ordering

"Just Use a Kafka Key"

4. Introducing orderingKey

5. Ordering Starts in the Outbox

6. Transport-Specific Ordering

Kafka

Amazon SQS FIFO

Amazon SQS Standard

7. Minimal Runtime Images Expose Hidden Dependencies

8. Database Compatibility

9. The Showcase Was the Important Test

10. The Bigger Lesson

Try NERV Event

Building a Production-Ready Persistence Layer in Spring Boot

Building a Production-Ready Persistence Layer in Spring Boot

The Persistence Layer Grows Faster Than You Expect

Repetition Is Often a Sign of Missing Infrastructure

Start with Consistent Entity Models

Dynamic Queries Should Be Composable

Specifications Should Be Reusable Too

Don't Load an Entire Entity When You Don't Need It

Pagination and Sorting Are Infrastructure Concerns

A Persistence Library Should Work With Spring Data, Not Against It

This Is Why I Built NERV Persistence

Where NERV Persistence Fits

Why This Matters More in Microservices

Production-Ready Doesn't Mean Complicated

What's Next?

NERV Persistence

Transactional Outbox Pattern with Spring Boot: Reliable Event Publishing Without Dual Writes

The Dual-Write Problem

Database succeeds, Kafka fails

Kafka succeeds, database fails

The Transactional Outbox

What Goes Into the Outbox?

Publishing the Event

Why Not Just Retry Kafka Inside the Transaction?

At-Least-Once Delivery Changes the Problem

Multiple Application Instances

What About CDC?

Making This Reusable

Reliability Doesn't End at the Producer

NERV Event

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

Introduction

The Dual-Write Problem

The Transactional Outbox Pattern

Your Outbox Should Be Debuggable

Publishing Reliably Is Only Half the Problem

The Inbox Pattern

The Inbox Is More Than a Deduplication Table

Retries Should Survive Application Restarts

Use Backoff Instead of Hammering a Failing Dependency

4. Introducing `orderingKey`