spring-core

Active contributors: Juergen Hoeller, Sam Brannen, Sébastien Deleuze

Purpose

spring-core is the foundation of every other Spring module. It contains general-purpose utilities (collection helpers, classpath scanning, reflection helpers), the Spring type system (ResolvableType, MethodParameter), the Resource abstraction, the Environment abstraction, and the AOT (Ahead-Of-Time) infrastructure for native-image support. It also ships repackaged versions of ASM, CGLIB, Objenesis, and JavaPoet so that Spring users do not face third-party version conflicts.

Directory layout

spring-core/
├── spring-core.gradle                              # build (multi-release JAR config)
└── src/
    ├── main/
    │   ├── java/org/springframework/
    │   │   ├── aot/                                # ahead-of-time processing (hints, generation)
    │   │   ├── asm/                                # repackaged ASM
    │   │   ├── cglib/                              # repackaged CGLIB
    │   │   ├── core/                               # type system, environment, parameter discovery
    │   │   │   ├── annotation/
    │   │   │   ├── codec/
    │   │   │   ├── convert/                        # ConversionService
    │   │   │   ├── env/                            # Environment, PropertySource, Profiles
    │   │   │   ├── io/                             # Resource, ResourceLoader
    │   │   │   ├── log/
    │   │   │   ├── style/
    │   │   │   ├── task/
    │   │   │   └── type/                           # type-system helpers and metadata readers
    │   │   ├── javapoet/                           # repackaged JavaPoet (used by AOT)
    │   │   ├── lang/                               # @Nullable, @NonNull (legacy)
    │   │   ├── objenesis/                          # repackaged Objenesis
    │   │   └── util/                               # general utilities
    │   ├── java21/                                 # JDK-21-specific overrides (MRJAR)
    │   └── java24/                                 # JDK-24-specific overrides (MRJAR)
    ├── test/                                       # tests
    ├── testFixtures/                               # fixtures shared with downstream modules
    └── jmh/                                        # JMH benchmarks

Key abstractions

Type	File	Role
ResolvableType	spring-core/src/main/java/org/springframework/core/ResolvableType.java	Full generic type resolution across hierarchies
MethodParameter	spring-core/src/main/java/org/springframework/core/MethodParameter.java	Carries reflective metadata about a parameter or return value
ParameterNameDiscoverer	spring-core/src/main/java/org/springframework/core/ParameterNameDiscoverer.java	Discovers parameter names (debug info, -parameters)
Resource / ResourceLoader	spring-core/src/main/java/org/springframework/core/io/	Abstraction over file/classpath/URL/byte-array data sources
Environment / PropertySource	spring-core/src/main/java/org/springframework/core/env/	Property and profile resolution
ConversionService / Converter / Formatter	spring-core/src/main/java/org/springframework/core/convert/	Type conversion SPI used everywhere from data binding to SpEL
RuntimeHints / ReflectionHints / ResourceHints	spring-core/src/main/java/org/springframework/aot/hint/	AOT-time registration of reflection/resource/proxy/serialization
RuntimeHintsRegistrar	spring-core/src/main/java/org/springframework/aot/hint/RuntimeHintsRegistrar.java	SPI: contribute hints by implementing this interface
ReactiveAdapterRegistry	spring-core/src/main/java/org/springframework/core/ReactiveAdapterRegistry.java	Adapts between Reactor, RxJava, Mutiny, etc.
Ordered / @Order / OrderComparator	spring-core/src/main/java/org/springframework/core/	Ordering of beans, advisors, converters, anywhere ordering matters
ConfigurableObjectInputStream	spring-core/src/main/java/org/springframework/core/ConfigurableObjectInputStream.java	Classloader-aware Java deserialization

How it works

spring-core does not assemble higher-level constructs — it gives them parts. A few conceptual flows are worth tracing:

Resource resolution

ResourceLoader abstracts how Spring opens files. Almost everything that "loads a config" eventually goes through it.

graph LR
    Caller -->|"location string"| RL[ResourceLoader]
    RL -->|"classpath:foo.xml"| CR[ClassPathResource]
    RL -->|"file:/etc/foo.xml"| FR[FileSystemResource]
    RL -->|"http://..."| UR[UrlResource]
    RL -->|"jar:..."| JR[JarResource]
    CR --> Stream[InputStream]
    FR --> Stream
    UR --> Stream
    JR --> Stream

The two implementations users actually instantiate are DefaultResourceLoader and PathMatchingResourcePatternResolver (the latter understands wildcards: classpath*:META-INF/spring.factories).

Environment and PropertySource

The Environment abstraction layers configuration sources:

graph TD
    App -->|"getProperty('db.url')"| Env[Environment]
    Env --> SP[Stack of PropertySources]
    SP --> S1[System properties]
    SP --> S2[Environment variables]
    SP --> S3[application.properties]
    SP --> S4[Custom sources]

Each PropertySource is consulted in priority order. PropertySourcesPlaceholderConfigurer (in spring-context) uses this to resolve ${property} placeholders.

AOT hints

The AOT system collects hints during build-time processing so a GraalVM native image keeps the right reflection/resource/proxy data:

graph LR
    BuildTime[AOT build] -->|"discovers"| Registrars[RuntimeHintsRegistrar instances]
    Registrars -->|"register"| RH[RuntimeHints]
    RH -->|"writes"| ConfigFiles["reflect-config.json, resource-config.json, …"]
    ConfigFiles -->|"read by"| GraalVM[GraalVM native-image]

Every module that does any reflection is expected to ship a *RuntimeHints registrar pointing at the types it touches.

Repackaged dependencies

spring-core repackages four libraries via the Gradle shadow plugin:

• ASM → org.springframework.asm.*
• CGLIB → org.springframework.cglib.*
• Objenesis → org.springframework.objenesis.*
• JavaPoet → org.springframework.javapoet.* (used only by AOT generation)

Configuration is in spring-core/spring-core.gradle. End users don't see these libraries on the classpath under their original names.

Integration points

spring-core exports symbols used by every other module:

• spring-beans uses ResolvableType for autowiring resolution.
• spring-context uses Environment and Resource for property and resource loading.
• spring-aop uses MethodParameter for advice signature matching.
• spring-web uses ConversionService for query/path-param binding.
• All AOT-aware modules ship RuntimeHintsRegistrar implementations.

It depends on only:

• org.apache.commons:commons-logging (the JCL bridge)
• Optional: Kotlin reflection, JSpecify annotations, GraalVM SDK

Entry points for modification

• Adding a new utility — Pick the right sub-package (util, core/annotation, core/io, …). Most utilities are small and self-contained.
• AOT hint registration — Implement RuntimeHintsRegistrar and reference it from META-INF/spring/aot.factories.
• Type-system support for new generics features — ResolvableType is the touch point. Tread carefully; this class is one of the most depended-on in the framework.
• Conversion — Add a Converter<S, T> or GenericConverter and register it via DefaultConversionService.addConverter() or as a bean in higher modules.

Notable internals

• SpringFactoriesLoader (spring-core/src/main/java/org/springframework/core/io/support/SpringFactoriesLoader.java) — Loads SPI implementations from META-INF/spring.factories and META-INF/spring/<key>.imports. Used by Spring Boot auto-configuration but defined here.
• SerializableTypeWrapper — Allows generic type information to survive deserialization, used in distributed and remote scenarios.
• NativeDetector — Detects whether the JVM is currently running as a GraalVM native image; many code paths short-circuit when running natively.

See also: features/dependency-injection, overview/architecture, and the reference/configuration page for what Environment exposes by default.