DEV Community: Solon Framework

No JSON Required: Configuring SolonCode's Model from the Web Settings Panel

Solon Framework — Tue, 04 Aug 2026 00:42:39 +0000

Most coding agents make you earn your first conversation. You install the binary, then you go hunting for a config file, then you find out the config file wants a provider name you have to spell exactly right, a base URL that may or may not need a trailing path segment, and a key you paste into a text editor and hope you didn't leave a trailing space on.

SolonCode skips that. You start it in web mode, the browser opens, and you add your model in a settings panel — paste the endpoint, paste the key, hit test, save. The chat area picks up the new model immediately. There is a settings.json underneath, and you can read it if you're curious, but on the way to your first task you never need to open it.

Here's the whole path, with the screens you'll actually see.

Before you start

Two things:

Java 8 or newer. SolonCode runs on Java 8 through Java 26, so whatever JDK your project already builds against is almost certainly fine.
One reachable model endpoint. OpenAI, Anthropic, Gemini, Ollama, or anything speaking a compatible format.

Optional, and only if you want the matching features later: Node.js (for some MCP servers, Skills, and browser-type tools), Git (so the web UI can show you diffs and staging), and a language server (for LSP-backed code understanding). None of these block your first run.

Install:

# macOS / Linux / Harmony PC
curl -fsSL https://solon.noear.org/soloncode/setup.sh | bash

# Windows PowerShell
irm https://solon.noear.org/soloncode/setup.ps1 | iex

Re-running the same command later is how you update. The installer refreshes program files and does its best to preserve what you've already configured — settings.json, AGENTS.md, and friends stay put.

Confirm it landed:

soloncode version
# SolonCode v2026.8.4

Start web mode

Go to the project you actually want to work on. The directory you launch from becomes the workspace, and that matters for scoping later, so cd first rather than launching from your home directory.

cd your-project
soloncode web 0

Three ways to pick a port:

Command	Port
`soloncode web`	Default, 4808
`soloncode web 0`	Random free port
`soloncode web 1212`	That specific port

web 0 is the one to reach for when you keep several projects open, because you're not going to collide with an instance you forgot about. The browser tab is labeled with the workspace name and path, which is how you tell four open tabs apart.

The terminal prints the address it picked:

SolonCode v2026.8.4 PID-4131 Model:your-model
/path/to/your-project
Web interface: http://localhost:1212/

The browser opens on its own. If it doesn't — remote box, headless environment, an OS that decided not to cooperate — copy the address from that output.

What you land on is the welcome screen: an input box in the middle, the workspace file tree on the right, conversation controls on the left, and the current model shown under the input.

First stop: set your language

Click Settings in the left rail, and the first card under General is Display Language. It ships as Follow system default, which means the UI speaks whatever your OS does.

Twenty-three locales in that list. Pick yours and the interface re-renders on the spot — no restart, no reload. Menus, section names, buttons, placeholder text, all of it.

Two things worth knowing that the dropdown doesn't tell you:

The setting is per-session. Selecting a language applies it immediately, but reloading the page drops you back to Follow system default. If your OS locale already matches what you want, you'll never notice. If it doesn't, expect to re-pick after a reload.

It changes the UI, not the agent. Display Language controls chrome. The language your model answers in comes from the model, and it will happily reply in one language to a prompt written in another. If you want English answers, ask for English answers:

Reply in English. <your actual request>

Or put it in AGENTS.md once and stop repeating yourself.

The rest of General, for when you come back to it: Conversation Strategy, Sandbox Mode, Memory, Retry on Failure, and Appearance.

The settings panel

Nine sections down the side:

General · Agents · Mounts · Skills · Providers · Models · MCP Servers · OpenAPI Servers · LSP Servers

You want Models.

One small thing that will bite you if nobody says it: Esc closes the whole settings panel, not just the form you have open. Use the panel's own Back button when you mean to back out of a form.

Add your first model

Models → + Add Model. This opens as a full page inside the panel, not a popup dialog:

Name — how it shows up in the model picker. Free text, so name it something you'll recognize at a glance.
Scope — two buttons, User (Global) and Workspace (Local). More on this below.
URL mode — a dropdown, default Full URL (auto-detect). The alternatives are BaseUrl modes for OpenAI Chat Completions, OpenAI Responses, and Anthropic, plus dedicated Gemini and Ollama entries. Auto-detect covers the common cases; reach for a specific mode when your endpoint isn't a full completions URL.
API URL — placeholder shows the shape it wants, e.g. https://api.deepseek.com/v1/chat/completions.
API Key — sk-..., with a show/hide toggle.
Model — the provider's model identifier.
Context length — a dropdown of common sizes.
Timeout — 120s by default.
Extra options — a JSON field for things like temperature, top_p, or reasoning flags, with a Format JSON button. Empty is a perfectly good answer here.
Set as default model — a checkbox.

Filled in against a local Ollama instance:

Then the part people skip: press Test Connection before you press Save.

A model that's added but unreachable looks identical to a model that works, right up until your first task dies mid-run and you're reading logs to figure out whether the problem was your key, your URL, or your proxy. The test button is right next to Save. Ten seconds there removes a whole category of confusion.

After you save, the model list in the chat area refreshes to match — no restart. If you've accumulated a long list, the picker supports search filtering, so you type a fragment instead of scrolling.

Global or workspace

The scope buttons in the form decide which file your model lands in:

Scope	File	Use it for
User (Global)	`~/.soloncode/settings.json`	Your everyday model, shared across every project
Workspace (Local)	`.soloncode/settings.json` in the project	Models specific to this project

SolonCode reads the user-level file first, then the workspace file, and workspace config overrides or supplements what it found.

Workspace scope has a second-order effect worth thinking about for a second. That file sits inside the project directory, which means it can be committed. Sharing endpoint and model choices with your team that way is genuinely useful. Sharing an API key that way is not. Decide which of those you're doing before you git add.

Providers, when one key serves many models

If you're adding a second and third model against the same endpoint, the Providers section is the better place to work. It manages vendor config — API address, keys — as one entry, with add, modify, and enable/disable per provider.

The reason to care is maintenance rather than setup. When a key rotates, you want one place to change it, not four model entries that each remember their own copy. Same story when you're moving an endpoint. Set the provider up once; point models at it.

First conversation

Don't lead with a code change. Lead with a question, because the answer tells you whether the model is actually seeing your repo:

Reply in English. What kind of project is this directory?
Check the build file and source layout before answering.

Watch the tool trace above the answer: ls, a glob for pom.xml, a read of that file, then a recursive listing of src. It looked before it spoke. And what it reported back was that the skeleton exists — parent POM, one web dependency, standard Maven layout — but there's no source, no app.yml, no tests, so nothing is actually written yet.

That's the signal you're checking for. An agent that had described a working application there would be an agent you couldn't trust on a real repo. Note the footer too: token count, elapsed time, and running context usage, so you can see what a turn cost you.

Once you're connected, give it a foundation to work from:

Generate .soloncode/CODE.md for this project, including build commands,
test commands, and notes on what to be careful about when modifying code.

If that file already exists, SolonCode prefers what's in it. That's the point — it's the engineering contract for the repo, and having it written down means you stop re-explaining your build every session.

Now a small task, scoped tightly:

Check whether the install instructions in README are out of date.
Docs only, no code changes. Tell me what you changed when you're done.

Small and reviewable on the first pass. You're not testing whether the agent can do impressive things yet; you're testing whether you can read and trust its output.

For anything bigger, four things belong in the prompt:

Goal: fix the NPE in the user login endpoint.
Scope: only the user module.
Constraint: do not change the response structure.
Verification: run the related unit tests; if none exist, say so.

Goal, scope, constraint, verification. The last one matters more than it looks — asking for verification is what turns "I made a change" into "I made a change and here's the evidence."

What else the panel covers

Model config is one section out of nine. The rest are there when a specific need shows up: permissions and tool allow/deny lists, mount pools that expose external directories as Skills or Agents resources, a Skills marketplace with install support, MCP servers over stdio/SSE/streamable with connection checks and per-tool disabling, OpenAPI servers imported from a JSON/YAML spec, and LSP servers for code intelligence.

None of that is required today, and the pattern is the same each time: open the section, fill in the entry, test, save.

Saving generally writes through to the running engine, so most changes don't need a restart. When you're running several instances against the same config, there's a Reload config from disk button at the top of the panel to bring them in sync.

Two things to set before you expose it

Web auth. General settings has username and password fields for a login page, and they're empty by default — which is fine for localhost, and not fine the moment you bind to an address other machines can reach. If you're running SolonCode on a dev box or a shared server, turn this on before anything else. An unauthenticated agent UI is a remote shell with a nicer font.

Keys out of Git. Global config lives in your home directory, nowhere near your repo. Workspace config lives in .soloncode/settings.json, inside the project. Check what your .gitignore does with it. The scan-for-leaked-keys conversation is much less pleasant than the two minutes this takes.

Things you'll appreciate later

Web-mode features that don't matter on day one and become daily habits by week two:

Mermaid rendering — ask for an architecture diagram and read it as a diagram
Memory management — inspect, edit, and delete long-term memory from the UI, with scope switching
File preview — images, video, and Markdown, including fullscreen
Conversation management — pin, fork (copy), and delete threads
Voice input — hold to talk, release to send
Skins — default, eyecare, contrast, plus custom skins you upload as a zip

And the keyboard, since you'll live here:

Key	Action
`Ctrl + Enter`	Send
`↑` / `↓`	Cycle input history
`/` then Tab	Command completion
`@` then Tab	Subagent completion

When you don't want a UI at all

For scripts, CI, or a one-shot job, skip the interactive console entirely:

soloncode run "Summarize the current project structure"

Same engine, same config, no browser. The settings you just made in the web panel apply here too — which is the actual reason the panel is worth using first. You configure once, visually, with a connection test to confirm it, and every other entry point inherits it.

Sources

Quick start, install to first conversation — https://solon.noear.org/article/1467
settings.json and the Web settings page — https://solon.noear.org/article/1465
Web interactive mode — https://solon.noear.org/article/1442
SolonCode CLI index — https://solon.noear.org/article/soloncode
Screens captured live on SolonCode v2026.8.4, 2026-08-04, UI set to English

SolonCode in 15 Minutes: Install, Configure a Model, and Land Your First Reviewable Diff

Solon Framework — Mon, 03 Aug 2026 16:02:56 +0000

If your experience with coding agents is "it installed and it chats," you haven't had a first success yet — not the kind you can screenshot and show your team. Most getting-started posts stop at "I talked to it once," which doesn't tell you whether the tool can actually touch a real repository. This guide fixes that with a different yardstick.

SolonCode is an open-source coding agent written in Java, built on the Solon AI framework, and designed to run on Java 8 through Java 26. One honest caveat up front: its prompt system is built around Chinese-first interaction (the official docs state it's not recommended if you can't work with Chinese prompts) — which makes it an interesting pick for Chinese-speaking teams and for developers who want a model-agnostic agent they can run on their own gateway. Everything below is verified against the official docs as of SolonCode v2026.8.3.

What "first success" actually means here

Most short tutorials leave you with three failure modes:

The model won't connect, and you can't tell whether that counts as a failure or a misconfiguration.
You chatted, but the agent never modified a real file, so you still don't trust it.
Something breaks and you don't know whether to check the API key, the proxy, or the workspace path.

So this guide sets three concrete pass criteria — L1, L2, L3 — and gives you a fixed path: install → configure a model in the Web UI → land a small reviewable change. The goal isn't to learn all of SolonCode in 15 minutes; it's to earn one screenshot-worthy first success that you can explain to a colleague.

Prerequisites (2-minute self-check)

Item	Requirement	How to verify
JDK	Java 8 or higher (official support: Java 8 ~ 26)	`java -version` prints a version
OS	macOS / Linux / Windows (Harmony PC also supported)	you can run a shell / PowerShell
Model API	any LLM endpoint in OpenAI / Anthropic / Gemini / Ollama-compatible form	you have `apiUrl`, `apiKey` (if needed), and a model name

SolonCode does not bundle or bind to any vendor — you bring your own model (BYOK) or point it at an internal gateway. Without a working model configuration, the process starts but that's not a first success.

Nice-to-haves (not blockers): Git (helps you view diffs in the Web UI), a small real project directory (the launch directory becomes the workspace), and stable network / correct proxy settings.

Install: one command, then verify the version

macOS / Linux / Harmony PC:

curl -fsSL https://solon.noear.org/soloncode/setup.sh | bash

Windows (PowerShell):

irm https://solon.noear.org/soloncode/setup.ps1 | iex

Re-running the same install command updates the program while keeping your config and definition files. Program and user-level config default to ~/.soloncode/ (Windows: .soloncode under your home directory).

Minimum success check:

soloncode version

If it prints a version string, you're good to continue. If you get command not found: re-run the installer, check that soloncode is on your PATH, and open a new terminal window (PATH changes often require a fresh shell).

For offline / intranet installs, the official path is: download soloncode-cli-bin-*.tar.gz from Gitee Releases on a networked machine, copy it over, extract, and run install.sh / install.ps1. For your first success, do it online first.

Configure your first model in the Web UI

The officially recommended path for new users is the Web settings page — no need to hand-edit config files on day one.

soloncode web 0

The web command behavior: soloncode web uses default port 4808; soloncode web 0 picks an available port automatically (handy when 4808 is taken); soloncode web 1212 binds a specific port. The terminal prints something like Web interface: http://localhost:xxxxx/.

Then:

Open Settings → LLM (or equivalent) in the Web UI.
Add a model with at least: API URL (apiUrl), API key (if the provider needs one), and model name (exactly as shown in your provider console).
Use the "Test connection" button — the official docs emphasize it works.
Make sure the model is enabled and appears in the conversation's model list.

Config lands in settings.json: user-level at ~/.soloncode/settings.json (shared across projects), workspace-level at .soloncode/settings.json (project-specific). Workspace settings are read after user-level and can override or extend them. Security note: keys are secrets — never commit settings.json to Git; use a secret manager or per-developer local config for team setups.

Model-configuration success checklist:

[ ] Test connection passes
[ ] A "hello" message gets a normal model reply (not timeout / 401 / empty)
[ ] The current model name shows near the UI title (e.g. Model:deepseek-v4-flash — whatever you configured)

Only now are you "installed and talking." That's not yet a coding success.

Enter your project (workspace = launch directory)

The official docs recommend starting inside the project root; the launch directory becomes the current workspace.

cd /path/to/your-project
soloncode web 0
# or
soloncode cli

No project yet? You can explore conversation and file generation in any empty directory, but L2/L3 strongly benefit from a real repository — otherwise your "demo" has no persuasive power. When the CLI starts, the tips line looks like:

Tips: (esc) interrupt | /(tab) command | $(tab) skill | @(tab) agent

esc interrupts; commands / skills / subagents have tab completion. Natural language is enough for your first success.

The three-level task: L1 → L2 → L3

Suggested time budget (roughly 15 minutes total, model speed dependent): L1 ~3 min, L2 5–7 min, L3 5–7 min. If the model is slow or the repo is large, do L2 thoroughly rather than skipping review and rushing L3.

L1 — greeting and project scan

Send (in Chinese — this is the product's first-class interaction language):

请先阅读当前项目结构，告诉我：
1）这是什么技术栈；
2）构建命令和测试命令分别可能是什么；
3）如果存在 .soloncode/CODE.md，请优先参考它。
不要修改任何文件。

If the project has no CODE.md yet, the official quick start suggests continuing with:

请根据当前项目生成 .soloncode/CODE.md，包含构建命令、测试命令和代码修改注意事项。

L1 pass criteria (all must hold):

[ ] The tech-stack description roughly matches the repo (honest "needs further confirmation" is allowed)
[ ] Build/test entry points are stated or inferred (or honestly reported as not found)
[ ] When you asked for no file changes, git status shows no unexpected dirty files

Common L1 failures: not starting in the project root; model misconfigured; empty repo or unreadable permissions.

L2 — a small change + explain the diff (first "demoable" step)

Task A (docs, lowest risk):

请帮我检查 README 中是否有过时的安装说明，只修改文档，不改业务代码。
完成后：
1）列出改了哪些文件；
2）用简短条目说明每处为什么改；
3）不要提交 Git，交给我人工确认。

Task B (code, still small):

请新增一个简单的健康检查接口（或补全已有 health 相关说明），范围尽量小。
限制：
- 不要做大范围重构；
- 不要改无关模块；
- 改完说明如何本地验证；
- 不要 git commit。

L2 pass criteria:

[ ] Pointable file changes exist (visible in Web Git Diff or git diff)
[ ] The agent explains in natural language what changed and why
[ ] You scanned the diff yourself — no keys, no huge unrelated reformatting, nothing deleted by accident
[ ] You can describe this change to a colleague in one sentence (that's "demoable")

Human review checklist (mandatory, 30s–2min): did the change exceed your allowed scope? Any API keys, intranet addresses, or passwords? Any lockfiles or generated artifacts modified? Can you actually run the verification steps yourself?

This is where SolonCode's value starts showing: it advances the implementation; you guard the boundary and the merge decision.

L3 — a constrained small feature (must be reviewable)

Only after L2 passes. The prompt template includes the four elements the official docs emphasize: goal, scope, constraints, verification.

目标：{one sentence describing the deliverable behavior, e.g. 为用户模块增加按邮箱查询的只读接口}
范围：只允许修改 {包名/目录} 下的文件；文档仅在必要时更新 README 一小节。
限制：
- 不要改变既有接口的返回结构；
- 不要升级依赖版本；
- 不要执行删除文件、强制推送、修改 CI 密钥类操作；
- 不要 git commit / push。
验证：
- 修改后运行：{e.g. mvn -pl xxx test 或 npm test 或具体命令}；
- 若无法运行测试，请说明阻塞原因与你已做的静态检查。
交付：
1）变更文件列表；
2）行为说明（给 reviewer 看）；
3）你执行过的命令与结果摘要；
4）残留风险（若有）。

L3 pass criteria:

[ ] All four deliverables present (list / explanation / command results / risks)
[ ] The diff is reviewable by a third person (no mysterious large-scale reshuffling)
[ ] Verification commands were run, or the blocker is credible
[ ] You explicitly decide: accept / partially accept / roll back — the decision stays with a human

L3 explicitly should NOT be: whole-site rewrites, multi-service migration in one shot, "refactoring as a side effect" without tests, production data operations, permission escalation, key rotation — and never treat "one conversation" as "can merge without review."

Screenshot checklist (for your team channel)

Four to six screenshots beat a paragraph of adjectives:

#	What to capture	What it proves
1	`soloncode version` output	installed
2	Web Settings → LLM + test connection success	model wired up
3	L1's reply about project structure	reads the workspace
4	Git Diff or `git diff` snippet (mask sensitive info)	actually changed code/docs
5	Agent's change summary + your verification output	reviewable and verifiable
6	(optional) Web file tree + workspace path	right directory

Top 10 failures and where to look first

Debugging hint from the official docs: check on-disk logs under the workspace .soloncode/logs/; docs: logs & troubleshooting.

#	Symptom	Check first	Fix
1	`soloncode` command not found	PATH, installed for current user	reinstall; new terminal; confirm `~/.soloncode/bin`
2	Java not 8+ / missing	`java -version`	install any JDK 8–26 release
3	Web UI won't open	terminal URL; port occupied	use `web 0` or another port; open the printed address manually
4	Model connection fails	`apiUrl` / `apiKey` / model name	compare character-by-character with provider console; check proxy
5	401 / 403	key permissions & quota	rotate key; check plan and IP restrictions
6	Timeout / spinner forever	network, proxy, cross-border path	switch to reachable gateway; increase timeout; try a lighter model
7	Chats but won't touch files	prompt forbade changes; permission / sandbox	L2: explicitly allow target paths; check tool permissions in settings
8	Modified wrong directory	launch dir ≠ repo root	`cd` to the root containing `pom.xml` / `package.json` / `.git` before starting
9	Ignoring instructions	language expectations	the product is Chinese-prompt-driven; write constraints in Chinese
10	Weird behavior / stale state	long or old session context	start a new session; complex tasks → check task state under `.soloncode/sessions/`

Mental note on safety: HITL (human-in-the-loop) switches like hitlEnabled exist in settings. During your first success, keep the default conservative posture — don't disable safety-related limits just to go faster on a production repo.

After first success: only two compounding steps

Don't dive straight into Loop / multi-agent / IM binding. The smallest next loop is:

1. Write a 10-line project AGENTS.md at .soloncode/AGENTS.md (workspace beats user-level ~/.soloncode/AGENTS.md). Minimal copy-paste template:

# 本项目 Agent 规约（精简）

## 必须
- 改代码前先读相关文件；小步修改
- 优先运行项目既有测试命令（见 CODE.md）
- 完成后给出：变更列表、验证方式、风险

## 禁止
- 无确认不删文件、不 force push、不改密钥与 CI 密钥
- 不引入与任务无关的依赖升级
- 不把 API Key 写进仓库

## 技术偏好
- 语言/框架：{填写}
- 代码风格：与现有文件保持一致

The official advice: keep it short so it doesn't eat your context; state identity, boundaries, and workflow clearly.

2. Install exactly one Skill. Either via Web Settings → Skill Market (browse, read the description, then install to global or workspace pool), or manually: drop a directory containing SKILL.md into ~/.soloncode/skills/ or .soloncode/skills/. Trigger it with:

请使用 {技能名} 按它的规约帮我完成 {一件具体事}。

CLI skill completion: $(tab). Principle: read the SKILL.md scenario and permissions before installing. More skills ≠ stronger agent; more relevant skills = stronger agent. Official skills doc: agent skills.

Boundaries: what is NOT first success, and when to stop

Not first success yet: you only opened the web page and the model test fails; you only chatted and never produced a reviewable diff in a real repo; you have a diff but never looked at it and can't explain it.

Stop for today if: the target is a production main branch with no tests and no one available to review; the ask is architecture-level rewrite; or you have no legitimate model access path (account / gateway / compliance).

SolonCode is a delegatable coding agent, not an auto-disclaimer machine. People own direction, boundaries, and merge; the agent advances within the boundary.

The 15-minute path (one page)

1. java -version            # 8+
2. curl ...setup.sh | bash  # or irm ...setup.ps1 | iex
3. soloncode version
4. soloncode web 0
5. Settings → LLM → Add model → Test connection → say "你好"
6. cd your-project && soloncode web 0
7. L1: scan the project (no file changes)
8. L2: small change + you review the diff
9. (optional) L3: constrained small feature + verification commands
10. Write a 10-line .soloncode/AGENTS.md or install one skill

Why this matters

First success isn't about faith in AI; it's about four real things: a real environment (JDK + command on PATH), a real model (test the connection, don't just save the form), a real task (a reviewable small change in the project root), and real review (a human reads the diff and clicks merge).

When you can repeat L2 reliably, SolonCode stops being "another chat window" and becomes the onboarding day of a digital employee in your workflow. The next steps — model routing & cost (series B2), codifying specs into AGENTS.md (series D3), or remote delegation via IM (series C2) — all build on the pass criteria above.

Try it now: run the first 8 steps of the one-page path and keep the L2 diff screenshot. That's the most honest manual SolonCode can give you.

References (all official): Repository · Docs entry · Quick start: install to first conversation · Install / update / uninstall · Settings & Web UI · Web interaction mode · Workspace & AGENTS.md / CODE.md · Skills · Logs & troubleshooting · Offline releases (Gitee)

Solon Server Threads: Zero-Config Auto-Tuning by CPU Cores — ioBound, coreThreads, maxThreads

Solon Framework — Mon, 03 Aug 2026 15:58:02 +0000

It was 2 AM, and the on-call chat was on fire again: the order service was healthy on every dashboard, but throughput had flatlined at ~800 req/s while P99 climbed past 4 seconds. The usual suspect? A thread pool sized by guesswork during a late-night deploy, six months earlier. We'd hand-tuned maxThreads to "something that felt right," and it wasn't right anymore.

That's the moment I started appreciating a different default: in Solon, all of those knobs ship as 0 — meaning auto, derived from your machine's actual CPU cores at runtime. You can go months without thinking about a single thread-pool property. This post walks through the five knobs that exist, how the auto-tuning math works, and the three failure modes that tell you it's time to touch them.

The five knobs under the hood

Solon exposes these on app.yml (all values are the documented defaults):

# Minimum threads for the http server (0 = auto; also accepts fixed values like 2, or core multiples like x2)
server.http.coreThreads: 0
# Maximum threads for the http server (0 = auto; also accepts fixed values like 32, or core multiples like x32)
server.http.maxThreads: 0
# Idle thread timeout in ms (0 = auto)   # supported since v1.10.13
server.http.idleTimeout: 0
# Is this an IO-bound service? (default true)   # supported since v1.12.2
server.http.ioBound: true

# Enable the virtual thread pool (default false)   # supported since v2.7.3
solon.threads.virtual.enabled: false

Notice what's missing: no hard-coded defaults for coreThreads or maxThreads. 0 means "figure it out from the hardware." That single decision removes a whole class of "copy-pasted tuning values" problems — the ones that were right for someone else's 32-core box and wrong for your 2-core container.

CPU-bound or IO-bound: the one question that matters

The auto-tuner only needs you to answer one question: is your workload CPU-bound or IO-bound?

CPU-bound: the work happens entirely in CPU and memory — think a "hello world" handler that returns a string. Responses are extremely fast. Here, more threads just means more context-switch overhead; you're paying for nothing.
IO-bound: the work touches the network card or disk — a CRUD write to a database, an uploaded file flushed to disk. These requests can take 10+ seconds, and each one occupies a thread while it waits. Threads run out fast.

The server.http.ioBound flag tells the framework which world you live in, and the auto-tuner adjusts accordingly.

The auto-tuning math

With server.http.ioBound: true (the default):

Setting	Formula	Example: 2c4g box
coreThreads	CPU cores × 2	4
maxThreads	coreThreads × 32	128

With server.http.ioBound: false:

Setting	Formula	Example: 2c4g box
coreThreads	CPU cores × 2	4
maxThreads	coreThreads × 8	32

IO-bound services get 4× the headroom — because each thread spends most of its life waiting on IO, you need more of them in flight to keep the machine busy. CPU-bound services stay lean, because the CPU is the bottleneck and extra threads only add switching costs.

Doing the math yourself, the two-minute version

Before you override anything, it helps to estimate what a setting is worth:

Throughput (QPS). If one request takes 0.1 s to respond, one thread can serve ~10 requests per second. 100 threads → ~1000 QPS. Thread count is a direct throughput ceiling.

Memory. Each thread costs at least 1–2 MB. 100 threads ≈ 200 MB just sitting there. A 200 KB request payload can exist in ~4 copies during processing (≈800 KB), so at 1000 QPS you're churning ~800 MB/s of request data — and if GC only frees it after ~5 s, that's ~4 GB/s of live pressure. Thread tuning and memory tuning are the same conversation.

Why coreThreads is the "do not touch" knob

Two reasons, depending on the underlying transport:

For BIO servers, a large coreThreads means the pool never shrinks — your "minimum" becomes a permanent resident of RAM.
For NIO servers, coreThreads must stay small because the pool is two-staged: coreThreads is stage one, maxThreads is stage two. Bloating stage one defeats the whole design.

Default it, and forget it. If you're going to change anything, it's maxThreads.

Three ways "threads are exhausted" shows up

When maxThreads is genuinely too small, the symptoms are distinct — and each one tells you where the bottleneck is:

It stalls, then recovers. The pool rejects a submission and the main thread takes over the work. The main thread can't accept new requests while it's busy, so things pause — then resume once the backlog clears. Annoying, but survivable.
The protocol returns an error / refuses service. The server actively rejects requests with an error, so the client learns immediately that the server is overwhelmed. This is the polite refusal.
The connection just drops. The threads that parse the protocol are exhausted too — there's no thread left to even craft a proper error response, so the server slams the connection shut.

Symptom 3 is the emergency red line. Symptom 1 is your early warning.

When (and how) to actually override maxThreads

"Leave it at the default" is the honest starting point. The framework's auto values handle the vast majority of single-instance deployments. You reach for maxThreads when you're single-instance with heavy traffic or slow requests — and you size it against your memory budget, not against vibes.

Official guidance example: on a 1c2g container, you might configure x256 → 512 threads. At ~2 MB per thread, that's ~1 GB of thread memory alone, leaving ~1 GB for business data processing. Tight — and the docs say so plainly: it may be borderline, and it may blow up memory. The point isn't the exact number; it's that you should compute the memory cost before you type a bigger number.

Virtual threads: one flag, when your Java allows it

Since v2.7.3, Solon has a dedicated switch:

solon.threads.virtual.enabled: true   # default: false

One property. If your runtime supports virtual threads (Java 21+), this is the "more concurrency without more native threads" lever — the alternative to hand-inflating maxThreads. It exists precisely because the answer to "threads not enough" should not always be "increase the pool."

Context: how server configs relate

If you're wondering where these keys fit in the wider config map: Solon splits server settings into four series — server.* (the master config, reused by all signals), server.http.*, server.socket.*, and server.websocket.*. When a signal-specific value is absent, it falls back to the master config. Ports are the special case: http uses the main port, socket defaults to main + 20000, websocket to main + 15000.

And for the curious: Solon's http signals ship as tiny plugins — solon-server-jdkhttp (0.1 MB, BIO-based) and solon-server-smarthttp (0.5 MB, AIO-based). Your server.http.* knobs tune whichever signal you pulled in. (For context, in the Spring world — general knowledge, not a Solon claim — you'd typically hand-edit something like server.tomcat.threads.max and pick a fixed number yourself.)

The takeaway

Threads aren't "more is better," and they aren't "fewer is better" either — they're a budget you should spend knowingly. Solon's approach is to make the default a computed number (CPU cores × 2 → × 32 or × 8 depending on ioBound) instead of a hard-coded guess, so you only think about threads when your workload genuinely asks for it. When it does: size maxThreads against memory, leave coreThreads alone, and remember the virtual-thread flag is one line away.

Next time your on-call chat lights up at 2 AM, the answer might be a single server.http.maxThreads line — or the discovery that 0 was doing fine all along.

Written while exploring Solon (v4.0.4), an Apache-2.0 Java framework. Facts checked against the official docs (solon.noear.org articles 513, 565, 131).

Solon.cfg() Everything: The Programmatic Config Center Behind SolonProps — Typed Getters, Prefix Groups, and Bean Binding

Solon Framework — Sun, 02 Aug 2026 10:07:35 +0000

Most frameworks make you read config the same way: sprinkle @Value annotations everywhere, or grab a string from Environment and parse it yourself every single time. It works, but the code ends up with a hundred tiny, untestable couplings to a file somewhere.

Solon's answer is different. Config is not scattered across annotations — it lives in one place, and you can reach it from anywhere in your app. That place is SolonProps, the application's property collection (a.k.a. the config center). You grab it with a single static call:

SolonProps props = Solon.cfg();

That's it. No injection, no context lookup. Solon.cfg() is available anywhere, including in static contexts and utility classes. This post walks through the API surface you'll actually use — typed getters, prefix grouping, bean conversion, expression/template lookup, and dynamic loading.

1. Typed getters — no more manual parsing

The most common thing you do with config is read a value. SolonProps gives you typed shortcuts so you never hand-parse a string:

String name  = props.get("demo.name");              // String, or null
String port  = props.get("demo.port", "8080");      // with default
int    max   = props.getInt("demo.max", 100);       // int
long   ttl   = props.getLong("demo.ttl", 3000L);    // long
double ratio = props.getDouble("demo.ratio", 0.5);  // double
boolean on   = props.getBool("demo.on", false);     // boolean

There's also getByKeys("demo.url", "demo.url2") which returns the first non-null value across several keys — handy when you're migrating config keys and want a graceful fallback.

2. Prefix grouping — get a whole section at once

This is where it gets interesting. Spring has @ConfigurationProperties(prefix=...), but Solon does it at runtime without any annotation. Pass a key prefix and you get back a fresh Props collection with just that section:

// app.yml
// demo.db:
//   url: jdbc:mysql://localhost:3306/demo
//   user: root
//   maxPool: 8

Props db = props.getProp("demo.db");
String url = db.get("url");
int pool   = db.getInt("maxPool", 4);

Three variants cover different shapes:

getProp(keyStarts) → a single Props (one section)
getGroupedProp(keyStarts) → Map<String, Props> (multi-instance sections like demo.db1, demo.db2)
getListedProp(keyStarts) → Map<String, Props> (list-style indexed sections)

So multi-datasource or multi-client configs don't need custom parsing code. The framework splits them for you.

3. Bean conversion — config straight into objects

Instead of reading keys one by one, bind an entire prefix to a POJO:

// demo.mail:
//   host: smtp.example.com
//   port: 587
//   from: no-reply@example.com

public class MailConfig {
    public String host;
    public int    port;
    public String from;
}

MailConfig cfg = props.toBean("demo.mail", MailConfig.class);

Or bind the whole property set to an existing bean instance:

MailConfig cfg = new MailConfig();
props.bindTo(cfg);   // matches keys against bean fields

toBean(Class<T>) converts the entire collection; toBean(prefix, Class<T>) scopes it to a prefix. bindTo(bean) mutates an existing instance. No reflection boilerplate on your side.

4. Expression & template lookup

Config values can reference each other (Solon resolves ${...} inside values at load time), but you can also do it on demand:

// expr:  ${key} | key | ${key:def} | key:def
String v1 = props.getByExpr("demo.db.url");          // plain key
String v2 = props.getByExpr("${demo.db.url}");       // explicit expr
String v3 = props.getByExpr("${demo.db.port:3306}"); // with default

// tmpl:  ${key} | aaa${key}bbb | ${key:def}/ccc
String t1 = props.getByTmpl("jdbc:${demo.db.url}/db"); // template

getByExpr is for single expressions, getByTmpl for embedding values inside larger strings. Both respect :def defaults.

5. Loading & extending at runtime

Solon apps load app.yml automatically, but you can pull in more files at any time:

props.loadAdd("classpath:demo-ext.yml");        // from classpath
props.loadAdd(new URL("file:/etc/app/extra.yml")); // from URL
props.loadAdd(System.getProperties());          // merge JVM props

There's also loadAddIfAbsent(...) for incremental loading that won't clobber existing keys — useful for layering environment overrides. And if you build a plugin that needs to contribute config, loadAdd(Properties) plus plugs() (the plugin config collection) are your integration points.

6. Environment variables — bridge 12-factor style

Kubernetes, Docker, and CI all prefer env vars over files. Pull them into your props with a prefix filter:

props.loadEnv("DEMO_");                          // all vars starting with DEMO_
props.loadEnv(k -> k.contains("SOLON"));         // custom predicate

Loaded vars become normal props, readable through all the typed getters above. One line, no third-party dotenv library.

7. App & server metadata

The framework exposes its own identity as typed getters — useful in logs, health checks, and admin pages:

props.appName();        // solon.app.name
props.appGroup();       // solon.app.group
props.appNamespace();   // solon.app.namespace
props.appTitle();       // solon.app.title
props.appEnabled();     // solon.app.enabled (health)
props.locale();         // solon.locale

props.serverPort();     // server.port
props.serverHost();     // server.host
props.serverContextPath(); // server.contextPath

8. Runtime mode checks

Instead of passing flags around, ask the config center directly:

if (props.isDebugMode())      { /* dev-time behavior */ }
if (props.isSetupMode())      { /* first-run setup     */ }
if (props.isFilesMode())      { /* running from files  */ }
if (props.isDriftMode())      { /* solon cloud drift   */ }
if (props.isWhiteMode())      { /* security whitelist  */ }
if (props.testing())          { /* under unit test     */ }
if (props.isEnabledVirtualThreads()) { /* JDK 21+        */ }

9. One subtle gotcha: removing a key

Because props are synced to System.getProperties() at load time, removing a key requires a double delete:

props.remove("redis.onOff");
System.getProperties().remove("redis.onOff");

Forget the second line and the key can still surface through System.getProperties() lookups. It's the one place where the two-way sync shows its face.

Where it fits compared to Spring

@Value("${x}") → props.get("x") or the typed getters — no annotation needed, works in any context including static methods
Environment.getProperty("x") → Solon.cfg().get("x") — available without injecting Environment
@ConfigurationProperties(prefix="x") → props.getProp("x") / props.toBean("x", X.class) — runtime, no compile-time binding

Spring's approach is declarative and compile-checked; Solon's is a single runtime object with the same power, minus the annotation ceremony. Pick whichever fits your style — but know that in Solon the config center is always one call away.

TL;DR

Solon.cfg() gives you the whole config center, from anywhere, no injection
Typed getters (getInt/getLong/getBool/getDouble) kill manual parsing
getProp/getGroupedProp/getListedProp split config by prefix at runtime
toBean/bindTo convert config sections into POJOs without annotations
loadEnv(prefix) bridges env vars; loadAdd/loadAddIfAbsent layer extra files
getByExpr/getByTmpl handle expression and template lookup with :def defaults
Deleting a key needs a double remove (props + System.getProperties())

Full API reference: SolonProps Interface Reference — part of the official Solon config guide.

Solon Config Vault: ENC() Secrets, @VaultInject, and a Runtime Key — No Jasypt, No Config Server

Solon Framework — Sun, 02 Aug 2026 03:48:39 +0000

Every team has that one application.yml with a database password sitting in plain text, committed to a repo that half the company can read. You know it should not be there. But the fix usually means pulling in Jasypt, standing up a config server, or explaining to your ops team why they need to manage another secret store.

Solon takes a much smaller route. There's a built-in plugin called solon-security-vault that lets you encrypt sensitive values (database credentials, API keys, whatever) and mark them with an ENC(...) prefix right in your config file. No external service. No new infrastructure. Just a dependency, a helper method, and one annotation.

Full disclosure, straight from the official docs: this is "anti-honest-people, not anti-thieves." It keeps secrets from being readily visible, it does not pretend to be a KMS. If you need defense-in-depth, pair it with a proper config center. But for the very common problem of "don't leave plaintext passwords in Git," it's a clean, pragmatic answer.

The shape of it

You configure one vault password, then any value wrapped in ENC(...) gets decrypted on injection:

solon.vault:
  password: "liylU9PhDq63tk1C"

test.db1:
  url: "jdbc:mysql://localhost:3306/demo"
  username: "ENC(xo1zJjGXUouQ/CZac55HZA==)"
  password: "ENC(XgRqh3C00JmkjsPi4mPySA==)"

Three things to notice:

The vault password itself can come from a JVM arg at runtime instead of living in the file (more on that below).
The default algorithm expects a 16-character password — mixed case and digits are recommended.
Only the values wrapped in ENC(...) are affected. Everything else stays as normal config.

Step 1 — Add the plugin

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-security-vault</artifactId>
</dependency>

Step 2 — Generate ciphertext

You don't hand-roll the encrypted strings. A tiny helper in your app prints them:

public class TestApp {
    public static void main(String[] args) throws Exception {
        Solon.start(TestApp.class, args);

        // prints the encrypted form of "root"
        System.out.println(VaultUtils.encrypt("root"));
    }
}

Run it once, copy the output into your ENC(...) values, and delete the helper. (Or keep it behind a flag for rotating secrets later.)

Step 3 — Inject with @VaultInject

The idiomatic way is the @VaultInject annotation. It decrypts on the way in, so the rest of your code never sees the ciphertext:

@Configuration
public class TestConfig {
    @Bean("db2")
    private DataSource db2(@VaultInject("${test.db1}") HikariDataSource ds) {
        return ds;
    }
}

The manual route: VaultUtils.guard()

Not everything fits an annotation. When you need to decrypt imperatively, VaultUtils has you covered — either a whole config block or a single value:

// decrypt a whole config block
Props props = Solon.cfg().getProp("test.db1");
VaultUtils.guard(props);
HikariDataSource ds = props.getBean(HikariDataSource.class);

// decrypt a single value
String name = VaultUtils.guard(Solon.cfg().get("test.demo.name"));

This composes nicely with Solon.cfg() — the same property-collection entry point you already use for everything else. No second API to learn.

Keep the key out of the file

Hardcoding the vault password next to the ciphertext is only marginally better than hardcoding the plaintext. The docs suggest passing it at runtime instead:

java -Dsolon.vault.password=your-16-char-key -jar demo.jar

And if you're used to --key=value style args, Solon treats both forms equivalently — any startup arg containing a dot also becomes an app property. So --solon.vault.password=... works just the same. That means CI/CD pipelines can inject the key per environment without touching the repo at all.

Bring your own algorithm

The plugin ships with an AesVaultCoder, and the VaultCoder interface is your extension point. Either implement it as a component or register an existing implementation as a bean:

@Component
public class VaultCoderImpl implements VaultCoder {
    private final String password;

    public VaultCoderImpl() {
        // even the password's config key can be changed
        this.password = Solon.cfg().get("solon.vault.password");
    }

    @Override
    public String encrypt(String str) throws Exception { /* ... */ }

    @Override
    public String decrypt(String str) throws Exception { /* ... */ }
}

Or swap in a ready-made coder:

@Configuration
public class Config {
    @Bean
    public VaultCoder vaultCoderInit() {
        return new AesVaultCoder();
    }
}

The honest boundary

Let me quote the official line again, because it matters: this feature is "to prevent the gentleman, not the villain." It stops sensitive values from being directly visible — a stray screenshot, a careless paste, a config dump in CI logs. It is not encryption at rest for your whole config system, and the vault password itself must be protected.

So my take, after using it:

Use it for: keeping DB passwords, tokens, and API keys out of plaintext in shared repos.
Don't use it as: a replacement for a KMS or a proper config center when you operate at that scale.
Pair it with: a runtime-injected solon.vault.password, and treat the key like you'd treat any other secret — rotate it, restrict it.

If you've come from Spring Boot, this is the niche that Jasypt usually fills — except here it's a first-party Solon plugin, the annotation is native, and the whole thing hangs off Solon.cfg() with zero extra services. For a framework that prides itself on being restrained, it's a surprisingly complete little feature.

Now go find that plaintext password in your repo. You know the one.

Solon Config Injection: @Inject, @BindProps, and Auto-Refresh — No @Value, No @ConfigurationProperties

Solon Framework — Sat, 01 Aug 2026 15:45:49 +0000

I've been using Solon for a while now, and one of the first things I had to unlearn coming from Spring was how configuration gets into my code. There is no @Value scatter, no @ConfigurationProperties class hierarchy — but honestly, after a week I stopped missing both.

Here's how config injection and binding actually work in Solon, with the exact APIs I use daily.

The three expression forms you'll meet

Solon's @Inject uses a ${...} expression syntax. Three forms cover almost everything:

@Inject("${track.name}")              // plain property lookup
@Inject("${track.name:demoApi}")      // with a default value
@Inject("${classpath:user.config.yml}") // inject a whole resource file

The ${xxx:def} default only works for single values — don't try to default a collection or an entity with it. For those, you inject a whole property block instead (more below).

Field injection, the everyday case

@Component
public class DemoService {

    // static field injection, supported since v3.0
    // autoRefreshed = the value updates when config changes (singleton only!)
    @Inject(value = "${track.name:demoApi}", autoRefreshed = true)
    static String trackName;

    // without a match, the field initial value is kept
    @Inject("${track.url}")
    String trackUrl = "http://x.x.x/track";

    // inject a whole config block as Properties
    @Inject("${track.db1}")
    Properties trackDbCfg;

    // or let Solon build a real bean from the config block
    @Inject("${track.db1}")
    HikariDataSource trackDs;
}

The last two lines are the ones that surprised me most. Give @Inject a target type and a property prefix, and Solon constructs the object from the config block — HikariDataSource gets built straight from track.db1.* keys. No manual setJdbcUrl(...) wiring.

One caveat that bit me: autoRefreshed = true is only safe on field injection into singleton beans. If the bean is prototype-scoped, leave auto-refresh off, or you'll get surprising mid-lifecycle value swaps.

Injecting into @bean method parameters and constructors

@Configuration
public class DemoConfig {

    // inject a datasource built from config, into a @Bean method
    @Bean
    public DataSource db1(@Inject("${track.db1}") HikariDataSource ds) {
        return ds;
    }

    // conditional bean: only created when the property exists and is true
    @Bean
    @Condition(onExpression = "${cache.enable:false} == true")
    public CacheService cache(@Inject("${cache.config}") CacheServiceSupplier supplier) {
        return supplier.get();
    }
}

Constructor injection works the same way on @Component classes:

@Component
public class DemoConfig {
    private String demoName;

    public DemoConfig(@Inject("${demo.name}") String name) {
        this.demoName = name;
    }
}

Binding a whole config class: @BindProps

If you prefer a typed config object you can reuse (closer to Spring's @ConfigurationProperties), bind it once and inject it anywhere:

// Option A: bind with @Inject + @Configuration
@Inject("${user.config}")
@Configuration
public class UserProperties {
    public String name;
    public List<String> tags;
}

// Option B: bind with @BindProps (since v3.0.7) — also generates
// config metadata for IDE hints
@BindProps(prefix = "user.config")
@Configuration
public class UserProperties {
    public String name;
    public List<String> tags;
}

// Or bind on a @Bean method
@Configuration
public class DemoConfig {
    @BindProps(prefix = "user.config")
    @Bean
    public UserProperties userProperties() {
        return new UserProperties();
    }
}

Then reuse it anywhere with a plain @Inject:

@Inject
UserProperties userProperties;

A detail I appreciate: @Inject on classes has required detection — if the config is missing, Solon raises an exception instead of silently injecting nulls. That catches typos in app.yml at startup, not at 3am in production.

Manual access when you don't want injection

Sometimes injection is overkill — a util class, a static context, a one-off lookup. Solon.cfg() is your gateway:

String name  = Solon.cfg().get("track.name", "demoApi");   // with default
String url   = Solon.cfg().get("track.url");               // plain

Properties dbCfg = Solon.cfg().getProp("track.db1");       // whole block as Properties
HikariDataSource ds = Solon.cfg().getBean("track.db1", HikariDataSource.class); // as bean

Prefer method-call form for frequently-read values so you always get the freshest state:

public static String trackName() {
    return Solon.cfg().get("track.name", "demoApi");
}

Change subscription: two ways

Config can change at runtime (config service push, code updates). Two mechanisms exist:

1. Auto-refresh on injected fields (singletons only):

@Inject(value = "${track.name:demoApi}", autoRefreshed = true)
String trackName;

2. Manual subscription — you get every changed key and filter what you need:

Solon.cfg().onChange((key, val) -> {
    if (key.startsWith("track.name")) {
        // refresh whatever depends on it
    }
});

The mental model

You want to...	Spring way	Solon way
Inject a scalar	`@Value("${x}")`	`@Inject("${x}")` or `@Inject("${x:def}")`
Inject a config block	`@ConfigurationProperties` + class	`@Inject("${prefix}")` into `Properties` or a typed target
Reusable typed config	`@ConfigurationProperties` + registration	`@Inject`/`@BindProps` + `@Configuration` class, plain `@Inject` to reuse
Build a bean from config	`@Bean` + manual mapping	`@Inject("${prefix}") HikariDataSource` or `Solon.cfg().getBean(...)`
React to config change	`@RefreshScope` (cloud)	`autoRefreshed=true` or `Solon.cfg().onChange(...)`
Missing key handling	silently null / error varies	`@Inject` throws on missing (required detection)

Two things worth calling out:

@Inject doubles as the bean-injection annotation. In Spring, @Autowired and @Value are separate concerns. In Solon, one annotation handles bean references (@Inject DataSource) and config values (@Inject("${...}")) — and when both are present (@Inject("${track.db1}") HikariDataSource), it builds a bean from config. Fewer annotations, one consistent rule.
The config block is a first-class citizen. getProp() / getBean() on any prefix means config-to-object conversion isn't locked inside a DI annotation — it's available anywhere Solon.cfg() is.

That's the whole surface. No profile classes to register, no @ConfigurationProperties hierarchy to maintain — a prefix, a target type, and Solon does the rest.

Solon Multi-Environment Config: Six Loading Tiers, an In-File Segment Trick, and No Profiles API

Solon Framework — Sat, 01 Aug 2026 15:05:29 +0000

If you've spent time with Spring Boot, you know the spring.profiles.active routine — one property, multiple application-{profile}.properties files, and a creeping suspicion that somewhere a prod config is silently falling back to dev defaults.

Solon's answer is solon.env. Same concept, different design choices — and one pattern (solon.env.on in-file segments) that Spring has no direct equivalent for.

Here's how it works.

The Single Key: `solon.env`

Everything in Solon's multi-environment system pivots on one property:

# app.yml
solon.env: dev

Set this, and Solon automatically loads app-dev.yml alongside app.yml. Remove it, and only app.yml loads. No profiles API, no @ActiveProfiles, no annotation scanning — just a key.

Environment-Specific Files

The naming convention is app-{env}.yml (or .properties):

app.yml          ← always loaded
app-dev.yml      ← loaded when solon.env=dev
app-pro.yml      ← loaded when solon.env=pro
app-test.yml     ← loaded when solon.env=test

Keys in app-{env}.yml override the same keys in app.yml. Everything else in app.yml is inherited.

One constraint worth knowing: app-{env}.yml cannot itself declare another solon.env. The env chain is intentionally one level deep.

Four Ways to Activate an Environment

You don't have to hardcode solon.env in the file. You can set it at any of four levels, with higher numbers winning:

Priority	Method	Example
1 (lowest)	In `app.yml`	`solon.env: dev`
2	JVM system property	`-Dsolon.env=pro`
3	Launch argument	`--env=pro`
4 (highest)	OS environment variable	`export solon.env=pro`

In practice: set solon.env: dev in app.yml as a safe default for local development, then override at deploy time:

# Jar deployment
java -jar demo.jar --env=pro

# Docker run
docker run -e 'solon.env=pro' demo_image

# Kubernetes pod spec
env:
  - name: solon.env
    value: pro

All three launch forms below are equivalent:

java -Dsolon.env=pro -jar demo.jar
java -jar demo.jar --solon.env=pro
java -jar demo.jar --env=pro

Six Loading Tiers

solon.env controls which env file loads, but that's just the first two tiers of a six-tier config loading stack. Later tiers override earlier ones:

Tier	Source	Notes
1	`app.yml` + `app-{env}.yml`	Base config, inside the jar
2	`solon.config.load` classpath entries	v2.2.7+, supports `${solon.env}` variables; wildcard `*` from v2.7.6+
3	`solon.config.add` external files	Files placed beside the jar at runtime
4	JVM props / env vars / launch args	Runtime overrides
5	`app.cfg().loadAdd()` in startup code	Programmatic additions
6	Solon Cloud Config (e.g., Nacos)	Remote config center

The pattern: static defaults live inside the jar, runtime overrides live outside it, remote config sits at the top.

Loading More Configs: `solon.config.load`

For apps with per-module configs, solon.config.load lets you declare additional classpath resources with variable substitution and wildcard support (v2.7.6+):

# app.yml
solon.env: dev

solon.config.load:
  - "classpath:${solon.env}/jdbc.yml"        # resolves to classpath:dev/jdbc.yml
  - "classpath:${solon.env}/*.yml"           # all yml in dev/ folder (v2.7.6+)
  - "classpath:app-ds-${solon.env}.yml"      # e.g., app-ds-dev.yml
  - "classpath:common/base.yml"              # environment-agnostic shared config

This lets you split config by concern (database, cache, auth) rather than cramming everything into one file per environment.

For external files placed beside the jar, use solon.config.add:

solon.config.add: "./local-overrides.yml"

Or at launch time:

java -jar demo.jar --solon.config.add=./local-overrides.yml

The In-File Segment Trick (v2.5.5+)

This is the feature that has no Spring Boot equivalent. Solon lets you embed multiple environment-specific segments inside a single app.yml, separated by --- and guarded by solon.env.on:

solon.env: pro

---
solon.env.on: pro
demo.auth:
  user: root
  password: "${AUTH_PASSWORD}"

---
solon.env.on: dev|test
demo.auth:
  user: demo
  password: "demo1234"

Only the segment matching the current solon.env is applied. The | syntax lets one segment cover multiple environments.

This pattern suits small services where maintaining separate env files feels heavy, but you still want clear boundaries in the source.

Programmatic Loading

Sometimes you need to load config based on conditions known only at startup. Two clean hooks:

@SolonMain
public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args, app -> {
            // Tier 5: added before beans initialize, merged into the config stack
            app.cfg().loadAdd("app-jdbc-" + app.cfg().env() + ".yml");
            app.cfg().loadAdd("app-cache-" + app.cfg().env() + ".yml");
        });
    }
}

Or via @Import on the startup class:

@Import(profiles = "classpath:module-defaults.yml")
@SolonMain
public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args);
    }
}

For Docker/Kubernetes, loadEnv() pulls in environment variables by prefix:

Solon.start(App.class, args, app -> {
    app.cfg().loadEnv("demo."); // pulls in all env vars starting with "demo."
});

Note: Solon automatically syncs solon.* environment variables into the config store, so solon.env=pro as a container env var works without loadEnv().

Injecting Config Values

@Inject with ${} syntax wires config values into beans:

@Component
public class DataSourceConfig {

    @Inject("${db.url}")
    private String dbUrl;

    @Inject("${db.username}")
    private String username;
}

For structured config objects, @BindProps binds an entire prefix:

@BindProps(prefix = "app.mail")
@Component
public class MailProperties {
    public String host;
    public int port;
    public String username;
}

Variable references also work inside YAML values themselves:

db.server: "10.0.0.1"
db.name: "orders"
db.url: "jdbc:mysql://${db.server}/${db.name}"  # composed from other keys

A Realistic Project Layout

src/main/resources/
├── app.yml                   # base config + solon.env: dev
├── app-dev.yml               # dev overrides
├── app-pro.yml               # prod overrides
└── config/
    ├── common/
    │   └── base.yml          # shared constants (env-agnostic)
    ├── dev/
    │   └── jdbc.yml          # dev DB connection
    └── pro/
        └── jdbc.yml          # prod DB connection

app.yml:

solon.env: dev

solon.config.load:
  - "classpath:config/common/base.yml"
  - "classpath:config/${solon.env}/jdbc.yml"

solon.app.name: "order-service"
server.port: 8080

app-dev.yml:

solon.logging.level: debug
solon.debug: 1

app-pro.yml:

solon.logging.level: warn
server.port: 80

Deploy to prod:

java -jar order-service.jar --env=pro

One flag flips the entire config stack.

Migration Reference (from Spring Boot)

Spring Boot	Solon	Notes
`spring.profiles.active`	`solon.env`	Same concept, different key
`application-{profile}.properties`	`app-{env}.yml`	Same convention
`@Profile("dev")` on beans	`solon.env.on: dev` in YAML	Config-layer isolation vs code-layer
`@PropertySource`	`solon.config.load` in YAML	Declarative import
`@ConfigurationProperties(prefix="x")`	`@BindProps(prefix="x")`	Prefix binding
`@Value("${x}")`	`@Inject("${x}")`	Value injection

The mental model is nearly identical. The key difference: Solon keeps environment logic in config (via solon.env.on segments or separate files) rather than scattering @Profile annotations across bean definitions.

Key Takeaways

solon.env is the single activation key — set it in the file, at the JVM, or as a container env var
app-{env}.yml is loaded automatically; no registration step required
Six loading tiers let you layer static defaults with runtime overrides cleanly
solon.config.load with ${solon.env} handles per-module, per-environment config splitting
In-file --- segments with solon.env.on (v2.5.5+) are unique to Solon — useful for small services
Config injection uses @Inject("${...}") and @BindProps — both standard Solon IoC

The loading order is deterministic and documented. Deploy with confidence.

Solon's 10 HTTP Servers: Pick Your Engine With One Dependency Change

Solon Framework — Fri, 31 Jul 2026 04:34:01 +0000

I've been running Solon apps in production for a while now, and one thing that keeps surprising people is how the server engine works.

Not "which server does Solon use" — because the answer is: you choose.

Solon doesn't bundle a hardcoded HTTP server. The framework core is about 0.3MB. The HTTP engine is a separate plugin. You pick one. Or two. Or swap them between environments without touching a single line of application code.

Here's a quick rundown of the 10 HTTP server options, what they're good for, and how to switch.

The One-Dependency Swap

In Solon, changing your HTTP server means changing one dependency in pom.xml. Nothing else.

<!-- Default: jdkhttp (built-in JDK, 0.3MB) -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-web</artifactId>
</dependency>

Want Undertow instead?

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.noear</groupId>
            <artifactId>solon-server-jdkhttp</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-undertow</artifactId>
</dependency>

That's it. Your @Controller, @Mapping("/hello"), filters, interceptors — everything stays the same. The routing layer is framework-owned; the server underneath is a pluggable adapter.

The 10 Engines at a Glance

Plugin	Size	Protocols	Reactive	JDK
jdkhttp	0.3MB	http	✅	8+
smarthttp	0.8MB	http, ws	✅	8+
grizzly	1.8MB	http, ws, http2	✅	8+
vertx	6.3MB	http, ws, http2	✅	8+
jetty	2.7MB	http, ws	✅	8+
undertow	4.6MB	http, ws, http2	✅	8+
tomcat	—	http, ws, http2	✅	8+
jetty-jakarta	3.9MB	http, ws, http2	✅	17+
undertow-jakarta	—	http, ws, http2	✅	17+
tomcat-jakarta	—	http, ws, http2	✅	17+

Plus two dedicated WebSocket-only servers (solon-server-websocket at 0.4MB, solon-server-websocket-netty at 3.6MB) and one Socket.D server.

How to Choose

For microservices and edge services: jdkhttp or smarthttp

If you're building a lightweight API service or a microservice that needs to start in under a second, stick with jdkhttp. It's 0.3MB, requires zero external dependencies, and supports reactive I/O. The JDK built-in com.sun.net.httpserver is perfectly adequate for most API workloads.

smarthttp (0.8MB, Chinese-contributed) adds WebSocket support on the same port — useful if you need both REST and WebSocket without adding a second server.

@SolonMain
public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args, app -> {
            app.enableWebSocket(true);
        });
    }
}

When you need HTTP/2: grizzly, undertow, vertx, or tomcat

All four support HTTP/2. Enable it with a single line:

app.onEvent(HttpServerConfigure.class, e -> {
    e.enableHttp2(true);  // v2.3.8+
});

Undertow is a solid middle ground — 4.6MB, Apache 2.0 license, good community adoption. Vert.x is heavier (6.3MB) but gives you the full Vert.x event-loop ecosystem if you're already using it.

Traditional Java shops: Jetty or Tomcat

If your team is migrating from Spring Boot + embedded Tomcat, solon-server-tomcat is the most natural drop-in. It uses the same Tomcat v9 engine underneath — your ops team's existing tuning knowledge carries over.

Jetty is a great alternative if you prefer Eclipse ecosystem. It also has explicit JSP support via solon-server-jetty-add-jsp.

Jakarta EE migration: jetty-jakarta, undertow-jakarta, tomcat-jakarta

If you're on JDK 17+ and targeting Jakarta namespace (jakarta.*), use the Jakarta variants. They're paired with the corresponding Jakarta server versions (Jetty 12, Undertow 2.3, Tomcat 11).

The Code That Never Changes

This is the part I like most. No matter which server engine you pick, your application code looks identical:

@Controller
public class DemoController {
    @Mapping("/hello")
    public String hello() {
        return "Hello world!";
    }

    @Mapping("/greet/{name}")
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

The same code runs on jdkhttp (0.3MB, no dependencies), Undertow (4.6MB, HTTP/2), or Tomcat (production-hardened). Zero changes.

Advanced: Multiple Ports, SSL, and Debug Mode

All server adapters share the same configuration surface:

# app.yml
server.port: 8080
server.http.port: 8080          # alias
server.ssl.keyStore: "/data/ca/demo.jks"
server.ssl.keyPassword: "demo"

Or programmatically:

Solon.start(App.class, args, app -> {
    // Add a second HTTP port (useful when main port is HTTPS)
    app.onEvent(HttpServerConfigure.class, e -> {
        e.addHttpPort(8082);
        e.enableDebug(true);    // debug mode for smarthttp/jdkhttp
    });
});

Custom SSLContext (v2.5.9+):

app.onEvent(HttpServerConfigure.class, e -> {
    SSLContext sslContext = buildMyCustomSSLContext();
    e.enableSsl(true, sslContext);
});

What About the "Default" Default?

If you add solon-web without any explicit server exclusion, Solon uses jdkhttp — the built-in JDK HTTP server. It's the lightest option (0.3MB), requires zero external JARs, and works for 90% of development scenarios.

In production, you might want something more tuned. But the beauty is: you don't decide on day one. Start with jdkhttp, benchmark, then swap to Undertow or Tomcat when you need HTTP/2 or WebSocket — all without rewriting a single route.

Honest Limitations

Tomcat (v9) doesn't support WebSocket directly — you need the solon-server-tomcat-add-websocket sub-plugin.
smarthttp had a file upload size cap (~2.1GB) before v3.0.3 — fixed now, but worth noting if you're on an older version.
Vert.x is the heaviest at 6.3MB — great for reactive workloads but overkill for a simple CRUD API.
Jakarta variants (jetty-jakarta, undertow-jakarta, tomcat-jakarta) require JDK 17+.

Summary

Solon's pluggable server architecture is one of those features that seems small on paper but makes a big difference in practice. One dependency change, zero code impact, and a full spectrum of engines from 0.3MB to full-featured production servers.

Need	Pick
Lightest API server	jdkhttp (0.3MB)
REST + WebSocket on same port	smarthttp (0.8MB)
HTTP/2 + solid performance	undertow (4.6MB)
Spring Boot migration	tomcat
Reactive event-loop	vert.x or grizzly
Jakarta EE (JDK 17+)	jetty-jakarta / undertow-jakarta
Standalone WebSocket	solon-server-websocket (0.4MB)

The server is infrastructure. The framework is your code. Solon keeps them separate — and that's a good thing.

Solon Validation: @Valid, 20+ Annotations, and Custom Validators Without the JSR 380 Baggage

Solon Framework — Fri, 31 Jul 2026 02:00:18 +0000

I've been burned by JSR 380 enough times to appreciate a validation framework that doesn't drag in a whole ecosystem of dependencies. Solon's validation system lives in solon-security-validation — a single plugin that gives you 20+ annotations, entity validation, and custom validators, all without pulling in javax.validation or jakarta.validation.

Let me walk through what I've found useful.

The Two-Phase Validation Model

Solon separates validation into two phases:

Context validation (pre-injection) — runs before method parameters are resolved. Annotations on the method itself check headers, cookies, IP, or request-level constraints.
Parameter validation (post-injection) — runs after parameters are resolved. Annotations on individual parameters or entity fields.

This maps to two different implementation mechanisms:

Context validation uses @Addition(Filter.class) under the hood
Parameter validation uses @Around(Interceptor.class)

You don't need to think about this most of the time, but it explains why some annotations go on the method and others on the parameter.

Getting Started: @valid on a Controller

Add @Valid to your controller class (or its base class), then annotate the parameters:

@Valid
@Controller
public class UserController {

    @Mapping("/user/add")
    public void addUser(
            @NotNull String name,
            @Email String email,
            @Pattern("^https?://") String avatarUrl,
            @Length(min = 6, max = 20) String password) {
        // All parameters validated before this runs
    }
}

That's it. No need to configure a ValidatorFactory or declare a bean. @Valid on the class enables validation for all handler methods.

@Validated for Entity (Nested) Validation

When your parameter is a DTO with its own validation rules, use @Validated:

@Valid
@Controller
public class UserController {

    @Mapping("/user/register")
    public void register(@Validated RegisterRequest req) {
        // req fields are validated
    }
}

@Data
public class RegisterRequest {
    @NotNull
    @Length(min = 2, max = 50)
    private String name;

    @Email
    @NotNull
    private String email;

    @Validated  // Nested entity validation
    @NotNull
    @Size(min = 1)
    private List<Order> orderList;
}

Group Validation

For update vs create scenarios, use groups:

public interface UpdateGroup {}

@Data
public class User {
    @NotNull(groups = UpdateGroup.class)  // Only required on update
    private Long id;

    @NotNull
    private String name;
}

// Controller
@Valid
@Controller
public class UserController {
    @Mapping("/user/update")
    public void update(@Validated(UpdateGroup.class) User user) {
        // Only validates fields in UpdateGroup
    }
}

The 20+ Annotations in One Table

Solon's validation plugin ships with a comprehensive set of annotations. Here's the full list:

Annotation	Scope	Purpose
`@Valid`	Controller class	Enable validation
`@Validated`	Parameter/field	Validate entity fields
`@NotNull`	Method/param/field	Not null
`@Null`	Method/param/field	Is null
`@NotBlank`	Method/param/field	Not blank string
`@NotEmpty`	Method/param/field	Not empty string
`@NotZero`	Method/param/field	Not zero
`@Min(value)`	Parameter/field	>= value
`@Max(value)`	Parameter/field	<= value
`@DecimalMin(value)`	Parameter/field	>= decimal value
`@DecimalMax(value)`	Parameter/field	<= decimal value
`@Length(min, max)`	Parameter/field	String length range
`@Size`	Parameter/field	Collection size range
`@Email`	Parameter/field	Email format
`@Pattern(value)`	Parameter/field	Regex match
`@Date`	Parameter/field	Date format
`@Numeric`	Parameter/field	Numeric format
`@Logined`	Controller/method	User is logged in
`@NoRepeatSubmit`	Controller/method	No duplicate submission
`@Whitelist`	Controller/method	IP in whitelist
`@NotBlacklist`	Controller/method	IP not in blacklist

A few of these (@Logined, @NoRepeatSubmit, @Whitelist, @NotBlacklist) are "business-aware" — they need you to implement a checker interface. More on that below.

Validation on Non-Web Components

This surprised me: Solon's validation also works on plain @Component classes, not just controllers:

@Valid
@Component
public class UserService {
    public void addUser(@NotNull String name, @Email String email) {
        // Validation works here too
    }
}

Manual Validation with ValidUtils

You can also validate programmatically anywhere:

User user = new User();
user.setName(null);
ValidUtils.validateEntity(user);  // throws ValidatorException if invalid

Handling Validation Errors

Catch ValidatorException in a filter:

@Component
public class ValidationFilter implements Filter {
    @Override
    public void doFilter(Context ctx, FilterChain chain) throws Throwable {
        try {
            chain.doFilter(ctx);
        } catch (ValidatorException e) {
            ctx.render(Result.failure(e.getCode(), e.getMessage()));
        }
    }
}

By default, validation stops at the first error. If you want to collect all errors, set:

solon.validation.validateAll: true

Business-Aware Validators (The Four Checkers)

Four annotations need you to provide a checker implementation. This is where Solon's design shines — the framework handles the interception, you just plug in the business logic.

@NoRepeatSubmit

@Component
public class NoRepeatSubmitCheckerImpl implements NoRepeatSubmitChecker {
    @Override
    public boolean check(NoRepeatSubmit anno, Context ctx,
                         String submitHash, int limitSeconds) {
        return LockUtils.tryLock(Solon.cfg().appName(), submitHash, limitSeconds);
    }
}

@Whitelist

@Component
public class WhitelistCheckerImpl implements WhitelistChecker {
    @Override
    public boolean check(Whitelist anno, Context ctx) {
        String ip = ctx.realIp();
        return CloudClient.list().inListOfIp("whitelist", ip);
    }
}

@NotBlacklist

@Component
public class NotBlacklistCheckerImpl implements NotBlacklistChecker {
    @Override
    public boolean check(NotBlacklist anno, Context ctx) {
        String ip = ctx.realIp();
        return !CloudClient.list().inListOfIp("blacklist", ip);
    }
}

@Logined

@Component
public class LoginedCheckerImpl implements LoginedChecker {
    @Override
    public boolean check(Logined anno, Context ctx, String userKeyName) {
        return ctx.sessionAsLong("userId") > 0;
    }
}

Custom Validators: Creating Your Own Annotation

The framework is designed to be extended. Here's a complete example of creating a custom @Phone validator:

Step 1: Define the annotation

@Target({ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Phone {
    String message() default "Invalid phone number";
    Class<?>[] groups() default {};
}

Step 2: Implement the validator

public class PhoneValidator implements Validator<Phone> {
    private static final Pattern PHONE_PATTERN =
        Pattern.compile("^1[3-9]\\d{9}$");

    @Override
    public String message(Phone anno) {
        return anno.message();
    }

    @Override
    public Class<?>[] groups(Phone anno) {
        return anno.groups();
    }

    @Override
    public Result validateOfValue(Phone anno, Object val, StringBuilder tmp) {
        if (val == null) return Result.succeed();
        if (val instanceof String == false) return Result.failure();
        if (PHONE_PATTERN.matcher((String) val).matches()) {
            return Result.succeed();
        }
        return Result.failure();
    }

    @Override
    public Result validateOfContext(Context ctx, Phone anno,
                                    String name, StringBuilder tmp) {
        String val = ctx.param(name);
        if (val == null) return Result.succeed();
        if (PHONE_PATTERN.matcher(val).matches()) {
            return Result.succeed();
        }
        return Result.failure(name);
    }
}

Step 3: Register it

@Configuration
public class ValidationConfig {
    @Bean
    public void registerValidators() {
        ValidatorManager.register(Phone.class, new PhoneValidator());
    }
}

Step 4: Use it

@Valid
@Controller
public class UserController {
    @Mapping("/user/phone")
    public void setPhone(@Phone String phone) {
        // Validated
    }
}

What I'd Change

Two things:

No built-in @Phone or @URL — common ones you'd expect. Easy to write yourself, but would be nice as pre-built options.
The @Validated annotation name — it does something different from both JSR 380's @Valid and Spring's @Validated. In Solon, @Validated is specifically for triggering entity field validation on a parameter. It's fine once you know, but the naming overlap with JSR 380 caused me a moment of confusion.

Bottom Line

Solon's validation is a complete, self-contained system. You get 20+ annotations out of the box, entity validation, group validation, and a clean extension point for custom validators — all without a single javax.validation or jakarta.validation dependency.

The business-aware annotations (@Whitelist, @NoRepeatSubmit, @Logined) are the standout feature. They let you enforce security and idempotency constraints at the validation layer rather than scattering checks throughout your handlers.

For a project that wants to keep its dependency graph lean, Solon's validation is a solid choice.

Solon Cache: Three Annotations, One Interface, and a Tags Trick You'll Use Every Day

Solon Framework — Fri, 31 Jul 2026 01:12:45 +0000

I've been writing Solon for a while now, and one thing that surprised me early on was how clean the caching layer is. Not because it does anything revolutionary — it doesn't — but because it stays out of your way while still handling the edge cases you actually hit in production.

Let me walk through what I've learned.

The Three Annotations

Solon gives you exactly three annotations for caching. No more, no less:

@Cache — read-through cache. If the key exists, return it; otherwise run the method and store the result.
@CachePut — always run the method, then update the cache with the result.
@CacheRemove — run the method, then evict one or more cache entries.

Here's a minimal example that shows all three:

@Controller
public class CacheController {
    @Cache(key = "user:${userId}", seconds = 30)
    @Mapping("/user/{userId}")
    public User getUser(int userId) {
        return userService.findById(userId);
    }

    @CachePut(key = "user:${userId}")
    @Mapping("/user/{userId}/refresh")
    public User refreshUser(int userId) {
        return userService.findById(userId);
    }

    @CacheRemove(tags = "users")
    @Mapping("/user/{userId}/delete")
    public String deleteUser(int userId) {
        userService.delete(userId);
        return "deleted";
    }
}

The @CacheRemove(tags = "users") line is worth a closer look — it's doing something that's surprisingly hard with most annotation-based caching systems.

The Tags Trick

Most caching frameworks give you key-based eviction. You know the key, you remove it. Fine for simple cases, but what about "invalidate all user-related caches"?

That's where tags come in. When you annotate a method with @Cache(tags = "users"), Solon doesn't just store the value under the computed key — it also records that key in a tag index. Later, when you call @CacheRemove(tags = "users"), it finds all keys associated with that tag and evicts them all.

@Cache(key = "user:${userId}", tags = "users")
@Mapping("/user/{userId}")
public User getUser(int userId) { ... }

@Cache(key = "user:${userId}:profile", tags = "users")
@Mapping("/user/{userId}/profile")
public Profile getProfile(int userId) { ... }

// Both caches get cleared in one shot
@CacheRemove(tags = "users")
@Mapping("/admin/users/flush")
public String flushUsers() { ... }

I use this pattern constantly for paginated lists. You cache page 1, page 2, page 3 of search results — all tagged with "search". When new data comes in, one @CacheRemove(tags = "search") wipes them all.

The docs do warn you about one thing: tags work by storing the collected keys as a list, so don't tag thousands of keys with the same tag. For most real-world scenarios — a few dozen to a few hundred keys per tag — it's perfectly fine.

Key Templates: Beyond Simple Strings

The key parameter supports ${} expressions that resolve against method parameters:

// Simple parameter
@Cache(key = "user:${userId}")
public User getUser(int userId) { ... }

// Nested property
@Cache(key = "user:${user.id}")
public User getUser(UserDto user) { ... }

// Map key
@Cache(key = "result:${params.type}")
public List<Result> search(Map<String, String> params) { ... }

If you don't specify a key, Solon auto-generates one from an MD5 of all parameter names and values. It works, but I'd recommend always providing an explicit key — it makes debugging and manual inspection much easier.

There's also a special ${.property} syntax for referencing the return value, which is mainly useful with @CachePut:

@CachePut(key = "order:${.orderId}")
public Order createOrder(CreateRequest req) {
    // ... create order, return it
}

The Interface That Makes It Swappable

Under the hood, all caching goes through CacheService:

public interface CacheService {
    void store(String key, Object obj, int seconds);
    Object get(String key);
    void remove(String key);
}

Three methods. That's it. The default implementation is LocalCacheService — an in-memory cache that works fine for single-instance apps.

But the real power is that you can swap it out with a single bean definition:

@Configuration
public class Config {
    @Bean
    public CacheService cache(@Inject("${cache}") Properties props) {
        return new MemCacheService(props);
    }
}

Once you define a CacheService bean, it replaces the default globally. All @Cache, @CachePut, and @CacheRemove annotations automatically use the new backend.

Switching Backends by Config

Solon also provides a CacheServiceSupplier that picks the backend based on config:

demo.cache1:
  driverType: "local"
  # driverType: "redis"
  # driverType: "memcached"

@Bean
public CacheService cache1(@Inject("${demo.cache1}") CacheServiceSupplier supplier) {
    return supplier.get();
}

Supported backends out of the box:

Backend	Plugin	Notes
Local	`solon-data` (built-in)	Default, no extra dependency
Redis	`solon-cache-jedis` or `solon-cache-redisson`	Pick your client
Memcached	`solon-cache-spymemcached`	Old but still around

Second-Level Cache: Local + Remote

One pattern I've found useful in read-heavy services is the second-level cache. It layers a local in-memory cache in front of a remote one (Redis, Memcached):

@Bean
public CacheService cache1(@Inject("${demo.cache1}") CacheServiceSupplier supplier) {
    CacheService remote = supplier.get();

    if (remote instanceof LocalCacheService) {
        return remote;
    }

    // Local L1 + remote L2, with a 5-second buffer
    LocalCacheService local = new LocalCacheService();
    return new SecondCacheService(local, remote, 5);
}

The "buffer" means: when the local cache misses but the remote cache hits, the result is stored locally for 5 seconds. Subsequent reads within those 5 seconds hit the local cache directly — no network round trip. For hot data, this can cut Redis load significantly.

Partition Design

Once you have multiple services sharing the same Redis instance, you'll want to partition your caches. Solon supports this through named cache services:

demo.cache.user:
  keyHeader: "user"
  server: "localhost:6379"
  db: 0

demo.cache.order:
  keyHeader: "order"
  server: "localhost:6379"
  db: 1

@Configuration
public class Config {
    @Bean("cache_user")
    public CacheService cacheUser(@Inject("${demo.cache.user}") RedisCacheService cache) {
        return cache.enableMd5key(false);
    }

    @Bean("cache_order")
    public CacheService cacheOrder(@Inject("${demo.cache.order}") RedisCacheService cache) {
        return cache.enableMd5key(false);
    }
}

Then use them in your services:

@Component
public class OrderService {
    @Cache(service = "cache_order")
    public String hello(String name) {
        return String.format("Hello %s!", name);
    }
}

Different databases, different key prefixes, and the annotation just needs a service attribute to pick the right one.

What I'd Change

If I had one nit to pick, it's that the auto-generated key (when you don't specify one) is an MD5 of all parameters. In practice, I always specify an explicit key, so this hasn't been an issue for me. But for someone new to the framework, it might cause confusion when they see opaque hash strings in their cache store.

Bottom Line

Solon's caching layer is refreshingly simple. Three annotations, one interface, and a tags system that handles batch invalidation better than most frameworks I've used. The CacheService interface is trivial to implement, which means you can plug in basically any backend you want — or write a custom one for your specific use case.

If you're already using Solon, the caching annotations are in the solon-data module, which you probably already have as a dependency. Just add @Cache and you're done.

Solon WebSocket: Listener Interface Over Annotation Maze

Solon Framework — Thu, 30 Jul 2026 17:03:33 +0000

Solon's WebSocket support is one of those areas where the design diverges clearly from what most Java developers expect. If you've built WebSocket endpoints with JSR-356 — the standard that Spring, Tomcat, and most Java EE containers follow — Solon does it differently. Not worse, just different. And once the pattern clicks, it's actually cleaner.

The Key Difference: Listeners, Not Annotations

JSR-356 WebSocket development looks like this:

@ServerEndpoint("/ws/chat")
public class ChatEndpoint {
    @OnOpen
    public void onOpen(Session session) { ... }

    @OnMessage
    public void onMessage(Session session, String message) { ... }

    @OnClose
    public void onClose(Session session) { ... }
}

Solon replaces the @OnOpen, @OnMessage, @OnClose, @OnError annotations with a WebSocketListener interface. You keep @ServerEndpoint for path declaration, but lifecycle handling is interface-based:

@ServerEndpoint("/ws/chat/{roomId}")
public class ChatEndpoint extends SimpleWebSocketListener {

    @Override
    public void onOpen(WebSocket socket) {
        String roomId = socket.param("roomId"); // path variable
        String token  = socket.param("token");  // query param ?token=...
        if (!isValidToken(token)) {
            socket.close();
        }
    }

    @Override
    public void onMessage(WebSocket socket, String text) throws IOException {
        socket.send("Echo: " + text);
    }
}

SimpleWebSocketListener lets you override only the methods you need. For the full interface, implement WebSocketListener directly — it exposes onOpen, onMessage (text + binary), onClose, and onError.

Two Deployment Modes

Solon WebSocket works in two configurations depending on which server plugin you use.

Shared port — HTTP and WebSocket traffic share the same port. Most server plugins support this out of the box:

<!-- smart-http (built-in WS, no extra plugin needed) -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-smarthttp</artifactId>
</dependency>

<!-- Jetty v9 (javax) -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-jetty</artifactId>
</dependency>
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-jetty-add-websocket</artifactId>
</dependency>

<!-- Tomcat v9 (javax, requires v3.7.3+) -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-tomcat</artifactId>
</dependency>
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-tomcat-add-websocket</artifactId>
</dependency>

Independent port — a dedicated WebSocket server runs on a separate port (default: main port + 10000):

<!-- Java-WebSocket (nio), 0.4Mb, jdk 8+ -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-websocket</artifactId>
</dependency>

<!-- Netty (nio), 3.6Mb, jdk 8+, available since v2.3.5 -->
<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-server-websocket-netty</artifactId>
</dependency>

Configure the WS port in app.yml:

server.websocket.port: 18080

No version numbers needed in dependency declarations — the Solon BOM manages them.

Startup

Enable WebSocket in your main class:

public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args, app -> {
            app.enableWebSocket(true);
        });
    }
}

That's the only wiring required. Your @ServerEndpoint classes are auto-discovered through Solon's IoC container.

Path Variables and Query Parameters

Both are accessed through socket.param():

@ServerEndpoint("/ws/room/{id}")
public class RoomEndpoint extends SimpleWebSocketListener {

    @Override
    public void onOpen(WebSocket socket) {
        String roomId = socket.param("id");     // from /ws/room/42
        String userId = socket.param("userId"); // from ?userId=abc
        System.out.println("Connected: room=" + roomId + " user=" + userId);
    }

    @Override
    public void onMessage(WebSocket socket, String text) throws IOException {
        // broadcast would go here
        socket.send("[room:" + socket.param("id") + "] " + text);
    }

    @Override
    public void onClose(WebSocket socket) {
        System.out.println("Disconnected: " + socket.param("id"));
    }
}

Multi-Channel Routing

@ServerEndpoint("/ws/user/")
public class UserChannel extends SimpleWebSocketListener {
    @Override
    public void onMessage(WebSocket socket, String text) throws IOException {
        socket.send("user channel: " + text);
    }
}

@ServerEndpoint("/ws/admin/")
public class AdminChannel extends SimpleWebSocketListener {
    @Override
    public void onOpen(WebSocket socket) {
        if (!"admin".equals(socket.param("role"))) {
            socket.close();
        }
    }

    @Override
    public void onMessage(WebSocket socket, String text) throws IOException {
        socket.send("admin channel: " + text);
    }
}

Advanced: Pipeline Routing

PipelineWebSocketListener and PathWebSocketListener let you build layered routing within a single endpoint — useful for middleware-style pre-processing plus path-specific handlers:

@ServerEndpoint("/ws/app/**")
public class AppEndpoint extends PipelineWebSocketListener {

    public AppEndpoint() {
        // First layer: auth interceptor (runs for all paths under /ws/app/**)
        next(new SimpleWebSocketListener() {
            @Override
            public void onOpen(WebSocket socket) {
                if (socket.param("token") == null) {
                    socket.close();
                }
            }
        })
        // Second layer: path-based dispatch
        .next(new PathWebSocketListener()
            .of("/ws/app/chat/{id}", new SimpleWebSocketListener() {
                @Override
                public void onMessage(WebSocket socket, String text) throws IOException {
                    socket.send("chat[" + socket.param("id") + "]: " + text);
                }
            })
            .of("/ws/app/notify", new SimpleWebSocketListener() {
                @Override
                public void onOpen(WebSocket socket) {
                    socket.send("notification stream connected");
                }
            })
        );
    }
}

Global Interceptors via WebSocketRouter

For cross-cutting logic that applies to all WebSocket connections regardless of path, inject WebSocketRouter in a @Configuration class:

@Configuration
public class WsConfig {

    @Bean
    public void init(@Inject WebSocketRouter webSocketRouter) {
        webSocketRouter.before(new SimpleWebSocketListener() {
            @Override
            public void onOpen(WebSocket socket) {
                // e.g., rate limiting, logging, connection tracking
                System.out.println("WS connected from: " + socket.remoteAddress());
            }
        });
    }
}

Choosing Your Plugin

Plugin	Engine	Size	Port	JDK
`solon-server-smarthttp`	smart-http (aio)	0.8 Mb	shared	8+
`solon-server-jetty` + `add-websocket`	Jetty v9 (nio)	2.7 Mb	shared	8+
`solon-server-jetty-jakarta` + `add-websocket-jakarta`	Jetty v12 (nio)	3.9 Mb	shared	17+
`solon-server-tomcat` + `add-websocket`	Tomcat v9	—	shared	8+
`solon-server-undertow`	Undertow (nio)	4.6 Mb	shared	8+
`solon-server-websocket`	Java-WebSocket (nio)	0.4 Mb	independent	8+
`solon-server-websocket-netty`	Netty (nio)	3.6 Mb	independent	8+

For most services where HTTP and WS share the same host, solon-server-smarthttp is the lowest-friction option — WS support is built in with no additional dependency. If you need a standalone WebSocket service with minimal footprint, solon-server-websocket at 0.4 Mb is hard to beat.

What's Not There

Solon WebSocket doesn't implement the JSR-356 API. If you're migrating code that directly uses javax.websocket.Session, @ServerEndpoint in the javax.websocket namespace, or JSR-356 encoders/decoders — that code needs to be rewritten to the listener interface pattern. It's not a large rewrite, but it's a real one.

The flip side is that the listener pattern is easier to test (just instantiate the listener class and call its methods) and easier to compose (the pipeline/path listeners give you explicit, readable routing without annotation scanning surprises).

Resources

WebSocket architecture overview: https://solon.noear.org/article/332
Core listener API: https://solon.noear.org/article/643
Pipeline and path routing: https://solon.noear.org/article/645
Plugin index: https://solon.noear.org/article/family-solon-server

Solon State Machine: When if-else Spaghetti Meets a Cleaner Pattern

Solon Framework — Thu, 30 Jul 2026 16:17:32 +0000

The Core Idea

A state machine has four building blocks:

Concept	Meaning
State	A condition the system is in (e.g., "CREATED", "PAID")
Event	Something that happens (e.g., "PAY", "SHIP")
Action	What runs when a transition happens
Transition	The rule: from state X, on event Y, go to state Z (optionally if condition W, and do action A)

Solon's StateMachine<State, Event, Payload> ties them together with a fluent DSL.

Hello World: A Light Switch

Add the dependency:

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-statemachine</artifactId>
</dependency>

Now, a light switch that toggles between OFF and ON:

import org.noear.solon.statemachine.EventContext;
import org.noear.solon.statemachine.StateMachine;

public class LightSwitchApp {
    enum Event { PRESS }
    enum State { OFF, ON }

    public static void main(String[] args) {
        StateMachine<State, Event, String> stateMachine = new StateMachine<>();

        // OFF + PRESS -> ON
        stateMachine.addTransition(t -> t.from(State.OFF).on(Event.PRESS).to(State.ON)
                .then(context -> System.out.println("Light is ON")));

        // ON + PRESS -> OFF
        stateMachine.addTransition(t -> t.from(State.ON).on(Event.PRESS).to(State.OFF)
                .then(context -> System.out.println("Light is OFF")));

        // Test it
        State currentState = State.OFF;
        for (int i = 0; i < 6; i++) {
            currentState = stateMachine.sendEvent(
                Event.PRESS,
                EventContext.of(currentState, null)
            );
            System.out.println("New state: " + currentState);
        }
    }
}

Run it, and the light toggles back and forth. The sendEvent() returns the new state -- you don't manage a state variable manually; you just hand over the current state and let the machine compute the next.

The DSL Breakdown

The StateTransitionDecl has five methods:

Method	Required	Description
`.from(state)`	Yes	Source state(s) -- can have multiple
`.to(state)`	Yes	Target state (one)
`.on(event)`	Yes	Triggering event
`.when(condition)`	No	Optional guard condition
`.then(action)`	No	Optional action to execute

The when and then are optional. If you just need a simple state transition without side effects:

stateMachine.addTransition(t ->
    t.from(State.DRAFT).to(State.PUBLISHED).on(Event.PUBLISH));

Real-World Example: Order State Machine

Let's model an order lifecycle with states NONE -> CREATED -> PAID -> SHIPPED -> DELIVERED, with optional cancellation paths.

public enum OrderEvent { CREATE, PAY, SHIP, DELIVER, CANCEL }
public enum OrderState { NONE, CREATED, PAID, SHIPPED, DELIVERED, CANCELLED }

Define an Order payload that implements EventContext:

public class Order implements EventContext<OrderState, Order> {
    private String id;
    private String product;
    private OrderState state;
    private String status;

    @Override
    public OrderState getState() { return state; }
    @Override
    public Order getPayload() { return this; }

    public void setState(OrderState state) { this.state = state; }
    public void setStatus(String status) { this.status = status; }
}

Now build the state machine by extending StateMachine:

public class OrderStateMachine extends StateMachine<OrderState, OrderEvent, Order> {
    public OrderStateMachine() {
        from(OrderState.NONE).on(OrderEvent.CREATE).to(OrderState.CREATED).then(ctx -> {
            Order payload = ctx.getPayload();
            payload.setState(OrderState.CREATED);
            payload.setStatus("Created");
        });
        from(OrderState.CREATED).on(OrderEvent.PAY).to(OrderState.PAID).then(ctx -> {
            Order payload = ctx.getPayload();
            payload.setState(OrderState.PAID);
            payload.setStatus("Paid");
        });
        from(OrderState.PAID).on(OrderEvent.SHIP).to(OrderState.SHIPPED).then(ctx -> {
            Order payload = ctx.getPayload();
            payload.setState(OrderState.SHIPPED);
            payload.setStatus("Shipped");
        });
        from(OrderState.SHIPPED).on(OrderEvent.DELIVER).to(OrderState.DELIVERED).then(ctx -> {
            Order payload = ctx.getPayload();
            payload.setState(OrderState.DELIVERED);
            payload.setStatus("Delivered");
        });
    }
}

Test it:

public class OrderTest {
    public static void main(String[] args) {
        OrderStateMachine stateMachine = new OrderStateMachine();
        Order order = new Order("1", "iPhone 16 Pro Max", null);

        stateMachine.sendEvent(OrderEvent.CREATE, order);
        stateMachine.sendEvent(OrderEvent.PAY, order);
        stateMachine.sendEvent(OrderEvent.SHIP, EventContext.of(order.getState(), order));
        stateMachine.sendEvent(OrderEvent.DELIVER, EventContext.of(order.getState(), order));
    }
}

Two Usage Styles

1. Lambda style (composition)

StateMachine<State, Event, Payload> sm = new StateMachine<>();
sm.addTransition(t -> t.from(X).on(E).to(Y).then(ctx -> { ... }));

2. Inheritance style

public class MyMachine extends StateMachine<State, Event, Payload> {
    public MyMachine() {
        from(X).on(E).to(Y).then(ctx -> { ... });
    }
}

Both produce the same result. Use composition when you need multiple independent machines; use inheritance when the machine is a self-contained domain concept.

When to Use It (and When Not To)

Solon State Machine is designed as a complement to Solon Flow, not a replacement.

Use State Machine when:

You have discrete states and events (order lifecycle, document workflow, game state)
You want a declarative alternative to nested if-else or switch statements
You don't need persistence -- the state is maintained in memory via the event context

Use Solon Flow when:

You need persistent, resumable long-running processes
You need a visual designer for business users
You need complex branching, parallel execution, or sub-processes

The two can coexist in the same project.

The Honest Picture

No persistence. The state machine is stateless by design -- you pass the current state in via EventContext, and the machine returns the new state. You own the storage.

No visual designer. Unlike Solon Flow which has a web-based designer, the state machine is code-only.

No built-in event bus integration. State transitions trigger .then() actions synchronously.

Simple but not powerful for complex workflows. If your state logic involves parallel states or nested state machines, Solon Flow is the better choice.