BeanDefinition in Detail: The Registry Behind Every Bean

Beginners tend to picture Spring as "a factory that news objects for me in bulk". The truth is: during startup the container does not build objects at all — it first collects a book of instructions on how to build them, recording class names, scopes and init-method names. That instruction sheet is the BeanDefinition; the real object (the bean) is only produced from it later inside refresh(). Everything in this article hangs on one sentence: the container manages definitions, not objects.

Five words, one line each (they recur throughout):

• Container: the "housekeeper" object (ApplicationContext / BeanFactory) that creates and manages your objects; you ask it for things with getBean and it looks them up by name
• Bean: your plain Java object that has been handed to the container to create and manage
• BeanDefinition: a piece of data (not code) describing how to build one bean — which class, singleton or prototype, lazy or not, which init/destroy methods
• Registry: the Map holding every definition, beanName → BeanDefinition; any lookup starts there
• Reflection: calling a constructor or method by name at runtime. The container never binds your class at compile time — it builds the object reflectively from the definition's beanClass

After this article you should be able to answer three questions:

• Where exactly does the @Scope("prototype") I wrote on a class land — which table, which field?
• Are "XML configuration" and "annotation configuration" two mechanisms, or two entrances to the same one?
• Why must changes to which beans exist happen before step 5 of refresh(), while changes to what an object looks like need a different interface?

Ask "what does the container hold?" and the intuitive answer is "objects". That is precisely the common misconception — what really gets registered, looked up and rewritten during startup is the definition of an object, not the object itself.

Think of a household registry: a Bean is the actual person, and a BeanDefinition is that person's file — name (beanName), address (class), family members (dependsOn), notes (scope, lazy init, init method...). To look someone up, you first read the file; what gets copied, merged and edited is also the file. The object is "produced" from the file only at the very last moment.

This buys two crucial capabilities:

• Deferral and conditions: with definitions in hand, the container can "see the whole picture before deciding anything" — merging parent definitions, evaluating conditional wiring, and pre-building AOP proxies all happen before any object exists
• Programmability: drop a definition into the registry and the container treats it like any other bean. That is exactly how auto-configuration, @Bean and @Import conjure beans out of thin air

BeanDefinition is an interface; the real carrier is AbstractBeanDefinition and its subclasses. The core fields:

Here is what it looks like in code:

Those ten fields are only information on paper. Six steps still separate them from the object in your hand — scan, build the definition, register, get rewritten, instantiate, inject and initialize. Learn that route in ten seconds and every later section will occupy a spot on it:

Where do definitions come from? Three common paths. First, XML:

Second, annotation scanning:

Third, @Bean methods:

Place the same configuration written both ways side by side and the fields line up one for one — that is the visual proof of the sentence above:

Since definitions are the core, we can register one manually at runtime — "I can be a container too":

The console prints:

Six class names that look like a memorization drill — but only one question matters about each: which door did this definition come in through. Play a round: click the class, then click its origin.

Parent and child definitions are merged into one complete RootBeanDefinition before instantiation — the MergedBeanDefinition:

Even more powerful: a definition can be rewritten in bulk by a post-processor before instantiation. BeanFactoryPostProcessor runs at step 5 of refresh(), when all definitions are registered but no singleton has been created yet — the last window to change definitions:

Those two names that differ by one word are actually half a lifetime apart on the timeline. Cells ①→④ in the animation are the window where the paperwork can still be edited; once ④ passes, nobody reads definitions again, and everything in ⑤⑥ happens to objects:

This one deserves an animation, because "identical definition, one extra object" is the kind of difference beginners refuse to believe. Watch cell ②: in full mode a call to your own @Bean method is intercepted and answered from the singleton pool. Lite mode has no interception — the method is an ordinary method, so every call really does construct something:

The demo below visualizes "how each definition changes state in the Beans list" — from registration, through being rewritten by a post-processor, to final instantiation:

That one shows the result of wiring. To follow this article's actual thread — how an annotation becomes a definition — go back to the scanning scene. The lab below is that chain itself: pick "Scan & parse" to see how @Component is translated into an AnnotatedGenericBeanDefinition, then "scope / lazy attrs" to see which field your annotation value actually lands in:

The XML path works the same way, only its entrance is a file reader. This lab unfolds the whole XML container startup, and its last argument — "a typo in class" — maps directly onto the first row of the error table in Section 13:

A definition is not fixed once written: step 5 of refresh() runs processors whose entire job is adding and editing definitions. That is exactly how auto-configuration conjures beans. First locate that step in the twelve-step lab:

Conditional assembly (@Conditional) decides whether a definition enters the registry at all. Thousands of Boot auto-configured beans are discarded precisely this way:

One last definition-level special case belongs here: some definitions name a class that is not the type you receive. FactoryBean is precisely that — a definition that says "factory" while the container hands out "product". That is what Section 2 meant by "beanClass may point at the class holding the factory method". Start with the headline behaviour:

And the type question — the container answers "what type is this bean?" by calling getObjectType(), which is what type-based injection and @ConditionalOnBean key off. Get that wrong and you get the strangest message in this article: "the definition is there, yet no bean of this type exists":

Everything above answers where definitions come from. This answers how one is spent. The debugger below shows the real skeleton of getBean; the right-hand panel refreshes the variables and the call stack as you step — press next seven times and watch step ④, the moment the paperwork gets merged and then finally consumed:

Time to type the commands yourself. This console talks to the real container running in your browser; beans prints what the registry holds right now (name, scope, laziness) while di prints the wiring graph. Walk the claims of this article one line at a time:

What makes BeanDefinition feel abstract for beginners is this: the annotation you write on a class merely fills one cell of one table. Fill it right and you save memory; fill it wrong and every request gets a brand-new object — with no exception anywhere. The sandbox below folds "scope + lazy" into one switch; each position shows the consequence immediately:

A warm-up, straight from the field table in Section 2 and the sandbox above:

The heavier one, tying Section 6 and the decision card together:

Every excerpt below can be pasted into a search box unchanged. They share one family trait: each is a complaint about the paperwork — a missing card, two cards on the same drawer, or a card with the wrong cell filled in.

Row one is this article's most typical missing-file scene. Do not read the answer first — click the frame you believe is guilty in this real stack:

Goal: put two definitions into the registry yourself — one singleton, one prototype — and verify both halves of the story at once: what the definition fields say, and how many objects exist.

Step one, pom.xml needs a single dependency:

Step two, a minimal class at src/main/java/com/example/demo/HelloServiceImpl.java:

Step three, the driver at src/main/java/com/example/demo/DefinitionLab.java:

Run main. Expected output (the @xxxxxx parts are hash addresses and will differ on your machine; the singleton must log one construction line, and the two prototype addresses must differ):

Three readings of that output: ① the first construction line appears inside refresh(), not after any getBean — which is "registering is paperwork, refresh is production" proven on your own console; ② scope=[] is an empty string — the default singleton is not written into the definition as the word "singleton", only an explicit setting appears there, which is why you must ask isSingleton() instead of comparing strings; ③ the definition count is exactly 2, because GenericApplicationContext inserts no built-ins, unlike AnnotationConfigApplicationContext, which gives you a dozen internal bean names the moment you refresh.

Done when: ① you deleted .setScope(SCOPE_PROTOTYPE), saw prototype == ? turn into true — you just edited a definition and watched behaviour follow; ② you can say at which step hiSingleton was created (Section 4 plus step twelve in the next article); ③ you registered one beanName twice with two different classes and wrote down the exception verbatim.

Change one thing per run, and predict before you execute:

1. Add singletonBd.setLazyInit(true). You will observe the construction line for hiSingleton move out of refresh() to the moment of the first getBean — @Lazy / lazyInit changes only timing, never scope; it remains a singleton.
2. Call ctx.registerBeanDefinition("late", bd) after ctx.refresh(). You will observe no IllegalStateException from a GenericApplicationContext, but that definition is never pre-instantiated and can only be reached by an explicit getBean — this is why the Section 4 trap insists on BeanDefinitionRegistryPostProcessor for late registrations.
3. Register hiPrototype2, same HelloServiceImpl type but a different beanName, then call ctx.getBean(HelloServiceImpl.class). You will observe NoUniqueBeanDefinitionException: ... expected single matching bean but found 3, matching row two of the table above; add singletonBd.setPrimary(true) and it recovers instantly.
4. Grab the definition with ctx.getBeanFactory().getBeanDefinition("hiSingleton") and read getResourceDescription(). You will observe null for your hand-registered bean, while XML or scanned definitions carry a file name or class path — the single most useful trick when asking "who registered this bean?".

Tip: after variant 3, rerun the bd lab from Section 8 with the multi argument. The framework's view and your manual reproduction should agree exactly; where they don't, you have found something worth writing down.

Write DefinitionDumper, a mini registry visualizer for any project — plausibly the first framework-grade tool you own.

Requirements:

• A static dump(ConfigurableApplicationContext ctx) that walks getBeanDefinitionNames() and prints one line per bean: beanName | scope | lazyInit | primary | beanClassName | origin (resourceDescription)
• A summary block: total definitions, singleton / prototype / other-scope counts, how many are lazy, how many declare a parent (getParentName() != null)
• A filter argument listing only definitions whose class name contains a keyword, e.g. dump(ctx, "Tx")
• Bonus: flag suspicious same-name definitions coming from different origins by comparing resourceDescription — that is exactly the pre-emptive check for a BeanDefinitionOverride

Done when: ① running dump(ctx) in an empty Spring Boot project prints hundreds of lines including auto-configured definitions; ② --filter=DataSource narrows it to single digits; ③ you can manufacture a name collision and the tool warns before startup fails; ④ nothing in it depends on private API beyond reflection — every call comes from public ConfigurableListableBeanFactory methods.