Introduction to Solon Framework

Relevant source files

• README.md
• README_CN.md
• README_EN.md
• README_JP.md
• README_RU.md
• UPDATE_LOG.md
• V3.0.md
• __release/pom.xml
• __release/solon-base-bundle1/pom.xml
• __release/solon-base-bundle2/NOTICE
• __release/solon-base-bundle2/pom.xml
• __release/solon-base-bundle3/NOTICE
• __release/solon-base-bundle3/pom.xml
• __release/solon-base-bundle4/NOTICE
• __release/solon-base-bundle4/pom.xml
• __release/solon-base-bundle5/NOTICE
• __release/solon-base-bundle5/pom.xml
• __release/solon-base-bundle6/NOTICE
• __release/solon-base-bundle6/pom.xml
• __release/solon-shortcuts-bundle/pom.xml
• __test/pom.xml
• __test/src/main/java/webapp/demo6_aop/TestController.java
• __test/src/main/java/webapp/models/CfgItem.java
• __test/src/main/resources/IfAbsent.yml
• __test/src/main/resources/app.yml
• __test/src/test/java/features/PropRefTest.java
• __test/src/test/java/features/PropTest.java
• pom.xml
• solon-parent/pom.xml
• solon-projects/solon-scheduling/solon-scheduling-quartz/src/test/java/org/noear/solon/scheduling/quartz/test/features/CronTest.java
• solon-projects/solon-scheduling/solon-scheduling-simple/pom.xml
• solon-projects/solon-scheduling/solon-scheduling-simple/src/test/java/org/noear/solon/scheduling/simple/test/features/CronTest.java
• solon/pom.xml
• solon/src/main/java/org/noear/solon/Solon.java
• solon/src/main/java/org/noear/solon/SolonApp.java
• solon/src/main/java/org/noear/solon/SolonProps.java
• solon/src/main/java/org/noear/solon/Utils.java
• solon/src/main/java/org/noear/solon/core/Props.java
• solon/src/main/java/org/noear/solon/core/handle/Context.java
• solon/src/main/java/org/noear/solon/core/util/PropUtil.java
• solon/src/main/java/org/noear/solon/core/util/PropsExpressionContext.java
• solon/src/test/java/benchmark/PropTest.java
• solon/src/test/java/benchmark/PropTmplTest.java
• solon_cloud_schema.png

Purpose and Scope

This document provides a comprehensive introduction to the Solon Framework, a Java enterprise application development framework designed for full-scenario deployment. This page covers:

• Core philosophy and design principles (restraint, efficiency, openness)
• High-level architecture including the application lifecycle, IoC container, and request processing pipeline
• Performance characteristics and technical advantages
• Module organization and the bundle system
• Quick start guidance for creating your first Solon application

For detailed information on specific subsystems:

• Application lifecycle and initialization: see Application Lifecycle
• Dependency injection and IoC: see Bean Container and Dependency Injection
• Web request handling: see Web Request Handling
• Plugin development: see Plugin and Extension System
• Native image compilation: see Native Image and GraalVM Support

---

Philosophy and Design Principles

Solon is built on three core principles, as stated in README.md9:

Principle	Description
Restrained	Minimalist approach to framework design, avoiding unnecessary complexity
Efficient	Optimized for performance with lower resource consumption
Open	Pluggable architecture with flexible interface specifications

Non-Java EE Foundation

Unlike traditional Java enterprise frameworks, Solon is built from scratch without dependency on Java EE specifications. This architectural decision enables:

• Support for Java 8 through Java 25 (README.md23-36)
• Native runtime via GraalVM compilation
• Significantly reduced artifact sizes
• Faster startup times without servlet container overhead

Sources: README.md1-120 README_EN.md1-120

---

Performance Characteristics

Solon demonstrates exceptional performance metrics compared to traditional frameworks:

Metric	Improvement	Details
Concurrency	700% higher	Based on TechEmpower benchmarks
Memory Usage	50% savings	Optimized bean management and request processing
Startup Time	10x faster	Minimal initialization overhead, efficient classpath scanning
Artifact Size	90% smaller	Modular design allows including only required components

These characteristics are achieved through:

1. Efficient IoC container: Lazy initialization and optimized dependency resolution
2. Minimal reflection overhead: Pre-computed metadata via AOT processing
3. Direct servlet integration: No intermediary servlet container layers
4. Pluggable modules: Include only what you need

Sources: README.md55-70 solon-parent/pom.xml1-753

---

High-Level Architecture

Framework Core Components

The following diagram illustrates the main architectural layers and their relationships:

Key Classes and Their Roles:

• Solon: Static entry point providing global access to the application instance (solon/Solon.java48-404)
• SolonApp: Main application instance managing lifecycle, configuration, and request routing (solon/SolonApp.java58-780)
• SolonProps: Configuration loader supporting multiple sources with precedence rules (solon/SolonProps.java47-751)
• AppContext: IoC container for bean registration and dependency injection (solon/core/AppContext.java)
• Context: HTTP request/response abstraction for web applications (solon/core/handle/Context.java42-1247)

Sources: solon/Solon.java1-404 solon/SolonApp.java1-780 solon/SolonProps.java1-751 solon/core/handle/Context.java1-100

---

Application Lifecycle Flow

Lifecycle Phases:

1. Initialization: Load configuration from app.properties/app.yml and environment-specific files (solon/SolonProps.java100-125)
2. Plugin Discovery: SPI-based scanning of META-INF/services (solon/SolonProps.java376-387)
3. Plugin Initialization: Plugins sorted by priority and initialized (solon/SolonApp.java355-418)
4. Bean Scanning: Component scanning from source package (solon/SolonApp.java386-396)
5. Context Startup: Bean wiring and lifecycle callbacks (solon/SolonApp.java411-418)
6. Server Binding: HTTP server starts listening on configured port

Sources: solon/Solon.java163-271 solon/SolonApp.java244-268 solon/SolonApp.java355-418 solon/SolonProps.java72-220

---

Module Organization

Solon uses a tiered bundle system to organize over 100 modules:

Bundle Descriptions

Bundle	Purpose	Key Modules
Bundle 1	Core functionality, configuration, security	solon-aot, solon-handle, solon-proxy, solon-i18n, solon-mvc, solon-security-*
Bundle 2	Data access and caching	solon-data, solon-cache, solon-data-dynamicds, cache adapters (Caffeine, Jedis, Redisson)
Bundle 3	Web utilities and protocols	solon-web-cors, solon-web-staticfiles, solon-web-sse, solon-server-websocket
Bundle 4	View engines, logging, scheduling	solon-view (FreeMarker, Thymeleaf), solon-logging-*, solon-scheduling-*, solon-faas-luffy
Bundle 5	Serialization and testing	JSON (Snack4, FastJson, Jackson), binary formats, solon-test
Bundle 6	HTTP server implementations	solon-server-jdkhttp, solon-server-jetty, solon-server-tomcat, solon-server-undertow, etc.

Shortcuts for Common Use Cases

solon-lib: General-purpose applications

• Includes Bundle 1 (core + config + security)
• Includes Bundle 2 (data + cache)
• Ideal for backend services, command-line tools

solon-web: Web applications

• Includes Bundle 3 (web utilities + network)
• Includes Bundle 4 (views + logging + scheduling)
• Ideal for REST APIs, web services, full-stack applications

Sources: __release/solon-base-bundle1/pom.xml1-49 __release/solon-base-bundle2/pom.xml1-35 __release/solon-base-bundle3/pom.xml1-31 __release/solon-base-bundle4/pom.xml1-38 __release/solon-base-bundle5/pom.xml1-33 __release/solon-base-bundle6/pom.xml1-35 __release/solon-shortcuts-bundle/pom.xml1-30

---

Quick Start Example

Hello World Application

Create a minimal Solon application in three steps:

Step 1: Add dependency (pom.xml):

Step 2: Create main class:

Step 3: Create controller:

The application will:

1. Start an embedded HTTP server on port 8080 (configurable via server.port)
2. Scan the HelloApp package for @Controller and @Component classes
3. Register routes based on @Mapping annotations
4. Handle requests at http://localhost:8080/hello?name=World

Configuration Example

Create app.yml in src/main/resources:

Access configuration in code:

Sources: solon/SolonApp.java46-53 solon/Solon.java36-47 solon/SolonProps.java100-125 README.md1-120

---

Configuration System Overview

Solon's configuration system supports hierarchical property sources with clear precedence:

Configuration Precedence (Highest to Lowest)

Configuration Loading Process

1. Base Configuration: Load app.properties and app.yml (solon/SolonProps.java103-104)
2. Environment Profiles: Load app-{env}.properties and app-{env}.yml based on env parameter (solon/SolonProps.java110-119)
3. System Properties: Merge system properties with higher precedence (solon/SolonProps.java88-97)
4. Additional Files: Load files specified in solon.config.load (solon/SolonProps.java134-161)
5. External Files: Load files from solon.config.add parameter (solon/SolonProps.java164)

Expression Language

Configuration values support expression resolution with default values:

Syntax	Description	Example
${key}	Property reference	${database.url}
${key:default}	With default value	${server.port:8080}
${.key}	Relative reference	${.username} (within same section)

Sources: solon/SolonProps.java72-220 solon/core/Props.java40-900 solon/core/util/PropUtil.java1-300

---

Request Processing Flow

The following diagram shows how HTTP requests flow through Solon's processing pipeline:

Key Components:

• Server Adapter: Abstracts underlying HTTP server (Jetty, Tomcat, Undertow, etc.)
• RouterHandler: Matches request paths to handlers with support for wildcards and path variables
• ChainManager: Manages filter chain with configurable priority
• Filter: Pre/post-processing interceptors (authentication, CORS, logging)
• Action: Represents a controller method with parameter binding and AOP support
• RenderManager: Content negotiation and response serialization

Sources: solon/SolonApp.java617-664 solon/core/handle/Context.java42-100

---

Plugin System

Solon's SPI-based plugin architecture enables modular extensibility:

Plugin Discovery

Plugins are discovered via Java's ServiceLoader mechanism:

1. Define implementation in META-INF/services/org.noear.solon.core.Plugin
2. Framework scans classpath during initialization (solon/SolonProps.java376-387)
3. Plugins sorted by priority (higher values execute first) (solon/SolonProps.java386)

Plugin Lifecycle

Lifecycle Methods:

• init(AppContext ctx): Called during plugin discovery phase
• start(AppContext ctx): Called after configuration loading, before bean scanning
• preStop(): Called when shutdown signal received, before stopping
• stop(): Called during application shutdown

Plugin Exclusion

Exclude plugins without removing dependencies:

Or programmatically:

Sources: solon/SolonProps.java376-396 solon/SolonApp.java355-418 solon/SolonApp.java592-603

---

Key Concepts Summary

Core Abstractions

Abstraction	Purpose	Key Interface/Class
SolonApp	Application instance and lifecycle manager	org.noear.solon.SolonApp
AppContext	IoC container for dependency injection	org.noear.solon.core.AppContext
Context	HTTP request/response abstraction	org.noear.solon.core.handle.Context
Plugin	Extension point for modular features	org.noear.solon.core.Plugin
BeanWrap	Bean metadata wrapper	org.noear.solon.core.BeanWrap
Router	Request routing and matching	org.noear.solon.core.route.Router
Action	Controller method handler	org.noear.solon.core.handle.Action

Typical Development Workflow

1. Add Dependencies: Choose solon-lib or solon-web shortcut, or specific bundles
2. Create Entry Point: Annotate main class with @SolonMain, call Solon.start()
3. Define Components: Use @Controller, @Component, @Configuration annotations
4. Configure Application: Create app.yml with environment-specific profiles
5. Implement Business Logic: Controllers, services, repositories with dependency injection
6. Deploy: Package as standalone JAR with embedded server, or as native image

Version Compatibility

Current version: 3.9.3 (solon-parent/pom.xml10)

Supported Java versions:

• Java 8 (minimum)
• Java 11, 17, 21 (LTS versions)
• Java 25 (latest, via solon-java25 adapter)

Next Steps

For detailed information on specific subsystems:

• Bean lifecycle and dependency injection: Bean Container and Dependency Injection
• Web request handling and routing: Web Request Handling
• Configuration management: Configuration System
• Plugin development: Plugin and Extension System
• Native compilation: Native Image and GraalVM Support
• Module ecosystem: Module Ecosystem

Sources: solon/Solon.java48-404 solon/SolonApp.java58-780 solon-parent/pom.xml1-30 README.md1-120 UPDATE_LOG.md1-100