Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Getting Started

Build-Time Architecture

Understand how Quarkus does its work at build time: Jandex indexing, augmentation, recorders, closed-world assumptions and what they mean for your code.

The previous lessons said that Quarkus "moves work to the build". Now we look at how. Understanding this model explains many behaviours that surprise beginners: why unused beans disappear, why some properties cannot change at runtime, why reflection needs a hint and why a Quarkus application starts so quickly.

You do not need this knowledge to write endpoints, but it makes debugging much easier. As before, the real Quarkus classes are described in words and read-only snippets, and the runnable examples are plain-Java stand-ins: an index of annotated classes and a "closed world" dead-code remover.

Two phases: augmentation and runtime

A Quarkus build has a step called augmentation. It runs after your code is compiled and before the application is packaged. During augmentation Quarkus:

  1. Indexes every class in your application and its dependencies with Jandex, a fast annotation and hierarchy index (it reads class files without loading them).
  2. Runs the build steps of all extensions. A build step may look for annotations (@Path, @Entity, @Inject), validate them and produce build items.
  3. Generates bytecode: injection wiring, proxies, JAX-RS invokers, Hibernate metadata, and a "recorded" startup sequence.
  4. Records a list of actions the application must take at startup (create this bean, open that port) as ordinary bytecode.

At runtime the application loads the generated classes and replays the recorded actions. No scanning, no annotation parsing, no proxy generation.

flowchart LR
    A["Your classes + libraries"] --> B["Jandex index"]
    B --> C["Extension build steps"]
    C --> D["Generated bytecode + recorded startup"]
    D --> E["Packaged application"]
    E --> F["Fast startup"]

Augmentation happens once, at build time. Every start only replays the result.

The closed-world assumption

Because the build sees your whole application, it can assume a closed world: the set of classes does not change after the build. That allows optimisations a runtime framework cannot make:

  • Unused bean removal. A CDI bean that is never injected, never looked up and has no observers or interceptors is removed from the application. This saves memory.
  • Dead code elimination through GraalVM in native mode, which keeps only reachable methods.
  • No classpath scanning at startup, since the index already contains the answers.
  • Pre-computed proxies and metadata such as the Hibernate entity model.

The trade-off is that things you would have done dynamically need a little declaration. Adding a class at runtime and expecting the framework to discover it does not work, and reflection on arbitrary classes may need @RegisterForReflection.

Build-time and runtime configuration

Because the build already decided which code to generate, some properties cannot change later. Compare:

Kind Example When it applies
Build-time fixed quarkus.hibernate-orm.database.generation's mapping choices, quarkus.datasource.db-kind At packaging. Changing later has no effect.
Runtime quarkus.http.port, quarkus.datasource.jdbc.url, quarkus.log.level Read at startup; override with environment variables

Environment variables make runtime values easy to change per deployment:

Terminal
QUARKUS_HTTP_PORT=9000 java -jar target/quarkus-app/quarkus-run.jar

quarkus.datasource.db-kind is build-time because it decides which driver and dialect code to generate, while the URL is runtime. When a property seems ignored in production, check first whether it is build-time and you changed it too late.

Indexing stand-in

The first stand-in shows the idea of an index. It scans a list of "class descriptions" once (the build) and builds an inverted index from annotation to class. Looking up everything annotated with @Path afterwards is a map lookup and loads nothing. In real Quarkus the Jandex index does this for the whole classpath.

Java Stand-in: an annotation index

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Dead bean removal

ArC, the Quarkus CDI container, removes beans that nothing uses. Here is a real example. Mailer is a bean, but if no one injects it, no one looks it up through Instance<Mailer> and it has no observer methods, it is removed at build time:

Java
@ApplicationScoped
public class Mailer {
    public void send(String to) { /* ... */ }
}

If you call it only through reflection or CDI.current().select(Mailer.class), ArC cannot see the use. Fix it with @Unremovable:

Java
import io.quarkus.arc.Unremovable;

@Unremovable
@ApplicationScoped
public class Mailer { /* ... */ }

You can also switch the optimisation off with quarkus.arc.remove-unused-beans=none, which is useful while diagnosing a "bean not found" puzzle, though you should normally fix the cause.

Dead code stand-in

The second stand-in implements reachability analysis, the idea behind both unused-bean removal and native image dead-code elimination. Starting from an entry point, we follow "calls" edges. Anything not reached is dropped.

Java Stand-in: keep only what is reachable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The weakness shows immediately: reachability follows only the calls it can see. A method invoked through a string name (reflection) looks unreachable, so you must tell the tool. That is exactly why Quarkus has @Unremovable for beans and @RegisterForReflection for classes.

What this means for your code

  • Prefer normal injection over CDI.current() and reflection so the build can see usage.
  • Register classes that you create or serialise through reflection (for example classes serialised with a plain ObjectMapper by name) with @RegisterForReflection. Types returned from REST methods are handled for you.
  • Do not rely on classpath scanning of resources at runtime; use extensions, @ConfigMapping and the standard APIs.
  • Keep application code in the module that has the Jandex index. A dependency jar without annotations in the index is invisible to CDI. Libraries can add META-INF/beans.xml or a jandex.idx, or you can list it with quarkus.index-dependency.<name>.group-id.

When an annotated class in a library is ignored, the cause is nearly always indexing. Add the dependency to the index with the quarkus.index-dependency properties or the Jandex Maven plugin.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is augmentation in Quarkus?

    Augmentation runs at build time, indexes classes, executes extension build steps and generates the code replayed at startup.
  2. 2. A bean is only ever used through CDI.current().select(...). What may happen in Quarkus?

    ArC removes beans that look unused. Dynamic lookup is invisible to it, so @Unremovable keeps the bean.
  3. 3. Which property is typically fixed at build time?

    The database kind decides which driver and dialect code is generated, so it is fixed at build time. The URL, port and log level are runtime properties.
  4. 4. What is Jandex used for?

    Jandex reads class files into an index of classes, annotations and hierarchies that build steps query.
  5. 5. What is the "closed-world assumption"?

    Since the whole application is visible during the build, Quarkus can precompute and prune. Dynamic loading needs extra declarations.

Summary

  • Augmentation indexes your code (Jandex), runs extension build steps and generates bytecode and recorded startup actions.
  • A closed-world model lets Quarkus remove unused beans and avoid startup scanning.
  • Some properties are build-time fixed; runtime ones can come from environment variables.
  • Use @Unremovable and @RegisterForReflection when something is used in a way the build cannot see.
  • If an annotated library class is ignored, check indexing.

Next: CDI Beans and Injection