How frameworks use annotations and reflection

For this lesson, we'll build the machinery ourselves: scan a package, wire objects with a tiny DI container, then add transactions with a proxy. Once you've written those 100 lines, the famous production surprises (self-invocation, final methods, JPA's no-arg constructor) stop being trivia and become obvious. This is the lesson interviewers are really reaching for when they ask "how does @Transactional work?".

01Picture it first: a hotel concierge with your booking file

Think of a framework as a hotel concierge holding your booking file. The annotations are the notes in the file ("needs a car at 9", "wake-up call", "vegetarian"). The concierge never changes who you are; they read the notes and arrange things around you. And when the restaurant calls your room, the call goes through the front desk, which is the proxy, so the desk can apply the "vegetarian" note before connecting.

The machinery always runs in the same order, which this diagram walks through.

Fig. 1

Six numbered steps: scan the classpath, filter by annotation, build a dependency graph, call constructors reflectively, wrap beans in proxies, and hand out ready objects

Keep this picture. Every question in this lesson is about one of those six steps.

02Under the hood: build a mini DI container

Step 1: classpath scanning

There's no JDK API that says "give me every class in package com.shop". Frameworks ask the class loader for the package as a resource and walk what comes back: directories in development, JAR entries in production.

static List<Class<?>> scan(String basePackage) throws IOException, URISyntaxException {
    String path = basePackage.replace('.', '/');
    ClassLoader loader = Thread.currentThread().getContextClassLoader();
    List<Class<?>> found = new ArrayList<>();
    for (URL url : Collections.list(loader.getResources(path))) {
        Path root = Paths.get(url.toURI());                  // directories only; JARs need a JarFile walk
        try (Stream<Path> files = Files.walk(root)) {
            for (Path file : files.filter(f -> f.toString().endsWith(".class")).toList()) {
                String name = basePackage + "." + root.relativize(file).toString()
                        .replace(FileSystems.getDefault().getSeparator(), ".").replace(".class", "");
                try {
                    found.add(Class.forName(name, false, loader));   // load, don't initialise
                } catch (ClassNotFoundException e) {
                    throw new IllegalStateException(e);
                }
            }
        }
    }
    return found;
}

Notice:

• false means load without initialising, so scanning a class never runs its static blocks.
• Real frameworks go further and don't load classes at all during scanning. They read the class file bytes with a bytecode reader (ASM, or the JDK's java.lang.classfile API finalised in Java 24) and only load the classes that carry the right annotation. Loading every class in a large application would cost seconds and Metaspace.
• Build-time indexes skip the scan entirely: Quarkus builds a Jandex index of annotations at build time, and Micronaut generates the bean list during compilation.

Step 2: the container

Now the container: find @Component classes, map interfaces to implementations, and build each one by resolving its constructor parameters recursively.

@Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE)
@interface Component { }

final class MiniContainer {
    private final Map<Class<?>, Class<?>> implFor = new HashMap<>();
    private final Map<Class<?>, Object> singletons = new HashMap<>();
    private final Set<Class<?>> inCreation = new HashSet<>();

    MiniContainer(List<Class<?>> candidates) {
        for (Class<?> c : candidates) {
            if (!c.isAnnotationPresent(Component.class)) continue;
            implFor.put(c, c);
            for (Class<?> iface : c.getInterfaces()) implFor.put(iface, c);
        }
    }

    <T> T get(Class<T> type) {
        Class<?> impl = implFor.get(type);
        if (impl == null) throw new IllegalStateException("No @Component for " + type.getName());
        Object bean = singletons.get(impl);
        if (bean == null) {
            bean = create(impl);
            singletons.put(impl, bean);
        }
        return type.cast(bean);
    }

    private Object create(Class<?> impl) {
        if (!inCreation.add(impl)) throw new IllegalStateException("Cycle at " + impl.getSimpleName());
        try {
            Constructor<?>[] ctors = impl.getDeclaredConstructors();
            if (ctors.length != 1) throw new IllegalStateException(impl + " needs exactly one constructor");
            Constructor<?> ctor = ctors[0];
            Object[] deps = Arrays.stream(ctor.getParameterTypes()).map(this::get).toArray();
            ctor.setAccessible(true);
            return ctor.newInstance(deps);
        } catch (ReflectiveOperationException e) {
            throw new IllegalStateException("Cannot create " + impl.getName(), e);
        } finally {
            inCreation.remove(impl);
        }
    }
}