DEV Community: Ankit Verma

Application events & ApplicationEventPublisher

Ankit Verma — Tue, 01 Sep 2026 09:32:29 +0000

Every application has moments where one thing happens and several other things need to react. A user signs up — and now you want to send a welcome email, create their starter workspace, and bump a signup counter. The signup itself is one job. The reactions are three more, and they have nothing to do with each other.

The blunt way is to have the signup code call each of those directly. It works, but the signup code now has to know about email, workspaces, and metrics. Add a fourth reaction next quarter and you edit the signup code again.

Spring offers a different shape. The signup code announces "a user was registered" and then forgets about it. Anything that cares listens for that announcement and reacts on its own. This is application events, and it is built into the Spring container you already use.

Let me first make sure the two words in that last sentence are real.

A one-paragraph recap of the container

Spring keeps your objects for you. You hand it a class, it builds one instance, and it hands that instance to whatever else needs it. That managed instance is a bean, and the thing holding all the beans is the container. When you write a constructor that takes another object, the container looks up the matching bean and passes it in. Everything below rides on this: the event machinery is itself a bean the container hands you.

Announcing that something happened

To announce an event, you need the thing that broadcasts it. Spring exposes it as a bean called ApplicationEventPublisher. You ask for it the same way you ask for any bean — through the constructor.

@Service
class RegistrationService {

    private final ApplicationEventPublisher publisher;

    RegistrationService(ApplicationEventPublisher publisher) {
        this.publisher = publisher;
    }
}

Now RegistrationService can broadcast. But broadcast what? For a long time Spring required events to extend a base class, but since Spring 4.2 an event is just a plain object — any class you like. So the event is simply a small carrier of "what happened."

record UserRegistered(String email) {}

That is the whole event: a record holding the new user's email. Publishing it is one line.

void register(String email) {
    // ... save the user ...
    publisher.publishEvent(new UserRegistered(email));
}

Here is what just happened. register did its own job — saving the user — and then handed a UserRegistered object to the publisher. It did not call the email service. It does not know an email service exists. It said "this happened" and moved on. Which raises the obvious question: who hears it?

Listening for the event

A listener is any bean method marked with @EventListener, typed to the event it cares about.

@Component
class WelcomeEmailListener {

    @EventListener
    void on(UserRegistered event) {
        System.out.println("Sending welcome email to " + event.email());
    }
}

Spring reads the method's parameter type, UserRegistered, and wires it up: whenever an event of that type is published, this method runs with the event passed in. Add a second listener for the same type and both run. The publisher's one line now fans out to as many reactions as you have, and it never learns their names.

@Component
class SignupMetrics {

    @EventListener
    void on(UserRegistered event) {
        // increment a counter
    }
}

Two listeners, one event, zero coupling between them. To add analytics next quarter you write a third listener and touch nothing else. That is the whole point of the pattern — but the way Spring runs these listeners has consequences you need to see.

The part everyone gets wrong: it is synchronous

It is natural to picture the publisher tossing the event over a wall and carrying on while listeners work in the background. That is not what happens. By default, publishEvent runs every listener right there, on the same thread, before it returns.

So this line:

publisher.publishEvent(new UserRegistered(email));

does not finish until the welcome email has been sent and the metrics counter bumped. register is blocked the entire time. The event system decouples who knows about whom, not when things run. It is still one straight-line call.

Two consequences fall out of that, and both bite in production.

First, speed. If sending the email takes two seconds, register takes two seconds longer. The user waits for work they do not care about.

Second, and worse, failure. Because it is all one thread, an exception thrown by a listener travels straight back up into register.

@EventListener
void on(UserRegistered event) {
    throw new RuntimeException("mail server down");
}

That exception is not caught for you. It propagates out of publishEvent, out of register, and — if register was running inside a database transaction — it rolls the transaction back. The user you just saved is un-saved because the welcome email failed. A reaction that was meant to be a harmless side effect has killed the main job.

So the next question writes itself: how do we stop a listener from blocking or breaking the publisher?

Moving the work off the thread with @async

If the problem is that the listener runs on the publisher's thread, the fix is to run it on a different one. Mark the listener @Async and Spring hands it to a background thread pool instead of running it inline.

@Component
class WelcomeEmailListener {

    @Async
    @EventListener
    void on(UserRegistered event) {
        // now runs on a background thread
    }
}

publishEvent now returns immediately; the email is sent later, elsewhere. The blocking is gone, and so is the failure path — an exception on the background thread cannot roll back the publisher's transaction, because it is not on the publisher's thread anymore.

One catch: @Async does nothing unless you switch it on. Somewhere in your configuration you need @EnableAsync.

@Configuration
@EnableAsync
class AsyncConfig {}

Without it, @Async is silently ignored and you are back to synchronous — a genuinely confusing bug, because the annotation is right there and looks active. But async trades one problem for a subtler one, which is worth seeing clearly.

The transaction trap

Go back to the synchronous version for a moment, because it hides the nastiest gotcha of all. Picture the email being sent inside the transaction:

@Transactional
void register(String email) {
    save(email);
    publisher.publishEvent(new UserRegistered(email)); // listener runs, still inside the tx
}

The listener runs before register returns, which means it runs before the transaction commits. The email goes out. Then, a line later, the transaction hits a constraint violation and rolls back. The user is gone from the database — but the welcome email is already in their inbox. You have sent mail about a user that does not exist.

Async does not cleanly fix this either: the background thread might fire before or after the commit, and now you are racing.

Spring's answer is a listener that waits for the transaction itself. Swap @EventListener for @TransactionalEventListener, and it runs only at a chosen point in the transaction's lifecycle — by default, AFTER_COMMIT.

@Component
class WelcomeEmailListener {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void on(UserRegistered event) {
        // runs only after the transaction has successfully committed
    }
}

Now the ordering is guaranteed: the user is safely committed first, and only then does the email go out. If the transaction rolls back, the listener never runs at all. This is the correct home for any side effect that must not happen unless the main work actually committed. One thing to remember: if there is no active transaction when the event is published, an AFTER_COMMIT listener has nothing to wait for and, by default, simply does not fire.

Two smaller controls worth knowing

Once you have several listeners on one event, two questions come up.

Order. Listeners have no guaranteed order by default. If email must run before metrics, annotate them with @Order — the lower number runs first.

@Order(1)
@EventListener
void sendEmail(UserRegistered event) { }

@Order(2)
@EventListener
void recordMetric(UserRegistered event) { }

Filtering. Sometimes a listener only cares about some events of a type. @EventListener takes a condition written in Spring's expression language, and the method runs only when it evaluates to true. Here #event refers to the published event.

@EventListener(condition = "#event.email().endsWith('@vip.com')")
void on(UserRegistered event) {
    // runs only for VIP signups
}

The event is still published to everyone; this listener just opts out of the ones it does not want.

Where this comes from for free

You do not only publish your own events. Spring itself publishes events as your application starts and stops, using this exact mechanism. The most useful one is ApplicationReadyEvent, fired once the container is fully built and ready to serve traffic — the right place to run one-time startup work.

@EventListener(ApplicationReadyEvent.class)
void warmUp() {
    // load caches, ping downstream services
}

Because it is the same @EventListener you already understand, framework events and your own events read identically. There is nothing new to learn — the container is just another publisher.

The one mental model to keep

Application events let one bean announce that something happened without knowing who reacts. A publisher broadcasts a plain object; any bean with a matching @EventListener method receives it.

The single fact that governs everything else: listeners run synchronously, on the publisher's thread, inside the publisher's transaction, unless you say otherwise. From that one fact the rest follows — @Async to move the work off the thread, @EnableAsync to actually turn it on, and @TransactionalEventListener(AFTER_COMMIT) to make a side effect wait for the commit that justifies it. Get that fact right, and the pattern is a clean way to keep your components from ever having to know about each other.

SpEL basics

Ankit Verma — Mon, 31 Aug 2026 11:03:17 +0000

What SpEL actually is

Spring lets you configure a lot of things with strings. You put a string in an annotation, and Spring turns it into a value at runtime. Most of the time that string is a plain constant. But sometimes you want the value to be computed — read another bean, do a little math, pick between two options — and a plain constant can't do that.

SpEL, the Spring Expression Language, is Spring's answer. It's a tiny language you write inside a string, and Spring evaluates it while it's wiring your application together. Think of it as a formula bar for your configuration: instead of a fixed value, you hand Spring a small expression, and Spring runs it to produce the value.

You meet SpEL the first time you see a #{ ... } inside an annotation. It shows up in @Value, in caching conditions, in security rules, in @ConditionalOnExpression. This article builds it up from the simplest possible expression to the parts that quietly bite people in production.

The two dollar-hash cousins

Before any SpEL, we have to clear up the single most common confusion, because the two look almost identical.

You have probably written this:

@Value("${server.port}")
private int port;

That ${ ... } is not SpEL. It's a property placeholder — Spring looks up the key server.port in your properties (from application.properties, environment variables, and so on) and drops the value in. It only does key lookups. It can't do math or call methods.

SpEL uses a hash, not a dollar:

@Value("#{2 * 60 * 1000}")
private long cacheMillis;   // 120000

The #{ ... } says "evaluate this as an expression." So the rule of thumb: ${} looks something up, #{} computes something. They can even work together, which we'll get to — but keep them separate in your head for now.

Your first expressions: literals and math

The cleanest way to learn SpEL is to see what goes between the #{ and }. At its simplest, an expression is just a literal value.

@Value("#{true}")          // boolean
@Value("#{'Freddie'}")     // string, single-quoted
@Value("#{3.14159}")       // double

Strings inside SpEL use single quotes, because the whole expression already lives inside the double quotes of the Java annotation. Once you have literals, you get operators for free:

@Value("#{100 * 1024}")           // 102400  — arithmetic
@Value("#{'Spring'.length()}")    // 6        — method call on a string
@Value("#{'a,b,c'.split(',')}")   // ["a","b","c"]

That last line is the key idea: inside an expression you can call any method on any value, exactly as you would in Java. SpEL isn't a cut-down mini-language for constants — it can genuinely run things. Which immediately raises the question: run things on what? So far we've only touched literals. The real power starts when an expression can reach the objects Spring already manages.

Reaching into other beans

Spring keeps every object it manages in a container, and each one has a name — its bean name. SpEL can name a bean directly and pull a value out of it.

Say you have a bean that holds some tuning numbers:

@Component("tuning")
public class Tuning {
    public int getPoolSize() { return 8; }
}

Another bean can borrow that value through SpEL:

@Value("#{tuning.poolSize}")
private int poolSize;   // 8

Read that expression left to right: tuning is the bean, and .poolSize calls its getter. SpEL turns .poolSize into a call to getPoolSize() for you — it follows the JavaBean property convention, so you write the short property name and Spring finds the getter.

You can go further and call methods with arguments, chain calls, and reach built-in objects Spring exposes, like system properties:

@Value("#{systemProperties['user.timezone']}")
private String tz;

Here systemProperties is a Map Spring makes available, and ['user.timezone'] indexes into it — the same bracket syntax works for lists and arrays too.

Mixing properties and expressions

Now we can bring the two cousins back together. Spring resolves the property placeholder ${} first, before it hands the string to SpEL. That ordering lets you nest one inside the other: look a value up, then compute with it.

@Value("#{'${app.admins}'.split(',')}")
private String[] admins;

Walk the order carefully. First ${app.admins} is replaced with, say, the string alice,bob. That leaves SpEL looking at #{'alice,bob'.split(',')}, which it evaluates into a two-element array. The property gives you the raw text; SpEL reshapes it. This "look it up, then transform it" pattern is most of what people use SpEL for in day-to-day config.

Operators that make config decisions

SpEL really earns its place when a value has to depend on something. It has the operators you'd expect, plus three shorthands worth knowing by name.

The ternary operator picks between two values based on a condition:

@Value("#{tuning.poolSize > 4 ? 'large' : 'small'}")
private String profile;

The Elvis operator, ?:, is a shorter ternary for one specific job: "use this, or a fallback if it's null." It's named for the way ?: looks like Elvis's hair and eyes.

@Value("#{systemProperties['region'] ?: 'us-east'}")
private String region;   // the property, or 'us-east' if it's absent

The safe-navigation operator, ?., stops a null from blowing up a chain. If the left side is null, the whole expression is null instead of throwing:

@Value("#{tuning?.poolSize}")
private Integer poolSize;   // null if 'tuning' were null, no exception

Together these three let a single line of config express "compute a value, fall back gracefully, and don't crash on a missing piece" — logic you'd otherwise write in Java.

Filtering collections without a loop

This is the part of SpEL that feels like a superpower the first time you see it. Given a collection, SpEL can filter and transform it inline.

Selection filters a collection with .?[ ... ], where inside the brackets each element is available as #this:

// keep only the servers whose port is above 8000
@Value("#{servers.?[port > 8000]}")
private List<Server> highPorts;

Projection transforms each element with .![ ... ], pulling one piece out of every item:

// turn a list of Server objects into a list of their names
@Value("#{servers.![name]}")
private List<String> serverNames;

Read .?[] as "select where" and .![] as "map to." In two short expressions you've done a filter and a map that would each be a loop or a stream pipeline in Java. There are cousins too — .^[] grabs the first match and .$[] the last — but selection and projection are the two you'll reach for.

Running SpEL yourself

Everything so far happened inside annotations, where Spring runs the expression for you. But SpEL is a normal library, and you can drive it directly — useful when your own code needs to evaluate a formula, perhaps one a user or a config file supplied.

The entry point is an ExpressionParser. You parse a string into an Expression, then ask for its value:

ExpressionParser parser = new SpelExpressionParser();
Expression exp = parser.parseExpression("'Spring'.length() * 2");
int result = (int) exp.getValue();   // 12

Often you want the expression to run against some object — evaluate it "in the context of" a particular target. You pass that target as the root object:

Tuning tuning = new Tuning();
Expression exp = parser.parseExpression("poolSize > 4");
boolean big = exp.getValue(tuning, Boolean.class);   // properties resolve against 'tuning'

Now poolSize in the expression resolves against the tuning object you handed in. That idea — what the expression is allowed to see — is not just a convenience. It's the security boundary, and it's the last and most important thing to understand.

The context is the security boundary

When SpEL evaluates an expression, it does so inside an EvaluationContext — the object that decides what the expression can reach: which variables, which beans, whether it can even name Java types. There are two you'll encounter, and the difference matters enormously.

StandardEvaluationContext is the powerful one, and the default when Spring evaluates internally. It can do everything SpEL allows — including naming any class and calling any static method through the T() type operator:

// with a StandardEvaluationContext, this runs:
T(java.lang.Runtime).getRuntime().exec('rm -rf /')

That is not a hypothetical. If you ever pass a user-supplied string into a StandardEvaluationContext, you have handed the user the ability to run arbitrary code inside your JVM. This exact mistake — SpEL injection — is behind a string of real, severe Spring vulnerabilities.

SimpleEvaluationContext exists precisely for that danger. It's a deliberately restricted context: it allows property access and simple operators but forbids type references and arbitrary method resolution. When an expression comes from anywhere you don't fully trust, this is the one to use:

EvaluationContext ctx = SimpleEvaluationContext.forReadOnlyDataBinding().build();
Expression exp = parser.parseExpression(userSuppliedString);
Object value = exp.getValue(ctx, target);   // can read properties, cannot reach Runtime

The rule is simple and worth burning in: your own trusted expressions can use the standard context; anything a user can influence must use SimpleEvaluationContext. SpEL is powerful because it can run real code — which means the moment untrusted input reaches it, that power is the whole problem.

Where you'll meet it again

You now have the shape of SpEL end to end: a #{} string Spring evaluates at runtime, distinct from a ${} property lookup, able to do math, call methods, reach into beans, choose values with ternary and Elvis, filter collections with selection and projection, and — when you drive it yourself — run inside a context that is either fully powered or safely fenced.

The same #{} you learned here reappears across Spring: in @Cacheable(condition = "...") to decide when to cache, in @PreAuthorize("hasRole('ADMIN')") for security rules, and in @ConditionalOnExpression to switch beans on and off. They're all the same language you just built up — so wherever you see those hash-braces next, you already know how to read them.

Transaction isolation levels — what Spring controls

Ankit Verma — Sun, 30 Aug 2026 10:03:24 +0000

Picture a bank account row in your database. Two requests land at the same instant — one reads the balance to show it on a screen, the other is halfway through moving money out of it. What should the first request see? The old balance? The new one? A half-finished number that never really existed?

That question is what a transaction isolation level answers. It is a dial that decides how much one in-flight transaction is allowed to see of another in-flight transaction that touches the same data. You meet it the moment your app has more than one user, because then more than one transaction runs at once, and they start stepping on each other.

Spring gives you a single, small lever over this dial. This article builds up what the dial actually does, then shows exactly what Spring controls — and, just as important, what it does not.

First, what a transaction guarantees on its own

A transaction is a group of database operations that either all take effect or none do. Inside one transaction, you can read a row, change it, read it again, and the outside world sees nothing until you commit.

That is a clean story when transactions run one after another. The trouble is that a real server runs many at once, and they overlap in time. While your transaction is open, other transactions are opening, writing, and committing against the very same rows.

Isolation is the rulebook for that overlap. So before we can talk about levels, we need to see the specific ways that overlap can go wrong.

The three ways concurrent reads go wrong

There are three classic anomalies. They are worth naming carefully, because the isolation levels are defined entirely in terms of which of these they forbid.

The first is a dirty read. Your transaction reads a row that another transaction has changed but not yet committed. If that other transaction then rolls back, you have read a value that never officially existed.

// Transaction B writes but has NOT committed:
UPDATE account SET balance = 500 WHERE id = 1;   // was 100

// Transaction A reads right now and sees 500.
// Then B rolls back. A acted on a number that was never real.

The read was "dirty" because it saw uncommitted work. That is the most dangerous anomaly, and most systems forbid it by default.

The second is a non-repeatable read. Your transaction reads the same row twice and gets two different values, because another transaction committed a change in between.

// Transaction A:
SELECT balance FROM account WHERE id = 1;   // reads 100

// Transaction B commits: balance is now 500.

SELECT balance FROM account WHERE id = 1;   // reads 500 — same query, new answer

Nothing here is dirty; both values were committed. The problem is that A cannot trust a value to hold still for the length of its own transaction.

The third is a phantom read. This time you re-run a query that matches a set of rows, and the set changes size because another transaction inserted or deleted a matching row.

// Transaction A:
SELECT count(*) FROM account WHERE balance > 100;   // 3 rows

// Transaction B inserts a new row with balance = 900 and commits.

SELECT count(*) FROM account WHERE balance > 100;   // 4 rows — a "phantom" appeared

A non-repeatable read is about a row you already saw changing value. A phantom read is about new rows appearing (or vanishing) in a range you already queried. Keep that distinction in mind — the levels treat them separately.

The four isolation levels

Now the payoff. Each isolation level is just a promise about which of those three anomalies cannot happen. They stack: each stronger level forbids everything the weaker ones forbid, and one more.

READ UNCOMMITTED — allows all three. You can even see uncommitted (dirty) data. Fastest, and almost never what you want.
READ COMMITTED — forbids dirty reads. You only ever see committed data, but a row can still change between two reads. This is the default in PostgreSQL, Oracle, and SQL Server.
REPEATABLE READ — also forbids non-repeatable reads. A row you have read will keep its value for the rest of your transaction. This is MySQL's default.
SERIALIZABLE — forbids all three, phantoms included. The database behaves as if transactions ran one at a time, in some order. Safest, and slowest.

The pattern is a trade. As you climb, you rule out more surprises, but the database has to do more locking or more bookkeeping, so concurrency drops. Higher isolation buys correctness with throughput.

That is the whole concept. Everything Spring does sits on top of it.

Where Spring enters: one annotation attribute

You mark a method transactional with @Transactional. That is the annotation that tells Spring "wrap this method in a database transaction — begin before it runs, commit if it returns, roll back if it throws."

The isolation level is one attribute on that annotation:

@Transactional(isolation = Isolation.REPEATABLE_READ)
public void transfer(Long from, Long to, BigDecimal amount) {
    // every SQL statement in here runs at REPEATABLE_READ
}

Isolation is a Spring enum, and it mirrors the levels above one for one: READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE, plus one more we will get to — DEFAULT.

So from the developer's seat, choosing an isolation level in Spring is exactly this: pick a value for one attribute. That is the entire surface area. Which raises the real question — what does Spring do with it?

Spring sets the dial; the database does the work

Here is the part that surprises people. Spring does not implement isolation. It does not prevent a single dirty read on its own. All it does is pass your choice down to the database.

Under the hood, a Spring transaction runs on a JDBC Connection — the object that represents your app's open line to the database. That connection has a method for exactly this purpose:

// Roughly what Spring's transaction manager does when it opens the transaction:
connection.setTransactionIsolation(Connection.TRANSACTION_REPEATABLE_READ);

That single JDBC call is the whole mechanism. Spring translates your Isolation.REPEATABLE_READ into the matching JDBC constant and sets it on the connection before your method's SQL runs. From there, enforcing the level is entirely the database's job.

This is why the framing "what Spring controls" matters. Spring controls the request. It picks up your annotation, opens a connection, and dials the level in. The actual guarantees — what a dirty read or a phantom means in practice — come from the database engine, not from Spring.

When your transaction finishes, Spring is careful to set the connection's isolation back to what it was before, because that connection goes back into a pool and will be reused by the next transaction. You do not have to manage that reset; the transaction manager does it for you.

Isolation.DEFAULT, and why it is the sensible default

The extra enum value, Isolation.DEFAULT, means "do not call setTransactionIsolation at all — just use whatever the database is already configured to use."

@Transactional   // isolation defaults to Isolation.DEFAULT
public void placeOrder(Order order) { ... }

If you write @Transactional with no isolation attribute, you get DEFAULT. So your transaction runs at the database's own default level — READ COMMITTED on Postgres, REPEATABLE READ on MySQL. This is the right choice the vast majority of the time. You only reach for an explicit level when a specific piece of logic genuinely needs a stronger guarantee.

The gotcha: isolation is ignored when you join an existing transaction

This is the trap the mechanism creates, and it catches people who assume the annotation always wins.

Spring transactions can nest by participating. With the default propagation, if a transactional method calls another transactional method, the inner one does not start a new transaction — it joins the one already running. And a transaction's isolation level is fixed the moment it begins, on that one connection. You cannot change it midway.

So consider this:

@Transactional(isolation = Isolation.READ_COMMITTED)
public void outer() {
    inner();   // joins outer's transaction
}

@Transactional(isolation = Isolation.SERIALIZABLE)
public void inner() {
    // runs at READ_COMMITTED — outer's level — NOT serializable
}

Because inner() joins outer()'s existing transaction, its SERIALIZABLE request is quietly ignored. The transaction is already open at READ COMMITTED, and that is what inner() gets. The annotation reads like a firm instruction, but on a participating call it is more of a wish.

Spring can be told to shout instead of ignore. If you set the transaction manager's validateExistingTransaction flag on, Spring will throw an exception when an inner method asks for an isolation level that conflicts with the transaction it is joining, rather than silently running at the outer level. By default that flag is off, so the silent case above is what you get out of the box.

The clean way to actually get a different isolation level is to make the inner method start its own transaction — propagation REQUIRES_NEW — which opens a fresh connection that Spring can dial independently. But that is a separate, heavier decision, because a brand-new transaction commits on its own and no longer shares the outer one's fate.

Each database reads the levels its own way

One more thing Spring does not smooth over: the four level names are a SQL standard, but databases implement them with real differences.

The sharpest example is REPEATABLE READ. The standard only requires it to stop non-repeatable reads, leaving phantoms allowed. But MySQL's InnoDB engine, at REPEATABLE READ, also blocks most phantom reads through its snapshot mechanism. PostgreSQL does not even offer a distinct REPEATABLE READ that permits phantoms — its REPEATABLE READ is a full snapshot that rules them out too.

@Transactional(isolation = Isolation.REPEATABLE_READ)
public BigDecimal report() {
    // On MySQL and Postgres this behaves more strictly than
    // the SQL standard's bare minimum. On another engine it may not.
}

The lesson is not to memorize every engine. It is to remember where the boundary sits: the same isolation value can mean different things on different databases, because Spring only forwards the name — the behavior belongs to the engine. When a level matters enough to set explicitly, check what your specific database promises for it.

There is also a plainer failure mode. Some databases or drivers do not support every level. If you ask for one the database cannot honor, the setTransactionIsolation call fails, and your transaction fails to start. Spring surfaces that as an exception rather than silently downgrading, which is the safe behavior — you would rather know than believe you have a guarantee you do not.

What to actually reach for

Put the pieces together and the practical picture is simple.

Most of the time, leave isolation alone. @Transactional with Isolation.DEFAULT runs at your database's default — usually READ COMMITTED — and that is a sound choice for ordinary create-read-update work.

Raise the level only for a specific transaction that genuinely needs a steadier view of the data: a multi-step calculation that must not see rows shift underneath it, or money-movement logic where a phantom row would corrupt a total. And when you do raise it, remember the two edges — it is silently ignored on a participating call, and its exact meaning depends on the database underneath.

Spring's role in all of this is narrow and worth stating plainly: it reads one annotation attribute, sets one value on one JDBC connection at the right moment, and restores it afterward. The isolation guarantees themselves live in the database. Spring just makes sure the right request reaches it.

Transaction propagation (REQUIRED / REQUIRES_NEW / NESTED ...) (Part 2 of 2)

Ankit Verma — Sat, 29 Aug 2026 11:17:44 +0000

Picking up between "join" and "start fresh"

Part 1 left you with two propagation modes and a clean way to think about them. REQUIRED joins whatever transaction is already running, so everything shares one all-or-nothing boundary. REQUIRES_NEW ignores the outer transaction, suspends it, and runs a completely separate one that commits or fails on its own.

Those two are opposites. Join everything, or share nothing. But real code sometimes wants something in between: let the inner work fail and be undone on its own, yet still tie its success to the outer transaction's success. Neither mode gives you that. REQUIRED can't undo just the inner part; REQUIRES_NEW commits the inner part too early.

The mode that fills that gap is NESTED, and it works with a database feature called a savepoint. So before we can name NESTED, we have to build a savepoint.

What a savepoint is

Picture a single transaction running along, making changes. A savepoint is a marker you drop partway through it. It says: remember exactly what the world looked like at this spot.

Later, if something goes wrong, you have a new option. Instead of rolling back the whole transaction, you can roll back to the savepoint. That undoes every change made after the marker, keeps every change made before it, and — this is the important part — the transaction is still alive and can carry on.

So a savepoint is a partial undo button inside one transaction. Not the end of the transaction, just a rewind to a point you chose.

Hold that picture, because NESTED is nothing more than Spring dropping a savepoint for you.

NESTED — a savepoint around the inner method

NESTED means: if a transaction is already running, don't start a new one — instead drop a savepoint, run the inner method, and if it fails, roll back only to that savepoint. If no transaction is running yet, NESTED simply behaves like REQUIRED and starts a normal one.

You set it the usual way:

@Transactional(propagation = Propagation.NESTED)
public void writeAuditLog(Order order) {
    auditRepo.save(new AuditEntry(order));
}

Now walk the layered call again. placeOrder opens a transaction. It calls writeAuditLog, whose proxy sees a transaction already open and, because the mode is NESTED, drops a savepoint before running the body:

@Transactional
public void placeOrder(Order order) {
    orderRepo.save(order);
    try {
        writeAuditLog(order);      // NESTED — runs after a savepoint
    } catch (Exception e) {
        // inner failed; only its work is undone
    }
    // outer transaction is still healthy and commits here
}

Here is what makes NESTED different from the REQUIRED trap in Part 1. When writeAuditLog throws, Spring rolls the transaction back to the savepoint — undoing the audit write and nothing else. The transaction is not marked rollback-only. So when you catch the exception and let placeOrder continue, its commit goes through cleanly. The inner failure was contained; the outer work survived.

That is the in-between behaviour we wanted: the inner method can fail and be cleanly undone, without poisoning the whole transaction.

Why NESTED is not REQUIRES_NEW

They sound similar — both let the inner part fail alone — so it is worth being exact about the difference, because it changes what you can rely on.

There is still only one physical transaction. The savepoint lives inside it. That has one consequence that matters most: the inner work is not committed early. It becomes permanent only when the outer transaction finally commits. Roll the outer one back, and the nested work goes with it — savepoint or no savepoint.

Compare that to REQUIRES_NEW, where the inner transaction commits immediately and independently, and survives even if the outer one later rolls back.

So the rule of thumb is about durability on outer failure:

Inner work must survive the outer rolling back → REQUIRES_NEW (audit trails, attempt counters).
Inner work should be undoable on its own but still tied to the outer commit → NESTED (a sub-step you might retry or skip, but which is meaningless if the whole operation is abandoned).

There is also a plumbing catch worth knowing. Savepoints are a JDBC feature, so NESTED only works on a transaction manager that speaks straight to JDBC — Spring's DataSourceTransactionManager. The JPA manager (JpaTransactionManager), which most Hibernate apps use, does not support NESTED and will throw when you ask for it. It is the least portable of the modes for exactly this reason, which is why you meet it less often than REQUIRED and REQUIRES_NEW.

The four modes you meet less often

That covers the three modes that carry almost all real code. The remaining four are quicker to describe, because each is just a rule about whether a transaction must, may, or must not already exist. Meeting them completes the set of seven.

SUPPORTS — join a transaction if one is running, otherwise run with no transaction at all. It does not insist on either. You reach for it on a read that is fine standing alone but should ride along inside a transaction when one happens to be open.

@Transactional(propagation = Propagation.SUPPORTS)
public Order findOrder(Long id) {
    return orderRepo.findById(id);   // transactional only if a caller already had one
}

NOT_SUPPORTED — the opposite instinct. Suspend any transaction that is running and execute with none, then resume it afterwards. Use it for work that should not sit inside a transaction — a slow report or a long external call you do not want holding a database connection and locks open the whole time.

MANDATORY — run in the caller's transaction, and if there isn't one, throw. It never starts a transaction itself. This is a guard: a method that is only ever meant to be a step inside a larger unit of work, and should refuse to run if someone calls it standalone.

@Transactional(propagation = Propagation.MANDATORY)
public void applyLoyaltyPoints(Order order) {
    // throws IllegalTransactionStateException if no transaction is already open
}

NEVER — the mirror of MANDATORY. Run only if there is no transaction, and throw if one is open. It is a rare, defensive choice for code that must not be allowed to run inside a transaction under any circumstances.

Line them up and the pattern is clear. REQUIRED, REQUIRES_NEW, and NESTED each make a transaction happen in some form. SUPPORTS and NOT_SUPPORTED are relaxed — they take whatever is there. MANDATORY and NEVER are strict guards that throw when the world isn't the way they demand.

When does a transaction actually roll back?

One question is still open, and it surprises people as often as the propagation traps do. A transaction rolls back when an exception escapes the method — but which exceptions? The answer is not "all of them," and the default is easy to get wrong.

Recall from Java that exceptions come in two families. Unchecked exceptions extend RuntimeException (or Error) — the compiler does not force you to declare or catch them. Checked exceptions are everything else — the ones you must declare with throws or handle.

Spring's default rollback rule splits exactly along that line:

An unchecked exception (RuntimeException or Error) that escapes the method → rollback.
A checked exception that escapes the method → commit anyway.

That second line is the trap. Read it slowly, because it is the opposite of what most people expect:

@Transactional
public void placeOrder(Order order) throws PaymentException {
    orderRepo.save(order);
    paymentGateway.charge(order);   // throws PaymentException (a checked exception)
}

If PaymentException is a checked exception, Spring commits the order anyway. The save sticks even though payment failed and the method exited by throwing. Nothing about "an exception was thrown" saved you here — the kind of exception decided it, and a checked one does not trigger rollback by default.

This default is a historical inheritance from the old EJB world, where the same checked-versus-unchecked convention held. It rarely matches what a modern app wants. Fortunately you override it in one place.

Telling Spring what to roll back on

The override lives on the annotation. rollbackFor adds exception types that should roll back even though they normally wouldn't; noRollbackFor does the reverse.

@Transactional(rollbackFor = PaymentException.class)
public void placeOrder(Order order) throws PaymentException {
    orderRepo.save(order);
    paymentGateway.charge(order);   // now a thrown PaymentException rolls the save back
}

With rollbackFor in place, the checked PaymentException triggers a rollback like you wanted, and the order no longer sticks after a failed payment. The mirror case is rarer but real — a checked exception you throw for control flow, that you specifically do not want to undo the work:

@Transactional(noRollbackFor = OrderAlreadyConfirmedException.class)
public void confirmOrder(Order order) throws OrderAlreadyConfirmedException {
    // this exception signals "nothing to do," so keep whatever was written
}

The habit worth forming: whenever a @Transactional method can throw a checked exception that ought to undo its writes, name it in rollbackFor. Leave it out and the default quietly commits work you meant to discard.

The whole picture, in order

Propagation is a per-method answer to one question — when this method runs, what should happen to the transaction around it? The seven modes are just the seven honest answers. REQUIRED joins one. REQUIRES_NEW suspends the outer and runs a fully independent one. NESTED stays inside the outer transaction but drops a savepoint so the inner step can be undone alone — as long as your transaction manager speaks JDBC. SUPPORTS and NOT_SUPPORTED go along with whatever is there. MANDATORY and NEVER stand guard and throw when the surroundings are wrong.

And sitting underneath all of it is the rollback rule that decides whether a boundary commits or discards: unchecked exceptions roll back, checked ones commit, and rollbackFor is how you fix the mismatch when your checked failure should have undone the work.

Put Part 1 and Part 2 together and transactions stop being a single opaque annotation. They become a boundary you place deliberately, a propagation mode you choose per layer, and a rollback rule you make explicit — three decisions, each yours to make.

Transaction propagation (REQUIRED / REQUIRES_NEW / NESTED ...) (Part 1 of 2)

Ankit Verma — Fri, 28 Aug 2026 16:50:32 +0000

When one transactional method calls another

You have probably written a method like this and moved on:

@Transactional
public void placeOrder(Order order) {
    orderRepo.save(order);
    paymentGateway.charge(order);
}

That @Transactional tells Spring one thing: run everything in this method as a single unit of work against the database. Either both writes stick, or neither does.

That is simple enough when the method stands alone. But real code is layered. placeOrder calls a service, which calls another service — and several of those methods also carry @Transactional. So a question appears the moment your code has more than one layer: when a transactional method calls another transactional method, is that one transaction, or two?

The answer is not decided for you. You choose it, per method, with a setting called propagation. This article is about what that choice means, the two modes that carry almost all real use, and a trap that can silently switch the whole thing off.

What "a transaction" actually is here

Before propagation can make sense, we need to be precise about the thing being propagated.

A transaction is a boundary drawn around a group of database changes. Inside the boundary, the changes are provisional — pencilled in, not yet permanent. At the end, one of two things happens. You commit, and every change inside becomes permanent together. Or you roll back, and every change inside is thrown away together.

All-or-nothing is the entire point. No half-finished state — an order saved but never paid for — ever reaches the database.

How Spring opens one for you — the proxy

Notice that you never wrote code to open, commit, or roll back that transaction. Spring did it around your method. Here is how, because the "how" is where the traps live.

When a bean has a @Transactional method, Spring does not hand your object to the rest of the app directly. It wraps your object in a proxy — a stand-in object with the same method signatures. Everyone who calls your bean actually holds the proxy, not your real object.

The proxy's job is to run extra work before and after your real method:

// conceptually, the proxy wraps your call like this:
Transaction tx = txManager.begin();   // before your method runs
try {
    realOrderService.placeOrder(order);   // your actual code
    txManager.commit(tx);                 // after — if nothing threw
} catch (RuntimeException e) {
    txManager.rollback(tx);               // after — if it threw
    throw e;
}

Read the wrapper, not the details. Two facts matter later. First, the transaction is opened by the proxy, never by your own code. Second, it is opened only when a call arrives through the proxy. Hold on to both.

Propagation: join, or start fresh?

Now the layered call. placeOrder is transactional and calls writeAuditLog, which is also transactional.

The proxy around writeAuditLog is about to run. It checks a simple thing: is a transaction already open on this thread? Yes — placeOrder opened one a moment ago. So what should this inner proxy do? Join the transaction already running, or push it aside and start its own?

That decision is propagation. You set it on the annotation:

@Transactional(propagation = Propagation.REQUIRED)
public void writeAuditLog(Order order) { ... }

There are seven modes in total. Two of them carry almost every real case, so we build those fully here, then meet the trap that can quietly disable all seven. The remaining modes — and savepoints, a middle ground between the two — are Part 2.

REQUIRED — the default, and what "join" costs you

REQUIRED means: if a transaction is already running, join it; if not, start a new one. It is the default. Every @Transactional you write without naming a mode behaves this way.

So in our example, both methods are REQUIRED:

@Transactional                       // REQUIRED by default
public void placeOrder(Order order) {
    orderRepo.save(order);
    writeAuditLog(order);            // joins the same transaction
}

Joining means one physical transaction shared by both methods. Both writes land inside the same boundary, and a single commit at the very end — fired by the outermost method — makes them permanent together.

That shared fate is usually exactly what you want. If writeAuditLog succeeds but placeOrder fails afterwards, the audit write rolls back too. You never keep a log entry for an order that never happened.

But joining has a sharp edge, and it surprises people constantly.

The rollback-only trap

Here is the code that trips everyone up. The inner method throws, and you catch the exception so the outer method can carry on:

@Transactional
public void placeOrder(Order order) {
    orderRepo.save(order);
    try {
        writeAuditLog(order);       // inner REQUIRED — it throws
    } catch (Exception e) {
        // swallow it — auditing is not critical, keep going
    }
    // proxy now tries to commit here...
}

You caught the exception. You expect the order to commit. Instead you get this:

```plain text
UnexpectedRollbackException: Transaction silently rolled back
because it has been marked rollback-only





Why? Because the two methods share **one** transaction. When `writeAuditLog` throws, its proxy wants to roll back — but it cannot. It did not open the transaction, so it is not allowed to end it. The only thing it can do is set a flag on the shared transaction: **rollback-only**. Meaning: this transaction may no longer commit, no matter what happens next.


Your `catch` block swallowed the exception, but it could not unset that flag. When the outer proxy reaches its commit, the transaction manager sees rollback-only and refuses. The commit becomes a forced rollback, and you get the exception above.


The lesson is blunt: inside one shared transaction, a failure anywhere poisons the whole thing — even a failure you caught. If you genuinely need the inner work to fail on its own without dooming the order, joining is the wrong choice. You need a separate transaction. That is the next mode.


## REQUIRES_NEW — a genuinely separate transaction


**REQUIRES_NEW** means: always start a new, independent transaction. If one is already running, **suspend** it first — pause it, fully intact, changing nothing — run the new transaction to its own commit or rollback, then resume the outer one.




```java
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void writeAuditLog(Order order) {
    auditRepo.save(new AuditEntry(order));
}

Now there are two physical transactions, and they are strangers to each other. The audit log commits on its own, immediately, in its own boundary. Two consequences fall out of that, and both are the reason you would reach for this mode.

First, survival. If placeOrder fails and rolls back afterwards, the audit row was already committed in its own transaction — so it stays. The log records the attempt even though the order was undone.

Second, isolation of failure. If writeAuditLog throws and you catch it, only its own transaction rolled back. The outer transaction was suspended and untouched, so there is no rollback-only flag on it. The order commits normally. The trap from the last section simply cannot happen across a REQUIRES_NEW boundary, because the two were never the same transaction.

That independence is the whole use case: work that must land, or fail, regardless of what the surrounding transaction does — audit trails, attempt counters, "we tried to notify the user" records.

It has one real cost, worth knowing before you sprinkle it everywhere. Suspending the outer transaction does not release its database connection — that connection stays open and idle while the new transaction borrows a second one. So for a moment you hold two connections for one request. Under load, that can drain the connection pool faster than you expect. Use REQUIRES_NEW deliberately, where the independence earns its keep.

The trap that silently disables all of this: self-invocation

Everything above rests on one assumption: the call reaches the inner method through its proxy. Here is the everyday way it quietly does not.

@Service
public class OrderService {

    @Transactional
    public void placeOrder(Order order) {
        writeAuditLog(order);   // a plain internal call
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void writeAuditLog(Order order) {
        auditRepo.save(new AuditEntry(order));
    }
}

You asked for REQUIRES_NEW on writeAuditLog. You will not get it. The audit write runs inside placeOrder's transaction, exactly as if the annotation were not there.

The reason is the proxy again. placeOrder calls writeAuditLog(order) as a bare method call, which is really this.writeAuditLog(order). That call goes straight to the real object — this — and never leaves it. It never passes through the proxy. And the proxy is the only thing that reads @Transactional and acts on propagation. Skip the proxy, and you skip propagation entirely.

The fix is to make the call cross a proxy boundary. The cleanest way is usually to move the second method onto a different bean and inject it:

@Transactional
public void placeOrder(Order order) {
    orderRepo.save(order);
    auditService.writeAuditLog(order);   // a real proxy is in between
}

Now the call travels through auditService's proxy, that proxy reads REQUIRES_NEW, and you finally get the separate transaction you asked for. The rule to carry away: propagation only ever applies to a call that enters a bean from the outside, never to a method a bean calls on itself.

Where this leaves us

Three things are worth keeping. REQUIRED joins an existing transaction into one shared boundary — convenient, but a failure anywhere marks the whole thing rollback-only, even one you catch. REQUIRES_NEW carves out a truly independent transaction that commits or fails on its own, at the price of a second connection held open. And none of it takes effect on a plain internal call, because propagation lives in the proxy your own method never touches.

Part 2 picks up the middle ground between joining and full independence — NESTED and savepoints — then walks the four remaining modes, and pins down exactly which exceptions actually trigger a rollback.

Continued in Part 2.

@Transactional under the hood (proxy) + self-invocation gotcha

Ankit Verma — Thu, 27 Aug 2026 15:24:20 +0000

You put @Transactional on a service method, and suddenly the database treats everything inside it as one unit: either all of it sticks, or none of it does. Save three rows, throw an exception halfway through, and the first two vanish as if you never wrote them. You didn't open a transaction. You didn't commit at the end. You didn't roll back on the error. Yet all three happened.

So who did that work, and where does it run? That is what this article is about: the machinery Spring puts around your method the moment it sees @Transactional, the exact rule that decides whether it commits or rolls back — and the one call pattern that makes the whole thing silently do nothing.

We'll lean on one idea you've likely already met: the proxy, the stand-in object Spring slips in front of your bean so it can add behaviour around your methods without touching their bodies. Everything here is about what that stand-in actually does for transactions.

First, what a transaction even is

A transaction is a group of database operations that must succeed or fail together. Move money from one account to another and you touch two rows: subtract from one, add to the other. If the second write fails, the first must be undone too — otherwise money simply disappears. "All or nothing" is the whole promise.

The database gives you the tools to enforce that: a point where you begin, a point where you commit to make the changes permanent, and a rollback that throws away everything since the begin. Left alone, most databases auto-commit each statement on its own. A transaction is you telling the database, "stop doing that — hold these together until I say go."

The boilerplate you'd otherwise write by hand

Without Spring, wiring that up around some work looks like this:

Connection conn = dataSource.getConnection();
conn.setAutoCommit(false);        // begin: stop committing each statement
try {
    // ... your inserts and updates ...
    conn.commit();                // all good — make it permanent
} catch (Exception e) {
    conn.rollback();              // something failed — undo everything
    throw e;
} finally {
    conn.close();
}

Read it once and the shape is obvious: turn off auto-commit to open a transaction, do the work, commit if you reach the end, roll back if anything throws, and always release the connection.

Now notice the problem. Your actual logic is the one commented line in the middle. Everything else is ceremony — and it would be identical in every method that needs to be atomic. A concern that repeats across many unrelated methods like this is a cross-cutting concern, and Spring's standing answer to those is: keep your method clean, and push the ceremony into a proxy.

`@Transactional` moves that ceremony into a proxy

Here's the same operation the Spring way. The method holds only the business logic:

@Service
public class Orders {

    @Transactional
    public void placeOrder(Order o) {
        inventory.reserve(o);
        payments.charge(o);
        // no begin, no commit, no rollback — just the work
    }
}

When Spring builds this bean, it doesn't hand callers the real Orders object. It hands them a proxy — a stand-in of the same type that sits in front of the real bean and can run extra code before and after each method. @Transactional is the marker that tells Spring, "this method needs the transaction ceremony wrapped around it."

The code that does the wrapping is a piece of advice living inside the proxy called the TransactionInterceptor. Every outside call to placeOrder lands in the interceptor first, and it runs — almost literally — the try/commit/catch/rollback block you saw above:

Object invoke(Method method, Object[] args) {
    TransactionStatus tx = txManager.getTransaction(...);   // begin
    try {
        Object result = method.invoke(target, args);        // your method body
        txManager.commit(tx);                                // commit on success
        return result;
    } catch (RuntimeException | Error ex) {
        txManager.rollback(tx);                              // rollback on failure
        throw ex;
    }
}

That is the hand-written boilerplate again — except it was generated for you, and it wraps every @Transactional method without you repeating a line. Your method body is the method.invoke(target, args) in the middle; the interceptor supplies everything around it.

The transaction manager does the real database work

Notice the interceptor never touches a Connection itself. It delegates to a txManager — a PlatformTransactionManager, Spring's abstraction over "a thing that can begin, commit, and roll back a transaction."

Why an abstraction instead of raw JDBC? Because "a transaction" means different things to different persistence tools. Plain JDBC commits a Connection; JPA commits an EntityManager; each needs its own begin/commit calls. So Spring ships a different manager for each world — DataSourceTransactionManager for JDBC, JpaTransactionManager for JPA — and they all expose the same three methods. The interceptor calls getTransaction, commit, and rollback, and the right manager underneath translates that into the real thing: grabbing a connection, calling setAutoCommit(false), and so on.

How your queries join the same transaction

Here is the part that feels like magic until you see it. The manager opened a connection and began a transaction. But your method body calls a repository, a JdbcTemplate, or a JPA EntityManager — none of which you handed that connection to. How do they end up inside the same transaction instead of opening their own?

The answer is a thread-local handoff, run by a piece called the TransactionSynchronizationManager. When the transaction manager begins a transaction, it stashes the live connection in a map keyed to the current thread. When your repository later needs a connection, it doesn't call dataSource.getConnection() directly — it asks Spring's connection helper, which first checks that thread-local map and hands back the connection already bound there.

So the connection is shared not by passing it around, but by parking it on the thread everyone is running on. That single fact is why an entire call stack of repositories all land in one transaction without ever mentioning it.

It also explains a sharp edge: a transaction is tied to one thread. If your method spawns a new thread and does database work on it, that work runs on a different thread, finds nothing bound there, opens its own connection — and lives completely outside your transaction. The @Transactional boundary does not follow you across threads.

Gotcha 1: rollback only fires for unchecked exceptions

Look again at the interceptor's catch clause: catch (RuntimeException | Error). That is not a simplification — it is the actual default rule. Spring rolls back when your method throws an unchecked exception (a RuntimeException or an Error). If it throws a checked exception, Spring commits.

That surprises almost everyone the first time:

@Transactional
public void transfer() throws IOException {
    debit(fromAccount);
    throw new IOException("statement service down");   // checked → COMMITS the debit
}

The IOException is checked, so the interceptor doesn't treat it as a rollback signal. The debit is committed and the money is gone, even though the method failed. The reason is historical: the framework's authors decided checked exceptions represent "expected business outcomes" the caller might recover from, so they let the transaction stand.

You will usually disagree, and the override is one attribute:

@Transactional(rollbackFor = Exception.class)   // roll back on any exception

Set rollbackFor whenever a checked exception should still undo the work. It's the most common @Transactional tuning there is.

Gotcha 2: swallow the exception and you lose the rollback

The interceptor can only react to an exception that actually escapes your method. If you catch it inside the method and don't rethrow, the proxy sees a clean return — and commits.

@Transactional
public void placeOrder(Order o) {
    try {
        risky(o);
    } catch (Exception e) {
        log.error("order failed", e);   // swallowed — no exception leaves the method
    }
    // proxy sees a normal return → commits whatever risky() half-did
}

The transaction commits the partial work, because from the proxy's point of view nothing went wrong. If you must catch the exception but still want the work undone, mark the transaction for rollback explicitly:

TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();

That flag tells the manager, "no matter how this method returns, roll back." The commit then turns into a rollback at the boundary.

Gotcha 3: self-invocation — the transaction never starts

This is the trap in the topic's title, and it falls straight out of how the proxy works: the proxy only wraps calls that arrive from outside the bean. A call the bean makes to itself never leaves the object, so it never crosses the proxy — and the interceptor never runs.

@Service
public class Orders {

    public void placeAll(List<Order> orders) {
        for (Order o : orders) {
            save(o);            // internal call: really this.save(o)
        }
    }

    @Transactional
    public void save(Order o) {
        // expected to run in its own transaction
    }
}

You'd expect each save to open and commit its own transaction. It opens none. When placeAll calls save, that is a plain this.save(o) running inside the real object, underneath the proxy. The proxy — and its TransactionInterceptor — is standing outside, and this call never reaches it. So save runs with no transaction at all, and, worse, there's no error to tell you.

Only a call to save from another bean, one that enters through the proxy, gets wrapped. The fixes all amount to making the call cross the proxy boundary: move save into a separate bean and inject it, inject the bean into itself and call through that reference, or reach for the current proxy with AopContext.currentProxy().

Gotcha 4: public and non-final only

One more limit inherited from the proxy. When Spring proxies by subclassing your class (its Boot default), it can only wrap methods it can override. A private method can't be overridden, and a final method can't be either — so @Transactional on either one quietly does nothing, with no warning. Keep transactional methods public and non-final and this never bites you.

The model to keep

@Transactional adds no code to your method. A proxy wraps the bean, and inside it the TransactionInterceptor runs the begin / commit / rollback ceremony around your call, delegating the real database work to a PlatformTransactionManager. The connection that manager opens is parked on the current thread, so every repository and query on that thread quietly joins the same transaction.

Two facts explain nearly every surprise. First, a rollback happens only when an unchecked exception escapes the method — checked exceptions commit, and a swallowed exception commits, unless you say otherwise. Second, the whole mechanism only fires when the call enters through the proxy from outside, so a self-invoked method gets no transaction at all. Hold those two facts and @Transactional stops being magic and becomes something you can reason about.

AOP: aspect / pointcut / advice / weaving

Ankit Verma — Wed, 26 Aug 2026 22:31:30 +0000

Every codebase grows a set of chores that have nothing to do with the actual job of a method, yet somehow end up inside every method anyway. Logging that a call started. Timing how long it took. Checking the user is allowed in. Opening a database transaction. These are cross-cutting concerns — needs that cut across many unrelated methods, the same few lines copied into each one.

Aspect-Oriented Programming — AOP — is the tool for pulling that repeated code out of your methods and describing it in one place instead. You meet it in Spring the first time you use @Transactional, @Cacheable, or @Async: all of them are AOP underneath. So understanding AOP is really understanding how Spring makes a plain method call quietly do more than the method's body says.

The problem, in code

Here is a service method with a couple of those chores baked in:

public Order placeOrder(Cart cart) {
    long start = System.currentTimeMillis();
    log.info("placeOrder started");

    Order order = build(cart);   // the only line doing real work

    log.info("placeOrder took {}ms", System.currentTimeMillis() - start);
    return order;
}

Only one line does the actual job. The rest is timing and logging. Now picture those same four lines wrapped around every service method in the app. Change the log format once and you are editing it in fifty places.

The instinct is to move the noise into a helper. But a helper still has to be called from inside each method — the boilerplate shrinks, it never disappears. What we really want is for placeOrder to contain only its real work, and to describe the timing separately, somewhere else entirely.

A point where behavior could run

Start by naming the moments where extra behavior could plausibly happen. Just before a method starts. Right after it returns. The instant it throws. Each of these is a join point — a single, identifiable point during a program's execution where you could hook in extra code.

Spring keeps this deliberately narrow. In Spring, the only join points are method executions on Spring-managed objects. Every public method call on a bean is a candidate; nothing else is. That one restriction explains a lot of Spring AOP's behavior later on, so keep it in mind.

The code that runs there: advice

The extra behavior you want to run at a join point is called advice. Advice is just a method you write, tagged with when it should run relative to the join point.

The simplest kind runs before the target method:

@Before("...")   // the "..." — which methods — comes later
public void logStart(JoinPoint jp) {
    log.info("{} started", jp.getSignature().getName());
}

There are five kinds of advice, and the tag on the method picks which: @Before (runs first), @AfterReturning (only on success), @AfterThrowing (only on failure), @After (always, like a finally), and @Around (the most powerful — it wraps the call).

Around advice is worth dwelling on, because it can do what the other four can, and more. It receives the call itself as an object you must explicitly run:

@Around("...")
public Object time(ProceedingJoinPoint pjp) throws Throwable {
    long start = System.currentTimeMillis();
    Object result = pjp.proceed();   // <-- this runs the real method
    log.info("{} took {}ms", pjp.getSignature().getName(),
             System.currentTimeMillis() - start);
    return result;
}

That pjp.proceed() call is the target method. Everything above it runs before the method; everything below runs after. And if you never call proceed(), the real method simply never runs — which is exactly how a security aspect can block a call outright.

Choosing where advice applies: the pointcut

We have advice, but the "..." in those annotations is still empty. We need to say which join points a piece of advice attaches to. That selector is a pointcut — an expression that matches a set of join points.

The most common form matches by method signature:

@Around("execution(* com.shop.service.*.*(..))")
public Object time(ProceedingJoinPoint pjp) throws Throwable { ... }

Read the execution(...) expression left to right: the first * is "any return type", com.shop.service.* is "any class in that package", and .*(..) is "any method, with any arguments". Put together, this one line means every method of every class in the service package.

A pointcut can also match by annotation instead of by name:

@Around("@annotation(com.shop.Timed)")

This matches any method carrying a @Timed annotation, wherever it lives. That is precisely how @Transactional finds its targets — a pointcut looking for the annotation.

Bundling it together: the aspect

A pointcut plus the advice that runs at it is a natural pair. That pair, grouped into a class for one concern, is an aspect — a class marked @Aspect that holds related pointcuts and advice together.

@Aspect
@Component
public class TimingAspect {

    @Around("execution(* com.shop.service.*.*(..))")
    public Object time(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return pjp.proceed();
        } finally {
            log.info("{} took {}ms", pjp.getSignature().getName(),
                     System.currentTimeMillis() - start);
        }
    }
}

@Aspect marks the class as holding advice. @Component makes it a Spring bean, so the container discovers it. With this in place, placeOrder goes back to containing only its real work — the timing now lives here, in exactly one place, and applies to the whole service package at once.

How it actually gets applied: weaving

Now the question that ties everything together. Your service methods contain no reference at all to TimingAspect. So how does calling placeOrder actually run the timing code? The act of combining aspects with the target code, so the advice really fires, is called weaving.

Weaving can happen at three different moments: when you compile, when classes load into the JVM, or at runtime while the app is running. Spring chooses the last one, and it does it with a proxy.

A proxy is a stand-in object that has the very same methods as your bean, but each of its methods first runs the advice and then forwards to the real bean. The trick is in the wiring: when another bean asks the container for OrderService, Spring hands over the proxy, not the real object. The caller cannot tell — same type, same method signatures.

In spirit, the proxy's version of the method looks like this:

// what the generated proxy does, conceptually
public Order placeOrder(Cart cart) {
    long start = System.currentTimeMillis();
    try {
        return realOrderService.placeOrder(cart);   // delegate to the real bean
    } finally {
        log.info("placeOrder took {}ms", ...);
    }
}

Spring builds that proxy in one of two ways. If your bean implements an interface, it can create a JDK dynamic proxy — a runtime object implementing the same interface. If there is no interface (or you ask for it), it uses CGLIB, which generates a subclass of your bean and overrides its methods. Spring Boot defaults to CGLIB, so it works whether or not you have interfaces.

The trap the proxy creates: self-invocation

Because the woven behavior lives in the proxy and not inside your class, one everyday situation silently skips the advice: a method calling another method on the same object.

@Service
public class OrderService {

    public Order placeOrder(Cart cart) {
        return validateAndSave(cart);   // internal call — bypasses the proxy
    }

    @Timed
    public Order validateAndSave(Cart cart) { ... }
}

The proxy only wraps calls that arrive through it, from outside. But placeOrder calls validateAndSave directly on this — the real object, with no proxy in between — so the @Timed advice never runs. This catches everyone exactly once, and the mechanism explains it precisely: nothing sits between an object and a call to its own methods.

The fixes follow from the same fact: move the annotated method into a separate bean, or inject the proxy into itself, so the call goes through the proxy again. (Spring's transaction handling has its own version of this trap, which gets its own deep dive later.)

Where AspectJ comes in

Spring's proxy weaving is powerful, but it is bounded by that one mechanism: only Spring beans, only method-execution join points, and only calls coming from outside the object. Full AspectJ is a separate, more capable AOP system that Spring can integrate with. It weaves at compile time or class-load time by rewriting bytecode directly, so it can advise constructors, field access, and even internal calls — there is no proxy to bypass.

Most applications never need it; proxy-based Spring AOP covers the everyday concerns cleanly. Reach for AspectJ only when you genuinely need to advise something a proxy cannot see.

Putting the vocabulary together

The five words in this topic name five parts of one machine:

Join point — a point where behavior could run. In Spring, a method call on a bean.
Advice — the code that runs there, tagged with when (before, around, after…).
Pointcut — the expression selecting which join points the advice attaches to.
Aspect — the class bundling a pointcut and its advice for one concern.
Weaving — wiring the aspect into the target so the advice actually fires; Spring does it at runtime, through a proxy.

Every time you write @Transactional or @Cacheable, this entire machine is what turns a one-word annotation into real behavior wrapped around your method — with not a line of boilerplate left in sight.

Spring proxies: JDK dynamic vs CGLIB

Ankit Verma — Mon, 17 Aug 2026 05:08:46 +0000

You put @Transactional on a method and a database transaction opens before it runs and commits when it returns — yet you never wrote a line to start or end one. You add @Cacheable, and the second call with the same arguments skips your method body entirely. You didn't touch the code inside those methods. So where does the extra behaviour actually run?

It runs inside a proxy: a stand-in object that Spring slips between whoever calls your bean and the real bean itself. You meet proxies the moment you use any Spring annotation that wraps behaviour around a method — transactions, caching, security, retries, async. Most of the time you never see it. This article is about what that stand-in is, the two very different ways Spring builds one at runtime, and the traps that appear once you know it sits in the path.

A proxy is just a stand-in

Forget Spring for a moment. Suppose you have a class that does real work behind an interface:

public interface PaymentService {
    void charge(String account, long cents);
}

public class RealPaymentService implements PaymentService {
    public void charge(String account, long cents) {
        // actually move the money
    }
}

Now say you want to log every charge, but you can't edit RealPaymentService. You could write a second class that implements the same interface, holds the real one inside, and adds the logging:

public class LoggingPaymentService implements PaymentService {
    private final PaymentService target;

    LoggingPaymentService(PaymentService target) {
        this.target = target;
    }

    public void charge(String account, long cents) {
        System.out.println("charging " + cents);
        target.charge(account, cents);   // forward to the real object
    }
}

Hand callers a LoggingPaymentService and they can't tell the difference — it is a PaymentService. That wrapper is a proxy: same surface, extra behaviour, forwarding to the real object underneath, which we'll call the target.

Everything Spring does with proxies is this pattern. The only twist is that you don't write the wrapper by hand. Spring manufactures one for you, at runtime, for a class it has never seen before.

Why Spring needs them

The logging above has nothing to do with payments. It would apply the same way to refunds, lookups, anything. A behaviour that cuts across many unrelated methods like that is a cross-cutting concern. Transactions, security checks, caching, and metrics are all cross-cutting — you don't want to paste the same boilerplate into every method body.

Spring's answer is to keep your method clean and push the concern into a proxy. You annotate the method; Spring wraps the bean; the annotation's behaviour lives in the wrapper. That leaves one real question: how does Spring build that wrapper on the fly? There are two mechanisms, and the difference between them is the whole point of this topic.

Way one: a JDK dynamic proxy

Java has shipped a proxy tool since version 1.3: java.lang.reflect.Proxy. Give it a set of interfaces and it generates — in memory, at runtime — a brand-new class that implements them. That generated object is a JDK dynamic proxy.

Every call on it is funnelled into a single method you write, an InvocationHandler:

PaymentService proxy = (PaymentService) Proxy.newProxyInstance(
    real.getClass().getClassLoader(),
    new Class[]{ PaymentService.class },      // interfaces to mimic
    (proxyObj, method, args) -> {
        System.out.println("before " + method.getName());
        Object result = method.invoke(real, args);   // forward to target
        System.out.println("after " + method.getName());
        return result;
    });

The lambda is the handler. When someone calls proxy.charge(...), Java routes it into the lambda with method = charge and args = [...]. You run your extra work, call method.invoke(real, args) to reach the real object, and return its result. It's the hand-written wrapper from before — except the class was generated for you.

The catch hides in that second argument: new Class[]{ PaymentService.class }. A JDK dynamic proxy can only mimic interfaces. The generated class implements PaymentService, but it is not a RealPaymentService — it's a synthetic class that merely shares the interface. So this style works only when your bean has an interface to stand behind.

Way two: a CGLIB proxy

What if the bean has no interface — just a plain class? Java's built-in proxy can't help, so Spring reaches for a library called CGLIB. Instead of implementing an interface, CGLIB generates a subclass of your class at runtime and overrides its methods:

Enhancer enhancer = new Enhancer();
enhancer.setSuperclass(RealPaymentService.class);   // subclass the real class
enhancer.setCallback((MethodInterceptor) (obj, method, args, proxyRef) -> {
    System.out.println("before " + method.getName());
    Object result = proxyRef.invokeSuper(obj, args);   // call the original method
    System.out.println("after " + method.getName());
    return result;
});
PaymentService proxy = (PaymentService) enhancer.create();

The shape is identical — do something, forward, do something — but the mechanism differs. The proxy here is a subclass, so it genuinely is-a RealPaymentService. invokeSuper calls the original parent method, which is CGLIB's way of reaching the real behaviour.

Because it works by subclassing, CGLIB needs no interface at all. That is its entire reason to exist.

How Spring picks one

Spring makes this choice for you. The classic rule, still true in plain Spring Framework, is simple:

Bean implements at least one interface → JDK dynamic proxy against that interface.
Bean has no interface → CGLIB subclass.

You can force CGLIB even when interfaces exist, with a flag:

@EnableTransactionManagement(proxyTargetClass = true)

That proxyTargetClass = true says "subclass the class, don't proxy the interface." Spring Boot took this further: since Boot 2.0 the default is CGLIB for everything, interface or not. The reasoning is practical — a JDK proxy exposes only the interface, so any code that injects the concrete class breaks (more on that shortly). Subclass proxies avoid that whole category of surprise, so Boot standardised on them.

Gotcha 1: self-invocation

Now the traps — and nearly all of them fall out of one fact: the proxy only wraps calls that arrive from outside the bean. A call the bean makes to itself never leaves the object, so it never passes through the proxy.

Picture a bean where one method calls another:

@Service
public class Orders {

    public void placeAll(List<Order> orders) {
        for (Order o : orders) {
            save(o);            // internal call — stays inside 'this'
        }
    }

    @Transactional
    public void save(Order o) {
        // expected to run in its own transaction
    }
}

You'd expect every save to run in a transaction. It doesn't. When placeAll calls save, that is a plain this.save(o) — it happens inside the real object, underneath the proxy. The proxy never sees it, so the @Transactional wrapping is skipped. Only a call to save from another bean, which enters through the proxy, gets a transaction.

This is the single most common Spring surprise. @Transactional, @Cacheable, @Async — all of them silently do nothing on self-invocation, and the code looks completely correct. The fix is to make the call go through the proxy: move the annotated method into a separate bean, or inject the bean into itself and call through that injected reference.

Gotcha 2: final and private methods

CGLIB works by subclassing and overriding. Java won't let you override a final method or subclass a final class — so CGLIB simply can't wrap them. There's no error, just no proxying: a @Transactional on a final method quietly does nothing.

private methods hit the same wall for a different reason. A subclass can't override a private method, and an interface can't declare one, so neither proxy style can wrap it. Keep proxied methods public and non-final and you stay clear of this trap.

Gotcha 3: inject the interface, not the class

With a JDK dynamic proxy, recall that the proxy implements the interface but is not your class. So this injection blows up:

@Autowired
RealPaymentService payments;   // fails if a JDK proxy is in play

The proxy can be assigned to PaymentService but not to RealPaymentService, so Spring throws at startup. Inject the interface instead:

@Autowired
PaymentService payments;       // fine — the proxy is-a PaymentService

This is exactly the breakage that Boot's "CGLIB everywhere" default sidesteps: a subclass proxy is the concrete type, so both forms work.

Gotcha 4: the constructor runs oddly

CGLIB builds its subclass through a route that doesn't call your constructor the normal way — your bean's constructor can run twice, or field initialisers may not have run when you'd expect. The practical rule: don't put real work or important side effects in the constructor of a proxied bean. Do that setup in an @PostConstruct method, which Spring calls once on the fully built instance.

The one model to keep

A Spring proxy is a stand-in that wraps your bean so annotations can add behaviour around your methods without touching their bodies. It's built one of two ways: JDK dynamic proxies implement your interface; CGLIB proxies subclass your class — and Spring Boot defaults to CGLIB so the concrete type still resolves. Every proxy gotcha falls out of two facts: the wrapper only sees calls that enter from outside, so self-invocation escapes it; and it can only wrap what it can override or implement, so final and private escape it. Hold those two facts and the rest is just detail.

BeanPostProcessor & BeanFactoryPostProcessor

Ankit Verma — Mon, 17 Aug 2026 05:08:42 +0000

Two hooks with nearly the same name

Spring's container builds your objects so you don't have to. You mark a class, and a fully-wired object — a bean — appears, ready to use. Most days you never think about how that happens.

But Spring itself has to think about it constantly. To turn a ${db.url} placeholder into a real value, to satisfy an @Autowired field, to wrap a service in a transaction proxy — Spring needs a way to reach into its own build process and change what comes out. It does this through two official extension points, and their names are the single most confused pair in the framework: BeanFactoryPostProcessor and BeanPostProcessor.

They sound like synonyms. They are not. The difference is when they run and what they are allowed to touch — and once you see that, the confusion disappears for good. So we'll build the timeline first, then meet each hook in its place.

The container works in two passes

When the context starts, it does not build your beans in one motion. It works in two distinct passes.

First, it reads every source of configuration — your @Configuration classes, component scans, any XML — and turns each one into a bean definition: a plain metadata object describing how a bean should be built. Its class, its scope, its constructor arguments, its property values. A definition is a blueprint. No object exists yet; at this point the container is just holding a stack of blueprints.

Second, once all the blueprints are collected, the container starts instantiating — walking the definitions and actually building live objects from them, wiring each one's dependencies, running its init code.

Hold onto that split: blueprints first, buildings second. Each of the two post-processors hooks into exactly one of those passes. That is the whole distinction.

BeanFactoryPostProcessor — editing the blueprints

The first hook runs at the seam between the two passes: after every bean definition is loaded, but before a single bean is instantiated. It is called BeanFactoryPostProcessor, and it exists to let you edit the blueprints while they are still just blueprints.

The interface has one method:

public interface BeanFactoryPostProcessor {
    void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory);
}

That beanFactory argument is the container holding all the definitions. You can walk it, read any bean's definition, and change it before that bean is ever built.

Here is a small one that forces every bean to be lazily initialised:

@Component
public class LazyEverything implements BeanFactoryPostProcessor {
    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory bf) {
        for (String name : bf.getBeanDefinitionNames()) {
            bf.getBeanDefinition(name).setLazyInit(true);
        }
    }
}

We loop over every definition and flip its lazyInit flag. Because this runs before instantiation, the change lands in time to matter — when the container later builds these beans, it reads the modified blueprint. We changed the plan, not the product.

You have almost certainly relied on a BeanFactoryPostProcessor without noticing. Whenever a ${...} placeholder appears in your configuration — a database URL, a port number — something has to replace it with a real value from your properties files. That something is PropertySourcesPlaceholderConfigurer, a BeanFactoryPostProcessor Spring registers for you. It runs in this between-the-passes window and wires up placeholder resolution before any bean that needs a value is built.

There is a close cousin worth naming once: BeanDefinitionRegistryPostProcessor. It runs a moment earlier and can add whole new definitions, not just tweak existing ones — it is how your @Configuration classes get turned into bean definitions in the first place. Same idea, one step further up the chain.

The rule to carry: a BeanFactoryPostProcessor sees definitions, never instances. The moment you find yourself wanting the actual built object, you have reached for the wrong hook — which is the other one.

BeanPostProcessor — intercepting each finished bean

The second hook runs in the second pass, during instantiation. After the container builds a bean and injects its dependencies, and around the moment it runs the bean's init code, every BeanPostProcessor gets a turn with that live object.

This interface has two methods:

public interface BeanPostProcessor {
    Object postProcessBeforeInitialization(Object bean, String beanName);
    Object postProcessAfterInitialization(Object bean, String beanName);
}

Recall the init step of a bean's life — the callback that runs once a bean is fully wired, like a method marked @PostConstruct. These two methods bracket that step: before runs just before your init code, after runs just after. Every bean in the container passes through both, one bean at a time.

These callbacks are not exotic edge cases — Spring implements its own annotations with them. The @Autowired field injection and the @PostConstruct call you use every day are each carried out by a BeanPostProcessor that Spring registers on your behalf. The hook is not a rarely-used escape hatch; it is the machinery the framework itself runs on.

A trivial logger shows the bare shape:

@Component
public class InitLogger implements BeanPostProcessor {
    @Override
    public Object postProcessAfterInitialization(Object bean, String name) {
        System.out.println("Finished building: " + name);
        return bean;
    }
}

Notice the method returns a bean. That return value is the detail that makes this hook powerful — and it is worth slowing down on.

The return value is a swap point

Whatever object you return from postProcessAfterInitialization is what the container uses from then on. Return the same bean, and nothing changes. Return a different object that wraps the original, and you have quietly substituted the bean the whole application will see.

That is exactly how Spring gives you proxies. When a method carries @Transactional, the real bean is built normally — then a BeanPostProcessor catches it in the after-init step and returns a proxy: a stand-in object of the same type that opens a transaction, calls through to your real bean, and commits. Nobody who injected that bean can tell the difference. They asked the container for a PaymentService and got something that looks and types like one.

// what you wrote
@Transactional
public void transfer(...) { ... }

// what the container actually hands out
PaymentService proxy = wrapInTransaction(realService);

The same mechanism powers Spring AOP, caching, and security checks — any feature that needs to run code around your methods. All of it rides on that one move: a BeanPostProcessor returning a wrapper in the after-init step. Once you see the swap, a large amount of Spring's "magic" stops being magic.

Why this order causes a real trap

Now the gotcha, and it follows straight from the timeline. For a BeanPostProcessor to wrap other beans, it obviously has to exist before those beans are built. So Spring instantiates all BeanPostProcessors first, up front, before it starts on your ordinary beans.

That early instantiation is a trap waiting to spring. Suppose your post-processor needs a dependency:

@Component
public class AuditingProcessor implements BeanPostProcessor {
    @Autowired
    private PaymentService paymentService;   // trouble
    // ...
}

To build this post-processor, Spring must first build PaymentService to inject it. But this is happening in the early phase — before all the other post-processors are registered. So PaymentService gets created too soon and skips the post-processors that are not set up yet. If one of them was going to give it a transaction proxy, that proxy never happens. Your @Transactional silently does nothing.

Spring even warns about it in the log, in a line worth recognising:

Bean 'paymentService' is not eligible for getting processed by all BeanPostProcessors (for example: not eligible for auto-proxying)

The fix is to keep post-processors lean. They should depend on as little as possible, and never pull in the very beans they are meant to process. A post-processor is infrastructure, built before the world exists — treat it that way.

When many hooks compete: ordering

Because these hooks decide the shape of every bean, the order they run in matters. Two post-processors could both want to wrap the same object; which one wins? Spring lets a hook declare its place by implementing Ordered (or PriorityOrdered for the ones that must run first of all), returning a number — lower runs earlier.

@Component
public class FirstInLine implements BeanPostProcessor, Ordered {
    @Override public int getOrder() { return 0; }   // runs before higher numbers
    // ...
}

The same ordering applies to BeanFactoryPostProcessors among themselves. It rarely matters for hand-written hooks, but when two of them interact — two things both rewriting definitions, or two proxies stacking on one bean — Ordered is how you make the outcome deliberate instead of accidental.

The one mental model

Strip it all back and it is a single picture. The container runs in two passes: collect the blueprints, then construct the buildings.

A BeanFactoryPostProcessor works on the blueprints, between the passes. It sees bean definitions and can rewrite them before anything is built. Placeholder resolution lives here.
A BeanPostProcessor works on the buildings, during the second pass. It sees each live bean as it is initialised and can wrap or replace it. Proxies — transactions, AOP, caching — live here.

Both are called "post-processor" because both are Spring's way of stepping into its own construction line. Once you know which pass a hook belongs to, you always know what it is allowed to touch — a definition or an object — and every confusingly-named "…PostProcessor" in the framework falls neatly into one of the two.

Recap — M0 Foundations

Ankit Verma — Tue, 16 Jun 2026 09:40:01 +0000

This module built one thing, from many angles: the container — the part of Spring that creates your objects, wires them together, and hands them out. Eight articles each zoomed in on a different corner of it. This recap zooms back out. The goal here is not to re-explain each topic, but to show how they are all the same idea seen from different sides, so the whole module collapses into a picture you can hold in your head at once.

So before the details, here is the single sentence the entire module hangs on: the container is a factory that runs at startup, and almost every feature you met is just that factory doing a little extra work while it builds a bean. Keep that sentence close. Everything below is a way of filling it in.

The factory, in one picture

Picture an assembly line that runs exactly once, when your application boots. You hand it a list of what to build and how the pieces fit. It builds every object your app is made of, connects them, sets them on a shelf, and hands them out on request for the rest of the program's life.

That assembly line is the container. The objects it builds and manages are beans. An object you create yourself with new is not a bean — Spring never touched it — and that distinction is the thread running through every trap in this module.

The factory does four things at startup, and the order matters: it reads recipes, works out who needs whom, builds from the bottom up, and caches each result.

ApplicationContext ctx = SpringApplication.run(App.class, args);
OrderService svc = ctx.getBean(OrderService.class); // already built and wired

By the time run returns, the work is done. Asking for a bean is instant because the building already happened. Every other topic in the module is a detail about how that one startup pass works.

Why we hand the work over at all

The module opened with a question of control. Left alone, a class builds its own collaborators with new — and in doing so it welds together two unrelated decisions: what it needs, and which exact thing it gets and how that thing is built.

class OrderService {
    private final PaymentGateway gateway = new PaymentGateway(new HttpClient());
}

Pulling those two decisions apart is the whole point. The class should declare what it needs and let something outside choose and supply the which. Handing that choice to the framework is Inversion of Control — your code stops creating its own collaborators. The way the collaborator then arrives is Dependency Injection — it is passed in from outside.

@Service
class OrderService {
    private final PaymentGateway gateway;

    OrderService(PaymentGateway gateway) {   // declares the need, receives it
        this.gateway = gateway;
    }
}

IoC is the idea; DI is the delivery. And the delivery has a preferred form for a mechanical reason, not a stylistic one: constructor injection makes the field final, makes the object impossible to build half-wired, and makes it testable with a plain new in a unit test. That preference for the constructor is a decision the rest of the module keeps cashing in.

How a single bean comes to life

Once you accept that the factory builds your beans, the natural next question is how it builds one. The answer is a fixed four-stage sequence — the bean lifecycle:

Instantiate — construct the raw object.
Populate — inject field- and setter-style dependencies.
Initialize — run setup now that everything is wired.
Destroy — run teardown at an orderly shutdown.

The order is the lesson. A field-injected dependency is null if you touch it in the constructor, because populate (stage 2) has not run yet. Setup that needs dependencies belongs in @PostConstruct (stage 3), where wiring is guaranteed complete. Teardown mirrors it in @PreDestroy (stage 4).

Notice how this rewards constructor injection again: it folds populate into instantiate, so a constructor-injected bean is never half-there. The lifecycle is just the factory's per-bean routine, and most of its surprises come from forgetting which stage runs when.

How many, and how long

The lifecycle describes one bean's journey. Scope answers the other two questions about it: how many instances exist, and how long each lives.

Singleton — one instance per container, the default, shared by everyone.
Prototype — a fresh instance on every request, built on demand.
Request and session — one instance per HTTP request or per user session.

"Shared," in the singleton line, is the dangerous word, and it leads to the module's most common bug. Because one singleton serves every thread at once, any mutable field on it is a race condition.

@Service
class CartService {
    private int itemCount;          // one field, every thread, lost updates
    void addItem() { itemCount++; }
}

The rule that falls out is short: keep singletons stateless. Immutable shared state — your injected dependencies — is exactly what a singleton is good at; mutable shared state is the trap.

Which container is doing all this

Up to here, "the container" has been a single idea. In Spring's code it wears two names, and the difference matters. BeanFactory is the minimal contract — store recipes, build beans lazily on request. ApplicationContext extends it and staffs it.

That staffing is the whole reason you always use the ApplicationContext. Features like @Autowired and @PostConstruct are not part of the factory core — each is a plugin called a BeanPostProcessor that gets a crack at every bean during the lifecycle. The bare BeanFactory registers none of them, so it silently ignores your annotations. The ApplicationContext registers them all automatically, and it builds singletons eagerly at startup — so a broken wiring fails at boot, on your machine, not three days later in production.

ApplicationContext ctx = new AnnotationConfigApplicationContext("com.shop");
// every annotation honored, every singleton already built

This is the same fail-fast instinct constructor injection showed with circular dependencies: surface the problem at the safest possible moment.

How you tell the factory what exists — and how it finds it

The factory needs recipes. Where they come from is the configuration style, and Spring has had three, each fixing the last one's pain:

XML — all wiring in an external file. Central, but verbose and string-typed.
Annotations — @Component and friends mark the class itself. The default for your own code.
Java config — @Bean methods inside a @Configuration class. The way to register classes you cannot annotate, like third-party objects.

All three end as the same internal bean definitions, which is why one app mixes them freely. Java config carries one subtlety worth keeping: Spring wraps a @Configuration class in a proxy so that a call from one @Bean method to another returns the shared bean instead of building a second one.

For the annotation style, component scanning is how the factory actually finds your marked classes. @ComponentScan walks a base package and everything beneath it — and only ever downward, which is why the main class lives in the root package, and why a class above the scan's start point silently never registers. The stereotypes — @Service, @Repository, @Controller — are just @Component with a role attached, scanned identically, though @Repository earns exception translation as a bonus.

How the factory connects the beans

With every bean found and defined, the last job is wiring them — autowiring. The rule is resolution by type: the container finds the one bean whose type fits a dependency and injects it. One match and the wiring is silent.

The interesting part is the tie-break, when two beans fit one slot. The container refuses to guess and fails fast; you break the tie three ways:

Parameter name — a quiet fallback that matches the injection point's name to a bean name.
@Primary — one global default, declared on the bean.
@Qualifier — a named choice at the injection point, which overrides @Primary.

And when a dependency might legitimately be absent, Optional<T> or ObjectProvider<T> make that explicit instead of crashing.

The two threads that run through everything

Step back and two ideas turn out to connect almost every topic.

The first is the proxy — a same-shaped stand-in the factory can hand you instead of the bare bean. It is not one feature; it is the same trick reused everywhere. It is how @Transactional opens a transaction around your method. It is how a request-scoped bean gets injected into a singleton — the proxy resolves to the right per-request instance on each call. It is how a @Configuration class avoids building a bean twice. And its timing — created after @PostConstruct runs — is why init code self-calling a proxied method quietly skips the wrapper. Once you see the proxy, a dozen "how does Spring even do that?" questions share one answer.

The second is fail-fast: surface a mistake at the earliest, safest moment. Eager singleton startup catches broken wiring at boot. Constructor injection turns a circular dependency into a boot-time error instead of a production StackOverflowError. An ambiguous autowire stops the app rather than picking the wrong bean. The strictness is the safety.

The traps, as one family

Almost every gotcha in this module is the same mistake wearing different clothes — a mismatch between when injection happens and when you use the result:

A field-injected dependency touched in the constructor is null — populate runs after the constructor.
A mutable field on a singleton races — one instance is wired once and shared across every thread.
A prototype injected into a singleton freezes — injection is a one-time event, so you get one prototype forever; reach for ObjectProvider to pull a fresh one each call.
A proxied method self-called inside @PostConstruct skips the proxy — the wrapper is not built yet.

See them together and they stop being four facts to memorize. They are all consequences of one truth: for a singleton, wiring happens exactly once, at startup.

The one picture to keep

If you keep only one thing from this module, keep the factory. The container reads recipes, builds your beans bottom-up in dependency order, can wrap each one in a proxy, caches the results, and fails fast when something does not fit. Inversion of Control is why you hand the work over; dependency injection is how the pieces arrive; the lifecycle is how one bean is assembled; scope is how many and how long; the ApplicationContext is the fully-staffed factory that runs it; configuration, scanning, and autowiring are how it learns what to build and connects it all.

Everything heavier you meet from here — AOP, transactions, web request handling, data access — is a variation on this one startup pass. The factory does not go away. It just keeps finding new work to do while it builds your beans.

@Autowired resolution, @Qualifier/@Primary, injection types + circular-dependency gotcha

Ankit Verma — Mon, 15 Jun 2026 10:44:01 +0000

The last article left the container in a tidy state. Scanning has finished, and every class you marked is now a bean definition sitting in the container, names and all. But a definition is just a recipe. The moment the container starts actually building beans, it hits the question this article is about: to build OrderService, it needs to pass something into the PaymentGateway slot in its constructor — so which bean does it reach for?

When exactly one bean fits, the answer is obvious and you never think about it. The interesting part is everything around that happy path: how the container makes the match, what happens when two beans fit the same slot, and how you steer the choice when it can't decide on its own.

That whole job — the container finding and supplying the beans a dependency needs, instead of you naming each one by hand — is called autowiring. You meet it for real the first time Spring refuses to start, complaining it found more than one bean of some type and doesn't know which you meant. To fix that on purpose instead of by trial and error, you need to see how resolution actually works.

This article walks it end to end: the match by type, why @Autowired is often already implied, the ambiguity that breaks the match, the three tools that break the tie, what to do when a bean might be missing — and finally a deeper look at the circular-dependency trap the dependency-injection article only cracked open.

The happy path: resolution by type

Start with the rule from the dependency-injection article, now seen from the container's side. When the container builds a bean and reaches a dependency, it looks through every bean it knows about for one whose type fits, and injects that one.

@Service
class OrderService {
    private final PaymentGateway gateway;

    OrderService(PaymentGateway gateway) {   // "I need a PaymentGateway"
        this.gateway = gateway;
    }
}

If there is exactly one PaymentGateway bean in the container, the match is unambiguous and the wiring just happens. You declared a need by type; the container found the one bean that satisfies it and handed it over. That is autowiring in its simplest, invisible form.

Where did `@Autowired` go?

You may have noticed there is no @Autowired on that constructor. That is not an oversight. When a class has a single constructor, Spring treats it as an injection point automatically — it assumes the parameters are dependencies to resolve, no annotation required.

So @Autowired only needs to appear in the cases Spring cannot infer:

On a class with more than one constructor, to mark which one the container should call.
On a field or setter, where there is no sole constructor for Spring to assume.

@Service
class OrderService {
    @Autowired                                  // needed here only if there are other constructors
    OrderService(PaymentGateway gateway) { /* ... */ }
}

The useful way to hold it: @Autowired marks an injection point — a spot that says "fill this in from the container." A parameter on a sole constructor is an injection point implicitly. Everywhere else, the annotation is how you point at one.

When two beans fit one slot

Now the situation that breaks the happy path. Suppose two classes implement the same interface, and both are beans:

@Component
class StripeGateway implements PaymentGateway { /* ... */ }

@Component
class AdyenGateway implements PaymentGateway { /* ... */ }

OrderService still asks for a single PaymentGateway. The container searches by type and now finds two candidates. It has no basis to prefer one, and it will not guess. It fails at startup:

NoUniqueBeanDefinitionException: expected single matching bean
but found 2: stripeGateway, adyenGateway

This is the fail-fast philosophy again — an ambiguous wiring is caught at boot, on your machine, not silently resolved into the wrong gateway in production. Spring gives you three ways to resolve it, and they are worth knowing as a set, because they layer.

Tie-breaker 1: the parameter name

Before you reach for any annotation, Spring has a quiet fallback already running. When the type matches several beans, it tries to narrow them by name — matching the name of the injection point against the bean names. Recall from the scanning article that a scanned bean is named after its class, decapitalized: StripeGateway becomes stripeGateway.

@Service
class OrderService {
    OrderService(PaymentGateway stripeGateway) {   // parameter name matches a bean name
        // resolves to the stripeGateway bean
    }
}

Name the parameter stripeGateway and the ambiguity disappears: the container matches it to the bean of that name. It works, but lean on it carefully. It depends on parameter names surviving compilation (Spring Boot compiles with that turned on, so they do), and it is subtle — renaming a parameter silently rewires the application. It is fine as a fallback; it is a poor way to express intent. For that, be explicit.

Tie-breaker 2: `@Primary` — declare a default winner

@Primary marks one bean as the default to use whenever several fit:

@Component
@Primary
class StripeGateway implements PaymentGateway { /* ... */ }

@Component
class AdyenGateway implements PaymentGateway { /* ... */ }

Now any unqualified PaymentGateway injection, anywhere in the app, gets Stripe. The key trait is that @Primary lives on the bean — one declaration, applied everywhere that type is needed. It is the right tool when there is one obvious default and only rare exceptions.

Tie-breaker 3: `@Qualifier` — name the one you want

@Primary decides globally. @Qualifier decides at a single injection point. You give the beans qualifier names and then ask for one by name right where you need it:

@Component
@Qualifier("stripe")
class StripeGateway implements PaymentGateway { /* ... */ }

@Component
@Qualifier("adyen")
class AdyenGateway implements PaymentGateway { /* ... */ }

@Service
class OrderService {
    OrderService(@Qualifier("stripe") PaymentGateway gateway) {   // this slot wants Stripe
        // ...
    }
}

And the two combine cleanly. When both are present, @Qualifier at the injection point wins over @Primary. The idiom that falls out: mark the everyday default with @Primary, and use @Qualifier only at the few spots that need the exception. Most of the code stays quiet; the deviations are explicit.

When the bean might not be there

The mirror image of ambiguity is absence. If a required dependency has no matching bean, the container fails at boot with NoSuchBeanDefinitionException — the same fail-fast instinct. Usually that is exactly what you want. But occasionally a dependency is genuinely optional: a metrics sink that may or may not be configured, say. Spring has three ways to say "inject it if it exists, otherwise carry on":

@Autowired(required = false) — leaves a field or setter unset if no bean is found.
Optional<PaymentGateway> — arrives empty when the bean is absent.
ObjectProvider<PaymentGateway> — a lazy handle you ask for the bean only when you need it (the same type the bean-scopes article used to pull a fresh prototype on demand).

@Service
class OrderService {
    private final Optional<PaymentGateway> gateway;

    OrderService(Optional<PaymentGateway> gateway) {   // empty if no gateway bean exists
        this.gateway = gateway;
    }
}

Prefer Optional or ObjectProvider over required = false: they keep the field final and make the "might be absent" part visible in the type, instead of hiding it behind a field that is sometimes null. (And note the List<PaymentGateway> form from the DI article is a different case entirely — it asks for all matching beans on purpose, so several matches are the answer, not an error.)

Injection types, seen through resolution

The DI article already made the case for constructor injection over setters and fields, so this is just the same picture from the resolver's angle: the matching algorithm above is identical no matter where the injection point sits. @Qualifier and @Primary work the same on a constructor parameter, a setter, or a field.

What changes is when resolution runs and how safely. Constructor injection resolves everything at construction, so the object is never half-built and the fields can be final. Setter injection runs during the populate stage, which suits a truly optional or reconfigurable dependency. Field injection is the most concise and the least testable. The resolution rules don't pick a style for you — but as the next section shows, the style you pick decides how one particular failure behaves.

The circular-dependency gotcha, in full

The DI article showed one slice of this: two beans that depend on each other, wired through constructors, fail at boot. Here is the complete picture, because the outcome depends entirely on the injection style — and that is the whole lesson.

Say A needs B, and B needs A. With constructor injection on both sides, neither object can be built first: building A needs a finished B, which needs a finished A, and round it goes. The container detects the loop and stops:

BeanCurrentlyInCreationException:
Requested bean is currently in creation — is there an unresolvable circular reference?

That looks like an obstacle. It is actually the good case — the cycle is exposed the instant you start the app.

Now switch the two beans to field injection and watch the failure quietly vanish:

@Component
class A {
    @Autowired B b;
}

@Component
class B {
    @Autowired A a;
}

Because field injection happens after construction, Spring has a move available that constructors deny it. It builds the raw A first, then — before A is fully wired — exposes a reference to that half-built A. It builds B, setting B's field to the early A reference. With B now complete, it finishes wiring A by setting A's field to the finished B. The cycle resolves, and the application starts as if nothing were wrong.

That "as if nothing were wrong" is the trap. A circular dependency is a real design flaw — two beans so entangled that neither is whole without the other — and field injection lets it ship undetected. Constructor injection would have failed loudly at boot and forced the conversation. This is one more reason the earlier articles pushed constructors so hard: the strictness is the safety.

Spring offers an escape hatch, @Lazy, for when you must break a cycle without redesigning right now. Put @Lazy on one of the two injection points and the container injects a proxy — the same stand-in trick from the first article — instead of the real bean, deferring the real lookup until the first method call. By then both beans exist, so the loop never has to be resolved at construction time.

@Component
class A {
    A(@Lazy B b) { /* ... */ }   // injects a proxy now, resolves B on first use
}

Treat that as a patch, not a cure. The honest fix is to break the cycle: pull the shared logic into a third bean both can depend on, or let one side publish an event the other listens for, the way the ApplicationContext article wired OrderService to email without either knowing the other. A mutual dependency almost always means a responsibility is living in the wrong class.

It is worth knowing that recent Spring Boot takes your side here: since 2.6 it forbids circular references by default, so even a field-injected cycle fails at startup unless you deliberately set spring.main.allow-circular-references=true. The framework now nudges everyone toward the fix instead of the papering-over.

Putting it together

Autowiring is the container resolving each dependency by type: one matching bean and the wiring is silent, with @Autowired implied on a sole constructor and only spelled out for extra constructors, fields, and setters. When two beans fit one slot, the container fails fast rather than guess — and you break the tie three ways: the parameter name (a subtle fallback), @Primary (one global default on the bean), or @Qualifier (a named choice at the injection point that overrides @Primary). When a bean might be missing, Optional or ObjectProvider make the absence explicit instead of crashing.

The deepest point is the one about cycles. Resolution itself doesn't care which injection style you used — but a circular dependency does. Constructor injection turns it into a boot-time error you cannot miss; field injection papers over it and lets a design flaw ship. That asymmetry, now reinforced by Boot's default of refusing cycles outright, is the last and strongest argument for wiring through the constructor.

With that, the container's whole story is on the table: how it learns what your beans are, builds them, scopes them, and now connects them to each other. The next article steps back from the individual mechanisms and ties the entire Foundations module into one mental model — a recap of how every piece we have built fits together.

Component scanning & stereotypes

Ankit Verma — Sun, 14 Jun 2026 08:30:48 +0000

The last article left a thread dangling. It showed that the annotation style marks a class as a bean by putting @Component — or one of its cousins — right on the class, and then said the container finds those marked classes by component scanning. It promised that scanning was "its own topic, the very next article." This is that article.

Component scanning is the step where Spring walks through your code, finds the classes you marked as beans, and registers each one with the container. It is the bridge between "I annotated a class" and "the container knows that class exists." Without it, an @Service is just an annotation sitting on a class Spring never bothers to look at.

You meet scanning the first time a class you wrote refuses to show up. You added @Service, you asked the container for it, and Spring answers that there is no such bean. Almost always the class is sitting in a package the scan never visited. To fix that with intent instead of guesswork, you need to know what scanning actually does and where it actually looks.

This article walks the whole mechanism: how the scan finds your classes, the stereotype annotations that mark them, the one stereotype that quietly does more than mark, where the search begins, and the traps that come from searching too narrowly or too widely.

The mark and the search are two halves of one thing

Recall the single job of @Component: it labels a class as something the container should build and manage — a bean. But a label does nothing on its own. Something has to go looking for it.

That something is the component scanner. At startup, before a single bean is built, the scanner walks a set of packages, inspects every class it finds, and for each class wearing @Component it writes down a bean definition — the recipe card from the earlier articles. When the scan finishes, the container holds a definition for every annotated class, exactly as if you had spelled them all out in Java config by hand.

@Service
class OrderService {
    OrderService(PaymentGateway gateway) { /* ... */ }
}

On its own, that class is inert. The annotation says "I am a bean"; the scan is what hears it. Miss either half — forget the annotation, or never scan the package it lives in — and the bean simply does not exist.

Turning the scan on

You rarely write the line that starts scanning, but it is worth seeing once, plainly. The annotation that switches it on is @ComponentScan:

@Configuration
@ComponentScan("com.shop")
class AppConfig { }

That says: walk the com.shop package and everything beneath it, and register every @Component you find. The string is a base package — the root where the search begins. Scanning is recursive, so com.shop, com.shop.orders, and com.shop.billing.tax are all swept in by that one line.

In a Spring Boot app you never actually write @ComponentScan, because it is hidden inside the annotation on your main class. But it is running all the same, and knowing it is there is what makes the next trap avoidable.

Where the search starts — and the classic trap

The annotation on your main class, @SpringBootApplication, is a bundle: it folds together @Configuration, the auto-configuration switch, and @ComponentScan — the last one with no package argument.

When you give @ComponentScan no package, it does not scan nothing. It defaults to the package of the class it sits on, and everything below it.

package com.shop;          // the root package

@SpringBootApplication      // scans com.shop and downward
class ShopApplication {
    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }
}

This is the reason every Boot project puts its main class in the root package, above all the others. From there, the default scan naturally covers the whole application — com.shop.web, com.shop.billing, all of it.

Now the trap, which catches nearly everyone once. Move that main class down into a sub-package by mistake:

package com.shop.web;       // oops — not the root

@SpringBootApplication       // scans com.shop.web and downward ONLY
class ShopApplication { }

Scanning now starts at com.shop.web. Your com.shop.billing package is above the start point, so it is never visited, and none of its beans get registered. The symptom is a NoSuchBeanDefinitionException at startup — Spring asking for a bean it was never told about. The fix is to move the main class back up to the root, or to name the packages explicitly with @SpringBootApplication(scanBasePackages = "com.shop"). Either way, the cause is the same: the scan only ever looks down from where it starts.

The stereotypes: same scan, different meaning

@Component is the generic mark. On top of it, Spring ships three specialized labels — @Service, @Repository, and @Controller — known together as the stereotype annotations, because each names the role a class plays in the usual layered design: business logic, data access, web entry point.

Here is the detail that ties them to everything above. Each stereotype is itself meta-annotated with @Component — that is, @Component is stamped on the annotation itself:

@Component          // <-- right here, on the annotation
public @interface Service {
    // ...
}

Because the scanner treats "annotated with @Component, directly or through another annotation" as the trigger, a @Service is picked up by exactly the same scan as a bare @Component. There is no separate machinery for them. A stereotype is a @Component with a name on it.

So why bother with the specialized ones? Two reasons, both real but modest. They document the layer at a glance — @Repository tells a reader "this talks to the database" in a way @Component never could. And they give Spring and your tools a hook to treat a layer specially. For most classes the stereotypes are interchangeable with @Component; the habit is simply to pick the one that names what the class actually does.

@Repository earns more than its name

One stereotype does more than label, and it is worth knowing exactly what. When the scan registers a @Repository bean, Spring also wraps it in a proxy — the same stand-in trick from the first article — to perform exception translation.

Here is the problem it solves. Every persistence technology throws its own exceptions: raw JDBC throws SQLException, Hibernate throws its own HibernateException, and so on. If your service layer caught those directly, it would be welded to whichever library sits underneath.

@Repository
class JpaOrderRepository {
    Order findById(long id) { /* ... */ }   // may hit a vendor-specific failure
}

Because this is a @Repository, the proxy around it catches those vendor-specific exceptions on the way out and rethrows them as Spring's own DataAccessException family — one consistent hierarchy, the same no matter what runs below. Swap JPA for plain JDBC tomorrow, and the exception types your service code catches do not change. That single benefit is a concrete reason to put @Repository on data-access classes rather than a generic @Component.

The @Controller stereotype has its own special handling too — the web layer recognizes it and routes HTTP requests to its methods — but that belongs to the web module later. For now it is enough that the scan treats it like any other @Component, and something downstream gives it extra meaning.

Every scanned bean gets a name

When the scanner registers a bean, the container needs a name for it. By default, scanning takes the simple class name and decapitalizes the first letter: OrderService becomes the bean named orderService.

@Service
class OrderService { }      // registered under the name "orderService"

Most of the time you never touch the name, because injection resolves by type, as the dependency-injection article showed. The name starts to matter only when two beans share a type and you must point at one specifically — that tie-breaking is the next article's subject — or when two names collide.

The collision is worth flagging because it fails loudly. Put two classes with the same simple name in different packages, and both want to be orderService:

// com.shop.billing.OrderService   -> wants "orderService"
// com.shop.legacy.OrderService    -> also wants "orderService"

Scanning refuses the ambiguity and throws ConflictingBeanDefinitionException at startup. That is the fail-fast philosophy again — a name clash is caught at boot, not silently resolved into the wrong bean. When you genuinely need two such classes, give one an explicit name with @Service("legacyOrderService").

Scanning too wide

By default the scan registers everything annotated that it finds below the base package. Usually that is what you want. But a base package set too broad will quietly pull in classes you never meant to activate — a stray @Configuration in some sub-module that switches a feature on, or test-only beans that have no business in production.

For that, @ComponentScan accepts filters that include or exclude classes by annotation, type, or pattern:

@ComponentScan(
    basePackages = "com.shop",
    excludeFilters = @ComponentScan.Filter(
        type = FilterType.ANNOTATION,
        classes = Configuration.class)   // skip stray @Configuration classes
)
class AppConfig { }

Filters are the precise tool when the default sweep grabs too much. The blunter fix is the better default: keep your base packages tight. A narrow scan registers only what you intend, and as a bonus it costs less at startup — walking a smaller slice of the classpath is faster than walking all of it. Over-broad scanning is one of the quiet reasons a large application boots slowly.

Putting it together

Component scanning is how the annotation style turns marked classes into registered beans. The scanner walks a base package and everything under it, and for every class carrying @Component — directly or through a stereotype — it writes a bean definition into the container. The annotation declares the intent; the scan is what acts on it, and both halves are required.

The base package is where the search starts and only ever goes downward — which is why the main class lives in the root package, and why a class above the scan's start point silently never registers. The stereotypes — @Service, @Repository, @Controller — are @Component with a role attached; they are scanned identically, but @Repository also earns exception translation, and @Controller is later picked up by the web layer. Each scanned bean gets a decapitalized class name by default, and a name clash fails fast at boot.

So the scan ends with the container holding a complete set of bean definitions, names and all. Which raises the question the next article answers: when the container goes to build OrderService and sees it needs a PaymentGateway — and two beans happen to fit that type — how does it decide which one to inject? That is the job of @Autowired, @Qualifier, and @Primary, and it is where we go next.

DEV Community: Ankit Verma

Application events & ApplicationEventPublisher

A one-paragraph recap of the container

Announcing that something happened

Listening for the event

The part everyone gets wrong: it is synchronous

Moving the work off the thread with @async

The transaction trap

Two smaller controls worth knowing

Where this comes from for free

The one mental model to keep

SpEL basics

What SpEL actually is

The two dollar-hash cousins

Your first expressions: literals and math

Reaching into other beans

Mixing properties and expressions

Operators that make config decisions

Filtering collections without a loop

Running SpEL yourself

The context is the security boundary

Where you'll meet it again

Transaction isolation levels — what Spring controls

First, what a transaction guarantees on its own

The three ways concurrent reads go wrong

The four isolation levels

Where Spring enters: one annotation attribute

Spring sets the dial; the database does the work

Isolation.DEFAULT, and why it is the sensible default

The gotcha: isolation is ignored when you join an existing transaction

Each database reads the levels its own way

What to actually reach for

Transaction propagation (REQUIRED / REQUIRES_NEW / NESTED ...) (Part 2 of 2)

Picking up between "join" and "start fresh"

What a savepoint is

NESTED — a savepoint around the inner method

Why NESTED is not REQUIRES_NEW

The four modes you meet less often

When does a transaction actually roll back?

Telling Spring what to roll back on

The whole picture, in order

Transaction propagation (REQUIRED / REQUIRES_NEW / NESTED ...) (Part 1 of 2)

When one transactional method calls another

What "a transaction" actually is here

How Spring opens one for you — the proxy

Propagation: join, or start fresh?

REQUIRED — the default, and what "join" costs you

The rollback-only trap

The trap that silently disables all of this: self-invocation

Where this leaves us

@Transactional under the hood (proxy) + self-invocation gotcha

First, what a transaction even is

The boilerplate you'd otherwise write by hand

@Transactional moves that ceremony into a proxy

The transaction manager does the real database work

How your queries join the same transaction

Gotcha 1: rollback only fires for unchecked exceptions

Gotcha 2: swallow the exception and you lose the rollback

Gotcha 3: self-invocation — the transaction never starts

Gotcha 4: public and non-final only

The model to keep

AOP: aspect / pointcut / advice / weaving

The problem, in code

A point where behavior could run

The code that runs there: advice

Choosing where advice applies: the pointcut

Bundling it together: the aspect

How it actually gets applied: weaving

The trap the proxy creates: self-invocation

Where AspectJ comes in

Putting the vocabulary together

Spring proxies: JDK dynamic vs CGLIB

A proxy is just a stand-in

Why Spring needs them

Way one: a JDK dynamic proxy

Way two: a CGLIB proxy

How Spring picks one

Gotcha 1: self-invocation

Gotcha 2: final and private methods

Gotcha 3: inject the interface, not the class

`@Transactional` moves that ceremony into a proxy

Where did `@Autowired` go?

Tie-breaker 2: `@Primary` — declare a default winner

Tie-breaker 3: `@Qualifier` — name the one you want